From 23548f40a09f5f8bf9cf1e1bc2d4c2b236777560 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 28 Jul 2026 16:13:44 -0400
Subject: [PATCH 001/200] fix(share): give visual feedback when downloading
 from a share (#5865)

* fix(share): give visual feedback when downloading a share

The share page handed the download URL to navidrome-music-player, which fell
through to downloadjs and buffered the whole ZIP into memory via XHR before
saving it. Nothing was handed to the browser until the last byte arrived, so a
large share produced a long silent window with no player feedback and no
browser download UI, inviting repeat clicks that each spawn another server-side
zip+transcode.

Use the player's customDownloader prop to trigger a synthetic anchor instead,
so the browser performs the download and reports its own progress. An anchor
rather than assigning window.location.href: the share page's service worker
registers a NavigationRoute over all navigations, which intercepts the streamed
archive and fails it into the offline fallback (observed as HTTP 503 in Chrome).

handleDownloads now loads the share before streaming so it can set
Content-Disposition and Content-Type. This also fixes error reporting: ZipShare
previously wrote to the ResponseWriter before checkShareError ran, locking the
status at 200, so expired, missing and non-downloadable shares all returned 200.
They now correctly return 410, 404 and 403.

* feat(share): acknowledge the download click in the player

The browser's download UI is the real progress indicator, but nothing in the
page itself reacted to the click, so the moment before the browser catches up
still read as unresponsive. Dim the download button and make it unclickable for
two seconds after a download starts, reusing the JSS function-value pattern the
existing single-track styling already uses.

A repeat download restarts the window instead of extending the original, and
the timer is cleared on unmount. This also blunts repeat clicking, where every
extra click costs another server-side zip and transcode.

Add SharePlayer tests covering the download mechanism and this state machine.
The dimming itself is verified in a browser rather than jsdom: JSS function
values are not evaluated there, so the rule is never emitted and a CSS
assertion would pass or fail for the wrong reason.

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

* test(share): assert render counts in SharePlayer feedback tests

The two acknowledgement tests compared the props object across renders, which
React may reuse, so they passed without proving anything and then failed once
the surrounding assertions changed. Count renders instead, and let the pending
timer run out rather than advancing exactly to its deadline, which does not
cross it.

The repeat-download test now also asserts that no render happens at the
original deadline, proving the timer was replaced rather than merely that one
eventually fired.

* fix(share): count one visit per share download

The preflight share load added in this branch made every download record two
visits: handleDownloads called Share.Load, and ZipShare then loaded the share
again internally. Share.Load increments and persists VisitCount, so the counter
advanced twice per download and the repository work was duplicated.

Pass the already-loaded share into ZipShare instead of its id. handleDownloads
is its only production caller, and it now has the share in hand for the
Content-Disposition header anyway.

The archiver test asserts Load is not called, so the double-load cannot come
back unnoticed. Verified against a running server: the counter now advances by
one per download.

* test(share): derive feedback-window timings from the constant

The acknowledgement tests hardcoded clock advances tuned to a 2000ms window.
Raising DOWNLOAD_FEEDBACK_MS to 5000 left them advancing 1500ms and 1001ms,
which no longer reach the deadline they are meant to cross, so the repeat-
download test passed without proving the timer had been replaced.

Export the constant and derive the advances from it, and let the pending timer
run out in the unmount test rather than advancing a fixed amount. Changing the
duration can no longer silently strand a test short of its deadline.

---------

Signed-off-by: Deluan <deluan@navidrome.org>
---
 core/archiver.go                       |  12 +--
 core/archiver_test.go                  |   7 +-
 server/public/handle_downloads.go      |  27 ++++-
 server/public/handle_downloads_test.go | 134 ++++++++++++++++++++++++
 server/subsonic/e2e/e2e_suite_test.go  |   2 +-
 ui/src/share/SharePlayer.jsx           |  42 ++++++--
 ui/src/share/SharePlayer.test.jsx      | 139 +++++++++++++++++++++++++
 7 files changed, 344 insertions(+), 19 deletions(-)
 create mode 100644 server/public/handle_downloads_test.go
 create mode 100644 ui/src/share/SharePlayer.test.jsx

diff --git a/core/archiver.go b/core/archiver.go
index 5d1c090cd..8c42f8f49 100644
--- a/core/archiver.go
+++ b/core/archiver.go
@@ -21,7 +21,7 @@ import (
 type Archiver interface {
 	ZipAlbum(ctx context.Context, id string, format string, bitrate int, w io.Writer) error
 	ZipArtist(ctx context.Context, id string, format string, bitrate int, w io.Writer) error
-	ZipShare(ctx context.Context, id string, w io.Writer) error
+	ZipShare(ctx context.Context, s *model.Share, w io.Writer) error
 	ZipPlaylist(ctx context.Context, id string, format string, bitrate int, w io.Writer) error
 }
 
@@ -100,16 +100,14 @@ func (a *archiver) albumFilename(mf model.MediaFile, format string, isMultiDisc
 	return fmt.Sprintf("%s/%s", str.SanitizeFilename(mf.Album), file)
 }
 
-func (a *archiver) ZipShare(ctx context.Context, id string, out io.Writer) error {
-	s, err := a.shares.Load(ctx, id)
-	if err != nil {
-		return err
-	}
+// ZipShare takes an already-loaded share: Share.Load records a visit, so
+// loading it again here would count every download twice.
+func (a *archiver) ZipShare(ctx context.Context, s *model.Share, out io.Writer) error {
 	if !s.Downloadable {
 		return model.ErrNotAuthorized
 	}
 	log.Debug(ctx, "Zipping share", "name", s.ID, "format", s.Format, "bitrate", s.MaxBitRate, "numTracks", len(s.Tracks))
-	return a.zipMediaFiles(ctx, id, s.ID, s.Format, s.MaxBitRate, out, s.Tracks, false)
+	return a.zipMediaFiles(ctx, s.ID, s.ID, s.Format, s.MaxBitRate, out, s.Tracks, false)
 }
 
 func (a *archiver) ZipPlaylist(ctx context.Context, id string, format string, bitrate int, out io.Writer) error {
diff --git a/core/archiver_test.go b/core/archiver_test.go
index f432139d8..2ba8f1fc0 100644
--- a/core/archiver_test.go
+++ b/core/archiver_test.go
@@ -130,13 +130,16 @@ var _ = Describe("Archiver", func() {
 				Tracks:       mfs,
 			}
 
-			sh.On("Load", mock.Anything, "1").Return(share, nil)
 			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)
+			err := arch.ZipShare(context.Background(), share, out)
 			Expect(err).To(BeNil())
 
+			// Share.Load records a visit; re-loading here would double-count
+			// every download.
+			sh.AssertNotCalled(GinkgoT(), "Load", mock.Anything, mock.Anything)
+
 			zr, err := zip.NewReader(bytes.NewReader(out.Bytes()), int64(out.Len()))
 			Expect(err).To(BeNil())
 
diff --git a/server/public/handle_downloads.go b/server/public/handle_downloads.go
index 6aa35c341..0012c4b35 100644
--- a/server/public/handle_downloads.go
+++ b/server/public/handle_downloads.go
@@ -1,18 +1,41 @@
 package public
 
 import (
+	"cmp"
+	"fmt"
 	"net/http"
+	"strings"
 
+	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/req"
+	"github.com/navidrome/navidrome/utils/str"
 )
 
 func (pub *Router) handleDownloads(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
 	id, err := req.Params(r).String(":id")
 	if err != nil {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
 	}
 
-	err = pub.archiver.ZipShare(r.Context(), id, w)
-	checkShareError(r.Context(), w, err, id)
+	// Load the share before streaming: once ZipShare writes its first byte the
+	// status is locked at 200, so errors could no longer be reported.
+	s, err := pub.share.Load(ctx, id)
+	if err != nil {
+		checkShareError(ctx, w, err, id)
+		return
+	}
+	if !s.Downloadable {
+		checkShareError(ctx, w, model.ErrNotAuthorized, id)
+		return
+	}
+
+	name := str.SanitizeFilename(cmp.Or(s.Description, s.ID))
+	name = strings.ReplaceAll(name, ",", "_")
+	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", name+".zip"))
+	w.Header().Set("Content-Type", "application/zip")
+
+	err = pub.archiver.ZipShare(ctx, s, w)
+	checkShareError(ctx, w, err, id)
 }
diff --git a/server/public/handle_downloads_test.go b/server/public/handle_downloads_test.go
new file mode 100644
index 000000000..1a97f4379
--- /dev/null
+++ b/server/public/handle_downloads_test.go
@@ -0,0 +1,134 @@
+package public
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"time"
+
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type mockArchiver struct {
+	called bool
+	err    error
+}
+
+func (m *mockArchiver) ZipAlbum(context.Context, string, string, int, io.Writer) error {
+	return nil
+}
+
+func (m *mockArchiver) ZipArtist(context.Context, string, string, int, io.Writer) error {
+	return nil
+}
+
+func (m *mockArchiver) ZipPlaylist(context.Context, string, string, int, io.Writer) error {
+	return nil
+}
+
+func (m *mockArchiver) ZipShare(_ context.Context, _ *model.Share, w io.Writer) error {
+	m.called = true
+	if m.err != nil {
+		return m.err
+	}
+	_, _ = w.Write([]byte("zip-contents"))
+	return nil
+}
+
+var _ = Describe("handleDownloads", func() {
+	var ds *tests.MockDataStore
+	var shareRepo *tests.MockShareRepo
+	var archiver *mockArchiver
+	var pub *Router
+
+	BeforeEach(func() {
+		ds = &tests.MockDataStore{}
+		shareRepo = &tests.MockShareRepo{}
+		ds.MockedShare = shareRepo
+		archiver = &mockArchiver{}
+		pub = &Router{ds: ds, archiver: archiver, share: core.NewShare(ds)}
+	})
+
+	shareIs := func(s *model.Share) {
+		shareRepo.ID = s.ID
+		shareRepo.Entity = s
+	}
+
+	makeRequest := func(id string) *httptest.ResponseRecorder {
+		r := httptest.NewRequest("GET", "/public/d/"+id+"?%3Aid="+id, nil)
+		w := httptest.NewRecorder()
+		pub.handleDownloads(w, r)
+		return w
+	}
+
+	It("sets a Content-Disposition filename from the share description", func() {
+		shareIs(&model.Share{ID: "abc123", Description: "My Mixtape", Downloadable: true})
+
+		w := makeRequest("abc123")
+
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="My Mixtape.zip"`))
+		Expect(w.Header().Get("Content-Type")).To(Equal("application/zip"))
+		Expect(archiver.called).To(BeTrue())
+		Expect(w.Body.String()).To(Equal("zip-contents"))
+	})
+
+	It("falls back to the share ID when there is no description", func() {
+		shareIs(&model.Share{ID: "abc123", Downloadable: true})
+
+		w := makeRequest("abc123")
+
+		Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="abc123.zip"`))
+	})
+
+	It("sanitizes characters that are unsafe in a filename", func() {
+		shareIs(&model.Share{ID: "abc123", Description: `AC/DC: Live, 1979`, Downloadable: true})
+
+		w := makeRequest("abc123")
+
+		Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="AC_DC_ Live_ 1979.zip"`))
+	})
+
+	It("returns 403 without invoking the archiver when the share is not downloadable", func() {
+		shareIs(&model.Share{ID: "abc123", Description: "No Download", Downloadable: false})
+
+		w := makeRequest("abc123")
+
+		Expect(w.Code).To(Equal(http.StatusForbidden))
+		Expect(archiver.called).To(BeFalse())
+		Expect(w.Header().Get("Content-Disposition")).To(BeEmpty())
+	})
+
+	It("returns 404 when the share does not exist", func() {
+		shareIs(&model.Share{ID: "other", Downloadable: true})
+
+		w := makeRequest("missing")
+
+		Expect(w.Code).To(Equal(http.StatusNotFound))
+		Expect(archiver.called).To(BeFalse())
+	})
+
+	It("returns 410 when the share has expired", func() {
+		shareIs(&model.Share{ID: "abc123", Downloadable: true, ExpiresAt: new(time.Now().Add(-time.Hour))})
+
+		w := makeRequest("abc123")
+
+		Expect(w.Code).To(Equal(http.StatusGone))
+		Expect(archiver.called).To(BeFalse())
+	})
+
+	It("returns 500 when the share lookup fails", func() {
+		shareRepo.Error = errors.New("db error")
+
+		w := makeRequest("abc123")
+
+		Expect(w.Code).To(Equal(http.StatusInternalServerError))
+		Expect(archiver.called).To(BeFalse())
+	})
+})
diff --git a/server/subsonic/e2e/e2e_suite_test.go b/server/subsonic/e2e/e2e_suite_test.go
index 6875b6370..4e9039d68 100644
--- a/server/subsonic/e2e/e2e_suite_test.go
+++ b/server/subsonic/e2e/e2e_suite_test.go
@@ -330,7 +330,7 @@ func (n noopArchiver) ZipArtist(context.Context, string, string, int, io.Writer)
 	return model.ErrNotFound
 }
 
-func (n noopArchiver) ZipShare(context.Context, string, io.Writer) error {
+func (n noopArchiver) ZipShare(context.Context, *model.Share, io.Writer) error {
 	return model.ErrNotFound
 }
 
diff --git a/ui/src/share/SharePlayer.jsx b/ui/src/share/SharePlayer.jsx
index a3a15e50a..2384866ea 100644
--- a/ui/src/share/SharePlayer.jsx
+++ b/ui/src/share/SharePlayer.jsx
@@ -1,15 +1,24 @@
 import ReactJkMusicPlayer from 'navidrome-music-player'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import config, { shareInfo } from '../config'
 import { shareCoverUrl, shareDownloadUrl, shareStreamUrl } from '../utils'
 
 import { makeStyles } from '@material-ui/core/styles'
 
+// How long the download button stays inert after a click. The browser needs a
+// moment to show its own download UI; until then the page looks unresponsive.
+export const DOWNLOAD_FEEDBACK_MS = 5000
+
 const useStyle = makeStyles({
   player: {
     '& .group .next-audio': {
       pointerEvents: (props) => props.single && 'none',
       opacity: (props) => props.single && 0.65,
     },
+    '& .group.audio-download': {
+      pointerEvents: (props) => props.downloading && 'none',
+      opacity: (props) => props.downloading && 0.65,
+    },
     '@media (min-width: 768px)': {
       '& .react-jinke-music-player-mobile > div': {
         width: 768,
@@ -23,7 +32,14 @@ const useStyle = makeStyles({
 })
 
 const SharePlayer = () => {
-  const classes = useStyle({ single: shareInfo?.tracks.length === 1 })
+  const [downloading, setDownloading] = useState(false)
+  const timer = useRef(null)
+  const classes = useStyle({
+    single: shareInfo?.tracks.length === 1,
+    downloading,
+  })
+
+  useEffect(() => () => clearTimeout(timer.current), [])
 
   const list = shareInfo?.tracks.map((s) => {
     return {
@@ -34,11 +50,23 @@ const SharePlayer = () => {
       duration: s.duration,
     }
   })
-  const onBeforeAudioDownload = () => {
-    return Promise.resolve({
-      src: shareDownloadUrl(shareInfo?.id),
-    })
-  }
+  // An anchor, not a navigation: the service worker's NavigationRoute would
+  // intercept the streamed archive and fail it.
+  const customDownloader = useCallback(() => {
+    const link = document.createElement('a')
+    link.href = shareDownloadUrl(shareInfo?.id)
+    link.download = ''
+    document.body.appendChild(link)
+    link.click()
+    document.body.removeChild(link)
+
+    setDownloading(true)
+    clearTimeout(timer.current)
+    timer.current = setTimeout(
+      () => setDownloading(false),
+      DOWNLOAD_FEEDBACK_MS,
+    )
+  }, [])
   const options = {
     audioLists: list,
     mode: 'full',
@@ -59,7 +87,7 @@ const SharePlayer = () => {
     <ReactJkMusicPlayer
       {...options}
       className={classes.player}
-      onBeforeAudioDownload={onBeforeAudioDownload}
+      customDownloader={customDownloader}
     />
   )
 }
diff --git a/ui/src/share/SharePlayer.test.jsx b/ui/src/share/SharePlayer.test.jsx
new file mode 100644
index 000000000..68d1eff59
--- /dev/null
+++ b/ui/src/share/SharePlayer.test.jsx
@@ -0,0 +1,139 @@
+import { render, act } from '@testing-library/react'
+import SharePlayer, { DOWNLOAD_FEEDBACK_MS } from './SharePlayer'
+
+let playerProps
+let renderCount
+
+vi.mock('navidrome-music-player', () => ({
+  default: (props) => {
+    playerProps = props
+    renderCount++
+    return <div data-testid="player" />
+  },
+}))
+
+vi.mock('../config', () => ({
+  default: { enableDownloads: true },
+  shareInfo: {
+    id: 'share-1',
+    downloadable: true,
+    tracks: [{ id: 't1', title: 'One', artist: 'A', duration: 100 }],
+  },
+}))
+
+vi.mock('../utils', () => ({
+  shareDownloadUrl: (id) => `/share/d/${id}`,
+  shareStreamUrl: (id) => `/share/s/${id}`,
+  shareCoverUrl: (id) => `/share/img/${id}`,
+}))
+
+describe('SharePlayer', () => {
+  let clickSpy
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    playerProps = null
+    renderCount = 0
+    // Downloading for real would navigate the jsdom window.
+    clickSpy = vi
+      .spyOn(HTMLAnchorElement.prototype, 'click')
+      .mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('downloads via an anchor so the service worker does not intercept it', () => {
+    render(<SharePlayer />)
+
+    let anchor
+    clickSpy.mockImplementation(function () {
+      anchor = { href: this.href, download: this.download }
+    })
+
+    act(() => {
+      playerProps.customDownloader()
+    })
+
+    expect(clickSpy).toHaveBeenCalledTimes(1)
+    expect(anchor.href).toContain('/share/d/share-1')
+    // Empty, so the server's Content-Disposition filename wins.
+    expect(anchor.download).toBe('')
+  })
+
+  it('removes the anchor from the document after clicking', () => {
+    render(<SharePlayer />)
+
+    act(() => {
+      playerProps.customDownloader()
+    })
+
+    expect(document.querySelectorAll('a[download]')).toHaveLength(0)
+  })
+
+  // The inert styling itself is driven by JSS function values, which jsdom does
+  // not evaluate; it is verified in a browser. What is checked here is the
+  // state machine feeding it -- that the component re-renders on download and
+  // again when the window closes.
+  it('re-renders when the feedback window opens and closes', () => {
+    render(<SharePlayer />)
+
+    const beforeDownload = renderCount
+    act(() => {
+      playerProps.customDownloader()
+    })
+    expect(renderCount).toBeGreaterThan(beforeDownload)
+
+    const beforeExpiry = renderCount
+    act(() => {
+      vi.runAllTimers()
+    })
+    expect(renderCount).toBeGreaterThan(beforeExpiry)
+  })
+
+  it('restarts the feedback window on a repeat download', () => {
+    render(<SharePlayer />)
+
+    act(() => {
+      playerProps.customDownloader()
+    })
+    const elapsedBeforeRepeat = Math.floor(DOWNLOAD_FEEDBACK_MS / 2)
+    act(() => {
+      vi.advanceTimersByTime(elapsedBeforeRepeat)
+    })
+    act(() => {
+      playerProps.customDownloader()
+    })
+
+    // Past the first timer's deadline, which it would have fired at had the
+    // repeat download not replaced it.
+    const beforeOriginalDeadline = renderCount
+    act(() => {
+      vi.advanceTimersByTime(DOWNLOAD_FEEDBACK_MS - elapsedBeforeRepeat + 1)
+    })
+    expect(renderCount).toBe(beforeOriginalDeadline)
+
+    act(() => {
+      vi.runAllTimers()
+    })
+    expect(renderCount).toBeGreaterThan(beforeOriginalDeadline)
+  })
+
+  it('does not update state after unmount', () => {
+    const { unmount } = render(<SharePlayer />)
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    act(() => {
+      playerProps.customDownloader()
+    })
+    unmount()
+    act(() => {
+      vi.runAllTimers()
+    })
+
+    expect(errorSpy).not.toHaveBeenCalled()
+  })
+})

From add0a6dc9b8360db480f76793fa928499bf51741 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 29 Jul 2026 13:44:42 -0400
Subject: [PATCH 002/200] feat(config): warn about unrecognized options in the
 config file (#5870)

* feat(config): warn about unrecognized options in the config file

Options that don't match any known name were silently discarded, so a typo
or an option written outside its section looked like it was applied.

In #5869 the user set `ArtistSplitExceptions` at the root level instead of
under `Scanner`, and got no feedback that the option was being ignored.

The known names are derived by reflection over configOptions, so the check
stays in sync with the struct. Free-form maps (Tags, DevLogLevels) accept any
subkey. When an unknown key matches the last segment of a known one, the
warning suggests it. Keys are reported as spelled in the config file,
recovered by scanning it, since viper lowercases every key it loads.

Also fixes two gaps this surfaced:

- remapEnvVarKeysFromConfig accepted any ND_-prefixed key and advised a
  canonical name built by string substitution, so `ND_SCANNER_WATCHERENABLED`
  (not an option) suggested `Scanner.Watcherenabled` (not an option either).
  It now only advises names that exist, with their documented spelling, and
  leaves the rest to the unrecognized-option warning.

- The deprecated option list drove only the warnings, while the value
  migration kept a second hardcoded list. They had drifted: SearchFullString
  warned about `Search.FullString` but never migrated to it. Both now come
  from deprecatedOptions.

* fix(config): address Codex review on the unrecognized-option warning

- Values computed during Load (ConfigFile, LastFM.Languages, Deezer.Languages)
  were accepted as valid keys, so setting them in the config file stayed silent
  even though Load overwrites them. They are now marked `conf:"-"` at the
  declaration, so the exclusion can't drift from the struct.

- Removed options are in the known-key set only so they get their own warning,
  but suggestOptions drew from the same set, so an unknown `ID` advised
  `Spotify.ID`, a key Navidrome explicitly ignores. They are now filtered out
  of suggestions.

- mapDeprecatedOption uses viper.Set, which outranks the config file, so a
  deprecated value overrode an explicitly configured replacement. It now skips
  the migration when the replacement was provided. viper.IsSet counts defaults
  as set, so the check is InConfig plus the env var.

envVarName also returns "" for an empty option, so a deprecated option with no
replacement no longer advises "Please use the new 'ND_'".

* fix(config): cover the ND_ spelling of a replacement, and the warning output

- explicitlySet missed the case where the replacement is given in the config
  file under its ND_ spelling: remapEnvVarKeysFromConfig moves it to the
  override layer, out of InConfig's reach, so the deprecated value still won.
  It now also checks the ND_-prefixed config key.

- The tests asserted only the helpers' return values, so removing the
  logUnknownOptions call from Load left them green. Added a spec that captures
  the logger and checks the emitted warning and suggestion text; verified it
  fails when the call is removed.
---
 conf/configuration.go                    | 241 +++++++++++++++++++----
 conf/configuration_test.go               | 119 +++++++++++
 conf/export_test.go                      |   4 +
 conf/testdata/cfg_deprecated_search.toml |   2 +
 conf/testdata/cfg_nd_bogus.toml          |   3 +
 conf/testdata/cfg_runtime_fields.toml    |  10 +
 conf/testdata/cfg_unknown_casing.ini     |   3 +
 conf/testdata/cfg_unknown_casing.json    |   4 +
 conf/testdata/cfg_unknown_casing.toml    |   2 +
 conf/testdata/cfg_unknown_casing.yaml    |   2 +
 conf/testdata/cfg_unknown_keys.toml      |  18 ++
 conf/testdata/cfg_warning_output.toml    |   7 +
 12 files changed, 380 insertions(+), 35 deletions(-)
 create mode 100644 conf/testdata/cfg_deprecated_search.toml
 create mode 100644 conf/testdata/cfg_nd_bogus.toml
 create mode 100644 conf/testdata/cfg_runtime_fields.toml
 create mode 100644 conf/testdata/cfg_unknown_casing.ini
 create mode 100644 conf/testdata/cfg_unknown_casing.json
 create mode 100644 conf/testdata/cfg_unknown_casing.toml
 create mode 100644 conf/testdata/cfg_unknown_casing.yaml
 create mode 100644 conf/testdata/cfg_unknown_keys.toml
 create mode 100644 conf/testdata/cfg_warning_output.toml

diff --git a/conf/configuration.go b/conf/configuration.go
index 83793bd43..9b49fb264 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -2,14 +2,18 @@ package conf
 
 import (
 	"cmp"
+	"encoding"
 	"encoding/json"
 	"fmt"
 	"net/url"
 	"os"
 	"path/filepath"
+	"reflect"
+	"regexp"
 	"runtime"
 	"slices"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/bmatcuk/doublestar/v4"
@@ -21,11 +25,12 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/scheduler"
 	"github.com/navidrome/navidrome/utils/run"
+	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/spf13/viper"
 )
 
 type configOptions struct {
-	ConfigFile                      string
+	ConfigFile                      string `conf:"-"`
 	Address                         string
 	Port                            int
 	UnixSocketPerm                  string
@@ -201,7 +206,7 @@ type lastfmOptions struct {
 	ScrobbleFirstArtistOnly bool
 
 	// Computed values
-	Languages []string // Computed from Language, split by comma
+	Languages []string `conf:"-"` // Computed from Language, split by comma
 }
 
 type deezerOptions struct {
@@ -209,7 +214,7 @@ type deezerOptions struct {
 	Language string
 
 	// Computed values
-	Languages []string // Computed from Language, split by comma
+	Languages []string `conf:"-"` // Computed from Language, split by comma
 }
 
 type listenBrainzOptions struct {
@@ -340,12 +345,11 @@ func Load(noConfigDump bool) {
 	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")
-	mapDeprecatedOption("EnableTranscodingCancellation", "Transcoding.EnableCancellation")
+	for _, o := range deprecatedOptions {
+		if o.replacement != "" {
+			mapDeprecatedOption(o.name, o.replacement)
+		}
+	}
 
 	err := viper.Unmarshal(&Server, viper.DecodeHook(
 		mapstructure.ComposeDecodeHookFunc(
@@ -403,6 +407,13 @@ func Load(noConfigDump bool) {
 	log.SetLogSourceLine(Server.DevLogSourceLine)
 	log.SetRedacting(Server.EnableLogRedacting)
 
+	// Log deprecated, removed and unknown options
+	for _, o := range deprecatedOptions {
+		logDeprecatedOptions(o.name, o.replacement)
+	}
+	logRemovedOptions(removedOptions...)
+	logUnknownOptions()
+
 	err = run.Sequentially(
 		validateScanSchedule,
 		validateBackupSchedule,
@@ -461,21 +472,6 @@ 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")
-	logDeprecatedOptions("EnableTranscodingCancellation", "Transcoding.EnableCancellation")
-
-	// Removed options
-	logRemovedOptions("Spotify.ID", "Spotify.Secret")
-
 	// Validate other options
 	if Server.UICoverArtSize < 200 || Server.UICoverArtSize > 1200 {
 		newValue := max(200, min(1200, Server.UICoverArtSize))
@@ -489,9 +485,26 @@ func Load(noConfigDump bool) {
 	}
 }
 
+// deprecatedOptions still work, but will be removed in a future release. An empty
+// replacement means the option is now ignored.
+var deprecatedOptions = []struct{ name, replacement string }{
+	{"Scanner.GenreSeparators", ""},
+	{"Scanner.GroupAlbumReleases", ""},
+	{"DevEnableBufferedScrobble", ""},
+	{"SearchFullString", "Search.FullString"},
+	{"ReverseProxyWhitelist", "ExtAuth.TrustedSources"},
+	{"ReverseProxyUserHeader", "ExtAuth.UserHeader"},
+	{"HTTPSecurityHeaders.CustomFrameOptionsValue", "HTTPHeaders.FrameOptions"},
+	{"CoverJpegQuality", "CoverArtQuality"},
+	{"SimilarSongsMatchThreshold", "Matcher.FuzzyThreshold"},
+	{"EnableTranscodingCancellation", "Transcoding.EnableCancellation"},
+}
+
+var removedOptions = []string{"Spotify.ID", "Spotify.Secret"}
+
 func logDeprecatedOptions(oldName, newName string) {
-	envVar := "ND_" + strings.ToUpper(strings.ReplaceAll(oldName, ".", "_"))
-	newEnvVar := "ND_" + strings.ToUpper(strings.ReplaceAll(newName, ".", "_"))
+	envVar := envVarName(oldName)
+	newEnvVar := envVarName(newName)
 	logWarning := func(oldName, newName string) {
 		if newName != "" {
 			log.Warn(fmt.Sprintf("Option '%s' is deprecated and will be ignored in a future release. Please use the new '%s'", oldName, newName))
@@ -511,7 +524,7 @@ func logDeprecatedOptions(oldName, newName string) {
 // not available anymore
 func logRemovedOptions(options ...string) {
 	for _, option := range options {
-		envVar := "ND_" + strings.ToUpper(strings.ReplaceAll(option, ".", "_"))
+		envVar := envVarName(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))
 		}
@@ -532,35 +545,193 @@ func remapEnvVarKeysFromConfig() {
 			continue
 		}
 		stripped := strings.TrimPrefix(key, "nd_")
-		canonicalKey := strings.ReplaceAll(stripped, "_", ".")
+		canonicalKey := ndKeyToCanonical(key)
 		displayNDKey := "ND_" + strings.ToUpper(stripped)
-		displayCanonical := toPascalCase(canonicalKey)
+		canonicalName := canonicalOptionName(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,
+				displayNDKey, cmp.Or(canonicalName, toPascalCase(canonicalKey)),
 			))
 			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,
-		)
+		// Unknown keys get no advice here, logUnknownOptions reports them instead
+		if canonicalName != "" {
+			_, _ = 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, canonicalName,
+			)
+		}
 	}
 }
 
 // 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) {
-	if viper.IsSet(legacyName) {
+	// viper.Set outranks the config file, so an explicit replacement must win over the legacy value
+	if viper.IsSet(legacyName) && !explicitlySet(newName) {
 		viper.Set(newName, viper.Get(legacyName))
 	}
 }
 
+// explicitlySet reports whether the user provided the option, ignoring defaults,
+// which viper.IsSet counts as set. The ND_ spelling is also accepted in the config
+// file, and remapEnvVarKeysFromConfig has already moved it out of InConfig's reach.
+func explicitlySet(name string) bool {
+	envVar := envVarName(name)
+	return viper.InConfig(name) || os.Getenv(envVar) != "" || viper.InConfig(strings.ToLower(envVar))
+}
+
+func envVarName(option string) string {
+	if option == "" {
+		return ""
+	}
+	return "ND_" + strings.ToUpper(strings.ReplaceAll(option, ".", "_"))
+}
+
+func logUnknownOptions() {
+	for _, key := range unknownConfigKeys() {
+		msg := fmt.Sprintf("Option '%s' is not recognized and will be ignored", key)
+		if matches := suggestOptions(key); len(matches) > 0 {
+			msg += fmt.Sprintf(". Did you mean '%s'?", strings.Join(matches, "' or '"))
+		}
+		log.Warn(msg)
+	}
+}
+
+// suggestOptions returns the known options sharing the last segment with key,
+// catching options written outside their section.
+func suggestOptions(key string) []string {
+	key = strings.ToLower(key)
+	leaf := leafKey(key)
+	canonical, _ := configKeys()
+	var matches []string
+	for known, name := range canonical {
+		// Removed options are known only so they get their own warning, never suggest them
+		if known != key && leafKey(known) == leaf && !slices.Contains(removedOptions, name) {
+			matches = append(matches, name)
+		}
+	}
+	slices.Sort(matches)
+	return matches
+}
+
+func leafKey(key string) string {
+	return key[strings.LastIndex(key, ".")+1:]
+}
+
+// unknownConfigKeys returns config file keys that don't match any known option, so
+// typos and options written outside their section don't fail silently.
+func unknownConfigKeys() []string {
+	// INI files keep the original [default] section alongside the merged one
+	skipDefault := strings.EqualFold(filepath.Ext(viper.ConfigFileUsed()), ".ini")
+
+	var unknown []string
+	for _, key := range viper.AllKeys() {
+		if !viper.InConfig(key) || canonicalOptionName(key) != "" {
+			continue
+		}
+		if skipDefault && strings.HasPrefix(key, "default.") {
+			continue
+		}
+		// Only ND_-prefixed keys that remapEnvVarKeysFromConfig could resolve are valid
+		if strings.HasPrefix(key, "nd_") && canonicalOptionName(ndKeyToCanonical(key)) != "" {
+			continue
+		}
+		unknown = append(unknown, key)
+	}
+	slices.Sort(unknown)
+	return asWrittenInConfigFile(unknown)
+}
+
+func ndKeyToCanonical(key string) string {
+	return strings.ReplaceAll(strings.TrimPrefix(key, "nd_"), "_", ".")
+}
+
+// canonicalOptionName returns the documented spelling of a known option key, or ""
+// if it matches no option. Subkeys of free-form maps have no fixed spelling.
+func canonicalOptionName(key string) string {
+	keys, prefixes := configKeys()
+	if name, ok := keys[key]; ok {
+		return name
+	}
+	if slices.ContainsFunc(prefixes, func(p string) bool { return strings.HasPrefix(key, p) }) {
+		return toPascalCase(key)
+	}
+	return ""
+}
+
+// asWrittenInConfigFile restores the casing the keys have in the config file, as
+// viper lowercases every key it loads.
+func asWrittenInConfigFile(keys []string) []string {
+	if len(keys) == 0 {
+		return nil
+	}
+	data, err := os.ReadFile(viper.ConfigFileUsed())
+	if err != nil {
+		return keys
+	}
+	casing := map[string]string{}
+	for _, match := range configFileKeyRx.FindAllStringSubmatch(string(data), -1) {
+		for segment := range strings.SplitSeq(match[1], ".") {
+			lower := strings.ToLower(segment)
+			casing[lower] = cmp.Or(casing[lower], segment)
+		}
+	}
+	return slice.Map(keys, func(key string) string {
+		segments := strings.Split(key, ".")
+		for i, s := range segments {
+			segments[i] = cmp.Or(casing[s], s)
+		}
+		return strings.Join(segments, ".")
+	})
+}
+
+// Matches keys and section headers in all supported config formats.
+var configFileKeyRx = regexp.MustCompile(`(?m)^\s*\[?\s*"?([\w.]+)"?\s*[]=:]`)
+
+// configKeys maps every accepted option name, lowercased, to its canonical spelling,
+// plus the prefixes of free-form map options (Tags, DevLogLevels).
+var configKeys = sync.OnceValues(func() (map[string]string, []string) {
+	keys := map[string]string{}
+	var prefixes []string
+
+	var collect func(t reflect.Type, prefix string)
+	collect = func(t reflect.Type, prefix string) {
+		for field := range t.Fields() {
+			// `conf:"-"` marks values computed during Load, not settable in the config
+			if !field.IsExported() || field.Tag.Get("conf") == "-" {
+				continue
+			}
+			name := prefix + field.Name
+			if field.Type.Kind() == reflect.Struct && !reflect.PointerTo(field.Type).Implements(textUnmarshalerType) {
+				collect(field.Type, name+".")
+				continue
+			}
+			lower := strings.ToLower(name)
+			keys[lower] = name
+			if field.Type.Kind() == reflect.Map {
+				prefixes = append(prefixes, lower+".")
+			}
+		}
+	}
+	collect(reflect.TypeFor[configOptions](), "")
+
+	for _, o := range deprecatedOptions {
+		keys[strings.ToLower(o.name)] = o.name
+	}
+	for _, o := range removedOptions {
+		keys[strings.ToLower(o)] = o
+	}
+	return keys, prefixes
+})
+
+var textUnmarshalerType = reflect.TypeFor[encoding.TextUnmarshaler]()
+
 // parseIniFileConfiguration is used to parse the config file when it is in INI format. For INI files, it
 // would require a nested structure, so instead we unmarshal it to a map and then merge the nested [default]
 // section into the root level.
diff --git a/conf/configuration_test.go b/conf/configuration_test.go
index e43c91a4b..4eaa8e3d8 100644
--- a/conf/configuration_test.go
+++ b/conf/configuration_test.go
@@ -1,12 +1,14 @@
 package conf_test
 
 import (
+	"bytes"
 	"fmt"
 	"os"
 	"path/filepath"
 	"testing"
 
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/log"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/spf13/viper"
@@ -178,6 +180,123 @@ var _ = Describe("Configuration", func() {
 		})
 	})
 
+	Describe("unknownConfigKeys", func() {
+		BeforeEach(func() {
+			viper.Reset()
+			conf.SetViperDefaults()
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("loglevel", "error")
+			conf.ResetConf()
+		})
+
+		It("reports misplaced and misspelled options, as spelled in the config file", func() {
+			conf.InitConfig(filepath.Join("testdata", "cfg_unknown_keys.toml"), false)
+			conf.Load(true)
+
+			Expect(conf.UnknownConfigKeys()).To(ConsistOf(
+				"ArtistSplitExceptions", "EnableDownlods", "Whatever.Foo",
+			))
+		})
+
+		DescribeTable("recovers the original casing in all supported formats",
+			func(file string) {
+				conf.InitConfig(filepath.Join("testdata", file), false)
+				conf.Load(true)
+
+				Expect(conf.UnknownConfigKeys()).To(ConsistOf("NotAnOption"))
+			},
+			Entry("TOML", "cfg_unknown_casing.toml"),
+			Entry("YAML", "cfg_unknown_casing.yaml"),
+			Entry("JSON", "cfg_unknown_casing.json"),
+			Entry("INI", "cfg_unknown_casing.ini"),
+		)
+
+		It("does not report valid, deprecated or free-form keys", func() {
+			conf.InitConfig(filepath.Join("testdata", "cfg.toml"), false)
+			conf.Load(true)
+
+			Expect(conf.UnknownConfigKeys()).To(BeEmpty())
+		})
+
+		It("does not report the [default] section of INI files", func() {
+			conf.InitConfig(filepath.Join("testdata", "cfg.ini"), false)
+			conf.Load(true)
+
+			Expect(conf.UnknownConfigKeys()).To(BeEmpty())
+		})
+
+		DescribeTable("SuggestOptions",
+			func(key string, expected []string) {
+				Expect(conf.SuggestOptions(key)).To(Equal(expected))
+			},
+			Entry("suggests the section of a misplaced option", "artistsplitexceptions",
+				[]string{"Scanner.ArtistSplitExceptions"}),
+			Entry("suggests the section of a misplaced nested option", "backup.fuzzythreshold",
+				[]string{"Matcher.FuzzyThreshold"}),
+			Entry("suggests every section defining the option", "schedule",
+				[]string{"Backup.Schedule", "Scanner.Schedule"}),
+			Entry("suggests nothing for a typo", "enabledownlods", nil),
+		)
+
+		It("does not report ND_-prefixed keys, as they are remapped", func() {
+			conf.InitConfig(filepath.Join("testdata", "cfg_nd_keys.toml"), false)
+			conf.Load(true)
+
+			Expect(conf.UnknownConfigKeys()).To(BeEmpty())
+		})
+
+		It("reports ND_-prefixed keys that remap to no known option", func() {
+			conf.InitConfig(filepath.Join("testdata", "cfg_nd_bogus.toml"), false)
+			conf.Load(true)
+
+			Expect(conf.UnknownConfigKeys()).To(ConsistOf("ND_TOTALLY_BOGUS_OPTION"))
+			Expect(conf.Server.Scanner.Schedule).To(Equal("@every 1h"))
+		})
+
+		It("migrates every deprecated option that has a replacement", func() {
+			conf.InitConfig(filepath.Join("testdata", "cfg_deprecated_search.toml"), false)
+			conf.Load(true)
+
+			Expect(conf.Server.Search.FullString).To(BeTrue())
+			Expect(conf.UnknownConfigKeys()).To(BeEmpty())
+		})
+
+		It("warns about each unrecognized option at startup", func() {
+			var logBuf bytes.Buffer
+			log.SetOutput(&logBuf)
+			DeferCleanup(func() { log.SetOutput(GinkgoWriter) })
+
+			conf.InitConfig(filepath.Join("testdata", "cfg_warning_output.toml"), false)
+			conf.Load(true)
+
+			Expect(logBuf.String()).To(ContainSubstring(
+				"Option 'ArtistSplitExceptions' is not recognized and will be ignored. " +
+					"Did you mean 'Scanner.ArtistSplitExceptions'?"))
+			Expect(logBuf.String()).To(ContainSubstring(
+				"Option 'EnableDownlods' is not recognized and will be ignored"))
+			Expect(logBuf.String()).ToNot(ContainSubstring("ArtistJoiner"))
+		})
+
+		Context("with runtime-computed and removed options in the config", func() {
+			BeforeEach(func() {
+				conf.InitConfig(filepath.Join("testdata", "cfg_runtime_fields.toml"), false)
+				conf.Load(true)
+			})
+
+			It("reports values computed during Load, which the config cannot set", func() {
+				Expect(conf.UnknownConfigKeys()).To(ContainElements("ConfigFile", "LastFM.Languages"))
+			})
+
+			It("never suggests a removed option", func() {
+				Expect(conf.SuggestOptions("id")).To(BeEmpty())
+			})
+
+			It("keeps an explicit replacement over the deprecated value", func() {
+				Expect(conf.Server.Search.FullString).To(BeFalse())
+			})
+		})
+	})
+
 	Describe("logFatal", func() {
 		var invalidPath string
 		BeforeEach(func() {
diff --git a/conf/export_test.go b/conf/export_test.go
index acebca551..cbb64b3d0 100644
--- a/conf/export_test.go
+++ b/conf/export_test.go
@@ -32,3 +32,7 @@ func SetLogFatal(f func(...any)) func() {
 	logFatal = f
 	return func() { logFatal = old }
 }
+
+var UnknownConfigKeys = unknownConfigKeys
+
+var SuggestOptions = suggestOptions
diff --git a/conf/testdata/cfg_deprecated_search.toml b/conf/testdata/cfg_deprecated_search.toml
new file mode 100644
index 000000000..cc6541e09
--- /dev/null
+++ b/conf/testdata/cfg_deprecated_search.toml
@@ -0,0 +1,2 @@
+MusicFolder = "/toml/music"
+SearchFullString = true
diff --git a/conf/testdata/cfg_nd_bogus.toml b/conf/testdata/cfg_nd_bogus.toml
new file mode 100644
index 000000000..841b40998
--- /dev/null
+++ b/conf/testdata/cfg_nd_bogus.toml
@@ -0,0 +1,3 @@
+MusicFolder = "/toml/music"
+ND_TOTALLY_BOGUS_OPTION = true
+ND_SCANNER_SCHEDULE = "@every 1h"
diff --git a/conf/testdata/cfg_runtime_fields.toml b/conf/testdata/cfg_runtime_fields.toml
new file mode 100644
index 000000000..a9c09f619
--- /dev/null
+++ b/conf/testdata/cfg_runtime_fields.toml
@@ -0,0 +1,10 @@
+MusicFolder = "/toml/music"
+SearchFullString = true
+ConfigFile = "/somewhere/else"
+ID = "oops"
+
+[Search]
+FullString = false
+
+[LastFM]
+Languages = ["pt"]
diff --git a/conf/testdata/cfg_unknown_casing.ini b/conf/testdata/cfg_unknown_casing.ini
new file mode 100644
index 000000000..c88db9b1f
--- /dev/null
+++ b/conf/testdata/cfg_unknown_casing.ini
@@ -0,0 +1,3 @@
+[default]
+MusicFolder = /ini/music
+NotAnOption = true
diff --git a/conf/testdata/cfg_unknown_casing.json b/conf/testdata/cfg_unknown_casing.json
new file mode 100644
index 000000000..cd3a226cd
--- /dev/null
+++ b/conf/testdata/cfg_unknown_casing.json
@@ -0,0 +1,4 @@
+{
+  "MusicFolder": "/json/music",
+  "NotAnOption": true
+}
diff --git a/conf/testdata/cfg_unknown_casing.toml b/conf/testdata/cfg_unknown_casing.toml
new file mode 100644
index 000000000..f015c9cb2
--- /dev/null
+++ b/conf/testdata/cfg_unknown_casing.toml
@@ -0,0 +1,2 @@
+MusicFolder = "/toml/music"
+NotAnOption = true
diff --git a/conf/testdata/cfg_unknown_casing.yaml b/conf/testdata/cfg_unknown_casing.yaml
new file mode 100644
index 000000000..8987f6351
--- /dev/null
+++ b/conf/testdata/cfg_unknown_casing.yaml
@@ -0,0 +1,2 @@
+MusicFolder: /yaml/music
+NotAnOption: true
diff --git a/conf/testdata/cfg_unknown_keys.toml b/conf/testdata/cfg_unknown_keys.toml
new file mode 100644
index 000000000..a7ed55cb0
--- /dev/null
+++ b/conf/testdata/cfg_unknown_keys.toml
@@ -0,0 +1,18 @@
+MusicFolder = "/toml/music"
+
+# Valid option, but written at the root level instead of under Scanner
+ArtistSplitExceptions = ["AC/DC", "Tyler, the creator"]
+
+# Misspelled option
+EnableDownlods = true
+
+# Unknown section
+[Whatever]
+Foo = "bar"
+
+# Valid options, must not be reported
+[Scanner]
+ArtistJoiner = " • "
+
+[Tags.custom]
+aliases = ["toml", "test"]
diff --git a/conf/testdata/cfg_warning_output.toml b/conf/testdata/cfg_warning_output.toml
new file mode 100644
index 000000000..a52c5ea54
--- /dev/null
+++ b/conf/testdata/cfg_warning_output.toml
@@ -0,0 +1,7 @@
+MusicFolder = "/toml/music"
+LogLevel = "warn"
+ArtistSplitExceptions = ["AC/DC"]
+EnableDownlods = true
+
+[Scanner]
+ArtistJoiner = " • "

From 4f29465d27d35444683bd7fae70097583ab4b01f Mon Sep 17 00:00:00 2001
From: Kendall Garner <17521368+kgarner7@users.noreply.github.com>
Date: Thu, 30 Jul 2026 01:48:42 +0000
Subject: [PATCH 003/200] fix(artwork): do not promote artist folder to album
 folder (#5856)

* fix(artwork): do not promote artist folder to album folder

* use filesystem join for path instead

* fix(artwork): resolve artist folder for albums with disc subfolders

Dropping the promoted album root from the artist reader's paths fixed the
flat-album case but broke albums whose tracks live in disc subfolders: the
promoted root was what kept the byte-wise longest common prefix on a
directory boundary. Without it, CD1/CD2 siblings share the fragment
"Album/CD", so the artist folder resolved one level too deep and
album/artist.* won over artist.*.

loadAlbumFoldersPaths now collapses each album to its own root before the
paths are compared across albums, so a disc-split album contributes its
album folder rather than each disc folder. Folders no album claims (the
promoted parent) are still returned unchanged, keeping the album, disc and
mediafile readers unaffected. The prefix math moves into commonDir, which
appends a trailing separator so the comparison lands on segment boundaries
- this also fixes sibling folders sharing a name prefix (Album/Album2).

Adds e2e coverage for the case the branch fixes (artist.* with no album/
fallback, which failed before this branch), the disc-subfolder regression,
and a multi-album guard that pins the scope boundary.

* test(artwork): cover artist whose albums are all disc-split

The existing specs cover a single disc-split album and a disc-split album
alongside a flat one, but not an artist where every album is split into
disc subfolders. That layout resolves correctly because the albums diverge
one level above the disc folders, which re-anchors the common prefix - a
property worth pinning so a future change to the path math can't silently
break it.

* fix(artwork): resolve artist folder when albums share a folder

loadArtistFolder decided whether to climb above the common directory by
comparing len(paths) against 2. That count stands in for "how many distinct
album roots are there", and the two diverge when an artist has two albums in
the same folder: the slice holds two identical entries, the climb is skipped,
and the artist folder resolves to the album folder. Deduplicate the roots so
the branch tests the property it means to test.

Replace the includeParent flag with two functions split by audience. The flag
was a caller-identity switch - constant true at the album, disc and mediafile
readers, all of which discard the returned paths, and constant false at the
only caller that reads them. The artist path now has loadArtistAlbumRoots,
which collapses each album to its own root and never consults albumRootParent;
loadAlbumFoldersPaths goes back to taking a single album and always promoting
the parent. Both share the folder load and image aggregation.

This also makes albumRootParent's contract structural. Its guard only rejects
an artist folder when it can find audio outside the album being resolved, so
passing every album of an artist at once made the check meaningless; taking a
single album means it can no longer be called that way.

Drops the per-album grouping and unclaimed-folder reconciliation from the
album path, where the result was discarded, and removes 15 mechanical true
arguments from the tests.

---------

Co-authored-by: Deluan <deluan@navidrome.org>
---
 core/artwork/artwork_internal_test.go |  1 +
 core/artwork/e2e/artist_test.go       | 95 +++++++++++++++++++++++++++
 core/artwork/reader_album.go          | 32 ++++-----
 core/artwork/reader_album_test.go     | 27 ++++++++
 core/artwork/reader_artist.go         | 58 ++++++++++++++--
 core/artwork/reader_artist_test.go    | 13 ++++
 6 files changed, 206 insertions(+), 20 deletions(-)

diff --git a/core/artwork/artwork_internal_test.go b/core/artwork/artwork_internal_test.go
index c95371959..5bcd82f23 100644
--- a/core/artwork/artwork_internal_test.go
+++ b/core/artwork/artwork_internal_test.go
@@ -202,6 +202,7 @@ var _ = Describe("Artwork", func() {
 				repoRoot, err := os.Getwd()
 				Expect(err).ToNot(HaveOccurred())
 				folderRepo.result = []model.Folder{{
+					ID:          "f1",
 					LibraryPath: testFileLibPath(repoRoot),
 					Path:        "tests/fixtures/artist/an-album",
 					ImageFiles:  []string{"artist.png"},
diff --git a/core/artwork/e2e/artist_test.go b/core/artwork/e2e/artist_test.go
index d959b1d60..2079d37ce 100644
--- a/core/artwork/e2e/artist_test.go
+++ b/core/artwork/e2e/artist_test.go
@@ -80,6 +80,101 @@ var _ = Describe("Artist artwork resolution", func() {
 		})
 	})
 
+	When("ArtistArtPriority has no album/ fallback", func() {
+		// Artist/
+		// ├── artist.jpg               ← must resolve via the artist folder itself
+		// └── Album/
+		//     └── 01 - Track.mp3
+		It("still resolves the artist folder and returns artist.*", func() {
+			conf.Server.ArtistArtPriority = "artist.*"
+			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("the artist's only album has its tracks in disc subfolders", func() {
+		// Artist/
+		// ├── artist.jpg               ← wins (artist.* before album/artist.*)
+		// └── Album/
+		//     ├── artist.jpg
+		//     ├── CD1/01 - Track.mp3
+		//     └── CD2/02 - Track.mp3
+		It("prefers the artist-folder image over the album-folder one", func() {
+			conf.Server.ArtistArtPriority = "artist.*, album/artist.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "Track 1", map[string]any{"albumartist": "Artist", "album": "Album"}),
+				"Artist/Album/CD2/02 - Track.mp3": trackFile(2, "Track 2", map[string]any{"albumartist": "Artist", "album": "Album"}),
+				"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("one album has disc subfolders and another sits at artist level", func() {
+		// Artist/
+		// ├── artist.jpg               ← wins
+		// ├── Album1/
+		// │   ├── artist.jpg
+		// │   ├── CD1/01 - Track.mp3
+		// │   └── CD2/02 - Track.mp3
+		// └── Album2/03 - Track.mp3
+		It("prefers the artist-folder image over the album-folder one", func() {
+			conf.Server.ArtistArtPriority = "artist.*, album/artist.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album1/CD1/01 - Track.mp3": trackFile(1, "Track 1", map[string]any{"albumartist": "Artist", "album": "Album1"}),
+				"Artist/Album1/CD2/02 - Track.mp3": trackFile(2, "Track 2", map[string]any{"albumartist": "Artist", "album": "Album1"}),
+				"Artist/Album2/03 - Track.mp3":     trackFile(3, "Track 3", map[string]any{"albumartist": "Artist", "album": "Album2"}),
+				"Artist/artist.jpg":                imageFile("artist-folder"),
+				"Artist/Album1/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("every album of the artist has its tracks in disc subfolders", func() {
+		// Artist/
+		// ├── artist.jpg               ← wins
+		// ├── Album1/
+		// │   ├── artist.jpg
+		// │   ├── CD1/01 - Track.mp3
+		// │   └── CD2/02 - Track.mp3
+		// └── Album2/
+		//     ├── CD1/03 - Track.mp3
+		//     └── CD2/04 - Track.mp3
+		It("prefers the artist-folder image over the album-folder one", func() {
+			conf.Server.ArtistArtPriority = "artist.*, album/artist.*, external"
+			setLayout(fstest.MapFS{
+				"Artist/Album1/CD1/01 - Track.mp3": trackFile(1, "Track 1", map[string]any{"albumartist": "Artist", "album": "Album1"}),
+				"Artist/Album1/CD2/02 - Track.mp3": trackFile(2, "Track 2", map[string]any{"albumartist": "Artist", "album": "Album1"}),
+				"Artist/Album2/CD1/03 - Track.mp3": trackFile(3, "Track 3", map[string]any{"albumartist": "Artist", "album": "Album2"}),
+				"Artist/Album2/CD2/04 - Track.mp3": trackFile(4, "Track 4", map[string]any{"albumartist": "Artist", "album": "Album2"}),
+				"Artist/artist.jpg":                imageFile("artist-folder"),
+				"Artist/Album1/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/
diff --git a/core/artwork/reader_album.go b/core/artwork/reader_album.go
index 8ad07773b..58a47c8ae 100644
--- a/core/artwork/reader_album.go
+++ b/core/artwork/reader_album.go
@@ -20,6 +20,7 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils"
 	"github.com/navidrome/navidrome/utils/natural"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 type albumArtworkReader struct {
@@ -103,17 +104,13 @@ func (a *albumArtworkReader) fromCoverArtPriority(ctx context.Context, ffmpeg ff
 	return ff
 }
 
-func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...model.Album) ([]string, []string, *time.Time, error) {
-	var folderIDs []string
-	for _, album := range albums {
-		folderIDs = append(folderIDs, album.FolderIDs...)
-	}
-	folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderIDs, "missing": false}})
+func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, album model.Album) ([]string, []string, *time.Time, error) {
+	folders, err := loadFolders(ctx, ds, album.FolderIDs)
 	if err != nil {
 		return nil, nil, nil, err
 	}
 
-	parent, err := albumRootParent(ctx, ds, folders, folderIDs)
+	parent, err := albumRootParent(ctx, ds, folders, album.FolderIDs)
 	if err != nil {
 		return nil, nil, nil, err
 	}
@@ -121,11 +118,21 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...mo
 		folders = append(folders, *parent)
 	}
 
-	var paths []string
+	paths := slice.Map(folders, func(f model.Folder) string { return f.AbsolutePath() })
+	imgFiles, updatedAt := folderImages(folders)
+	return paths, imgFiles, &updatedAt, nil
+}
+
+func loadFolders(ctx context.Context, ds model.DataStore, folderIDs []string) ([]model.Folder, error) {
+	return ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderIDs, "missing": false}})
+}
+
+// folderImages collects the folders' image files, sorted so files without
+// numeric suffixes win (e.g. cover.jpg over cover.1.jpg).
+func folderImages(folders []model.Folder) ([]string, time.Time) {
 	var imgFiles []string
 	var updatedAt time.Time
 	for _, f := range folders {
-		paths = append(paths, f.AbsolutePath())
 		if f.ImagesUpdatedAt.After(updatedAt) {
 			updatedAt = f.ImagesUpdatedAt
 		}
@@ -134,13 +141,8 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, albums ...mo
 			imgFiles = append(imgFiles, path.Join(rel, img))
 		}
 	}
-
-	// Sort image files to ensure consistent selection of cover art
-	// This prioritizes files without numeric suffixes (e.g., cover.jpg over cover.1.jpg)
-	// by comparing base filenames without extensions
 	slices.SortFunc(imgFiles, compareImageFiles)
-
-	return paths, imgFiles, &updatedAt, nil
+	return imgFiles, updatedAt
 }
 
 // albumRootParent returns the common parent of the album's folders when it
diff --git a/core/artwork/reader_album_test.go b/core/artwork/reader_album_test.go
index fe4a1a545..c95ddedaa 100644
--- a/core/artwork/reader_album_test.go
+++ b/core/artwork/reader_album_test.go
@@ -3,6 +3,7 @@ package artwork
 import (
 	"context"
 	"errors"
+	"path/filepath"
 	"time"
 
 	"github.com/navidrome/navidrome/model"
@@ -339,6 +340,32 @@ var _ = Describe("Album Artwork Reader", func() {
 			Expect(repo.getCallCount).To(Equal(1))
 		})
 
+		It("promotes the album root parent into the returned paths", func() {
+			repo.result = []model.Folder{
+				{
+					ID:              "folder1",
+					Path:            "Artist",
+					Name:            "Album",
+					ParentID:        "artistFolder",
+					ImagesUpdatedAt: now,
+					ImageFiles:      []string{},
+				},
+			}
+			repo.parentResult = &model.Folder{
+				ID:              "artistFolder",
+				Path:            ".",
+				Name:            "Artist",
+				ParentID:        "libraryRoot",
+				ImagesUpdatedAt: expectedAt,
+				ImageFiles:      []string{"folder.jpg"},
+			}
+
+			paths, _, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(paths).To(Equal([]string{filepath.Join("Artist", "Album"), "Artist"}))
+		})
+
 		It("does not include parent images when other albums' audio lives under the parent", func() {
 			// Simulates: Artist/folder.jpg with Artist/Album (no images) and
 			// another album's tracks elsewhere under the artist folder
diff --git a/core/artwork/reader_artist.go b/core/artwork/reader_artist.go
index 37b7b6dee..fe5bcb196 100644
--- a/core/artwork/reader_artist.go
+++ b/core/artwork/reader_artist.go
@@ -19,6 +19,7 @@ import (
 	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/navidrome/navidrome/utils/str"
 )
 
@@ -54,7 +55,7 @@ func newArtistArtworkReader(ctx context.Context, artwork *artwork, artID model.A
 	if err != nil {
 		return nil, err
 	}
-	albumPaths, imgFiles, imagesUpdatedAt, err := loadAlbumFoldersPaths(ctx, artwork.ds, als...)
+	albumPaths, imgFiles, imagesUpdatedAt, err := loadArtistAlbumRoots(ctx, artwork.ds, als)
 	if err != nil {
 		return nil, err
 	}
@@ -232,17 +233,64 @@ func escapeGlobLiteral(s string) string {
 	return b.String()
 }
 
+// loadArtistAlbumRoots returns one path per album — the deepest folder holding
+// all of that album's tracks — so an album split into disc subfolders can't
+// pull the artist folder's common prefix below the artist level.
+func loadArtistAlbumRoots(ctx context.Context, ds model.DataStore, albums model.Albums) ([]string, []string, *time.Time, error) {
+	var folderIDs []string
+	for _, album := range albums {
+		folderIDs = append(folderIDs, album.FolderIDs...)
+	}
+	folders, err := loadFolders(ctx, ds, folderIDs)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+
+	pathByID := slice.ToMap(folders, func(f model.Folder) (string, string) {
+		return f.ID, f.AbsolutePath()
+	})
+	var roots []string
+	for _, album := range albums {
+		var albumPaths []string
+		for _, fid := range album.FolderIDs {
+			if p, ok := pathByID[fid]; ok {
+				albumPaths = append(albumPaths, p)
+			}
+		}
+		if len(albumPaths) > 0 {
+			roots = append(roots, commonDir(albumPaths))
+		}
+	}
+
+	imgFiles, updatedAt := folderImages(folders)
+	return roots, imgFiles, &updatedAt, nil
+}
+
+// commonDir returns the deepest directory containing all paths. Trailing
+// separators keep the comparison on segment boundaries, so a shared name
+// fragment (".../Album" and ".../Album2") is never read as a shared directory.
+func commonDir(paths []string) string {
+	sep := string(filepath.Separator)
+	common := str.LongestCommonPrefix(slice.Map(paths, func(p string) string { return p + sep }))
+	if !strings.HasSuffix(common, sep) {
+		common, _ = filepath.Split(common)
+	}
+	return filepath.Clean(common)
+}
+
 func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albums, paths []string) (string, time.Time, error) {
 	if len(albums) == 0 {
 		return "", time.Time{}, nil
 	}
 	libID := albums[0].LibraryID // Just need one of the albums, as they should all be in the same Library - for now! TODO: Support multiple libraries
 
-	folderPath := str.LongestCommonPrefix(paths)
-	if !strings.HasSuffix(folderPath, string(filepath.Separator)) {
-		folderPath, _ = filepath.Split(folderPath)
+	// paths holds one root per album: two or more distinct roots already meet at
+	// the artist folder, while a single root is an album folder needing a climb.
+	roots := slices.Compact(slices.Sorted(slices.Values(paths)))
+	folderPath := commonDir(roots)
+	if len(roots) < 2 {
+		folderPath = filepath.Dir(folderPath)
 	}
-	folderPath = filepath.Dir(folderPath)
 
 	// Manipulate the path to get the folder ID
 	// TODO: This is a bit hacky, but it's the easiest way to get the folder ID, ATM
diff --git a/core/artwork/reader_artist_test.go b/core/artwork/reader_artist_test.go
index 6d6d58fc5..c75f8447e 100644
--- a/core/artwork/reader_artist_test.go
+++ b/core/artwork/reader_artist_test.go
@@ -85,6 +85,19 @@ var _ = Describe("artistArtworkReader", func() {
 			})
 		})
 
+		When("two albums share the same folder", func() {
+			It("climbs above the shared album folder", func() {
+				paths = []string{
+					filepath.FromSlash("/music/artist/split"),
+					filepath.FromSlash("/music/artist/split"),
+				}
+				folder, upd, err := loadArtistFolder(ctx, fds, albums, paths)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
+				Expect(upd).To(Equal(expectedUpdTime))
+			})
+		})
+
 		When("the album paths contain same prefix", func() {
 			It("returns the common prefix", func() {
 				paths = []string{

From 600ea5482c36d3705fbca1d9ab749d9bdafd6f80 Mon Sep 17 00:00:00 2001
From: fxj368 <62541194+fxj368@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:36:37 +0800
Subject: [PATCH 004/200] fix(ui): update Chinese (Simplified) translation
 (#5873)

Signed-off-by: Deluan <deluan@navidrome.org>
---
 resources/i18n/zh-Hans.json | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/resources/i18n/zh-Hans.json b/resources/i18n/zh-Hans.json
index 21778506a..24f55357a 100644
--- a/resources/i18n/zh-Hans.json
+++ b/resources/i18n/zh-Hans.json
@@ -32,7 +32,7 @@
         "rating": "评分",
         "quality": "品质",
         "bpm": "BPM",
-        "playDate": "最后一次播放",
+        "playDate": "上次播放",
         "createdAt": "加入日期",
         "grouping": "分组",
         "mood": "情绪",
@@ -184,7 +184,7 @@
         "maxBitRate": "最大比特率",
         "client": "客户端",
         "userName": "用户名",
-        "lastSeen": "上次浏览",
+        "lastSeen": "上次使用",
         "reportRealPath": "报告真实路径",
         "scrobbleEnabled": "发送个性化记录到外部服务"
       }
@@ -210,7 +210,8 @@
         "songCount": "歌曲数",
         "comment": "注释",
         "sync": "自动导入",
-        "path": "导入路径"
+        "path": "导入路径",
+        "starred": "收藏"
       },
       "actions": {
         "selectPlaylist": "选择歌单",
@@ -530,7 +531,7 @@
       "no_results": "未找到结果",
       "no_more_results": "页码 %{page} 超出范围，尝试返回上一页",
       "page_out_of_boundaries": "页码 %{page} 超出范围",
-      "page_out_from_end": "已经最后一页",
+      "page_out_from_end": "已经是最后一页",
       "page_out_from_begin": "已经是第一页",
       "page_range_info": "%{offsetBegin}-%{offsetEnd} / %{total}",
       "page_rows_per_page": "每页项目数：",
@@ -636,6 +637,7 @@
     "albumList": "专辑",
     "playlists": "歌单",
     "sharedPlaylists": "共享的歌单",
+    "onlyFavourites": "仅显示收藏项",
     "about": "关于"
   },
   "player": {
@@ -668,10 +670,10 @@
       "homepage": "主页",
       "source": "源代码",
       "featureRequests": "功能需求",
-      "lastInsightsCollection": "最近的分析收集",
+      "lastInsightsCollection": "上次的匿名数据收集",
       "insights": {
-        "disabled": "禁用",
-        "waiting": "等待"
+        "disabled": "已禁用",
+        "waiting": "等待中"
       }
     },
     "tabs": {

From d23b68a4385d42b647cb2c349ba5e1ac36fc4c1e Mon Sep 17 00:00:00 2001
From: Mateusz Piotrowski <mpp302@gmail.com>
Date: Fri, 31 Jul 2026 14:54:29 +0200
Subject: [PATCH 005/200] fix: typo in description of --prometheus.enabled
 (#5878)

Remove a stray back tick.
---
 cmd/root.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmd/root.go b/cmd/root.go
index 9e2b38cd8..d9e766c32 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -394,7 +394,7 @@ func init() {
 	rootCmd.Flags().String("albumplaycountmode", viper.GetString("albumplaycountmode"), "how to compute playcount for albums. absolute (default) or normalized")
 	rootCmd.Flags().Bool("autoimportplaylists", viper.GetBool("autoimportplaylists"), "enable/disable .m3u playlist auto-import`")
 
-	rootCmd.Flags().Bool("prometheus.enabled", viper.GetBool("prometheus.enabled"), "enable/disable prometheus metrics endpoint`")
+	rootCmd.Flags().Bool("prometheus.enabled", viper.GetBool("prometheus.enabled"), "enable/disable prometheus metrics endpoint")
 	rootCmd.Flags().String("prometheus.metricspath", viper.GetString("prometheus.metricspath"), "http endpoint for prometheus metrics")
 
 	_ = viper.BindPFlag("address", rootCmd.Flags().Lookup("address"))

From 810b14ed571412e7a7ddb568ebee69ac1498faea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 2 Aug 2026 12:27:08 -0400
Subject: [PATCH 006/200] fix(plugins): confine plugin filesystem mounts to
 their root (#5881)

* fix(plugins): confine plugin filesystem mounts to their root

A plugin granted read-write filesystem access could escape its mount by
creating a relative symlink inside it and then writing through that link,
reaching any path the server process can write, including navidrome.db.

wazero resolves guest paths by concatenating them onto the host root. Its
WASI layer validates every path argument except the symlink target, which
path_symlink forwards unvalidated by design, and fs.ValidPath splits on
"/" only, so on Windows a "..\" path escapes the mount as well.

Mounts now go through a jailedFS wrapper that denies symlink creation and
rejects any path that is not filepath.IsLocal. That requires bypassing
extism's AllowedPaths, which discards any FSConfig passed alongside it, so
the mounts are built directly and applied per instance instead. Following
symlinks that already exist in a mount is unchanged: music libraries rely
on it, and read-only mounts already reject creating new ones.

* test(plugins): guard against setting extism AllowedPaths

Extracts the extism manifest construction so a test can assert AllowedPaths
is never set. Setting it makes extism build its own FSConfig and discard the
jailed mounts, silently restoring the symlink escape.

Verified by simulating the regression: with AllowedPaths populated for plugins
holding the filesystem permission, the new spec fails, as do two of the
end-to-end sandbox specs.
---
 plugins/manager_loader.go             |  59 +++------
 plugins/manager_loader_test.go        |  86 ++++--------
 plugins/manager_plugin.go             |  16 ++-
 plugins/plugins_suite_test.go         |  62 +++++----
 plugins/sandbox_fs.go                 | 157 ++++++++++++++++++++++
 plugins/sandbox_fs_internal_test.go   | 127 ++++++++++++++++++
 plugins/sandbox_fs_test.go            | 182 ++++++++++++++++++++++++++
 plugins/testdata/test-library/main.go |  26 +++-
 8 files changed, 572 insertions(+), 143 deletions(-)
 create mode 100644 plugins/sandbox_fs.go
 create mode 100644 plugins/sandbox_fs_internal_test.go
 create mode 100644 plugins/sandbox_fs_test.go

diff --git a/plugins/manager_loader.go b/plugins/manager_loader.go
index 0ba5fcf76..fc9296427 100644
--- a/plugins/manager_loader.go
+++ b/plugins/manager_loader.go
@@ -307,22 +307,10 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 		return fmt.Errorf("opening package: %w", err)
 	}
 
-	// Build extism manifest
-	pluginManifest := extism.Manifest{
-		Wasm: []extism.Wasm{
-			extism.WasmData{Data: pkg.WasmBytes, Name: "main"},
-		},
-		Config:  pluginConfig,
-		Timeout: uint64(defaultTimeout.Milliseconds()),
-	}
+	pluginManifest := buildExtismManifest(pkg, pluginConfig)
 
-	if pkg.Manifest.Permissions != nil && pkg.Manifest.Permissions.Http != nil {
-		if hosts := pkg.Manifest.Permissions.Http.RequiredHosts; len(hosts) > 0 {
-			pluginManifest.AllowedHosts = hosts
-		}
-	}
-
-	// Configure filesystem access for library permission
+	// Configure filesystem access for library permission, applied per instance
+	var fsConfig wazero.FSConfig
 	if pkg.Manifest.HasLibraryFilesystemPermission() {
 		adminCtx := adminContext(ctx)
 		libraries, err := m.ds.Library(adminCtx).GetAll()
@@ -330,8 +318,7 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 			return fmt.Errorf("failed to get libraries for filesystem access: %w", err)
 		}
 
-		allowedPaths := buildAllowedPaths(ctx, libraries, allowedLibraries, p.AllLibraries, p.AllowWriteAccess)
-		pluginManifest.AllowedPaths = allowedPaths
+		fsConfig = buildFSConfig(buildMounts(ctx, libraries, allowedLibraries, p.AllLibraries, p.AllowWriteAccess))
 	}
 
 	// Build host functions based on permissions from manifest
@@ -386,7 +373,7 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 	}
 
 	// Create instance to detect capabilities
-	instance, err := compiled.Instance(ctx, extism.PluginInstanceConfig{})
+	instance, err := compiled.Instance(ctx, instanceConfig(fsConfig))
 	if err != nil {
 		compiled.Close(ctx)
 		return fmt.Errorf("creating instance: %w", err)
@@ -413,6 +400,7 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 		allowedUserIDs: allowedUsers,
 		allUsers:       p.AllUsers,
 		libraries:      newLibraryAccess(allowedLibraries, p.AllLibraries),
+		fsConfig:       fsConfig,
 		lyricsSem:      make(chan struct{}, maxConcurrentLyricsCalls),
 	}
 	m.mu.Unlock()
@@ -459,31 +447,18 @@ func parsePluginConfig(configJSON string) (map[string]string, error) {
 	return pluginConfig, nil
 }
 
-// buildAllowedPaths constructs the extism AllowedPaths map for filesystem access.
-// When allowWriteAccess is false (default), paths are prefixed with "ro:" for read-only.
-// Only libraries that match the allowed set (or all libraries if allLibraries is true) are included.
-func buildAllowedPaths(ctx context.Context, libraries model.Libraries, allowedLibraryIDs []int, allLibraries, allowWriteAccess bool) map[string]string {
-	allowedLibrarySet := make(map[int]struct{}, len(allowedLibraryIDs))
-	for _, id := range allowedLibraryIDs {
-		allowedLibrarySet[id] = struct{}{}
+// buildExtismManifest describes the plugin to extism. It must never set
+// AllowedPaths: extism would replace our jailed FSConfig with plain dir mounts.
+func buildExtismManifest(pkg *ndpPackage, pluginConfig map[string]string) extism.Manifest {
+	manifest := extism.Manifest{
+		Wasm:    []extism.Wasm{extism.WasmData{Data: pkg.WasmBytes, Name: "main"}},
+		Config:  pluginConfig,
+		Timeout: uint64(defaultTimeout.Milliseconds()),
 	}
-	allowedPaths := make(map[string]string)
-	for _, lib := range libraries {
-		_, allowed := allowedLibrarySet[lib.ID]
-		if allLibraries || allowed {
-			mountPoint := toPluginMountPoint(int32(lib.ID))
-			hostPath := lib.Path
-			if !allowWriteAccess {
-				hostPath = "ro:" + hostPath
-			}
-			allowedPaths[hostPath] = mountPoint
-			log.Trace(ctx, "Added library to allowed paths", "libraryID", lib.ID, "mountPoint", mountPoint, "writeAccess", allowWriteAccess, "hostPath", hostPath)
+	if pkg.Manifest.Permissions != nil && pkg.Manifest.Permissions.Http != nil {
+		if hosts := pkg.Manifest.Permissions.Http.RequiredHosts; len(hosts) > 0 {
+			manifest.AllowedHosts = hosts
 		}
 	}
-	if allowWriteAccess {
-		log.Info(ctx, "Granting read-write filesystem access to libraries", "libraryCount", len(allowedPaths), "allLibraries", allLibraries)
-	} else {
-		log.Debug(ctx, "Granting read-only filesystem access to libraries", "libraryCount", len(allowedPaths), "allLibraries", allLibraries)
-	}
-	return allowedPaths
+	return manifest
 }
diff --git a/plugins/manager_loader_test.go b/plugins/manager_loader_test.go
index cc07f0611..5e6851481 100644
--- a/plugins/manager_loader_test.go
+++ b/plugins/manager_loader_test.go
@@ -1,11 +1,32 @@
 package plugins
 
 import (
-	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
+var _ = Describe("buildExtismManifest", func() {
+	var pkg *ndpPackage
+
+	BeforeEach(func() {
+		pkg = &ndpPackage{
+			WasmBytes: []byte("wasm"),
+			Manifest: &Manifest{Permissions: &Permissions{
+				Library: &LibraryPermission{Reason: new("test"), Filesystem: true},
+				Http:    &HTTPPermission{Reason: new("test"), RequiredHosts: []string{"example.com"}},
+			}},
+		}
+	})
+
+	It("never sets AllowedPaths, even with filesystem permission", func() {
+		Expect(buildExtismManifest(pkg, nil).AllowedPaths).To(BeEmpty())
+	})
+
+	It("carries the hosts the plugin is allowed to reach", func() {
+		Expect(buildExtismManifest(pkg, nil).AllowedHosts).To(Equal([]string{"example.com"}))
+	})
+})
+
 var _ = Describe("parsePluginConfig", func() {
 	It("returns nil for empty string", func() {
 		result, err := parsePluginConfig("")
@@ -57,66 +78,3 @@ var _ = Describe("parsePluginConfig", func() {
 		Expect(result).ToNot(BeNil())
 	})
 })
-
-var _ = Describe("buildAllowedPaths", func() {
-	var libraries model.Libraries
-
-	BeforeEach(func() {
-		libraries = model.Libraries{
-			{ID: 1, Path: "/music/library1"},
-			{ID: 2, Path: "/music/library2"},
-			{ID: 3, Path: "/music/library3"},
-		}
-	})
-
-	Context("read-only (default)", func() {
-		It("mounts all libraries with ro: prefix when allLibraries is true", func() {
-			result := buildAllowedPaths(nil, libraries, nil, true, false)
-			Expect(result).To(HaveLen(3))
-			Expect(result).To(HaveKeyWithValue("ro:/music/library1", "/libraries/1"))
-			Expect(result).To(HaveKeyWithValue("ro:/music/library2", "/libraries/2"))
-			Expect(result).To(HaveKeyWithValue("ro:/music/library3", "/libraries/3"))
-		})
-
-		It("mounts only selected libraries with ro: prefix", func() {
-			result := buildAllowedPaths(nil, libraries, []int{1, 3}, false, false)
-			Expect(result).To(HaveLen(2))
-			Expect(result).To(HaveKeyWithValue("ro:/music/library1", "/libraries/1"))
-			Expect(result).To(HaveKeyWithValue("ro:/music/library3", "/libraries/3"))
-			Expect(result).ToNot(HaveKey("ro:/music/library2"))
-		})
-	})
-
-	Context("read-write (allowWriteAccess=true)", func() {
-		It("mounts all libraries without ro: prefix when allLibraries is true", func() {
-			result := buildAllowedPaths(nil, libraries, nil, true, true)
-			Expect(result).To(HaveLen(3))
-			Expect(result).To(HaveKeyWithValue("/music/library1", "/libraries/1"))
-			Expect(result).To(HaveKeyWithValue("/music/library2", "/libraries/2"))
-			Expect(result).To(HaveKeyWithValue("/music/library3", "/libraries/3"))
-		})
-
-		It("mounts only selected libraries without ro: prefix", func() {
-			result := buildAllowedPaths(nil, libraries, []int{2}, false, true)
-			Expect(result).To(HaveLen(1))
-			Expect(result).To(HaveKeyWithValue("/music/library2", "/libraries/2"))
-		})
-	})
-
-	Context("edge cases", func() {
-		It("returns empty map when no libraries match", func() {
-			result := buildAllowedPaths(nil, libraries, []int{99}, false, false)
-			Expect(result).To(BeEmpty())
-		})
-
-		It("returns empty map when libraries list is empty", func() {
-			result := buildAllowedPaths(nil, nil, []int{1}, false, false)
-			Expect(result).To(BeEmpty())
-		})
-
-		It("returns empty map when allLibraries is false and no IDs provided", func() {
-			result := buildAllowedPaths(nil, libraries, nil, false, false)
-			Expect(result).To(BeEmpty())
-		})
-	})
-})
diff --git a/plugins/manager_plugin.go b/plugins/manager_plugin.go
index 155663781..13375a70f 100644
--- a/plugins/manager_plugin.go
+++ b/plugins/manager_plugin.go
@@ -24,16 +24,24 @@ type plugin struct {
 	allowedUserIDs []string // User IDs this plugin can access (from DB configuration)
 	allUsers       bool     // If true, plugin can access all users
 	libraries      libraryAccess
-	lyricsSem      chan struct{} // Caps concurrent lyrics calls (see LyricsPlugin.GetLyrics)
+	lyricsSem      chan struct{}   // Caps concurrent lyrics calls (see LyricsPlugin.GetLyrics)
+	fsConfig       wazero.FSConfig // Sandboxed library mounts, nil if no filesystem permission
+}
+
+// instanceConfig is used by every call site, so all instances get the sandboxed mounts.
+func instanceConfig(fsConfig wazero.FSConfig) extism.PluginInstanceConfig {
+	moduleConfig := wazero.NewModuleConfig().WithSysWalltime().WithRandSource(rand.Reader)
+	if fsConfig != nil {
+		moduleConfig = moduleConfig.WithFSConfig(fsConfig)
+	}
+	return extism.PluginInstanceConfig{ModuleConfig: moduleConfig}
 }
 
 // instance creates a new plugin instance for the given context.
 // The context is used for cancellation - if cancelled during a call,
 // the module will be terminated and the instance becomes unusable.
 func (p *plugin) instance(ctx context.Context) (*extism.Plugin, error) {
-	instance, err := p.compiled.Instance(ctx, extism.PluginInstanceConfig{
-		ModuleConfig: wazero.NewModuleConfig().WithSysWalltime().WithRandSource(rand.Reader),
-	})
+	instance, err := p.compiled.Instance(ctx, instanceConfig(p.fsConfig))
 	if err != nil {
 		return nil, err
 	}
diff --git a/plugins/plugins_suite_test.go b/plugins/plugins_suite_test.go
index bb081988e..77956e2f9 100644
--- a/plugins/plugins_suite_test.go
+++ b/plugins/plugins_suite_test.go
@@ -12,6 +12,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strings"
 	"testing"
 	"time"
 
@@ -81,46 +82,43 @@ func createTestManagerWithPlugins(pluginConfig map[string]map[string]string, plu
 	return createTestManagerWithPluginsAndMetrics(pluginConfig, noopMetricsRecorder{}, plugins...)
 }
 
+// installTestPlugins copies the given .ndp packages into dir and returns their
+// enabled DB rows, so callers can grant whatever access the test needs.
+func installTestPlugins(dir string, plugins ...string) model.Plugins {
+	var rows model.Plugins
+	for _, plugin := range plugins {
+		data, err := os.ReadFile(filepath.Join(testdataDir, plugin))
+		Expect(err).ToNot(HaveOccurred())
+		destPath := filepath.Join(dir, plugin)
+		Expect(os.WriteFile(destPath, data, 0600)).To(Succeed())
+
+		hash := sha256.Sum256(data)
+		rows = append(rows, model.Plugin{
+			ID:      strings.TrimSuffix(plugin, PackageExtension),
+			Path:    destPath,
+			SHA256:  hex.EncodeToString(hash[:]),
+			Enabled: true,
+		})
+	}
+	return rows
+}
+
 // createTestManagerWithPluginsAndMetrics creates a new plugin Manager with the given plugin config,
-// metrics recorder, and specified plugins. It creates a temp directory, copies the specified plugins, and starts the manager.
-// Returns the manager and temp directory path.
+// metrics recorder, and specified plugins. It creates a temp directory, copies the specified plugins,
+// and starts the manager. Returns the manager and temp directory path.
 func createTestManagerWithPluginsAndMetrics(pluginConfig map[string]map[string]string, metrics PluginMetricsRecorder, plugins ...string) (*Manager, string) {
 	// Create temp directory
 	tmpDir, err := os.MkdirTemp("", "plugins-test-*")
 	Expect(err).ToNot(HaveOccurred())
 
-	// Copy test plugins to temp dir and build plugin list with SHA256
-	var enabledPlugins model.Plugins
-	for _, plugin := range plugins {
-		srcPath := filepath.Join(testdataDir, plugin)
-		destPath := filepath.Join(tmpDir, plugin)
-		data, err := os.ReadFile(srcPath)
-		Expect(err).ToNot(HaveOccurred())
-		err = os.WriteFile(destPath, data, 0600)
-		Expect(err).ToNot(HaveOccurred())
-
-		// Compute SHA256 for the plugin
-		hash := sha256.Sum256(data)
-		hashHex := hex.EncodeToString(hash[:])
-		pluginName := plugin[:len(plugin)-len(PackageExtension)] // Remove .ndp extension
-
-		// Build config JSON if provided
-		configJSON := ""
-		if pluginConfig != nil && pluginConfig[pluginName] != nil {
-			// Encode config to JSON
-			configBytes, err := json.Marshal(pluginConfig[pluginName])
+	enabledPlugins := installTestPlugins(tmpDir, plugins...)
+	for i, p := range enabledPlugins {
+		enabledPlugins[i].AllUsers = true // Allow all users by default in tests
+		if pluginConfig[p.ID] != nil {
+			configBytes, err := json.Marshal(pluginConfig[p.ID])
 			Expect(err).ToNot(HaveOccurred())
-			configJSON = string(configBytes)
+			enabledPlugins[i].Config = string(configBytes)
 		}
-
-		enabledPlugins = append(enabledPlugins, model.Plugin{
-			ID:       pluginName,
-			Path:     destPath,
-			SHA256:   hashHex,
-			Enabled:  true,
-			Config:   configJSON,
-			AllUsers: true, // Allow all users by default in tests
-		})
 	}
 
 	// Setup config
diff --git a/plugins/sandbox_fs.go b/plugins/sandbox_fs.go
new file mode 100644
index 000000000..57bba85af
--- /dev/null
+++ b/plugins/sandbox_fs.go
@@ -0,0 +1,157 @@
+package plugins
+
+import (
+	"context"
+	"io/fs"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/tetratelabs/wazero"
+	experimentalsys "github.com/tetratelabs/wazero/experimental/sys"
+	"github.com/tetratelabs/wazero/experimental/sysfs"
+	"github.com/tetratelabs/wazero/sys"
+)
+
+// jailedFS confines a mount to its root: wazero resolves guest paths by bare
+// concatenation. Named field, not embedding, so a new sys.FS method can't slip through.
+type jailedFS struct {
+	fs experimentalsys.FS
+}
+
+// escapes reports whether a guest path can resolve outside the mount root.
+// WASI only validates "/"-separated paths, missing `..\`, `C:x` and device names.
+func escapes(path string) bool {
+	switch path {
+	case "", ".", "/": // how wazero opens the mount root itself
+		return false
+	}
+	return !filepath.IsLocal(path)
+}
+
+func (jailedFS) Symlink(string, string) experimentalsys.Errno {
+	return experimentalsys.EPERM
+}
+
+func (j jailedFS) OpenFile(path string, flag experimentalsys.Oflag, perm fs.FileMode) (experimentalsys.File, experimentalsys.Errno) {
+	if escapes(path) {
+		return nil, experimentalsys.EPERM
+	}
+	return j.fs.OpenFile(path, flag, perm)
+}
+
+func (j jailedFS) Lstat(path string) (sys.Stat_t, experimentalsys.Errno) {
+	if escapes(path) {
+		return sys.Stat_t{}, experimentalsys.EPERM
+	}
+	return j.fs.Lstat(path)
+}
+
+func (j jailedFS) Stat(path string) (sys.Stat_t, experimentalsys.Errno) {
+	if escapes(path) {
+		return sys.Stat_t{}, experimentalsys.EPERM
+	}
+	return j.fs.Stat(path)
+}
+
+func (j jailedFS) Mkdir(path string, perm fs.FileMode) experimentalsys.Errno {
+	if escapes(path) {
+		return experimentalsys.EPERM
+	}
+	return j.fs.Mkdir(path, perm)
+}
+
+func (j jailedFS) Chmod(path string, perm fs.FileMode) experimentalsys.Errno {
+	if escapes(path) {
+		return experimentalsys.EPERM
+	}
+	return j.fs.Chmod(path, perm)
+}
+
+func (j jailedFS) Rename(from, to string) experimentalsys.Errno {
+	if escapes(from) || escapes(to) {
+		return experimentalsys.EPERM
+	}
+	return j.fs.Rename(from, to)
+}
+
+func (j jailedFS) Rmdir(path string) experimentalsys.Errno {
+	if escapes(path) {
+		return experimentalsys.EPERM
+	}
+	return j.fs.Rmdir(path)
+}
+
+func (j jailedFS) Unlink(path string) experimentalsys.Errno {
+	if escapes(path) {
+		return experimentalsys.EPERM
+	}
+	return j.fs.Unlink(path)
+}
+
+func (j jailedFS) Link(oldPath, newPath string) experimentalsys.Errno {
+	if escapes(oldPath) || escapes(newPath) {
+		return experimentalsys.EPERM
+	}
+	return j.fs.Link(oldPath, newPath)
+}
+
+func (j jailedFS) Readlink(path string) (string, experimentalsys.Errno) {
+	if escapes(path) {
+		return "", experimentalsys.EPERM
+	}
+	return j.fs.Readlink(path)
+}
+
+func (j jailedFS) Utimens(path string, atim, mtim int64) experimentalsys.Errno {
+	if escapes(path) {
+		return experimentalsys.EPERM
+	}
+	return j.fs.Utimens(path, atim, mtim)
+}
+
+// mount is a host directory exposed to a plugin at guestPath.
+type mount struct {
+	hostPath  string
+	guestPath string
+	readOnly  bool
+}
+
+// buildMounts lists the libraries the plugin may reach through the filesystem.
+func buildMounts(ctx context.Context, libraries model.Libraries, allowedLibraryIDs []int, allLibraries, allowWriteAccess bool) []mount {
+	allowedLibrarySet := make(map[int]struct{}, len(allowedLibraryIDs))
+	for _, id := range allowedLibraryIDs {
+		allowedLibrarySet[id] = struct{}{}
+	}
+	var mounts []mount
+	for _, lib := range libraries {
+		_, allowed := allowedLibrarySet[lib.ID]
+		if allLibraries || allowed {
+			m := mount{hostPath: lib.Path, guestPath: toPluginMountPoint(int32(lib.ID)), readOnly: !allowWriteAccess}
+			mounts = append(mounts, m)
+			log.Trace(ctx, "Added library to plugin mounts", "libraryID", lib.ID, "mountPoint", m.guestPath, "readOnly", m.readOnly, "hostPath", m.hostPath)
+		}
+	}
+	if allowWriteAccess {
+		log.Info(ctx, "Granting read-write filesystem access to libraries", "libraryCount", len(mounts), "allLibraries", allLibraries)
+	} else {
+		log.Debug(ctx, "Granting read-only filesystem access to libraries", "libraryCount", len(mounts), "allLibraries", allLibraries)
+	}
+	return mounts
+}
+
+// buildFSConfig mounts each host directory jailed to its root.
+func buildFSConfig(mounts []mount) wazero.FSConfig {
+	if len(mounts) == 0 {
+		return nil
+	}
+	cfg := wazero.NewFSConfig()
+	for _, m := range mounts {
+		var mounted experimentalsys.FS = jailedFS{fs: sysfs.DirFS(m.hostPath)}
+		if m.readOnly {
+			mounted = &sysfs.ReadFS{FS: mounted}
+		}
+		cfg = cfg.(sysfs.FSConfig).WithSysFSMount(mounted, m.guestPath)
+	}
+	return cfg
+}
diff --git a/plugins/sandbox_fs_internal_test.go b/plugins/sandbox_fs_internal_test.go
new file mode 100644
index 000000000..73011225d
--- /dev/null
+++ b/plugins/sandbox_fs_internal_test.go
@@ -0,0 +1,127 @@
+package plugins
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	experimentalsys "github.com/tetratelabs/wazero/experimental/sys"
+	"github.com/tetratelabs/wazero/experimental/sysfs"
+)
+
+var _ = Describe("buildMounts", func() {
+	var libraries model.Libraries
+
+	BeforeEach(func() {
+		libraries = model.Libraries{
+			{ID: 1, Path: "/music/library1"},
+			{ID: 2, Path: "/music/library2"},
+			{ID: 3, Path: "/music/library3"},
+		}
+	})
+
+	It("mounts all libraries read-only by default", func() {
+		Expect(buildMounts(nil, libraries, nil, true, false)).To(Equal([]mount{
+			{hostPath: "/music/library1", guestPath: "/libraries/1", readOnly: true},
+			{hostPath: "/music/library2", guestPath: "/libraries/2", readOnly: true},
+			{hostPath: "/music/library3", guestPath: "/libraries/3", readOnly: true},
+		}))
+	})
+
+	It("mounts only the selected libraries", func() {
+		Expect(buildMounts(nil, libraries, []int{1, 3}, false, false)).To(Equal([]mount{
+			{hostPath: "/music/library1", guestPath: "/libraries/1", readOnly: true},
+			{hostPath: "/music/library3", guestPath: "/libraries/3", readOnly: true},
+		}))
+	})
+
+	It("mounts writable when write access is granted", func() {
+		Expect(buildMounts(nil, libraries, []int{2}, false, true)).To(Equal([]mount{
+			{hostPath: "/music/library2", guestPath: "/libraries/2", readOnly: false},
+		}))
+	})
+
+	DescribeTable("mounts nothing",
+		func(libs model.Libraries, allowedIDs []int, allLibraries bool) {
+			Expect(buildMounts(nil, libs, allowedIDs, allLibraries, false)).To(BeEmpty())
+		},
+		Entry("when no library matches", libraries, []int{99}, false),
+		Entry("when there are no libraries", model.Libraries(nil), []int{1}, false),
+		Entry("when no library is selected", libraries, nil, false),
+	)
+})
+
+var _ = Describe("jailedFS", func() {
+	var (
+		fs         jailedFS
+		root       string
+		outsideDir string
+	)
+
+	BeforeEach(func() {
+		tmpDir := GinkgoT().TempDir()
+		root = filepath.Join(tmpDir, "root")
+		outsideDir = filepath.Join(tmpDir, "outside")
+		Expect(os.MkdirAll(root, 0755)).To(Succeed())
+		Expect(os.MkdirAll(outsideDir, 0755)).To(Succeed())
+		Expect(os.WriteFile(filepath.Join(outsideDir, "secret.txt"), []byte("secret"), 0600)).To(Succeed())
+
+		fs = jailedFS{sysfs.DirFS(root)}
+	})
+
+	It("denies creating symlinks", func() {
+		Expect(fs.Symlink("../outside", "link")).To(Equal(experimentalsys.EPERM))
+	})
+
+	It("denies reading through a path that escapes the root", func() {
+		_, errno := fs.OpenFile("../outside/secret.txt", experimentalsys.O_RDONLY, 0)
+		Expect(errno).To(Equal(experimentalsys.EPERM))
+	})
+
+	It("denies traversal with the host separator", func() {
+		_, errno := fs.OpenFile(`..\outside\secret.txt`, experimentalsys.O_RDONLY, 0)
+
+		if runtime.GOOS == "windows" {
+			Expect(errno).To(Equal(experimentalsys.EPERM))
+		} else {
+			// A backslash is a legal filename character on POSIX, not a separator
+			Expect(errno).To(Equal(experimentalsys.ENOENT))
+		}
+	})
+
+	It("denies absolute paths", func() {
+		_, errno := fs.OpenFile("/etc/passwd", experimentalsys.O_RDONLY, 0)
+		Expect(errno).To(Equal(experimentalsys.EPERM))
+	})
+
+	It("denies creating a directory outside the root", func() {
+		Expect(fs.Mkdir("../outside/new-dir", 0755)).To(Equal(experimentalsys.EPERM))
+		Expect(filepath.Join(outsideDir, "new-dir")).ToNot(BeADirectory())
+	})
+
+	It("denies escaping through either side of a rename", func() {
+		Expect(fs.Rename("../outside/secret.txt", "stolen.txt")).To(Equal(experimentalsys.EPERM))
+		Expect(fs.Rename("inside.txt", "../outside/leaked.txt")).To(Equal(experimentalsys.EPERM))
+	})
+
+	// Music libraries symlink in folders from elsewhere; following them is intended
+	It("follows symlinks that already exist in the mount", func() {
+		if err := os.Symlink(outsideDir, filepath.Join(root, "linked")); err != nil {
+			Skip("cannot create symlinks here: " + err.Error()) // Windows without privileges
+		}
+
+		_, errno := fs.OpenFile("linked/secret.txt", experimentalsys.O_RDONLY, 0)
+		Expect(errno).To(BeZero())
+	})
+
+	It("allows access within the root", func() {
+		Expect(fs.Mkdir("sub", 0755)).To(BeZero())
+		f, errno := fs.OpenFile("sub/file.txt", experimentalsys.O_CREAT|experimentalsys.O_WRONLY, 0600)
+		Expect(errno).To(BeZero())
+		Expect(f.Close()).To(BeZero())
+		Expect(filepath.Join(root, "sub", "file.txt")).To(BeAnExistingFile())
+	})
+})
diff --git a/plugins/sandbox_fs_test.go b/plugins/sandbox_fs_test.go
new file mode 100644
index 000000000..ea033283f
--- /dev/null
+++ b/plugins/sandbox_fs_test.go
@@ -0,0 +1,182 @@
+//go:build !windows
+
+package plugins
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type sandboxInput struct {
+	Operation  string `json:"operation"`
+	MountPoint string `json:"mount_point,omitempty"`
+	FilePath   string `json:"file_path,omitempty"`
+	Content    string `json:"content,omitempty"`
+	Target     string `json:"target,omitempty"`
+}
+
+type sandboxOutput struct {
+	FileContent string  `json:"file_content,omitempty"`
+	Error       *string `json:"error,omitempty"`
+}
+
+// startSandboxManager loads test-library against libraryDir with the given grant.
+func startSandboxManager(tmpDir, libraryDir string, grant func(*model.Plugin)) *Manager {
+	GinkgoHelper()
+	installed := installTestPlugins(tmpDir, "test-library"+PackageExtension)
+	grant(&installed[0])
+
+	DeferCleanup(configtest.SetupConfig())
+	conf.Server.Plugins.Enabled = true
+	conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
+	conf.Server.Plugins.AutoReload = false
+
+	mockPluginRepo := tests.CreateMockPluginRepo()
+	mockPluginRepo.Permitted = true
+	mockPluginRepo.SetData(installed)
+
+	mockLibraryRepo := &tests.MockLibraryRepo{}
+	mockLibraryRepo.SetData(model.Libraries{{ID: 1, Name: "Test Library", Path: libraryDir}})
+
+	manager := &Manager{
+		plugins:        make(map[string]*plugin),
+		ds:             &tests.MockDataStore{MockedPlugin: mockPluginRepo, MockedLibrary: mockLibraryRepo},
+		subsonicRouter: http.NotFoundHandler(),
+	}
+	Expect(manager.Start(GinkgoT().Context())).To(Succeed())
+	DeferCleanup(func() { _ = manager.Stop() })
+	return manager
+}
+
+// callSandbox runs one filesystem operation inside the plugin sandbox.
+func callSandbox(manager *Manager, input sandboxInput) sandboxOutput {
+	GinkgoHelper()
+	manager.mu.RLock()
+	p := manager.plugins["test-library"]
+	manager.mu.RUnlock()
+	Expect(p).ToNot(BeNil())
+
+	instance, err := p.instance(context.Background())
+	Expect(err).ToNot(HaveOccurred())
+	defer instance.Close(context.Background())
+
+	inputBytes, err := json.Marshal(input)
+	Expect(err).ToNot(HaveOccurred())
+	_, outputBytes, err := instance.Call("nd_test_library", inputBytes)
+	Expect(err).ToNot(HaveOccurred())
+
+	var output sandboxOutput
+	Expect(json.Unmarshal(outputBytes, &output)).To(Succeed())
+	return output
+}
+
+var _ = Describe("Plugin filesystem sandbox", Ordered, ContinueOnFailure, func() {
+	var (
+		manager    *Manager
+		libraryDir string
+		outsideDir string
+		secretFile string
+		mountPoint string
+	)
+
+	call := func(input sandboxInput) sandboxOutput {
+		GinkgoHelper()
+		input.MountPoint = mountPoint
+		return callSandbox(manager, input)
+	}
+
+	BeforeAll(func() {
+		tmpDir := GinkgoT().TempDir()
+		libraryDir = filepath.Join(tmpDir, "music-library")
+		Expect(os.MkdirAll(libraryDir, 0755)).To(Succeed())
+
+		// Sibling of the mount root: anything reached here escaped the sandbox
+		outsideDir = filepath.Join(tmpDir, "outside")
+		Expect(os.MkdirAll(outsideDir, 0755)).To(Succeed())
+		secretFile = filepath.Join(outsideDir, "secret.txt")
+		Expect(os.WriteFile(secretFile, []byte("secret"), 0600)).To(Succeed())
+
+		mountPoint = toPluginMountPoint(1)
+		manager = startSandboxManager(tmpDir, libraryDir, func(p *model.Plugin) {
+			p.AllLibraries = true
+			p.AllowWriteAccess = true
+		})
+	})
+
+	It("allows writing inside the mount", func() {
+		out := call(sandboxInput{Operation: "write_file", FilePath: "inside.txt", Content: "hello"})
+
+		Expect(out.Error).To(BeNil())
+		Expect(os.ReadFile(filepath.Join(libraryDir, "inside.txt"))).To(BeEquivalentTo("hello"))
+	})
+
+	It("cannot escape the mount by creating a symlink", func() {
+		linked := call(sandboxInput{Operation: "symlink", FilePath: "escape", Target: "../outside"})
+		Expect(linked.Error).ToNot(BeNil())
+		_, err := os.Lstat(filepath.Join(libraryDir, "escape"))
+		Expect(err).To(MatchError(os.ErrNotExist), "the plugin created a symlink out of the mount")
+
+		wrote := call(sandboxInput{Operation: "write_file", FilePath: "escape/via-created-symlink.txt", Content: "escaped"})
+
+		Expect(wrote.Error).ToNot(BeNil())
+		Expect(filepath.Join(outsideDir, "via-created-symlink.txt")).ToNot(BeAnExistingFile())
+	})
+
+	// Accepted residual, pinned so a future tightening can't happen silently
+	It("still follows a symlink planted in the mount by something else", func() {
+		Expect(os.Symlink(outsideDir, filepath.Join(libraryDir, "planted"))).To(Succeed())
+
+		out := call(sandboxInput{Operation: "write_file", FilePath: "planted/via-symlink.txt", Content: "escaped"})
+
+		Expect(out.Error).To(BeNil())
+		Expect(filepath.Join(outsideDir, "via-symlink.txt")).To(BeAnExistingFile())
+	})
+
+	It("cannot read outside the mount with ..", func() {
+		out := call(sandboxInput{Operation: "read_file", FilePath: "../outside/secret.txt"})
+
+		Expect(out.Error).ToNot(BeNil())
+		Expect(out.FileContent).ToNot(Equal("secret"))
+	})
+
+	It("cannot write outside the mount with ..", func() {
+		out := call(sandboxInput{Operation: "write_file", FilePath: "../outside/via-dotdot.txt", Content: "escaped"})
+
+		Expect(out.Error).ToNot(BeNil())
+		Expect(filepath.Join(outsideDir, "via-dotdot.txt")).ToNot(BeAnExistingFile())
+	})
+})
+
+var _ = Describe("Plugin filesystem sandbox without library access", Ordered, func() {
+	var manager *Manager
+	var libraryDir string
+
+	BeforeAll(func() {
+		tmpDir := GinkgoT().TempDir()
+		libraryDir = filepath.Join(tmpDir, "music-library")
+		Expect(os.MkdirAll(libraryDir, 0755)).To(Succeed())
+		Expect(os.WriteFile(filepath.Join(libraryDir, "track.txt"), []byte("audio"), 0600)).To(Succeed())
+
+		manager = startSandboxManager(tmpDir, libraryDir, func(*model.Plugin) {})
+	})
+
+	It("mounts nothing when no library is granted", func() {
+		manager.mu.RLock()
+		p := manager.plugins["test-library"]
+		manager.mu.RUnlock()
+		Expect(p.fsConfig).To(BeNil())
+
+		out := callSandbox(manager, sandboxInput{Operation: "read_file", MountPoint: toPluginMountPoint(1), FilePath: "track.txt"})
+		Expect(out.Error).ToNot(BeNil())
+	})
+})
diff --git a/plugins/testdata/test-library/main.go b/plugins/testdata/test-library/main.go
index 9c04c5f9b..e83c9aec6 100644
--- a/plugins/testdata/test-library/main.go
+++ b/plugins/testdata/test-library/main.go
@@ -14,10 +14,12 @@ import (
 
 // TestLibraryInput is the input for nd_test_library callback.
 type TestLibraryInput struct {
-	Operation  string `json:"operation"` // "get_library", "get_all_libraries", "read_file", "list_dir"
+	Operation  string `json:"operation"` // "get_library", "get_all_libraries", "read_file", "list_dir", "write_file", "symlink"
 	LibraryID  int32  `json:"library_id,omitempty"`
 	MountPoint string `json:"mount_point,omitempty"` // For filesystem operations
 	FilePath   string `json:"file_path,omitempty"`   // For read_file operation (relative to mount point)
+	Content    string `json:"content,omitempty"`     // For write_file operation
+	Target     string `json:"target,omitempty"`      // For symlink operation
 }
 
 // TestLibraryOutput is the output from nd_test_library callback.
@@ -88,6 +90,28 @@ func ndTestLibrary() int32 {
 		pdk.OutputJSON(TestLibraryOutput{DirEntries: names})
 		return 0
 
+	case "write_file":
+		// Write a file to the mounted library directory
+		fullPath := filepath.Join(input.MountPoint, input.FilePath)
+		if err := os.WriteFile(fullPath, []byte(input.Content), 0600); err != nil {
+			errStr := err.Error()
+			pdk.OutputJSON(TestLibraryOutput{Error: &errStr})
+			return 0
+		}
+		pdk.OutputJSON(TestLibraryOutput{})
+		return 0
+
+	case "symlink":
+		// Create a symlink inside the mounted library directory
+		fullPath := filepath.Join(input.MountPoint, input.FilePath)
+		if err := os.Symlink(input.Target, fullPath); err != nil {
+			errStr := err.Error()
+			pdk.OutputJSON(TestLibraryOutput{Error: &errStr})
+			return 0
+		}
+		pdk.OutputJSON(TestLibraryOutput{})
+		return 0
+
 	default:
 		errStr := "unknown operation: " + input.Operation
 		pdk.OutputJSON(TestLibraryOutput{Error: &errStr})

From b40b41584ad5e4e08430aabcd2a0d6484c998bc2 Mon Sep 17 00:00:00 2001
From: Kendall Garner <17521368+kgarner7@users.noreply.github.com>
Date: Sun, 2 Aug 2026 09:39:51 -0700
Subject: [PATCH 007/200] feat(subsonic): Implement OpenSubsonic
 topSongsByArtistId extension (#5853)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* implement topSongsByArtistId extension

* do not look up by artist name if empty

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 core/artwork/e2e/helpers_test.go              |  2 +-
 core/external/provider.go                     | 34 ++++++--
 core/external/provider_topsongs_test.go       | 84 +++++++++++++++----
 server/subsonic/browsing.go                   |  5 +-
 server/subsonic/e2e/e2e_suite_test.go         |  2 +-
 server/subsonic/e2e/subsonic_browsing_test.go | 68 ++++++++-------
 server/subsonic/opensubsonic.go               |  1 +
 server/subsonic/opensubsonic_test.go          |  6 +-
 8 files changed, 143 insertions(+), 59 deletions(-)

diff --git a/core/artwork/e2e/helpers_test.go b/core/artwork/e2e/helpers_test.go
index e3abca097..ddc926cec 100644
--- a/core/artwork/e2e/helpers_test.go
+++ b/core/artwork/e2e/helpers_test.go
@@ -171,7 +171,7 @@ func (n *noopProvider) UpdateArtistInfo(context.Context, string, int, bool) (*mo
 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) {
+func (n *noopProvider) TopSongs(context.Context, string, string, int) (model.MediaFiles, error) {
 	return nil, nil
 }
 func (n *noopProvider) ArtistImage(context.Context, string) (*url.URL, error) {
diff --git a/core/external/provider.go b/core/external/provider.go
index 459e8a205..869841e06 100644
--- a/core/external/provider.go
+++ b/core/external/provider.go
@@ -34,7 +34,7 @@ type Provider interface {
 	UpdateAlbumInfo(ctx context.Context, id string) (*model.Album, error)
 	UpdateArtistInfo(ctx context.Context, id string, count int, includeNotPresent bool) (*model.Artist, error)
 	SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error)
-	TopSongs(ctx context.Context, artist string, count int) (model.MediaFiles, error)
+	TopSongs(ctx context.Context, artist, artistId string, count int) (model.MediaFiles, error)
 	ArtistImage(ctx context.Context, id string) (*url.URL, error)
 	AlbumImage(ctx context.Context, id string) (*url.URL, error)
 }
@@ -440,11 +440,16 @@ func (e *provider) AlbumImage(ctx context.Context, id string) (*url.URL, error)
 	return url.Parse(img.URL)
 }
 
-func (e *provider) TopSongs(ctx context.Context, artistName string, count int) (model.MediaFiles, error) {
-	artist, err := e.findArtistByName(ctx, artistName)
+func (e *provider) TopSongs(ctx context.Context, artistName, id string, count int) (model.MediaFiles, error) {
+	artist, err := e.findArtist(ctx, artistName, id)
 	if err != nil {
-		log.Error(ctx, "Artist not found", "name", artistName, err)
-		return nil, nil
+		if errors.Is(err, model.ErrNotFound) {
+			log.Error(ctx, "Artist not found", "name", artistName, "id", id, err)
+			return nil, nil
+		}
+
+		log.Error(ctx, "Failure occurred when trying to fetch artist", "name", artistName, "id", id, err)
+		return nil, err
 	}
 
 	songs, err := e.getMatchingTopSongs(ctx, e.ag, artist, count)
@@ -713,7 +718,24 @@ func (e *provider) loadArtistsByName(ctx context.Context, similar []agents.Artis
 	return matches, nil
 }
 
-func (e *provider) findArtistByName(ctx context.Context, artistName string) (*auxArtist, error) {
+func (e *provider) findArtist(ctx context.Context, artistName, id string) (*auxArtist, error) {
+	if id != "" {
+		artist, err := e.ds.Artist(ctx).Get(id)
+		if err == nil {
+			return &auxArtist{Artist: *artist}, nil
+		}
+
+		if errors.Is(err, model.ErrNotFound) {
+			log.Warn(ctx, "Could not find artist by id", "id", id, err)
+		} else {
+			return nil, err
+		}
+	}
+
+	if artistName == "" {
+		return nil, model.ErrNotFound
+	}
+
 	artists, err := e.ds.Artist(ctx).GetAll(model.QueryOptions{
 		Filters: squirrel.Like{"artist.name": artistName},
 		Max:     1,
diff --git a/core/external/provider_topsongs_test.go b/core/external/provider_topsongs_test.go
index 86f9110e2..795a7ff74 100644
--- a/core/external/provider_topsongs_test.go
+++ b/core/external/provider_topsongs_test.go
@@ -65,7 +65,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-song-2"}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 2)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 2)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(2))
@@ -76,6 +76,59 @@ var _ = Describe("Provider - TopSongs", func() {
 		mediaFileRepo.AssertExpectations(GinkgoT())
 	})
 
+	Context("artist id and/or name", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One", MbzArtistID: "mbid-artist-1"}
+
+		BeforeEach(func() {
+			agentSongs := []agents.Song{{Name: "Song One", MBID: "mbid-song-1"}}
+			ag.On("GetArtistTopSongs", ctx, "artist-1", "Artist One", "mbid-artist-1", 2).Return(agentSongs, nil).Once()
+
+			song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-song-1"}
+			mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
+		})
+
+		It("returns top songs for a known artist by id only", func() {
+			artistRepo.On("Get", "artist-1").Return(&artist1, nil).Once()
+
+			songs, err := p.TopSongs(ctx, "", "artist-1", 2)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(songs).To(HaveLen(1))
+			Expect(songs[0].ID).To(Equal("song-1"))
+			artistRepo.AssertExpectations(GinkgoT())
+			ag.AssertExpectations(GinkgoT())
+			mediaFileRepo.AssertExpectations(GinkgoT())
+		})
+
+		It("returns top songs for a known artist by id, falling back to name", func() {
+			artistRepo.On("Get", "fake-id").Return(nil, model.ErrNotFound).Once()
+			artistRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.Artists{artist1}, nil).Once()
+
+			songs, err := p.TopSongs(ctx, "Artist One", "fake-id", 2)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(songs).To(HaveLen(1))
+			Expect(songs[0].ID).To(Equal("song-1"))
+			artistRepo.AssertExpectations(GinkgoT())
+			ag.AssertExpectations(GinkgoT())
+			mediaFileRepo.AssertExpectations(GinkgoT())
+		})
+	})
+
+	It("bails if lookup by id returns a fatal error", func() {
+		artistRepo.On("Get", "artist-1").Return(nil, model.ErrInvalidAuth).Once()
+		songs, err := p.TopSongs(ctx, "Artist One", "artist-1", 2)
+		Expect(songs).To(BeEmpty())
+		Expect(err).To(HaveOccurred())
+	})
+
+	It("bails if lookup by name returns a fatal error", func() {
+		artistRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(nil, model.ErrInvalidAuth).Once()
+		songs, err := p.TopSongs(ctx, "Artist One", "", 2)
+		Expect(songs).To(BeEmpty())
+		Expect(err).To(HaveOccurred())
+	})
+
 	It("backfills name and MBID onto an unnamed primary credit (the queried artist) and matches", func() {
 		artist1 := model.Artist{ID: "artist-1", Name: "Artist One", MbzArtistID: "mbid-artist-1"}
 		artistRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.Artists{artist1}, nil)
@@ -96,7 +149,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{track}, nil)
 
-		songs, err := p.TopSongs(ctx, "Artist One", 1)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 1)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(1))
@@ -116,7 +169,8 @@ var _ = Describe("Provider - TopSongs", func() {
 		ag.On("GetArtistTopSongs", ctx, "artist-1", "Artist One", "mbid-artist-1", 1).Return(agentSongs, nil).Once()
 
 		// Library track is credited to Artist One (the queried artist) under a same title. If the
-		// queried MBID were wrongly stamped onto the "Artist Two" credit, that mismatched name+MBID
+		// queried MBID were wrongly stamped onto the "Artist Two" credit, that mismatched name+MBID			artistRepo.On("Get", "fake-id").Return(nil, model.ErrNotFound).Once()
+
 		// could mis-resolve. With the guard, "Artist Two" stays MBID-less and does not match One's track.
 		track := model.MediaFile{
 			ID: "one-track", Title: "Collab Song", ArtistID: "artist-1",
@@ -126,7 +180,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{track}, nil)
 
-		songs, err := p.TopSongs(ctx, "Artist One", 1)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 1)
 
 		Expect(err).ToNot(HaveOccurred())
 		// "Artist Two" (named, MBID-less, not in the library) does not resolve to One's track.
@@ -137,7 +191,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		// Mock artist not found
 		artistRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.Artists{}, nil).Once()
 
-		songs, err := p.TopSongs(ctx, "Unknown Artist", 5)
+		songs, err := p.TopSongs(ctx, "Unknown Artist", "", 5)
 
 		Expect(err).ToNot(HaveOccurred()) // TopSongs returns nil error if artist not found
 		Expect(songs).To(BeNil())
@@ -154,7 +208,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		agentErr := errors.New("agent error")
 		ag.On("GetArtistTopSongs", ctx, "artist-1", "Artist One", "mbid-artist-1", 5).Return(nil, agentErr).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 5)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 5)
 
 		Expect(err).To(MatchError(agentErr))
 		Expect(songs).To(BeNil())
@@ -170,7 +224,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		// Mock agent ErrNotFound
 		ag.On("GetArtistTopSongs", ctx, "artist-1", "Artist One", "mbid-artist-1", 5).Return(nil, agents.ErrNotFound).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 5)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 5)
 
 		Expect(err).To(MatchError(model.ErrNotFound))
 		Expect(songs).To(BeNil())
@@ -191,7 +245,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-song-1"}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 1)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 1)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(1))
@@ -220,7 +274,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once() // bulk MBID query
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{}, nil).Once()      // title track-fetch for song2: no match
 
-		songs, err := p.TopSongs(ctx, "Artist One", 2)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 2)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(1))
@@ -242,7 +296,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		ag.On("GetArtistTopSongs", canceledCtx, "artist-1", "Artist One", "mbid-artist-1", 5).Return(nil, context.Canceled).Once()
 
 		cancel() // Cancel the context before calling
-		songs, err := p.TopSongs(canceledCtx, "Artist One", 5)
+		songs, err := p.TopSongs(canceledCtx, "Artist One", "", 5)
 
 		Expect(err).To(MatchError(context.Canceled))
 		Expect(songs).To(BeNil())
@@ -276,7 +330,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 2)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 2)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(2))
@@ -313,7 +367,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song2}, nil).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 2)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 2)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(2))
@@ -341,7 +395,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1", MbzRecordingID: "mbid-song-2"}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 1)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 1)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(1))
@@ -369,7 +423,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		song2 := model.MediaFile{ID: "song-2", Title: "Song Two", ArtistID: "artist-1"}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1, song2}, nil).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 2)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 2)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(2))
@@ -397,7 +451,7 @@ var _ = Describe("Provider - TopSongs", func() {
 		song1 := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-song-1"}
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
 
-		songs, err := p.TopSongs(ctx, "Artist One", 1)
+		songs, err := p.TopSongs(ctx, "Artist One", "", 1)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(1))
diff --git a/server/subsonic/browsing.go b/server/subsonic/browsing.go
index f6a7047c4..59d267321 100644
--- a/server/subsonic/browsing.go
+++ b/server/subsonic/browsing.go
@@ -381,13 +381,14 @@ func (api *Router) GetSimilarSongs2(r *http.Request) (*responses.Subsonic, error
 func (api *Router) GetTopSongs(r *http.Request) (*responses.Subsonic, error) {
 	ctx := r.Context()
 	p := req.Params(r)
+	id, idErr := p.String("id")
 	artist, err := p.String("artist")
-	if err != nil {
+	if err != nil && idErr != nil {
 		return nil, err
 	}
 	count := p.IntOr("count", 50)
 
-	songs, err := api.provider.TopSongs(ctx, artist, count)
+	songs, err := api.provider.TopSongs(ctx, artist, id, count)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return nil, err
 	}
diff --git a/server/subsonic/e2e/e2e_suite_test.go b/server/subsonic/e2e/e2e_suite_test.go
index 4e9039d68..97d7fb40a 100644
--- a/server/subsonic/e2e/e2e_suite_test.go
+++ b/server/subsonic/e2e/e2e_suite_test.go
@@ -353,7 +353,7 @@ func (n noopProvider) SimilarSongs(context.Context, string, int) (model.MediaFil
 	return nil, nil
 }
 
-func (n noopProvider) TopSongs(context.Context, string, int) (model.MediaFiles, error) {
+func (n noopProvider) TopSongs(context.Context, string, string, int) (model.MediaFiles, error) {
 	return nil, nil
 }
 
diff --git a/server/subsonic/e2e/subsonic_browsing_test.go b/server/subsonic/e2e/subsonic_browsing_test.go
index 55aeb8e9e..992f9e0fb 100644
--- a/server/subsonic/e2e/subsonic_browsing_test.go
+++ b/server/subsonic/e2e/subsonic_browsing_test.go
@@ -13,6 +13,15 @@ var _ = Describe("Browsing Endpoints", func() {
 		setupTestDB()
 	})
 
+	getBeatlesId := func() string {
+		artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
+			Filters: squirrel.Eq{"name": "The Beatles"},
+		})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(artists).ToNot(BeEmpty())
+		return artists[0].ID
+	}
+
 	Describe("getMusicFolders", func() {
 		It("returns the configured music library", func() {
 			resp := doReq("getMusicFolders")
@@ -85,12 +94,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getMusicDirectory", func() {
 		It("returns an artist directory with its albums as children", func() {
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
-				Filters: squirrel.Eq{"name": "The Beatles"},
-			})
-			Expect(err).ToNot(HaveOccurred())
-			Expect(artists).ToNot(BeEmpty())
-			beatlesID := artists[0].ID
+			beatlesID := getBeatlesId()
 
 			resp := doReq("getMusicDirectory", "id", beatlesID)
 
@@ -125,12 +129,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getArtist", func() {
 		It("returns artist with albums in ID3 format", func() {
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
-				Filters: squirrel.Eq{"name": "The Beatles"},
-			})
-			Expect(err).ToNot(HaveOccurred())
-			Expect(artists).ToNot(BeEmpty())
-			beatlesID := artists[0].ID
+			beatlesID := getBeatlesId()
 
 			resp := doReq("getArtist", "id", beatlesID)
 
@@ -141,12 +140,7 @@ var _ = Describe("Browsing Endpoints", func() {
 		})
 
 		It("returns album names for the artist", func() {
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
-				Filters: squirrel.Eq{"name": "The Beatles"},
-			})
-			Expect(err).ToNot(HaveOccurred())
-			Expect(artists).ToNot(BeEmpty())
-			beatlesID := artists[0].ID
+			beatlesID := getBeatlesId()
 
 			resp := doReq("getArtist", "id", beatlesID)
 
@@ -381,13 +375,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getArtistInfo", func() {
 		It("returns artist info for a valid artist", func() {
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
-				Filters: squirrel.Eq{"name": "The Beatles"},
-			})
-			Expect(err).ToNot(HaveOccurred())
-			Expect(artists).ToNot(BeEmpty())
-			beatlesID := artists[0].ID
-
+			beatlesID := getBeatlesId()
 			resp := doReq("getArtistInfo", "id", beatlesID)
 
 			Expect(resp.Status).To(Equal(responses.StatusOK))
@@ -397,13 +385,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getArtistInfo2", func() {
 		It("returns artist info2 for a valid artist", func() {
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
-				Filters: squirrel.Eq{"name": "The Beatles"},
-			})
-			Expect(err).ToNot(HaveOccurred())
-			Expect(artists).ToNot(BeEmpty())
-			beatlesID := artists[0].ID
-
+			beatlesID := getBeatlesId()
 			resp := doReq("getArtistInfo2", "id", beatlesID)
 
 			Expect(resp.Status).To(Equal(responses.StatusOK))
@@ -426,6 +408,28 @@ var _ = Describe("Browsing Endpoints", func() {
 			Expect(resp.TopSongs).ToNot(BeNil())
 			Expect(resp.TopSongs.Song).To(BeEmpty())
 		})
+
+		It("returns an error if no arguments are specified", func() {
+			resp := doReq("getTopSongs")
+			Expect(resp.Status).To(Equal(responses.StatusFailed))
+			Expect(resp.TopSongs).To(BeNil())
+		})
+
+		It("returns a response only by id", func() {
+			beatlesID := getBeatlesId()
+			resp := doReq("getTopSongs", "id", beatlesID)
+
+			Expect(resp.Status).To(Equal(responses.StatusOK))
+			Expect(resp.TopSongs).ToNot(BeNil())
+		})
+
+		It("returns a response when both id and name are included", func() {
+			beatlesID := getBeatlesId()
+			resp := doReq("getTopSongs", "id", beatlesID, "artist", "The Beatles")
+
+			Expect(resp.Status).To(Equal(responses.StatusOK))
+			Expect(resp.TopSongs).ToNot(BeNil())
+		})
 	})
 
 	Describe("getSimilarSongs", func() {
diff --git a/server/subsonic/opensubsonic.go b/server/subsonic/opensubsonic.go
index 97b3cafcc..2b2a31bf3 100644
--- a/server/subsonic/opensubsonic.go
+++ b/server/subsonic/opensubsonic.go
@@ -15,6 +15,7 @@ func (api *Router) GetOpenSubsonicExtensions(_ *http.Request) (*responses.Subson
 		{Name: "indexBasedQueue", Versions: []int32{1}},
 		{Name: "transcoding", Versions: []int32{1}},
 		{Name: "playbackReport", Versions: []int32{1}},
+		{Name: "topSongsByArtistId", Versions: []int32{1}},
 	}
 	if api.sonic != nil && api.sonic.HasProvider() {
 		extensions = append(extensions, responses.OpenSubsonicExtension{
diff --git a/server/subsonic/opensubsonic_test.go b/server/subsonic/opensubsonic_test.go
index e4217303f..2615a652d 100644
--- a/server/subsonic/opensubsonic_test.go
+++ b/server/subsonic/opensubsonic_test.go
@@ -55,13 +55,14 @@ var _ = Describe("GetOpenSubsonicExtensions", func() {
 			err := json.Unmarshal(w.Body.Bytes(), &response)
 			Expect(err).NotTo(HaveOccurred())
 			Expect(*response.Subsonic.OpenSubsonicExtensions).To(SatisfyAll(
-				HaveLen(6),
+				HaveLen(7),
 				ContainElement(responses.OpenSubsonicExtension{Name: "transcodeOffset", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "formPost", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "songLyrics", Versions: []int32{1, 2}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "indexBasedQueue", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "transcoding", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "playbackReport", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "topSongsByArtistId", Versions: []int32{1}}),
 			))
 			Expect(*response.Subsonic.OpenSubsonicExtensions).NotTo(
 				ContainElement(responses.OpenSubsonicExtension{Name: "sonicSimilarity", Versions: []int32{1}}),
@@ -85,7 +86,7 @@ var _ = Describe("GetOpenSubsonicExtensions", func() {
 			err := json.Unmarshal(w.Body.Bytes(), &response)
 			Expect(err).NotTo(HaveOccurred())
 			Expect(*response.Subsonic.OpenSubsonicExtensions).To(SatisfyAll(
-				HaveLen(7),
+				HaveLen(8),
 				ContainElement(responses.OpenSubsonicExtension{Name: "transcodeOffset", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "formPost", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "songLyrics", Versions: []int32{1, 2}}),
@@ -93,6 +94,7 @@ var _ = Describe("GetOpenSubsonicExtensions", func() {
 				ContainElement(responses.OpenSubsonicExtension{Name: "transcoding", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "playbackReport", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "sonicSimilarity", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "topSongsByArtistId", Versions: []int32{1}}),
 			))
 		})
 	})

From f853ca604a534e6916ea9a2e2bda5a27dc185bb7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 2 Aug 2026 12:58:53 -0400
Subject: [PATCH 008/200] refactor(db): migrate all ids to a uniform canonical
 128-bit base62 encoding (#5824)

* refactor(model): extract canonical 128-bit base62 id codec

* feat(model): generate random ids as canonical 128-bit base62 values

* feat(scanner): emit legacy PIDs in canonical base62 encoding

* feat(db): add id canonicalization transform for the uniform-ids migration

* feat(db): migrate all ids to canonical 128-bit base62 encoding

* fix(db): canonicalize ids in junction tables and JSON columns

* chore(jellyfin): update id-family notes for uniform canonical ids

* test(ids): harden codec input contract and migration edge coverage

* refactor(model): use log.Fatal for Encode128 contract guard per project convention

* fix(db): force full rescan after id migration for legacy PID configs

* test(db): guard id-column inventory against schema drift

* refactor(ids): compile-time Encode128 contract and unified column rewrite helper

* refactor(db): apply review feedback to id migration

Filter empty strings in collectColumn's SQL, reuse a prepared statement
for rewriteColumn updates, and clarify the legacy ID functions' comment
now that they emit the canonical encoding.

* feat(auth): split session and public-link JWT secrets, rotating sessions on id migration

* test(subsonic): initialize public token secret in helpers suite

The suite sets auth.TokenAuth directly instead of calling auth.Init, so the
new PublicTokenAuth was nil whenever Ginkgo's spec order ran a helpers spec
before any spec that calls auth.Init, panicking in publicurl.ImageURL.

* refactor(db): inline canonicalID into its only consumer, the uniform-ids migration

* refactor(model): rename Encode128/Decode128 to Encode/Decode

With every id now exactly 128 bits, the width suffix is redundant; the
package-qualified id.Encode/id.Decode carries the same information.

* test(db): make the id-columns guard classify JSON columns too

The guard only inspected columns named id/pid/*_id, so it could not see ids
embedded in JSON. Widen it to *_ids and to every JSON column, and drive the
"covered" set from a new embeddedIDColumns list instead of the inline calls
in the migration.

Every JSON column the schema has now carries a verdict. The four denormalized
caches -- media_file/album.participants, media_file/album.tags,
album.folder_ids and artist.similar_artists -- hold only artist, tag and
folder ids. Those all come from id.NewHash, whose 22-char base62 encoding of
a 128-bit MD5 is already in canonical range, so canonicalID is the identity
on them and the migration correctly leaves them alone. A new codec test pins
that invariant, since the exemptions depend on it.

Verified on a copy of a 727MB/96k-track production database: canonicalizing
those four columns changed zero rows, and artist, tag and folder ids were
themselves unchanged by the migration (only media_file ids moved, 95108 of
96666).
---
 consts/consts.go                              |   1 +
 core/auth/auth.go                             |  53 +--
 core/auth/auth_test.go                        |  45 +++
 core/publicurl/publicurl_test.go              |   2 +-
 .../20260720015443_uniform_canonical_ids.go   | 310 ++++++++++++++++++
 db/migrations/id_canonical_test.go            |  47 +++
 db/migrations/id_columns_guard_test.go        | 119 +++++++
 db/migrations/migrations_suite_test.go        |  16 +
 db/migrations/uniform_canonical_ids_test.go   | 233 +++++++++++++
 model/id/id.go                                |  36 +-
 model/id/id_suite_test.go                     |  17 +
 model/id/id_test.go                           |  64 ++++
 model/metadata/legacy_ids.go                  |  15 +-
 model/metadata/persistent_ids_test.go         |  15 +
 plugins/host_artwork_test.go                  |   2 +-
 server/jellyfin/README.md                     |  16 +-
 server/jellyfin/dto/ids.go                    |   2 +-
 server/jellyfin/dto/ids_test.go               |   2 +-
 server/jellyfin/truncated_ids.go              |   4 +-
 server/public/handle_images.go                |   2 +-
 server/public/handle_images_test.go           |   2 +-
 server/public/handle_shares.go                |   4 +-
 server/public/handle_streams.go               |   2 +-
 server/public/handle_streams_test.go          |   6 +-
 server/subsonic/helpers_test.go               |   1 +
 25 files changed, 957 insertions(+), 59 deletions(-)
 create mode 100644 db/migrations/20260720015443_uniform_canonical_ids.go
 create mode 100644 db/migrations/id_canonical_test.go
 create mode 100644 db/migrations/id_columns_guard_test.go
 create mode 100644 db/migrations/migrations_suite_test.go
 create mode 100644 db/migrations/uniform_canonical_ids_test.go
 create mode 100644 model/id/id_suite_test.go
 create mode 100644 model/id/id_test.go

diff --git a/consts/consts.go b/consts/consts.go
index f453ac125..e1a535c79 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -28,6 +28,7 @@ const (
 	UIAuthorizationHeader  = "X-ND-Authorization"
 	UIClientUniqueIDHeader = "X-ND-Client-Unique-Id"
 	JWTSecretKey           = "JWTSecret"
+	JWTPublicSecretKey     = "JWTPublicSecret"
 	JWTIssuer              = "ND"
 	DefaultSessionTimeout  = 48 * time.Hour
 	CookieExpiry           = 365 * 24 * 3600 // One year
diff --git a/core/auth/auth.go b/core/auth/auth.go
index 7b3511bdf..b1e2667bd 100644
--- a/core/auth/auth.go
+++ b/core/auth/auth.go
@@ -19,35 +19,41 @@ import (
 )
 
 var (
-	once      sync.Once
+	once sync.Once
+	// TokenAuth signs UI/API session tokens. Rotated by the id migration so stale sessions die.
 	TokenAuth *jwtauth.JWTAuth
+	// PublicTokenAuth signs public-link tokens (artwork, share streams), on a separate secret that survives the rotation.
+	PublicTokenAuth *jwtauth.JWTAuth
 )
 
-// Init creates a JWTAuth object from the secret stored in the DB.
-// If the secret is not found, it will create a new one and store it in the DB.
+// Init creates the JWTAuth objects from the secrets stored in the DB.
+// Missing or undecryptable secrets are regenerated and stored.
 func Init(ds model.DataStore) {
 	once.Do(func() {
 		ctx := context.TODO()
 		log.Info("Setting Session Timeout", "value", conf.Server.SessionTimeout)
 
-		secret, err := ds.Property(ctx).Get(consts.JWTSecretKey)
-		if err != nil || secret == "" {
-			log.Info(ctx, "Creating new JWT secret, used for encrypting UI sessions")
-			secret = createNewSecret(ctx, ds)
-		} else {
-			if secret, err = utils.Decrypt(ctx, getEncKey(), secret); err != nil {
-				log.Error(ctx, "Could not decrypt JWT secret, creating a new one", err)
-				secret = createNewSecret(ctx, ds)
-			}
-		}
-
-		TokenAuth = jwtauth.New("HS256", []byte(secret), nil)
+		TokenAuth = jwtauth.New("HS256", []byte(loadOrCreateSecret(ctx, ds, consts.JWTSecretKey)), nil)
+		PublicTokenAuth = jwtauth.New("HS256", []byte(loadOrCreateSecret(ctx, ds, consts.JWTPublicSecretKey)), nil)
 	})
 }
 
+func loadOrCreateSecret(ctx context.Context, ds model.DataStore, key string) string {
+	secret, err := ds.Property(ctx).Get(key)
+	if err != nil || secret == "" {
+		log.Info(ctx, "Creating new JWT secret", "key", key)
+		return createNewSecret(ctx, ds, key)
+	}
+	if secret, err = utils.Decrypt(ctx, getEncKey(), secret); err != nil {
+		log.Error(ctx, "Could not decrypt JWT secret, creating a new one", "key", key, err)
+		return createNewSecret(ctx, ds, key)
+	}
+	return secret
+}
+
 func CreatePublicToken(claims Claims) (string, error) {
 	claims.Issuer = consts.JWTIssuer
-	_, token, err := TokenAuth.Encode(claims.ToMap())
+	_, token, err := PublicTokenAuth.Encode(claims.ToMap())
 	return token, err
 }
 
@@ -56,7 +62,7 @@ func CreateExpiringPublicToken(exp time.Time, claims Claims) (string, error) {
 	if !exp.IsZero() {
 		claims.ExpiresAt = exp
 	}
-	_, token, err := TokenAuth.Encode(claims.ToMap())
+	_, token, err := PublicTokenAuth.Encode(claims.ToMap())
 	return token, err
 }
 
@@ -91,6 +97,15 @@ func Validate(tokenStr string) (Claims, error) {
 	return ClaimsFromToken(token), nil
 }
 
+// ValidatePublic verifies a public-link token against the public secret.
+func ValidatePublic(tokenStr string) (Claims, error) {
+	token, err := jwtauth.VerifyToken(PublicTokenAuth, tokenStr)
+	if err != nil {
+		return Claims{}, err
+	}
+	return ClaimsFromToken(token), nil
+}
+
 func WithAdminUser(ctx context.Context, ds model.DataStore) context.Context {
 	u, err := ds.User(ctx).FindFirstAdmin()
 	if err != nil {
@@ -107,14 +122,14 @@ func WithAdminUser(ctx context.Context, ds model.DataStore) context.Context {
 	return request.WithUser(ctx, *u)
 }
 
-func createNewSecret(ctx context.Context, ds model.DataStore) string {
+func createNewSecret(ctx context.Context, ds model.DataStore, key string) string {
 	secret := id.NewRandom()
 	encSecret, err := utils.Encrypt(ctx, getEncKey(), secret)
 	if err != nil {
 		log.Error(ctx, "Could not encrypt JWT secret", err)
 		return secret
 	}
-	if err := ds.Property(ctx).Put(consts.JWTSecretKey, encSecret); err != nil {
+	if err := ds.Property(ctx).Put(key, encSecret); err != nil {
 		log.Error(ctx, "Could not save JWT secret in DB", err)
 	}
 	return secret
diff --git a/core/auth/auth_test.go b/core/auth/auth_test.go
index 3a3585e53..e5cbb2352 100644
--- a/core/auth/auth_test.go
+++ b/core/auth/auth_test.go
@@ -89,6 +89,51 @@ var _ = Describe("Auth", func() {
 		})
 	})
 
+	Describe("Session/Public secret split", func() {
+		claims := func() map[string]any {
+			return map[string]any{"iss": "issuer", "exp": time.Now().Add(1 * time.Minute).Unix()}
+		}
+
+		It("verifies a session token via Validate but not ValidatePublic", func() {
+			_, tokenStr, err := auth.TokenAuth.Encode(claims())
+			Expect(err).NotTo(HaveOccurred())
+			_, err = auth.Validate(tokenStr)
+			Expect(err).NotTo(HaveOccurred())
+			_, err = auth.ValidatePublic(tokenStr)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("verifies a public token via ValidatePublic but not Validate", func() {
+			_, tokenStr, err := auth.PublicTokenAuth.Encode(claims())
+			Expect(err).NotTo(HaveOccurred())
+			_, err = auth.ValidatePublic(tokenStr)
+			Expect(err).NotTo(HaveOccurred())
+			_, err = auth.Validate(tokenStr)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("decodes public tokens minted by CreatePublicToken via PublicTokenAuth", func() {
+			tokenStr, err := auth.CreatePublicToken(auth.Claims{ID: "art-1"})
+			Expect(err).NotTo(HaveOccurred())
+			claims, err := auth.ValidatePublic(tokenStr)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(claims.ID).To(Equal("art-1"))
+			_, err = auth.Validate(tokenStr)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("decodes expiring public tokens minted by CreateExpiringPublicToken via PublicTokenAuth", func() {
+			exp := time.Now().Add(1 * time.Hour)
+			tokenStr, err := auth.CreateExpiringPublicToken(exp, auth.Claims{ID: "art-2"})
+			Expect(err).NotTo(HaveOccurred())
+			claims, err := auth.ValidatePublic(tokenStr)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(claims.ID).To(Equal("art-2"))
+			_, err = auth.Validate(tokenStr)
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
 	Describe("TouchToken", func() {
 		It("updates the expiration time", func() {
 			yesterday := time.Now().Add(-oneDay)
diff --git a/core/publicurl/publicurl_test.go b/core/publicurl/publicurl_test.go
index a195fb9cd..7e9ee8b8e 100644
--- a/core/publicurl/publicurl_test.go
+++ b/core/publicurl/publicurl_test.go
@@ -175,7 +175,7 @@ var _ = Describe("Public URL Utilities", func() {
 		BeforeEach(func() {
 			conf.Server.ShareURL = "https://share.example.com"
 			// Initialize JWT auth for token generation
-			auth.TokenAuth = jwtauth.New("HS256", []byte("test secret"), nil)
+			auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test secret"), nil)
 		})
 
 		It("generates a URL with the artwork token", func() {
diff --git a/db/migrations/20260720015443_uniform_canonical_ids.go b/db/migrations/20260720015443_uniform_canonical_ids.go
new file mode 100644
index 000000000..346f22050
--- /dev/null
+++ b/db/migrations/20260720015443_uniform_canonical_ids.go
@@ -0,0 +1,310 @@
+package migrations
+
+import (
+	"context"
+	"crypto/md5"
+	"database/sql"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"math/big"
+	"strings"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/model/id"
+	"github.com/pressly/goose/v3"
+)
+
+// canonicalID maps any historical Navidrome id shape to the canonical 22-char base62 encoding
+// of a 128-bit value; unrecognized shapes (including empty and share ids) pass through unchanged.
+func canonicalID(s string) string {
+	switch len(s) {
+	case 22:
+		v, ok := new(big.Int).SetString(s, 62)
+		if !ok || v.Sign() < 0 || v.BitLen() <= 128 {
+			return s
+		}
+		sum := md5.Sum([]byte(s))
+		return id.Encode(sum)
+	case 32:
+		b, err := hex.DecodeString(s)
+		if err != nil {
+			return s
+		}
+		return id.Encode([16]byte(b))
+	case 36:
+		if s[8] != '-' || s[13] != '-' || s[18] != '-' || s[23] != '-' {
+			return s
+		}
+		b, err := hex.DecodeString(s[:8] + s[9:13] + s[14:18] + s[19:23] + s[24:])
+		if err != nil {
+			return s
+		}
+		return id.Encode([16]byte(b))
+	}
+	return s
+}
+
+func init() {
+	goose.AddMigrationContext(upUniformCanonicalIds, downUniformCanonicalIds)
+}
+
+// idColumns is the exhaustive list of Navidrome-id-bearing columns; anything absent is deliberately exempt.
+var idColumns = []struct{ table, col string }{
+	{"media_file", "id"}, {"media_file", "pid"}, {"media_file", "artist_id"},
+	{"media_file", "album_id"}, {"media_file", "album_artist_id"}, {"media_file", "folder_id"},
+	{"album", "id"}, {"album", "album_artist_id"},
+	{"artist", "id"},
+	{"folder", "id"}, {"folder", "parent_id"},
+	{"tag", "id"},
+	{"library_artist", "artist_id"},
+	{"user", "id"},
+	{"user_props", "user_id"},
+	{"playlist", "id"}, {"playlist", "owner_id"},
+	{"playlist_tracks", "playlist_id"}, {"playlist_tracks", "media_file_id"},
+	{"playlist_fields", "playlist_id"},
+	{"annotation", "user_id"}, {"annotation", "item_id"},
+	{"bookmark", "user_id"}, {"bookmark", "item_id"},
+	{"player", "id"}, {"player", "user_id"}, {"player", "transcoding_id"},
+	{"transcoding", "id"},
+	{"radio", "id"},
+	{"share", "user_id"},
+	{"scrobble_buffer", "id"}, {"scrobble_buffer", "user_id"}, {"scrobble_buffer", "media_file_id"},
+	{"playqueue", "id"}, {"playqueue", "user_id"},
+	{"user_library", "user_id"},
+	{"scrobbles", "user_id"}, {"scrobbles", "media_file_id"},
+	{"media_file_artists", "media_file_id"}, {"media_file_artists", "artist_id"},
+	{"album_artists", "album_id"}, {"album_artists", "artist_id"},
+	{"library_tag", "tag_id"},
+}
+
+// embeddedIDColumns holds ids nested inside a larger value; the id-columns guard checks this
+// list against the schema, so every JSON column must appear here or be exempted there.
+var embeddedIDColumns = []struct {
+	table, col string
+	transform  func(string) (string, bool)
+}{
+	{"playqueue", "items", canonicalizeIDList},
+	{"share", "resource_ids", canonicalizeIDList},
+	{"plugin", "users", canonicalizePluginUsers},
+	{"playlist", "rules", canonicalizePlaylistRules},
+}
+
+func upUniformCanonicalIds(ctx context.Context, tx *sql.Tx) error {
+	if err := buildIDMap(ctx, tx); err != nil {
+		return err
+	}
+	for _, tc := range idColumns {
+		if err := applyIDMap(ctx, tx, tc.table, tc.col); err != nil {
+			return fmt.Errorf("canonicalizing %s.%s: %w", tc.table, tc.col, err)
+		}
+	}
+	for _, tc := range embeddedIDColumns {
+		if err := rewriteColumn(ctx, tx, tc.table, tc.col, tc.transform); err != nil {
+			return fmt.Errorf("canonicalizing %s.%s: %w", tc.table, tc.col, err)
+		}
+	}
+	// Legacy PID specs embed old-shaped album/track ids into composite pids; a full rescan
+	// rewrites every pid with the new encoding so path-based move matching stays consistent.
+	if strings.Contains(conf.Server.PID.Track, "legacy") || strings.Contains(conf.Server.PID.Album, "legacy") {
+		if err := forceFullRescan(ctx, tx); err != nil {
+			return err
+		}
+	}
+	if err := rotateSessionSecret(ctx, tx); err != nil {
+		return err
+	}
+	_, err := tx.ExecContext(ctx, "DROP TABLE _id_map")
+	return err
+}
+
+// rotateSessionSecret renames the session JWT secret to the public key, so public-link tokens
+// keep verifying while auth.Init mints a fresh session secret, killing every stale session.
+func rotateSessionSecret(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx,
+		`UPDATE property SET id = ? WHERE id = ? AND NOT EXISTS (SELECT 1 FROM property WHERE id = ?)`,
+		consts.JWTPublicSecretKey, consts.JWTSecretKey, consts.JWTPublicSecretKey)
+	return err
+}
+
+// buildIDMap stages old->new pairs for every id that changes, indexed for the update joins.
+func buildIDMap(ctx context.Context, tx *sql.Tx) error {
+	_, err := tx.ExecContext(ctx,
+		"CREATE TEMP TABLE _id_map (old_id TEXT PRIMARY KEY, new_id TEXT NOT NULL) WITHOUT ROWID")
+	if err != nil {
+		return err
+	}
+	ins, err := tx.PrepareContext(ctx, "INSERT OR IGNORE INTO _id_map (old_id, new_id) VALUES (?, ?)")
+	if err != nil {
+		return err
+	}
+	defer ins.Close()
+	for _, tc := range idColumns {
+		if err := collectColumn(ctx, tx, ins, tc.table, tc.col); err != nil {
+			return fmt.Errorf("collecting %s.%s: %w", tc.table, tc.col, err)
+		}
+	}
+	return nil
+}
+
+func collectColumn(ctx context.Context, tx *sql.Tx, ins *sql.Stmt, table, col string) error {
+	rows, err := tx.QueryContext(ctx, fmt.Sprintf(
+		"SELECT DISTINCT %[2]s FROM %[1]s WHERE %[2]s IS NOT NULL AND %[2]s <> ''", table, col))
+	if err != nil {
+		return err
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var old string
+		if err := rows.Scan(&old); err != nil {
+			return err
+		}
+		if newID := canonicalID(old); newID != old {
+			if _, err := ins.ExecContext(ctx, old, newID); err != nil {
+				return err
+			}
+		}
+	}
+	return rows.Err()
+}
+
+func applyIDMap(ctx context.Context, tx *sql.Tx, table, col string) error {
+	_, err := tx.ExecContext(ctx, fmt.Sprintf(
+		`UPDATE %[1]s SET %[2]s = (SELECT new_id FROM _id_map WHERE old_id = %[1]s.%[2]s)
+		 WHERE %[2]s IN (SELECT old_id FROM _id_map)`, table, col))
+	return err
+}
+
+// canonicalizeIDList canonicalizes a comma-separated id list element-wise.
+func canonicalizeIDList(s string) (string, bool) {
+	parts := strings.Split(s, ",")
+	changed := false
+	for i, p := range parts {
+		if n := canonicalID(p); n != p {
+			parts[i] = n
+			changed = true
+		}
+	}
+	if !changed {
+		return s, false
+	}
+	return strings.Join(parts, ","), true
+}
+
+// rewriteColumn applies transform to each non-empty cell, updating only rows it changed.
+func rewriteColumn(ctx context.Context, tx *sql.Tx, table, col string, transform func(string) (string, bool)) error {
+	rows, err := tx.QueryContext(ctx, fmt.Sprintf(
+		"SELECT rowid, %[2]s FROM %[1]s WHERE ifnull(%[2]s, '') <> ''", table, col))
+	if err != nil {
+		return err
+	}
+	type change struct {
+		rowid int64
+		val   string
+	}
+	var changes []change
+	for rows.Next() {
+		var rowid int64
+		var val string
+		if err := rows.Scan(&rowid, &val); err != nil {
+			_ = rows.Close()
+			return err
+		}
+		if newVal, ok := transform(val); ok {
+			changes = append(changes, change{rowid, newVal})
+		}
+	}
+	if err := rows.Err(); err != nil {
+		_ = rows.Close()
+		return err
+	}
+	_ = rows.Close()
+	if len(changes) == 0 {
+		return nil
+	}
+	upd, err := tx.PrepareContext(ctx, fmt.Sprintf("UPDATE %s SET %s = ? WHERE rowid = ?", table, col))
+	if err != nil {
+		return err
+	}
+	defer upd.Close()
+	for _, c := range changes {
+		if _, err := upd.ExecContext(ctx, c.val, c.rowid); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// canonicalizePluginUsers maps a JSON array of user ids; malformed JSON passes through untouched.
+func canonicalizePluginUsers(s string) (string, bool) {
+	var users []string
+	if err := json.Unmarshal([]byte(s), &users); err != nil {
+		return s, false
+	}
+	changed := false
+	for i, u := range users {
+		if n := canonicalID(u); n != u {
+			users[i] = n
+			changed = true
+		}
+	}
+	if !changed {
+		return s, false
+	}
+	out, err := json.Marshal(users)
+	if err != nil {
+		return s, false
+	}
+	return string(out), true
+}
+
+// canonicalizePlaylistRules rewrites inPlaylist/notInPlaylist ids in smart-playlist criteria; malformed JSON passes through.
+func canonicalizePlaylistRules(s string) (string, bool) {
+	var root map[string]any
+	if err := json.Unmarshal([]byte(s), &root); err != nil {
+		return s, false
+	}
+	if !canonicalizeRulesNode(root) {
+		return s, false
+	}
+	out, err := json.Marshal(root)
+	if err != nil {
+		return s, false
+	}
+	return string(out), true
+}
+
+// canonicalizeRulesNode walks the criteria tree, canonicalizing the id of any inPlaylist/notInPlaylist object.
+func canonicalizeRulesNode(node any) bool {
+	changed := false
+	switch v := node.(type) {
+	case map[string]any:
+		for k, val := range v {
+			if lk := strings.ToLower(k); lk == "inplaylist" || lk == "notinplaylist" {
+				if obj, ok := val.(map[string]any); ok {
+					if id, ok := obj["id"].(string); ok {
+						if n := canonicalID(id); n != id {
+							obj["id"] = n
+							changed = true
+						}
+					}
+				}
+			}
+			if canonicalizeRulesNode(val) {
+				changed = true
+			}
+		}
+	case []any:
+		for _, item := range v {
+			if canonicalizeRulesNode(item) {
+				changed = true
+			}
+		}
+	}
+	return changed
+}
+
+func downUniformCanonicalIds(ctx context.Context, tx *sql.Tx) error {
+	return nil // irreversible data migration
+}
diff --git a/db/migrations/id_canonical_test.go b/db/migrations/id_canonical_test.go
new file mode 100644
index 000000000..0befbe469
--- /dev/null
+++ b/db/migrations/id_canonical_test.go
@@ -0,0 +1,47 @@
+package migrations
+
+import (
+	"strings"
+
+	"github.com/navidrome/navidrome/model/id"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("canonicalID", func() {
+	DescribeTable("transforms each historical id shape",
+		func(in, want string) {
+			Expect(canonicalID(in)).To(Equal(want))
+		},
+		Entry("hash-family id (fits 128 bits) is kept", "5cLJPkLA5DK2BADhoeotPk", "5cLJPkLA5DK2BADhoeotPk"),
+		Entry("overflowing random id is remapped via md5", "zzzzzzzzzzzzzzzzzzzzzz", "3LyqmwQBm5IRqlVjNYASwb"),
+		Entry("legacy 32-hex is re-encoded value-preserving", "e3b7fc2ae9447bbec37a13bf916e3cf6", "6VHl3uR4kss6sUPKA8Cwnk"),
+		Entry("playlist uuid is re-encoded value-preserving", "f47ac10b-58cc-4372-a567-0e02b2c3d479", "7rke2SAWaicSeSYzkhww6R"),
+		Entry("empty string passes through", "", ""),
+		Entry("share id (10 chars) passes through", "aB3xY9kQz1", "aB3xY9kQz1"),
+		Entry("truncated Finamp id (16 chars) passes through", "0123456789abcdef", "0123456789abcdef"),
+		Entry("22 chars with non-base62 char passes through", "!!!!!!!!!!!!!!!!!!!!!!", "!!!!!!!!!!!!!!!!!!!!!!"),
+		Entry("32 chars non-hex passes through", "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz", "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"),
+		Entry("36 chars without uuid dashes passes through", "000000000000000000000000000000000000", "000000000000000000000000000000000000"),
+	)
+
+	// The exemptions for participants/tags/folder_ids/similar_artists rest on this invariant.
+	It("is the identity on every NewHash id", func() {
+		for _, parts := range [][]string{
+			{""}, {"a"}, {"The Beatles"}, {"genre", "electronic"},
+			{"/music/Artist/Album", "1"}, {strings.Repeat("x", 500)},
+		} {
+			h := id.NewHash(parts...)
+			Expect(h).To(HaveLen(22))
+			Expect(canonicalID(h)).To(Equal(h), "NewHash(%v) = %q was rewritten", parts, h)
+		}
+	})
+
+	It("is idempotent for every shape", func() {
+		for _, s := range []string{"5cLJPkLA5DK2BADhoeotPk", "zzzzzzzzzzzzzzzzzzzzzz",
+			"e3b7fc2ae9447bbec37a13bf916e3cf6", "f47ac10b-58cc-4372-a567-0e02b2c3d479"} {
+			once := canonicalID(s)
+			Expect(canonicalID(once)).To(Equal(once))
+		}
+	})
+})
diff --git a/db/migrations/id_columns_guard_test.go b/db/migrations/id_columns_guard_test.go
new file mode 100644
index 000000000..c4cb3b241
--- /dev/null
+++ b/db/migrations/id_columns_guard_test.go
@@ -0,0 +1,119 @@
+package migrations
+
+import (
+	"context"
+	"database/sql"
+	"os"
+	"strings"
+
+	_ "github.com/mattn/go-sqlite3"
+	"github.com/pressly/goose/v3"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Version of the uniform-canonical-ids migration whose idColumns list this guard protects.
+const idColumnsMigrationVersion = 20260720015443
+
+var _ = Describe("idColumns inventory", func() {
+	It("covers every id-bearing column present at the migration version", func() {
+		ctx := context.Background()
+		db, err := sql.Open("sqlite3", "file::memory:")
+		Expect(err).ToNot(HaveOccurred())
+		db.SetMaxOpenConns(1) // non-shared :memory: — a second conn would be an empty DB
+		DeferCleanup(func() { _ = db.Close() })
+		_, err = db.ExecContext(ctx, "PRAGMA foreign_keys=off")
+		Expect(err).ToNot(HaveOccurred())
+
+		goose.SetBaseFS(os.DirFS("."))
+		DeferCleanup(func() { goose.SetBaseFS(nil) })
+		Expect(goose.SetDialect("sqlite3")).To(Succeed())
+		Expect(goose.UpToContext(ctx, db, ".", idColumnsMigrationVersion)).To(Succeed())
+
+		covered := map[string]bool{}
+		for _, tc := range idColumns {
+			covered[tc.table+"."+tc.col] = true
+		}
+		for _, tc := range embeddedIDColumns {
+			covered[tc.table+"."+tc.col] = true
+		}
+		// Columns that are id-named or JSON but need no rewrite.
+		exempt := map[string]string{
+			"share.id":                       "public share URLs, generated separately",
+			"property.id":                    "property key, not an entity id",
+			"plugin.id":                      "plugin name, not an entity id",
+			"media_file.participants":        "hash-family artist ids, unchanged",
+			"album.participants":             "hash-family artist ids, unchanged",
+			"media_file.tags":                "hash-family tag ids, unchanged",
+			"album.tags":                     "hash-family tag ids, unchanged",
+			"album.folder_ids":               "hash-family folder ids, unchanged",
+			"artist.similar_artists":         "hash-family artist ids, unchanged",
+			"media_file.search_participants": "participant names for FTS, not ids",
+			"album.search_participants":      "participant names for FTS, not ids",
+			"album.discs":                    "disc number -> title map",
+			"media_file.lyrics":              "synced lyrics, no ids",
+			"folder.image_files":             "image file names, no ids",
+			"plugin.manifest":                "plugin-authored manifest, no Navidrome ids",
+			"plugin.config":                  "free-form plugin config, must not be rewritten",
+			"plugin.libraries":               "integer library ids",
+		}
+
+		tables, err := queryColumn(ctx, db, "SELECT name FROM sqlite_master WHERE type='table'")
+		Expect(err).ToNot(HaveOccurred())
+
+		var dangling []string
+		for _, table := range tables {
+			if strings.HasPrefix(table, "sqlite_") || table == "goose_db_version" || strings.Contains(table, "_fts") {
+				continue
+			}
+			rows, err := db.QueryContext(ctx, "SELECT name, type FROM pragma_table_info(?)", table)
+			Expect(err).ToNot(HaveOccurred())
+			for rows.Next() {
+				var name, typ string
+				Expect(rows.Scan(&name, &typ)).To(Succeed())
+				lname := strings.ToLower(name)
+				utyp := strings.ToUpper(typ)
+				// JSON can hide an id under any key, so every JSON column needs a verdict.
+				isJSON := strings.Contains(utyp, "JSON")
+				isIDName := lname == "id" || lname == "pid" ||
+					strings.HasSuffix(lname, "_id") || strings.HasSuffix(lname, "_ids")
+				if !isJSON && !isIDName {
+					continue
+				}
+				if !isJSON && !strings.Contains(utyp, "TEXT") && !strings.Contains(utyp, "CHAR") {
+					continue // INTEGER ids (rowid PKs, library.id) are not canonical ids
+				}
+				if strings.HasPrefix(lname, "mbz_") {
+					continue // MusicBrainz UUIDs, not Navidrome ids
+				}
+				key := table + "." + name
+				if covered[key] || exempt[key] != "" {
+					continue
+				}
+				dangling = append(dangling, key)
+			}
+			Expect(rows.Err()).ToNot(HaveOccurred())
+			Expect(rows.Close()).To(Succeed())
+		}
+		Expect(dangling).To(BeEmpty(),
+			"id-bearing columns missing from idColumns; add them to the migration or exempt with a reason: %v", dangling)
+	})
+})
+
+func queryColumn(ctx context.Context, db *sql.DB, query string) ([]string, error) {
+	rows, err := db.QueryContext(ctx, query)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []string
+	for rows.Next() {
+		var s string
+		if err := rows.Scan(&s); err != nil {
+			return nil, err
+		}
+		out = append(out, s)
+	}
+	return out, rows.Err()
+}
diff --git a/db/migrations/migrations_suite_test.go b/db/migrations/migrations_suite_test.go
new file mode 100644
index 000000000..bb08ad8aa
--- /dev/null
+++ b/db/migrations/migrations_suite_test.go
@@ -0,0 +1,16 @@
+package migrations
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// tests.Init is omitted: the tests package imports db, which imports this package.
+func TestMigrations(t *testing.T) {
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Migrations Suite")
+}
diff --git a/db/migrations/uniform_canonical_ids_test.go b/db/migrations/uniform_canonical_ids_test.go
new file mode 100644
index 000000000..ced75cb7e
--- /dev/null
+++ b/db/migrations/uniform_canonical_ids_test.go
@@ -0,0 +1,233 @@
+package migrations
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+
+	_ "github.com/mattn/go-sqlite3"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("upUniformCanonicalIds", func() {
+	var db *sql.DB
+	var tx *sql.Tx
+	ctx := context.Background()
+
+	const (
+		hashID    = "5cLJPkLA5DK2BADhoeotPk" // canonical, kept
+		randOld   = "zzzzzzzzzzzzzzzzzzzzzz" // overflows -> remapped
+		randNew   = "3LyqmwQBm5IRqlVjNYASwb"
+		legacyOld = "e3b7fc2ae9447bbec37a13bf916e3cf6" // 32-hex -> re-encoded
+		legacyNew = "6VHl3uR4kss6sUPKA8Cwnk"
+		uuidOld   = "f47ac10b-58cc-4372-a567-0e02b2c3d479" // uuid -> re-encoded
+		uuidNew   = "7rke2SAWaicSeSYzkhww6R"
+		shareID   = "aB3xY9kQz1" // exempt family
+
+		sessionSecret = "encrypted-session-secret-sentinel"
+	)
+
+	BeforeEach(func() {
+		var err error
+		db, err = sql.Open("sqlite3", "file::memory:")
+		Expect(err).ToNot(HaveOccurred())
+		db.SetMaxOpenConns(1) // non-shared :memory: — every new conn is a fresh empty DB
+		DeferCleanup(func() { _ = db.Close() })
+
+		// Minimal fixture: every table/column idColumns and the list rewrites touch.
+		_, err = db.Exec(`
+			CREATE TABLE media_file (id text, pid text, artist_id text, album_id text, album_artist_id text, folder_id text, mbz_recording_id text);
+			CREATE TABLE album (id text, album_artist_id text);
+			CREATE TABLE artist (id text);
+			CREATE TABLE folder (id text, parent_id text);
+			CREATE TABLE tag (id text);
+			CREATE TABLE library_artist (artist_id text);
+			CREATE TABLE user (id text);
+			CREATE TABLE user_props (user_id text);
+			CREATE TABLE playlist (id text, owner_id text, rules text);
+			CREATE TABLE playlist_tracks (playlist_id text, media_file_id text);
+			CREATE TABLE playlist_fields (playlist_id text);
+			CREATE TABLE annotation (user_id text, item_id text, item_type text);
+			CREATE TABLE bookmark (user_id text, item_id text);
+			CREATE TABLE player (id text, user_id text, transcoding_id text);
+			CREATE TABLE transcoding (id text);
+			CREATE TABLE radio (id text);
+			CREATE TABLE share (id text, user_id text, resource_ids text, contents text);
+			CREATE TABLE scrobble_buffer (id text, user_id text, media_file_id text);
+			CREATE TABLE playqueue (id text, user_id text, items text);
+			CREATE TABLE user_library (user_id text, library_id integer);
+			CREATE TABLE scrobbles (id integer, media_file_id text, user_id text);
+			CREATE TABLE media_file_artists (media_file_id text, artist_id text);
+			CREATE TABLE album_artists (album_id text, artist_id text);
+			CREATE TABLE library_tag (tag_id text, library_id integer);
+			CREATE TABLE plugin (id text, users text);
+			CREATE TABLE property (id text primary key, value text);
+		`)
+		Expect(err).ToNot(HaveOccurred())
+
+		seed := func(query string, args ...any) {
+			_, err := db.Exec(query, args...)
+			ExpectWithOffset(1, err).ToNot(HaveOccurred())
+		}
+		// media_file: legacy id/pid, hash artist, legacy album, mbz uuid must stay untouched
+		seed(`INSERT INTO media_file VALUES (?, ?, ?, ?, '', '', ?)`, legacyOld, legacyOld, hashID, legacyOld, uuidOld)
+		seed(`INSERT INTO album VALUES (?, ?)`, legacyOld, hashID)
+		seed(`INSERT INTO user VALUES (?)`, randOld)
+		// uuid id, random owner, smart-playlist rules with an embedded inPlaylist id and a sibling operator
+		seed(`INSERT INTO playlist VALUES (?, ?, ?)`, uuidOld, randOld, `{"all":[{"inPlaylist":{"id":"`+uuidOld+`"}},{"inTheLast":{"lastPlayed":30}}]}`)
+		seed(`INSERT INTO annotation VALUES (?, ?, 'media_file')`, randOld, legacyOld)
+		seed(`INSERT INTO playqueue VALUES (?, ?, ?)`, randOld, randOld, legacyOld+","+hashID)
+		seed(`INSERT INTO share VALUES (?, ?, ?, 'Album Foo...')`, shareID, randOld, legacyOld+","+uuidOld)
+		seed(`INSERT INTO user_library VALUES (?, 1)`, randOld)
+		seed(`INSERT INTO scrobbles VALUES (1, ?, ?)`, legacyOld, randOld)
+		seed(`INSERT INTO media_file_artists VALUES (?, ?)`, legacyOld, hashID)
+		seed(`INSERT INTO album_artists VALUES (?, ?)`, legacyOld, hashID)
+		seed(`INSERT INTO library_tag VALUES (?, 1)`, hashID)
+		seed(`INSERT INTO plugin VALUES ('lastfm', ?)`, `["`+randOld+`","`+hashID+`"]`)
+		seed(`INSERT INTO plugin VALUES ('empty', '[]')`) // exempt: empty user list untouched
+		// malformed JSON in both a plugin list and a playlist rule: must pass through byte-for-byte
+		seed(`INSERT INTO plugin VALUES ('broken', 'not-json')`)
+		seed(`INSERT INTO playlist VALUES (?, ?, '{broken')`, hashID, hashID)
+		seed(`INSERT INTO property VALUES (?, ?)`, consts.JWTSecretKey, sessionSecret)
+	})
+
+	JustBeforeEach(func() {
+		var err error
+		tx, err = db.Begin()
+		Expect(err).ToNot(HaveOccurred())
+		Expect(upUniformCanonicalIds(ctx, tx)).To(Succeed())
+		Expect(tx.Commit()).To(Succeed())
+	})
+
+	get := func(query string) string {
+		var s string
+		ExpectWithOffset(1, db.QueryRow(query).Scan(&s)).To(Succeed())
+		return s
+	}
+
+	It("canonicalizes every id family and keeps references consistent", func() {
+		Expect(get(`SELECT id FROM media_file`)).To(Equal(legacyNew))
+		Expect(get(`SELECT pid FROM media_file`)).To(Equal(legacyNew))
+		Expect(get(`SELECT artist_id FROM media_file`)).To(Equal(hashID))
+		Expect(get(`SELECT album_id FROM media_file`)).To(Equal(legacyNew))
+		Expect(get(`SELECT id FROM album`)).To(Equal(legacyNew))
+		Expect(get(`SELECT id FROM user`)).To(Equal(randNew))
+		Expect(get(`SELECT id FROM playlist WHERE owner_id='` + randNew + `'`)).To(Equal(uuidNew))
+		Expect(get(`SELECT owner_id FROM playlist WHERE id='` + uuidNew + `'`)).To(Equal(randNew))
+		Expect(get(`SELECT item_id FROM annotation`)).To(Equal(legacyNew))
+		Expect(get(`SELECT user_id FROM annotation`)).To(Equal(randNew))
+	})
+
+	It("rewrites list columns element-wise", func() {
+		Expect(get(`SELECT items FROM playqueue`)).To(Equal(legacyNew + "," + hashID))
+		Expect(get(`SELECT resource_ids FROM share`)).To(Equal(legacyNew + "," + uuidNew))
+	})
+
+	It("leaves exempt columns alone", func() {
+		Expect(get(`SELECT id FROM share`)).To(Equal(shareID))
+		Expect(get(`SELECT contents FROM share`)).To(Equal("Album Foo..."))
+		Expect(get(`SELECT mbz_recording_id FROM media_file`)).To(Equal(uuidOld))
+	})
+
+	It("canonicalizes junction and membership tables", func() {
+		Expect(get(`SELECT user_id FROM user_library`)).To(Equal(randNew))
+		Expect(get(`SELECT media_file_id FROM scrobbles`)).To(Equal(legacyNew))
+		Expect(get(`SELECT user_id FROM scrobbles`)).To(Equal(randNew))
+		Expect(get(`SELECT media_file_id FROM media_file_artists`)).To(Equal(legacyNew))
+		Expect(get(`SELECT artist_id FROM media_file_artists`)).To(Equal(hashID)) // hash-family, unchanged
+		Expect(get(`SELECT album_id FROM album_artists`)).To(Equal(legacyNew))
+		Expect(get(`SELECT artist_id FROM album_artists`)).To(Equal(hashID)) // hash-family, unchanged
+		Expect(get(`SELECT tag_id FROM library_tag`)).To(Equal(hashID))      // hash-family, unchanged
+	})
+
+	It("rewrites JSON columns element-wise", func() {
+		Expect(get(`SELECT users FROM plugin WHERE id='lastfm'`)).To(Equal(`["` + randNew + `","` + hashID + `"]`))
+		Expect(get(`SELECT id FROM plugin WHERE id='lastfm'`)).To(Equal("lastfm")) // plugin name, untouched
+
+		var rules map[string]any
+		Expect(json.Unmarshal([]byte(get(`SELECT rules FROM playlist WHERE id='`+uuidNew+`'`)), &rules)).To(Succeed())
+		all, ok := rules["all"].([]any)
+		Expect(ok).To(BeTrue())
+		Expect(all).To(HaveLen(2))
+		inPl := all[0].(map[string]any)["inPlaylist"].(map[string]any)
+		Expect(inPl["id"]).To(Equal(uuidNew))
+	})
+
+	It("preserves sibling operators alongside a rewritten inPlaylist id", func() {
+		var rules map[string]any
+		Expect(json.Unmarshal([]byte(get(`SELECT rules FROM playlist WHERE id='`+uuidNew+`'`)), &rules)).To(Succeed())
+		all := rules["all"].([]any)
+		var sawInPlaylist, sawInTheLast bool
+		for _, e := range all {
+			op := e.(map[string]any)
+			if pl, ok := op["inPlaylist"].(map[string]any); ok {
+				Expect(pl["id"]).To(Equal(uuidNew))
+				sawInPlaylist = true
+			}
+			if last, ok := op["inTheLast"].(map[string]any); ok {
+				Expect(last["lastPlayed"]).To(Equal(float64(30)))
+				sawInTheLast = true
+			}
+		}
+		Expect(sawInPlaylist).To(BeTrue())
+		Expect(sawInTheLast).To(BeTrue())
+	})
+
+	It("leaves exempt JSON rows untouched", func() {
+		Expect(get(`SELECT users FROM plugin WHERE id='empty'`)).To(Equal("[]"))
+	})
+
+	It("passes malformed JSON columns through byte-for-byte", func() {
+		Expect(get(`SELECT users FROM plugin WHERE id='broken'`)).To(Equal("not-json"))
+		Expect(get(`SELECT rules FROM playlist WHERE id='` + hashID + `'`)).To(Equal("{broken"))
+	})
+
+	rescanCount := func() int {
+		var count int
+		ExpectWithOffset(1, db.QueryRow(
+			`SELECT count(*) FROM property WHERE id = ?`, consts.FullScanAfterMigrationFlagKey).Scan(&count)).To(Succeed())
+		return count
+	}
+
+	It("does not force a full rescan for the default PID config", func() {
+		Expect(rescanCount()).To(Equal(0))
+	})
+
+	Context("with a legacy PID configuration", func() {
+		BeforeEach(func() {
+			prev := conf.Server.PID.Album
+			conf.Server.PID.Album = "album_legacy"
+			DeferCleanup(func() { conf.Server.PID.Album = prev })
+		})
+
+		It("forces a full rescan so composite pids are rewritten", func() {
+			Expect(rescanCount()).To(Equal(1))
+		})
+	})
+
+	propCount := func(key string) int {
+		var count int
+		ExpectWithOffset(1, db.QueryRow(`SELECT count(*) FROM property WHERE id = ?`, key).Scan(&count)).To(Succeed())
+		return count
+	}
+
+	It("rotates the session secret to the public key", func() {
+		Expect(propCount(consts.JWTSecretKey)).To(Equal(0))
+		Expect(get(`SELECT value FROM property WHERE id = '` + consts.JWTPublicSecretKey + `'`)).To(Equal(sessionSecret))
+	})
+
+	Context("with no stored session secret", func() {
+		BeforeEach(func() {
+			_, err := db.Exec(`DELETE FROM property WHERE id = ?`, consts.JWTSecretKey)
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("is a no-op", func() {
+			Expect(propCount(consts.JWTSecretKey)).To(Equal(0))
+			Expect(propCount(consts.JWTPublicSecretKey)).To(Equal(0))
+		})
+	})
+})
diff --git a/model/id/id.go b/model/id/id.go
index b54542898..2885bc6ad 100644
--- a/model/id/id.go
+++ b/model/id/id.go
@@ -2,20 +2,36 @@ package id
 
 import (
 	"crypto/md5"
+	"crypto/rand"
 	"fmt"
 	"math/big"
 	"strings"
-
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/utils/nanoid"
 )
 
 func NewRandom() string {
-	id, err := nanoid.Generate("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz", 22)
-	if err != nil {
-		log.Error("Could not generate new ID", err)
+	var b [16]byte
+	_, _ = rand.Read(b[:])
+	return Encode(b)
+}
+
+// Encode renders a 16-byte value as the canonical 22-char zero-padded base62 id.
+func Encode(b [16]byte) string {
+	return fmt.Sprintf("%022s", new(big.Int).SetBytes(b[:]).Text(62))
+}
+
+// Decode is the exact inverse of Encode.
+func Decode(s string) ([]byte, error) {
+	if len(s) != 22 {
+		return nil, fmt.Errorf("invalid id length %d", len(s))
 	}
-	return id
+	v, ok := new(big.Int).SetString(s, 62)
+	if !ok || v.Sign() < 0 {
+		return nil, fmt.Errorf("invalid base62 id %q", s)
+	}
+	if v.BitLen() > 128 {
+		return nil, fmt.Errorf("id %q overflows 128 bits", s)
+	}
+	return v.FillBytes(make([]byte, 16)), nil
 }
 
 func NewHash(data ...string) string {
@@ -24,11 +40,7 @@ func NewHash(data ...string) string {
 		hash.Write([]byte(d))
 		hash.Write([]byte(string('\u200b')))
 	}
-	h := hash.Sum(nil)
-	bi := big.NewInt(0)
-	bi.SetBytes(h)
-	s := bi.Text(62)
-	return fmt.Sprintf("%022s", s)
+	return Encode([16]byte(hash.Sum(nil)))
 }
 
 func NewTagID(name, value string) string {
diff --git a/model/id/id_suite_test.go b/model/id/id_suite_test.go
new file mode 100644
index 000000000..e8a41f4e5
--- /dev/null
+++ b/model/id/id_suite_test.go
@@ -0,0 +1,17 @@
+package id_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestID(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "ID Suite")
+}
diff --git a/model/id/id_test.go b/model/id/id_test.go
new file mode 100644
index 000000000..407560a75
--- /dev/null
+++ b/model/id/id_test.go
@@ -0,0 +1,64 @@
+package id_test
+
+import (
+	"github.com/navidrome/navidrome/model/id"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Encode/Decode", func() {
+	It("encodes 16 bytes as 22-char zero-padded base62", func() {
+		Expect(id.Encode([16]byte{})).To(Equal("0000000000000000000000"))
+		allFF := [16]byte{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
+			0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff}
+		Expect(id.Encode(allFF)).To(Equal("7N42dgm5tFLK9N8MT7fHC7"))
+	})
+
+	It("round-trips arbitrary 16-byte values", func() {
+		b := [16]byte{0xe3, 0xb7, 0xfc, 0x2a, 0xe9, 0x44, 0x7b, 0xbe,
+			0xc3, 0x7a, 0x13, 0xbf, 0x91, 0x6e, 0x3c, 0xf6}
+		s := id.Encode(b)
+		Expect(s).To(Equal("6VHl3uR4kss6sUPKA8Cwnk"))
+		Expect(id.Decode(s)).To(Equal(b[:]))
+	})
+
+	It("rejects invalid input", func() {
+		_, err := id.Decode("short")
+		Expect(err).To(HaveOccurred())
+		_, err = id.Decode("!!!!!!!!!!!!!!!!!!!!!!") // 22 chars, not base62
+		Expect(err).To(HaveOccurred())
+		_, err = id.Decode("-000000000000000000001") // sign is not part of the alphabet
+		Expect(err).To(HaveOccurred())
+		_, err = id.Decode("zzzzzzzzzzzzzzzzzzzzzz") // > 2^128
+		Expect(err).To(HaveOccurred())
+	})
+})
+
+var _ = Describe("NewRandom", func() {
+	It("emits 22-char canonical ids that always fit 128 bits", func() {
+		seen := make(map[string]struct{})
+		for range 1000 {
+			s := id.NewRandom()
+			Expect(s).To(HaveLen(22))
+			_, err := id.Decode(s)
+			Expect(err).ToNot(HaveOccurred(), "id %q must decode to 128 bits", s)
+			seen[s] = struct{}{}
+		}
+		Expect(seen).To(HaveLen(1000))
+	})
+})
+
+var _ = Describe("NewHash", func() {
+	It("keeps its historical output byte-for-byte (golden)", func() {
+		Expect(id.NewHash("test")).To(Equal("5cLJPkLA5DK2BADhoeotPk"))
+		Expect(id.NewHash("[unknown artist]")).To(Equal("7lsE5pS09fPS1VuFqwXbia"))
+		Expect(id.NewTagID("genre", "electronic")).To(Equal("7bLYq0Np81m1Wgy5N31nuG"))
+	})
+
+	It("always emits 22 decodable chars", func() {
+		h := id.NewHash("anything", "at", "all")
+		Expect(h).To(HaveLen(22))
+		_, err := id.Decode(h)
+		Expect(err).ToNot(HaveOccurred())
+	})
+})
diff --git a/model/metadata/legacy_ids.go b/model/metadata/legacy_ids.go
index 18a273550..7156c4f50 100644
--- a/model/metadata/legacy_ids.go
+++ b/model/metadata/legacy_ids.go
@@ -9,17 +9,19 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/id"
 )
 
-// These are the legacy ID functions that were used in the original Navidrome ID generation.
-// They are kept here for backwards compatibility with existing databases.
+// These legacy ID functions hash the same inputs as the original Navidrome ID generation,
+// now emitted in the canonical base62 encoding (matching what the uniform-ids migration stores).
 
 func legacyTrackID(mf model.MediaFile, prependLibId bool) string {
-	id := mf.Path
+	key := mf.Path
 	if prependLibId && mf.LibraryID != model.DefaultLibraryID {
-		id = fmt.Sprintf("%d\\%s", mf.LibraryID, id)
+		key = fmt.Sprintf("%d\\%s", mf.LibraryID, key)
 	}
-	return fmt.Sprintf("%x", md5.Sum([]byte(id)))
+	sum := md5.Sum([]byte(key))
+	return id.Encode(sum)
 }
 
 func legacyAlbumID(mf model.MediaFile, md Metadata, prependLibId bool) string {
@@ -33,7 +35,8 @@ func legacyAlbumID(mf model.MediaFile, md Metadata, prependLibId bool) string {
 	if prependLibId && mf.LibraryID != model.DefaultLibraryID {
 		albumPath = fmt.Sprintf("%d\\%s", mf.LibraryID, albumPath)
 	}
-	return fmt.Sprintf("%x", md5.Sum([]byte(albumPath)))
+	sum := md5.Sum([]byte(albumPath))
+	return id.Encode(sum)
 }
 
 func legacyMapAlbumArtistName(md Metadata) string {
diff --git a/model/metadata/persistent_ids_test.go b/model/metadata/persistent_ids_test.go
index eb66d11d1..8e38bbd42 100644
--- a/model/metadata/persistent_ids_test.go
+++ b/model/metadata/persistent_ids_test.go
@@ -218,6 +218,21 @@ var _ = Describe("getPID", func() {
 	})
 
 	Context("legacy specs", func() {
+		It("emits canonical 22-char base62 ids", func() {
+			mf := model.MediaFile{Path: "/music/a.mp3", LibraryID: 1}
+			// md5("/music/a.mp3") = e3b7fc2ae9447bbec37a13bf916e3cf6 re-encoded as base62
+			Expect(legacyTrackID(mf, false)).To(Equal("6VHl3uR4kss6sUPKA8Cwnk"))
+		})
+		It("prepends the library id for a non-default library", func() {
+			mf := model.MediaFile{Path: "/music/a.mp3", LibraryID: 2}
+			// id.Encode(md5.Sum([]byte("2\\/music/a.mp3")))
+			Expect(legacyTrackID(mf, true)).To(Equal("4EK5DHQBMeFuDHw6S3iooO"))
+		})
+		It("emits a canonical album id (golden)", func() {
+			mf := model.MediaFile{LibraryID: 1}
+			// id.Encode(md5.Sum([]byte("[unknown artist]\\[unknown album]")))
+			Expect(legacyAlbumID(mf, Metadata{}, false)).To(Equal("6xBmxSAUFJSQuW7UvwCq8X"))
+		})
 		Context("track_legacy", func() {
 			When("library ID is default (1)", func() {
 				It("should not prepend library ID even when prependLibId is true", func() {
diff --git a/plugins/host_artwork_test.go b/plugins/host_artwork_test.go
index ed8a0e810..218d3d892 100644
--- a/plugins/host_artwork_test.go
+++ b/plugins/host_artwork_test.go
@@ -225,7 +225,7 @@ func decodeArtworkURL(artworkURL string) model.ArtworkID {
 	}
 
 	// Decode JWT token
-	token, err := auth.TokenAuth.Decode(tokenPart)
+	token, err := auth.PublicTokenAuth.Decode(tokenPart)
 	Expect(err).ToNot(HaveOccurred(), "Failed to decode JWT token")
 
 	c := auth.ClaimsFromToken(token)
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 17d2797ab..13ec79aa8 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -90,9 +90,9 @@ skipped, so it doesn't create a nameless player.
 Navidrome item ids are **hex-encoded at the API boundary** (`dto.EncodeID`/`DecodeID`): every id
 is hex-encoded on the way out and hex-decoded on the way in. This is required because some clients
 parse ids as radix-16 — Finamp's queue `packIds`, for instance, does `int.parse(chunk, radix:16)`,
-which chokes on Navidrome's base-62 nanoids (e.g. `5QFKvMsJrd57QE2Le2dKKo`). Because a raw MD5 id
-from an old migrated library is itself valid hex, correctness depends on every emit path encoding
-and every receive path decoding — see `dto/ids.go`.
+which chokes on Navidrome's base62 ids (e.g. `5QFKvMsJrd57QE2Le2dKKo`). Because a base62 id can
+itself be valid hex, correctness depends on every emit path encoding and every receive path
+decoding — see `dto/ids.go`.
 
 ## Multi-library behavior
 
@@ -184,13 +184,13 @@ their Navidrome `ArtworkID`.
 
 Real Jellyfin item ids are GUIDs — 128-bit values, always 32 hex characters. Finamp relies on that
 when persisting its play queue across restarts: `packIds()` bit-packs every id into exactly 16
-bytes. Navidrome ids are longer (nanoid ids can exceed 128 bits, so they cannot be mapped into
-GUIDs), which means Finamp silently stores only the first 16 characters of each id and asks for
-those **truncated ids** back when restoring the queue — item lookups, then streaming, images,
-favorites and playback reports for the restored tracks.
+bytes. Navidrome ids are 22-character base62 strings, not 32-hex GUIDs, which means Finamp silently
+stores only the first 16 characters of each id and asks for those **truncated ids** back when
+restoring the queue — item lookups, then streaming, images, favorites and playback reports for the
+restored tracks.
 
 This API compensates server-side (`truncated_ids.go`): a 16-character id — a length no Navidrome
-id family uses — is resolved to the full id by unique-prefix lookup (an indexed range scan;
+id uses — is resolved to the full id by unique-prefix lookup (an indexed range scan;
 ambiguity is detected and fails safe). The `/Items?ids=` batch response echoes the id **as
 requested**, because Finamp matches restored items back to its stored ids, and the other item
 endpoints accept truncated ids transparently.
diff --git a/server/jellyfin/dto/ids.go b/server/jellyfin/dto/ids.go
index 3490ba260..2ac7e2a79 100644
--- a/server/jellyfin/dto/ids.go
+++ b/server/jellyfin/dto/ids.go
@@ -3,7 +3,7 @@ package dto
 import "encoding/hex"
 
 // EncodeID renders a Navidrome id as lowercase hex; Jellyfin clients parse ids as radix-16 (e.g.
-// Finamp's queue packing) and crash on Navidrome's base62 nanoids if emitted as-is.
+// Finamp's queue packing) and crash on Navidrome's base62 ids if emitted as-is.
 func EncodeID(id string) string {
 	if id == "" {
 		return ""
diff --git a/server/jellyfin/dto/ids_test.go b/server/jellyfin/dto/ids_test.go
index 26a957604..d85786d99 100644
--- a/server/jellyfin/dto/ids_test.go
+++ b/server/jellyfin/dto/ids_test.go
@@ -6,7 +6,7 @@ import (
 )
 
 var _ = Describe("id codec", func() {
-	It("round-trips a base62 nanoid through Encode/Decode", func() {
+	It("round-trips a base62 id", func() {
 		id := "5QFKvMsJrd57QE2Le2dKKo"
 		Expect(DecodeID(EncodeID(id))).To(Equal(id))
 	})
diff --git a/server/jellyfin/truncated_ids.go b/server/jellyfin/truncated_ids.go
index b58296391..bb3e4ce9b 100644
--- a/server/jellyfin/truncated_ids.go
+++ b/server/jellyfin/truncated_ids.go
@@ -11,8 +11,8 @@ import (
 )
 
 // truncatedIDLen is what Finamp's saved-queue persistence cuts item ids to (16 bytes, assuming
-// Jellyfin GUIDs). No Navidrome id family is 16 chars (nanoid=22, legacy MD5=32, playlist
-// UUID=36), so the length alone identifies a truncated id. See README.
+// Jellyfin GUIDs). All Navidrome ids are 22 chars (share ids 10), so length alone flags a
+// truncated id. See README.
 //
 // Handlers taking an item id resolve it via resolveItemID/resolveItemIDs; playlist-write handlers
 // and ParentId scoping don't (a restored queue never edits playlists or browses by container id).
diff --git a/server/public/handle_images.go b/server/public/handle_images.go
index 50f9238e5..633665e0f 100644
--- a/server/public/handle_images.go
+++ b/server/public/handle_images.go
@@ -68,7 +68,7 @@ func (pub *Router) handleImages(w http.ResponseWriter, r *http.Request) {
 }
 
 func decodeArtworkID(tokenString string) (model.ArtworkID, error) {
-	token, err := auth.TokenAuth.Decode(tokenString)
+	token, err := auth.PublicTokenAuth.Decode(tokenString)
 	if err != nil {
 		return model.ArtworkID{}, err
 	}
diff --git a/server/public/handle_images_test.go b/server/public/handle_images_test.go
index 6895241f6..669f879a6 100644
--- a/server/public/handle_images_test.go
+++ b/server/public/handle_images_test.go
@@ -9,7 +9,7 @@ import (
 
 var _ = Describe("decodeArtworkID", func() {
 	BeforeEach(func() {
-		auth.TokenAuth = jwtauth.New("HS256", []byte("super secret"), nil)
+		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("super secret"), nil)
 	})
 
 	It("fails to decode an invalid token", func() {
diff --git a/server/public/handle_shares.go b/server/public/handle_shares.go
index 76f674483..13a7e4c32 100644
--- a/server/public/handle_shares.go
+++ b/server/public/handle_shares.go
@@ -111,8 +111,8 @@ func (pub *Router) mapShareToM3U(r *http.Request, s model.Share) *model.Share {
 // admin flag) and grants access to nothing beyond the share it belongs to; the
 // stream handler still verifies the share exists, is unexpired, and that the
 // track is actually a member of it. An attacker who can forge these tokens
-// necessarily already holds the signing secret, which also signs real user
-// sessions, so that scenario is out of scope for the share boundary specifically.
+// necessarily already holds the public-link signing secret, a full-server
+// compromise that is out of scope for the share boundary specifically.
 func encodeMediafileShare(s model.Share, id string) string {
 	claims := auth.Claims{
 		ID:      id,
diff --git a/server/public/handle_streams.go b/server/public/handle_streams.go
index 15abab693..3d624f661 100644
--- a/server/public/handle_streams.go
+++ b/server/public/handle_streams.go
@@ -107,7 +107,7 @@ func shareContainsTrack(share *model.Share, mediaFileID string) bool {
 // public-share capability, not an auth credential; see encodeMediafileShare for
 // why a JWT is used here.
 func decodeStreamInfo(tokenString string) (shareTrackInfo, error) {
-	c, err := auth.Validate(tokenString)
+	c, err := auth.ValidatePublic(tokenString)
 	if err != nil {
 		return shareTrackInfo{}, err
 	}
diff --git a/server/public/handle_streams_test.go b/server/public/handle_streams_test.go
index 2f32ea6f2..870dfa8ef 100644
--- a/server/public/handle_streams_test.go
+++ b/server/public/handle_streams_test.go
@@ -29,7 +29,7 @@ func (m *mockStreamer) NewStream(_ context.Context, _ *model.MediaFile, r stream
 
 var _ = Describe("decodeStreamInfo", func() {
 	BeforeEach(func() {
-		auth.TokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
+		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
 	})
 
 	It("decodes a valid token with all fields", func() {
@@ -81,7 +81,7 @@ var _ = Describe("decodeStreamInfo", func() {
 
 var _ = Describe("encodeMediafileShare", func() {
 	BeforeEach(func() {
-		auth.TokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
+		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
 	})
 
 	It("includes the share ID in the token", func() {
@@ -113,7 +113,7 @@ var _ = Describe("handleStream", func() {
 	var pub *Router
 
 	BeforeEach(func() {
-		auth.TokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
+		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
 		ds = &tests.MockDataStore{}
 		shareRepo = &tests.MockShareRepo{}
 		ds.MockedShare = shareRepo
diff --git a/server/subsonic/helpers_test.go b/server/subsonic/helpers_test.go
index 3741462a2..8db624649 100644
--- a/server/subsonic/helpers_test.go
+++ b/server/subsonic/helpers_test.go
@@ -22,6 +22,7 @@ var _ = Describe("helpers", func() {
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		auth.TokenAuth = jwtauth.New("HS256", []byte("test secret"), nil)
+		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test public secret"), nil)
 	})
 
 	Describe("fakePath", func() {

From 279ff98e0d5f0639077f730083b0c3fd498c800e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 2 Aug 2026 19:46:05 -0400
Subject: [PATCH 009/200] fix(ui): stop precaching index.html so logins can't
 show the wrong user (#5882)

* fix(ui): stop precaching index.html so logins can't show the wrong user

index.html is rendered per-user by the server: it carries __APP_CONFIG__,
including the auth payload (user id, name, role, Subsonic token) when
authentication comes from a reverse-proxy header. Workbox precached it, and
because precacheAndRoute registers its route before the NetworkOnly
NavigationRoute, every navigation to /app/ was answered from Cache Storage
with a frozen copy of whoever installed the service worker.

With ExtAuth, signing out and back in as a different user therefore kept
showing the previous user, along with their Subsonic token. Cache Storage
ignores the no-store header serve_index.go already sets, and ignores the
browser's "disable cache", so only clearing site data recovered.

Excluding index.html from the precache manifest lets the NetworkOnly
navigation strategy do the job it was written for. Existing poisoned caches
heal themselves: the entry is dropped when the new manifest activates.

The same stale document caused the create-admin dialog to reappear (#3613),
patched then by calling removeHomeCache() after login. That helper only ran
on password login and token refresh, so it never covered the ExtAuth path,
and a refetch re-poisoned the cache anyway. Fixing the cause makes it dead
code, so it is removed.

Also serve the offline page on 5xx: it arrives as a normal response, so the
existing catch never saw it, and without a precached shell a restarting
server would surface a raw gateway error. The offline copy is reworded to
fit both causes.

* test(ui): cover the service worker navigation fallback rules

The handler lived inside sw.js, which only loads in a service worker where
workbox arrives via importScripts, so none of it was reachable from vitest.
Moving the decision into its own module pins the rules that matter: a 5xx
falls back to the offline page like a thrown network error does, while 4xx
and 304 still pass through to the app.
---
 .gitignore                        |  1 +
 ui/public/offline.html            |  2 +-
 ui/src/authProvider.js            |  2 -
 ui/src/dataProvider/httpClient.js |  2 -
 ui/src/sw.js                      | 20 +++++-----
 ui/src/swNavigation.js            | 14 +++++++
 ui/src/swNavigation.test.js       | 62 +++++++++++++++++++++++++++++++
 ui/src/utils/removeHomeCache.js   | 20 ----------
 ui/vite.config.js                 |  3 ++
 9 files changed, 90 insertions(+), 36 deletions(-)
 create mode 100644 ui/src/swNavigation.js
 create mode 100644 ui/src/swNavigation.test.js
 delete mode 100644 ui/src/utils/removeHomeCache.js

diff --git a/.gitignore b/.gitignore
index fc8eaac69..3567a7d90 100644
--- a/.gitignore
+++ b/.gitignore
@@ -40,3 +40,4 @@ openspec/
 .agents
 go.work*
 .worktrees/
+.playwright-mcp/
diff --git a/ui/public/offline.html b/ui/public/offline.html
index 72f2d04ae..e3c44e8d3 100644
--- a/ui/public/offline.html
+++ b/ui/public/offline.html
@@ -5,6 +5,6 @@
 <p id="errorMessageDescription" style="text-align:center;font-size:21px;font-family:arial;margin-top:28px">
 It looks like we are having trouble connecting.
 <br/>
-Please check your internet connection and try again.</p>
+Please check your internet connection, or try again in a moment.</p>
 </body>
 </html>
\ No newline at end of file
diff --git a/ui/src/authProvider.js b/ui/src/authProvider.js
index 813a4f5b4..18badbc9c 100644
--- a/ui/src/authProvider.js
+++ b/ui/src/authProvider.js
@@ -1,7 +1,6 @@
 import { jwtDecode } from 'jwt-decode'
 import { baseUrl } from './utils'
 import config from './config'
-import { removeHomeCache } from './utils/removeHomeCache'
 
 // config sent from server may contain authentication info, for example when the user is authenticated
 // by a reverse proxy request header
@@ -49,7 +48,6 @@ const authProvider = {
         storeAuthenticationInfo(response)
         // Avoid "going to create admin" dialog after logout/login without a refresh
         config.firstTime = false
-        removeHomeCache()
         return response
       })
       .catch((error) => {
diff --git a/ui/src/dataProvider/httpClient.js b/ui/src/dataProvider/httpClient.js
index 3820f658d..706486fa6 100644
--- a/ui/src/dataProvider/httpClient.js
+++ b/ui/src/dataProvider/httpClient.js
@@ -3,7 +3,6 @@ import { v4 as uuidv4 } from 'uuid'
 import { baseUrl } from '../utils'
 import config from '../config'
 import { jwtDecode } from 'jwt-decode'
-import { removeHomeCache } from '../utils/removeHomeCache'
 
 const customAuthorizationHeader = 'X-ND-Authorization'
 export const clientUniqueIdHeader = 'X-ND-Client-Unique-Id'
@@ -27,7 +26,6 @@ const httpClient = (url, options = {}) => {
       localStorage.setItem('userId', decoded.uid)
       // Avoid going to create admin dialog after logout/login without a refresh
       config.firstTime = false
-      removeHomeCache()
     }
     return response
   })
diff --git a/ui/src/sw.js b/ui/src/sw.js
index f4a5664b8..edc272850 100644
--- a/ui/src/sw.js
+++ b/ui/src/sw.js
@@ -1,5 +1,7 @@
 /* eslint-disable */
 
+import { createNavigationHandler } from './swNavigation'
+
 // documentation: https://developers.google.com/web/tools/workbox/modules/workbox-sw
 importScripts('3rdparty/workbox/workbox-sw.js')
 
@@ -36,17 +38,13 @@ self.addEventListener('install', async (event) => {
 })
 
 const networkOnly = new workbox.strategies.NetworkOnly()
-const navigationHandler = async (params) => {
-  try {
-    // Attempt a network request.
-    return await networkOnly.handle(params)
-  } catch (error) {
-    // If it fails, return the cached HTML.
-    return caches.match(FALLBACK_HTML_URL, {
-      cacheName: CACHE_NAME,
-    })
-  }
-}
+const fallbackToCachedHtml = () =>
+  caches.match(FALLBACK_HTML_URL, { cacheName: CACHE_NAME })
+
+const navigationHandler = createNavigationHandler(
+  networkOnly,
+  fallbackToCachedHtml,
+)
 
 // self.__WB_MANIFEST is default injection point
 workbox.precaching.precacheAndRoute(self.__WB_MANIFEST)
diff --git a/ui/src/swNavigation.js b/ui/src/swNavigation.js
new file mode 100644
index 000000000..28d01eaef
--- /dev/null
+++ b/ui/src/swNavigation.js
@@ -0,0 +1,14 @@
+// Lives outside sw.js so it can be unit tested: sw.js only loads inside a
+// service worker, where workbox arrives via importScripts.
+export const createNavigationHandler =
+  (networkOnly, offlineFallback) => async (params) => {
+    try {
+      // Attempt a network request.
+      const response = await networkOnly.handle(params)
+      // A 5xx reaches us as a normal response, but carries no usable app
+      return response.status >= 500 ? offlineFallback() : response
+    } catch (error) {
+      // If it fails, return the cached HTML.
+      return offlineFallback()
+    }
+  }
diff --git a/ui/src/swNavigation.test.js b/ui/src/swNavigation.test.js
new file mode 100644
index 000000000..8ab749757
--- /dev/null
+++ b/ui/src/swNavigation.test.js
@@ -0,0 +1,62 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createNavigationHandler } from './swNavigation'
+
+const OFFLINE = { offlinePage: true }
+
+const setup = (networkResult) => {
+  const networkOnly = {
+    handle: vi.fn(() =>
+      networkResult instanceof Error
+        ? Promise.reject(networkResult)
+        : Promise.resolve(networkResult),
+    ),
+  }
+  const offlineFallback = vi.fn(() => Promise.resolve(OFFLINE))
+  return {
+    networkOnly,
+    offlineFallback,
+    handler: createNavigationHandler(networkOnly, offlineFallback),
+  }
+}
+
+describe('createNavigationHandler', () => {
+  it('serves the response from the network', async () => {
+    const response = { status: 200 }
+    const { handler, offlineFallback } = setup(response)
+
+    await expect(handler({})).resolves.toBe(response)
+    expect(offlineFallback).not.toHaveBeenCalled()
+  })
+
+  it('falls back to the offline page when the network fails', async () => {
+    const { handler } = setup(new Error('Failed to fetch'))
+
+    await expect(handler({})).resolves.toBe(OFFLINE)
+  })
+
+  it.each([500, 502, 503])(
+    'falls back to the offline page on %i',
+    async (status) => {
+      const { handler } = setup({ status })
+
+      await expect(handler({})).resolves.toBe(OFFLINE)
+    },
+  )
+
+  it.each([304, 401, 404])('passes %i through untouched', async (status) => {
+    const response = { status }
+    const { handler, offlineFallback } = setup(response)
+
+    await expect(handler({})).resolves.toBe(response)
+    expect(offlineFallback).not.toHaveBeenCalled()
+  })
+
+  it('passes the navigation params to the network strategy', async () => {
+    const params = { request: { url: '/app/' } }
+    const { handler, networkOnly } = setup({ status: 200 })
+
+    await handler(params)
+
+    expect(networkOnly.handle).toHaveBeenCalledWith(params)
+  })
+})
diff --git a/ui/src/utils/removeHomeCache.js b/ui/src/utils/removeHomeCache.js
deleted file mode 100644
index 08ed720e0..000000000
--- a/ui/src/utils/removeHomeCache.js
+++ /dev/null
@@ -1,20 +0,0 @@
-export const removeHomeCache = async () => {
-  try {
-    const workboxKey = (await caches.keys()).find((key) =>
-      key.startsWith('workbox-precache'),
-    )
-    if (!workboxKey) return
-
-    const workboxCache = await caches.open(workboxKey)
-    const indexKey = (await workboxCache.keys()).find((key) =>
-      key.url.includes('app/index.html'),
-    )
-
-    if (indexKey) {
-      await workboxCache.delete(indexKey)
-    }
-  } catch (e) {
-    // eslint-disable-next-line no-console
-    console.error('error reading cache', e)
-  }
-}
diff --git a/ui/vite.config.js b/ui/vite.config.js
index 9d9c845f1..182e825b0 100644
--- a/ui/vite.config.js
+++ b/ui/vite.config.js
@@ -16,6 +16,9 @@ export default defineConfig({
       filename: 'sw.js',
       injectManifest: {
         maximumFileSizeToCacheInBytes: 3 * 1024 * 1024, // 3 MiB
+        // index.html is rendered per-user by the server, so a precached copy
+        // would pin one user's config (and auth payload) across logins
+        globIgnores: ['index.html'],
       },
       devOptions: {
         enabled: true,

From 77726af59ca5808dae08681233b7df98ec6cc7a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 3 Aug 2026 13:09:53 -0400
Subject: [PATCH 010/200] fix(plugins): reject plugin IDs that are unusable as
 directory names (#5886)

The plugin ID is derived from the package filename and used verbatim as a
directory name under DataFolder/plugins by the kvstore and taskqueue host
services. A package installed as '..ndp' yields the ID '.', whose data
directory resolves to the parent of every other plugin's directory, so it
overlaps their private data. On Windows, trailing dots and spaces are dropped
during path normalization, so 'foo..ndp' and 'foo.ndp' yield distinct IDs that
resolve to the same directory and would share the same SQLite files.

Discovery and the file watcher now derive the ID through pluginIDFromPath,
which rejects '.', '..', empty names, separators, trailing dots or spaces, and
anything filepath.IsLocal refuses (Windows reserved names, drive-relative
paths). The loader repeats the check, since a sync failure is non-fatal and
could otherwise leave a stale row reaching the host services.
---
 plugins/manager_loader.go      |  4 ++++
 plugins/manager_loader_test.go | 13 +++++++++++
 plugins/manager_sync.go        |  6 ++++-
 plugins/manager_sync_test.go   | 40 ++++++++++++++++++++++++++++++++++
 plugins/manager_watcher.go     |  6 ++++-
 plugins/package.go             | 22 +++++++++++++++++++
 plugins/package_test.go        | 30 +++++++++++++++++++++++++
 7 files changed, 119 insertions(+), 2 deletions(-)

diff --git a/plugins/manager_loader.go b/plugins/manager_loader.go
index fc9296427..5238a4755 100644
--- a/plugins/manager_loader.go
+++ b/plugins/manager_loader.go
@@ -271,6 +271,10 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 		return fmt.Errorf("manager is stopped")
 	}
 
+	if !validPluginID(p.ID) {
+		return fmt.Errorf("invalid plugin ID %q", p.ID)
+	}
+
 	// Track this operation
 	m.loadWg.Add(1)
 	defer m.loadWg.Done()
diff --git a/plugins/manager_loader_test.go b/plugins/manager_loader_test.go
index 5e6851481..6326b2218 100644
--- a/plugins/manager_loader_test.go
+++ b/plugins/manager_loader_test.go
@@ -1,6 +1,7 @@
 package plugins
 
 import (
+	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -27,6 +28,18 @@ var _ = Describe("buildExtismManifest", func() {
 	})
 })
 
+var _ = Describe("loadPluginWithConfig", func() {
+	// Discovery already rejects these, but a row predating that check, or one
+	// left behind by a failed sync, must not reach the mount setup
+	It("refuses a plugin whose ID is not usable as a directory name", func() {
+		m := &Manager{plugins: make(map[string]*plugin)}
+
+		err := m.loadPluginWithConfig(&model.Plugin{ID: "..", Path: "/does/not/matter.ndp"})
+
+		Expect(err).To(MatchError(ContainSubstring("invalid plugin ID")))
+	})
+})
+
 var _ = Describe("parsePluginConfig", func() {
 	It("returns nil for empty string", func() {
 		result, err := parsePluginConfig("")
diff --git a/plugins/manager_sync.go b/plugins/manager_sync.go
index 2119f1a5a..480fa1bb9 100644
--- a/plugins/manager_sync.go
+++ b/plugins/manager_sync.go
@@ -152,7 +152,11 @@ func (m *Manager) syncPlugins(ctx context.Context, folder string) error {
 			log.Trace(ctx, "Skipping non-plugin entry", "name", entry.Name(), "isDir", entry.IsDir())
 			continue
 		}
-		name := strings.TrimSuffix(entry.Name(), PackageExtension)
+		name, ok := pluginIDFromPath(entry.Name())
+		if !ok {
+			log.Warn(ctx, "Skipping plugin with unusable name", "name", entry.Name())
+			continue
+		}
 		filesOnDisk[name] = filepath.Join(folder, entry.Name())
 	}
 	log.Debug(ctx, "Plugin sync: scanned folder", "folder", folder, "entriesTotal", len(entries), "pluginsFound", len(filesOnDisk))
diff --git a/plugins/manager_sync_test.go b/plugins/manager_sync_test.go
index 26da2079b..dd64dcd3f 100644
--- a/plugins/manager_sync_test.go
+++ b/plugins/manager_sync_test.go
@@ -12,6 +12,46 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+var _ = Describe("syncPlugins", func() {
+	var m *Manager
+	var repo *tests.MockPluginRepo
+	var folder string
+
+	BeforeEach(func() {
+		folder = GinkgoT().TempDir()
+		repo = tests.CreateMockPluginRepo()
+		repo.SetData(model.Plugins{})
+		m = &Manager{ds: &tests.MockDataStore{MockedPlugin: repo}}
+	})
+
+	writePackage := func(name string) {
+		GinkgoHelper()
+		manifest := &Manifest{Name: "Test Plugin", Author: "Test Author", Version: "1.0.0"}
+		wasm := []byte{0x00, 0x61, 0x73, 0x6d} // Minimal wasm header
+		Expect(createTestPackage(filepath.Join(folder, name), manifest, wasm)).To(Succeed())
+	}
+
+	It("registers a plugin with a usable ID", func() {
+		writePackage("my-plugin" + PackageExtension)
+
+		Expect(m.syncPlugins(context.Background(), folder)).To(Succeed())
+
+		_, err := repo.Get("my-plugin")
+		Expect(err).ToNot(HaveOccurred())
+	})
+
+	It("skips packages whose name yields a path-like ID", func() {
+		writePackage("." + PackageExtension)
+		writePackage(".." + PackageExtension)
+
+		Expect(m.syncPlugins(context.Background(), folder)).To(Succeed())
+
+		all, err := repo.GetAll()
+		Expect(err).ToNot(HaveOccurred())
+		Expect(all).To(BeEmpty())
+	})
+})
+
 var _ = Describe("removePluginFromDB", func() {
 	It("discards buffered scrobbles for the removed plugin", func() {
 		ctx := context.Background()
diff --git a/plugins/manager_watcher.go b/plugins/manager_watcher.go
index d666d8620..f7f658be9 100644
--- a/plugins/manager_watcher.go
+++ b/plugins/manager_watcher.go
@@ -89,7 +89,11 @@ func (m *Manager) handleWatcherEvent(event notify.EventInfo) {
 		return
 	}
 
-	pluginName := strings.TrimSuffix(filepath.Base(path), PackageExtension)
+	pluginName, ok := pluginIDFromPath(path)
+	if !ok {
+		log.Warn(m.ctx, "Ignoring plugin file with unusable name", "path", path)
+		return
+	}
 
 	log.Trace(m.ctx, "Plugin file event", "plugin", pluginName, "event", event.Event(), "path", path)
 
diff --git a/plugins/package.go b/plugins/package.go
index e0405d4d8..77cb6e5ac 100644
--- a/plugins/package.go
+++ b/plugins/package.go
@@ -5,6 +5,8 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"path/filepath"
+	"strings"
 )
 
 const (
@@ -18,6 +20,26 @@ const (
 	wasmFileName = "plugin.wasm"
 )
 
+// validPluginID reports whether id is usable. It names a directory under
+// DataFolder/plugins, so a path-like one would point at another plugin's data.
+func validPluginID(id string) bool {
+	if id == "." || id == ".." || strings.ContainsAny(id, `/\`) || !filepath.IsLocal(id) {
+		return false
+	}
+	// Windows drops trailing dots and spaces, so "foo." and "foo" would end up
+	// sharing a directory
+	return strings.TrimRight(id, ". ") == id
+}
+
+// pluginIDFromPath derives the plugin ID from a package path.
+func pluginIDFromPath(path string) (string, bool) {
+	id := strings.TrimSuffix(filepath.Base(path), PackageExtension)
+	if !validPluginID(id) {
+		return "", false
+	}
+	return id, true
+}
+
 // ndpPackage represents a loaded .ndp plugin package.
 // It contains the manifest and wasm bytes read from the archive.
 type ndpPackage struct {
diff --git a/plugins/package_test.go b/plugins/package_test.go
index 4a37f4352..953797750 100644
--- a/plugins/package_test.go
+++ b/plugins/package_test.go
@@ -11,6 +11,36 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+var _ = Describe("pluginIDFromPath", func() {
+	DescribeTable("derives the ID from the package filename",
+		func(path, expected string) {
+			id, ok := pluginIDFromPath(path)
+			Expect(ok).To(BeTrue())
+			Expect(id).To(Equal(expected))
+		},
+		Entry("plain name", "/plugins/discord-rich-presence.ndp", "discord-rich-presence"),
+		Entry("name with spaces", "/plugins/My Plugin.ndp", "My Plugin"),
+		Entry("leading dot", "/plugins/.hidden.ndp", ".hidden"),
+		Entry("dots inside", "/plugins/v1.2.3.ndp", "v1.2.3"),
+	)
+
+	// The ID becomes a directory name under DataFolder/plugins, so a path-like
+	// one would let a plugin reach another plugin's data
+	DescribeTable("rejects IDs that are unsafe as a directory name",
+		func(path string) {
+			_, ok := pluginIDFromPath(path)
+			Expect(ok).To(BeFalse())
+		},
+		Entry("empty", "/plugins/.ndp"),
+		Entry("current directory", "/plugins/..ndp"),
+		Entry("parent directory", "/plugins/...ndp"),
+		// Windows drops trailing dots and spaces, so these would share a
+		// directory with "foo"
+		Entry("trailing dot", "/plugins/foo..ndp"),
+		Entry("trailing space", "/plugins/foo .ndp"),
+	)
+})
+
 var _ = Describe("ndpPackage", func() {
 	var tmpDir string
 

From 54fe6c254e5b9eedf105660fe1ca03ee271c24ca Mon Sep 17 00:00:00 2001
From: Kendall Garner <17521368+kgarner7@users.noreply.github.com>
Date: Mon, 3 Aug 2026 11:23:42 -0700
Subject: [PATCH 011/200] feat(plugins): implement plugin specific storage
 (#5839)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* implement storage api/hooks

* fine. if the error messages are different, just match error

* rename storageMount

* add independent plugin test

* round 2

* .-.

* one more copypasta fail

* docs(plugins): document the Storage host service

The README is the plugin author reference and every other host service has a
section there, but Storage had none, so the /storage guest path contract only
existed in code.

Documents the mount point and its backing directory, the manifest permission,
the host function, and the two behaviours an author would otherwise discover
the hard way: there is no size limit, and the directory outlives an uninstall.

* docs(plugins): correct the library filesystem security notes

The README stated in three places that library filesystem access is read-only,
which stopped being true when AllowWriteAccess was added: an administrator can
grant a plugin write access to libraries.

Corrects those and gives the library and storage mounts the same wording for
what the sandbox guarantees, since both now go through the same jail.

* docs(plugins): describe symlink handling in mounts accurately

The security notes claimed paths resolving outside a mount are rejected, which
overstates the jail. Only lexical escapes are: '..' and absolute paths. Creating
symlinks is denied, but symlinks already present are followed and do reach
outside the mount, which is what lets music libraries link folders in from
elsewhere. Both behaviours are pinned by tests in the plugins package.

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 plugins/README.md                             |  53 +++-
 plugins/host/storage.go                       |  13 +
 plugins/host/storage_gen.go                   |  67 +++++
 plugins/host_storage.go                       |  34 +++
 plugins/host_storage_test.go                  | 270 ++++++++++++++++++
 plugins/manager_loader.go                     |  38 ++-
 plugins/manifest-schema.json                  |  14 +
 plugins/manifest.go                           |   4 +
 plugins/manifest_gen.go                       |  10 +
 plugins/pdk/go/host/doc.go                    |   1 +
 plugins/pdk/go/host/nd_host_storage.go        |  46 +++
 plugins/pdk/go/host/nd_host_storage_stub.go   |  34 +++
 plugins/pdk/rust/nd-pdk-host/src/lib.rs       |   8 +
 .../rust/nd-pdk-host/src/nd_host_storage.rs   |  34 +++
 plugins/testdata/test-storage-plugin-2        |   1 +
 plugins/testdata/test-storage-plugin/go.mod   |  16 ++
 plugins/testdata/test-storage-plugin/go.sum   |  14 +
 plugins/testdata/test-storage-plugin/main.go  |  50 ++++
 .../test-storage-plugin/manifest.json         |  11 +
 19 files changed, 709 insertions(+), 9 deletions(-)
 create mode 100644 plugins/host/storage.go
 create mode 100644 plugins/host/storage_gen.go
 create mode 100644 plugins/host_storage.go
 create mode 100644 plugins/host_storage_test.go
 create mode 100644 plugins/pdk/go/host/nd_host_storage.go
 create mode 100644 plugins/pdk/go/host/nd_host_storage_stub.go
 create mode 100644 plugins/pdk/rust/nd-pdk-host/src/nd_host_storage.rs
 create mode 120000 plugins/testdata/test-storage-plugin-2
 create mode 100644 plugins/testdata/test-storage-plugin/go.mod
 create mode 100644 plugins/testdata/test-storage-plugin/go.sum
 create mode 100644 plugins/testdata/test-storage-plugin/main.go
 create mode 100644 plugins/testdata/test-storage-plugin/manifest.json

diff --git a/plugins/README.md b/plugins/README.md
index 08ab967f3..a2f9532ca 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -30,6 +30,7 @@ The plugin system is built on **[Extism](https://extism.org/)**, a cross-languag
   - [Scheduler](#scheduler)
   - [Cache](#cache)
   - [KVStore](#kvstore)
+  - [Storage](#storage)
   - [Task](#task)
   - [WebSocket](#websocket)
   - [Library](#library)
@@ -548,6 +549,52 @@ usage, err := host.KVStoreGetStorageUsed()
 fmt.Printf("Using %d bytes\n", usage)
 ```
 
+### Storage
+
+A private read-write directory, mounted into the sandbox at `/storage` and backed by `${DataFolder}/plugins/${pluginID}/storage`. Survives server restarts. Use it for data that doesn't fit a key-value store: caches, downloaded files, generated indexes.
+
+**Manifest permission:**
+
+```json
+{
+  "permissions": {
+    "storage": {
+      "reason": "Cache generated playlists between restarts"
+    }
+  }
+}
+```
+
+**Host functions:**
+
+| Function                 | Parameters | Description                        |
+|--------------------------|------------|------------------------------------|
+| `storage_getstoragepath` | –          | Get the guest path of the mount    |
+
+**Usage:**
+
+Normal WASI filesystem calls work inside the mount, so use the `os` package directly:
+
+```go
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/plugins/pdk/go/host"
+)
+
+// The path never changes, so read it once instead of per operation
+var storageDir = host.StorageGetStoragePath() // "/storage"
+
+err := os.WriteFile(filepath.Join(storageDir, "cache.json"), data, 0600)
+content, err := os.ReadFile(filepath.Join(storageDir, "cache.json"))
+entries, err := os.ReadDir(storageDir)
+```
+
+> **Security:** Plugins cannot create symlinks inside the mount, and `..` or absolute paths are rejected. Symlinks that already exist in the directory are still followed, so anything linked in from elsewhere remains reachable.
+
+> **Note:** There is no size limit, unlike [KVStore](#kvstore). The directory is not deleted when a plugin is uninstalled.
+
 ### Task
 
 Background task queue with retry support. Plugins enqueue tasks and process them by exporting the [`nd_task_execute`](#taskworker) capability function.
@@ -644,7 +691,7 @@ Access music library metadata and optionally read files from library directories
 }
 ```
 
-- `filesystem` – Set to `true` to enable read-only access to library directories (default: `false`)
+- `filesystem` – Set to `true` to enable access to library directories, read-only unless an administrator grants write access (default: `false`)
 
 **Host functions:**
 
@@ -683,7 +730,7 @@ content, err := os.ReadFile("/libraries/1/Artist/Album/track.mp3")
 entries, err := os.ReadDir("/libraries/1/Artist")
 ```
 
-> **Security:** Filesystem access is read-only and restricted to configured library paths only.
+> **Security:** Plugins cannot create symlinks inside the mount, and `..` or absolute paths are rejected. Symlinks already present in the library are still followed, so folders linked in from elsewhere work as expected. Access is read-only unless an administrator grants the plugin write access (`navidrome plugin edit <name> --write-access`).
 
 **Usage:**
 
@@ -1058,7 +1105,7 @@ See [examples/](examples/) for complete working plugins:
 Plugins run in a secure WebAssembly sandbox provided by [Extism](https://extism.org/) and the [Wazero](https://wazero.io/) runtime:
 
 1. **Host Allowlisting** – Only explicitly allowed hosts are accessible via HTTP/WebSocket
-2. **Limited File System** – Read-only access to library directories, only when explicitly granted the `library.filesystem` permission
+2. **Limited File System** – Plugins cannot create symlinks inside a mount and `..` or absolute paths are rejected, though symlinks already present are followed. Library access requires the `library.filesystem` permission and is read-only unless an administrator grants write access; the `storage` permission grants a read-write directory private to the plugin
 3. **No Network Listeners** – Plugins cannot bind ports
 4. **Config Isolation** – Plugins only receive their own config section
 5. **Memory Limits** – Controlled by the WebAssembly runtime
diff --git a/plugins/host/storage.go b/plugins/host/storage.go
new file mode 100644
index 000000000..ed24d7508
--- /dev/null
+++ b/plugins/host/storage.go
@@ -0,0 +1,13 @@
+package host
+
+import "context"
+
+// StorageService provides access to a plugin-specific directory with read/write permissions
+//
+//nd:hostservice name=Storage permission=storage
+type StorageService interface {
+	// GetStoragePath retrieves the persistent storage path, if allowed
+	//
+	//nd:hostfunc
+	GetStoragePath(ctx context.Context) string
+}
diff --git a/plugins/host/storage_gen.go b/plugins/host/storage_gen.go
new file mode 100644
index 000000000..d705f0831
--- /dev/null
+++ b/plugins/host/storage_gen.go
@@ -0,0 +1,67 @@
+// Code generated by ndpgen. DO NOT EDIT.
+
+package host
+
+import (
+	"context"
+	"encoding/json"
+
+	extism "github.com/extism/go-sdk"
+)
+
+// StorageGetStoragePathResponse is the response type for Storage.GetStoragePath.
+type StorageGetStoragePathResponse struct {
+	Result string `json:"result,omitempty"`
+}
+
+// RegisterStorageHostFunctions registers Storage service host functions.
+// The returned host functions should be added to the plugin's configuration.
+func RegisterStorageHostFunctions(service StorageService) []extism.HostFunction {
+	return []extism.HostFunction{
+		newStorageGetStoragePathHostFunction(service),
+	}
+}
+
+func newStorageGetStoragePathHostFunction(service StorageService) extism.HostFunction {
+	return extism.NewHostFunctionWithStack(
+		"storage_getstoragepath",
+		func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
+
+			// Call the service method
+			result := service.GetStoragePath(ctx)
+
+			// Write JSON response to plugin memory
+			resp := StorageGetStoragePathResponse{
+				Result: result,
+			}
+			storageWriteResponse(p, stack, resp)
+		},
+		[]extism.ValueType{extism.ValueTypePTR},
+		[]extism.ValueType{extism.ValueTypePTR},
+	)
+}
+
+// storageWriteResponse writes a JSON response to plugin memory.
+func storageWriteResponse(p *extism.CurrentPlugin, stack []uint64, resp any) {
+	respBytes, err := json.Marshal(resp)
+	if err != nil {
+		storageWriteError(p, stack, err)
+		return
+	}
+	respPtr, err := p.WriteBytes(respBytes)
+	if err != nil {
+		stack[0] = 0
+		return
+	}
+	stack[0] = respPtr
+}
+
+// storageWriteError writes an error response to plugin memory.
+func storageWriteError(p *extism.CurrentPlugin, stack []uint64, err error) {
+	errResp := struct {
+		Error string `json:"error"`
+	}{Error: err.Error()}
+	respBytes, _ := json.Marshal(errResp)
+	respPtr, _ := p.WriteBytes(respBytes)
+	stack[0] = respPtr
+}
diff --git a/plugins/host_storage.go b/plugins/host_storage.go
new file mode 100644
index 000000000..e2ead7aae
--- /dev/null
+++ b/plugins/host_storage.go
@@ -0,0 +1,34 @@
+package plugins
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/plugins/host"
+)
+
+const storageMount = "/storage"
+
+type storageServiceImpl struct{}
+
+func getHostStoragePath(pluginName string) string {
+	return filepath.Join(conf.Server.DataFolder.String(), "plugins", pluginName, "storage")
+}
+
+func newStorageService(pluginName string) (host.StorageService, error) {
+	dataDir := getHostStoragePath(pluginName)
+	if err := os.MkdirAll(dataDir, 0700); err != nil {
+		return nil, fmt.Errorf("creating plugin data directory: %w", err)
+	}
+
+	return &storageServiceImpl{}, nil
+}
+
+func (s *storageServiceImpl) GetStoragePath(ctx context.Context) string {
+	return storageMount
+}
+
+var _ host.StorageService = (*storageServiceImpl)(nil)
diff --git a/plugins/host_storage_test.go b/plugins/host_storage_test.go
new file mode 100644
index 000000000..d6f895bff
--- /dev/null
+++ b/plugins/host_storage_test.go
@@ -0,0 +1,270 @@
+//go:build !windows
+
+package plugins
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	extism "github.com/extism/go-sdk"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("utility functions", Ordered, func() {
+	var tmpDir string
+
+	BeforeAll(func() {
+		var err error
+		tmpDir, err = os.MkdirTemp("", "storage-test-*")
+		Expect(err).ToNot(HaveOccurred())
+
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
+
+		DeferCleanup(func() {
+			_ = os.RemoveAll(tmpDir)
+		})
+	})
+
+	Describe("GetHostStoragePath", func() {
+		It("should join data folder, plugins, plugin name, and storage", func() {
+			actual := getHostStoragePath("plugin-name")
+			expected := filepath.Join(tmpDir, "plugins", "plugin-name", "storage")
+			Expect(actual).To(Equal(expected))
+		})
+	})
+
+	Describe("GetStoragePath", func() {
+		It("should return the fixed path", func() {
+			impl := storageServiceImpl{}
+			Expect(impl.GetStoragePath(context.TODO())).To(Equal("/storage"))
+		})
+	})
+
+	Describe("netStorageService", func() {
+		It("should create the directory on init", func() {
+			svc, err := newStorageService("plugin-name")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(svc).ToNot(BeNil())
+
+			dataDir := filepath.Join(tmpDir, "plugins", "plugin-name", "storage")
+			Expect(dataDir).To(BeADirectory())
+		})
+	})
+})
+
+var _ = Describe("Storage Host Function", Ordered, func() {
+	const ID = "test-storage-plugin"
+
+	var (
+		manager *Manager
+		tmpDir  string
+	)
+
+	BeforeAll(func() {
+		var err error
+		tmpDir, err = os.MkdirTemp("", "storage-test-*")
+		Expect(err).ToNot(HaveOccurred())
+
+		// Setup mock router and data store
+		router := &fakeSubsonicRouter{}
+		userRepo := tests.CreateMockUserRepo()
+		dataStore := &tests.MockDataStore{MockedUser: userRepo}
+
+		// Create and configure manager
+		manager = &Manager{
+			plugins: make(map[string]*plugin),
+			ds:      dataStore,
+		}
+		manager.SetSubsonicRouter(router)
+
+		mockPluginRepo := dataStore.Plugin(GinkgoT().Context()).(*tests.MockPluginRepo)
+		mockPluginRepo.Permitted = true
+
+		// Setup config
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
+		conf.Server.Plugins.Enabled = true
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
+		conf.Server.Plugins.AutoReload = false
+
+		pluginPaths := []string{ID, ID + "-2"}
+		plugins := []model.Plugin{}
+
+		for idx := range pluginPaths {
+			path := pluginPaths[idx] + PackageExtension
+			// Copy test plugin to temp dir
+			srcPath := filepath.Join(testdataDir, path)
+			destPath := filepath.Join(tmpDir, path)
+			data, err := os.ReadFile(srcPath)
+			Expect(err).ToNot(HaveOccurred())
+			err = os.WriteFile(destPath, data, 0600)
+			Expect(err).ToNot(HaveOccurred())
+
+			// Pre-enable the plugin in the mock repo so it loads on startup
+			// Compute SHA256 of the plugin file to match what syncPlugins will compute
+			pluginPath := filepath.Join(tmpDir, path)
+			wasmData, err := os.ReadFile(pluginPath)
+			Expect(err).ToNot(HaveOccurred())
+			hash := sha256.Sum256(wasmData)
+			hashHex := hex.EncodeToString(hash[:])
+
+			plugins = append(plugins, model.Plugin{
+				ID:       pluginPaths[idx],
+				Path:     pluginPath,
+				SHA256:   hashHex,
+				Enabled:  true,
+				AllUsers: true, // Allow all users for test plugin
+			})
+		}
+
+		mockPluginRepo.SetData(plugins)
+
+		// Start the manager
+		err = manager.Start(GinkgoT().Context())
+		Expect(err).ToNot(HaveOccurred())
+
+		DeferCleanup(func() {
+			_ = manager.Stop()
+			_ = os.RemoveAll(tmpDir)
+		})
+	})
+
+	var instance *extism.Plugin
+	BeforeEach(func() {
+		var err error
+		manager.mu.RLock()
+		plugin := manager.plugins[ID]
+		manager.mu.RUnlock()
+		Expect(plugin).ToNot(BeNil())
+
+		ctx := GinkgoT().Context()
+		instance, err = plugin.instance(ctx)
+		Expect(err).ToNot(HaveOccurred())
+
+		DeferCleanup(func() {
+			instance.Close(ctx)
+		})
+	})
+
+	Describe("Read", func() {
+		BeforeAll(func() {
+			path := filepath.Join(getHostStoragePath(ID), "real")
+			err := os.WriteFile(path, []byte("1234"), 0600)
+			Expect(err).ToNot(HaveOccurred())
+
+			DeferCleanup(func() {
+				_ = os.Remove(path)
+			})
+		})
+
+		It("should fail to read missing file", func() {
+			exit, _, err := instance.Call("call_read", []byte("missing"))
+			Expect(exit).To(Equal(uint32(1)))
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("should read an existing file", func() {
+			exit, output, err := instance.Call("call_read", []byte("real"))
+			Expect(exit).To(Equal(uint32(0)))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output).To(Equal([]byte("1234")))
+		})
+
+		It("should not escape read", func() {
+			path := filepath.Join(getHostStoragePath(ID), "..", "outside")
+			err := os.WriteFile(path, []byte("outside"), 0600)
+			Expect(err).ToNot(HaveOccurred())
+
+			exit, _, err := instance.Call("call_read", []byte("../outside"))
+			Expect(exit).To(Equal(uint32(1)))
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	Describe("Write", func() {
+		BeforeAll(func() {
+			path := filepath.Join(getHostStoragePath(ID), "real")
+			err := os.WriteFile(path, []byte("1234"), 0600)
+			Expect(err).ToNot(HaveOccurred())
+
+			DeferCleanup(func() {
+				_ = os.Remove(path)
+			})
+		})
+
+		It("should fail to write to nested file", func() {
+			exit, _, err := instance.Call("call_write", []byte(`{"path":"nested/file","contents":"1234"}`))
+			Expect(exit).To(Equal(uint32(1)))
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("should write to a file", func() {
+			exit, _, err := instance.Call("call_write", []byte(`{"path":"new","contents":"contents"}`))
+			Expect(exit).To(Equal(uint32(0)))
+			Expect(err).ToNot(HaveOccurred())
+
+			data, err := os.ReadFile(filepath.Join(getHostStoragePath(ID), "new"))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(data).To(Equal([]byte("contents")))
+
+			exit, output, err := instance.Call("call_read", []byte("new"))
+			Expect(exit).To(Equal(uint32(0)))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(output).To(Equal([]byte("contents")))
+		})
+
+		It("should not escape writing a file", func() {
+			path := filepath.Join(getHostStoragePath(ID), "..", "outside")
+			err := os.WriteFile(path, []byte("outside"), 0600)
+			Expect(err).ToNot(HaveOccurred())
+
+			exit, _, err := instance.Call("call_write", []byte(`{"path":"../new","contents":"contents"}`))
+			Expect(exit).To(Equal(uint32(1)))
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("should have independent storage for multiple plugins", func() {
+			manager.mu.RLock()
+			plugin2 := manager.plugins[ID+"-2"]
+			manager.mu.RUnlock()
+
+			Expect(plugin2).ToNot(BeNil())
+
+			secondInstance, err := plugin2.instance(GinkgoT().Context())
+			Expect(err).ToNot(HaveOccurred())
+			defer secondInstance.Close(GinkgoT().Context())
+
+			instances := []*extism.Plugin{instance, secondInstance}
+			names := []string{ID, ID + "-2"}
+
+			for idx := range instances {
+				exit, _, err := instances[idx].Call("call_write", fmt.Appendf(nil, `{"path":"new","contents":"%s"}`, names[idx]))
+				Expect(exit).To(Equal(uint32(0)))
+				Expect(err).ToNot(HaveOccurred())
+			}
+
+			for idx := range names {
+				data, err := os.ReadFile(filepath.Join(getHostStoragePath(names[idx]), "new"))
+				Expect(err).ToNot(HaveOccurred())
+				Expect(data).To(Equal([]byte(names[idx])))
+			}
+
+			for idx := range instances {
+				exit, output, err := instances[idx].Call("call_read", []byte("new"))
+				Expect(exit).To(Equal(uint32(0)))
+				Expect(err).ToNot(HaveOccurred())
+				Expect(output).To(Equal([]byte(names[idx])))
+			}
+		})
+	})
+})
diff --git a/plugins/manager_loader.go b/plugins/manager_loader.go
index 5238a4755..0e9e7bb62 100644
--- a/plugins/manager_loader.go
+++ b/plugins/manager_loader.go
@@ -166,6 +166,17 @@ var hostServices = []hostServiceEntry{
 			return host.RegisterTaskHostFunctions(service), service, nil
 		},
 	},
+	{
+		name:          "Storage",
+		hasPermission: func(p *Permissions) bool { return p != nil && p.Storage != nil },
+		create: func(ctx *serviceContext) ([]extism.HostFunction, io.Closer, error) {
+			service, err := newStorageService(ctx.pluginName)
+			if err != nil {
+				return nil, nil, err
+			}
+			return host.RegisterStorageHostFunctions(service), nil, nil
+		},
+	},
 }
 
 // extractManifest reads manifest from an .ndp package and computes its SHA-256 hash.
@@ -315,14 +326,29 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 
 	// Configure filesystem access for library permission, applied per instance
 	var fsConfig wazero.FSConfig
-	if pkg.Manifest.HasLibraryFilesystemPermission() {
-		adminCtx := adminContext(ctx)
-		libraries, err := m.ds.Library(adminCtx).GetAll()
-		if err != nil {
-			return fmt.Errorf("failed to get libraries for filesystem access: %w", err)
+	if pkg.Manifest.HasLibraryFilesystemPermission() || pkg.Manifest.HasStoragePermission() {
+		mounts := []mount{}
+
+		if pkg.Manifest.HasLibraryFilesystemPermission() {
+			adminCtx := adminContext(ctx)
+			libraries, err := m.ds.Library(adminCtx).GetAll()
+			if err != nil {
+				return fmt.Errorf("failed to get libraries for filesystem access: %w", err)
+			}
+			mounts = buildMounts(ctx, libraries, allowedLibraries, p.AllLibraries, p.AllowWriteAccess)
 		}
 
-		fsConfig = buildFSConfig(buildMounts(ctx, libraries, allowedLibraries, p.AllLibraries, p.AllowWriteAccess))
+		if pkg.Manifest.HasStoragePermission() {
+			pluginStore := getHostStoragePath(p.ID)
+			log.Info(ctx, "Granting read-write filesystem access to plugin storage", "path", pluginStore, "id", p.ID)
+
+			mounts = append(mounts, mount{
+				hostPath:  pluginStore,
+				guestPath: storageMount,
+			})
+		}
+
+		fsConfig = buildFSConfig(mounts)
 	}
 
 	// Build host functions based on permissions from manifest
diff --git a/plugins/manifest-schema.json b/plugins/manifest-schema.json
index 28adeed79..736677313 100644
--- a/plugins/manifest-schema.json
+++ b/plugins/manifest-schema.json
@@ -92,6 +92,9 @@
         },
         "matcher": {
           "$ref": "#/$defs/MatcherPermission"
+        },
+        "storage": {
+          "$ref": "#/$defs/StoragePermission"
         }
       }
     },
@@ -244,6 +247,17 @@
           "description": "Explanation for why matcher access is needed"
         }
       }
+    },
+    "StoragePermission": {
+      "type": "object",
+      "description": "Storage permissions for enabling persistent read-write storage exclusively for the plugin",
+      "additionalProperties": false,
+      "properties": {
+        "reason": {
+          "type": "string",
+          "description": "Explanation for why storage access is needed"
+        }
+      }
     }
   }
 }
diff --git a/plugins/manifest.go b/plugins/manifest.go
index 5e144b5c8..ef70e8d9d 100644
--- a/plugins/manifest.go
+++ b/plugins/manifest.go
@@ -123,3 +123,7 @@ func (m *Manifest) HasLibraryFilesystemPermission() bool {
 		m.Permissions.Library != nil &&
 		m.Permissions.Library.Filesystem
 }
+
+func (m *Manifest) HasStoragePermission() bool {
+	return m.Permissions != nil && m.Permissions.Storage != nil
+}
diff --git a/plugins/manifest_gen.go b/plugins/manifest_gen.go
index c2aa5e298..5e0035bd5 100644
--- a/plugins/manifest_gen.go
+++ b/plugins/manifest_gen.go
@@ -178,6 +178,9 @@ type Permissions struct {
 	// Scheduler corresponds to the JSON schema field "scheduler".
 	Scheduler *SchedulerPermission `json:"scheduler,omitempty" yaml:"scheduler,omitempty" mapstructure:"scheduler,omitempty"`
 
+	// Storage corresponds to the JSON schema field "storage".
+	Storage *StoragePermission `json:"storage,omitempty" yaml:"storage,omitempty" mapstructure:"storage,omitempty"`
+
 	// Subsonicapi corresponds to the JSON schema field "subsonicapi".
 	Subsonicapi *SubsonicAPIPermission `json:"subsonicapi,omitempty" yaml:"subsonicapi,omitempty" mapstructure:"subsonicapi,omitempty"`
 
@@ -197,6 +200,13 @@ type SchedulerPermission struct {
 	Reason *string `json:"reason,omitempty" yaml:"reason,omitempty" mapstructure:"reason,omitempty"`
 }
 
+// Storage permissions for enabling persistent read-write storage exclusively for
+// the plugin
+type StoragePermission struct {
+	// Explanation for why storage access is needed
+	Reason *string `json:"reason,omitempty" yaml:"reason,omitempty" mapstructure:"reason,omitempty"`
+}
+
 // SubsonicAPI service permissions. Requires 'users' permission to be declared.
 type SubsonicAPIPermission struct {
 	// Explanation for why SubsonicAPI access is needed
diff --git a/plugins/pdk/go/host/doc.go b/plugins/pdk/go/host/doc.go
index ff2c2a07f..e4157e29c 100644
--- a/plugins/pdk/go/host/doc.go
+++ b/plugins/pdk/go/host/doc.go
@@ -43,6 +43,7 @@ The following host services are available:
   - Library: provides access to music library metadata for plugins.
   - Matcher: resolves externally-obtained songs to local library tracks,
   - Scheduler: provides task scheduling capabilities for plugins.
+  - Storage: provides access to a plugin-specific directory with read/write permissions
   - SubsonicAPI: provides access to Navidrome's Subsonic API from plugins.
   - Task: provides persistent task queues for plugins.
   - Users: provides access to user information for plugins.
diff --git a/plugins/pdk/go/host/nd_host_storage.go b/plugins/pdk/go/host/nd_host_storage.go
new file mode 100644
index 000000000..4f37bc8e2
--- /dev/null
+++ b/plugins/pdk/go/host/nd_host_storage.go
@@ -0,0 +1,46 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains client wrappers for the Storage host service.
+// It is intended for use in Navidrome plugins built with TinyGo.
+//
+//go:build wasip1
+
+package host
+
+import (
+	"encoding/json"
+
+	"github.com/navidrome/navidrome/plugins/pdk/go/pdk"
+)
+
+// storage_getstoragepath is the host function provided by Navidrome.
+//
+//go:wasmimport extism:host/user storage_getstoragepath
+func storage_getstoragepath(uint64) uint64
+
+type storageGetStoragePathResponse struct {
+	Result string `json:"result,omitempty"`
+}
+
+// StorageGetStoragePath calls the storage_getstoragepath host function.
+// GetStoragePath retrieves the persistent storage path, if allowed
+func StorageGetStoragePath() string {
+	// No parameters - allocate empty JSON object
+	reqMem := pdk.AllocateBytes([]byte("{}"))
+	defer reqMem.Free()
+
+	// Call the host function
+	responsePtr := storage_getstoragepath(reqMem.Offset())
+
+	// Read the response from memory
+	responseMem := pdk.FindMemory(responsePtr)
+	responseBytes := responseMem.ReadBytes()
+
+	// Parse the response
+	var response storageGetStoragePathResponse
+	if err := json.Unmarshal(responseBytes, &response); err != nil {
+		return ""
+	}
+
+	return response.Result
+}
diff --git a/plugins/pdk/go/host/nd_host_storage_stub.go b/plugins/pdk/go/host/nd_host_storage_stub.go
new file mode 100644
index 000000000..c2213ece9
--- /dev/null
+++ b/plugins/pdk/go/host/nd_host_storage_stub.go
@@ -0,0 +1,34 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains mock implementations for non-WASM builds.
+// These mocks allow IDE support, compilation, and unit testing on non-WASM platforms.
+// Plugin authors can use the exported mock instances to set expectations in tests.
+//
+//go:build !wasip1
+
+package host
+
+import (
+	"github.com/stretchr/testify/mock"
+)
+
+// mockStorageService is the mock implementation for testing.
+type mockStorageService struct {
+	mock.Mock
+}
+
+// StorageMock is the auto-instantiated mock instance for testing.
+// Use this to set expectations: host.StorageMock.On("MethodName", args...).Return(values...)
+var StorageMock = &mockStorageService{}
+
+// GetStoragePath is the mock method for StorageGetStoragePath.
+func (m *mockStorageService) GetStoragePath() string {
+	args := m.Called()
+	return args.String(0)
+}
+
+// StorageGetStoragePath delegates to the mock instance.
+// GetStoragePath retrieves the persistent storage path, if allowed
+func StorageGetStoragePath() string {
+	return StorageMock.GetStoragePath()
+}
diff --git a/plugins/pdk/rust/nd-pdk-host/src/lib.rs b/plugins/pdk/rust/nd-pdk-host/src/lib.rs
index cc1fdc190..3da023f5c 100644
--- a/plugins/pdk/rust/nd-pdk-host/src/lib.rs
+++ b/plugins/pdk/rust/nd-pdk-host/src/lib.rs
@@ -40,6 +40,7 @@
 //! - [`library`] - provides access to music library metadata for plugins.
 //! - [`matcher`] - resolves externally-obtained songs to local library tracks,
 //! - [`scheduler`] - provides task scheduling capabilities for plugins.
+//! - [`storage`] - provides access to a plugin-specific directory with read/write permissions
 //! - [`subsonicapi`] - provides access to Navidrome's Subsonic API from plugins.
 //! - [`task`] - provides persistent task queues for plugins.
 //! - [`users`] - provides access to user information for plugins.
@@ -101,6 +102,13 @@ pub mod scheduler {
     pub use super::nd_host_scheduler::*;
 }
 
+#[doc(hidden)]
+mod nd_host_storage;
+/// provides access to a plugin-specific directory with read/write permissions
+pub mod storage {
+    pub use super::nd_host_storage::*;
+}
+
 #[doc(hidden)]
 mod nd_host_subsonicapi;
 /// provides access to Navidrome's Subsonic API from plugins.
diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_storage.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_storage.rs
new file mode 100644
index 000000000..336ae565f
--- /dev/null
+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_storage.rs
@@ -0,0 +1,34 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains client wrappers for the Storage host service.
+// It is intended for use in Navidrome plugins built with extism-pdk.
+
+use extism_pdk::*;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct StorageGetStoragePathResponse {
+    #[serde(default)]
+    result: String,
+}
+
+#[host_fn]
+extern "ExtismHost" {
+    fn storage_getstoragepath(input: Json<serde_json::Value>) -> Json<StorageGetStoragePathResponse>;
+}
+
+/// GetStoragePath retrieves the persistent storage path, if allowed
+///
+/// # Returns
+/// The result value.
+///
+/// # Errors
+/// Returns an error if the host function call fails.
+pub fn get_storage_path() -> Result<String, Error> {
+    let response = unsafe {
+        storage_getstoragepath(Json(serde_json::json!({})))?
+    };
+
+    Ok(response.0.result)
+}
diff --git a/plugins/testdata/test-storage-plugin-2 b/plugins/testdata/test-storage-plugin-2
new file mode 120000
index 000000000..444bafd87
--- /dev/null
+++ b/plugins/testdata/test-storage-plugin-2
@@ -0,0 +1 @@
+test-storage-plugin
\ No newline at end of file
diff --git a/plugins/testdata/test-storage-plugin/go.mod b/plugins/testdata/test-storage-plugin/go.mod
new file mode 100644
index 000000000..7b9a2b567
--- /dev/null
+++ b/plugins/testdata/test-storage-plugin/go.mod
@@ -0,0 +1,16 @@
+module test-storage-plugin
+
+go 1.25
+
+require github.com/navidrome/navidrome/plugins/pdk/go v0.0.0
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/extism/go-pdk v1.1.3 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/navidrome/navidrome/plugins/pdk/go => ../../pdk/go
diff --git a/plugins/testdata/test-storage-plugin/go.sum b/plugins/testdata/test-storage-plugin/go.sum
new file mode 100644
index 000000000..af880eb51
--- /dev/null
+++ b/plugins/testdata/test-storage-plugin/go.sum
@@ -0,0 +1,14 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/extism/go-pdk v1.1.3 h1:hfViMPWrqjN6u67cIYRALZTZLk/enSPpNKa+rZ9X2SQ=
+github.com/extism/go-pdk v1.1.3/go.mod h1:Gz+LIU/YCKnKXhgge8yo5Yu1F/lbv7KtKFkiCSzW/P4=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/plugins/testdata/test-storage-plugin/main.go b/plugins/testdata/test-storage-plugin/main.go
new file mode 100644
index 000000000..17ffc8e6b
--- /dev/null
+++ b/plugins/testdata/test-storage-plugin/main.go
@@ -0,0 +1,50 @@
+// Test plugin for Storage host function integration tests.
+// Build with: tinygo build -o ../test-storage-plugin.wasm -target wasip1 -buildmode=c-shared ./main.go
+package main
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/plugins/pdk/go/host"
+	"github.com/navidrome/navidrome/plugins/pdk/go/pdk"
+)
+
+//go:wasmexport call_read
+func callRead() int32 {
+	path := filepath.Join(host.StorageGetStoragePath(), pdk.InputString())
+	content, err := os.ReadFile(path)
+	if err != nil {
+		pdk.SetErrorString("failed to read file: " + err.Error())
+		return 1
+	}
+	pdk.Output(content)
+	return 0
+}
+
+type WriteInput struct {
+	Path     string `json:"path"`
+	Contents string `json:"contents"`
+}
+
+//go:wasmexport call_write
+func callWrite() int32 {
+	var config WriteInput
+	err := pdk.InputJSON(&config)
+
+	if err != nil {
+		pdk.SetErrorString("failed to parse json: " + err.Error())
+		return 1
+	}
+
+	path := filepath.Join(host.StorageGetStoragePath(), config.Path)
+	err = os.WriteFile(path, []byte(config.Contents), 0600)
+	if err != nil {
+		pdk.SetErrorString("failed to write file: " + err.Error())
+		return 1
+	}
+
+	return 0
+}
+
+func main() {}
diff --git a/plugins/testdata/test-storage-plugin/manifest.json b/plugins/testdata/test-storage-plugin/manifest.json
new file mode 100644
index 000000000..98ac24a47
--- /dev/null
+++ b/plugins/testdata/test-storage-plugin/manifest.json
@@ -0,0 +1,11 @@
+{
+  "name": "Test Storage Plugin",
+  "author": "Navidrome Test",
+  "version": "1.0.0",
+  "description": "Test plugin for storage host function",
+  "permissions": {
+    "storage": {
+      "reason": "persistent storage for testing"
+    }
+  }
+}

From e1b89050df7cb228f04d5870be03af3c985fc3bc Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Mon, 3 Aug 2026 14:34:53 -0400
Subject: [PATCH 012/200] chore: exclude .worktrees from golangci-lint checks

---
 .golangci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.golangci.yml b/.golangci.yml
index 200fe122f..0804138dc 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -69,6 +69,7 @@ linters:
       - examples$
       - node_modules
       - _gen\.go$
+      - .worktrees
 formatters:
   exclusions:
     generated: lax

From 50633f839dabe49571099977753036d166734982 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 4 Aug 2026 22:07:16 -0400
Subject: [PATCH 013/200] fix(ui): restore each page's scroll position when
 navigating back (#5892)

* fix(ui): anchor detail pages to the top when opened from a list

React Router keeps the previous page's scroll offset, so opening an album from
a scrolled list started the detail page mid-song-list. Artist pages had the
same bug; it just shows less because the artist list is rarely long enough to
scroll far.

Keyed on the record id rather than mount, so detail-to-detail navigation (an
album's artist link) resets too, and so the scroll waits for the record instead
of firing against an empty page.

* feat(ui): remember each route's scroll offset

A hook that saves window.scrollY per history entry and, on navigation, tops a
pushed route or returns a popped one to where it was. Keyed on location.key so
back and forward each restore their own offset, and bounded because history
entries are not.

Callers pass their own readiness: restoring before the rows render leaves the
document too short, so the browser clamps to the top and the offset is lost with
no error to show for it.

* refactor(ui): fold scroll-to-top into route scroll restoration

useScrollToTop only ever forced the top, so it fixed opening a detail page from a
scrolled list and did nothing for the return trip: coming back to the list landed
wherever it happened to be. The new hook covers both, and its readiness argument
carries over the reason the old one keyed on the record id - waiting for the
record rather than firing against an empty page.

* feat(ui): restore the album list's position when returning to it

The list is the page worth remembering: scrolling a long way to find an album and
landing back at the top is the annoyance the detail-page scroll fix could not
reach.

Mounted as a pass-through around the List's child rather than beside it, because
React Admin calls Children.only on List children and clones that one child with
the list props - which is also how this reads loaded/total to wait for rows.

* fix(ui): key scroll restoration on the route, not location.key

Hash history never assigns location.key - history.js calls createLocation with an
undefined key and warns that it cannot carry state - so every route collapsed
into one slot. The detail page's own scroll listener then overwrote the list's
saved offset with 0, and going back restored that 0. Only the scroll-to-top half
worked, which is what made it look fine.

Keyed on pathname+search instead. The spec that would have caught this asserts
two routes keep separate offsets; the previous ones mocked the router and so
only ever confirmed the assumption.

* refactor(ui): tidy up scroll restoration after review

Four cleanups, none changing behaviour:

ScrollRestorer read loaded/total off whatever props React Admin happened to clone
in. useListContext is the contract for those values and is already used three
times elsewhere, including further down this same file; the clone payload is an
implementation detail that would fail silently if it ever changed.

The restore runs in a layout effect now. A passive effect is flushed after paint,
so an image-heavy grid was painted at the old offset and then jumped.

MAX_ENTRIES matches the naming every other module-level cap in common/ uses.

The per-instance guard against re-restoring was deletable with a green suite, so
it now has a spec: readiness flickering on one route must not scroll twice.

* fix(ui): resolve media queries on the first render

MUI defaults useMediaQuery and withWidth to SSR-safe two-pass rendering: the first
render reports the wrong breakpoint and a layout effect corrects it. Navidrome is
client-only, so every mount paints a layout it immediately reflows. Album tiles
render without their artist line and grow 14px when it arrives, and react-admin's
own buttons paint labelled before collapsing to icons, which together grew the
album list 79px right after a scroll restore and dragged the position with it.

Setting noSsr on the theme reaches react-admin's internals too. withWidth needs its
own option because it gates on a mount flag rather than on the media query.

* fix(ui): keep restoring the scroll offset until it sticks

A single scrollTo assumes the page is already at its final height. It often is not:
the artist page reports ready as soon as its cached header record renders, while the
albums below are still loading, so the browser clamps the offset to the top of a
viewport-tall document and it is lost with no error.

The restore now retries until the offset lands, yielding as soon as the position moves
somewhere we did not put it. Keying that on input events instead breaks the trackpad
back-swipe, whose wheel momentum keeps firing through the restore window.

Offsets are also committed when leaving the page rather than on every scroll. Tearing
the page down collapses the document and snaps to the top, and a live listener recorded
that clamp over the offset being left behind.

* refactor(ui): tidy up scroll restoration after review

Folds the offset commit into the scroll tracker's own cleanup now that the tracker
ignores the collapse snap, so one effect does what two did. Skips scheduling the retry
loop when the first scrollTo already landed, and only pays for the scrollHeight read on
scroll events that reach the top, since that is the only case the guard can fire.

The theme hook's own prefers-color-scheme query runs above the ThemeProvider carrying
the new prop, so it needs noSsr passed directly or the auto theme still renders dark
first and flips.

Also lifts the repeated fake-timer fixture in the specs into one helper and restores
real timers from afterEach, so a failing assertion no longer leaves them installed for
every later spec.

* fix(ui): bank the scroll offset before the next page tops itself

Committing the offset from the scroll listener's passive cleanup ran too late. The
incoming page scrolls to the top in its own layout effect, and the outgoing page's
listener is still attached at that moment, so it recorded that 0 over the offset being
left behind. Whether it did depended on when the browser dispatched the scroll event
relative to React's passive flush, which made returning to a detail page lose its
position intermittently.

Moving the commit back into a layout cleanup makes it deterministic: React runs those
in the mutation phase, before the incoming page's layout effects. The scrollHeight
guard in the listener went with it, since it only covered the case where the incoming
page was shorter than the viewport and the ordering covers all of them.
---
 ui/src/album/AlbumList.jsx                  |  21 +-
 ui/src/album/AlbumShow.jsx                  |   3 +-
 ui/src/artist/ArtistShow.jsx                |   8 +-
 ui/src/common/ArtistLinkField.jsx           |   3 +-
 ui/src/common/index.js                      |   1 +
 ui/src/common/useScrollRestoration.jsx      |  64 ++++++
 ui/src/common/useScrollRestoration.test.jsx | 222 ++++++++++++++++++++
 ui/src/themes/useCurrentTheme.js            |  18 +-
 8 files changed, 329 insertions(+), 11 deletions(-)
 create mode 100644 ui/src/common/useScrollRestoration.jsx
 create mode 100644 ui/src/common/useScrollRestoration.test.jsx

diff --git a/ui/src/album/AlbumList.jsx b/ui/src/album/AlbumList.jsx
index 5108bfaa1..cd73fa0c3 100644
--- a/ui/src/album/AlbumList.jsx
+++ b/ui/src/album/AlbumList.jsx
@@ -1,3 +1,4 @@
+import { cloneElement } from 'react'
 import { useSelector } from 'react-redux'
 import { Redirect, useLocation } from 'react-router-dom'
 import {
@@ -23,6 +24,7 @@ import {
   Title,
   useAlbumsPerPage,
   useResourceRefresh,
+  useScrollRestoration,
   useSetToggleableFields,
 } from '../common'
 import AlbumListActions from './AlbumListActions'
@@ -39,6 +41,13 @@ import ExpandInfoDialog from '../dialogs/ExpandInfoDialog'
 import { humanize } from 'inflection'
 import { makeStyles } from '@material-ui/core/styles'
 
+// Waits for rows: restoring into an unrendered list leaves the page too short to hold the offset.
+const ScrollRestorer = ({ children, ...rest }) => {
+  const { loaded, total } = useListContext()
+  useScrollRestoration(loaded && total > 0)
+  return cloneElement(children, rest)
+}
+
 const useStyles = makeStyles({
   chip: {
     margin: 0,
@@ -255,11 +264,13 @@ const AlbumList = (props) => {
         }
         title={<AlbumListTitle albumListType={albumListType} />}
       >
-        {albumView.grid ? (
-          <AlbumGridView albumListType={albumListType} {...props} />
-        ) : (
-          <AlbumTableView {...props} />
-        )}
+        <ScrollRestorer>
+          {albumView.grid ? (
+            <AlbumGridView albumListType={albumListType} {...props} />
+          ) : (
+            <AlbumTableView {...props} />
+          )}
+        </ScrollRestorer>
       </List>
       <ExpandInfoDialog content={<AlbumInfo />} />
     </>
diff --git a/ui/src/album/AlbumShow.jsx b/ui/src/album/AlbumShow.jsx
index c9e944999..86b5ab1bc 100644
--- a/ui/src/album/AlbumShow.jsx
+++ b/ui/src/album/AlbumShow.jsx
@@ -10,7 +10,7 @@ import { makeStyles } from '@material-ui/core/styles'
 import AlbumSongs from './AlbumSongs'
 import AlbumDetails from './AlbumDetails'
 import AlbumActions from './AlbumActions'
-import { useResourceRefresh, Title } from '../common'
+import { useResourceRefresh, useScrollRestoration, Title } from '../common'
 
 const useStyles = makeStyles(
   (theme) => ({
@@ -28,6 +28,7 @@ const AlbumShowLayout = (props) => {
   const { record } = context
   const classes = useStyles()
   useResourceRefresh('album', 'song')
+  useScrollRestoration(!!record?.id)
 
   return (
     <>
diff --git a/ui/src/artist/ArtistShow.jsx b/ui/src/artist/ArtistShow.jsx
index 955a565d6..eef2989d5 100644
--- a/ui/src/artist/ArtistShow.jsx
+++ b/ui/src/artist/ArtistShow.jsx
@@ -13,7 +13,12 @@ import subsonic from '../subsonic'
 import AlbumGridView from '../album/AlbumGridView'
 import MobileArtistDetails from './MobileArtistDetails'
 import DesktopArtistDetails from './DesktopArtistDetails'
-import { useAlbumsPerPage, useResourceRefresh, Title } from '../common/index.js'
+import {
+  useAlbumsPerPage,
+  useResourceRefresh,
+  useScrollRestoration,
+  Title,
+} from '../common/index.js'
 import ArtistActions from './ArtistActions'
 import { makeStyles } from '@material-ui/core'
 
@@ -85,6 +90,7 @@ const ArtistShowLayout = (props) => {
   const [, perPageOptions] = useAlbumsPerPage(width)
   const classes = useStyles()
   useResourceRefresh('artist', 'album')
+  useScrollRestoration(!!record?.id)
 
   const maxPerPage = 90
   let perPage = 0
diff --git a/ui/src/common/ArtistLinkField.jsx b/ui/src/common/ArtistLinkField.jsx
index d41b47b06..2a70ded7c 100644
--- a/ui/src/common/ArtistLinkField.jsx
+++ b/ui/src/common/ArtistLinkField.jsx
@@ -7,7 +7,8 @@ import { intersperse } from '../utils/index.js'
 import { useDispatch } from 'react-redux'
 import { closeExtendedInfoDialog } from '../actions/dialogs.js'
 
-const ALink = withWidth()((props) => {
+// noSSR: withWidth otherwise renders null until mounted, so the artist line pops in and grows the row.
+const ALink = withWidth({ noSSR: true })((props) => {
   const { artist, width, ...rest } = props
   const artistLink = useGetHandleArtistClick(width)
   const dispatch = useDispatch()
diff --git a/ui/src/common/index.js b/ui/src/common/index.js
index ac8d7f62c..c88ea3e9c 100644
--- a/ui/src/common/index.js
+++ b/ui/src/common/index.js
@@ -28,6 +28,7 @@ export * from './useAlbumsPerPage'
 export * from './useGetHandleArtistClick'
 export * from './useInterval'
 export * from './useResourceRefresh'
+export * from './useScrollRestoration'
 export * from './useRefreshOnEvents'
 export * from './useToggleLove'
 export * from './useTraceUpdate'
diff --git a/ui/src/common/useScrollRestoration.jsx b/ui/src/common/useScrollRestoration.jsx
new file mode 100644
index 000000000..94e5cb2fd
--- /dev/null
+++ b/ui/src/common/useScrollRestoration.jsx
@@ -0,0 +1,64 @@
+import { useEffect, useLayoutEffect, useRef } from 'react'
+import { useHistory, useLocation } from 'react-router-dom'
+
+// Keyed on the route because hash history assigns no location.key, so every page would
+// otherwise share one slot and overwrite the offset we came back for.
+const positions = new Map()
+const MAX_ENTRIES = 50
+const MAX_FRAMES = 60
+
+export const useScrollRestoration = (ready = true) => {
+  const { pathname, search } = useLocation()
+  const history = useHistory()
+  const key = pathname + search
+  const handled = useRef(null)
+  const latest = useRef(0)
+
+  useEffect(() => {
+    latest.current = window.scrollY
+    const track = () => {
+      latest.current = window.scrollY
+    }
+    window.addEventListener('scroll', track, { passive: true })
+    return () => window.removeEventListener('scroll', track)
+  }, [key])
+
+  // Layout cleanup, so the offset is banked while this page is torn down. A passive one runs
+  // after the incoming page tops itself, and this page's listener records that 0 first.
+  useLayoutEffect(
+    () => () => {
+      positions.delete(key)
+      positions.set(key, latest.current)
+      if (positions.size > MAX_ENTRIES) {
+        positions.delete(positions.keys().next().value)
+      }
+    },
+    [key],
+  )
+
+  // Layout effect: a passive one runs after paint, so the list would be painted at the old
+  // offset first and visibly jump.
+  useLayoutEffect(() => {
+    if (!ready || handled.current === key) return
+    handled.current = key
+    const saved = positions.get(key)
+    const top = history.action === 'POP' && saved !== undefined ? saved : 0
+    window.scrollTo({ top })
+    if (!top || Math.round(window.scrollY) === top) return
+
+    // The page can still be filling in, and until it is tall enough the browser clamps us to
+    // the top. Keep asking until the offset sticks, yielding if anything else moves us.
+    let frame
+    let frames = 0
+    let landed = Math.round(window.scrollY)
+    const retry = () => {
+      const y = Math.round(window.scrollY)
+      if (y === top || y !== landed || ++frames > MAX_FRAMES) return
+      window.scrollTo({ top })
+      landed = Math.round(window.scrollY)
+      frame = requestAnimationFrame(retry)
+    }
+    frame = requestAnimationFrame(retry)
+    return () => cancelAnimationFrame(frame)
+  }, [ready, key, history.action])
+}
diff --git a/ui/src/common/useScrollRestoration.test.jsx b/ui/src/common/useScrollRestoration.test.jsx
new file mode 100644
index 000000000..7ca67a724
--- /dev/null
+++ b/ui/src/common/useScrollRestoration.test.jsx
@@ -0,0 +1,222 @@
+import { renderHook, act } from '@testing-library/react-hooks'
+import { render } from '@testing-library/react'
+import { useLayoutEffect } from 'react'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+const mockLocation = { pathname: '/album', search: '' }
+const mockHistory = { action: 'PUSH' }
+vi.mock('react-router-dom', () => ({
+  useLocation: () => mockLocation,
+  useHistory: () => mockHistory,
+}))
+
+import { useScrollRestoration } from './useScrollRestoration'
+
+describe('useScrollRestoration', () => {
+  beforeEach(() => {
+    window.scrollTo = vi.fn()
+    window.scrollY = 0
+    mockLocation.pathname = '/album'
+    mockLocation.search = ''
+    mockHistory.action = 'PUSH'
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.clearAllMocks()
+  })
+
+  const scrollTo = (y) => {
+    window.scrollY = y
+    act(() => {
+      window.dispatchEvent(new Event('scroll'))
+    })
+  }
+
+  // Returns to a page whose rows have not arrived, so scrollTo still clamps. The returned setter
+  // grows the page to the height it reaches once they do.
+  const returnToUnfilledPage = (saved) => {
+    vi.useFakeTimers()
+    let maxScroll = saved
+    window.scrollTo = vi.fn(({ top }) => {
+      window.scrollY = Math.min(top, maxScroll)
+    })
+
+    const first = renderHook(() => useScrollRestoration())
+    scrollTo(saved)
+    first.unmount()
+
+    maxScroll = 0
+    window.scrollY = 0
+    mockHistory.action = 'POP'
+    renderHook(() => useScrollRestoration())
+    return (height) => (maxScroll = height)
+  }
+
+  const advanceFrames = () => act(() => vi.advanceTimersByTime(100))
+
+  it('starts a pushed route at the top', () => {
+    renderHook(() => useScrollRestoration())
+    expect(window.scrollTo).toHaveBeenCalledWith({ top: 0 })
+  })
+
+  it('restores the saved offset when returning to an entry', () => {
+    const first = renderHook(() => useScrollRestoration())
+    scrollTo(640)
+    first.unmount()
+
+    mockLocation.pathname = '/album/al-1/show'
+    const second = renderHook(() => useScrollRestoration())
+    expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 0 })
+    second.unmount()
+
+    mockLocation.pathname = '/album'
+    mockHistory.action = 'POP'
+    renderHook(() => useScrollRestoration())
+    expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 640 })
+  })
+
+  it('tops a pushed route even if that key was seen before', () => {
+    const first = renderHook(() => useScrollRestoration())
+    scrollTo(500)
+    first.unmount()
+
+    mockHistory.action = 'PUSH'
+    renderHook(() => useScrollRestoration())
+    expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 0 })
+  })
+
+  // Restoring before the rows exist leaves the document too short: the browser clamps to the
+  // top and the offset is lost with no error.
+  it('waits for readiness before touching the scroll position', () => {
+    const { rerender } = renderHook(
+      ({ ready }) => useScrollRestoration(ready),
+      {
+        initialProps: { ready: false },
+      },
+    )
+    expect(window.scrollTo).not.toHaveBeenCalled()
+
+    rerender({ ready: true })
+    expect(window.scrollTo).toHaveBeenCalledWith({ top: 0 })
+  })
+
+  // Hash history assigns no location.key, so an implementation keyed on it would collapse every
+  // route into one slot and the detail page would erase the list's offset before we returned.
+  it('keeps a separate offset per route', () => {
+    const list = renderHook(() => useScrollRestoration())
+    scrollTo(900)
+    list.unmount()
+
+    mockLocation.pathname = '/album/al-1/show'
+    const detail = renderHook(() => useScrollRestoration())
+    scrollTo(0)
+    detail.unmount()
+
+    mockLocation.pathname = '/album'
+    mockHistory.action = 'POP'
+    renderHook(() => useScrollRestoration())
+    expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 900 })
+  })
+
+  // Without the per-instance guard this fires again when readiness flickers, fighting a user who
+  // has already started scrolling. Nothing else in the suite pins it.
+  it('does not scroll again when readiness flickers on the same route', () => {
+    const { rerender } = renderHook(
+      ({ ready }) => useScrollRestoration(ready),
+      {
+        initialProps: { ready: true },
+      },
+    )
+    expect(window.scrollTo).toHaveBeenCalledTimes(1)
+
+    rerender({ ready: false })
+    rerender({ ready: true })
+    expect(window.scrollTo).toHaveBeenCalledTimes(1)
+  })
+
+  it('scrolls once per entry, not on every re-render', () => {
+    const { rerender } = renderHook(() => useScrollRestoration())
+    rerender()
+    rerender()
+    expect(window.scrollTo).toHaveBeenCalledTimes(1)
+  })
+
+  // The artist page reports ready as soon as its header record is cached, while the albums below
+  // are still loading. A single scrollTo lands on a viewport-tall document and is clamped to 0.
+  it('keeps trying until the page is tall enough to hold the offset', () => {
+    const fillPageTo = returnToUnfilledPage(800)
+    expect(window.scrollY).toBe(0)
+
+    fillPageTo(1200)
+    advanceFrames()
+    expect(window.scrollY).toBe(800)
+  })
+
+  it('stops retrying once the user scrolls somewhere else', () => {
+    const fillPageTo = returnToUnfilledPage(800)
+
+    fillPageTo(1200)
+    window.scrollY = 300
+    advanceFrames()
+    expect(window.scrollY).toBe(300)
+  })
+
+  // A trackpad back-swipe keeps firing wheel momentum through the restore, so treating input as
+  // the yield signal cancels the gesture's own restore.
+  it('keeps restoring while wheel momentum fires, as a back-swipe does', () => {
+    const fillPageTo = returnToUnfilledPage(800)
+
+    act(() => {
+      for (let i = 0; i < 10; i++) {
+        window.dispatchEvent(
+          new WheelEvent('wheel', { deltaX: -30, deltaY: 0 }),
+        )
+      }
+    })
+    fillPageTo(1200)
+    advanceFrames()
+    expect(window.scrollY).toBe(800)
+  })
+
+  // The incoming page tops itself in its own layout effect, while this page's scroll listener is
+  // still attached. Banking the offset any later than the teardown records that 0 instead.
+  it('records the offset before the next page scrolls to the top', () => {
+    const Outgoing = () => {
+      useScrollRestoration()
+      return null
+    }
+    const Incoming = () => {
+      useLayoutEffect(() => {
+        window.scrollY = 0
+        window.dispatchEvent(new Event('scroll'))
+      }, [])
+      return null
+    }
+
+    const { rerender } = render(<Outgoing />)
+    scrollTo(1400)
+
+    mockLocation.pathname = '/album/al-1/show'
+    rerender(<Incoming />)
+
+    mockLocation.pathname = '/album'
+    mockHistory.action = 'POP'
+    renderHook(() => useScrollRestoration())
+    expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 1400 })
+  })
+
+  it('keeps saving after the restore, so leaving again remembers the new offset', () => {
+    const first = renderHook(() => useScrollRestoration())
+    scrollTo(200)
+    first.unmount()
+
+    mockHistory.action = 'POP'
+    const second = renderHook(() => useScrollRestoration())
+    expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 200 })
+    scrollTo(900)
+    second.unmount()
+
+    renderHook(() => useScrollRestoration())
+    expect(window.scrollTo).toHaveBeenLastCalledWith({ top: 900 })
+  })
+})
diff --git a/ui/src/themes/useCurrentTheme.js b/ui/src/themes/useCurrentTheme.js
index 0d986033d..2b5d13d13 100644
--- a/ui/src/themes/useCurrentTheme.js
+++ b/ui/src/themes/useCurrentTheme.js
@@ -3,10 +3,14 @@ import useMediaQuery from '@material-ui/core/useMediaQuery'
 import themes from './index'
 import { AUTO_THEME_ID } from '../consts'
 import config from '../config'
-import { useEffect } from 'react'
+import { useEffect, useMemo } from 'react'
 
 const useCurrentTheme = () => {
-  const prefersLightMode = useMediaQuery('(prefers-color-scheme: light)')
+  // Runs above the ThemeProvider carrying the prop below, so it needs its own noSsr or the
+  // auto theme renders dark first and flips.
+  const prefersLightMode = useMediaQuery('(prefers-color-scheme: light)', {
+    noSsr: true,
+  })
   const theme = useSelector((state) => {
     if (state.theme === AUTO_THEME_ID) {
       return prefersLightMode ? themes.LightTheme : themes.DarkTheme
@@ -50,7 +54,15 @@ const useCurrentTheme = () => {
     document.body.style.backgroundColor = bgColor
   }, [theme])
 
-  return theme
+  // We never server-render, so let media queries resolve on the first render: the default
+  // defers them to an effect, which makes every mount paint the wrong breakpoint and reflow.
+  return useMemo(
+    () => ({
+      ...theme,
+      props: { ...theme.props, MuiUseMediaQuery: { noSsr: true } },
+    }),
+    [theme],
+  )
 }
 
 export default useCurrentTheme

From d764a1e9d77d255a79a13eac1ef039957051252c Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Thu, 6 Aug 2026 00:40:58 -0400
Subject: [PATCH 014/200] fix(log): change debug log level to trace to reduce
 log noise from cron

Signed-off-by: Deluan <deluan@navidrome.org>
---
 scheduler/log_adapter.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scheduler/log_adapter.go b/scheduler/log_adapter.go
index 057818785..f7089f97c 100644
--- a/scheduler/log_adapter.go
+++ b/scheduler/log_adapter.go
@@ -11,7 +11,7 @@ func (l *logger) Info(msg string, keysAndValues ...any) {
 		"Scheduler: " + msg,
 	}
 	args = append(args, keysAndValues...)
-	log.Debug(args...)
+	log.Trace(args...)
 }
 
 func (l *logger) Error(err error, msg string, keysAndValues ...any) {

From dce48ff650f0f7ba30d7f4113fc443751d4c93ac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 6 Aug 2026 10:59:50 -0400
Subject: [PATCH 015/200] feat(smartplaylist): add album-level fields for
 sorting and filtering (#5899)

Smart playlists could only sort by the track-level `dateadded`, which scatters
an album's tracks because every track has its own timestamp. There was no way
to express "newest albums first, tracks in album order".

Adds five fields backed by the album table: albumdateadded, albumdatemodified,
albumduration, albumsongcount and albumsize, so `"sort": "-albumdateadded,
tracknumber"` now works. They filter as well as sort, which also enables rules
like "everything from albums added this month" or "skip singles and EPs".

These need the album table rather than the album_annotation table the existing
album* fields join, so they get their own bit in the join mask. The bitmask
already unions joins from both the expression and the sort fields, so a
sort-only reference pulls in the join for the main query while correctly
staying out of the percentage-limit count query.

No COALESCE default is used. That mechanism exists because an album_annotation
row is genuinely often absent; the album row always exists and song_count,
duration and size are NOT NULL, so leaving the columns bare keeps filters
index-friendly.

albumdatemodified follows the existing track-level `datemodified` naming rather
than the `albumdateupdated` spelling used in the request.

albumreleasedate was considered and rejected: album.release_date is
allOrNothing() over the tracks, so it equals the track-level releasedate when
they agree and collapses to empty when they disagree.

Closes https://github.com/navidrome/navidrome/discussions/5347
---
 model/criteria/fields.go                      |  5 ++
 persistence/criteria_sql.go                   |  6 +++
 persistence/criteria_sql_test.go              | 48 +++++++++++++++++++
 persistence/e2e/smartplaylist_test.go         | 37 ++++++++++++++
 persistence/smart_playlist_repository.go      | 14 +++---
 persistence/smart_playlist_repository_test.go | 35 ++++++++++++++
 6 files changed, 139 insertions(+), 6 deletions(-)

diff --git a/model/criteria/fields.go b/model/criteria/fields.go
index 5c9ec898d..a9a634c01 100644
--- a/model/criteria/fields.go
+++ b/model/criteria/fields.go
@@ -71,6 +71,11 @@ var fieldMap = map[string]FieldInfo{
 	"albumlastplayed":      {},
 	"albumdateloved":       {},
 	"albumdaterated":       {},
+	"albumdateadded":       {},
+	"albumdatemodified":    {},
+	"albumduration":        {},
+	"albumsongcount":       {},
+	"albumsize":            {},
 	"artistrating":         {},
 	"artistloved":          {Boolean: true},
 	"artistplaycount":      {},
diff --git a/persistence/criteria_sql.go b/persistence/criteria_sql.go
index 43cab4fdd..70f9a1fb5 100644
--- a/persistence/criteria_sql.go
+++ b/persistence/criteria_sql.go
@@ -21,6 +21,7 @@ const (
 	smartPlaylistJoinNone            smartPlaylistJoinType = 0
 	smartPlaylistJoinAlbumAnnotation smartPlaylistJoinType = 1 << iota
 	smartPlaylistJoinArtistAnnotation
+	smartPlaylistJoinAlbum
 )
 
 func (j smartPlaylistJoinType) has(other smartPlaylistJoinType) bool {
@@ -103,6 +104,11 @@ var smartPlaylistFields = map[string]smartPlaylistField{
 	"albumlastplayed":      {expr: "album_annotation.play_date", joinType: smartPlaylistJoinAlbumAnnotation},
 	"albumdateloved":       {expr: "album_annotation.starred_at", joinType: smartPlaylistJoinAlbumAnnotation},
 	"albumdaterated":       {expr: "album_annotation.rated_at", joinType: smartPlaylistJoinAlbumAnnotation},
+	"albumdateadded":       {expr: "album.created_at", joinType: smartPlaylistJoinAlbum},
+	"albumdatemodified":    {expr: "album.updated_at", joinType: smartPlaylistJoinAlbum},
+	"albumduration":        {expr: "album.duration", joinType: smartPlaylistJoinAlbum},
+	"albumsongcount":       {expr: "album.song_count", joinType: smartPlaylistJoinAlbum},
+	"albumsize":            {expr: "album.size", joinType: smartPlaylistJoinAlbum},
 	"artistrating":         {expr: "artist_annotation.rating", coalesceDefault: 0, joinType: smartPlaylistJoinArtistAnnotation},
 	"artistloved":          {expr: "artist_annotation.starred", coalesceDefault: false, joinType: smartPlaylistJoinArtistAnnotation},
 	"artistplaycount":      {expr: "artist_annotation.play_count", coalesceDefault: 0, joinType: smartPlaylistJoinArtistAnnotation},
diff --git a/persistence/criteria_sql_test.go b/persistence/criteria_sql_test.go
index 59bdc4452..0cd7187c5 100644
--- a/persistence/criteria_sql_test.go
+++ b/persistence/criteria_sql_test.go
@@ -51,6 +51,11 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 		Entry("not in playlist", criteria.NotInPlaylist{"id": "deadbeef-dead-beef"}, "media_file.id NOT IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND playlist.public = ?))", "deadbeef-dead-beef", 1),
 		Entry("album annotation", criteria.Gt{"albumRating": 3}, "album_annotation.rating > ?", 3),
 		Entry("artist annotation", criteria.Is{"artistLoved": true}, "artist_annotation.starred = ?", true),
+		Entry("album column", criteria.Gt{"albumSongCount": 5}, "album.song_count > ?", 5),
+		Entry("album duration column", criteria.Lt{"albumDuration": 600}, "album.duration < ?", 600),
+		Entry("album size column", criteria.Gt{"albumSize": 1000}, "album.size > ?", 1000),
+		Entry("album date column", criteria.After{"albumDateAdded": time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)}, "album.created_at > ?", time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)),
+		Entry("album modified column", criteria.Before{"albumDateModified": time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)}, "album.updated_at < ?", time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)),
 		// Annotation fields use a COALESCE default (0 for numeric, false for bool) so that tracks
 		// with no annotation row behave as that default. To keep the annotation index usable, the
 		// COALESCE is dropped when the compared value cannot match the default (the missing-row
@@ -298,6 +303,11 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "random"}).OrderBy()).To(Equal("random() asc"))
 		})
 
+		It("sorts by album columns bare, with no COALESCE default", func() {
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "-albumDateAdded,trackNumber"}).OrderBy()).
+				To(Equal("album.created_at desc, media_file.track_number asc"))
+		})
+
 		It("sorts by multiple fields", func() {
 			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "title,-rating"}).OrderBy()).To(Equal("media_file.title asc, COALESCE(annotation.rating, 0) desc"))
 		})
@@ -323,6 +333,28 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 		}
 	})
 
+	It("declares a joinType matching the table each field selects from", func() {
+		// Omitting the joinType still compiles, so without this the field would only fail at
+		// refresh time with "no such column".
+		joinByTable := map[string]smartPlaylistJoinType{
+			"media_file":        smartPlaylistJoinNone,
+			"annotation":        smartPlaylistJoinNone,
+			"album":             smartPlaylistJoinAlbum,
+			"album_annotation":  smartPlaylistJoinAlbumAnnotation,
+			"artist_annotation": smartPlaylistJoinArtistAnnotation,
+		}
+		for name, field := range smartPlaylistFields {
+			if field.expr == "" {
+				continue
+			}
+			table, _, ok := strings.Cut(field.expr, ".")
+			Expect(ok).To(BeTrue(), "field %q has expr %q with no table prefix", name, field.expr)
+			want, known := joinByTable[table]
+			Expect(known).To(BeTrue(), "field %q selects from unknown table %q", name, table)
+			Expect(field.joinType).To(Equal(want), "field %q selects from %q but declares the wrong joinType", name, table)
+		}
+	})
+
 	Describe("JSON condition merging", func() {
 		It("merges multiple role conditions in an OR group into a single EXISTS", func() {
 			expr := criteria.Any{
@@ -585,5 +617,21 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 
 			Expect(newSmartPlaylistCriteria(c).RequiredJoins().has(smartPlaylistJoinArtistAnnotation)).To(BeTrue())
 		})
+
+		It("keeps a sort-only album join out of the expression joins", func() {
+			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "love"}}, Sort: "-albumDateAdded"}
+			cSQL := newSmartPlaylistCriteria(c)
+
+			Expect(cSQL.ExpressionJoins()).To(Equal(smartPlaylistJoinNone))
+			Expect(cSQL.RequiredJoins().has(smartPlaylistJoinAlbum)).To(BeTrue())
+		})
+
+		It("distinguishes the album join from the album annotation join", func() {
+			c := criteria.Criteria{Expression: criteria.All{criteria.Gt{"albumRating": 3}}}
+			joins := newSmartPlaylistCriteria(c).RequiredJoins()
+
+			Expect(joins.has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
+			Expect(joins.has(smartPlaylistJoinAlbum)).To(BeFalse())
+		})
 	})
 })
diff --git a/persistence/e2e/smartplaylist_test.go b/persistence/e2e/smartplaylist_test.go
index 4966d3b8a..b96605d09 100644
--- a/persistence/e2e/smartplaylist_test.go
+++ b/persistence/e2e/smartplaylist_test.go
@@ -204,6 +204,43 @@ var _ = Describe("Smart Playlists", func() {
 		})
 	})
 
+	Describe("Album aggregate fields", func() {
+		// Abbey Road and IV have two tracks each; the other four albums have one.
+		It("matches albums with more than one track", func() {
+			results := evaluateRule(`{"all":[{"gt":{"albumsongcount":1}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "Stairway To Heaven", "Black Dog"))
+		})
+
+		It("matches single-track albums", func() {
+			results := evaluateRule(`{"all":[{"is":{"albumsongcount":1}}]}`)
+			Expect(results).To(ConsistOf("So What", "Bohemian Rhapsody", "All Along the Watchtower",
+				"We Are the Champions"))
+		})
+
+		It("matches albumDateAdded inTheLast 1 day", func() {
+			results := evaluateRule(`{"all":[{"inTheLast":{"albumdateadded":1}}]}`)
+			Expect(results).To(ConsistOf("Come Together", "Something", "Stairway To Heaven", "Black Dog",
+				"So What", "Bohemian Rhapsody", "All Along the Watchtower", "We Are the Champions"))
+		})
+
+		It("matches albumDateModified before a far-future date", func() {
+			results := evaluateRule(`{"all":[{"before":{"albumdatemodified":"2099-01-01"}}]}`)
+			Expect(results).To(HaveLen(8))
+		})
+
+		// Fixture durations are randomized, so only the aggregate being populated can be asserted.
+		It("resolves albumDuration and albumSize to non-zero aggregates", func() {
+			Expect(evaluateRule(`{"all":[{"gt":{"albumduration":0}}]}`)).To(HaveLen(8))
+			Expect(evaluateRule(`{"all":[{"gt":{"albumsize":0}}]}`)).To(HaveLen(8))
+		})
+
+		It("groups by album date and orders within the album (issue #5347)", func() {
+			results := evaluateRuleOrdered(
+				`{"all":[{"is":{"album":"Abbey Road"}}],"sort":"-albumdateadded,tracknumber"}`)
+			Expect(results).To(Equal([]string{"Come Together", "Something"}))
+		})
+	})
+
 	Describe("Logic operators", func() {
 		It("matches with ALL (AND)", func() {
 			results := evaluateRule(`{"all":[{"is":{"genre":"Blues"}},{"gt":{"bpm":130}}]}`)
diff --git a/persistence/smart_playlist_repository.go b/persistence/smart_playlist_repository.go
index f7c41597d..5f84981b3 100644
--- a/persistence/smart_playlist_repository.go
+++ b/persistence/smart_playlist_repository.go
@@ -122,7 +122,7 @@ func (r *playlistRepository) resolvePercentageLimit(pls *model.Playlist, rulesSQ
 	exprJoins := rulesSQL.ExpressionJoins()
 	countSq := Select("count(*) as count").From("media_file")
 	countSq = r.addMediaFileAnnotationJoin(countSq, userID)
-	countSq = r.addSmartPlaylistAnnotationJoins(countSq, exprJoins, userID)
+	countSq = r.addSmartPlaylistJoins(countSq, exprJoins, userID)
 	countSq = r.applyLibraryFilter(countSq, "media_file")
 
 	cond, err := rulesSQL.Where()
@@ -144,7 +144,7 @@ func (r *playlistRepository) resolvePercentageLimit(pls *model.Playlist, rulesSQ
 }
 
 // buildSmartPlaylistQuery constructs the SQL query to select media files matching the smart playlist criteria,
-// including necessary joins for annotations and library filtering.
+// including the joins its fields require and library filtering.
 func (r *playlistRepository) buildSmartPlaylistQuery(pls *model.Playlist, rulesSQL smartPlaylistCriteria, userID string) SelectBuilder {
 	orderBy := rulesSQL.OrderBy()
 	sq := Select("row_number() over (order by "+orderBy+") as id", "'"+pls.ID+"' as playlist_id", "media_file.id as media_file_id").
@@ -152,7 +152,7 @@ func (r *playlistRepository) buildSmartPlaylistQuery(pls *model.Playlist, rulesS
 	sq = r.addMediaFileAnnotationJoin(sq, userID)
 
 	requiredJoins := rulesSQL.RequiredJoins()
-	sq = r.addSmartPlaylistAnnotationJoins(sq, requiredJoins, userID)
+	sq = r.addSmartPlaylistJoins(sq, requiredJoins, userID)
 	sq = r.applyLibraryFilter(sq, "media_file")
 	return sq
 }
@@ -166,9 +166,8 @@ func (r *playlistRepository) addMediaFileAnnotationJoin(sq SelectBuilder, userID
 		" AND annotation.user_id = ?)", userID)
 }
 
-// addSmartPlaylistAnnotationJoins adds left joins to the annotation table for albums and artists as needed based on
-// the smart playlist criteria, filtering by user ID to include user-specific annotations in the evaluation.
-func (r *playlistRepository) addSmartPlaylistAnnotationJoins(sq SelectBuilder, joins smartPlaylistJoinType, userID string) SelectBuilder {
+// addSmartPlaylistJoins adds the left joins required by the criteria's fields.
+func (r *playlistRepository) addSmartPlaylistJoins(sq SelectBuilder, joins smartPlaylistJoinType, userID string) SelectBuilder {
 	if joins.has(smartPlaylistJoinAlbumAnnotation) {
 		sq = sq.LeftJoin("annotation AS album_annotation ON ("+
 			"album_annotation.item_id = media_file.album_id"+
@@ -181,6 +180,9 @@ func (r *playlistRepository) addSmartPlaylistAnnotationJoins(sq SelectBuilder, j
 			" AND artist_annotation.item_type = 'artist'"+
 			" AND artist_annotation.user_id = ?)", userID)
 	}
+	if joins.has(smartPlaylistJoinAlbum) {
+		sq = sq.LeftJoin("album ON album.id = media_file.album_id")
+	}
 	return sq
 }
 
diff --git a/persistence/smart_playlist_repository_test.go b/persistence/smart_playlist_repository_test.go
index 8e3ae488f..e62436890 100644
--- a/persistence/smart_playlist_repository_test.go
+++ b/persistence/smart_playlist_repository_test.go
@@ -9,6 +9,7 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/pocketbase/dbx"
@@ -392,6 +393,40 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 		})
 	})
 
+	Describe("Smart Playlists with Album Aggregate Criteria", func() {
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+		})
+
+		trackIDsOf := func(rules *criteria.Criteria) []string {
+			newPls := model.Playlist{Name: "Album Aggregates", OwnerID: "userid", Rules: rules}
+			Expect(repo.Put(&newPls)).To(Succeed())
+			DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+
+			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+			return slice.Map(pls.Tracks, func(t model.PlaylistTrack) string { return t.MediaFileID })
+		}
+
+		It("filters on albumSongCount", func() {
+			// albumMultiDisc (ID "104") is the only fixture album with SongCount > 3
+			rules := &criteria.Criteria{Expression: criteria.All{criteria.Gt{"albumSongCount": 3}}}
+
+			Expect(trackIDsOf(rules)).To(ConsistOf("2001", "2002", "2003", "2004"))
+		})
+
+		It("sorts by an album field not referenced in the expression (issue #5347)", func() {
+			// All four tracks share album 104, so the album date ties and disc/track number decide.
+			rules := &criteria.Criteria{
+				Expression: criteria.All{criteria.Is{"album": "Multi Disc Album"}},
+				Sort:       "-albumDateAdded,discNumber,trackNumber",
+			}
+
+			Expect(trackIDsOf(rules)).To(HaveExactElements("2002", "2004", "2003", "2001"))
+		})
+	})
+
 	Describe("Smart Playlists with Tag Criteria", func() {
 		var mfRepo model.MediaFileRepository
 		var testPlaylistID string

From 0f4c9b82121f870e5c925657458a9b87912f59ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 7 Aug 2026 09:36:52 -0400
Subject: [PATCH 016/200] fix(ui): don't start playback when closing the disc
 cover lightbox (#5901)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Lightbox renders through a React portal (react-modal), and React
propagates synthetic events up the React tree rather than the DOM tree, so
clicking its close button or backdrop bubbled into the ancestor TableRow and
triggered playSubset.

The existing timestamp guard could not catch this: react-image-lightbox defers
onCloseRequest by animationDuration via setTimeout, so lightboxClosedAt was
only stamped 200ms after the click had already propagated. The guard is kept
because it still covers the separate mobile ghost-click path, where the
synthesized click lands on the row after the overlay unmounts.

Stopping propagation in onCloseRequest — the approach used by ContextMenus,
whose MUI onClose fires synchronously — does not work for the same reason.
Instead, wrap the Lightbox in an element that stops propagation at the React
tree boundary the portal bubbles through, which also covers the lightbox
controls we don't own (zoom buttons, caption, image drag).
---
 ui/src/common/SongDatagrid.jsx      | 20 ++++----
 ui/src/common/SongDatagrid.test.jsx | 74 +++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+), 8 deletions(-)
 create mode 100644 ui/src/common/SongDatagrid.test.jsx

diff --git a/ui/src/common/SongDatagrid.jsx b/ui/src/common/SongDatagrid.jsx
index d2c98bbe7..4a813f84d 100644
--- a/ui/src/common/SongDatagrid.jsx
+++ b/ui/src/common/SongDatagrid.jsx
@@ -78,7 +78,7 @@ const useStyles = makeStyles({
   },
 })
 
-const DiscSubtitleRow = forwardRef(
+export const DiscSubtitleRow = forwardRef(
   ({ record, onClick, colSpan, contextAlwaysVisible }, ref) => {
     const translate = useTranslate()
     const isDesktop = useMediaQuery((theme) => theme.breakpoints.up('md'))
@@ -153,13 +153,17 @@ const DiscSubtitleRow = forwardRef(
             {subtitle}
           </Typography>
           {isLightboxOpen && !imageError && (
-            <Lightbox
-              imagePadding={50}
-              animationDuration={200}
-              imageTitle={record.album + ' - ' + subtitle}
-              mainSrc={fullImageUrl}
-              onCloseRequest={handleCloseLightbox}
-            />
+            // Lightbox portals out of the row, but React still bubbles its
+            // events up this tree, where the row's onClick would play the disc.
+            <span onClick={(e) => e.stopPropagation()}>
+              <Lightbox
+                imagePadding={50}
+                animationDuration={200}
+                imageTitle={record.album + ' - ' + subtitle}
+                mainSrc={fullImageUrl}
+                onCloseRequest={handleCloseLightbox}
+              />
+            </span>
           )}
         </TableCell>
         <TableCell>
diff --git a/ui/src/common/SongDatagrid.test.jsx b/ui/src/common/SongDatagrid.test.jsx
new file mode 100644
index 000000000..f8459d8eb
--- /dev/null
+++ b/ui/src/common/SongDatagrid.test.jsx
@@ -0,0 +1,74 @@
+import React from 'react'
+import { render, fireEvent, screen } from '@testing-library/react'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { createTheme, ThemeProvider } from '@material-ui/core/styles'
+import { DiscSubtitleRow } from './SongDatagrid'
+
+vi.mock('../subsonic', () => ({
+  default: { getDiscCoverArtUrl: () => 'http://localhost/cover.jpg' },
+}))
+
+vi.mock('react-redux', () => ({ useDispatch: () => vi.fn() }))
+
+vi.mock('../common', () => ({ AlbumContextMenu: () => null }))
+
+vi.mock('react-dnd', () => ({ useDrag: () => [{}, vi.fn()] }))
+
+const record = {
+  id: 'song-1',
+  albumId: 'album-1',
+  album: 'The Album',
+  discNumber: 2,
+  discSubtitle: 'Bonus Disc',
+  updatedAt: '2024-01-01',
+}
+
+const renderRow = (onClick) =>
+  render(
+    <ThemeProvider theme={createTheme()}>
+      <table>
+        <tbody>
+          <DiscSubtitleRow record={record} onClick={onClick} colSpan={3} />
+        </tbody>
+      </table>
+    </ThemeProvider>,
+  )
+
+const openLightbox = () => {
+  fireEvent.click(document.querySelector('img'))
+  expect(document.querySelector('.ril__closeButton')).toBeTruthy()
+}
+
+describe('DiscSubtitleRow', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('plays the disc when the row is clicked', () => {
+    const onClick = vi.fn()
+    renderRow(onClick)
+    fireEvent.click(screen.getByText('Bonus Disc'))
+    expect(onClick).toHaveBeenCalledWith(2)
+  })
+
+  it('does not play the disc when opening the lightbox', () => {
+    const onClick = vi.fn()
+    renderRow(onClick)
+    openLightbox()
+    expect(onClick).not.toHaveBeenCalled()
+  })
+
+  it('does not play the disc when closing the lightbox', () => {
+    const onClick = vi.fn()
+    renderRow(onClick)
+    openLightbox()
+    fireEvent.click(document.querySelector('.ril__closeButton'))
+    expect(onClick).not.toHaveBeenCalled()
+  })
+
+  it('does not play the disc when clicking the lightbox backdrop', () => {
+    const onClick = vi.fn()
+    renderRow(onClick)
+    openLightbox()
+    fireEvent.click(document.querySelector('.ril__inner'))
+    expect(onClick).not.toHaveBeenCalled()
+  })
+})

From a0bf78cdeab4d0f316edcd37094f03d09f0ede8e Mon Sep 17 00:00:00 2001
From: ant <marxguey@proton.me>
Date: Sat, 8 Aug 2026 12:40:05 -0700
Subject: [PATCH 017/200] fix(contrib): added missing hyphen in OpenRC script
 that caused crashes on startup (#5906)

Signed-off-by: Ant <marxguey@proton.me>
---
 contrib/navidrome | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contrib/navidrome b/contrib/navidrome
index bb6908797..8ab5afe2e 100644
--- a/contrib/navidrome
+++ b/contrib/navidrome
@@ -2,7 +2,7 @@
   
 name=$RC_SVCNAME
 command="/opt/navidrome/${RC_SVCNAME}"
-command_args="-datafolder /opt/navidrome"
+command_args="--datafolder /opt/navidrome"
 command_user="${RC_SVCNAME}"
 pidfile="/var/run/${RC_SVCNAME}.pid"
 output_log="/opt/navidrome/${RC_SVCNAME}.log"

From 5a5311a9c0ac0147fb49ed990f4cbb4f6c7ac0a6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 8 Aug 2026 21:57:44 -0400
Subject: [PATCH 018/200] fix(plugins): make generated mock stubs nil-safe for
 nilable returns (#5909)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ndpgen mock accessors asserted return types unconditionally, so a plugin
test using Return(nil, ...) — the natural way to model an empty result or a
pagination terminal page — panicked on the untyped-nil type assertion instead
of returning the zero value. Guard pointer, slice, map and any returns in both
the host-service client stubs and the PDK stub, and regenerate.
---
 plugins/cmd/ndpgen/internal/generator.go      | 62 ++++++++----
 plugins/cmd/ndpgen/internal/generator_test.go | 96 ++++++++++++++++++-
 .../internal/templates/client_stub.go.tmpl    |  2 +-
 .../internal/templates/pdk_stub.go.tmpl       |  2 +-
 plugins/pdk/go/host/mock_nil_returns_test.go  | 27 ++++++
 plugins/pdk/go/host/nd_host_cache_stub.go     |  6 +-
 plugins/pdk/go/host/nd_host_config_stub.go    |  6 +-
 plugins/pdk/go/host/nd_host_http_stub.go      |  6 +-
 plugins/pdk/go/host/nd_host_kvstore_stub.go   | 18 +++-
 plugins/pdk/go/host/nd_host_library_stub.go   | 12 ++-
 plugins/pdk/go/host/nd_host_matcher_stub.go   |  6 +-
 .../pdk/go/host/nd_host_subsonicapi_stub.go   |  6 +-
 plugins/pdk/go/host/nd_host_task_stub.go      |  6 +-
 plugins/pdk/go/host/nd_host_users_stub.go     | 12 ++-
 plugins/pdk/go/pdk/pdk_stub.go                | 24 ++++-
 15 files changed, 250 insertions(+), 41 deletions(-)
 create mode 100644 plugins/pdk/go/host/mock_nil_returns_test.go

diff --git a/plugins/cmd/ndpgen/internal/generator.go b/plugins/cmd/ndpgen/internal/generator.go
index 50f53cd37..bfc1b7c4e 100644
--- a/plugins/cmd/ndpgen/internal/generator.go
+++ b/plugins/cmd/ndpgen/internal/generator.go
@@ -27,32 +27,46 @@ func hostFuncMap(svc Service) template.FuncMap {
 // Uses private (lowercase) type names for request/response structs.
 func clientFuncMap(svc Service) template.FuncMap {
 	return template.FuncMap{
-		"lower":            strings.ToLower,
-		"title":            strings.Title,
-		"exportName":       func(m Method) string { return m.FunctionName(svc.ExportPrefix()) },
-		"requestType":      func(m Method) string { return m.ClientRequestTypeName(svc.Name) },
-		"responseType":     func(m Method) string { return m.ClientResponseTypeName(svc.Name) },
-		"formatDoc":        formatDoc,
-		"mockReturnValues": mockReturnValues,
+		"lower":          strings.ToLower,
+		"title":          strings.Title,
+		"exportName":     func(m Method) string { return m.FunctionName(svc.ExportPrefix()) },
+		"requestType":    func(m Method) string { return m.ClientRequestTypeName(svc.Name) },
+		"responseType":   func(m Method) string { return m.ClientResponseTypeName(svc.Name) },
+		"formatDoc":      formatDoc,
+		"mockReturnBody": mockReturnBody,
 	}
 }
 
-// mockReturnValues generates the testify mock return value accessors for a method.
-// For example: args.String(0), args.Bool(1), args.Error(2)
-func mockReturnValues(m Method) string {
+// mockReturnBody generates the testify mock body lines that extract return values.
+// Nil-able returns are guarded so tests can use Return(nil, ...) without the
+// type-assertion panic testify produces on an untyped nil.
+func mockReturnBody(m Method) string {
+	var b strings.Builder
 	var parts []string
-	idx := 0
 
-	for _, r := range m.Returns {
-		parts = append(parts, mockAccessor(r.Type, idx))
-		idx++
+	for idx, r := range m.Returns {
+		if isNilableType(r.Type) {
+			name := fmt.Sprintf("r%d", idx)
+			fmt.Fprintf(&b, "\tvar %s %s\n\tif v := args.Get(%d); v != nil {\n\t\t%s = v.(%s)\n\t}\n", name, r.Type, idx, name, r.Type)
+			parts = append(parts, name)
+		} else {
+			parts = append(parts, mockAccessor(r.Type, idx))
+		}
 	}
 
 	if m.HasError {
-		parts = append(parts, fmt.Sprintf("args.Error(%d)", idx))
+		parts = append(parts, fmt.Sprintf("args.Error(%d)", len(m.Returns)))
 	}
 
-	return strings.Join(parts, ", ")
+	b.WriteString("\treturn " + strings.Join(parts, ", "))
+	return b.String()
+}
+
+// isNilableType reports whether a nil mock return value is a valid intent for the
+// type, rather than a malformed test expectation.
+func isNilableType(typ string) bool {
+	return strings.HasPrefix(typ, "*") || strings.HasPrefix(typ, "[]") ||
+		strings.HasPrefix(typ, "map[") || typ == "any" || typ == "interface{}"
 }
 
 // mockAccessor returns the testify mock accessor call for a given type and index.
@@ -725,7 +739,7 @@ func pdkFuncMap() template.FuncMap {
 		"returnList":          pdkReturnList,
 		"argList":             pdkArgList,
 		"argListWithReceiver": pdkArgListWithReceiver,
-		"mockReturns":         pdkMockReturns,
+		"mockReturnBody":      pdkMockReturnBody,
 		"constValue":          pdkConstValue,
 		"stubTypeUnderlying":  stubTypeUnderlying,
 		"methodReceiver":      pdkMethodReceiver,
@@ -834,12 +848,20 @@ func pdkMethodReceiver(receiver, typeName string) string {
 }
 
 // pdkMockReturns generates the mock return accessors for a function.
-func pdkMockReturns(returns []PDKReturn) string {
+func pdkMockReturnBody(returns []PDKReturn) string {
+	var b strings.Builder
 	var parts []string
 	for i, r := range returns {
-		parts = append(parts, mockAccessorForType(r.Type, i))
+		if isNilableType(r.Type) {
+			name := fmt.Sprintf("r%d", i)
+			fmt.Fprintf(&b, "\tvar %s %s\n\tif v := args.Get(%d); v != nil {\n\t\t%s = v.(%s)\n\t}\n", name, r.Type, i, name, r.Type)
+			parts = append(parts, name)
+		} else {
+			parts = append(parts, mockAccessorForType(r.Type, i))
+		}
 	}
-	return strings.Join(parts, ", ")
+	b.WriteString("\treturn " + strings.Join(parts, ", "))
+	return b.String()
 }
 
 // mockAccessorForType returns the testify mock accessor for a type.
diff --git a/plugins/cmd/ndpgen/internal/generator_test.go b/plugins/cmd/ndpgen/internal/generator_test.go
index 15b97e1ae..ea94c7fc6 100644
--- a/plugins/cmd/ndpgen/internal/generator_test.go
+++ b/plugins/cmd/ndpgen/internal/generator_test.go
@@ -748,8 +748,9 @@ var _ = Describe("Generator", func() {
 			// Check bool return uses args.Bool(1)
 			Expect(codeStr).To(ContainSubstring("args.Bool(1)"))
 
-			// Check []byte return uses args.Get(0).([]byte)
-			Expect(codeStr).To(ContainSubstring("args.Get(0).([]byte)"))
+			// []byte is nil-able, so it gets a guarded extraction
+			Expect(codeStr).To(ContainSubstring("var r0 []byte"))
+			Expect(codeStr).To(ContainSubstring("r0 = v.([]byte)"))
 
 			// Check error returns use args.Error(N)
 			Expect(codeStr).To(ContainSubstring("args.Error("))
@@ -1699,6 +1700,97 @@ var _ = Describe("Rust Generation", func() {
 			Expect(codeStr).NotTo(ContainSubstring("use base64"))
 		})
 	})
+
+	Describe("nil-safe mock accessors", func() {
+		Describe("GenerateClientGoStub", func() {
+			It("guards pointer, slice and map returns so Return(nil, ...) does not panic", func() {
+				svc := Service{
+					Name:      "Paged",
+					Interface: "PagedService",
+					Methods: []Method{
+						{
+							Name:     "GetPage",
+							HasError: true,
+							Params:   []Param{NewParam("query", "string")},
+							Returns:  []Param{NewParam("items", "[]Item"), NewParam("next", "*PageOptions")},
+						},
+						{
+							Name:     "GetLabels",
+							HasError: true,
+							Params:   []Param{NewParam("id", "string")},
+							Returns:  []Param{NewParam("labels", "map[string]string")},
+						},
+					},
+				}
+
+				code, err := GenerateClientGoStub(svc, "host")
+				Expect(err).NotTo(HaveOccurred())
+				_, err = format.Source(code)
+				Expect(err).NotTo(HaveOccurred())
+
+				codeStr := string(code)
+				Expect(codeStr).To(ContainSubstring("var r0 []Item"))
+				Expect(codeStr).To(ContainSubstring("var r1 *PageOptions"))
+				Expect(codeStr).To(ContainSubstring("if v := args.Get(1); v != nil {"))
+				Expect(codeStr).To(ContainSubstring("r1 = v.(*PageOptions)"))
+				Expect(codeStr).To(ContainSubstring("return r0, r1, args.Error(2)"))
+				Expect(codeStr).To(ContainSubstring("var r0 map[string]string"))
+				Expect(codeStr).NotTo(ContainSubstring("args.Get(0).([]Item)"))
+				Expect(codeStr).NotTo(ContainSubstring("args.Get(1).(*PageOptions)"))
+			})
+
+			It("keeps non-nilable returns as inline accessors", func() {
+				svc := Service{
+					Name:      "Counter",
+					Interface: "CounterService",
+					Methods: []Method{
+						{
+							Name:     "Count",
+							HasError: true,
+							Params:   []Param{NewParam("id", "string")},
+							Returns:  []Param{NewParam("count", "int64"), NewParam("name", "string")},
+						},
+					},
+				}
+
+				code, err := GenerateClientGoStub(svc, "host")
+				Expect(err).NotTo(HaveOccurred())
+
+				codeStr := string(code)
+				Expect(codeStr).To(ContainSubstring("return args.Get(0).(int64), args.String(1), args.Error(2)"))
+				Expect(codeStr).NotTo(ContainSubstring("var r0"))
+			})
+		})
+
+		Describe("GeneratePDKGoStub", func() {
+			It("guards pointer and slice returns", func() {
+				symbols := &PDKSymbols{
+					Functions: []PDKFunc{
+						{
+							Name:    "NewHTTPRequest",
+							Params:  []PDKParam{{Name: "method", Type: "HTTPMethod"}, {Name: "url", Type: "string"}},
+							Returns: []PDKReturn{{Type: "*HTTPRequest"}},
+						},
+						{
+							Name:    "Input",
+							Returns: []PDKReturn{{Type: "[]byte"}},
+						},
+					},
+				}
+
+				code, err := GeneratePDKGoStub(symbols)
+				Expect(err).NotTo(HaveOccurred())
+				_, err = format.Source(code)
+				Expect(err).NotTo(HaveOccurred())
+
+				codeStr := string(code)
+				Expect(codeStr).To(ContainSubstring("var r0 *HTTPRequest"))
+				Expect(codeStr).To(ContainSubstring("r0 = v.(*HTTPRequest)"))
+				Expect(codeStr).To(ContainSubstring("var r0 []byte"))
+				Expect(codeStr).NotTo(ContainSubstring("return args.Get(0).(*HTTPRequest)"))
+			})
+		})
+	})
 })
 
 func writeFile(path, content string) error {
diff --git a/plugins/cmd/ndpgen/internal/templates/client_stub.go.tmpl b/plugins/cmd/ndpgen/internal/templates/client_stub.go.tmpl
index d2a8f3f27..eb5e9f844 100644
--- a/plugins/cmd/ndpgen/internal/templates/client_stub.go.tmpl
+++ b/plugins/cmd/ndpgen/internal/templates/client_stub.go.tmpl
@@ -51,7 +51,7 @@ var {{.Service.Name}}Mock = &mock{{.Service.Name}}Service{}
 // {{.Name}} is the mock method for {{$.Service.Name}}{{.Name}}.
 func (m *mock{{$.Service.Name}}Service) {{.Name}}({{range $i, $p := .Params}}{{if $i}}, {{end}}{{$p.Name}} {{$p.Type}}{{end}}) {{.ReturnSignature}} {
 	args := m.Called({{range $i, $p := .Params}}{{if $i}}, {{end}}{{$p.Name}}{{end}})
-	return {{mockReturnValues .}}
+{{mockReturnBody .}}
 }
 
 // {{$.Service.Name}}{{.Name}} delegates to the mock instance.
diff --git a/plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl b/plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl
index 6a57a6469..2bd73f107 100644
--- a/plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl
+++ b/plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl
@@ -34,7 +34,7 @@ func ResetMock() {
 func {{.Name}}({{paramList .Params}}){{returnList .Returns}} {
 {{- if .Returns}}
 	args := PDKMock.Called({{argList .Params}})
-	return {{mockReturns .Returns}}
+{{mockReturnBody .Returns}}
 {{- else}}
 	PDKMock.Called({{argList .Params}})
 {{- end}}
diff --git a/plugins/pdk/go/host/mock_nil_returns_test.go b/plugins/pdk/go/host/mock_nil_returns_test.go
new file mode 100644
index 000000000..ea5f334f1
--- /dev/null
+++ b/plugins/pdk/go/host/mock_nil_returns_test.go
@@ -0,0 +1,27 @@
+//go:build !wasip1
+
+package host
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// Return(nil, ...) models "no result"; the generated accessors must yield the
+// zero value instead of panicking on the type assertion.
+func TestMockNilPointerReturn(t *testing.T) {
+	HTTPMock.On("Send", HTTPRequest{URL: "http://nil.example"}).Return(nil, nil)
+
+	resp, err := HTTPSend(HTTPRequest{URL: "http://nil.example"})
+	require.NoError(t, err)
+	require.Nil(t, resp)
+}
+
+func TestMockNilSliceReturn(t *testing.T) {
+	LibraryMock.On("GetAllLibraries").Return(nil, nil)
+
+	libs, err := LibraryGetAllLibraries()
+	require.NoError(t, err)
+	require.Nil(t, libs)
+}
diff --git a/plugins/pdk/go/host/nd_host_cache_stub.go b/plugins/pdk/go/host/nd_host_cache_stub.go
index 46bb44bcf..faf4e65d2 100644
--- a/plugins/pdk/go/host/nd_host_cache_stub.go
+++ b/plugins/pdk/go/host/nd_host_cache_stub.go
@@ -154,7 +154,11 @@ func CacheSetBytes(key string, value []byte, ttlSeconds int64) error {
 // GetBytes is the mock method for CacheGetBytes.
 func (m *mockCacheService) GetBytes(key string) ([]byte, bool, error) {
 	args := m.Called(key)
-	return args.Get(0).([]byte), args.Bool(1), args.Error(2)
+	var r0 []byte
+	if v := args.Get(0); v != nil {
+		r0 = v.([]byte)
+	}
+	return r0, args.Bool(1), args.Error(2)
 }
 
 // CacheGetBytes delegates to the mock instance.
diff --git a/plugins/pdk/go/host/nd_host_config_stub.go b/plugins/pdk/go/host/nd_host_config_stub.go
index 463c29b76..0327346a3 100644
--- a/plugins/pdk/go/host/nd_host_config_stub.go
+++ b/plugins/pdk/go/host/nd_host_config_stub.go
@@ -59,7 +59,11 @@ func ConfigGetInt(key string) (int64, bool) {
 // Keys is the mock method for ConfigKeys.
 func (m *mockConfigService) Keys(prefix string) []string {
 	args := m.Called(prefix)
-	return args.Get(0).([]string)
+	var r0 []string
+	if v := args.Get(0); v != nil {
+		r0 = v.([]string)
+	}
+	return r0
 }
 
 // ConfigKeys delegates to the mock instance.
diff --git a/plugins/pdk/go/host/nd_host_http_stub.go b/plugins/pdk/go/host/nd_host_http_stub.go
index 09c4d0fcf..8706ac9e5 100644
--- a/plugins/pdk/go/host/nd_host_http_stub.go
+++ b/plugins/pdk/go/host/nd_host_http_stub.go
@@ -43,7 +43,11 @@ var HTTPMock = &mockHTTPService{}
 // Send is the mock method for HTTPSend.
 func (m *mockHTTPService) Send(request HTTPRequest) (*HTTPResponse, error) {
 	args := m.Called(request)
-	return args.Get(0).(*HTTPResponse), args.Error(1)
+	var r0 *HTTPResponse
+	if v := args.Get(0); v != nil {
+		r0 = v.(*HTTPResponse)
+	}
+	return r0, args.Error(1)
 }
 
 // HTTPSend delegates to the mock instance.
diff --git a/plugins/pdk/go/host/nd_host_kvstore_stub.go b/plugins/pdk/go/host/nd_host_kvstore_stub.go
index fce038aa1..e5243860a 100644
--- a/plugins/pdk/go/host/nd_host_kvstore_stub.go
+++ b/plugins/pdk/go/host/nd_host_kvstore_stub.go
@@ -64,7 +64,11 @@ func KVStoreSetWithTTL(key string, value []byte, ttlSeconds int64) error {
 // Get is the mock method for KVStoreGet.
 func (m *mockKVStoreService) Get(key string) ([]byte, bool, error) {
 	args := m.Called(key)
-	return args.Get(0).([]byte), args.Bool(1), args.Error(2)
+	var r0 []byte
+	if v := args.Get(0); v != nil {
+		r0 = v.([]byte)
+	}
+	return r0, args.Bool(1), args.Error(2)
 }
 
 // KVStoreGet delegates to the mock instance.
@@ -81,7 +85,11 @@ func KVStoreGet(key string) ([]byte, bool, error) {
 // GetMany is the mock method for KVStoreGetMany.
 func (m *mockKVStoreService) GetMany(keys []string) (map[string][]byte, error) {
 	args := m.Called(keys)
-	return args.Get(0).(map[string][]byte), args.Error(1)
+	var r0 map[string][]byte
+	if v := args.Get(0); v != nil {
+		r0 = v.(map[string][]byte)
+	}
+	return r0, args.Error(1)
 }
 
 // KVStoreGetMany delegates to the mock instance.
@@ -116,7 +124,11 @@ func KVStoreHas(key string) (bool, error) {
 // List is the mock method for KVStoreList.
 func (m *mockKVStoreService) List(prefix string) ([]string, error) {
 	args := m.Called(prefix)
-	return args.Get(0).([]string), args.Error(1)
+	var r0 []string
+	if v := args.Get(0); v != nil {
+		r0 = v.([]string)
+	}
+	return r0, args.Error(1)
 }
 
 // KVStoreList delegates to the mock instance.
diff --git a/plugins/pdk/go/host/nd_host_library_stub.go b/plugins/pdk/go/host/nd_host_library_stub.go
index 1e4c230c3..0232c49d9 100644
--- a/plugins/pdk/go/host/nd_host_library_stub.go
+++ b/plugins/pdk/go/host/nd_host_library_stub.go
@@ -39,7 +39,11 @@ var LibraryMock = &mockLibraryService{}
 // GetLibrary is the mock method for LibraryGetLibrary.
 func (m *mockLibraryService) GetLibrary(id int32) (*Library, error) {
 	args := m.Called(id)
-	return args.Get(0).(*Library), args.Error(1)
+	var r0 *Library
+	if v := args.Get(0); v != nil {
+		r0 = v.(*Library)
+	}
+	return r0, args.Error(1)
 }
 
 // LibraryGetLibrary delegates to the mock instance.
@@ -56,7 +60,11 @@ func LibraryGetLibrary(id int32) (*Library, error) {
 // GetAllLibraries is the mock method for LibraryGetAllLibraries.
 func (m *mockLibraryService) GetAllLibraries() ([]Library, error) {
 	args := m.Called()
-	return args.Get(0).([]Library), args.Error(1)
+	var r0 []Library
+	if v := args.Get(0); v != nil {
+		r0 = v.([]Library)
+	}
+	return r0, args.Error(1)
 }
 
 // LibraryGetAllLibraries delegates to the mock instance.
diff --git a/plugins/pdk/go/host/nd_host_matcher_stub.go b/plugins/pdk/go/host/nd_host_matcher_stub.go
index 07b34bb82..ade368c06 100644
--- a/plugins/pdk/go/host/nd_host_matcher_stub.go
+++ b/plugins/pdk/go/host/nd_host_matcher_stub.go
@@ -31,7 +31,11 @@ var MatcherMock = &mockMatcherService{}
 // MatchSongs is the mock method for MatcherMatchSongs.
 func (m *mockMatcherService) MatchSongs(songs []types.SongRef, opts MatchOptions) ([]*types.Track, error) {
 	args := m.Called(songs, opts)
-	return args.Get(0).([]*types.Track), args.Error(1)
+	var r0 []*types.Track
+	if v := args.Get(0); v != nil {
+		r0 = v.([]*types.Track)
+	}
+	return r0, args.Error(1)
 }
 
 // MatcherMatchSongs delegates to the mock instance.
diff --git a/plugins/pdk/go/host/nd_host_subsonicapi_stub.go b/plugins/pdk/go/host/nd_host_subsonicapi_stub.go
index 6d3a56b35..ef3d1b735 100644
--- a/plugins/pdk/go/host/nd_host_subsonicapi_stub.go
+++ b/plugins/pdk/go/host/nd_host_subsonicapi_stub.go
@@ -39,7 +39,11 @@ func SubsonicAPICall(uri string) (string, error) {
 // CallRaw is the mock method for SubsonicAPICallRaw.
 func (m *mockSubsonicAPIService) CallRaw(uri string) (string, []byte, error) {
 	args := m.Called(uri)
-	return args.String(0), args.Get(1).([]byte), args.Error(2)
+	var r1 []byte
+	if v := args.Get(1); v != nil {
+		r1 = v.([]byte)
+	}
+	return args.String(0), r1, args.Error(2)
 }
 
 // SubsonicAPICallRaw delegates to the mock instance.
diff --git a/plugins/pdk/go/host/nd_host_task_stub.go b/plugins/pdk/go/host/nd_host_task_stub.go
index 286d14035..f2c45a2b5 100644
--- a/plugins/pdk/go/host/nd_host_task_stub.go
+++ b/plugins/pdk/go/host/nd_host_task_stub.go
@@ -70,7 +70,11 @@ func TaskEnqueue(queueName string, payload []byte) (string, error) {
 // Get is the mock method for TaskGet.
 func (m *mockTaskService) Get(taskID string) (*TaskInfo, error) {
 	args := m.Called(taskID)
-	return args.Get(0).(*TaskInfo), args.Error(1)
+	var r0 *TaskInfo
+	if v := args.Get(0); v != nil {
+		r0 = v.(*TaskInfo)
+	}
+	return r0, args.Error(1)
 }
 
 // TaskGet delegates to the mock instance.
diff --git a/plugins/pdk/go/host/nd_host_users_stub.go b/plugins/pdk/go/host/nd_host_users_stub.go
index 8858b2109..e0f8c0939 100644
--- a/plugins/pdk/go/host/nd_host_users_stub.go
+++ b/plugins/pdk/go/host/nd_host_users_stub.go
@@ -33,7 +33,11 @@ var UsersMock = &mockUsersService{}
 // GetUsers is the mock method for UsersGetUsers.
 func (m *mockUsersService) GetUsers() ([]User, error) {
 	args := m.Called()
-	return args.Get(0).([]User), args.Error(1)
+	var r0 []User
+	if v := args.Get(0); v != nil {
+		r0 = v.([]User)
+	}
+	return r0, args.Error(1)
 }
 
 // UsersGetUsers delegates to the mock instance.
@@ -49,7 +53,11 @@ func UsersGetUsers() ([]User, error) {
 // GetAdmins is the mock method for UsersGetAdmins.
 func (m *mockUsersService) GetAdmins() ([]User, error) {
 	args := m.Called()
-	return args.Get(0).([]User), args.Error(1)
+	var r0 []User
+	if v := args.Get(0); v != nil {
+		r0 = v.([]User)
+	}
+	return r0, args.Error(1)
 }
 
 // UsersGetAdmins delegates to the mock instance.
diff --git a/plugins/pdk/go/pdk/pdk_stub.go b/plugins/pdk/go/pdk/pdk_stub.go
index 3bdbb1cb7..8f2707d56 100644
--- a/plugins/pdk/go/pdk/pdk_stub.go
+++ b/plugins/pdk/go/pdk/pdk_stub.go
@@ -62,7 +62,11 @@ func GetConfig(key string) (string, bool) {
 // GetVar GetVar returns the byte slice (if any) associated with `key`.
 func GetVar(key string) []byte {
 	args := PDKMock.Called(key)
-	return args.Get(0).([]byte)
+	var r0 []byte
+	if v := args.Get(0); v != nil {
+		r0 = v.([]byte)
+	}
+	return r0
 }
 
 // GetVarInt GetVarInt returns the int associated with `key` (or 0 if none).
@@ -74,7 +78,11 @@ func GetVarInt(key string) int {
 // Input Input returns a slice of bytes from the host.
 func Input() []byte {
 	args := PDKMock.Called()
-	return args.Get(0).([]byte)
+	var r0 []byte
+	if v := args.Get(0); v != nil {
+		r0 = v.([]byte)
+	}
+	return r0
 }
 
 // InputJSON InputJSON returns unmartialed JSON data from the host "input".
@@ -108,7 +116,11 @@ func LogMemory(level LogLevel, m Memory) {
 // NewHTTPRequest NewHTTPRequest returns a new `HTTPRequest`.
 func NewHTTPRequest(method HTTPMethod, url string) *HTTPRequest {
 	args := PDKMock.Called(method, url)
-	return args.Get(0).(*HTTPRequest)
+	var r0 *HTTPRequest
+	if v := args.Get(0); v != nil {
+		r0 = v.(*HTTPRequest)
+	}
+	return r0
 }
 func NewMemory(offset uint64, length uint64) Memory {
 	args := PDKMock.Called(offset, length)
@@ -139,7 +151,11 @@ func OutputString(s string) {
 // ParamBytes ParamBytes returns bytes from Extism host memory given an offset.
 func ParamBytes(offset uint64) []byte {
 	args := PDKMock.Called(offset)
-	return args.Get(0).([]byte)
+	var r0 []byte
+	if v := args.Get(0); v != nil {
+		r0 = v.([]byte)
+	}
+	return r0
 }
 
 // ParamString ParamString returns UTF-8 string data from Extism host memory given an offset.

From b0c6d2e444607e1bb71cafee9361b2dfe4139927 Mon Sep 17 00:00:00 2001
From: Kendall Garner <17521368+kgarner7@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:13:29 -0700
Subject: [PATCH 019/200] feat(plugins): add scrobbles access to PDK (#5795)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* initial scrobble api

* feat: add scrobble retrieval api

* address feedback (1)

* fix spelling

* be explicit about get

* add primary key field, update index, remove rowid references

* use unix timestamp for input and output

* initial api, some testing

* add tests, add count retrieval

* add docs, test for rejected user

* add permission validation for scrobble retriever

* chore(plugins): fix typos in scrobble retriever

Rename newScrobbleRetreverService, and fix FromTImestamp/nonero in the
ScrobbleRetriever doc comments, which generate into the Go and Rust PDKs.
Also corrects two mislabelled test entries.

* fix(plugins): make scrobble pagination order deterministic

Sorting only by submission_time left the order of equal timestamps up to the
query planner, but the cursor skips ties by offset, so an unstable order can
repeat or drop scrobbles between pages. Break ties on scrobbles.id, which the
existing scrobbles_user_time index already yields for free.

Descending is now honoured for every combination of From/To rather than only
when both or neither is set. This changes the default for a lone ToTimestamp
from newest-first to oldest-first.

* refactor(plugins): return the next page's options from GetScrobbles

Paging previously meant reading NextTimestamp and Cursor off the response and
deciding where each belonged: NextTimestamp into FromTimestamp when ascending
or ToTimestamp when descending, and Cursor copied every time, including when 0.
Both are silent data-loss bugs when a plugin gets them wrong.

GetScrobbles now returns the options for the following page, or nil when the
range is exhausted, so a plugin passes the value straight back and repeats.
ScrobbleCursor and ScrobbleList are gone; the query itself is unchanged.

* docs(plugins): warn against setting ScrobbleOptions.Offset manually

The all-ties carry rule assumes Offset counts already-returned rows at the
boundary timestamp, which only holds for the options GetScrobbles returns.
A hand-built From+Offset combination can silently skip scrobbles, so document
the field as managed pagination state instead of a generic skip.

* docs(plugins): document the ScrobbleRetriever host service in the README

Covers the manifest permissions (including the users requirement), the four
host functions, the options/ref field tables, and the pagination loop with
its two gotchas: the host-managed offset and the adjusted range on the
returned next options.

* chore(plugins): regenerate scrobble retriever stub with nil-safe accessors

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 plugins/README.md                             |  77 ++++
 plugins/host/scrobble_retriever.go            |  89 ++++
 plugins/host/scrobbleretriever_gen.go         | 230 +++++++++++
 plugins/host_scrobbleretriever.go             | 161 ++++++++
 plugins/host_scrobbleretriever_test.go        | 390 ++++++++++++++++++
 plugins/manager_loader.go                     |   8 +
 plugins/manifest-schema.json                  |  14 +
 plugins/manifest.go                           |   8 +-
 plugins/manifest_gen.go                       |   9 +
 plugins/manifest_test.go                      |  30 ++
 plugins/pdk/go/host/doc.go                    |   1 +
 .../pdk/go/host/nd_host_scrobbleretriever.go  | 266 ++++++++++++
 .../go/host/nd_host_scrobbleretriever_stub.go | 136 ++++++
 plugins/pdk/rust/nd-pdk-host/src/lib.rs       |   8 +
 .../src/nd_host_scrobbleretriever.rs          | 237 +++++++++++
 .../testdata/test-scrobble-retriever/go.mod   |  16 +
 .../testdata/test-scrobble-retriever/go.sum   |  14 +
 .../testdata/test-scrobble-retriever/main.go  | 120 ++++++
 .../test-scrobble-retriever/manifest.json     |  14 +
 19 files changed, 1826 insertions(+), 2 deletions(-)
 create mode 100644 plugins/host/scrobble_retriever.go
 create mode 100644 plugins/host/scrobbleretriever_gen.go
 create mode 100644 plugins/host_scrobbleretriever.go
 create mode 100644 plugins/host_scrobbleretriever_test.go
 create mode 100644 plugins/pdk/go/host/nd_host_scrobbleretriever.go
 create mode 100644 plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go
 create mode 100644 plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs
 create mode 100644 plugins/testdata/test-scrobble-retriever/go.mod
 create mode 100644 plugins/testdata/test-scrobble-retriever/go.sum
 create mode 100644 plugins/testdata/test-scrobble-retriever/main.go
 create mode 100644 plugins/testdata/test-scrobble-retriever/manifest.json

diff --git a/plugins/README.md b/plugins/README.md
index a2f9532ca..adc177324 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -38,6 +38,7 @@ The plugin system is built on **[Extism](https://extism.org/)**, a cross-languag
   - [SubsonicAPI](#subsonicapi)
   - [Config](#config)
   - [Users](#users)
+  - [ScrobbleRetriever](#scrobbleretriever)
 - [Configuration](#configuration)
 - [Building Plugins](#building-plugins)
 - [Examples](#examples)
@@ -896,6 +897,82 @@ for _, user := range users {
 admins, err := host.UsersGetAdmins()
 ```
 
+### ScrobbleRetriever
+
+Retrieve the scrobble history of users the plugin has been granted access to. Each scrobble carries only the media file ID and the submission time; use the Matcher host service to resolve them to track metadata.
+
+**Manifest permission:**
+
+```json
+{
+  "permissions": {
+    "scrobbleRetriever": {
+      "reason": "Sync scrobble history to an external service"
+    },
+    "users": {
+      "reason": "Access user information for scrobble retrieval"
+    }
+  }
+}
+```
+
+> **Important:** The `scrobbleRetriever` permission requires the `users` permission. Which users the plugin can act as is controlled through the Navidrome UI.
+
+**Host functions:**
+
+| Function                              | Parameters            | Returns                          |
+|---------------------------------------|-----------------------|----------------------------------|
+| `scrobbleretriever_getfirsttimestamp` | `username`            | Unix timestamp of oldest scrobble, or null |
+| `scrobbleretriever_getlasttimestamp`  | `username`            | Unix timestamp of newest scrobble, or null |
+| `scrobbleretriever_getscrobbles`      | `username`, `options` | One page of scrobbles + options for the next page |
+| `scrobbleretriever_getscrobblecount`  | `username`, `options` | Number of scrobbles in the range |
+
+**ScrobbleOptions fields** (all optional):
+
+| Field           | Type    | Description                                              |
+|-----------------|---------|----------------------------------------------------------|
+| `fromTimestamp` | int64   | Start of the range (inclusive). Default: first scrobble  |
+| `toTimestamp`   | int64   | End of the range (inclusive). Default: last scrobble     |
+| `descending`    | boolean | Newest first. Default: oldest first                      |
+| `maxItems`      | int     | Page size, capped at 5000 (the default)                  |
+| `offset`        | int     | Managed by the host for pagination. Never set it manually |
+
+**ScrobbleRef fields:**
+
+| Field            | Type   | Description                                    |
+|------------------|--------|------------------------------------------------|
+| `id`             | int64  | Scrobble ID, unique even for duplicate submissions |
+| `mediaFileId`    | string | The media file that was scrobbled              |
+| `submissionTime` | int64  | Unix timestamp of the submission               |
+
+**Usage:**
+
+`GetScrobbles` returns one page plus the options to fetch the following page. Pass them back unchanged and repeat until they are nil:
+
+```go
+opts := host.ScrobbleOptions{MaxItems: 500}
+var all []host.ScrobbleRef
+for {
+    page, next, err := host.ScrobbleRetrieverGetScrobbles("username", opts)
+    if err != nil {
+        return err
+    }
+    all = append(all, page...)
+    if next == nil {
+        break // no more scrobbles
+    }
+    opts = *next
+}
+
+// Range boundaries and counts
+first, err := host.ScrobbleRetrieverGetFirstTimestamp("username") // nil if no scrobbles
+count, err := host.ScrobbleRetrieverGetScrobbleCount("username", host.ScrobbleCountOptions{
+    FromTimestamp: first,
+})
+```
+
+> **Note:** The returned `next` options carry an adjusted `fromTimestamp`/`toTimestamp`, so keep a copy of your original options if you still need the range.
+
 ---
 
 ## Configuration
diff --git a/plugins/host/scrobble_retriever.go b/plugins/host/scrobble_retriever.go
new file mode 100644
index 000000000..2582dd650
--- /dev/null
+++ b/plugins/host/scrobble_retriever.go
@@ -0,0 +1,89 @@
+package host
+
+import "context"
+
+// ScrobbleRef represents one instance of a scrobble (instance id, file id, submission time)
+type ScrobbleRef struct {
+	// The ID of the scrobble. Useful if duplicate scrobbles happen for the same time
+	ID int64 `json:"id"`
+	// The ID of the MediaFile submitted at this time
+	MediaFileID string `json:"mediaFileId"`
+	// The UNIX timestamp this scrobble was submitted
+	SubmissionTime int64 `json:"submissionTime"`
+}
+
+// ScrobbleOptions carries optional parameters for retrieving user scrobbles
+type ScrobbleOptions struct {
+	// The starting unix timestamp to query for scrobbles (inclusive).
+	// If not specified, start from the first scrobble
+	FromTimestamp *int64 `json:"fromTimestamp,omitempty"`
+	// The ending unix timestamp to query for scrobbles (inclusive).
+	// If not specified, go up to the last scrobble
+	ToTimestamp *int64 `json:"toTimestamp,omitempty"`
+	// If true, return scrobbles from newest to oldest. Defaults to oldest first
+	Descending bool `json:"descending"`
+	// The maximum number of items to retrieve. This is capped at 5000, the
+	// default if not specified
+	MaxItems int `json:"maxItems"`
+	// Pagination state managed by GetScrobbles; only meaningful on the options it returns.
+	// Never set it or combine it with your own timestamps — scrobbles may be silently skipped
+	Offset int `json:"offset,omitempty"`
+}
+
+// ScrobbleCountOptions carries optional parameters for counting user scrobbles
+type ScrobbleCountOptions struct {
+	// The starting unix timestamp to query for scrobbles (inclusive).
+	// If not specified, start from the first scrobble
+	FromTimestamp *int64 `json:"fromTimestamp,omitempty"`
+	// The ending unix timestamp to query for scrobbles (inclusive).
+	// If not specified, go up to the last scrobble
+	ToTimestamp *int64 `json:"toTimestamp,omitempty"`
+}
+
+// ScrobbleRetrieverService allows a plugin to retrieve scrobbles for one or more authorized users.
+// It will only provide the media_file ID and submission time, which can be combined with the MatcherService
+// to fetch deduped tracks
+//
+//nd:hostservice name=ScrobbleRetriever permission=scrobbleRetriever
+type ScrobbleRetrieverService interface {
+	// GetFirstTimestamp returns the unix timestamp of the oldest scrobble for the user.
+	// If the user has no scrobbles, returns nil
+	//nd:hostfunc
+	GetFirstTimestamp(ctx context.Context, username string) (*int64, error)
+
+	// GetLastTimestamp returns the unix timestamp of the most recent scrobble for the user
+	// If the user has no scrobbles, return nil
+	//nd:hostfunc
+	GetLastTimestamp(ctx context.Context, username string) (*int64, error)
+
+	// GetScrobbles returns one page of scrobbles for a user.
+	//
+	// Parameters:
+	//   - username: the user to query for scrobbles
+	//   - options.FromTimestamp: If specified, the first UNIX timestamp to start fetching scrobbles (inclusive). Otherwise, start from the first scrobble
+	//   - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble
+	//   - options.Descending: If true, order from newest to oldest. Otherwise, oldest to newest
+	//   - options.MaxItems: The maximum number of items to retrieve. The maximum value (and default) if not specified is 5000
+	//   - options.Offset: Pagination state; only valid as received on the options returned by a previous call. Never set it manually
+	//
+	// Returns:
+	//   - scrobbles: The scrobbles in the requested range, ordered by submission time
+	//     (ties broken by scrobble ID) in the direction given by options.Descending
+	//   - next: The options for the following page, or nil once no scrobbles remain.
+	//     Pass it back to GetScrobbles unchanged and repeat until it is nil. It carries an
+	//     adjusted FromTimestamp/ToTimestamp, so keep a copy if you still need the original range
+	//nd:hostfunc
+	GetScrobbles(ctx context.Context, username string, options ScrobbleOptions) (scrobbles []ScrobbleRef, next *ScrobbleOptions, err error)
+
+	// GetScrobbleCount returns the number of scrobbles for a user in a given range
+	//
+	// Parameters:
+	//   - username: the user to query for scrobbles
+	//   - options.FromTimestamp: If specified, the first UNIX timestamp to start fetching scrobbles (inclusive). Otherwise, start from the first scrobble
+	//   - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble
+	//
+	// Returns:
+	//   - the number of scrobbles in the given range, or 0
+	//nd:hostfunc
+	GetScrobbleCount(ctx context.Context, username string, options ScrobbleCountOptions) (int64, error)
+}
diff --git a/plugins/host/scrobbleretriever_gen.go b/plugins/host/scrobbleretriever_gen.go
new file mode 100644
index 000000000..7a00c9c1f
--- /dev/null
+++ b/plugins/host/scrobbleretriever_gen.go
@@ -0,0 +1,230 @@
+// Code generated by ndpgen. DO NOT EDIT.
+
+package host
+
+import (
+	"context"
+	"encoding/json"
+
+	extism "github.com/extism/go-sdk"
+)
+
+// ScrobbleRetrieverGetFirstTimestampRequest is the request type for ScrobbleRetriever.GetFirstTimestamp.
+type ScrobbleRetrieverGetFirstTimestampRequest struct {
+	Username string `json:"username"`
+}
+
+// ScrobbleRetrieverGetFirstTimestampResponse is the response type for ScrobbleRetriever.GetFirstTimestamp.
+type ScrobbleRetrieverGetFirstTimestampResponse struct {
+	Result *int64 `json:"result,omitempty"`
+	Error  string `json:"error,omitempty"`
+}
+
+// ScrobbleRetrieverGetLastTimestampRequest is the request type for ScrobbleRetriever.GetLastTimestamp.
+type ScrobbleRetrieverGetLastTimestampRequest struct {
+	Username string `json:"username"`
+}
+
+// ScrobbleRetrieverGetLastTimestampResponse is the response type for ScrobbleRetriever.GetLastTimestamp.
+type ScrobbleRetrieverGetLastTimestampResponse struct {
+	Result *int64 `json:"result,omitempty"`
+	Error  string `json:"error,omitempty"`
+}
+
+// ScrobbleRetrieverGetScrobblesRequest is the request type for ScrobbleRetriever.GetScrobbles.
+type ScrobbleRetrieverGetScrobblesRequest struct {
+	Username string          `json:"username"`
+	Options  ScrobbleOptions `json:"options"`
+}
+
+// ScrobbleRetrieverGetScrobblesResponse is the response type for ScrobbleRetriever.GetScrobbles.
+type ScrobbleRetrieverGetScrobblesResponse struct {
+	Scrobbles []ScrobbleRef    `json:"scrobbles,omitempty"`
+	Next      *ScrobbleOptions `json:"next,omitempty"`
+	Error     string           `json:"error,omitempty"`
+}
+
+// ScrobbleRetrieverGetScrobbleCountRequest is the request type for ScrobbleRetriever.GetScrobbleCount.
+type ScrobbleRetrieverGetScrobbleCountRequest struct {
+	Username string               `json:"username"`
+	Options  ScrobbleCountOptions `json:"options"`
+}
+
+// ScrobbleRetrieverGetScrobbleCountResponse is the response type for ScrobbleRetriever.GetScrobbleCount.
+type ScrobbleRetrieverGetScrobbleCountResponse struct {
+	Result int64  `json:"result,omitempty"`
+	Error  string `json:"error,omitempty"`
+}
+
+// RegisterScrobbleRetrieverHostFunctions registers ScrobbleRetriever service host functions.
+// The returned host functions should be added to the plugin's configuration.
+func RegisterScrobbleRetrieverHostFunctions(service ScrobbleRetrieverService) []extism.HostFunction {
+	return []extism.HostFunction{
+		newScrobbleRetrieverGetFirstTimestampHostFunction(service),
+		newScrobbleRetrieverGetLastTimestampHostFunction(service),
+		newScrobbleRetrieverGetScrobblesHostFunction(service),
+		newScrobbleRetrieverGetScrobbleCountHostFunction(service),
+	}
+}
+
+func newScrobbleRetrieverGetFirstTimestampHostFunction(service ScrobbleRetrieverService) extism.HostFunction {
+	return extism.NewHostFunctionWithStack(
+		"scrobbleretriever_getfirsttimestamp",
+		func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
+			// Read JSON request from plugin memory
+			reqBytes, err := p.ReadBytes(stack[0])
+			if err != nil {
+				scrobbleretrieverWriteError(p, stack, err)
+				return
+			}
+			var req ScrobbleRetrieverGetFirstTimestampRequest
+			if err := json.Unmarshal(reqBytes, &req); err != nil {
+				scrobbleretrieverWriteError(p, stack, err)
+				return
+			}
+
+			// Call the service method
+			result, svcErr := service.GetFirstTimestamp(ctx, req.Username)
+			if svcErr != nil {
+				scrobbleretrieverWriteError(p, stack, svcErr)
+				return
+			}
+
+			// Write JSON response to plugin memory
+			resp := ScrobbleRetrieverGetFirstTimestampResponse{
+				Result: result,
+			}
+			scrobbleretrieverWriteResponse(p, stack, resp)
+		},
+		[]extism.ValueType{extism.ValueTypePTR},
+		[]extism.ValueType{extism.ValueTypePTR},
+	)
+}
+
+func newScrobbleRetrieverGetLastTimestampHostFunction(service ScrobbleRetrieverService) extism.HostFunction {
+	return extism.NewHostFunctionWithStack(
+		"scrobbleretriever_getlasttimestamp",
+		func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
+			// Read JSON request from plugin memory
+			reqBytes, err := p.ReadBytes(stack[0])
+			if err != nil {
+				scrobbleretrieverWriteError(p, stack, err)
+				return
+			}
+			var req ScrobbleRetrieverGetLastTimestampRequest
+			if err := json.Unmarshal(reqBytes, &req); err != nil {
+				scrobbleretrieverWriteError(p, stack, err)
+				return
+			}
+
+			// Call the service method
+			result, svcErr := service.GetLastTimestamp(ctx, req.Username)
+			if svcErr != nil {
+				scrobbleretrieverWriteError(p, stack, svcErr)
+				return
+			}
+
+			// Write JSON response to plugin memory
+			resp := ScrobbleRetrieverGetLastTimestampResponse{
+				Result: result,
+			}
+			scrobbleretrieverWriteResponse(p, stack, resp)
+		},
+		[]extism.ValueType{extism.ValueTypePTR},
+		[]extism.ValueType{extism.ValueTypePTR},
+	)
+}
+
+func newScrobbleRetrieverGetScrobblesHostFunction(service ScrobbleRetrieverService) extism.HostFunction {
+	return extism.NewHostFunctionWithStack(
+		"scrobbleretriever_getscrobbles",
+		func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
+			// Read JSON request from plugin memory
+			reqBytes, err := p.ReadBytes(stack[0])
+			if err != nil {
+				scrobbleretrieverWriteError(p, stack, err)
+				return
+			}
+			var req ScrobbleRetrieverGetScrobblesRequest
+			if err := json.Unmarshal(reqBytes, &req); err != nil {
+				scrobbleretrieverWriteError(p, stack, err)
+				return
+			}
+
+			// Call the service method
+			scrobbles, next, svcErr := service.GetScrobbles(ctx, req.Username, req.Options)
+			if svcErr != nil {
+				scrobbleretrieverWriteError(p, stack, svcErr)
+				return
+			}
+
+			// Write JSON response to plugin memory
+			resp := ScrobbleRetrieverGetScrobblesResponse{
+				Scrobbles: scrobbles,
+				Next:      next,
+			}
+			scrobbleretrieverWriteResponse(p, stack, resp)
+		},
+		[]extism.ValueType{extism.ValueTypePTR},
+		[]extism.ValueType{extism.ValueTypePTR},
+	)
+}
+
+func newScrobbleRetrieverGetScrobbleCountHostFunction(service ScrobbleRetrieverService) extism.HostFunction {
+	return extism.NewHostFunctionWithStack(
+		"scrobbleretriever_getscrobblecount",
+		func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
+			// Read JSON request from plugin memory
+			reqBytes, err := p.ReadBytes(stack[0])
+			if err != nil {
+				scrobbleretrieverWriteError(p, stack, err)
+				return
+			}
+			var req ScrobbleRetrieverGetScrobbleCountRequest
+			if err := json.Unmarshal(reqBytes, &req); err != nil {
+				scrobbleretrieverWriteError(p, stack, err)
+				return
+			}
+
+			// Call the service method
+			result, svcErr := service.GetScrobbleCount(ctx, req.Username, req.Options)
+			if svcErr != nil {
+				scrobbleretrieverWriteError(p, stack, svcErr)
+				return
+			}
+
+			// Write JSON response to plugin memory
+			resp := ScrobbleRetrieverGetScrobbleCountResponse{
+				Result: result,
+			}
+			scrobbleretrieverWriteResponse(p, stack, resp)
+		},
+		[]extism.ValueType{extism.ValueTypePTR},
+		[]extism.ValueType{extism.ValueTypePTR},
+	)
+}
+
+// scrobbleretrieverWriteResponse writes a JSON response to plugin memory.
+func scrobbleretrieverWriteResponse(p *extism.CurrentPlugin, stack []uint64, resp any) {
+	respBytes, err := json.Marshal(resp)
+	if err != nil {
+		scrobbleretrieverWriteError(p, stack, err)
+		return
+	}
+	respPtr, err := p.WriteBytes(respBytes)
+	if err != nil {
+		stack[0] = 0
+		return
+	}
+	stack[0] = respPtr
+}
+
+// scrobbleretrieverWriteError writes an error response to plugin memory.
+func scrobbleretrieverWriteError(p *extism.CurrentPlugin, stack []uint64, err error) {
+	errResp := struct {
+		Error string `json:"error"`
+	}{Error: err.Error()}
+	respBytes, _ := json.Marshal(errResp)
+	respPtr, _ := p.WriteBytes(respBytes)
+	stack[0] = respPtr
+}
diff --git a/plugins/host_scrobbleretriever.go b/plugins/host_scrobbleretriever.go
new file mode 100644
index 000000000..7417d7c50
--- /dev/null
+++ b/plugins/host_scrobbleretriever.go
@@ -0,0 +1,161 @@
+package plugins
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/plugins/host"
+)
+
+// maxScrobbleItems caps how many scrobbles a single GetScrobbles call can return.
+const maxScrobbleItems = 5000
+
+type scrobbleRetrieverServiceImpl struct {
+	ds    model.DataStore
+	users userAccess
+}
+
+func newScrobbleRetrieverService(ds model.DataStore, users userAccess) host.ScrobbleRetrieverService {
+	return &scrobbleRetrieverServiceImpl{
+		ds:    ds,
+		users: users,
+	}
+}
+
+func (s *scrobbleRetrieverServiceImpl) getUserContext(ctx context.Context, username string) (context.Context, error) {
+	usr, err := s.users.resolve(ctx, s.ds, username)
+	if err != nil {
+		return nil, fmt.Errorf("scrobbleRetriever: %w", err)
+	}
+
+	ctx = request.WithUser(ctx, *usr)
+	return ctx, nil
+}
+
+func (s *scrobbleRetrieverServiceImpl) getFirstLastScrobble(ctx context.Context, username string, order string) (*int64, error) {
+	ctx, err := s.getUserContext(ctx, username)
+	if err != nil {
+		return nil, err
+	}
+
+	scrobbles, err := s.ds.Scrobble(ctx).GetAll(model.QueryOptions{Sort: "submission_time", Order: order, Max: 1})
+	if err != nil {
+		return nil, err
+	}
+
+	if len(scrobbles) == 0 {
+		return nil, nil
+	}
+
+	return &scrobbles[0].SubmissionTime, nil
+}
+
+func (s *scrobbleRetrieverServiceImpl) GetFirstTimestamp(ctx context.Context, username string) (*int64, error) {
+	return s.getFirstLastScrobble(ctx, username, "ASC")
+}
+
+func (s *scrobbleRetrieverServiceImpl) GetLastTimestamp(ctx context.Context, username string) (*int64, error) {
+	return s.getFirstLastScrobble(ctx, username, "DESC")
+}
+
+func (s *scrobbleRetrieverServiceImpl) GetScrobbles(ctx context.Context, username string, options host.ScrobbleOptions) ([]host.ScrobbleRef, *host.ScrobbleOptions, error) {
+	ctx, err := s.getUserContext(ctx, username)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if options.MaxItems < 1 || options.MaxItems > maxScrobbleItems {
+		options.MaxItems = maxScrobbleItems
+	}
+	options.Offset = max(options.Offset, 0)
+
+	order := "ASC"
+	if options.Descending {
+		order = "DESC"
+	}
+
+	// Fetch one more item than requested. The last item is the next timestamp to fetch
+	lookahead := options.MaxItems + 1
+
+	scrobbles, err := s.ds.Scrobble(ctx).GetAll(model.QueryOptions{
+		Max:     lookahead,
+		Filters: scrobbleRangeFilters(options.FromTimestamp, options.ToTimestamp),
+		// The id tiebreak makes the order of equal timestamps stable, which is what
+		// lets Offset skip exactly the ties already returned
+		Sort:   "scrobbles.submission_time, scrobbles.id",
+		Order:  order,
+		Offset: options.Offset,
+	})
+	if err != nil {
+		return nil, nil, err
+	}
+
+	var next *host.ScrobbleOptions
+	targetLen := len(scrobbles)
+
+	if len(scrobbles) == lookahead {
+		nextTimestamp := scrobbles[lookahead-1].SubmissionTime
+		targetLen = lookahead - 1
+
+		ties := 0
+		for i := targetLen - 1; i >= 0; i-- {
+			if scrobbles[i].SubmissionTime != nextTimestamp {
+				break
+			}
+			ties++
+		}
+
+		// Every scrobble in this page shares the timestamp, so the ties skipped by the
+		// incoming offset are still ahead of us and must be carried over
+		if ties == targetLen {
+			ties += options.Offset
+		}
+
+		advanced := options
+		advanced.Offset = ties
+		if options.Descending {
+			advanced.ToTimestamp = &nextTimestamp
+		} else {
+			advanced.FromTimestamp = &nextTimestamp
+		}
+		next = &advanced
+	}
+
+	scrobbleRefs := make([]host.ScrobbleRef, targetLen)
+	for idx, scrobble := range scrobbles[:targetLen] {
+		scrobbleRefs[idx] = host.ScrobbleRef{
+			ID:             scrobble.ID,
+			MediaFileID:    scrobble.MediaFileID,
+			SubmissionTime: scrobble.SubmissionTime,
+		}
+	}
+
+	return scrobbleRefs, next, nil
+}
+
+func (s *scrobbleRetrieverServiceImpl) GetScrobbleCount(ctx context.Context, username string, options host.ScrobbleCountOptions) (int64, error) {
+	ctx, err := s.getUserContext(ctx, username)
+	if err != nil {
+		return 0, err
+	}
+
+	return s.ds.Scrobble(ctx).CountAll(model.QueryOptions{
+		Filters: scrobbleRangeFilters(options.FromTimestamp, options.ToTimestamp),
+	})
+}
+
+func scrobbleRangeFilters(from, to *int64) squirrel.And {
+	var filters squirrel.And
+	if from != nil {
+		filters = append(filters, squirrel.GtOrEq{"scrobbles.submission_time": *from})
+	}
+	if to != nil {
+		filters = append(filters, squirrel.LtOrEq{"scrobbles.submission_time": *to})
+	}
+	return filters
+}
+
+var _ host.ScrobbleRetrieverService = (*scrobbleRetrieverServiceImpl)(nil)
diff --git a/plugins/host_scrobbleretriever_test.go b/plugins/host_scrobbleretriever_test.go
new file mode 100644
index 000000000..ab817c282
--- /dev/null
+++ b/plugins/host_scrobbleretriever_test.go
@@ -0,0 +1,390 @@
+//go:build !windows
+
+package plugins
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strconv"
+	"time"
+
+	extism "github.com/extism/go-sdk"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/db"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/persistence"
+	"github.com/navidrome/navidrome/plugins/host"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// scrobblePage mirrors what the test plugin emits for the multi-return GetScrobbles
+type scrobblePage struct {
+	Scrobbles []host.ScrobbleRef    `json:"scrobbles"`
+	Next      *host.ScrobbleOptions `json:"next"`
+}
+
+var _ = Describe("Scrobble Retriever Host Function", Ordered, func() {
+	var (
+		manager   *Manager
+		tmpDir    string
+		dataStore *tests.MockDataStore
+	)
+
+	p := func(val int64) *int64 {
+		return &val
+	}
+
+	opts := func(from, to *int64, descending bool, offset, maxItems int) *host.ScrobbleOptions {
+		return &host.ScrobbleOptions{
+			FromTimestamp: from, ToTimestamp: to,
+			Descending: descending, Offset: offset, MaxItems: maxItems,
+		}
+	}
+
+	BeforeAll(func() {
+		ctx := GinkgoT().Context()
+
+		var err error
+		tmpDir, err = os.MkdirTemp("", "scrobble-retriever-test-*")
+		Expect(err).ToNot(HaveOccurred())
+
+		conf.Server.DbPath = filepath.Join(tmpDir, "test-scanner.db?_journal_mode=WAL")
+
+		db.Init(ctx)
+		DeferCleanup(func() {
+			Expect(tests.ClearDB()).To(Succeed())
+		})
+		dataStore = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
+
+		// Copy test plugin to temp dir
+		srcPath := filepath.Join(testdataDir, "test-scrobble-retriever"+PackageExtension)
+		destPath := filepath.Join(tmpDir, "test-scrobble-retriever"+PackageExtension)
+		data, err := os.ReadFile(srcPath)
+		Expect(err).ToNot(HaveOccurred())
+		err = os.WriteFile(destPath, data, 0600)
+		Expect(err).ToNot(HaveOccurred())
+
+		// Setup config
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.Plugins.Enabled = true
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
+		conf.Server.Plugins.AutoReload = false
+
+		userRepo := dataStore.User(ctx)
+		// Add test users
+		_ = userRepo.Put(&model.User{
+			ID:       "user1",
+			UserName: "testuser",
+			IsAdmin:  false,
+		})
+		_ = userRepo.Put(&model.User{
+			ID:       "admin1",
+			UserName: "adminuser",
+			IsAdmin:  true,
+		})
+
+		err = dataStore.MediaFile(ctx).Put(&model.MediaFile{ID: "1", LibraryID: 1})
+		Expect(err).To(BeNil())
+		err = dataStore.MediaFile(ctx).Put(&model.MediaFile{ID: "2", LibraryID: 1})
+		Expect(err).To(BeNil())
+		err = dataStore.MediaFile(ctx).Put(&model.MediaFile{ID: "3", LibraryID: 1})
+		Expect(err).To(BeNil())
+
+		scrobbleCtx := request.WithUser(GinkgoT().Context(), model.User{ID: "admin1", UserName: "adminuser"})
+
+		scrobbleRepo := dataStore.Scrobble(scrobbleCtx)
+		err = scrobbleRepo.RecordScrobble("1", time.Unix(0, 0))
+		Expect(err).To(BeNil())
+		err = scrobbleRepo.RecordScrobble("2", time.Unix(1, 0))
+		Expect(err).To(BeNil())
+		err = scrobbleRepo.RecordScrobble("3", time.Unix(2, 0))
+		Expect(err).To(BeNil())
+		err = scrobbleRepo.RecordScrobble("1", time.Unix(2, 0))
+		Expect(err).To(BeNil())
+
+		// Create and configure manager
+		manager = &Manager{
+			plugins: make(map[string]*plugin),
+			ds:      dataStore,
+		}
+		router := &fakeSubsonicRouter{}
+		manager.SetSubsonicRouter(router)
+
+		// Pre-enable the plugin in the mock repo so it loads on startup
+		// Compute SHA256 of the plugin file to match what syncPlugins will compute
+		pluginPath := filepath.Join(tmpDir, "test-scrobble-retriever"+PackageExtension)
+		wasmData, err := os.ReadFile(pluginPath)
+		Expect(err).ToNot(HaveOccurred())
+		hash := sha256.Sum256(wasmData)
+		hashHex := hex.EncodeToString(hash[:])
+
+		dataStore.MockedPlugin = tests.CreateMockPluginRepo()
+
+		mockPluginRepo := dataStore.Plugin(GinkgoT().Context()).(*tests.MockPluginRepo)
+		mockPluginRepo.Permitted = true
+		enabledPlugin := model.Plugin{
+			ID:      "test-scrobble-retriever",
+			Path:    pluginPath,
+			SHA256:  hashHex,
+			Enabled: true,
+			Users:   `["user1","admin1"]`,
+		}
+		mockPluginRepo.SetData(model.Plugins{enabledPlugin})
+
+		// Start the manager
+		err = manager.Start(GinkgoT().Context())
+		Expect(err).ToNot(HaveOccurred())
+
+		DeferCleanup(func() {
+			_ = manager.Stop()
+			_ = os.RemoveAll(tmpDir)
+		})
+	})
+
+	var instance *extism.Plugin
+
+	BeforeEach(func() {
+		manager.mu.RLock()
+		plugin := manager.plugins["test-scrobble-retriever"]
+		manager.mu.RUnlock()
+		Expect(plugin).ToNot(BeNil())
+
+		var err error
+		ctx := GinkgoT().Context()
+		instance, err = plugin.instance(ctx)
+		Expect(err).ToNot(HaveOccurred())
+		DeferCleanup(func() {
+			instance.Close(ctx)
+		})
+	})
+
+	Describe("not authorized", func() {
+		It("rejects first timestamp", func() {
+			exit, _, err := instance.Call("call_get_first_timestamp", []byte("baduser"))
+			Expect(err).To(HaveOccurred())
+			Expect(exit).To(Equal(uint32(1)))
+		})
+
+		It("rejects last timestamp", func() {
+			exit, _, err := instance.Call("call_get_last_timestamp", []byte("baduser"))
+			Expect(err).To(HaveOccurred())
+			Expect(exit).To(Equal(uint32(1)))
+		})
+
+		It("rejects scrobbles", func() {
+			exit, _, err := instance.Call("call_get_scrobbles", []byte(`{"username":"baduser"}`))
+			Expect(err).To(HaveOccurred())
+			Expect(exit).To(Equal(uint32(1)))
+		})
+
+		It("rejects scrobbles", func() {
+			exit, _, err := instance.Call("call_get_scrobbles_count", []byte(`{"username":"baduser"}`))
+			Expect(err).To(HaveOccurred())
+			Expect(exit).To(Equal(uint32(1)))
+		})
+	})
+
+	Describe("no items", func() {
+		It("calls get first timestamp", func() {
+			exit, output, err := instance.Call("call_get_first_timestamp", []byte("testuser"))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+
+			Expect(output).To(Equal([]byte("{\"timestamp\":null}")))
+		})
+
+		It("calls get last timestamp", func() {
+			exit, output, err := instance.Call("call_get_last_timestamp", []byte("testuser"))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+
+			Expect(output).To(Equal([]byte("{\"timestamp\":null}")))
+		})
+
+		It("calls scrobbles", func() {
+			exit, output, err := instance.Call("call_get_scrobbles", []byte(`{"username":"testuser"}`))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+
+			Expect(output).To(Equal([]byte(`{"scrobbles":[],"next":null}`)))
+		})
+
+		It("calls get scrobble count", func() {
+			exit, output, err := instance.Call("call_get_scrobbles_count", []byte(`{"username":"testuser"}`))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+			Expect(output).To(Equal([]byte("0")))
+		})
+	})
+
+	Describe("with items", func() {
+		scrobbles := []host.ScrobbleRef{
+			{ID: 1, MediaFileID: "1", SubmissionTime: 0},
+			{ID: 2, MediaFileID: "2", SubmissionTime: 1},
+			{ID: 3, MediaFileID: "3", SubmissionTime: 2},
+			{ID: 4, MediaFileID: "1", SubmissionTime: 2},
+		}
+
+		scrobblesReversed := make([]host.ScrobbleRef, 4)
+
+		BeforeAll(func() {
+			for idx := range scrobbles {
+				scrobblesReversed[3-idx] = scrobbles[idx]
+			}
+		})
+
+		It("calls get first timestamp", func() {
+			exit, output, err := instance.Call("call_get_first_timestamp", []byte("adminuser"))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+
+			Expect(output).To(Equal([]byte("{\"timestamp\":0}")))
+		})
+
+		It("calls get last timestamp", func() {
+			exit, output, err := instance.Call("call_get_last_timestamp", []byte("adminuser"))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+
+			Expect(output).To(Equal([]byte("{\"timestamp\":2}")))
+		})
+
+		DescribeTable("getScrobbles", func(params string, scrobbles []host.ScrobbleRef, next *host.ScrobbleOptions) {
+			exit, output, err := instance.Call("call_get_scrobbles", []byte(params))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+
+			var page scrobblePage
+			Expect(json.Unmarshal(output, &page)).To(Succeed())
+			Expect(page).To(Equal(scrobblePage{Scrobbles: scrobbles, Next: next}))
+		},
+			Entry("calls scrobbles in ascending order", `{"username":"adminuser"}`, scrobbles, nil),
+			Entry("calls scrobbles in descending order by request", `{"username":"adminuser","descending":true}`, scrobblesReversed, nil),
+			Entry("calls scrobbles in ascending order, beyond range", `{"username":"adminuser","fromTimestamp":-1, "toTimestamp": 1000}`, scrobbles, nil),
+			Entry("defaults to ascending even when only toTimestamp is given", `{"username":"adminuser","toTimestamp":2}`, scrobbles, nil),
+			Entry("calls subset of scrobbles in ascending order, next page", `{"username":"adminuser","maxItems":2}`, scrobbles[:2], opts(p(2), nil, false, 0, 2)),
+			Entry("calls subset of scrobbles in ascending order, next page with offset", `{"username":"adminuser","maxItems":2,"fromTimestamp":1}`, scrobbles[1:3], opts(p(2), nil, false, 1, 2)),
+			Entry("calls subset of scrobbles in ascending order, from and to timestamp", `{"username":"adminuser","toTimestamp":2,"fromTimestamp":1}`, scrobbles[1:], nil),
+			Entry("calls subset of scrobbles in descending order, from and to timestamp", `{"username":"adminuser","toTimestamp":2,"fromTimestamp":1,"descending":true}`, scrobblesReversed[:3], nil),
+			Entry("calls in reverse order, full", `{"username":"adminuser","toTimestamp":2,"descending":true}`, scrobblesReversed, nil),
+			Entry("calls in reverse order, with count", `{"username":"adminuser","toTimestamp":2,"descending":true, "maxItems": 3}`, scrobblesReversed[:3], opts(nil, p(0), true, 0, 3)),
+			Entry("calls in reverse order, with count of 1", `{"username":"adminuser","toTimestamp":2,"descending":true, "maxItems": 1}`, scrobblesReversed[:1], opts(nil, p(2), true, 1, 1)),
+		)
+
+		DescribeTable("GetScrobblesCount", func(params string, count int) {
+			exit, output, err := instance.Call("call_get_scrobbles_count", []byte(params))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+
+			value, err := strconv.ParseInt(string(output), 10, 64)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(value).To(Equal(int64(count)))
+		},
+			Entry("gets all scrobbles", `{"username":"adminuser"}`, 4),
+			Entry("gets two scrobbles ascending", `{"username":"adminuser", "fromTimestamp": 2}`, 2),
+			Entry("gets one scrobble descending", `{"username":"adminuser", "toTimestamp": 0}`, 1),
+			Entry("filters upper and bottom", `{"username":"adminuser", "fromTimestamp": 1, "toTimestamp": 1}`, 1),
+			Entry("accepts filter out of range", `{"username":"adminuser", "fromTimestamp": -1, "toTimestamp": 1000}`, 4),
+		)
+	})
+
+	Context("Complex edge cases - multiple scrobbles at the same timestamp", func() {
+		duplicates := make([]host.ScrobbleRef, 5)
+		duplicatesReversed := make([]host.ScrobbleRef, 5)
+
+		BeforeAll(func() {
+			scrobbleCtx := request.WithUser(GinkgoT().Context(), model.User{ID: "admin1", UserName: "adminuser"})
+
+			scrobbleRepo := dataStore.Scrobble(scrobbleCtx)
+
+			for i := range 5 {
+				err := scrobbleRepo.RecordScrobble("3", time.Unix(100, 0))
+				Expect(err).To(BeNil())
+
+				scrobble := host.ScrobbleRef{ID: 5 + int64(i), MediaFileID: "3", SubmissionTime: 100}
+				duplicates[i] = scrobble
+				duplicatesReversed[4-i] = scrobble
+			}
+		})
+
+		getPage := func(o host.ScrobbleOptions) scrobblePage {
+			GinkgoHelper()
+			payload, err := json.Marshal(struct {
+				Username      string `json:"username"`
+				FromTimestamp *int64 `json:"fromTimestamp,omitempty"`
+				ToTimestamp   *int64 `json:"toTimestamp,omitempty"`
+				Descending    bool   `json:"descending"`
+				Offset        int    `json:"offset,omitempty"`
+				MaxItems      int    `json:"maxItems"`
+			}{
+				Username:      "adminuser",
+				FromTimestamp: o.FromTimestamp,
+				ToTimestamp:   o.ToTimestamp,
+				Descending:    o.Descending,
+				Offset:        o.Offset,
+				MaxItems:      o.MaxItems,
+			})
+			Expect(err).ToNot(HaveOccurred())
+
+			exit, output, err := instance.Call("call_get_scrobbles", payload)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(exit).To(Equal(uint32(0)))
+
+			var page scrobblePage
+			Expect(json.Unmarshal(output, &page)).To(Succeed())
+			return page
+		}
+
+		// every scrobble here shares timestamp 100, so only Offset advances between pages
+		tied := func(offset, maxItems int, descending bool) host.ScrobbleOptions {
+			return *opts(p(100), p(100), descending, offset, maxItems)
+		}
+
+		DescribeTable("Edge cases; duplicate scrobbles", func(offset, count int, descending bool, scrobbles []host.ScrobbleRef, nextOffset *int) {
+			var next *host.ScrobbleOptions
+			if nextOffset != nil {
+				next = opts(p(100), p(100), descending, *nextOffset, count)
+			}
+			Expect(getPage(tied(offset, count, descending))).To(Equal(scrobblePage{Scrobbles: scrobbles, Next: next}))
+		},
+			Entry("All tracks, in order", 0, 100, false, duplicates, nil),
+			Entry("All tracks, in reverse order", 0, 100, true, duplicatesReversed, nil),
+			Entry("Ascending order, from the start", 0, 1, false, duplicates[:1], new(1)),
+			Entry("Ascending order, middle page", 1, 2, false, duplicates[1:3], new(3)),
+			Entry("Ascending order, to the end", 3, 100, false, duplicates[3:], nil),
+			Entry("Ascending order, from the start, continuing offset", 3, 1, false, duplicates[3:4], new(4)),
+			Entry("start descending", 0, 2, true, duplicatesReversed[:2], new(2)),
+			Entry("start descending, next step", 2, 2, true, duplicatesReversed[2:4], new(4)),
+			Entry("start descending, end", 4, 1, true, duplicatesReversed[4:], nil),
+		)
+
+		It("walks every page exactly once when all timestamps collide", func() {
+			for _, descending := range []bool{false, true} {
+				var seen []host.ScrobbleRef
+				o := tied(0, 2, descending)
+				var page scrobblePage
+				for range 10 {
+					page = getPage(o)
+					seen = append(seen, page.Scrobbles...)
+					if page.Next == nil {
+						break
+					}
+					o = *page.Next
+				}
+				Expect(page.Next).To(BeNil(), "pagination did not terminate")
+				if descending {
+					Expect(seen).To(Equal(duplicatesReversed))
+				} else {
+					Expect(seen).To(Equal(duplicates))
+				}
+			}
+		})
+	})
+})
diff --git a/plugins/manager_loader.go b/plugins/manager_loader.go
index 0e9e7bb62..439c944f5 100644
--- a/plugins/manager_loader.go
+++ b/plugins/manager_loader.go
@@ -177,6 +177,14 @@ var hostServices = []hostServiceEntry{
 			return host.RegisterStorageHostFunctions(service), nil, nil
 		},
 	},
+	{
+		name:          "ScrobbleRetriever",
+		hasPermission: func(p *Permissions) bool { return p != nil && p.ScrobbleRetriever != nil },
+		create: func(ctx *serviceContext) ([]extism.HostFunction, io.Closer, error) {
+			service := newScrobbleRetrieverService(ctx.manager.ds, newUserAccess(ctx.allowedUsers, ctx.allUsers))
+			return host.RegisterScrobbleRetrieverHostFunctions(service), nil, nil
+		},
+	},
 }
 
 // extractManifest reads manifest from an .ndp package and computes its SHA-256 hash.
diff --git a/plugins/manifest-schema.json b/plugins/manifest-schema.json
index 736677313..dae0fd937 100644
--- a/plugins/manifest-schema.json
+++ b/plugins/manifest-schema.json
@@ -95,6 +95,9 @@
         },
         "storage": {
           "$ref": "#/$defs/StoragePermission"
+        },
+        "scrobbleRetriever": {
+          "$ref": "#/$defs/ScrobbleRetrieverPermission"
         }
       }
     },
@@ -258,6 +261,17 @@
           "description": "Explanation for why storage access is needed"
         }
       }
+    },
+    "ScrobbleRetrieverPermission": {
+      "type": "object",
+      "description": "Scrobble retriever permissions for retrieving scrobbles from users",
+      "additionalProperties": false,
+      "properties": {
+        "reason": {
+          "type": "string",
+          "description": "Explanation for why scrobble retriever access is needed"
+        }
+      }
     }
   }
 }
diff --git a/plugins/manifest.go b/plugins/manifest.go
index ef70e8d9d..5c0d91f51 100644
--- a/plugins/manifest.go
+++ b/plugins/manifest.go
@@ -53,10 +53,14 @@ func ParseManifest(data []byte) (*Manifest, error) {
 // This validates rules like "SubsonicAPI permission requires users permission".
 func (m *Manifest) Validate() error {
 	// SubsonicAPI permission requires users permission
-	if m.Permissions != nil && m.Permissions.Subsonicapi != nil {
-		if m.Permissions.Users == nil {
+	if m.Permissions != nil && m.Permissions.Users == nil {
+		if m.Permissions.Subsonicapi != nil {
 			return fmt.Errorf("'subsonicapi' permission requires 'users' permission to be declared")
 		}
+
+		if m.Permissions.ScrobbleRetriever != nil {
+			return fmt.Errorf("'scrobbleRetriever' permission requires 'users' permission to be declared")
+		}
 	}
 
 	// Matcher returns library content, so it requires the library permission (which
diff --git a/plugins/manifest_gen.go b/plugins/manifest_gen.go
index 5e0035bd5..6f5c01596 100644
--- a/plugins/manifest_gen.go
+++ b/plugins/manifest_gen.go
@@ -178,6 +178,9 @@ type Permissions struct {
 	// Scheduler corresponds to the JSON schema field "scheduler".
 	Scheduler *SchedulerPermission `json:"scheduler,omitempty" yaml:"scheduler,omitempty" mapstructure:"scheduler,omitempty"`
 
+	// ScrobbleRetriever corresponds to the JSON schema field "scrobbleRetriever".
+	ScrobbleRetriever *ScrobbleRetrieverPermission `json:"scrobbleRetriever,omitempty" yaml:"scrobbleRetriever,omitempty" mapstructure:"scrobbleRetriever,omitempty"`
+
 	// Storage corresponds to the JSON schema field "storage".
 	Storage *StoragePermission `json:"storage,omitempty" yaml:"storage,omitempty" mapstructure:"storage,omitempty"`
 
@@ -200,6 +203,12 @@ type SchedulerPermission struct {
 	Reason *string `json:"reason,omitempty" yaml:"reason,omitempty" mapstructure:"reason,omitempty"`
 }
 
+// Scrobble retriever permissions for retrieving scrobbles from users
+type ScrobbleRetrieverPermission struct {
+	// Explanation for why scrobble retriever access is needed
+	Reason *string `json:"reason,omitempty" yaml:"reason,omitempty" mapstructure:"reason,omitempty"`
+}
+
 // Storage permissions for enabling persistent read-write storage exclusively for
 // the plugin
 type StoragePermission struct {
diff --git a/plugins/manifest_test.go b/plugins/manifest_test.go
index 32bcbba08..bfd8bcac1 100644
--- a/plugins/manifest_test.go
+++ b/plugins/manifest_test.go
@@ -222,6 +222,36 @@ var _ = Describe("Manifest", func() {
 			Expect(err.Error()).To(ContainSubstring("library"))
 		})
 
+		It("validates manifest with scrobbleRetriever and users permissions", func() {
+			m := &Manifest{
+				Name:    "Test",
+				Author:  "Author",
+				Version: "1.0.0",
+				Permissions: &Permissions{
+					ScrobbleRetriever: &ScrobbleRetrieverPermission{},
+					Users:             &UsersPermission{},
+				},
+			}
+
+			err := m.Validate()
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("returns error when scrobbleRetriever without users permission", func() {
+			m := &Manifest{
+				Name:    "Test",
+				Author:  "Author",
+				Version: "1.0.0",
+				Permissions: &Permissions{
+					ScrobbleRetriever: &ScrobbleRetrieverPermission{},
+				},
+			}
+
+			err := m.Validate()
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("scrobbleRetriever"))
+		})
+
 		It("validates manifest without subsonicapi", func() {
 			m := &Manifest{
 				Name:    "Test",
diff --git a/plugins/pdk/go/host/doc.go b/plugins/pdk/go/host/doc.go
index e4157e29c..9063f2bd0 100644
--- a/plugins/pdk/go/host/doc.go
+++ b/plugins/pdk/go/host/doc.go
@@ -43,6 +43,7 @@ The following host services are available:
   - Library: provides access to music library metadata for plugins.
   - Matcher: resolves externally-obtained songs to local library tracks,
   - Scheduler: provides task scheduling capabilities for plugins.
+  - ScrobbleRetriever: allows a plugin to retrieve scrobbles for one or more authorized users.
   - Storage: provides access to a plugin-specific directory with read/write permissions
   - SubsonicAPI: provides access to Navidrome's Subsonic API from plugins.
   - Task: provides persistent task queues for plugins.
diff --git a/plugins/pdk/go/host/nd_host_scrobbleretriever.go b/plugins/pdk/go/host/nd_host_scrobbleretriever.go
new file mode 100644
index 000000000..596d7ec1d
--- /dev/null
+++ b/plugins/pdk/go/host/nd_host_scrobbleretriever.go
@@ -0,0 +1,266 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains client wrappers for the ScrobbleRetriever host service.
+// It is intended for use in Navidrome plugins built with TinyGo.
+//
+//go:build wasip1
+
+package host
+
+import (
+	"encoding/json"
+	"errors"
+
+	"github.com/navidrome/navidrome/plugins/pdk/go/pdk"
+)
+
+// ScrobbleCountOptions represents the ScrobbleCountOptions data structure.
+// ScrobbleCountOptions carries optional parameters for counting user scrobbles
+type ScrobbleCountOptions struct {
+	FromTimestamp *int64 `json:"fromTimestamp"`
+	ToTimestamp   *int64 `json:"toTimestamp"`
+}
+
+// ScrobbleOptions represents the ScrobbleOptions data structure.
+// ScrobbleOptions carries optional parameters for retrieving user scrobbles
+type ScrobbleOptions struct {
+	FromTimestamp *int64 `json:"fromTimestamp"`
+	ToTimestamp   *int64 `json:"toTimestamp"`
+	Descending    bool   `json:"descending"`
+	MaxItems      int    `json:"maxItems"`
+	Offset        int    `json:"offset"`
+}
+
+// ScrobbleRef represents the ScrobbleRef data structure.
+// ScrobbleRef represents one instance of a scrobble (instance id, file id, submission time)
+type ScrobbleRef struct {
+	ID             int64  `json:"id"`
+	MediaFileID    string `json:"mediaFileId"`
+	SubmissionTime int64  `json:"submissionTime"`
+}
+
+// scrobbleretriever_getfirsttimestamp is the host function provided by Navidrome.
+//
+//go:wasmimport extism:host/user scrobbleretriever_getfirsttimestamp
+func scrobbleretriever_getfirsttimestamp(uint64) uint64
+
+// scrobbleretriever_getlasttimestamp is the host function provided by Navidrome.
+//
+//go:wasmimport extism:host/user scrobbleretriever_getlasttimestamp
+func scrobbleretriever_getlasttimestamp(uint64) uint64
+
+// scrobbleretriever_getscrobbles is the host function provided by Navidrome.
+//
+//go:wasmimport extism:host/user scrobbleretriever_getscrobbles
+func scrobbleretriever_getscrobbles(uint64) uint64
+
+// scrobbleretriever_getscrobblecount is the host function provided by Navidrome.
+//
+//go:wasmimport extism:host/user scrobbleretriever_getscrobblecount
+func scrobbleretriever_getscrobblecount(uint64) uint64
+
+type scrobbleRetrieverGetFirstTimestampRequest struct {
+	Username string `json:"username"`
+}
+
+type scrobbleRetrieverGetFirstTimestampResponse struct {
+	Result *int64 `json:"result,omitempty"`
+	Error  string `json:"error,omitempty"`
+}
+
+type scrobbleRetrieverGetLastTimestampRequest struct {
+	Username string `json:"username"`
+}
+
+type scrobbleRetrieverGetLastTimestampResponse struct {
+	Result *int64 `json:"result,omitempty"`
+	Error  string `json:"error,omitempty"`
+}
+
+type scrobbleRetrieverGetScrobblesRequest struct {
+	Username string          `json:"username"`
+	Options  ScrobbleOptions `json:"options"`
+}
+
+type scrobbleRetrieverGetScrobblesResponse struct {
+	Scrobbles []ScrobbleRef    `json:"scrobbles,omitempty"`
+	Next      *ScrobbleOptions `json:"next,omitempty"`
+	Error     string           `json:"error,omitempty"`
+}
+
+type scrobbleRetrieverGetScrobbleCountRequest struct {
+	Username string               `json:"username"`
+	Options  ScrobbleCountOptions `json:"options"`
+}
+
+type scrobbleRetrieverGetScrobbleCountResponse struct {
+	Result int64  `json:"result,omitempty"`
+	Error  string `json:"error,omitempty"`
+}
+
+// ScrobbleRetrieverGetFirstTimestamp calls the scrobbleretriever_getfirsttimestamp host function.
+// GetFirstTimestamp returns the unix timestamp of the oldest scrobble for the user.
+// If the user has no scrobbles, returns nil
+func ScrobbleRetrieverGetFirstTimestamp(username string) (*int64, error) {
+	// Marshal request to JSON
+	req := scrobbleRetrieverGetFirstTimestampRequest{
+		Username: username,
+	}
+	reqBytes, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	reqMem := pdk.AllocateBytes(reqBytes)
+	defer reqMem.Free()
+
+	// Call the host function
+	responsePtr := scrobbleretriever_getfirsttimestamp(reqMem.Offset())
+
+	// Read the response from memory
+	responseMem := pdk.FindMemory(responsePtr)
+	responseBytes := responseMem.ReadBytes()
+
+	// Parse the response
+	var response scrobbleRetrieverGetFirstTimestampResponse
+	if err := json.Unmarshal(responseBytes, &response); err != nil {
+		return nil, err
+	}
+
+	// Convert Error field to Go error
+	if response.Error != "" {
+		return nil, errors.New(response.Error)
+	}
+
+	return response.Result, nil
+}
+
+// ScrobbleRetrieverGetLastTimestamp calls the scrobbleretriever_getlasttimestamp host function.
+// GetLastTimestamp returns the unix timestamp of the most recent scrobble for the user
+// If the user has no scrobbles, return nil
+func ScrobbleRetrieverGetLastTimestamp(username string) (*int64, error) {
+	// Marshal request to JSON
+	req := scrobbleRetrieverGetLastTimestampRequest{
+		Username: username,
+	}
+	reqBytes, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	reqMem := pdk.AllocateBytes(reqBytes)
+	defer reqMem.Free()
+
+	// Call the host function
+	responsePtr := scrobbleretriever_getlasttimestamp(reqMem.Offset())
+
+	// Read the response from memory
+	responseMem := pdk.FindMemory(responsePtr)
+	responseBytes := responseMem.ReadBytes()
+
+	// Parse the response
+	var response scrobbleRetrieverGetLastTimestampResponse
+	if err := json.Unmarshal(responseBytes, &response); err != nil {
+		return nil, err
+	}
+
+	// Convert Error field to Go error
+	if response.Error != "" {
+		return nil, errors.New(response.Error)
+	}
+
+	return response.Result, nil
+}
+
+// ScrobbleRetrieverGetScrobbles calls the scrobbleretriever_getscrobbles host function.
+// GetScrobbles returns one page of scrobbles for a user.
+//
+// Parameters:
+//   - username: the user to query for scrobbles
+//   - options.FromTimestamp: If specified, the first UNIX timestamp to start fetching scrobbles (inclusive). Otherwise, start from the first scrobble
+//   - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble
+//   - options.Descending: If true, order from newest to oldest. Otherwise, oldest to newest
+//   - options.MaxItems: The maximum number of items to retrieve. The maximum value (and default) if not specified is 5000
+//   - options.Offset: Pagination state; only valid as received on the options returned by a previous call. Never set it manually
+//
+// Returns:
+//   - scrobbles: The scrobbles in the requested range, ordered by submission time
+//     (ties broken by scrobble ID) in the direction given by options.Descending
+//   - next: The options for the following page, or nil once no scrobbles remain.
+//     Pass it back to GetScrobbles unchanged and repeat until it is nil. It carries an
+//     adjusted FromTimestamp/ToTimestamp, so keep a copy if you still need the original range
+func ScrobbleRetrieverGetScrobbles(username string, options ScrobbleOptions) ([]ScrobbleRef, *ScrobbleOptions, error) {
+	// Marshal request to JSON
+	req := scrobbleRetrieverGetScrobblesRequest{
+		Username: username,
+		Options:  options,
+	}
+	reqBytes, err := json.Marshal(req)
+	if err != nil {
+		return nil, nil, err
+	}
+	reqMem := pdk.AllocateBytes(reqBytes)
+	defer reqMem.Free()
+
+	// Call the host function
+	responsePtr := scrobbleretriever_getscrobbles(reqMem.Offset())
+
+	// Read the response from memory
+	responseMem := pdk.FindMemory(responsePtr)
+	responseBytes := responseMem.ReadBytes()
+
+	// Parse the response
+	var response scrobbleRetrieverGetScrobblesResponse
+	if err := json.Unmarshal(responseBytes, &response); err != nil {
+		return nil, nil, err
+	}
+
+	// Convert Error field to Go error
+	if response.Error != "" {
+		return nil, nil, errors.New(response.Error)
+	}
+
+	return response.Scrobbles, response.Next, nil
+}
+
+// ScrobbleRetrieverGetScrobbleCount calls the scrobbleretriever_getscrobblecount host function.
+// GetScrobbleCount returns the number of scrobbles for a user in a given range
+//
+// Parameters:
+//   - username: the user to query for scrobbles
+//   - options.FromTimestamp: If specified, the first UNIX timestamp to start fetching scrobbles (inclusive). Otherwise, start from the first scrobble
+//   - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble
+//
+// Returns:
+//   - the number of scrobbles in the given range, or 0
+func ScrobbleRetrieverGetScrobbleCount(username string, options ScrobbleCountOptions) (int64, error) {
+	// Marshal request to JSON
+	req := scrobbleRetrieverGetScrobbleCountRequest{
+		Username: username,
+		Options:  options,
+	}
+	reqBytes, err := json.Marshal(req)
+	if err != nil {
+		return 0, err
+	}
+	reqMem := pdk.AllocateBytes(reqBytes)
+	defer reqMem.Free()
+
+	// Call the host function
+	responsePtr := scrobbleretriever_getscrobblecount(reqMem.Offset())
+
+	// Read the response from memory
+	responseMem := pdk.FindMemory(responsePtr)
+	responseBytes := responseMem.ReadBytes()
+
+	// Parse the response
+	var response scrobbleRetrieverGetScrobbleCountResponse
+	if err := json.Unmarshal(responseBytes, &response); err != nil {
+		return 0, err
+	}
+
+	// Convert Error field to Go error
+	if response.Error != "" {
+		return 0, errors.New(response.Error)
+	}
+
+	return response.Result, nil
+}
diff --git a/plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go b/plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go
new file mode 100644
index 000000000..a75fcebb5
--- /dev/null
+++ b/plugins/pdk/go/host/nd_host_scrobbleretriever_stub.go
@@ -0,0 +1,136 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains mock implementations for non-WASM builds.
+// These mocks allow IDE support, compilation, and unit testing on non-WASM platforms.
+// Plugin authors can use the exported mock instances to set expectations in tests.
+//
+//go:build !wasip1
+
+package host
+
+import (
+	"github.com/stretchr/testify/mock"
+)
+
+// ScrobbleCountOptions represents the ScrobbleCountOptions data structure.
+// ScrobbleCountOptions carries optional parameters for counting user scrobbles
+type ScrobbleCountOptions struct {
+	FromTimestamp *int64 `json:"fromTimestamp"`
+	ToTimestamp   *int64 `json:"toTimestamp"`
+}
+
+// ScrobbleOptions represents the ScrobbleOptions data structure.
+// ScrobbleOptions carries optional parameters for retrieving user scrobbles
+type ScrobbleOptions struct {
+	FromTimestamp *int64 `json:"fromTimestamp"`
+	ToTimestamp   *int64 `json:"toTimestamp"`
+	Descending    bool   `json:"descending"`
+	MaxItems      int    `json:"maxItems"`
+	Offset        int    `json:"offset"`
+}
+
+// ScrobbleRef represents the ScrobbleRef data structure.
+// ScrobbleRef represents one instance of a scrobble (instance id, file id, submission time)
+type ScrobbleRef struct {
+	ID             int64  `json:"id"`
+	MediaFileID    string `json:"mediaFileId"`
+	SubmissionTime int64  `json:"submissionTime"`
+}
+
+// mockScrobbleRetrieverService is the mock implementation for testing.
+type mockScrobbleRetrieverService struct {
+	mock.Mock
+}
+
+// ScrobbleRetrieverMock is the auto-instantiated mock instance for testing.
+// Use this to set expectations: host.ScrobbleRetrieverMock.On("MethodName", args...).Return(values...)
+var ScrobbleRetrieverMock = &mockScrobbleRetrieverService{}
+
+// GetFirstTimestamp is the mock method for ScrobbleRetrieverGetFirstTimestamp.
+func (m *mockScrobbleRetrieverService) GetFirstTimestamp(username string) (*int64, error) {
+	args := m.Called(username)
+	var r0 *int64
+	if v := args.Get(0); v != nil {
+		r0 = v.(*int64)
+	}
+	return r0, args.Error(1)
+}
+
+// ScrobbleRetrieverGetFirstTimestamp delegates to the mock instance.
+// GetFirstTimestamp returns the unix timestamp of the oldest scrobble for the user.
+// If the user has no scrobbles, returns nil
+func ScrobbleRetrieverGetFirstTimestamp(username string) (*int64, error) {
+	return ScrobbleRetrieverMock.GetFirstTimestamp(username)
+}
+
+// GetLastTimestamp is the mock method for ScrobbleRetrieverGetLastTimestamp.
+func (m *mockScrobbleRetrieverService) GetLastTimestamp(username string) (*int64, error) {
+	args := m.Called(username)
+	var r0 *int64
+	if v := args.Get(0); v != nil {
+		r0 = v.(*int64)
+	}
+	return r0, args.Error(1)
+}
+
+// ScrobbleRetrieverGetLastTimestamp delegates to the mock instance.
+// GetLastTimestamp returns the unix timestamp of the most recent scrobble for the user
+// If the user has no scrobbles, return nil
+func ScrobbleRetrieverGetLastTimestamp(username string) (*int64, error) {
+	return ScrobbleRetrieverMock.GetLastTimestamp(username)
+}
+
+// GetScrobbles is the mock method for ScrobbleRetrieverGetScrobbles.
+func (m *mockScrobbleRetrieverService) GetScrobbles(username string, options ScrobbleOptions) ([]ScrobbleRef, *ScrobbleOptions, error) {
+	args := m.Called(username, options)
+	var r0 []ScrobbleRef
+	if v := args.Get(0); v != nil {
+		r0 = v.([]ScrobbleRef)
+	}
+	var r1 *ScrobbleOptions
+	if v := args.Get(1); v != nil {
+		r1 = v.(*ScrobbleOptions)
+	}
+	return r0, r1, args.Error(2)
+}
+
+// ScrobbleRetrieverGetScrobbles delegates to the mock instance.
+// GetScrobbles returns one page of scrobbles for a user.
+//
+// Parameters:
+//   - username: the user to query for scrobbles
+//   - options.FromTimestamp: If specified, the first UNIX timestamp to start fetching scrobbles (inclusive). Otherwise, start from the first scrobble
+//   - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble
+//   - options.Descending: If true, order from newest to oldest. Otherwise, oldest to newest
+//   - options.MaxItems: The maximum number of items to retrieve. The maximum value (and default) if not specified is 5000
+//   - options.Offset: Pagination state; only valid as received on the options returned by a previous call. Never set it manually
+//
+// Returns:
+//   - scrobbles: The scrobbles in the requested range, ordered by submission time
+//     (ties broken by scrobble ID) in the direction given by options.Descending
+//   - next: The options for the following page, or nil once no scrobbles remain.
+//     Pass it back to GetScrobbles unchanged and repeat until it is nil. It carries an
+//     adjusted FromTimestamp/ToTimestamp, so keep a copy if you still need the original range
+func ScrobbleRetrieverGetScrobbles(username string, options ScrobbleOptions) ([]ScrobbleRef, *ScrobbleOptions, error) {
+	return ScrobbleRetrieverMock.GetScrobbles(username, options)
+}
+
+// GetScrobbleCount is the mock method for ScrobbleRetrieverGetScrobbleCount.
+func (m *mockScrobbleRetrieverService) GetScrobbleCount(username string, options ScrobbleCountOptions) (int64, error) {
+	args := m.Called(username, options)
+	return args.Get(0).(int64), args.Error(1)
+}
+
+// ScrobbleRetrieverGetScrobbleCount delegates to the mock instance.
+// GetScrobbleCount returns the number of scrobbles for a user in a given range
+//
+// Parameters:
+//   - username: the user to query for scrobbles
+//   - options.FromTimestamp: If specified, the first UNIX timestamp to start fetching scrobbles (inclusive). Otherwise, start from the first scrobble
+//   - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble
+//
+// Returns:
+//   - the number of scrobbles in the given range, or 0
+func ScrobbleRetrieverGetScrobbleCount(username string, options ScrobbleCountOptions) (int64, error) {
+	return ScrobbleRetrieverMock.GetScrobbleCount(username, options)
+}
diff --git a/plugins/pdk/rust/nd-pdk-host/src/lib.rs b/plugins/pdk/rust/nd-pdk-host/src/lib.rs
index 3da023f5c..33cbe7725 100644
--- a/plugins/pdk/rust/nd-pdk-host/src/lib.rs
+++ b/plugins/pdk/rust/nd-pdk-host/src/lib.rs
@@ -40,6 +40,7 @@
 //! - [`library`] - provides access to music library metadata for plugins.
 //! - [`matcher`] - resolves externally-obtained songs to local library tracks,
 //! - [`scheduler`] - provides task scheduling capabilities for plugins.
+//! - [`scrobbleretriever`] - allows a plugin to retrieve scrobbles for one or more authorized users.
 //! - [`storage`] - provides access to a plugin-specific directory with read/write permissions
 //! - [`subsonicapi`] - provides access to Navidrome's Subsonic API from plugins.
 //! - [`task`] - provides persistent task queues for plugins.
@@ -102,6 +103,13 @@ pub mod scheduler {
     pub use super::nd_host_scheduler::*;
 }
 
+#[doc(hidden)]
+mod nd_host_scrobbleretriever;
+/// allows a plugin to retrieve scrobbles for one or more authorized users.
+pub mod scrobbleretriever {
+    pub use super::nd_host_scrobbleretriever::*;
+}
+
 #[doc(hidden)]
 mod nd_host_storage;
 /// provides access to a plugin-specific directory with read/write permissions
diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs
new file mode 100644
index 000000000..fe80d98f6
--- /dev/null
+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs
@@ -0,0 +1,237 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains client wrappers for the ScrobbleRetriever host service.
+// It is intended for use in Navidrome plugins built with extism-pdk.
+
+use extism_pdk::*;
+use serde::{Deserialize, Serialize};
+
+/// ScrobbleCountOptions carries optional parameters for counting user scrobbles
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ScrobbleCountOptions {
+    #[serde(default)]
+    pub from_timestamp: Option<i64>,
+    #[serde(default)]
+    pub to_timestamp: Option<i64>,
+}
+
+/// ScrobbleOptions carries optional parameters for retrieving user scrobbles
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ScrobbleOptions {
+    #[serde(default)]
+    pub from_timestamp: Option<i64>,
+    #[serde(default)]
+    pub to_timestamp: Option<i64>,
+    pub descending: bool,
+    pub max_items: i32,
+    #[serde(default)]
+    pub offset: i32,
+}
+
+/// ScrobbleRef represents one instance of a scrobble (instance id, file id, submission time)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ScrobbleRef {
+    pub id: i64,
+    pub media_file_id: String,
+    pub submission_time: i64,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ScrobbleRetrieverGetFirstTimestampRequest {
+    username: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ScrobbleRetrieverGetFirstTimestampResponse {
+    #[serde(default)]
+    result: Option<i64>,
+    #[serde(default)]
+    error: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ScrobbleRetrieverGetLastTimestampRequest {
+    username: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ScrobbleRetrieverGetLastTimestampResponse {
+    #[serde(default)]
+    result: Option<i64>,
+    #[serde(default)]
+    error: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ScrobbleRetrieverGetScrobblesRequest {
+    username: String,
+    options: ScrobbleOptions,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ScrobbleRetrieverGetScrobblesResponse {
+    #[serde(default)]
+    scrobbles: Vec<ScrobbleRef>,
+    #[serde(default)]
+    next: Option<ScrobbleOptions>,
+    #[serde(default)]
+    error: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ScrobbleRetrieverGetScrobbleCountRequest {
+    username: String,
+    options: ScrobbleCountOptions,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ScrobbleRetrieverGetScrobbleCountResponse {
+    #[serde(default)]
+    result: i64,
+    #[serde(default)]
+    error: Option<String>,
+}
+
+#[host_fn]
+extern "ExtismHost" {
+    fn scrobbleretriever_getfirsttimestamp(input: Json<ScrobbleRetrieverGetFirstTimestampRequest>) -> Json<ScrobbleRetrieverGetFirstTimestampResponse>;
+    fn scrobbleretriever_getlasttimestamp(input: Json<ScrobbleRetrieverGetLastTimestampRequest>) -> Json<ScrobbleRetrieverGetLastTimestampResponse>;
+    fn scrobbleretriever_getscrobbles(input: Json<ScrobbleRetrieverGetScrobblesRequest>) -> Json<ScrobbleRetrieverGetScrobblesResponse>;
+    fn scrobbleretriever_getscrobblecount(input: Json<ScrobbleRetrieverGetScrobbleCountRequest>) -> Json<ScrobbleRetrieverGetScrobbleCountResponse>;
+}
+
+/// GetFirstTimestamp returns the unix timestamp of the oldest scrobble for the user.
+/// If the user has no scrobbles, returns nil
+///
+/// # Arguments
+/// * `username` - String parameter.
+///
+/// # Returns
+/// The result value.
+///
+/// # Errors
+/// Returns an error if the host function call fails.
+pub fn get_first_timestamp(username: &str) -> Result<Option<i64>, Error> {
+    let response = unsafe {
+        scrobbleretriever_getfirsttimestamp(Json(ScrobbleRetrieverGetFirstTimestampRequest {
+            username: username.to_owned(),
+        }))?
+    };
+
+    if let Some(err) = response.0.error {
+        return Err(Error::msg(err));
+    }
+
+    Ok(response.0.result)
+}
+
+/// GetLastTimestamp returns the unix timestamp of the most recent scrobble for the user
+/// If the user has no scrobbles, return nil
+///
+/// # Arguments
+/// * `username` - String parameter.
+///
+/// # Returns
+/// The result value.
+///
+/// # Errors
+/// Returns an error if the host function call fails.
+pub fn get_last_timestamp(username: &str) -> Result<Option<i64>, Error> {
+    let response = unsafe {
+        scrobbleretriever_getlasttimestamp(Json(ScrobbleRetrieverGetLastTimestampRequest {
+            username: username.to_owned(),
+        }))?
+    };
+
+    if let Some(err) = response.0.error {
+        return Err(Error::msg(err));
+    }
+
+    Ok(response.0.result)
+}
+
+/// GetScrobbles returns one page of scrobbles for a user.
+/// 
+/// Parameters:
+///   - username: the user to query for scrobbles
+///   - options.FromTimestamp: If specified, the first UNIX timestamp to start fetching scrobbles (inclusive). Otherwise, start from the first scrobble
+///   - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble
+///   - options.Descending: If true, order from newest to oldest. Otherwise, oldest to newest
+///   - options.MaxItems: The maximum number of items to retrieve. The maximum value (and default) if not specified is 5000
+///   - options.Offset: Pagination state; only valid as received on the options returned by a previous call. Never set it manually
+/// 
+/// Returns:
+///   - scrobbles: The scrobbles in the requested range, ordered by submission time
+///     (ties broken by scrobble ID) in the direction given by options.Descending
+///   - next: The options for the following page, or nil once no scrobbles remain.
+///     Pass it back to GetScrobbles unchanged and repeat until it is nil. It carries an
+///     adjusted FromTimestamp/ToTimestamp, so keep a copy if you still need the original range
+///
+/// # Arguments
+/// * `username` - String parameter.
+/// * `options` - ScrobbleOptions parameter.
+///
+/// # Returns
+/// A tuple of (scrobbles, next).
+///
+/// # Errors
+/// Returns an error if the host function call fails.
+pub fn get_scrobbles(username: &str, options: ScrobbleOptions) -> Result<(Vec<ScrobbleRef>, Option<ScrobbleOptions>), Error> {
+    let response = unsafe {
+        scrobbleretriever_getscrobbles(Json(ScrobbleRetrieverGetScrobblesRequest {
+            username: username.to_owned(),
+            options: options,
+        }))?
+    };
+
+    if let Some(err) = response.0.error {
+        return Err(Error::msg(err));
+    }
+
+    Ok((response.0.scrobbles, response.0.next))
+}
+
+/// GetScrobbleCount returns the number of scrobbles for a user in a given range
+/// 
+/// Parameters:
+///   - username: the user to query for scrobbles
+///   - options.FromTimestamp: If specified, the first UNIX timestamp to start fetching scrobbles (inclusive). Otherwise, start from the first scrobble
+///   - options.ToTimestamp: If specified, the last UNIX timestamp to fetch (inclusive). Otherwise, end at the last scrobble
+/// 
+/// Returns:
+///   - the number of scrobbles in the given range, or 0
+///
+/// # Arguments
+/// * `username` - String parameter.
+/// * `options` - ScrobbleCountOptions parameter.
+///
+/// # Returns
+/// The result value.
+///
+/// # Errors
+/// Returns an error if the host function call fails.
+pub fn get_scrobble_count(username: &str, options: ScrobbleCountOptions) -> Result<i64, Error> {
+    let response = unsafe {
+        scrobbleretriever_getscrobblecount(Json(ScrobbleRetrieverGetScrobbleCountRequest {
+            username: username.to_owned(),
+            options: options,
+        }))?
+    };
+
+    if let Some(err) = response.0.error {
+        return Err(Error::msg(err));
+    }
+
+    Ok(response.0.result)
+}
diff --git a/plugins/testdata/test-scrobble-retriever/go.mod b/plugins/testdata/test-scrobble-retriever/go.mod
new file mode 100644
index 000000000..59486d796
--- /dev/null
+++ b/plugins/testdata/test-scrobble-retriever/go.mod
@@ -0,0 +1,16 @@
+module test-scrobble-retriever
+
+go 1.25
+
+require github.com/navidrome/navidrome/plugins/pdk/go v0.0.0
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/extism/go-pdk v1.1.3 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/navidrome/navidrome/plugins/pdk/go => ../../pdk/go
diff --git a/plugins/testdata/test-scrobble-retriever/go.sum b/plugins/testdata/test-scrobble-retriever/go.sum
new file mode 100644
index 000000000..af880eb51
--- /dev/null
+++ b/plugins/testdata/test-scrobble-retriever/go.sum
@@ -0,0 +1,14 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/extism/go-pdk v1.1.3 h1:hfViMPWrqjN6u67cIYRALZTZLk/enSPpNKa+rZ9X2SQ=
+github.com/extism/go-pdk v1.1.3/go.mod h1:Gz+LIU/YCKnKXhgge8yo5Yu1F/lbv7KtKFkiCSzW/P4=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/plugins/testdata/test-scrobble-retriever/main.go b/plugins/testdata/test-scrobble-retriever/main.go
new file mode 100644
index 000000000..cc824acb9
--- /dev/null
+++ b/plugins/testdata/test-scrobble-retriever/main.go
@@ -0,0 +1,120 @@
+package main
+
+import (
+	"strconv"
+
+	"github.com/navidrome/navidrome/plugins/pdk/go/host"
+	"github.com/navidrome/navidrome/plugins/pdk/go/pdk"
+)
+
+func main() {
+
+}
+
+type TestScrobbleTimestampOutput struct {
+	Timestamp *int64 `json:"timestamp"`
+}
+
+//go:wasmexport call_get_first_timestamp
+func callGetFirstTimestamp() int32 {
+	username := pdk.InputString()
+
+	time, err := host.ScrobbleRetrieverGetFirstTimestamp(username)
+	if err != nil {
+		pdk.SetErrorString("failed to call scrobble retriever api " + err.Error())
+		return 1
+	}
+
+	pdk.OutputJSON(TestScrobbleTimestampOutput{Timestamp: time})
+	return 0
+}
+
+//go:wasmexport call_get_last_timestamp
+func callGetLastTimestamp() int32 {
+	username := pdk.InputString()
+
+	time, err := host.ScrobbleRetrieverGetLastTimestamp(username)
+	if err != nil {
+		pdk.SetErrorString("failed to call scrobble retriever api " + err.Error())
+		return 1
+	}
+
+	pdk.OutputJSON(TestScrobbleTimestampOutput{Timestamp: time})
+	return 0
+}
+
+type TestScrobbleOptions struct {
+	Username      string `json:"username"`
+	FromTimestamp *int64 `json:"fromTimestamp,omitempty"`
+	ToTimestamp   *int64 `json:"toTimestamp,omitempty"`
+	Descending    bool   `json:"descending"`
+	Offset        int    `json:"offset,omitempty"`
+	MaxItems      int    `json:"maxItems"`
+}
+
+// TestScrobblePage mirrors the multi-return shape so tests can assert on both values
+type TestScrobblePage struct {
+	Scrobbles []host.ScrobbleRef    `json:"scrobbles"`
+	Next      *host.ScrobbleOptions `json:"next"`
+}
+
+//go:wasmexport call_get_scrobbles
+func callGetScrobbles() int32 {
+	var options TestScrobbleOptions
+	err := pdk.InputJSON(&options)
+
+	if err != nil {
+		pdk.SetErrorString("failed to deserialize input " + err.Error())
+		return 1
+	}
+
+	scrobbles, next, err := host.ScrobbleRetrieverGetScrobbles(options.Username, host.ScrobbleOptions{
+		FromTimestamp: options.FromTimestamp,
+		ToTimestamp:   options.ToTimestamp,
+		MaxItems:      options.MaxItems,
+		Descending:    options.Descending,
+		Offset:        options.Offset,
+	})
+
+	if err != nil {
+		pdk.SetErrorString("failed to call scrobble retriever api " + err.Error())
+		return 1
+	}
+
+	if scrobbles == nil {
+		scrobbles = []host.ScrobbleRef{}
+	}
+
+	pdk.OutputJSON(TestScrobblePage{Scrobbles: scrobbles, Next: next})
+	return 0
+}
+
+type TestScrobbleCountOptions struct {
+	Username      string `json:"username"`
+	FromTimestamp *int64 `json:"fromTimestamp,omitempty"`
+	ToTimestamp   *int64 `json:"toTimestamp,omitempty"`
+}
+
+//go:wasmexport call_get_scrobbles_count
+func callGetScrobblesCount() int32 {
+	var options TestScrobbleOptions
+	err := pdk.InputJSON(&options)
+
+	if err != nil {
+		pdk.SetErrorString("failed to deserialize input " + err.Error())
+		return 1
+	}
+
+	count, err := host.ScrobbleRetrieverGetScrobbleCount(options.Username, host.ScrobbleCountOptions{
+		FromTimestamp: options.FromTimestamp,
+		ToTimestamp:   options.ToTimestamp,
+	})
+
+	if err != nil {
+		pdk.SetErrorString("failed to call scrobble retriever api " + err.Error())
+		return 1
+	}
+
+	pdk.OutputString(strconv.FormatInt(count, 10))
+	return 0
+}
diff --git a/plugins/testdata/test-scrobble-retriever/manifest.json b/plugins/testdata/test-scrobble-retriever/manifest.json
new file mode 100644
index 000000000..a60203704
--- /dev/null
+++ b/plugins/testdata/test-scrobble-retriever/manifest.json
@@ -0,0 +1,14 @@
+{
+  "name": "Test Scrobble Retriever",
+  "author": "Navidrome Test",
+  "version": "1.0.0",
+  "description": "A test plugin for scrobble retriever integration settings",
+  "permissions": {
+    "scrobbleRetriever": {
+      "reason": "For testing scrobble retriever operations"
+    },
+    "users": {
+      "reason": "Access user information for scrobble retrieval"
+    }
+  }
+}

From 5c5b849a4e6133eb7fc7286007ee2260f0aa3638 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 8 Aug 2026 22:25:48 -0400
Subject: [PATCH 020/200] docs(plugins): sync plugins README with the
 implementation (#5912)

* docs(plugins): document the Matcher host service

The Matcher host service (matcher_matchsongs, permission 'matcher') was
missing from the README entirely. Add its section with permission example,
the matcher-requires-library rule, result ordering/scoping semantics, and
a Go usage example.

* docs(plugins): add missing nd_scrobbler_playback_report to Scrobbler

The Scrobbler capability has four required methods, but the README said
three and omitted nd_scrobbler_playback_report from the function table.
Add the table row and document the PlaybackReport input payload and its
possible playback states.

* docs(plugins): remove stale coverartarchive-as example row

The AssemblyScript coverartarchive-as example no longer exists in
plugins/examples/ (and no AssemblyScript code remains in the repo), so
drop its row from the examples table.

* docs(plugins): add Command Line Interface section

The 'navidrome plugin' CLI (list, info, validate, enable, disable, edit,
rescan) was undocumented; the README's only mention was a single inline
'plugin edit --write-access' reference, and it claimed plugins could only
be enabled/disabled via the UI. Add a CLI section with all subcommands
and the 'plugin edit' flags, and link it from Runtime Management.

* docs(plugins): add pdk and types packages to Go PDK table

The Go PDK package table was missing two of the packages that ship under
plugins/pdk/go/: 'types' (shared DTOs used across capabilities and host
services) and 'pdk' (the extism/go-pdk wrapper the README's own examples
already import).

* docs(plugins): correct capabilities and host services in examples table

Several example rows understated what the plugins implement: the
scheduler/websocket callback capabilities were omitted for nowplaying-py,
library-inspector-rs, crypto-ticker, and discord-rich-presence-rs, and
the Discord example also uses the Config host service.

* docs(plugins): state that scheduler/taskqueue permissions require callbacks

Manifest validation rejects a plugin that declares the scheduler or
taskqueue permission without exporting nd_scheduler_callback or
nd_task_execute, but the README worded both callbacks as soft
suggestions (TaskWorker was even labeled optional). Make the load-time
failure explicit in both capability sections.

* docs(plugins): document HTTP, WebSocket, and Task limits and defaults

Add the runtime limits plugins actually hit: HTTP default 10s timeout,
5-redirect cap with per-hop host re-validation, and 10MB response cap;
the 30s timeout on WebSocket callbacks; and the full task_createqueue
parameter list (delayMs, retentionMs) with queue defaults, retention
bounds, the 1MB payload cap, and task persistence across restarts.

* docs(plugins): include scrobbleRetriever in user-scoped authorization note

The ScrobbleRetriever host service added in #5795 is user-scoped like
subsonicapi and scrobbler, but the Security section's user-scoped
authorization item didn't list it.

* docs(plugins): clarify matcher user scoping requires the users permission

The Matcher usage example set opts.Username while the section's manifest
example declares only matcher+library; without the users permission no
users can be assigned to the plugin, so userAccess.resolve rejects the
call at runtime. Make the example unscoped and state that user scoping
requires the users permission with users assigned. Raised by Codex
review on PR #5912.
---
 plugins/README.md | 143 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 120 insertions(+), 23 deletions(-)

diff --git a/plugins/README.md b/plugins/README.md
index adc177324..b04e12bd9 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -34,12 +34,14 @@ The plugin system is built on **[Extism](https://extism.org/)**, a cross-languag
   - [Task](#task)
   - [WebSocket](#websocket)
   - [Library](#library)
+  - [Matcher](#matcher)
   - [Artwork](#artwork)
   - [SubsonicAPI](#subsonicapi)
   - [Config](#config)
   - [Users](#users)
   - [ScrobbleRetriever](#scrobbleretriever)
 - [Configuration](#configuration)
+- [Command Line Interface](#command-line-interface)
 - [Building Plugins](#building-plugins)
 - [Examples](#examples)
 - [Security](#security)
@@ -226,13 +228,14 @@ func ndGetArtistBiography() int32 {
 
 ### Scrobbler
 
-Integrates with external scrobbling services. All three methods are **required**.
+Integrates with external scrobbling services. All four methods are **required**.
 
-| Function                     | Input                 | Output | Description                 |
-|------------------------------|-----------------------|--------|-----------------------------|
-| `nd_scrobbler_is_authorized` | `{username}`          | `bool` | Check if user is authorized |
-| `nd_scrobbler_now_playing`   | See below             | (none) | Send now playing            |
-| `nd_scrobbler_scrobble`      | See below             | (none) | Submit a scrobble           |
+| Function                        | Input        | Output | Description                  |
+|---------------------------------|--------------|--------|------------------------------|
+| `nd_scrobbler_is_authorized`    | `{username}` | `bool` | Check if user is authorized  |
+| `nd_scrobbler_now_playing`      | See below    | (none) | Send now playing             |
+| `nd_scrobbler_scrobble`         | See below    | (none) | Submit a scrobble            |
+| `nd_scrobbler_playback_report`  | See below    | (none) | Send playback state report   |
 
 > **Important:** Scrobbler plugins require the `users` permission in their manifest. Scrobble events are only sent for users assigned to the plugin through Navidrome's configuration.
 
@@ -270,6 +273,25 @@ Integrates with external scrobbling services. All three methods are **required**
 }
 ```
 
+**PlaybackReport Input:**
+
+Same `username` and `track` fields, plus playback state details:
+
+```json
+{
+  "username": "john",
+  "track": { ... },
+  "state": "playing",
+  "positionMs": 45000,
+  "playbackRate": 1.0,
+  "playerId": "player-id",
+  "playerName": "My Client",
+  "timestamp": 1703270400
+}
+```
+
+`state` is one of `starting`, `playing`, `paused`, `stopped`, or `expired`.
+
 **Error Handling:**
 
 On success, return `0`. On failure, use `pdk.SetError()` with one of these error types:
@@ -309,7 +331,7 @@ Each match contains a `song` reference and a `similarity` score (float64, 0.0–
 
 ### TaskWorker
 
-Processes tasks from a queue. The method is **optional** — export it if your plugin uses the [Task](#task) host service for background work.
+Processes tasks from a queue. **Required** if your plugin uses the [Task](#task) host service: declaring the `taskqueue` permission without exporting this function fails the plugin load.
 
 | Function            | Input                                       | Output  | Description          |
 |---------------------|---------------------------------------------|---------|----------------------|
@@ -329,7 +351,7 @@ Useful for initializing connections, scheduling recurring tasks, etc. Errors are
 
 ### SchedulerCallback
 
-Receives scheduled task events. **Required** if your plugin uses the [Scheduler](#scheduler) host service.
+Receives scheduled task events. **Required** if your plugin uses the [Scheduler](#scheduler) host service: declaring the `scheduler` permission without exporting this function fails the plugin load.
 
 | Function                  | Input                                        | Output | Description                 |
 |---------------------------|----------------------------------------------|--------|-----------------------------|
@@ -346,6 +368,8 @@ Receives WebSocket events. Export any subset of these to handle events from the
 | `nd_websocket_on_error`          | `{connectionId, error}`         | Connection error                 |
 | `nd_websocket_on_close`          | `{connectionId, code, reason}`  | Connection closed                |
 
+Each callback invocation is subject to a 30-second timeout.
+
 ---
 
 ## Host Services
@@ -390,6 +414,8 @@ Make HTTP requests to external services. This is a dedicated host service (separ
 |-------------|----------------------------------------------------------|----------------------------------|
 | `http_send` | `method, url, headers, body, timeoutMs, noFollowRedirects` | `statusCode, headers, body`    |
 
+**Limits:** Requests time out after 10 seconds by default (override per request with `timeoutMs`). Redirects are followed up to 5 times, re-checking the allowed hosts on every hop. Response bodies are capped at 10MB.
+
 **Usage:**
 
 ```go
@@ -615,13 +641,21 @@ Background task queue with retry support. Plugins enqueue tasks and process them
 
 **Host functions:**
 
-| Function            | Parameters                                        | Description                |
-|---------------------|---------------------------------------------------|----------------------------|
-| `task_createqueue`  | `name, concurrency, maxRetries, backoffMs, ...`   | Create a named task queue  |
-| `task_enqueue`      | `queueName, payload`                              | Add a task to the queue    |
-| `task_get`          | `taskID`                                          | Get task status and result |
-| `task_cancel`       | `taskID`                                          | Cancel a pending task      |
-| `task_clearqueue`   | `queueName`                                       | Remove all tasks from queue|
+| Function            | Parameters                                                    | Description                |
+|---------------------|---------------------------------------------------------------|----------------------------|
+| `task_createqueue`  | `name, concurrency, maxRetries, backoffMs, delayMs, retentionMs` | Create a named task queue  |
+| `task_enqueue`      | `queueName, payload`                                          | Add a task to the queue    |
+| `task_get`          | `taskID`                                                      | Get task status and result |
+| `task_cancel`       | `taskID`                                                      | Cancel a pending task      |
+| `task_clearqueue`   | `queueName`                                                   | Remove all tasks from queue|
+
+Tasks are persisted to SQLite, so pending tasks survive server restarts. Queue behavior:
+
+- `concurrency` – Parallel workers (default 1), capped by the manifest's `maxConcurrency`
+- `maxRetries` – Retries for a failed task (default 0); `backoffMs` (default 1000) doubles on each retry
+- `delayMs` – Minimum delay between consecutive task starts, useful for rate limiting (default 0)
+- `retentionMs` – How long finished tasks are kept (default 1 hour, min 1 minute, max 1 week)
+- Payloads are capped at 1MB
 
 **Usage:**
 
@@ -747,6 +781,45 @@ for _, lib := range libraries {
 }
 ```
 
+### Matcher
+
+Match externally-obtained songs (e.g. results from a recommendation or similarity API) to tracks in the local library, reusing Navidrome's matching algorithm (ID > MBID > ISRC > fuzzy title).
+
+**Manifest permission:**
+
+```json
+{
+  "permissions": {
+    "matcher": {
+      "reason": "Resolve external recommendations to library tracks"
+    },
+    "library": {
+      "reason": "Required by the matcher permission"
+    }
+  }
+}
+```
+
+> **Important:** The `matcher` permission requires the `library` permission.
+
+**Host functions:**
+
+| Function             | Parameters    | Returns                 |
+|----------------------|---------------|-------------------------|
+| `matcher_matchsongs` | `songs, opts` | Array of matched tracks |
+
+The result has one entry per input song, in the same order; the entry for a song with no match is empty. Results are limited to the libraries the plugin (and the scoped user, if any) can access. Set `opts.username` to run the match as a specific user: their favorites and ratings inform tiebreaking, and the returned tracks carry their annotations. User scoping additionally requires the [`users`](#users) permission, with users assigned to the plugin.
+
+**Usage:**
+
+```go
+import "github.com/navidrome/navidrome/plugins/pdk/go/types"
+
+matches, err := host.MatcherMatchSongs([]types.SongRef{
+    {Name: "Song Title", Artists: []types.ArtistRef{{Name: "Artist Name"}}},
+}, host.MatchOptions{})
+```
+
 ### Artwork
 
 Generate public URLs for Navidrome artwork (albums, artists, tracks, playlists).
@@ -1008,6 +1081,29 @@ For more advanced access (listing keys, integer values), use the [Config](#confi
 
 ---
 
+## Command Line Interface
+
+Manage plugins from the command line with `navidrome plugin`:
+
+| Command                                                | Description                                                |
+|--------------------------------------------------------|------------------------------------------------------------|
+| `navidrome plugin list [-f table\|csv\|json]`          | List installed plugins                                     |
+| `navidrome plugin info <id\|file.ndp> [-f text\|json]` | Show details for an installed plugin or a `.ndp` package   |
+| `navidrome plugin validate <id\|file.ndp>`             | Validate an installed plugin or a `.ndp` package manifest  |
+| `navidrome plugin enable <id>`                         | Enable a plugin                                            |
+| `navidrome plugin disable <id>`                        | Disable a plugin                                           |
+| `navidrome plugin edit <id>`                           | Update a plugin's config and/or permissions                |
+| `navidrome plugin rescan`                              | Re-discover plugins in the plugins folder                  |
+
+**`plugin edit` flags:**
+
+- `--config <json>` / `--config-file <path>` – Set the plugin configuration (`-` reads from stdin)
+- `--users <list>` / `--all-users` – Usernames the plugin may access (comma-separated or JSON array), or all users
+- `--libraries <list>` / `--all-libraries` – Library IDs the plugin may access (comma-separated or JSON array), or all libraries
+- `--write-access` / `--no-write-access` – Allow or deny the plugin write access to libraries
+
+---
+
 ## Building Plugins
 
 ### Supported Languages
@@ -1070,6 +1166,8 @@ replace github.com/navidrome/navidrome => ../../..
 | `scheduler`       | `plugins/pdk/go/scheduler`           | Scheduled task callbacks             |
 | `websocket`       | `plugins/pdk/go/websocket`           | WebSocket event handlers             |
 | `host`            | `plugins/pdk/go/host`                | Host service SDK (all services)      |
+| `types`           | `plugins/pdk/go/types`               | Shared data types (tracks, artists, song refs) |
+| `pdk`             | `plugins/pdk/go/pdk`                 | Low-level helpers (wraps extism/go-pdk: config, logging, memory) |
 
 See the example plugins in [examples/](examples/) for complete usage patterns.
 
@@ -1168,12 +1266,11 @@ See [examples/](examples/) for complete working plugins:
 | [minimal](examples/minimal/)                                   | Go             | MetadataAgent | –                                          | Basic structure example        |
 | [wikimedia](examples/wikimedia/)                               | Go             | MetadataAgent | HTTP                                       | Wikidata/Wikipedia integration |
 | [coverartarchive-py](examples/coverartarchive-py/)             | Python         | MetadataAgent | HTTP                                       | Cover Art Archive              |
-| [coverartarchive-as](examples/coverartarchive-as/)             | AssemblyScript | MetadataAgent | HTTP                                       | Cover Art Archive              |
-| [webhook-rs](examples/webhook-rs/)                             | Rust           | Scrobbler     | HTTP                                       | HTTP webhooks                  |
-| [nowplaying-py](examples/nowplaying-py/)                       | Python         | Lifecycle     | Scheduler, SubsonicAPI                     | Periodic now-playing logger    |
-| [library-inspector-rs](examples/library-inspector-rs/)         | Rust           | Lifecycle     | Library, Scheduler                         | Periodic library stats logging |
-| [crypto-ticker](examples/crypto-ticker/)                       | Go             | Lifecycle     | WebSocket, Scheduler                       | Real-time crypto prices demo   |
-| [discord-rich-presence-rs](examples/discord-rich-presence-rs/) | Rust           | Scrobbler     | HTTP, WebSocket, Cache, Scheduler, Artwork | Discord integration            |
+| [webhook-rs](examples/webhook-rs/)                             | Rust           | Scrobbler                                        | HTTP                                               | HTTP webhooks                  |
+| [nowplaying-py](examples/nowplaying-py/)                       | Python         | Lifecycle, SchedulerCallback                     | Scheduler, SubsonicAPI                             | Periodic now-playing logger    |
+| [library-inspector-rs](examples/library-inspector-rs/)         | Rust           | Lifecycle, SchedulerCallback                     | Library, Scheduler                                 | Periodic library stats logging |
+| [crypto-ticker](examples/crypto-ticker/)                       | Go             | Lifecycle, SchedulerCallback, WebSocketCallback  | WebSocket, Scheduler                               | Real-time crypto prices demo   |
+| [discord-rich-presence-rs](examples/discord-rich-presence-rs/) | Rust           | Scrobbler, SchedulerCallback, WebSocketCallback  | HTTP, WebSocket, Cache, Scheduler, Artwork, Config | Discord integration            |
 
 ---
 
@@ -1186,7 +1283,7 @@ Plugins run in a secure WebAssembly sandbox provided by [Extism](https://extism.
 3. **No Network Listeners** – Plugins cannot bind ports
 4. **Config Isolation** – Plugins only receive their own config section
 5. **Memory Limits** – Controlled by the WebAssembly runtime
-6. **User-Scoped Authorization** – Plugins with `subsonicapi` or `scrobbler` capabilities can only access/receive events for users assigned to them through Navidrome's configuration
+6. **User-Scoped Authorization** – Plugins with `subsonicapi`, `scrobbleRetriever`, or `scrobbler` capabilities can only access/receive events for users assigned to them through Navidrome's configuration
 7. **Users Permission** – Plugins requesting user access must be explicitly configured with allowed users; sensitive data (passwords, emails) is never exposed
 
 ---
@@ -1201,7 +1298,7 @@ If `AutoReload` is disabled, Navidrome needs to be restarted to pick up plugin c
 
 ### Enabling/Disabling Plugins
 
-Plugins can be enabled/disabled via the Navidrome UI. The plugin state is persisted in the database.
+Plugins can be enabled/disabled via the Navidrome UI or the [`navidrome plugin` CLI](#command-line-interface). The plugin state is persisted in the database.
 
 ### Important Notes
 

From 944ca3100fce669e4bd63be09bdd158ab59faa3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 9 Aug 2026 15:03:27 -0400
Subject: [PATCH 021/200] feat(artwork): new artwork pipeline with background
 resolution and Low Quality Image Placeholders (#5847)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(artwork): add artwork, item_artwork and artwork_queue tables

* feat(artwork): add artwork models, repository interfaces and mocks

* feat(artwork): implement artwork repository

* feat(artwork): implement item_artwork repository with batched hydration

* feat(artwork): implement artwork_queue repository

* feat(artwork): add content-addressed originals store

* feat(artwork): add artwork prune (orphan cleanup)

* fix(artwork): never sweep files on transient DB errors during prune

* refactor(artwork): fold originals package into core/artwork as ImageStore

* refactor(artwork): merge item artwork state into ArtworkRepository

* fix(artwork): chunk unbounded IN clauses and restore interface docs

* refactor(artwork): apply simplify-pass cleanups

Internal item_artwork sqlRepository helper, toSQLArgs upserts, batched queue enqueue, EnqueueStaleAbsent moved to queue repo, snapshot-based prune sweep, mock/real semantics aligned.

* fix(artwork): address review findings on prune/sweep races and mock fidelity

Sweep now honors an mtime grace window (in-flight acquisitions and temp files), reacquired orphans reset the prune grace window, and the queue mock implements real stale-absent semantics.

* fix(artwork): atomic orphan deletion and timestamp semantics from review

DeleteOrphans re-checks age+references at delete time, PutItemArtwork defaults attempted_at, queue mock timestamps mirror SQL.

* fix(artwork): guard orphan file removal with the prune grace window

Duplicate ImageStore writes refresh the file mtime and Remove skips files newer than the cutoff, so overlapping acquisitions cannot lose their store files to a concurrent prune.

* fix(artwork): rewrite vanished duplicates and sweep stale mime variants

Write falls through to a real write when the liveness touch fails, and sweep retention now matches the recorded mime's extension so obsolete variants are reclaimed.

* fix(artwork): index artwork_queue in dequeue order

The previous leading retry_at range column forced a temp B-tree sort of the whole eligible set on every DequeueBatch; ordering the index by (priority DESC, enqueued_at) lets scans stop after the batch size.

* fix(artwork): honor the orphan cutoff in the repository mock

The mock's DeleteOrphans now applies createdBefore like the SQL implementation, and a new spec covers a freshly reacquired row surviving prune.

* fix(artwork): reject malformed hashes in ImageStore operations

Known-absent states carry an empty hash and malformed persisted hashes could panic path sharding or inject separators; Write/Open/Remove now return an error for anything but 16 lowercase hex chars.

* fix(artwork): mock PutImage refreshes created_at like the SQL repository

Prune specs now age fixtures directly instead of seeding stale timestamps through the upsert.

* fix(artwork): store backing-file provenance per item, not per hash

* feat(artwork): import blurhash encoder from #5797

* feat(artwork): add worker-side artwork resolvers

* fix(artwork): propagate playlist tile failures and dedupe external step

* feat(artwork): add acquisition processor

Resolves one queue item end to end: hash/dedup, decode + 128px thumbnail
blurhash, place bytes (store vs source file), and persist found/absent/
failed state for the worker (Task 4) to act on.

* style(artwork): tighten processor comments to budget

* feat(artwork): add acquisition worker service

* feat(artwork): enqueue artwork resolution from scan and CRUD paths

* feat(artwork): artwork backfill, fingerprint re-resolution and scheduled jobs

* test(artwork): leak/soak coverage and deferred assertions

* fix(artwork): propagate transient artist image errors to the worker

callGetImage swallowed all agent errors, so an agent outage surfaced as ErrNotFound and the worker settled artist artwork as a definitive absent (and reset the breaker). Add an additive ArtistImageResult path that returns the underlying agent error on transient failure while keeping ArtistImage byte-identical for existing callers; the worker's artist external step uses it via fromArtistExternalResult.

* fix(artwork): resolve full playlist source chain

resolvePlaylist only built the generated grid, dropping the uploaded-image, sidecar and ExternalImageURL sources the old reader_playlist.go chain serves. Port the full chain before the grid fallback: uploaded (upload), sidecar (folder), and ExternalImageURL routed through extGate with the same extError semantics as the other external steps. Also rewires the artist external step onto ArtistImageResult.

* fix(artwork): purge dangling queue rows and guard concurrent re-enqueues

Queue rows for deleted entities failed forever (Get -> ErrNotFound -> failed -> capped retries, unbounded). Add ArtworkQueueRepository.PurgeDangling, called from Prune next to the item_artwork purge. Separately, the found/absent path unconditionally deleted the dequeued row, erasing a concurrent scan re-enqueue; switch to DeleteIfUnchanged, which deletes only while retry_at still matches the dequeued value (verified retry_at is the column an Enqueue upsert resets).

* style(artwork): fix comment accuracy and budget; fingerprint ArtistImageFolder

Correct the inverted workerDeps.extGate comment, trim over-budget doc comments, and add conf.Server.ArtistImageFolder to the resolution fingerprint so an image-folder change re-resolves artist artwork.

* fix(artwork): treat missing local playlist cover as definitive, not transient

A playlist ExternalImageURL pointing at a local file that fails to open was
routed through extError, causing failed/48h-retry loops that burn a rate
limiter token forever instead of falling through to the generated grid.

* refactor(artwork): deduplicate purge loop, backfill table, and extGate alias

* fix(artwork): cap resolved image reads

A user-editable ExternalImageURL can point at an arbitrarily large endpoint;
a fast server could make the worker buffer hundreds of MB inside the 5s HTTP
timeout. Bound the read to a fixed 20MB cap (no config knob) via io.LimitReader
and fail the item if it is exceeded.

* fix(artwork): retry higher-priority external art after fallback hit

With CoverArtPriority="external,cover.jpg", a transient external failure
followed by a folder hit dropped the external error: the worker recorded
found and deleted the queue row, so the configured higher-priority external
art was never retried. Carry extError onto the fallback resolution and add
an outcomeFoundStale that persists+serves the art but reschedules via
MarkFailed, giving the external source another chance. When external later
answers definitively-not-found, the hit is not stale and the row is deleted.

* fix(artwork): treat playlist cover URL 404 as definitive miss

The playlist ExternalImageURL step used sources.go's fromURL, which maps any
non-200 to a generic error, so a stale URL returning 404/410 was classified
transient: infinite backoff plus it counted toward the circuit breaker,
blocking valid external work. Add a local fetch in resolve.go that maps
404/410 to model.ErrNotFound (definitive) while keeping other non-200s
transient. sources.go is left untouched.

* test(artwork): move soak test into the Ginkgo suite

* test(artwork): make leak and permission tests pass on linux

goleak now ignores notify's nonrecursive-tree goroutines (linux uses
inotify, which spawns dispatch+internal instead of darwin's recursive
dispatch), and the read-only-dir prune spec skips under root, where
permission bits cannot make Remove fail.

* fix(artwork): reject decompression-bomb dimensions before decoding

* fix(artwork): keep fresh re-enqueues ahead of stale failure backoff

* fix(artwork): include M3U external art flag in the config fingerprint

* fix(artwork): resolve private playlists with an admin context

* test(artwork): convert non-synctest timing tests to Ginkgo specs

TestArtworkBackoffSchedule and TestArtworkWorkerRunNoLeak needed no real
*testing.T (no synctest), so move them into worker_test.go as Ginkgo
specs. TestArtworkBreakerHalfOpen stays plain since testing/synctest
requires a real *testing.T, matching core/scrobbler's precedent.

* fix(artwork): store backing-file provenance per item, not per hash

* fix(artwork): apply image limits to playlist tile decoding

decodeTile ran image.Decode on every sampled album's resolved bytes
before processItem's maxImageBytes/maxImagePixels guards applied,
letting an oversized or decompression-bomb tile fully decode
unbounded. Enforce both caps inside decodeTile itself.

* refactor(artwork): reuse auth.WithAdminUser and dedupe image cap guards

* perf(artwork): fetch only IDs for backfill enumeration

Backfill enumerated every album, artist, playlist and radio via GetAll
and mapped out just the ID. GetAll materializes full entities (library
joins, participant/stats/tags JSON, annotation, artwork hydration), so on
a large library it loaded tens of thousands of heavy structs only to read
one field each — spiking transient RSS to ~1GB during the one-time
upgrade backfill, a memory risk on small NAS/Pi hardware.

Add GetAllIDs to the album, artist, playlist and radio repositories: it
reuses each repo's base row-set filter (library visibility, artist
content join, playlist userFilter) but projects only id, skipping the
heavy columns and post-processing. A per-repo parity test asserts
GetAllIDs returns exactly the same id set as GetAll.

Verified on a 727MB / 29k-artist production DB copy: peak RSS during
backfill dropped from ~1012MB to ~89MB, file descriptors flat, same
36,138 items enqueued.

* feat(artwork): promote worker concurrency and external rate to real configs

The artwork worker's drain speed was governed by two hidden Dev flags,
DevArtworkWorkerConcurrency and DevArtworkExternalRPS, both defaulting to 2.
On a large library's one-time backfill the external rate limiter is the real
ceiling: every art-less item waits on it before the (rate-limited) external
lookup, so the drain crawls at ~RPS items/sec while local-art items are
unaffected.

Promote both to documented, supported options: ArtworkWorkerConcurrency
(default 4) sets local-resolution parallelism, ArtworkExternalMaxRPS
(default 2, 0 = unlimited) caps external-agent lookups to stay polite to
Last.fm/Deezer/etc. Operators can now trade first-backfill speed against
external-API rate limits. The old Dev names still map for backward compat.

* fix(deezer): never return empty-image-id placeholder pictures

* feat(agents): enumerate enabled image-retriever agents per capability

* feat(artwork): worker fetches agent images directly with per-agent rate limits and breakers

* fix(artwork): treat agent not-found as breaker success

* feat(model): content-hash artwork id suffix and hydratable per-entity image state

* feat(persistence): hydrate artwork hash and absence onto entity pages

* feat(artwork): resolve media_file embedded art in the worker, invalidate on rescan

* feat(artwork): broadcast refresh events when artwork lands

* fix(artwork): broadcast refresh for stale-found artwork too

* feat(artwork): state-backed serving path with provisional read-through

* feat(server): serve artwork from persisted state with content-hash caching

* feat(subsonic): content-hash coverArt ids, omit artwork on known-absent

* refactor(artwork): delete the legacy reader chain, cache warmer, and provider image methods

* feat(artwork): precache on acquisition, bump on upload/radio changes, manual re-resolve API

* test(artwork): end-to-end coverage for the serving cutover

* chore(artwork): generic 500 bodies on refresh endpoint, trim stale test comments

* fix(artwork): request read-through must not reset the failure backoff

The provisional read-through and dangling re-enqueue used Enqueue, whose upsert
resets retry_at, so any browse of an unresolved entity that was backing off after
an external failure made it immediately eligible again — defeating the exponential
backoff during a provider outage. Add EnqueueBump, which raises priority but leaves
an existing row's retry_at intact, and route the serving path through it. Scan and
manual re-resolve keep Enqueue's reset (a detected change wants immediate retry).

* fix(artwork): keep an eligible track's cover requestable when its album is absent

An embedded-eligible track with no resolved item_artwork row inherited the album's
ImageAbsent, so when the album resolved absent (e.g. CoverArtPriority without
'embedded') the track's coverArt was omitted permanently — the client never
requested it, so the lazy mediafile path never resolved it — even though the
serving path would extract and serve the track's own embedded art. Hydration now
never copies the album's absence onto an eligible-but-unresolved track.

* fix(artwork): validate each agent image URL before picking the largest

bestImageURL selected the largest by size and only then parsed it, so a malformed
largest URL (e.g. a bad percent-escape) returned nil and shadowed a valid smaller
candidate, contradicting the documented skip-unparseable behavior. Parse per
candidate and compare sizes only among URLs that parse.

* fix(artwork): fall back to disc art, not the album, for multi-disc tracks

serveMediaFile delegated an absent/ineligible track straight to AlbumCoverArtID,
skipping the disc-specific lookup that MediaFile.CoverArtID (and the deleted legacy
reader) use. On multi-disc albums with per-disc images that served the album cover
instead of the configured disc artwork. Delegate through DiscCoverArtID.

* fix(artwork): enqueue uploaded artwork only after the filename is persisted

SetImage cleared state and enqueued the bump before the caller stored the new
filename, so a worker drain in that window could resolve against the old (already
deleted) file and settle absent, leaving the upload unused until a later scan. Move
the invalidate+enqueue into EnqueueArtwork, which each caller now invokes after the
entity Put.

* fix(artwork): keep multi-disc tracks requestable when the album is absent

Round-1's hydration fix still copied the album's known-absent onto a non-eligible
(or own-absent) track, but MediaFile.CoverArtID routes a multi-disc track to disc
art, which resolves provisionally and is never known-absent. Marking it absent made
Subsonic omit coverArt so clients never requested a valid disc image. Only mark a
single-disc track absent, and only when its own art won't resolve.

* fix(artwork): serve a local playlist ExternalImageURL as a file-backed reference

A local ExternalImageURL was resolved through the external step and labelled
external, so placeBytes copied it into the content-addressed store and dropped its
path/mtime — replacing the file never tripped the staleness check. Classify local
references as file-backed (resolved in place, even on the request path) and keep
store-backed behaviour only for http(s) URLs.

* fix(artwork): requeue playlist cover when its track set changes

A generated-grid cover went stale after track mutations: nothing re-resolved the
playlist's artwork, and the request path deliberately never rebuilds the grid, so
serveEntity kept returning the old grid hash indefinitely. Enqueue pl artwork from
refreshCounters (the choke point for every track-set change); no clear, so the old
cover keeps serving until the worker rebuilds.

* fix(artwork): open library-backed artwork through its on-disk root

A library configured with a file:// path stored absRoot as the raw URI, so Abs
produced strings like file:/music/cover.jpg that os.Open/os.Stat reject — folder,
upload and embedded art were treated as dangling on every request, looping forever.
Normalize a file:// path to its parsed OS path (the same root os.DirFS uses);
non-local schemes are left unchanged (out of scope, per the artwork-musicfs TODO).

* fix(artwork): only use disc resolution for multi-disc albums

DiscCoverArtID returns a dc- id for any track with DiscNumber>0, so serveDisc ran
the full DiscArtPriority chain even for single-disc albums, where a stray disc*/
embedded image could shadow higher-priority album art. Gate disc resolution on the
album having more than one disc, matching the legacy reader; single-disc tracks
serve album art directly.

* fix(artwork): invalidate artwork when an uploaded image is deleted

Deleting an artist/radio/playlist upload cleared the filename but left the found
item_artwork row and its hash, so lists kept advertising the deleted cover's
hash-suffixed immutable URL and clients could display it indefinitely. Call
EnqueueArtwork after the delete-side Put, symmetric with upload, so the state is
cleared and re-resolved to the next source (or absent).

* fix(artwork): restore synthetic-artist guard and unicode normalization in agent lookups

Moving agent calls into the worker bypassed two behaviors of the aggregate provider:
Agents.GetArtistImages' guard for Unknown/Various Artists (a direct retriever call
could assign an unrelated image to a synthetic artist), and auxAlbum/auxArtist.Name's
DevPreserveUnicodeInExternalCalls normalization (records with typographic quotes/dashes
missed exact-name searches). Re-apply both before enumerating retrievers.

* fix(artwork): enforce entity visibility on the Subsonic getCoverArt path

serveEntity reads persisted item_artwork by id, bypassing the library and private-
playlist filters that the legacy entity-load applied. On the authenticated Subsonic
path a user could fetch artwork for an inaccessible album or someone else's private
playlist by guessing an id. getCoverArt now resolves the underlying entity through
the request-scoped (filtered) repositories and serves the placeholder when it is not
visible, so existence isn't leaked and the always-an-image invariant holds. The
public share (JWT-authorized) and Jellyfin (admin) paths are intentionally untouched.

* fix(artwork): version the artwork ETag with the served representation

The ETag was the pixel hash of the original image, so a CoverArtQuality or
EnableWebPEncoding change altered the resized bytes without changing the ETag —
revalidating clients got a spurious 304 and kept the old encoding. Resized responses
now carry a representation ETag (hash + size + square + encode settings) used for the
ETag header and If-None-Match, while the immutable decision stays on the pixel hash
(URLs remain pixel-identity per the spec, so hash-suffixed clients keep zero-request
caching). Full-size originals fall back to the pixel hash as before.

* fix(artwork): don't stamp the album hash onto multi-disc tracks

The hydration fallback assigned a found album hash to every fallback track, but a
multi-disc track's CoverArtID emits a dc- id served from disc-specific art whose hash
is unknown at hydration time. Advertising dc-..._<albumHash> gave clients a content-
version that never changes when the disc image does, breaking id-based refresh. Only
stamp the album hash for single-disc tracks (DiscNumber == 0); multi-disc tracks stay
unhashed and rely on the correct ETag returned by the served response.

* fix(artwork): enqueue new empty playlists by id, and refresh on absent outcomes

Two worker/enqueue fixes from review:
- playlistRepository.Put assigned the generated id to the caller's Playlist but passed
  the stale copy (empty id) to refreshCounters, enqueueing a pl|"" row the worker
  failed until the daily dangling purge while the real playlist went unresolved. Set
  the id on the copy before enqueueing.
- The drain refresh batch only included found/foundStale, so a cover removed by a scan
  (found -> absent) never notified clients, leaving the old immutable image displayed.
  Broadcast absent outcomes too; precache still only warms found/foundStale.

* fix(artwork): honor disabled per-track art at serve time; use nanosecond mtime provenance

Two serving-correctness fixes from review:
- serveMediaFile served a persisted mf embedded image even after EnableMediaFileCoverArt
  was turned off (the setting isn't in the config fingerprint, so found rows aren't
  reprocessed). Direct mf- URLs now honor the setting at serve time and fall back to
  disc/album art.
- The file-backed staleness check compared whole-second mtimes, so a same-second content
  replacement (two writes in one second, or timestamp-preserving tools) could serve
  different bytes under the old hash + immutable policy. RefMtime is now unix-nanoseconds
  (no schema change; int64 column), detecting sub-second changes where the filesystem
  records them.

* fix(artwork): preserve the drive when normalizing Windows file:// library paths

url.Parse puts the volume of file://C:/Music in Host, not Path, so localOSRoot dropped
it and returned /Music — os.Open/os.Stat then failed and folder/embedded art on Windows
looped as dangling. Rejoin the host volume, matching core/storage/local's newLocalStorage.

* fix(artwork): clamp negative sizes to full-size; convert imghttp test to Ginkgo

- A negative size (Subsonic size / Jellyfin maxwidth accept signed ints) reached
  resizeStaticImage, where the square path builds image.NewNRGBA(Rect(0,0,size,size))
  — a giant rectangle that panics/OOMs. Clamp size<0 to 0 (full-size) at the Service
  entry. Positive sizes were already clamped to the original.
- imghttp used a plain func Test with a table; convert to a Ginkgo DescribeTable with
  the suite entry point in imghttp_suite_test.go (AGENTS.md test-framework requirement).

* test(artwork): use renamed ArtworkWorkerConcurrency in e2e tests

* feat(artwork): carry blurhash through item image hydration

* feat(nativeapi): expose artwork hash, absence and blurhash

* feat(artwork): hydrate the parent album's artwork state onto tracks

* test(artwork): add hydrateArtwork regression guard for AlbumImage wiring

Drives hydrateArtwork itself (not applyItemImage directly) over tracks that
take each of the loop's continue branches, so a future edit moving the
AlbumImage fill below a continue would fail loudly instead of passing silently.

* feat(jellyfin): version album and artist image tags by content hash

* fix(jellyfin): trim primaryImageTag comment to why-only, within budget

* feat(jellyfin): emit real blurhashes and drop the synthesized fallback

* feat(ui): version cover art urls by content hash and skip absent art

* feat(ui): add BlurHashCanvas placeholder component

* fix(ui): clear stale blurhash pixels and assert the draw path in tests

Clear the canvas before each decode attempt so a hash change that fails
to decode doesn't leave the previous frame's pixels on screen once this
wires into a list that recycles items. Also strengthen the specs to
assert createImageData/putImageData were actually invoked (and with
what), instead of only checking that a <canvas> element exists.

* feat(ui): show the blurhash while an album cover loads

* fix(artwork): hydrate cursor streams via an id pre-pass

The album, artist and playlist GetCursor built their own select and never
called hydrateArtwork, so every Jellyfin list endpoint (all six stream via
GetCursor) emitted entity-id image tags and no blurhash. Only GetAll
hydrated, which is why Subsonic and the native API were unaffected.

Each cursor now resolves its ordered/filtered/paginated id set with the
cheap id-only GetAllIDs query, then streams those ids in chunks through the
repo's existing GetAll, which already hydrates and applies the full select.
Max/Offset are consumed by the pre-pass alone; the chunk query carries only
the caller's filters, Sort and Order.

This also removes a pre-existing deep-pagination cost: keeping OFFSET out of
the joined query makes the pre-pass a covering index scan instead of paying
the library and annotation joins for every skipped row. Benchmarked on a
synthetic 100k-album DB with the real schema, page=500 at offset 90,000:
3.9ms via the id pre-pass, 52.5ms for the current shape, 192.7ms for a naive
join. An unpaginated full stream costs ~24% more, which is the trade.

GetAllIDs gains the annotation join whenever the caller's filters or sort
reference an annotation column (same gate CountAll uses), otherwise
Filters=IsFavorite and SortBy=PlayCount would fail in the pre-pass. The
playlist pre-pass repeats GetAll's columns so ORDER BY keeps resolving to
playlist.name rather than the joined user.name.

* fix(jellyfin): hydrate artwork on the song cursor

Jellyfin's listSongs streamed media files via GetCursor, which never
hydrates artwork, so songs emitted entity-id image tags and no blurhash.

media_file now uses the same id pre-pass as the other three cursors
(album/artist/playlist), for consistency, but on a separate method,
GetCursorWithArtwork: GetCursor itself must stay untouched, since it's
also the scanner's hot path and the scanner never reads artwork.

Measured on 1,000,000 tracks, the pre-pass over all ids costs +41.8 MB
heap and +298 ms versus GetCursor's bounded +0.0 MB. The Jellyfin path
is paginated, though, so in practice it only ever pre-passes a page's
worth of ids, not the full library, and doesn't pay that cost.

* feat(jellyfin): emit a song's own cover art when it differs from the album's

Real Jellyfin fills ImageTags from each item's own images before falling back
to the parent album, and Finamp checks imageTags.Primary before AlbumId. Our
mapper read only the album's image, so a track with distinct embedded art
silently showed the album cover.

Emit exactly one entry under ImageBlurHashes.Primary: Go marshals
map[string]string in sorted key order rather than insertion order, so a
second entry could pair the wrong blurhash with the image imageId resolves
to, and Finamp pins that pairing in its cache for 365 days.

* test(persistence): scope the GetCursorWithArtwork full-stream spec to tie-free ids

The fixture has title ties (e.g. three "Antenna" tracks), so the unscoped
positional comparison against GetAll only passed because SQLite's tie order
happened to coincide between the full scan and the pre-pass's id IN (...)
fetch. Scope it to onlySongs like the sibling ordering specs already do.

* refactor(artwork): route song own-art through primaryImageTag; align chunk size

Cleanups surfaced by /simplify: the song mapper's own-art branch reimplemented
primaryImageTag's tag+blurhash-map construction (and its one-entry invariant) — route
it through the helper so that invariant lives in one place. Tie artworkChunkSize to a
whole multiple of artworkBatchSize so a cursor page re-chunks into even hydration
batches. Hoist a duplicated imageLoading && blurHash boolean in the album grid.

* fix(ui): serve the placeholder for known-absent art instead of a broken icon

getCoverArtUrl returned '' for an imageAbsent record, so <img src={undefined}> rendered as the browser's broken-image icon on every absent cover. The server already serves a proper placeholder for absent art, so build the url and let it render.

* feat(ui): show the blurhash as the loading placeholder across cover surfaces

Add a shared CoverImage component (useImageUrl blob cache + blurhash + fade) and render the blurhash while a cover loads on the list thumbnails (CoverArtAvatar, radio) and the artist/album/playlist detail pages. The detail pages now go through CoverImage instead of a plain CardMedia, so their images come from the in-memory blob cache and survive React remounts without re-fetching. BlurHashCanvas gains an optional style prop.

* refactor(ui): unify list cover surfaces onto the shared CoverImage component

Route the album grid, CoverArtAvatar (artist/playlist lists) and the radio list's cover field through CoverImage instead of each carrying its own useImageUrl + blurhash-overlay wiring. CoverImage gains a default object-fit: cover. Radio keeps its uploaded-image gate and the generic radio placeholder for stations with no art.

* fix(ui): address CoverImage review findings

Restructure CoverImage so the size/shape lives on the root and the blurhash + image are absolute fills: the <img> mounts only once its blob is ready, so an unresolved cover never flashes a broken <img>. Add a fit prop (default cover) so album/playlist detail keep their letterbox instead of being cropped by a hardcoded object-fit. Remove the orphaned coverLoading styles and an unused subsonic import; add a CoverImage unit test.

* perf(ui): only refetch already-loaded records on SSE refresh

The artwork worker broadcasts a RefreshResource event per resolved chunk,
carrying every id in the chunk. useResourceRefresh was doing a getMany for
all of them, so any open list/detail page fetched hundreds of artists it
was not displaying. Filter the event ids to records already in the store;
the rest load fresh (with their new artwork) when navigated to.

* refactor(artwork): scale worker concurrency with CPU count

ArtworkWorkerConcurrency now defaults to max(2, NumCPU()/2) instead of a
fixed 4, mirroring MaxOpenConns: local resolution scales with the host but
stays at half the SQLite pool so it never starves the scanner/UI. External
RPS stays a fixed 2 — it gates third-party API calls and is bounded by their
tolerance, not the host, so it must not scale with CPUs.

Also drop the DevArtworkWorkerConcurrency/DevArtworkExternalRPS deprecated
aliases: those names were never released, so there is nothing to migrate.

* feat(artwork): re-queue an absent cover when its page is viewed

serveEntity now schedules a Bump recheck for an entity whose art was recorded
absent, so viewing a missing cover re-triggers resolution (e.g. after an
external source that was down during the scan comes back), matching the
request-time bump that already covers never-resolved entities.

Throttled by attempted_at against requestRecheckAge (1h) so repeatedly opening
a genuinely-absent page can't hammer external services. EnqueueBump preserves
an existing failed-state backoff via MAX(priority,...) and inserts a fresh,
immediately-eligible recheck for a settled-absent row (whose queue row was
already deleted).

* refactor(artwork): move ImageUploadService to artwork.Uploader

Relocate the image-upload service from core to core/artwork as
artwork.Uploader, co-locating it with the resolver/worker/serving that own
the artwork state it invalidates. MaxImageUploadSize moves too — its only
callers are the two image-upload handlers — which lets core/image_upload.go
be deleted entirely.

Extract the shared "clear resolved state + re-queue at Bump" invalidation
into artwork.Refresh and fold nativeapi's refreshArtwork handler onto it,
removing the duplicated DeleteForItem+Enqueue block that had drifted into
three places.

The wire provider moves from core's set to artwork's; the
playlists.ImageUploadService binding moves to the top-level injector so
core/artwork stays unaware of playlists. Behavior is unchanged.

* refactor(artwork): thread model.Kind through the artwork API

Entity-level artwork queries now take a typed model.Kind instead of a bare
prefix string. GetItemArtwork, DeleteForItem(s), GetInfoForItems,
EnqueueStaleAbsent, hydrateItemImages, enqueueBackfillKind and artwork.Refresh
convert to the prefix string only at the two real boundaries: the SQL
item_kind column (kind.Prefix() inside each repo) and external string inputs
(a new model.ParseKind for the nativeapi URL param, which also validates it).

The Backfill/stale-absent kind slices, the resolve.go dispatch switch, and the
kind→resource / kind→table lookup maps now use the Kind vars directly. The
queue lifecycle methods (MarkFailed/Delete*) keep string kinds — they operate
on a dequeued item's raw ItemKind column, which stays a string field, always
populated via kind.Prefix().

Removes every bare "al"/"ar"/… prefix literal from non-test code (27 -> 0);
behavior is unchanged.

* tune(artwork): drop backoff base from 5m to 15s

The exponential retry (base × 4^attempts, cap 48h) started at 5 minutes, so a
single transient failure — a timeout under load, an external blip — parked a
cover for 5 minutes even though a retry seconds later would have resolved it.
Start at 15s instead: transient failures recover almost immediately (15s → 1m
→ 4m → 16m …), while persistent failures still escalate to the 48h cap (now at
the 8th attempt instead of the 5th).

* tune(artwork): 5s backoff base + 12h give-up, drop the cap

Retry backoff now starts at 5s (was 15s) so a transient failure recovers on
essentially the next drain, and jitter widens to ±40% so a wave of correlated
failures doesn't re-clump into one poll.

Add a 12h give-up budget measured from enqueued_at: once the next backoff would
land past it, the worker stops retrying instead of grinding at a cap forever. A
bare failure settles absent (handed to the 24h stale-absent sweep, and still
recoverable on a page view); a found-stale keeps its already-served art. The
budget bounds the tail, so the separate 48h backoffCap is removed.

* fix(lastfm): match album.getInfo on name+artist only, not MBID

Last.fm's album.getInfo by MBID is unreliable: a correct MBID can return a
different album, or none. Observed with black midi's "7-eleven" (whose correct
MBID returned a FLEETWOOD release) and both missing The Chats albums (one MBID
404s, the other resolves to a different self-titled release). The worker then
recorded covers absent — or would fetch the wrong art — even though the correct
cover is on Last.fm by name+artist.

Stop passing the MBID to album.getInfo; query by name+artist only, which also
drops the now-dead error-6 MBID-retry fallback. The low-level client keeps its
MBID support for other callers; only the album lookup changes.

* fix(lastfm): return agents.ErrNotFound on error 6 (not found)

Last.fm returns error 6 for a missing artist/album — a definitive negative —
but the agent returned the raw *lastFMError, so the artwork worker treated
every not-found as a real fault: it counted toward the per-source circuit
breaker (5 in a row opens it, fast-failing all Last.fm calls including valid
ones) and was retried as a transient error instead of settling absent. On a
first scan of a library with many artists Last.fm lacks, this stalled valid
cover lookups and left entities churning in backoff.

Translate error 6 to the shared agents.ErrNotFound at the agent boundary
(callAlbumGetInfo / callArtistGetInfo), matching how the Deezer agent maps its
client's not-found, and log it at Debug instead of Error — which also removes
the not-found log spam.

* feat(artwork): log external image-lookup failures at debug

The worker's res.reader==nil && extError branch returned outcomeFailed with no
log, so a failing external cover lookup (agent error, dead image URL, download
timeout) was undiagnosable. Log the agent, entity, and underlying error at the
fetch site where it's in hand — this surfaced a Last.fm album.getInfo returning
an image URL that itself 404s.

* fix(artwork): treat a 404/410 image URL as not-found, not a transient fault

An agent (notably Last.fm's album.getInfo) can advertise a cover URL that is
itself dead — a 404. sources.go's fromURL returned a generic error for any
non-200, so a dead URL was treated as a transient failure: it churned in
backoff and counted toward the circuit breaker, stalling valid lookups.

Map 404/410 to model.ErrNotFound in fromURL so a dead URL settles absent, and
collapse the near-identical fetchPlaylistImageURL (which already did this for
M3U covers) into it.

* feat(artwork): make artwork re-resolution targeted, not blunt

Two gaps in when the pipeline re-resolves artwork:

The recheck job only requeued absent-state rows (hash=''), so an entity that was
never processed — added between scans, or on a server with the scanner disabled —
had no periodic safety net and stayed without artwork indefinitely. Add
EnqueueMissing(kind): a SQL set-difference enqueueing entities with no
item_artwork row at Recheck priority (ON CONFLICT DO NOTHING, so it never
disturbs a queued row). Run it once at startup and hourly alongside the
stale-absent recheck. Rename staleAbsentKinds -> recheckKinds accordingly.

Conversely, the config fingerprint included consts.Version, which embeds the git
SHA and so changed on every build, re-enqueueing every entity in the library
(~34k here) and re-querying external agents at the configured RPS for anything
without local art. Replace it with an explicit artworkEpoch constant, bumped
deliberately when resolution semantics change. The cases that motivated the
version input — absent art becoming available — are already covered by the
stale-absent and missing-row rechecks; only a corrected wrong-pick needs the
epoch. A test guards against reintroducing the version.

* test(artwork): restore resolution edge-case e2e coverage

The serving cutover removed the album/disc/artist/mediafile/playlist/radio e2e
specs that documented the folder-selection rules and guarded the #5376/#5456/
#5451/#5457 regressions; nothing replaced them, so compareImageFiles and the
parent-fallback logic were left untested.

Restore them driving the real pipeline: a real scanner populates the folder
graph from an in-memory library, the real Worker drains the queue, and the real
Service serves. Folder-backed art is file-backed (served via os.Open, which the
in-memory FS can't satisfy) so its selection is asserted on the persisted state
row; store-backed and real-disk sources are asserted byte-for-byte. Single-disc
disc resolution now serves album art directly, so only multi-disc disc scenarios
are ported.

* fix(artwork): run disc resolution for single-disc albums too

ed4178a6 gated serveDisc on len(album.Discs) > 1, claiming parity with the legacy
reader. The legacy reader has no such gate: artwork.go dispatches every dc- id to
newDiscArtworkReader, whose Reader() walks DiscArtPriority unconditionally.

The gate also lost art. For a single-disc album whose only image is disc1.jpg,
the disc request skipped the chain and fell through to album art, which does not
match CoverArtPriority — so tracks tagged disc 1 (whose CoverArtID is a dc- id)
served nothing at all, where before they served disc1.jpg.

A single disc can legitimately have its own cover, distinct from the album's, and
DiscArtPriority is what expresses that preference. Drop the gate and restore the
single-disc e2e scenarios that covered it.

* fix(artwork): register the GIF decoder in core/artwork

The deleted artwork.go carried blank imports for image/gif and
x/image/webp. WebP came back via resize.go's gen2brain/webp, which
self-registers, but GIF did not: core/artwork claims GIF support in
mimeForFormat and extForMime while relying on an unrelated server
package to have imported the decoder.

The guard lives in the e2e suite because that test binary has no other
image/gif importer; a spec in core/artwork would pass regardless, since
animation_test.go imports the package non-blank.

* fix(artwork): never record absent after a local I/O failure

Local sources swallowed their open errors, so a stale NFS/SMB mount was
indistinguishable from "this entity has no artwork": the chain returned
no reader, processItem took the absent branch, and the upsert replaced a
good content hash with the empty string. Clients then saw a placeholder
until the 1h request recheck or the 24h stale-absent sweep, and the
orphaned bytes became eligible for the next prune.

A candidate the resolver knows about — a file in the folder listing, a
track's own audio file — failing to open is not evidence of absence, so
it now forces a retry the same way an external agent error does.

* fix(artwork): keep served art when the retry budget runs out

Exhausting the 12h budget called writeAbsent unconditionally, so an
entity whose art was already resolved and serving lost it to a long
upstream outage: the hash went empty, clients fell back to the
placeholder, and the now-unreferenced bytes were freed by the next
prune even though nothing about the image had changed.

Exhaustion means the source stayed unreachable, not that the cover
disappeared, so absent is now recorded only when there is nothing to
keep.

* fix(artwork): restart the retry budget on re-enqueue

The conflict clause updated only priority and retry_at, so a row that
already existed kept its original attempts and enqueued_at. The worker
measures the 12h give-up budget from enqueued_at, so any row that had
been pending across a longer gap — a server left off, an upgrade, a
laptop asleep — gave up on its very first attempt and settled absent.

The manual re-resolve endpoint is the sharpest case: it clears artwork
state and re-queues, but inherited the old row's spent window, so a
deliberate retry got one shot. A fresh request now gets a fresh budget,
with the mock updated to match.

* fix(artwork): keep not-found distinct from artwork-absent

GetOrPlaceholder folded model.ErrNotFound in with ErrUnavailable, so an
id matching no entity returned 200 and the placeholder PNG. That made
the ErrorDataNotFound branch in getCoverArt unreachable: Subsonic went
from error 70 to a successful placeholder, and Jellyfin's Primary image
endpoint from 404 to 200. Neither is ours to change.

An entity with no art and an id with no entity are different answers;
only the first is a placeholder.

* fix(artwork): make the prune sweep cancellable

Sweep walked the whole store with no context, and RunPrune holds the
prune write lock for its full duration. In-flight acquisitions park on
the read lock, drain's WaitGroup never returns, and Run never reaches
its ctx.Err() check — so a SIGTERM during a daily prune over a large
store on slow storage waits out the container's grace period and dies
mid-remove.

* fix(artwork): hydrate the tracks reached through a playlist

loadTracks and the playlist-track cursor were the only entity-page
paths that never hydrated artwork state, so a song reached through a
playlist behaved differently from the same song in the songs list:
Subsonic emitted a hashless coverArt id, which imghttp downgrades to
no-cache, and advertised art even for known-absent albums; Jellyfin
emitted AlbumPrimaryImageTag as the bare album id — a tag that never
changes when the cover does — and no blurhash at all.

The media-file hydration moves next to the other hydration helpers so
both paths share one implementation rather than growing a third.

* feat(ui): cross-fade the cover over its blurhash

The blurhash unmounted the moment the blob arrived, so the placeholder
vanished a frame before the image painted. The image now mounts
transparent and fades in over the blurhash, which stays behind it until
the fade completes. A blob already cached when the instance mounts
skips the fade, so a remount does not re-animate.

* fix(ui): retire the blurhash on a timer, not transitionend

Under prefers-reduced-motion the img rule sets transition:none, so
toggling opacity fires no transitionend and the handler that unmounts
the blurhash never ran. The placeholder stayed mounted for the life of
the component — visible in the letterbox bars wherever the cover is
rendered with fit="contain", and a live canvas per tile everywhere else.

One duration constant now drives both the CSS transition and the timer,
so they cannot drift.

* fix(artwork): stop advertising a hash for bytes that won't be served

Hydration stamped the album's hash and blurhash onto an embedded-eligible
track that had no state row yet. Serving takes provisionalEmbedded for
exactly that case and returns the track's own embedded image, so the id
carried a content-version belonging to a different picture: every such
request fell back to no-cache instead of immutable, and a client keying
its cover cache on the blurhash paired the album's with the track's art.

AlbumCoverArtID had the mirror-image problem, building the album id from
the track's own ItemImage. It happened to work only because hydration
overwrote ImageHash in precisely the fallback cases; a track with its own
resolved art would have stamped that hash onto the album's id.

* perf(artwork): precache from the bytes just acquired

Warming the resize cache re-read the two rows and the file the
acquisition had just written, so every acquired image cost two extra
queries and a second full read of a file whose bytes were still in
memory. processItem now hands back what it persisted and precache warms
from that, under the same cache key the serving path computes.

Resolving the admin user also moves behind the empty-queue check: it is
needed only to resolve private playlists, so an idle server no longer
runs a user lookup on every poll.

* perf(artwork): keep the worker pool fed across a drain

The pool was fed from a batch sized to the pool itself (2x concurrency)
with a WaitGroup barrier before the next dequeue, so one item burning
its external timeout idled every other slot until it finished. The
legacy cache warmer had no such barrier: it streamed through a pipeline
of 4.

Dequeuing well past the pool keeps the slots fed for the whole pass at
no extra cost, since DequeueBatch does not mark rows taken and was
already one query per pass. Acquiring a slot now also observes
cancellation, so a larger batch cannot delay shutdown.

* perf(artwork): drain local and external artwork in separate pools

A first backfill enqueues artists before albums at a single priority, so
the drain took them in that order. Artists resolve through a
rate-limited agent, and gate() waits for its permit while holding a
worker slot, so the whole pool sat asleep in the limiter with every
album queued behind it.

Measured on a 96k-track library (29,115 artists to 6,949 albums, 4:1):
zero albums resolved in seven minutes, and roughly 3.3 hours before the
first album cover would have appeared. Splitting the drain gives each
class its own slots: albums now finish in under eight minutes while
artists trickle at the same 2/s they were always limited to.

The two budgets are carved out of MaxOpenConns so a second pool cannot
take connections the scanner and the UI need. Dequeue filters by kind,
and the drain index leads with item_kind so each pool seeks to its own
work instead of scanning past the other's backlog.

* fix(artwork): treat an unreadable upload as a failure, not a miss

resolveLocalFile swallowed every os.Open error, so uploads, playlist
sidecars, a local M3U image and the artist image folder still had the
bug that was fixed for folder and embedded sources: a permission or
transient I/O error on a file that exists read as "no image here". The
worker then settled the item absent and dropped its queue row.

Uploads outrank every other source, so an unreadable one now stops the
chain rather than letting a lower-priority image be persisted in its
place. A genuinely missing file stays a clean miss.

Reported by Codex on #5847.

* fix(artwork): make the pool-split worker test race-clean

CI runs the suite under -race, which the local `make test` does not, so
this only showed up there: 230 specs passed and the detector still
failed the run.

The drain-pools spec started Run and never waited for it, so pool
goroutines outlived the spec and raced the config snapshot Ginkgo
restores on cleanup. It now cancels, unparks the blocked lookups and
waits for Run to return.

Two test doubles also had to become concurrency-safe, since the spec is
the first to resolve several artists at once: fakeImageAgent's call
counters, and MockAlbumRepo.GetAll, which records the last query options
on a read path. MockDataStore's lazy accessors get the same treatment —
only MediaFile was guarded before, and two pools now reach them
concurrently. ArtworkQueue takes an unlocked helper for its internal
Artwork call, since repoMu is not reentrant.

* perf(artwork): stop reading and hashing disc art on every request

The resize-cache key was the content hash, which cannot be computed
without reading the file, so a warm cache never prevented the I/O: every
sized disc request read up to 20MB and hashed it before the lookup. The
legacy reader keyed on the id and the album's mtime and touched the file
only on a miss.

Disc art has no state row and therefore no stored hash, so the key is
that same identity — id, album mtime, DiscArtPriority — and the
selection chain now runs only when the cache misses. Full-size requests
stream the source instead of buffering and hashing it.

This matters more now that single-disc albums keep running the disc
chain, which puts every disc-tagged track without embedded art on this
path.

* fix(artwork): key disc art on folder image changes, not just the album

The identity cache key used album.UpdatedAt alone, which a replaced
disc image does not necessarily move — the sized response would then
serve the old image indefinitely. The legacy reader folded ImportedAt
and the folder's ImagesUpdatedAt into its key for exactly this reason,
and loadAlbumFoldersPaths already returns that timestamp; the disc
reader was discarding it.

* fix(artwork): return undispatched items when a drain is cancelled

claim() reserves the whole batch before dispatch, but the cancellation
path returned without releasing what it had not yet started, leaving
those items in the in-flight set permanently — no later drain could
claim them again.

Harmless until the batch grew past the pool size; now a cancel strands
up to a full batch. The e2e harness cancels mid-drain after every
acquire, so it surfaced there first: one spec timed out waiting for an
item that had been claimed and abandoned, and the suite went from 59s
to 87s on CI.

* fix(jellyfin): make a track's own cover reachable for Jellyfin clients

Media files are never enqueued — the scanner drops their state without
queueing them and the recheck kinds exclude them — so an unresolved
track keeps an empty ImageHash and SongToBaseItem always fell through to
AlbumPrimaryImageTag. Finamp then asks for the album image, nothing ever
requests mf-, and the read-through that resolves the track never fires:
the own-cover branch was unreachable for Jellyfin-only users.

An eligible, unresolved, not-known-absent track now advertises its id as
the Primary tag, which is what makes the client ask. The request serves
the embedded art and queues the track so the worker persists a real
hash. No blurhash is sent, since none exists yet and a fake would be
cached against that tag forever.

Serving gains the album fallback that made this safe to advertise: an
eligible track whose frame will not extract now falls back the way
CoverArtID does instead of answering with a placeholder.

Reported by Codex on #5847.

* fix(artwork): treat an unreadable artist-folder image as a failure

Third and last site in this class: findImageInFolder logged and skipped
an image the glob had already matched, so a permissions or mount failure
during the artist-folder traversal read as "no image here" and let
processItem settle the artist absent, discarding any artwork already
resolved.

A matched-but-unreadable file now propagates through fromArtistFolder
and lands as localError, the same as album folder art, embedded art and
uploads. A folder with no match stays a definitive miss.

Also normalizes the e2e path assertions with filepath.ToSlash: the
stored SourcePath is OS-native, so the forward-slash suffixes failed
all 23 folder specs on Windows.

Reported by Codex on #5847.

* fix(artwork): give full-size disc art a real ETag

Regression from 04d5a556. Keying the resize cache on identity meant the
disc response no longer carried a content hash, and the full-size branch
set no ETag either — so WriteImageHeaders fell back to the empty hash
and emitted `ETag: ""` for every full-size disc image. Since ifNoneMatch
compares the unquoted value, a client echoing that back matched, and got
a 304 even after the image was replaced.

The full-size branch now carries the same identity validator the sized
branch uses, so it moves when the folder's images change.

WriteImageHeaders is hardened against the class as well: an empty
validator is no validator, so it is neither emitted nor matched.

Reported by Codex on #5847.

* test(artwork): inject the unreadable source instead of chmod

os.Chmod cannot revoke read access on Windows — it only toggles the
read-only attribute — so the findImageInFolder spec opened the file
happily and failed there, and the upload spec passed for the wrong
reason: outcomeFailed came from the 1-byte payload failing to decode,
not from the source being unreadable.

findImageInFolder takes an fs.FS, so the failure is now injected and
the spec is filesystem-independent. The upload path goes through
os.Open directly and has nothing to inject, so it skips on Windows
rather than pretend to cover it.

* fix(artwork): compare the pixel cap without multiplying

Defence in depth rather than a live hole: the reported crafted PNG
(0xffffffff square) never reaches the multiplication, because
image/png rejects it at DecodeConfig, and the largest dimensions any
supported format can declare — 2^30-1 for PNG, 16-bit for JPEG and
GIF, 14-bit for WebP — cannot overflow the int64 product.

decodeCapped is format-agnostic though, so the guard should not depend
on a decoder's own limits staying where they are. Comparing by division
holds for any dimensions a decoder might report, and non-positive ones
are now rejected outright.

* refactor(ui): rename cover artwork components

* fix(ui): remove Artwork rendering gate

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

* fix(cache): re-fetch when a cache entry outlives its data file

fscache's Remove drops the in-memory entry, releases the lock, and only then
unlinks - blocking until every outstanding reader closes. A Get landing in that
window re-creates the file at the same path under a fresh entry, and the deferred
unlink deletes those new bytes. The entry survives pointing at nothing, and since
a present entry is treated as a hit, every later Get for that key returns ENOENT
for the rest of the process's life. Only a restart, which rebuilds the map from
disk, cleared it.

Get now drops such an entry and retries once, so a vanished data file costs one
re-fetch instead of poisoning the key permanently. This also covers a file
disappearing for reasons unrelated to that race, such as external deletion or a
restored backup.

Specs cover an in-process entry, one adopted at startup, and the deferred-removal
race itself.

* fix(artwork): log why a sized cover fell back to the placeholder

serveHash routed every non-cancel cache error into dangling(), which returns
ErrUnavailable and is then rendered as a placeholder at 200 OK. A cache-layer
fault was therefore indistinguishable from an album genuinely having no artwork,
and left no trace: a broken resize cache silently served placeholders for a
quarter of the library while the logs stayed clean.

Log the error before falling back, so the cause is recoverable from the logs.

* fix(artwork): precache the cover variant the UI actually requests

precache built its resizedItem without setting square, so it warmed
h-<hash>.<size>.false.<quality>. The list surfaces - album grid, artwork avatars,
playlist and radio details - all request square covers, so the warmed entry was
never read and every grid cover stayed a cold miss on first view.

Set square on the precache item so the key matches the request path. The existing
specs asserted the '.300.false.' key and were updated accordingly.

* fix(cache): give a re-created cache entry its own file

Create re-opened the path with O_TRUNC, which shrinks the file out from under an
older stream that may still be serving readers. stream.Reader then hits EOF from
the OS at the new, shorter length while the broadcaster still reports the original
size, so Wait() reports 'more data exists' and the reader retries forever - a tight
pread loop that burns a core and never releases its handle, which in turn blocks
Stream.Remove() indefinitely.

Unlink first and create with O_EXCL so the new entry gets a fresh inode. Existing
readers keep their descriptor on the old inode, see its full contents, and reach a
clean EOF.

Note this does not address the deferred unlink deleting the re-created file, which
is handled separately by the re-fetch in fileCache.Get.

* fix(cache): keep the in-place truncate on windows

Unlinking before re-creating fixes the premature-EOF spin on unix, but Windows
refuses to remove a file another handle still has open and returns a sharing
violation. Because Create surfaces that error, every cache miss on a path with a
live reader would have failed outright - worse than the spin it was meant to fix.

Split the create behind a build tag: unix unlinks for a fresh inode, Windows keeps
truncating in place and stays exposed to the spin, which is the behaviour it
already had. The unix-only spec is skipped there.

* fix(artwork): shape the blurhash placeholder to the artwork's aspect ratio

The UI decoded every blurhash into a 32x32 bitmap and stretched it to fill its
container, so a non-square cover showed a full-box blur that collapsed into a
letterboxed image the moment it loaded. On the album detail page the
placeholder overhung the image by a third of the box height.

A blurhash string carries no aspect ratio of its own, so the dimensions have to
come from the server. artwork.width/height were already stored and read by
nobody; they now surface on ItemImage as imageWidth/imageHeight, hydrated
through the join that was already in place. Existing rows already carry them,
so no migration or rescan is needed.

A square request is padded rather than cropped, which aspect-fits the content
inside the square the server returns. That made the grid a second instance of
the same bug, so `square` now implies contain for the image as well as the
placeholder, instead of the two renderers reading it differently.

* feat(jellyfin): expose PrimaryImageAspectRatio

Real Jellyfin carries width/height of the Primary image on BaseItemDto
(MediaBrowser.Model/Dto/BaseItemDto.cs), attaching it only when the request's
Fields asks for it (DtoService.cs ContainsField). The dimensions are now on
model.ItemImage for the web UI's blurhash placeholder, so the adapter can
report the same thing for free.

Gated behind Fields to match, and omitted rather than defaulted when the item
has no image or unknown dimensions: real Jellyfin falls back to a per-type
default of 1 for music, but a wrong ratio mis-shapes a client's placeholder,
and we only lack dimensions when the artwork is genuinely unresolved.

primaryImageTag becomes primaryImage, returning the tag, blurhashes and ratio
together, so the choice of which image is Primary is made once per mapper
rather than the same ItemImage being threaded through two calls.

ArtistToBaseItem and PlaylistToBaseItem take Fields now, like the album and
song mappers already did.

* refactor(model): give ItemImage an AspectRatio method

The zero/absent guards around width/height are ItemImage's own invariant, not
the Jellyfin adapter's. Moving them onto the model keeps one definition for
every consumer, so a second one cannot quietly disagree about what an unknown
ratio means.

* fix(ui): anchor detail pages to the top when opened from a list

React Router keeps the previous page's scroll offset, so opening an album from
a scrolled list started the detail page mid-song-list. Artist pages had the
same bug; it just shows less because the artist list is rarely long enough to
scroll far.

Keyed on the record id rather than mount, so detail-to-detail navigation (an
album's artist link) resets too, and so the scroll waits for the record instead
of firing against an empty page.

* fix(ui): stop the Random album grid collapsing on every keystroke

The grid was replaced by a spinner whenever the random list was loading, so
each search keystroke collapsed it to spinner height and back. That blanket
blanking is the flicker commit 9e559311a removed for every other list; random
kept the exception so a re-roll would not flash the roll it is replacing.

Blank on a seed change instead of on any load: a re-roll gets a new seed and
still blanks, while a search keeps the seed and leaves the grid in place. The
seed is tracked from empty rather than from the current value because a re-roll
redirects and remounts the grid, which would otherwise look already-settled
with the previous roll still on screen.

Same rule for the pagination, which was hidden on the same condition.

* refactor(artwork): move fingerprint property key const to `consts` package

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

* refactor(tests): enhance database handling with resettable tables and truncation

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

* refactor(artwork): narrow the prune lock and drop redundant in-flight tracking

The prune read-lock wrapped all of processItem, including external fetches under
their own timeout. Since a pending RWMutex writer blocks new readers, one prune
arriving behind a slow provider stalled every subsequent item in both drain
pools. Extract persist() so the lock covers only the window it protects: store
placement plus the two row writes.

The in-flight set guarded against a queue row appearing twice in one batch, but
artwork_queue's primary key makes that impossible, drains are serial per pool,
and the pools' kind lists are disjoint. Removing it also retires the cancellation
unwind loop that existed only to release those claims.

* fix(artwork): never settle absent for a kind no recheck job revisits

The 12h retry budget hands a bare failure to the periodic stale-absent
sweep, which is what makes the resulting absent row recoverable. Media
files are deliberately excluded from that sweep -- they resolve embedded
only, at scan or on view -- so exhausting the budget on a transient read
error recorded a "this track has no cover" verdict that nothing would
ever revisit.

Settle absent only for kinds a recheck job covers. Without a row the
track stays unresolved, so the next view re-enqueues it.

* refactor(artwork): remove dead plumbing from the serving path

artworkReader.LastUpdated had no callers: invalidation rides entirely on
the cache key, so the interface member, the resizedItem field and its
four assignments were vestigial. Reader's second return value was
likewise discarded at all three call sites.

resizedItem.Key duplicated representationTag's format string over
identical inputs, where drift would serve a wrong-keyed entry under a
right-looking validator; it now derives from it. newResizedItem had one
caller and a doc comment claiming a sharing with worker.precache that
never existed -- precache builds its own literal.

Also unexport Prune, which no caller outside the package used while
RunPrune documented itself as the only sanctioned path, drop a
single-call placeholder wrapper, and delete five fakeFolderRepo fields
no spec ever set.

* refactor(artwork): drop queue repository methods only tests called

MarkFailed and Delete had no production caller: the worker only ever uses
MarkFailedIfUnchanged and DeleteIfUnchanged, which refuse to act on a row
a concurrent scan re-enqueued. Keeping the unconditional pair meant the
interface offered the racy variant under the more obvious name.

MarkFailedIfUnchanged does not build on MarkFailed, so nothing in the
implementation needed them either. The repository tests used them to put
a row into a backed-off state; they now do that directly.

* test(artwork): pin that a request never fetches or samples album art

resolveItemLocal's guard against the remote ExternalImageURL fetch and
the 2x2 grid had no coverage: deleting it left the whole suite green
while putting synchronous network calls on the request path.

The worker resolving the same playlist is asserted alongside, so the
spec cannot pass by simply resolving nothing.

* refactor(artwork): give the resolver a receiver and one capability field

The resolve* chain walkers each took seven parameters -- ds, agents,
ffmpeg, gate, localOnly -- while the package already had workerDeps
bundling the same collaborators for processItem. They are now methods on
a resolver.

The external capability is one nilable field instead of three values
that had to agree. Previously a local-only resolution passed agents=nil,
gate=denyGate and localOnly=true, and only the localOnly check actually
protected anything: the external branch dereferences agents in the loop
header, before the gate closure runs, so denyGate could never fire. It
is deleted. A nil ext now both marks the resolution local-only and
removes the agents there were to dereference, and newLocalResolver takes
no parameter that could supply one.

The playlist tile loop hardcoded localOnly=false, safe only because an
early return 22 lines above it made that unreachable; it now inherits
the resolver's capability.

* refactor(artwork): funnel every served representation through one path

serveHash, serveBytes and serveDisc each hand-copied the same five steps
-- test for full size, stream or build a resizedItem, call the cache,
wrap with a validator -- with a different error policy bolted on. The
ETag rule was restated at four sites and applied inconsistently.

serveSource now states it once: full size streams open() directly, and
an ETag is attached only when the bytes are resized or there is no hash
to validate against. Each caller keeps just its own error policy, and
serveBytes folds into its single caller.

Two behavior changes fall out, both narrowing an aborted request's blast
radius: serveDisc propagates context.Canceled instead of falling back to
a full album resolution, and serveHash's full-size path propagates it
instead of going dangling, which would have enqueued a re-resolution for
a request nobody is waiting on.

* style(artwork): use one log prefix, spelled the way the codebase does

The package logged under three spellings of its own name -- "artwork: "
lowercase, "Prune: " and one "Artwork: " -- and the lowercase ones
carried lowercase message text, against 568 capitalized to 48 lowercase
elsewhere.

Prefixing itself is the convention here (Scanner:, API:, Watcher:) and
it earns its place: DevLogSourceLine is off by default, so without it a
line does not say which subsystem emitted it. So this normalizes the
spelling rather than dropping the prefix. Error strings stay lowercase
and unprefixed per Go convention.

* refactor(artwork): give workerDeps only what the processor uses

The bag carried cache, which processItem never reads and only the
worker's precache uses, and carried agents/ffmpeg/gate solely to
reconstruct a resolver on every queue item. cache and ffmpeg move to
Worker, where precache actually uses them, and the resolver is built
once in NewWorker.

persist's hash parameter was redundant: decodeArtwork sets Hash and
GetImage selects it, so art.Hash already holds it on both paths.

The type itself now lives beside Worker, which owns it, rather than in
the file of the function it is passed to.

* refactor(artwork): make acquisition a processor with its own receiver

workerDeps was a parameter bag threaded into two free functions that
nothing outside the worker calls. It becomes the processor type, with
processItem and persist as acquire and persist methods on it, and Worker
holds one collaborator instead of reaching through a bag.

Kept as a separate type rather than folding onto Worker: acquisition
takes a queue item and returns bytes, while Worker.process settles the
queue row around it. That boundary is what keeps retry policy out of the
image pipeline, and what lets the acquisition specs build a three-field
value instead of a Worker with drain pools, gates, a broker and a
real on-disk cache.

* refactor(artwork): collect the external gate contract in one file

gateFunc, passthroughGate and isTransientExternal sat in agent_images.go
while every implementation lived in worker.go: extGate, breaker,
Worker.gate, gateFor. isTransientExternal even carries a comment saying
it must stay consistent with breaker.record, which was in the other
file -- a rule spanning two files with only a comment holding it
together.

Pure move into gate.go: no symbol added or removed.

* refactor(artwork): put the whole playlist grid in playlist_cover.go

decodeTile and assembleTiles were in resolve.go while the geometry they
depend on -- rect, fillCenter, tileSize -- was in playlist_cover.go and
used nowhere else, so one file held the grid's helpers and another its
assembly.

Pure move.

* refactor(artwork): move resizedItem next to the interface it implements

resizedItem is the only implementation of artworkReader, which is
declared in image_cache.go, and it is used by the worker's precache as
well as the serving path -- so worker.go was reaching into serving.go
for a cache type. representationTag stays in serving.go, where the
HTTP validator belongs.

Pure move.

* refactor(artwork): fold Refresh into housekeeping

refresh.go was a 21-line file for one function that clears artwork state
and enqueues -- the same thing Backfill, EnqueueStaleAbsentAll and
EnqueueMissingAll already do next door.

Pure move.

* refactor(artwork): accumulate priority-chain state in one place

Every source in the album and artist chains repeated the same five
lines: stamp the accumulated external failure onto a hit, or OR the
local fault into the running total on a miss. Each new source was a
chance to forget the OR, which is how the local-I/O-settles-absent bug
happened.

chainState.try does both, so each case drops to three lines and the
omission is no longer expressible. Semantics are unchanged: a hit still
carries extErr only. Also drops localErr from resolvePlaylist, which
declared it but never assigned it.

* refactor(artwork): expose housekeeping through the Worker

scheduleArtworkHousekeeping received a *artwork.Worker and then called
CreateDataStore() for a second handle onto the state that Worker already
owns, because Backfill, EnqueueStaleAbsentAll and EnqueueMissingAll were
free functions taking a DataStore.

They are now Worker methods over unexported implementations, the same
shape prune/RunPrune already uses: one public path, and the specs keep
calling the plain function with a mock store instead of standing up a
Worker. Fingerprint is unexported too -- nothing outside the package
used it.

* refactor(artwork): name the service for its domain, not its role

Every other core interface is named for what it is -- Playlists,
Library, Scrobbler, MediaStreamer -- while this one was artwork.Service,
the only X.Service in the tree. It becomes artwork.Artwork/NewArtwork,
and serving.go follows the type to artwork.go.

ProvideImageStore was likewise the only "func Provide" in the repo; it
is GetImageStore now, matching GetImageCache beside it. cmd/wire_gen.go
regenerated via make wire.

* docs(artwork): give each Worker housekeeping method its own godoc

The three methods shared one comment attached to Backfill, so godoc
rendered the other two undocumented and the one it did show described
the group rather than the call. Each now opens with its own name and
says what that call does, including Backfill's bool return.

* refactor(artwork): move fakeFolderRepo to artwork_suite_test.go

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

* refactor(artwork): unexport artwork.HashImage function

* fix(log): stop ShortDur eating significant trailing zeros

TrimSuffix(s, "0s") was meant to turn "4h0m0s" into "4h", but it strips
any trailing "0s"/"0m" -- so 10s logged as "1", 20s as "2", 1m30s as
"1m3", 2h30m as "2h3", and a zero duration as the empty string. Every
elapsed/duration field in the app was affected.

The suffix now has to include the preceding unit, so only a whole
zero-valued component is dropped. The existing table only covered values
that dodge the bug (4m, 4h, 4m3s); added the ones that don't.

* feat(artwork): prefix every log message and time the slow steps

Prefix: 22 messages still logged unprefixed, so a line from this package
was indistinguishable from any other subsystem's. All 40 now carry
"Artwork: ", matching Scanner:/API:/Watcher: -- which earns its place
because DevLogSourceLine is off by default.

Timing on what can actually be slow: total per acquisition (on every
exit, failures included), the read that also covers the provider
download, hashing, decode+blurhash, resize, drain batch, precache,
prune, backfill, and the external agent call -- with the rate-limiter
wait counted separately, since a throttled agent and a slow one look
identical from the drain.

Debug coverage for states that were previously silent: dedup hit vs
decode, settling absent, serving a lower-priority source after an
external failure, retry scheduling with attempts and budget left, giving
up when the budget runs out, breaker open/close per agent, provisional
read-through, dangling state rows, and the mtime mismatch that makes art
appear to vanish. outcome gained a String() so it reads as a name.

* refactor(artwork): log decoded dimensions as fields, not a formatted string

fmt.Sprintf ran on every newly-decoded image even with Debug off, since
Go evaluates log arguments regardless of level. Separate width/height
fields also query better than a "300x300" string.

Correction to e0f1acd1a's message: it said "all 40" messages carry the
prefix. The package has 68 log call sites and 62 distinct messages; 40
was only what the test suite happened to exercise. The sweep itself was
complete -- zero unprefixed messages remain.

* fix(subsonic): stop serving artwork for a deleted radio

artworkAccessible checked every kind except radio, which fell through to
the default "no per-user access control" branch and returned true without
a lookup. Radio deletion removes only the entity row -- item_artwork and
the uploaded file survive until the next prune -- so the old ra- id kept
serving the removed radio's image for up to a day.

This is a regression against master, where newRadioArtworkReader loaded
the radio first and returned its error, so deletion took effect at once.
Radios stay globally visible; only existence is checked.

CreateMockedRadioRepo left Data nil, so its own Put panicked on first
use; initialized it.

Reported by Codex on #5847.

* fix(artwork): stop serving artwork for entities that no longer exist

Artwork state and its bytes outlive a deleted entity until the next
prune (@daily), and the serving path consulted only item_artwork, so a
Subsonic id or a signed public token kept serving a removed entity's
image in the meantime. Master's readers loaded the entity first, so this
was a regression.

The check goes in serveHash, the one path that can hand back a found
row's bytes: absent rows are already unavailable, and the provisional
and disc paths load their entity to resolve at all. Doing it there
instead of per-handler also settles who owns the invariant. Subsonic had
worked around it with artworkAccessible, whose comment described the
service "bypassing the library and private-playlist filters"; that
workaround is now deleted, since the service resolves through the
request-scoped repositories and enforces the filters itself.

Because those repositories are ctx-scoped, each caller says what it
wants by what it passes: Subsonic hands over the request context and so
gets visibility as well as existence, while the public image route
elevates like the Jellyfin one already did -- a token is the
authorization there, and a visibility check would hide a shared private
playlist, the very case shares exist for.

Two supporting fixes. albumRepository.Exists and mediaFileRepository
.Exists used the plain exists() helper, which applies no library filter,
so they reported rows in libraries the caller cannot see; they now count
through applyLibraryFilter as CountAll and artistRepository.Exists
already do. Neither had a production caller. RadioRepository gained the
Exists it lacked.

Tests follow the layers: the service refuses a found row whose entity is
gone, the repositories hide rows the caller may not see, and the
handlers only assert the context they hand over. Jellyfin needed no
change -- resolveArtworkID probes the entity tables, so a deleted item
yields an empty artwork id -- but that protection was incidental and
untested, so it is pinned now.

* fix(playlist): rebuild the generated cover only when the tracks change

The enqueue sat in refreshCounters, which Put also reaches for an
ordinary metadata update, so renaming a playlist or editing its comment
re-resolved the cover. The 2x2 grid samples albums with random(), so
that silently handed the playlist a different cover for an edit that
touched no tracks -- and refetched remote artwork to do it.

It now happens where the track set actually changes: addTracks (which
Put-with-tracks and updatePlaylist both funnel through) and renumber
(reached from removeOrphans). Creation still enqueues even with no
tracks, since an imported m3u can carry an ExternalImageURL.

Reported by Codex on #5847.

* style(artwork): trim verbose comments to the 1-2 line budget

Comments only; no executable code changed. Verified by comparing the Go
token stream of every touched file before and after: identical.

Removes 375 of the 1104 comment lines this branch added, targeting content
that belongs in a commit message or PR body rather than in the code:
rejected alternatives ("DeleteIfUnchanged, not Delete", "Waking all beats
routing by kind"), refactor history ("as the legacy reader did"), issue
references (#5798, #5597, #5376), benchmark numbers (~400ms, ~16k allocs),
and four persistence doc comments that duplicated the interface godoc in
model/artwork.go verbatim.

Comments predating this branch are left untouched.

The ASCII fixture trees in the e2e suites are deliberately kept above the
line budget: they diagram the fixture layout with its expected outcomes,
and every pre-existing block in those files carries one.

* test(artwork): make the artists-first backfill assertion non-vacuous

The follow-up loop could never fail: once the first "ar" index is asserted
to be 0, every non-"ar" element is necessarily at an index greater than 0.
A sequence like ["ar", "al", "ar"] passed both assertions, which is exactly
the interleaving the check exists to forbid.

Assert the partition directly instead: nothing after the first non-artist
call may be an artist. Verified by mutation — enqueueing artists a second
time after albums now fails the spec.

* refactor: use stdlib slices/maps and utils helpers in artwork code

Mechanical cleanups, no behavior change:

- 15 copies of the same id-extraction loop collapse to slice.Map (5 repo
  mocks, the scanner's track sweep, 4 wantIDs assertions) and slice.ToMap
  (6 index-by-id loops in the hydration specs).
- disc.go built a map[string]bool purely to dedup folder ids and then
  walked it back into a slice; slice.Unique says that directly.
- folders_artist.go's image filter is slice.Filter over model.IsImageFile.
- mock_artwork_repo deleted from a map while ranging it; maps.DeleteFunc
  states the intent.
- sort.Slice -> slices.SortFunc + cmp.Or; math.Min/Max -> builtin min/max;
  make+copy -> bytes.Clone; strings.Split -> SplitSeq on a per-request
  path; three-clause pixel loops -> for range.
- Reuse utils.BaseName where a stem was recomputed by hand. Not at
  playlist_cover.go:27: that path is a full OS path and utils.BaseName
  uses path.Base, which does not split backslashes.
- Drop a dead nil-guard in agents.go: getAgent returns a bare nil
  interface, and a type assertion on nil already yields ok == false.

cmp.Or was rejected for the gate fallback (func types are not comparable,
does not compile) and for ItemArtwork.AttemptedAt (cmp.Or compares
time.Time with ==, which includes loc; IsZero does not).

* refactor(persistence): collapse the four hydrateArtwork copies into one generic

album/artist/playlist/radio each carried the same eight lines, differing
only in element type and model.Kind. hydrateItems takes a ref callback
yielding an item's id and the ItemImage to fill, which is all that varied.

The len()==0 guards drop out: hydrateItemImages already short-circuits an
empty id list, and both loops are no-ops on an empty slice. applyItemImage
stays as-is; hydrateMediaFileArtwork and its own specs still use it.

* perf(scanner): stop reprocessing album and artist artwork on every full scan

A full scan re-imports every track, so the per-entity artwork enqueue in
persistChanges fired for every album and artist in the library — measured as
100% of both on a live instance, and ~8.5k artists / ~16.7k Deezer fetches on a
96k-file library. Re-importing a track is no evidence the art changed: artist
art has no track-content source at all, and the albums re-derived to identical
hashes across three consecutive scans.

Enqueue through EnqueueIfMissing on a full scan, which anti-joins item_artwork
so only entities that never resolved are queued. Incremental scans keep the
unconditional Enqueue, where a re-import does mean the file changed. Doing this
at the enqueue site rather than skipping it wholesale keeps a first scan filling
in covers as it walks, instead of stalling every cover until the scan ends.

EnqueueMissing grows a priority argument and runs once at end of scan, so an
entity phase 1 never saw still resolves, at Scan priority rather than dropping
to Recheck behind the backfill.

* refactor(artwork): derive blurhash components inside Encode

Components had a single caller, which only ever fed it the bounds of the image
it then passed to Encode. Exporting it gave callers two ways to get it wrong —
components mismatched with the image, or out of the 1..9 range — in exchange for
a knob nobody turned.

Derive them from img.Bounds() at the top of Encode and unexport the helper. The
counts must come from the pre-downscale bounds: downscale's integer rounding can
shift the ratio across a component boundary, and the hash is a client-side cache
key. Verified byte-identical over 18 hashes spanning 9 aspect ratios.

The out-of-range validation goes with it, being unreachable once the counts are
always derived. The aspect-ratio table now asserts through Encode's size flag,
which encodes (x-1)+(y-1)*9.

* refactor(ui): replace the blurhash package with a local decoder

The UI pulled in the `blurhash` dependency for one function, `decode`, called
from a single component. The decoder is ~80 lines of well-specified arithmetic,
so carrying a dependency for it costs more in supply chain and bundle than it
saves.

Equivalence was proven against the package before removing it: 84 hashes — three
real ones plus every component count from 1x1 to 9x9 — decoded at six sizes,
compared byte for byte, plus parity on which malformed inputs throw. Those pixel
values are now pinned in the spec, so drift from the reference algorithm fails.

The punch parameter is dropped rather than reproduced: no caller passes one, and
the package applies `punch | 1`, which silently turns a punch of 2 into 3.

* refactor: simplify the artwork enqueue and blurhash paths

Cleanup pass over the three preceding commits.

Tabulate the cosine terms in the UI blurhash decoder instead of calling Math.cos
per pixel per component: 248us -> 75us for a 32x32 decode, and an album grid
mounts one decoder per tile. Output is unchanged, which the pinned pixel specs
enforce. The Go encoder already tabulated the same terms.

Drop the dead paths that deriving components inside Encode left behind: the
zero-size guard in components, the post-downscale empty check, and the
no-AC-factor branch, which cannot be reached now that the counts are always at
least 1x9. The empty-image check moves ahead of the derivation, where it belongs.

In the queue mock, look up item_artwork by its existing iaKey rather than
scanning the map, and hold the lock across EnqueueIfMissing through a shared
unlocked helper instead of releasing it mid-operation. Extract the duplicated
drain-and-resolve block in the scanner specs into one helper.

* fix(artwork): refresh songs when their album's artwork changes

A track with no art of its own is served its album's, so hydration copies the
album's hash onto the track record. When an album resolution changed, the worker
broadcast only an `album` refresh, leaving song and now-playing surfaces holding
the previous hash-suffixed URL until something else refetched them.

Pair the album refresh with a song one. The dependent id list is unbounded — an
album has arbitrarily many tracks and a drained batch arbitrarily many albums —
so this refreshes the resource as a whole via the protocol's existing wildcard
rather than enumerating ids.

Reported by Codex on #5847.

* feat(persistence): log SQLite result codes on failed statements

SQLite reuses one message for errors that need different responses: "database
is locked" is both SQLITE_BUSY, which busy_timeout retries, and
SQLITE_BUSY_SNAPSHOT, which it can never retry because the transaction's read
snapshot is already stale. Reading only the message, the two are
indistinguishable, and a lock error seen in the wild could not be diagnosed
without guessing which one it was.

Add db.ErrorCodes to unwrap a sqlite3.Error and report its result and extended
result codes, and include them in the SQL error log. The helper lives in db
because that package already owns the driver, so persistence does not need to
import it. Constraint, readonly and disk-full errors share messages the same
way, so this applies to every failed statement, not just locks.

* fix(ui): keep the Random grid blank while a refresh re-rolls

Refresh bumps the list version, which changes the random seed and remounts the
grid. useRollChanged tracked the seed on screen in a ref inside the grid, so the
remount started it empty and adopted the new seed on the first render, while the
refetch had not begun and the store still held the previous roll. The grid
painted the old albums for the length of the request and swapped when the new
roll arrived.

Move the ref up to AlbumList, which a refresh does not remount, and pass it to
the grid and the pagination. The seed on screen then survives the remount, so a
refresh reads as a re-roll and blanks until the new roll lands. A search
keystroke keeps the seed and still leaves the grid in place.

* fix(ui): keep the album grid working outside the Random list

Hoisting the shown-seed ref into AlbumList made the prop mandatory in practice:
ArtistShow renders the same grid through ReferenceManyField and passes no seed
tracking, so useRollChanged dereferenced undefined and the artist page died with
"Cannot read properties of undefined (reading 'current')".

Own a ref in the grid when none is passed. A caller with no roll to track then
behaves as it did before, while the Random list keeps the ref that has to outlive
the refresh remount.

* refactor(config): make the artwork tuning options dev flags

ArtworkWorkerConcurrency and ArtworkExternalMaxRPS become
DevArtworkWorkerConcurrency and DevArtworkExternalMaxRPS, joining the
other DevArtwork* flags. Their defaults should not need tuning, so they
do not belong in the documented, user-facing option set.

* refactor(artwork): name the hashed image store folder for how it is addressed

The content-addressed store sat in artwork/store/, which did not
distinguish it from the artist/, playlist/ and radio/ upload folders
beside it — those hold artwork too. It is now artwork/hashed/, naming the
one property that sets it apart, and the path comes from a consts entry
rather than a bare literal, matching how the sibling folders are built.

Deliberately not under cache/: that folder holds resizes that rebuild
offline from a local source, while this one holds the only local copy of
externally fetched images, whose re-fetch depends on a third party still
serving them and whose bytes back the stored blurhash and dimensions.

No migration: anything left in the old artwork/store/ is orphaned and
re-resolved into the new location.

* refactor(artwork): call the album e2e helpers by their real names

album_test.go aliased expectAlbumFolderCover and expectAlbumAbsent to
shorter local names, which cost a lookup to resolve and hid the prefix
that distinguishes them from the artist and playlist helpers.

* test(artwork): cover the album-root and artist-folder path arithmetic

The unit specs for these helpers lived in the readers #5856 patched, both
deleted here, leaving the album-root promotion and the artist-folder climb
covered only end-to-end. A layout can show which image won but not why, so
these pin the parts behind it: that the parent is fetched only when it could
qualify as an album root, that a failed fetch propagates or degrades, and
that commonDir keeps a shared name fragment from reading as a shared folder.

Each spec was checked against a mutant: removing the library-root guard, the
other-album audio check, the single-folder short circuit, the single-root
climb, or commonDir's separator all turn one red.

Master's remaining specs were dropped as redundant — they cover sources this
branch already exercises under different names.

* fix(ui): stop artwork refreshes reloading the whole page

Resolving an album broadcast song:["*"], because a track with no art of its
own is served its album's and the dependent ids are unbounded server-side.
useResourceRefresh checked for that wildcard across every resource in the
payload, not just the ones a component shows, so the album grid called
refresh() — a full page reload — for every drained batch. Upgrading a large
library reloaded the grid thousands of times.

The client knows what the server cannot: which tracks are loaded, and their
albumId. So the fan-out moves there, the wildcard check is scoped to watched
resources, and the backend now names only what it resolved.

The playlist views watch playlistTrack too: their rows carry albumId but are
keyed by playlist entry, so a song refresh never reached them — previously
masked by the wildcard's page reload.

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

* fix(ui): stop the album grid blanking its covers on refresh

Cover takes its height from react-measure, which reports nothing until it
re-measures. That was harmless while the cover class sat on the img itself,
which has intrinsic size; it now sits on the Artwork root, whose img fills it
absolutely and so lends no height. A refresh remounts the tiles, and for the
frame before measurement lands the box collapsed to zero and every cover
vanished.

Give the box its own aspect ratio as a floor. The measured height still wins
once it arrives.

* refactor(artwork): drop the unused Bump/wake path from the worker

Worker.Bump had no production callers. Every real bump writes the queue row
through the repository instead: artwork.Refresh (the refresh endpoint and the
uploader), service.enqueue (read-through and stale-absent views), and
radio_repository. None of them wake a pool.

Bump was also the only sender to drainPool.wake, so the select case it fed was
unreachable outside tests, and runPool read as if a bump were picked up
promptly when it always waited for the 5s poll.

The e2e and unit suites used Bump only as a driver, never as the subject, so
they now enqueue with EnqueueBump and exercise the path production takes.
EnqueueBump rather than Refresh because Refresh also clears the state row,
which would change semantics for the re-bump-after-state and dedup specs.

Both harnesses start Run after enqueueing, so a fresh pool drains on its first
iteration and the wake never affected them: core/artwork/e2e averaged 3.26s
before and 3.30s after over 5 runs, within noise.

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

* refactor(artwork): unexport what nothing outside the package calls

PlaceholderFor had no callers at all. Its comment offered it to callers that
must not consult persisted state, but no such caller was ever written, so it
is removed rather than unexported.

entityExists and encode83 are only reached from inside their own packages;
their tests are package-internal (artwork) or never touch them (blurhash_test).

ImageStore stays exported: server/subsonic/e2e constructs one to wire up the
worker, and that suite cannot move into package artwork.

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

* refactor(persistence): name the backoff-preserving enqueue for what it does

EnqueueBump was named for a priority, but its behaviour is preserving an
existing row's retry_at; the priority comes from the item. Its one caller
passes ArtworkPriorityScan, which read like a bug at the call site and is not.

The three DO NOTHING inserts each repeated the INSERT prefix, the column list
and the conflict clause. They now share insertIfNotQueued, with the CTE that
EnqueueIfMissing needs passed as a prefix, and the column list lives in one
slice used by both squirrel and the raw SQL.

EnqueueIfMissing had no test against real SQL, only a mock mirroring the
anti-join by hand, so the rewritten statement had nothing verifying it. Two
specs now cover it: items with a state row are skipped, and an already-queued
row keeps its priority.

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

* test(thumbhash): vendor the reference and generate golden vectors

* test(thumbhash): add a faithful reference port as the differential oracle

* fix(thumbhash): re-condition alpha fixture and assert solid.png header

alpha.png varied only alpha over a constant color, so compositing atop the
average canceled L/P/Q exactly like solid.png, leaving it just as float-noise
unstable and silently dropping alpha-path coverage. Vary R/G/B with position
too so alpha.png carries real signal and reproduces byte-exactly, then
replace the blanket solid.png skip with a precise assertion on its
well-conditioned header bytes and quantized-zero scales.

Also apply a range-over-int modernizer hint in reference_test.go.

* test(thumbhash): dither the fixtures so no DCT coefficient is degenerate

The gradient fixtures are smooth analytic ramps, and alpha.png's alpha channel varied
along x only. Both make whole families of DCT coefficients mathematically zero: 13 of
alpha.png's 38 AC nibbles, and at least one in every other ramp fixture.

A zero coefficient normalizes to exactly the 0.5 midpoint, i.e. 15*f = 7.5, so which of
nibble 7 or 8 it quantizes to is decided by ~1e-16 of float rounding noise. Those nibbles
are therefore unstable across any two summation orders -- the vendored JS and the Go port
already disagreed on solid.png for this reason -- and they carry no signal, so a bug that
transposed two of them would be invisible.

A deterministic +/-4 dither, plus an alpha ramp that varies in x and y, leaves every
coefficient at least 4.8e-5 from the tie boundary: ~1e9 times the observed inter-
implementation noise. solid.png and tiny.png regenerate byte-identical and keep their
existing carve-outs.

* feat(thumbhash): add a two-pass separable ThumbHash encoder

Encode replaces the reference's four w*h scratch arrays (~320 KB at 100x100) and its 40
re-reads of every pixel with a single pixel pass that folds each row into per-frequency
sums, then a second fold over rows. The transform drops from O(terms * pixels) to
O(nx * pixels + terms * h), nx <= 7.

Verified against the vendored JS goldens and, differentially, against the literal Go port
on 500 randomized images. On the fixtures the two implementations' AC coefficients agree
to 8e-15; the separable inner loop reassociates the additions, so exact agreement holds
only where a coefficient is not sitting on a quantization tie, which is why the fixtures
are now dithered.

* test(thumbhash): fuzz the opaque path and drop an ill-conditioned golden

The 500-image randomized differential filled every byte randomly, so hasAlpha
(avgA < w*h) was true for all 500 images: the 7x7 no-alpha layout, terms(7,7),
nx=7 and the `if hasAlpha` false branch were never fuzzed. Force full opacity on
alternating iterations, which splits the run 250/250 with the seed and iteration
count unchanged. All 500 still match the reference port.

tiny.png is 1x1, so it has no non-zero AC content: 12 of its 37 AC coefficients
sit exactly on the round(15*f) = .5 tie and 24 are within 1e-12. It passed only
because a single pixel admits no summation reassociation. Give it the same
header-only carve-out solid.png already had, in both test files. The four
well-conditioned fixtures keep strict full byte equality.

Also document the divergence class on Encode itself rather than only in test
comments, add a sub-image regression spec, and use the max builtin over
math.Max. The toNRGBA Rect.Min gate turns out to protect nothing — SubImage
re-slices Pix so Pix[0] is the Rect.Min pixel and the loops read it correctly
either way — so its comment, which claimed the opposite, is corrected. The gate
is kept for now; removing it is a separate call.

* test(thumbhash): benchmark against blurhash at the pipeline input size

* feat(artwork): persist a thumbhash alongside the blurhash

The artwork table is content-addressed, so this costs one row per unique image
rather than per entity. Measured on a 25k-image library: +0.6MB on a 727MB DB.

The column is added to the existing add_artwork_tables migration rather than a
new one, since #5847 has not been released and the table it extends ships in
that same PR.

* feat(artwork): hydrate and expose thumbHash on every entity

ItemArtworkInfo.Image() is the single projection every hydration branch goes
through, so adding the field there covers albums, artists, playlists and both
the own-art and inherited media-file branches.

* feat(artwork): encode blurhash and thumbhash from one 100px thumbnail

thumbnailSize drops 128 -> 100 so a single CatmullRom scale feeds both encoders;
thumbhash hard-rejects anything larger and a second downscale would cost more
than shrinking the shared one.

decodeArtwork on a 1000x1000 JPEG, before -> after:
  15.53ms -> 15.45ms/op, 5878122 -> 5014796 B/op, 37 -> 75 allocs/op

Time is a wash because the JPEG decode dominates; the 863KB drop is the smaller
thumbnail more than paying for thumbhash's added work.

This rewrites every blurhash value, so it must land before #5847 reaches a
release: Finamp keys its cover cache and download dedup on that value.

* feat(ui): use thumbhash for the cover loading placeholder

Adds a local decoder rather than the thumbhash npm package, matching the local
blurhash decoder it replaces. Pixels are pinned against evanw/thumbhash's
reference decoder via the vendored copy already in the encoder's testdata.

Unlike a blurhash, a thumbhash carries its own approximate aspect, so a record
with no dimensions now falls back to that instead of to a square.

The blurHash API field stays: Jellyfin clients and third-party native clients
still consume it.

* perf(artwork): hand both hash encoders one NRGBA thumbnail

makeThumbnail emitted a premultiplied *image.RGBA, so thumbhash allocated and
un-premultiplied a full copy on every image while blurhash paid nothing. It now
emits *image.NRGBA, which thumbhash wants as-is, and blurhash reads that type
directly, premultiplying per pixel to keep its output identical.

thumbhash.Encode at the pipeline's 100x100 input:
  134200 -> 95300 ns/op, 56188 -> 15163 B/op, 37 -> 35 allocs/op
decodeArtwork on a 1000x1000 JPEG:
  5014796 -> 4973800 B/op, exactly the conversion that is gone

The scaler costs the same into either destination (7.33ms vs 7.34ms measured),
so no time is traded for this.

* test(artwork): drop the decodeArtwork benchmark

It existed to capture the before/after baseline for the 128->100 thumbnail
change, which it has served. As an ongoing guard it is misleading: a 1000x1000
JPEG decode is ~97% of the 15ms it measures, so the two encoders it would be
reached for are ~2.6% of the signal. It reported a phantom 2.8% regression for
the NRGBA thumbnail change that isolating the scaler disproved.

The per-encoder benchmarks in blurhash/ and thumbhash/ cover the part that
actually changes.

* test(artwork): benchmark both hash encoders from one file

benchImage and BenchmarkEncodeAtInputSize existed in both encoder packages, and
blurhash's copy had drifted into a third inline duplicate once both benches
moved to NRGBA input.

The head-to-head now lives in core/artwork, which already imports both encoders
and can pin the input to the real thumbnailSize constant. The gradient builder
moves to tests, which both packages already import via their suite bootstrap.

thumbhash keeps a shipped-vs-reference benchmark, since referenceEncode is
test-only and cannot be reached from core/artwork.

* test(thumbhash): drop the shipped-vs-reference benchmark

The two-pass rewrite's advantage over the naive port is already recorded in its
commit message; carrying the benchmark to re-derive it has no ongoing use.

reference_test.go stays: besides the benchmark baseline it holds the
differential oracle the golden-vector and randomised specs assert against.

* test(thumbhash): assert against reference goldens, drop the Go port

The reference port existed to be a differential oracle, but its packing half was
a verbatim copy of production pack(), so it was not as independent as it looked.
Only the 500-image randomised spec needed it; the six PNG fixtures cannot reach
random sizes, aspects, or both coefficient layouts.

gen_generated.mjs now emits 300 vectors from evanw's actual JS. Their pixels are
a pure function of their index, so Go rebuilds them byte-for-byte and only the
hashes are committed (16KB). The oracle is now the reference itself rather than
a hand transcription of it.

Also from the cleanup pass:
- maxCX/maxCY scanned every term to recover a bound that is just the widest
  coefficient region
- tests.GradientImage duplicated generateGradientImage three files away
- BenchmarkHashEncodersAtInputSize was also BenchmarkHashEncoders/*/100x100
- processor had two internal test files with no rule for which gets a new spec
- three blurhash specs differing only by alpha became a DescribeTable
- the shared mock's GetInfoForItems projection had drifted from the real query

* refactor(model): keep the blurhash off native JSON and fold its specs

Nothing on the native API consumes blurHash: the web UI reads thumbHash, and
Jellyfin's mappers take the Go field directly rather than through this
serialization. It was shipping ~40 unused bytes on every row of every list
response, on a surface that accretes clients once published.

The JSON specs were five marshal-and-check-keys blocks over the same struct;
they collapse to one populated case, one bare case, and a guard that the
blurhash stays off the wire.

* refactor(persistence): simplify the artwork dangling-row purge helper

purgeDangling took a bound executeSQL method value and a table name only because
its two callers live on unrelated types. Neither parameter was load-bearing:
executeSQL is a value receiver on sqlRepository that never reads tableName, and
both callers already hold an sqlRepository whose tableName is the table being
purged. Taking that struct collapses both parameters into the receiver.

itemArtworkSQL wrapped sqlRepository without adding a single method, so the items
field becomes a plain sqlRepository.

danglingItemArtworkKinds is also read by EnqueueAllMissing, which enqueues
entities that have no artwork row yet - neither a purge nor anything specific to
item_artwork. Renamed to artworkOwnerTables to describe both of its uses.

* fix(artwork): keep sweeping past a store file that cannot be removed

Sweep returned the os.Remove error straight out of WalkDir, so a single
unremovable file abandoned the rest of the walk. Every later orphan, stale mime
variant and abandoned temp file then survived until the next prune, which would
abort at the same place.

Warn and carry on instead. The orphan-file loop in prune already had this
resilience; Sweep is where it belongs, since it is the only step that reaches
stray files and superseded variants.

* refactor(artwork): let the sweep reclaim orphan files instead of prune

Deleting unreferenced artwork rows took five round trips: snapshot the orphan
hashes, fetch their mimes, delete, re-fetch to see which rows actually went, then
remove each file. The last four exist only to work out which files to delete -
but the sweep that runs moments later already derives exactly that from the
database, since GetAllMimes is read after the delete and Sweep removes any file
whose hash has no row, under the same mtime guard. The sweep is also the more
thorough of the two: it reclaims stale mime variants of an orphan hash, which the
per-hash removal never looked at.

Delete the rows in one predicate-only statement and let the sweep follow. The
orphan predicate now runs once per prune instead of once for the snapshot plus
once per 200-hash delete chunk, and with no hash list to bind there is nothing
left to chunk.

GetOrphanHashes and GetImages had no other caller and are gone. Dropping them
also removes the mock's OrphanHashes lever, which let a spec declare a hash
orphaned while item_artwork still referenced it - a state the SQL repository
could never produce, since both predicates were always identical.

* refactor(model): name the artwork mime lookup for what it is keyed by

GetAllMimes reads as a collection of mime types; it returns a hash -> mime index
over every stored artwork. GetMimeByHash names the key, matching the convention
the other map-returning repository methods already follow (CountBySuffix,
CountByClient).

* refactor(artwork): split the repository's deletes from its purges by name

Six removal methods across the two artwork repositories used Delete and Purge
interchangeably, so neither prefix told you anything. There is a real distinction
underneath: Delete methods are caller-directed and take the rows to remove, while
Purge methods are garbage collection - the repository finds rows whose referent
is gone by joining against the owning table, and returns a count because the
caller cannot know one. The signatures already followed that split; only the
names did not.

DeleteOrphans was the odd one out, taking a grace cutoff rather than a target and
returning a count, so it becomes PurgeOrphans. PurgeDanglingItemArtwork loses the
Artwork it repeats from its own interface and keeps the Items that says which of
that interface's two tables it means.

DeleteForItem was DeleteForItems with one id - squirrel emits = for a scalar and
IN for a slice against the same predicate - so its one caller passes a slice
instead. Dangling and Orphan stay distinct: dangling is a row whose entity is
gone, orphan is an image no state row references.

* refactor(artwork): drop the orphaned store remover, aggregate sweep failures

Review follow-ups to the prune rework.

ImageStore.Remove lost its only production caller when the sweep took over
orphan-file reclamation. It carried its own copy of the mtime guard that now
lives solely in Sweep, so the two could drift, and it stood as an invitation to
grow a second reclaim path. Its specs either duplicated Sweep's own coverage or
tested nothing else, so they go with it; the one unrelated test that used it to
delete a file calls os.Remove directly.

Sweep warned once per file it could not remove, which is fine for a stray
permission bit and useless for a store mounted read-only - a large library would
emit one line per aged file on every prune, and prune would still report success.
Count the failures instead and warn once, with the count and the last error, so a
systemic failure is legible without drowning the log.

Also: the orphan log line counts rows, not files, and now says so; and the
blocked-removal spec asserts its two fixtures really do land in different shards,
since the assertion is vacuous if they collide.

* fix(ui): show the placeholder when a refresh swaps in an uncached cover

A cover whose hash changed under a mounted grid went blank for the whole fetch,
instead of falling back to its thumbhash. Artwork decided 'this blob was already
cached, skip the placeholder' once at mount and never revisited it, so every
later url for that record inherited the answer.

The fix has to live in useImageUrl. imgUrl is state cleared in an effect, so on
the render where url changes it still holds the previous url's blob - any caller
inspecting it reads the new url as already cached. Only the hook can see
cache.get(url) for the url actually being rendered, so it now reports fromCache
and resyncs its state during render rather than one render later.

Two shapes were tried and rejected against a live server before this one: a ref
recomputed per url, which a render-phase resync discards without rolling back the
ref, and the same tracking in Artwork state, which still samples imgUrl before
React re-runs the component. Verified on a running instance with cover-art
responses held open: the thumbhash now covers the whole window and stays under
the image until the fade ends.

* fix(ui): keep the placeholder for a cover whose fetch failed

useImageUrl caches a failed fetch as an entry with no blob, so treating every
cached entry as instantly painted suppressed the placeholder on remount: the
cover became an empty box instead of falling back to its thumbhash. Only a
cached blob counts as instant.

Caught by Codex on the previous commit, which introduced fromCache with the
looser predicate.

* feat(artwork): capture each image's dominant colour

A flat colour is the one placeholder a client can paint with no decoding at all,
so it can cover the frames before a thumbhash canvas even renders. Extract it
from the same 100px thumbnail the two hash encoders already share, and expose it
as dominantColor on the native API.

Dominant means presence, not salience: the largest cluster wins, so a white
sleeve reports white. That is what a placeholder needs. An accent colour is the
opposite question and is deliberately not answered here - it depends on the
client's theme, and by the time a client needs one it has the cover pixels and
can compute whatever suits it.

Bins at 4 bits per channel, then merges perceptually-near bins in Oklab before
picking the winner: a gradient splits across adjacent bins and would otherwise
lose to a smaller flat region. Measured at 246us per image on the weakest target
hardware we care about (Celeron N5105), against ~15.8 images/s for the pipeline
around it.

The column goes into the feature's original migration rather than a new one:
computing it later would mean re-decoding every image in the library.

* fix(artwork): ignore image candidates that cannot be fetched

bestImageURL only rejected URLs that url.Parse itself refuses, which is almost
nothing: relative paths and any scheme parse cleanly. A candidate like
images/big.jpg or ftp://host/big.jpg therefore won on size, and since the
function returns a single URL whose failure ends that agent's turn, the agent's
valid smaller images were never tried.

Two details made it easy to hit rather than theoretical. Size is frequently 0 for
every candidate, and only a strictly larger one replaces the first, so an
unfetchable entry in first position sticks. And these strings come straight from
plugins, where a relative path is an ordinary mistake.

Accept only absolute http/https URLs with a host.

* revert(ui): move detail-page scroll handling to its own branch

Reverts 40153bd43. Scroll position carrying over between pages is stock React
Router behaviour rather than something this branch introduced, so the fix does
not belong in an artwork PR that is otherwise ready for review.

The work continues on fix/scroll-restoration, off master, where it grew into
per-route restoration: a new page starts at the top and going back returns to
where you were, which the scroll-to-top could not do.

* fix(ui): fade cover art consistently, and shorten the fade to 150ms

The <img> mounts with its blob URL already set, so onLoad often fires in the
same frame the element is inserted. The opacity:0 start state never gets
painted, the transition has no value to animate from, and the cover pops in
instead of fading. Only tiles whose decode happened to straddle a paint
boundary actually faded, which made a grid load look ragged: 4 to 6 of 18
covers faded, varying between runs.

Deferring the decoded flag by two animation frames guarantees the hidden state
is painted first. Measured on a live grid afterwards, 17 of 18 covers fade, the
18th having a cached blob and taking the intentional instant path, and the tail
after the last byte arrives drops from ~440ms to ~163ms.

The duration also drops from 500ms to 150ms. That 500ms mirrored master's fade,
but master paints no placeholder behind the image and needs a slow blend to
cover a blank tile. Here a thumbhash already fills the gap, so a long crossfade
only delays the grid settling, measured at 145-190ms slower to full opacity
than master.

---------

Signed-off-by: Deluan <deluan@navidrome.org>
---
 adapters/deezer/deezer.go                     |  13 +-
 adapters/deezer/deezer_test.go                |  48 ++
 adapters/lastfm/agent.go                      |  34 +-
 adapters/lastfm/agent_test.go                 |  32 +-
 cmd/pls.go                                    |   4 +-
 cmd/root.go                                   |  66 ++
 cmd/scan.go                                   |   4 +-
 cmd/wire_gen.go                               | 109 ++-
 cmd/wire_injectors.go                         |   8 +
 conf/configuration.go                         |   8 +
 consts/consts.go                              |  10 +
 core/agents/agents.go                         |  36 +
 core/agents/agents_test.go                    |  72 ++
 core/artwork/agent_images.go                  | 100 +++
 core/artwork/agent_images_test.go             | 262 ++++++
 core/artwork/artwork.go                       | 422 +++++++--
 core/artwork/artwork_internal_test.go         | 629 --------------
 core/artwork/artwork_suite_test.go            |  48 +-
 core/artwork/artwork_test.go                  | 522 ++++++++++-
 core/artwork/benchmark_e2e_test.go            | 189 ----
 core/artwork/benchmark_helpers_test.go        |   9 +
 core/artwork/blurhash/blurhash.go             | 191 ++++
 core/artwork/blurhash/blurhash_suite_test.go  |  17 +
 core/artwork/blurhash/blurhash_test.go        | 137 +++
 core/artwork/cache_warmer.go                  | 162 ----
 core/artwork/cache_warmer_test.go             | 245 ------
 core/artwork/{reader_disc.go => disc.go}      | 128 ++-
 .../{reader_disc_test.go => disc_test.go}     |   0
 core/artwork/dominant/dominant.go             | 127 +++
 core/artwork/dominant/dominant_suite_test.go  |  17 +
 core/artwork/dominant/dominant_test.go        |  91 ++
 core/artwork/e2e/acquire_serve_test.go        | 326 +++++++
 core/artwork/e2e/album_test.go                | 217 ++---
 core/artwork/e2e/artist_test.go               | 113 +--
 core/artwork/e2e/disc_test.go                 | 128 +--
 core/artwork/e2e/e2e_suite_test.go            |  83 ++
 core/artwork/e2e/helpers_test.go              | 184 ----
 core/artwork/e2e/mediafile_test.go            |  71 +-
 core/artwork/e2e/playlist_test.go             | 133 ++-
 core/artwork/e2e/radio_test.go                |  29 +-
 core/artwork/e2e/resolution_harness_test.go   | 365 ++++++++
 core/artwork/e2e/suite_test.go                | 120 ---
 core/artwork/e2e/testdata/embedded_art.mp3    | Bin 64223 -> 0 bytes
 .../{reader_album.go => folders_album.go}     |  90 +-
 core/artwork/folders_album_test.go            | 214 +++++
 core/artwork/folders_artist.go                | 210 +++++
 core/artwork/folders_artist_paths_test.go     | 117 +++
 core/artwork/folders_artist_test.go           |  47 +
 core/artwork/gate.go                          | 120 +++
 core/artwork/hash_encoder_bench_test.go       |  51 ++
 core/artwork/housekeeping.go                  | 129 +++
 core/artwork/housekeeping_test.go             | 261 ++++++
 core/artwork/image_cache.go                   |  62 +-
 core/artwork/image_store.go                   | 155 ++++
 core/artwork/image_store_test.go              | 228 +++++
 core/artwork/library_fs.go                    |  22 +-
 core/artwork/library_fs_test.go               |   7 +
 core/artwork/playlist_cover.go                | 116 +++
 core/artwork/processor.go                     | 311 +++++++
 core/artwork/processor_test.go                | 495 +++++++++++
 core/artwork/prune.go                         |  63 ++
 core/artwork/prune_test.go                    | 239 +++++
 core/artwork/reader_album_test.go             | 481 -----------
 core/artwork/reader_artist.go                 | 359 --------
 core/artwork/reader_artist_test.go            | 761 ----------------
 core/artwork/reader_mediafile.go              |  82 --
 core/artwork/reader_playlist.go               | 269 ------
 core/artwork/reader_radio.go                  |  40 -
 core/artwork/reader_radio_test.go             |  84 --
 core/artwork/reader_resized.go                | 209 -----
 core/artwork/reader_resized_test.go           | 176 ----
 core/artwork/resize.go                        | 144 ++++
 core/artwork/resolve.go                       | 452 ++++++++++
 core/artwork/resolve_test.go                  | 632 ++++++++++++++
 core/artwork/sources.go                       |  72 +-
 core/artwork/thumbhash/testdata/alpha.png     | Bin 0 -> 24912 bytes
 .../thumbhash/testdata/gen_fixtures.mjs       |  90 ++
 .../thumbhash/testdata/gen_generated.mjs      |  28 +
 .../artwork/thumbhash/testdata/gen_golden.mjs |  37 +
 .../artwork/thumbhash/testdata/generated.json |   1 +
 core/artwork/thumbhash/testdata/golden.json   |   8 +
 core/artwork/thumbhash/testdata/landscape.png | Bin 0 -> 20198 bytes
 core/artwork/thumbhash/testdata/portrait.png  | Bin 0 -> 20102 bytes
 core/artwork/thumbhash/testdata/solid.png     | Bin 0 -> 209 bytes
 core/artwork/thumbhash/testdata/square.png    | Bin 0 -> 33071 bytes
 core/artwork/thumbhash/testdata/thumbhash.js  | 288 +++++++
 core/artwork/thumbhash/testdata/tiny.png      | Bin 0 -> 70 bytes
 core/artwork/thumbhash/thumbhash.go           | 257 ++++++
 .../artwork/thumbhash/thumbhash_suite_test.go |  17 +
 core/artwork/thumbhash/thumbhash_test.go      | 194 +++++
 core/{image_upload.go => artwork/uploader.go} |  54 +-
 .../uploader_test.go}                         |  67 +-
 core/artwork/wire_providers.go                |   4 +-
 core/artwork/worker.go                        | 318 +++++++
 core/artwork/worker_soak_test.go              | 146 ++++
 core/artwork/worker_test.go                   | 813 ++++++++++++++++++
 core/artwork/worker_timing_test.go            |  76 ++
 core/external/provider.go                     |  85 +-
 core/external/provider_albumimage_test.go     | 365 --------
 core/external/provider_artistimage_test.go    | 426 ---------
 core/playlists/import_test.go                 |  44 +-
 core/playlists/playlists.go                   |  17 +-
 core/playlists/playlists_test.go              |  38 +-
 core/playlists/rest_adapter_test.go           |   4 +-
 core/wire_providers.go                        |   2 -
 db/db.go                                      |  12 +
 .../20260722023032_add_artwork_tables.sql     |  46 +
 go.mod                                        |   2 +-
 log/formatters.go                             |  11 +-
 log/formatters_test.go                        |   6 +
 model/album.go                                |   2 +
 model/artist.go                               |   2 +
 model/artwork.go                              | 144 ++++
 model/artwork_id.go                           |  82 +-
 model/artwork_id_test.go                      |  63 +-
 model/artwork_test.go                         |  73 ++
 model/datastore.go                            |   2 +
 model/mediafile.go                            |  16 +-
 model/playlist.go                             |   2 +
 model/radio.go                                |   4 +
 model/radio_test.go                           |   5 +-
 persistence/album_repository.go               |  36 +-
 persistence/album_repository_test.go          |  28 +
 persistence/artist_repository.go              |  37 +-
 persistence/artist_repository_test.go         |  12 +
 persistence/artwork_hydration.go              | 181 ++++
 persistence/artwork_hydration_test.go         | 773 +++++++++++++++++
 persistence/artwork_queue_repository.go       | 149 ++++
 persistence/artwork_queue_repository_test.go  | 284 ++++++
 persistence/artwork_repository.go             | 176 ++++
 persistence/artwork_repository_test.go        | 248 ++++++
 persistence/e2e/e2e_suite_test.go             |   5 +-
 persistence/mediafile_repository.go           |  43 +-
 persistence/mediafile_repository_test.go      |  36 +
 persistence/persistence.go                    |   8 +
 persistence/playlist_repository.go            |  66 +-
 persistence/playlist_repository_test.go       |  88 ++
 persistence/playlist_track_repository.go      |   5 +-
 persistence/radio_repository.go               |  45 +-
 persistence/radio_repository_test.go          |  33 +
 persistence/sql_base_repository.go            |  13 +-
 scanner/controller.go                         |   9 +-
 scanner/controller_test.go                    |   3 +-
 scanner/phase_1_folders.go                    |  51 +-
 scanner/phase_4_playlists.go                  |  11 +-
 scanner/phase_4_playlists_test.go             |  28 +-
 scanner/scanner.go                            |  32 +-
 scanner/scanner_benchmark_test.go             |   5 +-
 scanner/scanner_multilibrary_test.go          |   5 +-
 scanner/scanner_selective_test.go             |   5 +-
 scanner/scanner_test.go                       |  94 +-
 server/imghttp/headers.go                     |  67 ++
 server/imghttp/headers_test.go                | 117 +++
 server/imghttp/imghttp_suite_test.go          |  17 +
 server/jellyfin/dto/blurhash.go               |  36 -
 server/jellyfin/dto/blurhash_test.go          |  27 -
 server/jellyfin/dto/dto.go                    |  15 +-
 server/jellyfin/dto/mappers.go                | 137 ++-
 server/jellyfin/dto/mappers_test.go           | 283 +++++-
 server/jellyfin/e2e/e2e_suite_test.go         |  11 +-
 server/jellyfin/e2e/playlists_test.go         |  22 +-
 server/jellyfin/images.go                     |  29 +-
 server/jellyfin/images_test.go                |  54 +-
 server/jellyfin/items.go                      |  13 +-
 server/jellyfin/similar.go                    |   2 +-
 server/nativeapi/artists.go                   |  12 +-
 server/nativeapi/artwork.go                   |  42 +
 server/nativeapi/artwork_test.go              |  95 ++
 server/nativeapi/image_upload.go              |   4 +-
 server/nativeapi/native_api.go                |   6 +-
 server/nativeapi/radios.go                    |  12 +-
 server/public/handle_images.go                |  16 +-
 server/public/handle_images_test.go           |  63 ++
 server/subsonic/browsing.go                   |  18 +-
 server/subsonic/browsing_test.go              |  54 ++
 server/subsonic/e2e/e2e_suite_test.go         |  22 +-
 server/subsonic/e2e/subsonic_artwork_test.go  | 328 +++++++
 .../e2e/subsonic_multilibrary_test.go         |   5 +-
 .../e2e/subsonic_sonic_similarity_test.go     |   3 +-
 server/subsonic/helpers.go                    |  41 +-
 server/subsonic/helpers_test.go               |  76 ++
 server/subsonic/media_retrieval.go            |  13 +-
 server/subsonic/media_retrieval_test.go       |  88 +-
 server/subsonic/playlists.go                  |   2 +-
 server/subsonic/playlists_test.go             |  13 +
 server/subsonic/radio.go                      |   4 +-
 server/subsonic/radio_test.go                 |  19 +-
 server/subsonic/searching.go                  |  12 +-
 server/subsonic/searching_test.go             |  30 +
 tests/harness/harness.go                      |  47 +-
 tests/mock_album_repo.go                      |  14 +
 tests/mock_artist_repo.go                     |   9 +
 tests/mock_artwork_queue_repo.go              | 258 ++++++
 tests/mock_artwork_repo.go                    | 175 ++++
 tests/mock_data_store.go                      |  78 +-
 tests/mock_mediafile_repo.go                  |  12 +
 tests/mock_playlist_repo.go                   |   9 +
 tests/mock_playlist_track_repo.go             |   8 +
 tests/mock_radio_repository.go                |  11 +-
 ui/src/album/AlbumDetails.jsx                 |  39 +-
 ui/src/album/AlbumGridView.jsx                |  43 +-
 ui/src/album/AlbumGridView.test.jsx           |  18 +
 ui/src/album/AlbumList.jsx                    |  18 +-
 ui/src/album/AlbumTableView.jsx               |   6 +-
 ui/src/album/useRollChanged.jsx               |  13 +
 ui/src/album/useRollChanged.test.jsx          |  73 ++
 ui/src/artist/ArtistList.jsx                  |   4 +-
 ui/src/artist/ArtistSimpleList.jsx            |   4 +-
 ui/src/artist/DesktopArtistDetails.jsx        |  47 +-
 ui/src/artist/MobileArtistDetails.jsx         |  49 +-
 ui/src/common/Artwork.jsx                     | 127 +++
 ui/src/common/Artwork.test.jsx                | 232 +++++
 ui/src/common/ArtworkAvatar.jsx               |  40 +
 ui/src/common/CoverArtAvatar.jsx              |  52 --
 ui/src/common/ThumbHashCanvas.jsx             |  75 ++
 ui/src/common/ThumbHashCanvas.test.jsx        |  95 ++
 ui/src/common/index.js                        |   2 +-
 ui/src/common/useImageUrl.js                  |  14 +-
 ui/src/common/useImageUrl.test.js             |   3 +
 ui/src/common/useResourceRefresh.jsx          |  48 +-
 ui/src/common/useResourceRefresh.test.js      | 185 +++-
 ui/src/playlist/PlaylistDetails.jsx           |  49 +-
 ui/src/playlist/PlaylistList.jsx              |   4 +-
 ui/src/playlist/PlaylistShow.jsx              |   2 +-
 ui/src/playlist/PlaylistSongs.jsx             |   3 +-
 ui/src/radio/RadioList.jsx                    |  32 +-
 ui/src/subsonic/index.js                      |  14 +-
 ui/src/subsonic/index.test.js                 |  41 +
 ui/src/utils/thumbhash.js                     | 138 +++
 ui/src/utils/thumbhash.test.js                |  66 ++
 utils/cache/file_caches.go                    |   9 +
 utils/cache/file_caches_test.go               |  87 ++
 utils/cache/spread_fs.go                      |   2 +-
 utils/cache/spread_fs_test.go                 |  36 +
 utils/cache/spread_fs_unix.go                 |  18 +
 utils/cache/spread_fs_windows.go              |  15 +
 236 files changed, 16349 insertions(+), 6350 deletions(-)
 create mode 100644 core/artwork/agent_images.go
 create mode 100644 core/artwork/agent_images_test.go
 delete mode 100644 core/artwork/artwork_internal_test.go
 delete mode 100644 core/artwork/benchmark_e2e_test.go
 create mode 100644 core/artwork/blurhash/blurhash.go
 create mode 100644 core/artwork/blurhash/blurhash_suite_test.go
 create mode 100644 core/artwork/blurhash/blurhash_test.go
 delete mode 100644 core/artwork/cache_warmer.go
 delete mode 100644 core/artwork/cache_warmer_test.go
 rename core/artwork/{reader_disc.go => disc.go} (60%)
 rename core/artwork/{reader_disc_test.go => disc_test.go} (100%)
 create mode 100644 core/artwork/dominant/dominant.go
 create mode 100644 core/artwork/dominant/dominant_suite_test.go
 create mode 100644 core/artwork/dominant/dominant_test.go
 create mode 100644 core/artwork/e2e/acquire_serve_test.go
 create mode 100644 core/artwork/e2e/e2e_suite_test.go
 delete mode 100644 core/artwork/e2e/helpers_test.go
 create mode 100644 core/artwork/e2e/resolution_harness_test.go
 delete mode 100644 core/artwork/e2e/suite_test.go
 delete mode 100644 core/artwork/e2e/testdata/embedded_art.mp3
 rename core/artwork/{reader_album.go => folders_album.go} (63%)
 create mode 100644 core/artwork/folders_album_test.go
 create mode 100644 core/artwork/folders_artist.go
 create mode 100644 core/artwork/folders_artist_paths_test.go
 create mode 100644 core/artwork/folders_artist_test.go
 create mode 100644 core/artwork/gate.go
 create mode 100644 core/artwork/hash_encoder_bench_test.go
 create mode 100644 core/artwork/housekeeping.go
 create mode 100644 core/artwork/housekeeping_test.go
 create mode 100644 core/artwork/image_store.go
 create mode 100644 core/artwork/image_store_test.go
 create mode 100644 core/artwork/playlist_cover.go
 create mode 100644 core/artwork/processor.go
 create mode 100644 core/artwork/processor_test.go
 create mode 100644 core/artwork/prune.go
 create mode 100644 core/artwork/prune_test.go
 delete mode 100644 core/artwork/reader_album_test.go
 delete mode 100644 core/artwork/reader_artist.go
 delete mode 100644 core/artwork/reader_artist_test.go
 delete mode 100644 core/artwork/reader_mediafile.go
 delete mode 100644 core/artwork/reader_playlist.go
 delete mode 100644 core/artwork/reader_radio.go
 delete mode 100644 core/artwork/reader_radio_test.go
 delete mode 100644 core/artwork/reader_resized.go
 delete mode 100644 core/artwork/reader_resized_test.go
 create mode 100644 core/artwork/resize.go
 create mode 100644 core/artwork/resolve.go
 create mode 100644 core/artwork/resolve_test.go
 create mode 100644 core/artwork/thumbhash/testdata/alpha.png
 create mode 100644 core/artwork/thumbhash/testdata/gen_fixtures.mjs
 create mode 100644 core/artwork/thumbhash/testdata/gen_generated.mjs
 create mode 100644 core/artwork/thumbhash/testdata/gen_golden.mjs
 create mode 100644 core/artwork/thumbhash/testdata/generated.json
 create mode 100644 core/artwork/thumbhash/testdata/golden.json
 create mode 100644 core/artwork/thumbhash/testdata/landscape.png
 create mode 100644 core/artwork/thumbhash/testdata/portrait.png
 create mode 100644 core/artwork/thumbhash/testdata/solid.png
 create mode 100644 core/artwork/thumbhash/testdata/square.png
 create mode 100644 core/artwork/thumbhash/testdata/thumbhash.js
 create mode 100644 core/artwork/thumbhash/testdata/tiny.png
 create mode 100644 core/artwork/thumbhash/thumbhash.go
 create mode 100644 core/artwork/thumbhash/thumbhash_suite_test.go
 create mode 100644 core/artwork/thumbhash/thumbhash_test.go
 rename core/{image_upload.go => artwork/uploader.go} (55%)
 rename core/{image_upload_test.go => artwork/uploader_test.go} (60%)
 create mode 100644 core/artwork/worker.go
 create mode 100644 core/artwork/worker_soak_test.go
 create mode 100644 core/artwork/worker_test.go
 create mode 100644 core/artwork/worker_timing_test.go
 delete mode 100644 core/external/provider_albumimage_test.go
 delete mode 100644 core/external/provider_artistimage_test.go
 create mode 100644 db/migrations/20260722023032_add_artwork_tables.sql
 create mode 100644 model/artwork.go
 create mode 100644 model/artwork_test.go
 create mode 100644 persistence/artwork_hydration.go
 create mode 100644 persistence/artwork_hydration_test.go
 create mode 100644 persistence/artwork_queue_repository.go
 create mode 100644 persistence/artwork_queue_repository_test.go
 create mode 100644 persistence/artwork_repository.go
 create mode 100644 persistence/artwork_repository_test.go
 create mode 100644 server/imghttp/headers.go
 create mode 100644 server/imghttp/headers_test.go
 create mode 100644 server/imghttp/imghttp_suite_test.go
 delete mode 100644 server/jellyfin/dto/blurhash.go
 delete mode 100644 server/jellyfin/dto/blurhash_test.go
 create mode 100644 server/nativeapi/artwork.go
 create mode 100644 server/nativeapi/artwork_test.go
 create mode 100644 server/subsonic/e2e/subsonic_artwork_test.go
 create mode 100644 tests/mock_artwork_queue_repo.go
 create mode 100644 tests/mock_artwork_repo.go
 create mode 100644 ui/src/album/AlbumGridView.test.jsx
 create mode 100644 ui/src/album/useRollChanged.jsx
 create mode 100644 ui/src/album/useRollChanged.test.jsx
 create mode 100644 ui/src/common/Artwork.jsx
 create mode 100644 ui/src/common/Artwork.test.jsx
 create mode 100644 ui/src/common/ArtworkAvatar.jsx
 delete mode 100644 ui/src/common/CoverArtAvatar.jsx
 create mode 100644 ui/src/common/ThumbHashCanvas.jsx
 create mode 100644 ui/src/common/ThumbHashCanvas.test.jsx
 create mode 100644 ui/src/utils/thumbhash.js
 create mode 100644 ui/src/utils/thumbhash.test.js
 create mode 100644 utils/cache/spread_fs_unix.go
 create mode 100644 utils/cache/spread_fs_windows.go

diff --git a/adapters/deezer/deezer.go b/adapters/deezer/deezer.go
index d8e832cf1..742b8b1a5 100644
--- a/adapters/deezer/deezer.go
+++ b/adapters/deezer/deezer.go
@@ -70,16 +70,27 @@ func (s *deezerAgent) GetArtistImages(ctx context.Context, _, name, _ string) ([
 		{artist.PictureSmall, deezerApiPictureSmallSize},
 	}
 	for _, imgData := range possibleImages {
-		if imgData.URL != "" {
+		if imgData.URL != "" && !isPlaceholderPicture(imgData.URL) {
 			res = append(res, agents.ExternalImage{
 				URL:  imgData.URL,
 				Size: imgData.Size,
 			})
 		}
 	}
+	if len(res) == 0 {
+		return nil, agents.ErrNotFound
+	}
 	return res, nil
 }
 
+// deezerEmptyPicturePath is Deezer's empty-image-id path shape for artists with no picture
+// (…/images/artist//1000x1000-…), which serves a generic silhouette on any CDN host.
+const deezerEmptyPicturePath = "/images/artist//"
+
+func isPlaceholderPicture(url string) bool {
+	return strings.Contains(url, deezerEmptyPicturePath)
+}
+
 func (s *deezerAgent) searchArtist(ctx context.Context, name string) (*Artist, error) {
 	artists, err := s.client.searchArtists(ctx, name, deezerArtistSearchLimit)
 	if errors.Is(err, ErrNotFound) || len(artists) == 0 {
diff --git a/adapters/deezer/deezer_test.go b/adapters/deezer/deezer_test.go
index f478af115..360db1f13 100644
--- a/adapters/deezer/deezer_test.go
+++ b/adapters/deezer/deezer_test.go
@@ -94,6 +94,54 @@ var _ = Describe("deezerAgent", func() {
 		})
 	})
 
+	Describe("GetArtistImages", func() {
+		var agent *deezerAgent
+		var httpClient *fakeHttpClient
+
+		BeforeEach(func() {
+			httpClient = &fakeHttpClient{}
+			agent = &deezerAgent{
+				dataStore: &tests.MockDataStore{},
+				client:    newClient(httpClient),
+			}
+		})
+
+		It("returns the real images when the artist has a picture", func() {
+			httpClient.mock("https://api.deezer.com/search/artist", http.Response{
+				StatusCode: 200,
+				Body: io.NopCloser(bytes.NewBufferString(`{"data":[
+					{"id":412,"name":"Queen","nb_fan":12744378,
+					 "picture_xl":"https://cdn-images.dzcdn.net/images/artist/abc/1000x1000-000000-80-0-0.jpg",
+					 "picture_big":"https://cdn-images.dzcdn.net/images/artist/abc/500x500-000000-80-0-0.jpg"}
+				],"total":1}`)),
+			})
+
+			images, err := agent.GetArtistImages(ctx, "", "Queen", "")
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(images).To(HaveLen(2))
+			Expect(images[0].URL).To(ContainSubstring("1000x1000"))
+		})
+
+		It("returns ErrNotFound when the artist only has empty-id placeholder pictures", func() {
+			httpClient.mock("https://api.deezer.com/search/artist", http.Response{
+				StatusCode: 200,
+				Body: io.NopCloser(bytes.NewBufferString(`{"data":[
+					{"id":412,"name":"Queen","nb_fan":12744378,
+					 "picture_xl":"https://cdn-images.dzcdn.net/images/artist//1000x1000-000000-80-0-0.jpg",
+					 "picture_big":"https://cdn-images.dzcdn.net/images/artist//500x500-000000-80-0-0.jpg",
+					 "picture_medium":"https://cdn-images.dzcdn.net/images/artist//250x250-000000-80-0-0.jpg",
+					 "picture_small":"https://cdn-images.dzcdn.net/images/artist//56x56-000000-80-0-0.jpg"}
+				],"total":1}`)),
+			})
+
+			images, err := agent.GetArtistImages(ctx, "", "Queen", "")
+
+			Expect(err).To(MatchError(agents.ErrNotFound))
+			Expect(images).To(BeEmpty())
+		})
+	})
+
 	Describe("GetArtistBiography - Language Fallback", func() {
 		var agent *deezerAgent
 		var httpClient *langAwareHttpClient
diff --git a/adapters/lastfm/agent.go b/adapters/lastfm/agent.go
index eb8f3d36e..f967595e3 100644
--- a/adapters/lastfm/agent.go
+++ b/adapters/lastfm/agent.go
@@ -93,7 +93,7 @@ func (l *lastfmAgent) GetAlbumInfo(ctx context.Context, name, artist, mbid strin
 	var resp agents.AlbumInfo
 	for _, lang := range l.languages {
 		var err error
-		a, err = l.callAlbumGetInfo(ctx, name, artist, mbid, lang)
+		a, err = l.callAlbumGetInfo(ctx, name, artist, lang)
 		if err != nil {
 			return nil, err
 		}
@@ -114,7 +114,7 @@ func (l *lastfmAgent) GetAlbumInfo(ctx context.Context, name, artist, mbid strin
 }
 
 func (l *lastfmAgent) GetAlbumImages(ctx context.Context, name, artist, mbid string) ([]agents.ExternalImage, error) {
-	a, err := l.callAlbumGetInfo(ctx, name, artist, mbid, l.languages[0])
+	a, err := l.callAlbumGetInfo(ctx, name, artist, l.languages[0])
 	if err != nil {
 		return nil, err
 	}
@@ -286,22 +286,18 @@ func (l *lastfmAgent) GetArtistImages(ctx context.Context, _, name, mbid string)
 	return res, nil
 }
 
-func (l *lastfmAgent) callAlbumGetInfo(ctx context.Context, name, artist, mbid string, lang string) (*Album, error) {
-	a, err := l.client.albumGetInfo(ctx, name, artist, mbid, lang)
-	var lfErr *lastFMError
-	isLastFMError := errors.As(err, &lfErr)
-
-	if mbid != "" && (isLastFMError && lfErr.Code == 6) {
-		log.Debug(ctx, "LastFM/album.getInfo could not find album by mbid, trying again", "album", name, "mbid", mbid)
-		return l.callAlbumGetInfo(ctx, name, artist, "", lang)
-	}
-
+// callAlbumGetInfo matches on name+artist only. Last.fm's album.getInfo by MBID is unreliable —
+// a correct MBID can return a different album (or none) — so the MBID is deliberately not passed.
+func (l *lastfmAgent) callAlbumGetInfo(ctx context.Context, name, artist, lang string) (*Album, error) {
+	a, err := l.client.albumGetInfo(ctx, name, artist, "", lang)
 	if err != nil {
-		if isLastFMError && lfErr.Code == 6 {
-			log.Debug(ctx, "Album not found", "album", name, "mbid", mbid, err)
-		} else {
-			log.Error(ctx, "Error calling LastFM/album.getInfo", "album", name, "mbid", mbid, err)
+		if lfErr, ok := errors.AsType[*lastFMError](err); ok && lfErr.Code == 6 {
+			// A not-found is a definitive absence, not a fault: return the shared sentinel so the
+			// artwork worker's breaker/transient checks don't retry it, and log it at Debug.
+			log.Debug(ctx, "Album not found in Last.fm", "album", name, "artist", artist)
+			return nil, agents.ErrNotFound
 		}
+		log.Error(ctx, "Error calling LastFM/album.getInfo", "album", name, "artist", artist, err)
 		return nil, err
 	}
 	return a, nil
@@ -313,6 +309,12 @@ func (l *lastfmAgent) callArtistGetInfo(ctx context.Context, name string, lang s
 
 	a, err := l.client.artistGetInfo(ctx, name, lang)
 	if err != nil {
+		if lfErr, ok := errors.AsType[*lastFMError](err); ok && lfErr.Code == 6 {
+			// A not-found is a definitive absence, not a fault: return the shared sentinel so it
+			// doesn't trip the artwork worker's breaker, and log at Debug instead of Error.
+			log.Debug(ctx, "Artist not found in Last.fm", "artist", name)
+			return nil, agents.ErrNotFound
+		}
 		log.Error(ctx, "Error calling LastFM/artist.getInfo", "artist", name, err)
 		return nil, err
 	}
diff --git a/adapters/lastfm/agent_test.go b/adapters/lastfm/agent_test.go
index 7e4e29294..94024b9ab 100644
--- a/adapters/lastfm/agent_test.go
+++ b/adapters/lastfm/agent_test.go
@@ -539,7 +539,10 @@ var _ = Describe("lastfmAgent", func() {
 				URL:         "https://www.last.fm/music/Cher/Believe",
 			}))
 			Expect(httpClient.RequestCount).To(Equal(1))
-			Expect(httpClient.SavedRequest.URL.Query().Get("mbid")).To(Equal("03c91c40-49a6-44a7-90e7-a700edf97a62"))
+			// MBID is deliberately not sent — album.getInfo matches on name+artist only.
+			Expect(httpClient.SavedRequest.URL.Query().Get("mbid")).To(BeEmpty())
+			Expect(httpClient.SavedRequest.URL.Query().Get("album")).To(Equal("Believe"))
+			Expect(httpClient.SavedRequest.URL.Query().Get("artist")).To(Equal("Cher"))
 		})
 
 		It("returns empty images if no images are available", func() {
@@ -558,7 +561,7 @@ var _ = Describe("lastfmAgent", func() {
 			_, err := agent.GetAlbumInfo(ctx, "123", "U2", "mbid-1234")
 			Expect(err).To(HaveOccurred())
 			Expect(httpClient.RequestCount).To(Equal(1))
-			Expect(httpClient.SavedRequest.URL.Query().Get("mbid")).To(Equal("mbid-1234"))
+			Expect(httpClient.SavedRequest.URL.Query().Get("mbid")).To(BeEmpty())
 		})
 
 		It("returns an error if Last.fm call returns an error", func() {
@@ -566,23 +569,17 @@ var _ = Describe("lastfmAgent", func() {
 			_, err := agent.GetAlbumInfo(ctx, "123", "U2", "mbid-1234")
 			Expect(err).To(HaveOccurred())
 			Expect(httpClient.RequestCount).To(Equal(1))
-			Expect(httpClient.SavedRequest.URL.Query().Get("mbid")).To(Equal("mbid-1234"))
+			Expect(httpClient.SavedRequest.URL.Query().Get("mbid")).To(BeEmpty())
 		})
 
-		It("returns an error if Last.fm call returns an error 6 and mbid is empty", func() {
+		It("returns an error when Last.fm returns an error 6 (album not found)", func() {
 			httpClient.Res = http.Response{Body: io.NopCloser(bytes.NewBufferString(lastfmError6)), StatusCode: 200}
-			_, err := agent.GetAlbumInfo(ctx, "123", "U2", "")
+			_, err := agent.GetAlbumInfo(ctx, "123", "U2", "mbid-1234")
 			Expect(err).To(HaveOccurred())
+			// A definitive not-found must satisfy the sentinel, or the artwork worker retries it.
+			Expect(errors.Is(err, agents.ErrNotFound)).To(BeTrue())
 			Expect(httpClient.RequestCount).To(Equal(1))
-		})
-
-		Context("MBID non existent in Last.fm", func() {
-			It("calls again when last.fm returns an error 6", func() {
-				httpClient.Res = http.Response{Body: io.NopCloser(bytes.NewBufferString(lastfmError6)), StatusCode: 200}
-				_, _ = agent.GetAlbumInfo(ctx, "123", "U2", "mbid-1234")
-				Expect(httpClient.RequestCount).To(Equal(2))
-				Expect(httpClient.SavedRequest.URL.Query().Get("mbid")).To(BeEmpty())
-			})
+			Expect(httpClient.SavedRequest.URL.Query().Get("mbid")).To(BeEmpty())
 		})
 	})
 
@@ -613,6 +610,13 @@ var _ = Describe("lastfmAgent", func() {
 			Expect(images[0].URL).To(Equal("https://lastfm.freetls.fastly.net/i/u/ar0/818148bf682d429dc21b59a73ef6f68e.png"))
 		})
 
+		It("maps a Last.fm error 6 (artist not found) to the shared not-found sentinel", func() {
+			apiClient.Res = http.Response{Body: io.NopCloser(bytes.NewBufferString(lastfmError6)), StatusCode: 200}
+			_, err := agent.GetArtistImages(ctx, "123", "Nonexistent Artist", "")
+			// Not a fault: runs of missing artists must not trip the worker's circuit breaker.
+			Expect(errors.Is(err, agents.ErrNotFound)).To(BeTrue())
+		})
+
 		It("returns empty list if image is the ignored default image", func() {
 			fApi, _ := os.Open("tests/fixtures/lastfm.artist.getinfo.json")
 			apiClient.Res = http.Response{Body: fApi, StatusCode: 200}
diff --git a/cmd/pls.go b/cmd/pls.go
index 95cbe4eec..184ca6fe7 100644
--- a/cmd/pls.go
+++ b/cmd/pls.go
@@ -12,7 +12,7 @@ import (
 	"strings"
 
 	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -260,7 +260,7 @@ func runImport(ctx context.Context, files []string) {
 		ctx = request.WithUser(ctx, *user)
 	}
 
-	pls := playlists.NewPlaylists(ds, core.NewImageUploadService())
+	pls := playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 	for _, file := range files {
 		absPath, err := filepath.Abs(file)
diff --git a/cmd/root.go b/cmd/root.go
index d9e766c32..ff1641bd3 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -11,6 +11,7 @@ import (
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -88,6 +89,9 @@ func runNavidrome(ctx context.Context) {
 	g.Go(startInsightsCollector(ctx))
 	g.Go(scheduleDBAnalyzer(ctx))
 	g.Go(startPluginManager(ctx))
+	artworkWorker := CreateArtworkWorker()
+	g.Go(startArtworkWorker(ctx, artworkWorker))
+	g.Go(scheduleArtworkHousekeeping(ctx, artworkWorker))
 	g.Go(runInitialScan(ctx))
 	if conf.Server.Scanner.Enabled {
 		g.Go(startScanWatcher(ctx))
@@ -344,6 +348,68 @@ func startPlaybackServer(ctx context.Context) func() error {
 	}
 }
 
+// startArtworkWorker starts the background artwork acquisition worker. It always
+// runs; the queue is simply empty until something enqueues work into it.
+func startArtworkWorker(ctx context.Context, worker *artwork.Worker) func() error {
+	return func() error {
+		log.Info(ctx, "Starting artwork worker")
+		return worker.Run(ctx)
+	}
+}
+
+// scheduleArtworkHousekeeping runs the startup fingerprint backfill and registers the
+// recurring stale-absent recheck and prune jobs.
+func scheduleArtworkHousekeeping(ctx context.Context, worker *artwork.Worker) func() error {
+	return func() error {
+		schedulerInstance := scheduler.GetInstance()
+
+		if _, err := schedulerInstance.Add(consts.ArtworkStaleAbsentRecheckSchedule, func() {
+			if err := worker.EnqueueStaleAbsentAll(ctx); err != nil {
+				log.Error(ctx, "Error enqueueing stale artwork rechecks", err)
+			}
+			if err := worker.EnqueueMissingAll(ctx); err != nil {
+				log.Error(ctx, "Error enqueueing missing artwork rechecks", err)
+			}
+		}); err != nil {
+			log.Error(ctx, "Error scheduling artwork stale-absent recheck", err)
+		}
+
+		if _, err := schedulerInstance.Add(consts.ArtworkPruneSchedule, func() {
+			if err := worker.RunPrune(ctx); err != nil {
+				log.Error(ctx, "Error running artwork prune", err)
+			}
+		}); err != nil {
+			log.Error(ctx, "Error scheduling artwork prune", err)
+		}
+
+		// Also run the missing-row recheck once at startup so a never-scanned entity is picked up
+		// immediately, not only on the next hourly tick (e.g. after enabling the feature).
+		if err := worker.EnqueueMissingAll(ctx); err != nil {
+			log.Error(ctx, "Error enqueueing missing artwork rechecks", err)
+		}
+
+		backfilled, err := worker.Backfill(ctx)
+		if err != nil {
+			log.Error(ctx, "Error running artwork backfill", err)
+			return nil
+		}
+		if !backfilled {
+			return nil
+		}
+		log.Info(ctx, "Artwork backfill enqueued, scheduling a follow-up prune")
+		timer := time.NewTimer(consts.ArtworkPostBackfillPruneDelay)
+		defer timer.Stop()
+		select {
+		case <-timer.C:
+			if err := worker.RunPrune(ctx); err != nil {
+				log.Error(ctx, "Error running post-backfill artwork prune", err)
+			}
+		case <-ctx.Done():
+		}
+		return nil
+	}
+}
+
 // startPluginManager starts the plugin manager, if configured.
 func startPluginManager(ctx context.Context) func() error {
 	return func() error {
diff --git a/cmd/scan.go b/cmd/scan.go
index 320b401d4..08eccbf2a 100644
--- a/cmd/scan.go
+++ b/cmd/scan.go
@@ -9,7 +9,7 @@ import (
 	"os"
 	"strings"
 
-	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
@@ -82,7 +82,7 @@ func runScanner(ctx context.Context) {
 	sqlDB := db.Db()
 	defer db.Db().Close()
 	ds := persistence.New(sqlDB)
-	pls := playlists.NewPlaylists(ds, core.NewImageUploadService())
+	pls := playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 	// Parse targets from command line or file
 	var scanTargets []model.ScanTarget
diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index c4a797ef4..4bdd48422 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -65,25 +65,18 @@ func CreateNativeAPIRouter(ctx context.Context) *nativeapi.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	share := core.NewShare(dataStore)
-	imageUploadService := core.NewImageUploadService()
-	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
+	uploader := artwork.NewUploader(dataStore)
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
 	insights := metrics.GetInstance(dataStore)
-	fileCache := artwork.GetImageCache()
-	fFmpeg := ffmpeg.New()
 	broker := events.GetBroker()
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
-	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
-	agentsAgents := agents.GetAgents(dataStore, manager)
-	matcherMatcher := matcher.New(dataStore)
-	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
-	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
-	cacheWarmer := artwork.NewCacheWarmer(artworkArtwork, fileCache)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
+	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	watcher := scanner.GetWatcher(dataStore, modelScanner)
+	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	library := core.NewLibrary(dataStore, modelScanner, watcher, broker, manager)
 	user := core.NewUser(dataStore, manager)
 	maintenance := core.NewMaintenance(dataStore)
-	router := nativeapi.New(dataStore, share, playlistsPlaylists, insights, library, user, maintenance, manager, imageUploadService)
+	router := nativeapi.New(dataStore, share, playlistsPlaylists, insights, library, user, maintenance, manager, uploader)
 	return router
 }
 
@@ -91,23 +84,23 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	fileCache := artwork.GetImageCache()
+	imageStore := artwork.GetImageStore()
 	fFmpeg := ffmpeg.New()
+	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, imageStore, fFmpeg)
+	transcodingCache := stream.GetTranscodingCache()
+	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
+	share := core.NewShare(dataStore)
+	archiver := core.NewArchiver(mediaStreamer, dataStore, share)
+	players := core.NewPlayers(dataStore)
 	broker := events.GetBroker()
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
 	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	agentsAgents := agents.GetAgents(dataStore, manager)
 	matcherMatcher := matcher.New(dataStore)
 	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
-	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
-	transcodingCache := stream.GetTranscodingCache()
-	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
-	share := core.NewShare(dataStore)
-	archiver := core.NewArchiver(mediaStreamer, dataStore, share)
-	players := core.NewPlayers(dataStore)
-	cacheWarmer := artwork.NewCacheWarmer(artworkArtwork, fileCache)
-	imageUploadService := core.NewImageUploadService()
-	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
+	uploader := artwork.NewUploader(dataStore)
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
+	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	playTracker := scrobbler.GetPlayTracker(dataStore, broker, manager)
 	playbackServer := playback.GetInstance(dataStore)
 	lyricsLyrics := lyrics.NewLyrics(dataStore, manager)
@@ -121,21 +114,22 @@ func CreateJellyfinAPIRouter(ctx context.Context) *jellyfin.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	fileCache := artwork.GetImageCache()
+	imageStore := artwork.GetImageStore()
 	fFmpeg := ffmpeg.New()
-	broker := events.GetBroker()
-	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
-	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
-	agentsAgents := agents.GetAgents(dataStore, manager)
-	matcherMatcher := matcher.New(dataStore)
-	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
-	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
+	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, imageStore, fFmpeg)
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
 	transcodeDecider := stream.NewTranscodeDecider(dataStore, fFmpeg)
 	players := core.NewPlayers(dataStore)
+	broker := events.GetBroker()
+	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
+	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	playTracker := scrobbler.GetPlayTracker(dataStore, broker, manager)
-	imageUploadService := core.NewImageUploadService()
-	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
+	uploader := artwork.NewUploader(dataStore)
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
+	agentsAgents := agents.GetAgents(dataStore, manager)
+	matcherMatcher := matcher.New(dataStore)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
 	sonicSonic := sonic.New(dataStore, manager, matcherMatcher)
 	lyricsLyrics := lyrics.NewLyrics(dataStore, manager)
 	router := jellyfin.New(dataStore, artworkArtwork, mediaStreamer, transcodeDecider, players, playTracker, playlistsPlaylists, provider, sonicSonic, lyricsLyrics, broker)
@@ -146,14 +140,9 @@ func CreatePublicRouter() *public.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
 	fileCache := artwork.GetImageCache()
+	imageStore := artwork.GetImageStore()
 	fFmpeg := ffmpeg.New()
-	broker := events.GetBroker()
-	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
-	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
-	agentsAgents := agents.GetAgents(dataStore, manager)
-	matcherMatcher := matcher.New(dataStore)
-	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
-	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
+	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, imageStore, fFmpeg)
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
 	share := core.NewShare(dataStore)
@@ -193,38 +182,22 @@ func CreatePrometheus() metrics.Metrics {
 func CreateScanner(ctx context.Context) model.Scanner {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
-	fileCache := artwork.GetImageCache()
-	fFmpeg := ffmpeg.New()
 	broker := events.GetBroker()
+	uploader := artwork.NewUploader(dataStore)
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
-	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
-	agentsAgents := agents.GetAgents(dataStore, manager)
-	matcherMatcher := matcher.New(dataStore)
-	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
-	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
-	cacheWarmer := artwork.NewCacheWarmer(artworkArtwork, fileCache)
-	imageUploadService := core.NewImageUploadService()
-	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
+	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	return modelScanner
 }
 
 func CreateScanWatcher(ctx context.Context) scanner.Watcher {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
-	fileCache := artwork.GetImageCache()
-	fFmpeg := ffmpeg.New()
 	broker := events.GetBroker()
+	uploader := artwork.NewUploader(dataStore)
+	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
-	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
-	agentsAgents := agents.GetAgents(dataStore, manager)
-	matcherMatcher := matcher.New(dataStore)
-	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
-	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, fFmpeg, provider)
-	cacheWarmer := artwork.NewCacheWarmer(artworkArtwork, fileCache)
-	imageUploadService := core.NewImageUploadService()
-	playlistsPlaylists := playlists.NewPlaylists(dataStore, imageUploadService)
-	modelScanner := scanner.New(ctx, dataStore, cacheWarmer, broker, playlistsPlaylists, metricsMetrics)
+	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	watcher := scanner.GetWatcher(dataStore, modelScanner)
 	return watcher
 }
@@ -236,6 +209,20 @@ func GetPlaybackServer() playback.PlaybackServer {
 	return playbackServer
 }
 
+func CreateArtworkWorker() *artwork.Worker {
+	sqlDB := db.Db()
+	dataStore := persistence.New(sqlDB)
+	imageStore := artwork.GetImageStore()
+	broker := events.GetBroker()
+	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
+	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
+	agentsAgents := agents.GetAgents(dataStore, manager)
+	fFmpeg := ffmpeg.New()
+	fileCache := artwork.GetImageCache()
+	worker := artwork.NewWorker(dataStore, imageStore, agentsAgents, fFmpeg, broker, fileCache)
+	return worker
+}
+
 func getPluginManager() *plugins.Manager {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
@@ -247,7 +234,7 @@ func getPluginManager() *plugins.Manager {
 
 // wire_injectors.go:
 
-var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, jellyfin.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(sonic.Engine), new(*sonic.Sonic)), 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, jellyfin.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(sonic.Engine), new(*sonic.Sonic)), 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)), wire.Bind(new(playlists.ImageUploadService), new(artwork.Uploader)))
 
 func GetPluginManager(ctx context.Context) *plugins.Manager {
 	manager := getPluginManager()
diff --git a/cmd/wire_injectors.go b/cmd/wire_injectors.go
index 94faa5af3..ae24b61fa 100644
--- a/cmd/wire_injectors.go
+++ b/cmd/wire_injectors.go
@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/core/lyrics"
 	"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/db"
@@ -56,6 +57,7 @@ var allProviders = wire.NewSet(
 	wire.Bind(new(core.PluginUnloader), new(*plugins.Manager)),
 	wire.Bind(new(plugins.PluginMetricsRecorder), new(metrics.Metrics)),
 	wire.Bind(new(core.Watcher), new(scanner.Watcher)),
+	wire.Bind(new(playlists.ImageUploadService), new(artwork.Uploader)),
 )
 
 func CreateDataStore() model.DataStore {
@@ -136,6 +138,12 @@ func GetPlaybackServer() playback.PlaybackServer {
 	))
 }
 
+func CreateArtworkWorker() *artwork.Worker {
+	panic(wire.Build(
+		allProviders,
+	))
+}
+
 func getPluginManager() *plugins.Manager {
 	panic(wire.Build(
 		allProviders,
diff --git a/conf/configuration.go b/conf/configuration.go
index 9b49fb264..5122b15eb 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -144,6 +144,8 @@ type configOptions struct {
 	DevArtworkThrottleBacklogLimit    int
 	DevArtworkThrottleBacklogTimeout  time.Duration
 	DevArtworkThrottleBuffered        bool
+	DevArtworkWorkerConcurrency       int
+	DevArtworkExternalMaxRPS          int
 	DevArtistInfoTimeToLive           time.Duration
 	DevAlbumInfoTimeToLive            time.Duration
 	DevExternalScanner                bool
@@ -1071,6 +1073,12 @@ func setViperDefaults() {
 	viper.SetDefault("devartworkthrottlebackloglimit", consts.RequestThrottleBacklogLimit)
 	viper.SetDefault("devartworkthrottlebacklogtimeout", consts.RequestThrottleBacklogTimeout)
 	viper.SetDefault("devartworkthrottlebuffered", true)
+	// Half the CPU count (min 2), so local resolution scales with the host but stays under the
+	// SQLite pool (MaxOpenConns) — leaving connections for the scanner, scrobbles and the UI.
+	viper.SetDefault("devartworkworkerconcurrency", max(2, runtime.NumCPU()/2))
+	// External RPS gates outbound calls to third-party services (per service); it is bounded by
+	// their tolerance, not the host, so it stays a small constant regardless of CPU count.
+	viper.SetDefault("devartworkexternalmaxrps", 2)
 	viper.SetDefault("devartistinfotimetolive", consts.ArtistInfoTimeToLive)
 	viper.SetDefault("devalbuminfotimetolive", consts.AlbumInfoTimeToLive)
 	viper.SetDefault("devexternalscanner", true)
diff --git a/consts/consts.go b/consts/consts.go
index e1a535c79..46906b8b5 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -24,6 +24,9 @@ const (
 	LastDBAnalyzeAttemptAtKey     = "LastDBAnalyzeAttemptAt"
 	DBAnalyzePendingKey           = "DBAnalyzePending"
 	DBAnalyzeFailureCountKey      = "DBAnalyzeFailureCount"
+	// ArtConfFingerprintPropertyKey is the model.PropertyRepository key Backfill compares against
+	// to detect artwork-affecting config changes across restarts.
+	ArtConfFingerprintPropertyKey = "ArtConfFingerprint"
 
 	UIAuthorizationHeader  = "X-ND-Authorization"
 	UIClientUniqueIDHeader = "X-ND-Client-Unique-Id"
@@ -36,6 +39,10 @@ const (
 	DBAnalyzeCheckSchedule = "@every 30m"
 	DBAnalyzeMaxAge        = 24 * time.Hour
 
+	ArtworkStaleAbsentRecheckSchedule = "@every 1h"
+	ArtworkPruneSchedule              = "@daily"
+	ArtworkPostBackfillPruneDelay     = 10 * time.Minute
+
 	// DefaultEncryptionKey This is the encryption key used if none is specified in the `PasswordEncryptionKey` option
 	// Never ever change this! Or it will break all Navidrome installations that don't set the config option
 	DefaultEncryptionKey  = "just for obfuscation"
@@ -80,6 +87,9 @@ const (
 	I18nFolder     = "i18n"
 	ScanIgnoreFile = ".ndignore"
 	ArtworkFolder  = "artwork"
+	// HashedArtworkFolder is a subtree of ArtworkFolder, kept apart from the name-addressed
+	// upload folders beside it so Prune's sweep never reaches them.
+	HashedArtworkFolder = "hashed"
 
 	PlaceholderArtistArt            = "artist-placeholder.webp"
 	PlaceholderAlbumArt             = "album-placeholder.webp"
diff --git a/core/agents/agents.go b/core/agents/agents.go
index ead6dacd0..348f7d4e7 100644
--- a/core/agents/agents.go
+++ b/core/agents/agents.go
@@ -124,6 +124,42 @@ func (a *Agents) AgentName() string {
 	return "agents"
 }
 
+// ArtistImageAgent pairs an enabled agent's name with its ArtistImageRetriever capability.
+type ArtistImageAgent struct {
+	Name      string
+	Retriever ArtistImageRetriever
+}
+
+// AlbumImageAgent pairs an enabled agent's name with its AlbumImageRetriever capability.
+type AlbumImageAgent struct {
+	Name      string
+	Retriever AlbumImageRetriever
+}
+
+// ArtistImageAgents returns the enabled agents implementing ArtistImageRetriever,
+// in conf.Server.Agents order (same order the aggregate dispatch uses).
+func (a *Agents) ArtistImageAgents() []ArtistImageAgent {
+	var result []ArtistImageAgent
+	for _, ea := range a.getEnabledAgentNames() {
+		if retriever, ok := a.getAgent(ea).(ArtistImageRetriever); ok {
+			result = append(result, ArtistImageAgent{Name: ea.name, Retriever: retriever})
+		}
+	}
+	return result
+}
+
+// AlbumImageAgents returns the enabled agents implementing AlbumImageRetriever,
+// in conf.Server.Agents order (same order the aggregate dispatch uses).
+func (a *Agents) AlbumImageAgents() []AlbumImageAgent {
+	var result []AlbumImageAgent
+	for _, ea := range a.getEnabledAgentNames() {
+		if retriever, ok := a.getAgent(ea).(AlbumImageRetriever); ok {
+			result = append(result, AlbumImageAgent{Name: ea.name, Retriever: retriever})
+		}
+	}
+	return result
+}
+
 func (a *Agents) GetArtistMBID(ctx context.Context, id string, name string) (string, error) {
 	switch id {
 	case consts.UnknownArtistID:
diff --git a/core/agents/agents_test.go b/core/agents/agents_test.go
index 50285a084..e3087f995 100644
--- a/core/agents/agents_test.go
+++ b/core/agents/agents_test.go
@@ -362,6 +362,64 @@ var _ = Describe("Agents", func() {
 			})
 		})
 	})
+
+	Describe("Image retriever enumeration", func() {
+		var ag *Agents
+		var artistImg, artistImg2 *testImageAgent
+		var albumImg, albumImg2 *testAlbumImageAgent
+
+		BeforeEach(func() {
+			artistImg = &testImageAgent{Name: "artistImg"}
+			artistImg2 = &testImageAgent{Name: "artistImg2"}
+			albumImg = &testAlbumImageAgent{name: "albumImg"}
+			albumImg2 = &testAlbumImageAgent{name: "albumImg2"}
+			Register("artistImg", func(model.DataStore) Interface { return artistImg })
+			Register("artistImg2", func(model.DataStore) Interface { return artistImg2 })
+			Register("albumImg", func(model.DataStore) Interface { return albumImg })
+			Register("albumImg2", func(model.DataStore) Interface { return albumImg2 })
+			Register("noImages", func(model.DataStore) Interface { return &emptyAgent{} })
+		})
+
+		Describe("ArtistImageAgents", func() {
+			It("returns only ArtistImageRetriever agents, named, in configured order", func() {
+				conf.Server.Agents = "artistImg,noImages,artistImg2"
+				ag = createAgents(ds, nil)
+
+				result := ag.ArtistImageAgents()
+				Expect(result).To(HaveLen(2))
+				Expect(result[0].Name).To(Equal("artistImg"))
+				Expect(result[0].Retriever).To(BeIdenticalTo(artistImg))
+				Expect(result[1].Name).To(Equal("artistImg2"))
+				Expect(result[1].Retriever).To(BeIdenticalTo(artistImg2))
+			})
+
+			It("is empty when external services are disabled", func() {
+				conf.Server.Agents = "" // what disableExternalServices() sets when EnableExternalServices=false
+				ag = createAgents(ds, nil)
+				Expect(ag.ArtistImageAgents()).To(BeEmpty())
+			})
+		})
+
+		Describe("AlbumImageAgents", func() {
+			It("returns only AlbumImageRetriever agents, named, in configured order", func() {
+				conf.Server.Agents = "albumImg,noImages,albumImg2"
+				ag = createAgents(ds, nil)
+
+				result := ag.AlbumImageAgents()
+				Expect(result).To(HaveLen(2))
+				Expect(result[0].Name).To(Equal("albumImg"))
+				Expect(result[0].Retriever).To(BeIdenticalTo(albumImg))
+				Expect(result[1].Name).To(Equal("albumImg2"))
+				Expect(result[1].Retriever).To(BeIdenticalTo(albumImg2))
+			})
+
+			It("is empty when external services are disabled", func() {
+				conf.Server.Agents = "" // what disableExternalServices() sets when EnableExternalServices=false
+				ag = createAgents(ds, nil)
+				Expect(ag.AlbumImageAgents()).To(BeEmpty())
+			})
+		})
+	})
 })
 
 type mockAgent struct {
@@ -497,3 +555,17 @@ func (t *testImageAgent) GetArtistImages(_ context.Context, id, name, mbid strin
 	t.Args = []any{id, name, mbid}
 	return t.Images, t.Err
 }
+
+type testAlbumImageAgent struct {
+	name   string
+	Images []ExternalImage
+	Err    error
+	Args   []any
+}
+
+func (t *testAlbumImageAgent) AgentName() string { return t.name }
+
+func (t *testAlbumImageAgent) GetAlbumImages(_ context.Context, name, artist, mbid string) ([]ExternalImage, error) {
+	t.Args = []any{name, artist, mbid}
+	return t.Images, t.Err
+}
diff --git a/core/artwork/agent_images.go b/core/artwork/agent_images.go
new file mode 100644
index 000000000..c7032b62b
--- /dev/null
+++ b/core/artwork/agent_images.go
@@ -0,0 +1,100 @@
+package artwork
+
+import (
+	"context"
+	"io"
+	"net/url"
+
+	"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/str"
+)
+
+// externalName mirrors the normalization the aggregate provider applies, so agent searches match.
+func externalName(name string) string {
+	if conf.Server.DevPreserveUnicodeInExternalCalls {
+		return name
+	}
+	return str.Clear(name)
+}
+
+// bestImageURL returns the largest fetchable image URL. Only one is returned and its failure ends
+// the agent's turn, so an unfetchable candidate must never win: url.Parse alone accepts anything.
+func bestImageURL(imgs []agents.ExternalImage) *url.URL {
+	var best *url.URL
+	var bestSize int
+	for i := range imgs {
+		if imgs[i].URL == "" {
+			continue
+		}
+		u, err := url.Parse(imgs[i].URL)
+		if err != nil || !u.IsAbs() || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+			continue
+		}
+		if best == nil || imgs[i].Size > bestSize {
+			best, bestSize = u, imgs[i].Size
+		}
+	}
+	return best
+}
+
+// fetchArtistImage tries each enabled artist-image agent in order. extErr is true only when no
+// agent succeeded and at least one failed transiently.
+func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar model.Artist) (r io.ReadCloser, agentName string, extErr bool) {
+	// Synthetic artists would otherwise get an unrelated agent result assigned to them.
+	switch ar.ID {
+	case consts.UnknownArtistID, consts.VariousArtistsID:
+		return nil, "", false
+	}
+	name := externalName(ar.Name)
+	for _, a := range ag.ArtistImageAgents() {
+		reader, _, err := gate(a.Name, func() (io.ReadCloser, string, error) {
+			imgs, err := a.Retriever.GetArtistImages(ctx, ar.ID, name, ar.MbzArtistID)
+			if err != nil {
+				return nil, "", err
+			}
+			u := bestImageURL(imgs)
+			if u == nil {
+				return nil, "", agents.ErrNotFound
+			}
+			return fromURL(ctx, u)
+		})
+		if reader != nil {
+			return reader, a.Name, false
+		}
+		if isTransientExternal(err) {
+			extErr = true
+			log.Debug(ctx, "Artwork: External artist-image lookup failed", "agent", a.Name, "artist", ar.Name, err)
+		}
+	}
+	return nil, "", extErr
+}
+
+// fetchAlbumImage is the album counterpart of fetchArtistImage.
+func fetchAlbumImage(ctx context.Context, ag *agents.Agents, gate gateFunc, al model.Album) (r io.ReadCloser, agentName string, extErr bool) {
+	name, artist := externalName(al.Name), externalName(al.AlbumArtist)
+	for _, a := range ag.AlbumImageAgents() {
+		reader, _, err := gate(a.Name, func() (io.ReadCloser, string, error) {
+			imgs, err := a.Retriever.GetAlbumImages(ctx, name, artist, al.MbzAlbumID)
+			if err != nil {
+				return nil, "", err
+			}
+			u := bestImageURL(imgs)
+			if u == nil {
+				return nil, "", agents.ErrNotFound
+			}
+			return fromURL(ctx, u)
+		})
+		if reader != nil {
+			return reader, a.Name, false
+		}
+		if isTransientExternal(err) {
+			extErr = true
+			log.Debug(ctx, "Artwork: External album-image lookup failed", "agent", a.Name, "album", al.Name, err)
+		}
+	}
+	return nil, "", extErr
+}
diff --git a/core/artwork/agent_images_test.go b/core/artwork/agent_images_test.go
new file mode 100644
index 000000000..716245c93
--- /dev/null
+++ b/core/artwork/agent_images_test.go
@@ -0,0 +1,262 @@
+package artwork
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/str"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// fakeImageAgent is a built-in agent stub implementing both image retrievers; it
+// records call counts so per-agent ordering and short-circuiting can be asserted.
+type fakeImageAgent struct {
+	name          string
+	imgs          []agents.ExternalImage
+	err           error
+	artistCalls   int
+	albumCalls    int
+	gotArtistName string
+	gotAlbumName  string
+	// block, when set, holds every lookup until closed, standing in for a slow/rate-limited agent.
+	block chan struct{}
+	// mu guards the call counters: the worker resolves several items concurrently.
+	mu sync.Mutex
+}
+
+func (f *fakeImageAgent) AgentName() string { return f.name }
+
+func (f *fakeImageAgent) GetArtistImages(_ context.Context, _, name, _ string) ([]agents.ExternalImage, error) {
+	if f.block != nil {
+		<-f.block
+	}
+	f.mu.Lock()
+	f.artistCalls++
+	f.gotArtistName = name
+	f.mu.Unlock()
+	return f.imgs, f.err
+}
+
+func (f *fakeImageAgent) GetAlbumImages(_ context.Context, name, _, _ string) ([]agents.ExternalImage, error) {
+	f.albumCalls++
+	f.gotAlbumName = name
+	return f.imgs, f.err
+}
+
+// imageAgents registers the fakes as built-in agents and enables them in order. The fakes
+// ignore the DataStore, so reusing the process-wide GetAgents singleton across tests is safe.
+func imageAgents(fakes ...*fakeImageAgent) *agents.Agents {
+	names := make([]string, 0, len(fakes))
+	for _, f := range fakes {
+		fake := f
+		agents.Register(fake.name, func(model.DataStore) agents.Interface { return fake })
+		names = append(names, fake.name)
+	}
+	conf.Server.Agents = strings.Join(names, ",")
+	return agents.GetAgents(&tests.MockDataStore{}, nil)
+}
+
+var _ = Describe("agent images", func() {
+	var (
+		ctx context.Context
+		srv *httptest.Server
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		ctx = context.Background()
+		srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write([]byte("image-bytes"))
+		}))
+		DeferCleanup(srv.Close)
+	})
+
+	img := func(path string, size int) agents.ExternalImage {
+		return agents.ExternalImage{URL: srv.URL + path, Size: size}
+	}
+
+	Describe("bestImageURL", func() {
+		It("picks the largest-Size URL and skips empty ones", func() {
+			u := bestImageURL([]agents.ExternalImage{
+				{URL: "http://x/small", Size: 10},
+				{URL: "", Size: 9999},
+				{URL: "http://x/big", Size: 100},
+			})
+			Expect(u).ToNot(BeNil())
+			Expect(u.String()).To(Equal("http://x/big"))
+		})
+
+		It("skips a malformed largest URL and falls back to a valid smaller one", func() {
+			u := bestImageURL([]agents.ExternalImage{
+				{URL: "http://x/valid", Size: 10},
+				{URL: "http://x/%zz", Size: 100}, // invalid percent-escape, largest
+			})
+			Expect(u).ToNot(BeNil())
+			Expect(u.String()).To(Equal("http://x/valid"))
+		})
+
+		It("returns nil when there is no non-empty URL", func() {
+			Expect(bestImageURL(nil)).To(BeNil())
+			Expect(bestImageURL([]agents.ExternalImage{{URL: "", Size: 5}})).To(BeNil())
+		})
+
+		// Plugins hand these over as free-form strings, and url.Parse accepts them all. An
+		// unfetchable candidate that wins here ends the agent's turn before its valid images run.
+		DescribeTable("skips a candidate that cannot be fetched",
+			func(badURL string) {
+				u := bestImageURL([]agents.ExternalImage{
+					{URL: badURL, Size: 100}, // largest, and first
+					{URL: "https://cdn.example.com/ok.jpg", Size: 10},
+				})
+				Expect(u).ToNot(BeNil())
+				Expect(u.String()).To(Equal("https://cdn.example.com/ok.jpg"))
+			},
+			Entry("a relative path", "images/big.jpg"),
+			Entry("a root-relative path", "/images/big.jpg"),
+			Entry("a scheme we cannot fetch", "ftp://host/big.jpg"),
+			Entry("a scheme-relative URL", "//host/big.jpg"),
+			Entry("a URL with no host", "http:///big.jpg"),
+		)
+
+		// Size is often 0 for every candidate, and only a strictly larger one replaces the first,
+		// so an unfetchable entry in first position would otherwise stick.
+		It("skips an unfetchable first candidate when every Size is zero", func() {
+			u := bestImageURL([]agents.ExternalImage{
+				{URL: "images/rel.jpg"},
+				{URL: "https://cdn.example.com/ok.jpg"},
+			})
+			Expect(u).ToNot(BeNil())
+			Expect(u.String()).To(Equal("https://cdn.example.com/ok.jpg"))
+		})
+
+		It("returns nil when no candidate is fetchable", func() {
+			Expect(bestImageURL([]agents.ExternalImage{
+				{URL: "images/a.jpg", Size: 10},
+				{URL: "ftp://host/b.jpg", Size: 20},
+			})).To(BeNil())
+		})
+	})
+
+	Describe("fetchArtistImage", func() {
+		It("returns the first agent's image and its name", func() {
+			a := &fakeImageAgent{name: "agentA", imgs: []agents.ExternalImage{img("/a", 100)}}
+			ag := imageAgents(a)
+
+			r, name, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1", Name: "Artist"})
+			Expect(r).ToNot(BeNil())
+			defer r.Close()
+			Expect(name).To(Equal("agentA"))
+			Expect(extErr).To(BeFalse())
+		})
+
+		It("skips the external lookup for synthetic artists", func() {
+			a := &fakeImageAgent{name: "agentA", imgs: []agents.ExternalImage{img("/a", 100)}}
+			ag := imageAgents(a)
+
+			for _, id := range []string{consts.UnknownArtistID, consts.VariousArtistsID} {
+				r, name, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: id, Name: "Various Artists"})
+				Expect(r).To(BeNil())
+				Expect(name).To(BeEmpty())
+				Expect(extErr).To(BeFalse())
+			}
+			Expect(a.artistCalls).To(Equal(0), "synthetic artists never reach the agents")
+		})
+
+		It("clears typographic characters from the query name unless preserving unicode", func() {
+			conf.Server.DevPreserveUnicodeInExternalCalls = false
+			a := &fakeImageAgent{name: "agentA"}
+			ag := imageAgents(a)
+
+			_, _, _ = fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1", Name: "AC’DC"})
+			Expect(a.gotArtistName).To(Equal(str.Clear("AC’DC")))
+		})
+
+		It("falls through to a later agent, and its success beats the earlier error", func() {
+			a := &fakeImageAgent{name: "agentA", err: errBreakerOpen}
+			b := &fakeImageAgent{name: "agentB", imgs: []agents.ExternalImage{img("/b", 50)}}
+			ag := imageAgents(a, b)
+
+			r, name, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
+			Expect(r).ToNot(BeNil())
+			defer r.Close()
+			Expect(name).To(Equal("agentB"))
+			Expect(extErr).To(BeFalse(), "a later hit clears an earlier agent's error")
+			Expect(a.artistCalls).To(Equal(1))
+			Expect(b.artistCalls).To(Equal(1))
+		})
+
+		It("reports a clean miss when every agent finds nothing", func() {
+			a := &fakeImageAgent{name: "agentA"} // no images, no error -> not found
+			b := &fakeImageAgent{name: "agentB", err: agents.ErrNotFound}
+			ag := imageAgents(a, b)
+
+			r, name, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
+			Expect(r).To(BeNil())
+			Expect(name).To(BeEmpty())
+			Expect(extErr).To(BeFalse(), "not-found is definitive, never a transient failure")
+		})
+
+		It("reports extErr when one agent fails transiently and the rest find nothing", func() {
+			a := &fakeImageAgent{name: "agentA", err: agents.ErrNotFound}
+			b := &fakeImageAgent{name: "agentB", err: context.DeadlineExceeded}
+			ag := imageAgents(a, b)
+
+			r, _, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
+			Expect(r).To(BeNil())
+			Expect(extErr).To(BeTrue())
+		})
+	})
+
+	Describe("fetchAlbumImage", func() {
+		It("returns the winning agent's image and name", func() {
+			a := &fakeImageAgent{name: "agentA", imgs: []agents.ExternalImage{img("/a", 100)}}
+			ag := imageAgents(a)
+
+			r, name, extErr := fetchAlbumImage(ctx, ag, passthroughGate, model.Album{Name: "Album", AlbumArtist: "Artist"})
+			Expect(r).ToNot(BeNil())
+			defer r.Close()
+			Expect(name).To(Equal("agentA"))
+			Expect(extErr).To(BeFalse())
+			Expect(a.albumCalls).To(Equal(1))
+		})
+
+		It("reports extErr when the only agent fails transiently", func() {
+			a := &fakeImageAgent{name: "agentA", err: context.DeadlineExceeded}
+			ag := imageAgents(a)
+
+			r, _, extErr := fetchAlbumImage(ctx, ag, passthroughGate, model.Album{Name: "Album"})
+			Expect(r).To(BeNil())
+			Expect(extErr).To(BeTrue())
+		})
+	})
+
+	Describe("gate naming", func() {
+		It("invokes the gate once per agent, keyed by agent name", func() {
+			a := &fakeImageAgent{name: "agentA", err: context.DeadlineExceeded}
+			b := &fakeImageAgent{name: "agentB", imgs: []agents.ExternalImage{img("/b", 1)}}
+			ag := imageAgents(a, b)
+
+			var gatedNames []string
+			gate := func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+				gatedNames = append(gatedNames, name)
+				return f()
+			}
+
+			r, _, _ := fetchArtistImage(ctx, ag, gate, model.Artist{ID: "ar1"})
+			Expect(r).ToNot(BeNil())
+			defer r.Close()
+			Expect(gatedNames).To(Equal([]string{"agentA", "agentB"}))
+		})
+	})
+})
diff --git a/core/artwork/artwork.go b/core/artwork/artwork.go
index b8c395c12..8ac8d9c9d 100644
--- a/core/artwork/artwork.go
+++ b/core/artwork/artwork.go
@@ -1,134 +1,394 @@
 package artwork
 
 import (
+	"bytes"
 	"context"
 	"errors"
-	_ "image/gif"
+	"fmt"
 	"io"
+	"os"
 	"time"
 
+	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"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/resources"
 	"github.com/navidrome/navidrome/utils/cache"
-	_ "golang.org/x/image/webp"
 )
 
 var ErrUnavailable = errors.New("artwork unavailable")
 
+// errStaleSource means the backing file's mtime no longer matches RefMtime, so the stored hash may be stale.
+var errStaleSource = errors.New("artwork: source file changed since resolution")
+
+// Image is one servable artwork response.
+type Image struct {
+	io.ReadCloser
+	Hash        string // pixel identity; "" for placeholders
+	ETag        string // representation validator; "" means Hash applies (full-size original)
+	LastUpdated time.Time
+	Placeholder bool
+}
+
+// representationTag varies with dimensions and encode settings, so a config change invalidates
+// a revalidating client's cache even though the pixel hash is unchanged.
+func representationTag(hash string, size int, square bool) string {
+	return fmt.Sprintf("%s.%d.%v.%s", hash, size, square, formatQualityTag())
+}
+
 type Artwork interface {
-	Get(ctx context.Context, artID model.ArtworkID, size int, square bool) (io.ReadCloser, time.Time, error)
-	GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (io.ReadCloser, time.Time, error)
+	// Get returns ErrUnavailable when there is nothing to serve and model.ErrNotFound when
+	// the id resolves to nothing, so the caller can pick placeholder vs 404.
+	Get(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error)
+	// GetOrPlaceholder accepts an artwork token or a raw entity id, falling back to the
+	// kind's placeholder image (never resized, Placeholder=true).
+	GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (*Image, error)
 }
 
-func NewArtwork(ds model.DataStore, cache cache.FileCache, ffmpeg ffmpeg.FFmpeg, provider external.Provider) Artwork {
-	return &artwork{ds: ds, cache: cache, ffmpeg: ffmpeg, provider: provider}
+func NewArtwork(ds model.DataStore, cache cache.FileCache, store *ImageStore, ffm ffmpeg.FFmpeg) Artwork {
+	return &service{ds: ds, cache: cache, store: store, ffmpeg: ffm}
 }
 
-type artwork struct {
-	ds       model.DataStore
-	cache    cache.FileCache
-	ffmpeg   ffmpeg.FFmpeg
-	provider external.Provider
+// entityExists reports whether the entity an artwork id points at is still there: state rows
+// outlive a deleted entity until the next prune, so a servable row is not evidence of its owner.
+func entityExists(ctx context.Context, ds model.DataStore, artID model.ArtworkID) bool {
+	var found bool
+	var err error
+	switch artID.Kind {
+	case model.KindArtistArtwork:
+		found, err = ds.Artist(ctx).Exists(artID.ID)
+	case model.KindAlbumArtwork:
+		found, err = ds.Album(ctx).Exists(artID.ID)
+	case model.KindMediaFileArtwork:
+		found, err = ds.MediaFile(ctx).Exists(artID.ID)
+	case model.KindPlaylistArtwork:
+		found, err = ds.Playlist(ctx).Exists(artID.ID)
+	case model.KindRadioArtwork:
+		found, err = ds.Radio(ctx).Exists(artID.ID)
+	case model.KindDiscArtwork:
+		albumID, _, perr := model.ParseDiscArtworkID(artID.ID)
+		if perr != nil {
+			return false
+		}
+		found, err = ds.Album(ctx).Exists(albumID)
+	default:
+		return false
+	}
+	return err == nil && found
 }
 
-type artworkReader interface {
-	cache.Item
-	LastUpdated() time.Time
-	Reader(ctx context.Context) (io.ReadCloser, string, error)
+type service struct {
+	ds     model.DataStore
+	cache  cache.FileCache
+	store  *ImageStore
+	ffmpeg ffmpeg.FFmpeg
 }
 
-func (a *artwork) GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (reader io.ReadCloser, lastUpdate time.Time, err error) {
-	artID, err := a.getArtworkId(ctx, id)
+func (s *service) GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (*Image, error) {
+	artID, err := s.parseArtworkID(ctx, id)
+	var img *Image
 	if err == nil {
-		reader, lastUpdate, err = a.Get(ctx, artID, size, square)
+		img, err = s.Get(ctx, artID, size, square)
 	}
+	// Only a resolvable entity with no art gets a placeholder; an unknown id must stay
+	// ErrNotFound so callers can still answer 404 / Subsonic error 70.
 	if errors.Is(err, ErrUnavailable) {
-		if artID.Kind == model.KindArtistArtwork {
-			reader, _ = resources.FS().Open(consts.PlaceholderArtistArt)
-		} else {
-			reader, _ = resources.FS().Open(consts.PlaceholderAlbumArt)
-		}
-		return reader, consts.ServerStart, nil
+		return placeholderImage(artID.Kind), nil
 	}
-	return reader, lastUpdate, err
+	return img, err
 }
 
-func (a *artwork) Get(ctx context.Context, artID model.ArtworkID, size int, square bool) (reader io.ReadCloser, lastUpdate time.Time, err error) {
-	artReader, err := a.getArtworkReader(ctx, artID, size, square)
-	if err != nil {
-		return nil, time.Time{}, err
+func (s *service) Get(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
+	if artID.ID == "" {
+		return nil, ErrUnavailable
 	}
-
-	r, err := a.cache.Get(ctx, artReader)
-	if err != nil {
-		if !errors.Is(err, context.Canceled) && !errors.Is(err, ErrUnavailable) {
-			log.Error(ctx, "Error accessing image cache", "id", artID, "size", size, err)
-		}
-		return nil, time.Time{}, err
+	if size < 0 {
+		size = 0 // a negative size means full-size, not a giant (OOM) resize rectangle
+	}
+	switch artID.Kind {
+	case model.KindDiscArtwork:
+		return s.serveDisc(ctx, artID, size, square)
+	case model.KindMediaFileArtwork:
+		return s.serveMediaFile(ctx, artID, size, square)
+	default:
+		return s.serveEntity(ctx, artID, size, square)
 	}
-	return r, artReader.LastUpdated(), nil
 }
 
-type coverArtGetter interface {
+// requestRecheckAge throttles view-triggered rechecks so reopening a genuinely-absent page can't
+// hammer external services; below staleAbsentAge to catch younger absences.
+const requestRecheckAge = time.Hour
+
+func (s *service) serveEntity(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
+	ia, err := s.ds.Artwork(ctx).GetItemArtwork(artID.Kind, artID.ID, model.ImageTypePrimary)
+	switch {
+	case errors.Is(err, model.ErrNotFound):
+		return s.provisional(ctx, artID, size, square)
+	case err != nil:
+		return nil, err
+	case ia.Hash == "":
+		// Inserts an immediately-eligible recheck for a settled absent row.
+		if time.Since(ia.AttemptedAt) > requestRecheckAge {
+			s.enqueue(ctx, artID, model.ArtworkPriorityBump)
+		}
+		return nil, ErrUnavailable
+	default:
+		return s.serveHash(ctx, artID, ia, size, square)
+	}
+}
+
+// serveSource is the one place bytes become an Image. hash is the pixel identity ("" for disc art)
+// and doubles as the full-size validator, so an ETag is only needed when resized or hash is "".
+func (s *service) serveSource(ctx context.Context, key, hash string, lastUpdate time.Time,
+	size int, square bool, open func() (io.ReadCloser, error),
+) (*Image, error) {
+	if size == 0 && !square {
+		rc, err := open()
+		if err != nil {
+			return nil, err
+		}
+		if rc == nil {
+			return nil, ErrUnavailable
+		}
+		img := &Image{ReadCloser: rc, Hash: hash, LastUpdated: lastUpdate}
+		if hash == "" {
+			img.ETag = representationTag(key, size, square)
+		}
+		return img, nil
+	}
+	stream, err := s.cache.Get(ctx, &resizedItem{
+		hash: key, size: size, square: square, ffmpeg: s.ffmpeg, open: open,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &Image{ReadCloser: stream, Hash: hash, ETag: representationTag(key, size, square), LastUpdated: lastUpdate}, nil
+}
+
+// serveHash serves the bytes of a found state row. A mismatch/open error is dangling, but a
+// cancelled request is not: it must not enqueue a re-resolution.
+func (s *service) serveHash(ctx context.Context, artID model.ArtworkID, ia *model.ItemArtwork, size int, square bool) (*Image, error) {
+	// Only this path can hand back a deleted entity's bytes; the others load their entity anyway.
+	if !entityExists(ctx, s.ds, artID) {
+		return nil, ErrUnavailable
+	}
+	art, err := s.ds.Artwork(ctx).GetImage(ia.Hash)
+	if err != nil {
+		if errors.Is(err, model.ErrNotFound) {
+			return s.dangling(ctx, artID)
+		}
+		return nil, err
+	}
+	img, err := s.serveSource(ctx, ia.Hash, ia.Hash, ia.UpdatedAt, size, square,
+		func() (io.ReadCloser, error) { return openOriginal(ia, art.Mime, s.store) })
+	if err != nil {
+		if errors.Is(err, context.Canceled) {
+			return nil, err
+		}
+		log.Warn(ctx, "Artwork: Could not serve image", "artID", artID, "size", size, err)
+		return s.dangling(ctx, artID)
+	}
+	return img, nil
+}
+
+// openOriginal enforces the mtime invariant: bytes are never served under a hash they no longer match.
+func openOriginal(ia *model.ItemArtwork, mime string, store *ImageStore) (io.ReadCloser, error) {
+	if isFileBacked(ia.Source) {
+		f, err := os.Open(ia.SourcePath)
+		if err != nil {
+			return nil, err
+		}
+		info, err := f.Stat()
+		if err != nil {
+			f.Close()
+			return nil, err
+		}
+		if ia.RefMtime != 0 && info.ModTime().UnixNano() != ia.RefMtime {
+			f.Close()
+			log.Debug("Artwork: Backing file changed since resolution", "path", ia.SourcePath,
+				"hash", ia.Hash, "resolvedMtime", ia.RefMtime, "currentMtime", info.ModTime().UnixNano())
+			return nil, errStaleSource
+		}
+		return f, nil
+	}
+	// Store-backed bytes still carry the source's mtime, to detect edits to embedded art.
+	if ia.SourcePath != "" && ia.RefMtime != 0 {
+		info, err := os.Stat(ia.SourcePath)
+		if err != nil {
+			return nil, err
+		}
+		if info.ModTime().UnixNano() != ia.RefMtime {
+			log.Debug("Artwork: Source file changed since resolution", "path", ia.SourcePath,
+				"hash", ia.Hash, "resolvedMtime", ia.RefMtime, "currentMtime", info.ModTime().UnixNano())
+			return nil, errStaleSource
+		}
+	}
+	return store.Open(ia.Hash, mime)
+}
+
+// provisional serves local bytes for an entity with no state row, enqueuing the worker but
+// never writing a state row itself.
+func (s *service) provisional(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
+	item := model.ArtworkQueueItem{ItemKind: artID.Kind.Prefix(), ItemID: artID.ID, ImageType: model.ImageTypePrimary}
+	res, err := newLocalResolver(s.ds, s.ffmpeg).resolve(ctx, item)
+	if err != nil {
+		return nil, err
+	}
+	s.enqueue(ctx, artID, model.ArtworkPriorityBump)
+	log.Debug(ctx, "Artwork: Provisional read-through, no state row yet", "artID", artID,
+		"source", res.source, "hit", res.reader != nil)
+	return s.serveResolution(ctx, res, size, square)
+}
+
+// serveResolution turns a local resolution's bytes into a servable Image (byte-hash only, no decode).
+func (s *service) serveResolution(ctx context.Context, res resolution, size int, square bool) (*Image, error) {
+	if res.reader == nil {
+		return nil, ErrUnavailable
+	}
+	defer res.reader.Close()
+	data, err := readCapped(res.reader)
+	if err != nil {
+		return nil, ErrUnavailable
+	}
+	hash, err := hashImage(bytes.NewReader(data))
+	if err != nil {
+		return nil, ErrUnavailable
+	}
+	// Keyed by the byte-hash, so the entry lines up with the worker's eventual store entry.
+	return s.serveSource(ctx, hash, hash, unixMtime(res.refMtime), size, square,
+		func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(data)), nil })
+}
+
+func (s *service) serveMediaFile(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
+	// The setting is not in the config fingerprint, so honor it at serve time: a direct mf- URL
+	// must fall back to disc/album instead of serving stale persisted embedded art.
+	if !conf.Server.EnableMediaFileCoverArt {
+		mf, err := s.ds.MediaFile(ctx).Get(artID.ID)
+		if err != nil {
+			return nil, err
+		}
+		return s.Get(ctx, mf.DiscCoverArtID(), size, square)
+	}
+	ia, err := s.ds.Artwork(ctx).GetItemArtwork(model.KindMediaFileArtwork, artID.ID, model.ImageTypePrimary)
+	switch {
+	case err == nil && ia.Hash != "":
+		return s.serveHash(ctx, artID, ia, size, square)
+	case err == nil:
+		// absent row: fall through
+	case errors.Is(err, model.ErrNotFound):
+		// no row: fall through
+	default:
+		return nil, err
+	}
+	noRow := errors.Is(err, model.ErrNotFound)
+
+	mf, err := s.ds.MediaFile(ctx).Get(artID.ID)
+	if err != nil {
+		return nil, err
+	}
+	if noRow && conf.Server.EnableMediaFileCoverArt && mf.HasCoverArt {
+		return s.provisionalEmbedded(ctx, artID, *mf, size, square)
+	}
+	// Mirror MediaFile.CoverArtID: a track defers to its disc art, which falls back to the album.
+	return s.Get(ctx, mf.DiscCoverArtID(), size, square)
+}
+
+// provisionalEmbedded serves a track's embedded art immediately, leaving the state row to the worker.
+func (s *service) provisionalEmbedded(ctx context.Context, artID model.ArtworkID, mf model.MediaFile, size int, square bool) (*Image, error) {
+	lib, err := loadLibraryView(ctx, s.ds, mf.LibraryID)
+	if err != nil {
+		return nil, err
+	}
+	res, ok := resolveEmbedded(ctx, lib, s.ffmpeg, mf.Path)
+	s.enqueue(ctx, artID, model.ArtworkPriorityBump)
+	if !ok {
+		// Eligible but unextractable: fall back the way CoverArtID does, not to a placeholder.
+		return s.Get(ctx, mf.DiscCoverArtID(), size, square)
+	}
+	return s.serveResolution(ctx, res, size, square)
+}
+
+// serveDisc reads disc art through with no state row and no enqueue, falling back to the album cover.
+func (s *service) serveDisc(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
+	dr, err := newDiscArtworkReader(ctx, s.ds, artID)
+	if err != nil {
+		return nil, err
+	}
+	// Single-disc albums run the chain too: a disc can carry art distinct from the album cover.
+	selectImage := func() (io.ReadCloser, string, error) {
+		funcs := dr.fromDiscArtPriority(ctx, s.ffmpeg, conf.Server.DiscArtPriority)
+		return selectImageReader(ctx, artID, funcs...)
+	}
+	albumArtID := model.ArtworkID{Kind: model.KindAlbumArtwork, ID: dr.album.ID}
+	// Disc art has no state row, hence no content hash: keying on id, album mtime and
+	// DiscArtPriority lets a warm cache answer without running the chain or touching the disk.
+	key := fmt.Sprintf("%s|%d|%s", artID.ID, dr.cacheTime().UnixNano(), conf.Server.DiscArtPriority)
+	img, err := s.serveSource(ctx, key, "", dr.cacheTime(), size, square,
+		func() (io.ReadCloser, error) { rc, _, err := selectImage(); return rc, err })
+	if err != nil {
+		if errors.Is(err, context.Canceled) {
+			return nil, err
+		}
+		return s.Get(ctx, albumArtID, size, square)
+	}
+	return img, nil
+}
+
+// dangling enqueues a re-resolution and reports unavailable, leaving the state row untouched.
+func (s *service) dangling(ctx context.Context, artID model.ArtworkID) (*Image, error) {
+	log.Debug(ctx, "Artwork: State row points at bytes we cannot serve, re-resolving", "artID", artID)
+	s.enqueue(ctx, artID, model.ArtworkPriorityScan)
+	return nil, ErrUnavailable
+}
+
+func (s *service) enqueue(ctx context.Context, artID model.ArtworkID, priority int) {
+	err := s.ds.ArtworkQueue(ctx).EnqueuePreservingBackoff(model.ArtworkQueueItem{
+		ItemKind:  artID.Kind.Prefix(),
+		ItemID:    artID.ID,
+		ImageType: model.ImageTypePrimary,
+		Priority:  priority,
+	})
+	if err != nil {
+		log.Warn(ctx, "Artwork: Could not enqueue re-resolution", "artID", artID, err)
+	}
+}
+
+func placeholderImage(kind model.Kind) *Image {
+	path := consts.PlaceholderAlbumArt
+	if kind == model.KindArtistArtwork {
+		path = consts.PlaceholderArtistArt
+	}
+	r, _ := resources.FS().Open(path)
+	return &Image{ReadCloser: r, Placeholder: true}
+}
+
+type coverArtIDGetter interface {
 	CoverArtID() model.ArtworkID
 }
 
-func (a *artwork) getArtworkId(ctx context.Context, id string) (model.ArtworkID, error) {
+// parseArtworkID accepts an artwork token or a raw entity id, resolving the latter to its CoverArtID.
+func (s *service) parseArtworkID(ctx context.Context, id string) (model.ArtworkID, error) {
 	if id == "" {
 		return model.ArtworkID{}, ErrUnavailable
 	}
-	artID, err := model.ParseArtworkID(id)
-	if err == nil {
+	if artID, err := model.ParseArtworkID(id); err == nil {
 		return artID, nil
 	}
-
-	log.Trace(ctx, "ArtworkID invalid. Trying to figure out kind based on the ID", "id", id)
-	entity, err := model.GetEntityByID(ctx, a.ds, id)
+	entity, err := model.GetEntityByID(ctx, s.ds, id)
 	if err != nil {
 		return model.ArtworkID{}, err
 	}
-	if e, ok := entity.(coverArtGetter); ok {
-		artID = e.CoverArtID()
+	if e, ok := entity.(coverArtIDGetter); ok {
+		return e.CoverArtID(), nil
 	}
-	switch e := entity.(type) {
-	case *model.Artist:
-		log.Trace(ctx, "ID is for an Artist", "id", id, "name", e.Name, "artist", e.Name)
-	case *model.Album:
-		log.Trace(ctx, "ID is for an Album", "id", id, "name", e.Name, "artist", e.AlbumArtist)
-	case *model.MediaFile:
-		log.Trace(ctx, "ID is for a MediaFile", "id", id, "title", e.Title, "album", e.Album)
-	case *model.Playlist:
-		log.Trace(ctx, "ID is for a Playlist", "id", id, "name", e.Name)
-	}
-	return artID, nil
+	return model.ArtworkID{}, model.ErrNotFound
 }
 
-func (a *artwork) getArtworkReader(ctx context.Context, artID model.ArtworkID, size int, square bool) (artworkReader, error) {
-	var artReader artworkReader
-	var err error
-	if size > 0 || square {
-		artReader, err = resizedFromOriginal(ctx, a, artID, size, square)
-	} else {
-		switch artID.Kind {
-		case model.KindArtistArtwork:
-			artReader, err = newArtistArtworkReader(ctx, a, artID, a.provider)
-		case model.KindAlbumArtwork:
-			artReader, err = newAlbumArtworkReader(ctx, a, artID, a.provider)
-		case model.KindMediaFileArtwork:
-			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
-		}
+func unixMtime(mtime int64) time.Time {
+	if mtime <= 0 {
+		return time.Time{}
 	}
-	return artReader, err
+	return time.Unix(0, mtime) // RefMtime is unix-nanoseconds
 }
diff --git a/core/artwork/artwork_internal_test.go b/core/artwork/artwork_internal_test.go
deleted file mode 100644
index 5bcd82f23..000000000
--- a/core/artwork/artwork_internal_test.go
+++ /dev/null
@@ -1,629 +0,0 @@
-package artwork
-
-import (
-	"context"
-	"errors"
-	"image"
-	"image/jpeg"
-	"image/png"
-	"io"
-	"os"
-	"path/filepath"
-	"time"
-
-	_ "github.com/gen2brain/webp"
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/conf/configtest"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/tests"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Artwork", func() {
-	var aw *artwork
-	var ds model.DataStore
-	var ffmpeg *tests.MockFFmpeg
-	var folderRepo *fakeFolderRepo
-	ctx := log.NewContext(context.TODO())
-	var alOnlyEmbed, alEmbedNotFound, alOnlyExternal, alExternalNotFound, alMultipleCovers, alSingleDisc model.Album
-	var arMultipleCovers model.Artist
-	var mfWithEmbed, mfAnotherWithEmbed, mfWithoutEmbed, mfCorruptedCover model.MediaFile
-
-	BeforeEach(func() {
-		DeferCleanup(configtest.SetupConfig())
-		conf.Server.ImageCacheSize = "0" // Disable cache
-		conf.Server.CoverArtPriority = "folder.*, cover.*, embedded , front.*"
-
-		folderRepo = &fakeFolderRepo{}
-		libRepo := &tests.MockLibraryRepo{}
-		repoRoot, _ := os.Getwd()
-		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
-		ds = &tests.MockDataStore{
-			MockedTranscoding: &tests.MockTranscodingRepo{},
-			MockedFolder:      folderRepo,
-			MockedLibrary:     libRepo,
-		}
-		// Paths use forward slashes because the scanner stores fs.FS-relative paths in the DB.
-		alOnlyEmbed = model.Album{ID: "222", Name: "Only embed", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}}
-		alEmbedNotFound = model.Album{ID: "333", Name: "Embed not found", EmbedArtPath: "tests/fixtures/NON_EXISTENT.mp3", FolderIDs: []string{"f1"}}
-		alOnlyExternal = model.Album{ID: "444", Name: "Only external", FolderIDs: []string{"f1"}, Discs: model.Discs{1: "", 2: ""}}
-		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",
-			Name:          "All options",
-			EmbedArtPath:  "tests/fixtures/artist/an-album/test.mp3",
-			FolderIDs:     []string{"f1"},
-			AlbumArtistID: "777",
-		}
-		mfWithEmbed = model.MediaFile{ID: "22", Path: "tests/fixtures/test.mp3", HasCoverArt: true, AlbumID: "222"}
-		mfAnotherWithEmbed = model.MediaFile{ID: "23", Path: "tests/fixtures/artist/an-album/test.mp3", HasCoverArt: true, AlbumID: "666"}
-		mfWithoutEmbed = model.MediaFile{ID: "44", Path: "tests/fixtures/test.ogg", AlbumID: "444"}
-		mfCorruptedCover = model.MediaFile{ID: "45", Path: "tests/fixtures/test.ogg", HasCoverArt: true, AlbumID: "444"}
-
-		cache := GetImageCache()
-		ffmpeg = tests.NewMockFFmpeg("content from ffmpeg")
-		aw = NewArtwork(ds, cache, ffmpeg, nil).(*artwork)
-	})
-
-	Describe("albumArtworkReader", func() {
-		Context("ID not found", func() {
-			It("returns ErrNotFound if album is not in the DB", func() {
-				_, err := newAlbumArtworkReader(ctx, aw, model.MustParseArtworkID("al-NOT-FOUND"), nil)
-				Expect(err).To(MatchError(model.ErrNotFound))
-			})
-		})
-		Context("Embed images", func() {
-			BeforeEach(func() {
-				folderRepo.result = nil
-				ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
-					alOnlyEmbed,
-					alEmbedNotFound,
-				})
-			})
-			It("returns embed cover", func() {
-				aw, err := newAlbumArtworkReader(ctx, aw, alOnlyEmbed.CoverArtID(), nil)
-				Expect(err).ToNot(HaveOccurred())
-				_, path, err := aw.Reader(ctx)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(path).To(Equal("tests/fixtures/artist/an-album/test.mp3"))
-			})
-			It("returns ErrUnavailable if embed path is not available", func() {
-				ffmpeg.Error = errors.New("not available")
-				aw, err := newAlbumArtworkReader(ctx, aw, alEmbedNotFound.CoverArtID(), nil)
-				Expect(err).ToNot(HaveOccurred())
-				_, _, err = aw.Reader(ctx)
-				Expect(err).To(MatchError(ErrUnavailable))
-			})
-		})
-		Context("External images", func() {
-			BeforeEach(func() {
-				folderRepo.result = []model.Folder{}
-				ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
-					alOnlyExternal,
-					alExternalNotFound,
-				})
-			})
-			It("returns external cover", func() {
-				folderRepo.result = []model.Folder{{
-					Path:       "tests/fixtures/artist/an-album",
-					ImageFiles: []string{"front.png"},
-				}}
-				aw, err := newAlbumArtworkReader(ctx, aw, alOnlyExternal.CoverArtID(), nil)
-				Expect(err).ToNot(HaveOccurred())
-				_, path, err := aw.Reader(ctx)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(path).To(Equal("tests/fixtures/artist/an-album/front.png"))
-			})
-			It("returns ErrUnavailable if external file is not available", func() {
-				folderRepo.result = []model.Folder{}
-				aw, err := newAlbumArtworkReader(ctx, aw, alExternalNotFound.CoverArtID(), nil)
-				Expect(err).ToNot(HaveOccurred())
-				_, _, err = aw.Reader(ctx)
-				Expect(err).To(MatchError(ErrUnavailable))
-			})
-		})
-		Context("Multiple covers", func() {
-			BeforeEach(func() {
-				folderRepo.result = []model.Folder{{
-					Path:       "tests/fixtures/artist/an-album",
-					ImageFiles: []string{"cover.jpg", "front.png", "artist.png"},
-				}}
-				ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
-					alMultipleCovers,
-				})
-			})
-			DescribeTable("CoverArtPriority",
-				func(priority string, expected string) {
-					conf.Server.CoverArtPriority = priority
-					aw, err := newAlbumArtworkReader(ctx, aw, alMultipleCovers.CoverArtID(), nil)
-					Expect(err).ToNot(HaveOccurred())
-					_, path, err := aw.Reader(ctx)
-					Expect(err).ToNot(HaveOccurred())
-					Expect(path).To(Equal(expected))
-				},
-				Entry(nil, " folder.* , cover.*,embedded,front.*", "tests/fixtures/artist/an-album/cover.jpg"),
-				Entry(nil, "front.* , cover.*, embedded ,folder.*", "tests/fixtures/artist/an-album/front.png"),
-				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{{
-					ID:          "f1",
-					LibraryPath: testFileLibPath(repoRoot),
-					Path:        "tests/fixtures/artist/an-album",
-					ImageFiles:  []string{"artist.png"},
-				}}
-				ds.Artist(ctx).(*tests.MockArtistRepo).SetData(model.Artists{
-					arMultipleCovers,
-				})
-				ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
-					alMultipleCovers,
-				})
-				ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-					mfAnotherWithEmbed,
-				})
-			})
-			DescribeTable("ArtistArtPriority",
-				func(priority string, expected string) {
-					conf.Server.ArtistArtPriority = priority
-					aw, err := newArtistArtworkReader(ctx, aw, arMultipleCovers.CoverArtID(), nil)
-					Expect(err).ToNot(HaveOccurred())
-					_, path, err := aw.Reader(ctx)
-					Expect(err).ToNot(HaveOccurred())
-					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"),
-			)
-		})
-	})
-	Describe("mediafileArtworkReader", func() {
-		Context("ID not found", func() {
-			It("returns ErrNotFound if mediafile is not in the DB", func() {
-				_, err := newMediafileArtworkReader(ctx, aw, model.MustParseArtworkID("mf-NOT-FOUND"))
-				Expect(err).To(MatchError(model.ErrNotFound))
-			})
-		})
-		Context("Embed images", func() {
-			BeforeEach(func() {
-				folderRepo.result = []model.Folder{{
-					Path:       "tests/fixtures/artist/an-album",
-					ImageFiles: []string{"front.png"},
-				}}
-				ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
-					alOnlyEmbed,
-					alOnlyExternal,
-					alSingleDisc,
-				})
-				ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-					mfWithEmbed,
-					mfWithoutEmbed,
-					mfCorruptedCover,
-				})
-			})
-			It("returns embed cover", func() {
-				aw, err := newMediafileArtworkReader(ctx, aw, mfWithEmbed.CoverArtID())
-				Expect(err).ToNot(HaveOccurred())
-				_, path, err := aw.Reader(ctx)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(path).To(Equal("tests/fixtures/test.mp3"))
-			})
-			It("returns embed cover if successfully extracted by ffmpeg", func() {
-				aw, err := newMediafileArtworkReader(ctx, aw, mfCorruptedCover.CoverArtID())
-				Expect(err).ToNot(HaveOccurred())
-				r, path, err := aw.Reader(ctx)
-				Expect(err).ToNot(HaveOccurred())
-				data, _ := io.ReadAll(r)
-				Expect(data).ToNot(BeEmpty())
-				Expect(path).To(Equal("tests/fixtures/test.ogg"))
-			})
-			It("returns album cover if cannot read embed artwork", func() {
-				// Force fromTag to fail
-				mfCorruptedCover.Path = "tests/fixtures/DOES_NOT_EXIST.ogg"
-				Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Put(&mfCorruptedCover)).To(Succeed())
-				// Simulate ffmpeg error
-				ffmpeg.Error = errors.New("not available")
-
-				aw, err := newMediafileArtworkReader(ctx, aw, mfCorruptedCover.CoverArtID())
-				Expect(err).ToNot(HaveOccurred())
-				_, path, err := aw.Reader(ctx)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(path).To(Equal("al-444_0"))
-			})
-			It("returns album cover if media file has no cover art", func() {
-				aw, err := newMediafileArtworkReader(ctx, aw, model.MustParseArtworkID("mf-"+mfWithoutEmbed.ID))
-				Expect(err).ToNot(HaveOccurred())
-				_, path, err := aw.Reader(ctx)
-				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{{
-				Path:       "tests/fixtures/artist/an-album",
-				ImageFiles: []string{"cover.jpg", "front.png"},
-			}}
-			ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
-				alMultipleCovers,
-			})
-		})
-		When("Square is false", func() {
-			It("returns PNG if original image is a PNG", func() {
-				conf.Server.CoverArtPriority = "front.png"
-				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 15, false)
-				Expect(err).ToNot(HaveOccurred())
-
-				img, format, err := image.Decode(r)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(format).To(Equal("png"))
-				Expect(img.Bounds().Size().X).To(Equal(15))
-				Expect(img.Bounds().Size().Y).To(Equal(15))
-			})
-			It("returns JPEG if original image is not a PNG", func() {
-				conf.Server.CoverArtPriority = "cover.jpg"
-				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 200, false)
-				Expect(err).ToNot(HaveOccurred())
-
-				img, format, err := image.Decode(r)
-				Expect(format).To(Equal("jpeg"))
-				Expect(err).ToNot(HaveOccurred())
-				Expect(img.Bounds().Size().X).To(Equal(200))
-				Expect(img.Bounds().Size().Y).To(Equal(200))
-			})
-		})
-		When("When square is true", func() {
-			var alCover model.Album
-
-			DescribeTable("resize",
-				func(srcFormat string, expectedFormat string, landscape bool, size int) {
-					coverFileName := "cover." + srcFormat
-					dirName := createImage(srcFormat, landscape, size)
-					alCover = model.Album{
-						ID:        "444",
-						Name:      "Only external",
-						FolderIDs: []string{"tmp"},
-					}
-					folderRepo.result = []model.Folder{{ImageFiles: []string{coverFileName}}}
-					rootLibRepo := &tests.MockLibraryRepo{}
-					rootLibRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(dirName)}})
-					ds.(*tests.MockDataStore).MockedLibrary = rootLibRepo
-					ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{
-						alCover,
-					})
-
-					conf.Server.CoverArtPriority = coverFileName
-					r, _, err := aw.Get(context.Background(), alCover.CoverArtID(), size, true)
-					Expect(err).ToNot(HaveOccurred())
-
-					img, format, err := image.Decode(r)
-					Expect(err).ToNot(HaveOccurred())
-					Expect(format).To(Equal(expectedFormat))
-					Expect(img.Bounds().Size().X).To(Equal(size))
-					Expect(img.Bounds().Size().Y).To(Equal(size))
-				},
-				Entry("portrait png image", "png", "png", false, 200),
-				Entry("landscape png image", "png", "png", true, 200),
-				Entry("portrait jpg image", "jpg", "png", false, 200),
-				Entry("landscape jpg image", "jpg", "png", true, 200),
-			)
-		})
-		When("EnableWebPEncoding is true and square is false", func() {
-			BeforeEach(func() {
-				conf.Server.EnableWebPEncoding = true
-			})
-			It("returns WebP even if original image is a PNG", func() {
-				conf.Server.CoverArtPriority = "front.png"
-				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 15, false)
-				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"
-				// front.png is 16x16, requesting 99999 should return at original size
-				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 99999, false)
-				Expect(err).ToNot(HaveOccurred())
-
-				img, _, err := image.Decode(r)
-				Expect(err).ToNot(HaveOccurred())
-				// Should be clamped to original size (16), not 99999
-				Expect(img.Bounds().Size().X).To(Equal(16))
-				Expect(img.Bounds().Size().Y).To(Equal(16))
-			})
-
-			It("clamps square size to original dimensions", func() {
-				conf.Server.CoverArtPriority = "front.png"
-				// front.png is 16x16, requesting 99999 with square should return 16x16 square
-				r, _, err := aw.Get(context.Background(), alMultipleCovers.CoverArtID(), 99999, true)
-				Expect(err).ToNot(HaveOccurred())
-
-				img, _, err := image.Decode(r)
-				Expect(err).ToNot(HaveOccurred())
-				// Should be clamped to original size (16), not 99999
-				Expect(img.Bounds().Size().X).To(Equal(16))
-				Expect(img.Bounds().Size().Y).To(Equal(16))
-			})
-		})
-	})
-})
-
-func createImage(format string, landscape bool, size int) string {
-	var img image.Image
-
-	if landscape {
-		img = image.NewRGBA(image.Rect(0, 0, size, size/2))
-	} else {
-		img = image.NewRGBA(image.Rect(0, 0, size/2, size))
-	}
-
-	tmpDir := GinkgoT().TempDir()
-	f, _ := os.Create(filepath.Join(tmpDir, "cover."+format))
-	defer f.Close()
-	switch format {
-	case "png":
-		_ = png.Encode(f, img)
-	case "jpg":
-		_ = jpeg.Encode(f, img, &jpeg.Options{Quality: 75})
-	}
-
-	return tmpDir
-}
diff --git a/core/artwork/artwork_suite_test.go b/core/artwork/artwork_suite_test.go
index d42d7f3e4..1ea82b7fa 100644
--- a/core/artwork/artwork_suite_test.go
+++ b/core/artwork/artwork_suite_test.go
@@ -11,13 +11,26 @@ import (
 
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/metadata"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
+	"go.uber.org/goleak"
 )
 
 func TestArtwork(t *testing.T) {
+	// Runs unconditionally: the two leaks below are pre-existing and out of this
+	// package's control, so they're ignored by exact top-function instead.
+	defer goleak.VerifyNone(t,
+		goleak.IgnoreTopFunction("github.com/onsi/ginkgo/v2/internal/interrupt_handler.(*InterruptHandler).registerForInterrupts.func2"),
+		// notify's own init() starts a singleton tree the moment it's imported (via
+		// core/storage/local or plugins); recursive on darwin, nonrecursive on linux.
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*recursiveTree).dispatch"),
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*nonrecursiveTree).dispatch"),
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*nonrecursiveTree).internal"),
+	)
+
 	tests.Init(t, false)
 	log.SetLevel(log.LevelFatal)
 	RegisterFailHandler(Fail)
@@ -25,7 +38,6 @@ func TestArtwork(t *testing.T) {
 }
 
 // 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 }
@@ -69,3 +81,37 @@ func (s *osDirStorage) FS() (storage.MusicFS, error) {
 	}
 	return osDirFS{os.DirFS(s.root)}, nil
 }
+
+// fakeFolderRepo covers the three FolderRepository methods the resolvers reach for. The zero value
+// answers as an unremarkable library does; the fields drive the album-root lookup and its failures.
+type fakeFolderRepo struct {
+	model.FolderRepository
+	result       []model.Folder
+	err          error
+	parentResult *model.Folder
+	getErr       error
+	getCallCount int
+	// hasOtherAudio is returned by HasAudioOutsideFolders (the album-root check).
+	// False means the parent qualifies as an album root.
+	hasOtherAudio bool
+	otherAudioErr error
+}
+
+func (f *fakeFolderRepo) GetAll(...model.QueryOptions) ([]model.Folder, error) {
+	return f.result, f.err
+}
+
+func (f *fakeFolderRepo) HasAudioOutsideFolders(model.Folder, []string) (bool, error) {
+	return f.hasOtherAudio, f.otherAudioErr
+}
+
+func (f *fakeFolderRepo) Get(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
+}
diff --git a/core/artwork/artwork_test.go b/core/artwork/artwork_test.go
index adddd0dc3..c6b848101 100644
--- a/core/artwork/artwork_test.go
+++ b/core/artwork/artwork_test.go
@@ -1,57 +1,523 @@
-package artwork_test
+package artwork
 
 import (
+	"bytes"
 	"context"
+	"image"
 	"io"
+	"os"
+	"path/filepath"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/resources"
 	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/cache"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
 var _ = Describe("Artwork", func() {
-	var aw artwork.Artwork
-	var ds model.DataStore
-	var ffmpeg *tests.MockFFmpeg
+	var (
+		ctx        context.Context
+		ds         *tests.MockDataStore
+		artRepo    *tests.MockArtworkRepo
+		queueRepo  *tests.MockArtworkQueueRepo
+		albumRepo  *tests.MockAlbumRepo
+		mfRepo     *tests.MockMediaFileRepo
+		folderRepo *fakeFolderRepo
+		libRepo    *tests.MockLibraryRepo
+		ffm        *tests.MockFFmpeg
+		store      *ImageStore
+		imgCache   cache.FileCache
+		svc        Artwork
+		repoRoot   string
+		coverBytes []byte
+		seedEntity func(kind, id string)
+	)
+
+	primaryKey := func(kind, id string) string { return kind + "|" + id + "|" + model.ImageTypePrimary }
+
+	seedFoundStore := func(kind, id string, imgBytes []byte) string {
+		hash, err := hashImage(bytes.NewReader(imgBytes))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(store.Write(hash, "image/jpeg", bytes.NewReader(imgBytes))).To(Succeed())
+		Expect(artRepo.PutImage(&model.Artwork{Hash: hash, Mime: "image/jpeg"})).To(Succeed())
+		Expect(artRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: kind, ItemID: id, Hash: hash, Source: "external"})).To(Succeed())
+		seedEntity(kind, id)
+		return hash
+	}
+
+	// Without its owning entity, a state row is not served at all.
+	seedEntity = func(kind, id string) {
+		GinkgoHelper()
+		switch kind {
+		case "al":
+			Expect(albumRepo.Put(&model.Album{ID: id, Name: "Album"})).To(Succeed())
+		case "mf":
+			Expect(mfRepo.Put(&model.MediaFile{ID: id})).To(Succeed())
+		}
+	}
+
+	readAll := func(img *Image) []byte {
+		GinkgoHelper()
+		defer img.Close()
+		data, err := io.ReadAll(img)
+		Expect(err).ToNot(HaveOccurred())
+		return data
+	}
 
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
-		conf.Server.ImageCacheSize = "0" // Disable cache
-		cache := artwork.GetImageCache()
-		ffmpeg = tests.NewMockFFmpeg("content from ffmpeg")
-		aw = artwork.NewArtwork(ds, cache, ffmpeg, nil)
+		ctx = context.Background()
+		var err error
+		repoRoot, err = os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		coverBytes, err = os.ReadFile(filepath.Join(repoRoot, "tests/fixtures/artist/an-album/cover.jpg"))
+		Expect(err).ToNot(HaveOccurred())
+
+		conf.Server.EnableWebPEncoding = false
+		conf.Server.CoverArtQuality = 75
+		conf.Server.CoverArtPriority = "cover.*"
+		conf.Server.DiscArtPriority = "cover.*"
+		conf.Server.CacheFolder = conf.NewDir(GinkgoT().TempDir())
+
+		artRepo = tests.CreateMockArtworkRepo()
+		queueRepo = tests.CreateMockArtworkQueueRepo()
+		albumRepo = tests.CreateMockAlbumRepo()
+		mfRepo = tests.CreateMockMediaFileRepo()
+		folderRepo = &fakeFolderRepo{}
+		libRepo = &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		ds = &tests.MockDataStore{
+			MockedArtwork:      artRepo,
+			MockedArtworkQueue: queueRepo,
+			MockedAlbum:        albumRepo,
+			MockedMediaFile:    mfRepo,
+			MockedFolder:       folderRepo,
+			MockedLibrary:      libRepo,
+		}
+		ffm = tests.NewMockFFmpeg("")
+		store = NewImageStore(GinkgoT().TempDir())
+		imgCache = cache.NewFileCache("ServingTest", "100MB", "images", 0,
+			func(ctx context.Context, arg cache.Item) (io.Reader, error) {
+				return arg.(artworkReader).Reader(ctx)
+			})
+		Eventually(func() bool { return imgCache.Available(ctx) }).Should(BeTrue())
+		svc = NewArtwork(ds, imgCache, store, ffm)
 	})
 
-	Context("GetOrPlaceholder", func() {
-		Context("Empty ID", func() {
-			It("returns placeholder if album is not in the DB", func() {
-				r, _, err := aw.GetOrPlaceholder(context.Background(), "", 0, false)
-				Expect(err).ToNot(HaveOccurred())
+	Describe("found state", func() {
+		It("serves a store-backed found image sized (cache miss resizes, second call is a cache hit)", func() {
+			seedFoundStore("al", "al1", coverBytes)
 
-				ph, err := resources.FS().Open(consts.PlaceholderAlbumArt)
-				Expect(err).ToNot(HaveOccurred())
-				phBytes, err := io.ReadAll(ph)
-				Expect(err).ToNot(HaveOccurred())
+			img, err := svc.Get(ctx, model.MustParseArtworkID("al-al1"), 100, false)
+			Expect(err).ToNot(HaveOccurred())
+			// A resized response versions its ETag with the encode settings, not the pixel hash.
+			Expect(img.ETag).To(Equal(representationTag(img.Hash, 100, false)))
+			Expect(img.ETag).ToNot(Equal(img.Hash))
+			resized := readAll(img)
+			cfg, _, err := image.DecodeConfig(bytes.NewReader(resized))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(cfg.Width).To(Equal(100))
 
-				result, err := io.ReadAll(r)
-				Expect(err).ToNot(HaveOccurred())
+			// Deleting the store file proves the warm entry serves without touching the original.
+			hash, _ := hashImage(bytes.NewReader(coverBytes))
+			Expect(os.Remove(store.path(hash, "image/jpeg"))).To(Succeed())
+			Eventually(func(g Gomega) {
+				img2, err := svc.Get(ctx, model.MustParseArtworkID("al-al1"), 100, false)
+				g.Expect(err).ToNot(HaveOccurred())
+				g.Expect(readAll(img2)).To(Equal(resized))
+			}).Should(Succeed())
+		})
 
-				Expect(result).To(Equal(phBytes))
-			})
+		It("treats a negative size as a full-size request, not a giant resize", func() {
+			seedFoundStore("al", "alneg", coverBytes)
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("al-alneg"), -2000000000, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes), "original bytes, no resize (would OOM)")
+		})
+
+		It("streams a file-backed found image at full size", func() {
+			dir := GinkgoT().TempDir()
+			imgPath := filepath.Join(dir, "cover.jpg")
+			Expect(os.WriteFile(imgPath, coverBytes, 0600)).To(Succeed())
+			mtime := fileMtime(imgPath)
+			Expect(artRepo.PutImage(&model.Artwork{Hash: "aaaaaaaaaaaaaaaa", Mime: "image/jpeg"})).To(Succeed())
+			seedEntity("al", "al2")
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al2", Hash: "aaaaaaaaaaaaaaaa",
+				Source: "folder", SourcePath: imgPath, RefMtime: mtime,
+			})).To(Succeed())
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("al-al2"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes))
+		})
+
+		It("treats a full-size mtime mismatch as dangling: unavailable, re-enqueued at Scan, state untouched", func() {
+			dir := GinkgoT().TempDir()
+			imgPath := filepath.Join(dir, "cover.jpg")
+			Expect(os.WriteFile(imgPath, coverBytes, 0600)).To(Succeed())
+			Expect(artRepo.PutImage(&model.Artwork{Hash: "bbbbbbbbbbbbbbbb", Mime: "image/jpeg"})).To(Succeed())
+			seedEntity("al", "al3")
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al3", Hash: "bbbbbbbbbbbbbbbb",
+				Source: "folder", SourcePath: imgPath, RefMtime: fileMtime(imgPath) + 999,
+			})).To(Succeed())
+
+			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al3"), 0, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+			Expect(queueRepo.Data[primaryKey("al", "al3")].Priority).To(Equal(model.ArtworkPriorityScan))
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Hash).To(Equal("bbbbbbbbbbbbbbbb"))
+		})
+
+		It("enforces the mtime rule on the sized (loader) path too", func() {
+			dir := GinkgoT().TempDir()
+			imgPath := filepath.Join(dir, "cover.jpg")
+			Expect(os.WriteFile(imgPath, coverBytes, 0600)).To(Succeed())
+			Expect(artRepo.PutImage(&model.Artwork{Hash: "cccccccccccccccc", Mime: "image/jpeg"})).To(Succeed())
+			seedEntity("al", "al3b")
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al3b", Hash: "cccccccccccccccc",
+				Source: "folder", SourcePath: imgPath, RefMtime: fileMtime(imgPath) + 999,
+			})).To(Succeed())
+
+			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al3b"), 100, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+			Expect(queueRepo.Data[primaryKey("al", "al3b")].Priority).To(Equal(model.ArtworkPriorityScan))
+		})
+
+		// State rows outlive a deleted entity until the next prune.
+		It("refuses to serve a found row whose entity is gone", func() {
+			hash := seedFoundStore("al", "alzz", coverBytes)
+			Expect(hash).ToNot(BeEmpty())
+			albumRepo.SetData(model.Albums{}) // the album is deleted; its artwork row survives
+
+			_, err := svc.Get(ctx, model.MustParseArtworkID("al-alzz"), 0, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+		})
+
+		It("does not re-enqueue a recently-attempted absent state", func() {
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al4", AttemptedAt: time.Now(),
+			})).To(Succeed())
+
+			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al4"), 0, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+			Expect(queueRepo.Data).To(BeEmpty())
+		})
+
+		It("promotes a stale absent state at Bump priority on view", func() {
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al4b", AttemptedAt: time.Now().Add(-2 * requestRecheckAge),
+			})).To(Succeed())
+
+			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al4b"), 0, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+			Expect(queueRepo.Data[primaryKey("al", "al4b")].Priority).To(Equal(model.ArtworkPriorityBump))
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al4b", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Hash).To(BeEmpty())
 		})
 	})
-	Context("Get", func() {
-		Context("Empty ID", func() {
-			It("returns an ErrUnavailable error", func() {
-				_, _, err := aw.Get(context.Background(), model.ArtworkID{}, 0, false)
-				Expect(err).To(MatchError(artwork.ErrUnavailable))
-			})
+
+	Describe("provisional read-through", func() {
+		It("serves local folder art, enqueues a Bump, and writes no state row", func() {
+			folderRepo.result = []model.Folder{{Path: "tests/fixtures/artist/an-album", ImageFiles: []string{"cover.jpg"}}}
+			albumRepo.SetData(model.Albums{{ID: "al5", Name: "Album", FolderIDs: []string{"f1"}}})
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("al-al5"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes))
+
+			Expect(queueRepo.Data[primaryKey("al", "al5")].Priority).To(Equal(model.ArtworkPriorityBump))
+			_, err = artRepo.GetItemArtwork(model.KindAlbumArtwork, "al5", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
+		It("returns ErrUnavailable and enqueues a Bump when nothing local resolves", func() {
+			folderRepo.result = nil
+			albumRepo.SetData(model.Albums{{ID: "al6", Name: "Album"}})
+
+			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al6"), 0, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+			Expect(queueRepo.Data[primaryKey("al", "al6")].Priority).To(Equal(model.ArtworkPriorityBump))
+			_, err = artRepo.GetItemArtwork(model.KindAlbumArtwork, "al6", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+	})
+
+	Describe("media file", func() {
+		It("serves a track's own found art", func() {
+			seedFoundStore("mf", "mf1", coverBytes)
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf1"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes))
+		})
+
+		It("ignores a resolved mf row and delegates to the album when per-track art is disabled", func() {
+			conf.Server.EnableMediaFileCoverArt = false
+			seedFoundStore("mf", "mf7", []byte("stale embedded track art"))
+			seedFoundStore("al", "albz", coverBytes)
+			mfRepo.SetData(model.MediaFiles{{ID: "mf7", AlbumID: "albz"}})
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf7"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes), "album art, not the persisted embedded art")
+		})
+
+		It("delegates to the album when the track's state is absent", func() {
+			seedFoundStore("al", "albm", coverBytes)
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: "mf2"})).To(Succeed())
+			mfRepo.SetData(model.MediaFiles{{ID: "mf2", AlbumID: "albm"}})
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf2"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes))
+			_, mfEnq := queueRepo.Data[primaryKey("mf", "mf2")]
+			Expect(mfEnq).To(BeFalse())
+		})
+
+		It("delegates to the album (no enqueue) when the track is not embedded-eligible", func() {
+			conf.Server.EnableMediaFileCoverArt = true
+			seedFoundStore("al", "albn", coverBytes)
+			mfRepo.SetData(model.MediaFiles{{ID: "mf3", AlbumID: "albn", HasCoverArt: false}})
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf3"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes))
+			_, mfEnq := queueRepo.Data[primaryKey("mf", "mf3")]
+			Expect(mfEnq).To(BeFalse())
+		})
+
+		It("extracts embedded art provisionally and enqueues the track when eligible", func() {
+			conf.Server.EnableMediaFileCoverArt = true
+			mfRepo.SetData(model.MediaFiles{{
+				ID: "mf4", AlbumID: "albo", HasCoverArt: true,
+				Path: "tests/fixtures/artist/an-album/test.mp3", LibraryID: 0,
+			}})
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf4"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(len(readAll(img))).To(BeNumerically(">", 0))
+			Expect(queueRepo.Data[primaryKey("mf", "mf4")].Priority).To(Equal(model.ArtworkPriorityBump))
+			_, err = artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mf4", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
+		It("delegates a multi-disc track to its disc art, not straight to the album", func() {
+			folderRepo.result = []model.Folder{{Path: "tests/fixtures/artist/an-album", ImageFiles: []string{"cover.jpg"}}}
+			albumRepo.SetData(model.Albums{{ID: "aldd", Name: "Album", FolderIDs: []string{"f1"}, Discs: model.Discs{1: "One", 2: "Two"}}})
+			seedFoundStore("al", "aldd", []byte("album-art-distinct")) // album's own found art differs
+			mfRepo.SetData(model.MediaFiles{{ID: "mf5", AlbumID: "aldd", DiscNumber: 1, HasCoverArt: false}})
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf5"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			// The disc-folder image, not the album's own art: proof it routed through serveDisc.
+			Expect(readAll(img)).To(Equal(coverBytes))
+		})
+
+		It("falls back to the album when an eligible track's embedded art will not extract", func() {
+			conf.Server.EnableMediaFileCoverArt = true
+			// HasCoverArt is set, but the file is not audio, so nothing extracts.
+			mfRepo.SetData(model.MediaFiles{{
+				ID: "mfbad", AlbumID: "albad", LibraryID: 0, HasCoverArt: true,
+				Path: "tests/fixtures/artist/an-album/front.png",
+			}})
+			albumRepo.SetData(model.Albums{{ID: "albad", Name: "Album"}})
+			seedFoundStore("al", "albad", coverBytes)
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mfbad"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes), "a placeholder here would be worse than the album cover")
+		})
+
+		It("routes a single-disc track through disc resolution too", func() {
+			// DiscArtPriority applies to single-disc albums too, over the album's own found art.
+			folderRepo.result = []model.Folder{{Path: "tests/fixtures/artist/an-album", ImageFiles: []string{"cover.jpg"}}}
+			albumRepo.SetData(model.Albums{{ID: "alsd", Name: "Album", FolderIDs: []string{"f1"}, Discs: model.Discs{1: ""}}})
+			seedFoundStore("al", "alsd", []byte("album-art-distinct"))
+			mfRepo.SetData(model.MediaFiles{{ID: "mf6", AlbumID: "alsd", DiscNumber: 1, HasCoverArt: false}})
+
+			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf6"), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes))
+		})
+	})
+
+	Describe("disc", func() {
+		It("serves a local disc-folder image", func() {
+			folderRepo.result = []model.Folder{{Path: "tests/fixtures/artist/an-album", ImageFiles: []string{"cover.jpg"}}}
+			albumRepo.SetData(model.Albums{{ID: "aldc", Name: "Album", FolderIDs: []string{"f1"}}})
+
+			img, err := svc.Get(ctx, model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID("aldc", 1), nil), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes))
+		})
+
+		// The resize cache keys on id + album mtime, not on the bytes, so dropping the source
+		// between the two requests is what shows a warm hit never touches the filesystem.
+		It("serves a sized disc image from cache without re-reading the source", func() {
+			folderRepo.result = []model.Folder{{Path: "tests/fixtures/artist/an-album", ImageFiles: []string{"cover.jpg"}}}
+			albumRepo.SetData(model.Albums{{ID: "aldc3", Name: "Album", FolderIDs: []string{"f1"}}})
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID("aldc3", 1), nil)
+
+			first, err := svc.Get(ctx, discID, 64, false)
+			Expect(err).ToNot(HaveOccurred())
+			warmed := readAll(first)
+			Expect(warmed).ToNot(BeEmpty())
+
+			folderRepo.result = nil
+
+			second, err := svc.Get(ctx, discID, 64, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(second)).To(Equal(warmed), "a warm sized request must not touch the source")
+		})
+
+		// A disc image can change without the album row changing, so the key folds in ImagesUpdatedAt.
+		It("invalidates the cached image when the folder's images change", func() {
+			folderRepo.result = []model.Folder{{
+				Path: "tests/fixtures/artist/an-album", ImageFiles: []string{"cover.jpg"},
+				ImagesUpdatedAt: time.Now().Add(-time.Hour),
+			}}
+			albumRepo.SetData(model.Albums{{ID: "aldc4", Name: "Album", FolderIDs: []string{"f1"}}})
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID("aldc4", 1), nil)
+
+			first, err := svc.Get(ctx, discID, 64, false)
+			Expect(err).ToNot(HaveOccurred())
+			firstKey := first.ETag
+			readAll(first)
+
+			folderRepo.result[0].ImagesUpdatedAt = time.Now()
+			second, err := svc.Get(ctx, discID, 64, false)
+			Expect(err).ToNot(HaveOccurred())
+			readAll(second)
+			Expect(second.ETag).ToNot(Equal(firstKey), "a replaced image must not keep the old cache entry")
+		})
+
+		// Disc art has no content hash, so without an explicit validator every ETag would be empty.
+		It("gives a full-size disc image a validator that tracks the source", func() {
+			folderRepo.result = []model.Folder{{
+				Path: "tests/fixtures/artist/an-album", ImageFiles: []string{"cover.jpg"},
+				ImagesUpdatedAt: time.Now().Add(-time.Hour),
+			}}
+			albumRepo.SetData(model.Albums{{ID: "aldc5", Name: "Album", FolderIDs: []string{"f1"}}})
+			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID("aldc5", 1), nil)
+
+			first, err := svc.Get(ctx, discID, 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			readAll(first)
+			Expect(first.ETag).ToNot(BeEmpty())
+
+			folderRepo.result[0].ImagesUpdatedAt = time.Now()
+			second, err := svc.Get(ctx, discID, 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			readAll(second)
+			Expect(second.ETag).ToNot(Equal(first.ETag), "a replaced image must not revalidate as unchanged")
+		})
+
+		It("falls back to album art when no disc image matches", func() {
+			folderRepo.result = nil
+			albumRepo.SetData(model.Albums{{ID: "aldc2", Name: "Album"}})
+			seedFoundStore("al", "aldc2", coverBytes)
+
+			img, err := svc.Get(ctx, model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID("aldc2", 1), nil), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(readAll(img)).To(Equal(coverBytes))
+		})
+	})
+
+	Describe("GetOrPlaceholder", func() {
+		It("accepts a raw entity id and serves its cover art", func() {
+			albumRepo.SetData(model.Albums{{ID: "rawal", Name: "Album"}})
+			seedFoundStore("al", "rawal", coverBytes)
+
+			img, err := svc.GetOrPlaceholder(ctx, "rawal", 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(img.Placeholder).To(BeFalse())
+			Expect(readAll(img)).To(Equal(coverBytes))
+		})
+
+		It("falls back to the album placeholder ignoring size and square", func() {
+			img, err := svc.GetOrPlaceholder(ctx, "", 300, true)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(img.Placeholder).To(BeTrue())
+			Expect(img.Hash).To(BeEmpty())
+			Expect(img.LastUpdated).To(BeZero())
+
+			ph, err := resources.FS().Open(consts.PlaceholderAlbumArt)
+			Expect(err).ToNot(HaveOccurred())
+			phBytes, _ := io.ReadAll(ph)
+			Expect(readAll(img)).To(Equal(phBytes))
+		})
+
+		It("falls back to the artist placeholder for an absent artist", func() {
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "arph"})).To(Succeed())
+
+			img, err := svc.GetOrPlaceholder(ctx, "ar-arph", 300, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(img.Placeholder).To(BeTrue())
+
+			ph, err := resources.FS().Open(consts.PlaceholderArtistArt)
+			Expect(err).ToNot(HaveOccurred())
+			phBytes, _ := io.ReadAll(ph)
+			Expect(readAll(img)).To(Equal(phBytes))
+		})
+
+		// "No art" and "no such entity" are different answers: clients 404 only on the latter.
+		It("reports not-found rather than a placeholder for an id with no entity", func() {
+			_, err := svc.GetOrPlaceholder(ctx, "al-nosuchalbum", 0, false)
+			Expect(err).To(MatchError(model.ErrNotFound))
+
+			_, err = svc.GetOrPlaceholder(ctx, "nosuchrawid", 0, false)
+			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 	})
 })
+
+func fileMtime(path string) int64 {
+	GinkgoHelper()
+	info, err := os.Stat(path)
+	Expect(err).ToNot(HaveOccurred())
+	return info.ModTime().UnixNano()
+}
+
+var _ = Describe("EntityExists", func() {
+	var ctx context.Context
+	var ds *tests.MockDataStore
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		albumRepo := tests.CreateMockAlbumRepo()
+		albumRepo.SetData(model.Albums{{ID: "al1"}})
+		artistRepo := tests.CreateMockArtistRepo()
+		artistRepo.SetData(model.Artists{{ID: "ar1"}})
+		radioRepo := tests.CreateMockedRadioRepo()
+		Expect(radioRepo.Put(&model.Radio{ID: "ra1", Name: "R"})).To(Succeed())
+		ds = &tests.MockDataStore{MockedAlbum: albumRepo, MockedArtist: artistRepo, MockedRadio: radioRepo}
+	})
+
+	DescribeTable("reports whether the owning entity is still there",
+		func(id string, expected bool) {
+			Expect(entityExists(ctx, ds, model.MustParseArtworkID(id))).To(Equal(expected))
+		},
+		Entry("existing album", "al-al1", true),
+		Entry("deleted album", "al-gone", false),
+		Entry("existing artist", "ar-ar1", true),
+		Entry("deleted artist", "ar-gone", false),
+		Entry("existing radio", "ra-ra1", true),
+		Entry("deleted radio", "ra-gone", false),
+		// Disc art has no entity of its own; it stands or falls with its album.
+		Entry("disc of an existing album", "dc-al1:1", true),
+		Entry("disc of a deleted album", "dc-gone:1", false),
+		Entry("malformed disc id", "dc-nodiscnum", false),
+	)
+})
diff --git a/core/artwork/benchmark_e2e_test.go b/core/artwork/benchmark_e2e_test.go
deleted file mode 100644
index bf3d435a8..000000000
--- a/core/artwork/benchmark_e2e_test.go
+++ /dev/null
@@ -1,189 +0,0 @@
-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 = conf.NewDir(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 range n {
-						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()
-				}
-			})
-		}
-	}
-}
diff --git a/core/artwork/benchmark_helpers_test.go b/core/artwork/benchmark_helpers_test.go
index 0076506f3..f3201d412 100644
--- a/core/artwork/benchmark_helpers_test.go
+++ b/core/artwork/benchmark_helpers_test.go
@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"image"
 	"image/color"
+	"image/draw"
 	"image/jpeg"
 	"image/png"
 	"testing"
@@ -45,3 +46,11 @@ func generateGradientImage(width, height int) *image.RGBA {
 	}
 	return img
 }
+
+// gradientNRGBA mirrors generateGradientImage in the type makeThumbnail hands the encoders.
+func gradientNRGBA(size int) *image.NRGBA {
+	src := generateGradientImage(size, size)
+	dst := image.NewNRGBA(src.Bounds())
+	draw.Draw(dst, dst.Bounds(), src, src.Bounds().Min, draw.Src)
+	return dst
+}
diff --git a/core/artwork/blurhash/blurhash.go b/core/artwork/blurhash/blurhash.go
new file mode 100644
index 000000000..ca5bf7026
--- /dev/null
+++ b/core/artwork/blurhash/blurhash.go
@@ -0,0 +1,191 @@
+// Package blurhash implements the blurhash encoding (https://github.com/woltapp/blurhash),
+// parameterized to match Jellyfin so clients see equivalent hashes.
+package blurhash
+
+import (
+	"errors"
+	"image"
+	"image/draw"
+	"math"
+	"strings"
+	"sync"
+
+	xdraw "golang.org/x/image/draw"
+)
+
+const alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz#$%*+,-.:;=?@[]^_{|}~"
+
+// maxInputSize: larger inputs are slower with no visible difference in the result.
+const maxInputSize = 128
+
+// components picks x/y component counts targeting ~16 near-square tiles.
+func components(width, height int) (int, int) {
+	xf := math.Sqrt(16.0 * float64(width) / float64(height))
+	yf := xf * float64(height) / float64(width)
+	return min(int(xf)+1, 9), min(int(yf)+1, 9)
+}
+
+// Encode returns the blurhash of img, deriving the component counts from its aspect ratio.
+func Encode(img image.Image) (string, error) {
+	if img.Bounds().Dx() == 0 || img.Bounds().Dy() == 0 {
+		return "", errors.New("blurhash: empty image")
+	}
+	// Pre-downscale: its rounding can flip a component count, and the hash is a client cache key.
+	xComp, yComp := components(img.Bounds().Dx(), img.Bounds().Dy())
+	src := pixelsOf(downscale(img))
+	w, h := src.w, src.h
+
+	cosX := make([][]float64, xComp)
+	for i := range cosX {
+		cosX[i] = make([]float64, w)
+		for x := range cosX[i] {
+			cosX[i][x] = math.Cos(math.Pi * float64(i) * float64(x) / float64(w))
+		}
+	}
+	cosY := make([][]float64, yComp)
+	for j := range cosY {
+		cosY[j] = make([]float64, h)
+		for y := range cosY[j] {
+			cosY[j][y] = math.Cos(math.Pi * float64(j) * float64(y) / float64(h))
+		}
+	}
+
+	lin := srgbToLinearTable()
+	factors := make([][3]float64, xComp*yComp)
+	for y := range h {
+		row := src.pix[y*src.stride:]
+		for x := range w {
+			p := x * 4
+			r, g, b := row[p], row[p+1], row[p+2]
+			if src.straight {
+				r, g, b = premultiply(r, g, b, row[p+3])
+			}
+			lr, lg, lb := lin[r], lin[g], lin[b]
+			for j := range yComp {
+				for i := range xComp {
+					basis := cosX[i][x] * cosY[j][y]
+					f := &factors[j*xComp+i]
+					f[0] += basis * lr
+					f[1] += basis * lg
+					f[2] += basis * lb
+				}
+			}
+		}
+	}
+	for idx := range factors {
+		norm := 2.0
+		if idx == 0 {
+			norm = 1.0
+		}
+		scale := norm / float64(w*h)
+		factors[idx][0] *= scale
+		factors[idx][1] *= scale
+		factors[idx][2] *= scale
+	}
+
+	var sb strings.Builder
+	sb.WriteString(encode83((xComp-1)+(yComp-1)*9, 1))
+
+	// Derived counts are at least 1x9, so there is always at least one AC factor.
+	ac := factors[1:]
+	actualMax := 0.0
+	for _, f := range ac {
+		actualMax = max(actualMax, math.Abs(f[0]), math.Abs(f[1]), math.Abs(f[2]))
+	}
+	quantMax := int(max(0, min(82, math.Floor(actualMax*166-0.5))))
+	maxVal := float64(quantMax+1) / 166
+	sb.WriteString(encode83(quantMax, 1))
+
+	dc := factors[0]
+	sb.WriteString(encode83(linearToSRGB(dc[0])<<16|linearToSRGB(dc[1])<<8|linearToSRGB(dc[2]), 4))
+	for _, f := range ac {
+		sb.WriteString(encode83(quantAC(f[0], maxVal)*19*19+quantAC(f[1], maxVal)*19+quantAC(f[2], maxVal), 2))
+	}
+	return sb.String(), nil
+}
+
+// pixels is direct Pix access for the pixel loop, avoiding a per-pixel allocation via image.At.
+type pixels struct {
+	pix    []uint8
+	stride int
+	w, h   int
+	// straight marks non-premultiplied alpha, which the loop premultiplies to keep the hash
+	// identical to the one an equivalent *image.RGBA produces.
+	straight bool
+}
+
+// pixelsOf accepts the two types the artwork pipeline produces without copying, and converts
+// anything else.
+func pixelsOf(img image.Image) pixels {
+	b := img.Bounds()
+	switch src := img.(type) {
+	case *image.RGBA:
+		return pixels{pix: src.Pix, stride: src.Stride, w: b.Dx(), h: b.Dy()}
+	case *image.NRGBA:
+		return pixels{pix: src.Pix, stride: src.Stride, w: b.Dx(), h: b.Dy(), straight: true}
+	}
+	dst := image.NewRGBA(image.Rect(0, 0, b.Dx(), b.Dy()))
+	draw.Draw(dst, dst.Bounds(), img, b.Min, draw.Src)
+	return pixels{pix: dst.Pix, stride: dst.Stride, w: b.Dx(), h: b.Dy()}
+}
+
+func premultiply(r, g, b, a uint8) (uint8, uint8, uint8) {
+	if a == 255 {
+		return r, g, b
+	}
+	return uint8(uint32(r) * uint32(a) / 255), uint8(uint32(g) * uint32(a) / 255), uint8(uint32(b) * uint32(a) / 255)
+}
+
+var srgbToLinearTable = sync.OnceValue(func() *[256]float64 {
+	var t [256]float64
+	for i := range t {
+		t[i] = srgbToLinear(i)
+	}
+	return &t
+})
+
+func downscale(img image.Image) image.Image {
+	b := img.Bounds()
+	w, h := b.Dx(), b.Dy()
+	if w <= maxInputSize && h <= maxInputSize {
+		return img
+	}
+	scale := float64(maxInputSize) / float64(max(w, h))
+	dst := image.NewRGBA(image.Rect(0, 0, max(1, int(float64(w)*scale)), max(1, int(float64(h)*scale))))
+	xdraw.ApproxBiLinear.Scale(dst, dst.Bounds(), img, b, draw.Src, nil)
+	return dst
+}
+
+func quantAC(v, maxVal float64) int {
+	return int(max(0, min(18, math.Floor(signPow(v/maxVal, 0.5)*9+9.5))))
+}
+
+func signPow(v, exp float64) float64 {
+	return math.Copysign(math.Pow(math.Abs(v), exp), v)
+}
+
+func srgbToLinear(v int) float64 {
+	f := float64(v) / 255
+	if f <= 0.04045 {
+		return f / 12.92
+	}
+	return math.Pow((f+0.055)/1.055, 2.4)
+}
+
+func linearToSRGB(v float64) int {
+	v = min(max(0, v), 1)
+	if v <= 0.0031308 {
+		return int(v*12.92*255 + 0.5)
+	}
+	return int((1.055*math.Pow(v, 1/2.4)-0.055)*255 + 0.5)
+}
+
+// encode83 encodes value as a fixed-width, big-endian base83 string of the given length.
+func encode83(value, length int) string {
+	b := make([]byte, length)
+	for i := length - 1; i >= 0; i-- {
+		b[i] = alphabet[value%83]
+		value /= 83
+	}
+	return string(b)
+}
diff --git a/core/artwork/blurhash/blurhash_suite_test.go b/core/artwork/blurhash/blurhash_suite_test.go
new file mode 100644
index 000000000..b0e96d7a7
--- /dev/null
+++ b/core/artwork/blurhash/blurhash_suite_test.go
@@ -0,0 +1,17 @@
+package blurhash_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestBlurHash(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "BlurHash Suite")
+}
diff --git a/core/artwork/blurhash/blurhash_test.go b/core/artwork/blurhash/blurhash_test.go
new file mode 100644
index 000000000..91187165e
--- /dev/null
+++ b/core/artwork/blurhash/blurhash_test.go
@@ -0,0 +1,137 @@
+package blurhash_test
+
+import (
+	"image"
+	"image/color"
+	"strings"
+
+	"github.com/navidrome/navidrome/core/artwork/blurhash"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+const alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz#$%*+,-.:;=?@[]^_{|}~"
+
+func decode83(s string) int {
+	v := 0
+	for _, c := range s {
+		v = v*83 + strings.IndexRune(alphabet, c)
+	}
+	return v
+}
+
+func solidImage(w, h int, c color.NRGBA) image.Image {
+	img := image.NewNRGBA(image.Rect(0, 0, w, h))
+	for y := range h {
+		for x := range w {
+			img.SetNRGBA(x, y, c)
+		}
+	}
+	return img
+}
+
+func gradientImage(w, h int) image.Image {
+	img := image.NewNRGBA(image.Rect(0, 0, w, h))
+	for y := range h {
+		for x := range w {
+			img.SetNRGBA(x, y, color.NRGBA{R: uint8(255 * x / w), G: uint8(255 * y / h), B: 128, A: 255})
+		}
+	}
+	return img
+}
+
+var _ = Describe("Encode input types", func() {
+	// The pipeline hands Encode an *image.NRGBA; reading it must stay equivalent to the
+	// premultiplied *image.RGBA it used to receive, or every hash silently shifts.
+	buildPair := func(alpha uint8) (*image.NRGBA, *image.RGBA) {
+		const size = 40
+		nrgba := image.NewNRGBA(image.Rect(0, 0, size, size))
+		rgba := image.NewRGBA(image.Rect(0, 0, size, size))
+		for y := range size {
+			for x := range size {
+				c := color.NRGBA{
+					R: uint8(255 * x / size), G: uint8(255 * y / size),
+					B: uint8((x + y) * 255 / (2 * size)), A: alpha,
+				}
+				nrgba.SetNRGBA(x, y, c)
+				rgba.Set(x, y, c) // image.RGBA.Set premultiplies
+			}
+		}
+		return nrgba, rgba
+	}
+
+	DescribeTable("gives an NRGBA the same hash as the premultiplied RGBA it replaces",
+		func(alpha uint8) {
+			nrgba, rgba := buildPair(alpha)
+			fromNRGBA, err := blurhash.Encode(nrgba)
+			Expect(err).ToNot(HaveOccurred())
+			fromRGBA, err := blurhash.Encode(rgba)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(fromNRGBA).To(Equal(fromRGBA))
+		},
+		Entry("opaque", uint8(255)),
+		Entry("partly transparent", uint8(128)),
+		Entry("fully transparent, which premultiplication crushes to black", uint8(0)),
+	)
+})
+
+var _ = Describe("Encode", func() {
+	// The size flag encodes (xComp-1) + (yComp-1)*9.
+	DescribeTable("derives component counts from aspect ratio (Jellyfin formula)",
+		func(w, h, expectedX, expectedY int) {
+			hash, err := blurhash.Encode(gradientImage(w, h))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(decode83(hash[:1])).To(Equal((expectedX - 1) + (expectedY-1)*9))
+		},
+		Entry("square album art", 60, 60, 5, 5),
+		Entry("smallest square", 1, 1, 5, 5),
+		Entry("landscape 16:9", 192, 108, 6, 4),
+		Entry("portrait 9:16", 108, 192, 4, 6),
+		Entry("extreme landscape capped at 9", 1000, 10, 9, 1),
+		Entry("extreme portrait capped at 9", 10, 1000, 1, 9),
+	)
+
+	It("rejects an empty image", func() {
+		_, err := blurhash.Encode(image.NewNRGBA(image.Rect(0, 0, 0, 0)))
+		Expect(err).To(HaveOccurred())
+	})
+
+	It("produces the spec-mandated length", func() {
+		// 1 (size flag) + 1 (max AC) + 4 (DC) + 2 per AC component; a square derives 5x5
+		h, err := blurhash.Encode(solidImage(8, 8, color.NRGBA{R: 10, G: 20, B: 30, A: 255}))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(h).To(HaveLen(4 + 2 + 2*(5*5-1)))
+	})
+
+	It("stores the average color in the DC component", func() {
+		h, err := blurhash.Encode(solidImage(16, 16, color.NRGBA{R: 200, G: 100, B: 50, A: 255}))
+		Expect(err).ToNot(HaveOccurred())
+		dc := decode83(h[2:6])
+		Expect(dc >> 16).To(BeNumerically("~", 200, 1))
+		Expect((dc >> 8) & 0xFF).To(BeNumerically("~", 100, 1))
+		Expect(dc & 0xFF).To(BeNumerically("~", 50, 1))
+	})
+
+	It("is deterministic", func() {
+		img := gradientImage(64, 64)
+		h1, err1 := blurhash.Encode(img)
+		h2, err2 := blurhash.Encode(img)
+		Expect(err1).ToNot(HaveOccurred())
+		Expect(err2).ToNot(HaveOccurred())
+		Expect(h1).To(Equal(h2))
+	})
+
+	It("produces different hashes for different images", func() {
+		h1, _ := blurhash.Encode(solidImage(16, 16, color.NRGBA{R: 255, A: 255}))
+		h2, _ := blurhash.Encode(gradientImage(16, 16))
+		Expect(h1).ToNot(Equal(h2))
+	})
+
+	It("downscales large images internally without changing the result materially", func() {
+		big, err := blurhash.Encode(solidImage(1000, 1000, color.NRGBA{R: 60, G: 120, B: 180, A: 255}))
+		Expect(err).ToNot(HaveOccurred())
+		small, err := blurhash.Encode(solidImage(16, 16, color.NRGBA{R: 60, G: 120, B: 180, A: 255}))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(big[2:6]).To(Equal(small[2:6]))
+	})
+})
diff --git a/core/artwork/cache_warmer.go b/core/artwork/cache_warmer.go
deleted file mode 100644
index 5090d638e..000000000
--- a/core/artwork/cache_warmer.go
+++ /dev/null
@@ -1,162 +0,0 @@
-package artwork
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"maps"
-	"slices"
-	"sync"
-	"time"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/model/request"
-	"github.com/navidrome/navidrome/utils/cache"
-	"github.com/navidrome/navidrome/utils/pl"
-)
-
-type CacheWarmer interface {
-	PreCache(artID model.ArtworkID)
-}
-
-// 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 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 {
-		return &noopCacheWarmer{}
-	}
-
-	// If the file cache is disabled, return a NOOP implementation
-	if cache.Disabled(context.Background()) {
-		log.Debug("Image cache disabled. Cache warmer will not run")
-		return &noopCacheWarmer{}
-	}
-
-	a := &cacheWarmer{
-		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
-	ctx := request.WithUser(context.TODO(), model.User{IsAdmin: true})
-	go a.run(ctx)
-	return a
-}
-
-type cacheWarmer 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) {
-	if a.cache.Disabled(context.Background()) {
-		return
-	}
-	a.mutex.Lock()
-	defer a.mutex.Unlock()
-	a.buffer[artID] = struct{}{}
-	a.sendWakeSignal()
-}
-
-func (a *cacheWarmer) sendWakeSignal() {
-	// Don't block if the previous signal was not read yet
-	select {
-	case a.wakeSignal <- struct{}{}:
-	default:
-	}
-}
-
-func (a *cacheWarmer) run(ctx context.Context) {
-	for {
-		a.waitSignal(ctx, 10*time.Second)
-		if ctx.Err() != nil {
-			break
-		}
-
-		if a.cache.Disabled(ctx) {
-			a.mutex.Lock()
-			pending := len(a.buffer)
-			a.buffer = make(map[model.ArtworkID]struct{})
-			a.mutex.Unlock()
-			if pending > 0 {
-				log.Trace(ctx, "Cache disabled, discarding precache buffer", "bufferLen", pending)
-			}
-			return
-		}
-
-		// If cache not available, keep waiting
-		if !a.cache.Available(ctx) {
-			a.mutex.Lock()
-			bufferLen := len(a.buffer)
-			a.mutex.Unlock()
-			if bufferLen > 0 {
-				log.Trace(ctx, "Cache not available, buffering precache request", "bufferLen", bufferLen)
-			}
-			continue
-		}
-
-		a.mutex.Lock()
-
-		// If there's nothing to send, keep waiting
-		if len(a.buffer) == 0 {
-			a.mutex.Unlock()
-			continue
-		}
-
-		batch := slices.Collect(maps.Keys(a.buffer))
-		a.buffer = make(map[model.ArtworkID]struct{})
-		a.mutex.Unlock()
-
-		a.processBatch(ctx, batch)
-	}
-}
-
-func (a *cacheWarmer) waitSignal(ctx context.Context, timeout time.Duration) {
-	select {
-	case <-time.After(timeout):
-	case <-a.wakeSignal:
-	case <-ctx.Done():
-	}
-}
-
-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, 4, input, a.doCacheImage)
-	for err := range errs {
-		log.Debug(ctx, "Error warming cache", err)
-	}
-}
-
-func (a *cacheWarmer) doCacheImage(ctx context.Context, id model.ArtworkID) error {
-	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
-	defer cancel()
-
-	size := a.coverArtSize
-	r, _, err := a.artwork.Get(ctx, id, size, true)
-	if err != nil {
-		return fmt.Errorf("caching id='%s', size=%d: %w", id, size, err)
-	}
-	_, err = io.Copy(io.Discard, r)
-	r.Close()
-	return err
-}
-
-func NoopCacheWarmer() CacheWarmer {
-	return &noopCacheWarmer{}
-}
-
-type noopCacheWarmer struct{}
-
-func (a *noopCacheWarmer) PreCache(model.ArtworkID) {}
diff --git a/core/artwork/cache_warmer_test.go b/core/artwork/cache_warmer_test.go
deleted file mode 100644
index a5da2004c..000000000
--- a/core/artwork/cache_warmer_test.go
+++ /dev/null
@@ -1,245 +0,0 @@
-package artwork
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"io"
-	"strings"
-	"sync"
-	"sync/atomic"
-	"time"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/conf/configtest"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/utils/cache"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("CacheWarmer", func() {
-	var (
-		fc *mockFileCache
-		aw *mockArtwork
-	)
-
-	BeforeEach(func() {
-		DeferCleanup(configtest.SetupConfig())
-		fc = &mockFileCache{}
-		aw = &mockArtwork{}
-	})
-
-	Context("initialization", func() {
-		It("returns noop when cache is disabled", func() {
-			fc.SetDisabled(true)
-			cw := NewCacheWarmer(aw, fc)
-			_, ok := cw.(*noopCacheWarmer)
-			Expect(ok).To(BeTrue())
-		})
-
-		It("returns noop when ImageCacheSize is 0", func() {
-			conf.Server.ImageCacheSize = "0"
-			cw := NewCacheWarmer(aw, fc)
-			_, ok := cw.(*noopCacheWarmer)
-			Expect(ok).To(BeTrue())
-		})
-
-		It("returns noop when EnableArtworkPrecache is false", func() {
-			conf.Server.EnableArtworkPrecache = false
-			cw := NewCacheWarmer(aw, fc)
-			_, ok := cw.(*noopCacheWarmer)
-			Expect(ok).To(BeTrue())
-		})
-
-		It("returns real implementation when properly configured", func() {
-			conf.Server.ImageCacheSize = "100MB"
-			conf.Server.EnableArtworkPrecache = true
-			fc.SetDisabled(false)
-			cw := NewCacheWarmer(aw, fc)
-			_, ok := cw.(*cacheWarmer)
-			Expect(ok).To(BeTrue())
-		})
-	})
-
-	Context("buffer management", func() {
-		BeforeEach(func() {
-			conf.Server.ImageCacheSize = "100MB"
-			conf.Server.EnableArtworkPrecache = true
-			fc.SetDisabled(false)
-		})
-
-		It("drops buffered items when cache becomes disabled", func() {
-			cw := NewCacheWarmer(aw, fc).(*cacheWarmer)
-			cw.PreCache(model.MustParseArtworkID("al-test"))
-			fc.SetDisabled(true)
-			Eventually(func() int {
-				cw.mutex.Lock()
-				defer cw.mutex.Unlock()
-				return len(cw.buffer)
-			}).Should(Equal(0))
-		})
-
-		It("adds multiple items to buffer", func() {
-			fc.SetReady(false) // Make cache unavailable so items stay in buffer
-			cw := NewCacheWarmer(aw, fc).(*cacheWarmer)
-			cw.PreCache(model.MustParseArtworkID("al-1"))
-			cw.PreCache(model.MustParseArtworkID("al-2"))
-			cw.mutex.Lock()
-			defer cw.mutex.Unlock()
-			Expect(len(cw.buffer)).To(Equal(2))
-		})
-
-		It("deduplicates items in buffer", func() {
-			fc.SetReady(false) // Make cache unavailable so items stay in buffer
-			cw := NewCacheWarmer(aw, fc).(*cacheWarmer)
-			cw.PreCache(model.MustParseArtworkID("al-1"))
-			cw.PreCache(model.MustParseArtworkID("al-1"))
-			cw.mutex.Lock()
-			defer cw.mutex.Unlock()
-			Expect(len(cw.buffer)).To(Equal(1))
-		})
-	})
-
-	Context("error handling", func() {
-		BeforeEach(func() {
-			conf.Server.ImageCacheSize = "100MB"
-			conf.Server.EnableArtworkPrecache = true
-			fc.SetDisabled(false)
-		})
-
-		It("continues processing after artwork retrieval error", func() {
-			aw.err = errors.New("artwork error")
-			cw := NewCacheWarmer(aw, fc).(*cacheWarmer)
-			cw.PreCache(model.MustParseArtworkID("al-error"))
-			cw.PreCache(model.MustParseArtworkID("al-1"))
-
-			Eventually(func() int {
-				cw.mutex.Lock()
-				defer cw.mutex.Unlock()
-				return len(cw.buffer)
-			}).Should(Equal(0))
-		})
-
-		It("continues processing after cache error", func() {
-			fc.err = errors.New("cache error")
-			cw := NewCacheWarmer(aw, fc).(*cacheWarmer)
-			cw.PreCache(model.MustParseArtworkID("al-error"))
-			cw.PreCache(model.MustParseArtworkID("al-1"))
-
-			Eventually(func() int {
-				cw.mutex.Lock()
-				defer cw.mutex.Unlock()
-				return len(cw.buffer)
-			}).Should(Equal(0))
-		})
-	})
-
-	Context("background processing", func() {
-		BeforeEach(func() {
-			conf.Server.ImageCacheSize = "100MB"
-			conf.Server.EnableArtworkPrecache = true
-			fc.SetDisabled(false)
-		})
-
-		It("processes items in batches", func() {
-			cw := NewCacheWarmer(aw, fc).(*cacheWarmer)
-			for i := range 5 {
-				cw.PreCache(model.MustParseArtworkID(fmt.Sprintf("al-%d", i)))
-			}
-
-			Eventually(func() int {
-				cw.mutex.Lock()
-				defer cw.mutex.Unlock()
-				return len(cw.buffer)
-			}).Should(Equal(0))
-		})
-
-		It("wakes up on new items", func() {
-			cw := NewCacheWarmer(aw, fc).(*cacheWarmer)
-
-			// Add first batch
-			cw.PreCache(model.MustParseArtworkID("al-1"))
-			Eventually(func() int {
-				cw.mutex.Lock()
-				defer cw.mutex.Unlock()
-				return len(cw.buffer)
-			}).Should(Equal(0))
-
-			// Add second batch
-			cw.PreCache(model.MustParseArtworkID("al-2"))
-			Eventually(func() int {
-				cw.mutex.Lock()
-				defer cw.mutex.Unlock()
-				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
-	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)
-}
-
-type mockFileCache struct {
-	disabled atomic.Bool
-	ready    atomic.Bool
-	err      error
-}
-
-func (f *mockFileCache) Get(ctx context.Context, item cache.Item) (*cache.CachedStream, error) {
-	if f.err != nil {
-		return nil, f.err
-	}
-	return &cache.CachedStream{Reader: io.NopCloser(strings.NewReader("cached"))}, nil
-}
-
-func (f *mockFileCache) Available(ctx context.Context) bool {
-	return f.ready.Load() && !f.disabled.Load()
-}
-
-func (f *mockFileCache) Disabled(ctx context.Context) bool {
-	return f.disabled.Load()
-}
-
-func (f *mockFileCache) SetDisabled(v bool) {
-	f.disabled.Store(v)
-	f.ready.Store(true)
-}
-
-func (f *mockFileCache) SetReady(v bool) {
-	f.ready.Store(v)
-}
diff --git a/core/artwork/reader_disc.go b/core/artwork/disc.go
similarity index 60%
rename from core/artwork/reader_disc.go
rename to core/artwork/disc.go
index 0f648c987..21f596b60 100644
--- a/core/artwork/reader_disc.go
+++ b/core/artwork/disc.go
@@ -2,7 +2,6 @@ package artwork
 
 import (
 	"context"
-	"crypto/md5"
 	"fmt"
 	"io"
 	"path"
@@ -12,16 +11,16 @@ import (
 	"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"
 	"github.com/navidrome/navidrome/utils"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
+// discArtworkReader resolves disc-level artwork from a library's folder images
+// and embedded tags. It is used by the serving path's provisional disc read-through.
 type discArtworkReader struct {
-	cacheKey
-	a              *artwork
 	album          model.Album
 	discNumber     int
 	imgFiles       []string        // library-relative, forward-slash, no leading slash
@@ -29,27 +28,40 @@ type discArtworkReader struct {
 	isMultiFolder  bool
 	firstTrackRel  string // library-relative; for fromTag / ffmpeg via lib.Abs
 	lib            libraryView
-	updatedAt      *time.Time
+	// Newest ImagesUpdatedAt across the album's and this disc's folders: an image can be
+	// replaced without the album row changing, so this is what makes a cache key notice it.
+	imagesUpdatedAt time.Time
 }
 
-func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID) (*discArtworkReader, error) {
+// cacheTime is the disc image's validity stamp: any of these moving means the selection may
+// have changed.
+func (d *discArtworkReader) cacheTime() time.Time {
+	return utils.TimeNewest(d.album.UpdatedAt, d.album.ImportedAt, d.imagesUpdatedAt)
+}
+
+func newDiscArtworkReader(ctx context.Context, ds model.DataStore, 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)
+	al, err := ds.Album(ctx).Get(albumID)
 	if err != nil {
 		return nil, err
 	}
 
-	_, imgFiles, imagesUpdatedAt, err := loadAlbumFoldersPaths(ctx, a.ds, *al)
+	_, imgFiles, albumImagesAt, err := loadAlbumFoldersPaths(ctx, ds, *al)
 	if err != nil {
 		return nil, err
 	}
 
+	var imagesUpdatedAt time.Time
+	if albumImagesAt != nil {
+		imagesUpdatedAt = *albumImagesAt
+	}
+
 	// Query mediafiles for this album + disc to find folder associations and first track
-	mfs, err := a.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
 		Sort:    "track_number",
 		Order:   "ASC",
 		Filters: squirrel.Eq{"album_id": albumID, "disc_number": discNumber},
@@ -58,29 +70,25 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 		return nil, err
 	}
 
-	lib, err := loadLibraryView(ctx, a.ds, al.LibraryID)
+	lib, err := loadLibraryView(ctx, 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 == "" {
+		if mf.Path != "" {
 			firstTrackRel = filepath.ToSlash(mf.Path)
+			break
 		}
 	}
+	folderIDs := slice.Unique(slice.Map(mfs, func(mf model.MediaFile) string { return mf.FolderID }))
 
 	// 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{
+	if len(folderIDs) > 0 {
+		folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{
 			Filters: squirrel.Eq{"folder.id": folderIDs},
 		})
 		if err != nil {
@@ -89,49 +97,20 @@ func newDiscArtworkReader(ctx context.Context, a *artwork, artID model.ArtworkID
 		for _, f := range folders {
 			rel := strings.TrimPrefix(path.Join(f.Path, f.Name), "/")
 			discFoldersRel[rel] = true
+			imagesUpdatedAt = utils.TimeNewest(imagesUpdatedAt, f.ImagesUpdatedAt)
 		}
 	}
 
-	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
-	r.cacheKey.lastUpdate = utils.TimeNewest(al.UpdatedAt, al.ImportedAt)
-	if imagesUpdatedAt != nil {
-		r.cacheKey.lastUpdate = utils.TimeNewest(r.cacheKey.lastUpdate, *imagesUpdatedAt)
-	}
-	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...)
+	return &discArtworkReader{
+		album:           *al,
+		discNumber:      discNumber,
+		imgFiles:        imgFiles,
+		discFoldersRel:  discFoldersRel,
+		isMultiFolder:   len(al.FolderIDs) > 1,
+		firstTrackRel:   firstTrackRel,
+		lib:             lib,
+		imagesUpdatedAt: imagesUpdatedAt,
+	}, nil
 }
 
 func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string) []sourceFunc {
@@ -162,14 +141,13 @@ func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmp
 func (d *discArtworkReader) fromDiscSubtitle(ctx context.Context, subtitle string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		for _, file := range d.imgFiles {
-			name := path.Base(file)
-			stem := strings.TrimSuffix(name, path.Ext(name))
+			stem := utils.BaseName(file)
 			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)
+				log.Warn(ctx, "Artwork: Could not open disc art file", "file", file, err)
 				continue
 			}
 			return f, file, nil
@@ -178,19 +156,12 @@ func (d *discArtworkReader) fromDiscSubtitle(ctx context.Context, subtitle strin
 	}
 }
 
-// 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.
+// filepath.Match's '\' escape is excluded on purpose: treating it 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.
+// extractDiscNumber parses the disc number from a filename matched by a filepath.Match-style
+// glob. Caller must lowercase both args and have already verified the match.
 func extractDiscNumber(pattern, filename string) (int, bool) {
 	metaIdx := strings.IndexAny(pattern, globMetaChars)
 	if metaIdx < 0 {
@@ -216,9 +187,8 @@ func extractDiscNumber(pattern, filename string) (int, bool) {
 	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.
+// fromExternalFile matches image files against a (lowercase) glob pattern. A numbered
+// filename whose number equals the target disc wins over any unnumbered candidate.
 func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string) sourceFunc {
 	isLiteral := !strings.ContainsAny(pattern, globMetaChars)
 	return func() (io.ReadCloser, string, error) {
@@ -227,7 +197,7 @@ func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string
 			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)
+				log.Warn(ctx, "Artwork: Error matching disc art file to pattern", "pattern", pattern, "file", file)
 				continue
 			}
 			if !match {
@@ -241,7 +211,7 @@ func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string
 					}
 					f, err := d.lib.FS.Open(file)
 					if err != nil {
-						log.Warn(ctx, "Could not open disc art file", "file", file, err)
+						log.Warn(ctx, "Artwork: Could not open disc art file", "file", file, err)
 						continue
 					}
 					return f, file, nil
@@ -257,7 +227,7 @@ func (d *discArtworkReader) fromExternalFile(ctx context.Context, pattern string
 		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)
+				log.Warn(ctx, "Artwork: Could not open disc art file", "file", file, err)
 				continue
 			}
 			return f, file, nil
diff --git a/core/artwork/reader_disc_test.go b/core/artwork/disc_test.go
similarity index 100%
rename from core/artwork/reader_disc_test.go
rename to core/artwork/disc_test.go
diff --git a/core/artwork/dominant/dominant.go b/core/artwork/dominant/dominant.go
new file mode 100644
index 000000000..2bbda8ae9
--- /dev/null
+++ b/core/artwork/dominant/dominant.go
@@ -0,0 +1,127 @@
+// Package dominant extracts an image's dominant colour, for use as a flat placeholder while the
+// real artwork loads.
+package dominant
+
+import (
+	"fmt"
+	"image"
+	"math"
+	"sort"
+)
+
+const (
+	// 4 bits per channel: coarse enough that near-identical pixels land together, fine enough that
+	// distinct colours stay apart.
+	bits  = 4
+	nBins = 1 << (3 * bits)
+	// Only the heaviest bins can win, and merging is O(n^2) over whatever survives.
+	maxBins = 64
+	// Oklab distance below which two bins are the same colour to the eye. Merging matters because a
+	// gradient splits across adjacent bins and would otherwise lose to a smaller flat region.
+	mergeDist = 0.10
+)
+
+type bin struct {
+	r, g, b float64
+	n       float64
+}
+
+// Color returns the dominant colour as "#rrggbb", or "" when the image has no pixels. It reports
+// presence, not salience: a mostly white sleeve returns white.
+func Color(img image.Image) string {
+	var bins [nBins]bin
+	total := 0
+	eachPixel(img, func(r, g, b uint8) {
+		i := int(r>>(8-bits))<<(2*bits) | int(g>>(8-bits))<<bits | int(b>>(8-bits))
+		bins[i].r += float64(r)
+		bins[i].g += float64(g)
+		bins[i].b += float64(b)
+		bins[i].n++
+		total++
+	})
+	if total == 0 {
+		return ""
+	}
+
+	used := make([]bin, 0, 32)
+	for i := range bins {
+		if bins[i].n > 0 {
+			used = append(used, bins[i])
+		}
+	}
+	sort.Slice(used, func(i, j int) bool { return used[i].n > used[j].n })
+	if len(used) > maxBins {
+		used = used[:maxBins]
+	}
+
+	merged := make([]bin, 0, len(used))
+	for _, b := range used {
+		if i := nearest(merged, b); i >= 0 {
+			merged[i].r += b.r
+			merged[i].g += b.g
+			merged[i].b += b.b
+			merged[i].n += b.n
+			continue
+		}
+		merged = append(merged, b)
+	}
+
+	best := merged[0]
+	for _, m := range merged[1:] {
+		if m.n > best.n {
+			best = m
+		}
+	}
+	return fmt.Sprintf("#%02x%02x%02x",
+		uint8(best.r/best.n+0.5), uint8(best.g/best.n+0.5), uint8(best.b/best.n+0.5))
+}
+
+func nearest(merged []bin, b bin) int {
+	bl, ba, bb := oklab(b.r/b.n, b.g/b.n, b.b/b.n)
+	for i, m := range merged {
+		ml, ma, mb := oklab(m.r/m.n, m.g/m.n, m.b/m.n)
+		if math.Sqrt((bl-ml)*(bl-ml)+(ba-ma)*(ba-ma)+(bb-mb)*(bb-mb)) < mergeDist {
+			return i
+		}
+	}
+	return -1
+}
+
+// eachPixel walks the image, taking the NRGBA fast path the artwork pipeline always hits: both hash
+// encoders already read the shared thumbnail in that form.
+func eachPixel(img image.Image, fn func(r, g, b uint8)) {
+	if p, ok := img.(*image.NRGBA); ok {
+		for y := range p.Rect.Dy() {
+			row := p.Pix[y*p.Stride : y*p.Stride+p.Rect.Dx()*4]
+			for x := 0; x < len(row); x += 4 {
+				fn(row[x], row[x+1], row[x+2])
+			}
+		}
+		return
+	}
+	b := img.Bounds()
+	for y := b.Min.Y; y < b.Max.Y; y++ {
+		for x := b.Min.X; x < b.Max.X; x++ {
+			r, g, bl, _ := img.At(x, y).RGBA()
+			fn(uint8(r>>8), uint8(g>>8), uint8(bl>>8))
+		}
+	}
+}
+
+func srgbToLinear(v float64) float64 {
+	v /= 255
+	if v <= 0.04045 {
+		return v / 12.92
+	}
+	return math.Pow((v+0.055)/1.055, 2.4)
+}
+
+func oklab(r, g, b float64) (float64, float64, float64) {
+	lr, lg, lb := srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)
+	l := math.Cbrt(0.4122214708*lr + 0.5363325363*lg + 0.0514459929*lb)
+	m := math.Cbrt(0.2119034982*lr + 0.6806995451*lg + 0.1073969566*lb)
+	s := math.Cbrt(0.0883024619*lr + 0.2817188376*lg + 0.6299787005*lb)
+	return 0.2104542553*l + 0.7936177850*m - 0.0040720468*s,
+		1.9779984951*l - 2.4285922050*m + 0.4505937099*s,
+		0.0259040371*l + 0.7827717662*m - 0.8086757660*s
+}
diff --git a/core/artwork/dominant/dominant_suite_test.go b/core/artwork/dominant/dominant_suite_test.go
new file mode 100644
index 000000000..56dbd6209
--- /dev/null
+++ b/core/artwork/dominant/dominant_suite_test.go
@@ -0,0 +1,17 @@
+package dominant_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestDominant(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Dominant Suite")
+}
diff --git a/core/artwork/dominant/dominant_test.go b/core/artwork/dominant/dominant_test.go
new file mode 100644
index 000000000..da7fed09c
--- /dev/null
+++ b/core/artwork/dominant/dominant_test.go
@@ -0,0 +1,91 @@
+package dominant_test
+
+import (
+	"image"
+	"image/color"
+
+	"github.com/navidrome/navidrome/core/artwork/dominant"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// fill paints rect with c onto img.
+func fill(img *image.NRGBA, r image.Rectangle, c color.NRGBA) {
+	for y := r.Min.Y; y < r.Max.Y; y++ {
+		for x := r.Min.X; x < r.Max.X; x++ {
+			img.SetNRGBA(x, y, c)
+		}
+	}
+}
+
+func newImg(w, h int, c color.NRGBA) *image.NRGBA {
+	img := image.NewNRGBA(image.Rect(0, 0, w, h))
+	fill(img, img.Bounds(), c)
+	return img
+}
+
+var _ = Describe("Color", func() {
+	It("returns a solid image's own colour", func() {
+		Expect(dominant.Color(newImg(20, 20, color.NRGBA{0x33, 0x66, 0x99, 255}))).To(Equal("#336699"))
+	})
+
+	It("returns empty for an image with no pixels", func() {
+		Expect(dominant.Color(image.NewNRGBA(image.Rect(0, 0, 0, 0)))).To(Equal(""))
+	})
+
+	// Presence, not salience: this is a placeholder, so the large field wins even though the small
+	// patch is the more interesting colour.
+	It("picks the largest area, not the most vivid one", func() {
+		img := newImg(20, 20, color.NRGBA{0xfa, 0xfa, 0xfa, 255})
+		fill(img, image.Rect(0, 0, 4, 4), color.NRGBA{0xff, 0x00, 0x00, 255})
+		Expect(dominant.Color(img)).To(Equal("#fafafa"))
+	})
+
+	It("reports a near-black cover as near-black", func() {
+		img := newImg(20, 20, color.NRGBA{0x05, 0x05, 0x05, 255})
+		fill(img, image.Rect(0, 0, 5, 5), color.NRGBA{0x00, 0xff, 0x00, 255})
+		Expect(dominant.Color(img)).To(Equal("#050505"))
+	})
+
+	// A gradient splits across many quantisation bins. Without merging, each slice is smaller than
+	// the flat block and the block would win despite covering far less of the image.
+	It("merges a gradient's bins so it beats a smaller flat block", func() {
+		img := image.NewNRGBA(image.Rect(0, 0, 40, 40))
+		for y := range 40 {
+			for x := range 40 {
+				// 30 columns of blue gradient == 75% of the image
+				if x < 30 {
+					img.SetNRGBA(x, y, color.NRGBA{0x10, 0x20, uint8(0xa0 + x), 255})
+				} else {
+					img.SetNRGBA(x, y, color.NRGBA{0xff, 0xcc, 0x00, 255})
+				}
+			}
+		}
+		got := dominant.Color(img)
+		Expect(got).To(HavePrefix("#1020"), "expected the blue gradient, got "+got)
+	})
+
+	It("is deterministic", func() {
+		img := image.NewNRGBA(image.Rect(0, 0, 30, 30))
+		for y := range 30 {
+			for x := range 30 {
+				img.SetNRGBA(x, y, color.NRGBA{uint8(x * 7), uint8(y * 5), uint8(x + y), 255})
+			}
+		}
+		first := dominant.Color(img)
+		for range 5 {
+			Expect(dominant.Color(img)).To(Equal(first))
+		}
+	})
+
+	It("handles images that are not NRGBA", func() {
+		src := newImg(10, 10, color.NRGBA{0x20, 0x40, 0x60, 255})
+		rgba := image.NewRGBA(src.Bounds())
+		for y := range 10 {
+			for x := range 10 {
+				rgba.Set(x, y, src.At(x, y))
+			}
+		}
+		Expect(dominant.Color(rgba)).To(Equal("#204060"))
+	})
+})
diff --git a/core/artwork/e2e/acquire_serve_test.go b/core/artwork/e2e/acquire_serve_test.go
new file mode 100644
index 000000000..d6c374e39
--- /dev/null
+++ b/core/artwork/e2e/acquire_serve_test.go
@@ -0,0 +1,326 @@
+package e2e
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"io"
+	"os"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server/events"
+	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/cache"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Covers the enqueue → drain → serve chain; per-source resolution rules live in the unit suites.
+var _ = Describe("Acquisition → serve loop", func() {
+	var (
+		ctx        context.Context
+		ds         *tests.MockDataStore
+		artRepo    *tests.MockArtworkRepo
+		queueRepo  *tests.MockArtworkQueueRepo
+		albumRepo  *tests.MockAlbumRepo
+		artistRepo *tests.MockArtistRepo
+		mfRepo     *tests.MockMediaFileRepo
+		plRepo     *tests.MockPlaylistRepo
+		radioRepo  *tests.MockedRadioRepo
+		folderRepo *fakeFolderRepo
+		libRepo    *tests.MockLibraryRepo
+		store      *artwork.ImageStore
+		svc        artwork.Artwork
+		worker     *artwork.Worker
+		coverBytes []byte
+	)
+
+	itemFound := func(kind model.Kind, id string) func() bool {
+		return func() bool {
+			ia, err := artRepo.GetItemArtwork(kind, id, model.ImageTypePrimary)
+			return err == nil && ia.Hash != ""
+		}
+	}
+	itemAbsent := func(kind model.Kind, id string) func() bool {
+		return func() bool {
+			ia, err := artRepo.GetItemArtwork(kind, id, model.ImageTypePrimary)
+			return err == nil && ia.Hash == ""
+		}
+	}
+	// Enqueues the way the serving paths do, so the drain is driven by a plain queue row.
+	bump := func(kind, id string) {
+		GinkgoHelper()
+		Expect(ds.ArtworkQueue(ctx).EnqueuePreservingBackoff(model.ArtworkQueueItem{
+			ItemKind: kind, ItemID: id, ImageType: model.ImageTypePrimary,
+			Priority: model.ArtworkPriorityBump,
+		})).To(Succeed())
+	}
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		ctx = context.Background()
+		repoRoot, err := os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		coverBytes = readFixture(coverFixture)
+
+		conf.Server.CacheFolder = conf.NewDir(GinkgoT().TempDir())
+		conf.Server.DataFolder = conf.NewDir(GinkgoT().TempDir())
+		conf.Server.CoverArtPriority = "cover.jpg"
+		conf.Server.ArtistArtPriority = "artist.png" // keeps artist resolution offline
+		conf.Server.EnableMediaFileCoverArt = true
+		conf.Server.DevArtworkWorkerConcurrency = 1
+
+		folderRepo = &fakeFolderRepo{}
+		libRepo = &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: repoRoot}})
+		artRepo = tests.CreateMockArtworkRepo()
+		queueRepo = tests.CreateMockArtworkQueueRepo()
+		albumRepo = tests.CreateMockAlbumRepo()
+		artistRepo = tests.CreateMockArtistRepo()
+		mfRepo = tests.CreateMockMediaFileRepo()
+		plRepo = tests.CreateMockPlaylistRepo()
+		radioRepo = tests.CreateMockedRadioRepo()
+		radioRepo.Data = map[string]*model.Radio{}
+		ds = &tests.MockDataStore{
+			MockedArtwork:      artRepo,
+			MockedArtworkQueue: queueRepo,
+			MockedAlbum:        albumRepo,
+			MockedArtist:       artistRepo,
+			MockedMediaFile:    mfRepo,
+			MockedPlaylist:     plRepo,
+			MockedRadio:        radioRepo,
+			MockedFolder:       folderRepo,
+			MockedLibrary:      libRepo,
+		}
+		ffm := tests.NewMockFFmpeg("")
+		store = artwork.NewImageStore(GinkgoT().TempDir())
+		// size=0 requests stream originals, so this reader is never called (serving_test covers resizing).
+		imgCache := cache.NewFileCache("ArtworkPipelineE2E", "100MB", "images", 0,
+			func(context.Context, cache.Item) (io.Reader, error) {
+				return nil, errors.New("resize not exercised in e2e")
+			})
+		Eventually(func() bool { return imgCache.Available(ctx) }).Should(BeTrue())
+
+		svc = artwork.NewArtwork(ds, imgCache, store, ffm)
+		worker = artwork.NewWorker(ds, store, agents.GetAgents(ds, nil), ffm, events.NoopBroker(), imgCache)
+	})
+
+	seedFolderAlbum := func(albumID string) {
+		folderRepo.result = []model.Folder{{Path: albumFolderPath, ImageFiles: []string{"cover.jpg"}}}
+		albumRepo.SetData(model.Albums{{ID: albumID, Name: "Album", FolderIDs: []string{"f1"}, LibraryID: 0}})
+	}
+
+	It("acquires album folder art and serves the exact bytes under its hash", func() {
+		seedFolderAlbum("al1")
+		bump("al", "al1")
+		runWorkerUntil(ctx, worker, itemFound(model.KindAlbumArtwork, "al1"))
+
+		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("folder"))
+
+		img, err := svc.Get(ctx, model.MustParseArtworkID("al-al1"), 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(img.Hash).To(Equal(ia.Hash))
+		Expect(img.Placeholder).To(BeFalse())
+		Expect(readAll(img)).To(Equal(coverBytes))
+	})
+
+	It("acquires an artist's uploaded image and serves it", func() {
+		name := writeUpload(consts.EntityArtist, "artist-e2e.png", artistPngFixture)
+		artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist", UploadedImage: name}})
+		bump("ar", "ar1")
+		runWorkerUntil(ctx, worker, itemFound(model.KindArtistArtwork, "ar1"))
+
+		ia, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("upload"))
+
+		img, err := svc.Get(ctx, model.MustParseArtworkID("ar-ar1"), 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(img.Hash).To(Equal(ia.Hash))
+		Expect(readAll(img)).To(Equal(readFixture(artistPngFixture)))
+	})
+
+	It("generates a playlist grid from its tracks' album art and serves it from the store", func() {
+		seedFolderAlbum("al1")
+		plRepo.SetData(model.Playlists{{ID: "pl1", Name: "Playlist"}})
+		plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"al1"}}
+		bump("pl", "pl1")
+		runWorkerUntil(ctx, worker, itemFound(model.KindPlaylistArtwork, "pl1"))
+
+		ia, err := artRepo.GetItemArtwork(model.KindPlaylistArtwork, "pl1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("generated"))
+
+		img, err := svc.Get(ctx, model.MustParseArtworkID("pl-pl1"), 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(img.Hash).To(Equal(ia.Hash))
+		art, err := artRepo.GetImage(ia.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(art.Mime).To(Equal("image/png"))
+		Expect(len(readAll(img))).To(BeNumerically(">", 0))
+	})
+
+	It("acquires a radio station's uploaded image and serves it", func() {
+		name := writeUpload(consts.EntityRadio, "radio-e2e.jpg", coverFixture)
+		radioRepo.Data["ra1"] = &model.Radio{ID: "ra1", Name: "Station", UploadedImage: name}
+		bump("ra", "ra1")
+		runWorkerUntil(ctx, worker, itemFound(model.KindRadioArtwork, "ra1"))
+
+		ia, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("upload"))
+
+		img, err := svc.Get(ctx, model.MustParseArtworkID("ra-ra1"), 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(img.Hash).To(Equal(ia.Hash))
+		Expect(readAll(img)).To(Equal(coverBytes))
+	})
+
+	It("serves an unresolved track provisionally, then upgrades to the worker's state row", func() {
+		mfRepo.SetData(model.MediaFiles{{
+			ID: "mf1", AlbumID: "al1", HasCoverArt: true, LibraryID: 0, Path: mp3Fixture,
+		}})
+
+		provisional, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf1"), 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(provisional.Placeholder).To(BeFalse())
+		Expect(provisional.Hash).ToNot(BeEmpty())
+		provisionalBytes := readAll(provisional)
+		Expect(len(provisionalBytes)).To(BeNumerically(">", 0))
+
+		_, err = artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound), "provisional serving must not write a state row")
+
+		// The provisional read enqueued a Bump; drain it.
+		runWorkerUntil(ctx, worker, itemFound(model.KindMediaFileArtwork, "mf1"))
+		ia, err := artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("embedded"))
+		Expect(ia.Hash).To(Equal(provisional.Hash))
+
+		resolved, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf1"), 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(resolved.Hash).To(Equal(ia.Hash))
+		Expect(readAll(resolved)).To(Equal(provisionalBytes))
+	})
+
+	It("stores dimensions, mime and a real blurhash alongside the acquired bytes", func() {
+		seedFolderAlbum("al1")
+		bump("al", "al1")
+		runWorkerUntil(ctx, worker, itemFound(model.KindAlbumArtwork, "al1"))
+
+		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		art, err := artRepo.GetImage(ia.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(art.Mime).To(Equal("image/jpeg"))
+		Expect(art.Width).To(BeNumerically(">", 0))
+		Expect(art.Height).To(BeNumerically(">", 0))
+		Expect(art.SizeBytes).To(BeNumerically("==", len(coverBytes)))
+		// Never a synthesized value: both hashes are encoded from the real pixels.
+		Expect(art.BlurHash).ToNot(BeEmpty())
+		Expect(art.ThumbHash).ToNot(BeEmpty())
+		raw, err := base64.StdEncoding.DecodeString(art.ThumbHash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(len(raw)).To(BeNumerically(">=", 5))
+	})
+
+	It("acquires GIF artwork, whose decoder only core/artwork's blank import registers", func() {
+		writeUploadedImage(consts.EntityRadio, "station.gif", gifFixture)
+		radioRepo.Data["ra1"] = &model.Radio{ID: "ra1", Name: "Station", UploadedImage: "station.gif"}
+		bump("ra", "ra1")
+		runWorkerUntil(ctx, worker, itemFound(model.KindRadioArtwork, "ra1"))
+
+		ia, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		art, err := artRepo.GetImage(ia.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(art.Mime).To(Equal("image/gif"))
+		Expect(art.Width).To(BeNumerically("==", 4))
+	})
+
+	It("deduplicates byte-identical art across entities onto one image row", func() {
+		folderRepo.result = []model.Folder{{Path: albumFolderPath, ImageFiles: []string{"cover.jpg"}}}
+		albumRepo.SetData(model.Albums{
+			{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}, LibraryID: 0},
+			{ID: "al2", Name: "Same Cover", FolderIDs: []string{"f1"}, LibraryID: 0},
+		})
+		bump("al", "al1")
+		bump("al", "al2")
+		runWorkerUntil(ctx, worker, func() bool {
+			return itemFound(model.KindAlbumArtwork, "al1")() && itemFound(model.KindAlbumArtwork, "al2")()
+		})
+
+		ia1, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		ia2, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al2", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia1.Hash).To(Equal(ia2.Hash), "identical bytes must share one content hash")
+		Expect(readAll(mustGet(svc.Get(ctx, model.MustParseArtworkID("al-al2"), 0, false)))).To(Equal(coverBytes))
+	})
+
+	It("stops serving a file-backed image once its source file changes underneath", func() {
+		name := writeUpload(consts.EntityRadio, "radio-stale.jpg", coverFixture)
+		radioRepo.Data["ra1"] = &model.Radio{ID: "ra1", Name: "Station", UploadedImage: name}
+		bump("ra", "ra1")
+		runWorkerUntil(ctx, worker, itemFound(model.KindRadioArtwork, "ra1"))
+
+		ia, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		staleHash := ia.Hash
+
+		path := model.UploadedImagePath(consts.EntityRadio, name)
+		Expect(os.WriteFile(path, readFixture(artistPngFixture), 0o600)).To(Succeed())
+		newer := time.Now().Add(2 * time.Second)
+		Expect(os.Chtimes(path, newer, newer)).To(Succeed())
+
+		// The mtime no longer matches the state row, so the stale bytes are not served.
+		_, err = svc.Get(ctx, model.MustParseArtworkID("ra-ra1"), 0, false)
+		Expect(err).To(MatchError(artwork.ErrUnavailable))
+
+		// That failed read enqueued a re-resolution.
+		runWorkerUntil(ctx, worker, func() bool {
+			cur, gerr := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+			return gerr == nil && cur.Hash != "" && cur.Hash != staleHash
+		})
+		img, err := svc.Get(ctx, model.MustParseArtworkID("ra-ra1"), 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(readAll(img)).To(Equal(readFixture(artistPngFixture)))
+	})
+
+	It("records an absent state for an entity with no art and reports it unavailable", func() {
+		albumRepo.SetData(model.Albums{{ID: "alx", Name: "Artless", LibraryID: 0}})
+		bump("al", "alx")
+		runWorkerUntil(ctx, worker, itemAbsent(model.KindAlbumArtwork, "alx"))
+
+		_, err := svc.Get(ctx, model.MustParseArtworkID("al-alx"), 0, false)
+		Expect(err).To(MatchError(artwork.ErrUnavailable))
+
+		img, err := svc.GetOrPlaceholder(ctx, "al-alx", 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(img.Placeholder).To(BeTrue())
+	})
+})
+
+func mustGet(img *artwork.Image, err error) *artwork.Image {
+	GinkgoHelper()
+	Expect(err).ToNot(HaveOccurred())
+	return img
+}
+
+// Raw bytes on purpose: encoding a GIF here would register image/gif in the test binary, masking
+// the production import the spec above guards.
+var gifFixture = []byte{
+	0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x04, 0x00, 0x04, 0x00, 0x80, 0x00,
+	0x00, 0x2e, 0x86, 0xc1, 0xf4, 0xd0, 0x3f, 0x2c, 0x00, 0x00, 0x00, 0x00,
+	0x04, 0x00, 0x04, 0x00, 0x00, 0x02, 0x05, 0x44, 0x7c, 0x67, 0xb8, 0x05,
+	0x00, 0x3b,
+}
diff --git a/core/artwork/e2e/album_test.go b/core/artwork/e2e/album_test.go
index 5e61684cc..7b5e7b4a3 100644
--- a/core/artwork/e2e/album_test.go
+++ b/core/artwork/e2e/album_test.go
@@ -1,4 +1,4 @@
-package artworke2e_test
+package e2e
 
 import (
 	"testing/fstest"
@@ -9,14 +9,11 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-const (
-	defaultCoverPriority = "cover.*, folder.*, front.*, embedded, external"
-	defaultDiscPriority  = "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded"
-)
-
+// The in-memory library FS cannot satisfy the os.Open(SourcePath) used to serve folder art, so
+// folder scenarios assert on the worker's state row (Source + SourcePath) instead of the bytes.
 var _ = Describe("Album artwork resolution", func() {
 	BeforeEach(func() {
-		setupHarness()
+		setupResolutionHarness()
 	})
 
 	When("an album has a single folder with cover.jpg at the album root", func() {
@@ -28,12 +25,10 @@ var _ = Describe("Album artwork resolution", func() {
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("album-root"),
+				"Artist/Album/cover.jpg":      smallPNG("album-root"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/cover.jpg")
 		})
 	})
 
@@ -55,16 +50,16 @@ var _ = Describe("Album artwork resolution", func() {
 			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"),
+				"Artist/Album/cover.jpg":          smallPNG("album-root"),
+				"Artist/Album/CD1/cover.jpg":      smallPNG("disc1"),
+				"Artist/Album/CD2/cover.jpg":      smallPNG("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")))
+				"sanity check: the two disc subfolders should form one multi-disc album")
+			expectAlbumFolderCover(al, "Artist/Album/cover.jpg")
 		})
 	})
 
@@ -86,14 +81,12 @@ var _ = Describe("Album artwork resolution", func() {
 			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"),
+				"Artist/Album/folder.jpg":         smallPNG("album-root"),
+				"Artist/Album/CD1/folder.jpg":     smallPNG("disc1"),
+				"Artist/Album/CD2/folder.jpg":     smallPNG("disc2"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/folder.jpg")
 		})
 	})
 
@@ -109,12 +102,10 @@ var _ = Describe("Album artwork resolution", func() {
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			setLayout(fstest.MapFS{
 				"Artist/Album/disc1/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":            imageFile("album-root"),
+				"Artist/Album/cover.jpg":            smallPNG("album-root"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/cover.jpg")
 		})
 	})
 
@@ -133,14 +124,12 @@ var _ = Describe("Album artwork resolution", func() {
 			setLayout(fstest.MapFS{
 				"Album/CD1/01 - Track.mp3": trackFile(1, "Track CD1"),
 				"Album/CD2/01 - Track.mp3": trackFile(1, "Track CD2"),
-				"Album/cover.jpg":          imageFile("album-root"),
-				"Album/CD1/folder.jpg":     imageFile("disc1"),
-				"Album/CD2/folder.jpg":     imageFile("disc2"),
+				"Album/cover.jpg":          smallPNG("album-root"),
+				"Album/CD1/folder.jpg":     smallPNG("disc1"),
+				"Album/CD2/folder.jpg":     smallPNG("disc2"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root")))
+			expectAlbumFolderCover(firstAlbum(), "Album/cover.jpg")
 		})
 	})
 
@@ -153,14 +142,14 @@ var _ = Describe("Album artwork resolution", 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"),
+				"Artist/Album/cover.jpg":      smallPNG("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))
+			ia := acquire(model.KindAlbumArtwork, firstAlbum().ID)
+			Expect(ia.Source).To(Equal("embedded"))
+			Expect(storedBytes(ia)).To(Equal(embeddedArtBytes))
 		})
 	})
 
@@ -176,8 +165,9 @@ var _ = Describe("Album artwork resolution", func() {
 			scan()
 			replaceWithRealMP3("Artist/Album/01 - Track.mp3")
 
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(embeddedArtBytes))
+			ia := acquire(model.KindAlbumArtwork, firstAlbum().ID)
+			Expect(ia.Source).To(Equal("embedded"))
+			Expect(storedBytes(ia)).To(Equal(embeddedArtBytes))
 		})
 	})
 
@@ -190,12 +180,10 @@ var _ = Describe("Album artwork resolution", func() {
 			conf.Server.CoverArtPriority = "cover.*, folder.*"
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/Cover.JPG":      imageFile("case-insensitive"),
+				"Artist/Album/Cover.JPG":      smallPNG("case-insensitive"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("case-insensitive")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/Cover.JPG")
 		})
 	})
 
@@ -209,30 +197,25 @@ var _ = Describe("Album artwork resolution", 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"),
+				"Artist/Album/cover.jpg":      smallPNG("primary"),
+				"Artist/Album/cover.1.jpg":    smallPNG("secondary"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("primary")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/cover.jpg")
 		})
 	})
 
 	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() {
+		//     └── 01 - Track.mp3       (no image files — settles absent)
+		It("settles absent", 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())
+			expectAlbumAbsent(firstAlbum())
 		})
 	})
 
@@ -248,12 +231,10 @@ var _ = Describe("Album artwork resolution", func() {
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/folder.jpg":     imageFile("folder"),
+				"Artist/Album/folder.jpg":     smallPNG("folder"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("folder")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/folder.jpg")
 		})
 	})
 
@@ -266,12 +247,10 @@ var _ = Describe("Album artwork resolution", func() {
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/front.jpg":      imageFile("front"),
+				"Artist/Album/front.jpg":      smallPNG("front"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("front")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/front.jpg")
 		})
 	})
 
@@ -286,14 +265,12 @@ var _ = Describe("Album artwork resolution", 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"),
+				"Artist/Album/cover.jpg":      smallPNG("cover"),
+				"Artist/Album/folder.jpg":     smallPNG("folder"),
+				"Artist/Album/front.jpg":      smallPNG("front"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/cover.jpg")
 		})
 	})
 
@@ -307,13 +284,11 @@ var _ = Describe("Album artwork resolution", 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"),
+				"Artist/Album/folder.jpg":     smallPNG("folder"),
+				"Artist/Album/front.jpg":      smallPNG("front"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("folder")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/folder.jpg")
 		})
 	})
 
@@ -328,14 +303,12 @@ var _ = Describe("Album artwork resolution", 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"),
+				"Artist/Album/cover.2.jpg":    smallPNG("second"),
+				"Artist/Album/cover.jpg":      smallPNG("primary"),
+				"Artist/Album/cover.1.jpg":    smallPNG("first"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("primary")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/cover.jpg")
 		})
 	})
 
@@ -348,12 +321,10 @@ var _ = Describe("Album artwork resolution", func() {
 			conf.Server.CoverArtPriority = "bogus.*, cover.*"
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("cover"),
+				"Artist/Album/cover.jpg":      smallPNG("cover"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/cover.jpg")
 		})
 	})
 
@@ -371,21 +342,16 @@ var _ = Describe("Album artwork resolution", func() {
 		It("does not use the artist image as album art", func() {
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			setLayout(fstest.MapFS{
-				"Artist/folder.jpg":             imageFile("artist-thumbnail"),
+				"Artist/folder.jpg":             smallPNG("artist-thumbnail"),
 				"Artist/Album A/01 - Track.mp3": trackFile(1, "Track A", map[string]any{"album": "Album A", "albumartist": "Artist"}),
 				"Artist/Album B/01 - Track.mp3": trackFile(1, "Track B", map[string]any{"album": "Album B", "albumartist": "Artist"}),
-				"Artist/Album B/cover.jpg":      imageFile("album-b"),
+				"Artist/Album B/cover.jpg":      smallPNG("album-b"),
 			})
 			scan()
 
-			alA := albumByName("Album A")
-			_, err := readArtworkOrErr(alA.CoverArtID())
-			Expect(err).To(HaveOccurred(),
-				"Album A has no images of its own, so it must fall through to the placeholder "+
-					"instead of inheriting the artist folder's folder.jpg")
-
-			alB := albumByName("Album B")
-			Expect(readArtwork(alB.CoverArtID())).To(Equal(imageBytes("album-b")))
+			// Album B first: the acquire in expectAlbumAbsent would settle Album B too.
+			expectAlbumFolderCover(albumByName("Album B"), "Artist/Album B/cover.jpg")
+			expectAlbumAbsent(albumByName("Album A"))
 		})
 	})
 
@@ -402,21 +368,58 @@ var _ = Describe("Album artwork resolution", func() {
 		It("does not use the artist image as album art for the spread album", func() {
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			setLayout(fstest.MapFS{
-				"Artist/folder.jpg":                   imageFile("artist-thumbnail"),
+				"Artist/folder.jpg":                   smallPNG("artist-thumbnail"),
 				"Artist/Album A/01 - Track.mp3":       trackFile(1, "Track A1", map[string]any{"album": "Album A", "albumartist": "Artist"}),
 				"Artist/Album A bonus/02 - Track.mp3": trackFile(2, "Track A2", map[string]any{"album": "Album A", "albumartist": "Artist"}),
 				"Artist/Album B/01 - Track.mp3":       trackFile(1, "Track B", map[string]any{"album": "Album B", "albumartist": "Artist"}),
-				"Artist/Album B/cover.jpg":            imageFile("album-b"),
+				"Artist/Album B/cover.jpg":            smallPNG("album-b"),
 			})
 			scan()
 
 			alA := albumByName("Album A")
 			Expect(alA.FolderIDs).To(HaveLen(2),
-				"sanity check: scanner should treat the two sibling folders as one spread album")
-			_, err := readArtworkOrErr(alA.CoverArtID())
-			Expect(err).To(HaveOccurred(),
-				"the spread album has no images of its own, so it must fall through to the "+
-					"placeholder instead of inheriting the artist folder's folder.jpg")
+				"sanity check: the two sibling folders should form one spread album")
+			expectAlbumAbsent(alA)
+		})
+	})
+
+	// albumRootParent refuses the library root as an album root (parent.ParentID == "").
+	When("a multi-disc album sits directly at the library root with a cover.jpg beside it", func() {
+		// (library root)
+		// ├── cover.jpg                ← must NOT be adopted
+		// ├── CD1/
+		// │   └── 01 - Track.mp3
+		// └── CD2/
+		//     └── 01 - Track.mp3
+		It("does not adopt the library-root image as album art", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"cover.jpg":          smallPNG("library-root"),
+				"CD1/01 - Track.mp3": trackFile(1, "T1", map[string]any{"album": "Rootless", "disc": "1"}),
+				"CD2/01 - Track.mp3": trackFile(1, "T2", map[string]any{"album": "Rootless", "disc": "2"}),
+			})
+			scan()
+			expectAlbumAbsent(firstAlbum())
+		})
+	})
+
+	// The shallower artist-folder cover.jpg would win the basename tie, but albumRootParent skips
+	// the parent folder for a single-folder album that has images of its own.
+	When("a single-folder album has its own cover.jpg and the artist folder has one too", func() {
+		// Artist/
+		// ├── cover.jpg                ← shallower, but must NOT win
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── cover.jpg            ← should win
+		It("prefers the album's own cover over the shallower artist-folder cover", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/cover.jpg":            smallPNG("artist-image"),
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist"}),
+				"Artist/Album/cover.jpg":      smallPNG("album-own"),
+			})
+			scan()
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/cover.jpg")
 		})
 	})
 
@@ -430,13 +433,13 @@ var _ = Describe("Album artwork resolution", func() {
 		// ├── Album A bonus/
 		// │   └── 02 - Track.mp3       (album: "Album A")
 		// └── Album B/
-		//     └── 01 - Track.mp3
+		//     └── 01 - Track.mp3       (other-album audio: rejects the artist folder as a root)
 		It("prefers the album's own art over the artist image", func() {
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			setLayout(fstest.MapFS{
-				"Artist/cover.jpg":                    imageFile("artist-image"),
+				"Artist/cover.jpg":                    smallPNG("artist-image"),
 				"Artist/Album A/01 - Track.mp3":       trackFile(1, "Track A1", map[string]any{"album": "Album A", "albumartist": "Artist"}),
-				"Artist/Album A/front.jpg":            imageFile("album-a-front"),
+				"Artist/Album A/front.jpg":            smallPNG("album-a-front"),
 				"Artist/Album A bonus/02 - Track.mp3": trackFile(2, "Track A2", map[string]any{"album": "Album A", "albumartist": "Artist"}),
 				"Artist/Album B/01 - Track.mp3":       trackFile(1, "Track B", map[string]any{"album": "Album B", "albumartist": "Artist"}),
 			})
@@ -444,8 +447,8 @@ var _ = Describe("Album artwork resolution", func() {
 
 			alA := albumByName("Album A")
 			Expect(alA.FolderIDs).To(HaveLen(2),
-				"sanity check: scanner should treat the two sibling folders as one spread album")
-			Expect(readArtwork(alA.CoverArtID())).To(Equal(imageBytes("album-a-front")))
+				"sanity check: the two sibling folders should form one spread album")
+			expectAlbumFolderCover(alA, "Artist/Album A/front.jpg")
 		})
 	})
 
@@ -458,12 +461,10 @@ var _ = Describe("Album artwork resolution", func() {
 			conf.Server.CoverArtPriority = "embedded, cover.*"
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("cover"),
+				"Artist/Album/cover.jpg":      smallPNG("cover"),
 			})
 			scan()
-
-			al := firstAlbum()
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("cover")))
+			expectAlbumFolderCover(firstAlbum(), "Artist/Album/cover.jpg")
 		})
 	})
 })
diff --git a/core/artwork/e2e/artist_test.go b/core/artwork/e2e/artist_test.go
index 2079d37ce..5a9396cc3 100644
--- a/core/artwork/e2e/artist_test.go
+++ b/core/artwork/e2e/artist_test.go
@@ -1,4 +1,4 @@
-package artworke2e_test
+package e2e
 
 import (
 	"os"
@@ -8,6 +8,7 @@ import (
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -16,9 +17,11 @@ import (
 // Doc reference:
 // https://www.navidrome.org/docs/usage/library/artwork/#artists
 // Default ArtistArtPriority is "artist.*, album/artist.*, external".
+// Library-folder images are file-backed (asserted on the worker state row); uploaded and
+// image-folder images are real files on disk (asserted byte-for-byte).
 var _ = Describe("Artist artwork resolution", func() {
 	BeforeEach(func() {
-		setupHarness()
+		setupResolutionHarness()
 	})
 
 	When("the artist folder contains an artist.jpg", func() {
@@ -30,13 +33,10 @@ var _ = Describe("Artist artwork resolution", 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/artist.jpg":           smallPNG("artist-folder"),
 			})
 			scan()
-
-			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-folder")))
+			expectArtistFolder(soleArtist(), "Artist/artist.jpg")
 		})
 	})
 
@@ -49,13 +49,10 @@ var _ = Describe("Artist artwork resolution", 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"),
+				"Artist/Album/artist.jpg":     smallPNG("album-artist"),
 			})
 			scan()
-
-			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("album-artist")))
+			expectArtistFolder(soleArtist(), "Artist/Album/artist.jpg")
 		})
 	})
 
@@ -69,14 +66,11 @@ var _ = Describe("Artist artwork resolution", 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"),
+				"Artist/artist.jpg":           smallPNG("artist-folder"),
+				"Artist/Album/artist.jpg":     smallPNG("album-artist"),
 			})
 			scan()
-
-			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-folder")))
+			expectArtistFolder(soleArtist(), "Artist/artist.jpg")
 		})
 	})
 
@@ -89,13 +83,10 @@ var _ = Describe("Artist artwork resolution", func() {
 			conf.Server.ArtistArtPriority = "artist.*"
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist"}),
-				"Artist/artist.jpg":           imageFile("artist-folder"),
+				"Artist/artist.jpg":           smallPNG("artist-folder"),
 			})
 			scan()
-
-			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-folder")))
+			expectArtistFolder(soleArtist(), "Artist/artist.jpg")
 		})
 	})
 
@@ -111,14 +102,11 @@ var _ = Describe("Artist artwork resolution", func() {
 			setLayout(fstest.MapFS{
 				"Artist/Album/CD1/01 - Track.mp3": trackFile(1, "Track 1", map[string]any{"albumartist": "Artist", "album": "Album"}),
 				"Artist/Album/CD2/02 - Track.mp3": trackFile(2, "Track 2", map[string]any{"albumartist": "Artist", "album": "Album"}),
-				"Artist/artist.jpg":               imageFile("artist-folder"),
-				"Artist/Album/artist.jpg":         imageFile("album-artist"),
+				"Artist/artist.jpg":               smallPNG("artist-folder"),
+				"Artist/Album/artist.jpg":         smallPNG("album-artist"),
 			})
 			scan()
-
-			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-folder")))
+			expectArtistFolder(soleArtist(), "Artist/artist.jpg")
 		})
 	})
 
@@ -136,14 +124,11 @@ var _ = Describe("Artist artwork resolution", func() {
 				"Artist/Album1/CD1/01 - Track.mp3": trackFile(1, "Track 1", map[string]any{"albumartist": "Artist", "album": "Album1"}),
 				"Artist/Album1/CD2/02 - Track.mp3": trackFile(2, "Track 2", map[string]any{"albumartist": "Artist", "album": "Album1"}),
 				"Artist/Album2/03 - Track.mp3":     trackFile(3, "Track 3", map[string]any{"albumartist": "Artist", "album": "Album2"}),
-				"Artist/artist.jpg":                imageFile("artist-folder"),
-				"Artist/Album1/artist.jpg":         imageFile("album-artist"),
+				"Artist/artist.jpg":                smallPNG("artist-folder"),
+				"Artist/Album1/artist.jpg":         smallPNG("album-artist"),
 			})
 			scan()
-
-			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-folder")))
+			expectArtistFolder(soleArtist(), "Artist/artist.jpg")
 		})
 	})
 
@@ -164,14 +149,11 @@ var _ = Describe("Artist artwork resolution", func() {
 				"Artist/Album1/CD2/02 - Track.mp3": trackFile(2, "Track 2", map[string]any{"albumartist": "Artist", "album": "Album1"}),
 				"Artist/Album2/CD1/03 - Track.mp3": trackFile(3, "Track 3", map[string]any{"albumartist": "Artist", "album": "Album2"}),
 				"Artist/Album2/CD2/04 - Track.mp3": trackFile(4, "Track 4", map[string]any{"albumartist": "Artist", "album": "Album2"}),
-				"Artist/artist.jpg":                imageFile("artist-folder"),
-				"Artist/Album1/artist.jpg":         imageFile("album-artist"),
+				"Artist/artist.jpg":                smallPNG("artist-folder"),
+				"Artist/Album1/artist.jpg":         smallPNG("album-artist"),
 			})
 			scan()
-
-			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-folder")))
+			expectArtistFolder(soleArtist(), "Artist/artist.jpg")
 		})
 	})
 
@@ -189,18 +171,19 @@ var _ = Describe("Artist artwork resolution", 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/artist.jpg":           smallPNG("artist-folder"),
 			})
 			scan()
 			ar := soleArtist()
 
 			uploaded := ar.ID + "_upload.jpg"
-			writeUploadedImage(consts.EntityArtist, uploaded, imageBytes("artist-uploaded"))
+			writeUploadedImage(consts.EntityArtist, uploaded, pngBytes("artist-uploaded"))
 			ar.UploadedImage = uploaded
-			Expect(ds.Artist(ctx).Put(&ar)).To(Succeed())
+			Expect(rds.Artist(rctx).Put(&ar)).To(Succeed())
 
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("artist-uploaded")))
+			ia := acquire(model.KindArtistArtwork, ar.ID)
+			Expect(ia.Source).To(Equal("upload"))
+			Expect(serveBytes(model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil))).To(Equal(pngBytes("artist-uploaded")))
 		})
 	})
 
@@ -213,13 +196,36 @@ var _ = Describe("Artist artwork resolution", 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"),
+				"Artist/Album/artist.jpg":     smallPNG("album-artist"),
 			})
 			scan()
+			expectArtistFolder(soleArtist(), "Artist/Album/artist.jpg")
+		})
+	})
+
+	// resolveArtist only samples albums where this artist is the SOLE album artist, so a
+	// collaboration or compilation never donates its images as the artist's own.
+	When("the artist's only album is credited to two album artists", func() {
+		// Artist/
+		// └── Collab Album/            (album artists: "Artist" + a collaborator)
+		//     ├── 01 - Track.mp3
+		//     └── artist.jpg           ← must NOT become the artist image
+		It("ignores the album's images and settles absent", func() {
+			conf.Server.ArtistArtPriority = "album/artist.*"
+			// " / " is a default artists split separator, so this single tag yields two album artists.
+			setLayout(fstest.MapFS{
+				"Artist/Collab Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"albumartist": "Artist / Collaborator"}),
+				"Artist/Collab Album/artist.jpg":     smallPNG("collab-artist"),
+			})
+			scan()
+			Expect(firstAlbum().Participants[model.RoleAlbumArtist]).To(HaveLen(2),
+				"sanity check: the album must be credited to two album artists")
 
 			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("album-artist")))
+			ia := acquire(model.KindArtistArtwork, ar.ID)
+			Expect(ia.Hash).To(BeEmpty())
+			Expect(serveErr(model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil))).
+				To(MatchError(artwork.ErrUnavailable))
 		})
 	})
 
@@ -232,7 +238,7 @@ var _ = Describe("Artist artwork resolution", func() {
 		//     └── 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())
+			Expect(os.WriteFile(filepath.Join(imgFolder, "Artist.jpg"), pngBytes("image-folder"), 0o600)).To(Succeed())
 			conf.Server.ArtistImageFolder = imgFolder
 			conf.Server.ArtistArtPriority = "image-folder, artist.*, album/artist.*"
 
@@ -242,15 +248,16 @@ var _ = Describe("Artist artwork resolution", func() {
 			scan()
 
 			ar := soleArtist()
-			artID := model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("image-folder")))
+			ia := acquire(model.KindArtistArtwork, ar.ID)
+			Expect(ia.Source).To(Equal("folder"))
+			Expect(serveBytes(model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil))).To(Equal(pngBytes("image-folder")))
 		})
 	})
 })
 
 func soleArtist() model.Artist {
 	GinkgoHelper()
-	artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
+	artists, err := rds.Artist(rctx).GetAll(model.QueryOptions{
 		Filters: squirrel.Eq{"artist.name": "Artist"},
 	})
 	Expect(err).ToNot(HaveOccurred())
diff --git a/core/artwork/e2e/disc_test.go b/core/artwork/e2e/disc_test.go
index 667079458..5fdd5f27b 100644
--- a/core/artwork/e2e/disc_test.go
+++ b/core/artwork/e2e/disc_test.go
@@ -1,18 +1,20 @@
-package artworke2e_test
+package e2e
 
 import (
 	"fmt"
 	"testing/fstest"
 
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/core/artwork"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
+// Disc art is a serve-time read through the library FS (no worker state row), so per-disc images
+// are asserted byte-for-byte, while album-root covers are asserted on the state row.
 var _ = Describe("Disc artwork resolution", func() {
 	BeforeEach(func() {
-		setupHarness()
+		setupResolutionHarness()
 	})
 
 	When("the album is single-disc with a disc1.jpg in the only folder", func() {
@@ -24,32 +26,25 @@ var _ = Describe("Disc artwork resolution", 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"),
+				"Artist/Album/disc1.jpg":      smallPNG("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")))
+			expectDiscImage(firstAlbum(), 1, "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() {
+		//     └── 01 - Track.mp3       (no disc or album art — nothing to serve)
+		It("reports the disc lookup as unavailable", 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())
+			Expect(serveErr(discArtID(firstAlbum(), 1))).To(MatchError(artwork.ErrUnavailable))
 		})
 	})
 
@@ -63,13 +58,10 @@ var _ = Describe("Disc artwork resolution", func() {
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("album-cover"),
+				"Artist/Album/cover.jpg":      smallPNG("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")))
+			expectDiscImage(firstAlbum(), 1, "album-cover")
 		})
 	})
 
@@ -83,14 +75,11 @@ var _ = Describe("Disc artwork resolution", 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"),
+				"Artist/Album/disc1.jpg":      smallPNG("disc-one"),
+				"Artist/Album/disc10.jpg":     smallPNG("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")))
+			expectDiscImage(firstAlbum(), 1, "disc-one")
 		})
 	})
 
@@ -108,14 +97,11 @@ var _ = Describe("Disc artwork resolution", func() {
 			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/CD1/disc1.jpg":      smallPNG("disc-1"),
+				"Artist/Album/CD2/disc2.jpg":      smallPNG("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")))
+			expectDiscImage(firstAlbum(), 2, "disc-2")
 		})
 	})
 
@@ -136,14 +122,11 @@ var _ = Describe("Disc artwork resolution", func() {
 			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/CD1/disc1.jpg":      smallPNG("disc-1"),
+				"Artist/Album/CD2/cd2.png":        smallPNG("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")))
+			expectDiscImage(firstAlbum(), 2, "cd-2")
 		})
 	})
 
@@ -161,14 +144,11 @@ var _ = Describe("Disc artwork resolution", func() {
 			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"),
+				"Artist/Album/CD1/cover.jpg":      smallPNG("disc1-cover"),
+				"Artist/Album/CD2/cover.jpg":      smallPNG("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")))
+			expectDiscImage(firstAlbum(), 1, "disc1-cover")
 		})
 	})
 
@@ -188,17 +168,15 @@ var _ = Describe("Disc artwork resolution", func() {
 			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"),
+				"Artist/Album/CD1/disc1.jpg":      smallPNG("disc-1"),
+				"Artist/Album/CD2/cd2.png":        smallPNG("cd-2"),
+				"Artist/Album/cover.jpg":          smallPNG("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)
+				expectDiscImage(al, n, "album-cover")
 			}
 		})
 	})
@@ -223,17 +201,15 @@ var _ = Describe("Disc artwork resolution", func() {
 				"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"),
+				"Artist/Album/disc1/disc1.jpg":      smallPNG("disc-1"),
+				"Artist/Album/disc2/cd2.png":        smallPNG("cd-2"),
+				"Artist/Album/cover.jpg":            smallPNG("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")))
+			expectDiscImage(al, 1, "disc-1")
+			expectDiscImage(al, 2, "cd-2")
 		})
 	})
 
@@ -246,13 +222,10 @@ var _ = Describe("Disc artwork resolution", 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"),
+				"Artist/Album/Bonus Tracks.jpg": smallPNG("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")))
+			expectDiscImage(firstAlbum(), 1, "bonus-tracks")
 		})
 	})
 
@@ -286,26 +259,22 @@ var _ = Describe("Disc artwork resolution", func() {
 				"Disc 12 (History of the Grateful Dead, Volume One (Bear's Choice))",
 			}
 			layout := fstest.MapFS{
-				"Pop; Rock/Grateful Dead/(2001) The Golden Road/cover.jpg": imageFile("album-root-cover"),
+				"Pop; Rock/Grateful Dead/(2001) The Golden Road/cover.jpg": smallPNG("album-root-cover"),
 			}
 			for i, name := range discNames {
 				discNum := i + 1
 				prefix := fmt.Sprintf("Pop; Rock/Grateful Dead/(2001) The Golden Road/%s/", name)
 				layout[prefix+"01 - Track.mp3"] = trackFile(1, fmt.Sprintf("T%d", discNum), map[string]any{"disc": fmt.Sprintf("%d", discNum)})
-				layout[prefix+"folder.jpg"] = imageFile(fmt.Sprintf("disc-%02d-folder", discNum))
+				layout[prefix+"folder.jpg"] = smallPNG(fmt.Sprintf("disc-%02d-folder", discNum))
 			}
 			setLayout(layout)
 			scan()
 
 			al := firstAlbum()
-
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root-cover")))
-
+			expectAlbumFolderCover(al, "(2001) The Golden Road/cover.jpg")
 			for i := range discNames {
 				discNum := i + 1
-				discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, discNum), &al.UpdatedAt)
-				Expect(readArtwork(discID)).To(Equal(imageBytes(fmt.Sprintf("disc-%02d-folder", discNum))),
-					"disc %d should use its own folder.jpg", discNum)
+				expectDiscImage(al, discNum, fmt.Sprintf("disc-%02d-folder", discNum))
 			}
 		})
 	})
@@ -328,24 +297,20 @@ var _ = Describe("Disc artwork resolution", func() {
 			conf.Server.DiscArtPriority = defaultDiscPriority
 			conf.Server.CoverArtPriority = defaultCoverPriority
 			layout := fstest.MapFS{
-				"Album/cover.jpg": imageFile("album-root-cover"),
+				"Album/cover.jpg": smallPNG("album-root-cover"),
 			}
 			for i := 1; i <= 3; i++ {
 				prefix := fmt.Sprintf("Album/Disc %02d/", i)
 				layout[prefix+"01 - Track.mp3"] = trackFile(1, fmt.Sprintf("T%d", i), map[string]any{"disc": fmt.Sprintf("%d", i)})
-				layout[prefix+"folder.jpg"] = imageFile(fmt.Sprintf("disc-%02d-folder", i))
+				layout[prefix+"folder.jpg"] = smallPNG(fmt.Sprintf("disc-%02d-folder", i))
 			}
 			setLayout(layout)
 			scan()
 
 			al := firstAlbum()
-
-			Expect(readArtwork(al.CoverArtID())).To(Equal(imageBytes("album-root-cover")))
-
+			expectAlbumFolderCover(al, "Album/cover.jpg")
 			for i := 1; i <= 3; i++ {
-				discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, i), &al.UpdatedAt)
-				Expect(readArtwork(discID)).To(Equal(imageBytes(fmt.Sprintf("disc-%02d-folder", i))),
-					"disc %d should use its own folder.jpg", i)
+				expectDiscImage(al, i, fmt.Sprintf("disc-%02d-folder", i))
 			}
 		})
 	})
@@ -359,13 +324,10 @@ var _ = Describe("Disc artwork resolution", 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"),
+				"Artist/Album/cover.jpg":      smallPNG("cover"),
 			})
 			scan()
-
-			al := firstAlbum()
-			discID := model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, 1), &al.UpdatedAt)
-			Expect(readArtwork(discID)).To(Equal(imageBytes("cover")))
+			expectDiscImage(firstAlbum(), 1, "cover")
 		})
 	})
 })
diff --git a/core/artwork/e2e/e2e_suite_test.go b/core/artwork/e2e/e2e_suite_test.go
new file mode 100644
index 000000000..8881da3a6
--- /dev/null
+++ b/core/artwork/e2e/e2e_suite_test.go
@@ -0,0 +1,83 @@
+// Package e2e exercises the artwork pipeline end to end: the real Worker drains the queue and the
+// real Service serves the result, over a real ImageStore and real library files.
+package e2e
+
+import (
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	_ "github.com/navidrome/navidrome/adapters/gotaglib" // registers the "taglib" local-storage extractor
+	"github.com/navidrome/navidrome/core/artwork"
+	_ "github.com/navidrome/navidrome/core/storage/local"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"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 Pipeline E2E Suite")
+}
+
+// Fixtures relative to the project root (tests.Init chdirs there).
+const (
+	coverFixture     = "tests/fixtures/artist/an-album/cover.jpg"
+	mp3Fixture       = "tests/fixtures/artist/an-album/test.mp3"
+	artistPngFixture = "tests/fixtures/artist/an-album/artist.png"
+	albumFolderPath  = "tests/fixtures/artist/an-album"
+)
+
+func readFixture(rel string) []byte {
+	GinkgoHelper()
+	data, err := os.ReadFile(rel)
+	Expect(err).ToNot(HaveOccurred(), "reading fixture %q", rel)
+	return data
+}
+
+func readAll(img *artwork.Image) []byte {
+	GinkgoHelper()
+	Expect(img).ToNot(BeNil())
+	defer img.Close()
+	data, err := io.ReadAll(img)
+	Expect(err).ToNot(HaveOccurred())
+	return data
+}
+
+func runWorkerUntil(ctx context.Context, worker *artwork.Worker, until func() bool) {
+	GinkgoHelper()
+	runCtx, cancel := context.WithCancel(ctx)
+	done := make(chan error, 1)
+	go func() { done <- worker.Run(runCtx) }()
+	Eventually(until, 5*time.Second, 10*time.Millisecond).Should(BeTrue())
+	cancel()
+	Eventually(done, 2*time.Second).Should(Receive(BeNil()))
+}
+
+type fakeFolderRepo struct {
+	model.FolderRepository
+	result []model.Folder
+}
+
+func (f *fakeFolderRepo) GetAll(...model.QueryOptions) ([]model.Folder, error) { return f.result, nil }
+
+func (f *fakeFolderRepo) HasAudioOutsideFolders(model.Folder, []string) (bool, error) {
+	return false, nil
+}
+
+func (f *fakeFolderRepo) Get(string) (*model.Folder, error) { return nil, model.ErrNotFound }
+
+func writeUpload(entityType, name, srcFixture string) string {
+	GinkgoHelper()
+	dst := model.UploadedImagePath(entityType, name)
+	Expect(os.MkdirAll(filepath.Dir(dst), 0o755)).To(Succeed())
+	Expect(os.WriteFile(dst, readFixture(srcFixture), 0o600)).To(Succeed())
+	return name
+}
diff --git a/core/artwork/e2e/helpers_test.go b/core/artwork/e2e/helpers_test.go
deleted file mode 100644
index ddc926cec..000000000
--- a/core/artwork/e2e/helpers_test.go
+++ /dev/null
@@ -1,184 +0,0 @@
-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, 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)
diff --git a/core/artwork/e2e/mediafile_test.go b/core/artwork/e2e/mediafile_test.go
index 1f43a3827..d26756dcd 100644
--- a/core/artwork/e2e/mediafile_test.go
+++ b/core/artwork/e2e/mediafile_test.go
@@ -1,4 +1,4 @@
-package artworke2e_test
+package e2e
 
 import (
 	"testing/fstest"
@@ -17,13 +17,11 @@ import (
 //  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() {
+// Embedded art lands in the content-addressed store (asserted byte-for-byte); disc-level art is a
+// serve-time read through the library FS.
+var _ = Describe("MediaFile artwork resolution", func() {
 	BeforeEach(func() {
-		setupHarness()
+		setupResolutionHarness()
 	})
 
 	When("a multi-disc album track has no embedded art", func() {
@@ -42,14 +40,14 @@ var _ = Describe("MediaFile artwork fallback", func() {
 			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"),
+				"Artist/Album/CD1/disc1.jpg":      smallPNG("disc-1"),
+				"Artist/Album/CD2/disc2.jpg":      smallPNG("disc-2"),
+				"Artist/Album/cover.jpg":          smallPNG("album-root"),
 			})
 			scan()
 
 			mf := mediafileOn("Artist/Album/CD2/01 - Track.mp3")
-			Expect(readArtwork(mf.CoverArtID())).To(Equal(imageBytes("disc-2")))
+			Expect(serveBytes(mf.CoverArtID())).To(Equal(pngBytes("disc-2")))
 		})
 	})
 
@@ -63,12 +61,12 @@ var _ = Describe("MediaFile artwork fallback", func() {
 			conf.Server.DiscArtPriority = defaultDiscPriority
 			setLayout(fstest.MapFS{
 				"Artist/Album/01 - Track.mp3": trackFile(1, "Track"),
-				"Artist/Album/cover.jpg":      imageFile("album-cover"),
+				"Artist/Album/cover.jpg":      smallPNG("album-cover"),
 			})
 			scan()
 
 			mf := mediafileOn("Artist/Album/01 - Track.mp3")
-			Expect(readArtwork(mf.CoverArtID())).To(Equal(imageBytes("album-cover")))
+			Expect(serveBytes(mf.CoverArtID())).To(Equal(pngBytes("album-cover")))
 		})
 	})
 
@@ -86,19 +84,60 @@ var _ = Describe("MediaFile artwork fallback", func() {
 			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"),
+				"Artist/Album/cover.jpg":          smallPNG("album-root"),
 			})
 			scan()
 
 			mf := mediafileOn("Artist/Album/CD2/01 - Track.mp3")
-			Expect(readArtwork(mf.CoverArtID())).To(Equal(imageBytes("album-root")))
+			Expect(serveBytes(mf.CoverArtID())).To(Equal(pngBytes("album-root")))
+		})
+	})
+
+	When("a track has its own embedded art", func() {
+		// Artist/
+		// └── Album/
+		//     └── 01 - Track.mp3       ← has embedded picture (wins over every fallback)
+		It("resolves the track's embedded image into the store", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"has_picture": "true"}),
+			})
+			scan()
+			replaceWithRealMP3("Artist/Album/01 - Track.mp3")
+
+			mf := mediafileOn("Artist/Album/01 - Track.mp3")
+			ia := acquire(model.KindMediaFileArtwork, mf.ID)
+			Expect(ia.Source).To(Equal("embedded"))
+			Expect(storedBytes(ia)).To(Equal(embeddedArtBytes))
+		})
+	})
+
+	When("EnableMediaFileCoverArt is turned off after the track was scanned", func() {
+		// Artist/
+		// └── Album/
+		//     ├── 01 - Track.mp3       ← has embedded picture (must NOT be served)
+		//     └── cover.jpg            ← wins (per-track art disabled at serve time)
+		It("serves the album cover instead of the track's embedded art", func() {
+			conf.Server.CoverArtPriority = defaultCoverPriority
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track", map[string]any{"has_picture": "true"}),
+				"Artist/Album/cover.jpg":      smallPNG("album-cover"),
+			})
+			scan()
+			replaceWithRealMP3("Artist/Album/01 - Track.mp3")
+
+			// The setting is not part of the artwork fingerprint, so it must be honored at serve time.
+			conf.Server.EnableMediaFileCoverArt = false
+			mf := mediafileOn("Artist/Album/01 - Track.mp3")
+			trackArtID := model.NewArtworkID(model.KindMediaFileArtwork, mf.ID, nil)
+			Expect(serveBytes(trackArtID)).To(Equal(pngBytes("album-cover")))
 		})
 	})
 })
 
 func mediafileOn(relPath string) model.MediaFile {
 	GinkgoHelper()
-	mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	mfs, err := rds.MediaFile(rctx).GetAll(model.QueryOptions{
 		Filters: squirrel.Like{"media_file.path": relPath},
 	})
 	Expect(err).ToNot(HaveOccurred())
diff --git a/core/artwork/e2e/playlist_test.go b/core/artwork/e2e/playlist_test.go
index d28efca8e..f5ac8a7e3 100644
--- a/core/artwork/e2e/playlist_test.go
+++ b/core/artwork/e2e/playlist_test.go
@@ -1,13 +1,16 @@
-package artworke2e_test
+package e2e
 
 import (
+	"image/color"
 	"os"
 	"path/filepath"
 	"testing/fstest"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -17,14 +20,13 @@ import (
 //  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
+//  5. Absent
 //
-// 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.
+// The library is an in-memory FS, but uploaded/sidecar/local-external images are real files on
+// disk — the resolver reads them via os.Open, so those tests place them in a real tempdir.
 var _ = Describe("Playlist artwork resolution", func() {
 	BeforeEach(func() {
-		setupHarness()
+		setupResolutionHarness()
 	})
 
 	When("a playlist has an uploaded image", func() {
@@ -33,11 +35,12 @@ var _ = Describe("Playlist artwork resolution", func() {
 		//     └── 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"))
-
+			writeUploadedImage(consts.EntityPlaylist, "pl-1_upload.jpg", pngBytes("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")))
+			ia := acquire(model.KindPlaylistArtwork, pl.ID)
+			Expect(ia.Source).To(Equal("upload"))
+			Expect(serveBytes(pl.CoverArtID())).To(Equal(pngBytes("playlist-upload")))
 		})
 	})
 
@@ -48,12 +51,14 @@ var _ = Describe("Playlist artwork resolution", func() {
 		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())
+			Expect(os.WriteFile(m3uPath, []byte("#EXTM3U\n"), 0o600)).To(Succeed())
+			Expect(os.WriteFile(filepath.Join(dir, "MyList.jpg"), pngBytes("sidecar"), 0o600)).To(Succeed())
 
 			pl := putPlaylist(model.Playlist{ID: "pl-2", Name: "MyList", Path: m3uPath})
 
-			Expect(readArtwork(pl.CoverArtID())).To(Equal(imageBytes("sidecar")))
+			ia := acquire(model.KindPlaylistArtwork, pl.ID)
+			Expect(ia.Source).To(Equal("folder"))
+			Expect(serveBytes(pl.CoverArtID())).To(Equal(pngBytes("sidecar")))
 		})
 	})
 
@@ -64,12 +69,12 @@ var _ = Describe("Playlist artwork resolution", func() {
 		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())
+			Expect(os.WriteFile(m3uPath, []byte("#EXTM3U\n"), 0o600)).To(Succeed())
+			Expect(os.WriteFile(filepath.Join(dir, "MyList.PNG"), pngBytes("sidecar-png"), 0o600)).To(Succeed())
 
 			pl := putPlaylist(model.Playlist{ID: "pl-3", Name: "MyList", Path: m3uPath})
 
-			Expect(readArtwork(pl.CoverArtID())).To(Equal(imageBytes("sidecar-png")))
+			Expect(serveBytes(pl.CoverArtID())).To(Equal(pngBytes("sidecar-png")))
 		})
 	})
 
@@ -80,31 +85,39 @@ var _ = Describe("Playlist artwork resolution", 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())
+			Expect(os.WriteFile(imgPath, pngBytes("external-local"), 0o600)).To(Succeed())
 
 			pl := putPlaylist(model.Playlist{ID: "pl-4", Name: "WithExt", ExternalImageURL: imgPath})
 
-			Expect(readArtwork(pl.CoverArtID())).To(Equal(imageBytes("external-local")))
+			Expect(serveBytes(pl.CoverArtID())).To(Equal(pngBytes("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() {
+		// (no local files — the http source is gated off, so resolution settles absent)
+		It("skips the URL and settles absent", 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()))
+			ia := acquire(model.KindPlaylistArtwork, pl.ID)
+			Expect(ia.Hash).To(BeEmpty())
+			Expect(serveErr(pl.CoverArtID())).To(MatchError(artwork.ErrUnavailable))
+
+			img, err := rsvc.GetOrPlaceholder(rctx, pl.CoverArtID().String(), 0, false)
+			Expect(err).ToNot(HaveOccurred())
+			defer img.Close()
+			Expect(img.Placeholder).To(BeTrue())
 		})
 	})
 
 	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() {
+		// (no uploaded/sidecar/external image and no album art to sample)
+		It("settles absent", func() {
 			pl := putPlaylist(model.Playlist{ID: "pl-6", Name: "Empty"})
 
-			Expect(readArtwork(pl.CoverArtID())).To(Equal(placeholderBytes()))
+			ia := acquire(model.KindPlaylistArtwork, pl.ID)
+			Expect(ia.Hash).To(BeEmpty())
+			Expect(serveErr(pl.CoverArtID())).To(MatchError(artwork.ErrUnavailable))
 		})
 	})
 
@@ -113,37 +126,79 @@ var _ = Describe("Playlist artwork resolution", func() {
 		// Artist/
 		// ├── AlbumA/
 		// │   ├── 01 - Track.mp3
-		// │   └── cover.png          (real PNG — wins as tile 1 source)
+		// │   └── cover.png          ← 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).
+		//     └── cover.png          ← tile 2 source
+		// Playlist "pl-7" references tracks from both albums, so the worker generates a tiled
+		// cover from 2 distinct album art tiles (mirrored to fill the 2x2 grid).
 		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/AlbumA/cover.png":      smallPNG("albumA"),
 				"Artist/AlbumB/01 - Track.mp3": trackFile(1, "TB", map[string]any{"album": "AlbumB"}),
-				"Artist/AlbumB/cover.png":      realPNG("albumB"),
+				"Artist/AlbumB/cover.png":      smallPNG("albumB"),
 			})
 			scan()
 
-			// Pull the scanned mediafile IDs so we can attach them to the playlist.
-			mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{})
+			mfs, err := rds.MediaFile(rctx).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())
+			Expect(rds.Playlist(rctx).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.
+			ia := acquire(model.KindPlaylistArtwork, pl.ID)
+			Expect(ia.Source).To(Equal("generated"))
+			data := storedBytes(ia)
+			// The tiled cover is a PNG-encoded image; exact bytes vary (random album order).
 			Expect(data[:8]).To(Equal([]byte{0x89, 'P', 'N', 'G', 0x0d, 0x0a, 0x1a, 0x0a}))
-			Expect(len(data)).To(BeNumerically(">", 1000))
+			// Two tiles are mirrored into the 2x2 grid as [A B B A], so opposite corners match.
+			q := gridQuadrants(data)
+			Expect(q[0]).To(Equal(q[3]))
+			Expect(q[1]).To(Equal(q[2]))
+			Expect(q[0]).ToNot(Equal(q[1]))
+		})
+	})
+
+	When("a playlist has tracks from four albums, each with its own cover", func() {
+		// Library:
+		// Artist/
+		// ├── AlbumA/{01 - Track.mp3, cover.png}   ← tile 1
+		// ├── AlbumB/{01 - Track.mp3, cover.png}   ← tile 2
+		// ├── AlbumC/{01 - Track.mp3, cover.png}   ← tile 3
+		// └── AlbumD/{01 - Track.mp3, cover.png}   ← tile 4
+		It("fills all four grid quadrants with distinct album art", func() {
+			conf.Server.CoverArtPriority = "cover.*"
+			layout := fstest.MapFS{}
+			for _, name := range []string{"AlbumA", "AlbumB", "AlbumC", "AlbumD"} {
+				layout["Artist/"+name+"/01 - Track.mp3"] = trackFile(1, "T"+name, map[string]any{"album": name})
+				layout["Artist/"+name+"/cover.png"] = smallPNG(name)
+			}
+			setLayout(layout)
+			scan()
+
+			mfs, err := rds.MediaFile(rctx).GetAll(model.QueryOptions{})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(mfs).To(HaveLen(4))
+			ids := slice.Map(mfs, func(mf model.MediaFile) string { return mf.ID })
+
+			pl := model.Playlist{ID: "pl-8", Name: "Four", OwnerID: "admin-1"}
+			pl.AddMediaFilesByID(ids)
+			Expect(rds.Playlist(rctx).Put(&pl)).To(Succeed())
+
+			ia := acquire(model.KindPlaylistArtwork, pl.ID)
+			Expect(ia.Source).To(Equal("generated"))
+			q := gridQuadrants(storedBytes(ia))
+			Expect([]color.RGBA{q[0], q[1], q[2], q[3]}).To(HaveLen(4))
+			Expect(q[0]).ToNot(Equal(q[1]))
+			Expect(q[0]).ToNot(Equal(q[2]))
+			Expect(q[0]).ToNot(Equal(q[3]))
+			Expect(q[1]).ToNot(Equal(q[2]))
+			Expect(q[1]).ToNot(Equal(q[3]))
+			Expect(q[2]).ToNot(Equal(q[3]))
 		})
 	})
 })
@@ -153,6 +208,6 @@ func putPlaylist(pl model.Playlist) model.Playlist {
 	if pl.OwnerID == "" {
 		pl.OwnerID = "admin-1"
 	}
-	Expect(ds.Playlist(ctx).Put(&pl)).To(Succeed())
+	Expect(rds.Playlist(rctx).Put(&pl)).To(Succeed())
 	return pl
 }
diff --git a/core/artwork/e2e/radio_test.go b/core/artwork/e2e/radio_test.go
index 73ee5f377..bba85224a 100644
--- a/core/artwork/e2e/radio_test.go
+++ b/core/artwork/e2e/radio_test.go
@@ -1,15 +1,18 @@
-package artworke2e_test
+package e2e
 
 import (
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
+// Radio art is uploaded-image-only, with no fallback. Uploads are real files on disk, so they
+// serve back byte-for-byte; a radio with no upload settles absent.
 var _ = Describe("Radio artwork resolution", func() {
 	BeforeEach(func() {
-		setupHarness()
+		setupResolutionHarness()
 	})
 
 	When("a radio has an uploaded image", func() {
@@ -18,25 +21,25 @@ var _ = Describe("Radio artwork resolution", func() {
 		//     └── 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"))
-
+			writeUploadedImage(consts.EntityRadio, "rd-1_logo.jpg", pngBytes("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())
+			Expect(rds.Radio(rctx).Put(&rd)).To(Succeed())
 
-			artID := model.NewArtworkID(model.KindRadioArtwork, rd.ID, nil)
-			Expect(readArtwork(artID)).To(Equal(imageBytes("radio-logo")))
+			ia := acquire(model.KindRadioArtwork, rd.ID)
+			Expect(ia.Source).To(Equal("upload"))
+			Expect(serveBytes(model.NewArtworkID(model.KindRadioArtwork, rd.ID, nil))).To(Equal(pngBytes("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() {
+		// (no files on disk — the resolver has no sources to fall back to)
+		It("settles absent", func() {
 			rd := model.Radio{ID: "rd-2", Name: "Bare Radio", StreamUrl: "https://example.com/stream"}
-			Expect(ds.Radio(ctx).Put(&rd)).To(Succeed())
+			Expect(rds.Radio(rctx).Put(&rd)).To(Succeed())
 
-			artID := model.NewArtworkID(model.KindRadioArtwork, rd.ID, nil)
-			_, err := readArtworkOrErr(artID)
-			Expect(err).To(HaveOccurred())
+			ia := acquire(model.KindRadioArtwork, rd.ID)
+			Expect(ia.Hash).To(BeEmpty())
+			Expect(serveErr(model.NewArtworkID(model.KindRadioArtwork, rd.ID, nil))).To(MatchError(artwork.ErrUnavailable))
 		})
 	})
 })
diff --git a/core/artwork/e2e/resolution_harness_test.go b/core/artwork/e2e/resolution_harness_test.go
new file mode 100644
index 000000000..1168393df
--- /dev/null
+++ b/core/artwork/e2e/resolution_harness_test.go
@@ -0,0 +1,365 @@
+package e2e
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"hash/fnv"
+	"image"
+	"image/color"
+	"image/png"
+	"io"
+	"maps"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing/fstest"
+	"time"
+
+	_ "github.com/navidrome/navidrome/adapters/gotaglib"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
+	"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/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/navidrome/navidrome/tests/harness"
+	"github.com/navidrome/navidrome/utils/cache"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"go.senan.xyz/taglib"
+)
+
+const fakeLibScheme = "artworkfake"
+const fakeLibPath = fakeLibScheme + ":///music"
+
+const (
+	defaultCoverPriority = "cover.*, folder.*, front.*, embedded, external"
+	defaultDiscPriority  = "disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded"
+)
+
+var (
+	rctx    context.Context
+	rds     *tests.MockDataStore
+	rstore  *artwork.ImageStore
+	rsvc    artwork.Artwork
+	rworker *artwork.Worker
+	fakeFS  *storagetest.FakeFS
+)
+
+// The go-sqlite3 singleton holds the file open for the whole suite, and Windows cannot unlink a
+// file with a live handle, so the DB cannot live in Ginkgo's per-spec TempDir.
+var suiteDBTempDir string
+
+// Migrating the schema costs ~400ms, so it runs once per suite and specs reset by truncating.
+var userTables []string
+
+var _ = BeforeSuite(func() {
+	suiteDBTempDir = GinkgoT().TempDir()
+
+	DeferCleanup(configtest.SetupConfig())
+	conf.Server.DbPath = filepath.Join(suiteDBTempDir, "artwork-resolution-e2e.db") + "?_journal_mode=WAL"
+	conf.Server.DataFolder = conf.NewDir(GinkgoT().TempDir())
+	db.Db().SetMaxOpenConns(1)
+	db.Init(request.WithUser(context.Background(), model.User{ID: "admin-1", IsAdmin: true}))
+
+	userTables = harness.ResettableTables()
+})
+
+var _ = AfterSuite(func() {
+	db.Close(context.Background())
+})
+
+func setupResolutionHarness() {
+	DeferCleanup(configtest.SetupConfig())
+
+	tempDir := GinkgoT().TempDir()
+	conf.Server.DbPath = filepath.Join(suiteDBTempDir, "artwork-resolution-e2e.db") + "?_journal_mode=WAL"
+	conf.Server.DataFolder = conf.NewDir(tempDir)
+	conf.Server.MusicFolder = fakeLibPath
+	conf.Server.DevExternalScanner = false
+	conf.Server.ImageCacheSize = "0"
+	conf.Server.EnableExternalServices = false
+	conf.Server.EnableMediaFileCoverArt = true
+	conf.Server.DevArtworkWorkerConcurrency = 1
+
+	rctx = request.WithUser(GinkgoT().Context(), model.User{ID: "admin-1", UserName: "admin", IsAdmin: true})
+	harness.TruncateDB(userTables)
+
+	rds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
+
+	adminUser := model.User{ID: "admin-1", UserName: "admin", Name: "Admin", IsAdmin: true, NewPassword: "password"}
+	Expect(rds.User(rctx).Put(&adminUser)).To(Succeed())
+
+	lib := model.Library{ID: 1, Name: "Music", Path: fakeLibPath}
+	Expect(rds.Library(rctx).Put(&lib)).To(Succeed())
+	Expect(rds.User(rctx).SetUserLibraries(adminUser.ID, []int{lib.ID})).To(Succeed())
+
+	loadEmbeddedFixture()
+
+	fakeFS = &storagetest.FakeFS{}
+	storagetest.Register(fakeLibScheme, fakeFS)
+
+	ffm := tests.NewMockFFmpeg("")
+	rstore = artwork.NewImageStore(filepath.Join(tempDir, consts.HashedArtworkFolder))
+	// size=0 requests stream originals, so this reader is never called (serving_test covers resizing).
+	imgCache := cache.NewFileCache("ArtworkResolutionE2E", "100MB", "images", 0,
+		func(context.Context, cache.Item) (io.Reader, error) {
+			return nil, fmt.Errorf("resize not exercised in e2e")
+		})
+	Eventually(func() bool { return imgCache.Available(rctx) }).Should(BeTrue())
+
+	rsvc = artwork.NewArtwork(rds, imgCache, rstore, ffm)
+	rworker = artwork.NewWorker(rds, rstore, agents.GetAgents(rds, nil), ffm, events.NoopBroker(), imgCache)
+}
+
+// setLayout paths must be relative and forward-slash.
+func setLayout(files fstest.MapFS) {
+	GinkgoHelper()
+	fakeFS.SetFiles(files)
+}
+
+func scan() {
+	GinkgoHelper()
+	s := scanner.New(rctx, rds, events.NoopBroker(),
+		playlists.NewPlaylists(rds, artwork.NewUploader(rds)), metrics.NewNoopInstance())
+	_, err := s.ScanAll(rctx, true)
+	Expect(err).ToNot(HaveOccurred())
+}
+
+func acquire(kind model.Kind, id string) model.ItemArtwork {
+	GinkgoHelper()
+	// Enqueues the way the serving paths do, so the drain is driven by a plain queue row.
+	Expect(rds.ArtworkQueue(rctx).EnqueuePreservingBackoff(model.ArtworkQueueItem{
+		ItemKind: kind.Prefix(), ItemID: id, ImageType: model.ImageTypePrimary,
+		Priority: model.ArtworkPriorityBump,
+	})).To(Succeed())
+	var ia *model.ItemArtwork
+	runResolutionWorkerUntil(func() bool {
+		got, err := rds.Artwork(rctx).GetItemArtwork(kind, id, model.ImageTypePrimary)
+		if err != nil {
+			return false
+		}
+		ia = got
+		return true
+	})
+	return *ia
+}
+
+func runResolutionWorkerUntil(until func() bool) {
+	GinkgoHelper()
+	runCtx, cancel := context.WithCancel(rctx)
+	done := make(chan error, 1)
+	go func() { done <- rworker.Run(runCtx) }()
+	Eventually(until, 5*time.Second, 10*time.Millisecond).Should(BeTrue())
+	cancel()
+	Eventually(done, 2*time.Second).Should(Receive(BeNil()))
+}
+
+func serveBytes(artID model.ArtworkID) []byte {
+	GinkgoHelper()
+	img, err := rsvc.Get(rctx, artID, 0, false)
+	Expect(err).ToNot(HaveOccurred())
+	defer img.Close()
+	data, err := io.ReadAll(img)
+	Expect(err).ToNot(HaveOccurred())
+	return data
+}
+
+func serveErr(artID model.ArtworkID) error {
+	img, err := rsvc.Get(rctx, artID, 0, false)
+	if img != nil {
+		img.Close()
+	}
+	return err
+}
+
+func libFileBytes(suffix string) []byte {
+	GinkgoHelper()
+	var match string
+	for name := range fakeFS.MapFS {
+		if strings.HasSuffix(name, suffix) {
+			Expect(match).To(BeEmpty(), "suffix %q is ambiguous: %q and %q", suffix, match, name)
+			match = name
+		}
+	}
+	Expect(match).ToNot(BeEmpty(), "no library file ends with %q", suffix)
+	return fakeFS.MapFS[match].Data
+}
+
+// Serving before acquiring is deliberate: with no state row the request resolves through the
+// library FS, while a settled folder row is read with os.Open, which the in-memory FS cannot serve.
+func expectAlbumFolderCover(al model.Album, suffix string) {
+	GinkgoHelper()
+	requireNoStateRow(model.KindAlbumArtwork, al.ID)
+	Expect(serveBytes(al.CoverArtID())).To(Equal(libFileBytes(suffix)))
+	ia := acquire(model.KindAlbumArtwork, al.ID)
+	Expect(ia.Source).To(Equal("folder"))
+	Expect(filepath.ToSlash(ia.SourcePath)).To(HaveSuffix(suffix))
+}
+
+// A drain settles every ready item, so byte-level folder assertions must precede any acquire.
+func requireNoStateRow(kind model.Kind, id string) {
+	GinkgoHelper()
+	_, err := rds.Artwork(rctx).GetItemArtwork(kind, id, model.ImageTypePrimary)
+	Expect(err).To(MatchError(model.ErrNotFound),
+		"assert %s %q before acquiring any other entity in this spec", kind, id)
+}
+
+func expectAlbumAbsent(al model.Album) {
+	GinkgoHelper()
+	ia := acquire(model.KindAlbumArtwork, al.ID)
+	Expect(ia.Hash).To(BeEmpty())
+	Expect(serveErr(al.CoverArtID())).To(MatchError(artwork.ErrUnavailable))
+}
+
+func expectArtistFolder(ar model.Artist, suffix string) {
+	GinkgoHelper()
+	requireNoStateRow(model.KindArtistArtwork, ar.ID)
+	Expect(serveBytes(model.NewArtworkID(model.KindArtistArtwork, ar.ID, nil))).To(Equal(libFileBytes(suffix)))
+	ia := acquire(model.KindArtistArtwork, ar.ID)
+	Expect(ia.Source).To(Equal("folder"))
+	Expect(filepath.ToSlash(ia.SourcePath)).To(HaveSuffix(suffix))
+}
+
+func writeUploadedImage(entity, filename string, data []byte) {
+	GinkgoHelper()
+	dst := model.UploadedImagePath(entity, filename)
+	Expect(os.MkdirAll(filepath.Dir(dst), 0o755)).To(Succeed())
+	Expect(os.WriteFile(dst, data, 0o600)).To(Succeed())
+}
+
+func discArtID(al model.Album, disc int) model.ArtworkID {
+	return model.NewArtworkID(model.KindDiscArtwork, model.DiscArtworkID(al.ID, disc), &al.UpdatedAt)
+}
+
+// Disc art is a pure serve-time read through the library FS: no worker, no state row.
+func expectDiscImage(al model.Album, disc int, label string) {
+	GinkgoHelper()
+	Expect(serveBytes(discArtID(al, disc))).To(Equal(pngBytes(label)))
+}
+
+// Samples in rect() order: top-left, top-right, bottom-left, bottom-right.
+func gridQuadrants(data []byte) [4]color.RGBA {
+	GinkgoHelper()
+	img, _, err := image.Decode(bytes.NewReader(data))
+	Expect(err).ToNot(HaveOccurred())
+	b := img.Bounds()
+	qw, qh := b.Dx()/4, b.Dy()/4
+	at := func(x, y int) color.RGBA {
+		c := color.RGBAModel.Convert(img.At(b.Min.X+x, b.Min.Y+y))
+		return c.(color.RGBA)
+	}
+	return [4]color.RGBA{at(qw, qh), at(3*qw, qh), at(qw, 3*qh), at(3*qw, 3*qh)}
+}
+
+// Store-backed sources only (embedded/generated); file-backed ones assert on ia.SourcePath.
+func storedBytes(ia model.ItemArtwork) []byte {
+	GinkgoHelper()
+	art, err := rds.Artwork(rctx).GetImage(ia.Hash)
+	Expect(err).ToNot(HaveOccurred())
+	r, err := rstore.Open(ia.Hash, art.Mime)
+	Expect(err).ToNot(HaveOccurred())
+	defer r.Close()
+	data, err := io.ReadAll(r)
+	Expect(err).ToNot(HaveOccurred())
+	return data
+}
+
+// The pixel color derives from label, so each label yields distinct, still-decodable bytes.
+func smallPNG(label string) *fstest.MapFile {
+	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}
+	img := image.NewRGBA(image.Rect(0, 0, 2, 2))
+	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()}
+}
+
+func pngBytes(label string) []byte {
+	GinkgoHelper()
+	return smallPNG(label).Data
+}
+
+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)
+}
+
+// FakeFS's JSON-encoded tags aren't taglib-readable, so embedded-art specs swap in these real MP3
+// bytes after scanning. Loaded lazily: tests.Init must chdir to the project root first.
+var (
+	embeddedFixtureOnce sync.Once
+	embeddedArtFixture  []byte
+	embeddedArtBytes    []byte
+)
+
+func loadEmbeddedFixture() {
+	embeddedFixtureOnce.Do(func() {
+		embeddedArtFixture = readFixture(mp3Fixture)
+		embeddedArtBytes = extractEmbeddedArt(embeddedArtFixture)
+	})
+}
+
+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
+}
+
+func replaceWithRealMP3(relPath string) {
+	GinkgoHelper()
+	fakeFS.MapFS[relPath] = &fstest.MapFile{Data: embeddedArtFixture}
+}
+
+func firstAlbum() model.Album {
+	GinkgoHelper()
+	albums, err := rds.Album(rctx).GetAll(model.QueryOptions{})
+	Expect(err).ToNot(HaveOccurred())
+	Expect(albums).To(HaveLen(1), "expected exactly one album, got %d", len(albums))
+	return albums[0]
+}
+
+func albumByName(name string) model.Album {
+	GinkgoHelper()
+	albums, err := rds.Album(rctx).GetAll(model.QueryOptions{})
+	Expect(err).ToNot(HaveOccurred())
+	for _, al := range albums {
+		if al.Name == name {
+			return al
+		}
+	}
+	Fail(fmt.Sprintf("album %q not found among %d albums", name, len(albums)))
+	return model.Album{}
+}
diff --git a/core/artwork/e2e/suite_test.go b/core/artwork/e2e/suite_test.go
deleted file mode 100644
index 06cc05b6f..000000000
--- a/core/artwork/e2e/suite_test.go
+++ /dev/null
@@ -1,120 +0,0 @@
-package artworke2e_test
-
-import (
-	"context"
-	"fmt"
-	"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 = conf.NewDir(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]
-}
-
-func albumByName(name string) model.Album {
-	GinkgoHelper()
-	albums, err := ds.Album(ctx).GetAll(model.QueryOptions{})
-	Expect(err).ToNot(HaveOccurred())
-	for _, al := range albums {
-		if al.Name == name {
-			return al
-		}
-	}
-	Fail(fmt.Sprintf("album %q not found among %d albums", name, len(albums)))
-	return model.Album{}
-}
diff --git a/core/artwork/e2e/testdata/embedded_art.mp3 b/core/artwork/e2e/testdata/embedded_art.mp3
deleted file mode 100644
index 18cb906749e047afda734b62c1ffcdd89ca72ead..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 64223
zcmd421yodD7dUzeNdb`(kWvJc8fJzW1_h)+kOo0=3ZxrFK#&xXE)kRl2?-HN!JtH1
zq`SL2{}+G$zIyLl>wD|1_13$?y|eGW`|RHPoS8W&%fW~N03Z~l(^1xef)EJ+5NX@n
zSpYg3@*?0p8F(-4<YMXU0_bSTs{BO(K!rshfR41P40um^Mqz_-wFQT$YlDb$;3*;u
z1$5-JWI^ye_#6rmfeS)J1)(B<j;y*Gh&_{|WskK6@9%1W_e9_y_)tdUE_efSAQFMX
z&UAo-w`UTZ(0~&L(2>{I0TJXN!UoNW25dl-hCB>JQGzI}y&W0=FCbD*T?<5>i55Yj
z5P~8izeUSwss6!2Ay9~*2viXETcI<VRKFS6o^i$6+y3Tz<_~HR{o6XuzrCQXerDAf
z9xcELlK!EWRlj@2<^p))?JO*HT<tUzr8NKu04l9^HsT^U;tY*<<`jVn!Gyq56wuMv
z*Z=cOPFYJ{RtMA@XNd++P=mjoF@WRLwUiYN<fXL$&>As82vQI#2K*7o1U?1@0<!kD
zws<=i5sE(m=>NaQpAp!&J6U4E7&_ZKxd5QrHh;P9F9LRuKucajRoXyNT3O8$jH>Qk
zQw@1(6#ycH5`q3h$^W3!(UO)``I`<dD)JA3od3@6FS;|<fS`yFT#OSZ^S5eO|DEzL
z$-gQ2LH~$|iu@-2V<<OB3>vB|2XhnQ{A1+*jn&!)s%I(khnkQ8(0O3#%xUQi;s8M2
z&ceph`2pu2BJ#RF03XQv(W6KILG5bi?10Bwnp@&={~V#K{hL3SUId^vrzZe#dSVEM
z83Ks^z6$-m8Us4O1Hck+1~`9TDS&^{Kmj2@6r?f+<N-Ut0<if_@c>ls5AXXRZ%~{6
zcf4Ie-p+snfCsQ3e{=A}12|B|pR6zgEw*)aw!~tb(3W<OO>He7;hjt^aeyey93zT`
z;slWp5riNdio^?|MG-JT97;q?1ceqghl!#A1RN^@!y`lm%^^6nARLWB38G;Th#*n~
zj~9huATT5X{kJ6ae@Mbv{gwra!a)!)a}gLu5Gg8#5`^Q;v4Us}(p(UWfZ!20j0h46
zM*=Ve41qvGu!1l#QFBlquxQ0lSg;7p%|%6U2n-f3iuiA$obZ2(!Xj}XSCptAN)!ec
zgkzB)7bF&xhetz1ATT%riZuts@EANE<SK}Th+zfcNEkv8g@S_mz>s1{2nLVE<8XhA
z!u*F-U?Xs_cg8z`W?{~35*33BnnRHw8yF5FC}s`^dks_!C5D5+aBw^nKtbUU7zzy)
zgrKmXn{iN-APNIF7ZinHv7&G|9EpSd!z}E7$U-|gq3taG3Ktv!5k-sO;DTZ}5mC@R
zXqX@d2Sx&gg+lOfs5uxB1OS0R%|U;O2_li0GarJ6i$THYB1F(AET|w>1pbdI|4(5!
zOD8<m#r}70n4{n@5iu}ANEi+eItT?9#NgpbK`}8b0s%_ELCoO*28+iaMZvTX5fg<8
z!Z9$MAO?m)31Xl~a|jk~j)jS#{`TU33Ii+3(hmQZW#$MN9Al2a3E~h4Fvp;xI8crl
z8f<-N91I0RL6M>;019f4fTQt(I8kthfy414f+&axS`Y(fD-MBzV$gW}e-rk1Q#{Lh
ztQg!J0T(kDM2Mlma6rJopdna{AWj4(iUCEVVOS^tK_juEVqj^Az+s?9qHu^H298I8
zUWGy+VqjgEBmS!!9h~fOuGqgU!=aEOSTP(D%q|p|AYe@iqOmX$uzFBPs0bPZ6U89_
za|jxOf*`?2!l0mKFfcdJqM#cQI8YrtP7H}b{KJi4UH@A#gL5D#>`&0p=3)pjBnku0
zfN+ts3^5nPpmAV2ilNYO92O-42jc<5nS&;R(r{qnfk8tdK^KDI!$QH7#law=__O|g
zSN3fF#Dmf-TrFMDPJn|28V&pd#$W(9do0=pY&&is{vR-iH@9(h!2=HFAo>sJ24WrX
zPUiMbw)itf|9*Q$_^0n%o{9WxMpaYSx(jeZejjk?9{`5@1Bl7}0g&*&01+7K-vJQ?
zIOI1*L{|1M00Nbh`HKbwz~-o|ab}@CXyM-h102Am$G_ZQek*g9qyQfMFE9oGdkp}t
z27bR`0J%GYXAsT`{Z9}B{9U>LXx~3!%pY3`i2iA-_FWB`zioy5t*po&044JW_{$d%
zY1rTPfQaArz-8oR|1#`v%o*wbg86%jAawbUtolc^&I$$!7CQz8uB%YyXfZ*!xj9(i
zc(6px5#}(Q2m%9^1D=!buhh5>K%p=k1O~wfV$8wJf@7g*K`;dof?&5tVla59C>90#
ze?|?6ikM^I;Isg;1^XVzR}d{C0wy^gj}Q@sBEgyz{a<J}`F`i)bpVSIL5Z4!^8);=
z4Zy(y1uFmnmWeqGoa=B96b>fF$@f=IUk4Bnw1~MF44g%<V5@+m%n^cO2n0k>42}~8
z+Z+-j3WfZG_5VivH*0APWmy2YD+DeAEN#&icwq-{bw_l1f(6sk4J<w<Fh_zl)D)>G
zSSUb{N?Az`T#Nvp&rULMSq*3n*?=o%fY?I%t~3A?hf^M*&z9tzSS7G}fX6%l;NuSf
z2O!F44gg%i73zW+0EoW?049f|O3ho~19Ar?18~K3F8J&uuzm3QjGEL%`K~<aG!YXu
z-37O8<wOu=;v%o_qJ@6Q2^NUCr463b#oYnVY3bmC1t`w06r8^gs2BxI3=V~(;5Y~z
zeEst<7r{cH2t0^@i9+EBIM^7$mHF9mb_FRZ%w9>n0VR=OR21ca)3aB~r|f8Ofw!eB
zC#~~nVA+^7Mz4OGBW9)xO(31|E!TyTGew6s^M;DBFTJ#8#FcVJIb|h`j9h5ivlH73
zgPj)y^!+F<UNltA@5@Bybh(^t9?lpJ8}BAo!0bov&AxGNA1|ufoN2Av9C_{Gz59@P
zbK=eoN?XCLE2;M=jk&kbsqGYADs#LtWt792owl8$Ui=4TG>VO1UlOJDzMYC6R7uOI
z?og8vrhA;-(d)l*p?NaDd?rt3^;ugc*2T`GS}gW*DmFlf@t~#yOAc|%#n`Qqe=?lA
zlzR7gauai-G(e61;88c*`1OLpv|V41+-Z)&_=$|i-M39HK891hkc?xet-LcwoZ5d<
zZ1GX&Im<D>@=A~YywE55;qwfiP`JPtdU2(>(E#?g+v(w%LFv{|zDfm?F4Y?lW`(0$
zseyV6#BFMCzZz7qB<b4f>;KS=m-@EK?FO^CApT1+rb|}s;(<qMm8|Hii;a$Y@5n9g
zw#_c(2PbX6Y&Tf>mSlWDVWB-Tx%A2&mFVG9vY(W-H*7H4R9k<kg66wOdlF~iQ|s|p
z<95VT+>CO5geF?5EEJ!F>5;SLlc>C3fh8ZKQH$O*7STP9Zj(<c9jmmAHs6=kU1kia
zP`&7EB{<6%=HXJ<K{ApbWy(V7_1Thpwmd57*J7PPFRNJ9)VVghK2~pR_5zhh-R0!j
z{2$wxHn!=ZVTFh|1ydoDC{-&8<B68FJos4tF@2lDiC_iQoA+D_x4s!v@z+WGdRR(Z
z)UZqTZoE}!-Pdnm)t{a0$gIR!Y!MM(l6R6=Nm8gi#JVC<l@k)`BU-CGM?P|%?&@(G
zE#+a5{`>P5?*g3>E23?7`yyUcwQna(9Lw!Q<O-yVLf3LSMn*1A^1Av<vMt#PkN7Yh
z1(#GWCt$aVw+3vJwku;xtU~?l{CU$gk-}Wc33I%=DXv>t`<!h&)#IU(aTr^t0|&h{
z|79MrOI`|@pDHS26;vlCmoZy{K~8S<RU@Bs9`Dzptm9a5SM#^g+DI+m@A*?SGl8Zu
zHS5_=rl<z=vY+tvcGz9L{6ezo;>e5TjOQJ^`6IV^%XSOGRM>WD+SJ5<?pPNk?NcDI
zmb_brll3H7=2Oq7LdpROk!9@s{TE)!4Kt(?S76`$;++u|&Q><W`R|M+$5~TtKN<YQ
z`8yh&?sX-(wyB)w<{E7(Jm9eS_9ljw;WPJ!$jz6DjNI|pkg|8Udv~1N+C(R6?j+dx
z9?Jwh-V77;85e>+sp6cbnGDIM<@6M{%Jf%+ONN)ckG%{m+)=tDn_DigJrZA#wf{+o
z{&6*O_bVZXV{E6)*SUjXhGgQNRz+0RmTp_yn}r)8_p5uPc(*TFd994)tDgJm;T5L*
ztdfZ<`;vuAq6z2GjNrKULXgB4gT=_C*BYXd`bW=QwKgNp&$;;tW$hj^NBa{od-n~0
zRgFj(wr8}T!g77;d=gbeHbvztOWbuzsj<c1zpbFHv}2xXVV=AGkhU_sT0d58#%5x`
zfqlfaN~~(FJxN#UTJbM^v3nV^h>8hip50IP<|-1*kIdB5nevj{BK>zNpXlE^2`WLv
zbJv`w?IlHAH{Kv|zlo!7$)7X7opnh{BPpmUGSYdr{GodUTVNvH6N6Mw)~}_~3Z<<N
z4502SHf@!|bq4LDj&7Y=3A{>WQ_MzbYB1IJO+~>q^L9t&U#?E|Nk+*FaWrpHb&(mz
zQ)90F5(_Q)+33`Bh)96QJlM(N@MLr!J5886Z^r7?^=t1iB9tSa{B5Z#$^P&S%I4N+
zWU(=$Tv}y&G(M`=dzH#KQ>+S)Pb`<Uyl2`W@`}7$`1W+=O78nH@$t~5E1Cfpru*-G
zmo?GXeCwi@R5llcC01-xW16(Ty5-Ron$Cxv>9u1#T2Mz>_ldsjjL+e-_G>KMQCO9+
z@Z?&*|6!Xn_U;cI<dY(}4ev1IfrQ3udY8!Yhm#S^b;CJ>PfJq6LyD>0(_KxT@(gv-
z8754TFJ$Jf``K?Cm$OJwSCp!kNi`u@`RLFi8k0rj_qCE+s|3y&ENIk}zjE<|=raX1
zNryY>RaP74aLYu)YPJHI)jvHc<Gz$G!3*b7&Vl|IR7UER(pr=tNeq=b$Ud^;gKFe#
zBuA9A3Tyc`IJORa19C7&SDQ3rQ|yf|zg+wPLq4f?Z>U|Nf-uwDSqBVsTOhgnLpeV4
zcpVFM#7bMcehE<y7gPxdaT%9M$b8ZG?e!<+H`g_me0^V2|IDcRg@IUPZ%yZG(zLzW
zijs$KhT&FtKHn?1!8gPFZC}61Z!kqsIR3&tQgKAg)SFQTLS?i+@C;=@RA{oju28Y{
zN*@czyj6(IE~)1cOR7jT+bYo!`WYTo8fV5lFKy~#S`@(IP{=&bUvu$WG6gA7c*O@6
z^alAo{*;k~CF<1A!5{T#coNscx$a&r&5+Iwj|dhO;p4n$?0=8){oC#15aO}`f{eV*
zmSplVo~|Bi-1|%3bQcRa8Xg$dJd<Idf0ZcrsHop)?_jO9bBS>Cp$gLEJin_~Ex}p~
zi%V8MQ^&b&I@_a0dF+RU?_cG~CcMABylce17cI?EH{|zzq}1ut-mi1O-G!^NNyeLO
z7Sq;RJxlmFvx#@#UuZR4^3R}nB7&;!7k^|z5P+0m(%|s9DUUm^d9{`x4QEuSiC(0;
zh(DU6Pn%tRD$*}R*i4^8;-6-NWAfuvJRD)JCEW8BCM&=9Q)*Y?G%tSiRx`^AI!ff$
z%0{)D(=+G6gJUMC+l4$b+&oHTj$acu7RS4aXtU0ZoD=b;54q|>saO7e@!Bj;n$lbO
zoxlQWPxz98!D{R};>2h<BciV;0HJOq8@^dq+w~;+>HTvIm>q$pb4D+3ymw=sCE<3v
z<vGCS|0+&<o=JF8n0M>uvcCp}MF@?w{H6Liz~kdg#gU=ILsD*ox69{dEqGjC2A5Im
z%S>~$K5ry>nfF?C@=cuniL8qa&DS)t@CM3T_bz;9n!h$9?XvD1Q0Hvd{d&W5<16B%
zQnfcV(*@-b!MfmfUExuK*v-ktYMal_`}Q85za|2%ZX7I9)JEa2XU3F%9Rhaef9`Jz
z^b@gXFk{s0Z;tiN&1NLqS?zKDkh#)wxE0(h)T{ZXe;Cbtnj;gQWBoX>Pab=LAvHof
zHHKQ~#r$3cO+viV6&fF<nBC=Q#mJ=YUYgGeiGjrg?7vuApJgwnki=Zzrfwi(dleS$
z_ujIQU~dn>+G@S`{J!n6vnS{I>hMa+n`^8Hq|1oCr9!a&r};1QNe1Q(rrClP@wLmL
z0{t{~bL6SKeNF=ztI~pdHeFK7;_=!O$Isp+3SFdbRv4==IPpn@${AYowYvtZH2Dqe
zN-blm1USs<D_Nz73+DTHnmQ>;Z_&x!xN&2lyM5;Y+=^MB(Q01K=H<|uUiM|VFK`>E
zkbd0V+#;Jc29sz%OEuHz^~00~8p*ifw$Tm<xF$%wZYr7E`nHIqNY=uM93wuLL*&x#
zZqc!{_UryA^UY3|iImnJW<H2G57sv$j%7jaYir}Swkd&hr_^emO(;hINwQe@QOnVt
z<W3^|b8-X5hKz~F9sMFBtyeT?9M_MNTx;|^-2)xteky(~vrgt>IBhr`x7cGl5=t}a
zUEWeC(Dss>lO3e$(6v@Y#NLaUJD>86XOHU=ZT+6d(8UuX0_64gZF|jJj!eXs6dX*b
zC^gtLQ=4-vBaxMnw80PO;ULMUp(3qOChG+!V_K(1B_aetS(oT27QQ_u6I0=o_A4uA
zFT9v9OweZZXfC1Us?LW9azK82Ku}cl<i>qpejV!sHO8ruO4vEF!nc#Du$%P`uciZu
zEPZIx>S<qZ48Hcg!>&P<Ts4;8%i+4{3TZZ!j|(1X$-h3_^dWqE1u$#oIseVz*H)lY
zm%$2}s!tVibc5>Rpph_PyB(iqZo&%#8FaKH0PVpMRp(#MufMSCDeS<eYSx_{o~mm(
z?z7}n+*wK9Vjqk+nlQV}SJu*fH)T@@M=q@VzO<a9`{OI9;9T>7xEd0BKIJl}<0aS9
z&&ZYdac!pQX!P}!isg(J;tk`CTjw}*0^Sn{VJkl-XC)iH4kw9!e#e5ami4?9I!=Xg
zw<nxeN<%~52h;44@bFTPcK?fX8y}|E3fc}zKbh4RBe&LX-&L}#9KZ1+q=7Z_eST=M
zP5=99!!o;D!ouOB-lxZ&+Y7%uzXeixPBw&k_7)h^*4M6k@AY?Os$8udEVaI8lBLRg
zco*PV;_`0IzuU3mG+cR0@u}q7o8{@~r0a`?D`?Hg42Mh?a^Z;UT(WZ*Y3WS6@r@Y%
zdtu@160ZvHmp<pX^(bPH;$$a)$z&{DA#}pPz`#vNb5%Z}gh0qEK&G(3Ut#N)*5y}~
zQcZRXWbc|viE2BgT)0Dx%-SL&Md9TNp)Bk5AxxW}Ja(OWeMMF)7llTOQstXUe{7FX
z9mor7*!om;tDcW;QR#CDGQHu7YUt|BOfhP!C+O(dTkI`tj~6s-2xq(5@GUM~F?>Uj
z-QB<Uonf!NFD96wVX<ez?H9?O)_&tym!m-qiC-3vQ-`O_ZbZ<nnTBO97Tp}J%)KO(
z^WIY;(nr<!)01P*o_vEyR0L8wdGMz<(O5vPNsv00*_+5VV<zyE9k!%fm;w<jG*5g>
zqoba+`o+>F@<E4Bp=s?K-upf844L)`Bio6;y-`}F0-oqggnAVRK(GF~l|0;vJry@P
zUwScw&>ce1!SF+MJ#q?u<&swIljFUW;VSp{WLK2E4z^NleW488jcVfdgk#^k7a<?Y
zsT|5S!ZoT_x{j}VUtx<L-6Hg|h~?A(l31;h6rh~tY*NQtbn1vNN#<=y%BynGZQr31
zd0TAtwm!Q_fl{4RnxgC}wA@LJ=EuBL8TX|bUp(Xcv@>As{{F{OzZ}b@=oXKI0NGRH
z?md1!%F*%Ds}xu$IV88DPor`G?cz@!wMF<1NFD9nn*ZsZ+w{Tm=Yv@Sx+&Wm*Uk7B
z;%7P^v@Kf9zm?Z{r3w_0uzB+_v=<P)(X8bzo@nsLygE5PY`j)Ce+P1}D**s1UF0JP
zsZwfAcU+Ft53dJy#!R#9%x%v3zpV@s+czZ`a2k2XR_i#~aCEp@JDbBJmJuCgE<M=8
zleduL*uXRdJiOt}e6*y%l$>$>Zqh0bPdK%J^m7CFrE6x6Bkr?oZ*n(w2JJV&)Lxt)
z`C0rn>l8CgQvPm?WG{#=U#(`L<CV@S2iv``3sQl;jID!?Bh~J=e&JV!Dh>*LY+=zE
z=HZ4a^N{@#n|thW4sRh9<u~4h4FMF5*LClSk0shhQ<!<d(dyilzCeGJd_-o!J$1i^
zcl|>JqcTwb4UL72nHkT?!nenAuS_me=32eH%S`mh&6xemPHL#P@u8kkjVDT-iNH<i
zkl`~cY`BK-fQ9<QA?Dr7f^StS1F{enjRxRFud4x1angJD%^Br{rT4KM-bazMQ&SI`
zzBXi!l5~{mS~a8%Z(~lo4C4DMF3E?`MW{f&^Y~S2hzip;^qG5!lIhZCW+Vz2yq6pO
z6+Q7PiwXJx8KTt~;M_q>qfuyxf7|*2pIcxV`0lijODk6+Rp!B5o7drvyxC78QtGMJ
zSE7@@^6t%wT6I4=x(R;aG~qV>@T*LCoUo~htjmtkV_QIu^%v_Hg^iDtKLxZzA|to?
z!a8h_xUFA1HU#?Q=+SJ$!@V_hjl;Oio7b=3ZPyoHXB50&7k(Kv;mM9|c<>Vb**sp2
z)huFXsl-Qq@O$|;ph9Ddf|~z?rc$Q9k5Ag=x~bPTgZ=P8HKkV~!gjCM)O*=Qs9o~V
zW-nqR<16u}Ttf@E7mi=XQS>V@tn`u%a>cbOrkn%pCY4g)fUY1;(OC0Dq`ljM?{&%t
zMF^gZx||N#+n*ZLu|)ZrCl~e0q69-Meyp93Gp{dyee<E4xsBA(8j=0rM_aS!(L2k7
zo3cUFsKj2>Y*I98T!W1#w79pJKvK`ibs*!rBbq+juZf}bt%K!@gD)n9Z^Q=P3<!`t
zXcX1=z6bR_Ir`j?Tu8|%;D9J(hMD8k^e*wCw+BvWSk16Y3#rfD)+W-JjWp=Py!zQf
zujqfaVU+tRda+tUh<L1`IhOzCAfTJ4H|?>r6s#_`HH4aXrPjE&@0AxQ9g}Al_N~AO
ziO8hr`YH67?Bz$*Ycq@^o||`h6?QsgX(G?Fn%%sy|0_LQasg+@IjUun_iN3JB*+07
z6?6LnVCTECg7Bj1aAuJhx_uJDa|!W@FU3l%RnNvp;tq>kbVzD;d{pVvCY``@I-yvV
z!`>~K>2g!g^#Ho7tnddB8{*H73ymtEzJoyp`o&i+p6DF6cBIO_ZlOBw(p)MZPGmTl
zTqDiX{XEQ|Fxo&RcS7T{L*wBvUXs^^Ak?dN&O3XK2;d=!4x#GsG|7=T=kz$QG2x^F
zU;N<!D91KZ^D2<=1uTd|_R=<5VC{UTS)doxW<J^uBG~VIb2eT^h&qQCye@8{A8UI_
zg71EmLevLHHSid;I<kJ6_hPlZe2e&(*c_GFrjJ#rX4vA50j+oUmuk*6H4r9h8!<5P
zF<_6`q8=2aY2P=|9Xz1u&}v{|GBs@$6Z5Z9ZSmz3+j-PDWCvXMUdd--KcxNT*r2OM
zB7($Z+=^(dBiHwS-2iaot;`StFuC~g?hPXivx#dtETqB)jjW$vQ^Gy8ZODiY42?I9
z9k}_1u3Fc;>~?*6|D(-3&JLV}sT$8!9>BKC=ayE|C^|m)M~@L!+$2_<`?30B{Nz#*
z{ncHKGTC)DQ*%$+&x*PnzO_diD!dAaM{8p(H;GNx!xHDBsB5tleX_&PW-e44E2A(a
zm(ov!s4j5{_`g?0$!`vZy0t~8!u`81e61t6uJlYu4Xwc`X&fZY;jvUaMeP^X`$8q)
zm)`&+u2WCEKdD27jbu1Y*<V+wFoP`W*7G2L?nwTY(3McTG*RoG7oQW1n<RE0C<W4%
zm3hrqq`l+VoGAR31HtKRB($jv4^6Q$-X(23xpwchUX=7CSpX1Un@0tt-+j#IABIaA
zygT#E%tm3#|F-J`KV_nX#K*Q$pGh9c?yHFPnUiVX4x(mDVrE%8x<AG&P0%5$4%{Pj
zc&$wmk&Nc)ecM?7gSX#oJBlhmBK_#v?K?m5M0L#6pYT5z#a-Rcn^VZyPLKpCTpnel
z_OkM(@|+Icld{+0&h6d1ZsT+KTH|H*bE_zH0VT$5Wr*1_%EIbM;_=qABU>X%%xziA
zs)ByhIJdALAMkR))g(<gSk8(6HNs~`J9Nfv{{BUj=bpp%b|*_Sf---hJB-No${W`L
z#+XajgOk#-M5?cSLI4v@HGDOX<hQQ9Xy*T^rQ%=pl$9t|CgMq>*rPn;XPk|XBy&9z
z(F382R&N+HmD;jjdDW>mj(1xTd*xG}Y*|}5Z)JVtlD_FBkb}ihx>{$jGxusR=Qj&o
z6%J+`qNMJ&B3a{K?xll}UVAe8X6#*&O-jdSjvVCYoN<k-JXL8a4cb>3^#;wE*G?lL
zx}kTMm3uU31%O0FrS4}d-yNfk$*0Q6Oe>pfc(fd{I(Fzu;`5g8V<z7=WKDbryfj61
z;ezd=oQ(n1QI2&v;&UH0KCs+zt=PCDa|*M{G;yQ|r2f?>7}VJyT|PX`^9$lbW~}Q#
zB;fS?iyC<Y;N|xs>YB<%sdaBw{(7N736B#^s%R5%(-hy@8!%v$xfp8K&iD4Vw!Kfl
zc&XAIhHD>`eEDNkC7$N^j(oY_%ljaNd)R<t1;+3tZ*e(<$myA2)DYsk3d1$TcUi2>
zD0iXQ&NTVLy5rkS-<~^hn)VshY^jLvH>Ky$c;<=F!!Bn!&fxS#Spk=+rpW7^Fu=Ln
z-1Dl-c4plt?+cLRwD~dEm<dwn<%0@56gigA{mve}h!5GJFeywT=1C|BjrB^mc^K<`
zPQ@(emPTdPLe|OYOWn#t@4Rxg^|I@yZx37Ns|Xx83x0;-#K7e%#kuTB!Y84H^xyY1
zGc8mEBGggO76g8YzM{&AuZ{ajPebM141v0)+fkk943S*QY9o87K1v0=K8OrcDC|h!
zOrUNMTZ{5MIl3Wbg=v0Y#Fu8~=Iqn@yzcbw&E7fc?iW-y?1;K`4_{=~^V-@!w)g$=
z!{vLljQ;WVVlVH|9=LK<EJXR3-dYOwdFq$`zQ=I3M7#K=t&nE;ug4jwr?rVrS$VCP
zrqiUrG%Zcn50}r;*I#p<X(6YQ$d!GV=C5rqrloT@#O~?kvgFNE>|Nb2dOUEYw1H<+
zR!d!?b~i!hB>xB-(UWyZ;zP(}-`7M4nSJDchrovDV-WqMu+GvGuQgX`%@7i0R%Icr
zb|zW&pYWADoLYX~VH(6O&x&YE??mL%8^5|xZE}8GIeAJbi|9lMlkkkk?ux73-X*$#
zo!hxA@%JhrPh>m{t{(hQ$_GEbq9(OAtJU^jRifS$4gk}!`#y5p=T$Op%H5))*KzPn
zdvEhASNCaU>!iJAT5yxLo?cwV__tXk7x&MnBi+TW2HLkJco&MrlZ-cf2Yc>Eom(f)
zii~ZRj=;3VP({$Z;x`_tEcyg~@QHjiR$X1KL_~c-`{`?2@Doqu92NcV&#in7Usm0g
z2VzxUF~A0hn7--KMrKu{(5^^*1qy=i>q`BqCR2z{h$FsmpE>U`v52AJnojOQOCc_r
zMDdnXD!-V<-9sp;vd*;gb1f>yP$pMXy|E9f&M1RlE}NI-`+<I$@EfEohg#;gK1XGo
zeXV3g!T#6BsAk*TRLtWJi#+rL>||4)jnF^#`)IJ>&Q5zjfEFJcEnq5sBT6Z>T}5)z
z-l+!n!0pXt?sD(Bd4&cOuauRmW`o(PjVj#69`9AVdFl&><0=w?$f6LAvHbhdb*z$m
ztDO(OWIZtIT@Ce#36&#>^t{qbv#T8*BrIU0_H%@|(Rz~$dlvzuNqfW+?Hn1;*!lRP
zkuCx`zr;@hX?%q*JAETl`8NEMDMlqd@k5y83MjgfnCb1jXZvBO-OzB%oVupF28wUw
zNkRl2XB8#Kom0bBMGjR>uV1zW)p{>Yk;c(qlTqn2iJ^HR++Ru{%cnl^7jg%>osF9X
zGW^^Kd?)U7Z5N&QxtGnn@zijNmZE-r-Sx{jtB7NwTY477OE}(6j5MJdAf<hI{jCHs
z#dukq_RL_LIZ@1ogJ35!f09p~c?_|tN(X>+@DlWS9W7B%2muG{bMML1HP{jL6Q=3F
z-sKneJFG5K^plE{^bp}_gIBfuHC|Sl-Px@bS~S?xh;tF&2kMI~?~jRoZ-XjcTk@f|
z60~I}Y3I6KIzEulW|+J`-RTon8WYaW`PDLiNp$^r?z=#_9V@v9s)NRw8)Rb0{+OXF
zTY2mr*&PCm8jN$bgn6I1GI4>2)&`f<C89N0Uo**to6j>Bzk5I<>=g^0b#Hmv-9tDP
z@pzXc7E>?vV>>2L+K4{sx*FSU9}Sn{ALzN%>p;yfv#=@YQwF8<0}Hvws%hG0WJpmh
zn@bdC?eKYdYtMD(P0D*(>W2)sF%7flq6~RYRotG6kk_ZBKFe9ZdP}X}3{gNcaq<|q
zz?I4iYjjH92?S`?0^>X>-rio+G`IJ<{K%GN(0JSQl{LfntNP`VV=P_mr*@3Kp#Gl&
zGWehB<;sZO_R=q?MCH;4^J9-XB$Y9FtQ?;_vb`{pl4OO=zm%E=lTR2R%cP5<#8Rh4
z0;+{QeYXzJe?(qT>BoI$-OVum_Hor{w%Y&G@n&Xa$7*SC6laWwi657kX0%~(7~2-1
zzX2iuZuamtFITguPyG9evLB~+bL#uhzWZgd2Hah`o=-k$Ht>erbUJ6zN}9u}%6EJ`
ziSKThNf>V(&0s1vPmMQDA&%s~qs)W-sed`+Lx*~4^!&D>eG>X$=h>VOVbL8wGcxTM
z+OYeUwfkySFWuN8Ec-EukA+f<Cb6lR`bpgPZgS~dtSHcE#`!6-2|jxlVbtZg84;0n
z4aX!uNYW!_k#cx-`u-j?p__`n+mhplY{`lEv3}AtxmIW3kArTP?nSrnJQqLjshbEt
zHE-%l+rBXLiq0^%V$+tMOlL6b(f*bnpD!=7H}fHj(-sxbnsy@oL!WR;F11SL=2k|D
z+9>Db*t$?rP!-X~08Vlh8@*SW&4=kxQ;gYc1zAQGhA~ZCT+jrU&xGtFtS7<%oJr_K
z@Rb|>B;C@^aPSAD3U(_I8mm~_!gEE5Vb4?+h~sXf)aI-+zRsf(KdsB=Oa}_lzcY(`
z{ct?cH$$(zYBS``uHm6|s*i%YBbgWKetE1$4qIrgl}!5bgmzc_()|j%a)t0V0YMUH
z#DM`)m6l98jr%9D0<C`t{S&EBoLPv<2MdjgXCEL53VHfTz8meOo!@kCYf={7?EWan
zO`Xw><NQV@MSp>Yq~+rB<70!U@6fI~zYo)@q?w=nm7g3dzjr6@p%e03boX_V?<Fqe
zBmB%b5m9(MsH<R?Q$;36U<-D!!>T1Dp_PT8=_zfet$cs($JPhIf#(M%loVIf>_xV$
z*}WZ3h%1DQ5chSKuBI~RN8JhQkl==oWq6yrVJPiy-X`)%MP(Ll4Sq=o?%=p>YIdJ}
z_x_PDY16`+Q&Oko4>Gv#(#g|xr5j6Wwd@WL?&?SVAai<P*ARcA8gc%48IsCcTVLId
zBPoCdMQimSwwOyme#(tSGUM#ml*dG>F}`|r-E2RkTn2q-DFSZRPUqk8T5x50Pk(WW
z^bODOCCFk4(jEIEJMGEf$5Dcb&9~pF#7V37wqgSJ4|KY-wC>!1_D6=_-Wm`u>Cc+1
ze-J9e)bZ>mG`}AEEX#W(tDhaB_F=JxbvpZwa?Z6a{;p8M9_u?V7Gg<00ql7)?||jF
z8_lv6lwCx7M=oWvC2|v<M#`+V3<lB<oAB1jFQ`gSI74v2J?iJ&=Qfk`%+8rO=zcdA
z`l8eql^N_pUzzMO=|iy>b?0Uop}pm$d|SMJr!W+=Sulf~mPn{hH}+2MC^2}Y95fd?
z&jb|D(Y8NI??G=!Cs1D`bih?Y4vtC{L#|j=X<wuqhDPsaX0FewnDQjXb~;?kdQJHA
z*K2}aY9kg0=d|aPkJ323NHI_6BK%9<T?omX)6QQc*DH@S=7^i=3YZ@dX3*IyzD<^u
zh`vhlq*JTkio)LUvQ8v9$q+%T*_dG_?=wP|IDuC1N9>_l><oLvG4-5tKWk~|i-?k!
z83kFp-`<Z$sOl}d=G~01*Xt}I9A^7QCO%eV-Gj7M?B;>q8Hfb8Fr;xjWma~bB&~gN
zg^DAP{5G4I|JQOUozsK>BUsnoW@bf){fo7kVS6>(wp2Nnq{d#7f~h*uao_pdKV^1z
z-QkKZEI%A_c($n0Nht!ctajgV8jtxPj|gr(R|%A0mNZ?AJxz7=W$ft<(8HTt@zvRN
zZn)%f`?+>#lthd0ZMU!&Q-A_ncp-OBO*@-;C?ey;_yNj(Cm=JUL%xBAjpSU{Tb+JD
zNvMJhJ#h|z-d`g{tGcAWnDz4EB6N7LSwZy69sF^)&-bw}QA6r2`bdA*BIkEa_8Jto
z9ZdW0;>XV~<j_j6oWu;R1s`m1Ne5;zzg>dCJUIyhA8%$UYp0%yKB-CxWLRp-aZn;5
zzI@)nN7yHXBf%c>_USoh7oR3N?r4u7S)rbu47EL`W1r01*Y3S1e^790HO)TubIBtP
zC6MI)tGcvH_~2Q`osp#FX~NXRd`6C6YCabpUH#Z%ke}j$3D0B=*x8s_R9GPM>OA;N
z#xdYc+cL5@CR8ewQTv%2{fem(sx+s!Na}ZkdrjAOxrOzhka?^KA!<l0a<uxA_|{``
z&Chp^AEjKtl=4IgAndD<o-t`xDsey6^NWPQz0bNY$$gQnfo2z;LX%2agy<9#x+gE~
zQYesJ*d|$(@UfF-dhD!fv|)24`ttf0c5c2O1Z<zb2(u}B5~#BulvgVvx0VdktxdZU
z(G!_j9oJ;S#h=pqET1p;tedwzynoH_%FP#60uIm2@m0P?W}&O=D{4-6u&Fd+gJk<u
zk_&DT5kxVZl>!VdZ!(9k&g@lZ@G1(`olj8C>A8R7Ln^Xlis=?Nd|R@`h^Wm>hp&SG
zPGDdJ_f{b$ChC<-E<6dTH{wxFsx|a$zn4G$Nrv@N$sGxl^4w}dMjshX0D0PVxj2oa
zu=fq@o2VaN`t0y8fq*`drvsfg+o$rivP)NYxll6+bW@@Zf`(4~m1+8xPs3-kgM8Eu
ztx}Uq<n*uvKoHS`3YI92?39V2r^%iAQQvgrda~Zrn`1ZA;$ScRjaOBRQm;j?yeRn2
zJaP-Fctif%qe3!?xTgx?9#4Y53x%BRpZTa0ZWkDTDYlGHlwtSd4XZ71qm9RPwL1#N
zPx~#4xWeRC(QaFBJiD4hiUAL}#$0khfrXIs`4tA|L*8h75ECqcb8DhLC*@^TbjJ_>
zk?*+lH8yackI|-X>O;BNuE>2EXJK-B|NCDY{jNl;%h+E$U`kboDids^b}Xwl^oHcQ
zOI|qc|2Vf=5O%U`nuZOfd;DaJMN)2F>4XF4;ELF379|9CL|r@Edxb;0;Ki{{c<>DX
z|EEC&+zuxQh3SaE#YM!#MN#|^h&Tko^z^j#-v-#)<1EeH|N8**Aw@@U0P~pyZF_T<
zhiE4}@bKY7Axk@JXDr$QFJ$jzk+^b;1tbEL<<;a0WXybj?^`2Kf`YpS|Jt`^<$$*U
zpP%-fjsX|$C@3oc1Ox<t68Hj62LV}tl8lUkjFggsoPz2+B^B-Ei?lQ}v{#r}=r3RA
z=D)$m&C4qYy^R!vNI-ab#Z*xevhqsGO8f|QT{Q)r+lor^r=LL<g!+W~1O&9eX&t}{
z5CBA=2!b=M{yGSW&k>Ojkb)02F93vuga9!SG08bnGEy>-kPsjuragC&ON35ZljI88
zksb=udK!6ECbjqr0~~?r>{=t$b#ifyd0)cFEh_6gzJ5(xM-S^8oz5f|C4V{qkex}A
z0*;<v`5zAM=w+rEZp{Bcc|}>W^9e@bf1&*UnyEp0koi<0LXurRy{9sv)*-T%l%Hw8
zO|<(In9#eo+eS-En?BDX8414Af^YwTX}Oah)QVg^L(|ed49zVpIcdL;!k9K3aq}cL
zi(YPcr&t$O<ogy_J96%@E)3+M|2bBDdEL;~!_LS?0KX1}Ub4}vC74m3Bd$I&^chd4
zA$|HHlkJwx;>!|GcMTsYn}a0v{-X*0wy{Q1FUd$h>x;D)!<3|6CLCG&)slXfXUtL%
zofB+qDqI){Y9I4_wgE$2u{#vV?O9jDlNup55I5OWug@I^mVDlMVZ^|e+fY+aof=qg
zqtG~xI+XvmzMS<2`SoW!5hP-p<`gJ=xXAmX#Zyw7kY~4ep|BzUd}>f9l=|7|@lRFe
z8rnz6#Z$TA8EbiuBg9J)-dOK?$Q7Pb;G*t$P0QMnkOmY+-cr8!)-+H5s3LrVM+mu@
z>;03X#>&Ga_f5~bt_FjGiVx7iW)9!JS-+!A%G@SuU}SNl*lpDWS1-HmlAY=#zP;RK
zK6R+u2u*ZbH~Qp$<G!Y16BWU=&}I9}^>bpOJH4~I%M<A|GVh87*3WxN!oCVj97(Y`
zIyt^P-*W#XD>0>*G-6cdR;Bt)#Br#uxAh}TWuUf0-&M0M7)$#H`-DWv2A`2$hoaB4
zlVScgYCRs-jR7x6yl<-?cX_)ho+LV+0w+?ZKv(i`z)t(~iXPKW=Nl4>O$`d9JA_h1
zl8&mE1={Gv+9}?4>KEz8J~w=+HD$xVTX?;5wJ+EY`RSFe%@b5h%3@%jLL;`Ngyafu
z&Ulixu)hZbevgsj-4jmQ<VgM4wcUc0=Gv{n@KazNloxZd<o(kQl-hU-9B3aFp8|Kw
z&-R0IoC5ReD=qv2*6%z7Za%#B@*w(mrd?Ft3E8|T@;m8}<+EE4`$xAuyk|aqd6sz6
z>n-)=6tI}|{y|6h`20t)Cv^@7+Ntf|KQ7XYkY{Qh>Yu>c>$aGR%lZUl?X}e}6yM-o
zi8&WETiE8l7hJoPJ?Ln<W3G4vBYaGQm0GTn>fZ34hEFc7GG<dO7M1%5f8D%Y$ff9V
z_)&N}X8Wivr{U4vA*Nu1U`J|_S5-_4eL=ZJd$fFaPXVm=@6l4z@Xv{oKc;_$H!!}4
z&R6XgD_i|;nso{grSGW@EvY!b3hSz^1_VTl_WW|bnv7M8t=ox&_|x!}es(*|6)!#l
zcw8or<Q&yRqoehwGs>><?^<hSaztE=`<+~-qoQ8LC-Lj{+wsSnjE^~NX%j=UG!_-~
zL=jyh^6o(Im^6p~W+!}4n65DB^7JR>h32~VzD(WQ+Ittyw<Olop8_g-rYDf&28_W@
z_$JJ{uYKN|5{v{L%V??h)(d}i>90uB_eoEFi0hiAWsD|nZax{aNKQOy@kUP8E)7ae
zC_km8d*ppP@i<Frn%VDnOlbet0C@@3%fwx~SH$~aUvRCBIl6vRn~A!{nl*<vEp5Mq
zgHysh=mV;}UgXg|YHvD9fOcZhL^Noz_D2fQ7;zmK>}IbrhEu>C=lu=Bo3aBt87w(g
z=RMI@my%GVL@y)BE;CL@#W+eo;XtoUR%xj(n}(~SW|$2w<q_s*%dwBOuKr7q!hUvm
zD4zl!L>@h4G0DDBNXdB$Z0B`wAN9tZ@VM{KiAkNb?sx~U%XSS0briSP2M&ctZJh!u
zZ=Sd|oVcnVSRc+5ew6Au5j=T+3e;d)Ygm`hxtfKs)))0k5hz=AmtBjA9!huj467?X
zieDOW9ARQDBM-MKnd7E8*&1DmDCukCX*MNTe-uSs_4ShtSPjYV4tW^54MVMUz3g?L
zyJ&X%N)d4(y+Tgn*J_W@hcD_%mN{n3dyBD8`W#Z!YSqNsK02^7+F-mgzp$wvw~h`+
zo=A^-AGP|O0^?PO??;$QZZXat3x6mtoY#HO)V_B9K=a1oU2{EDdSDXC_#S+D{%slZ
znYssM*bDWy^HaS48RcJVEw?;J(aWj@Txt}Bw8Rp*EtmGZK6T)wrr4QIftEh06V}=)
zj;33}r$9oH_Yu<D&ADl;8j<fIP&jb;=4+kUcUB)5CH<^(f`6yUzfK+Aq1!w5{XJ~e
ztU;3#$;&Tk>AVL{k`$@bT|YOFo&pU##CP8?ENv&0&)!5#e;I$~(vJwwf3hI#CUyPi
zv-JgSsyz#$%wh-DW#jO9rzb*QQn})uGxTy`9pWVipPvFHP^s~kbR8bdr+{t$Np|!p
za6LOYI(Lw-R4}Jm{{^#w+Ow<0Z^A>nlRN^!?sr~}@^M6xLM(@FyY=lYdnwt?B#F>d
z;N#LMpxtx|#QY@WO&OCqRPlF|q<-A@eXAOM3Uo`a5^UZ*k#S!m7iUx5V*i<(l0|w>
z_Nd{Fb?L10Ve7s}-k!RY_@uXZ_Oa;k=Dk6Vd2hy3z`%PHy0&i9){@Q`%4+X;-)7F{
zH96(Hr^iy(m+W`XA$xx5T-;&5%5j){ao=n?^?P6U{0_ClEl4LC8=Dzm<M=W|+8DYf
z!wM||HV@{htkq)gt`jgEFQgn_#(AY5wG8aQ4ots-owlx_Y}xeqDi>Xs18ZW4!%`c0
zl&2hhjRKclR^A2Y3lc<tG{^Os8PHiAt$VA7i1xiGGdZ~tjt+2&vkc!?FsqaMeMEVs
z9o4<~4XP{3TfFdK+0sG1FV}5-$hp#8Q}JvcLVPrv6zuK0R`sZnKApPYY1@+Xzy~&i
z@XzGE1Cm^(^ppMWaF>*_YqAH=2@979@vSRV-`3WPSVJBC5t#J7M|+>=ruxL^lCQBL
zyvb!l9FuBbQG!1loBiS{Bb+i-rgA^|#9TR>dEY17)_eCSaICeE&q=)a6QJ*B0cx-7
z8Z$C3M_yo}XTtVn<v(XFEq$}#9n|nxjrA*Cz@e&5z4Jqw<}XcUjH}gwS##d`G_to;
zRXl|y+nDOsORNsI^f^o_SEOjW9^WrVAcQ~ajVK~18w>a4)uVL_@TPSUCC$^*28ju7
zy34J$ZN}ksuiIb+|JR-@On0qllka=s;!jMUq}ht~p<&>SNt)MT$bdTUMY!0KtSkQ}
zsabFUUB@A-X5RDudVyWXN3QCwVIKA|0j3Gu<g>y3L&H15e}yn;1$MFhgLgurNrU%U
z-xhn>bDVbyWZ<qm7B=U%xgi$BT<+8v9=6q^zBq`9rI2tT=bgT_G`fS`uVn)}Wk0xB
zQ6+np`0aprbXnvS;A^?`?Dr9+{=xKR<Zm$8B53{m8>U1P6Sl0pJPESRZDM!7d4%cB
z{t-S;)uCH&*rG-aiau<MY){!bositddI*|UA1MY8NlswW==S2Es5c$jCR9mMzUX68
z#*z4&QWCv13ie!UY&`VpcOJD9HII8rF-ei4lBv`6;ZryAF4hNkYIm>hs7WdB+&dbr
zml}yajND4bd$%5GAJ0ow@Xs25Hf0DTVfQj%z5LE~p;_YbIl3!X9yo;YREuo%=OMhV
zGPXFTzhh(>YJYW$F1V1q-6k-<k0sG+n$*;oVs)owE_m)Zd8csyDiJRwKkK|srBr7-
zB9yvWCvuH*n}guil-y{^0M_Dt@K;YN93j8W8@qQ(m@lFykwc$@#go5Pa2QUTxeBfq
zaEcW&x3u4H#a`(t;<`EAzs%SAgt>8)lA*|HeX(u4ZK#obI85)b>054cOp$iKQL?+;
z#7nu8)OSKeQ*PNi>Zua34ZE*ac#{;5``%qAopEd2xih34-k<#9rGEML*xJHif@98T
z^{9K_Hg+9$#dOS5{*fYcUAtAQZ_o@Mbs1mr48}`s`h>LZp1)(h>Tdo(`3@-`b;uK#
z^!rb7=G<#5*WW)p0$nEQ#oKSX=}mtMJXT*(+z2X(@#uCi${TWHMm<@bV33wdO0O5|
zxyQKHHA<cTSRuDD)7?7XleDmIJK?9HkE5y`vz=LM+TdJsgB7!tLq0;fkDEi;VqUWO
z6iD35KJ4;#l8jy|+^>D^{fT$?>b&F+?>}g>j}_rUpGWVuwlUY2<2^67vDS+~?X)AH
z3~x)d731R-&A$JeYF%EjrvP$YeK+G|>R%tI-V9YZq@wttiEX;P^mMv}>ukpO*JZ_D
z3yuGJ{g=7rzta5m;QwDt1;)l|T(c_sNQk^FJm1jT!8}?h+>6*UR>tCZ#HVzvhBa3-
z*a};edcWQcX`Os)JolO|$GqKqMY^=6jHT}ejY0eV`FFt+xU}x${Aq5Qq)v5=y>+CT
zEn$`9yUJ^-IrYbJEn_`=pJEs6dQz^bdUqz?Rd$-{`2`t;Xs;a2b}oGa`#%{@Pnp#u
zXk=gI#}d2tjp83~xmMiOt2XHh!G&Q$bz8bnly<G`V2`rY_cp_xC79(vn4O92dtM{q
z4a?Xh)^8JVewr(xJ%-swQ5FLR-Z759;+xW4qt!QLlNR#D-XIbWLdC;3V0GXJu5Cx}
zQ-De`d_$y;jCcPYQ}#BCp7(}g-Nmm#&n8_KYZQ{bPp-BJU2wc*8(I7Ir_d>|;T0b~
zxoNKDNtd1}@kHt)Zk@(L=rdm1NnigWN;*kktmmG*-d?VJ&~57vV-8B?dOZXsX#;b-
z17fyieHs_w2<5G0r$^RUe&_r7x)m;@pV?0O>n0#MHZv@|_oG#rT(!t{!+g4{>W-7k
z0xGYS^|btGxjkC7mgKl6pFltQpp@|EyVZ7&lkea6Y@hSrT9946ztPz}SIs^{9LV-j
z{NeI(Ny?a;M`BH>a0<bwN#*h8>IOs2m2@LN>lU@}suODeiKOczrvPRB-O#0d0#pGF
zgty*!pNe^>jomuua$iQxR*GwHe(+a&Z?#LD{Z|~{M}_|Q6ge+`OdfEh!GV5jS*+jS
z-3PU)zrRNK_b(Mp$1NX9#A#%Pnq4H#*t%5VI&EoaH1IS1;eL~GV7D{)f8oWex<_)k
z893oNmw19zzGKT?#=+=2;ps#CZZQ3|A23IR&()&ci2WnEcL9-J6n*ZOo20ww4zeDf
z7f5tourbOFh^5WD5H{L#F>!5X93|7NTkutKIhK9l*0jx%Y1&9go0`OH%W`)PPK)$$
zW`z#^?~4zNo!#}NK0e6hE2+<Wxu>!!oM5WlJ#{bCR*$C|c~f>uF{AkTvy5SxjR>`$
zEsujsU&z0W=Y6>-J`h-hlJ40R=ow_)Q`S0a84G(|*Vckb;C*T7I-=1~JQ{+8dFgbp
zm%zfhtqOTM2ikPebK=`?U<2o^Epzj9h-$3L=DWj(A^og#4BG?Q{K-%INpvS-_8#j0
z=nx^Md8&y*PZNJwO%Zj9UMEyeGS{@kFobZ8e!J~WZc@~c0<ch%9TB{GB=*_ZaA0v;
zg>Q>Zyv;~1Dc8DY@L?;KsFthbZDZNj@m=jZwuRFYo<5^H&8@mM*K{wag?*4vKPgc%
zo?s$=Kun(6$3|D%kJ85TOgpJ~u@PuI!7c7I;YxGkqJ~-;<FPA#$0_P*fel$*-`t?|
z*foiVdp1v;0{F3oqAH`->m;ttxee8VibHaw-Y(vuZMx@n7uVq#%T1d^g=<M6DIa3)
z2FxL6yezD3kd;03&V0S<+P!<t72D5WmG%j~D{Jr4`D>nk7R-GpzaRW()_)dUvNYr2
zaFl1Gd!G5WnHN&RdM%$CrP=&VlH^WkEW1;zx*bD^!UL?y@ei`)y|&%8=NtM{n8SEp
zJyTxxH2kQab<}p~1+VE7*uDOfYg-;+46{a~_mcOR-z5hr7|RC_hpfaA6;AT6Wl7s}
zImPR_yLdnncP6}q0@m`UDxTzQ?=jE*VqP!&Tyfj==9JX8@#`4e;J2Dun1+6k_Q?BN
zb=&%7eV(`cuQV%lUTwSI^v&}H={rD!28vvdoo}vUUw{Gvm20b}GPh>mj<>wkzdmfg
zO5@*4!BIV>9%N?lqhYE<Zoj=kNpN-k)<9hSBqP&E?8E)7Fo@ySAS+{U=6?Itq>rZB
z-QPUNpeN@^SKc`DB$EtYczqp1wy}J}@tU<7iui#}ZINnQDXHdmY40XoHZmxXL2cl(
zGzWnIx`&!eXh73!w4g$@>KnwagpT+6K{wMk){XvA^=7d!GWE2~>_|AJb;tJn9y5jY
z+Q@F+sNODpa?;cmuEv@QLf}U?-{DQA!p!ihNU(!zw`?zT&U!Ox?QQYEEWShja_jV3
zlI_f_Bn2bh{?R^1%(9mO5tUB=M{}+d;zjHZ`7Xn`Tloul`nI&S?-qy)qZU@J2z3i?
zHFgMl-Pzl|%J1W`)xQ~;mi@lRtnwXG!Y8SQDU<2^^87^$&k>7hzM+}MS?v4A32lE`
z$-jT;$P+})_$cnx!aAVYQcGSIkZ3L%68U@pC%G*+@>s4tI}B5*>Z9+Gx?1bsUN^xX
z`p{=dH)0M^i@u23b0cMb8QN-a@P$Tmt$W&-!BKi;S;!>CedWGUV%`V6Hu<E=*=<RG
z_1wPwd#v`@yWdjzJK!B2@8>i0;~xEr-0m&kTaaHexvn*sYU1U^8ebA_5TEeyS(xB8
zL6gJ{-i}ki=F^u)v3n`k%nZY3N7O|mYR+v7DkTme)oKFeCex;04LK!W-L31WlMQ#;
z?-{1~YJ;t<l)UKHb7|APWhi<jenb0H+uIYdcSi|$M1vtrU|_q~dmMJ0dX*z6$g$@m
zv8P;1!?!}dBFg_m*LOz4*>-J9B$0-MkRV7RIuQg>W)RWKXro4n8odriPjt~4y+$u%
zw9!j+MsK4Nof&N~I{B>i-S1lO^RD~3{$1CPS!>pLo_inr*vCH3iqMH-Z}R@xR=R~(
z3ykJ5m8kCVb5yE<f9Spyg;j_CSA>Dv5YsovJA>-_j4rPZ<um#mTgg|ORiiq%E<&WW
zG<!JVc?a=df(ON}6dygA>2I+sf1&e=xQ=BP5bARRPv6>~Q0B^dNVK0&9uWCG?DoZs
z>oh${pjJcBnioA?<wE;_vDdQ6X#(T615s_WK%l`MDep%BvYMh-{!SrD4{h%bn?0t`
zs%V2_;uSxzA-0miOp<by1q{58zcSunPi-~DEQgQiI@9SfzARq2&<lRl@8bMcPbX8Q
zx`ap;?R&I5wVhME<8idbQpem}?|p`vVDD?;uKO>$B9f?ihO=t&*TV~xX9wC+%JFb`
z)|A#W*`ai!8?yc`qN#+w%VKUtD7Rwbie(ogd}(4K_)&qgs109(W!*FlMDnESD#bE_
zFwS!$JxCswJgi#sP(g>YUFsj$_%!Ek45{gX!&Sxa{LR<N#oD+zYf?VmUEWgVVy4)o
z)p6(-k`%i7w9|C9_2MtEfW~k^dX3hrN}7O~DZzA_@Iqk?TC{tk2z=(KMtq<gftzuc
z`{cl(vrXK<CiIvwxyW>~WDH?Qh)7JEf<}x6ntD+YO;kwSRebg^r9O>Nu!hB)u}Y!s
zIN?phM<q#)Kk1*^*WY@@*Egs|MM*?DUrNiuW81B)W5h7?3Wsx6eq*2Dkrj>pks%8k
z>w=+0C+hwY#!cRUT=}?iL=B4pSL)QCj}ol<)$kP0fql9yvIWU!>Ffrf-O&U9A1a!d
zY?Ma+?CN`TW4(N;&>{s(0gK$=c>FFAt7x0na-AeRi{0zht>Bv#zVOdV3Jgy$B+*vi
zN$Ihxqvssd_*!p2G%|^@sUq<DT$}`{%4WQ;a=WPV)}(RcniTtFh*vyG5meyPN3b94
zIuetq8Qmf`bm0%z^9Bq#eOx0l&zJ2Km6>Hu3fa1F1?oAN>zwSq+W9!1x{*FqB$N@^
zX5VA$A&7(@)5XU9|GNLPEb|Okzf8wJZ;C$V<zozQM$E;Y(O&cFTvPOPZOcRDt_+oe
zVcyZvk;g@)q>9ny2MG?mMZY>sL6CDklOuZ8U#BbZ#CN2kYHBXb!|qg?uO^M$kX%7A
z8G+YCD_r~6jNz&9$c*zx_}%GMg$UJVicK1+><QhTjEs`uc2sv=X!%{pM39YpXDxBK
z&nO#+GH+9-^1|FH*+I41y?rGXWiYn!(SeRaa^m!eUDNTRT@UP!{+;zP@UCkB9VdXs
zKua-#R=dN&i*rD-ew|J?1vc5!Jy?UuAN{hnEp5C2^4Qv9ThkcQ4cHXhI!x4b&@2j_
z|9!^;u@9)>J>7U(NjIbI?$*0o6TcBTv;s=e8!x*x{Dic$tL1C5em4zEUOZ>N1exZj
zcW^vsNqFfMGaaKO)r%dy>;fXS13Km(NZcHPSO%;r1~fTIsv2kCXS4Kc%1O_z(O+Ca
z+uBc_GXW;`kW-9a09Q6mSa?4&ZPtp;CWF&1r&*$!8`;&UDU!X^+){ZW|G_YYt-S72
zy4k_@!;GDz>7$1PU}X>MJriu-amX>skw-oBxq?<kP~X}+0M&<gfXCpvXU^AUdpwR6
zwx$prFZ9>uG>^1i+#N_4Av1(^>XnZ!VtX#P<Dl@tkvm{q{XS%_f8+DVnOm@D5ylu$
z{+ghsxZFT8`&Ntg7j?a0Wk~b7OFjicr11~a#kmsIGR#Dd|I?lgmi2#j$p0dWZuZRd
zF=R)+f;yA5ZjW%Qu1R03P@}s*ThnZ9msuf#MoQ9bn}~9JWwC&+5JxV$dHW}2wLSPe
zn`&B({qfP=s5EDQc#NwhKGtqa`N(0q*++21fE3Vaxj=QWzTKvi-O*J#NE6?Pk95yx
zHr9`g`7;eRW+3i+llJ~l1(!U>z*$h!R%02)e}CI77sJtQxTIgbt9ElxfRYsScWBDT
z$<m7ekN4USq~3}3lx%UltVa8&pI_!@Khhc2kD-uVH$C75k#bt+i``S%T6>2ECm3#n
z!X8fd3sa#6DnwbQ(<MS{M$og?=V4G8puSHVbeA>V$&FTnWoAWt+^#e~wt+8&xx;-z
z!Y<CL|1ZIY03e~aBH~R@VM%)SDQJWnj*L!{LK;q@T!+ep^dF2oDn|f7{k*%#+J-p{
zRFA}$mPy9r?rE6+qeqS|J7`;+wT9e)QjU{aS$6ZWz@_;+sy5hw#(~EwR^Lzh(wlrF
z;&vD-)1W#<RJ(U&%ZPQ>T}VXE(cvC%`BjG1JARYAtCiBG@5z+*b1vDNQ#(uOAlRap
zmaEX^npLeAr@exUNb7x7B|I((+Xi#ez`mRD+s$8^bYc%4=Q&h4czNoh8<(DT?meL3
zSyYIVnEKsNZlqbYW(f~2LS!1~iQE*5xR@S$Uo?H1vZF7N%XmQ|!eYc$OqeT)2la>A
z;RyQOc#mG3=QQe(=~poVE|5W&>c1n@>^2b)*_awZtA~3?r3|tzIR;cjx9nMTlJ^IF
zFRQUc$q$!29=ELC1ib~tmtn^ch(WKsN%?y~jXLCR9WAwXZ`Ztd5=GqcqEDBR$^Nw}
z+SsGG8JUj7(LcxykFR?X*pQI$CX%ZOA=`UEL&#yGexqUB>^lJ^^2*F)KQT~B(=82(
zK8jtsR8WhFiyl&=`*RZ#<w|~j^cL6Q*yuJ!0*w(WADp<$cZx~^*fP^%n(EJ}tVr99
z&4gx4zwYk!U~5obUG)nu1(QDf-n^{Y;CFDM*b&JW!%t=<vn)+!EovLEbs>tlRK_D!
zxZS!qp|u*{EI9OH4>FPfK_s&d5(2(E%aBvo)QT>k%6d^VSORI6peOI$J4Zyx^5<0z
z=8$d`vL&k8YUnUMEhz7*wx9IU{DUz8c8}rkH8AZluJ%Q{;JxYCS5v?3)>u}JebDjE
z_CqS1Sy+I#5~Y+bd`Ihos}sa^jGAK);49d*b{^ga`kW7mSrx}8TN#(01C1cy(njA^
z^0BIXZ&Utv#j20EX-!?bkoLZeUdyr!8y_cCiZZ`3biBd?)%YrcJs!b0nn;42Hdr@I
zN3&$awxv}H1EN*TAB{HQZw1{@<vG+EQPmb&EK{Oxe+eSz1+|UcdXUT^s7KLo;`AmT
zs<tAYj1E&J6$4doo^-wA7>cBjNpY6-i6wxcUq!>)Gd#@bAISQj#joW)n<QFaTPr|i
z!n1y$4_o;teic$(A>@9|GeN1+VR<Xc4j*`NnJ>{=qwPtfZKKo}&OR?W{bB=~`}4f1
zYi)rhv2G&lOCYP;)@1+rAjeaLC68cHlQ2C~2K|Ex@%6i{Gc^l-t{>SgEgHKE;_cBe
zoK?4(-bE`2k(jzuNjZRE4uY5)MzYq07AN_Gk8`%-JMn4nQ3dX4m-=e?`ttyj3Qo%k
zAE`&G1g|1imiP~NihDaZB>JI3k=g;@cc_^(0}T1@T$!c+3^H#@puse8{%VC2P7Sa-
zLChP4O6%Q2bheAOG)jjbmTw*K9vWD>d5lHTMY>d67Pl}U=0&jcjt6m~*~|(pROTcX
zf>;-#nCz-aOor?^f_P9c@x``xbCqYK|KX*qJ|@@*Oz79QSbFri$ink+21Sxr=Q=%I
zrVo`w;GbDn3SBL08q$?@=7ujGi&P02(Wpc6MYVM%lA`-zb93!xmdwN-ZurqBL`pII
z#^0>DxZfx@P!yMVhs%F2129^#Rxx^BuQ%q(7vA?<5b1UTHnQQ0Uq?-eaUL>Bcftuc
zL!U<r_AoS`lg^n@Wa1wCcKy=(E|TdIuNKIdE4ldVp*-#Jrf7v)9rq?l?NI-=yH&|q
zv;os|Uv$*`BYHI!W0f!)jtd(o#uzuL*#j?Ld>2fUr1B5d_n+k7hmTU=sRXU@avEy8
z;Pi-8R7RZ18zkpk7N%lg?)HK~u6;wm#L4Ihz5ht-P_@6@X~12`%mn?-_@98L{D)jp
z1G47K%Z{uLH${*kD*IFG_|qvA`fIfp9l-pk#~I}rmZQl)om+ke?_5ap9PV?ApZI3&
z*vwNlZ*ukZb;NSQMCil96N7%w^?*|Y#ZD^=$#W@Dw8}Xa%VKP<8|0-;;kQJ&<{q-e
zuZpT*tz^obC9ELwf`-h^bjQ94yc0k6n)aoVV52TQW&Y#5X1%9<TO#>SP>8obExm1Q
zf=X*<wEu`0F3&-&{}L4Yjo+FzZ#-)0JJI|3wdND5cazlqCKP{zS+2n2*gYdF?VKa|
z7+SU&4pI*f*#^6Nx{PRx##o7Ji4fcA@Ak;5NsYFsBK)_4EY4Ndgtx|_AC8*`ah>j+
zB6B%UKKQV1+V9gXRBuLS^PINavz#cMHZ^e4-5NiNuhk?mxEW`>wSGp0!L;7aeK{{i
z&<7hXXd;+9gMosx%-Ol8p&$V<KHizA(tfQywCP4H0(vH02z%%@=?Jdi8&6VQb2Nw_
zV0r85A|#gtp?N<Cc3>JHZNIct`*rbtvQ6&nc4>G}9X^RTB{oe1oI1nNRt69XA&~qq
zrE;B@U_7+MdKzhujHW|7-Wy7Q3UfYNepU_`7cy!o@$6__PSEy1@22|tq4?HV{=u)G
z{}Y~!{uysV&-dikX_}B+t^fL3e0zN6k#~i_&D>V4xoFUJ?Ctik;^FS&kfwm{qJAJH
zME~yf=ZJ9Nd<R?G4B#a!b{t^{Fzpu!`n+x#bIJUdpi!bpZgN_axc6M2owBP6(*ZE8
z_l}H$;->XD&L>0_`<0m6(*vk#<xoW+9%x~_Wes73;X!36Pw*OcYyp31QtLWqPb(Qx
z%sx{cIjMcTM-prLD{b=I<_l+Llvg+9PvY9DXz+?8fV8Bc9gE-!m|dbQ?Y9yP_4K?c
zHrKB*`yO;?e~Kx+7k6Dasq$WrhO9Mvcst~oNbrYFSs~tPQL-kUN4%TIulkIIaN3%p
zblJ^~xt5N0g}oB^ZcyM_I)lb&v!R$I%^5xpYtwLJR@?AOk%ZV-Ev6>?-eW=8L!i?U
z32o<O@G8=+`qU*~O5#JM)?#~!o)ZD4A4o$kL0$Hndi?#Wp0}DgT{gUIgttz)S(U_D
zfOXN3(PjP?mhB+h#*eT?HYq8Lvn<`Vdr-Zr@WXM?+vCKf4>M<!?_aBszMo88>EyO8
zQBhe}@~g=|<%xXe!Pc%|3cRXcH(py%{^IdPQ==`f8nW(sl?>ZKZ1MSv{>p<}=?y8}
zGy(S_B5HG%(Vxm6evceNoZ?e?lUgLT*O<zG@r`-=tSpIaP?vM`lrT`P>5*g6X8#Ub
zXO1mrih65xWFBV{o(?q5F=%oI9l>g_J{xR@bJ^*c*5E^;1#R2LnF`i1r+c(o0&&$z
z^zw+d*LveFiw%a?_avSHg~{7_6cw9mkJE_H<?+v}YAXVBdrq(iqEE4cV1F$;vTM_Y
z;k|{DbI-g|+9dffEKJ4$;pTq%d9d%#(wv^JpVyfHJW|%XIGj^{p`J8r4@!lHmdzLR
zfXGS4`UMt#`S`Ea(f4X-g$76}_TR!hr02e1oH>nWIR^!3vc3Xd_AuP&TR@g56SL9Y
z^;=Vi)QL&1r;V$=o`H?cJPjGcc^5Gz(}Lv#9ry+0L2P$p6xkm1!Pa4#*g5@^iFq}z
zrq9h<CX+o{PJUxPB_b_h@W|lFwFC6SA5d9QD(_Iij|n3<X~_}QYc=V>Rd9HRjqXd$
z=<J%)Z4fBDBh-E_rNq`N699A?-}l&ZXX8uzkvT9iLPNfSN{FqT%o!Y-?lLX7=raD<
zNNJz)RzQsLt5>@>?$r+n2ccH`ogY*YzhT^EI}B+VNlFpH2N^sf9@bWHCDXO3t+h2?
zpugi{Y8H_P!CBARF!I-g4uR{Qmb69ud*X=FVC`F@m+n?(a(l$=`&eoSffM;`Rw9&A
zqo}{5(uKg?eMq<?Xe+u7D)H|3r76ol2=sq7LvOyMH1`{Mz1xoCD9XC^HZttU?Z_aI
zx_oKPD0c7NNnty0U^BxN?_KMU8-@3w$o)6=#F25}^3b#^%h_z!Q%~mZqHQuB?%vgf
z^Kf6Y0KutC*@W)WqP=Y`y2z_Q3xaqy4K904%%Q76;0DK>OLvd11$#B-GTnz(QHj2D
zL<^jtkG1`N#n{;Y2>R2wfW?FO_%tMKd0Ns=%6-SRY}MtgFX>454}-ekIEg=GDyfco
zptIonFo~4ihs3%hda?bHs|)s%7m?hnrnZ7^ltwVZT$Ag2Uz26J_@Uh6Kc-KD8k$FY
za+pK3ftz}MhvWfqO)hRG+l8Cb`6Xo?tCKpB2(81zWGzb=C9ZxZXx^axFM%LwUR`-z
z;7^vd$>{j9VnJ<n#uP<A)XuuMqo&ck`7>0-ezq4ssnW$YxqQGXHTYZepsCX??TG<s
z&_jtlDnz&5qi6^P5Pq=DVuNmBMQhfVxkt~Ko1lZCRjv!hx@wQSMn4E=gav@zTvg=4
z;}`lb5;JQh>D4!>W|HSw2wRjYn!)@!S>g=tJ6pgBKT|EVmOJ^d?N@UKWMHWTO1C8`
zm4{~Y50kKMo9txwpxK(yEdzc<-)|lr(4)izuAeboEtT81XgfMq#2$wptwnOJ?I%V5
zD|isNf>}*6ye>bJz0VI{7vQ@w0&ZOQQ#-q{c`5hnFnBm<EjHJU)tHx%cZqo3DL&8e
zh-(d=q}w*o3V_;Z2#p*@+dh{vw6cO1)p%*5T)O@e6#2r<Rq!$GBSF8<sAgulQ;Ybj
z*#yRY_<%9%?*RSHbm$I1%7uC6QoMGsYQy)Bt5(tojux1o+ElNX=Y-Hj7?Hy|lM55z
z3m-bm!P5mm2z{U%y#JRVa}g@uXqAw7YYi*HOkt{Psc&m*oH=`N0IN-F7S1N)%lh?}
zMIu^)1=ClFK$$<0dHcYXR<S@SL|>15YwMK_#}hKZK!KeKE*|#+Zs!tLUFEtqo71Go
z@AZ*^prmk_-D@d}XJYqUYFhd|_Anm39bZ)Tg6F3&^oQxp#Pn`yAAw6HJ~E2Paco&l
z<L<*<$?&ghc8bIyJAhR4hgI_vvQty(vo9PcvZj=N4+VX;@Gp)QE8~xh8>plR5$_#N
z&y#hS++u5W|DN?`O2^3<f-M8`7IbqOh);DU24$ghJzM*m?zJ70v&}rS$SCH=b60YY
zk<xV!TRno{MIUU`=DM^5zNAnV3^|}b>u(`B87_EIKVrP7_B>*Ad{)`!wz$yIe*=iM
zoPrwjcEde53fI0S@`H3g`q1Ro{NQ2D6=AK~cm(jCev&&<Bi#Fqr<LvMT73@E2i&6N
znLDSU%l5!dsM2Lo<y1Cw=P`%87K_jZVZm95*X5&|KNIJc|Ca!&i6cv^ea2^~@|Cdn
zi_)9`i#iQGe+~REfyV02>A(z6WGKuj&`2mB(E*YS-B~)dC1S?x_4MfeRMM;mt6V(s
zTvJFDC8sS<Ypb|zW#@l66!HgI^WKXQ(+%^Ch>Sy_I$Vsk?l`hc9l<s|SRBc}`Ytqm
zKE>t=?TR#+rV8-E3uhWMhtOc#?}JU~G~B~xG5H5;wT?A6yDu9uptz^}R$C5Jy%-<Z
zy}=x=C@|9hK=)HToqxzkc?7%qA0o9}hNW3YN_1pAM@jrAS>~~P;}1AcSk>uejuVld
z3jq{l?ia1cchTM8#6pV)xbSsi2}tVW$Et_CK=4_|^0(ZCg9@4KD33w?`;URQT|Pv*
zdaGJ#frrT`C+pH;RUA;+LnT?ZTwMA~?%PA6wuA;z$8$5PvV^0?X7CcIv!v+|TlCu4
zP0*o<3DddM{ZZ;mQFxW-W@o{Zz|K>VvIZVr%+L=1=kWe#GoM`Tdwrf{KwLCRC}ITx
z#cZo3L{OiD$MiU9eFVjE+)$`ot=jbWg`CO2RY%sgo-dI)At(NOHw9sV=DYa)#?~A2
zHD0-5>T#UIjwZ-phkVUhuirK+2p>mFD9F#G=g&5U0!^&P<GL($SbD_bBMZOMK5oze
z`7fuxmLbAh>tnphM~%#zWQyH%pIynv4*fC911eHkH4z`fPSYMZQcN-+)P0sjMOR+L
zgAI$$W$xJ4oMv!dlfUamq*9i|^r2P;6b{dH<z?(9HpBO$7?Y?Ps~^OFyM<wGE|PeC
zdM?9gn2>uld=+xQ8_&%eliL1EK)b2S!8;ZL#lK(mR<{>Hj`>tLwu;q-OQ8_TaNI$P
zMTnUqrJnMwC^}2srA5_>6(*n}2<+EZpMAD@#2cCmlJpF-Tm$Ye`b2IB)Y_5lm;Tz0
zE}9@^Cq?tlj-(zN|16?4C_757P2klK0l^C`ocrGNRg;N(fU<;kWrCw@vzG+<B<kWE
zv2OyW*U0Z-&~fj&>!#>QSvL-~v968bF??D;{XFRPE3|%l2j+ZJ`0if<>U8-CV$(N=
z_g+KBHhBMAV_Tb$uJ3_ZYheArw#bZ?tz}vvbN$}ee5(W8u6<jjWKiDt(YH>vFGv@*
z8Q~|8cg!#ByXk{9<T551)B<36!l#MV<hpbnSOdZAuuZmi)g(>$anjU!*hGdVSICi7
z5ZDxmmH#-owj#8GyQ6D)CI8I&DPII5m0T%-y)fZayQa>lPVQIbbCgF(Jj?#~>R)vE
z+u|6~oVkwvZ2p*AcjGL^Psjt6C^U_qS$6(x@^!~RdAI-cw%qvS(ibgQnn$jPh%(T6
zvKK#|h=Im=JMsI!EcL_O#L~UDfR2}$n;9t3E1Ig_HM}n#|76_vr)8AZk)g<X^CQ-F
zs}dy>Q}(|7xA@Cf*;--h;T6934+$|f`zdY%9*m}H@dqNxA|*65<f3ni4tcC9?^B3f
zxJM@F=g9FHC@-fIqjX9g?~|hq-&=p7_PlFtl%15(cXOh!We%~_ffR=VyyWA1s=Ks#
z>#tr@)5?-v=^m!x2|(pQDl+CaAygeKu;9=o-Su5s4Itl;mTgG1!=+yf!8YFV2SnBJ
zuBX3@Nr*q_li1!(sY%uDDa@uztKB0^uxB8c@~_8|Y=LOf$0H$U<l{z`klwK=<}p%(
z_*k7^Ft(O`{C>?Nu9r>^r>rUqrWjT@mT~^&z{rj#2QKSqJTt7lQ=KSp%#?U~eA}Bh
z?ZpWzsq9)!AFTR?VwlJ>jkeo1@HnsrM^DuhX~uWjSoP(d{*vq%2R2Aaku=*1`T2;>
zJ$XwN7!Z&sAcnmNhOxHRJgNJ=R{d+1FLpv<B`vymwBPYGNe5E`m`r=`m0LEu1Q00^
z64lS(X6UGG`EKYAU&D_M@pf|{-akUmyZx*-c<=QY=l*r5a%0%NkK#*~C%Y@kSpphj
z)bw!s6I2$s5{bjb{HhH8OOU&r6L{)3cB%-Rd(zCh=nvKNQvXYU6<nD~)Y{RWC7jTm
zP&mS9mvh^~+bIZP$hmEWbHzG*YAU@eQ^WmozH1@6N<oc!w@{t-MVz!y^winFE+yx(
zHuRaMZE<c;{X*>Y*YPRXcvhda^<MwkKyu2QNM(}`=S{Y)+?Gin1*&pDpT)A8)cTaj
z5SFDoaWSFfwT<lZ>sw|;(56A0sD%}Y&zajyQu<)$yQ`-6v%f6FcH{a)<guILBX6k^
z{(UL`5<GO)wI=!goz6+oq9mN1V*0$YWti7NS?_1mT>kL&nfddd4iAC#lys(_XWP8V
zJ6qD=;29s?FZnn+$ED*>RaaajJ?m=o;OhK!CJj4c1?G1YTh17jAgMDYn|Mbyur7se
zE%Dl`fj@|lBjceKw=CWfdv8W#<;L*-=5O5#+FLlixJNJUNyiLym6MKge~3@Ny0Oqf
z37$>ue99*;d1m|5D5A)lm(jsF{EtQJw5kU^C^~Mtv=3`V+ewM`T0^&z4>}~%A#qPG
zisqZ0$gRxPvc~$*vTSdDhY2}jPnD)#r@U1?huFDT%oIa5AKZfdfC19PZYw1Rd~kaQ
z;#O5B6%Fc_*+<Kt71VB0yoNTg-gYM;x1_uVdHv`(1!1p+K&jcjrVHDA%Umsp4A7kE
z%kD+LB>fr-#uUBo(;I|r9EfV}Pz~(RS0(lK9kK}SoEI0i+5Eo7|5VSpVGEvQ@hrM>
z#+giQTc$jEAzxsYB+uMT7i{>$eTc847A94*E~I{Rm`*OheNX|m(pO&?GGLW{Q~l{j
zmuhhn>(Ro=g?ajNH4T>rAXo^P?X~tl+K>ONa*{>p=~7dy<sB&l*G?X}Fgs}s(!+w?
z<9ZN#8nbV7iZJtHR9|jTOGBA+yd(qxZfLLE-OD<Y;kF#&tIBQP<C3EHZ)#tpVf{-W
zo@C4Smw*zzK4!G$X33MP->l#s&1$kwT{(zliFer=J0wrGk9gfyCz0+xgo*B_*43v8
z+vZ_wDu*8;M!ywp7@;37aHvhj9W5SH<+q=fO)IoKb;W~&b`#PYMe37YWZ$C)H(ZnV
ztm~QI9ny)b1b?04obqHIe4X~`BNDGt<(PJ*aSuAkE+unC?WOd`&M-2y!xO^x=|_Zc
zVcOwczo!rMHQ{2+dgqD1Me(6K7%hv4Cesq0YTO;15;~q%Ix#K8l4oLko9Jcc<;7)A
zbg{YXeU~foojv(R%1PZq`B?>7w(B6&H(V;Lg|~Dny5jz}hmUptKHQr+ao~pgAaokp
z@7H5gT(Kb}AWfV+C7(8$)GnLyx6-+1p`n=?zNg2CBvjk|1FBr&U5fIckm@h=TGKR^
z@HT@+Fvf!AR%iQHhZs_fbgK%}e1W)wdqxIc&Qp{{1L-FSC${+*1BMjVXRi+MTklVi
z8w_tnS-@zRbkvO^`u{)w$%$LoTUu53HGYz2`|&}bt^}DJ6r$&M^@QX`0Y8?;rD!0{
zeSvZhS;*A~>ntWon<C9Mvb>vYZvhqGP9+|1PDN^qA`DdOX4`wS;?xp(p6mUz@UN(u
zlb-qU$JO|kC{=muVa0%rhV%{Z-BZ0Dd0+-K-feNX_R1AWr-}`-Oo67S;imvhfmEg2
zc8`SwxRgm%A8&%6;;kN@@2d7Wqu>S8$jO3rnj|W@x)+>Mk_<^w-wEB1(oF->Mg5M_
zA>w%1t5}#I#Y|vorZb|{20}0R)nSsoBfn$bHnR|@gAu=~P`B@U&+|g#a#MZ#dpSb;
z_r!o{Th%KVffWjJF0SCtL4iR9tAg4uK9?IX>6~jlH)PrSOOTI?>T>tAY|}=u+td40
zs*O8Xf2ax4ObG5XE}SjnY1W`+YBaQdHLX%ky1<}Ex)XouR=FuA_!ciRUw<@?e}NX_
zgxnc^1xblhLoL;et#BNA%w%ZSnYWsC%i>bg$C4`Ln@%!_8;i$L(^PzF+UBC)69uWN
zO|?GNKI}dqC*tq7RBuAx?$~sX6+!z@$UhyUtKbKgA0{Ffx;pPaD33TBQekh%|7b4k
z2toJ{EVC6G9sGDe>-t~1t7Cr>z~E!I1_Hz<fO(d<UMR6Pz!T<Q#`-uvJ;L5ckJJF=
zctv4u5|!QCZQ-6$R2FC%SFrgBGFM---$2C9K78%}Z75+m7jno{!3H=2ED5T$TUHE@
z&-688R;rpWUl!c;`Fwt&M+)k4Swe5Dv@nTLQUFLULbh0z@Avf?M>nTdlZ;`%7HhAp
z#A(tyyPi^Y{jLjYuM@P<|9y6u=dCYHKpEY$lGlT|)4r@PKvFVw98XDWBX#7>+i#-J
zRdx7`QUF9=Ci*}|n4L2yn=qfK{In19qwY<$ND)fYaNCplvuD_shJ>^vsWHQo7`WnO
zjsI_bm-=m2tdOSsLMbg&&%ODAjM<j1u-$P7!C=|{p<!Dy-$Ln9JiOy<+h*kJG%$8z
zA1PfnruI~F;^=UiCT^>{_e)BdV93LC&c};IvLp0mieWFkizVk;<+->Q5!bQ9MgD7)
zy1Rh{?n9Enm*YQ_RvjH<eq?4qBW3p+w18zdQUUGM+7(#Jyncz-o#OCLDZ_eH%8?~x
zcqqwJ?2sC3S8xx%#^%GqTgCyZcLp+n2m4F=9@Muk<)dF6Cr&yfS8%dN=)!J_NJ3n?
z=1&~kHV25?$ZKR^N+B~cDmC-H0U!<YrCSasV^&aE?Q1;sK&S5;;$_nZwixL~P-^>N
zxpfuAVv_KGX^2_aL!_!FoQaWJEvX}=mGWda5qwIa#(+%u+!7s#pH7?o`H|qERekob
z-=x#8b))jfwc#2U2Lg6&pfk&8q-AH}W_MM&k~wK*9K3o(AokwO^&4GxN7Nx2zgU`8
z43G)4<%<r3etE7k|I*TGvTLh}pyp*>^PcwjbWj3*26gG@F8eqv{n@X<Bz3ziwLE%3
zo65~WMCWH#qqFxT8Qe}={XW^{`VKhE<HAliiPdG8SZmEV;c&>=2KAEWA1z7bdsUbF
zM=(XZBb)I#{3bbu*`5FT@V&mo*fMF!m@Q;kgGk+dhvqS<?Bk-lFU8?greFK-->Bag
zo~Gw@=e5bY3@>_Ruo?rL!@<|5dJngmOKZjz`cw3RMz-%1d~FHJK`&WPodJn+<12EC
zNyh<<moG1@mRC)=1d%V$n&s!&Cxt1A*;@@S=f2ArigX(nB4Txrg_ZCqF?=!@$3~W?
zyz<T2y?>CoW86Ru8Oo+MSyJhuoi!GV??Q4PlqmSQ2KNhAzp$&FtNHoIaDPC(;qj~}
zRqts4#Uq2LASXCgthZZT5HD8jpyJ&5s**W$75o)JS#5V8VgtS0pxM?f+^=HorY4lu
z-87RQ3jlYaKW*s;MwYC&C?*L2g6}$ipK_kdwl$5{{?$RiOrsgaE_i3pvpJ2)bf>>P
zuU<*zAK3PPT4HYEV5_7!{y1j_Zzr>6Mlt1T&DnmA8hvke;+G~BO_0Y;=EFBPKcVJj
znDL|*MyO&*jc(M2(nYy@$X5q9eVtq8{+tY0LinII-Jp@sq0yS70KS2~OQZO?aFEsu
zA|%oEPF|Xb_`LHa0>c4vlf9x&g#-CDM{E{tv2_miwdq1X)*GaYj(K*00;B9$x59>J
z2fSGOh64IuJ?n&J%%>=8gGaCJ>iyqll&0Ju-8m9wB}G%{aE8S2;7dgoR6#a)2$KUE
za&%KuMNf;Fl+aS}^5k2>S;QAEFFWcKoAFf(UJEKcD=pB;47bLTd5LeNZ-8WOQ^b%h
z8?kWWZ73CxHEz-_jfz6-j@3|q|4bUTva>c_RmiSi5p`hQzqF1Ln|Gh&aypD&I<s(J
zMi%th3YI;c{hSuEb*d!Rr(PY4>WA9UdEl>N&3S%GvKq5;s$S%Kt@DGA$J%#D@;ihc
zWG^~~IxR{xeGd_OnLnhrJ^=-r8-tyMHG)%f($h?ZE0PY>X-^pi4wKnoVIOt1zZ$}b
zZ>CdCaH;GRsvAbKQ({8lXZ?-+okoR0WgCb>x*yW7x%V^LdK*$0hZJ2@a4@c+oR+4(
zVQbNZKTI~${o6TqdP9XjTFZMm78qLU{f_qzVWs83OzPpib%o`Q_p@ZOWO<)95e<D~
zXor8e?*F3)M%+xeiH>rvvf`!MBZ5kf6hqOIgAOAt!we^Kba#U{j)?Zt2-nb}DJjpr
zl7!{m>efIEU=-+6L=$7UF`LuX-A54(N~42ZPdf+`+V&H#vz_ns5r(K{CbYhmP8QI9
zyPW81Q&0(u#7tFCekt{x2SfPr%bA-#4@|jtO3V5ZbA`jxW7npp1#E}qYP<?&lJ4|0
z)=zvjRTgrB${M8O(LE=G<(ZvQ{)6Xtj|!_B*dMybkV+gJ#dEub?-?RqFCb|tf()+A
zJ%r#@I+7FhF`S3#4mgYI8R?Loa{$O-@ZC~a^~34oC9mH^4u>!jpxDx^&g`7cCP|y?
zZ&VG%?b&9%ZRfq_gBhG$Y=)uGkLL?ClhDVZW$<h}bN``V$+SejubtBGng_l&cGTif
z8>Wj91kWYipSaD=`D<=|9q|zL#S`vSq1Obn^-Y7MkDLbgbggb^*op~);`#>Q2W*8_
zCy6o6QuXfrx6GvY72`ElQ;67JU+JBsZT5mz_t9E<6m?0@AhsE^A5Cyz)bl%ra4o_(
z62F0b!p?WSxtJ0^T_;|y-;lY1EKbU>6fL_rdXMrL1Ym!D>QriMoW9;v({hIsl929#
zk;TZSI&A9hxR|XMdQfh?HcedWw9Ki#@B@P7X5C+z(Y&H{S4vRPeMHw>e<{F%G$k*j
z`=#3G(cZEm`0q{9BVf-8I5r`Q(^X0RuC`K@E5Kua#)?hnc<t&y=@d!&aJG^0U}o<a
z6+tka9jv}c0C^jca1qb5K(MX3aJg#P)@k-8?7KX4^6N+jeNYo~B2t4nJ|!#7s;vmO
zXPGxS0rX)2dOdvxYwmck{zcyHl7Tj8v*HO_>bJ&1zRsz5;c*g4d)+5~(xrErUR5za
zRSWf7eJbSoJwE=}Rs}angSu2o5!oqhL!ZlqNlZu1+W(9h-7SWFJL0Sx?02SoqrowP
zAwtunI#I8Hc<&UUs-JkB`E|^66&1&%f0`xk@!a?#(EAa;V6*;Ucl*o^4eG9W&RC2*
z!<JdqAW|`$McZIq%;xv%`G`CplJ?b#R&$-WLz^J<QCex2S)sMgSsyQj#8zD@UN^)T
zSs=4rG?q5`rBI79reU4UN4>A=3+Tu0udemix?asUH9~6C$6|)qUYoD7U&q|j17c7o
zPCQw~mI7Oa>j(4f&3)l1QcB>h^Z9DgCuTNDkMy3a$FtGi*_q6TX83c!^*ao&vE(gW
ztfQAjIPUMOw>R{`ggtUDtMu7C6^Fj_LT9MZCH0^YBazD->(BZs`g7mNq!Bq=M~FL)
z0I`hs3YG1+!p7nm-NdvzDmPc4kYGyH#v3Awo|p0DeOlGZ`gBKfrxGrQm9t3h`)>ET
zP@3Iy#pCkx(!UY`<YO1)dM>7GZV7y18Xv?KGg42y?{aC3Vh;G`-Y;Iq1f14yg$dH{
zmQP((6c#hkFV=@<jQ`qG?GkwMYk;X}F-u<~jjn{<KvUD0z)Jwp<)ZM8u5W2YuLp#g
zs%)@FSt&n^0ce)&8IZIg1>dbgu4|yZR}r0c^7|JH#X;F1q`eaN&k>~kfvL??&Rm5V
z1PjlM@N@l^)M^LE5ec;(j4&}ipr`2g1Mab9pH;t{_80mfbTbo$XTz1UyFw1Q=$LN~
zFFJofbiw5FqK7gn=|kC9{1*Wyb~PhLqY^l$3+-)b@0ep^*dNZRxlpZeU-x3t)av}(
zGcHrV3%C07F}<_xPs=eCNO{)EZ|bh99=1+hOVwH;q>tIaRYo39*Vq^J(7HvRaxKn*
zb^wgSvTV4bOhTDcX^!jSjVx_xX+EboQL7uF?+b}zEw^}FRMM&S#EU7OF=AR~&mPYI
z;la@kAWaZrYNYMuLSrLz*RzE+JjMS^1N>>!-J|vU=uw=b{d2mX)FVsCpe*AGGnb<F
zLgf~Td1*&)(FdAux+->^O9Y~Tf%eU#T%QT(Bnk5^x(&5xeP<!;n{Ty_%$Qr0iQ-7z
z{F=!4<stF7ch&i3#a=GA2%YLz*Z52bhn+d{7kESW=NeL64vHe`T@IoV_x80zi&+3v
z^@O~qSw2*Rz8~tT&rsa|iZ}q~WnjL#GjS@3hpo37&xfq1oU?E|?{}pC5-g~jMhEC2
zf5e~mZC<^Q9(E|X%RaDA)9+5TzfX-k*Z8$^Qb)k#C_<U)vQab}YfwaEe2}WiGn1M-
z@m$%vl4H25<>7&-0=~w^E~omNy(||PdG-xLe)C%#PXik&f{TTUNdnNfn=^Y;ljlL9
zo}clACUP8#8kE_rNv?R1BB*ACNeOOdxKhcwb&7)PPN*<<m;gV?)4@=m0!WoIu_$wg
z(%UCr@^Tp@TDpu!+MU={^uZj;&Ufnv9<so3Gl8EPSF)HfmjWMfALSpbC|X8vPy<t7
z@IPmGE=JSB*MV(merP*m?LPv5UewG<!b)M>HP@3t_gMP)bojv3F4)eDZf3h2HvT>H
zivk@(q$I@w++U{|%R=jV{TS6GM;D58+NNugNj-bC<SWai3lZJ{fGW9+U~H(+jV#-S
zw-2zqZcgC9J^g`z`^qBu5zFyo%5ZB9en-T6<8dFqI+!VBHV#_%h(A&w>LBh=j~o7V
zJPOjnz&?HCp_yj0W(3Tn^AT)Ku6|kES0)sHh!uQV+W0$C%tKZ~8Ac+5g|jTm*8Hf|
zBz>%9IWjf9Cu|zft#1u^oZZ}Hrn^C-6>bqJ<~rs>HN?QoNClmvp#5>2l!QL5W_SEP
zhSK<Vps_95yQ78PSbrQtKtZA^OD&v!`Df1erHAKdQ8eH!=bx^5t<Jh8m8#FDbDXTI
zbQiKf+lGwicizORrFdI^KCK4!n3@`VBKc!t@&o)yM+7$cS!v=xtG*|fd_T>iqZLqU
z3e?AqSBD-&P0XNKb_wRT7f3$YOhFDFWxv6%3}-9!fQ*Qsiio@h8TTGwj*X61wm=YH
zYGXmkf-ZW)iY(_<aU4+{88VSQj&Nme$jD_)q$Rbzf1tmu$MWFG_th@l-^=uJ%AAOp
zk*V0-sz&?GszW$S>HPimO%sE_)s+Jzp&WpwWY-Ng;ctbR27LIO-{JPdr0D4Wb^TS0
zmLNp=N8i1SganBeXw~uKu;-AOLjCMfZ~1PzFl+3Gq2>3}hu9XuA19M`jhCGvSCvSy
zsdyf1M=tK^^q;;3b%lI>C`6gSKFwu*({i0n$and?sp?~|JC~JV4uobNP9DFbJkC+F
zUg=zH?}q`m(pvfBJ;0uP)C?ZeaV74wbyj!1jT>XtQ(JPJMK^mwu~pv$*dqN;E%>4^
z1hmes3y@AphHuy^;b|U?YKiSs-(u{nkN=P4VW-<Kuhy@7M>|W>tvEF3ogbv6J`;i|
zDN9>u{KG!|=MWKd)n5Xp<7dl)nX1)?>ijS4^vpN=`Ug-&mPbcv0opy;+i(LcE&ZSu
zPNV!>Z`^we!{|EDLHY}-+h<iEP;LN`h{UA-GFw|U)*=nJDOjnA8}jUjl|4+<*1DJv
zs{xTMw04!$;I*i%Xd;LYN&(2)ow1zJ?&V`{w3H}|D7?_kQ3ueazKF0G+H94=R^-|7
zc!2VWsQ(ZjscU)H-zo=s-S%yF;ie5d2f+g%*7Q^(G6$1Bso`_+@6YwVm5B6A@r3vO
z(2O}!lDc6Nw0k*=iR8e^WnN=9ysYDM1`Ra_R@~MpD1Mb&y6D_>%%Uz3{UbrGUt72O
zBK%wl;`OF$eum?NGQw;!I>qe_gZ84R(wIPZV~#RnZuAt*oH4mS9qR}#@BAuhrdr<=
z-x_PI`EE9fip2_2&&~Z2@FE3<J2{eE(EA@#Y3l>oDkAJ3+{t(?Dmn=68K|XD=^a+U
z{MKz+6CxDj^1-2{y7^*Y<)_;{2fW0AL<Us7vIy^%2Xsc=9&d#9K4UkSBFIgj7m(fA
zjJY_4{8*|l5E*^B?Rg?NBg>HDl==_m`_C~Ckj=FsUB|LuSGCId>t?&uD~2t0b9s?>
zc8&RnHNolS@8=@F+jpawd0o_KEfbD7%*D7Y@h*%?q+TD#*X<vn75P$KXhWMfh<fT{
zG<k}4N=QpIOHS3unSNPO5P1ABHTb2b*Vq?Y<OQx`M4funJ)VA<U3Sm4I=@?dyt(Bm
z`{UO2?=Q}iX6ZxTq)XrbokmND{`PRI$!pMrXt!z`=H^bbPM6c?EbtycaMr7<0l=vK
zhG4e@uO629zS0%LlciO$)_Mm-2Vw0{X6uVe<b`_4i5ClwRGyMtS;SUNF3dS?J*dvi
zk8j#Q%?2$jspY4+;JN2VIRYx1i>#R^G}DCzr%KP0T<3P7kHd6RUSCJaO%LRaUQb6S
zg*oh;1RHwLYrpjLxSN@M3*iPyz*WrBzp7JREb#_P9}hWvFD|1yo+=uCK$qt1<BYo=
zMq8p>v*TD#?uB*hfpvMyaq7pgmxpBYUJAhseeOqTliR=5i8q>hc&6NA2#$_Yb@iLP
z$#-0lCKS|fWJHamCEg4+&Ie~ava8$K64ViAQ2i&}{%<3$n@<3Na&4~gl$Z$w|FHG9
z=mn3NneB-?##)&t?4=p0<wrCR2{=qduM{7MX0NJEcIUO8@LifyE|W@Z;S!>bro3C?
zuu5hC__?rt5HLS09(+JDI`AdE;prc>z6ufU&GxF~N!@&&+5Q`%-^IKeL5Dg61$Xyw
zuZ8l6@a7eD5RM-{m>K4|clp71)x@%3VtkkYsJE7^inKKWdGr&`?x&UNat^Q33i&n3
zmI}ka^#7^J<PD8oc4Bzi>`%^-@{*YaVi1;<;DNlmRi230Niv+a@ts@}5b(BR;N^9S
zF0s~~g(Z?})8^g%(b<dSkYXAPl{RQ!15O%`W=OZ_Z=DEXRd)?5w%vC-d+(jgylKMI
zKd{;=Ok4#RXNZ%QMy7VHXgyMK(1~)t(d^wh)Of_w5HqZNa?j$cZiH^~_}lj^D`jWb
zTbNTRgDctMjoalniiN55J4ZJZO}IVYv|xOx1Z-xn<U4n8_UI4XI*0D-%~0TAYb!%b
zVvGg}|L+8%GTPNvrU5U#qcs3CyF9Oz^io}4CcvXNP`_K1bKDhMM@ArI+!A*-chU6r
z<rDXwe^(#k{}QZTgsj;2Uv{D1a>58cG#qAR(y_KzYJ%sUWxRnZtk_a$;Bi{mWto7b
z1fJd0P{_#_y4W4JFN)S<DvBW(nw*M{_847yTAB&ns@0?QZ$*w;={gSV>Cdg+d$lNS
z%Emqm^B@HB^|kN`)5q0GNeYRep8)7|5duV>1^tmHu~jKw1m!gyf#=~Rg_jk`^pzBM
zHq#lN{R&cEf@-R-@JgMML#{&Df#WFheh_TPQCb$2ZbHXEQFUgi^A!xU{mlmGx{wo$
zpLz0da8j?^BFIcW$~(q#;YfrR4r1)E=`LJA&7IDifa|e{xJcsV()h?6r}qx1J2j>P
zy48{bg+j_=Z#@NGdr>`eoJM2=46QQi(#k8FQ<ANa_mShbF&`jU4u`<k&q!QedHgwx
zjKkFc5gee8wEP}@T4$yep$GTY&x=d_2dp{zSWP>?YoFw~57kC3aWBC-^NS4yugJ%T
z*gGAl1Rp)ExYvd3<7undzI}@jMV>tQ&^Mm9oLI%sz{DB5CP+5uBD+p&Li>og6cur0
z4j{z5t$PuX@(Pq}#4pmAqjdF_`hTqb{!b1pJ|?FuDVakeDezjaxQF)uX8MGCN5I=8
zGwdz1A1B)3+o>|>MQ840txM*R*uiNe#Z4Oew(_Bc$4sNQrRcdCgx`eMJL6d;DVnfx
zHxWHYsOjUo2#KPyMfMeVRFAKEPft{EqAMJzn)%W~Zq(?-Ltj*hN^>RJ*_8?n3vZlF
zWtP`@=;YB|2cy_y6w-b!z7iU&<+qD1&FlQ~+WO(pK-L;Rce!PjJ6Yx#U4<a*bwN=a
z!5PL_x9ulwf;~V53DlOG)aa{DK=9IrB$?Szl*2i6t!*>8#6OzleeBe1V*doM_>7~f
z$MvzHS4<FGP<`x;!48~!j(}O=9dDF{dvaTWN5H1SFv)QNmC5P~8h}<CCk;FOwXyv1
zIE7Vb@CVt<E5$E<+8$ihBlg?$-X3voEqB{0U`?D94Rk1>4{gQIH+SRf%hzna(H*RF
zcI~qFS#EOQmAZHWF#AjJM1VSpSY-EJd>7zat%sM;L02ovozAw&oTxB*rs>D?A+;!u
z$Wm`T+8@mFPpu1IOhJ*8R&UU}8V%|qO#&N&DLqpJkUc@d$(p8?Hi$x?n3yu)aYAUs
zjHwvNsq`?mwBb8K<)ik(e_7z{V^QYKX()56u3!|YM_<XYF&8UVRI<C9dB|3rjIq{_
zfOBc{F9BLtG%Pa6k{DJF&`fcUx2U0uB1UVgkv7gVBA4T4vZUM(F7X$pp=1p%R(<P0
zv8tpZR4Wsb_~ZnrS{JqwKVVhEy7$4N8)dv#&M-On<pm5jfeaL-8}<AZx1D@l^1XMM
zgF>mXBirstS=uBxe6k{a)Oo}7;P9pE-qeRepC?scppgTz)M@1Jqd1BN6<ra{H;N5u
zflv$C`goPCv66lS)6cP__97>b=Jl}d6~S8YBuaZ*W4DEBePLS#b=Mk>AqkFu-o9S3
zm-CvWu@SLYmD@AdZ}Da~nb9-9qZ%_|Ri5??KO!{e#6AVCCcxac9kU9YHEn#K$NdtU
z>AJzPy0OX&*Cw9LXE^{?rcLs^%Bf`|;(a=oWbS{O1br>l)Y?xombC|{1$$H8Qw$|#
zxq3w#hP%|gRk%?R6|dp(eQ`gDPgot|7*!9r7<BPR3SJi+9Kz0IMYS@xqI|*bPg~w=
zI6>6lPrPZ7K)AUfgl1<{M%_Ig6Vwl-nkcU;qG2ze8oc$19(oSNmaIiDku_6ZK;~Bd
zNu&QqKsN3{s_3#|a_Ud4!B>e(??M$Was}=J#3pxOU2?`c&n*i?s%6s*n6RMDBHbs)
zHzS+P%oJ5VJR(7R9;3#-rgMJD5e7#x<d_S=xFTY<VAnmjc<&wgH>r&pbe#DTyVYnt
z#7}T=(WDbA&`_Rm1~qjGp)<y~D{XZoFIDWeY^I^kw8La>|9Nm=?>-1#;v86}EVJ94
z9=;}<nbzRGLzcV=Z5Ui&OyUbD9Tdkd<{Ww|VYqGh+_sF#&pcNhcKM@VWm1#TGXt-|
zAZ1CZ>h|H9EPPU`q+Rx${3ANOcmT8CGQYO1I6v6~jH#;Jdm&*w&tt6^*@cTi*!0p9
z&0<pS=Xxuys(fgvcp8AS3}AhOz+53g+)$OTauveZRkUG8*{S^d2tuz#F9`c4w+QO@
zxDAlXt07eIpz@niuA9Ole6J42Cps+Q_c%K_UOATG$!VBSJf1pn4@*nZ#X!*Yy$#B<
zI!w-u@j?0a>%gE!k;v3@)^&5|P4YtWl{eGXgz*F0x26WGmBYo{Lu^Q)A{{@#mSq~u
zagdQ6CX0F`&PtDUS0vZWcwjfLW=#nFG+0+9Dg$7vIhfz(Ja%uLW{d6Llk5DkLDcF3
z2M#JnS}6qB$Y+(Oc%)=Z`ZJ9xKU}e(1@9?EG_v5?5W2q7!dM$TbD%Mj3aU!rA8oXf
zYAG>ih)#<Wk?O7R^+Yl&@5d(h&9pb?Z1>Kmxd{0w301df;gcpE-Z5J_3B6K<?7qWu
zjMz%Q+m-eSVwr>0XiIvO%qlY%Fx0HDBB(6S0+L8Fw&*OZ$itVL<C;3oDkAc%$E5Db
z|4ixda^G_tv^5XVe8(t}7!El|C+E2t<L7L7{fxY_klHOB$Y`kAKd?SFY(FS$YZO-~
zc%PQ0ZZ5mK(y8m+8B!b2lP+H3V0J8f(IwSQbLUXls*X41ho;H*7B0cNQ?v}85$=I+
zoZB;3SK-EmJo9o>Nw3phSR4uUok97NM~iRm?OH?WwUvj_r_!+!(uH{1jV}t!bw5>S
z*hrZ!`_rYw5ixx)PBYWOPu{5amsi+5M@R_?kqPqOwRvyUFJV`s#@>_~4-fs2zrq0o
zf98ZS-!ylvk2B<RVYXR$%%v?Aj=3lu!l;zPuVZV#)l*pQopcZrok7@zk~9mu!#W+P
zIa6j)+>9$io~!+2kdCw9K7@JFDPU%u`i|$|#>aoyh5r<@qz6q?4<u>dvXL8lHDU*>
z90zC;_#FS_rk!}=C%gjhur{y*vENU--z~*-WA?{QD{jo8(VO{A4y%Ik3EQ;FPNcIO
zyoj*iZQH6*+JJdI!$`L-eXz?~%#aYAPHMx7z+zk86gPSEQtmQH|1^S6OH39J9>6#V
zU)}L+@Z?=|&-j*q+ppA$D#+G`=ejpD>CWc(Gi=^yo!QTd@brU(BZ_dV4Tg?cfz8qx
zzDpwLN=$?~?j0+JkW682Y3`$bGXtj_K<+3-D_$ieV*OXO_EZ2h%~87W49A6|V|+Sf
zmCzJiPslCgx1d-Dlj>H(3YIU_EO^rS4i#$iJ7Ud8b=sZ69j7M^@skN{R#zk~^c1^B
z5)|tUHQHOXL6!Nh)w9+dCP*>I>Bgc&49_Lvl4XY(deZ&-UXtG2OIbbBm@B)+d~+Sg
z<)v6%y~{270z=nK&m0_%&(3$JLQ^~_R!J~UC$aQIRWa)~P9*qLE_KO<uXdE~|FQSp
zQB4N_g7*^=LV(bVbV9E}=p94vy(4JoUFls3RX}>L(h(Gqs({ja73oC;=^)YtRLYC@
z{`Nh4-*eBNvuF3+y?ghUf1cz#lP5FZ`Q%$>zBAK3zUw_uCP6WUy-6$igBxNs{Uj)H
ziPwL1p=$x!Z=d{X(rjkfI4DM}xY})M0pk0Zt5<7o{d;g*%BRnlcAM4HwEOT+L)dN`
zZmxma|9)H}dX+O`A^m**LmfcGcj_mDf8_d7>Q()9@-|23BYWl1dB?&tTxNmXK$o|h
z#~h!IQhw8`)hA~;GbGx+PnhG*>0$2P{V_K<AF^wf6zel5=A^-~ol&$o(2%^u^PMSP
zSzN#Ady45fpv8S5vj1w>NHut2to(^IVN!2h9d^$5ffAHPx<O<jiaW1zqj6>ny6PW`
zs=5Kra3%fIFLx`^llh(%Ke&Tb&#EP)_n>_Z4mlRj=t}adSZbIpG%+Tp9~4hFzqIRa
zetXoEUYFWt9UO5K!0j?%_h@Ax__Ea3^i%%GcT=TF*-wRJE!Y}V1Ql}!U;TRVc(m>2
zwzg#)UVgh!iP1A}DZne1I(_kprv5T(Xjg;jT&FAGD*|U+nid7r6Xtgwryq)|i^@=b
z2<i#FUEZH1ZC(IoVa|XcIFb|7#+2%YT|kL4E*o2wr(e!n(>}Z~cn2Pjzg?8hJ#Se#
zASx{OR@}s>D*V99rRZ4jp*kxzO$9^l!-obE_hLtA%dZSIaBZac?=_E(3%)Jr(JrH&
zn(FWhjFJ0jo)vlk_{g&D#gBj(KGw%qnYF}gd;Fs#|LqL4m`oPxmsr?tj@)#j_Q^D#
z2t2Rztb4x_F*d4hU?P~)ci92NsFr+vI<xZfrGR95lwfOI8n;wJ<WfN5kNoyjJ+cB8
zE)3(VLhp395A?K#m=0eT$xn?AMyBxf_6`D~E;Ah`!DiLIE?CLWFWa~s9#7d`_?d_9
zs!TKHZGSW#Q7ArJ@{l|zW4x<oKA-*K+6FJ_7thlhK<%dq!>caC-q3xc_w9Wy?m0ZY
zSl_2f#P-3<TS8AN2ahC_jDzy~b(W;-*71y@J=GXxhN)CN_Z8u&Wr4fn!7r;s@}4rB
z#&g*mNbH=v01FriRvA8WCz|=0htsDe2Yx9Zs1q8<Q0H<#=*{;<&v`lHst+Z#5YA)L
zb9gVE2AiDct@#Lc*#1J3!&7|tv^YQi*Qnp^_I%X0>01&F(q)AAx+!8MO&S^gcqV+H
zchIKju4u<~o}=XdD01|Ic3}ixVb0(?&kL)Q7dAxv-EA2x#qY8%iP9Q-Dt_N15!F?z
z^bREA7vQ!v<*5zh{A?{(!0oM(>^jTi2MHWl2>bB0uCR#1Tqu`Nx9ZK1$lR~&BVO%S
ze{^+b7!2OB#rD4TK!czBPDZFVZC2FWt18vjEX!RDavAe#D)7r4aQ6K7hkCu9dGLt4
zCH&;B^>`aJ<jm3d%Xv|Rg}^aPJMQ9o+M-+Ixq9N5QT+nlaN-W_(w|q}toIXaDK>QP
ztZhl$0NisrZ6CWQvj#(W+8S5NTUpyP4mLJ6EOo-;76K)4z%{Ic1&)Hv0lM5K=XVP8
zKG6)w=1Z5}k6m<FNC-iho@V%mH1LOq#Cp7L`UPbL@!1C1r6;Mm20kl~*%8`bd;CQD
zt$gOp^Aq}AL+ZR&z#G5YU9^G;c`qb10xI1$b}16o{G=ADsxHO)>t1#EZf-*MH0>K|
zzeXfRtIg9E1RLzgUc59PPm$oY5YY9R3)C)&7PlTX7vKnzx-5%(B;k9vjm>+y^`PS3
zqVVKm-tUQCi(q$NnLsg}+s~J;JQUxiZu{H1Sl%xAxlPF)$|P@c+4g@vX$cN-t&G3c
zy~yCfYP#sTRPec~%Op8#7m6{nS<(XM`QQ<SJUAh@t*I|a4?57FJPIlZRMZ_FLM@v;
z*z0Rb(UX(4_7u&S`Tf0gdtPZ;PHFSu%=hM_I<xe&3hCuKFG|L|q^7rMXhMINmS_IM
zTvYzAPw`1=%iM`+@w2p90sv#g*1zi#{};9V?_U4yfBfGq^3R9<mB7CZGyYqG`u~jU
z{kMw#^P$gANN#s$_G#x_4{2FW^Srn8c<6S{`TYi6;`#mK1eHH;eyOlr&0LlwUw?n9
z_s^35ze(wL^fmLJmrch7H}n7HypDff|0#igO5mRo_*V(s{Hgo<CKl&?=z(eqHHiIC
zW{n(cocSx<Dhy*6albPUsSD~DpbZZ-XI-`TiJFt6elHJb3J@G`Iz?Vs<vX_$y9>Aj
z@{F7?NtkVCwmW8p&a@RyWNaG*AxReM@)yJ=yx{!e&)(6(g|-fiXYnW2#LY=kSowC3
z_YuMWDZQX<{gYakot-O0A)TB6*5g18P7H~J8DX~)>g!B+P-75MA9)0ShJ7qjWnkeP
zpbI*WC4Pk;NLN}=y0WM1Xt6@L+Dj&wP}##ef0+5^wBv@MGeS&9Nw+&eiadDG(fhDB
zMonRAmDKe@W9BzHBoW<3`?9#gs{j8K@%;DI^DlDc7+@doeYj~Sg6^B~p$!!)c!2vW
z{M$OlKk^ni>7@U@C;n$FO<X99@xtO(5aob5MH2%n{L#tQ-AH=;L*cm9B(ySdlO!gP
zDcT$J%FO8$8x%6d_0lSfF!F*%*+Uh{Lc@_pqnrIip$kXwmDN{n+mEHa5AlFj9KqUF
z|6YTp+uOt*u_GV_Dy%A)Uu-s?6Vjv$!!I{d_4t8+;r@R<asC6ji(BOQ0}u>Mx5yE(
zf>-_(xhL5FMDAa@Txdg5_fURSCTCz^AOoiVj>s<JL-d&-G}N)UFE}zxX!UKfBN%&C
zx`sKuCWx2qi%M;hFuoFHF{v&mA`x;?{)(1F6<HCcPe_)B3Y%e&R(9g}sEPD11yeeX
zq!UD!QW?r|;oy!T<XngtScFqC|M@ukuUhmE<Q8G?!>KxoX^SXtwH&zu261axSEJn{
zXm7Qg-hWm6|I)Wm3*uj*XdOI!k<JHvsFLp`_u<b{tRi9~^3K^FZObxLh{9_m>f`kA
z)y$<&a6O@nmNav=(y4G(L)NWk9zVImpK>(_TkNDf!8&}yT=<*M^kGJ+W}7Y=^haV!
zL5C^#SuU^0X|UjBHYD(fI^wdj7M2?IIw$FoN}G2E-X`t1Y<2fOeU>ZyPa*z)MGizn
zAQmnjfMhBvKXf2shv*7_C9qoWh=S(cBA4}_qM`pojli#tADQZG%I?^h$z|kK5;PH9
zbg<R;m3Ou9346M`y6~L31%F++q_nG8Ipq_wvClNtw%YF9%s}a0#9Y&N$klXjBc+gc
ztSc8m1S`$}o|T~iabv8$bcCJpsiIoPLm}CG(=}X6f?cArTKa8!s&COWzU53V<fQ?y
zp*P#nshBqVCz7>&q%E}L|3l6AkMZSyAV>AD$T5E_zcsAv5OKl3zFfz%sK18wpU45i
zys9Otg|E<!3bb*>16-Y9G_Tc0Wz}FO!B6Q-{B!QyJ&CcRV|xS35!EC%2#1Imr{)Bw
zkZfLDidP>AM6e--$nkN_!%+8N6Nai4+0q}>nGIQSedai^zO~tt=qg7>T36`4Q;lF#
zjEzYhZYXAxmrh>_!|>6r{KtUge{L=QVOWoDeL3+?1pRIJ;BXs0e7W`I)*u+)TVE~?
z{m<|LfaqJSvPSyR=q_u6t;>nT*Valb!+<;TVe-QKYQ7-y3MAZ0-vD#Ji7hrudMz;_
zAeb0vAtEIy3e>29TNENa!D8t-%-sA)2kJ-t5iOIz8x#C5blXE=&x@${NYDb-k)bcM
zgyP=YbXhuKj9*9Y6MEaB{^xe|f1IcN1G(eB$ORzii*Av-4Ikpz|7y8gUvBYM%O(HE
zsqO!+n(!f#hUtuvJ{vFf6jwOcX>?(b3H(}znLagB%Wy7in#!IiB@s$(tOQv$0Hclm
zK>5VgHa&_6OI}OBAg@PL5gV&e-In1F9*e9FzN<4Qp6Mp5ss^~HKkAh{ga#XxHXzMM
zt{hxWIX9(CUfc1%tCjzYe)k{9&EozGax|f${}QocIB&y;b<E?)zv06_wHzSOiBxQ&
z0LXDI%r^MQ@fGqL9Rfw8A!J+>Nzxli@2|?73Imi&OV{|%tG<km4m&IjM^12Sio>A;
zgjK_?+CK3WIqX`gh0XTANAi`O>6t0%I1qewlzEGe95s#EL9Sxh6GmilEczR%sd?wx
zx2LY%Y|Pm1Zcqyb&oc{`)U;-}a+vTAcHP`ueY&~1Txk9DgU#G-PjvB4`_0W^j*?nr
z7?y|p4!&XEh6oLM03@$#8>PO^-Z5cjX#7-{nlLOBQ05Yto{(bcTHrvwv+3<=WRT+^
z5}2^IQFE3KE$%`eN)h9VcYk*N+(+8?f={tgT5BW(Z0epB@GO>6!1Xli;758!KSRQi
zcB=RBu;bOVq*iIo8WF;UherBHt|~H))&D7{nQ|iXR7Gc_($r&<5}CXzk&ucvb$jbu
z_lWdq!Oaz&6?11{;Zx3kMGjjwSON^y@T?%pL|VZf-LJjEqlf~)U)zi1YYqX^+r^N8
z9#omi|Fk?rQmfl*GU-e6K$3!sM%1%Sr~~#9T}Nl%ni<~DT^wPzkL%DdbI)%!yT7`0
zH94itNRNxw2$8!#H$8p~+D#TsI(~gnksb{p35+H;9T^jO4v8daOUk~#ZX&K83la99
zPUo&=VSl_jI)u#kN_)L8Cf6~}K{O^2ZD^6<ttlOG6+Pb5#AIxU^qR9(u&7Bom_9@0
zto8h$GOcc&FuNp-aenv#6>2l1fBeNKxT4|3?)ez=2jYU^w25MaGC2R!6RDv53ZB&E
z_Q}lbbkfDQKvIz%yo<MxlXxhKXJl7pQROR5+()hT<1RUlT{GRWJd3g~MnUd6ug83|
zgl25=^R*+py>vOo!sR4Ghz9HquZWM_#hDcxoOO{*ahlv~p%3O#wOZZvdFl2H^!M;Y
z*9CTWV81`~F1$6!=rf{E-Mar`j-fBisi`13-9VnfmyZ6SRFDuWwxTo=`Q{}ZZ<N#4
z{6&oP_z(~63}bse7By6s@#}^E(YoRvylR@N7c3O<^<Pz9TBNE`_@AJQJ>E3GY2Gc;
z-e<A;EJ8JBmTfux5U=+5Mj)H1BfWqKVW+y#^9^(vbd$Rj->F@a_+(ONdRKYT`Isqz
zh?BZz64RCC0D}}#MH6?p#$`UM&<B_>JnqOeX!uKZe1+h6I^});Iag=GlDvqliX(+l
zd%3PM(?`Ul!l6E1bHTxdOOPVE*Ez+hF?gn3L-(?2h?<sEhN8zL#jUzuCK8b{qrb$c
zlQIi?%*en=#)O?+sP55{{Y6d+19eMMi85UQru1=vVRC?kz~R=d!+?%yZ53LOfP+0^
zAYd~t$99^QM$)Q3Cz3uo&j-diel&M6P3NH%uthZ{!QjB{QqLqeuwy6g>P0F-Ak(kK
zl#J92V2;3v`1S1ON{!Yt;uAA^PRS<W<`0$Z<C~j{;MFxS&No})X9(mr4Q49(h%^)h
zjzCAOpvPgj5}}43#Da7W?=UB$P;?Zr2m~D&%Kf5{97;h56k8V^b<QGlV{r?;_Zh{T
zn!IJ#)Kxe!C5g8kpU`Ec&B@G&XDFAz&fFcxNX(h!-shpqx|UE%W<>6V7+*=w(9;7}
zB1~7UU8`36Xt<-ug!0sFqO%NFq4*9G*w{E!mT8)5z2OO7oVD}V>MEopT*?sa`Mwe+
z!ZNNjUDefYY)I7ly_+%SZVPmCuW9FuK>M{4j>*l<we6_`l(77_6N6Z}QU%PKkOSzL
zM%sf>NPa4EOqM%YWCyV+*y#8A^Y%w&ha}_TOf;dhA+ZOK6svH1GPN8e>q+vV;}gl<
z@@RuZa3i<j@1!5Yd^crlpWgMJCf*%p7MwSsZBvYz&-D;`*eIJV>o2suYLlKtQc);c
zERVNSqd%$J=NSEZeGIQE?%umk-4<HCpW)Lov5^w7p}Oce^fn<cek=w?Gdi#Mf*;Eq
zL=Qtm&DFEbw%C3)lC<}hd;Q*<)n4rOU{?OyWjdLUzQ~WYqzRq4YocY%e!S2CAPKc7
zGE*Kkp;5wSgtZ!92TWK?)3Udh#?@HP%C8LD$Yp=8O;bdO`h>2-8kvemMo7$sd`n42
zr29v)8_>na!-&IxzsM0`AZmA2!E-d$fosi7eqePH+iX@Hw3FOn66^FA0?y7AcY`0@
zN<Lz~OHU2Q9=<r)4Drg}m+8*aV?Q0OB&r)&Dm9$;t~Pt$t-$F}Yf(*~^s<SiDInxy
z!C*tc%ginhJm7{_^r6SfP7zGy#?g@W=L6aLPZr<bOb46=$r^Tan_ic=<!!%XJSM?e
zttfwir_33<sU2o7Q($kNu}k&f^fBL@Cn7`pPnB;0LHC7KOHk0K^AW)l=49DOcHY=P
ziR@De%nMf4{;q^nI_YtC!X`u{bg;rulZF{tNN9&uHWs6W@a!qf;i5^?k+oDx8&e$i
z5K5V)C#{zFWp@V=FWOkOiyaEqT>U9%Kp-SZrY7)EsvClkMGC=epfz;JFvvKu5*1r0
z$(xZLa;J39utCxd1Jq}8XQymq>3SE2#?QE;19=4tN(KA&bU9|dIf9?5G%>CNy3!V&
zG*hoYf-;3eR;zNV5yD&1sIbl=q3^F!ipE2GKWWkRs0tb6t=&aGcKK>aKYUoJT&i6P
zaMj#YN-yij9ZFV>Um|<ZSzWaqy}GJ>9eZ?QRFB})x?eObjl9cA!`f$xCmUwU?Tq{q
zgTChI`hI<4-e>Q7`11p7VLav=Gr&on7MqVTPZ_45X<)d6VD%cpBXt3#6JhbRs<M+w
zE1zE#$N88LCtAsl(l6r`Ro>ADunfVvdiqFbdLfGAc7cb4^@N{sk#8Y@E_N0WipuA4
zmFGO(Be@F6wquiSTd()v$u4^OG-bLni4UX1gJ8kp{Z`NPQ(C$RR*Wr&97JC*W3XLR
zk4;KrKXG;{jM4C^7XL*~003{@Q6rnD?ub+6A`V!y(91ev<wv`O{)sOQ{ef7qTsVF#
zrYAl?obrglBrRy&{!f3aCt+QGGpnKVDrX;|!Ydmri%ou}O>06{_B&{QC`bs<6@=p$
zQBVLW2u4aU>n0r$<Lh-}2O{p92RLn&Prj2qc`W<kNH{KSUaN#|Xa9k3$&|XfQkmHc
z`%kknu(9Rk%fYn_6|uu14fAuk=VUlM%@#?mD{f3zQn_luOOKWBuxqEY{ZKuBZ_{>h
z8Fz*=zx(I`7@CdKXNLtZ&$DZ>`(g|gETXZRqO=E4{^&Lwc03Fx8UU0bs7KhKV$~=`
zZZ?x3hREHX!tB|FrQD32`pplC*HTwj3GG4pvR)UKoZgjD&3(@{CN9jWtIX5szBF0B
z=XC9BVTv3r)X!Ak7fx5Nl6*%&>G8Qdja%F2gzTrP9nF-C-kY>X&;1o8ov7S5HPNw7
zGzOa{z2r7{B;_<9Ycw3E4}Zni2M@ra?n6&PA`~Eza@-&0PWg>3NixDp2CY^<HIR;)
zKM5}Vvkd0!`>lNk4ppojtYt<l^krH-A3<{0C-@ZgruORer4vge4+e2lfAr`_?g=CK
zf?2HM(oMdYG#Y9jMth6olG_kQJ`{9NFu3!LRFDE>0B3?BWr5BWp1YO}FQlna8s*zk
z#PImV&@C29haE1ysZTN*Y!cp>Pa=7PZa9$Joxu4XdKKS#Yn7)y8b}>;$u{{XMU3r-
z<F3tA7G?9z!<k3<8K)V7FtNSXwC%o-=>o?m`yZax>ovUjWAgjH%n$x{vUmK|1<wZ3
zp|WoFeV@y1NxF=(6BNh)BBu>N)aV9owVeLbN?ZY-H475&b`E}9r_i&E4eBrPNSHJ`
zXyW=wBo-!YReTnXpFO=FSmqZS_~1{UOKwQsmU$n(=Dwm&aV=R$MvIE|g1hy+;YX$d
z$qlY2tj#P!PlN>Te&cTEQ5#D>wQHahJIEyDv_Pf0$bTi4@A_u3lX(W0eizlJx@C~u
zUIhSX<0K(N@l;CPA3~vU8)c>vflw$57T|_d#n!E1!~y0pEBJYBc-0T0APHJ*Q4K00
zztdHgOz{%-_R4*8g8Vm@etJ)AxBuW<c=%g)koQ8_Y|{>R)1jeTN|PAc{oGM61`a(^
zN=Oi_-Au8XU^VQm)oA3sKlD&My}H--{A<Xmh;Xr|2fqP;p))Ea?0Tnlmq&Y<gDBcS
zONasvBO8$<=>ZkiFrYD%u5;YZ!NO&HzUISdXZ|U54y>U!M)@D?H{SO1FKfTsl!$-f
zv0q1%aYOPn&~8%b3BjZg6C_L4lsj2mbEW8g#8}z$%GhWvGI3F_dW*c3^U8~*3?7by
z>)7Cpm~AZhnQ~UgQNAWpwe%Cp9**jA?{tK!q0k+wpmE0z7#1}`7?8g!u1*M%Q878M
zA377yevvhEVtHUbbNAyPgRSqAqS6x-QhhJqT77Mh=U~&9|5nSjzR;zN8OdqBQeKQ!
ztIqu3CcVt^W+l>{>NCbi+^s_Nhs}Iv@tCz?iUVP!GtyZ#UycIb{JE}!`Q1L;5gMyH
zIr~RlU#!MRqHsIpQCNLgC_-)kg~3t)a3ajzUohaF1^0(w;e_4nFT}Vm2fd^-l1Cbu
z^)bJ(*Lu5O?d)3}0+VC<i<}z(anMkG{)y%=X5+7x)6{bfU?y^OQin&ghVI3ELymFY
z#WT;JQx|4GV;vuWPa3V(+<RQXpM^W~?$ahgh}TcK`sA0h*>x&j&~HFMNZZqi%(J(b
zEJJO-|7?$iif9VQeCaHch{qzd?M5)had!@M1{25O166z=cAOPc$C9iSjp*i)R+Q1O
z;8UwCrp>a~gyZHj<^z0gJ(VTXI{`Tv4p{{|qS3Dg5(myG`nfKyn8fonzVca}X})J&
zl`1QLwz$Xf&6$q6b@_3@!Sa!;&2=BjetG;y@Yju(Vq$KWeajaw*!Hp`8O_2E&$Gk}
z1+u?A%`yRpMsNyHafTL!5)(%&NTEfVL5QiO!DUlp^QBUOY*y(almc=Dw<~+othdJt
z-(2ucNeQPq4U0igZ^@Lz#mBf|@}(WZ#CjDC;NW8vs+Q_{>vg4Dh;QlSy%WFl8@Y*_
z=$q`f2iH>{>aT7D-rwkuo}q*~xq$kftX{Z4F)Ee{17(V+aLVEcr4olnVh|k=tZoc}
z9h*%kR=B&CS^mhZM|V<Nugss*P1p4?V_M#K6P~|X7hCUtwVzrHG&?9LTNYklIFQYM
zR4Y6-^7+D?wCL<Bp<U)_>cX#&$1Ysq#il!H2|Z@)Ue6<}<jG5q*D_ryMU&piS@Un5
ze~H|Ks(Z1vIB=_Cp4}19rB=9S1xH@s+Q1G!BXzLckrX5ViX2PhtSvosJREZo_4I0F
zR=hj?P38HAWbgOKUq<tsZbn}1g*CQcZ#|v;v5_2i7|$kdY%+C8`aL&QiZuT;u>6WE
zbwWi_)2x+}d3{~UGQ{)PA^YY}4G@ZfBwDC~M`%6Mcw&Hn@JD)dxvV<2PV%bMwsKqX
z9ui>r^0u?0X8YhTcVuS{_ckx1I~Kn)<)r_**_S^9vq_{_8e_m5J@*Ax5cM*UQUNjQ
zdTNXtk{SpH5bO*%EC4`-<OK;iFtN|s5UI>=>TVdtjVR3g*!Ml7^hw|r`&Bt1kU?gg
z<LoR|Zno<awbc0v$|&8*lW{a6`C%3xLdzHJZPsaoCxM-9X8c@QTV{Z_R6f-?KuK_>
zLa|e2*E8IY%8hb0d-W}^T}0X@swcrwwE)V!=4oR=SPotxM#HfcQI}{qxDN{Op+%ux
z9m?7;aSqM2Z|R2L^`!&~XZT)ko-OfLG|xOOw2pI(Q&v^>nQ>XjKX%?-e^^UBsiAt4
zt|DMzGclng7VOvQ`>cc{_Fm$>_fYfEdS^lE?3wR4UeNZ{hj*<aDMOM>s&oF#=H96M
zntPksekSA~QG#PkAyg_5s#`A*2r2>9h$AIIs|aEks2&86BH;iw+M7Ou9YEf>V?^A0
zyB9Iv;%Ta-RqTf-=~r(Vz3j{$n;_jj%!s{<4W*0r>zQ2O{%RM=d~uMdS453HO6w(}
zB6)W|Na-<)43W_B$PMpMaO-rEMmNoDr)wO}yt=`_@X*rb4fN?|%7lwuoASLe$#)`|
z9M^3&e57BI_jOPBnZxiPPB9&LRM?>&p*1ja0C307f&fTyEQ%fhY6mnS{(3({(3fPt
zl&J}OAHvU@an*QYO6Rn}1fv;rgPyKKh`MfV>rgQIrD{fRrRsT9F{iNLyQ=2o+I-0;
zhY>x_$20R^12Sc}9~343iz^omK&E_E!Ut$QGlsc<0PrINf}aQ?gj<&pW9eVwMs)<p
z*02sI-b-)HT&yhnU(GnFS9#dTnB34m6dBXG{uNiA!8$hQs5KUMIHec{=K$?>9+GI1
zgCaWIp%C;_^dnFo7-g&p#vf^{bA^O46*dghA)m~xt58ked5IG{#q3tqph6}l8vfQ9
zr<VFR5y>ZI2_42Or}VbLUuA)s?z^)2k%X$*mD|CB>e}W-DNdzhMzf3dp07Vf_~jl1
z*HK(u>6G`(<^(9Tf62)g<T}t`IpNhkJ&;SDP{<C!`&C_QOhXa(E&Px#iyt%}2C!w}
z0`3)*SriyK44N<%uo8mo_7QCuiny?z_+M)pFXsQ`cbmLFB4xb=i@PHdwP$XyKzO~Y
zyQr2gRP7Y}!z9ACJZ1S(wLIV4)}PZ}J^<BK=x^ZvPQTit-0X$=!+FO&&&q=lpvK3y
za#8zp&P~X-=Pm+UAD+I`S^je>Sg#1i`Ya=S$O+a@0U>2zskkc%zBm}50g8oYM-u{^
zd~d$fXQr|T62X0!%NGug@3T;Sq}qN_E?arBdHpMW*KH`3*`;d@Sr`S|pRP9kSRIS|
zWjgxB64ffTpZ7wss?D_)lL71f<2MRSiGogYn~^PBy=z~-xoefz^;L$jnJ2yc_@k^`
z(dfQ`P-*{jCN;9K$K80^WNSI$-)B;Blu~J+s>MmVU=YfktY_qXYQsnIqo0JyKcbJm
z8OX9|j@@SRv7hBpBTOT$a@WGGqu!c<=kV)v4DTb@dWtqJQ**JF?O>WpHRR9ov$QJW
zc(kWI**_1gD9P3dXMOcF{A*V+03<CyCA^Q;JsiA4?6an>cT|rcqH-HDZd?bg5j5{3
zsg|wa>Tc0uYC%hnm}=htIY~XQXJm5_1}GFBGtUYK@pe<zJV0^+;n+xaBoy!h4#knI
zw-<ME20#?ABM(iC%Y>lg^SYjI-)++wbpBAn!E@GUll`vkzKC>mWaRApK|9&l0%v_x
zkN(vaH)*oA>$OJn`ET{7f=!P^Z)Sd%C7!63y|TY#mTvzwky_>ulsxKIrOG#%dG_;e
zRl3930k*)po`H0zuxK22ssd@2fF7g-v_go~!?FPoAS5pM))~Y`VuK+352`9>Sh?(z
z1vltNyvf#sT&2_+iGr%kp7ttl1i!ml>(v13n=xfCe<#Q;^a;|UmBs$Nl~Q8xKu@!o
zKQw!wU(M^aw)+>eoyP?(xn!T>BC|hMc;{8?#e0iAv>VdGm2^YV`ZT)ixY@qG_uijV
zpj`uuYfC76NZ75S+b=+mO@@UQLn?subfMZO019yabR{+!x{qWbdrmY&x0<qOF^H`$
z7*E$G4gJz`(Qad=dLrJ7t2@7UrOB>b_L#81chv)%cjH{XREdz3x*l&7OnsPsg(Xwk
zj<dOWdm2)2;XC47p**f^p(n|FKZE0bpwi7udmn?d2Ha%gSV+XDIb{j>yS;lM6eDmD
zc_%Nl4@FJ531A>!n|*hO#zdyco0BYJddkzB9O!~s);Gl$W(_r&E4`%-vR}_pFLNe1
z!B$w<35%I#<6@r_J&;=3zEdUaz&(>?-FcSV7M|Vt&`VapvQN(H6o1|BE%b`%@k_&S
zstO%#dm7>#EjU8B1V`mBa<KqJ*<2;Oo7OWsfojFS`;kHX4IL5OtxLOUt@B%aGgq_o
z2#s#NhWcF;*1jLyiFW-n;yT`qUU;yIIL@SFoE%={4n^VuURVG>GsttbHez?Zf<ti~
z#Z7>H7c$jx%);{RLIA4hI%bB@?c{8F9Uaa#XeOvz6IN+bEeqnSH41f}cLP#wrW86M
zHT8yKj~cnRwD(nrHD2$8;cKd;Al^&GM7YZ@)>dxd2w4(UPsiXcI^fXCjGW7s=}rC6
ze=o!}nefQH^^!V{bSb-yx~QD=G#eJ`5d$NKU^yBBZ~z7GP{maT?lRvmf!^-npjMS7
z=s4CC`lz&d?+n0&j-g+8P)G<YX^kh<RKVgPDMtoxRi8EWe5b78_z8V)OGB6CO$K|P
zMo}|;;Ot%4EFQkWWTj#VS7K;e6C2#<HyESMXBIM%o%quJLA59U<w;4Zmypk|9}KcO
zAt<ENgA&9Bt00_i66cs51|k6fY@mS?stiRTEJdo<bs7ipBJ+a8w0u;Ci)TraCxf<*
z`X0%qeRO#?`qq6hy0*s&S2ee+gqTqPwZ*5bHekD}(rYJ8PNk&3ZDJVFVrW=uGJ40>
zW;b8OP=uMuCgkOJiKYRqT-t}6=#LkM)hcR%8?%vGj8a6rLu|8rlySj__5?dMHs~m*
zXx9+>t9V!k>4Q!b6FC+b3xTI1ssm>L!kEDx_NpdvW@W5F(>;paHEpAQ1vsR2<FP`O
zLga$X;#sM4$?W#MyDyu#jt2tnzEJpB1W#q&COGLVewg*#jjw?ON#P%iiBPN7RWZb+
zuf&sG5lnLy;Zv`F{TI1g!<rk?|5wY!;s)Fr)&~YwTMR_JZbRaTe=)3LFK>u``CPIj
zG_7zfmJ`MBS#>x;>8j+N3PrF{vq(~CHy+|4atliVjG@8CY7QNMPGnXz|3HG}U{3(K
z&~A~HD+QT`E2yS+{q|?<Kd}W_L2IwiB>JOgW!BS=#b~H=HQcDpIJ%Fx8-}7MOD$Z}
zik_Fd!DyG}p^}<C9{4BET-H5K6sAhr=l5L9`9i$Hb9iOH=Kidb%CHZV%+}HTzI!T2
z_oP;tI4Z*mrKU_;(PzKTAy1r%B!<{P3uTZ6ARABzoDi!Xix^Z*FW=_P#O*+qT<mo6
z;Q_nYtNZsD83W4s)$g*5|GcYOdMbg(C*D;ef|Kq)E7UcrKk<2PhJyEIh&xkgIEsH2
zED%NAuDOZ}^Jp3U>AmIFaC4JJ_p41h;d@ByImu~xC(n;J2c&BRVz(nQ2r6WWiVcC@
zDUu(rL<Eh8WPzVRP-n;y!c@4sFR}oVijRH(-jUhDTOpz3CBR|K6f?WuH!(F@B<)V2
zlQ~=PcGPs{hU-zU&}u>d*=39J)7~J7?&`Y$GdF;(B;QRXj^;M%r~s{l$3!!e7>3AZ
zX^w2vWC7{QOpwYe-psc7?DM=c83OYu-)7o9H=r{zmYzy4kr=`b?*mjjKJsglgco*g
zi)!-9HFX&hk8p!b;k4!OLTQ~HlHRcHJLRr|=Wn_V#El4Cn`z%ZZjVgx%DeU=+Kdzk
z>4~z8Z>=4j$#lAsZDbp$=K;wMWjs=}FYSV?L=($)ZvumKX1wIAlP7%4pvoPnMfY>i
zYpu#4=c&cN$i)GW=iF)v3pD7|EnKD`77Nn7cy^;50P6{UX;do)^p>F<k500&;)kc$
z+yY>S8eB<@*HXrGxoX2Lu!1{mB}X1YFr6@|5n_;TcLeJQEr>OX4urZuM}t@j0gM3%
zO{jW?Bto@@LEySV3P?_7Zd5cVSzIAa-)u|J23t_0cyD`l=4adcN<6411OVz$P(pI@
zIAM`W!L<l%L(?Qa_sJ0ijj1IYbRkmkQo>U*!1L0Kk7qXM-OM7%IQLrCKn0bZqh3^P
ziMtgc7gQir9WBbRDJ1WY#xR!Sc2rsIlW!6N3B1Hm+}lBzLeN?v?7ji0keI(Efy4tw
zQA9!a(!)>Ls=~TK?`%D#HE+Yz;z#a7-+j)=S<z440+9>9l|2Kpq(IMDR{AZ@MGX3!
zUhhSa_Xv3Ug?h(q>~G`0-5tESKCkZ|ewgJqy34umQoVfR^1b&A%6P-ZC-l32;_r;P
z6ze;evfGs=zw6LQD?=g_16Y6rNY#Y%MSz(JJ36d%g|~U(fs`OLjDWP;7`i~~9;Zx|
zozm@iDF)f|N-`aH&zAV0V-}}hXP;gehAYt+_*#o&s&pz$bJyHiI+ZJ}I%RB!ee#vL
z=C+{A8+F^)zDr4Zvj(N*trJ>q`uRMThGgbyeA8UFGe7_Kbz3)(1KXGuYdQuvcP~VG
zNE5*rz;}rND|;xJ3@9;b1x=hqV@L><zynrb1SGeWt0ZVrW`P?HTEi~oap$%Wqd1kR
zxeX_X-l>Wfcr4z1$+U*gHiL-gw9F0p*o+QOw1?Hm=kG!&8w^kWA{U8)Y$s{Y7!?99
zCU6&q8UU(mIc_s204$)&rg9enc&AzK%0YDAV1G@~{LnVwSQ`Gue6}tll`A8?YUKA5
zwcDxXfAhNJ^vOa2Yp(2Ik<uzcOUR)>sd&e*cs7`W)gP{w<t~5+LyhmCz|`nD>|SE3
zS@4RgNoWKygwhZSL+JvcHRt{Q@!e32IED^~la_d#k`$((ge8m(l~@n;u5ji}<={&n
zC01M#et@>kIMYwEd*l4Zh<lJPMNQJFFxFl({;iVsf!<WUvl97TIZA!U(%jNm=g9|e
z=d%rW|J3b1bZ(pC+b^s9z9V%Y->_)^M*HUU_PnL5jK+Gyoa*oG*YQ5w)sfCd4}Vc2
za0niZQ%ABOJhEs)<BIyAI!dP0984%{i>A<MT~X+hL3gSTPyh|l0L3MVg5^KL88L{u
zLZmzv1_F<k_KOimkK+)7F&p3n8ZfgQ%&|}fUDz+3#FwsxonpJm`pf-ud^wK~=R6z2
zx!jJmg<om!+}kiUo2t6372H5_pKIJa*{3D#jhc~COC{H1OW}FTJH=)D`A~05N?YT>
zw@N;5Sl=22CL8%U8GIdUeG%YuuWr10bXw=;{&w}7B|poXGjF5mh1hhHYrJYO5fRzX
z#Wn58?m$%q)roGtq*NiDHA;Ceo^UWd#D)m91^}K+JspK4OiEGM$j2zoF8JLJDs)4{
z9KTJ22QfT`<Zv#X@p)f4JKu9X+tK(+DcJ$WaV_#kgM4L@i?$O=Y*NnN^Hl?tdkbl$
zl<$4ac$S*~d<};8;}fy&-_$h-XmR=7>{|XsP6>cG%M4}u6atZ)0iOE}0LjPu?EG$9
zxW8iT)RsQ3FpNq@ws&-4+3pFij2WP(J={m?#rs$H22$p_#|`^Yj=iYDE_dR((k@jh
zz*HacEls9Sulu3^?5eDg#%?>ITA0kNsoJ8gMn-00j(fWYmC=)=Ant)hOR^X<M>AGS
z9Q~9^HLhF-2{(0n<(HKslUkx~IQkBTVX68~)P{u8-`j7NcPDS`z~4e02Xh`I2*h6q
zQF~zqQ#qTc(qebQb*-qH!)g;t3Q`<V-^j&T6^Fr-jswaXxvurmw(m5?S-SR3O<;9D
zxaJ-kt!j{%`Z%_{D;%WuD$790e1GpWea^~gKg#4DVx?Et*4zj#^c8w1WB&aKrR6}~
z;vbjCgAd;=Hu_!vyt(mW{EZ`Z6S90IbMtnl!w%DFD16p%F_}!fa%i|P1&j*y^mbm1
zC(ZS#k0p&DkX2Rkcs7_<-qz?HgB*4)0~sy3Q>&u8v0i^T!++P_G0lN>j2luCG;&*a
z5;FtV9v~6?=p@e0GC0lzNsgN1D`JTl;=+m|)X*1?urNR?wyowZSU)qw#OB=cat_-J
z3|jKq)D3sl6)GAf%NP!Ss#0$n;ib~6z^R-{)I){?)NsPw<$(5A6_CPOr*%Ko^t6YK
zs~uDnbb7TDpJY6!jViUt?k%)uh(6IeKRrpBx7y5M(J{?4z6!ZabejnFyj~;6C-JfG
zP{~+(`qtCib!TqDng6_HxzJ2)_VsC)C4lWCwZ1Ci{Yjknwb<=n&ec*lT1F^BUXWZ5
zImIs=35ft_QT{%HCJ7sr5$PJ8rnvTYI2n5VMa~j{;EE2Bwa~1D*){9?v1k$%zUI{4
zb_x?^wjKNu@1AIxz0GG}K5c0<!dR*KB~$ibu;|4TxTgtKTta^7HAJ}tM+YA_w1ek)
zp`s&qiMl8*u`qfGp}=PssPg%Te&+j$f{-@>miMlc%#&DSbYw&cYHde<S&p{TjFEB1
zYfC80%h%?OBq6wYT`MU*rxHt4U<rq|Dzdhik|*hHJqd1qS3+8`XYV}aYd^C|*@)NB
zzw1j<@~7^i^tVQlNaV?#XhNpro?hH%{Z-7uC=VXV4T+<2>)lp@-%q#9zuLD|ZB1*x
zy)MK~;#S$}%<J1~;2>yV-${7Mkl9zw@D1gkH6!E-2QX_&YFey`(pzZe8L_f6)cQ~U
zu6hZVji2Qq%(|M&&Xz#Gn_2nq_VipCeac~6-IkD?fzQ$}*dQ+I**6p*GjsA`Wl8&i
zpd{hO>LX8{%rS>V90iUIge~(K+r%vCbI#YIynb)YBl*6Q8@2CJftsBz*z`I*xhjr#
zLSJXsyUNA%!?;Jq3gY%`@X*TeF*2#naTwu@ja*9yqEueL!k<cZj09tu`DxoVisa)$
z{-Q|1qr1!gjXAD3Q51P`PKDbw-r^hxUTn?*Q^FNN;?G;g@9_#qDu%x6r5F|^%8I-B
zA*_`Y)){8Y&6swRiAHEd+mt*uIjvQD#q{KW)|udD!$*6}j+f4;x}57KstCuNLaZ!T
zX)10;Dj_*{c69a>DF$WiMM*FN!e%B-SLpbhzhO==q`qUBA<Cg1#ggZO(sQf;jJT5T
z47@WFi8!6w9}dzuTo(JGwdWk_caU282a%Dw|1XC12?i2DrH0=U(2=5~hVWC+)T{c$
zuD$INrcblpyF}n&n2~ssh`|f`-OjRiej;-6(CzBi8^aC8_9r?I3hG~!HGS|7`SA01
z61FW?X29eMS948v79rQbbEk{}WZFk3q`i%<A>IS*uu$e;!tLdFl~iJ68rg4RYAly@
zPRej|kHwE`HfcR&CU)ZLm38G;*QO8VarqY`rMWzYsv<UPW)-;j)$bS)B?^|>P^AT7
zck#<oC|(+-CdL?s|0aFb`uH7jtD$(kB5b?DOS@=b?+LlvLa#<>sPnq!jcDsn!J;B@
zD=oqCQ-;)0Quv7DZK@2SMweG3be^`BE6^I7LhfD>COO_pKh#m=CH-1nuyg-yRU{M5
z_uJ{uv!<CXhmT{d&CH(MhG~R8C6nCFTP|DsuAxvt#4&cChg60Ywyhzt`F>a9)X$&Z
zFO1ILQC)qQ_FLp_E8O10V-#F2dGe?I`_)azpT&YKs4npC*qb`V&4StE+wZ5}etYQx
zkFqP!fV@lDi(Y$J3s|$JTNEQM5XS(OqN8CBjR}sE|0<y|L{)9fFYuxwuQ<~@63=<{
zB70xt4r1INK^}m@CFwkz8&5LYC1#+YW;QoX21N=O$enaRiBTOxS*n6b-JCVZ*BPbx
zCU)Cyc-pBAZP^`F-}%}UA2iBuGePefM5>XQEu479)epoGe>$9<sL>@tCP@j1GeJOQ
zza)Ug2tp(s-Q3EN{x_>MrDyebj4tE#wM@d$j4@hI&HEXz=j%A-XzSS)qXMO$<x=YW
zvLkw(oOdkK(qC@zd2ZN^XnBlp4MJ5)CrOT^%0b6|`>W-`Fpy}fL9$!q;&FZn_<=1*
zYiyWr4J#fxb6xHSfk0<NogdOL;&8TX@NVio<Lr(%BQ3v`e#&pdum)spMcLVTttad;
z^nGcV4tsG<dp4#iLT)cED=Ci}VF_}lW@x-;7zT?vGO6h3o99~DE^nM%;oW}HwCjX2
zyJXF!jM?e%JCunkMq}lq*RtL^%e`0+Ms9cSg$@o+eW&a3l5+U=IBxLu=6dhrw)&Cm
z$M4OsTOF#-^NSL<W+Run8GnEJUjOye-i?iy$>r1LPZTw^d)YYAPO-OZ3@|v!#T}y5
zUbxNCS<Vo$U!mf6vy3qn4o4mwg{p1D?!a)@r{Xom;e@<O>qc@9t9-{e5od$Dg^3o^
z_Y<&cvuAis(kA9ocR0Mt%LrG=Pr9uwWyh!<BR8>YmuVyOO@e8CwKN~hewD3x4jw7x
zH#?n7P##~Vz(M%))7|7c74IDM?}gMhzrMa_u@yUq1Qfg|J}V)=;Y|u)B?%2t+Azxn
zAh*E^6z=3Ap5S^cL1HVGm7Nn7S_NXg74hUtl$9Svv-q=YmOJ`^N6ckiTof$RJOu31
zesTH^{SVx{FX1O|8k#`{b{n86A%&m(l~Y;S{HEPwXD1K$HZ{{X?e(O}bAB8;NS~hw
z$BS0_8aOZ1hwO)&oE&;J8{TXG(;O6E+M|IbMy9PRbXS$Eps2ei1?)<Cau*C%MwO_M
z<0Miw36OZ0?Zm~DsfyPitdR+@ijH&-ZJhz!mLulou58UE?5K9Vr*5$`H-=dq$)uzt
zS$fH>{zsjX%lj&17whE7KQ8a(kuHBbXk6}iD6`7g=Up!F7r6)k(tJlXd@-Oa*@g?@
z_gGwa+k=&FeNf((jaBYTd_Zo1(b<CHudmO!8Qb44E&tAJ=Q$NOdN>erv%mFaS98z?
zO)`_UU!OH0N#|rv-H}A~&M8+_KZ}Nv3Xg*-8W(awfmkv<*OgfPUL?z0J2jeBJ(ElB
z8b2g*&S%^$rxlR>Q%&?X&nno9N|cT$4U15iH`Q(k7AChcj{P>Uvz9aN4vffAbvsVQ
zh0>*2lKi!Evzbt=e{o~=tk{GKXXfa_fmVQ?o?RiyuWaS6tW{aMWMAr<e5wVv+$57o
z1u&LUI60`W3&{ti-D9kVTHq4k?#I5=_<3Au%Bxo+#OboHt7WCZl{S6-_{nhgnwl4H
z2;(0M`GA7vEkiAZ((Ii^=@{da!I`c$!uj)zX$82;)Wc(D#mF|Bg2QgRn_u43^rcbE
z#b0h>N4)%cO-y_=#_42&_;#{p+Rp=Tj>@aIiLsWbQ)11+U)H`i4}Hg3RI`>`0ENkK
zd&JQ(ZK7f_L>-ARFJ9tVA?o?2Qt(_lRP$OWUMJSwp2rvz)KaCYcIBmkX+J}$Z0#@{
zqplL1wV(TmkoL2-eO(oP_)BH7oY(v2K+XX3bL<Jjr(uOk|M>NTgRz<5KCL;j>R-G!
zXIINtv)4T!=z`6vxs}t3Yagd;<%NrCj{}o4T{TrSJ{1Nhiw-A?6}Le2DV}>d={@lo
zmT@w3mrqkIZ?a#xImF+eKL|L;x{>I-bB~2(ZO8(uJ9|!cS)jqk8(;qFp{>R{kCgSt
z(fu9uyc9G?)|>gNN3m2&)eL3wKh!7~i1IkBZ4A@Xh^xElA}{_l{zdK?0O6*%HLO-$
zu?|kR>2emtA9LA6K4b7)xYw~hB0(jp0HDi_aRx&JJ>}hF_HDKwx&KPD!UJq{IfW51
zAUTjbnzfZw3DYK+c~()lg)Igz<KT8wAqu1_;LmySntp2SXjA7!leEe-`rz)PtdGiO
z@ptfE82+{`s*bO}Vc_f;zB0NFd1b$1V63wr{`hj2{N25`Da$u!TluHKuA-k#E`6`I
zeCnw>mxZAesazyH$Rcn(=MfaiPu2}9WFW*&a=!x(6{mv?R?q=lLv!|)3wl<agxxO)
z?z_+3kFCWxPZRDv2dB{#y$LUKmZId3($G}jMS1q4u%4hl(Vv*Ed*Fi3(=MuV=v+rw
zWvt$CutX+@FX65+XTSZ>)`v|KS_ukd>li#(SdU-Mrip)&J~_0XNZ9Rqr9vekl*u*I
z0q6sqfDmg6Y6K+@MmVOy^MNF3Sx3wSx)eYk^J6-ju&_|7aH-J4-tgdGmSpm1t_;pT
zNwA?esUd30nnH!Z){wVH(Li$-D?`7&!dBNg(t2(zwJ4jgPcS`c%#Z?ZVnAHo-%PSJ
zJ#gl_SLQ@DECW~TtYsS;8>+hBGObWPp_?PCKR)DKL^3jB`NI0cpkeLuO<ruQG2i}P
zRmkP;ba9!Jlx6!01SrHnjS`xuC9ykf;LDiLJK$p5arh4yz)G$xjuocM3Bq*4NQhPr
zJX<(o0j{KKgE`9)@1#|AI|?PMRc${#BLjg~R^%#4T_ujY&+^7fnPZE-q%|B1^wmDt
ze&uvD6w4l!tZnC+uY$)F)ta1^o3BVX5XnZO9p~IU-^lc3|1WYG0JcVwTD2((cuk6{
z^fxK^qa3Tu76vOUyHw%hI4HKyiX@WTSU;PDVyl?`cwi{%Yq|#g&2c>2tKp@2)0^Lu
z8fJf+vn5w@NS5Ut)0u6$oRu1zoiN@?MS=|qQ&r5u#nfUBxv98-%{UxXBo}~kH#_B4
zg<1=#QOn8`oe%bjiC84Og^}UGh%lY?KTHe1A$8$UD-Z@M5l0f%XK{oZ$v~FlgxF5H
zqpHkmG*RhHFhIG;s|95suMuYTdT4V;A&GK6!N2z<4UqEr-ksph-&&%8fA<&TxGySG
zy>L@a3>4kb#0#hBvhA?IiNg(b?{vp`O+^yQO@EtwgAI^#t75Mb6^RiuVMzVxAlZ&v
zo-rp*!GmC^WGQ93kfM*|q}KLpH7CKUFjcdPyELzTtF23(JCtr)(rp!D?x7z?zh!@W
z?*g=#%ue5uhog23Kc;J;PMlBLW7qs-W_TPpyk+n8he<DXM(Z`>&-Rgn_A@#HH6`KU
zOB+qF5`5&sc|<vMuiG0o!q|a9Qo|tt0sujx*kFa08=`L3NflUAzVD3P-~0Jrn_7Jd
zS^sA8@qzr%rtX#gG2Mq;zQ*e!dO|F$FgU6*z3e@sT(W<+w*1yIUFMq=G8KGgERQO8
zqs<gf-j^`b58RpRi<V$I#RqA=i&cX{S{??1vy>Bsso7z0iQAE%EXPpXa7Q9=Xi|qN
zfWbgafiPkamhI{t=Hm(t#?)%pUws84*9&K3jkzuz=QlZ)x+RJ(<d4sDgW35u-JW;_
zT1d%cq+gQONqp=)ULB};wQ%#9WA^iNHRXGofA&t^T>eEa7=Q@#s^QPkpkvv05Vskc
z28ufzw;7sYZW*k9eYp)Y^VFELul-wXUxO=NPdECuwO`+aT)!3vz{Dekj!jDCoZ(~k
zn-ow!g-cr$ZWQi{s1*%f6fR00EsM<#S&^jzD?>4GmMjW<WYZ(8CB;aSM~PjtkKpAv
zafbEx^dEB#``!K4eh{Rwup!7g_?w=7dYEsbb&Tn3Qi#@*S=+=b!pulk`iusN2aUje
zPC<-^6*<Ak@RC72u!nxOIJunMW9MB?Qf$J#<QMa%ErSd1S*J~lM(*SCekK=*^N6V!
z@~4WU?}+I7LLWy1jC6d2j}V|f!Uxuf@d}WoDF7A)hINRQ`-AsWI)A30ncZn=2B+!A
ztr>619LQmb4x$l>Sy}_fo;*kU$Aj;aeH1;}T75$^?v=Q`H*1^{c)E*X8?Jvr%)uQ`
z!TB8on>p(=8SuRv9>xy*e({hb0Dgvi{3Xt5<k-Zw#pcQH9~hB&gpi1*o&dRskRfx3
zz;A2?7*ZdOdjdfMOrSbq5E1~*D29*9Dd1bF8cOpB1jv|pei{q=Il8<2*r|2L?WX<5
zS>jdEWxsWHW_7i<aMb(F11gF2>{YT&%H3e$WVU0$ftg7+Wqq?hlk&^Yv<1%d^u@Q8
z%zrORx;}ouCBu*}E(Lo7^G|0nr4W`sg}M=P|4aa!L_(SBg(j4cb^KmB#X17J*lRe4
zvNW(mOcXI@AP%GnVBAnikbX*#v6^P7LJApuLT#l8LO<hIdrpm*Ec?Na4-Nr+M?YMZ
z8fBOlnwmbS=V*S6%=aG~QGrDlOwn7<2-n0r8=G2M|3&V0TE7YXH+RWB8;%PEtUV$%
zjA!Pz9aMK^VAb0r@EFV1e_8Nj;Ck%X_}2#G?U6&@?u;a;JTP6C$RfZ;s4}%2hYcz)
zSpUD3Cnn%Y2p+0MY1V#@{_MC6w*aqqG|+0&V7%en$}pe;jmGX<EewhWFeVs)|J95h
zc2oD#0G|j`P(_K)hOt`|#~q!_0}<)!<@b+Q-}>^5T6F!%R*1S*F-=fxRG&)&-UW$~
zkGh{LgllddRJpY$j#@s*cftBKr^cVQyl4lzd~csT8IWK0@@Oh}`DS@De|Z}KV8G{^
zDa``Xh#@yT0x$t*FGf}qPp+Y}0xH*Ki1x>g!p2yj#jy$tABn>VkB9K+HDa;eQ!mD_
z#j6$m8ho%}{CMtVbE`vCP5;9`fh1G|?b5TOE`p+}546=oAfEqEd)F1!)Yh$cLI?p8
z2u+G~0#X75M5P@KJwQ~NfCuTJD@8z1I2uBSfb=Fm5}H9N2NdZT1S!%&v(bwIR6Ho6
z6d^aBJI>>IzvGU7KCQji%baU`d#<_m`sSR1*H6g4(P8f0s)@=k*f)G>gv6xY|NKz(
zsJ`Zp%@Z@9q>am{=MQEMrVnl8$_{omkHvldM>Q>1?oc5c2h4|K0tz4>j4sqY;~3@w
zm`LN30pfy10Tj_kAe{;j>Fe4Jd}+R&5A(fBZZ1WRmH5qUv<B8G)Y{9<uU*j4nwQC3
z^;!*NDjB^K=s5@{FEGsdm_x03eZLpy`7sBcO?=&mKpHky&6g4NNEi6li$Wz@Fshi`
zCsw}2juWf;cxUtBUSHSY682%*u0#@+wGF^yXu6spPP!&Akbyvel1@urNaoAaJbvvj
zmzj}AuYT6vIXp<L3$~5blyzamm331j)MGNuJ+R@AtJMb6)_6GNgq)yzVgu>;4v0MW
zUY(YVR;m;0C&`~cBoU(UJB~$O3QkXCK`!=+O>mmL5Nl(-z+aKj@h7M(@ZGtsIjLfo
zBbl+2N7~IwZ*F$UJklMn^?@aS2x_JjtP%m~X!z%}p99tA_~Kl}!6bV!p$8SmNoF@d
zcW-f%AqEf{gku;&i=^S$XwncjIG}vJjJwt!QtCM99^`iA>8a;U*PLE4qh2Zb2QeQl
z*njT|Ptw{Sn-6_fT}04li%H=!RFRbcrB+%5do;e3ju*6$ykh<2?AhGQrfwE_jFXJZ
zE(Z~qnY_SQ&Ya+crr$;@6i+6c%$6c7Y1&*Um!lYJL~xH26*0V!Y!0j%MgSrJAVo0<
zP&u%O022Wio8#9c%nclzr(r7(r=h44SHxmMR5DzC^cEK+j_oWU>YOA(9UkB&-L~EN
z^ft{OAUD@Nhs|cY=2pJGdbBdgRGkj+4Vrv3T=|~dS8#X{U9vD7^?AH*&vp9fL(o>3
z)L)Wow`pvOi*Mk=i5NZ86yhu2HnvS|Y4~E=7C+dO2!dqVgL;P5u9iA0OdvWvKy1Bm
z+k&r<E1z!&Awv`Y1CtPcK_KWMA4%58YL~@Aii4XC%10k)Eqiz-zWFfi&JZDm$dsW7
zD!SVJf+r<jia1bdww$>s(tRG7);<v{$2GN{%fs%TrqVkCS|K?-bHj$2j^$Q%455q^
z>cfXV-bOhVtDfx*?4Oz=n0tcjo<d*xnM_J?qD;SqD|1UDiyIhRzr>cqSVZtAm+D8I
zCJrg~0Ccbxpv{wkL8<kKHX3Iq))~`bl0t&G_7(~RAEHsC*smRZrC&%dHQlpP1VgQ(
zc=7#mawLF#I0FZDECrgcb0S%x9KUvq>~HUhT#kw;qYfe<Zg^>G*^pi66uDnaR(pe>
z7~3$6sSA-E)qegWO!}5>!>li<of-o-^Ux*<_BgJ0_gdeOD~KH5mTlyF@iN@qGg*f!
zquiK0)KrL941Hm$Gn%T2b9nQhac+V6wODt3q=Ctt&R__b_*pWKq($q6lM})CqA7_O
zav{9nYitHxP(&$SCdQZ54s|gON(KXDJGNvjUJ>A`>k+*N=KzP4Ca9|EUJbVsvT*z^
zd7EKz=K4|9wVKy=JM%eP5pthO<auI4H`3w~_We3bhQ6s3rgDC}Z?_tcUYR6m4D4K5
zKs|6h|9Cgu>9*X>d)8}j)Bcz{bG3QbOf@L*GxKd>gF}IjtocKY2O>}Jwx;{)@q!FU
z1$Ytum_0=aE>?_+MUsiuFphi;i?>D*UH}B_4n)hs`clOlyDQWQjz7FpwO8aP#+My(
z3vaEZwjMF+7|um9yDK5|$q&u;ul2vY>zGFCJ4d)~e$g16#y4oF*ITQ0^kMu2WpXQI
z!`vtg8BRyv%bO~Kwfz=rrOyinzPICK;fwv)AuCsM4^)wkG9w#e!*FmA_Pa6cOMKDF
zQ_xL#L%YMd<4d1DM@3zXI+r#i!_n6M%{uFhZRoBU*TSjBLfe6)J==POPa$F460HTV
zJvqnzKEWvcnzpXb_4sFV2RvOnK1ma<cN%tne!f+xA+vLCqW%tF-MQ|lYag9ix3Un)
zr*sMZ#}bi^Qe}yvuiyz#qI*Z=Ie&PtK+j^$*S@u@2To;&sXN`gXWRN#j2;x6q8gj!
zx9$IeoHM|-tAk4&5?hXr^AimBw6M~Ca3aXfoP-lurL3g|=fTDrmNh4C@CRMmhm6c8
zw-gRO$@vi#ER2^-xYTh&i(P{GOsD!=bK2+oM|$kHj@njtK~=5G_Yb~^t^5>zI^RTR
zk)yDG623Vx<YMdmW<|X{%jelSi~uVEj3!$)n68Y0fccPYDKs(7pR%^>sy5;_Aqg7Z
z?Fi@R(?xH6MptS-9{Ej*rX5aSFz>gkv<a)^ydsxjpa9|Ru#mIom5|P~@$Zz)rzlRE
z?z>9(@66>o871Db``+~;_0+y|_2GSg8ZeE7*OF1aZnsBl+4M)Qk_JI<XecP27x+e-
z;wFQM6<CmGDbi(23|K`=zvD-~ImbT`u;F4Bh4S4toNi7VyJG*9!85fsuUao7Rhbw0
zb4_+zZjIGq7EfB%*zPNmx$quoahJO>%#f%lqV_~TNl1ESnHoty(kAsR8D0$FOuOZ#
zAZ%&4kL9U8%zMnzh$V&1`P~%v4bfd_W`Scpn3R*Gjt3Fxk#KA}$5s}vd7!?`h~w70
zJ**-^7{N$&UPhy=kWTq!+wscs!euJOoF4B+W5U<)dI7KH({uETiNd!5Kh&J4_#N)~
zTMzfe#3K?q)oQ1ihN$n`Lw`MYndfaoD?N+&{^Q0$^I3Hr=0d@@{emMN*q+D0rVvb<
zB8$dD;T)t)H+W|N(0hey+=0~a=!MTeg2G1vd+jD{`4dPk|JiESD_KoZq_9s>w7x*G
zA*kSB(Wcp<I{c{j8a45|@%gb0Tf(I0T*2ny)e{X9nGE~W)<d%cb$(I<*{S2}f1e(R
z5H(?(+?eR|6f!3e<{4-MS(2?c4oJ~Fjxu0{axPz^9#*#AmCCNJ=6V(s5!4>KynX+0
zj|fA0Jqct8_MrV%GZcJfy1-~F7)pdI#xEAbR=`VKM1c|j1UK*-`=L<jgmgKTUV|@P
zf9QWR+e9$H=G6}yYR;*Xo@Xn%%y3h8!>)~-$WMqrx`{e5B19%v>MEytIkgueq$F<N
z_O5Vo|8#h+JzAx0$MK-~=zGqqgGXjx179&__VTOqNf}20uV1$_s~n+$?sh8BY?!~-
zzKEMgHJD^TOcE@>06N579xzrEYKsvkR0m70eV4yJt(xkZ=)aQi;izV5ww2jA{|cgK
zWavNRVCaC3Hjhr-cDx^OB<AH_fIe&-zBIp9vTa{xUiLoPWUSupkM_TwMRpA9JTh(f
zzxCIvA3LS(YuNH{OlD(Yq!KTq^N*-!`&tsFMyz%VS~&Q&U}>-h7F^C|rK${6#}K*L
zi1uX<tL3ZD>8H~lC)k>3N7Ob}-4G~N&T$`3*1M|oaYZ9@NGI=L4)fu&GNRreMk0xx
zF*dy$A~p5fYp1aAo~=+X5;;@dPO~#y>zK&gM()hWK-vJ`<D#7O1c#4&s0HOT&{rEn
zUb(&L%3Y<-y>fvLhaVjL?8bd^NDS7MIx@9D{+SJo!Zh$^Anjfx2b_x*X9pRE5f#M&
zZB?O;Nj?4aEy)i)eSw38Ps$yu2ecWU$1g_P+Ae>dICCx_2jdR0o0UKrqi1EIy{S_M
z-R#Q{nYNi7d}G;_<9<*2S8wE?D?H|fLSBcSg;t8@2il+F9$4)!(E!%Yq`-ecE{(+r
zjW%Or(dCNNleT^_G*h@GfAP>mnpXK%5G_Scxa{;IKB=tC^~ASx__XC`^blz+{9}V8
zdmkK0!D2{@5H?sPv_f^K@>j8_M{YL|>>ySG6q^Ew$a6&+!_Eb$Si3)mrEtf_#%b74
zvMh>6Ym<{++OB&(f4$yRH0P@KX<(y<nsBT(<Hj12TC`XD-s~iX=`nNG3%9N15KrLp
zYU*W#%B%47je1AO<boa}yzEnq&1+Wb@Gng-a{Cs&&+ee7*1c$U%HO}^RiqI$_J#R^
z$Z{k29)wo^o;*2HFsJ*cJ6r)YjNyiJbz_r`levj_nlxaQ!vmm1Lw~1dmZB7ekjk6f
zUTg1KRUs-tEn|^3P{NO!%!O1^3KZ{7FDv@^r-f?Kt@n0m2EBz{`MSMJALnqHPqc4u
zJ=e)>$m&=Lx1;P$obcE|)jEVa<X$sWeLHk|XVMQ<=xbuI8doM(pz!np8ckeP?aBb8
zV~9~pqC4m>e50aXkR=Shz&ZA9+^#_iC?+Q37%K(H56g)vRb&@M9qV192D2@7XWS`z
zdF5!T<D@sI=474xgg3v-8J7(u`_j<$1_!}><f*GOC7Wwbb)WAu9K0CK4!+ww(lr{5
zBFM|#{+2CIk2^lj?gCk#{@#7XS=Pp9;o6;h32eut)Vp4b9CfZH>irnothFYosEPgu
zB|`?dM3o@OEkhCWSf$uqt$1P*t&|haON&baa;&7mVubVceH2>yu!dPX+HPjbR7du$
z4M#}X3rpR}g#hy=WBP`X{XU_DV`KXFg(uNA%-W%kx)%E*mc8;?J-;Bwx?*iQH=ueG
z0A~$~BI~6AR|^A^R#yJZG)}QunGT@HZG|7gB*!S0w>ztY;_d#NZQ5-7Bi8gdqw`H?
zN@Eu3DEmg|{nvXBn9Oreo3H=?24QJ#7!f!W0H96Sm@F{O7f7;tCys%Eh^6|Di6IJ5
zI5)8cmU%s606>bUQRe_?fy$TJdx{o=My2OT{#+lGlhwH0$byi*^IT~GwI|sOPKqx_
z%NY$CXU$#G=@_1M=P1qR8IM;ibFR&;nQ-&f84T;^ME#bQrOu;bweRh{LT?!m5#vWy
zuUeK*6}v<@Ea3Ccgbj}jC6HrCCQF|@oDKLlWC_=pKj~ffs=NzBxS+7(RgY!ApgjD`
z`8UD_<qLn6`#1`8#gA7dz>arxc^4tn#H34H&)_>!PQWcIr;2+AI$TW1WXsBFo#f2O
zj@DnLTimQLB3w{#3=sfTUz8?bGeifDaf=#B07MuU_(e-Hznfbrm7B;_XCn^4!H8BZ
z;1ubZ6qV|gm1uB*+gG*r_rc&NoH1BDfxh~<EfY_p<NLMm!^Y9&sE^+FhDZ9Pzws}<
z)3H!2pb#E~n#Yv>P;Xg6B{npgEcNb;2iTrGBN^X^rO`9xFY~YOXsYYcUz<-Ass(OT
z6$X!I82qyDAIlHH`(cy#mUsyA%y~cI)INoW#%<2#|JYsRou*{~nGd{II%$l&s9yDc
z)!I5atS!5sP&jp<A(J(HprNULT#Z2FJry}>Ml^isd=cK1`>xk_F7Nu!sWi*Fz6&TF
zC}pD(TzX7P7uvm@at}NNM~D7hkwk<DN!B#Edkp~ct8k^86@U>@Y@YW$3G2`1)Xi$w
zcpY&y)7HJn{{1C?_IN7AJD2L8;N6O{pLPhyZN20o@&Q^BW{eTjmq(E5^yMYFT8tx2
zbP;f9iM+0ShtS{8X|#!$YTFJWM-_BbtOfMZ)+M+4#fjKwq(_L`2#GcdivaHkcChY2
zpK`ZXJx&^REy}D8e=}r}kz#_b;RF<LvBr~^ihe(Z!c|nmDnC%XD^=2GJ;f_<4FsE(
z_m;{wdG7@EMEWY5C0hE<=9$EtzsE@|FH2>2TeR;!ABRz?ipL1<R=rs1c47~cql9<k
z*`sZ}e~_MX?@1gjR)L=h-`Q1hV?k^Q&whu=Bt2DO)tXVH$8h7G>$45h20=8M8}Mm6
z_zfD8B}PuIvW)&_mktjGe|k<3B=Zp~R<OfxasE7#VMeqGO?yr_mftM`;|g8@y9u05
z5*PdsVs^~pe7A8%PsXteN-G!?T#4O`UqGLtkWYzrM?rm*h@MuL!-!T{&Zbhga3ZsO
zCB{zErvpmY%_C_n9RL54UtW&&b+$pz#J<5~2ufFNMO_3NIttG75*Bd=V5ja`aTbsE
zzw+M|_`k9Ob_Qm)L4iL1u8zU=Fu%~Sf15YB>JiRzuKyyM7!9p|nfl+?V7~tW<0N0n

diff --git a/core/artwork/reader_album.go b/core/artwork/folders_album.go
similarity index 63%
rename from core/artwork/reader_album.go
rename to core/artwork/folders_album.go
index 58a47c8ae..88f0181a3 100644
--- a/core/artwork/reader_album.go
+++ b/core/artwork/folders_album.go
@@ -3,107 +3,19 @@ package artwork
 import (
 	"cmp"
 	"context"
-	"crypto/md5"
 	"errors"
-	"fmt"
-	"io"
 	"path"
 	"slices"
 	"strings"
 	"time"
 
 	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/conf"
-	"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"
 	"github.com/navidrome/navidrome/utils/natural"
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
-type albumArtworkReader struct {
-	cacheKey
-	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) {
-	al, err := artwork.ds.Album(ctx).Get(artID.ID)
-	if err != nil {
-		return nil, err
-	}
-	_, imgFiles, imagesUpdateAt, err := loadAlbumFoldersPaths(ctx, artwork.ds, *al)
-	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,
-		lib:       lib,
-	}
-	a.cacheKey.artID = artID
-	a.cacheKey.lastUpdate = utils.TimeNewest(al.UpdatedAt, al.ImportedAt)
-	if imagesUpdateAt != nil {
-		a.cacheKey.lastUpdate = utils.TimeNewest(a.cacheKey.lastUpdate, *imagesUpdateAt)
-	}
-	return a, nil
-}
-
-func (a *albumArtworkReader) Key() string {
-	hashInput := conf.Server.CoverArtPriority
-	if conf.Server.EnableExternalServices {
-		hashInput = conf.Server.Agents + hashInput
-	}
-	hash := md5.Sum([]byte(hashInput))
-	return fmt.Sprintf(
-		"%s.%x.%t",
-		a.cacheKey.Key(),
-		hash,
-		conf.Server.EnableExternalServices,
-	)
-}
-func (a *albumArtworkReader) LastUpdated() time.Time {
-	return a.lastUpdate
-}
-
-func (a *albumArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
-	var ff = a.fromCoverArtPriority(ctx, a.a.ffmpeg, conf.Server.CoverArtPriority)
-	return selectImageReader(ctx, a.artID, ff...)
-}
-
-func (a *albumArtworkReader) fromCoverArtPriority(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":
-			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.lib.FS, a.imgFiles, pattern))
-		}
-	}
-	return ff
-}
-
 func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, album model.Album) ([]string, []string, *time.Time, error) {
 	folders, err := loadFolders(ctx, ds, album.FolderIDs)
 	if err != nil {
@@ -169,7 +81,7 @@ func albumRootParent(ctx context.Context, ds model.DataStore, folders []model.Fo
 	}
 	parent, 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)
+		log.Warn(ctx, "Artwork: Parent folder not found for album cover art lookup", "parentID", commonParentID)
 		return nil, nil
 	}
 	if err != nil {
diff --git a/core/artwork/folders_album_test.go b/core/artwork/folders_album_test.go
new file mode 100644
index 000000000..a263dbaaf
--- /dev/null
+++ b/core/artwork/folders_album_test.go
@@ -0,0 +1,214 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// The e2e specs cover which image wins for a layout; these pin what a layout cannot reach: that
+// the album-root parent is only fetched when it could qualify, and what happens when that fails.
+var _ = Describe("loadAlbumFoldersPaths", func() {
+	var (
+		ctx   context.Context
+		ds    *tests.MockDataStore
+		repo  *fakeFolderRepo
+		album model.Album
+		now   time.Time
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		now = time.Now().Truncate(time.Second)
+		repo = &fakeFolderRepo{}
+		ds = &tests.MockDataStore{MockedFolder: repo}
+		album = model.Album{
+			ID:        "album1",
+			Name:      "Album",
+			FolderIDs: []string{"folder1", "folder2", "folder3"},
+		}
+	})
+
+	It("does not query the parent when it is already one of the album's folders", func() {
+		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},
+		}
+
+		_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(imgFiles).To(ConsistOf("Artist/Album/cover.jpg"))
+		Expect(repo.getCallCount).To(BeZero())
+	})
+
+	It("does not query the parent when the album's folders have different parents", func() {
+		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},
+		}
+
+		_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(imgFiles).To(ConsistOf("Artist1/Album/part1/cover.jpg"))
+		Expect(repo.getCallCount).To(BeZero())
+	})
+
+	It("does not query the parent for a single-folder album that has images of its own", 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(ConsistOf("Artist/Album/cover.jpg"))
+		Expect(repo.getCallCount).To(BeZero())
+	})
+
+	It("does not promote the library root, so its images never become album art", func() {
+		repo.result = []model.Folder{
+			{ID: "folder1", Path: ".", Name: "AlbumPart1", ParentID: "rootFolder",
+				ImagesUpdatedAt: now, ImageFiles: []string{"cover.jpg"}},
+			{ID: "folder2", Path: ".", Name: "AlbumPart2", ParentID: "rootFolder",
+				ImagesUpdatedAt: now},
+		}
+		repo.parentResult = &model.Folder{ID: "rootFolder", Name: ".", ImageFiles: []string{"unrelated.jpg"}}
+
+		_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(imgFiles).To(ConsistOf("AlbumPart1/cover.jpg"))
+		Expect(repo.getCallCount).To(Equal(1))
+	})
+
+	It("does not promote a parent that holds another album's audio", func() {
+		repo.result = []model.Folder{
+			{ID: "folder1", Path: "Artist/Album", Name: "CD1", ParentID: "albumFolder",
+				ImagesUpdatedAt: now, ImageFiles: []string{"cover.jpg"}},
+			{ID: "folder2", Path: "Artist/Album", Name: "CD2", ParentID: "albumFolder",
+				ImagesUpdatedAt: now},
+		}
+		repo.parentResult = &model.Folder{ID: "albumFolder", Path: "Artist", Name: "Album",
+			ParentID: "artistFolder", ImageFiles: []string{"artist.jpg"}}
+		repo.hasOtherAudio = true
+
+		_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(imgFiles).To(ConsistOf("Artist/Album/CD1/cover.jpg"))
+	})
+
+	It("promotes the album root parent into the returned paths", func() {
+		repo.result = []model.Folder{
+			{ID: "folder1", Path: "Artist/Album", Name: "CD1", ParentID: "albumFolder",
+				ImagesUpdatedAt: now},
+			{ID: "folder2", Path: "Artist/Album", Name: "CD2", ParentID: "albumFolder",
+				ImagesUpdatedAt: now},
+		}
+		repo.parentResult = &model.Folder{ID: "albumFolder", Path: "Artist", Name: "Album",
+			ParentID: "artistFolder", ImageFiles: []string{"cover.jpg"}}
+
+		paths, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(imgFiles).To(ConsistOf("Artist/Album/cover.jpg"))
+		Expect(paths).To(HaveLen(3))
+	})
+
+	It("propagates errors from the album-root check", func() {
+		repo.result = []model.Folder{
+			{ID: "folder1", Path: "Artist/Album", Name: "disc1", ParentID: "albumFolder",
+				ImagesUpdatedAt: now},
+		}
+		repo.parentResult = &model.Folder{ID: "albumFolder", Path: "Artist", Name: "Album",
+			ParentID: "artistFolder", ImageFiles: []string{"cover.jpg"}}
+		repo.otherAudioErr = errors.New("db connection failed")
+
+		_, _, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+		Expect(err).To(MatchError("db connection failed"))
+	})
+
+	It("propagates non-ErrNotFound errors from the 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},
+		}
+		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 when the parent folder has been deleted", func() {
+		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},
+		}
+
+		_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(imgFiles).To(ConsistOf("Artist/Album/CD1/cover.jpg"))
+		Expect(repo.getCallCount).To(Equal(1))
+	})
+})
+
+// folderImages is the sort that decides which of several same-named images wins, so it is pinned
+// directly rather than through a layout that can only show the winner.
+var _ = Describe("folderImages", func() {
+	It("prefers base filenames over numeric-suffixed ones", func() {
+		imgFiles, _ := folderImages([]model.Folder{
+			{Path: "Artist", Name: "Album", ImageFiles: []string{"cover.1.jpg", "cover.jpg", "cover.2.jpg"}},
+		})
+
+		Expect(imgFiles).To(HaveExactElements(
+			"Artist/Album/cover.jpg", "Artist/Album/cover.1.jpg", "Artist/Album/cover.2.jpg"))
+	})
+
+	It("prefers shallower paths when the base filenames tie", func() {
+		imgFiles, _ := folderImages([]model.Folder{
+			{Path: "Artist/Album", Name: "CD1", ImageFiles: []string{"cover.jpg"}},
+			{Path: "Artist", Name: "Album", ImageFiles: []string{"cover.jpg"}},
+		})
+
+		Expect(imgFiles).To(HaveExactElements("Artist/Album/cover.jpg", "Artist/Album/CD1/cover.jpg"))
+	})
+
+	It("sorts case-insensitively", func() {
+		imgFiles, _ := folderImages([]model.Folder{
+			{Path: "Artist", Name: "Album", ImageFiles: []string{"Cover.jpg", "back.JPG"}},
+		})
+
+		Expect(imgFiles).To(HaveExactElements("Artist/Album/back.JPG", "Artist/Album/Cover.jpg"))
+	})
+
+	It("reports the newest ImagesUpdatedAt across the folders", func() {
+		now := time.Now().Truncate(time.Second)
+		newest := now.Add(5 * time.Minute)
+
+		_, updatedAt := folderImages([]model.Folder{
+			{Path: "Artist", Name: "Album", ImagesUpdatedAt: now},
+			{Path: "Artist/Album", Name: "CD1", ImagesUpdatedAt: newest},
+		})
+
+		Expect(updatedAt).To(Equal(newest))
+	})
+})
diff --git a/core/artwork/folders_artist.go b/core/artwork/folders_artist.go
new file mode 100644
index 000000000..1ca1ce034
--- /dev/null
+++ b/core/artwork/folders_artist.go
@@ -0,0 +1,210 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils"
+	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/navidrome/navidrome/utils/str"
+)
+
+const (
+	maxArtistFolderTraversalDepth = 3
+)
+
+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 needs forward slashes; filepath.Rel returns backslashes on Windows.
+		rel = filepath.ToSlash(rel)
+		current := artistFolder
+		var unreadable error
+		for range maxArtistFolderTraversalDepth {
+			reader, hit, err := findImageInFolder(ctx, libFS, rel, current, pattern)
+			if err == nil {
+				return reader, hit, nil
+			}
+			if errors.Is(err, errSourceUnreadable) {
+				unreadable = err
+			}
+			if rel == "." {
+				break // reached library root
+			}
+			rel = path.Dir(rel)
+			current = filepath.Dir(current)
+		}
+		if unreadable != nil {
+			return nil, "", unreadable
+		}
+		return nil, "", fmt.Errorf(`no matches for '%s' in '%s' or its parent directories (within library)`, pattern, artistFolder)
+	}
+}
+
+// findImageInFolder returns the first image matching pattern; absFolder is only used for
+// the returned display path and log messages.
+func findImageInFolder(ctx context.Context, libFS fs.FS, relFolder, absFolder, pattern string) (io.ReadCloser, string, error) {
+	log.Trace(ctx, "Artwork: 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, "Artwork: Error matching artist image pattern", "pattern", pattern, "folder", absFolder, err)
+		return nil, "", err
+	}
+
+	imagePaths := slice.Filter(matches, model.IsImageFile)
+
+	// Prefer base filenames over numeric-suffixed ones (artist.jpg before artist.1.jpg)
+	slices.SortFunc(imagePaths, compareImageFiles)
+
+	var openErr error
+	for _, p := range imagePaths {
+		f, err := libFS.Open(p)
+		if err != nil {
+			log.Warn(ctx, "Artwork: Could not open cover art file", "file", p, err)
+			openErr = fmt.Errorf("%w: %s: %w", errSourceUnreadable, p, err)
+			continue
+		}
+		_, name := path.Split(p)
+		return f, filepath.Join(absFolder, name), nil
+	}
+	if openErr != nil {
+		return nil, "", openErr
+	}
+
+	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()
+}
+
+// loadArtistAlbumRoots returns one path per album — the deepest folder holding
+// all of that album's tracks — so an album split into disc subfolders can't
+// pull the artist folder's common prefix below the artist level.
+func loadArtistAlbumRoots(ctx context.Context, ds model.DataStore, albums model.Albums) ([]string, []string, *time.Time, error) {
+	var folderIDs []string
+	for _, album := range albums {
+		folderIDs = append(folderIDs, album.FolderIDs...)
+	}
+	folders, err := loadFolders(ctx, ds, folderIDs)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+
+	pathByID := slice.ToMap(folders, func(f model.Folder) (string, string) {
+		return f.ID, f.AbsolutePath()
+	})
+	var roots []string
+	for _, album := range albums {
+		var albumPaths []string
+		for _, fid := range album.FolderIDs {
+			if p, ok := pathByID[fid]; ok {
+				albumPaths = append(albumPaths, p)
+			}
+		}
+		if len(albumPaths) > 0 {
+			roots = append(roots, commonDir(albumPaths))
+		}
+	}
+
+	imgFiles, updatedAt := folderImages(folders)
+	return roots, imgFiles, &updatedAt, nil
+}
+
+// commonDir returns the deepest directory containing all paths. Trailing
+// separators keep the comparison on segment boundaries, so a shared name
+// fragment (".../Album" and ".../Album2") is never read as a shared directory.
+func commonDir(paths []string) string {
+	sep := string(filepath.Separator)
+	common := str.LongestCommonPrefix(slice.Map(paths, func(p string) string { return p + sep }))
+	if !strings.HasSuffix(common, sep) {
+		common, _ = filepath.Split(common)
+	}
+	return filepath.Clean(common)
+}
+
+func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albums, paths []string) (string, time.Time, error) {
+	if len(albums) == 0 {
+		return "", time.Time{}, nil
+	}
+	libID := albums[0].LibraryID // TODO: Support albums spanning multiple libraries
+
+	// paths holds one root per album: two or more distinct roots already meet at
+	// the artist folder, while a single root is an album folder needing a climb.
+	roots := slices.Compact(slices.Sorted(slices.Values(paths)))
+	folderPath := commonDir(roots)
+	if len(roots) < 2 {
+		folderPath = filepath.Dir(folderPath)
+	}
+
+	// TODO: Hacky, but the easiest way to get the folder ID ATM
+	libPath := core.AbsolutePath(ctx, ds, libID, "")
+	folderID := model.FolderID(model.Library{ID: libID, Path: libPath}, folderPath)
+
+	log.Trace(ctx, "Artwork: Calculating artist folder details", "folderPath", folderPath, "folderID", folderID,
+		"libPath", libPath, "libID", libID, "albumPaths", paths)
+
+	folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderID, "missing": false}})
+	if err != nil || len(folders) == 0 {
+		log.Warn(ctx, "Artwork: Could not find folder for artist", "folderPath", folderPath, "id", folderID,
+			"libPath", libPath, "libID", libID, err)
+		return "", time.Time{}, err
+	}
+	return folderPath, folders[0].ImagesUpdatedAt, nil
+}
+
+// findImageInArtistFolder matches an image by MBID or artist name (case-insensitive), "" if none.
+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 := utils.BaseName(name)
+			if strings.EqualFold(base, candidate) && model.IsImageFile(name) {
+				return filepath.Join(folder, name)
+			}
+		}
+	}
+	return ""
+}
diff --git a/core/artwork/folders_artist_paths_test.go b/core/artwork/folders_artist_paths_test.go
new file mode 100644
index 000000000..cc8af3e63
--- /dev/null
+++ b/core/artwork/folders_artist_paths_test.go
@@ -0,0 +1,117 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"time"
+
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// commonDir and loadArtistFolder decide how far above the albums the artist folder sits. A layout
+// can only show the image that won, so the arithmetic is pinned here.
+var _ = Describe("commonDir", func() {
+	It("returns the folder itself for a single path", func() {
+		Expect(commonDir([]string{filepath.FromSlash("/music/artist/album")})).
+			To(Equal(filepath.FromSlash("/music/artist/album")))
+	})
+
+	It("returns the deepest shared folder", func() {
+		Expect(commonDir([]string{
+			filepath.FromSlash("/music/artist/album/cd1"),
+			filepath.FromSlash("/music/artist/album/cd2"),
+		})).To(Equal(filepath.FromSlash("/music/artist/album")))
+	})
+
+	It("does not read a shared name fragment as a shared folder", func() {
+		Expect(commonDir([]string{
+			filepath.FromSlash("/music/artist/Album"),
+			filepath.FromSlash("/music/artist/Album2"),
+		})).To(Equal(filepath.FromSlash("/music/artist")))
+	})
+})
+
+var _ = Describe("loadArtistFolder", func() {
+	var (
+		ctx       context.Context
+		ds        *tests.MockDataStore
+		repo      *fakeFolderRepo
+		albums    model.Albums
+		updatedAt time.Time
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		DeferCleanup(stubCoreAbsolutePath())
+
+		updatedAt = time.Now().Truncate(time.Second).Add(5 * time.Minute)
+		repo = &fakeFolderRepo{result: []model.Folder{{ImagesUpdatedAt: updatedAt}}}
+		ds = &tests.MockDataStore{MockedFolder: repo}
+		albums = model.Albums{{LibraryID: 1, ID: "album1", Name: "Album 1"}}
+	})
+
+	It("returns empty when the artist has no albums", func() {
+		folder, upd, err := loadArtistFolder(ctx, ds, model.Albums{}, []string{"/dummy/path"})
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(folder).To(BeEmpty())
+		Expect(upd).To(BeZero())
+	})
+
+	It("climbs above the album folder when the artist has a single album root", func() {
+		folder, upd, err := loadArtistFolder(ctx, ds, albums,
+			[]string{filepath.FromSlash("/music/artist/album1")})
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
+		Expect(upd).To(Equal(updatedAt))
+	})
+
+	It("climbs above the shared folder when two albums live in the same one", func() {
+		folder, upd, err := loadArtistFolder(ctx, ds, albums, []string{
+			filepath.FromSlash("/music/artist/split"),
+			filepath.FromSlash("/music/artist/split"),
+		})
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
+		Expect(upd).To(Equal(updatedAt))
+	})
+
+	It("stops at the folder where distinct album roots already meet", func() {
+		folder, upd, err := loadArtistFolder(ctx, ds, albums, []string{
+			filepath.FromSlash("/music/artist/album1"),
+			filepath.FromSlash("/music/artist/album2"),
+		})
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
+		Expect(upd).To(Equal(updatedAt))
+	})
+
+	It("returns the error when the folder lookup fails", func() {
+		repo.err = errors.New("fake error")
+
+		folder, upd, err := loadArtistFolder(ctx, ds, albums, []string{
+			filepath.FromSlash("/music/artist/album1"),
+			filepath.FromSlash("/music/artist/album2"),
+		})
+
+		Expect(err).To(MatchError(ContainSubstring("fake error")))
+		Expect(folder).To(BeEmpty())
+		Expect(upd).To(BeZero())
+	})
+})
+
+func stubCoreAbsolutePath() func() {
+	original := core.AbsolutePath
+	core.AbsolutePath = func(context.Context, model.DataStore, int, string) string {
+		return filepath.FromSlash("/music")
+	}
+	return func() { core.AbsolutePath = original }
+}
diff --git a/core/artwork/folders_artist_test.go b/core/artwork/folders_artist_test.go
new file mode 100644
index 000000000..a35e40232
--- /dev/null
+++ b/core/artwork/folders_artist_test.go
@@ -0,0 +1,47 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"io/fs"
+	"testing/fstest"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// unreadableFS globs like its embedded MapFS but refuses to open anything. Injecting the error
+// keeps this independent of the filesystem: os.Chmod does not restrict read access on Windows.
+type unreadableFS struct{ fstest.MapFS }
+
+func (u unreadableFS) Open(string) (fs.File, error) { return nil, fs.ErrPermission }
+
+var _ = Describe("findImageInFolder", func() {
+	var ctx context.Context
+	var files fstest.MapFS
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		files = fstest.MapFS{"artist.jpg": &fstest.MapFile{Data: []byte("img")}}
+	})
+
+	It("returns the first matching image", func() {
+		r, hit, err := findImageInFolder(ctx, files, ".", "/lib", "artist.*")
+		Expect(err).ToNot(HaveOccurred())
+		defer r.Close()
+		Expect(hit).To(HaveSuffix("artist.jpg"))
+	})
+
+	// The glob matched, so the image exists; failing to open it says nothing about whether the
+	// artist has one, and must not let the resolver settle on absent.
+	It("reports a matched but unreadable image as unreadable, not as a miss", func() {
+		_, _, err := findImageInFolder(ctx, unreadableFS{files}, ".", "/lib", "artist.*")
+		Expect(err).To(MatchError(errSourceUnreadable))
+	})
+
+	It("reports a plain miss when nothing matches", func() {
+		_, _, err := findImageInFolder(ctx, files, ".", "/lib", "nothing.*")
+		Expect(err).To(HaveOccurred())
+		Expect(errors.Is(err, errSourceUnreadable)).To(BeFalse(), "no match is definitive, not transient")
+	})
+})
diff --git a/core/artwork/gate.go b/core/artwork/gate.go
new file mode 100644
index 000000000..a64c11a20
--- /dev/null
+++ b/core/artwork/gate.go
@@ -0,0 +1,120 @@
+package artwork
+
+import (
+	"errors"
+	"io"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"golang.org/x/time/rate"
+)
+
+const (
+	breakerThreshold  = 5
+	breakerProbeAfter = time.Minute
+)
+
+var errBreakerOpen = errors.New("artwork: external circuit breaker open")
+
+// gateFunc gates one named external fetch (rate limit + circuit breaker per name).
+type gateFunc = func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error)
+
+func passthroughGate(_ string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+	return f()
+}
+
+// isTransientExternal reports whether an external failure is worth retrying; a not-found
+// (from either package) is a definitive answer, not a fault.
+func isTransientExternal(err error) bool {
+	return err != nil && !errors.Is(err, agents.ErrNotFound) && !errors.Is(err, model.ErrNotFound)
+}
+
+// extGate is one agent's rate limiter and circuit breaker, so a failing provider backs off
+// in isolation from the others.
+type extGate struct {
+	limiter *rate.Limiter
+	breaker *breaker
+}
+
+// gate runs a named external step through that agent's rate limiter and circuit breaker.
+func (w *Worker) gate(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+	g := w.gateFor(name)
+	if !g.breaker.allow() {
+		log.Debug(w.runCtx, "Artwork: Skipping agent, circuit breaker open", "agent", name)
+		return nil, "", errBreakerOpen
+	}
+	// Timed separately so a throttled agent isn't mistaken for a slow provider.
+	waitStart := time.Now()
+	if err := g.limiter.Wait(w.runCtx); err != nil {
+		return nil, "", err
+	}
+	callStart := time.Now()
+	r, path, err := f()
+	g.breaker.record(name, err)
+	log.Trace(w.runCtx, "Artwork: External agent call", "agent", name, "hit", r != nil,
+		"limiterWait", callStart.Sub(waitStart), "elapsed", time.Since(callStart), err)
+	return r, path, err
+}
+
+// gateFor lazily creates the per-name gate on first use.
+func (w *Worker) gateFor(name string) *extGate {
+	w.gatesMu.Lock()
+	defer w.gatesMu.Unlock()
+	if g, ok := w.gates[name]; ok {
+		return g
+	}
+	rps := conf.Server.DevArtworkExternalMaxRPS
+	limit := rate.Inf
+	if rps > 0 {
+		limit = rate.Limit(rps)
+	}
+	g := &extGate{limiter: rate.NewLimiter(limit, max(1, rps)), breaker: newBreaker()}
+	w.gates[name] = g
+	return g
+}
+
+// breaker opens after breakerThreshold consecutive errors and admits a single probe once
+// breakerProbeAfter has elapsed; a success re-closes it.
+type breaker struct {
+	mu       sync.Mutex
+	failures int
+	openedAt time.Time
+}
+
+func newBreaker() *breaker { return &breaker{} }
+
+func (b *breaker) allow() bool {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if b.failures < breakerThreshold {
+		return true
+	}
+	if time.Since(b.openedAt) >= breakerProbeAfter {
+		b.openedAt = time.Now() // start a fresh probe window so only one caller passes
+		return true
+	}
+	return false
+}
+
+func (b *breaker) record(name string, err error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	// A not-found is a definitive answer, not a fault; keep in sync with isTransientExternal.
+	if err == nil || errors.Is(err, model.ErrNotFound) || errors.Is(err, agents.ErrNotFound) {
+		if b.failures >= breakerThreshold {
+			log.Info("Artwork: Circuit breaker closed for agent", "agent", name)
+		}
+		b.failures = 0
+		return
+	}
+	b.failures++
+	if b.failures == breakerThreshold {
+		b.openedAt = time.Now()
+		log.Warn("Artwork: Circuit breaker opened for agent", "agent", name,
+			"consecutiveFailures", b.failures, "probeAfter", breakerProbeAfter, err)
+	}
+}
diff --git a/core/artwork/hash_encoder_bench_test.go b/core/artwork/hash_encoder_bench_test.go
new file mode 100644
index 000000000..2bc4b90ba
--- /dev/null
+++ b/core/artwork/hash_encoder_bench_test.go
@@ -0,0 +1,51 @@
+package artwork
+
+import (
+	"fmt"
+	"image"
+	"testing"
+
+	"github.com/navidrome/navidrome/core/artwork/blurhash"
+	"github.com/navidrome/navidrome/core/artwork/thumbhash"
+)
+
+// hashEncoders are the two placeholder hashes decodeArtwork computes from one shared thumbnail.
+var hashEncoders = []struct {
+	name   string
+	encode func(image.Image) error
+}{
+	{"blurhash", func(img image.Image) error { _, err := blurhash.Encode(img); return err }},
+	{"thumbhash", func(img image.Image) error { _, err := thumbhash.Encode(img); return err }},
+}
+
+func benchEncoder(b *testing.B, encode func(image.Image) error, img image.Image) {
+	b.Helper()
+	b.ReportAllocs()
+	for b.Loop() {
+		if err := encode(img); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+// BenchmarkHashEncodersAtInputSize is the bar: both encoders are handed the identical image
+// makeThumbnail produces, so neither is measured with a conversion the other avoids.
+func BenchmarkHashEncodersAtInputSize(b *testing.B) {
+	img := gradientNRGBA(thumbnailSize)
+	for _, e := range hashEncoders {
+		b.Run(e.name, func(b *testing.B) { benchEncoder(b, e.encode, img) })
+	}
+}
+
+// BenchmarkHashEncoders sweeps past the pipeline's input size, where each package's own defensive
+// downscale starts to dominate. thumbnailSize itself is covered by the benchmark above.
+func BenchmarkHashEncoders(b *testing.B) {
+	for _, size := range []int{300, 600, 900, 1200, 1500} {
+		img := gradientNRGBA(size)
+		for _, e := range hashEncoders {
+			b.Run(fmt.Sprintf("%s/%dx%d", e.name, size, size), func(b *testing.B) {
+				benchEncoder(b, e.encode, img)
+			})
+		}
+	}
+}
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
new file mode 100644
index 000000000..ce72a6c8e
--- /dev/null
+++ b/core/artwork/housekeeping.go
@@ -0,0 +1,129 @@
+package artwork
+
+import (
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"fmt"
+	"slices"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
+)
+
+const staleAbsentAge = 24 * time.Hour
+
+// recheckKinds omits media files: they resolve embedded-only, at scan or on view.
+var recheckKinds = []model.Kind{
+	model.KindArtistArtwork, model.KindAlbumArtwork, model.KindPlaylistArtwork, model.KindRadioArtwork,
+}
+
+// hasRecheckPath reports whether a periodic job will revisit this kind, making an absent settle recoverable.
+func hasRecheckPath(prefix string) bool {
+	kind, ok := model.ParseKind(prefix)
+	return ok && slices.Contains(recheckKinds, kind)
+}
+
+// artworkEpoch invalidates all resolution state when bumped; bump it whenever resolution semantics change.
+const artworkEpoch = 1
+
+// fingerprint covers the inputs that affect resolution outcomes; a change invalidates stored state.
+func fingerprint() string {
+	raw := fmt.Sprintf("%s|%s|%s|%s|%t|%t|%d",
+		conf.Server.CoverArtPriority, conf.Server.ArtistArtPriority, conf.Server.ArtistImageFolder,
+		conf.Server.Agents, conf.Server.EnableExternalServices, conf.Server.EnableM3UExternalAlbumArt, artworkEpoch)
+	sum := md5.Sum([]byte(raw)) //nolint:gosec // fingerprint, not security-sensitive
+	return hex.EncodeToString(sum[:])
+}
+
+// backfill enqueues artwork resolution for every entity when the config fingerprint changed.
+func backfill(ctx context.Context, ds model.DataStore) (bool, error) {
+	start := time.Now()
+	ctx = auth.WithAdminUser(ctx, ds)
+	current := fingerprint()
+	props := ds.Property(ctx)
+	stored, err := props.DefaultGet(consts.ArtConfFingerprintPropertyKey, "")
+	if err != nil {
+		return false, err
+	}
+	if stored == current {
+		return false, nil
+	}
+
+	// Artists first: few entities, most external-dependent, so they get a queue headstart.
+	kinds := []struct {
+		kind  model.Kind
+		fetch func() ([]string, error)
+	}{
+		{model.KindArtistArtwork, func() ([]string, error) { return ds.Artist(ctx).GetAllIDs() }},
+		{model.KindAlbumArtwork, func() ([]string, error) { return ds.Album(ctx).GetAllIDs() }},
+		{model.KindPlaylistArtwork, func() ([]string, error) { return ds.Playlist(ctx).GetAllIDs() }},
+		{model.KindRadioArtwork, func() ([]string, error) { return ds.Radio(ctx).GetAllIDs() }},
+	}
+	for _, k := range kinds {
+		ids, err := k.fetch()
+		if err != nil {
+			return false, err
+		}
+		if err := enqueueBackfillKind(ctx, ds, k.kind, ids); err != nil {
+			return false, err
+		}
+	}
+
+	if err := props.Put(consts.ArtConfFingerprintPropertyKey, current); err != nil {
+		return false, err
+	}
+	log.Info(ctx, "Artwork: Config fingerprint changed, backfill enqueued", "elapsed", time.Since(start))
+	return true, nil
+}
+
+func enqueueBackfillKind(ctx context.Context, ds model.DataStore, kind model.Kind, ids []string) error {
+	if len(ids) == 0 {
+		return nil
+	}
+	items := slice.Map(ids, func(id string) model.ArtworkQueueItem {
+		return model.ArtworkQueueItem{
+			ItemKind: kind.Prefix(), ItemID: id, ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBackfill,
+		}
+	})
+	return ds.ArtworkQueue(ctx).Enqueue(items...)
+}
+
+func enqueueStaleAbsentAll(ctx context.Context, ds model.DataStore) error {
+	cutoff := time.Now().Add(-staleAbsentAge)
+	queue := ds.ArtworkQueue(ctx)
+	for _, kind := range recheckKinds {
+		if _, err := queue.EnqueueStaleAbsent(kind, cutoff); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// enqueueMissingAll is the safety net for entities a scan never enqueued (added between scans, or scanner off).
+func enqueueMissingAll(ctx context.Context, ds model.DataStore) error {
+	queue := ds.ArtworkQueue(ctx)
+	for _, kind := range recheckKinds {
+		if _, err := queue.EnqueueAllMissing(kind, model.ArtworkPriorityRecheck); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// Refresh drops an item's resolved artwork state and re-queues it at Bump priority.
+func Refresh(ctx context.Context, ds model.DataStore, kind model.Kind, id string) error {
+	if err := ds.Artwork(ctx).DeleteForItems(kind, []string{id}); err != nil {
+		return fmt.Errorf("clearing artwork state: %w", err)
+	}
+	item := model.ArtworkQueueItem{ItemKind: kind.Prefix(), ItemID: id, ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBump}
+	if err := ds.ArtworkQueue(ctx).Enqueue(item); err != nil {
+		return fmt.Errorf("enqueuing artwork refresh: %w", err)
+	}
+	return nil
+}
diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.go
new file mode 100644
index 000000000..3b75c5186
--- /dev/null
+++ b/core/artwork/housekeeping_test.go
@@ -0,0 +1,261 @@
+package artwork
+
+import (
+	"context"
+	"slices"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// visibilityPlaylistDS models playlist_repository's userFilter: a private playlist is only
+// visible when the ctx carries an admin, so headless work must wrap ctx with one first.
+type visibilityPlaylistDS struct {
+	*tests.MockDataStore
+	private model.Playlist
+	tracks  model.PlaylistTrackRepository
+}
+
+func (v *visibilityPlaylistDS) Playlist(ctx context.Context) model.PlaylistRepository {
+	repo := tests.CreateMockPlaylistRepo()
+	repo.TracksRepo = v.tracks
+	if u, ok := request.UserFrom(ctx); ok && u.IsAdmin {
+		repo.SetData(model.Playlists{v.private})
+	}
+	return repo
+}
+
+func adminUserRepo() *tests.MockedUserRepo {
+	repo := tests.CreateMockUserRepo()
+	Expect(repo.Put(&model.User{ID: "admin", UserName: "admin", IsAdmin: true})).To(Succeed())
+	return repo
+}
+
+// orderTrackingQueueRepo records the item kind of each Enqueue call, so tests can
+// assert phase ordering (artists-first) that same-priority timestamps can't guarantee.
+type orderTrackingQueueRepo struct {
+	*tests.MockArtworkQueueRepo
+	callKinds []string
+}
+
+func (o *orderTrackingQueueRepo) Enqueue(items ...model.ArtworkQueueItem) error {
+	if len(items) > 0 {
+		o.callKinds = append(o.callKinds, items[0].ItemKind)
+	}
+	return o.MockArtworkQueueRepo.Enqueue(items...)
+}
+
+var _ = Describe("Housekeeping", func() {
+	var (
+		ctx       context.Context
+		ds        *tests.MockDataStore
+		queueRepo *orderTrackingQueueRepo
+		propRepo  *tests.MockedPropertyRepo
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		ctx = context.Background()
+		conf.Server.CoverArtPriority = "embedded, folder"
+		conf.Server.ArtistArtPriority = "artist.jpg"
+		conf.Server.Agents = "spotify"
+		conf.Server.EnableExternalServices = true
+
+		queueRepo = &orderTrackingQueueRepo{MockArtworkQueueRepo: tests.CreateMockArtworkQueueRepo()}
+		propRepo = &tests.MockedPropertyRepo{}
+		ds = &tests.MockDataStore{MockedArtworkQueue: queueRepo, MockedProperty: propRepo}
+	})
+
+	seedEntities := func() {
+		artistRepo := tests.CreateMockArtistRepo()
+		artistRepo.SetData(model.Artists{{ID: "ar1"}, {ID: "ar2"}})
+		ds.MockedArtist = artistRepo
+
+		albumRepo := tests.CreateMockAlbumRepo()
+		albumRepo.SetData(model.Albums{{ID: "al1"}})
+		ds.MockedAlbum = albumRepo
+
+		playlistRepo := tests.CreateMockPlaylistRepo()
+		playlistRepo.SetData(model.Playlists{{ID: "pl1"}})
+		ds.MockedPlaylist = playlistRepo
+
+		radioRepo := tests.CreateMockedRadioRepo()
+		radioRepo.All = model.Radios{{ID: "ra1"}}
+		ds.MockedRadio = radioRepo
+	}
+
+	Describe("Fingerprint", func() {
+		It("changes when a fingerprint-affecting config value changes", func() {
+			f1 := fingerprint()
+			conf.Server.CoverArtPriority = "folder, embedded"
+			f2 := fingerprint()
+			Expect(f1).NotTo(Equal(f2))
+		})
+
+		It("changes when ArtistImageFolder changes", func() {
+			conf.Server.ArtistImageFolder = "/before"
+			f1 := fingerprint()
+			conf.Server.ArtistImageFolder = "/after"
+			Expect(fingerprint()).NotTo(Equal(f1))
+		})
+
+		It("changes when EnableM3UExternalAlbumArt is toggled", func() {
+			conf.Server.EnableM3UExternalAlbumArt = false
+			f1 := fingerprint()
+			conf.Server.EnableM3UExternalAlbumArt = true
+			Expect(fingerprint()).NotTo(Equal(f1))
+		})
+
+		It("does not change when the server version changes", func() {
+			original := consts.Version
+			DeferCleanup(func() { consts.Version = original })
+			f1 := fingerprint()
+			consts.Version = original + "-next"
+			Expect(fingerprint()).To(Equal(f1),
+				"the version must not invalidate artwork state: it would re-resolve every entity on every build")
+		})
+	})
+
+	Describe("Backfill", func() {
+		It("enqueues nothing and returns false when the stored fingerprint matches", func() {
+			seedEntities()
+			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, fingerprint())).To(Succeed())
+
+			did, err := backfill(ctx, ds)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(did).To(BeFalse())
+
+			count, err := queueRepo.Count()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(count).To(BeZero())
+		})
+
+		It("runs the backfill when no fingerprint was ever stored", func() {
+			seedEntities()
+
+			did, err := backfill(ctx, ds)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(did).To(BeTrue())
+
+			count, err := queueRepo.Count()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(count).To(Equal(int64(5))) // 2 artists + 1 album + 1 playlist + 1 radio
+
+			stored, err := propRepo.Get(consts.ArtConfFingerprintPropertyKey)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(stored).To(Equal(fingerprint()))
+		})
+
+		It("enqueues a private playlist by resolving it under an admin context", func() {
+			ds.MockedUser = adminUserRepo()
+			vds := &visibilityPlaylistDS{
+				MockDataStore: ds,
+				private:       model.Playlist{ID: "plPrivate", OwnerID: "admin"},
+				tracks:        &tests.MockPlaylistTrackRepo{},
+			}
+
+			did, err := backfill(ctx, vds)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(did).To(BeTrue())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "pl", "plPrivate")).ToNot(BeNil())
+		})
+
+		It("enqueues artists before albums/playlists/radios, all at Backfill priority", func() {
+			seedEntities()
+			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, "stale-fingerprint")).To(Succeed())
+
+			did, err := backfill(ctx, ds)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(did).To(BeTrue())
+
+			Expect(queueRepo.callKinds).ToNot(BeEmpty())
+			firstOther := slices.IndexFunc(queueRepo.callKinds, func(k string) bool { return k != "ar" })
+			Expect(firstOther).ToNot(Equal(0), "artists must be the first Enqueue call")
+			if firstOther >= 0 {
+				Expect(queueRepo.callKinds[firstOther:]).ToNot(ContainElement("ar"),
+					"no artist Enqueue may follow another kind")
+			}
+
+			for _, it := range queueRepo.Data {
+				Expect(it.Priority).To(Equal(model.ArtworkPriorityBackfill))
+				Expect(it.ItemKind).To(BeElementOf("ar", "al", "pl", "ra"))
+			}
+		})
+	})
+
+	Describe("EnqueueStaleAbsentAll", func() {
+		var artRepo *tests.MockArtworkRepo
+
+		BeforeEach(func() {
+			artRepo = tests.CreateMockArtworkRepo()
+			ds.MockedArtwork = artRepo
+			queueRepo.ItemArtworkSource = artRepo
+		})
+
+		It("enqueues only absent entries older than the recheck window, across all kinds", func() {
+			old := time.Now().Add(-48 * time.Hour)
+			recent := time.Now().Add(-time.Hour)
+
+			artRepo.ItemData["ar-stale"] = model.ItemArtwork{ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
+			artRepo.ItemData["al-stale"] = model.ItemArtwork{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
+			artRepo.ItemData["pl-stale"] = model.ItemArtwork{ItemKind: "pl", ItemID: "pl1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
+			artRepo.ItemData["ra-stale"] = model.ItemArtwork{ItemKind: "ra", ItemID: "ra1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
+			artRepo.ItemData["ar-recent"] = model.ItemArtwork{ItemKind: "ar", ItemID: "ar2", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: recent}
+			artRepo.ItemData["al-resolved"] = model.ItemArtwork{ItemKind: "al", ItemID: "al2", ImageType: model.ImageTypePrimary, Hash: "somehash", AttemptedAt: old}
+
+			err := enqueueStaleAbsentAll(ctx, ds)
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(queueRepo.Data).To(HaveLen(4))
+			for _, it := range queueRepo.Data {
+				Expect(it.Priority).To(Equal(model.ArtworkPriorityRecheck))
+			}
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar1")).ToNot(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al1")).ToNot(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "pl", "pl1")).ToNot(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ra", "ra1")).ToNot(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar2")).To(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al2")).To(BeNil())
+		})
+	})
+
+	Describe("EnqueueMissingAll", func() {
+		var artRepo *tests.MockArtworkRepo
+
+		BeforeEach(func() {
+			artRepo = tests.CreateMockArtworkRepo()
+			ds.MockedArtwork = artRepo
+			queueRepo.ItemArtworkSource = artRepo
+			queueRepo.ExistingIDs = map[string]map[string]bool{
+				"al": {"al1": true, "al2": true},
+				"ar": {"ar1": true},
+				"pl": {"pl1": true},
+				"ra": {"ra1": true},
+			}
+		})
+
+		It("enqueues only entities that have no item_artwork row, across all kinds", func() {
+			artRepo.ItemData["al-resolved"] = model.ItemArtwork{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "somehash", AttemptedAt: time.Now()}
+			artRepo.ItemData["ar-absent"] = model.ItemArtwork{ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()}
+
+			err := enqueueMissingAll(ctx, ds)
+			Expect(err).ToNot(HaveOccurred())
+
+			for _, it := range queueRepo.Data {
+				Expect(it.Priority).To(Equal(model.ArtworkPriorityRecheck))
+			}
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al2")).ToNot(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "pl", "pl1")).ToNot(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ra", "ra1")).ToNot(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al1")).To(BeNil())
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar1")).To(BeNil())
+		})
+	})
+})
diff --git a/core/artwork/image_cache.go b/core/artwork/image_cache.go
index ac0f63794..39938a755 100644
--- a/core/artwork/image_cache.go
+++ b/core/artwork/image_cache.go
@@ -1,30 +1,22 @@
 package artwork
 
 import (
+	"bytes"
 	"context"
-	"fmt"
 	"io"
-	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/utils/cache"
 	"github.com/navidrome/navidrome/utils/singleton"
 )
 
-type cacheKey struct {
-	artID      model.ArtworkID
-	lastUpdate time.Time
-}
-
-func (k *cacheKey) Key() string {
-	return fmt.Sprintf(
-		"%s-%s.%d",
-		k.artID.Kind,
-		k.artID.ID,
-		k.lastUpdate.UnixMilli(),
-	)
+// artworkReader is the cache.Item the image cache loader dispatches on: Reader
+// produces the (possibly resized) bytes to store under Key.
+type artworkReader interface {
+	cache.Item
+	Reader(ctx context.Context) (io.ReadCloser, error)
 }
 
 type imageCache struct {
@@ -36,9 +28,45 @@ func GetImageCache() cache.FileCache {
 		return &imageCache{
 			FileCache: cache.NewFileCache("Image", conf.Server.ImageCacheSize, consts.ImageCacheDir, consts.DefaultImageCacheMaxItems,
 				func(ctx context.Context, arg cache.Item) (io.Reader, error) {
-					r, _, err := arg.(artworkReader).Reader(ctx)
-					return r, err
+					return arg.(artworkReader).Reader(ctx)
 				}),
 		}
 	})
 }
+
+// resizedItem is an artworkReader that resizes bytes opened by open() and caches the
+// result under a hash-derived key.
+type resizedItem struct {
+	hash   string
+	size   int
+	square bool
+	ffmpeg ffmpeg.FFmpeg
+	open   func() (io.ReadCloser, error)
+}
+
+// Key is the ETag namespaced for the cache, so the validator a client holds and the entry it
+// validates can never drift apart.
+func (r *resizedItem) Key() string {
+	return "h-" + representationTag(r.hash, r.size, r.square)
+}
+
+func (r *resizedItem) Reader(ctx context.Context) (io.ReadCloser, error) {
+	orig, err := r.open()
+	if err != nil {
+		return nil, err
+	}
+	defer orig.Close()
+	data, err := readCapped(orig)
+	if err != nil {
+		return nil, err
+	}
+	resized, _, err := resizeImageData(ctx, r.ffmpeg, data, r.size, r.square)
+	if err != nil || resized == nil {
+		// Resize failed or image already within bounds: serve the original bytes.
+		return io.NopCloser(bytes.NewReader(data)), nil
+	}
+	if rc, ok := resized.(io.ReadCloser); ok {
+		return rc, nil
+	}
+	return io.NopCloser(resized), nil
+}
diff --git a/core/artwork/image_store.go b/core/artwork/image_store.go
new file mode 100644
index 000000000..5dbe727e4
--- /dev/null
+++ b/core/artwork/image_store.go
@@ -0,0 +1,155 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/log"
+	"github.com/zeebo/xxh3"
+)
+
+// ImageStore is the content-addressed store for artwork images with no library file backing them.
+type ImageStore struct {
+	root string
+}
+
+func NewImageStore(rootDir string) *ImageStore {
+	return &ImageStore{root: rootDir}
+}
+
+func GetImageStore() *ImageStore {
+	return NewImageStore(filepath.Join(conf.Server.DataFolder.String(), consts.ArtworkFolder, consts.HashedArtworkFolder))
+}
+
+// extForMime must stay stable across OSes: extensions are baked into stored paths and re-derived on Open.
+func extForMime(m string) string {
+	switch m {
+	case "image/jpeg":
+		return ".jpg"
+	case "image/png":
+		return ".png"
+	case "image/gif":
+		return ".gif"
+	case "image/webp":
+		return ".webp"
+	}
+	return ".img"
+}
+
+func hashImage(r io.Reader) (string, error) {
+	d := xxh3.New()
+	if _, err := io.Copy(d, r); err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("%016x", d.Sum64()), nil
+}
+
+// validHash guards path sharding: a malformed hash would slice-panic or inject path separators.
+func validHash(hash string) bool {
+	if len(hash) != 16 {
+		return false
+	}
+	for _, c := range []byte(hash) {
+		if (c < '0' || c > '9') && (c < 'a' || c > 'f') {
+			return false
+		}
+	}
+	return true
+}
+
+func (s *ImageStore) path(hash, mimeType string) string {
+	return filepath.Join(s.root, hash[0:2], hash[2:4], hash+extForMime(mimeType))
+}
+
+func (s *ImageStore) Write(hash, mimeType string, r io.Reader) error {
+	if !validHash(hash) {
+		return fmt.Errorf("imagestore: invalid hash %q", hash)
+	}
+	dst := s.path(hash, mimeType)
+	if _, err := os.Stat(dst); err == nil {
+		// A touched mtime marks the file live so a concurrent prune spares it.
+		now := time.Now()
+		if err := os.Chtimes(dst, now, now); err == nil {
+			return nil
+		}
+		// touch failed (likely pruned concurrently) — fall through and rewrite it
+	}
+	if err := os.MkdirAll(filepath.Dir(dst), 0755); err != nil {
+		return err
+	}
+	tmp, err := os.CreateTemp(filepath.Dir(dst), "."+hash+".tmp*")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(tmp.Name())
+	if _, err := io.Copy(tmp, r); err != nil {
+		tmp.Close()
+		return err
+	}
+	if err := tmp.Close(); err != nil {
+		return err
+	}
+	return os.Rename(tmp.Name(), dst)
+}
+
+func (s *ImageStore) Open(hash, mimeType string) (io.ReadCloser, error) {
+	if !validHash(hash) {
+		return nil, fmt.Errorf("imagestore: invalid hash %q", hash)
+	}
+	return os.Open(s.path(hash, mimeType))
+}
+
+// Sweep removes store files not accepted by keep. Files modified after cutoff are always
+// kept: their acquisition row may not be committed yet.
+func (s *ImageStore) Sweep(ctx context.Context, cutoff time.Time, keep func(hash, ext string) bool) (int, error) {
+	removed, failed := 0, 0
+	var lastErr error
+	err := filepath.WalkDir(s.root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return err
+		}
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		if info.ModTime().After(cutoff) {
+			return nil
+		}
+		name := d.Name()
+		remove := strings.HasPrefix(name, ".") // abandoned temp file past the grace window
+		if !remove {
+			ext := filepath.Ext(name)
+			remove = !keep(strings.TrimSuffix(name, ext), ext)
+		}
+		if remove {
+			// #nosec G122 -- path comes from WalkDir over our own store root, no attacker-controlled symlinks
+			if err := os.Remove(path); err != nil {
+				// One unremovable file must not strand the rest of the store until the next prune.
+				failed, lastErr = failed+1, err
+				return nil //nolint:nilerr // counted and reported in aggregate below
+			}
+			removed++
+		}
+		return nil
+	})
+	// Aggregated: a store that has gone read-only would otherwise warn once per file, every prune.
+	if failed > 0 {
+		log.Warn(ctx, "Artwork: Could not remove store files", "count", failed, "swept", removed, lastErr)
+	}
+	if errors.Is(err, fs.ErrNotExist) {
+		return removed, nil
+	}
+	return removed, err
+}
diff --git a/core/artwork/image_store_test.go b/core/artwork/image_store_test.go
new file mode 100644
index 000000000..f7b2467ca
--- /dev/null
+++ b/core/artwork/image_store_test.go
@@ -0,0 +1,228 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("ImageStore", func() {
+	var store *ImageStore
+	var root string
+	var ctx context.Context
+
+	BeforeEach(func() {
+		root = GinkgoT().TempDir()
+		store = NewImageStore(root)
+		ctx = context.Background()
+	})
+
+	It("hashes deterministically", func() {
+		h1, err := hashImage(bytes.NewReader([]byte("some image bytes")))
+		Expect(err).ToNot(HaveOccurred())
+		h2, _ := hashImage(bytes.NewReader([]byte("some image bytes")))
+		Expect(h1).To(Equal(h2))
+		Expect(h1).To(HaveLen(16))
+		h3, _ := hashImage(bytes.NewReader([]byte("other bytes")))
+		Expect(h3).ToNot(Equal(h1))
+	})
+
+	It("writes sharded and reads back", func() {
+		data := []byte("jpeg-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+
+		Expect(filepath.Join(root, h[0:2], h[2:4], h+".jpg")).To(BeAnExistingFile())
+
+		rc, err := store.Open(h, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		defer rc.Close()
+		got, _ := io.ReadAll(rc)
+		Expect(got).To(Equal(data))
+	})
+
+	It("is idempotent on duplicate writes and preserves the original content", func() {
+		data := []byte("dup")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/png", bytes.NewReader(data))).To(Succeed())
+		// A duplicate write only touches mtime; passing different bytes under the same
+		// hash proves the second reader is never consumed to overwrite the file.
+		Expect(store.Write(h, "image/png", bytes.NewReader([]byte("not-dup")))).To(Succeed())
+
+		rc, err := store.Open(h, "image/png")
+		Expect(err).ToNot(HaveOccurred())
+		defer rc.Close()
+		got, err := io.ReadAll(rc)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(Equal(data))
+	})
+
+	It("refreshes the mtime on a duplicate write", func() {
+		data := []byte("touch-me")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/png", bytes.NewReader(data))).To(Succeed())
+		old := time.Now().Add(-2 * time.Hour)
+		Expect(os.Chtimes(store.path(h, "image/png"), old, old)).To(Succeed())
+
+		Expect(store.Write(h, "image/png", bytes.NewReader(data))).To(Succeed())
+
+		info, err := os.Stat(store.path(h, "image/png"))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(info.ModTime()).To(BeTemporally(">", time.Now().Add(-time.Minute)))
+	})
+
+	It("rewrites the bytes when the existing file vanished before the liveness touch", func() {
+		data := []byte("vanishing")
+		h, _ := hashImage(bytes.NewReader(data))
+		for range 10 {
+			Expect(store.Write(h, "image/png", bytes.NewReader(data))).To(Succeed())
+			Expect(os.Remove(store.path(h, "image/png"))).To(Succeed())
+			Expect(store.Write(h, "image/png", bytes.NewReader(data))).To(Succeed())
+
+			rc, err := store.Open(h, "image/png")
+			Expect(err).ToNot(HaveOccurred())
+			got, _ := io.ReadAll(rc)
+			rc.Close()
+			Expect(got).To(Equal(data))
+		}
+	})
+
+	It("returns fs.ErrNotExist for missing images", func() {
+		_, err := store.Open("beefbeefbeefbeef", "image/jpeg")
+		Expect(os.IsNotExist(err)).To(BeTrue())
+	})
+
+	It("rejects invalid hashes instead of panicking", func() {
+		for _, h := range []string{"", "ab", "BEEFBEEFBEEFBEEF", "../../../../etcpw", "beefbeefbeefbee/"} {
+			Expect(store.Write(h, "image/jpeg", bytes.NewReader([]byte("x")))).To(MatchError(ContainSubstring("invalid hash")))
+			_, err := store.Open(h, "image/jpeg")
+			Expect(err).To(MatchError(ContainSubstring("invalid hash")))
+		}
+	})
+
+	It("sweeps unknown files, keeps known ones", func() {
+		d1 := []byte("keep-me")
+		h1, _ := hashImage(bytes.NewReader(d1))
+		Expect(store.Write(h1, "image/jpeg", bytes.NewReader(d1))).To(Succeed())
+		d2 := []byte("orphan")
+		h2, _ := hashImage(bytes.NewReader(d2))
+		Expect(store.Write(h2, "image/jpeg", bytes.NewReader(d2))).To(Succeed())
+
+		old := time.Now().Add(-2 * time.Hour)
+		Expect(os.Chtimes(store.path(h2, "image/jpeg"), old, old)).To(Succeed())
+
+		removed, err := store.Sweep(ctx, time.Now().Add(-time.Hour), func(h, _ string) bool { return h == h1 })
+		Expect(err).ToNot(HaveOccurred())
+		Expect(removed).To(Equal(1))
+		_, err = store.Open(h2, "image/jpeg")
+		Expect(os.IsNotExist(err)).To(BeTrue())
+		rc, err := store.Open(h1, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("sweeps a stale mime variant of a known hash, keeps the current one", func() {
+		data := []byte("same-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/png", bytes.NewReader(data))).To(Succeed())
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+		old := time.Now().Add(-2 * time.Hour)
+		Expect(os.Chtimes(store.path(h, "image/png"), old, old)).To(Succeed())
+		Expect(os.Chtimes(store.path(h, "image/jpeg"), old, old)).To(Succeed())
+
+		// The recorded mime is image/jpeg, so the .png variant is obsolete.
+		removed, err := store.Sweep(ctx, time.Now().Add(-time.Hour), func(hash, ext string) bool {
+			return hash == h && ext == ".jpg"
+		})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(removed).To(Equal(1))
+		_, err = store.Open(h, "image/png")
+		Expect(os.IsNotExist(err)).To(BeTrue())
+		rc, err := store.Open(h, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("keeps young unknown files inside the grace window", func() {
+		d := []byte("fresh-orphan")
+		h, _ := hashImage(bytes.NewReader(d))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(d))).To(Succeed())
+
+		removed, err := store.Sweep(ctx, time.Now().Add(-time.Hour), func(string, string) bool { return false })
+		Expect(err).ToNot(HaveOccurred())
+		Expect(removed).To(Equal(0))
+		rc, err := store.Open(h, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("removes abandoned temp files past the grace window, keeps fresh ones", func() {
+		oldTmp := filepath.Join(root, ".old.tmp")
+		Expect(os.WriteFile(oldTmp, []byte("x"), 0600)).To(Succeed())
+		old := time.Now().Add(-2 * time.Hour)
+		Expect(os.Chtimes(oldTmp, old, old)).To(Succeed())
+
+		freshTmp := filepath.Join(root, ".fresh.tmp")
+		Expect(os.WriteFile(freshTmp, []byte("y"), 0600)).To(Succeed())
+
+		removed, err := store.Sweep(ctx, time.Now().Add(-time.Hour), func(string, string) bool { return true })
+		Expect(err).ToNot(HaveOccurred())
+		Expect(removed).To(Equal(1))
+		Expect(oldTmp).ToNot(BeAnExistingFile())
+		Expect(freshTmp).To(BeAnExistingFile())
+	})
+
+	It("keeps sweeping past a file it cannot remove", func() {
+		tests.SkipOnWindows("uses Unix file permission bits")
+		if os.Geteuid() == 0 {
+			Skip("read-only dir cannot block root (e.g. tests in a container)")
+		}
+		old := time.Now().Add(-2 * time.Hour)
+		// "blocked" sorts before "ok", so the walk hits the unremovable file first.
+		blockedDir := filepath.Join(root, "blocked")
+		Expect(os.MkdirAll(blockedDir, 0755)).To(Succeed())
+		blocked := filepath.Join(blockedDir, "a.jpg")
+		Expect(os.WriteFile(blocked, []byte("x"), 0600)).To(Succeed())
+		Expect(os.Chtimes(blocked, old, old)).To(Succeed())
+
+		okDir := filepath.Join(root, "ok")
+		Expect(os.MkdirAll(okDir, 0755)).To(Succeed())
+		reachable := filepath.Join(okDir, "b.jpg")
+		Expect(os.WriteFile(reachable, []byte("y"), 0600)).To(Succeed())
+		Expect(os.Chtimes(reachable, old, old)).To(Succeed())
+
+		Expect(os.Chmod(blockedDir, 0500)).To(Succeed())
+		DeferCleanup(func() { _ = os.Chmod(blockedDir, 0755) })
+
+		removed, err := store.Sweep(ctx, time.Now().Add(-time.Hour), func(string, string) bool { return false })
+		Expect(err).ToNot(HaveOccurred())
+		Expect(removed).To(Equal(1))
+		Expect(blocked).To(BeAnExistingFile())
+		Expect(reachable).ToNot(BeAnExistingFile())
+	})
+
+	// Prune holds the worker's write lock for the whole sweep, and shutdown waits on the
+	// worker, so an uncancellable walk over a large store stalls it until SIGKILL.
+	It("abandons the walk when the context is cancelled", func() {
+		old := time.Now().Add(-2 * time.Hour)
+		for _, name := range []string{"a", "b", "c", "d"} {
+			p := filepath.Join(root, name+".jpg")
+			Expect(os.WriteFile(p, []byte("x"), 0600)).To(Succeed())
+			Expect(os.Chtimes(p, old, old)).To(Succeed())
+		}
+		cancelCtx, cancel := context.WithCancel(ctx)
+		cancel()
+
+		_, err := store.Sweep(cancelCtx, time.Now().Add(-time.Hour), func(string, string) bool { return false })
+		Expect(err).To(MatchError(context.Canceled))
+		matches, _ := filepath.Glob(filepath.Join(root, "*.jpg"))
+		Expect(matches).To(HaveLen(4), "a cancelled sweep must not keep deleting")
+	})
+})
diff --git a/core/artwork/library_fs.go b/core/artwork/library_fs.go
index ff557294e..6e6099325 100644
--- a/core/artwork/library_fs.go
+++ b/core/artwork/library_fs.go
@@ -2,7 +2,9 @@ package artwork
 
 import (
 	"context"
+	"net/url"
 	"path/filepath"
+	"strings"
 
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/model"
@@ -40,5 +42,23 @@ func loadLibraryView(ctx context.Context, ds model.DataStore, libID int) (librar
 	if err != nil {
 		return libraryView{}, err
 	}
-	return libraryView{FS: fs, absRoot: lib.Path}, nil
+	return libraryView{FS: fs, absRoot: localOSRoot(lib.Path)}, nil
+}
+
+// localOSRoot maps a library path to its on-disk root so Abs() yields paths os.Open/os.Stat accept:
+// a file:// URL becomes its parsed OS path (bare paths already are; non-local schemes stay unchanged).
+func localOSRoot(libPath string) string {
+	if !strings.Contains(libPath, "://") {
+		return libPath
+	}
+	u, err := url.Parse(libPath)
+	if err != nil || u.Scheme != storage.LocalSchemaID {
+		return libPath
+	}
+	// Windows drive URLs (file://C:/Music) put the volume in Host; rejoin it, matching
+	// core/storage/local's newLocalStorage so os.Open/os.Stat get a valid path.
+	if filepath.VolumeName(u.Host) != "" {
+		return filepath.Join(u.Host, u.Path)
+	}
+	return u.Path
 }
diff --git a/core/artwork/library_fs_test.go b/core/artwork/library_fs_test.go
index acf08fda3..22498e7a1 100644
--- a/core/artwork/library_fs_test.go
+++ b/core/artwork/library_fs_test.go
@@ -32,6 +32,13 @@ var _ = Describe("loadLibraryView", Ordered, func() {
 		Expect(lib.absRoot).To(Equal("fake:///music"))
 	})
 
+	It("normalizes a library path to an OS root that Abs can join for os.Open/os.Stat", func() {
+		// file:// URLs become their parsed OS path; bare paths and non-local schemes are unchanged.
+		Expect(localOSRoot("file:///music/library")).To(Equal("/music/library"))
+		Expect(localOSRoot("/music/library")).To(Equal("/music/library"))
+		Expect(localOSRoot("fake:///music")).To(Equal("fake:///music"))
+	})
+
 	It("returns an error when the library does not exist", func() {
 		_, err := loadLibraryView(ctx, ds, 999)
 		Expect(err).To(HaveOccurred())
diff --git a/core/artwork/playlist_cover.go b/core/artwork/playlist_cover.go
new file mode 100644
index 000000000..e74b64808
--- /dev/null
+++ b/core/artwork/playlist_cover.go
@@ -0,0 +1,116 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"image"
+	"image/draw"
+	"image/png"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils"
+	xdraw "golang.org/x/image/draw"
+)
+
+const tileSize = 600
+
+// findPlaylistSidecarPath finds an image beside plsPath with the same base name (case-insensitive).
+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, "Artwork: Could not read directory for playlist sidecar", "dir", dir, err)
+		return ""
+	}
+	for _, entry := range entries {
+		name := entry.Name()
+		nameBase := utils.BaseName(name)
+		if !entry.IsDir() && strings.EqualFold(nameBase, base) && model.IsImageFile(name) {
+			return filepath.Join(dir, name)
+		}
+	}
+	return ""
+}
+
+func rect(pos int) image.Rectangle {
+	r := image.Rectangle{}
+	switch pos {
+	case 1:
+		r.Min.X = tileSize / 2
+	case 2:
+		r.Min.Y = tileSize / 2
+	case 3:
+		r.Min.X = tileSize / 2
+		r.Min.Y = tileSize / 2
+	}
+	r.Max.X = r.Min.X + tileSize/2
+	r.Max.Y = r.Min.Y + tileSize/2
+	return r
+}
+
+// fillCenter center-crops src and scales it to fill dstW x dstH exactly.
+func fillCenter(src image.Image, dstW, dstH int) image.Image {
+	srcBounds := src.Bounds()
+	srcW := srcBounds.Dx()
+	srcH := srcBounds.Dy()
+
+	srcAspect := float64(srcW) / float64(srcH)
+	dstAspect := float64(dstW) / float64(dstH)
+
+	var cropRect image.Rectangle
+	if srcAspect > dstAspect {
+		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 {
+		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
+}
+
+// decodeTile runs before the processor's size guards apply, so it enforces the caps itself.
+func decodeTile(r io.ReadCloser) (image.Image, error) {
+	data, err := readCapped(r)
+	if err != nil {
+		return nil, err
+	}
+	img, _, err := decodeCapped(data)
+	if err != nil {
+		return nil, err
+	}
+	return fillCenter(img, tileSize/2, tileSize/2), nil
+}
+
+func assembleTiles(tiles []image.Image) (io.ReadCloser, error) {
+	buf := new(bytes.Buffer)
+	var err error
+	if len(tiles) == 4 {
+		rgba := image.NewRGBA(image.Rectangle{Max: image.Point{X: tileSize - 1, Y: tileSize - 1}})
+		draw.Draw(rgba, rect(0), tiles[0], image.Point{}, draw.Src)
+		draw.Draw(rgba, rect(1), tiles[1], image.Point{}, draw.Src)
+		draw.Draw(rgba, rect(2), tiles[2], image.Point{}, draw.Src)
+		draw.Draw(rgba, rect(3), tiles[3], image.Point{}, draw.Src)
+		err = png.Encode(buf, rgba)
+	} else {
+		err = png.Encode(buf, tiles[0])
+	}
+	if err != nil {
+		return nil, err
+	}
+	return io.NopCloser(buf), nil
+}
diff --git a/core/artwork/processor.go b/core/artwork/processor.go
new file mode 100644
index 000000000..c3cf15b71
--- /dev/null
+++ b/core/artwork/processor.go
@@ -0,0 +1,311 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"image"
+	"image/draw"
+	_ "image/gif" // the only artwork format with no other importer in this package
+	"io"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/core/artwork/blurhash"
+	"github.com/navidrome/navidrome/core/artwork/dominant"
+	"github.com/navidrome/navidrome/core/artwork/thumbhash"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	xdraw "golang.org/x/image/draw"
+)
+
+// outcome tells the worker whether to delete the queue row (found/absent) or reschedule it.
+type outcome int
+
+const (
+	outcomeFound outcome = iota
+	// outcomeFoundStale: state was written and is served, but a higher-priority external
+	// source failed, so the row must retry to give it another chance.
+	outcomeFoundStale
+	outcomeAbsent
+	outcomeFailed
+)
+
+func (o outcome) String() string {
+	switch o {
+	case outcomeFound:
+		return "found"
+	case outcomeFoundStale:
+		return "foundStale"
+	case outcomeAbsent:
+		return "absent"
+	default:
+		return "failed"
+	}
+}
+
+// thumbnailSize is the max dimension fed to both hash encoders; thumbhash rejects anything larger.
+const thumbnailSize = 100
+
+// maxImageBytes caps a resolved image read: a user-editable ExternalImageURL could point at
+// an arbitrarily large endpoint.
+const maxImageBytes = 20 << 20
+
+// maxImagePixels guards against decompression bombs: a tiny file can declare a canvas that
+// image.Decode would expand into gigabytes.
+const maxImagePixels = 64 << 20
+
+// acquired is what a successful acquire persisted, handed back so the caller can warm the resize
+// cache without re-reading the rows and the file it just wrote.
+type acquired struct {
+	ia   *model.ItemArtwork
+	mime string
+	data []byte
+}
+
+// processor turns one queue item into stored artwork; settling the queue row is the Worker's job.
+type processor struct {
+	ds        model.DataStore
+	store     *ImageStore
+	resolver  *resolver
+	pruneLock sync.Locker
+}
+
+// acquire resolves one queue item end to end: find an image, hash/decode/
+// blurhash it, place its bytes, and persist the resulting state.
+func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (out outcome, got *acquired) {
+	repo := p.ds.Artwork(ctx)
+	start := time.Now()
+	defer func() {
+		log.Debug(ctx, "Artwork: Acquisition finished", "kind", item.ItemKind, "id", item.ItemID,
+			"outcome", out, "elapsed", time.Since(start))
+	}()
+
+	res, err := p.resolver.resolve(ctx, item)
+	if err != nil {
+		log.Warn(ctx, "Artwork: Could not resolve item", "kind", item.ItemKind, "id", item.ItemID, err)
+		return outcomeFailed, nil
+	}
+	if res.reader == nil {
+		if res.extError || res.localError {
+			// A fault is not a definitive "no image": never settle absent, keep serving old state.
+			log.Debug(ctx, "Artwork: No image, but a source faulted; keeping previous state",
+				"kind", item.ItemKind, "id", item.ItemID, "extError", res.extError, "localError", res.localError)
+			return outcomeFailed, nil
+		}
+		return writeAbsent(ctx, repo, item), nil
+	}
+	defer res.reader.Close()
+
+	readStart := time.Now()
+	data, err := readCapped(res.reader)
+	if err != nil {
+		log.Warn(ctx, "Artwork: Failed to read resolved image", "kind", item.ItemKind, "id", item.ItemID, "source", res.source, err)
+		return outcomeFailed, nil
+	}
+	log.Debug(ctx, "Artwork: Read resolved image", "kind", item.ItemKind, "id", item.ItemID,
+		"source", res.source, "bytes", len(data), "elapsed", time.Since(readStart))
+
+	hashStart := time.Now()
+	hash, err := hashImage(bytes.NewReader(data))
+	if err != nil {
+		log.Warn(ctx, "Artwork: Failed to hash image", "kind", item.ItemKind, "id", item.ItemID, err)
+		return outcomeFailed, nil
+	}
+	log.Trace(ctx, "Artwork: Hashed image", "kind", item.ItemKind, "id", item.ItemID,
+		"hash", hash, "bytes", len(data), "elapsed", time.Since(hashStart))
+
+	art, err := repo.GetImage(hash)
+	switch {
+	case err == nil:
+		log.Debug(ctx, "Artwork: Reusing a known image, skipping decode", "kind", item.ItemKind,
+			"id", item.ItemID, "hash", hash)
+	case errors.Is(err, model.ErrNotFound):
+		decodeStart := time.Now()
+		art, err = decodeArtwork(ctx, hash, data)
+		if err != nil {
+			log.Warn(ctx, "Artwork: Failed to decode resolved image", "kind", item.ItemKind, "id", item.ItemID, err)
+			return outcomeFailed, nil
+		}
+		log.Debug(ctx, "Artwork: Decoded new image", "kind", item.ItemKind, "id", item.ItemID, "hash", hash,
+			"width", art.Width, "height", art.Height, "mime", art.Mime, "elapsed", time.Since(decodeStart))
+	default:
+		log.Warn(ctx, "Artwork: Failed to look up image hash", "kind", item.ItemKind, "id", item.ItemID, err)
+		return outcomeFailed, nil
+	}
+	art.SizeBytes = int64(len(data))
+
+	ia, err := p.persist(repo, item, art, res, data)
+	if err != nil {
+		log.Warn(ctx, "Artwork: Failed to persist resolved image", "kind", item.ItemKind, "id", item.ItemID, err)
+		return outcomeFailed, nil
+	}
+	got = &acquired{ia: ia, mime: art.Mime, data: data}
+	if res.extError {
+		log.Debug(ctx, "Artwork: Serving a lower-priority source after an external failure",
+			"kind", item.ItemKind, "id", item.ItemID, "source", res.source)
+		return outcomeFoundStale, got
+	}
+	return outcomeFound, got
+}
+
+// persist places the bytes and commits the rows referencing them, excluding Prune for that
+// window only so a slow resolution can never hold it off.
+func (p *processor) persist(repo model.ArtworkRepository, item model.ArtworkQueueItem,
+	art *model.Artwork, res resolution, data []byte,
+) (*model.ItemArtwork, error) {
+	if p.pruneLock != nil {
+		p.pruneLock.Lock()
+		defer p.pruneLock.Unlock()
+	}
+	sourcePath, refMtime, err := placeBytes(p.store, art, res, data)
+	if err != nil {
+		return nil, fmt.Errorf("writing image store: %w", err)
+	}
+	if err := repo.PutImage(art); err != nil {
+		return nil, fmt.Errorf("persisting artwork image: %w", err)
+	}
+	ia := &model.ItemArtwork{
+		ItemKind:    item.ItemKind,
+		ItemID:      item.ItemID,
+		ImageType:   item.ImageType,
+		Hash:        art.Hash,
+		Source:      res.source,
+		SourcePath:  sourcePath,
+		RefMtime:    refMtime,
+		AttemptedAt: time.Now(),
+	}
+	// PutItemArtwork stamps UpdatedAt on ia, so the returned struct matches the persisted row.
+	if err := repo.PutItemArtwork(ia); err != nil {
+		return nil, fmt.Errorf("persisting item artwork state: %w", err)
+	}
+	return ia, nil
+}
+
+// writeAbsent records a known-absent state: every source answered definitively "no".
+func writeAbsent(ctx context.Context, repo model.ArtworkRepository, item model.ArtworkQueueItem) outcome {
+	err := repo.PutItemArtwork(&model.ItemArtwork{
+		ItemKind:    item.ItemKind,
+		ItemID:      item.ItemID,
+		ImageType:   item.ImageType,
+		AttemptedAt: time.Now(),
+	})
+	if err != nil {
+		log.Warn(ctx, "Artwork: Failed to persist absent state", "kind", item.ItemKind, "id", item.ItemID, err)
+		return outcomeFailed
+	}
+	log.Debug(ctx, "Artwork: Settled absent, every source answered definitively",
+		"kind", item.ItemKind, "id", item.ItemID)
+	return outcomeAbsent
+}
+
+func readCapped(r io.Reader) ([]byte, error) {
+	data, err := io.ReadAll(io.LimitReader(r, maxImageBytes+1))
+	if err != nil {
+		return nil, err
+	}
+	if len(data) > maxImageBytes {
+		return nil, fmt.Errorf("image exceeds size cap %d", maxImageBytes)
+	}
+	return data, nil
+}
+
+// decodeCapped rejects declared dimensions over maxImagePixels before the full-decode allocation.
+func decodeCapped(data []byte) (image.Image, string, error) {
+	cfg, format, err := image.DecodeConfig(bytes.NewReader(data))
+	if err != nil {
+		return nil, "", fmt.Errorf("decode image config: %w", err)
+	}
+	// Compared by division so the cap cannot be defeated by an int64 overflow.
+	if cfg.Width <= 0 || cfg.Height <= 0 || cfg.Width > maxImagePixels/cfg.Height {
+		return nil, "", fmt.Errorf("image dimensions %dx%d exceed pixel cap %d", cfg.Width, cfg.Height, maxImagePixels)
+	}
+	img, _, err := image.Decode(bytes.NewReader(data))
+	if err != nil {
+		return nil, "", fmt.Errorf("decode image: %w", err)
+	}
+	return img, format, nil
+}
+
+// decodeArtwork builds a new Artwork row from raw bytes: dimensions, mime and the two
+// placeholder hashes, both encoded from one shared downscaled thumbnail.
+func decodeArtwork(ctx context.Context, hash string, data []byte) (*model.Artwork, error) {
+	img, format, err := decodeCapped(data)
+	if err != nil {
+		return nil, err
+	}
+
+	thumb := makeThumbnail(img, thumbnailSize)
+	bh, err := blurhash.Encode(thumb)
+	if err != nil {
+		log.Warn(ctx, "Artwork: Blurhash encoding failed", "hash", hash, err)
+		bh = ""
+	}
+
+	var th string
+	if raw, err := thumbhash.Encode(thumb); err != nil {
+		log.Warn(ctx, "Artwork: Thumbhash encoding failed", "hash", hash, err)
+	} else {
+		th = base64.StdEncoding.EncodeToString(raw)
+	}
+
+	return &model.Artwork{
+		Hash:          hash,
+		Mime:          mimeForFormat(format),
+		Width:         img.Bounds().Dx(),
+		Height:        img.Bounds().Dy(),
+		BlurHash:      bh,
+		ThumbHash:     th,
+		DominantColor: dominant.Color(thumb),
+	}, nil
+}
+
+// makeThumbnail downscales img to fit within maxSize on its longest side; it never upscales.
+func makeThumbnail(img image.Image, maxSize int) image.Image {
+	b := img.Bounds()
+	w, h := b.Dx(), b.Dy()
+	if w <= maxSize && h <= maxSize {
+		return toFastScaleType(img)
+	}
+	scale := float64(maxSize) / float64(max(w, h))
+	// NRGBA, not RGBA: thumbhash requires straight alpha, and blurhash reads this type without
+	// converting, so neither encoder allocates a second copy of the thumbnail.
+	dst := image.NewNRGBA(image.Rect(0, 0, max(1, int(float64(w)*scale)), max(1, int(float64(h)*scale))))
+	xdraw.CatmullRom.Scale(dst, dst.Bounds(), toFastScaleType(img), b, draw.Src, nil)
+	return dst
+}
+
+// isFileBacked reports whether the bytes already live in a library/upload file, so the
+// content-addressed store must not duplicate them.
+func isFileBacked(source string) bool {
+	return source == "folder" || source == "upload"
+}
+
+// placeBytes reports the item's backing-file provenance and writes the bytes into the store
+// for the sources that have none.
+func placeBytes(store *ImageStore, art *model.Artwork, res resolution, data []byte) (sourcePath string, refMtime int64, err error) {
+	if isFileBacked(res.source) {
+		return res.sourcePath, res.refMtime, nil
+	}
+	if res.source == "embedded" {
+		sourcePath, refMtime = res.sourcePath, res.refMtime
+	}
+	return sourcePath, refMtime, store.Write(art.Hash, art.Mime, bytes.NewReader(data))
+}
+
+// mimeForFormat maps an image.Decode format name to its MIME type; extForMime is the inverse.
+func mimeForFormat(format string) string {
+	switch format {
+	case "jpeg":
+		return "image/jpeg"
+	case "png":
+		return "image/png"
+	case "gif":
+		return "image/gif"
+	case "webp":
+		return "image/webp"
+	}
+	return "application/octet-stream"
+}
diff --git a/core/artwork/processor_test.go b/core/artwork/processor_test.go
new file mode 100644
index 000000000..d326dde09
--- /dev/null
+++ b/core/artwork/processor_test.go
@@ -0,0 +1,495 @@
+package artwork
+
+import (
+	"context"
+	"encoding/binary"
+	"errors"
+	"hash/crc32"
+	"image"
+	"image/color"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// DecodeConfig reads only the header, so the pixel data can be omitted entirely.
+func pngHeaderWithDims(w, h uint32) []byte {
+	ihdr := make([]byte, 13)
+	binary.BigEndian.PutUint32(ihdr[0:], w)
+	binary.BigEndian.PutUint32(ihdr[4:], h)
+	ihdr[8] = 8 // bit depth
+	ihdr[9] = 2 // color type: truecolor
+	chunk := append([]byte("IHDR"), ihdr...)
+	out := []byte{0x89, 'P', 'N', 'G', 0x0d, 0x0a, 0x1a, 0x0a}
+	out = binary.BigEndian.AppendUint32(out, uint32(len(ihdr)))
+	out = append(out, chunk...)
+	return binary.BigEndian.AppendUint32(out, crc32.ChecksumIEEE(chunk))
+}
+
+var _ = Describe("processor.acquire", func() {
+	var (
+		ctx        context.Context
+		ds         *tests.MockDataStore
+		folderRepo *fakeFolderRepo
+		libRepo    *tests.MockLibraryRepo
+		ffm        *tests.MockFFmpeg
+		ag         *agents.Agents
+		store      *ImageStore
+		artRepo    *tests.MockArtworkRepo
+		repoRoot   string
+		proc       *processor
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		ctx = context.Background()
+		var err error
+		repoRoot, err = os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+
+		folderRepo = &fakeFolderRepo{}
+		libRepo = &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		ffm = tests.NewMockFFmpeg("")
+		ag = agents.GetAgents(&tests.MockDataStore{}, nil)
+		artRepo = tests.CreateMockArtworkRepo()
+		ds = &tests.MockDataStore{
+			MockedFolder:  folderRepo,
+			MockedLibrary: libRepo,
+			MockedArtwork: artRepo,
+		}
+		ds.MockedAlbum = tests.CreateMockAlbumRepo()
+		store = NewImageStore(GinkgoT().TempDir())
+		proc = &processor{ds: ds, store: store, resolver: newResolver(ds, ag, ffm, nil)}
+
+		conf.Server.CoverArtPriority = "cover.jpg, embedded"
+	})
+
+	It("found-folder: persists state from a folder image, writes no store file, keeps sourcePath/refMtime", func() {
+		folderRepo.result = []model.Folder{{
+			Path:       "tests/fixtures/artist/an-album",
+			ImageFiles: []string{"cover.jpg"},
+		}}
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}},
+		})
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"})
+		Expect(out).To(Equal(outcomeFound))
+
+		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Hash).ToNot(BeEmpty())
+		Expect(ia.Source).To(Equal("folder"))
+		Expect(filepath.ToSlash(ia.SourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/cover.jpg"))
+		Expect(ia.RefMtime).To(BeNumerically(">", 0))
+
+		art, err := artRepo.GetImage(ia.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		// Every placeholder is derived from the one shared thumbnail, so all three land together.
+		Expect(art.BlurHash).ToNot(BeEmpty())
+		Expect(art.ThumbHash).ToNot(BeEmpty())
+		Expect(art.DominantColor).To(MatchRegexp(`^#[0-9a-f]{6}$`))
+		_, err = store.Open(ia.Hash, art.Mime)
+		Expect(os.IsNotExist(err)).To(BeTrue(), "folder-backed art must not be duplicated into the store")
+	})
+
+	Describe("prune lock scope", func() {
+		var lock *countingLocker
+
+		BeforeEach(func() {
+			lock = &countingLocker{}
+			proc.pruneLock = lock
+		})
+
+		It("holds it once across the write window", func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "alL1", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+
+			out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alL1"})
+			Expect(out).To(Equal(outcomeFound))
+			Expect(lock.locks).To(BeNumerically(">", 0), "the write window must exclude prune")
+			Expect(lock.held()).To(BeFalse(), "the window must close before acquire returns")
+		})
+
+		// Resolution can reach the network, so holding the lock across it would let one slow
+		// provider block prune, and every drain queued behind prune's writer.
+		It("never takes it while only resolving", func() {
+			folderRepo.result = nil
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "alL2", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+
+			out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alL2"})
+			Expect(out).To(Equal(outcomeAbsent))
+			Expect(lock.locks).To(BeZero())
+		})
+	})
+
+	It("found-embedded: writes a store file and computes a non-empty blurhash from a real fixture", func() {
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "al2", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},
+		})
+		folderRepo.result = nil
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"})
+		Expect(out).To(Equal(outcomeFound))
+
+		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al2", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("embedded"))
+		Expect(filepath.ToSlash(ia.SourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/test.mp3"))
+
+		art, err := artRepo.GetImage(ia.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(art.BlurHash).ToNot(BeEmpty())
+
+		rc, err := store.Open(ia.Hash, art.Mime)
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("absent: no local source and no external error persists a known-absent state", func() {
+		folderRepo.result = nil
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "al3", Name: "Album"},
+		})
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"})
+		Expect(out).To(Equal(outcomeAbsent))
+
+		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Hash).To(BeEmpty())
+		Expect(ia.Source).To(BeEmpty())
+		Expect(ia.AttemptedAt).To(BeTemporally("~", time.Now(), time.Second))
+	})
+
+	It("failed-on-unreadable-local: a listed cover that will not open never records absent", func() {
+		conf.Server.CoverArtPriority = "cover.jpg"
+		// A folder listing that names a cover the FS will not hand over: a stale mount.
+		libRoot := GinkgoT().TempDir()
+		Expect(os.MkdirAll(filepath.Join(libRoot, "an-album"), 0o755)).To(Succeed())
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(libRoot)}})
+		folderRepo.result = []model.Folder{{Path: "an-album", ImageFiles: []string{"cover.jpg"}}}
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "al-io", Name: "Album", FolderIDs: []string{"f1"}},
+		})
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al-io"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al-io", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound), "an I/O fault must not be recorded as absent")
+	})
+
+	// An upload outranks every source, so an unreadable one must not let a lower one take over.
+	It("failed-on-unreadable-upload: an upload that will not open never records absent", func() {
+		if runtime.GOOS == "windows" {
+			// The file would still open, so the spec would pass on the decode error instead.
+			Skip("chmod does not restrict read access on Windows")
+		}
+		radioRepo := tests.CreateMockedRadioRepo()
+		radioRepo.Data = map[string]*model.Radio{}
+		ds.MockedRadio = radioRepo
+		dir := GinkgoT().TempDir()
+		conf.Server.DataFolder = conf.NewDir(dir)
+		upload := model.UploadedImagePath(consts.EntityRadio, "ra-io.jpg")
+		Expect(os.MkdirAll(filepath.Dir(upload), 0o755)).To(Succeed())
+		Expect(os.WriteFile(upload, []byte("x"), 0o600)).To(Succeed())
+		Expect(os.Chmod(upload, 0o000)).To(Succeed()) // present, but unreadable
+		DeferCleanup(func() { _ = os.Chmod(upload, 0o600) })
+		radioRepo.Data["ra-io"] = &model.Radio{ID: "ra-io", Name: "Station", UploadedImage: "ra-io.jpg"}
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra-io"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		_, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra-io", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound), "an unreadable upload must not be recorded as absent")
+	})
+
+	It("failed-on-extError: leaves the item's state untouched", func() {
+		conf.Server.CoverArtPriority = "external"
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "al4", Name: "Album"},
+		})
+		imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al4", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+
+	It("found-stale: a fallback hit after a transient external failure persists state and returns outcomeFoundStale", func() {
+		conf.Server.CoverArtPriority = "external, cover.jpg"
+		folderRepo.result = []model.Folder{{
+			Path:       "tests/fixtures/artist/an-album",
+			ImageFiles: []string{"cover.jpg"},
+		}}
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "alstale", Name: "Album", FolderIDs: []string{"f1"}},
+		})
+		imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alstale"})
+		Expect(out).To(Equal(outcomeFoundStale))
+
+		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alstale", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Hash).ToNot(BeEmpty())
+		Expect(ia.Source).To(Equal("folder"))
+	})
+
+	It("found-external: persists source as external:<agentName> and stores the fetched bytes", func() {
+		conf.Server.CoverArtPriority = "external"
+		imgBytes, err := os.ReadFile(filepath.Join(repoRoot, "tests/fixtures/artist/an-album/cover.jpg"))
+		Expect(err).ToNot(HaveOccurred())
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write(imgBytes)
+		}))
+		DeferCleanup(srv.Close)
+
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alext", Name: "Album"}})
+		imageAgents(&fakeImageAgent{name: "deezerFake", imgs: []agents.ExternalImage{{URL: srv.URL, Size: 500}}})
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alext"})
+		Expect(out).To(Equal(outcomeFound))
+
+		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alext", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("external:deezerFake"))
+		Expect(ia.Hash).ToNot(BeEmpty())
+
+		art, err := artRepo.GetImage(ia.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		rc, err := store.Open(ia.Hash, art.Mime)
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("dedup: a second item with identical bytes skips decode and reuses the artwork row", func() {
+		folderRepo.result = []model.Folder{{
+			Path:       "tests/fixtures/artist/an-album",
+			ImageFiles: []string{"cover.jpg"},
+		}}
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "al5", Name: "Album A", FolderIDs: []string{"f1"}},
+			{ID: "al6", Name: "Album B", FolderIDs: []string{"f1"}},
+		})
+
+		out1, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al5"})
+		Expect(out1).To(Equal(outcomeFound))
+		ia1, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al5", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+
+		// A re-decode instead of a hash dedup would overwrite this sentinel.
+		poisoned := artRepo.Data[ia1.Hash]
+		poisoned.BlurHash = "SENTINEL"
+		artRepo.Data[ia1.Hash] = poisoned
+
+		out2, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al6"})
+		Expect(out2).To(Equal(outcomeFound))
+		ia2, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al6", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia2.Hash).To(Equal(ia1.Hash))
+
+		reused, err := artRepo.GetImage(ia1.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(reused.BlurHash).To(Equal("SENTINEL"))
+	})
+
+	It("two items, two files, identical bytes: each item keeps its own provenance; the shared artwork row is written once", func() {
+		// Byte-identical files share one hash, but provenance is per item.
+		libRoot := GinkgoT().TempDir()
+		imgBytes, err := os.ReadFile(filepath.Join(repoRoot, "tests/fixtures/artist/an-album/cover.jpg"))
+		Expect(err).ToNot(HaveOccurred())
+		for sub, mtime := range map[string]int64{"album-a": 1000, "album-b": 2000} {
+			dir := filepath.Join(libRoot, sub)
+			Expect(os.MkdirAll(dir, 0755)).To(Succeed())
+			img := filepath.Join(dir, "cover.jpg")
+			Expect(os.WriteFile(img, imgBytes, 0600)).To(Succeed())
+			Expect(os.Chtimes(img, time.Unix(mtime, 0), time.Unix(mtime, 0))).To(Succeed())
+		}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(libRoot)}})
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "alA", Name: "Album A", FolderIDs: []string{"fa"}},
+			{ID: "alB", Name: "Album B", FolderIDs: []string{"fb"}},
+		})
+
+		folderRepo.result = []model.Folder{{Path: "album-a", ImageFiles: []string{"cover.jpg"}}}
+		outN, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alA"})
+		Expect(outN).To(Equal(outcomeFound))
+		iaA, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alA", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(iaA.Source).To(Equal("folder"))
+		Expect(filepath.ToSlash(iaA.SourcePath)).To(HaveSuffix("album-a/cover.jpg"))
+		Expect(iaA.RefMtime).To(Equal(time.Unix(1000, 0).UnixNano()))
+
+		// A re-decode instead of a hash dedup would overwrite this sentinel.
+		poisoned := artRepo.Data[iaA.Hash]
+		poisoned.BlurHash = "SENTINEL"
+		artRepo.Data[iaA.Hash] = poisoned
+
+		folderRepo.result = []model.Folder{{Path: "album-b", ImageFiles: []string{"cover.jpg"}}}
+		outN, _ = proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alB"})
+		Expect(outN).To(Equal(outcomeFound))
+		iaB, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alB", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(iaB.Hash).To(Equal(iaA.Hash))
+		Expect(filepath.ToSlash(iaB.SourcePath)).To(HaveSuffix("album-b/cover.jpg"))
+		Expect(iaB.RefMtime).To(Equal(time.Unix(2000, 0).UnixNano()))
+
+		iaAafter, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alA", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(filepath.ToSlash(iaAafter.SourcePath)).To(HaveSuffix("album-a/cover.jpg"))
+		Expect(iaAafter.RefMtime).To(Equal(time.Unix(1000, 0).UnixNano()))
+
+		Expect(artRepo.Data).To(HaveLen(1))
+		reused, err := artRepo.GetImage(iaA.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(reused.BlurHash).To(Equal("SENTINEL"))
+	})
+
+	It("decode failure on found bytes: fails without writing state", func() {
+		tmpDir := GinkgoT().TempDir()
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
+		Expect(os.MkdirAll(filepath.Join(tmpDir, "artwork", "radio"), 0755)).To(Succeed())
+		imgPath := filepath.Join(tmpDir, "artwork", "radio", "ra1_test.jpg")
+		Expect(os.WriteFile(imgPath, []byte("not actually an image"), 0600)).To(Succeed())
+
+		radioRepo := tests.CreateMockedRadioRepo()
+		radioRepo.Data = map[string]*model.Radio{"ra1": {ID: "ra1", Name: "Radio", UploadedImage: "ra1_test.jpg"}}
+		ds.MockedRadio = radioRepo
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra1"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		_, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+
+	It("oversized read: a resolved image larger than the cap fails without writing state", func() {
+		tmpDir := GinkgoT().TempDir()
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
+		Expect(os.MkdirAll(filepath.Join(tmpDir, "artwork", "radio"), 0755)).To(Succeed())
+		imgPath := filepath.Join(tmpDir, "artwork", "radio", "big_test.jpg")
+		f, err := os.Create(imgPath)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(f.Truncate(maxImageBytes + 1)).To(Succeed())
+		Expect(f.Close()).To(Succeed())
+
+		radioRepo := tests.CreateMockedRadioRepo()
+		radioRepo.Data = map[string]*model.Radio{"big": {ID: "big", Name: "Radio", UploadedImage: "big_test.jpg"}}
+		ds.MockedRadio = radioRepo
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "big"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		_, err = artRepo.GetItemArtwork(model.KindRadioArtwork, "big", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+
+	// The cap is compared by division so an overflowing product cannot slip past it; no supported
+	// format can declare these dimensions, so this pins the arithmetic, not a live hole.
+	DescribeTable("rejects out-of-range declared dimensions",
+		func(w, h uint32) {
+			_, err := decodeArtwork(ctx, "bomb", pngHeaderWithDims(w, h))
+			Expect(err).To(HaveOccurred())
+		},
+		Entry("both dimensions at the 32-bit maximum", uint32(0xffffffff), uint32(0xffffffff)),
+		Entry("both dimensions at the signed 32-bit maximum", uint32(0x7fffffff), uint32(0x7fffffff)),
+		Entry("zero width", uint32(0), uint32(100)),
+		Entry("zero height", uint32(100), uint32(0)),
+	)
+
+	It("decompression bomb: rejects huge declared dimensions before the full decode", func() {
+		data := pngHeaderWithDims(50000, 50000) // 2.5 gigapixels, far above the cap
+		_, err := decodeArtwork(ctx, "bomb", data)
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("dimensions"))
+	})
+
+	It("store write failure: fails without writing state", func() {
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "al7", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},
+		})
+		folderRepo.result = nil
+
+		// A store root that is a plain file makes every MkdirAll under it fail.
+		blockedRoot := filepath.Join(GinkgoT().TempDir(), "not-a-dir")
+		Expect(os.WriteFile(blockedRoot, []byte("x"), 0600)).To(Succeed())
+		proc.store = NewImageStore(blockedRoot)
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al7"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al7", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+})
+
+type countingLocker struct {
+	locks   int
+	unlocks int
+}
+
+func (l *countingLocker) Lock()      { l.locks++ }
+func (l *countingLocker) Unlock()    { l.unlocks++ }
+func (l *countingLocker) held() bool { return l.locks != l.unlocks }
+
+var _ = Describe("makeThumbnail", func() {
+	// Both encoders read Pix directly and thumbhash needs straight alpha, so emitting NRGBA is
+	// what keeps either of them from allocating a converted copy of the thumbnail.
+	It("emits NRGBA when it downscales", func() {
+		src := image.NewRGBA(image.Rect(0, 0, 400, 300))
+		Expect(makeThumbnail(src, 100)).To(BeAssignableToTypeOf(&image.NRGBA{}))
+	})
+
+	It("fits the longest side to maxSize and keeps the aspect ratio", func() {
+		src := image.NewRGBA(image.Rect(0, 0, 400, 300))
+		b := makeThumbnail(src, 100).Bounds()
+		Expect(b.Dx()).To(Equal(100))
+		Expect(b.Dy()).To(Equal(75))
+	})
+
+	It("never upscales an image already within bounds", func() {
+		src := image.NewRGBA(image.Rect(0, 0, 40, 30))
+		Expect(makeThumbnail(src, 100).Bounds()).To(Equal(src.Bounds()))
+	})
+
+	// A fully transparent pixel's colour cannot survive any resample, since the scaler works in
+	// premultiplied space and multiplying by zero is not invertible. Partial alpha is the case
+	// that distinguishes straight storage from premultiplied.
+	It("keeps partly transparent colour straight rather than premultiplied", func() {
+		src := image.NewNRGBA(image.Rect(0, 0, 400, 400))
+		for y := range 400 {
+			for x := range 400 {
+				src.SetNRGBA(x, y, color.NRGBA{R: 200, G: 40, B: 90, A: 128})
+			}
+		}
+		thumb, ok := makeThumbnail(src, 100).(*image.NRGBA)
+		Expect(ok).To(BeTrue())
+		// Premultiplied storage would have halved this to ~100.
+		Expect(thumb.Pix[0]).To(BeNumerically("==", 200))
+		Expect(thumb.Pix[3]).To(BeNumerically("==", 128))
+	})
+})
diff --git a/core/artwork/prune.go b/core/artwork/prune.go
new file mode 100644
index 000000000..c79458b8f
--- /dev/null
+++ b/core/artwork/prune.go
@@ -0,0 +1,63 @@
+package artwork
+
+import (
+	"context"
+	"time"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+// pruneMinAge guards the window between artwork insert and item_artwork upsert.
+const pruneMinAge = time.Hour
+
+func prune(ctx context.Context, ds model.DataStore, store *ImageStore) error {
+	start := time.Now()
+	defer func() { log.Debug(ctx, "Artwork: Prune finished", "elapsed", time.Since(start)) }()
+	repo := ds.Artwork(ctx)
+
+	purged, err := repo.PurgeDanglingItems()
+	if err != nil {
+		return err
+	}
+	if purged > 0 {
+		log.Info(ctx, "Artwork: Purged dangling item state", "count", purged)
+	}
+
+	// Queue rows for deleted entities would otherwise retry forever (Get -> not found -> failed).
+	queuePurged, err := ds.ArtworkQueue(ctx).PurgeDangling()
+	if err != nil {
+		return err
+	}
+	if queuePurged > 0 {
+		log.Info(ctx, "Artwork: Purged dangling queue rows", "count", queuePurged)
+	}
+
+	// Files younger than the grace window may belong to acquisitions whose rows aren't committed yet.
+	cutoff := time.Now().Add(-pruneMinAge)
+	orphans, err := repo.PurgeOrphans(cutoff)
+	if err != nil {
+		return err
+	}
+	if orphans > 0 {
+		log.Info(ctx, "Artwork: Removed orphan image rows", "count", orphans)
+	}
+
+	// Read after the delete, so the sweep below reclaims the files of the rows just removed.
+	mimes, err := repo.GetMimeByHash()
+	if err != nil {
+		return err
+	}
+	removed, err := store.Sweep(ctx, cutoff, func(hash, ext string) bool {
+		// A known hash under a stale extension is a superseded mime variant — reclaim it.
+		m, ok := mimes[hash]
+		return ok && ext == extForMime(m)
+	})
+	if err != nil {
+		return err
+	}
+	if removed > 0 {
+		log.Info(ctx, "Artwork: Swept stray files", "count", removed)
+	}
+	return nil
+}
diff --git a/core/artwork/prune_test.go b/core/artwork/prune_test.go
new file mode 100644
index 000000000..8b8504f89
--- /dev/null
+++ b/core/artwork/prune_test.go
@@ -0,0 +1,239 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type flakyGetArtworkRepo struct {
+	*tests.MockArtworkRepo
+}
+
+func (f *flakyGetArtworkRepo) GetMimeByHash() (map[string]string, error) {
+	return nil, errors.New("db locked")
+}
+
+var _ = Describe("Prune", func() {
+	var ds *tests.MockDataStore
+	var store *ImageStore
+	var awRepo *tests.MockArtworkRepo
+
+	BeforeEach(func() {
+		ds = &tests.MockDataStore{}
+		awRepo = ds.Artwork(context.Background()).(*tests.MockArtworkRepo)
+		store = NewImageStore(GinkgoT().TempDir())
+	})
+
+	// PutImage refreshes created_at like the SQL repo, so fixtures are aged directly.
+	ageArtwork := func(h string, t time.Time) {
+		a := awRepo.Data[h]
+		a.CreatedAt = t
+		awRepo.Data[h] = a
+	}
+
+	It("purges dangling item_artwork state for gone entities, summed across kinds", func() {
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "gone-album", ImageType: model.ImageTypePrimary})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "gone-artist", ImageType: model.ImageTypePrimary})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "live-artist", ImageType: model.ImageTypePrimary})).To(Succeed())
+		awRepo.ExistingIDs = map[string]map[string]bool{
+			"al": {},
+			"ar": {"live-artist": true},
+		}
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		_, err := awRepo.GetItemArtwork(model.KindAlbumArtwork, "gone-album", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+		_, err = awRepo.GetItemArtwork(model.KindArtistArtwork, "gone-artist", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+		_, err = awRepo.GetItemArtwork(model.KindArtistArtwork, "live-artist", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+	})
+
+	It("purges dangling artwork_queue rows for gone entities", func() {
+		queueRepo := tests.CreateMockArtworkQueueRepo()
+		Expect(queueRepo.Enqueue(
+			model.ArtworkQueueItem{ItemKind: "al", ItemID: "gone-album", ImageType: model.ImageTypePrimary},
+			model.ArtworkQueueItem{ItemKind: "al", ItemID: "live-album", ImageType: model.ImageTypePrimary},
+		)).To(Succeed())
+		queueRepo.ExistingIDs = map[string]map[string]bool{"al": {"live-album": true}}
+		ds.MockedArtworkQueue = queueRepo
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		Expect(findQueued(queueRepo, "al", "gone-album")).To(BeNil())
+		Expect(findQueued(queueRepo, "al", "live-album")).ToNot(BeNil())
+	})
+
+	It("deletes orphan rows and their store files, keeps referenced ones", func() {
+		data := []byte("orphan-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+		old := time.Now().Add(-2 * time.Hour)
+		Expect(os.Chtimes(store.path(h, "image/jpeg"), old, old)).To(Succeed())
+		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+		ageArtwork(h, old)
+
+		kept := []byte("kept-bytes")
+		hk, _ := hashImage(bytes.NewReader(kept))
+		Expect(store.Write(hk, "image/jpeg", bytes.NewReader(kept))).To(Succeed())
+		Expect(awRepo.PutImage(&model.Artwork{Hash: hk, Mime: "image/jpeg"})).To(Succeed())
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		_, err := awRepo.GetImage(h)
+		Expect(err).To(MatchError(model.ErrNotFound))
+		_, err = store.Open(h, "image/jpeg")
+		Expect(os.IsNotExist(err)).To(BeTrue())
+		rc, err := store.Open(hk, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("spares an aged row that item_artwork state still references", func() {
+		data := []byte("reacquired-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+		ageArtwork(h, time.Now().Add(-2*time.Hour))
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "a1",
+			ImageType: model.ImageTypePrimary, Hash: h, Source: "folder"})).To(Succeed())
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		_, err := awRepo.GetImage(h)
+		Expect(err).ToNot(HaveOccurred())
+		rc, err := store.Open(h, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("spares an unreferenced row recreated inside the grace window", func() {
+		data := []byte("fresh-reacquired-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+		// Reacquisition refreshed created_at, so the row is unreferenced but too young to drop.
+		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		_, err := awRepo.GetImage(h)
+		Expect(err).ToNot(HaveOccurred())
+		rc, err := store.Open(h, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("spares an orphan file freshly touched by an overlapping acquisition", func() {
+		data := []byte("racing-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+		ageArtwork(h, time.Now().Add(-2*time.Hour))
+		// The row is orphaned, but a concurrent acquisition just touched the file's mtime.
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		rc, err := store.Open(h, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("sweeps store files that have no artwork row", func() {
+		stray := []byte("no-row-bytes")
+		h, _ := hashImage(bytes.NewReader(stray))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(stray))).To(Succeed())
+		old := time.Now().Add(-2 * time.Hour)
+		Expect(os.Chtimes(store.path(h, "image/jpeg"), old, old)).To(Succeed())
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		_, err := store.Open(h, "image/jpeg")
+		Expect(os.IsNotExist(err)).To(BeTrue())
+	})
+
+	It("sweeps an obsolete mime variant of a reacquired hash", func() {
+		data := []byte("variant-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/png", bytes.NewReader(data))).To(Succeed())
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+		old := time.Now().Add(-2 * time.Hour)
+		Expect(os.Chtimes(store.path(h, "image/png"), old, old)).To(Succeed())
+		Expect(os.Chtimes(store.path(h, "image/jpeg"), old, old)).To(Succeed())
+		// The row records the current mime; the .png file is a superseded variant.
+		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		_, err := store.Open(h, "image/png")
+		Expect(os.IsNotExist(err)).To(BeTrue())
+		rc, err := store.Open(h, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("reclaims the other orphan files when one of them cannot be removed", func() {
+		tests.SkipOnWindows("uses Unix file permission bits")
+		if os.Geteuid() == 0 {
+			Skip("read-only dir cannot block root (e.g. tests in a container)")
+		}
+		old := time.Now().Add(-2 * time.Hour)
+
+		blocked := []byte("blocked-bytes")
+		hb, _ := hashImage(bytes.NewReader(blocked))
+		Expect(store.Write(hb, "image/jpeg", bytes.NewReader(blocked))).To(Succeed())
+		Expect(os.Chtimes(store.path(hb, "image/jpeg"), old, old)).To(Succeed())
+		Expect(awRepo.PutImage(&model.Artwork{Hash: hb, Mime: "image/jpeg"})).To(Succeed())
+		ageArtwork(hb, old)
+
+		good := []byte("good-bytes")
+		hg, _ := hashImage(bytes.NewReader(good))
+		Expect(store.Write(hg, "image/jpeg", bytes.NewReader(good))).To(Succeed())
+		Expect(os.Chtimes(store.path(hg, "image/jpeg"), old, old)).To(Succeed())
+		Expect(awRepo.PutImage(&model.Artwork{Hash: hg, Mime: "image/jpeg"})).To(Succeed())
+		ageArtwork(hg, old)
+
+		// A read-only shard directory makes os.Remove fail (EACCES) for hb's file only.
+		shardDir := filepath.Dir(store.path(hb, "image/jpeg"))
+		Expect(shardDir).ToNot(Equal(filepath.Dir(store.path(hg, "image/jpeg"))), "fixtures must land in different shards")
+		Expect(os.Chmod(shardDir, 0500)).To(Succeed())
+		DeferCleanup(func() { _ = os.Chmod(shardDir, 0755) })
+
+		Expect(prune(context.Background(), ds, store)).To(Succeed())
+
+		_, err := awRepo.GetImage(hg)
+		Expect(err).To(MatchError(model.ErrNotFound))
+		_, err = store.Open(hg, "image/jpeg")
+		Expect(os.IsNotExist(err)).To(BeTrue())
+
+		// The row purge does not depend on file removal, so only the file survives.
+		_, err = awRepo.GetImage(hb)
+		Expect(err).To(MatchError(model.ErrNotFound))
+		rc, err := store.Open(hb, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+
+	It("never sweeps files on a transient DB error", func() {
+		ds.MockedArtwork = &flakyGetArtworkRepo{MockArtworkRepo: tests.CreateMockArtworkRepo()}
+
+		data := []byte("live-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+
+		Expect(prune(context.Background(), ds, store)).ToNot(Succeed())
+
+		rc, err := store.Open(h, "image/jpeg")
+		Expect(err).ToNot(HaveOccurred())
+		rc.Close()
+	})
+})
diff --git a/core/artwork/reader_album_test.go b/core/artwork/reader_album_test.go
deleted file mode 100644
index c95ddedaa..000000000
--- a/core/artwork/reader_album_test.go
+++ /dev/null
@@ -1,481 +0,0 @@
-package artwork
-
-import (
-	"context"
-	"errors"
-	"path/filepath"
-	"time"
-
-	"github.com/navidrome/navidrome/model"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Album Artwork Reader", func() {
-	Describe("loadAlbumFoldersPaths", func() {
-		var (
-			ctx        context.Context
-			ds         *fakeDataStore
-			repo       *fakeFolderRepo
-			album      model.Album
-			now        time.Time
-			expectedAt time.Time
-		)
-
-		BeforeEach(func() {
-			ctx = context.Background()
-			now = time.Now().Truncate(time.Second)
-			expectedAt = now.Add(5 * time.Minute)
-
-			// Set up the test folders with image files
-			repo = &fakeFolderRepo{}
-			ds = &fakeDataStore{
-				folderRepo: repo,
-			}
-			album = model.Album{
-				ID:        "album1",
-				Name:      "Album",
-				FolderIDs: []string{"folder1", "folder2", "folder3"},
-			}
-		})
-
-		It("returns sorted image files", func() {
-			repo.result = []model.Folder{
-				{
-					Path:            "Artist/Album/Disc1",
-					ImagesUpdatedAt: expectedAt,
-					ImageFiles:      []string{"cover.jpg", "back.jpg", "cover.1.jpg"},
-				},
-				{
-					Path:            "Artist/Album/Disc2",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{"cover.jpg"},
-				},
-				{
-					Path:            "Artist/Album/Disc10",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{"cover.jpg"},
-				},
-			}
-
-			_, imgFiles, imagesUpdatedAt, err := loadAlbumFoldersPaths(ctx, ds, album)
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(*imagesUpdatedAt).To(Equal(expectedAt))
-
-			// Check that image files are sorted by base name (without extension)
-			Expect(imgFiles).To(HaveLen(5))
-
-			// 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("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() {
-			// Test case for issue #4683: cover.jpg should come before cover.1.jpg
-			repo.result = []model.Folder{
-				{
-					Path:            "Artist/Album",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{"cover.1.jpg", "cover.jpg", "cover.2.jpg"},
-				},
-			}
-
-			_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(imgFiles).To(HaveLen(3))
-
-			// cover.jpg should come first because "cover" < "cover.1" < "cover.2"
-			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() {
-			// Test that Cover.jpg and cover.jpg are treated as equivalent
-			repo.result = []model.Folder{
-				{
-					Path:            "Artist/Album",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{"Folder.jpg", "cover.jpg", "BACK.jpg"},
-				},
-			}
-
-			_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(imgFiles).To(HaveLen(3))
-
-			// Files should be sorted case-insensitively: BACK, cover, Folder
-			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",
-				ParentID:        "artistFolder",
-				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 library root parent for multi-folder albums", func() {
-			// Two album parts directly under the library root — parent is the root itself
-			repo.result = []model.Folder{
-				{
-					ID:              "folder1",
-					Path:            ".",
-					Name:            "AlbumPart1",
-					ParentID:        "rootFolder",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{"cover.jpg"},
-				},
-				{
-					ID:              "folder2",
-					Path:            ".",
-					Name:            "AlbumPart2",
-					ParentID:        "rootFolder",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{},
-				},
-			}
-			repo.parentResult = &model.Folder{
-				ID:         "rootFolder",
-				Path:       "",
-				Name:       ".",
-				ParentID:   "",
-				ImageFiles: []string{"unrelated.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("includes top-level album folder for multi-disc albums", func() {
-			// Album folder directly under library root, with disc subfolders
-			repo.result = []model.Folder{
-				{
-					ID:              "folder1",
-					Path:            "Album",
-					Name:            "Disc1",
-					ParentID:        "albumFolder",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{"folder.jpg"},
-				},
-				{
-					ID:              "folder2",
-					Path:            "Album",
-					Name:            "Disc2",
-					ParentID:        "albumFolder",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{"folder.jpg"},
-				},
-			}
-			repo.parentResult = &model.Folder{
-				ID:              "albumFolder",
-				Path:            ".",
-				Name:            "Album",
-				ParentID:        "rootFolder",
-				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(3))
-			Expect(imgFiles[0]).To(Equal("Album/cover.jpg"))
-			Expect(imgFiles[1]).To(Equal("Album/Disc1/folder.jpg"))
-			Expect(imgFiles[2]).To(Equal("Album/Disc2/folder.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",
-				ParentID:        "artistFolder",
-				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("promotes the album root parent into the returned paths", func() {
-			repo.result = []model.Folder{
-				{
-					ID:              "folder1",
-					Path:            "Artist",
-					Name:            "Album",
-					ParentID:        "artistFolder",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{},
-				},
-			}
-			repo.parentResult = &model.Folder{
-				ID:              "artistFolder",
-				Path:            ".",
-				Name:            "Artist",
-				ParentID:        "libraryRoot",
-				ImagesUpdatedAt: expectedAt,
-				ImageFiles:      []string{"folder.jpg"},
-			}
-
-			paths, _, _, err := loadAlbumFoldersPaths(ctx, ds, album)
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(paths).To(Equal([]string{filepath.Join("Artist", "Album"), "Artist"}))
-		})
-
-		It("does not include parent images when other albums' audio lives under the parent", func() {
-			// Simulates: Artist/folder.jpg with Artist/Album (no images) and
-			// another album's tracks elsewhere under the artist folder
-			repo.result = []model.Folder{
-				{
-					ID:              "folder1",
-					Path:            "Artist",
-					Name:            "Album",
-					ParentID:        "artistFolder",
-					ImagesUpdatedAt: now,
-					ImageFiles:      []string{},
-				},
-			}
-			repo.parentResult = &model.Folder{
-				ID:              "artistFolder",
-				Path:            ".",
-				Name:            "Artist",
-				ParentID:        "libraryRoot",
-				ImagesUpdatedAt: expectedAt,
-				ImageFiles:      []string{"folder.jpg"},
-			}
-			repo.hasOtherAudio = true
-
-			_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, ds, album)
-
-			Expect(err).ToNot(HaveOccurred())
-			Expect(imgFiles).To(BeEmpty())
-		})
-
-		It("propagates errors from the album-root check", 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",
-				ParentID:        "artistFolder",
-				ImagesUpdatedAt: expectedAt,
-				ImageFiles:      []string{"cover.jpg"},
-			}
-			repo.otherAudioErr = errors.New("db connection failed")
-
-			_, _, _, err := loadAlbumFoldersPaths(ctx, ds, album)
-
-			Expect(err).To(MatchError("db connection failed"))
-		})
-
-		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))
-		})
-	})
-})
diff --git a/core/artwork/reader_artist.go b/core/artwork/reader_artist.go
deleted file mode 100644
index fe5bcb196..000000000
--- a/core/artwork/reader_artist.go
+++ /dev/null
@@ -1,359 +0,0 @@
-package artwork
-
-import (
-	"context"
-	"crypto/md5"
-	"fmt"
-	"io"
-	"io/fs"
-	"os"
-	"path"
-	"path/filepath"
-	"slices"
-	"strings"
-	"time"
-
-	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
-	"github.com/navidrome/navidrome/core/external"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/utils/slice"
-	"github.com/navidrome/navidrome/utils/str"
-)
-
-const (
-	// maxArtistFolderTraversalDepth defines how many directory levels to search
-	// when looking for artist images (artist folder + parent directories)
-	maxArtistFolderTraversalDepth = 3
-)
-
-type artistReader struct {
-	cacheKey
-	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) {
-	ar, err := artwork.ds.Artist(ctx).Get(artID.ID)
-	if err != nil {
-		return nil, err
-	}
-	// Only consider albums where the artist is the sole album artist.
-	als, err := artwork.ds.Album(ctx).GetAll(model.QueryOptions{
-		Filters: squirrel.And{
-			squirrel.Eq{"album_artist_id": artID.ID},
-			squirrel.Eq{"json_array_length(participants, '$.albumartist')": 1},
-		},
-	})
-	if err != nil {
-		return nil, err
-	}
-	albumPaths, imgFiles, imagesUpdatedAt, err := loadArtistAlbumRoots(ctx, artwork.ds, als)
-	if err != nil {
-		return nil, err
-	}
-	artistFolder, artistFolderLastUpdate, err := loadArtistFolder(ctx, artwork.ds, als, albumPaths)
-	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))
-	return fmt.Sprintf(
-		"%s.%t.%x",
-		a.cacheKey.Key(),
-		conf.Server.EnableExternalServices,
-		hash,
-	)
-}
-
-func (a *artistReader) LastUpdated() time.Time {
-	return a.lastUpdate
-}
-
-func (a *artistReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
-	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), ",") {
-		pattern = strings.TrimSpace(pattern)
-		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/"):
-			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.lib.FS, a.lib.absRoot, a.artistFolder, pattern))
-		}
-	}
-	return ff
-}
-
-// 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 {
-			reader, hit, err := findImageInFolder(ctx, libFS, rel, current, pattern)
-			if err == nil {
-				return reader, hit, nil
-			}
-			if rel == "." {
-				break // reached library root; don't traverse above it
-			}
-			rel = path.Dir(rel)
-			current = filepath.Dir(current)
-		}
-		return nil, "", fmt.Errorf(`no matches for '%s' in '%s' or its parent directories (within library)`, pattern, artistFolder)
-	}
-}
-
-// 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", absFolder, err)
-		return nil, "", err
-	}
-
-	// Filter to valid image files
-	var imagePaths []string
-	for _, m := range matches {
-		if !model.IsImageFile(m) {
-			continue
-		}
-		imagePaths = append(imagePaths, m)
-	}
-
-	// Sort image files by prioritizing base filenames without numeric
-	// suffixes (e.g., artist.jpg before artist.1.jpg)
-	slices.SortFunc(imagePaths, compareImageFiles)
-
-	for _, p := range imagePaths {
-		f, err := libFS.Open(p)
-		if err != nil {
-			log.Warn(ctx, "Could not open cover art file", "file", p, err)
-			continue
-		}
-		_, name := path.Split(p)
-		return f, filepath.Join(absFolder, name), nil
-	}
-
-	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()
-}
-
-// loadArtistAlbumRoots returns one path per album — the deepest folder holding
-// all of that album's tracks — so an album split into disc subfolders can't
-// pull the artist folder's common prefix below the artist level.
-func loadArtistAlbumRoots(ctx context.Context, ds model.DataStore, albums model.Albums) ([]string, []string, *time.Time, error) {
-	var folderIDs []string
-	for _, album := range albums {
-		folderIDs = append(folderIDs, album.FolderIDs...)
-	}
-	folders, err := loadFolders(ctx, ds, folderIDs)
-	if err != nil {
-		return nil, nil, nil, err
-	}
-
-	pathByID := slice.ToMap(folders, func(f model.Folder) (string, string) {
-		return f.ID, f.AbsolutePath()
-	})
-	var roots []string
-	for _, album := range albums {
-		var albumPaths []string
-		for _, fid := range album.FolderIDs {
-			if p, ok := pathByID[fid]; ok {
-				albumPaths = append(albumPaths, p)
-			}
-		}
-		if len(albumPaths) > 0 {
-			roots = append(roots, commonDir(albumPaths))
-		}
-	}
-
-	imgFiles, updatedAt := folderImages(folders)
-	return roots, imgFiles, &updatedAt, nil
-}
-
-// commonDir returns the deepest directory containing all paths. Trailing
-// separators keep the comparison on segment boundaries, so a shared name
-// fragment (".../Album" and ".../Album2") is never read as a shared directory.
-func commonDir(paths []string) string {
-	sep := string(filepath.Separator)
-	common := str.LongestCommonPrefix(slice.Map(paths, func(p string) string { return p + sep }))
-	if !strings.HasSuffix(common, sep) {
-		common, _ = filepath.Split(common)
-	}
-	return filepath.Clean(common)
-}
-
-func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albums, paths []string) (string, time.Time, error) {
-	if len(albums) == 0 {
-		return "", time.Time{}, nil
-	}
-	libID := albums[0].LibraryID // Just need one of the albums, as they should all be in the same Library - for now! TODO: Support multiple libraries
-
-	// paths holds one root per album: two or more distinct roots already meet at
-	// the artist folder, while a single root is an album folder needing a climb.
-	roots := slices.Compact(slices.Sorted(slices.Values(paths)))
-	folderPath := commonDir(roots)
-	if len(roots) < 2 {
-		folderPath = filepath.Dir(folderPath)
-	}
-
-	// Manipulate the path to get the folder ID
-	// TODO: This is a bit hacky, but it's the easiest way to get the folder ID, ATM
-	libPath := core.AbsolutePath(ctx, ds, libID, "")
-	folderID := model.FolderID(model.Library{ID: libID, Path: libPath}, folderPath)
-
-	log.Trace(ctx, "Calculating artist folder details", "folderPath", folderPath, "folderID", folderID,
-		"libPath", libPath, "libID", libID, "albumPaths", paths)
-
-	// Get the last update time for the folder
-	folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderID, "missing": false}})
-	if err != nil || len(folders) == 0 {
-		log.Warn(ctx, "Could not find folder for artist", "folderPath", folderPath, "id", folderID,
-			"libPath", libPath, "libID", libID, err)
-		return "", time.Time{}, err
-	}
-	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 ""
-}
diff --git a/core/artwork/reader_artist_test.go b/core/artwork/reader_artist_test.go
deleted file mode 100644
index c75f8447e..000000000
--- a/core/artwork/reader_artist_test.go
+++ /dev/null
@@ -1,761 +0,0 @@
-package artwork
-
-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"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("artistArtworkReader", func() {
-	var _ = Describe("loadArtistFolder", func() {
-		var (
-			ctx             context.Context
-			fds             *fakeDataStore
-			repo            *fakeFolderRepo
-			albums          model.Albums
-			paths           []string
-			now             time.Time
-			expectedUpdTime time.Time
-		)
-
-		BeforeEach(func() {
-			ctx = context.Background()
-			DeferCleanup(stubCoreAbsolutePath())
-
-			now = time.Now().Truncate(time.Second)
-			expectedUpdTime = now.Add(5 * time.Minute)
-			repo = &fakeFolderRepo{
-				result: []model.Folder{
-					{
-						ImagesUpdatedAt: expectedUpdTime,
-					},
-				},
-				err: nil,
-			}
-			fds = &fakeDataStore{
-				folderRepo: repo,
-			}
-			albums = model.Albums{
-				{LibraryID: 1, ID: "album1", Name: "Album 1"},
-			}
-		})
-
-		When("no albums provided", func() {
-			It("returns empty and zero time", func() {
-				folder, upd, err := loadArtistFolder(ctx, fds, model.Albums{}, []string{"/dummy/path"})
-				Expect(err).ToNot(HaveOccurred())
-				Expect(folder).To(BeEmpty())
-				Expect(upd).To(BeZero())
-			})
-		})
-
-		When("artist has only one album", func() {
-			It("returns the parent folder", func() {
-				paths = []string{
-					filepath.FromSlash("/music/artist/album1"),
-				}
-				folder, upd, err := loadArtistFolder(ctx, fds, albums, paths)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
-				Expect(upd).To(Equal(expectedUpdTime))
-			})
-		})
-
-		When("the artist have multiple albums", func() {
-			It("returns the common prefix for the albums paths", func() {
-				paths = []string{
-					filepath.FromSlash("/music/library/artist/one"),
-					filepath.FromSlash("/music/library/artist/two"),
-				}
-				folder, upd, err := loadArtistFolder(ctx, fds, albums, paths)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(folder).To(Equal(filepath.FromSlash("/music/library/artist")))
-				Expect(upd).To(Equal(expectedUpdTime))
-			})
-		})
-
-		When("two albums share the same folder", func() {
-			It("climbs above the shared album folder", func() {
-				paths = []string{
-					filepath.FromSlash("/music/artist/split"),
-					filepath.FromSlash("/music/artist/split"),
-				}
-				folder, upd, err := loadArtistFolder(ctx, fds, albums, paths)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
-				Expect(upd).To(Equal(expectedUpdTime))
-			})
-		})
-
-		When("the album paths contain same prefix", func() {
-			It("returns the common prefix", func() {
-				paths = []string{
-					filepath.FromSlash("/music/artist/album1"),
-					filepath.FromSlash("/music/artist/album2"),
-				}
-				folder, upd, err := loadArtistFolder(ctx, fds, albums, paths)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(folder).To(Equal(filepath.FromSlash("/music/artist")))
-				Expect(upd).To(Equal(expectedUpdTime))
-			})
-		})
-
-		When("ds.Folder().GetAll returns an error", func() {
-			It("returns an error", func() {
-				paths = []string{
-					filepath.FromSlash("/music/artist/album1"),
-					filepath.FromSlash("/music/artist/album2"),
-				}
-				repo.err = errors.New("fake error")
-				folder, upd, err := loadArtistFolder(ctx, fds, albums, paths)
-				Expect(err).To(MatchError(ContainSubstring("fake error")))
-				// Folder and time are empty on error.
-				Expect(folder).To(BeEmpty())
-				Expect(upd).To(BeZero())
-			})
-		})
-	})
-
-	var _ = Describe("fromArtistFolder", 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() {
-			BeforeEach(func() {
-				// Create test structure: /temp/artist/artist.jpg
-				artistDir := filepath.Join(tempDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				artistImagePath := filepath.Join(artistDir, "artist.jpg")
-				Expect(os.WriteFile(artistImagePath, []byte("fake image data"), 0600)).To(Succeed())
-
-				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("finds and returns the image", func() {
-				reader, path, err := testFunc()
-				Expect(err).ToNot(HaveOccurred())
-				Expect(reader).ToNot(BeNil())
-				Expect(path).To(ContainSubstring("artist.jpg"))
-
-				// Verify we can read the content
-				data, err := io.ReadAll(reader)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(string(data)).To(Equal("fake image data"))
-				reader.Close()
-			})
-		})
-
-		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/
-				parentDir := filepath.Join(tempDir, "parent")
-				artistDir := filepath.Join(parentDir, "artist")
-				albumDir := filepath.Join(artistDir, "album")
-				Expect(os.MkdirAll(albumDir, 0755)).To(Succeed())
-
-				// Put artist image in parent directory
-				artistImagePath := filepath.Join(parentDir, "artist.jpg")
-				Expect(os.WriteFile(artistImagePath, []byte("parent image"), 0600)).To(Succeed())
-
-				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("finds image in parent directory", func() {
-				reader, path, err := testFunc()
-				Expect(err).ToNot(HaveOccurred())
-				Expect(reader).ToNot(BeNil())
-				Expect(path).To(ContainSubstring("parent" + string(filepath.Separator) + "artist.jpg"))
-
-				data, err := io.ReadAll(reader)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(string(data)).To(Equal("parent image"))
-				reader.Close()
-			})
-		})
-
-		When("image is two levels up", func() {
-			BeforeEach(func() {
-				// Create test structure: /temp/grandparent/artist.jpg and /temp/grandparent/parent/artist/
-				grandparentDir := filepath.Join(tempDir, "grandparent")
-				parentDir := filepath.Join(grandparentDir, "parent")
-				artistDir := filepath.Join(parentDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				// Put artist image in grandparent directory
-				artistImagePath := filepath.Join(grandparentDir, "artist.jpg")
-				Expect(os.WriteFile(artistImagePath, []byte("grandparent image"), 0600)).To(Succeed())
-
-				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("finds image in grandparent directory", func() {
-				reader, path, err := testFunc()
-				Expect(err).ToNot(HaveOccurred())
-				Expect(reader).ToNot(BeNil())
-				Expect(path).To(ContainSubstring("grandparent" + string(filepath.Separator) + "artist.jpg"))
-
-				data, err := io.ReadAll(reader)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(string(data)).To(Equal("grandparent image"))
-				reader.Close()
-			})
-		})
-
-		When("images exist at multiple levels", func() {
-			BeforeEach(func() {
-				// Create test structure with images at multiple levels
-				grandparentDir := filepath.Join(tempDir, "grandparent")
-				parentDir := filepath.Join(grandparentDir, "parent")
-				artistDir := filepath.Join(parentDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				// Put artist images at all levels
-				Expect(os.WriteFile(filepath.Join(artistDir, "artist.jpg"), []byte("artist level"), 0600)).To(Succeed())
-				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, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("prioritizes the closest (artist folder) image", func() {
-				reader, path, err := testFunc()
-				Expect(err).ToNot(HaveOccurred())
-				Expect(reader).ToNot(BeNil())
-				Expect(path).To(ContainSubstring("artist" + string(filepath.Separator) + "artist.jpg"))
-
-				data, err := io.ReadAll(reader)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(string(data)).To(Equal("artist level"))
-				reader.Close()
-			})
-		})
-
-		When("pattern matches multiple files", func() {
-			BeforeEach(func() {
-				artistDir := filepath.Join(tempDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				// Create multiple matching files
-				Expect(os.WriteFile(filepath.Join(artistDir, "artist.abc"), []byte("text file"), 0600)).To(Succeed())
-				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, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("returns the first valid image file in sorted order", func() {
-				reader, path, err := testFunc()
-				Expect(err).ToNot(HaveOccurred())
-				Expect(reader).ToNot(BeNil())
-
-				// Should return an image file,
-				// Files are sorted: jpg comes before png alphabetically.
-				// .abc comes first, but it's not an image.
-				Expect(path).To(ContainSubstring("artist.jpg"))
-				reader.Close()
-			})
-		})
-
-		When("prioritizing files without numeric suffixes", func() {
-			BeforeEach(func() {
-				// Test case for issue #4683: artist.jpg should come before artist.1.jpg
-				artistDir := filepath.Join(tempDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				// Create multiple matches with and without numeric suffixes
-				Expect(os.WriteFile(filepath.Join(artistDir, "artist.1.jpg"), []byte("artist 1"), 0600)).To(Succeed())
-				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, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("returns artist.jpg before artist.1.jpg and artist.2.jpg", func() {
-				reader, path, err := testFunc()
-				Expect(err).ToNot(HaveOccurred())
-				Expect(reader).ToNot(BeNil())
-				Expect(path).To(ContainSubstring("artist.jpg"))
-
-				// Verify it's the main file, not a numbered variant
-				data, err := io.ReadAll(reader)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(string(data)).To(Equal("artist main"))
-				reader.Close()
-			})
-		})
-
-		When("handling case-insensitive sorting", func() {
-			BeforeEach(func() {
-				// Test case to ensure case-insensitive natural sorting
-				artistDir := filepath.Join(tempDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				// Create files with mixed case names
-				Expect(os.WriteFile(filepath.Join(artistDir, "Folder.jpg"), []byte("folder"), 0600)).To(Succeed())
-				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, libFS, tempDir, artistDir, "*.*")
-			})
-
-			It("sorts case-insensitively", func() {
-				reader, path, err := testFunc()
-				Expect(err).ToNot(HaveOccurred())
-				Expect(reader).ToNot(BeNil())
-
-				// Should return artist.jpg first (case-insensitive: "artist" < "back" < "folder")
-				Expect(path).To(ContainSubstring("artist.jpg"))
-
-				data, err := io.ReadAll(reader)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(string(data)).To(Equal("artist"))
-				reader.Close()
-			})
-		})
-
-		When("no matching files exist anywhere", func() {
-			BeforeEach(func() {
-				artistDir := filepath.Join(tempDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				// Create non-matching files
-				Expect(os.WriteFile(filepath.Join(artistDir, "cover.jpg"), []byte("cover image"), 0600)).To(Succeed())
-
-				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("returns an error", func() {
-				reader, path, err := testFunc()
-				Expect(err).To(HaveOccurred())
-				Expect(reader).To(BeNil())
-				Expect(path).To(BeEmpty())
-				Expect(err.Error()).To(ContainSubstring("no matches for 'artist.*'"))
-				Expect(err.Error()).To(ContainSubstring("parent directories"))
-			})
-		})
-
-		When("directory traversal reaches filesystem root", func() {
-			BeforeEach(func() {
-				// Start from a shallow directory to test root boundary
-				artistDir := filepath.Join(tempDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("handles root boundary gracefully", func() {
-				reader, path, err := testFunc()
-				Expect(err).To(HaveOccurred())
-				Expect(reader).To(BeNil())
-				Expect(path).To(BeEmpty())
-				// Should not panic or cause infinite loop
-			})
-		})
-
-		When("file exists but cannot be opened", func() {
-			BeforeEach(func() {
-				artistDir := filepath.Join(tempDir, "artist")
-				Expect(os.MkdirAll(artistDir, 0755)).To(Succeed())
-
-				// Create a file that cannot be opened (permission denied)
-				restrictedFile := filepath.Join(artistDir, "artist.jpg")
-				Expect(os.WriteFile(restrictedFile, []byte("restricted"), 0600)).To(Succeed())
-
-				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("logs warning and continues searching", func() {
-				// This test depends on the ability to restrict file permissions
-				// For now, we'll just ensure it doesn't panic and returns appropriate error
-				reader, _, err := testFunc()
-				// The file should be readable in test environment, so this will succeed
-				// In a real scenario with permission issues, it would continue searching
-				if err == nil {
-					Expect(reader).ToNot(BeNil())
-					reader.Close()
-				}
-			})
-		})
-
-		When("single album artist scenario (original issue)", func() {
-			BeforeEach(func() {
-				// Simulate the exact folder structure from the issue:
-				// /music/artist/album1/ (single album)
-				// /music/artist/artist.jpg (artist image that should be found)
-				artistDir := filepath.Join(tempDir, "music", "artist")
-				albumDir := filepath.Join(artistDir, "album1")
-				Expect(os.MkdirAll(albumDir, 0755)).To(Succeed())
-
-				// Create artist.jpg in the artist folder (this was not being found before)
-				artistImagePath := filepath.Join(artistDir, "artist.jpg")
-				Expect(os.WriteFile(artistImagePath, []byte("single album artist image"), 0600)).To(Succeed())
-
-				// The fromArtistFolder is called with the artist folder path
-				testFunc = fromArtistFolder(ctx, libFS, tempDir, artistDir, "artist.*")
-			})
-
-			It("finds artist.jpg in artist folder for single album artist", func() {
-				reader, path, err := testFunc()
-				Expect(err).ToNot(HaveOccurred())
-				Expect(reader).ToNot(BeNil())
-				Expect(path).To(ContainSubstring("artist.jpg"))
-				Expect(path).To(ContainSubstring("artist"))
-
-				// Verify the content
-				data, err := io.ReadAll(reader)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(string(data)).To(Equal("single album artist image"))
-				reader.Close()
-			})
-		})
-	})
-
-	Describe("fromArtistUploadedImage", func() {
-		var (
-			tempDir string
-			reader  *artistReader
-		)
-
-		BeforeEach(func() {
-			DeferCleanup(configtest.SetupConfig())
-			tempDir = GinkgoT().TempDir()
-			conf.Server.DataFolder = conf.NewDir(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
-	parentResult *model.Folder
-	getErr       error
-	getCallCount int
-	err          error
-	// hasOtherAudio is returned by HasAudioOutsideFolders (the album-root
-	// check). False means the parent qualifies as an album root.
-	hasOtherAudio bool
-	otherAudioErr error
-}
-
-func (f *fakeFolderRepo) GetAll(...model.QueryOptions) ([]model.Folder, error) {
-	return f.result, f.err
-}
-
-func (f *fakeFolderRepo) HasAudioOutsideFolders(model.Folder, []string) (bool, error) {
-	return f.hasOtherAudio, f.otherAudioErr
-}
-
-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
-}
-
-func (fds *fakeDataStore) Folder(_ context.Context) model.FolderRepository {
-	return fds.folderRepo
-}
-
-func stubCoreAbsolutePath() func() {
-	// Override core.AbsolutePath to return a fixed string during tests.
-	original := core.AbsolutePath
-	core.AbsolutePath = func(_ context.Context, ds model.DataStore, libID int, p string) string {
-		return filepath.FromSlash("/music")
-	}
-	return func() {
-		core.AbsolutePath = original
-	}
-}
diff --git a/core/artwork/reader_mediafile.go b/core/artwork/reader_mediafile.go
deleted file mode 100644
index eac3c5e70..000000000
--- a/core/artwork/reader_mediafile.go
+++ /dev/null
@@ -1,82 +0,0 @@
-package artwork
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"time"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/model"
-)
-
-type mediafileArtworkReader struct {
-	cacheKey
-	a         *artwork
-	mediafile model.MediaFile
-	album     model.Album
-	lib       libraryView
-}
-
-func newMediafileArtworkReader(ctx context.Context, artwork *artwork, artID model.ArtworkID) (*mediafileArtworkReader, error) {
-	mf, err := artwork.ds.MediaFile(ctx).Get(artID.ID)
-	if err != nil {
-		return nil, err
-	}
-	al, err := artwork.ds.Album(ctx).Get(mf.AlbumID)
-	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
-	a.cacheKey.lastUpdate = mf.UpdatedAt
-	if al.UpdatedAt.After(a.cacheKey.lastUpdate) {
-		a.cacheKey.lastUpdate = al.UpdatedAt
-	}
-	if imagesUpdatedAt != nil && imagesUpdatedAt.After(a.cacheKey.lastUpdate) {
-		a.cacheKey.lastUpdate = *imagesUpdatedAt
-	}
-	return a, nil
-}
-
-func (a *mediafileArtworkReader) Key() string {
-	return fmt.Sprintf(
-		"%s.%t",
-		a.cacheKey.Key(),
-		conf.Server.EnableMediaFileCoverArt,
-	)
-}
-func (a *mediafileArtworkReader) LastUpdated() time.Time {
-	return a.lastUpdate
-}
-
-func (a *mediafileArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
-	var ff []sourceFunc
-	if a.mediafile.CoverArtID().Kind == model.KindMediaFileArtwork {
-		ff = []sourceFunc{
-			fromTag(ctx, a.lib.FS, a.mediafile.Path),
-			fromFFmpegTag(ctx, a.a.ffmpeg, a.lib.Abs(a.mediafile.Path)),
-		}
-	}
-	// For multi-disc albums, fall back to disc artwork first; for single-disc albums,
-	// 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...)
-}
diff --git a/core/artwork/reader_playlist.go b/core/artwork/reader_playlist.go
deleted file mode 100644
index 09707843d..000000000
--- a/core/artwork/reader_playlist.go
+++ /dev/null
@@ -1,269 +0,0 @@
-package artwork
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"image"
-	"image/draw"
-	"image/png"
-	"io"
-	"net/url"
-	"os"
-	"path/filepath"
-	"strings"
-	"time"
-
-	"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 {
-	cacheKey
-	a  *artwork
-	pl model.Playlist
-}
-
-const tileSize = 600
-
-func newPlaylistArtworkReader(ctx context.Context, artwork *artwork, artID model.ArtworkID) (*playlistArtworkReader, error) {
-	pl, err := artwork.ds.Playlist(ctx).Get(artID.ID)
-	if err != nil {
-		return nil, err
-	}
-	a := &playlistArtworkReader{
-		a:  artwork,
-		pl: *pl,
-	}
-	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
-}
-
-func (a *playlistArtworkReader) LastUpdated() time.Time {
-	return a.lastUpdate
-}
-
-func (a *playlistArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
-	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)()
-	}
-}
-
-// 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 {
-	return func() (io.ReadCloser, string, error) {
-		tiles, err := a.loadTiles(ctx)
-		if err != nil {
-			return nil, "", err
-		}
-		r, err := a.createTiledImage(ctx, tiles)
-		return r, "", err
-	}
-}
-
-func toAlbumArtworkIDs(albumIDs []string) []model.ArtworkID {
-	return slice.Map(albumIDs, func(id string) model.ArtworkID {
-		al := model.Album{ID: id}
-		return al.CoverArtID()
-	})
-}
-
-func (a *playlistArtworkReader) loadTiles(ctx context.Context) ([]image.Image, error) {
-	tracksRepo := a.a.ds.Playlist(ctx).Tracks(a.pl.ID, false)
-	albumIds, err := tracksRepo.GetAlbumIDs(model.QueryOptions{Max: 4, Sort: "random()"})
-	if err != nil {
-		log.Error(ctx, "Error getting album IDs for playlist", "id", a.pl.ID, "name", a.pl.Name, err)
-		return nil, err
-	}
-	ids := toAlbumArtworkIDs(albumIds)
-
-	var tiles []image.Image
-	for _, id := range ids {
-		r, _, err := fromAlbum(ctx, a.a, id)()
-		if err == nil {
-			tile, err := a.createTile(ctx, r)
-			if err == nil {
-				tiles = append(tiles, tile)
-			}
-			_ = r.Close()
-		}
-		if len(tiles) == 4 {
-			break
-		}
-	}
-	switch len(tiles) {
-	case 0:
-		return nil, errors.New("could not find any eligible cover")
-	case 2:
-		tiles = append(tiles, tiles[1], tiles[0])
-	case 3:
-		tiles = append(tiles, tiles[0])
-	}
-	return tiles, nil
-}
-
-func (a *playlistArtworkReader) createTile(_ context.Context, r io.ReadCloser) (image.Image, error) {
-	img, _, err := image.Decode(r)
-	if err != nil {
-		return nil, err
-	}
-	return fillCenter(img, tileSize/2, tileSize/2), nil
-}
-
-func (a *playlistArtworkReader) createTiledImage(_ context.Context, tiles []image.Image) (io.ReadCloser, error) {
-	buf := new(bytes.Buffer)
-	var rgba draw.Image
-	var err error
-	if len(tiles) == 4 {
-		rgba = image.NewRGBA(image.Rectangle{Max: image.Point{X: tileSize - 1, Y: tileSize - 1}})
-		draw.Draw(rgba, rect(0), tiles[0], image.Point{}, draw.Src)
-		draw.Draw(rgba, rect(1), tiles[1], image.Point{}, draw.Src)
-		draw.Draw(rgba, rect(2), tiles[2], image.Point{}, draw.Src)
-		draw.Draw(rgba, rect(3), tiles[3], image.Point{}, draw.Src)
-		err = png.Encode(buf, rgba)
-	} else {
-		err = png.Encode(buf, tiles[0])
-	}
-	if err != nil {
-		return nil, err
-	}
-	return io.NopCloser(buf), nil
-}
-
-func rect(pos int) image.Rectangle {
-	r := image.Rectangle{}
-	switch pos {
-	case 1:
-		r.Min.X = tileSize / 2
-	case 2:
-		r.Min.Y = tileSize / 2
-	case 3:
-		r.Min.X = tileSize / 2
-		r.Min.Y = tileSize / 2
-	}
-	r.Max.X = r.Min.X + tileSize/2
-	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
-}
diff --git a/core/artwork/reader_radio.go b/core/artwork/reader_radio.go
deleted file mode 100644
index 22db6e302..000000000
--- a/core/artwork/reader_radio.go
+++ /dev/null
@@ -1,40 +0,0 @@
-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())
-}
diff --git a/core/artwork/reader_radio_test.go b/core/artwork/reader_radio_test.go
deleted file mode 100644
index 37ce1d827..000000000
--- a/core/artwork/reader_radio_test.go
+++ /dev/null
@@ -1,84 +0,0 @@
-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 = conf.NewDir(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())
-			})
-		})
-	})
-})
diff --git a/core/artwork/reader_resized.go b/core/artwork/reader_resized.go
deleted file mode 100644
index cd16cbada..000000000
--- a/core/artwork/reader_resized.go
+++ /dev/null
@@ -1,209 +0,0 @@
-package artwork
-
-import (
-	"bytes"
-	"context"
-	"fmt"
-	"image"
-	"image/draw"
-	"image/jpeg"
-	"image/png"
-	"io"
-	"sync"
-	"time"
-
-	"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() {
-		// gen2brain/webp selects native (purego/libwebp) vs WASM in its own
-		// package init() and exposes the result only via webp.Dynamic(); there is
-		// no runtime way to switch back. On 32-bit ARM/x86 the purego callback path
-		// crashes (issue #5597), so those builds must be compiled with the
-		// "nodynamic" tag (see Dockerfile), which makes webp.Dynamic() report an
-		// error here and forces the safe WASM path.
-		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
-	lastUpdate time.Time
-	size       int
-	square     bool
-	a          *artwork
-}
-
-func resizedFromOriginal(ctx context.Context, a *artwork, artID model.ArtworkID, size int, square bool) (*resizedArtworkReader, error) {
-	r := &resizedArtworkReader{a: a}
-	r.artID = artID
-	r.size = size
-	r.square = square
-
-	// Get lastUpdated and cacheKey from original artwork
-	original, err := a.getArtworkReader(ctx, artID, 0, false)
-	if err != nil {
-		return nil, err
-	}
-	r.cacheKey = original.Key()
-	r.lastUpdate = original.LastUpdated()
-	return r, nil
-}
-
-func (a *resizedArtworkReader) Key() string {
-	baseKey := fmt.Sprintf("%s.%d", a.cacheKey, a.size)
-	if a.square {
-		return baseKey + ".square"
-	}
-	return fmt.Sprintf("%s.%d", baseKey, conf.Server.CoverArtQuality)
-}
-
-func (a *resizedArtworkReader) LastUpdated() time.Time {
-	return a.lastUpdate
-}
-
-func (a *resizedArtworkReader) Reader(ctx context.Context) (io.ReadCloser, string, error) {
-	// Get artwork in original size, possibly from cache
-	orig, _, err := a.a.Get(ctx, a.artID, 0, false)
-	if err != nil {
-		return nil, "", err
-	}
-	defer orig.Close()
-
-	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 {
-		log.Trace(ctx, "Resizing artwork", "artID", a.artID, "original", origSize, "resized", a.size, "square", a.square)
-	}
-	if err != nil {
-		log.Warn(ctx, "Could not resize image. Will return image as is", "artID", a.artID, "size", a.size, "square", a.square, err)
-	}
-	if err != nil || resized == nil {
-		// if we couldn't resize the image, return the original
-		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 (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)
-}
-
-// toFastScaleType converts images whose concrete type has no optimized scaler
-// in x/image/draw (e.g. *image.NYCbCrA from WebP, *image.Paletted from indexed
-// PNGs) into *image.RGBA, which has a fast path. Without this, CatmullRom.Scale
-// falls back to a generic per-pixel At()/RGBA() loop that is several times
-// slower. Fast-path types are returned unchanged.
-func toFastScaleType(img image.Image) image.Image {
-	switch img.(type) {
-	case *image.RGBA, *image.NRGBA, *image.Gray, *image.YCbCr:
-		return img
-	default:
-		rgba := image.NewRGBA(img.Bounds())
-		draw.Draw(rgba, rgba.Bounds(), img, img.Bounds().Min, draw.Src)
-		return rgba
-	}
-}
-
-func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, error) {
-	original, format, err := image.Decode(bytes.NewReader(data))
-	if err != nil {
-		return nil, 0, err
-	}
-
-	bounds := original.Bounds()
-	originalSize := max(bounds.Max.X, bounds.Max.Y)
-
-	// Clamp size to original dimensions - upscaling wastes resources and adds no information
-	if size > originalSize {
-		size = originalSize
-	}
-
-	if originalSize <= size && !square {
-		return nil, originalSize, nil
-	}
-
-	// 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)
-
-	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 {
-		// Tight-fit canvas
-		dst = image.NewNRGBA(image.Rect(0, 0, dstW, dstH))
-		dstRect = dst.Bounds()
-	}
-	original = toFastScaleType(original)
-	xdraw.CatmullRom.Scale(dst, dstRect, original, bounds, draw.Src, nil)
-
-	buf := bufPool.Get().(*bytes.Buffer)
-	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
-}
diff --git a/core/artwork/reader_resized_test.go b/core/artwork/reader_resized_test.go
deleted file mode 100644
index 7c14f5e44..000000000
--- a/core/artwork/reader_resized_test.go
+++ /dev/null
@@ -1,176 +0,0 @@
-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
-}
diff --git a/core/artwork/resize.go b/core/artwork/resize.go
new file mode 100644
index 000000000..9536c3bb1
--- /dev/null
+++ b/core/artwork/resize.go
@@ -0,0 +1,144 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"image"
+	"image/draw"
+	"image/jpeg"
+	"image/png"
+	"io"
+	"sync"
+	"time"
+
+	"github.com/gen2brain/webp"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/ffmpeg"
+	"github.com/navidrome/navidrome/log"
+	xdraw "golang.org/x/image/draw"
+)
+
+func init() {
+	conf.AddHook(func() {
+		// gen2brain/webp picks native vs WASM in its own init(), with no way to switch at
+		// runtime: 32-bit builds need the "nodynamic" tag (see Dockerfile) to force WASM.
+		if err := webp.Dynamic(); err != nil {
+			log.Debug("Artwork: Using WASM WebP encoder/decoder", "reason", err)
+		} else {
+			log.Debug("Artwork: Using native libwebp for WebP encoding/decoding")
+		}
+	})
+}
+
+var bufPool = sync.Pool{
+	New: func() any {
+		return new(bytes.Buffer)
+	},
+}
+
+// resizeImageData resizes raw image bytes to fit size, preserving animation where
+// possible. A nil reader means the image was already within bounds (no resize needed).
+func resizeImageData(ctx context.Context, ffm ffmpeg.FFmpeg, data []byte, size int, square bool) (io.Reader, int, error) {
+	start := time.Now()
+	defer func() {
+		log.Trace(ctx, "Artwork: Resized image", "bytes", len(data), "size", size, "square", square,
+			"elapsed", time.Since(start))
+	}()
+	if isAnimatedGIF(data) {
+		if ffm.IsAvailable() {
+			// Animated GIF: convert to animated WebP via ffmpeg (with optional resize)
+			r, err := ffm.ConvertAnimatedImage(ctx, bytes.NewReader(data), size, conf.Server.CoverArtQuality)
+			if err == nil {
+				return r, 0, nil
+			}
+			log.Warn(ctx, "Artwork: 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, size, square)
+}
+
+// toFastScaleType converts types x/image/draw has no optimized scaler for (e.g. *image.NYCbCrA,
+// *image.Paletted) to *image.RGBA, avoiding CatmullRom.Scale's generic per-pixel fallback.
+func toFastScaleType(img image.Image) image.Image {
+	switch img.(type) {
+	case *image.RGBA, *image.NRGBA, *image.Gray, *image.YCbCr:
+		return img
+	default:
+		rgba := image.NewRGBA(img.Bounds())
+		draw.Draw(rgba, rgba.Bounds(), img, img.Bounds().Min, draw.Src)
+		return rgba
+	}
+}
+
+func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, error) {
+	original, format, err := image.Decode(bytes.NewReader(data))
+	if err != nil {
+		return nil, 0, err
+	}
+
+	bounds := original.Bounds()
+	originalSize := max(bounds.Max.X, bounds.Max.Y)
+
+	// Clamp size to original dimensions - upscaling wastes resources and adds no information
+	if size > originalSize {
+		size = originalSize
+	}
+
+	if originalSize <= size && !square {
+		return nil, originalSize, nil
+	}
+
+	// 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)
+
+	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 {
+		// Tight-fit canvas
+		dst = image.NewNRGBA(image.Rect(0, 0, dstW, dstH))
+		dstRect = dst.Bounds()
+	}
+	original = toFastScaleType(original)
+	xdraw.CatmullRom.Scale(dst, dstRect, original, bounds, draw.Src, nil)
+
+	buf := bufPool.Get().(*bytes.Buffer)
+	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 := bytes.Clone(buf.Bytes())
+	bufPool.Put(buf)
+	return bytes.NewReader(encoded), originalSize, nil
+}
+
+// formatQualityTag folds the encoder config (WebP toggle + quality) into a cache-key
+// fragment, so flipping either setting invalidates previously-encoded sized artwork.
+func formatQualityTag() string {
+	if conf.Server.EnableWebPEncoding {
+		return fmt.Sprintf("webp%d", conf.Server.CoverArtQuality)
+	}
+	return fmt.Sprintf("q%d", conf.Server.CoverArtQuality)
+}
diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
new file mode 100644
index 000000000..11711469d
--- /dev/null
+++ b/core/artwork/resolve.go
@@ -0,0 +1,452 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"image"
+	"io"
+	"io/fs"
+	"net/url"
+	"os"
+	"strings"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/ffmpeg"
+	"github.com/navidrome/navidrome/model"
+)
+
+// resolution is one attempted acquisition outcome for an entity.
+type resolution struct {
+	reader     io.ReadCloser // nil when no source yielded an image
+	source     string        // model.ItemArtwork.Source value: "folder", "embedded", "external", "upload", "generated"
+	sourcePath string        // backing library/upload file (folder/upload: the image; embedded: the audio file); "" otherwise
+	refMtime   int64         // sourcePath mtime (unix-nanoseconds) at resolution; 0 when no sourcePath
+	// external source errored/timed out. With no reader it forces failed (never absent);
+	// on a hit a higher-priority external step failed—serve this, but retry later.
+	extError bool
+	// a local source that should have been readable wasn't. With no reader it forces failed,
+	// so a transient I/O fault never records absent.
+	localError bool
+}
+
+// chainState carries what a priority walk has seen so far. A hit takes extErr with it so a
+// transient external failure still retries; localErr is dropped, as the scanner re-lists changes.
+type chainState struct{ extErr, localErr bool }
+
+// try stamps the accumulated external failure onto a hit, and records the miss otherwise.
+func (c *chainState) try(res resolution, ok bool) (resolution, bool) {
+	if ok {
+		res.extError = c.extErr
+		return res, true
+	}
+	c.localErr = c.localErr || res.localError
+	return resolution{}, false
+}
+
+// exhausted is the outcome when no source in the chain yielded an image.
+func (c *chainState) exhausted() resolution {
+	return resolution{extError: c.extErr, localError: c.localErr}
+}
+
+// externalSource holds the agents to ask and the rate limiter/circuit breaker to ask them through.
+type externalSource struct {
+	agents *agents.Agents
+	gate   gateFunc
+}
+
+// resolver walks a kind's priority chain and returns the first hit; a nil ext means local-only.
+type resolver struct {
+	ds     model.DataStore
+	ffmpeg ffmpeg.FFmpeg
+	ext    *externalSource
+}
+
+func newResolver(ds model.DataStore, ag *agents.Agents, ffm ffmpeg.FFmpeg, gate gateFunc) *resolver {
+	if gate == nil {
+		gate = passthroughGate
+	}
+	return &resolver{ds: ds, ffmpeg: ffm, ext: &externalSource{agents: ag, gate: gate}}
+}
+
+// newLocalResolver builds a resolver that can neither reach the network nor sample album art
+// for the worker-built grid.
+func newLocalResolver(ds model.DataStore, ffm ffmpeg.FFmpeg) *resolver {
+	return &resolver{ds: ds, ffmpeg: ffm}
+}
+
+func (r *resolver) resolve(ctx context.Context, item model.ArtworkQueueItem) (resolution, error) {
+	kind, _ := model.ParseKind(item.ItemKind)
+	switch kind {
+	case model.KindAlbumArtwork:
+		return r.resolveAlbum(ctx, item.ItemID)
+	case model.KindArtistArtwork:
+		return r.resolveArtist(ctx, item.ItemID)
+	case model.KindPlaylistArtwork:
+		return r.resolvePlaylist(ctx, item.ItemID)
+	case model.KindRadioArtwork:
+		return r.resolveRadio(ctx, item.ItemID)
+	case model.KindMediaFileArtwork:
+		return r.resolveMediaFile(ctx, item.ItemID)
+	default:
+		return resolution{}, fmt.Errorf("artwork: kind %q is not resolvable by the worker", item.ItemKind)
+	}
+}
+
+// fetchExternalAlbum and fetchExternalArtist are the only places resolution touches the network,
+// so a local-only resolver is stopped here rather than at each point in the chain walk.
+func (r *resolver) fetchExternalAlbum(ctx context.Context, al model.Album) (io.ReadCloser, string, bool) {
+	if r.ext == nil {
+		return nil, "", false
+	}
+	return fetchAlbumImage(ctx, r.ext.agents, r.ext.gate, al)
+}
+
+func (r *resolver) fetchExternalArtist(ctx context.Context, ar model.Artist) (io.ReadCloser, string, bool) {
+	if r.ext == nil {
+		return nil, "", false
+	}
+	return fetchArtistImage(ctx, r.ext.agents, r.ext.gate, ar)
+}
+
+// resolveAlbum walks conf.Server.CoverArtPriority over the folder, embedded and external sources.
+func (r *resolver) resolveAlbum(ctx context.Context, albumID string) (resolution, error) {
+	al, err := r.ds.Album(ctx).Get(albumID)
+	if err != nil {
+		return resolution{}, err
+	}
+	_, imgFiles, _, err := loadAlbumFoldersPaths(ctx, r.ds, *al)
+	if err != nil {
+		return resolution{}, err
+	}
+	lib, err := loadLibraryView(ctx, r.ds, al.LibraryID)
+	if err != nil {
+		return resolution{}, err
+	}
+
+	var chain chainState
+	for pattern := range strings.SplitSeq(strings.ToLower(conf.Server.CoverArtPriority), ",") {
+		pattern = strings.TrimSpace(pattern)
+		switch {
+		case pattern == "embedded":
+			if res, ok := chain.try(resolveEmbedded(ctx, lib, r.ffmpeg, al.EmbedArtPath)); ok {
+				return res, nil
+			}
+		case pattern == "external":
+			if rd, name, isErr := r.fetchExternalAlbum(ctx, *al); rd != nil {
+				return resolution{reader: rd, source: "external:" + name}, nil
+			} else if isErr {
+				chain.extErr = true
+			}
+		case len(imgFiles) > 0:
+			if res, ok := chain.try(resolveFolderFile(ctx, lib, imgFiles, pattern)); ok {
+				return res, nil
+			}
+		}
+	}
+	return chain.exhausted(), nil
+}
+
+// resolveArtist tries the uploaded image first, then walks conf.Server.ArtistArtPriority.
+func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resolution, error) {
+	ar, err := r.ds.Artist(ctx).Get(artistID)
+	if err != nil {
+		return resolution{}, err
+	}
+	upload, ok := resolveLocalFile(ar.UploadedImagePath(), "upload")
+	if ok {
+		return upload, nil
+	}
+	if upload.localError {
+		// The upload outranks every other source; falling through would persist a lower-priority
+		// image as if the upload were gone.
+		return upload, nil
+	}
+
+	// Only consider albums where the artist is the sole album artist.
+	als, err := r.ds.Album(ctx).GetAll(model.QueryOptions{
+		Filters: squirrel.And{
+			squirrel.Eq{"album_artist_id": artistID},
+			squirrel.Eq{"json_array_length(participants, '$.albumartist')": 1},
+		},
+	})
+	if err != nil {
+		return resolution{}, err
+	}
+	albumPaths, imgFiles, _, err := loadArtistAlbumRoots(ctx, r.ds, als)
+	if err != nil {
+		return resolution{}, err
+	}
+	artistFolder, _, err := loadArtistFolder(ctx, r.ds, als, albumPaths)
+	if err != nil {
+		return resolution{}, err
+	}
+	var lib libraryView
+	if len(als) > 0 {
+		lib, err = loadLibraryView(ctx, r.ds, als[0].LibraryID)
+		if err != nil {
+			return resolution{}, err
+		}
+	}
+
+	var chain chainState
+	for pattern := range strings.SplitSeq(strings.ToLower(conf.Server.ArtistArtPriority), ",") {
+		pattern = strings.TrimSpace(pattern)
+		switch {
+		case pattern == "external":
+			if rd, name, isErr := r.fetchExternalArtist(ctx, *ar); rd != nil {
+				return resolution{reader: rd, source: "external:" + name}, nil
+			} else if isErr {
+				chain.extErr = true
+			}
+		case pattern == "image-folder":
+			if res, ok := chain.try(resolveArtistImageFolder(ar)); ok {
+				return res, nil
+			}
+		case strings.HasPrefix(pattern, "album/"):
+			if lib.FS == nil {
+				continue
+			}
+			if res, ok := chain.try(resolveFolderFile(ctx, lib, imgFiles, strings.TrimPrefix(pattern, "album/"))); ok {
+				return res, nil
+			}
+		default:
+			if lib.FS == nil || artistFolder == "" {
+				continue
+			}
+			if res, ok := chain.try(resolveArtistFolderPattern(ctx, lib, artistFolder, pattern)); ok {
+				return res, nil
+			}
+		}
+	}
+	return chain.exhausted(), nil
+}
+
+// resolvePlaylist tries the uploaded image, the sidecar and ExternalImageURL, then a generated grid.
+func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (resolution, error) {
+	pl, err := r.ds.Playlist(ctx).Get(playlistID)
+	if err != nil {
+		return resolution{}, err
+	}
+
+	var extErr bool
+	for _, src := range []struct{ path, source string }{
+		{pl.UploadedImagePath(), "upload"},
+		{findPlaylistSidecarPath(ctx, pl.Path), "folder"},
+	} {
+		res, ok := resolveLocalFile(src.path, src.source)
+		if ok {
+			return res, nil
+		}
+		if res.localError {
+			// These outrank the generated grid; falling through would replace them with it.
+			return res, nil
+		}
+	}
+	// A local ExternalImageURL is file-backed and served in place; only http(s) needs the gated fetch.
+	localImg, remoteImg := classifyPlaylistImage(pl.ExternalImageURL)
+	if localImg != "" {
+		res, ok := resolveLocalFile(localImg, "folder")
+		if ok {
+			return res, nil
+		}
+		if res.localError {
+			return res, nil
+		}
+	}
+	if r.ext == nil {
+		// The remote fetch and the generated grid are worker-only; a request must do neither.
+		return resolution{}, nil
+	}
+	if remoteImg != nil && conf.Server.EnableM3UExternalAlbumArt {
+		sf := func() (io.ReadCloser, string, error) { return fromURL(ctx, remoteImg) }
+		if res, ok, isErr := resolveExternalStep(r.ext.gate, "m3u", sf); ok {
+			return res, nil
+		} else if isErr {
+			extErr = true
+		}
+	}
+
+	albumIDs, err := r.ds.Playlist(ctx).Tracks(pl.ID, false).GetAlbumIDs(model.QueryOptions{Max: 4, Sort: "random()"})
+	if err != nil {
+		return resolution{}, err
+	}
+
+	var tiles []image.Image
+	var tileErr error // first internal (non-external) tile failure, e.g. album deleted mid-flight
+	for _, albumID := range albumIDs {
+		res, err := r.resolveAlbum(ctx, albumID)
+		if err != nil {
+			if tileErr == nil {
+				tileErr = err
+			}
+			continue
+		}
+		if res.extError {
+			extErr = true
+		}
+		if res.reader == nil {
+			continue
+		}
+		tile, decErr := decodeTile(res.reader)
+		res.reader.Close()
+		if decErr == nil {
+			tiles = append(tiles, tile)
+		}
+		if len(tiles) == 4 {
+			break
+		}
+	}
+	if len(tiles) == 0 {
+		// A tile-level failure must never resolve as a clean absent.
+		if tileErr != nil {
+			return resolution{}, fmt.Errorf("resolvePlaylist: sampled album art failed: %w", tileErr)
+		}
+		return resolution{extError: extErr}, nil
+	}
+	// Grow to 4 tiles by repeating what we have.
+	switch len(tiles) {
+	case 2:
+		tiles = append(tiles, tiles[1], tiles[0])
+	case 3:
+		tiles = append(tiles, tiles[0])
+	}
+	grid, err := assembleTiles(tiles)
+	if err != nil {
+		return resolution{extError: extErr}, nil //nolint:nilerr // encode failure is a soft "no image", not a resolution error
+	}
+	return resolution{reader: grid, source: "generated", extError: extErr}, nil
+}
+
+// resolveRadio serves only an uploaded image; there is no fallback.
+func (r *resolver) resolveRadio(ctx context.Context, radioID string) (resolution, error) {
+	radio, err := r.ds.Radio(ctx).Get(radioID)
+	if err != nil {
+		return resolution{}, err
+	}
+	res, _ := resolveLocalFile(radio.UploadedImagePath(), "upload")
+	return res, nil
+}
+
+// resolveMediaFile resolves a track's own embedded art only, so disabled or missing cover art
+// is a definitive absent.
+func (r *resolver) resolveMediaFile(ctx context.Context, id string) (resolution, error) {
+	mf, err := r.ds.MediaFile(ctx).Get(id)
+	if err != nil {
+		return resolution{}, err
+	}
+	if !conf.Server.EnableMediaFileCoverArt || !mf.HasCoverArt {
+		return resolution{}, nil
+	}
+	lib, err := loadLibraryView(ctx, r.ds, mf.LibraryID)
+	if err != nil {
+		return resolution{}, err
+	}
+	res, _ := resolveEmbedded(ctx, lib, r.ffmpeg, mf.Path)
+	return res, nil
+}
+
+// resolveExternalStep runs a single external sourceFunc through the named gate. extErr excludes
+// a not-found, which is a definitive "no" rather than a failure.
+func resolveExternalStep(gate gateFunc, name string, sf sourceFunc) (res resolution, ok bool, extErr bool) {
+	r, path, err := gate(name, sf)
+	if r != nil {
+		return resolution{reader: r, source: "external", sourcePath: path}, true, false
+	}
+	return resolution{}, false, err != nil && !errors.Is(err, model.ErrNotFound)
+}
+
+// classifyPlaylistImage splits a playlist ExternalImageURL into a local filesystem path or a
+// remote http(s) URL; at most one is set.
+func classifyPlaylistImage(imageURL string) (localPath string, remote *url.URL) {
+	if imageURL == "" {
+		return "", nil
+	}
+	u, err := url.Parse(imageURL)
+	if err != nil {
+		return imageURL, nil // unparseable → treat as a local path
+	}
+	switch u.Scheme {
+	case "http", "https":
+		return "", u
+	case "file":
+		return u.Path, nil
+	default:
+		return imageURL, nil
+	}
+}
+
+func resolveEmbedded(ctx context.Context, lib libraryView, ffm ffmpeg.FFmpeg, embedRel string) (resolution, bool) {
+	if embedRel == "" {
+		return resolution{}, false
+	}
+	abs := lib.Abs(embedRel)
+	var unreadable bool
+	for _, sf := range []sourceFunc{fromTag(ctx, lib.FS, embedRel), fromFFmpegTag(ctx, ffm, abs)} {
+		r, _, err := sf()
+		if r != nil {
+			return resolution{reader: r, source: "embedded", sourcePath: abs, refMtime: mtimeViaFS(lib.FS, embedRel)}, true
+		}
+		unreadable = unreadable || errors.Is(err, errSourceUnreadable)
+	}
+	return resolution{localError: unreadable}, false
+}
+
+func resolveFolderFile(ctx context.Context, lib libraryView, imgFiles []string, pattern string) (resolution, bool) {
+	r, path, err := fromExternalFile(ctx, lib.FS, imgFiles, pattern)()
+	if r == nil {
+		return resolution{localError: errors.Is(err, errSourceUnreadable)}, false
+	}
+	return resolution{reader: r, source: "folder", sourcePath: lib.Abs(path), refMtime: mtimeViaFS(lib.FS, path)}, true
+}
+
+func resolveArtistImageFolder(ar *model.Artist) (resolution, bool) {
+	folder := conf.Server.ArtistImageFolder
+	if folder == "" {
+		return resolution{}, false
+	}
+	return resolveLocalFile(findImageInArtistFolder(folder, ar.MbzArtistID, ar.Name), "folder")
+}
+
+func resolveArtistFolderPattern(ctx context.Context, lib libraryView, artistFolder, pattern string) (resolution, bool) {
+	r, path, err := fromArtistFolder(ctx, lib.FS, lib.absRoot, artistFolder, pattern)()
+	if r == nil {
+		return resolution{localError: errors.Is(err, errSourceUnreadable)}, false
+	}
+	return resolution{reader: r, source: "folder", sourcePath: path, refMtime: mtimeOf(path)}, true
+}
+
+// resolveLocalFile opens an absolute path directly. A missing path is "no source"; any other
+// open failure says nothing about whether the image exists.
+func resolveLocalFile(path, source string) (resolution, bool) {
+	if path == "" {
+		return resolution{}, false
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		return resolution{localError: !errors.Is(err, fs.ErrNotExist)}, false
+	}
+	return resolution{reader: f, source: source, sourcePath: path, refMtime: mtimeOf(path)}, true
+}
+
+func mtimeOf(path string) int64 {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0
+	}
+	return info.ModTime().UnixNano()
+}
+
+// mtimeViaFS stats through the library FS, since library roots in tests may not be real OS paths.
+func mtimeViaFS(fsys fs.FS, name string) int64 {
+	if fsys == nil || name == "" {
+		return 0
+	}
+	info, err := fs.Stat(fsys, name)
+	if err != nil {
+		return 0
+	}
+	return info.ModTime().UnixNano()
+}
diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.go
new file mode 100644
index 000000000..fc1a6a3ff
--- /dev/null
+++ b/core/artwork/resolve_test.go
@@ -0,0 +1,632 @@
+package artwork
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"image"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"sync/atomic"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("resolveItem", func() {
+	var (
+		ctx        context.Context
+		ds         *tests.MockDataStore
+		folderRepo *fakeFolderRepo
+		libRepo    *tests.MockLibraryRepo
+		ffm        *tests.MockFFmpeg
+		ag         *agents.Agents
+		repoRoot   string
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		ctx = context.Background()
+		var err error
+		repoRoot, err = os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+
+		folderRepo = &fakeFolderRepo{}
+		libRepo = &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		ffm = tests.NewMockFFmpeg("")
+		ag = agents.GetAgents(&tests.MockDataStore{}, nil)
+		ds = &tests.MockDataStore{
+			MockedFolder:  folderRepo,
+			MockedLibrary: libRepo,
+		}
+	})
+
+	Describe("kind dispatch", func() {
+		It("returns an error for kinds the worker never enqueues", func() {
+			_, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "zz", ItemID: "x"})
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	Describe("media file", func() {
+		BeforeEach(func() {
+			conf.Server.EnableMediaFileCoverArt = true
+			ds.MockedMediaFile = tests.CreateMockMediaFileRepo()
+		})
+
+		It("resolves embedded art from the track file", func() {
+			ds.MockedMediaFile.(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+				{ID: "mf1", LibraryID: 0, Path: "tests/fixtures/artist/an-album/test.mp3", HasCoverArt: true},
+			})
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mf1"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("embedded"))
+			Expect(filepath.ToSlash(res.sourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/test.mp3"))
+			Expect(res.refMtime).To(BeNumerically(">", 0))
+			Expect(res.extError).To(BeFalse())
+		})
+
+		It("resolves absent when the track has no cover art", func() {
+			ds.MockedMediaFile.(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+				{ID: "mf2", LibraryID: 0, Path: "tests/fixtures/artist/an-album/test.mp3", HasCoverArt: false},
+			})
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mf2"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeFalse())
+		})
+
+		It("resolves absent when media file cover art is disabled", func() {
+			conf.Server.EnableMediaFileCoverArt = false
+			ds.MockedMediaFile.(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+				{ID: "mf3", LibraryID: 0, Path: "tests/fixtures/artist/an-album/test.mp3", HasCoverArt: true},
+			})
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mf3"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+		})
+
+		It("returns the error when the track is not in the DB", func() {
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "missing"})
+			Expect(err).To(MatchError(model.ErrNotFound))
+			Expect(res.reader).To(BeNil())
+		})
+	})
+
+	Describe("album", func() {
+		BeforeEach(func() {
+			conf.Server.CoverArtPriority = "cover.jpg, embedded"
+			ds.MockedAlbum = tests.CreateMockAlbumRepo()
+		})
+
+		It("resolves folder art from the library FS", func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("folder"))
+			Expect(filepath.ToSlash(res.sourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/cover.jpg"))
+			Expect(res.refMtime).To(BeNumerically(">", 0))
+			Expect(res.extError).To(BeFalse())
+		})
+
+		It("falls back to embedded art when no folder image matches", func() {
+			folderRepo.result = nil
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al2", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},
+			})
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("embedded"))
+			Expect(filepath.ToSlash(res.sourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/test.mp3"))
+			Expect(res.refMtime).To(BeNumerically(">", 0))
+		})
+
+		It("sets extError when the external source errors without being not-found", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al3", Name: "Album"},
+			})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeTrue())
+		})
+
+		It("does not set extError when the external source reports not-found", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al4", Name: "Album"},
+			})
+			// no image agents enabled -> the external step is a definitive not-found
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeFalse())
+		})
+
+		It("carries extError onto a fallback folder hit after a transient external failure", func() {
+			conf.Server.CoverArtPriority = "external, cover.jpg"
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al6", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al6"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("folder"))
+			Expect(res.extError).To(BeTrue())
+		})
+
+		It("does not carry extError onto a fallback folder hit after a definitive external not-found", func() {
+			conf.Server.CoverArtPriority = "external, cover.jpg"
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al7", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+			// no image agents enabled -> the external step is a definitive not-found
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al7"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("folder"))
+			Expect(res.extError).To(BeFalse())
+		})
+
+		It("routes the external step through the injected gate, keyed by agent name", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al5", Name: "Album"},
+			})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("boom")})
+			var gatedNames []string
+			gate := func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+				gatedNames = append(gatedNames, name)
+				return f()
+			}
+
+			res, err := newResolver(ds, ag, ffm, gate).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al5"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.extError).To(BeTrue())
+			Expect(gatedNames).To(Equal([]string{"failAgent"}))
+		})
+	})
+
+	Describe("artist", func() {
+		It("resolves the uploaded image before any priority chain lookup", func() {
+			tmpDir := GinkgoT().TempDir()
+			conf.Server.DataFolder = conf.NewDir(tmpDir)
+			Expect(os.MkdirAll(filepath.Join(tmpDir, "artwork", "artist"), 0755)).To(Succeed())
+			imgPath := filepath.Join(tmpDir, "artwork", "artist", "ar1_test.jpg")
+			Expect(os.WriteFile(imgPath, []byte("uploaded artist image"), 0600)).To(Succeed())
+
+			artistRepo := tests.CreateMockArtistRepo()
+			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist", UploadedImage: "ar1_test.jpg"}})
+			ds.MockedArtist = artistRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar1"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("upload"))
+			Expect(res.sourcePath).To(Equal(imgPath))
+		})
+
+		It("falls through to the ArtistArtPriority chain when there is no upload", func() {
+			conf.Server.ArtistArtPriority = "album/artist.*"
+			folderRepo.result = []model.Folder{{
+				LibraryPath: testFileLibPath(repoRoot),
+				Path:        "tests/fixtures/artist/an-album",
+				ImageFiles:  []string{"artist.png"},
+			}}
+			artistRepo := tests.CreateMockArtistRepo()
+			artistRepo.SetData(model.Artists{{ID: "ar2", Name: "Artist"}})
+			ds.MockedArtist = artistRepo
+			ds.MockedAlbum = tests.CreateMockAlbumRepo()
+			ds.MockedAlbum.(*tests.MockAlbumRepo).All = model.Albums{
+				{ID: "al9", Name: "Album", LibraryID: 0, FolderIDs: []string{"f1"}},
+			}
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar2"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("folder"))
+			Expect(filepath.ToSlash(res.sourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/artist.png"))
+		})
+
+		It("sets extError when the external source errors without being not-found", func() {
+			conf.Server.ArtistArtPriority = "external"
+			artistRepo := tests.CreateMockArtistRepo()
+			artistRepo.SetData(model.Artists{{ID: "ar3", Name: "Artist"}})
+			ds.MockedArtist = artistRepo
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar3"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeTrue())
+		})
+
+		It("does not set extError when the external source reports not-found", func() {
+			conf.Server.ArtistArtPriority = "external"
+			artistRepo := tests.CreateMockArtistRepo()
+			artistRepo.SetData(model.Artists{{ID: "ar4", Name: "Artist"}})
+			ds.MockedArtist = artistRepo
+			// no image agents enabled -> the external step is a definitive not-found
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar4"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeFalse())
+		})
+
+		It("routes the external step through the injected gate, keyed by agent name", func() {
+			conf.Server.ArtistArtPriority = "external"
+			artistRepo := tests.CreateMockArtistRepo()
+			artistRepo.SetData(model.Artists{{ID: "ar5", Name: "Artist"}})
+			ds.MockedArtist = artistRepo
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("boom")})
+			var gatedNames []string
+			gate := func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+				gatedNames = append(gatedNames, name)
+				return f()
+			}
+
+			res, err := newResolver(ds, ag, ffm, gate).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar5"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.extError).To(BeTrue())
+			Expect(gatedNames).To(Equal([]string{"failAgent"}))
+		})
+	})
+
+	Describe("radio", func() {
+		It("yields an empty resolution when there is no uploaded image", func() {
+			tmpDir := GinkgoT().TempDir()
+			conf.Server.DataFolder = conf.NewDir(tmpDir)
+
+			radioRepo := tests.CreateMockedRadioRepo()
+			radioRepo.Data = map[string]*model.Radio{"ra1": {ID: "ra1", Name: "Radio"}}
+			ds.MockedRadio = radioRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra1"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res).To(Equal(resolution{}))
+		})
+
+		It("resolves the uploaded image when set", func() {
+			tmpDir := GinkgoT().TempDir()
+			conf.Server.DataFolder = conf.NewDir(tmpDir)
+			Expect(os.MkdirAll(filepath.Join(tmpDir, "artwork", "radio"), 0755)).To(Succeed())
+			imgPath := filepath.Join(tmpDir, "artwork", "radio", "ra2_test.jpg")
+			Expect(os.WriteFile(imgPath, []byte("uploaded radio image"), 0600)).To(Succeed())
+
+			radioRepo := tests.CreateMockedRadioRepo()
+			radioRepo.Data = map[string]*model.Radio{"ra2": {ID: "ra2", Name: "Radio", UploadedImage: "ra2_test.jpg"}}
+			ds.MockedRadio = radioRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra2"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("upload"))
+			Expect(res.sourcePath).To(Equal(imgPath))
+		})
+	})
+
+	Describe("playlist", func() {
+		BeforeEach(func() {
+			conf.Server.CoverArtPriority = "cover.jpg"
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum = tests.CreateMockAlbumRepo()
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "t1", Name: "T1", FolderIDs: []string{"f1"}},
+				{ID: "t2", Name: "T2", FolderIDs: []string{"f1"}},
+				{ID: "t3", Name: "T3", FolderIDs: []string{"f1"}},
+				{ID: "t4", Name: "T4", FolderIDs: []string{"f1"}},
+			})
+		})
+
+		DescribeTable("yields a generated grid from up to 4 album tiles",
+			func(albumIDs []string, expectedSize int) {
+				plRepo := tests.CreateMockPlaylistRepo()
+				plRepo.SetData(model.Playlists{{ID: "pl1", Name: "Playlist"}})
+				plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: albumIDs}
+				ds.MockedPlaylist = plRepo
+
+				res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl1"})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(res.reader).ToNot(BeNil())
+				defer res.reader.Close()
+				Expect(res.source).To(Equal("generated"))
+
+				img, format, err := image.Decode(res.reader)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(format).To(Equal("png"))
+				Expect(img.Bounds().Dx()).To(Equal(expectedSize))
+				Expect(img.Bounds().Dy()).To(Equal(expectedSize))
+			},
+			// tileSize-1: the 4-tile canvas is built as [0, tileSize-1].
+			Entry("1 album -> single tile", []string{"t1"}, tileSize/2),
+			Entry("2 albums -> duplicated to 4 tiles", []string{"t1", "t2"}, tileSize-1),
+			Entry("3 albums -> duplicated to 4 tiles", []string{"t1", "t2", "t3"}, tileSize-1),
+			Entry("4 albums -> full grid", []string{"t1", "t2", "t3", "t4"}, tileSize-1),
+		)
+
+		It("resolves the uploaded image before the generated grid", func() {
+			tmpDir := GinkgoT().TempDir()
+			conf.Server.DataFolder = conf.NewDir(tmpDir)
+			Expect(os.MkdirAll(filepath.Join(tmpDir, "artwork", "playlist"), 0755)).To(Succeed())
+			imgPath := filepath.Join(tmpDir, "artwork", "playlist", "plu_test.jpg")
+			Expect(os.WriteFile(imgPath, []byte("uploaded playlist image"), 0600)).To(Succeed())
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "plu", Name: "Playlist", UploadedImage: "plu_test.jpg"}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1", "t2"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plu"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("upload"))
+			Expect(res.sourcePath).To(Equal(imgPath))
+		})
+
+		It("resolves a sidecar image next to the playlist file before the grid", func() {
+			plDir := GinkgoT().TempDir()
+			Expect(os.WriteFile(filepath.Join(plDir, "list.m3u"), []byte("#EXTM3U"), 0600)).To(Succeed())
+			Expect(os.WriteFile(filepath.Join(plDir, "list.jpg"), []byte("sidecar image"), 0600)).To(Succeed())
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "pls", Name: "Playlist", Path: filepath.Join(plDir, "list.m3u")}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1", "t2"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pls"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("folder"))
+			Expect(filepath.ToSlash(res.sourcePath)).To(HaveSuffix("list.jpg"))
+		})
+
+		It("serves a local ExternalImageURL as a file-backed reference (staleness-checked)", func() {
+			dir := GinkgoT().TempDir()
+			imgPath := filepath.Join(dir, "cover.png")
+			Expect(os.WriteFile(imgPath, []byte("local external image"), 0600)).To(Succeed())
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "pll", Name: "Playlist", ExternalImageURL: imgPath}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pll"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("folder"))
+			Expect(res.sourcePath).To(Equal(imgPath))
+			Expect(res.refMtime).To(BeNumerically(">", 0))
+		})
+
+		It("routes ExternalImageURL through extGate and sets extError on transient failure", func() {
+			conf.Server.EnableM3UExternalAlbumArt = true
+			folderRepo.result = nil // no grid tiles, so the external failure is what surfaces
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "ple", Name: "Playlist", ExternalImageURL: "http://example.com/cover.jpg"}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+
+			var gatedNames []string
+			gate := func(name string, _ func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+				gatedNames = append(gatedNames, name)
+				return nil, "", errors.New("network down")
+			}
+
+			res, err := newResolver(ds, ag, ffm, gate).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "ple"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeTrue())
+			Expect(gatedNames).To(Equal([]string{"m3u"}), "the playlist URL fetch is gated under \"m3u\"")
+		})
+
+		It("treats a missing local ExternalImageURL as a definitive miss, not extError", func() {
+			folderRepo.result = nil // no grid tiles, so the local-file miss is what surfaces
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "plm", Name: "Playlist", ExternalImageURL: "/nonexistent/path/cover.jpg"}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plm"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeFalse())
+		})
+
+		It("treats an ExternalImageURL 404 as a definitive miss and falls through to the grid", func() {
+			conf.Server.EnableM3UExternalAlbumArt = true
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusNotFound)
+			}))
+			defer srv.Close()
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "pl404", Name: "Playlist", ExternalImageURL: srv.URL}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl404"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).ToNot(BeNil())
+			defer res.reader.Close()
+			Expect(res.source).To(Equal("generated"))
+			Expect(res.extError).To(BeFalse())
+		})
+
+		// A local resolver holds no agents: reaching the external branch would panic, not degrade.
+		It("skips the external step instead of dereferencing absent agents", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum = tests.CreateMockAlbumRepo()
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alx", Name: "Album"}})
+
+			res, err := newLocalResolver(ds, ffm).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alx"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeFalse(), "a skipped step is not a failed one")
+		})
+
+		// The worker resolving the same playlist is asserted alongside, so this cannot pass vacuously.
+		It("resolves a playlist locally without fetching remotely or building the grid", func() {
+			conf.Server.EnableM3UExternalAlbumArt = true
+			var hits atomic.Int32
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				hits.Add(1)
+				w.WriteHeader(http.StatusNotFound)
+			}))
+			defer srv.Close()
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "pllocal", Name: "Playlist", ExternalImageURL: srv.URL}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+			item := model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pllocal"}
+
+			res, err := newLocalResolver(ds, ffm).resolve(ctx, item)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil(), "no local source, and the grid is worker-only")
+			Expect(hits.Load()).To(BeZero(), "a request must never reach the network")
+
+			worker, err := newResolver(ds, ag, ffm, nil).resolve(ctx, item)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(worker.reader).ToNot(BeNil())
+			defer worker.reader.Close()
+			Expect(worker.source).To(Equal("generated"), "the worker does build the grid")
+			Expect(hits.Load()).To(Equal(int32(1)), "and the worker does fetch")
+		})
+
+		It("treats an ExternalImageURL 500 as a transient failure and sets extError", func() {
+			conf.Server.EnableM3UExternalAlbumArt = true
+			folderRepo.result = nil // no grid tiles, so the external failure is what surfaces
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusInternalServerError)
+			}))
+			defer srv.Close()
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "pl500", Name: "Playlist", ExternalImageURL: srv.URL}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl500"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.extError).To(BeTrue())
+		})
+
+		It("yields an empty resolution when no album has art", func() {
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "empty1", Name: "Empty"},
+			})
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "pl2", Name: "Playlist"}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"empty1"}}
+			ds.MockedPlaylist = plRepo
+			folderRepo.result = nil
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl2"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.source).To(BeEmpty())
+		})
+
+		It("skips a grid tile whose declared dimensions are a decompression bomb", func() {
+			libRoot := GinkgoT().TempDir()
+			Expect(os.MkdirAll(filepath.Join(libRoot, "bomb"), 0755)).To(Succeed())
+			Expect(os.WriteFile(filepath.Join(libRoot, "bomb", "cover.jpg"), pngHeaderWithDims(50000, 50000), 0600)).To(Succeed())
+			libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(libRoot)}})
+			folderRepo.result = []model.Folder{{Path: "bomb", ImageFiles: []string{"cover.jpg"}}}
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "plbomb", Name: "Playlist"}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plbomb"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.source).To(BeEmpty())
+		})
+
+		It("does not resolve as absent when every sampled album fails to resolve", func() {
+			// The album ids are absent from MockAlbumRepo, so every tile fails non-externally.
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "pl3", Name: "Playlist"}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"missing1", "missing2"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl3"})
+			Expect(err).To(HaveOccurred())
+			Expect(res).To(Equal(resolution{}))
+		})
+	})
+})
+
+// decodeTile runs before the processor's own guards, so it must enforce the caps itself.
+var _ = Describe("decodeTile", func() {
+	It("rejects a decompression bomb before the full decode", func() {
+		data := pngHeaderWithDims(50000, 50000) // 2.5 gigapixels, far above the cap
+		_, err := decodeTile(io.NopCloser(bytes.NewReader(data)))
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("dimensions"))
+	})
+
+	It("rejects a tile larger than the size cap", func() {
+		data := bytes.Repeat([]byte{0}, maxImageBytes+1)
+		_, err := decodeTile(io.NopCloser(bytes.NewReader(data)))
+		Expect(err).To(HaveOccurred())
+	})
+})
diff --git a/core/artwork/sources.go b/core/artwork/sources.go
index 04a9257fb..885ca03cf 100644
--- a/core/artwork/sources.go
+++ b/core/artwork/sources.go
@@ -3,6 +3,7 @@ package artwork
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"io/fs"
@@ -16,14 +17,16 @@ import (
 	"time"
 
 	"github.com/navidrome/navidrome/consts"
-	"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/resources"
 	"go.senan.xyz/taglib"
 )
 
+// errSourceUnreadable marks a candidate the resolver knows exists but could not read. Failing
+// to open it is not evidence the entity has no artwork, so callers must not settle on absent.
+var errSourceUnreadable = errors.New("artwork source unreadable")
+
 func selectImageReader(ctx context.Context, artID model.ArtworkID, extractFuncs ...sourceFunc) (io.ReadCloser, string, error) {
 	for _, f := range extractFuncs {
 		if ctx.Err() != nil {
@@ -32,11 +35,11 @@ func selectImageReader(ctx context.Context, artID model.ArtworkID, extractFuncs
 		start := time.Now()
 		r, path, err := f()
 		if r != nil {
-			msg := fmt.Sprintf("Found %s artwork", artID.Kind)
+			msg := fmt.Sprintf("Artwork: Found %s artwork", artID.Kind)
 			log.Debug(ctx, msg, "artID", artID, "path", path, "source", f, "elapsed", time.Since(start))
 			return r, path, nil
 		}
-		log.Trace(ctx, "Failed trying to extract artwork", "artID", artID, "source", f, "elapsed", time.Since(start), err)
+		log.Trace(ctx, "Artwork: Failed trying to extract artwork", "artID", artID, "source", f, "elapsed", time.Since(start), err)
 	}
 	return nil, "", fmt.Errorf("could not get `%s` cover art for %s: %w", artID.Kind, artID, ErrUnavailable)
 }
@@ -55,11 +58,12 @@ func (f sourceFunc) String() string {
 
 func fromExternalFile(ctx context.Context, libFS fs.FS, files []string, pattern string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
+		var openErr error
 		for _, file := range files {
 			_, name := filepath.Split(file)
 			match, err := filepath.Match(pattern, strings.ToLower(name))
 			if err != nil {
-				log.Warn(ctx, "Error matching cover art file to pattern", "pattern", pattern, "file", file)
+				log.Warn(ctx, "Artwork: Error matching cover art file to pattern", "pattern", pattern, "file", file)
 				continue
 			}
 			if !match {
@@ -67,11 +71,15 @@ func fromExternalFile(ctx context.Context, libFS fs.FS, files []string, pattern
 			}
 			f, err := libFS.Open(file)
 			if err != nil {
-				log.Warn(ctx, "Could not open cover art file", "file", file, err)
+				log.Warn(ctx, "Artwork: Could not open cover art file", "file", file, err)
+				openErr = fmt.Errorf("%w: %s: %w", errSourceUnreadable, file, err)
 				continue
 			}
 			return f, file, nil
 		}
+		if openErr != nil {
+			return nil, "", openErr
+		}
 		return nil, "", fmt.Errorf("pattern '%s' not matched by files %v", pattern, files)
 	}
 }
@@ -90,7 +98,7 @@ func fromTag(ctx context.Context, libFS fs.FS, relPath string) sourceFunc {
 		}
 		f, err := libFS.Open(relPath)
 		if err != nil {
-			return nil, "", err
+			return nil, "", fmt.Errorf("%w: %s: %w", errSourceUnreadable, relPath, err)
 		}
 		rs, ok := f.(io.ReadSeeker)
 		if !ok {
@@ -103,7 +111,7 @@ func fromTag(ctx context.Context, libFS fs.FS, relPath string) sourceFunc {
 		)
 		if err != nil {
 			f.Close()
-			return nil, "", err
+			return nil, "", fmt.Errorf("%w: %s: %w", errSourceUnreadable, relPath, err)
 		}
 		// Close in LIFO order: tf first (it holds rs internally), then f.
 		defer f.Close()
@@ -127,12 +135,12 @@ func findBestImageIndex(ctx context.Context, images []taglib.ImageDesc, path str
 	for _, regex := range picTypeRegexes {
 		for i, img := range images {
 			if regex.MatchString(img.Type) {
-				log.Trace(ctx, "Found embedded image", "type", img.Type, "path", path)
+				log.Trace(ctx, "Artwork: Found embedded image", "type", img.Type, "path", path)
 				return i
 			}
 		}
 	}
-	log.Trace(ctx, "Could not find a front image. Getting the first one", "type", images[0].Type, "path", path)
+	log.Trace(ctx, "Artwork: Could not find a front image. Getting the first one", "type", images[0].Type, "path", path)
 	return 0
 }
 
@@ -171,44 +179,6 @@ type readCloser struct {
 	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)
-		if err != nil {
-			return nil, "", err
-		}
-		return r, id.String(), nil
-	}
-}
-
-func fromAlbumPlaceholder() sourceFunc {
-	return func() (io.ReadCloser, string, error) {
-		r, _ := resources.FS().Open(consts.PlaceholderAlbumArt)
-		return r, consts.PlaceholderAlbumArt, nil
-	}
-}
-func fromArtistExternalSource(ctx context.Context, ar model.Artist, provider external.Provider) sourceFunc {
-	return func() (io.ReadCloser, string, error) {
-		imageUrl, err := provider.ArtistImage(ctx, ar.ID)
-		if err != nil {
-			return nil, "", err
-		}
-
-		return fromURL(ctx, imageUrl)
-	}
-}
-
-func fromAlbumExternalSource(ctx context.Context, al model.Album, provider external.Provider) sourceFunc {
-	return func() (io.ReadCloser, string, error) {
-		imageUrl, err := provider.AlbumImage(ctx, al.ID)
-		if err != nil {
-			return nil, "", err
-		}
-
-		return fromURL(ctx, imageUrl)
-	}
-}
-
 func fromURL(ctx context.Context, imageUrl *url.URL) (io.ReadCloser, string, error) {
 	hc := http.Client{Timeout: 5 * time.Second}
 	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, imageUrl.String(), nil)
@@ -217,6 +187,12 @@ func fromURL(ctx context.Context, imageUrl *url.URL) (io.ReadCloser, string, err
 	if err != nil {
 		return nil, "", err
 	}
+	// An agent-advertised URL that 404s is a definitive miss, not a fault: settle absent
+	// instead of retrying forever and tripping the artwork breaker.
+	if resp.StatusCode == http.StatusNotFound || resp.StatusCode == http.StatusGone {
+		resp.Body.Close()
+		return nil, "", model.ErrNotFound
+	}
 	if resp.StatusCode != http.StatusOK {
 		resp.Body.Close()
 		return nil, "", fmt.Errorf("error retrieving artwork from %s: %s", imageUrl, resp.Status)
diff --git a/core/artwork/thumbhash/testdata/alpha.png b/core/artwork/thumbhash/testdata/alpha.png
new file mode 100644
index 0000000000000000000000000000000000000000..6ac85943a9041b9592a0550e7ef5be8f34683785
GIT binary patch
literal 24912
zcmV(^K-IsAP)<h;3K|Lk000e1NJLTq002+`002-31^@s6juG;$003bZNkl<Zc$^&4
zhgTbh!S-z#W6U%d%-&P%Jp>X$NJvO%qJ{PzXfGrX8VC)Rkk}wL7~{Q1Y$uNGBu*PQ
z)7fd-IL&n0G--Cy^m+T8e&;^Ff8aVd001~}5D*p~9tJo7I1C5_M2AHmOgIn|brf(o
zJUuM_VDf>O=!~%FnEZorF(rVc_yRzDd=(%uruty&k&5v2n3k~QgeE}Fk>>E6B=CX!
zq|SrcNk~9Z1`3duhB=s*)e}~niUSm9kPepTG69vDeSp$@&Vjmo0iY&N5?-ID05s(*
z0S$RtKod{}Xf81xY%MkcpcTUaXr(o*y~=U0quL8V0w)2`%CWHSvMB(fZZ535VgZ1v
z4uxTxR>HA0TVce8;|H-#dk1OFdttq8rvZ$nvjB3_wJ=KC4FC;tD~#EC6TpYuIlzM4
z2@}9x07wvj07yDs1jt}70s7%DhpFI?4obV;JfKFr572bK4^W~%JgCC{E!;@>Jj{as
z8eqbH127T3KWM`K1Ta&60@$cO14anHgbkAbVPOXjh93$)a4-UJC=L*PAPx`}mKYup
zlNufsnR+NHE+Zm3I_+>=R6Zaft|%ftrtHws_{u}cG1U>r;;JLEj@E?dB-aD-5?aD@
zkHRAI(-45-V~9h!>FC2n8Aw2R8X8cTfeSCmAsi@8ryVRSU;}D083!wJ1!0Z3vhdm>
z>4ByKDWIi5bpTXm0JN0o4z^TUA|Pe9aCn6c0510c;5F_rWX0qGc-{B`RNYh<x?wIH
zSG{}?SHB#Nt6Mur0Br;Ct-Anx>rQxY%N~FPITb-}Js-h>o<BeXT{%qeympA&e*F-?
z<NhH*=ksBr_WJ-H;^6@){G~8C`qglG_oFa*_alG``&M{A{vCh{^_MUe=94fD;gbUc
z_)iZF62CY+Nc{G&mGC`ai1N*WVfrrzT=XBqZN2}EaP$EHQGi2$u*idl!=l3?qhi9N
z!Xsl6q9UV{qvB#SB90tR4~vh<2uqI5jZTayj64<(3{N})j7&`^J(QYIACa2ebT}ue
zB|1L|9G#N^iO5Yy94t)fiY&-RMFP{&QAO#bi1Pg2sH$vARA~++tTKypxS^OEU7g2`
zYAzN;HI~T2>q}&Z!9eBV<|0EBxXKjSQEEK|s~9>AFLNI3EO$hp%6(zz`iU@j^;mRQ
z<HTWf<6JnQJ{V1GUI^=LSUp5+T8-*$*$Jn#Z->)b_9E%f(~&grg+ol(rGu=_i_wDi
zr@}a$HxG+pw+>1=o;fT=z8EG(JUlEz{2@$&c^D-{y%MIxz8l%!{cgAd`{zh4`lCZy
z;wJ}<<S!x(<R{^#-Y1b3>eo@jl<y;L)Ndjj<nO~>lpiA;eg8h}qyhl32M!;MJRA`o
zb1>#mM09LybWCJoTvSwi+>s+GF-H=zqK?Mo#v~lci%m%^j!jG{I+UDJ9Fdw<btpZ#
zDkd|fDJC<cKB6F{^>9u$BpR605t*L}iz)cu1Jlv5mHDJdU>+`}Jc|%np4%5$SICNK
z$P+}=0|kc~$|Vuah00hEP#p=WQpdEH7!QL>P0=0I12NEY$Dz(DM=YY+5sRqw#3E}Z
z<Ir`1Said56bdvKfoq*RjBi<pBtSMJ$W2>OMDRu|t>eTYO6#d87UX<1t>Z!j2XgKZ
z19s)G2!11ykGvTzMBk2;c0C{0kGU5mL%a~vk9v5xzvp3u7XM157WXJxhkG-^M0_Vw
zOMV=oC43xb!F?8Kp?no*C46ycnEd3BgZypeFzwr@;l5vE?d+c;U5x)b<fQ`+#)d~9
zjE#<tiiwLn6n!{0;Yd_;TwG#QeALmz^dreJDY5bK*)fSna}til17p&T0TVLPt76kr
ztKzfLD<ZSAY9h0;8xo4rT4M4uAW^01keI@BSOPE?9bKA*j4I6`#?=&(<Le6uF}20i
zgsNh0R8yJYNMoTOp|wOD1uhjG0ax`O0hj6{+pAPDot64{NTngRtJWHYY;eZFn;cQ7
zhLI!4hOtO|T_6F|HW`C%m`NZuE<}-=LPzi|OL6p;tyns2J&pxC5k>FVOQ3h0isZr1
zB(OU#C2+c)ie$sCMu{-D6NJb+38J27V#GbqCG?{o#Hlf_#H+g>#;b9!98r=UMX7Kf
zMC$N=PSBD58b3h&Fy2V`IC6;mS?mz=??)`GCvi6R_mMWvPth*!_c0FUkMVBK|3$l)
zfCEPk#U4(Ki48vzoe*~<J}NRU_GsMEm?OzCM-z@EB*$kbB_?Ji9!tqjNIq5=o0eLT
zn3Yx)lapSVl$BDIn4i&@keAsSpPLRzD9D4w6z9NWOLLKN<vGasvRrg*S$@xvs$$BK
z3LrhP5lBB$TS|*-u4KoyR&b6qRr2E6Yx<A2S169O)$}K{Rcm6wRhIa!T0;`5dN2{y
zGJFKp=uE^k`r?qS?pQ+0)KPTHYz!XaKS~4#V+k$GF*H~xkp$a1%7pGE(L1(dIFREp
zy!JD(Oz5RV5$t>tr~6tAA9Xceh`b&r>ADxA#5@<T#5{;s5nqgz5nnl??Rou(0r%EX
zJ>m5P6Y1TU0qXnlX6k!K%=Ev;4^uvhv9dlnYGXf1uyVeM8|nKt-og4g!PWO&qKETa
zoKN^mf|myXq(;U7l46e>PL7F<O^P`hbu=zM=Gc*ANeS^sljDyiWW=W@WhNvg<)@~m
z6dujaEK1DIsEE%<t2vsJS{+}M*_c|GSs!0e07)n*Y)=6eKvSv;U@0|uh~!dW&$04S
zTyk9jF0~0rNvbI)r#1lTNsT3pl(uTlF>o0_v9(qd-&(Cqf!3)LJL(Lnuv$|*yvCT)
z)o4vdfb7Q*AZI+f(RmEpHj#*F^C#k)11V(iY$6pjcZ>>MNMOK1@yzy(6h`OnF$R1q
zfd$)7Vj)f(<zUVn6~M0~i!e_e74%#?D(t><RMvevNkY7rpz3*$sKx*Bs2=w)S&e-o
zK}UX+q$R(dY#_dOOyBp;(V^bICJ(bdOde!@8gJ+PE!jqU5^v>wnd;&EE7`~S?${{n
zhoe5>Z^@JF|E73306<cF!ok!dv4_&*5@S=75~7onQWDcrjwWQJ97|44N={8pPR>eB
z&L~JvO#!CnW)>yqr5C3ZWLBl+X4Rw>XEdi57PMs)6oHb8^C79gd{}Z-0W_nwu;*A+
zAv&?X5SLb4flI0d(vljhsA=`3oHTGPH>0hRmkOy6CbiedQlSm<<c@k}dV8%d1=eCZ
zhHf^dV_Ix!s0QaTT$3#g)$U5cx4YAb;ORts$80(Qx^RpLpHF6hms1(A)eKhGdKweH
zo7~sApTfrM9b+L*C-bmp5=F?1=|c2V8A8m>6h-&-<bM3^r2d{eX<GcfV+!(f$x8gg
zBsJ-kV+P7AN#?${(~Yzbjtwy1J!WNpnCPH=k~GZu=$M`HMUs>Cb&8As&tpE`KaY*F
z|CQ<y{g&$G{gUAo{WoPw3IL=hBt>LLCq<;hr$(nFCdH>ECnaVaJ(iN1ek?URBPBB}
zJv%!qH77SMFRLUgGow5+GovIkKc_q!m|LHnpIet*kk_1CTnI_8$cJRs6hM+Ii%}`n
z#i)$hQe;LWkeFUyK}>G}_NKN~v9eoh`%;?fILV+YVHT)Sl+{rq&VtpcQ#<Q)>79+5
zWLUj91=BQ;-qmQ$z&1NGdfFV>JuM^Y1h6}q02@!Hw);~Eh?!)1*Gwk0V=kKoUr*-3
zc2b#`?MxPOFN4=}GL?fqnJqz{&k*4+r_1qIvlXP<sY?9KR5|H>wx;(^s*3nRwubV@
zbUo?iG%fvMrh)Qu@<87k$yU}|sl&9tWDhal%e1l|rwy?mXOFTz%^GDrNgEM<n?1_^
zN5%yAyR1>k4_T9<|D*>*zh_U&0O7fD$HFs@rbgr>AB#&*$vBdmmL8jzoD!dtmY$N4
zlA4m4nw6cIk&~O2l~bIZlTnnFpIwz!kYAaXpIeh%SkjPNT+o<SQr4DTSpdnYDCx+l
zDu-rN7I$Y=RiZNMD$!Y>a$Fv$nvw>tW@NQhF*93gIa%#h>|9u#B&!o7%IvI@r@@-F
znO$w#tR9d#2Mrm_#zAZusE*-u62z0&19jz5I>)og2wxr<5y)e}=5i?Tg^WJLLM|P#
zp2hCk&SUlLWeK{rvba5`viP{u=~B$;94Y2ndOzVxma6Agu8Q<@hLZ41x{`1|Pfd6}
zPeXhmP2cxowu$jZx|#7-o`v~#riuP2$I5swbCCZy*UI@c&&K{D+rj@N%`JYCHzN2l
zdrbVVtZ~7&Ig^4P(*pAU<V}eFofc36!V6>559TMQh36hU7Lj)>H6b@WH7+YDJux>q
zGc7A4J2^i)D<`KQGc!M@pg1!xuROarAD9aSmSq<KtMkfAoAZE0P1)5Ypxo+`_U!6%
zSWaz8M{ZMfcTRl`rl7W_C$G7Zl-XKA&jwYoa@%Sd*|27AHn@(R0|p5)+grq$NN|51
zs!5yI1=i)D!TKx=$driz59Z>*_Do#6JsS%hE2MOeW)cwNS&Xh=R$upgE(5b%(APDW
z%kEmq<aKQn@bOz&oSx(PBJ`PT3HDT$fOx4ujJ;YQ$6n4;;jU+E@V9ex#Jf3K>YYpj
z<$i&N^)T1a_e$;{{pGwt?xS1__nk}&`<;S8&O7<Ttd9yuI3MOZMSsh5OTNq><A0qu
zCiy1cE&MubO#ZKYpY*$|aq-Xjv&#RMHP;US<Q`3m0H$Px6{coK<)-Dt=cT44<Ys23
z=A~t(<!9z)6&7Tr<>nP;=j9X^<pT@KfyG5-g(XFmz+zxkepyj-ad~NLUU><)prRa7
zP*d4i)L0G!Hq~MB8!OTIjn$-lP$e$ErGZcgX`uo;YB{+u5EBS%5dxuY(gGMnS=<Sc
z0+B8K1&CHt2^MAnV!@VTV&_mH9x)6g!`=D4a917`HJ(pK`$|~dfnp|Vu9%CNEukY<
zO9VaZ`8@1;9v^$WfJ@rWlM&A33kYXQ<b(@_D%|-J4dE(KMY>g>qu&M^dY>*b((jk(
z=r88$seddq(O=9ra^EPia$YMO=Dk^L6TF>o=l{8Al=DHpo%eCkDDU%pAOEvLm-tJd
zPy8f*T=9KzK=nh>l;Y>Yfa)h;K>kZfKmiCZPD(ypa4ajLBt18-C^aLhI3q8nI4v`^
zAfq6uFe^8^Br7+!xHvDrAg`pTq@bj%v=mrUP+U@7SXEwMUR_dOSX<IiP*K%hUQq!8
zR#!kun<@~6jTJ~>b7gmVLp7<iy%|>yYU%|-Tl#>I7DiDgm|Fw`2@4Rd0wAnK0qg?F
z3Q!%oG91`YjO{cR^}wy=JrGL)vE5ccMY)TK2v<>Wr>}&Jnl7bbr^;EV=^_>`Sj@#O
z0oj;P8LuY<<l%RV1cbf9e#)s*DdBvHgmj@$-FvM}O}bI2q1-G~F`fph+4ss#%)4bq
z+5_MK{Xwa<@5Qn~_R9ss!dJ>|ymw0MqIXK2{C9w(yvIO~;Bo1w==0)H$yWtF>1PGw
z{ZC3K)!!FPNq;B{D8DZcsD3R7>i=KqoB{wSOG!OYnUr}Dn3;FDI4$Q$WmZl+Fe5Li
zG%Gi$BC8;|ys#vv6j+p9QB(-51eTYUlvh-gl~+`kmz7mil~&c3Radu_)YXE34OQ)x
zHFa<xsJ5%5u>oDyP>-r?Z^2fz*7cTlG?FWzO*9~+rLO`8=2Su3`BmMmvN9xCS%&RY
z7Na1Vaso_Mj)fUZ2pxu!UZ}m2(mhl~>~dA~b&r;ldpsq5UE^h3RG^a8<1gi*m&&;K
z)lx2T87L)f6pKm6D`lje3K8W*xq@=OLPk7WuAp58D(P2%2G+GQ6XSZ7k$bn;z`av$
zWZtc^GG8hk5IzK2MQ>CLb6%~qbKWi+<v#+tBp+6I1@Bdj_J3OD>VI76?f;^3O!^gY
zTKV^qNyWb^CpG^np3(nUHLd%#d`AC!@w^srpe!RVq9!xvU|D8vR83}KOl4Y0OnE_Z
zLRn^UdTmibc2!<cR%H>eptQ6yx3Z+Pq`bJgva+<Sw6v_Iy0W&crnI8IsjR88wY;_t
zTvOW!u4!oKs0D+%N}EB*GH?U79Mp=f?Pw*H!NJt>j%H3ZvV~KL?%<bU!2BvCTv~&J
zD$8&XZDkK!TiT1Vl#}2CRV0k9l!9=T^`f0+OpL3FfpJ&R(c@)2e6W&-pD*VU=gZlI
z`AP|KvzAZTu9Z`FOZ#bi)e_3d3Ps=Pa%JDeQYG_BrJ8xQ!oYZ{QqQ<kGr+x7V`1H^
z7-HS69u_{VunHblStT!*4M`uB+hp&QI>m37j|ktZa?Af(<Cgxl#w~wbHYNYE!YBW%
zJShLV#;^anI;j1*Y(f81>4NIls#)W|tCkG_Ky7+fSY>KKRBdKSTy<tiY;9&~Vr4;b
zYHeXzN=<QDc5P8fPF*oDx1yx1xW2TasG_>Oq`IQ6vc9sqy0)UCwyLhOv8J)EwV}BM
zT+`IjS=-zUuWD<?R6(1%t6Li}6`de_bw@j)7T(5cfVXpMQSJN+6hv6n4HndQLlo7R
zc6kjErK`ntYwL)emRb^GsDXraRQ95WDycorDms3&j!hV?WRs@q8H8XhmmI8TQ-XCO
z@<N4(veqD?tyhStJM{|sUbU3ETccs0tyMD5)hlUNs*HU%sttWtDz)6(RYS~sHD>M$
zH8%0x3OnbyszK??bx!_E)i&`P)lTtS)eiXw)jrkxbsoh>bw1T!tHxBH){ggoUOBD#
zqGnS4P0gg?>-wPK$J*e)FIBVVUuu`lzt%1r0pWGYC5LL#@}p{V3nLnH%A)FWfk*4}
ziW2K`OVevg%Q6~DfVs656`6G<Rr&R$RV58IbtTOe6{WScwRLrk4UP3R4J|G8EzNcH
zjiB0=26%IO8?>>#6<rH!!qj#^3ANx3QcDMjPzP&gG<L#SE!`cQCN!Maf`*G5v2b}E
zwo}@I#pr4&2z@gNt!pBot+jnUmPQuJQOCxPG_&y|b#$V)j?+8dz{XEBu<?N!9(A!+
z*t=3ICa%?q$m@+N`gVhwy5Fpz@7Acf`}Hcug<37|YO{%bsY%PaQ8ysCS!d)v-C*L~
zZMKRYG&%SW8Xe+4)r|DN+TfDC+~||N*65T!s+~~$rDj6?VY5&ExOrOpxOPJOWlKQy
zdE=bn+giWw+qy-~kIl=b?^{9xzt*qlf2mzE003=S#bGU3z_6D5l9>8}qUeUa@|c$V
z%43a%RVnoa<>^gDRawm?<@wF!b@>gI)ddYzRlxeXn)2rQmYUXvmX_wariPa07D#g&
zxUCV~2yJL>Ml`j7G0l+HZV<Qw+Xii?G$Y%4o4YzF^~m<VhAtSZz6T+0!NPbgIJl^R
zh|x5Vu!^=`w5Ea7t!trlo9f9Jdp(8ZY-13dt#qQhflcr=2nm5!K7OW2N|*=n>9b98
z+FY}O8EWgN?KG<x#~W1i6K!hV9!SGG-)dl;sn_$aHt2*;H4SpEHdqDM8wZ4U8Z3hQ
z4G!^(ts~+WK~CvQ^)}@z4PN;pkW2ok-lzGXZCv|dlc)c$ZIjB!4MD?44FTg9jZ?bM
z>K6w7*|cc+p&@AgreSIDhlU07PoTBI-<p=~001PrGy;@caj3nZEUvk@I00N#8Q+>;
zk<?sVn*k~>%Yc-W=e7gu3PGiH1<jRB<xLe$Rgk*IQgB^sZ4;=et_{@K3TkL<Z*BpB
z!Obo0O`uk28w7%C>+HldcXZ<05C~E;s*?^uLn$rD4lWqq$p+!!JP-jT0ufN+b`nnA
zM8PRQB)qYu7pHCS!x-CH_(2GRINZj=yC6KO3nC<rwsVO7CN6Oj%xC%`GR9J~guVh+
zvNzf_^bL@PwcVs(?0^i+Q%xrBxfTQWOq)S`zGZ-Wwav)A(q<Ch0a;|vf^GfJH4pbc
z-!dY7*y5Hv1bd{fHo0VPwvVdbY#Ud-4f1O~Xq_~^*X}nxZkaKD4Dsv#))dhGqjkyj
zEo9d6575%!H=tGXFRjZ%ze83m{{e3f{tvJs0-9ZU7?xcg3oWTm0Ogm*gUV{+TT83c
zIx6bY+R7`lp|!PnZB?}et<{adj;6Y@*2bpFj>e`sXnj)?sI9dT(%jb4-qH>Nw?g3{
zC>ROpY=^_TI&h#4C=rV6Ac49%NF6;0Ca4=tgW}O#7!fOK!=gnU1dI$sM)kue`2JQh
zK@DS(^sUq$1FVlY1ncW{v@>Z=5R2}Ga>-+Dd}^Rw)He;0(&pMkee>;N&O*DIvjUZ|
zHX!}1omRDA52oYowd=%ZK}P;rh*5AEX5d}#un4Y!%))12L*m=5BmK|7hUND`Bbw*h
zU7A0^T-rZ@y~@`?qsliyUc(3ADeVXC6UINc`86LyCk>xLX3d{KW(;4pEgQaV4-J0b
z8nS&0U3L7>8nXWzvg-VA+s-fm0LcP|LGpkRFko#oB)>8aQC@STqqy!UtfDTZy{tN`
zqq;d0URR$BtF9|RRJWEx8(K=C&EVP&P;*^pV_OTP71D|T!$9Cx2pHPl0qcZ9pzR1K
z8rFfpAkbZec0?Dc1KUOJ?CGXKa9wmL2`zw=umTvCAb^n23IrY75AE&MbkOi7D2rl(
z_mKuV`>4b1Y`PO6q}e+JG!I<D@_;2wf4i9NZ<o>L+U2aJ4r$*CT*F%HQ1VtgG`tO%
zj&~BG<DY^KaL+;v;tSA0(fN)+@ug0i=w^pib-Uduxeu`^@4+3a7Z4-bhft^fj|iXc
zr4Ens&GsqXTd;BcyWnZ<2hdr=haCa^WBAPAM;&wj104JUv1I=TbanVUc*yz_bk*@Q
zWX1L~bZz9{;7vE+06ees5WJu^q61hJ2`{LN?ksOegcVoCqskf+VPy@es7g>yXI*n4
zvKmy}S=(3wZvdBdf<UERt<XwnJER5G3Ts7xI-8Ikoe)F^4E{gD4k)|_21DafXcW2w
zg&}tIU}*?^54{VAX27s$9=sRFLy?IBB(X=1q!Ic%`g;3OG?J-<(`!QTNQ0dmssq6%
z4|j=ZZUn#2*C}H9P;!P3CSeEQO5Pko!Jg}oaaNH1f;E(yzX><+H((~=37A288fp@p
zfelE`BTb?!2&?=u)GEE&HQav-?o`}II+b_29Et~BBl-tj<EmGn6Z)5+Q`*<ye$#86
ze&YunGnPMh&6yu}O%ML1GdT1qa&hQ0#H{^G)S~lC)VlpU<eKwG<ksk~om<Y|;A`$*
zVOt(RSa(Tv1iGjp3RPGa(N*3MgD!18iY#qRLY6kApzE8G;WdqEUDcp$WOI8lvZcKY
z-3%`8ZfdJRHMQ1uH^b^M(9Y&A2n2$LK*1O!5{~FXbaf*!-3TPA2ZKW4yHH(Z463`g
zn}F*>VX<^L0mnd6dw6gPR*WLy<XtR+0>$iAplD<RnocqIuo**0K6MzyWsLMl=p#Km
zh7T@ec##UmBvLN$qm`V69xZ>aTO(RQ=)~(7qc{ZD3-{0_{vKvXu#YxLPW6}+=a9qF
zYdsFxMYuzC9X{ND1L;!Tf_qf=yT`QmFka(J7_a)p?g`_om?`7yn2CXRy8Y(2yQa;5
zM$Fp&+BIkW7%@Bi7_%_^C3?mB5BR#{EBLDIYt)AGNA#xa$L=ln@5o)p@2DLQAiO)T
zCIVGdAC4@mi@=sQ$D^uS;?Px~qnJuiI;OfU9aj&|LN>G&V(QxqyPI1}kZs@+B&59*
z(+;k~LtwS&&UO&09npsBM1nEU&dzQ$5{~Y|_Mouc-54AS-;KibVn{d|u9v{VV0&p;
z5|M+X_Hw&PWFDSOl=ZNwGGrfBfnm|~cs5mwV^ar_eD*L-$gpE&Y!_0@cA}Mnahyaj
zj+P21QT^hXZVhJ^spKtU)WVH!gLo5f5*$bAl_&6ns(svm@&w8uzlgT?pF`P{7cmay
zRs5*oI(kHN59u=9!;NX~_Dt%Z!;c&PgqpPcsb_NF^`1%NYu%IPw=oOmw{gM2KjY`D
zA0wBBA0t<Wzd|jzo?up;-{969U!y`J-y&DNKjU`Yzu<R$|3Ph!0S@*QHbfAMTMlC@
z8l%y`=6FIyYdogBHGxzQ&Oq0;WMFF`Y3RoG0(1i`58K#Tj&Fum5?VTI&|qi<wgXm!
zL%<qH$nG`*3<V>?v7LAX7EVGTyYUzl8jUBC&{#By*xO6T5__pQDxQg^;Q1s9iA(Gw
z@vwBd0?nZ-u{@TB$fT-?LZ%TTWSOxdhMB-)+t4Dx2v)}O^+-6AL>146Q}8Eo3TY6p
z7tZ$Rr3)mzC`2+#wr~c;CfXq1!P?ZP2^RTjyi<3MIHI~j8dhIKyL3;X-I{0c?ty19
zV}@t(Uej}gG1CLWl>Q-h%K8RoV(1lO!2Tv-#_<6rXnB{kIQS86$@VF6$@v*()$un%
z$n$sHit}si>gYd+tE2xS9v}IEurvBIdS~=^^u8Mq)(dP3CzRD6qEs}*5i1(w$mO6!
zY;Ef?Ty<+AxdxO?ZfH%%H^Z`VjnI4?xC@ADfftk7pyj=tT{XR6L=zs0XeFait%PnI
zgwTy{CnIp3#2!pHiGWA;;t3cmnLwtHuw)#Kz`zp8Gy;jrCsRqB-adv9%caSQbhezx
zXKE-Mu9n1OYjOO(0RoRZh!YBIL<!G9Q3>1>sc3?rl1`FTd_PGg2;xosb2zPhl`x=O
z#|`vv;0M&36svXzXV&dwhg9dW4&^z#-FP1FQ9Xrqny%u!12=nJre}J6gD>DG&Ce11
z)|bc=125zKw%72pmNy7N$6NRr+xysg`+L2!u8)XI_78DOqo0x1ykFwhoL~2DxV|E<
z`Tj{+AN!fKGxi;2%l$iP$NO*WaUTFcD{c-a03ioy<;{nw<t?#<%Jw*79q1^b29`o=
zfu)f_@C-szS3a=?2JCG?lo7x%AfcnXk^t$cqrfqBy+~{`tqTh#!qFfK1`DO4Feo~P
zfT58HIC2k;K<g#oDCAxeg+wBg>2xNUL1$1|OfH?<$D=X(6eJ!^L*;WcBq7U4=L-fX
ze72F?&vwvc++lh@-$s*5ePpF%f~XYws0y*4q!!Q9jN&D#PPRZbYBot0)dt0;+w8Td
zb}0_S3DSu61j(+uNVe%O&|TW=1ef6^&1<<u88_UfjT>K}Ob_4howU9{nY2G3Ogmqv
z&Dmb32d(dt=Ung67j5s7794+}EP4J)*cknUwCeeszBBqIb#45c-fi~}^iB8Aq&@#n
zq|;+RQg{8oQ}(9-09JW(1i893npqExVpKtn^fkeb&}-Tgsi5}szD8&^9fZs!gJ5}7
za91${3@@d_y2_~#bSVviuB3Kg>S-{16AeWGk$Z5hbSwcv>Bb@$L|iuuPsUL3Bn*W_
zCep}#y)<fXAC*F8Q~GFp8kfbUF#1F^K1)OsFy$;BOU)Dtj0_=5OBV<Rm@?iFO(}Mg
z)soRZm2j+2Cv^9zW#bf`)K536XQ>0S#XhroiEP#`(afq1sztL+acK7$Bidb-)p(xe
zFrOhi2d<F4<{Pvz(>1!=a+Bp9e3mg~y~CQaJ)rxYFZ2b59x$heU!w%AZ_$JHH~T`4
zH|Y!Z_vy>-Kld$-eM}FHf5F`HenHvwea6`KKA~)l{m^&P_cQ(E*e}%m$=~`;PXEF>
z9|Qn6RUiPpwl$hj1Bv8R!;i3Q;jye*XfnILJ&6nMOlP)s=k$TQ^EqwELOKjp-Ur53
z&=AP#K16o|qqDn_jli|g5%_i%7T>|fkzi~L70ST%!f7M|icO&rX+$!PL7|XneSHiL
zoz};oa|E<LwvfhQ@ab&6f+iL!Xd<?rBj9N`5`m5@<{SD{GAmQTcd*nFSD#YuWaz|`
zeOl=>SFa2(^_m&FS+l@4YZn<N-5SHD+TdD^#~C)`4trF8obDMo!EqbUGCc$5m}7>k
zG_UnG!!vl3J?XgBH!*mZHRX7o8?ZiL%nrZ8Sa3aL&N<$ot=Qk;tT-RhS4ZBaue#pr
z+wlI4v+Dhnwl(pDwmJEA-|@gd*;|3{n5V}7MLQn+xo>~+=e{%k|D&Cr2LM<VPyoBC
z?J&C<c8FaAi(xh+k8m10;#pwiF@75|Q_zCQX0~-@v7y)^0T>PBc41052x0{ThOgov
zaLxRl-WEQlx0Q*Zw(@bbb}q5ElR=`vIRplVL!^<oBs!MGqEc9FI)%q(vKZ_>CXd4t
zGud1rM<5ilgd90n%2#uRLL*Zl&@rUqA+B67#MVgc483HOtCD&cI`tUepq=KKbpe4z
zJIy!ggUn&w5@W~^Vp)uvESF)A@6_+I9OhFT$KXk>cjzqNGkj4nX}iwxS#Ar)hwreb
zY_}K__Pg9U`wN`F@I%3({S|i5{u*<^`4(?^>~&UX^j*P{>qGvs_dUUy_ha_j<VURa
zu`l_%<Dap1X1-?ZPJPWiJ@+l^<jl{ElMDY5oLcx@a3KHyuq!*l`PCiK>;_mgyAGbf
zZ$utpH^Gy6?LA4NwyqQ|tSdtV?#UB(;)=w`o-z&;TgpWcs(A=(0~<kU7Iae@x#->&
z5ti1<CiX%EL`sJcPlJmH45Wz8L~|*91TnLZBxW$k943p&Ww7`>A(zb-3B&>(S1b@p
zR3a%~Cr}8D0)=RRt&m&9a`_NnCmCTY<W9D}-y=3ECb?#nPduoZ;13uV!~^POk;OR2
z8`Q7!9HuS4V{n7(96TW$HSe=smUH~^fs3MX%X!X}<D$rCy~&w$J;R-F-sjBP?h5>l
zyS!P)i{csIL+-5e74fR?74d@mUGawdJ^qIK17T?DF?%iW5&L-HF>k~F8Fy#q3+}0@
zulOgX{vp~6{7ZOZ{s+OCz`up(mwpvoSp)#YP4Gj!2E;*e3p#?|&>bsiL?-dUUCEO6
z?lft8PbLrAlO~4s<nR%M5*Zv{Bta4?BxrKE2u-LLB6}MIJ%nZvj@~NnA$Q1#v<?B4
z(J3U+QBpDoC1i0)Vk(a;W%Eb^E|(=`3ON!!PaqQugi;<?#uM@65~)Bf6N_~+u|y?P
z%k(^T{}4~DvWXN*mr$*6iHus8ctGctnN)tsfW|L1X{Y%PLr~}(n3viImPI22A+c*<
zi#Iy3D|QX+^SndnC8L(h;&J;0>6GoNWWsq{=C?m140`ShXFT_L3(g0UW$*KXS<j22
zkozUk;@GRA)yX&bD-(}|Yh!;AuLnL5ZUsM;9H0D1wB`Ss@YM7Z{>k~Tc&FyR6`!8@
zm-OuHZ?bdCzlbg`{#Sfu5pY0M*LgtEf{d0nz~iJ~WQ@GEJ6_R@Oq7GVGvsZ=ba^{5
zLjlF-D`DhfNjI)Q3MZE;P~-|Rl29o@(QA|ha;vz90+NwgFd3~6(NCel`$;T}gvslc
zF&P8}Lx7hu_(Ua#&+O-m=nB4+BbNv{N|8(`7R#jysazwID0Q-aiBYVSnw4tJpiHH+
zDO75wVnAtEXjNk(gJw)Ns2P)4&9l;>ff@0zVOC}{Ey@3f=Nt%0efD*U)3PfW9XcWR
z*v^W5&eQU#kt;I4?V32?xFQYOZ_B5Bx0JKqXO&B14@3*Tmt;%6KS`H8e-f=szAg#*
z-w|*6-%_kk{YA1p@xFX(_AiqCz~_?vz!S;I+0PXFi~p3IU;06LarP(K<>eoxmqP!M
zU0eE9d370ZP~CtAs9R76<t^w#n)dEUWg9k0){0G4wi7eth@LbJ44b9y!WPP4y@jf7
zN};lwP^##r*T^yCS`CR-FYoEASCQ#$Dk2x$Po+atG%i%y$Av4XJe-Eh#VEL3f{G^~
zYB+p`nk%DggnXt((9f636#~Wo1m)^}X}?U>uTdGLD$Rggr!i=Bsv)`A;E<VABXWb$
zBOf%4D@;aTzu7X~Z#4wvj)7UFeRxhYYTHnFZQE+MeOu)kJSm%S?kUEGPpT%|7gS@m
zbJD4iE6Q2-RoT4vY1ypjzGA`kydvazUOn%9s9YF-AY1jlu38^|t$%0ck!(HifqY}`
zFS5OvKPykpeXQP}c`Q9S`-$qz(wCb3nXja0mcCJ4SouzNZvGeLwWZ(H7uNo(erg2(
z(1XwbMML*NMH4Pg)7%rKhhh_zP<*@|K}^<kQBu_%q+A7znytnVOOyzDsR~Ug)#E8u
zIt;5qNn+P4aqI>qjSkX~_~3p9AEIV(P&&4-OWh|%YUw<pLck}eMFNsaC}OC^a;8Gi
z&(w$|Tur}RpqD8Xx_*U1t=4IDs(!UzsU6U34Ffu}$*R#04E3A!qbiHmryDZ5bvDzO
zW^iCeZMDwpthQyf)4r<r4KM3PM?wnE(2m+Wx~HG8?e+VdXH~(Gv-+UpoMLwLnm#ao
zQy1_)qg@)kqhIpeQ_oM{)vr%K(5?mks9qg^Nxe4pnr3_EHPv3=9nD7YJ;m1Id;O>8
zAFI#If37((_lb6Y;dAAwm2Xw&*S^zTT=-dgY2^p~^_71sFRlNd;`$Z<plazpY;3|r
zn;@ja+73dL4%&0X&_O<`gW}Tko%l>6oRDcmk~59nv?48*R;<A@%hW_hwU)rBQ{$Mm
zDhi{~ND(w^Xk4g<%IVZnxKIs~4_9*}Sgk;eQ?dDYEn7}8h{Sywsf3}DD>z0)zeq2Y
ziHr)RSg+Em3_6wCq*Lp)My*+=AF!(R2CLd)u&RbEBN~&*qjn5<G(*-Y<H+!=&f%EX
zxNP%U*KkNX;#}5FjD!sCksZC?xoh%!_q0LBzA@mwY@8dtX!Lup=$E|LG;>q8)C;~_
z>ZQPQ>XpEYn&s&iw4sTYOdElh)oX#bG@F6fbX&6@==SG6FzzqCZ`@!0SaoXUBi)JB
zPxNQjzA&9x{JZMP#y_-IR=-nS{{Q<`b7lA6rrT=(fUyMw(6!^E^iXoF1xAT8fboe&
zC?!#c>`gMj$jQ1MMy3``&o|&1#U?bTz<{HdnThOLJ&9khCkyHZD4Yf@Lj*BXIS><D
z)H%Qrp$v2}#=sQgjVviq&lVE~q*9_@reGR`{WObM#WyK5BC|#<H7g7vom#KZs*F0l
z#$?dzO<IFRJ76#lT6I>v&0sa#3}%~0XSceI!#1DEZl5&Uhh_&{&L!=bYr!~bThqBc
zA^oIh-8khuVVQQG(oT(?GfsIg>-^r!mVoDme#v{=81g-3UY)pSSQvlKvN`jDWo`Ne
z%lgcpv>OW#Ejx3s=(Yln%=-)Pn)m15F`Nl~G_be)q3O)R-?SH3zS5sw{k#7B=97Ud
zo8RltZ~th#xbvg&^3IR?D_j4yJiP+|n8En)fmUpU5kieLz^Rdgozw&)l#*nC(^8B`
zR;m%(mp9nW&L6}u3ygS9v6;XuH{v+81}d|`Kom4u`?#$ZGN;+dkhGfEGQ<Fz-(eL9
zFh-sTW8(Gqm?ScyK`8AV6lqz5vVQuYRKYbV4P2{2BeiJtQiIaiZ_;Ws2EA5mHk*wW
zi^XI#n$1>|dDvjKjtttY9_z4k)Z`fSo9!c$MwdM><g_nZCv0<Ow{y+x9a$Tg_UxFZ
z$4?GTdQMxWeWy&*Q<sP4CN3J5CN2*y_-_p^O<f;Ynz(CNo4adWpLxL?nto|uZT6vY
zJ@~qLd;S&c{_N|96H9NK_7~r=oLl?IbY|(Jp_8GHtQR-GG@M`geDGZ8iSg>jcZM6g
zKbWr{|H*i5?`Pw+t^ZhV?Ewx9LZ|>6loVlw5~9q|-q@i|>d`?YEy0SSBs-Aw>|s1R
z+kvGQ+VR|?;U0F;FqT_6L=sh*>D($incHG!@tdr4Uh^PJ*kR%JgDpG-d{Eerv52I2
zn^;9MOVv1=L_@VpwN!^f#j+~&oWXvra9BMcuqh03tI;C28co_kqeX2VG8=8iA+vdC
z*kK<wyR0^gYk1f?GGrYdx7w}KX19H2$my6Kni!e2`MgU*-m#En%)4cq_U>9Hd|Q^_
z*eOeJ`t0!h^rhjYvCG!b_+|Uz<W=*+<kLf|bN9^a3-^as1NUufv(K5=m;d0{n|XEc
z<nn8d(@Sp+pIUn~cy|45%ZZJ@4qaIP#C&P{vH9ZGCxe$)|8BXw^Tc*}=X=|&o$oC-
zkAG*sw)3m))~Ww<+&KjR*rAjN7n~X~45vldP>kr|PUca2S6{NNhk4A2<z`#ayj%x~
zljZ2)<_%$4g)R!G+)kHNj8FtsHkz<@n96T;a%4?*rVM6fDiKzpx@(A|Mh;69$Pu9&
z?U3szu6`xOrc~00rFxc4Yv2rPbsW1w%eSfqrB0JsHKaA`?Ix4nZnj%&gTtngA)9&F
zX}6Bp9HWjA`-sc#^jcl+F{^JR;Bb59hkTv|*Q6&jH04^hPJ1_;{)x@uxydcZ?9}d1
zAb4_QE^yg48@%iY%{(={JafYtT6o&NGWWD~CveBUHvgh?ec`2{t%ZlfCzoD!oLYNi
zKe_m}>-75juJg<9*v@VK*>Ps$L)V$r$0HZEKO4HR`Gxb!iLaekx4&`S*!jtMef#H;
z+b4gvK6~c(p?hZlfRRp0*a(aj?dYJ!IJ#NUPBb^sfo7+AdblYgC}xU{$WM0=xtUHp
z7wDu&fF822)J_#tyP2X|8&%riW-37rrWkBvOF$z$Ri}rqMc5>Av`wh)u?dveQL&of
zkediDshZ|d>e#k^3*Vt16nfManZr0FcbSI!?PjaaHDFP>hlU26mJyT7X|sA9_7R)Q
zJ?b8D`s|}4qjsNn-0ks9+dZzJ&F5bB_&iH)zi-*$_pdvGfxVHL@g4iz#GZ3$;;egd
z@|=5h_Pl*<{^ICr;I?NiaMQLmd(XYPa(85B`Tof9xreU(wTGj}*Iybv6?%PifBo%|
z(`#>!oZoq8^z_>Mj*FWgJFo11>N>ym#B*`?3&+jlUwf{f{MLQr)Q`67$A7gwb>dgg
z{d2#K-a82h_rchQU0w7DAB-M5+Qo@=W7%;oB>SklTae_za8gEkM7g6xakiT%%pIl6
z3f&|TaI8;K;iE|#yj*Fshp7bl*!`_eo~*+uRCl@s`Yx|b2OsIzq1_TS(bKQNxn*X`
zs9ei(>J4<a%EIxf3_`cjDst+~3a{Rw88g{+BPP4rH#}_cI!6ab91e%m?i%viM@M}w
z@7Sn&Y;wfop74#kr$;^Bxsj=<S?9Qa$vHW;?g@@>y61y?qf5c#?)m8x-r3nRzLntF
zv6bm-?v3EZ(XHUMv9-k;uJwic-mRtk&h5}W&(_+*(NoJWc}{J;>OHmnrt?(j4d2<V
z51f~dzwf)S{=W0t=3l+nc0M1wvi*tk=H6%SYp0%gZtQ<O_RNXzM{l3|(Rcs!uiocQ
z{_eYX8UXOY7zf;4>@ZIkBXShUh#bcWVn@-ugbB1baSYGN_7X%Hlf9BcH(8YLp$f}K
zDatAjOHn(?kk^j0RSh1#w%)^6f_-dF>o`x}Il)tROiBz$w^)lBmki+Daszf!X&{Vg
zEmV(ki0jdrS)(Q!*F7*OnbZ%9JeFbE#Gq3@HZ-bo504lpY|f!^hr>KE;;@dn-L|n&
zk9X4J@{Es-`6s44!SN~Y+~m~slGi^z?+pevJ+o75<1;hIC+7UeeT&m)##d+0co*g`
zj;<|V7+;^cKDIG`ZFDDeV`6vtwr6+o{`k)F{qa*Pe;hx)_0Y4w{p#eo^_M43ZoNK!
zcJtlIE1U28uI&HCdu9J`<JWfn=DoS|x%cYnzq@ble>-~f>^Bp)&wuB>d-k`nXD|FT
z`t0dnC!W6m08AkJ4g?U~@Bo$*H;oe<nL_d7r!kz=ak4ah8ZXG6CQ8#LXrhA2K1tyO
zRarjHR+UY26}4k5RfC_YtDWL&TYVf|i(jCGOi8rh>3(&`xY&T6lABOdY8`%3GejEi
zx6*yeA=a4M&JGx?+^GS(c*0=iO`As~lNP6XY;agHWwmSlLtfLAbHp@mcMtmAt`VPi
z)H&@L^ZF;oe7;F<z&APR_fL!mCMKt6r~MPF{<+{vAQ;#PECttnE5WVF`NflC3-hNY
zmuD|dt<GH@+g!dhzP)zCx4w2Ou)X<o;P~?M<EK`hn>xAi!uZL}S0+vze|6&A#v|XE
z&DR1KHy`<~?7Tm9dH1ir%R8S;T-pC(>el`f|1+naj6HSYiT}>|Z>R5^`QCT;(ywE8
z&i?4Xd-?xOzIYXIaJq|gXrfDaXu5|RJJBONGDVao1hM>MejGnNNRy{d(WJSv3}tqJ
zDg(~Yl*Ivt7C6z@UpC3@ub5$}Yo-Ls`k+ADG%eFYX5<5~S&11wB_G60sZ6LT#Q<hP
zXCVg+1C)T#LY_4a(*1e|*KZu+&kR{*!9k~N)?!!A42@`}?H<E~-KU?jyR1`AuXWZn
z>I}NPo@w`#d)5<}^iNJr&x}t`O-=*@GeQ4CaDHmVKObBPF3*Pii-GOgrTLTomANz1
z8w;oXE321hw-+u<?S`%dHkPkU?uBmpw?lXQr$W#A_creZPpmx`JhS(*|Llo3W-jl%
zJbh*FQQ-XEqlv3~@6B93@qz!T(~pB!&wU(t=G<pfx6gh(ee3*J{--bfYx0>3KTke?
z>BpJpulzLqhwHxvUbp}NOm}m_{YY-~0-hV??-9h#;AQavk}!3ySDZXgm81lzl8kw(
zykLQ*ED3V@3l^B_%4w#u#?R4J2Ka{N1>r#3EMM0i>^HZ~$V?q`(gB2DX+#B8W^6!j
z$IR=7djlF9by_#lH$Px!`SmuzjCEAFFyIi)*xeGp#oa&SaH^(<J^E>fTfg8OvrN0a
zgEQ{wp#|TBXWADW3yx3v0^_q&vy)R3fysb>ZpJ?wTv}KP&Mt=L=jTJyi?he)LW|q}
zjnMvVXytTZWBv5Z?)s(a^_A<hJKNW$_tvimc6M(Cj&DD^aBk~CaDV%Sg|oXa&7Ix)
z)AZ$2Zv`&zzA<<4)I0tgC*BD@b@IKL>-(QB+&KH`?2S{O1nyq^$K0I@PXc!@d>g!b
z?We%A7rvi+@$#>;FJAn=>F2Hj0JGgZz;d_X@N$nhc7`O1Tf{07mhq~@AWfRSNR_26
z^eHmu`&3!8Y<2z|TT?W{)ECdN^<{G$W8ETG-?S*zwap7mparp|Z9zH!TaZ~1Gb$@)
zNpHq1Xl*?U8ar{(G}60l86huQM%YVM8+Xy{6$gi$vIV=Rf5GNbE;vSY3!@X7CFi7J
z#xrgS`ligm@iEuDf5si0oE!^I1w8Y!^W(wknc2CynYp?7x#ij5?Be{~!b)&Hw6PRg
z+*w!&9iLlXJ-xKKdS-rW<-+{&l?zKdTbGx%H*e1DY+Ro?xp8Z0f8+k#sr~1c&h0)w
zb9wiV%a`}xn7MNN&G~D4kCvV~_h|9*>A%e1KKb7KQ>Q;!e(LhyW}dqARq)Q`FN4os
z`secVSN=Kw;PUqi4=(<^_=g++nR|Ho*V&hD001j^$$=$|@X%_nG-d&-h+874j;xaV
z6Bg*QlsQ&^>IzezxlA+UtS}8liyU>?0^3x+%-2;fN=&sYB6IVyY^ZrfVgfBIY_NIR
zFl<q7?Oaq3buH<Kv2&^+((1r4VZr30u3AQza|SPae!$6_A081dI9$Sc>u7&y*xkS2
z@+#&WUhR@=$~ZSMF|;%~>6rJ-I9H}-ouR3qZ+T{REHpjsUk=Pogl3n6OUny0D@!ZO
zi}TAXON$Gk`PIdZ`HhY3)t$97q3xCZ)!nU2q0OCh^V@3|=XSQQtn6*yoI7>=nYq(@
z&(2*ub#Lk1?sKbWPCQt?a^mIHD<>X>uAX=+bnV=m^G{uPf93Y2j~1W0@M-9&v!Bf0
zy82}P_Vp+8_bz@Nx_9-T%MUJnyL$if&r5&2{o~>bSASc6@j4)U9j83FgzrDN+N+G%
z=v7Cp(G*A4$?{|CR88s%TbsGg)ub=6ba^WbL+&QuSh&G8ly3-(HR}RHWk@pE7?PMl
zYtljRs%ofpMd^Sos~ymF^)TvxEt?$Z70W0kWN?#L1|9Sj(`etad7Qg6?B*}ICS)6q
zG3k=cD_eE>HJiS1Rmc~#Y>Wl0q47CO$Ui%@F*WDeoSpHkPS5$4=a#281Ixjcg{6hi
z?85xU($ezU;_^l)v>w_Bt*ozagmyO8*N(4jub*7mUOTgSa{I#i-qyv9Gbe7WojGx5
z_0;~o(5X{*H!dB2uzGR-g_ZOBe+pec|8V`r`PVnEoqZ#8<Ln1Zx6Z!3dHcc#>(5^K
z%gWQ&KUshJ;^(3JPkp)c?4>W4p1c0f<>zjHyZ+$jcdIYm{AuOIXMSD#;|%~{l`H{l
zlT~3`Bz5ctQ5hNP(<iPmmGP@g)v+ChK5K(DkhjIu<!+121#4nU@g~n)u_-c^t;($p
z>q>Lox@5R{OF7iO-ai7`QCXpz1{Y#O<L+70yL#3JM$xN-Uh=xpLtP&lp@)V&+->VP
zZ*ABk+;L9wR-HcCs(W0q<@IaUypx7)Z_p4L3tDz2<_1^C796XyGwzT-=nTy+dp8yq
zrnVMC(`)l<)0>Nn^Xm(1%c0QP=EmB_=Fa;1&gSm!-s<+o$<?i`lRNucXE#sopI<w(
zeR*qd_vYHUooCiBoVd4j;pDxw3n!lsUEKe}#^nnSwx7EA^4gWNudZLe@b=ENtB=;7
zKKDWB*^7_Yp1ttV_MIz_x9?wivi{)K-?yK;`OWHso8PWIy!GAMOV9ka@zTxTcm8na
z_pLYX0|4v2+JoB^P1Gh$8Mi@I#O<=wvD<7@{5o5ky3NvN?C_1bn*v?ly3ky*!7~(W
zNC%3y`UlIlWP??ka!dVg|6tR)Y@~fhKMdZ~IuP6H5yWwWyKBSjMQ>QfNZUj1-s5IB
zVb3u}+jNf6_C~y{ZO52s%jFjyADNbK`}~Sc@0@1GGo#=21_n0#i^k*A^XB6d^UhuW
zvTN7BG`2Cj<lS3Zm|kC5n%Z34^dDc}np+QrmiI!T(Dvr`#@5cp#_^4f6C1mmC;qpM
z6UWc(?VY%`clyNT-BYJ-Y+u;Fas2d&``hQvzOZxY;=S$b=l`&C`TU=Du3UO`<JRTZ
zw{Bd0WBulpcaJ}F<K69NFaCM`{?!jRp1Jwi?w#A8?A*Qm)yDJJzS?-{`nP*8-uZ6p
zrJKL4zk2uIJFnjUZRd^W0Duz&MZ^|C8M#Z*MW1A;6Sipjgp)LL>K4nAy3e*GZwpPi
zC;9(hhjif|cVRdTI0H6{jlMt`w!tV2##(f&*jVXsDQr+^fjZUHB2D9-G<vznCAs8s
z?(VMNb9cYo<s`Yg<l+|(?eDYqUwA%G`BV5al~3c&+;|p!uKY#Bg{r-n3)Oq!g;lR&
zE>*sTxm5j6%*FbD;VxDG3t3Wg09jOb0Cm0Y6MRv_SLho}-{2}*zlT>ge~+tcJ%XtP
zoxs%hoW#_29!J%6okq8IU%)hgE+TJsm%!V>rPvNo8M0%b91rTRz;q2Z;d_Sa@SwpK
zbpJ>jZg8**35E9HpwI#Q7;Fd!MGvA7$WhGL7!r*@;?Z~v28Tisu|y0LLm{%!R3aBk
z#t2bVoCr&%O7S$3498%ouzZ>h&Zp_&EQS>+;JDEOjuR!Kd$2-g2qED_F)~pMsS+eG
za&8u{6i%T5@jOl=Uq+hcd4xf_fwRfiP)7AS*7E-Wi+_tcboEa3k5}%)A1S?$_|w&g
zNr#IbB_1n#6nnJ%3H0fz$I!<rpTr%z{v7sf^=|a}iWi8dEB=PRShWXzw(b?em8y5J
zMFA!u+1^d>;fovI#gx|l8(&)Y0j{X+Gi+JI=Y-0RFNif={~=U$eM6|dc?eh0^%JQM
zd=y>Nae~y;cLv?kdmhsUK8tSYzl?3|yGH8jFCl>kD)7C~YE;)q4XPVjM+A>FqlZUY
zNl<tPY82T{7=wbaLt{O-VRSD6fgHiY(8DPB|KxC3G@5`$kuZ1^mO#c3@l*nx#K%!-
zEF6h0#nYJzB8#phGT0idfT1RFxfYy&ZNYK*Zk(KD$I7^Ftb`vTs)bRMiXTP+(j-nT
zO%m0D9M-7F;q|gvlv%n+v;b>Z8?cJAsW)&Ipx`&uLq!Fo@2=lL`svzzl*2c6;*OQv
zPx!fL7x`$#BjnSie<Yu&d5n0X@=5Z!>ObQy*1teHQ@00qzIG4xO3hy4)#g{R7i#z6
zidx<xUuoQrzt*~+TGIM4xv24TY*p(Q*qXL4akX6s@zovQkScqQ;H!ELQ(M4?Ne$gc
zNloBiNG*M5iEX_X@hyE<aG-(9<ZehQwRgA#*Ed>?>xR@42BD3(;n6xObhHUSFnSX=
z1aBk5$GXYGm;o#dF+f0J2Z<OY0*gYzu^1edfW;E1I1&X*q|k|YG6hR!@NiV35Km)@
za164Pz~ZP$9Il2Spy{X*j)5#;7;${AgQ^rcC~|=luNH+VQo%S?%S%x7iX=rVn<8iw
zlLQkmPu5G9$R_0?(J9}+In`Sfk9M2v0SXEzhp*kmIDGX^;typzm_L-=Lp)M(Kk-=Q
zADE|V9wD8o+(kKE`vmh;{hw(U8=hvKZ+L-nuIaDjOLebMuhzdzxmfoa<!bBe%quN#
zQcG^WPbzObKq+ebH?yky0KNR?7xWuFUs7s1zogao{FmMU`j*iG`kCC=bA;XmIZkZ?
zpP{$*oThg76*9Vq&okQ~ml$BkHDVXEn9)CagV+Ntr-R{jjDAEN1&VGVLPlFjLzo^S
z6xBt7BL^rL{2&d1AEBeLBTN()M#Ez9WFis8Bv6SI5`n^C(r9!#nNDT0xpX>5N@g*Y
zbS6v2;P4d`G2ckxa&>e$&qS5-Y($aB##9JgM1U8h0)h|;kj1GQX^de~WoUX}l5Upf
zh&K5=!=%iUE$TeQsb8ae)wh{;Z9xI`(DmO^kCfcOJX&=R>&NOHl%th9DL+*|%062C
zDEmb96V%fU&(O})Jwv@v{T$<L({uC-jen(FZQjec*zh{1r0F&KmDYFY*Bakql(znh
zQqgvRS>F9VtE%H8b`AJTPIb>gN<HWcYHiOUW()XxW<BUArJ?@_y`}FIrD^yKtz+Oc
zy>0js4Lop#+BH;2>m4a$^bTF8f)SOJepC&!f258&469|0!5b+<s5Ukn-NAxkdnpKf
z9~(jF<>1I8bPQpXO(c!cF?1}8Lc>w<G!mP{qO)jZ7M;puP?!uBmB$m%nG7j~!vmON
zj+V;j0xUjT!%|9&G#TGXR|~yNmBLL|%0q0uBurN+BP_Ez!7^wvbdz$LZBkCt?V4q(
zSv61dXf~L3<0j2-SZDYx1qJk@CBJ1Kt=K_7TzN13=#3rR(^WeeM{EATJXZS<<4ol)
z=7svlnP-~+$SiDmhI6rLH{)XC9$sP7OU%oSf8$>5c#VFw^DRbk=RcXH9sB9mdp_Wm
z^?b;yX#a#!)$s|x2J{uZ4)g`R5qyZ*3^~kd10P{F_a3LW44mS%_aCQs^`B*f2hXv(
zq1QM)@FL#8$W;ymTFf3oU*`>BDw+L=dhQUqg$+fu@W&8s3>dM4g&_8_;g}vahTKQT
zQ6U^GVVF*$jj{<O441}0@o6kFi%g|+SPUAI#^SQrOcsm95OaiFDO=1_GbJK5Tg2Bg
zm3%E<Brx!m3L6g)dzl)!hid?W3^g#$(8(eUizdM`>L&RPeVS!bXLvTv9LK3&p!*EV
zY`boY;nLk^2h9ZqoTFuTa*vkXDLPv5JMPc54{}b`JjDB@?m^zUs$Igf&3_b}Z+?t(
zzV1okxw=0KuQWZ&z1aA?ps4Xh*0r`hyprzM1m&%7v#)o)%`FGN&#3_);Ma8T7nS#Z
zBB<&6h|>uAj9mvlC~6q|FTY{<M^@9o&z$!D!`#+^6Rg&;vpf*&G`Dl?91k>hRoFdR
zEa(|4<@6!T1bwhFK4h$t14TEnNAR^mB&vmj!ncaXupJy2wugrzL)aMV5RXWLa4}4%
zfIx%sXe<<)O2hD2Oe~khW$>wVDv!?O@>l{Pm&fLdI6^Up&y$KoA_ZF^Q?r$FEk`P}
z3RDuiNF{ZPG=Ptz)A$8CMNp(wMg@9ZOkmfi*mixEYgf;5UFrpv*R;yD>sPr!(;6@6
zxW)P(An$lx0r%(19lX;O5AaSk+%G;|^N{dV-6O&?HGklpX?;p?uK989rPilJ7h0ba
z7dGw|mfU<^bfsetulVN6;v1mXB}F}N3(9-m=2iB*Ehz)NFR1G}AgTd>#IJ*V#ccwA
zDQbcIM|^YWptNE5J8ARq_u@|I&%E}L<Gk+Sll)%fS#dYwj1+{tCLS0q7C<ni(ji2-
zWE6E>JccXhLXlPCVQixShHDlhu$??Cv0IF$^l&lsK?#X5#G_D$Bv>j;LSmyuR62^!
zViH6gK3T}%Qp9`?mCqINq&zWS!WZ%cVu_R|kV?5CnT{({YQ$=lk*`o1`6{)G2dJG=
zjlv_<YQqwv(l0R@;$jC7=bQB@u0x%b+H_fg%eo}6n-{r3M_%Z0uJFT-TjHpt;4a1S
zir*=ZSM89VY`j}~y6yq#*~SNir)zgfPB;HSa=z_J+2yuBiLc#!R(_%5dD-QT=Y+*K
zpO+Qid{ul6{EDo&>s4hXXrJtQ-&>L!{qITZ1`dd8!25;OJ)g+x`@T{%K)#VSLcf-^
z_kSmDAN*0;1v?~c8$BTcjT{q!M^DN6;1?ti*m=nS;<9vj?2>!{S0aI;i=;!uYRM43
zUJl3ADiD-L2@2b$MAO>EXkw2T$>@~h=@2=V2^ACRgK{DpsU)#R<#Yy4PT^n`G!{X`
z<dcLf4n@uuazrArP|6hw#WJx_Ay=p*a*0x;R_KLNz$8?v401qemuM9}sZQY)YYbtr
zQ6H5U)Cq}27gahfX^C4qBlGEU5|@2e;xw(w!mc%G(3)3999u%av)~TJ$=U+x@uuG?
zf2n^!ak6QL>|EV_%G0g86qlPGQJ!mjRDQMNPtu~+-O4LBcT0*uFG)(lF9Jm!ugXfh
z_NdA_-&E9ey{;%9*e9#&eMee7@Sds>@}at=?^9(h<TG_W<V$%g<O`s4?7z~Mk?$p)
z!-rID@MF>r<Y`qe=A?Q6eM$<#ol*DU3Z+owRoMXY3NVVfp&r3ks$j$##VDyx1tYdf
z;DmMn#q3h!7~KGd(XYfZ!EzG4UqNFHt7uFpKo`K}bUs$j5aAVE4pzbyG2|RELn0J0
zr4lJmEmR6rN|iz(7OMccS|I_XT9r;^QECB$RHtz%j4H2Er*lcITA$iz46Dq>sN8Hx
z0#3^$;4n=B9^<?sXj+zpU2}?%H81nKwxu!0nqtCHPyifjxI=Zk<zC${P4{aqH0@Ad
zym_DILennIrRH5gVdqnd!tSSm!p<j^MP0iUWuV>4(!M>)QqW)36<x0@s`~z}y3zZ#
zrmlCNt`7W`ws!bkbp!MxMa$sl>eiu8wJorNz)k2kx)%5$ZP&;VpbPe+rUP?C*NZ)>
z>&BeW_MtDRhLIOFgTxD(VO+5aM!ceglgkw_Vhu1ttyaS64LTI94#1Eb<VbRh9K!;u
ziHtrqmN^Je=|fr)YfM8EBIR_>n3BrIC>dO|nj^vL_!63qC#5OGQkFs{XDh@Kfle+L
z%H?V~pphx$a+ON0(i;FZU<Ax6GoaHs0fW{hH|irgi#{y38e=+_aZ2qnPH7#M9N@A{
zYeJS8W!RmUM}6z+h+|z9bZ!D+SHT_XQ;l~3XX<yTE;jy7bGrF{!<n|7z{QS7)fYg2
zP#1MPX}H$$wBa)78GUKz3#zj2=d@*A&jS?$do?vZFKf$s_8Dq=Usu-;zpJeoc*oE@
z{I0qcdO+O>{|sn@e{5(&er@a;`%-li@tvw2@vRPwK4j>^olx~7kEy`;6F@)V7xe)8
zEC3;028PHbDj4}XFiI>|qv+*&IHS%u#%$2x*)3``r$I$vc56v=u#U<G19VQ0ioxwQ
zvV<cVju4?{3*dUL7!UAxc%x8?Gx9`C6;Dpn31oDYSSHeoHBvnw7wVN-i9xAWs<j5d
zpwnqpdZSHa)YyzRlgnV#xiuD>N98n+15RgD=eA9%eU?ds%aYZEZL@l>XHM;RFBt;f
z6;&*_4McsnwBw$F0?qlR-{{Xa-K#&_a<A!J$4+fw+k@uw9gi3<bUa}wZhzcV+V_P1
zYS+`+YkkjXi+i6pltKPxE`z*is_A`QTi*AIzH0bwW8>&srW)uw+NQzxE%mT}>uw@G
zGPJ=z)^;O4HFaSAV*!o**VutQr0+xisDWUQ>%r)g8VLTlz7O|{VU%#rGK{-mhEuK>
z5X3SIoKa#NqgELZ)M_1`QfI<38Z9Vpn}xt=H{n=d9f{d#VX}M7OwNFw!5cJk1aKoy
ziZ%*m2%|uOH%UZPvp`8U$Q3k$T+Oh^Ra}h(;OnG1kqJ-&7L`G6R_S#nt<kJE87(H0
z-f4Ci>=vWNt+klEMz>|$=(b069!tvX_r&!+PfqJ~W;ElD1%1@DVhDOS3=z+!Ar;y*
zM8gGlT2Hm#Y5b+-cjn8jJB)=l?{{44c))(G>mk#%j)$$qollvs_dj910eaR_(f^#G
zyzejO>wSBTRggW_O32Ih`r&=Hdg$xsmf?4-4bb<EjidW5t)m~BJH|dXw!uEL-^6@w
zX+!+i(S!Zo-h()7?neJ$>BIeO>BpS34U<orA-G>mP~th$80oxuly=nuXB63xj1n`F
zaovt&SDTUCIs=+fZzQqW93*as1262hkU8BBDhFhzN`{S8@vws<N7#7MQKLYKHgly|
zlR!>2%al~R5};WWTAoF!6PV;mp-HP#+5x@Vsx_*NI<v~5vl#4VtI=w6IP4~?+u(Er
zEq1rZ=(L0ketXmua8Fo+&bZz0%Gm?KjA1;mY>WGr4CCQ-Tg1C&nFwr{5|M%e=XucG
z*2`V@y3cpt<GKR+y`!jir}a|T!<N#nN3ErxKiJCqo^cn0cRNe_o^w_7y<n~#e%@L)
zy4O-W_=c+i_NJu<vCrB({1036$bNIn$iL04=nrhIhy(Uc<j3Z2<ma{y<kz-t<UwZ-
z;Ri=Q@sN8Md)xsb{N(H>owAKlPuWIj7i^=H3zji<p%YFoaU$p?b~wA*f#udY(7YxG
zj@RhKvKq`(PN$15?sU_Hy-unG;^s;Q9c&52##4+qxGIEGsKC3q0L~!*C>9AocPO+h
z3!r6~)kdCGq2t+fYN1=Jk=e8cl~t$LSglrr*=#XeY-WeU?r@teR*%)@4!gbXh|}eX
z+Pt2mE#OI7{h=9iAdq#2!%OzW_>wslT6Dw$Th>%~!<vZ~{KkF>e3$z&=pNtI&ima(
zpdFrK@PoGN13P`CphxUCAb+&q7<k560om=nKCs(YGyJT#c66`37PiM(GxRr4^VmLT
z1MKhKdc@nlcI11GX5>G;H&GwBJFx$@fw3QXyK!H6K&XT6e$scgKHT@dA?%O7e)5m5
zLHbEMjP#3rgmKXUrJZq&aSFYooDw&TSLVa<D!fGQ4L6Eg<G^tmT?BrEht6rX(fK#M
z3|^;)ChBu=6%ZRw3iWc7qduVuY3Hd>b_sxY$h9b^P)D_kRTLLs;CSVFj!UiO+YCmY
zPiGOi^m@RpGplW8o6c!5X*^D|-DkDfy*8`M;dKSvZdb_Z^M%}AU)&e)#@vx`+BF`@
z*~Z7Su4rV&J`r7UC&J5~WO&t;iLKjG69onC3thkUU+ulebqV}{?;7~`fnv~ofl}~;
zt}@7Dfuf<u+$DWad&(eBddmi%3Dgb05U3b=(OEnEs=opLs;_?Z@7~7IH@!`;H@zLG
zcirvi{eceDem@xXxv!J>nYSDBRRE0r!renY=!4J?`vxgLc!rrrgTwSw&Ozoe4}x~q
zJIcD?ALU$jA{m#QI7UeT$*XV?_~l*_uf|W|*9WM=1~*OA;-|^m{A^)okfZAIbHqIX
zzI@0lki%SD&9IBF91ZXlIHz1o@T!cYph8FUt4u79+QJIx3?iS-B=Q^05~tazb{nl4
zx6uYTjaG}-<}tW!cB|L!cey-HugmH8xPt+|JLrjeeg27{Kag?<0~uE&Htmna7hSRO
zRd0GC@0*Nldy<p4eUqtzyF!JayTccH@9`B6JP;}#+z~1PKNKt<e8f}IzbjNZ__)7j
z^iP4>u|IigN1ut*A)fP8kG|xuLA)4jM!XSd7~2<aK<@K)VBZRL;{NFe;oc2`NFRhc
zNS}H-37`1}2w#VKDc|~f>EHYNNIwLitizrW=HcKF{gemE{3Q&d{}O<4FGo<ULJyi#
z=qK`v{3K3=hs3WAVx`qyili<;m$Z0U!j>>c+V15_+I=iZw@;`5d-<AyAYTXd@YRT*
zKnoAcRrrWZjq(6SY(Q=xM*suOr_nP#8mlO%wQ~JtlgMweC<11?+GBI6f=;hK<nUNM
zF0a#T_xXZ8x6AJfhe8o=I1n07`2C@nHyq9cWAPbJBr+X}O)UEpsrg7cx*VFG+76}D
z+ku%(K|$ym=(mxQzPrXt`tA;08F(O2()UobbYRzb>EN#M3iwlzGU$`Bdf1cEO2qE*
zM%c5V#<9JDX3Q&*R?HjWX5{OEHtbve7UbLhHr)P5H~GEsF470VPV%P#F!9saAmxj2
zKl2O!AoDx_AoECgi2Z|qi1kwp!9Ed%vd@MwytCs7R^d2WbTLTaUI}1@*Mm4wQ3xlh
z2@nOfL87cN!2I7npf$*rb%uG0&T*y^9OP>uVTp3c&(n;?<iJQ+tU-<|^+><cND3=V
zlptWH1yoi_SYxF7wRTa^WEMwFPG!vO1;$Nw`MA>u1e_jI#NjbV{62fg9dZYKK~KyR
z@P<R7Kr|MJ`X|OGV-w-Ya5OR%h$d$P$?;q$o1BYfQ;UIAVm&mMUJp#C3+{?t9=tPI
z(tlUtI^_P?_5ORKrGvkZRE|BItcE@ss~mkIUOx6%ycYRvyb-=T+>Cub(TIF;q8YU}
z)<}3I(MotF-hzKU0>ZvC(T#a8(t+Eb=qG+029rLFKxm(Z2dSThp_FgJ!}M>GL)`BY
zaPFZfoOwKf5d0KFb54g*+zSz$s4$M^Uzxy*E``bBvIJFlJx-LD$EcE;ai+8>$yT)_
zX|l!%mb_)0uWe8ARNWDd7Mu_p`@>RTEGbvR!V1%9LaoP-OU<a5+CmDeP2{-I!HDZE
zjF{QV4;$UmsNE@vTKwv;!>dYIJi3U>V~+UT)|l6CjR*X;iEuC&9uJ1c$K$bhWFnb}
zMB>q8GL?*tXJZqSbK|M_e0(Y~pU5UwW7E^?<FnJhPGn~a3S!rwcT8Lv`dzeW?7sMo
zk)5$J_|8Q6=&nQs;?ZP1Y*)Mn@$^Ik`q@}B>V>I#%u5q(gcqh-Q7^}u(Qm|W68;|V
zCcTwxBfK*KBD^)xOFIw+(LYM`(LPBHvp-8h*k2|FIN!#g+(VNv`gd_C@6hCk@aP1R
zeKG~-pN_%>r=uwTnK)K_HH8xvPm(1iDVnS(L6lcUnexgw6{w9-wXI1O&@#nTwkKK2
z_N2rBP6z-{N~#%5O7(+ri5`|zTVM&94IR^3PzkLS8#B6y39XYgVezmhEIw}B>J`Ur
z0a486R7E|0b=>9GCG37v%<H!$d=YEH8+1j-qru5g)E5s;_+#-%EIu)joSaN#Qt7F5
zBA%L0WipG=snk+@D!CS$%WX_8W`9jC&lKE|xdOc_T{?J2sseWJWa;od$r{-2vsJJM
zllAb2C+lF3#p_Uy$D6Uwq#BTaNi`97$J<bQvYqHxk~hh(#XAXaraGznG9A?SvYn)N
zCi__*Bzl-1P7Sg@P4#m=P7U$C$_(=kPQiHx6L8^w(<tuI^qA<U^qAy$3duhk$H^|F
zQIfM6oU(8dt0<1s<ku&O(&8zav@*+(SI4Q!`UGE7o8<w`S&^zEDblwmx%&RJ*aFT-
zt<Z$j2Fs{z$hh1wmQk4Calnp>>#ewi$xX`Yyo@QUpFL%F@KbgVf70fc$1QFk<?sP1
zzt@m;`gHMd$efHsEvab4l@3ROiBQBp6`k-WlgV&uDm9r(Bqy_}sp(`on@wkv3+cJc
zTxNP^b#iuUB|bO5mYvHK+?6dGE|@GH*)ds$ynCv0<biC(=>MCpLhVXbA|9TqLOeQM
zgLph!k9#Uzk9#50M0hFNirJfPp}siTO8nbYH~F<(JN5N6nEYnCm-)}!Ap3({FZaW2
zANSLlA;uRogWNCEP~q1p1nb-B5y6oxn)5>nE<Qeu5uHe*1t&6i#V<L6`1~|kae0cQ
zx{_h4%cd!^qDi)@GR@G|WI4*3EC*=J3H5C$zNU4GtLw?h4E;Hosb@xP8%j%zgE^HG
zmXh0H8G{EmZFFF!)J}ZLXs1pYJ(R57!%Lf8{ERs$NO=PCtS6+HcK8%Ik6$|-j2JSZ
zh&An>aOOf0?{qlnNhPMd*?1zHOU1`C>FmTzYC1ig%4BDza@m=g?EFkRvy{oruFcHm
zwp00;wV9<{LBVVh?Cx~Q*gfeg#C_9MsQYFs&^vRLxSiAWgokJAiI2`Vlb)V##ypj2
z!#y+8OnElbN!>f!P5Ik&C-dd$Uh-?XZstE`K&*dE53v531=HTm4)FI+L%9E*A7g)#
z9pZeN8y0+#MR2~JLrcHQV)#GIBPBoP(9)ARg5rPk&SpvSi*sbvr7RIB%rNC;vs9ow
z$JAEN@zoWxEMr5Cr)!wyYTGkXU1v^g>z+|s`(|X;foX+hFsn2}r{xydoX!QyYV6po
z(TSZmIw-R?KV!}kpv{<r^o%1Snz#D-8E;59?Fs`k!5}abjH%P%q;5VKv1k30j_GjJ
zl^dV%r4wmSb|N)CJCRCGr)J{W<YXqD$<Ab_rqi?2nfdf|b~(2+y^@_@+MZd;Z>3je
z3+`Gjh2K3}4!>u<7I*J_Ir729dc@Af8uYG(TEecm7SdDmE%-k!x8R@3wcvNpv@)K{
zwUJ&}0+C*vZD;J6?dH5W*F)Pk2jacGFu>WL>u2s?f^rTlKm;Ey3~@eNM)JO1fQ!Ff
z9OZvI1D772!6|>7C5V5X$IDL4V`Rsc3DPr5RN19PhVtSZNmaPS)|V~O^rZ`Q&GluT
zwtksou3r-9o0r7KmK@*Ix+phx%!n=hb8-u0QRNy~lG}$CG|tg^y&E>C_TZN^LBgWm
zO<J-9D9ctaXU5@WE;z#6oZBy2aD^p{?x<qUKcUG5V(OXkxM?mtY0FJa*yp23_fjMk
zTu5a+%kjzR%v3g!o65wNb2Ev>nOtrmw=h35mz!J2<rWw63rq7$`TXoser++oSWu9!
zz!uC^VDHXXVSYPTkK3_WgLyb#k9laR75{j?mHNa=E9Fmft)xFLv=U!f?Pk8T*v@!y
zxr_7iN+<V?6)@|~)n5J^^MmYn^8>7RRtEX+&5g1@ULN6pzA_^DVrfkF%^X_%<s4G^
zpJlZ8yA_P$=n_Hx(;P;9d=4u=zCzQUT_&pwS1E?ea~y5SDob6I=jzLsIEJ!$p0;L*
zW2&Fynws-sW9zci(Y`3N_AJZnol9z4{|ew3p4T~t@;WDUQSTp{Gr5tg<^XBY=%eIq
zUizv%z*=^V^YZo(d(M&Iue!$NtNy5TE-<NG3Qg&kqDlR7Xwp14o-r>Zrfn;!8Q;Q0
zI<lCW4lT^gjnB`drxvpd*_FA)Y(6_Ty}G=xw6M6iw6HqAwz#miHMh9DzPzzsP>?Uf
z7p&G`?pdnG-@j5t+_~0*`~6x2{-MR2^j*ts#K)G~n15Ptr#-uNll=5j5A`pLVCr92
zx|uKMLEODdVAiXPVAku4{erhw`q}TTj!E8M8RdVt3>SU8G%ERM8K(Gj9WMQ95urM`
zj#3}V<AI~AB=t{=1l7;$H2v{alHpvQrYc;d=q|5tj8~TFx@#*eWAVDkRIwtqS8NEJ
zHH$)P!>Y{Po|oF%R#djmRiy`%*Eo8Y^a02^;2B=lgvM4hA<VKRf?qL3&})t$Wz7<x
zty+WhWyd&c#TVnQ`6GhGP+Ytgj4L-nN!>;;u3rnqO^b<)X(csjSxrv*))HxFKAZC|
zPEH3Fv-63i+)`>Ow~$(!U&^k}FJ%_<i!-bFrIq#hwbhl4{8oN_bA5Sjwct0~HH16Y
z>WTMm)Zurm)DrK{H<BODx6yX3HZq>rYG*yM-p+Vzy_NIib{pd_t3CAR);n1*twK02
zZGi<ZZx6BmvDGj7#}<V5*2*aNofW9yy^RsYfjmO=(Kb^0<<^+u;5I`3^(tER-4;f5
zXbr3RVS}tamZxb?<r$ij+jQgU4T|yX7Ta=dn{FuF<{PeVvaQ#*x%RScp1FQqY-?PX
zxa+s&w)PFF@8+h;*}krEg7ZozWL*~=+%$!T)-3_py3P;VGzJiPv!Afxh-0^16U@9V
z%FO#xjLl$@v+0d;^N|VVihokMJw63&L^Hr<IBnXR$Qm~%C*2#VDaTrN)|F4^!do+o
zq4nwIWInT;+*(}7Zp_V1ugovcZ7i=WY^|)#uWYO@=kuFuD_a|D+uOeu+_70t{>`l_
z!j8=b;*Rxt((l(A8TW6sP<GvFXFqbQo%z(QF4hybK(r@+?O{K&)-QPWR}gQ{Z7}=Q
zUx#?FZbKyd)*;e2euYT?u|6b!cMYm||5upg{Y|v|(`~rwqiwA6%U@CIgWG8Jcbf#o
zp)HE)&@CEpe1oJtc8g>@w#_h}zRfZf-lppc*M;`tTWn|XZJy)CHs4mhDfLuuh}`wJ
z<+l1Yz|pj=^0cpO0zI1=SKn=Qa9~aC9o{empc|G5bj==sZJI-fTh0h-%Mz#Fa>j@o
z-YDnSK#X}im=xR!C%7AtgnWBEqrMf(YS$t;)p{al-b_syw^M2N)?~)JF*)bjn4FFL
zI=kS%on8uW&MZbZ=T_5exz+5}((3f)+WOqq#^%E9&8@XxS61`e>l@p*H@5x{se}NN
TQ)lJ100000NkvXXu0mjf_`5Pu

literal 0
HcmV?d00001

diff --git a/core/artwork/thumbhash/testdata/gen_fixtures.mjs b/core/artwork/thumbhash/testdata/gen_fixtures.mjs
new file mode 100644
index 000000000..b2e488b51
--- /dev/null
+++ b/core/artwork/thumbhash/testdata/gen_fixtures.mjs
@@ -0,0 +1,90 @@
+// Generates lossless PNG fixtures <=100px. Run: node gen_fixtures.mjs
+import { writeFileSync } from 'fs'
+import { deflateSync } from 'zlib'
+
+const crcTable = Array.from({ length: 256 }, (_, n) => {
+  let c = n
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+  return c >>> 0
+})
+const crc32 = (buf) => {
+  let c = 0xffffffff
+  for (const b of buf) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+const chunk = (type, data) => {
+  const len = Buffer.alloc(4)
+  len.writeUInt32BE(data.length)
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data])
+  const crc = Buffer.alloc(4)
+  crc.writeUInt32BE(crc32(body))
+  return Buffer.concat([len, body, crc])
+}
+const png = (w, h, rgba) => {
+  const ihdr = Buffer.alloc(13)
+  ihdr.writeUInt32BE(w, 0)
+  ihdr.writeUInt32BE(h, 4)
+  ihdr[8] = 8 // bit depth
+  ihdr[9] = 6 // truecolor + alpha
+  const raw = Buffer.alloc(h * (w * 4 + 1))
+  for (let y = 0; y < h; y++) {
+    raw[y * (w * 4 + 1)] = 0 // filter: none
+    for (let x = 0; x < w * 4; x++) raw[y * (w * 4 + 1) + 1 + x] = rgba[y * w * 4 + x]
+  }
+  return Buffer.concat([
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', deflateSync(raw)),
+    chunk('IEND', Buffer.alloc(0)),
+  ])
+}
+
+// A ramp has exactly-zero DCT coefficients, and a zero coefficient's nibble is decided by float
+// rounding noise, so no two summation orders agree on it. Dither gives every coefficient signal.
+let seed = 0
+const dither = () => {
+  seed ^= seed << 13
+  seed ^= seed >>> 17
+  seed ^= seed << 5
+  seed >>>= 0
+  return (seed % 9) - 4
+}
+const shade = (v) => Math.max(0, Math.min(255, v + dither()))
+
+const make = (w, h, fn) => {
+  seed = 0x9e3779b9
+  const rgba = new Uint8Array(w * h * 4)
+  for (let y = 0; y < h; y++)
+    for (let x = 0; x < w; x++) fn(rgba, (y * w + x) * 4, x, y, w, h)
+  return png(w, h, rgba)
+}
+
+const gradient = (rgba, i, x, y, w, h) => {
+  rgba[i] = shade(Math.floor((255 * x) / w))
+  rgba[i + 1] = shade(Math.floor((255 * y) / h))
+  rgba[i + 2] = shade(Math.floor((255 * (x + y)) / (w + h)))
+  rgba[i + 3] = 255
+}
+const solid = (rgba, i) => {
+  rgba[i] = 60
+  rgba[i + 1] = 120
+  rgba[i + 2] = 180
+  rgba[i + 3] = 255
+}
+// RGB must vary with position too: a constant color composited over its own average cancels to a
+// flat L/P/Q (the bug this fixture exists to catch), so pair a color gradient with the alpha ramp.
+const alphaRamp = (rgba, i, x, y, w, h) => {
+  rgba[i] = shade(Math.floor((255 * x) / w))
+  rgba[i + 1] = shade(Math.floor((255 * y) / h))
+  rgba[i + 2] = shade(Math.floor((255 * (x + y)) / (w + h)))
+  rgba[i + 3] = shade(Math.floor((255 * (x + 2 * y)) / (w + 2 * h)))
+}
+
+const out = new URL('.', import.meta.url).pathname
+writeFileSync(out + 'square.png', make(100, 100, gradient))
+writeFileSync(out + 'landscape.png', make(100, 60, gradient))
+writeFileSync(out + 'portrait.png', make(60, 100, gradient))
+writeFileSync(out + 'alpha.png', make(80, 80, alphaRamp))
+writeFileSync(out + 'solid.png', make(64, 64, solid))
+writeFileSync(out + 'tiny.png', make(1, 1, solid))
+console.log('fixtures written')
diff --git a/core/artwork/thumbhash/testdata/gen_generated.mjs b/core/artwork/thumbhash/testdata/gen_generated.mjs
new file mode 100644
index 000000000..e8eae585e
--- /dev/null
+++ b/core/artwork/thumbhash/testdata/gen_generated.mjs
@@ -0,0 +1,28 @@
+// Produces generated.json: ThumbHashes of synthetic images, from the vendored reference.
+// The pixels are a pure function of their index, so Go rebuilds them byte-for-byte from the same
+// formula and only the hashes need committing. Run: node gen_generated.mjs
+import { writeFileSync } from 'fs'
+import { rgbaToThumbHash } from './thumbhash.js'
+
+const COUNT = 300
+
+// mix is a stateless 32-bit finaliser; Go's mix in thumbhash_test.go must match it exactly.
+const mix = (n) => {
+  n = Math.imul(n ^ (n >>> 16), 2246822507) >>> 0
+  n = Math.imul(n ^ (n >>> 13), 3266489909) >>> 0
+  return (n ^ (n >>> 16)) >>> 0
+}
+
+const out = []
+for (let i = 0; i < COUNT; i++) {
+  const w = 1 + (mix(i * 3 + 1) % 100)
+  const h = 1 + (mix(i * 3 + 2) % 100)
+  const rgba = new Uint8Array(w * h * 4)
+  for (let k = 0; k < rgba.length; k++) rgba[k] = mix(i * 1000003 + k) & 255
+  // Random alpha is opaque essentially never, so half are forced opaque to exercise the 7x7
+  // no-alpha layout as often as the 5x5-plus-alpha one.
+  if (i % 2 === 0) for (let k = 3; k < rgba.length; k += 4) rgba[k] = 255
+  out.push({ w, h, hash: Buffer.from(rgbaToThumbHash(w, h, rgba)).toString('base64') })
+}
+writeFileSync(new URL('.', import.meta.url).pathname + 'generated.json', JSON.stringify(out) + '\n')
+console.log(`${out.length} vectors; first ${out[0].w}x${out[0].h} ${out[0].hash}`)
diff --git a/core/artwork/thumbhash/testdata/gen_golden.mjs b/core/artwork/thumbhash/testdata/gen_golden.mjs
new file mode 100644
index 000000000..2825e0709
--- /dev/null
+++ b/core/artwork/thumbhash/testdata/gen_golden.mjs
@@ -0,0 +1,37 @@
+// Produces golden.json from the vendored reference. Run: node gen_golden.mjs
+import { readFileSync, writeFileSync, readdirSync } from 'fs'
+import { inflateSync } from 'zlib'
+import { rgbaToThumbHash } from './thumbhash.js'
+
+// Minimal reader for the exact PNGs gen_fixtures.mjs writes: 8-bit RGBA, filter 0, single IDAT.
+const readPNG = (buf) => {
+  let w = 0, h = 0
+  const idat = []
+  for (let off = 8; off < buf.length; ) {
+    const len = buf.readUInt32BE(off)
+    const type = buf.toString('ascii', off + 4, off + 8)
+    const data = buf.subarray(off + 8, off + 8 + len)
+    if (type === 'IHDR') {
+      w = data.readUInt32BE(0)
+      h = data.readUInt32BE(4)
+      if (data[8] !== 8 || data[9] !== 6) throw new Error('expected 8-bit RGBA')
+    } else if (type === 'IDAT') idat.push(data)
+    off += 12 + len
+  }
+  const raw = inflateSync(Buffer.concat(idat))
+  const rgba = new Uint8Array(w * h * 4)
+  for (let y = 0; y < h; y++) {
+    if (raw[y * (w * 4 + 1)] !== 0) throw new Error('expected filter 0')
+    for (let x = 0; x < w * 4; x++) rgba[y * w * 4 + x] = raw[y * (w * 4 + 1) + 1 + x]
+  }
+  return { w, h, rgba }
+}
+
+const dir = new URL('.', import.meta.url).pathname
+const golden = {}
+for (const name of readdirSync(dir).filter((f) => f.endsWith('.png')).sort()) {
+  const { w, h, rgba } = readPNG(readFileSync(dir + name))
+  golden[name] = Buffer.from(rgbaToThumbHash(w, h, rgba)).toString('base64')
+}
+writeFileSync(dir + 'golden.json', JSON.stringify(golden, null, 2) + '\n')
+console.log(golden)
diff --git a/core/artwork/thumbhash/testdata/generated.json b/core/artwork/thumbhash/testdata/generated.json
new file mode 100644
index 000000000..1b49bbb03
--- /dev/null
+++ b/core/artwork/thumbhash/testdata/generated.json
@@ -0,0 +1 @@
+[{"w":28,"h":79,"hash":"4AcCCgBFgGVnc6OLh2u/b7Y="},{"w":94,"h":86,"hash":"4PeBBYAIBZlXeaVKmwl6Zx+i9EeEUqdlGA=="},{"w":61,"h":88,"hash":"3/cBBQCxf6l3ioV1WadpmG+B7Pm4"},{"w":29,"h":41,"hash":"H/iBDAIHX5Chbnyqawdo8otij7N3a0qJBA=="},{"w":63,"h":74,"hash":"3wcCBgB0x884dZeDiopMhclYDUpUAm4="},{"w":29,"h":25,"hash":"HwiCBIIHF79zi6+Gg2fAhk/4fEtnapaYDQ=="},{"w":57,"h":98,"hash":"H/gBBABIejmXynwHHoVAnvdXSw=="},{"w":71,"h":69,"hash":"IPiBBYAHmD2KUW/lQQyLaLCDh0KklFn32g=="},{"w":71,"h":50,"hash":"3/cBBYBohqhLaJpwZoZUd011gBCJ"},{"w":89,"h":83,"hash":"4PeBBYAHkBp+Q/bXx0CSiZ+sT4Z4fIyYZg=="},{"w":92,"h":57,"hash":"IPgBBICgJdaPlJqBnUfQcGbwdA=="},{"w":39,"h":95,"hash":"3/eBAgAIymeYlAuWDQ9RUidjZat7jxk="},{"w":100,"h":82,"hash":"4AcCBoDiuKh2N+TrR6fh9nFm+5lp8Kc="},{"w":92,"h":93,"hash":"HwiCBQAIuI2JaEYDVRA6gU/q5PxIULPapw=="},{"w":67,"h":90,"hash":"IPgBBQC1bGaGk47Hl3+nddp6vwuY"},{"w":78,"h":71,"hash":"HwiCBYAHmZZIYn9JhXCLjZaQSWV2ZUGrfw=="},{"w":85,"h":42,"hash":"4AcCA4KeKZCAlcZzkAz7i6k="},{"w":8,"h":50,"hash":"3/eBCQAH+IVwSkj7IiZPL/h0dYpCSEg="},{"w":13,"h":78,"hash":"HwgCCQJGjqtkmUowdno/3fY="},{"w":66,"h":95,"hash":"HwiCAwAHCjuAqh2Fn/H9K5loYGiYmJU="},{"w":2,"h":84,"hash":"nvcFEQJ7c7iHmKwJj5iHCGA="},{"w":37,"h":32,"hash":"IAiCBIIIldBHeXKZ6f3EA2DV0K2GZkvDBA=="},{"w":41,"h":25,"hash":"3wcCDII7Jst5c0WFhga8cEnTBg=="},{"w":57,"h":26,"hash":"IPiBAoAIuvRneZfgjPSmAhZrl9W8SPU="},{"w":31,"h":40,"hash":"IPgBDQK6o7REKkCxJ1cXRlNqsK+B"},{"w":7,"h":69,"hash":"3veBCQIHdoKrFgYOxqU5cAVYqapmgjQ="},{"w":82,"h":59,"hash":"3/cBBYD4M6tIe6iJenZX0jv3i6QF"},{"w":85,"h":48,"hash":"IAiCA4AHyKR2lgvPG0TFBnXQWGkydzw="},{"w":53,"h":67,"hash":"HwgCBgKbVol5V393ersDOea29bSlZPk="},{"w":79,"h":26,"hash":"IAiCAoAI6QZtSGnvJmnwcJiHZquG+Hc="},{"w":14,"h":28,"hash":"3/cBDAJIhLeYi1+pu1owyIVvMg=="},{"w":85,"h":78,"hash":"4AeCBYAHXPhldaZ2ibVPVQmKh/iJlZQrig=="},{"w":26,"h":67,"hash":"H/gBCwI4T6OnR3GPhq81kGo="},{"w":51,"h":13,"hash":"IPiBCYII24eGC4VNfYAJR/S6V8WLeyg="},{"w":57,"h":81,"hash":"4AcCBQCoojSIY0qYe3f3UQGuawz+"},{"w":8,"h":72,"hash":"4PeBCQIHSUVYVn8ANrQoB3UWWYiXWbA="},{"w":89,"h":40,"hash":"IAgCA4LDe0AG5hb2aM8bcEM="},{"w":55,"h":94,"hash":"3/eBAwAHpIVmT7VvjwahW2NPhkiaDok="},{"w":59,"h":81,"hash":"H/gBDQBERoZIo4nKhqgKaJYvSkVA"},{"w":41,"h":45,"hash":"3/eBBQAHdeyYm3UGRR99adcGQ0RwRZpGmA=="},{"w":11,"h":28,"hash":"HxgCCwLHZnhGlGVggoAJ6GU="},{"w":8,"h":36,"hash":"4PeBCQIIbWHpldBF78rO/EKZaaiAqHo="},{"w":40,"h":100,"hash":"IAgCAwAIT2uoiESGs1BDrxw="},{"w":63,"h":33,"hash":"3weCA4IHmrEpmk9KVK92+LOxI+sLqfs="},{"w":72,"h":63,"hash":"HwgCBoCYlQZkaHeXaeabRJit12VwH7Y="},{"w":29,"h":90,"hash":"3/eBAgAIzqlo+KRtoAl1qh2KO7ZwWWo="},{"w":81,"h":26,"hash":"IPgBAoJVdauz6giWSnhgCYk="},{"w":92,"h":76,"hash":"IPiBBIAHrET8bFvpCZQdZQubVvO0vEV5DQ=="},{"w":85,"h":99,"hash":"3wcCBgB4L9nVxUhpWUyqb76n4LjPOfw="},{"w":79,"h":72,"hash":"4AeCBYAHWneox5/01wN7aHnvSAZscNB3qA=="},{"w":76,"h":18,"hash":"4PcBCoL6mZdmelSFz5UU9EQ="},{"w":78,"h":90,"hash":"4PeBBAAIDnhKoKRQpgBqMJy+iar8L4pZDg=="},{"w":72,"h":13,"hash":"3+cBCYKsdkJZyx6/lICO+8I="},{"w":78,"h":19,"hash":"H/iBAYAImX9hwHSeDXImENV3UIN1hMc="},{"w":29,"h":34,"hash":"IAgCDgB+WIp4KreKyhKJX6mqKKCvEI0="},{"w":63,"h":43,"hash":"H/iBA4AI++eiSIlZkLl/ZwKZhrlnSqg="},{"w":19,"h":79,"hash":"3wcCCgD1k3t0hnYqBHm6Di4="},{"w":82,"h":44,"hash":"3/eBA4AIqi2AjW6pr5YLmwF+OlNou7s="},{"w":70,"h":24,"hash":"3wcCCoAyRWCKl2Z3kHa6A1o="},{"w":28,"h":93,"hash":"4PeBCgAHwrsHVqZgqIePdy6kkJh4RRY="},{"w":44,"h":28,"hash":"H/gBBIJ2xMevRKKpZ4bnUTD6hQ=="},{"w":77,"h":9,"hash":"HwiCCYIIxixdZgmgw/m6OIcDrDM6WZ0="},{"w":59,"h":39,"hash":"H/gBBYKlW6qoh11be/NmovTQCbYc"},{"w":9,"h":93,"hash":"4PeBAQIHFVn4p5mIv/DH95KWbUXgUOk="},{"w":9,"h":96,"hash":"3wcCAQKKqluVczewLNPP0G8="},{"w":54,"h":83,"hash":"IPiBAwAIZVRaj5dvnH4NiFfGpfFPxjg="},{"w":75,"h":3,"hash":"3/cFEYR4iPWKmIiV99OsmPc="},{"w":96,"h":42,"hash":"4PeBAoAHcJqRe3qfQ6f3THWIkFi2ivY="},{"w":74,"h":8,"hash":"4PcBCYJ8JYC0NJh5+a5HnaA="},{"w":2,"h":95,"hash":"oPeBCQR3f82Im7eL3/dIdXgHiHiHiHc="},{"w":40,"h":25,"hash":"3/cBDIJGPXu1PFWvGyI2SH8JWA=="},{"w":48,"h":56,"hash":"H/iBDAAHU4OHDHmKpoT1qngAiHZWl2d4CQ=="},{"w":71,"h":18,"hash":"3/cBCoBFzceDtlBaL20Z8Ok="},{"w":60,"h":44,"hash":"3/eBBIAHqreoZmb9ePMT+YS4hIZZmncHCg=="},{"w":42,"h":25,"hash":"3/cBDIKPdrNMd9eNmFlSn7SZCw=="},{"w":64,"h":67,"hash":"IPiBBQAHbSpXaJBWxEgLybIIa6jFdgxmsw=="},{"w":74,"h":85,"hash":"4AcCBgCVe0R0W1l7eTSq0/dH+zScBSU="},{"w":42,"h":71,"hash":"4AeCAwAIZyCedbhPdZlPiaKXHQRSNeA="},{"w":61,"h":34,"hash":"H/gBBII/nL94LK58lLTVCUz9Jw=="},{"w":26,"h":66,"hash":"4AeCCgAISob0BHp4m1BvNhVnCiiFAtM="},{"w":17,"h":62,"hash":"IAgCCgI8jI9nEofooGprka8="},{"w":58,"h":90,"hash":"IAiCAwAI+Rt0bsP6o/o02aef81rcY4g="},{"w":41,"h":96,"hash":"H/gBAwDLuolgvElQHQppYPY="},{"w":57,"h":6,"hash":"IPiBCYIIh0q8dn/PhQBnd8ApWKNbdKo="},{"w":38,"h":47,"hash":"4PcBDgI6lpeRR2aABrhXvWW0UNaEIHg="},{"w":76,"h":6,"hash":"3xeCCYAISIuiIk91a6CpEKQVvUdsBYc="},{"w":85,"h":66,"hash":"H/gBBYDvamWWd5h1Vo2YlvdTB6/w"},{"w":7,"h":52,"hash":"4AeCCQII+ZuGYmj6XPaXdqa3B0a2dNA="},{"w":1,"h":4,"hash":"Hhk+UjgIh2iYh4iYGIuPh/g="},{"w":19,"h":26,"hash":"3weCDAIHY2JJumCmuqb1ToC4Yy94dxtUBw=="},{"w":63,"h":98,"hash":"3/cBBQBSUpp6Kn2Gnn+ikgXX5EBM"},{"w":36,"h":27,"hash":"IPiBBIAHh6xAemiM6Of5b5+q+XOJtpUwBg=="},{"w":69,"h":50,"hash":"IAgCBYK2ilWImIhgd8ikFPeoVvSn"},{"w":17,"h":100,"hash":"HwiCAQAI8el0tLUJG2OAFon6I0mAZ8U="},{"w":59,"h":24,"hash":"4AcCC4Inv4c4e2OIYDUGV7g="},{"w":57,"h":48,"hash":"3/eBBIAHBXh6Y4qllpB1ryKBqvqpSomhDA=="},{"w":90,"h":41,"hash":"IAgCC4CidBWGNweJm6+coBY="},{"w":68,"h":3,"hash":"oBiCCYII8hsmqlAgxcXwJHh2mAVZhWc="},{"w":77,"h":25,"hash":"4PcBCoL0iEqFdXO2zo+n9Eo="},{"w":50,"h":41,"hash":"HwiCBIAHSK9XhZbW6qiAX4j+o1Yn5JPmBA=="},{"w":95,"h":87,"hash":"3/cBBoBbqfUutpKElbmKm4B0C4I0ePA="},{"w":19,"h":7,"hash":"H/iBCoIYmUl/V1VESZ+mA6eLeHenBnY="},{"w":62,"h":28,"hash":"3wcCC4JqV4G1jAeTn3ttsvs="},{"w":80,"h":84,"hash":"HwiCBQAItaKauK+3WPxqSRf6TQlTiYgs1w=="},{"w":58,"h":11,"hash":"IPgBCYJWdVboUvKJ+nc6wI4="},{"w":62,"h":1,"hash":"oRjCKYZ3iIiIiHCXiJCLCIeIiIiAd/g="},{"w":83,"h":84,"hash":"IAgCBwCXsHOreqRrykpmV4t8lq9nsqEP"},{"w":38,"h":50,"hash":"HwiCBAAIMJSGqHiF+EsGGyZ/MLJmynBjAA=="},{"w":90,"h":25,"hash":"4AcCAoAmQEenlsuKgE4WyvY="},{"w":44,"h":34,"hash":"4AeCDIAIlUgqYFOZB1WIemC1gMKUhIq2Bg=="},{"w":44,"h":58,"hash":"4AcCDQJ1xMubx4YIEjhy2ct7H/IW"},{"w":53,"h":97,"hash":"3/eBAwAIfvkuWL5QdinGj6Tb3EAkpKk="},{"w":46,"h":78,"hash":"3wcCBAD69gtnSeOmSQvGoFC4QA=="},{"w":1,"h":91,"hash":"Xui9GQR3CIiHeIgIiXhfqAj3h4iHiHg="},{"w":62,"h":53,"hash":"HwgCBoDPnGynWGlHeHhaWbZ4ymtwP7k="},{"w":31,"h":16,"hash":"HwiCC4IHYMrnVnx9T5138ke3RXBlSHs="},{"w":79,"h":89,"hash":"3wcCBgCwS65nmVZ1Z3pFOze0G4xfP4U="},{"w":88,"h":46,"hash":"HwiCA4AIeft1qUicgPivQEqYkHp7hEY="},{"w":42,"h":42,"hash":"IAgCBwJd0ybqWZCUd6pdbkhHCZnq9ZoE"},{"w":33,"h":75,"hash":"4AeCAgAIin9mWYoCq51AulUCcmlfBB0="},{"w":74,"h":1,"hash":"3ic+AYp4h4eIiAiHD4hcjQg="},{"w":55,"h":35,"hash":"4AeCA4AIeIClN5NyENOgNZyaiIljBmw="},{"w":2,"h":11,"hash":"HlgKIQZwiHh0aZdocCUKd0w="},{"w":29,"h":33,"hash":"IPiBDAIH9lRItpqqd6CWmKAo+ad49JdoCg=="},{"w":63,"h":40,"hash":"HwgCBIBmUIs2Vol2OVgfOEvSHw=="},{"w":77,"h":90,"hash":"4PeBBAAINniEP5lGAIykwV9XCmS5VmjHCg=="},{"w":78,"h":14,"hash":"3wcCCYBGGoFHx5agj3xrR+8="},{"w":37,"h":40,"hash":"4PeBBQAHy1gEeihmdftWmwDn5DhniHAnSA=="},{"w":79,"h":27,"hash":"H/gBCoCc92ZmanaKgGcGl5k="},{"w":32,"h":86,"hash":"3weCAgAHW6NocGpT+AjOVShetbR/aso="},{"w":14,"h":30,"hash":"H/gBCwLNrIeFxaZPd6YvX1o="},{"w":33,"h":30,"hash":"oAeCBYIHarRwplZVhZj915j1dwd5Y352aQ=="},{"w":62,"h":95,"hash":"H/gBBQB5kGdZ1udkd3lJiV2PbAVc"},{"w":38,"h":93,"hash":"3weCAgAH5D7FRwOFXbAZ+fVpeYk0iHY="},{"w":47,"h":32,"hash":"3/cBDYJ0r1iqSJRkd6p3V3s/a9B/"},{"w":24,"h":9,"hash":"3weCCoIXijxlaV+Eb3RI9odfWVeFVEo="},{"w":17,"h":54,"hash":"4PcBAgSYZHWYgGhbIwMCqHU="},{"w":8,"h":78,"hash":"X/iBAQIIiFJTAjdPiZYEl2PU18bU8nQ="},{"w":8,"h":29,"hash":"HvgBCgYccKvOOXhJ20mAnyg="},{"w":90,"h":54,"hash":"H/iBA4AIb+2Md4RWn/Kfe/FJlyZ1jaQ="},{"w":88,"h":16,"hash":"H/gBCYBnc+aN1jVQYFe1Ov4="},{"w":38,"h":43,"hash":"IAiCBAAHzaaMBvyTQkB3gJ94bziEt4h4AQ=="},{"w":45,"h":33,"hash":"H/gBDYLClnt/2qJ5pLuZZpLzfW+Z"},{"w":9,"h":54,"hash":"3weCAQIIGp+aj3Wd9/GWhYjzxmlbRNg="},{"w":97,"h":47,"hash":"HwgCC4DRtDd8iLn5CHJ3Dnc="},{"w":69,"h":50,"hash":"HwiCBIAHyWepeKMEBzTqh8/5k21oaT90Bw=="},{"w":13,"h":65,"hash":"3/cBCQJpo8dpn410PLfAMvg="},{"w":25,"h":30,"hash":"IPiBBAIHqzf2RJS69XfSTG8Ld2qHiYe2Bw=="},{"w":35,"h":77,"hash":"IPgBAwC/xkaVdZYoy6K/wGU="},{"w":71,"h":99,"hash":"3/eBBAAI8jHjH4eYVgrLOHcQSAdCRrQ3Cw=="},{"w":51,"h":61,"hash":"HwgCDgB4ioRm1K+IiVmHolm68zhYANY="},{"w":99,"h":81,"hash":"4AeCBIAH/JSLl4h51voehr91sfZoWH5pBw=="},{"w":58,"h":89,"hash":"4AcCBQAN9jWNunlhuGOXV/qTrGQG"},{"w":92,"h":16,"hash":"H/iBAYAHzWadOEC11RAUXzefbZKQ2lw="},{"w":20,"h":9,"hash":"3vcBC4R6lm+5cB20+YmS1Ag="},{"w":87,"h":10,"hash":"3+eBAYII7ZVjl0/0dZfQebdwhKU8pfo="},{"w":59,"h":3,"hash":"nwcCCYIU+4fttp4sIM3/v4Y="},{"w":13,"h":39,"hash":"H/iBCgII915YU3MIrA+InAykfK6VeHk="},{"w":22,"h":87,"hash":"3/cBCgJ3MMpXK6a/3GXAf2Y="},{"w":20,"h":61,"hash":"H/iBCgIHcMhmxIC4f1uGBYYJhDl0p9c="},{"w":66,"h":33,"hash":"HwgCBIIVdWCYY5inCWn6Zwzbhg=="},{"w":24,"h":56,"hash":"HwiCAgAIV60ZefWzRA93WHxypWdW1wc="},{"w":36,"h":4,"hash":"HvgBGYaQohaH1cJad41gsFs="},{"w":93,"h":76,"hash":"IPiBBIAIcF8CZi2l97tl7aDCr7ubuXQ4Bg=="},{"w":50,"h":49,"hash":"IAgCB4K8Q4h4hHd5l/iUSzW62DWwG5AE"},{"w":89,"h":33,"hash":"H/iBAoAItPphyoZ4+FLXCCappHhPZLM="},{"w":88,"h":38,"hash":"4PcBA4Dgi0XjhoOT8obwtio="},{"w":92,"h":5,"hash":"4PeBAYII9+Mpe4oUCPQYNXqZtjd56L8="},{"w":16,"h":43,"hash":"HwgCCwLaREjvVTaWYGcna/o="},{"w":43,"h":25,"hash":"H/iBC4IIh7kDmbD1XptgRBwqiJg/xcs="},{"w":23,"h":15,"hash":"IAgCFYLE742XWmeuhhpXpJRT8NAa"},{"w":81,"h":7,"hash":"IPiBAYII/XuJaMxPhJlP16ewLUeXWQQ="},{"w":43,"h":10,"hash":"4PcBCoLS3wRpnEkUcvkwb3Q="},{"w":40,"h":31,"hash":"4PeBBIAHbvoid+O8vCBou5CEhcBWSHukBg=="},{"w":2,"h":54,"hash":"XggCGQh2P1eHhUhzil+FCIM="},{"w":81,"h":51,"hash":"HwiCA4AIXq5fhicHMAp5mmqAO6paeLQ="},{"w":66,"h":34,"hash":"3wcCBIKiaF02Rp91WXV/yMDyNw=="},{"w":82,"h":74,"hash":"4PeBBYAIuB98SKHF1VCErjT2iqiJh49Jlw=="},{"w":68,"h":37,"hash":"H/gBBICMWJmAh1d2Z4isj9tQYw=="},{"w":97,"h":1,"hash":"nxe+GYR3d3iIiIBYh8+FCId4iIiAd/g="},{"w":35,"h":74,"hash":"IAgCAwJaeHZYpGRvC0sBaJg="},{"w":84,"h":16,"hash":"4AeCAYIHtlwCmBe5QIZI/dVrfKfVQJM="},{"w":25,"h":39,"hash":"HwgCDAJR+5x4R7xqGLm9dQAwSA=="},{"w":7,"h":89,"hash":"3weCAQIH71t0jh3R8bisB2CGlqVZa/w="},{"w":11,"h":93,"hash":"4PcBEQIIiUqUVniGpkCGDmY="},{"w":28,"h":16,"hash":"3/eBC4AHZgaLiVrzW/ntHXFCuDtPelc="},{"w":47,"h":1,"hash":"4OdBGYaHiHiIiAh4+ojcfPg="},{"w":83,"h":79,"hash":"4PeBBYAHWU/JlHJmlyqL8DdUi9V3hwhJZQ=="},{"w":31,"h":58,"hash":"3/cBDACMjykH1lXXk4f1m1lXwA=="},{"w":87,"h":27,"hash":"3/eBAoAIWAuadHnSkGf6ZDCpWDbDVHk="},{"w":16,"h":25,"hash":"HxgCDALVgxjVRLTpv0gXoIL7lg=="},{"w":95,"h":6,"hash":"3/eBAYAHNhipdw3ol29wPIUrqUSnB0Y="},{"w":40,"h":79,"hash":"3/cBBACXn5bth4n5V0ifeYb4CA=="},{"w":37,"h":88,"hash":"3/eBAgAHatYMrGagPXqAUTT0aZlkV6k="},{"w":7,"h":64,"hash":"H/gBCQI1U92VyEzQtwv3UiI="},{"w":73,"h":44,"hash":"4AeCA4AI27s6T2uqZi+wyMCreGFnrNs="},{"w":13,"h":53,"hash":"H/gBCgKVPabFiVmfjzmJPgc="},{"w":26,"h":88,"hash":"4AeCAQAH+JrYmobr0Ntl9nJ0DUiHpaU="},{"w":92,"h":96,"hash":"H/gBBwDjZwxVe4qVdpSGh3maxpnPRPAB"},{"w":22,"h":93,"hash":"IPiBAQAIem4GeFLLT5awR4mPYXKA5Tc="},{"w":11,"h":63,"hash":"3/cBCQIEtyd3dmiLRl8zsW8="},{"w":1,"h":16,"hash":"IUbCgRB3CIiHeHj3iIhgOAj3homHiJg="},{"w":86,"h":54,"hash":"3wcCBIBmpUU+NtE5BapGT91XLw=="},{"w":45,"h":45,"hash":"3/eBBQAIjRSWIMBjFweKEy/f4ohbs78Dtw=="},{"w":86,"h":72,"hash":"IPgBBoDpdbynqIevhmp4hEio9NP2gBk="},{"w":56,"h":61,"hash":"HwiCBQAH/ErFesNrqQBrC8foSKc/e7px+A=="},{"w":36,"h":82,"hash":"IPgBAwDXSB9klzdqJkDSCJM="},{"w":19,"h":26,"hash":"IPiBBAIHimHC+WqsTSHQA8CFXPR1aWR7Bw=="},{"w":63,"h":30,"hash":"4AcCC4I3YoJa+ltaWY+Hed8="},{"w":22,"h":67,"hash":"H/iBCgAIdFg69+dzCKkNMJDF6aaPSyc="},{"w":7,"h":4,"hash":"XggGJIgRdYiZWVxIaK+wffh5Sg=="},{"w":65,"h":44,"hash":"H/iBA4AI2jgH3cmnUEkHdX5wtrmFaHQ="},{"w":97,"h":19,"hash":"HwgCCYBPdSVmN45n94dKaAM="},{"w":67,"h":11,"hash":"HwiCCYIImJywpza6bza/d0WndXmo+Dc="},{"w":83,"h":76,"hash":"3wcCBoAIXnqYdVekp+pHk3pn3blfP2g="},{"w":80,"h":98,"hash":"IAiCBAAI39GbiZdfdejP/6+SXIhJSPW3BA=="},{"w":72,"h":86,"hash":"3/cBBgKS+2i4h4h1a46YhnlKwb9G+qc="},{"w":78,"h":29,"hash":"3weCAoAIY2hKCQcA2gp4mpvrhouJX2c="},{"w":91,"h":1,"hash":"IfhBEYZ3iIeIiAiIB4j1i4g="},{"w":68,"h":99,"hash":"IAiCAwAIvewBFkMMqfxbLHqvcVbUZms="},{"w":79,"h":4,"hash":"4AcCCYSbW4Z9nYBL6TpgcE0="},{"w":80,"h":44,"hash":"IAiCA4IHxb+flWn5zAqJiPi0z6Vxk5g="},{"w":43,"h":36,"hash":"4PcBDoC6Qb9xjJWgeX5rc6hoklAaxH8="},{"w":61,"h":21,"hash":"4PeBAoAHoJ2KVFQu/C75JX+S/veGdqI="},{"w":23,"h":93,"hash":"4AcCCgKo/IiJRxNo2ZmfDd0="},{"w":96,"h":65,"hash":"HwiCA4AIgHXGaTw2+itpEHn4d5dxd6c="},{"w":90,"h":27,"hash":"IPgBCoBhgm/V6idYX+m39Sg="},{"w":81,"h":31,"hash":"3weCAoAHn6dXpYipr98KiLRmcGlrmIc="},{"w":73,"h":41,"hash":"3/cBBIA25bcwaFfYQdYCSqbxlg=="},{"w":91,"h":68,"hash":"3/eBBIAI0Jd2OHJIevfJgHx8NNZGpwl/CA=="},{"w":94,"h":74,"hash":"IPgBBoBvTGmIeYhay4x3Z3U3pn8gD0I="},{"w":72,"h":34,"hash":"3weCAoAHQIe83bnPpAqzRjjYpIKvlzc="},{"w":51,"h":34,"hash":"HwgCBYA6fzbdPH26bIaJuMpavwGt"},{"w":55,"h":33,"hash":"H/iBA4AHNLA1nUbPzZ4NNVOQpXiZ11k="},{"w":92,"h":20,"hash":"4PcBAoL2t02KyoishKT/vWc="},{"w":1,"h":94,"hash":"Hvi9CQKICId4iIgYj3tPOAj3h4iHiHg="},{"w":46,"h":34,"hash":"HwgCDYCYTefPhieK2bw3PMCa2Lrw"},{"w":64,"h":30,"hash":"IAiCAoAHTDx/WamEcJBD9saIKnufjmc="},{"w":36,"h":19,"hash":"HwgCDIKHuMmduHeamoBgk/PTeg=="},{"w":90,"h":94,"hash":"IAiCBQAHZy+dmah1KFYwiwVXfURlxoBptQ=="},{"w":89,"h":49,"hash":"H/gBBIBpkIl5rJU5yJrcT/x9UQ=="},{"w":34,"h":2,"hash":"Y8iBCYSIVbsJgXeT+wc2iYeHh4eHiAc="},{"w":25,"h":40,"hash":"3wcCDAKkNHd3x4wKpngw3Pa3Cw=="},{"w":47,"h":32,"hash":"IPiBA4AHl3CHY4VS/WGvOem9n4xZNiY="},{"w":53,"h":96,"hash":"4PcBBAB4zFkHVnZ5Vnb+cQoyqA=="},{"w":47,"h":93,"hash":"4PeBAwAHovPYd5nJhr9y84volUge9qQ="},{"w":86,"h":89,"hash":"4AcCBwIxnclaVpZmhwuXeIqsOUOABWQF"},{"w":40,"h":90,"hash":"IPiBAgAIzWDGoI4lL8cOkpTyeDiGmHY="},{"w":38,"h":66,"hash":"H/gBBAK5wb10WqSEx3BqgHasQA=="},{"w":12,"h":21,"hash":"4AeCAwIHU5iHp/TaqbBfi7ypznOSRIA="},{"w":54,"h":29,"hash":"3/cBBILTCdd3yod7eIVwrqfOnw=="},{"w":78,"h":77,"hash":"3weCBYAIfO9WhGEMTcBzWAd3QJc6hLVohw=="},{"w":88,"h":96,"hash":"3/cBBgCfiF9LQRun2ME2UJ5yuGC1Dgg="},{"w":49,"h":89,"hash":"4PeBAwAIKc/XsRei+QLKXFcyRHdFSvM="},{"w":19,"h":41,"hash":"3wcCCwKIj4pZgGhJXAfKXfQ="},{"w":70,"h":53,"hash":"IPiBBIII2CpoSAcGTfhW94S4b3aFdlqmBQ=="},{"w":55,"h":57,"hash":"4PcBBwAGraR0aVs6blrol9aYrApGsBgG"},{"w":54,"h":29,"hash":"3/eBC4AHyLBqhpD4VxQX9hqwzY9DuVg="},{"w":15,"h":75,"hash":"HwgCCQKJ9qeHapW2EDvPhPc="},{"w":93,"h":81,"hash":"H/iBBIAHC2WedpVnfngIVnX/YBI7RopLBw=="},{"w":64,"h":96,"hash":"4AcCBQCMiJ5GnFu6rDv1yHqfSLQP"},{"w":76,"h":44,"hash":"IPiBA4AHqQeWWI2puG+/SsVZfH+EKFc="},{"w":88,"h":33,"hash":"IAgCA4L4N5JQnp1odH8Id50="},{"w":1,"h":34,"hash":"Xue9MQaICIh3iHj3h3WfiAj3h4iId4g="},{"w":30,"h":4,"hash":"IOgFGYa2AneplIqU+YGncKc="},{"w":92,"h":76,"hash":"HwiCBIAHKrOomZBJlckKC2XFT54JnMSLCA=="},{"w":91,"h":16,"hash":"IPgBCYLldw2ryLmLYHjxVkk="},{"w":3,"h":26,"hash":"3yeGCQIYiY/WpUpL9DmJ/2WYd4anCrk="},{"w":2,"h":14,"hash":"YNcFCQ56SgeK1ld+hvp2+FY="},{"w":93,"h":90,"hash":"IPiBBYAHlR+Hm5gJyPdlAqqImTuPWXlFeA=="},{"w":47,"h":88,"hash":"3/cBBAALd4h3lHZpeIlfs6NTDQ=="},{"w":35,"h":32,"hash":"4AeCBYIHdgJPGVxze8rQrvpIvplllljXBw=="},{"w":38,"h":5,"hash":"4AcCCYRTKNxEawW3UJsl/5Y="},{"w":8,"h":78,"hash":"H/iBCQIHjIUIg8cEM2XQxWp6oKdah5A="},{"w":39,"h":36,"hash":"3/cBDoJQZreZx2RPmKWGpxpkSXA6/EM="},{"w":55,"h":13,"hash":"HwiCAYAHfuUceQxcnO/ZMFE234F3aZY="},{"w":13,"h":56,"hash":"IAgCCgJ7gviHc4ur2H4A1gI="},{"w":26,"h":22,"hash":"3weCBIIHx2iLhiCf+OrZYBToaS9I6Zd1BA=="},{"w":83,"h":19,"hash":"3wcCCoL5dJtjKLdzdZvA/G0="},{"w":7,"h":9,"hash":"IRiCDAQXc8cFtlkd8SmVQIVf+rcJWDm7BA=="},{"w":90,"h":43,"hash":"4PcBA4BWXGyC3oWPkJfDrgo="},{"w":43,"h":77,"hash":"IPiBAwAHhT8asHZ/VIr3tMogVkNnm1g="},{"w":36,"h":27,"hash":"IPgBBYKokWWJhMqLlilFBLsGpL/F"},{"w":86,"h":62,"hash":"3weCBIAHsSsGVZlmSOT8f6tyeRCPwHh6DA=="},{"w":63,"h":89,"hash":"IAgCBQC69pVJd3nafFOo1Xr893oE"},{"w":69,"h":98,"hash":"4AeCBAAHidVTQLuXiQbeVJ9H32iHhUaHAg=="},{"w":12,"h":58,"hash":"HwgCCQKZX0iHh3rGb6X1Nec="},{"w":7,"h":7,"hash":"YPeFFQYXh8baRainTwmCfET7/Km5ia0jxw=="},{"w":40,"h":12,"hash":"IPgBEoSX8Ul3WeSbcLd1Zfg="},{"w":93,"h":47,"hash":"4PeBA4AHY4N7pPu7oJO5AnmeQLYcRLk="},{"w":15,"h":42,"hash":"4AcCCwJ0D/zATmOWM/r3xXM="},{"w":67,"h":45,"hash":"3/eBA4AHVbr4h517mv+eZprFsJioaoQ="},{"w":67,"h":74,"hash":"IAgCBgBqmUc1R2d6iqtrigl4lSf/VXQ="},{"w":29,"h":67,"hash":"3weCAgAHYJRmaGqgmaOAV5q0AZR2akk="},{"w":43,"h":10,"hash":"4AcCCoL8SVDXdVsyiECVaK8="},{"w":75,"h":40,"hash":"IAiCA4AHw2mXw6/AoA5Eo8onAwY4s2o="},{"w":73,"h":91,"hash":"3wcCBgDFhsbJlnmDaYxwRZZUl5GAfzY="},{"w":21,"h":54,"hash":"4AeCAgIHWamZCKf0fNZpTyw6aHxHXzM="},{"w":98,"h":52,"hash":"H/gBBICZZsltiKuMUHewoYEI5g=="},{"w":2,"h":29,"hash":"XwiCCQR3cpuYwKqODEIHWXgHiHiIiIc="}]
diff --git a/core/artwork/thumbhash/testdata/golden.json b/core/artwork/thumbhash/testdata/golden.json
new file mode 100644
index 000000000..578986e75
--- /dev/null
+++ b/core/artwork/thumbhash/testdata/golden.json
@@ -0,0 +1,8 @@
+{
+  "alpha.png": "JOiFBQ4nkIexh3p4iA8uB+lYhIeAh3d4dw==",
+  "landscape.png": "3wcOFJpwh4eBh3d4iIePgAj3hw==",
+  "portrait.png": "3/cNFBqBB4iId4d3d4iAjwj4hw==",
+  "solid.png": "HoUBBwB4eHeHd3hweId3h3h4B2+Ih4gA",
+  "square.png": "H/gNBxpwh4dwd3eIiHd3iHeHeJ+dcH8I",
+  "tiny.png": "HoU9tx4I9wiIh4hwj3CI+AiIcH/494cP"
+}
diff --git a/core/artwork/thumbhash/testdata/landscape.png b/core/artwork/thumbhash/testdata/landscape.png
new file mode 100644
index 0000000000000000000000000000000000000000..413851f47af829397cfbabc5b9ccb09b413a03cb
GIT binary patch
literal 20198
zcmV)6K*+y|P)<h;3K|Lk000e1NJLTq003kF002A)1^@s6kUt;J002&{Nkl<Zc$_rT
zWpow>*0${%2oMM%K@ubhNr(|4?(XjH?(TNS-QC@l1cDVWUZJ#9naWhAolaXiwW*H0
z=eOvyz8}{*_y1#Ufk3d0oq`>R?hvqBAV5?g!XCjM4hi;hP(*@*g1sExA&Hzo3^~Ce
zWVcJ8wEYN*+m4~ST?S==6xt$3(G;A(VA~0FL=@2zQNmDg64M<Dn2VgkMsNxzfhH~j
zb=(CycnMD9woM0rfe}92_3;<z6DTkwa+?Lw0&}7S=0u8ElDNZ;6oCzC+nvZ1IFYs8
zfjof|Ioq8m+~Gutz=QG~o(Kh=)Qk91yFG~7?S8ZiLTD8Ur9&iuK0y$@f=Gr0;q(jQ
z7~dYl@U}R{1xd_pOJ!ChiP`OGtO_#O5TvuYBbT#+9JY4ka9$*vOM+}JixhK3P|Ayf
zQtodr<&L0?R|FNjDiHF@_8Q*UR?9m(>UnE>9d8Soc~8*DUj>bPBGSw!J6iZu(8WIl
z-F&sJ=g)pC80Oiw0e;;!#?RX)`CVj~-v!hBA(%w4W48doZUNhNi?D0w9z?h8MN}Zh
zzHQ=2iijh%OM=7O4kEQviesV@$P1*A+kFHDQ5n>>A47fDQFM07qb_nB!|iey2^28i
zsfyutH7vKOVY^Eei(OjS2sCint%<`<Jv;<j_zHCJ-Kj&+ZexN)4G7<6O2l&vQFCGh
zrX+5EUTYF|T9YoYB~{=+);4$Y1+HWZ+{oMELGf-ks&;x%xx<T^?Os&v^r3!x5N*2x
zXx<S>$F?ZCcZbuvD~jQrQS=L<nH0n`B@)N%_Ee^}r!l)dh2`z3tnSWaeRmpLA~|gC
z%;o&Hd@hL;aZQlV&0YCi*;T~t9nVpUd1*&AcXw3s+U`1D*<Q)3JDPYbTF1LP8+dD1
z3x5%9=cApSe6+KLkGHk*xo9U}ZtvwEI|q5TbAa!54e(EqA->-^!B0Df_|LXceiKab
zpZ_03M07j5MMc;nCW`1jG4}0~;J_{k#CJ;~xl4lMdnJ$)lR$2lBqzlVb8^>l6!u7Q
za^Er3MHEomt%%-ES+sX6V<@J8@m@8|_G(}*s)Ut@I@Y_?aNezj>uyb4_UhoaM+euP
zdiaUz<F(rmKQR;h_gE0V*ObV8Hbm^TCq~SMgkAQe@3bdruQO?4&gATIBIkMcxl_E)
zoASM02*o@Q?)0KkB#8QbAvEp_pkY@y9eYCP7LA~5S17$ZV;C0wKa_E?1g7^SGrKFD
z>Afk;?a5?rZwf0r(^=b>#yOD!&WmNSxhsdOJ4?8*r;zJ=i@3e3h<jo}UKFY3j%WoB
zcUAD3Xbq2d)$`WQI^Nn@&%2^+ytlWRr+ZrYP^^OwM0@yXUq7Gj>E!c0y?ni|pD%Zg
z@Qug_KkS*{yWJ!FzGs4;ca8Gv-U$$yLLd+oK}1rNZF@x7DY}P!`}ZO$A;!M_2iU*w
z5J&g#=a|F+j)))TgxE3UC601ZLI!2=BdCfWLuIcbr$pt^+^2xv9(nX66fxeXf|-~K
zmZDmi?a{)1-)Zdk>fyTQG!Bw_c<eL6L&5}~eFg;XHzYvZl2CC=B1LTp6SX8x)RJgP
zdt&z5lepi3)cvlcN;r@%;X>|S7mD|JQ6}k4@g5&a_j^&c-<Jx}02(F2Xb}sbWlsdn
zqQSI_hS4n+ORsnwgQ7|FizPB9n!xn_1g1nYm={lFNi2)iec7yw=CUG|$)<QdTVjQ5
z?I~qzUm;f{O1ZkXg6pC}?uwQ3K(dOvl65=~tK}8ZMqc03z?)+AJlWUCTVkDju&14O
z_IL0X@ismc@8@r#U3{{?kFUf=_*!&`XM0BZMs$#8`$qXea+06LCi%D641Y*Yg2XI>
z9a4MQxqml1#dovk;2y*z#1P*v#-YRekUVsdLkFdh-hTkOLx+&rFT=_GQYajhM@9Su
zDhCzNl2SxXLJn<71+)$;Vj!uE;eIuY4rpPuUmFWaO{@=T;3%$-ql5u22aIt)Y=EzX
zK3?Lc1RXNQU&4ZLaZ`d1*%N)pf$;ryL`paiFX2Fvlp~2!&SV~NC-0y)g$LXzIOs>w
zArA^9gD4jFp=N(5brONpN(9reKZ=I^VKj+{({mt(9*JnW#G~nvNMiVK5)+5h852)t
z`d|tR;^{2!&t^p`hZXT$HV@~pxxbiA@nS9>F64!Sg<Kae=el?qFG`kkcfXLE2kLlm
zpo&)xH}JAV3$N~P<n{fnydl}f8&XYtAl1%C`#X3l-pywRJNaz?ARiwd;<Np|d@a?_
zw+F`gQGA?#9iHNQ$tix4n&3Cd3I2Cz8YCAG2#)PU<k(KO9S}uCS`x8i;)qEdLj0&W
zk_V+YbW94V!$*)kEQ9<JDP)eypm^{E3P<HoIv|JE0eRGqsG%XHih-0mI!Be!JEVfy
zVGYa=>tb_61BZjU*c~&(_K*qghm7z#XoTxw1N^1T2{>eopR@&mN9>6_VoTUzTjGz|
zk#NA4xI=Cv9&sS$h!YuyUCBP;M&U6}@}&GJI1)hVAwS9w22gn*j2h_(s*Z%ya4eLD
zLou{V#n5>;hF+;Cx{fB$do-24!^un>OlACN3e$(um^qZj+`)9_4`s6~UBv2vLbi^U
za89a_v(g1zI8w>wgO%JkDCF9aGHxEL=iZS9?n%{h|40q59%$s%gY~?2td)19nt1xW
zN4xpxP!}Ic_3-JDUOqq6!`~0~@wL<l-y9g>y91;AaA1n>rAPVx;5fe=nCCx-7y0Gr
z694b$A_5UPQMOC(MpSAKJLL8vCcO_)*~1)?l0-^c8Y!v6NJ}5#=n*N7A3K7glmdz}
zCr~}Ah^mYVr=;c4mQzAUS{)rZ6-;C_FqGE9{Mc!XW%RH*ri-1FF7~o|ILhkdAZ3h~
zv>9G<X81~56L`cL|6|q!9&;f4s1+fy4n!ZfCr-|u#G@|6%ej&w<xb{tFLI80QgF<Z
zLTMigj(Afl9Zb2jKjlXQsFn(+N;Z^w=};PE;%Pn_Lz_$@9Y+)BlZmDKNE!o26Bv=o
zWbAl0Q%6#nIFiSbbPlV>3t5rLV?(Zxb=fk`NSCoGTh3*vN?wqu;<9utw~y8EqEtOM
z<!ZSr-N1dRT3(ZF<CWv>Jd$qZiEImRNO$s7wwn)*_3+{G0X{q0&u3DDd@Mc2-;a&*
zjr1hn93SEPqoaH$J<h+5&+*&QX?~ZP=Xa?kkX=TwO?E#5S#frs*oTPX0rng_%w9QZ
zBu_|lQ1%Ft$B%GW?ifd8k8oT@0T~&2<m44mmRCVpMg>(FMbs6QIelCi-Q%Y*cs_Ye
zEah}DRXmNgye<}sy4cGb<9OTzH+f^6<;`(bG{H;3lmK}<LXX)IC~r@YyfY#44us3u
z6RGGxilRFy^4_G%dXawIlZ+Go<jDt-tr$f9F+U0wLn%KIMwx6RRVSjTR}804HkLMp
zI696;(<2{8r)(TOGAZ=Rq%e3ag9(LXMijG{J(0n*d=}Gkg)E#XWJ$J=GxB+yQz+)V
zVkMi3Wt^80^1=xrS58!MOQw>0iZwitsppPtEw3DF=8<d%uN-gYHHB8*RA}ejV;#IN
zKgdTXhWJRfpO5AH_~iHqf0G;I?+PRQLvE6<6h`?*Zkm58%<_ZcJU=Qd^Sk^qzaLxW
z-wKNe1j?f9QrOQfm3{0{I)M0z14yVIVV}}*B;;i{tSHApC0S%n%A%m6h@7%KipmNo
z$g85NcnVd8lbkxKik7M>T1uzTSJA{!RUacoJ<L^3W2R_`t-Ky~@&-7o8sn&7jOPh6
z+~lqBl()i9!G<7tYr<3=iBxbTM!|_V1t;QF-H1_jAx-`{geMsazN9PpQg||eB4vNd
zlmaPI45U;klxo!osuUt<l8>R~WGropadavt(Q_h+F8O2zl@b|H%w$kGl?kOZMpZJH
zmCt2CC5J`Dd{&i8SWqouRkf6JD#dK5R<J2w#tSDaxujapHI+uLD%NoCL>+fd)N@~@
znV02Td8FFRD<?X5tlGw#3f;V;)XQ5+gS@9Qzz0f${8go&PZTEkTy=_nsEqOV6El2s
zVv=Xd^E^|X;}@klepFfF7nMc+kYDG&imM0&C-)*y--oEOB)gR)*sCVZo>NDVP?bVT
zS&9RyGDs;M<*2$WN7YXtrzD4psyr$hikwnbMp;7x%~LAqozy{FMHhopS{SP7Vydo>
zsgeN}8YWn%nqaSPile#(E*e&NX_(`qYK51w9YGq71S{DRq~b)Bs_UPNRCgsx-Gw9-
zcj8ZalcwxJj=B#S>OK@|1dx9+ltQ%-icf}7q7hBGatyUf(bOu()1nbe^T`A{l@jPa
znMQ|t8oe5646CFwb}E}m^-LzzvYAoOV@@NFWu+2UPnB}!R3V!x&u<}TRm(Z6RL;ed
zHC$1t=7wq&*VLN0ty0U2s?FThXyk!f8;_M*c}=a2H&y$1L%Ewbl!kb!Hpn}w!+fAJ
z%qJ@2e55?g$7&ONc4~}&D9`Yv>H^P{miSR^k?%AX`Bim=UsRX*RdtR3s;wXpoIZd+
z>j1m8CD^4QiKyyf_Gw8Yar!6+v}HJ=CC4!>d1SQ|Ij*XLteP5%+NY4$R7OKv0}V|L
zbX0XXefl(p+NUwn(!xkn2UB%Dtkm?e(J;a4v<0@Ot#H&b#zDgzcP(q&wQTS_ZG)GV
z1Af|eglakwrtLuVX%AwwT!}s9@#j*sy-CyvB2CqoH1%MzG(#xV4y0H!3ZZ5M73!gs
zsm4-$Dw<lgBw9|#(5#(G^Qm+?Po>hXn$Dm`Ha!}t3~S{urjf^}S^+a^c}!@Ru&iCc
zta<^frz_c1t71c|hOJYToKvgdvPKQpH5$2cs+KG24S!<XQ)}UYY6mZ=ck!}z8!u~h
z@upTMPc(*jQ>&kMG)DMHZIJg*kMOb9B%f=J@u~VaU#U;=mDUu`PR;S1<~%>B&heA>
z8o#J7^KXp}e$iUve;VruwrLzfpnm`n&7<trmST^V3=%p=*r#~}Ney`pY8>Z?rVO(B
z3drdyprCUSC2bXybyQH&Rz+1q0}U-Lw6(O+($Yp(>okV?CYbB!Vyt0`g{B2|y2d!@
zS>dQ-i-(>iE*ds?Y1-hSYmJ|t6QQRa2+(#RLdTgHEl;9OyAi4DN3y0TX?lJnY6Xy`
z5kQ8XKY6Fa$<Ym^SSN%6-Ed0v!l}`Zp-MZ6I=xuxb&_e<O{PUJofgeBy7W@$)y$?>
zGnX;lEC#i6nL3@#w0<#j`UNcOl(DQQWKpYx<<r%y>z1*pQNdY_YF^N9;F@L&SG8)n
zq0z=Yy-sdwck;4!3oq;U@KC#h#~S@S*6-$Zts&k#J<R*s<Giae$VYl3e4shaXIis-
zra#Y@+B1BmJ<B)xb9|>Y&-a>Z{Cs+a-!xbFS$CaZwKw>W_BjOG4W$w29c8!4F?JeA
zu}AL+VkXCs)H#NPo&u5viX7KdK~_hVqeg1Tn5c2mND~EPEmZV$&@xg-TSp%)T}^a!
zbTBbC!py`JGd&Y5jm@z%FvUU78Yd$g><w&i(zV0O$Od;4Yy3@|@i%fM(8!H&BNrld
zT!=CDCC12;SVM1O4g5&c_a;-<j~v5rGIT=7GY%)uFq|@-Fv?9LC^w0v+&Gpx;{=*a
zVyQDsquDT>X8las^pfc@$e>F%gC64oMvd|rF(_ctpqOdnLZ%E#Sv0I<POp?jy-L;%
z$~mW3#~J-vHVtaIYEaKby+&>tw{qL0joSw8+%@Rrp>8h^b=!GOubU_OeY|SY!<$Bf
zylp(r2YREtr#s3=#v^>BJH{6}ll)zGlF#**_)2${f9kLDjnO>c8m;n^-a5Y-ZSuSB
zD!=J(@rTKI1UoE_ATU0}9)rW|FqC1x#Sz2|<k)8<!yz+Sqzn}~XspaJgOey2C~?wE
z6J^8GD4J@ZW~Pn0sTNwsr_r&{N88u{BLgFhj7%^zG{?fo7;^(N?9FX(GP1?N)E;*u
z8$2zXaW$~R!^9q619w8rT?sIDCB)E`2orar&HaeB@FB(2mjt6gG7N&qGz%fyFoYcQ
zFmer|$Tx|l$S4M(VG=cFiBuV-QfHV%qhUHt7MZjgX3=VzPLE**{bsrJSQIj5R=|jP
zA;V_HOc@k2XHmqAc{vNlrL0<%vuRq*Ig?t>n>292xR%RibzC=X<%&r=*Nr>5W!S+3
zgHG-lwDZuki$^9yykRiFtEMBoWir51lTqF?8091LDLyn9<*#Prd~80+XNEI;Z9c~r
z#*2JwzQVUAOZ?MhjUSCx`O$2RUk%RjAG7oP$6^bCz)Bi{&2e^F%OGNXf_)Zp?6;Cf
z+*}4J6D1B<C~?$A5gBV0j$5fBZ>@rowK{4R+9;XnqG6$lhN&TX*7_Kl>tbYXhJl3{
zre>y?nwnu@Wr3ZAJ=WGXxLVubVPS`>jU&D`E_j$a;cw|hkckID7M=uKcoJgjN4Rw$
z@z&m?m<Ety6-JtQC@Iz<q+0}&Z4pb3WgJBo5focRQ)v-LrA-2rRtePDq|soKPK$LG
z?H1{DndH!EnMa>Z0X-(U44eNS%D8zEbJiuy*pxGEQ^~4T8OzocteaJ{YSY9S>w3=G
zG;zVAo$FSuykOSJ4U;Zjv}xz2Sq~4b`+3E*i^t|8JhABIiRl<mEXR1ye3++Z)4Xp!
z#s}szd}=z!$0iGWX}-eWtQPs&Y?W_JR`}L(nSWWI<rkX`el*?UH;W7WVZFtFO|Co#
zkwL^#nr*fx5VJqVep?y#+Q=heql~zn8j?0jNZBYO<)DGAr5eXAPN8hAg^Gm+CoK$6
zvozwAjUF1d27f~6*c)PGX@#YODaMvIm|5CjX>EnIofWRO4mer5;9=#6yM;S`_D=ZO
zcoSmdMwpcc;Z^~J+XoV5>qERnFbP&6Bw2)$=@3GuRT$aUvE*CCkmC?ZzHKap_6d~Q
zCQ)ITM1@rn)eadn*<{jUpH7Qi7Ht+ewA&QY>rhOORS9GErHosYF=Z=c+(yW>O%?N2
zl`Po_S+c8V&AOfq>n1jB8`-jI=ZalB7wkK@V$;rxmaW{e@8f}WFAr?{dEn5`LyJ*f
zw;JRv`$3-AjPj<{DDT=%^1j_1?^{jrspTwxwOr;?y9GY8oaal21)kZj@}uP@KiF>Z
zy~7qiTb$=#HW&EK?gIa_yM#dCB!j@=C_9|x5p_JteuooCIG$vmt1A0llsW2jiervy
z$T*)y&QTo&XHDcCH8|;@hq{9vs<y_c+ZmwcYK(!s3HnY(=-HWKYHN<UlQmYZb~rfL
zVdvtAlY<j3_Aa=&IN@vWg14PB-nKpj*n1J|;z78RFEOtE#JB_z?-)jmV-TtKVI<l|
zk!Bl1rb9T{j`0+`#8coBN10<RRZdBixnxl3nnkr;IyH9bv^ZqY;*w35b0KYZ1q?cs
z(Ct*hu!E2hmm;QZE0}gJXTq_X1=mVe94c9Ks%OKwkxhqMHf)=@<l4?<`*tq7v~t<G
zofqx;xaHW%O}j20IQ8+W?Fg?p4)MfslDBM!c*k~xH|=J5-+7jIZKrwPah{JH=K0KF
zmd{<6_{w#KZyeV7r}G)Uw_oQwr*r(veuJOwF7mtmMSgX-!hdbAArN>RN5ox@?Vbwk
zbXH=In-UUE%1FALLc&o4X-8!ad#EDoatb+DU1XfKIq9y=Nhe*D9SzWQG)2?RnA1+?
zoc1(B$Jqp9XA6v6tugno$K1mj3r8CqT%ED^aK+Wd0XH`<+&x_Ia`eE<$s0cpf5JVy
z2=@pe$|;m^*8t)?!-#c^BE>V5M8|N_Tw}?0N+8cOo_yCtiro_sx}+d<OQpgsg(|0H
znw)ZJcFLo{EuR**=OFp?IhD}oRLrnrDFdEmjCxcs;Z)9;dj(Ujb<Da}G4EK%f>Rw!
zPA!~uYGTv9i7m%=E;zPw*{zpruHC%oG{9Y#9&S1g@UqhY_nk+0=rX|@9uquvn&Pq3
zByYOT@~-nF?>W!$)OnsyU6=Tq`x>9Ptn#Jn8NP5o$1~SW{^@v*f4Q9DUyfV+;B<xG
zJh%9-`wQTF5rM!*9uYSgc6ccw=5>PIUTW<3RYc4~6$u|Dq<v0v#7ze|FD+!eH8}2e
z8aYoRl)dy(^E5`;%M49#19aU?IPGDHj+Z&6UY3~n*kJ5xi<O5Bww{jIxVhr!;f|A=
z8?LS{c(}Ra;q8f!r!S$Nfdu;m6Xq63s8=vCJ|QIdh7ji+Op;p!NnTN;dBv0E9z(Ww
zG({e%<a?%5;*(67XBri5$yB+eQ|*>Xoog;FzWKDdX4C1JN1IzQ1HOd}_!cwfS<bLq
zIiqe>OuAJv;abg-YZa^BEi8LAu;JRmhFc4pp3Pix@8ODPE7v^wx$M)=Ri7Si`3!K=
zbA*>X#(Bwol2^RPc*AXyN8Yo%={w20p7VU*v%q_9GkoB+!Ut|^eBrUqCvMAp?YY92
zZX0~#c7|tO8~o&XiC=s!@U!=2e)YV-FFsfJ!{;i3?f$X|d}P=apn{mcD&js0i27?F
z@f;>l3rR06j`?XI?W4ibKz$T^3{eTxMc!W*B|kG%y^PTGvOw3@6df;HbOLNJ39!a2
z&=%_e2kg9Du?Td<!QTZ(FE?Dg-0%wYz{k@Ee=iRL1HA|i^uymTfMD-%Vmt$g4U8n#
zH<%>vSW-OWN%4*)%PWyg&u9w0;>q(#CC@8~0?!nR{Zgs$&7w9ii)!zD8vXKV_sgN(
zuas{8eA>N>=n51v>{Z5KKp7)G)r|XAG38Umf?pF$o=vQHHLw)W#)?-PtAXvD@#^7{
zZ#!3fdbs2_$Q8dqZUy#nH=v)Jfdky}ALOp*Fps=ucsXF2Cjk?@;WNj(0gJpJxWc=>
z3w-Rm%==!8eC)HyC;lsZ?R$<deK+}s-&ub2I>+~37x|ah7C-o1;P=26_%+}<|IhFC
za}YU1g5=p9pvKNn1;j#5AsVcNxStkM{+b*P)<!DuG;%?@$Oaj4Jj@W4AbnIr3{ej-
zM%m8<wNP{Pf^0Deutg`(785^PECU=d4|K#f)Dg>IH=O+4a18XqJ;WW)V1HbL{P7D7
zB*@PP{~%w&Li`C14k0Qug4n=NV*H{=3X38oAeyAWXwric$PJ4n*FS~4pmd4?GAQ#)
zp~5eRihwLCg0iUhFQ6tcht|+sS_4Yy2q~s5tb*RqVtN9q83`6L=2yu`Km)UZjZ6eI
zGab^xa&SBAVI8dax3Ll0&e@<=F8FnEHMpM({yp6AAK`XrKR5jQxfwRh{lF>i1yAy-
z|16LE#(67bjyD45c{5<14}uqYKWLec0@nD@Z<SAjSNMCtCSQeY@QvSDz6sjoS@0I$
zg<j^@pcnWl_%i<qxy&Dd*Z6P14Fubw<Pb!tA`*O(9YIQnN2#zUSe1j}YDfiZaxh4n
z<3YL{jWj?Z#2DF7L*&Eskq<WEWUwV#p%!R_TcH_Yg?6X~h7nd6M%ZH(VTXB$1C}8k
zSVXzw9Oi{xqz{e}zIcUr;t>&mPiPQ9A))w(1`rS&OmJur5#iCqhlddr8beA{EJ<N8
zq=zJs6`n{&NCE|6X%vNKQW}y@X=o~CQR!4iWm6rNOKn6EEn&qpM3m4JCZsj2oZcuQ
zgQ2DLgjO&ZTEkdG4I@D{%!D*C8{Eu%R6ENN%`Aqsvli9PMno6qLOZw^+{MMHKCVX&
zaU*<)D^Y{o2p!^n)D-tZ$GI0Z#VesxJPDoWt?)(O2%G2K;1!;REb&pq89t6!=C9#r
z_$=}qUxuvnkBIYp8G4DYLoV`l#09<&yT(sJ7x^{vCclK=;J5H={5R}H1cGQKw#6y3
zBk~lxVwBhyu8MfH1_vV5IS_T412K9WjM3w0oFT_!bU7Jr$jK;k6r;`2h_FH{(iELY
zd$eOL(2cOdIKl~|XeW%LTriGt#5&Ro>nL~Z!##0{^1~s@2e)u<+@gF5hz`XsGMu28
za6%#@35|**@;OFC6wxu!#6%^L5*0^cOd{#A$$u^<Dv82~G)iN0C<;rXI4+CIupBBP
zb7^`G5m`cWTsckALfXTN>53B4A63C%gpiS#28P0#7>{dVGPZ@;ur{V++gOfjXC<ne
z<;YG}!`nF<*Ue_!5LaUcxez|U&8Pux#!YZLc7i)G6Wog&=U&7tuf)vqC~lrNBbIqR
ze2Mp>mw7jQl@G!;c|YnLAH;6(S@Z=yjXBHTqc8Jy^cG*mT;bc;EBrI+IzL8T=jXT=
z`8Di1zeV5Xzp?iaY>!uFTdWe>V%6CjrHNRQ2K(Z*I1sCeM1l^|F}fT})Zu8f5yxYV
zIgx09T!J}Dai*M%HA5xA5{)<;v}2txh_ypE!4~}lSBw&!u}pNvF3JnrC|8_fyl_nL
z!y(omw<I5Y5`*ze3Lz*Vkl^T00^%cxOo${rKAgDN1Y(k+NJ&Z{H8F|wgfw!J(#cFn
zBQGw6qUdxA6LTm{%%L(NkDA1MD&n8Fg!+VH+7e1>iYuo*s)DYBT6&(NL{~BpUB_^2
zGt&tT%qF%m7uU){d<*l59V|q3u^!dSdSX9YaXp-i8s>%QJ}xJYb2D*>Td@<|j-TOf
z^aS_g=Xel1%S+KyypcG=Yq3kbov^~&(JQ<iwaQ<j*7-R44DZLE;j_3id=h_-uVXIq
zRl+6y5qE)qCS2oL+)aLseUaZ{Z}Cg~i~JUU4-#)95Tu`ETbdHv6Hl=#?G$^Hw2(~F
zMKZ|%sdRk~r5JK7RS%goQ{>akI390`Lb@f&@m8p(n{z7F3iTu>)Kl%yNwLEu-3|SC
z2h37jF-~y7Jjn~|cy}BVeQ`?n!!gYt&$JLc;sfwa3B^AxoWSHL0#jlLPl_QtF`DSq
zXyVcniAzo*B_WZtgmluAGssCzr64|+g2Xh65;G}D&7&f<fXbvIYEnz7O)a1yxr~<d
zQW}%0X-%x6BfggIgn9;28|hDLVmPUZ$;4(RQaYGP>R>*tljY=AR+9T!OYCPOv5zy!
zJzPrcV=HZl3&|5)PMzXL@+h~`M!A<T$%B+h9;VFlO8gA3C$921d5JgD&+sIDm3NZQ
z@@~pHPm{LzYx)+Sr(NQU^ox9!zQs35SNJCW8s8^g;aTbxevQA*&nfr#BjE<WrM$?0
zlkX$gmaU2)S&Qu{r`eINgIJa}V(EGu%FstV%>c<XQ;uhvA)RG}OtK|1DW<5To1>g;
z$;lK;)Y7fd$g<^hx)X*O_86x)V3z5HdA2)NDc+c+_+ypnjbo}8c4>Y%qzB@X5{`Fv
z0N$yg1SW?PnjS-FN;u)!(S&5j5uF)BY*svpX~`sKB$AYzLP}~HS=ni1W~GyxRzP7|
zJ_Q+hlq45Zo}G^{tAx7rGMcl>X-p}jF|C}I<T|>u>gi2uVj#1T{*-1WQX3f0>R=+P
zo$1VW7Lr?8%<5%1vzO)PDA~hoW%sg`GQ!2=F)k#JaXo8<t65{*N}1z9#w7Q$7PyzO
z%!9N!UQS!#wd57vO<v|{_9jm=*ZE8KdEU=H&&Mg3_%!<hA7@<V@5z_>BI^d<C12(1
zj2HPS`wl;*-{q(Dd;F4qi+`uQ1ZnpX2=X)#q-!9Or^AlC=O6}1<`}XsLzlyOMjXyC
z<w&+M$1{yMk#3G$x;ZM@Rw!lIqnu%bR-Pjo>5gb+IiQ>2fqsrBhMBII<+@{?<%wm!
zKUTSZ*yQ?Rn;w8uRydw{VYp?4;hP_gZ(a-mx$y*KMG%w|Ph@%mk$FkP=BE&wn?hnv
zDrs4nq-ST4laoeXRu0Aa+2rNqP@Y{%d2SIk`Gr)Zm(Y}3OmlW6P5Cvn=G4-fTSHrJ
zErYoY^kg<Mn9<B&UL#|foy?}UF_+!OY<efN*`2JW4{#=XfX%Ey*0aVrpFYW@tRb%C
zjc_$@l$%*I+{l>XX5JLH^Ot#$KF3ShtGt@A$m7gq-p=3PNya8`<!tay=6OEOKF=rV
z=lNUac|OUz#@AU__($F?zR9}Dx0$zjmV1kza&GZU&O?4rf5^Xc?(%#7O9*xpYaz&2
zXHTv!J92c{m3Nx`MaGEd=y53Dj6>NLNEMhNRcwlEkrndAmZ;>}a<ae*rCe*&@@&z{
zbwH!Y8Qokr^oqSP&iBQz&=0eM0IUjpvCIp=HYWi4;&7aE0&y=6#k(jH&-_UIa-#^z
zO(3*5hT!aEBC_L&Dvl>ECz-gsEE00FNi0q!wJ4qR!hCWHvna?bq^P)*qQYXz^2(?w
zs-QBblA63~nsRGsD5#>PsE)SWI(oAk=*?@UyQqz!{ALDoT9_>CWV*PU$@~tM3wxQ*
z9b~bvkIm=bQ83K8>`6AWC%K$G!sYBSF6Yg0C2yAN*-P9in&VFHGIw*9d62WltIwCa
z!sDV1-YeST-Td=>n7hgQ#h3XY_aa~9UF7qki+quNg)a(j@lEzMek{Dr4~4h*vFHIm
z7v1NN!n^#EdyoGWzKlRnrj9_Uk4ULLdxd(4m*}vk%!C6)1{^Fk`E!R0%#kU#M7GR^
z<7M_J7dfF;VvTyS1DZvys0rQBE^|k_%nf6qJ7#4*7!`S9F7(E(+#jo=P#lW=aVd(x
zy(A2e@(|pMLh&nz!nY_Azw$&v3X+H@j3=xtk$7PeaiwV_3ZG-7ky4yZwlJHF@;ow&
z^2jeMB(J0ZVR0c91tkc}Dyc57puVh}+VW}|gmrY3*U(<vNJnWM0|oW;2|E}qYhzT{
z%80O&$?{$nO1hXW>S4Zgkfri|mdc0OC>r5h$rP81#(AM|hHJ&sydYfQYQYjWOP9G*
zw91`=RqmFq@M_U2uL{?BRKCjF#TR%_c!BrI&heMBOMFs(k-rvP=98iud|G~;&x>yJ
zRp}l6S#XPIrMLK@<UT(a-{IGim-wah0l${s=RakyJ_pfcd$~5-s&v^UG-gkU3HwTo
zIZ$E9{!(M4Dy=wFVaw4<YmS#$BU5UNqR<YdY6nz=_NbRRqE_k5=`t^Ls=d)E^~6Bv
zjfKz)vr1nqsspeRhGAb7j&pes4#HsE%VY2?i^97qj)0Oxf-4gUDN7~1DuK|7WTMNG
zi7iVbp(2-*vK*2sbIGjCBTZODW_dn&!UFPzB@|YbQCV4uu%rfIWi3r*_0*PB(OOwW
zdu222l?`+V8|W+Vq(|7!NJS?@)tyXMb~9Ps&8)DS>8f7lEBjb18E36zn2m}lHcBTr
zS2D?^@)<5yOmM4Wj%(E`+^t;XZs|JrOV)T;w#>t_HJ(&#@oM#1-Yz-Mo5FKEt+>En
zO0M!r#brLNxWr#eZ}3U=b^cy{gJ-4p__p#UKa}3%S=mE=F1f>x)sOg9_%eS~y~e*Q
zUPrLK?ljw~wb@-|!cL(H`-G;5)*2yMVTELcF;cZ=NY_{(RqcRWtu2bRj-0G<Mxovw
zl}Z<sh3=?Tc%oD5gI0wHx>erjS9)Pq9f(zx9~M;s*w+VOQxk!0bqJ0XVR+Vs<69qt
zM@=+Ab+H6grVw16KvYE%A(dIgSEmyz%p$Qii<HVN(uBEW35&_7%A=sZkb;^L3hK%z
ztf@d)TR~OT^VU#XTSY^CEp2u6wA9wqRo_H=MJN5jP6n#l7^>-Hu)3Gw=P0#9Obh#&
zs~u!jILK1P2<w#-Y}8M1rfPx<74uxIo#SHlELUn~cu}~*-P#3iR;+PHxXi<f6<(^{
z;PtvQJgzyzTeX*Xqw*3TRKCDRwO4ssca6W+UFKuqRlcaX&ga6Ld|7joZ-uw{q3SN*
z*4*L8%6t4$^?=`nukcItBmSs;6M>*!2SK$Sdm8lF+hEMTW<&Ng7$aU|f@Hl7QqAT_
zHP|9sXN_!wGji3ooUC<5q0SxkCQsCx+&NwEhE}r&2K52xHTYv#=Z#sTFXlC2Sk(t&
z-5ic}T`=~|p}5w@<6IMmcU?Rl4bgZvCKBA7KtO#mVGWst)}|9tn?*uh7Kt@Eq}3FX
zT$4>&eF@pMdF0fUlUrXzSxp6{wPgsaE2(a%qq@0)hNdPOo118@X`#8Pp4O%|x~g00
zuWO^bv5SG`ZYG=h7_IAJqH&0s>JereMp>zyV7Y0O&E{#&){k?hd7g9i3tX(9<3jZe
z*XowIUAMxEwF^9G-r!F2I(Mtj^04j<Pa3y)tLEIFAWy5ec)#faPpfb6e(iNWs=4_m
z&L@p``LgB)U)Db4S@j*B)jZ^<=KK6m_Z;G7{?q(~Uz;97!y^QO23@wd8nV6FoE<I3
zh&@N?Fh{)A0`Vpbq?;W$-ss4&MjMWI*dp8Rz{yq*RNCCp=x{@`(G`tmPqbS7&}sC>
zq`@1r_8^Sg12Jt1!J<7B`^I1#n!<2uiNvuj0@sE_Tw9~@Z%e|fDFOfH3_=@Ih-ywD
zq%niYmJA{r^NDZICBC7EwALb08}rF-E+@aeoSb$crA^h8wh5_dsHU>Dk&2dD>e_2)
zZm6ZPxt_MBHhNlH=xgexr=gdjmUf1k2bt{XW~5`7@wQ&38;4kI9%HF(jFpa2R+?ux
z+cwSFmI=-^FLJ4UhO6z%ywJG7i|q^CZCK%6<2o<5uXDHc0uS3ac+|SdYYi88(s+rd
zjn{eFbdh&jZt+RmRX%ID&KDhb`K0YO|7f_!Hw_Q@uHh~}Hs9l?_6Pjf@GAdmdX;}S
zJ>tKOkNI!&YX}70x(M1#+16!*XuA>ny3CPiwc=2xH3xfak#4c$NUH;~J$4*xb>&2x
zBMLpvsI+==s@nsNZXdL|JUHFqg<hv0`mMp3bcbWw5rk!D7&cvz*tbRE&=!Y7OAIb;
zaX59v<Jp~vZ%YD!Jt+iqq!8AbMrd0)5#1TYwPuspT|{DQ5oz7Uq_-82-615mwSs~!
zA$dJDlyy{7-YTT3rIymp25MTHX=-htxu>4SmQFg_TWIO(ptq%y{;qDiI|dnS?P08A
zkjb_oX1WGgXdhy+Yn1u+X%^bXSnio-wS9rD)<w>D&T^@1kqezGTy0<AM(ZlK+g7;K
zvcbKcE$+5l<kgM~yxM(<#~m;5M(1^&wqNG`_UnAqbDa;nZ}EQD4gS`3pD$W(^I69o
zzUscmmmT-{uI**M?|zx@TVLac_DB5O^Mv2JU*|vV?;;TCGeyv0@+ZiyepB{#S|RZq
zrPqdoJvJQdx99MHD@XgCknMNjWUmJbz0N3hx})CjjaIiOY6HILb@`#!6M#X#KYHDv
z7<NWs(GiVRZ#ec{aoF_4;o6miTUQd!9SOMhCE?$lif?BUzMZM~_oouomritN1`*wP
zB=i@PFi=2xUonY2Wu){}kkMaBc25=AeKi#JS5n+nN6A1P75z=r^wrVW(@sNg2Th$_
zwDz~t+TBBEe;0iNz4Y`CGSuC}MCTyG{o_pak2BLX#bW;mi+wY!cTTX;G09fPG#kAO
zT<o0VQr|k)yO+7qv&@aIHD2sK!=2tO?saeQpmUR#2d?mP*A|buFY$WU3%t{HjlXnW
z<AaV{eAIV`zxLkbv(9^b+VLFXAzybs;>&@T_`d6Pe(Han@48>-x1Klnt?vzf?|j1V
zUGE?e^cf*CY|O4fQ}*^*u)oh5(Oz4`hpmwqw&O^j6NiT#IX>Wke4i%@ecmXK_@dV9
zhw6wQYW)FdkNBh4?}y<~5XQs7nDj<s)*piDKqO`(@mTf5Vn3LKU2i-dg9&(!B;wnf
zOhA7!e#4pgj-=r~m_@{39-)JIg!ktYJzPRue?BQALQ?umNEs+5XSkfaAtA;6Rh0Bp
zQ8w5>aZe+aJ&jZhw$U`wLhV2&js0D;546$K*GbQCH-o)H^!M~K);G#%&lppEqm1{A
zGchp3T+ak^{Zp(D&a>3Nz}dbf&h@NvzHf;OBkNr0UFY(^8drxlxjD4Oy@4~_fBqrE
z7kRn=JdgUW@VM_PPlhk^bm&FiAGpm2!*}^`=r*79+~SMgm-wRZ0ble!;G6!}csBHq
zuX|qRpZ%}#ui+>B*!wnr486hc15f$y;F}0`j9MWWwPO3QEuw=~>>9E`bix72Av+`|
zT{$%5$dO4Wq$j;NHsOKXm@i6WekhN4a&pWUmGMBdM?%pU3`A=r6#emVOh!U59*o9f
zG7{T~NNgt)aUP1sbvzNrp?F+|5^){R!gnwY@5yWeCNc;f%^+$rpYX9F;)e@~8Z9Mu
zu$;uv3X&#DNtvi3b3{naWF0wU4dhQ$Q8eC6*>D|ILygoAwopIZMg3q8Z9|>3kMz?$
zIY7r~4}*h4bPtcvKRL+A=p>`Vqs)v<F*82H{Lm!JL$fRo&9FW`&-&y7=O)(J8d>4e
z_$F5-*10^i#nrJb?u}gF_QYjg9=*i<$t@m?UFP+XtGqgKleb2$^4|Cj-X6Qb(}~;s
zW&8o34!*<}qxbpy<RiWweZaGk*ZFej5nqoz=DW!!{5tlSp9Wv&*YUUb-^klA{x$-^
zm=)WmY}qku%id8N#HSq*opeTW%#j0QE=bOL{0VV<#tqpCSB_75B0u4a%Cr|MvwobK
z@<n4J0QK1bv}VFFn2g3~CJLkR2rS2<F&~e{ZZ;14*<@U%;_;YH!R0x|SSDU$nFNew
z5j>ee@K_O%qq)S)785^SNWxSh36n)6O_!4~UP0<;HQ5tF@@Jm6k-~`@$|oBUPP8JN
zXr^wujp~^WnkG7Fntt9cTBf_{m>Fbnte=6&Q3l3`8J`$pbaafViBTq}=UALrU}<uS
z#nCxdM_1UKUg6Bt5|_qS*_zqlg_(0)ojJ#~(R19L+~U^MB_2+{z$@b~@Ob(%k0);O
zc;*IAX7BK1{6*dyyUWwDTYNlopASdx^V!%VJ{y0?=hKgPHuE~)O+MzwnaBJv^@JZM
z-sHE5C;Tz?4*#2eoBucVK7ws?wrrcRXZNBNyB4k3z2LyUMHdcDJ8^i@g+p^*NKLzP
zbkUPzGaekD@<C<Z8>NLHl&6AFoe4y3HiFZ$p`4xy!({sZP>g32FkgtndLaS(sTAxN
zQm~y($6+=Juc-_?7SjosO2>DyfRM>tLTB;_n$0I<vVe%$BBB;cNm(o=akiYK$#Sx1
z>&TdIq+qdu;<<YArdlYOYNc$d1L0IF!kHGT7kj9m?4fzSht9bHI;Tfyn;E2Qc8r0!
zNe1Son3$eqdU~4anF%Hq7g$=DVQzMjGxN)wSy*9fW`T1HtDK!Z$EC?lu1&A=!pwPY
zPoL%H;wA3Soaf%;b?(hw=hgWeys>bb*B5T{WbryrX7BRe<ZV7&xXb$sFY)2bD||Hb
z8XwQR!sm;x@%P17_<H6|{yF&u&lcb2`}ueHarSNgnEVUB&%X;(PZ4ZewnAjZf;}rX
z?4GkhY|akJSw{}6IB;Oe8R=C|4lcWLWW^8JIUi2Wd7-crjQm^($}9e8Ek>X=ABo<4
z6gsn^7_G)*x|D$FLd>5SHnRyh%%$V7l!)DY63#1GxG&}4wUCbYY5{@ESp>}%5HeRl
z&}tDe^94jNmk_g3Leg>-Y4c@dELW4VQbX2k1DW$R<gK<+y4Xy~QVYU`W=a=Zsa)-#
zYNd~w<z8Bsx@lY-pk;oLuDKxw=Z6?xoML2tn(^fc#up}-UY=%VafXGtSr%7kS)W~J
zX>N_p)eSaQHrSk9<NVTjF3z9l*6J2FXScYwy2bsu7r4E6nFmW(cxmMtug%`z)rC8}
zv3j3(7hmM<<-5GQbdQf#AMn}2OMJfc8lNw`%-@z@<I9CdJez%kuNU6pr{%Z#*YZ<-
zntO-eW<TPW`M>b{>_-R$XKdNN?!=BwYj&>LvTw}+iDgIjuexw}$rb5MUk)yLBfa8_
z?6MECt3jMx_eW(j9QEa3G}lAXTn$BIGZurjX!MujF<eQ&WIYMXwFJyo6R|jxfWu}g
zuIm}NuBGC<k%`+{E}l!-1g_-~xLiuuay~(8rG&4P5w$ENakHAZbs<R`LQ<9*$=YZj
zZMBB1Gqq$dH&C+LPQgYe!nF>n*V?Gu=%jk7i^lanTGsn$-Rz}nZHTV55jxj~=vkRy
zaCL(5l^MpCXP8==WnpEG<@HsT*VkEHI>W~L88+8f*j(9UbL~7AS1)p9=`vSVUf|mD
zRjzMd;`Z7L++Kc;@gfg5?(p*R9o}5K#XIW{c(QSa56-;A2b=f!_{;-7S$mDYZ9L+O
zl{fjv$`ig?dy8*Yp78CNcldtuZGK*Q$}ejl@}HFt`1jgh`S;o<2n1_RY~OTb`&mbJ
zoONaYmMfy?-H=@K;NTf|4s5t{_?!>YYk?d+>x<%sFY@a_sBHvsYBQ2k8zJaygrRXZ
z7X5QE7_CQPv=)QeW-=xl>DZi2#eORtr?m_m&;NfV(|24G2HwYU+Uxb{yk56$@9K58
zw%4=QUiZ`1_O!!M_uhz#;6NNWP!Sazh>8j*4p7-UAt8(m5(tC@5(ps)VFZ#8HiV7U
z&+}@ZKfbTe@BjDfx0&fV{>=CTCXhLqyIGjJo26O1Sdg}x6=^{%N!`Qx^doqu9%5Z?
z2tK*T*_;*1*4!ib<($MnEtK8a;RIzx5SVk0y{Tt8lor8})F=*TUL+*@0^vE)L}W&D
zGW!araxN2@d7Y@-8(hgwASUxBaXE>^XWiy{)*WtUq>+@K$erwTQq$AO%E%@wJqKZq
zklge<3bOJkNE4BtDWot}h%~ndMOG1-+#<9YQZyMdbZK&`Qq|PusHw>;!<<`+Ij0J1
zj-J+34bBW5?hGwm8CAHlO!Vhk7)UcSkYi*h-Naaym3vu@Ok_9W<(2ylURl$4Ks234
zg+K8`=5(GA{lZ@|XY+LKd?w}m%8S_xnIxFQ%c4cRlDCN0g-dxWXE9T<mh(>53O>wQ
z!PK0!e3b3Yr<v>dRIr&ZbA9<#;LVp=eteVb&oto{z87ud2f+@0$=u3Mq8-f7*~6lo
z02T{^SSAc+NzMUQ2oJDc7|bd`Fl$A@c;_BwbKVIy<%Z*%eS(1O2zKV2CP;Lay@FF5
z6rJNx-X%gaBMA{)CRA{Nu*|C*&%8`z_EjP>V~NbZ!3EJxVzRFjBT67PFOjR6iQE#T
z5TBJsN^T-)c`2j{(@4+FL?Fr}D@%wVPefjh7-?P}#eyP~f+7^T`6#j^R0xYu3uKh%
z$kB?F)QZZe&s9^GRgOuhqbWy+C98^-ylPy+Djb<c968mva_i_5Hqa-s(3@vsB-6^M
zz`}4=6Zf;4@bVJ=mxptI<bm87JTCf?Cvs=-SII9tQ!tn31@o9BoX<<*1-vX-z)RvK
zye3}EtGO$AQ@E111Z#O)yq+l{Z$8Z1zz33z{715ZPbA)ap6AVH5`Vsu`0|~|m+u7r
zd?(z>%z~}_DB8{JyZ~nB1u<6`#L|L&f1oTD?PFQq5tip4Wo_;eHWnPiTM&j{ZWw-o
z(*%f)vpx3=J0y_=6r5qN_&h<PD1r*2I9hOtW5QUD<i~PCbd@l19A`vVi4fi3k|3T)
z!8I<5<GGTT$Te{ySA?nD&P^s>n86)!Hc65UGK9Hg<))J^$s|)KL{cCjFJD4_K_P_&
zQi}5nP)H;wBvMrQaw-Z+&<N$|gr!tTR2T(i)C$UIkW~J$MqxF!JR>ea4fZ?(-Qqer
zBz1HbSQ!*HGMLxMh{VQ-sDbg^HpcSX@OrRtIu95B%%jEAc}O;sM+<-9QR%PzHGdXQ
z=P%;<f?s(?HkZFk7VtO8GG3J~;_t=Fd9!#WujjAe{o)n;OXkD-#XkH~?88*)CO$6k
z<!hNApB4EsP3*^a;_ZA}6u^%KyO>$9li9KWW)|#Xe(`SR73^j~@m`k5_OmGe2rI+~
zSy6nHb@`!qOT*YwaFQ*BVfYn<vt4|K0O?r*B<I;Jj$*I$EPDzr6C{Ztxaa~$B$o*<
zjv=h*_r?+-zR87x1kM)5b4hlKn8IY@#J7o-q;kC|oj7SGx1{OB=ckaKpFz4bi)>jA
z>G|2@73Pp9DL_~xq99+2Oj3ljK!IGUL{(UVMqGlnP(gX25}ibap-6>6qNYx)!6>e#
zNvg#n(bFic!X-B15L;+3Fyoe)>66vdS74#P(8`$D#$8zxzZJWnpcStN6hHBh>_;9^
z&fw4TnLHu;g(r*V@kGf2o-3To)5?WRk}lwd;)T3gw35k1OZi9PTHYvL&O3^Ayj{GS
z50z{AXYqPIQ26pukuM)Bw(^N=BcIFt__Aax)08`yrrgRjSs*`_1oBhKUS<^qGGDfv
zIr0N6EDUCm>@cgO2Uw;!${NLSyo*lYBM)J-G7P_xaJCeM;V(bSuHv)oC_Yc1;v)N{
zk?faUWS=scP+1Hig;zLHc$L$|*Ev;qg9zC*&J^C_V$mHg$>O;vPvDB;4l%{4#22NL
zP?W{(;xv-w0@8}p$tcVvRgp`ET!N@bOrD~Md}$%Y3Ms`!MMz5uQAmqXD`b>O%PEzX
zQ(00*jkJ_nSrtZE6}5$x7>jCXlvQJsSJ9-@(^hPuL)t)BiIr}-i5^)K-Gz4gm2Hfc
zG%>7nGOB3iZb=(ne^SoEOZhW@Dx1rn)$@3)YynTG=kSzjG0)1E^0aCRlgbwGLg^A-
zEm_Q~s@42MwvKmXD|u7Cjw!13d?5E>s%#Te%l!C6;lmf|jr>QogU{pve5>Bhx2m1|
zw{#Cb$anHX*=}Yj_A*m-kXed7%uyX+UddtRtB<f;b(m#}!>m@EV4XaiHKoV!DGSH9
z^bFgSXYegO$u3zWJ4>Pnl%Hdd{1QQBQ3R=D2~kCJLLSR8^$kwQVmYI@${G1BBIVaP
zUviss@+6{5ZgWMRLYzFAo9cApWZB$OXOf~2k}S(3xh$J>m53}w9y!V)gfc1lCB=wK
zB}n9jC{;xi%T$yoODR*RDOD(`E-9r-U5T-znmV-(lU#>UUPEJP4J}FoEix0%G9#^W
zBb^ExJ<2Bf%Npq^vC}JWV^G<~a9K0ss&*#Iy6}3S;zzv7XY!zO9*<Ve=aJHdJg!;H
zvzqxlQ@W5znnk==wwy_oOPQov#w)5d{9U=8$z`i}vwSsgR(LZ-xsi`bH}SE?pHC_`
z^SOEppI7eS^NMYJS-OL7RNI(dwwLLZ0sK_HpBc(vW~=rxr}Pl>%MLJCeUxR&<E&60
zWkqEOE6T%JT^5eF`ZSxBC-Eyi#b(uc{8W+bsElM=#YF;2W7w;TW`AWAM=E1DtiHx^
z)isW)VmVowz^T%B&T6i6uIvuyN|T6I-{O+`HnEkdT&+ywdT9<fHJRKh%OIsvM4Bp>
z<Vq3g<wDYxdE}K!5UM1I%jAekr4*=(QK+O8SCmq&QBhV|iMCQrxw?w#G96Xw3aTrr
zsMAzYUuvMSqLyZrg{JZboMk3l>L%Q!Hr!<m^q1S{Q9J0<v@xi0GOluRuhPN2G6!B>
z6|?Zt{lWtk3wXSGHjkCh<uUC-{!+b|r*sRMRJDv}D_8MK#WG&eF6VF6tC(Ev!)sa}
z-l|^5n|dGKuin6v3V%M(_%T)E&u7&Ee6A1VtBUPRtK7r)nq7Ra-OUWm-v0;D?qjy*
z5VQ3m%&87xQPp7<>W;Bk6VA%&FjnhAS*eM@TOYw@{Yf@zBiL3Ifp7T*wriu<R(YPC
z+RN<HTp~z+nP6Qshc#C?s)^@_{st%X*9g-ma$1wXSxo|$bjh5nxXs1#6fRYz6Rk-n
zp*o8j8UYE_+1x45A*lhc4p8wTpLCs=)bc`dwS{EsiV$cO2((Iyw8i9CsE}*RkyVtT
zEH9-*uR>i>iAJwSSEZ$@Qb)a3kEu$JQKP3xZ=peFq^Zh;Lu<mVG1FdU!=-JaQ}3Wh
z+s0r;GXt6q#;ZFR*E*Tdb>QVyJ)4JXXY-(L4v*H(<1xb`9;x{qX9-VLE#_(C5}q@x
z<wgBEUaDEe<eF8yY1qhQqc^YDdh>qGCf=>y!iUwqOx61{wQ4*6soKUD`t5wC+r<~U
z0KU`h;@g^i%+Ln$b4@Taj0gEie~`Jl5PmfrW`QA;1vST6Y&gN{+S4r8pJJUMoDEeG
zY^;gIuR4nDH4y~VM6t6rhHZvu0*zM*tiH@4Lma_1*EpoRPN+VPFhc^Ts_t;2_7*1%
zw~5pyb3uEXOWI5>8?%YiW)Ndc<GMbRn?@1wS^;;ALQ<<Gq!{wasS=S<T|}0?kQ|*7
zajgQ0K}kW43aM6&s<s@Jp&YfYl8V}LG_^YPRW(%UYtU=;)aZ=VY0X%)W^C0qnrj=d
z>&$di+32oqp;y;RXKgDUT`R-J4*F}_7&W@Nr*-jLwHvQLnSTeF!vm(p{K>eONA-(&
z!nA^C>Xz`dc^S{ut>&4!wY*~T<`wfQUa9fsHN!^UuG_%dh7G)9_GgM|Gw+$UGS#qy
zf19`SiD5fm>UZ*~Ie@QBd-<U@h;Ph6%%~0Kr`m(es6W8Z^+%X%Jj{aH<1DH>!D3T5
z%T1?QVG3hq?P=DV&#~4J$)?&fY_2_rU(GqT)<>~Zf1YjTs{|Qh*j*RLLGyJE*2i+d
z9M56HHBK0Aam<v!8N=;AK+e_Q;cRU(7i&_upid#jm_eK|orIb^Zt8PMGUSkKl8{m_
zCc{`jcAbpuIypId1)>@`f_eqgS`~6*35q%mCAFoL)@V=~$|*Bys4y5X7>v{zO_)s8
z)SBzD)>|>x8?hQp*!1<Z>YHh+ZNg!+)1hyrx2Bmvb1R-&2mNLTBl<4x)^tK$CteRW
z%)`sFh=(lmc*wGp$E?eEs$nTlnpg9jaVgK$E$5|%l{{}-$4lllOm6VzHPa^EGHzgs
z(TDfU{`|}6$9qOUKC1KQGiv}}n78qnC4eujd-<|qFW=YgXL|iUW|)Hb$$EfaEWymR
zgfh<-!W`o<7Ft4?ZwY0U<rGUB!dYdBWKI1!d`xHXu0PKf%XxfFm)T~z$WC)C0d>*r
zZn(-W^L6%E<JfPG=V0A64qM|nVoK(u?KUT@Nu09Y=Bz1^bEXs`ZJAs!XAo-?a^054
zb+dptV-7dXB9bgcq}7Q?vB=12kdkeal4~nQXjLI-P*G&7Kwe*ttiBvYotE+jJtYm*
zs4aT*^;)#%It=wjjCDpV^(L&w1}t?Zn$2dK8X9P+Ys6`4!d2fyyRDrbQ#-w;Him6o
z3|YDvw{<aQ?dNWt2QROdMR+wY<YC)F{%l>u6Sh_S)w+^rntw-F#WS`wJZE3U%huKW
zqsg1UHT&|0)rZ&YzPxMQ#Jjew{LALc6pJ4p*aG;-x}7hqd-$v=fG?YV2ie2-)&qQN
zIlwggK7MF9%1lcrGn<d|t2LC_mT;D~9A}yJIE$OZSY|)XnwALG+N1EXMzXQxGJduT
zY;U>9Hfsz!n_}5+jV7r1CVT8x2(rZy+?c?ThD1Udk~w0(%`sat5iKd4X~^V4LmC&F
z(zw)=MpTP{I9nER%>r&%@`!5^k<=n4sX3oStCY+pDJfPdX^q7QtR;w>Rpd96B5u}D
z*rcY=rlG`MNm+x2k`_H>_A06^dNh`5YFdocHk+t#w$jjO#$q?qWV6y@YoM*khNIDi
zyU{_H-9dMgn?ZXAeT{C0tsRUs4Dee+5BHjf@bYS2%I|xic^Q9pEaJ(QRXpxk&0p=S
zdCI<;=Ni}YZ0mYna;#;t)0e+DZ(wrsW?r}ZGo^6{Z?<gbomM}lHt*)c)@}UT5y&S^
zL447;pD&!jeCyc9G{-)^Zw=;q=MiQ!A7z&FD6^WwSkQQad2Odz+IXC$&QmOFJIm_k
zbF6fpVQu3De4OX-w#VS#c%H4zF>JM8CZP2iI~`Zp+jyP8wwnYuT_dRR21lE265_l~
zNJ|pOn-e+Nn8MkXWFi_<xaiC#x+#l`tvOt?=Ww+(pX+UTTyqqX&{RZ<vxu}785zyR
zq&QV%x5yFM<wzU~^6YBF4mHKC6_hmVD6#8N+I5sU4QQHc(Y5K(w$)JUG-7JAP~$LR
zZfnHiXrj5X1xHgett~FxO)eacHr&lF1{%8<bav3&;%3;{#b8Sx6K(z6b@b!q<z9eS
z`$8UWUCN)^7xQrIN}h16=Si10&%4&~O#3<}IXCb(hc}b$8+hHhi8ng@c%#FYw>!4+
zo@*=bx9?<1dm#UG@8M%dAfLAd@|kNt|LZ!$SI%I*a_nQe<M$6a#?S4CnB97upWG*y
z)fURHt!J3)Jj+7&X_h)qvc`Uawe1&JXFtaVcQotUFW}>jVpHo?{2f;b=(x%Dj#vVn
zH#uOx%^`aNM_fr9a>sMnok&<mGN)QIiEt+q=}zaAGnaFY3@*C_M7QS=Z5MN;HJ_WU
z1;jh^NpeX@bj!J8myz6FL`Iu}bh{FPU5Ui5BHvj~zDq}uQ%|9@0)@K<h0}n#!-U3F
zPnD|%U8{*IM;*287EG>s>f0J<Xl=vdY^Jrnl_r;+HkX5Lmy33nlirSAdR%Ts?A;7G
zdl_>KGGX^H(LR8eSN9UUx>oUsdnJ##*785@wLJOzT<dw-y^cv8n|ZO_mlxVM@oM*G
zUhmw-o8A7r)3u#<JN$Ux9l*PtyO`3oi%;4E`KWsjpSut6b;kid?K;5M&V78_8O-<H
z$N8`O7&F|VOm~Ozlj|h2+QV7c8P3v<Q!MF>V7c=QYkDGB-F|^poiS{5#jvIQ3R}7^
z<Lkc8j;=ViyJOkoif3o%HTF0YIq1B@L01By?J0zIr4ibl&as|s!rHTm?8@P+JBy2*
zSw#0_6Xg<fsY5_?r<j{vVy<-+5Z^5!!7V4Hy_h7Yl9aA8(t1>gx;2Qp%MrEf5clYi
zI<?4LwW!<%<ef$;dTP-2Sg7hUV`#Th>#|Vmv|;XP#MWt}-et$$>G}i0(ba~#!-2EC
zlP-5VJ)M0Fbo4UP)5lon5O=$OzlRuej^gDtu!KMLFX7SNRXpxl$K##e{I$!QXFJ#Z
z(WiUY^HQfTuk>!=l`cPC?%cv#9zWjh58#dNUA)z~hxfX7Fr_b$4}148wLh3oJ^T55
zAc!wJk1(z85I+nY<A=Ube(Vb8=bmtW?mo>-PXxdAo@QQeI7>YdEbl(U(!TR7>p91o
z{%AJz$FQdFGV42I@$b9BmVqnm=#FJqPdvN(;@Q=Elfb?N_6^+OaDO64`V%?Ylg`oJ
zWWxG#IMtU<M7NMreIg?J#a!@6i1LWI+>=jqe-YRE3rO%tNa|OT(kUmgS4#RoDQR65
z2>Qy&?yn@bM}xRiPky%!nMX@ur;d^?BkG<ylsy*I-4=A7da6A(be+vqdm1ozwo%{P
zNOQlPhTc}1`dV=gII;J))9vZT)z?W^cQ3uY0}S>KFw{H9NZ$a%J)?|!eg_#^!Gl9<
zd30zc4-I?sWZx<t8Cu7)1Dp8E$VQ$X@#FdaO}x;*nV0(gd3h*+$^8LL9uDO7fgQXv
zu!n#4?PhA<em)r3&A)s1@t>gseAa)MZ~8;{t~Z45hmP`%=Lp~RpX8Um6HFft<Co#n
z%o+%1-oP1_j+|rBNEAzl&a!eOhBcmOyn8RQwl|hdBiHfozk&Z?EPf;L1P;d$FqBA8
zZxZ{5Q#df3MDSn|2Zxdf8OkPnD3xQwIfQw#I5U#Pg+37%hVzLY$|q(>MC?Ejv4b*h
z^cE1;uOMNhn8ZFQcZL)sder2MXb|+5BJh+U9IPg9q!Q_n9{GqC<zO8p0|v@HwUiH7
zsTi)Oa-g2dek+Dy3-x_1)OhSzhni{bbz$puVjt<k)!T`quba-kJ~{__>F(>tGt|$}
zkcWZcQAUOb86Ozp{=jc|d5tW`YkVyac~<g26Ki;4+=r(;n|XZLo9D)Tc*e7l7Y4WT
z%IFp*4f^r&m>+M9?Bcbt?YuP>#JipV-WlA*l<|XnFu0$ogTZ_}c95^fkMPxSDBp~Q
z@Xb&--wqvR`tUJk4xQp>&sk=Uong-KN#>46v1llYC4*;KHX6h7u_)G0Tw=}0HGDi*
z*f4$t|G_x6jo-rGbCYdjiR>J@&F<mb1bR}~Gm*@J!9+ql85|u+A#^Z<@Ud*dhqH(r
z7ju48$i+bk7d;X#jERXImk>Kv$kh=kH%65tjFob0qMX~qN|J`k$r>yt!&6D#gck9T
z0fDEA!ci^xV|A2xj3~xyQH>fYov@)EZa_EKNabiFRpX7+4BIhzoLEQOFb}!0Pq=6r
zcG5P{L7S%&_ed8#o<X|D2k0N~WoXR9;P@DK$L}&eHo@5V1YTaFt9bC<S{|KP$0K8F
z_{+#To*ebzsqrm5IkJ@($NYGH)Q=Z`+ri8C{rSh}4knN6;H`-u-ku2H-O=5Acy~7+
z+&{oaV?lg8dWe6Igz)v)AwC^F%GdW!@a<R_)9#++yNT2Mc<&@LN6zu<{j<y&k7Vw>
zi!2&D&;0wBS#d9#6{AtCxf{o-`*HY8#ISk%3cjOP@f(k0%e_RlkKbhbL_C4Nr4n>6
ziQv&>4vc1UU?hcO_XUKEWpn(u93sZWMBJ5dW;~Cm-wL@rR=}kZDVKj!aAQKj_4~>{
zdgopVx5ibZ-mN5Qq?FXLDl+fu$hudJ;JzN=L=Do>D&!+|$nKd?j?_|m*GTE8iOTy8
z=teD6-)}^B*M|OX6E$NlETe5$?mKDtt((TXowSX*X&djSYpfUdSTCI;L-gDqpm%hP
lk<nqs?~gDxai6g<_&<#E%P6umr2+r|002ovPDHLkV1h_jpGE)x

literal 0
HcmV?d00001

diff --git a/core/artwork/thumbhash/testdata/portrait.png b/core/artwork/thumbhash/testdata/portrait.png
new file mode 100644
index 0000000000000000000000000000000000000000..bc6e5f0de3954404c0f72c5a455f44e996ac8c92
GIT binary patch
literal 20102
zcmV(@K-RyBP)<h;3K|Lk000e1NJLTq002Ay003kN1^@s6+96Zu002%+Nkl<Zc$_5E
z^?MX%`nTZ$LI{L}2$BR6LfqZm-IIw=TqnuI-QC??i2$KkX{kV4x^<y0TUqMcvK6|e
z+rGPdy$AdK;qwQa$8|rCKp@z|0l_|G_X#*G5O72wg_7VP>ViXPNF6~_a0s1!3YZCG
zF&8Lfx%UW;dr#oFM-}(IC-D#*BUnm>Ab|$ado+lYI)hM3n*@Otsrxj^lrlgpFrZXm
zOr^k(I)ORO0#h3HnA0V&rE9MheF7_n1U5|Xab`i_^uH}ixv;s<lk)<19@*>5Re>+p
z_j>b`z?Y}?`tsa9UtSah^V+@;-V}uJp;QDP>=p9y-blU{#PPLMJb#yp=DtA4eL*sR
z2om{Skd9!l)E)%;_OV}Z0Qr4~I3g{LqLeIZd*sm+97cP;5_$qf4EHNyEUkd0KmluM
z73}w_;Vw|aUrG(%Jtql&h!v<4C8b5;K5f$W>yjp=L#DuxJb^wX0(~l^4XN61M6JMr
zR)Hn$`>g2PYe~Prk%4`7%<OYvR?3YfX-8HBo~#Mn+1>BTx&3Zj-0#Dq`vSQk2;xaW
zFwY1=cwuiSuS<pVh9HVN`-HqF9mZ#ZSU%k!#~0E`d@o4gC#g6d>`UeT-bDT@5FyyR
zXD|Du4<NPgAo6=<IC?+^#RKvj-y@5rj2s%$N*L^s$83)x=F$q-%c$UZ@F?zk)$rVN
z3crJ=2;8Ga#J-b+?9n7jT9c$bS|sk#C4H|kd3%h=*<*}Y%9K(WW9p?%Xpl0eWuH0C
z(w21ZvuF5#4MS3POzd@IPR51B1MZxac4KXi2N(Bvb9uivkM0ZN+P)xe><i@CeSthL
z6UIw2!Q9y&$(zzqyt_A=5BJCMw>>d@bs&bj2jci%DuH`@;`vP~o%>R${6{7WfndJ?
zf%GAyWcMR4BZJ(*!yJ>9M@>eNQ!=t>O39%wtBCRbqnOI5Vk2_`hl46O9#F$Y<}_Y1
zYJ^CgB50o$;rq@I{}6mYhtvbQWF9giOV$*ztOX_eEs;oDQoi4k=7W~BAF`lhzZC<A
zY#H3|!k~;DBeG7+?ek(*+KaPNZmdiDa{iDfj~oo->cL>HAMoYLeL>vZAHa*!VZ16G
z!fOX3xg!(79jPcjJ`lr4(n3Bvl)zn?WWGO`$WOBA{B$sr-wvho=l)CtQU|2jbNC?A
zatD!@J&1zbL6qd>QIl6h^RNQia!1fTpn!q2D(3QP*vKEpMn(fSSv9;4oyJGzBmoDs
zh&XhH$OD?h$>}4KH6%^Ol(fUfWXqb9d)OGs0aME4O{tT%r%BF&dKqiF4>-{w>%ib)
z2PR}3n2~d5TH1@bLmsTkxU+r8oAWaMTsh#&)dT)KekhbD4+n8mHk8|P;XHpRhL_}H
zc|$gWw`GNVBp=I12a@?rI*D&&Q~CN}GWTUu`AJ5^uZL6lk8}nCfy@D<6=ab*c$h;n
zhf$W7L-B|_$K{WrcK8H(@`@N9If{YY2`pq!VRPgZ4o5U_kyFE6?i8MfbnunYCg`v>
zkq5PiKB7b7VFOZR4at--C*z<wMTaer9I~P6pe5xBHZ&e~py`Mc?T78?m$#>1&Ydwi
z52j_jnU-;9MaG?F1z%PV`LQkU$3^*I9y#L2)gwVXc_^6Mha-4VA(9skM)8V#1h31-
z@Rm$0e?5}SUD;T^IGDnhGKqXAlgv-DncSDl;$Jd({4Se^V2`W}GKw<D$SQC|L5`#H
zN~j)D=9KJlPRc8yt#ASZc~uM#t7CLT4I3qO?BveiB&&&+{AmJ|b?{TxCs<yO2w5ZI
z4jYmzZ%FbHBhuup5FfT6N70f31q&(_9H^DGrbf}8HhEV%WS!|f>_)Gw69Y%w7*qCQ
zR^E#hd0$qQz1ddsV^=wp%ZG!wA{)fx3L!it7sfM(!+23CoEH>@ys8k-ox?GFs2Ix!
zhf}zFIG(>LWbmzQI^QW|a$h-%ALY{cT|ScsN)O+#!a?@QA7;OzB1hzvIHI7yQRO3?
zlskd?5f!u))zCkxg4vN1n8>MPuY3~QBbvC&spF!okH4}3KJt1595EpLhygLj3=tkP
zCPmSlY$a>Nislq3*&$K3K%(G8xttBn@~*TUaiHypGd=QN^vb(2DCf?MqBrwLyqS~p
zX6Z-}n@5A#JsQTYTrgLaLU=+hoLlnIJa;UH+j2r)JsQL7@=3fYm&E%=6ZlvufxB|4
zd?A;@cM7T8lTYJ&#aw<>%;b-w`TTLD2!TNHFj9&NNGmHKqaw#K6(v*^l{uzxoHNIi
z(N;W#)(Lg=6jd-+QN#A=8Jrcga6h4oi?S|WD%u1nYZGx?j~HcRgepcPsTh%<U_#0<
zTXI#b$Uo{p;R!2B6&<NkaiUJynKoq)x{f>1dBU9mMQ;XAcrvQs#iD`_^T&f(IvULO
z(NH!|1aeL(h^xwBTvrzI^zkrmD++l|C4t*YNxZ3)$h(RO+)<9_uSZk)Tq%jqj-~PC
z@f_|Q&*q+THV;&C_(LI^e<?i#s~lpViYzk6jv%L^z%ex?jviO#go-K}M^(^LRzqLu
zG{z^iFjCRPTJ1D8NA++$u8YSpJ^YVr<Ev^!kg7Q$$4rP<HYY*Vl$4_uq#v~)TiKGl
zqqY>CaHdqrnR-=M8jd^DaKedJ6>qwgeHc>qWJtw>F|{D(Rf1SJ9>B7SADc=cY%2$G
zK`op|kB9PvS~xdUW4V1)$nE2?yrL4%n@3}LM>&BHkEimnQVMsK()da#i?2_l@r`l@
zKPicMaIBE~s)hVpwGe@nx;#?H<&Zt5fQ-5VO2?H^Jf(*EvE!UMu8#IGHS~^aV0hvr
zCaUV#9n;7Dqz-N>2DqOz#^<;$!RkhY9XBUj-Gqdb7Q`R7B30D}(Mfx9RP8A|W{2dI
zJ!PjHC_m;x^KlPa)ZOVg?o0m(ANo{%7*Y*lQpKCeQ$Z}M1+b<bz@|zVo9bcg9*g9v
zS~QQVL~&C!nrDv-dG>^mmyRd%+VObaP)X$7V`;p5DwR);r|{XyJib)P;oFm9?x~3R
z^<)nBPZaYnmHdZ=kFrnw1Ttz0$f&7tRP_X^>ZefEP(xGm6q={C&{jQz-f1n&RrIjd
z(8F5Q2=`M4xT_fBp=pGlstG|VMns>sB1+wwSXC>MPg@{TwIlbmJ%y(nkf^&*b<&v{
z6*sC?y=Xq=NvEnWJ?b6|o%CW@)tgE6U=~jLv!oHsib^=!r^7jaGKO;}qq(LY#Z}FC
zo={2T=~Kx(ub#|HCq=xZn!+2WQhEENi1*cU_*gBQPc`!RMx%gl)e5+$mdnqYVjif9
z`BSwVf#BpZ_G&6~SVM(FTE|e*R6$Wo1yxNA)K8v9M^giBO)d1aG%-1&iLIs~&T57@
zY8v6JX^w}cF+Lhb1ZWu(qh&>`racMjwj`glA@#HqxtgxzXt`3L=18%Y2i2!NsZsZ#
z>9j8$T3&Ri2QYjlknxj#%xDHOqaMh@sc@E0g|nd+&F+~n&T9#I^mGi5Y6^KwBbl40
zlX+G>nU^&adGkyP?`UOnM=PE8PG$1x=`21!ox``MviXNr9`{cb@RNEzf2bAnZ}kcU
z0u4p>>L??la}0U);~dpKjjEO=YMSb3XrJPYh8B8fbTHD<!t{(jmO9$loH4{v#{^eh
zQ#^Gn3DmYESlya19Sb70EfAfyBSpuCOf5(9)g36(b*DhfixLfQsx^J7*7BzHj1S#9
zfply8GoT&7phhSYnh{K&4r1<17%RGAtZId`qZ7@pZX%CpCU9Lx$YYvGJfo4oa~es!
ztee8ir&D-GJ)O5SvUyJ<n@>;Y@`XkY-{}@|?{p#ePZ#pr=_3B6Tgn67Vg&m%k8|Mk
zF=WoDaZpE%W7_Jd=$=AdN1c;e8ffZhVW_W*;Tc`5G!3xVHo{5E7<XNByic3sqiIfv
zjv1j^c7*F%5wBxSoSrRdnoeZvIgqF2f<(s?vA#Q{`d-xOxl^m}N4=&uo!b6%>4!3)
z7sjAg5HqJkm^~fJqFyBHno(@&N3wM~mR<cAuAE8WF`Yyn(@EuNy%e6)N##X75wD)f
z;Vu0<-q*|Gz0>0Vfj`$R;;w!n_jC&QL9c|L^@@3*S;?PT4^LW48G+$(WOdXytgV8g
zz9vcrnyBiX=8Vp1PV4EQtF48hp)N*-23Tq9<E&?ZtC2CDI;MCS*$`l0PK1^NVY*HT
z4Qz?mcS2<7OscjESw^1Z=y@P9^rFnrhiW5#nvHyD)AOTMCzt`FP=>UF7}gDEMlX_i
zy(s1lBUv(xWJ@=OO|3W{(GhapFrI6M3EVOgaZ4+m=k(KgK`Voojq-RyC!hDVbNN80
zkh@0t+|?@L@7jgj(<<YhVLA7W%J@^ag8v#+BakvyVZWgohm21lZ=%jIT`g3NbWk_a
z<cz)+8b<o)8R(*~tB0wM2{!shI2st?XlRLtzA0V?*7%uN5Nv2ijIIqrLpzcUTuIV%
zLZs_OuAv7x2Hq6udr_h9N4cIi)rS7m8~M?u7fgpi1bw<uj2T8SViL)`LG=H&WDv_)
z!)P{*lel1%$TgFA9yLhhhK`6^MrqtOPUl6FEZ#KA<sG9uJ}@faeH{sZ)h*$!Nhx;?
zi};601wR{>^FXJD2gX(W*Q5%;UQ-pMOw^DuI>iwKb(D>@P&U)&gqZ>Ardnti>!NRJ
zh=Hjw#%4yCo0?-|Zi1_c1@7kN_?y`gXlg@<p&g-ycEp-HA~g0ON#6yLktdlZUKE<U
zQ*07Im5D#KM&8uu2h(gANSi?f17^Vtm`5{YC}h$wnkjuDtHy~e8Ar2en#6hIWG)z_
zaLqu(74r;knWyrkQ3}tS<?*V4nAc1Tc-t_aw+(Xn$hd&J#wC1i_^@;df7dVLXM=Kn
z)vxAvqgwtjuR<U&Kgj`eH4d0+bI4qiBc^(&8fkIDLKh8lBXrI5(J?W^)WjGwa}#Wg
z&2ccZz{Su4cT0PGO>7A^bt1sro=8&%Vh!C8TDp*I<W0J%2ieAc6q$KZVB|%qVGxyu
zzBD|nYZ*+3c`$uup$wTuFlrXTsA(kAhC&vM<5)9JVAVK*E#r80Ei<@gmc$jqOl}zE
z@T_?{&s*g4qFDiVEOL3nP|SNqV%{~+=TnOkzBZBYg=rZ-n3ZzhxSC%~D!6anz<-RY
z5$v<pKwzfHArnmwS)WG9TpuMXUDPafP_@!W(^?-R8xssItT3}S#mdqeXDe%*tnG0&
zwZq5Sh5%D%f=peBv2r5P!j)umXHsmu$+Yo6Z0Sd#bpQosJ`|gWP-*2yok<`KCLwg%
zMAC06q~9!z5tBG(tP`2ENMzMQ$hwV)HH!q!o20R8lguM#nOrl^;-*C&Pnl%!ymdCu
zn-=oAnS?iON_fwrhz~6!d}>q77iJ}VZCcF_=9T<nTFFmVHT-H(#~&7r2=>}&vDZ?U
zL-u+cverVuQir4Vx~Q4!anjNh4Qn%uEUhp#x5CKQ1`B%|9BdtMuye%C(wP8TJA%#K
z2)1w_+}wo(J5NORzNA=slWFHqwzV%3%V0`vLnyHhrqUveX4?=N?StvEkEYi)h5_4H
zCTwGvHjiP^PQ;RJJgYWItXZe9Yn8+mixjTg<opl(lwB@2ZE|_hJcn28b9v3ah&SvC
z`M|D(Pwb2Mt4$?$ZL0aws)lbZ%lX;5hMz2I_|>k3|JXJm5ZG!VZL7;c2W<}7>Z5FD
zjFPoJ$E{7!ur);2+7fLWbM$O2u(Gwn!rBHW2M6389q_Pq!q?WBAS(|-tel9pb|t~a
z6QQFUB6}aw9fA;B`;%uCK(T`#rB;E|TZYhN6+)wpkanwZ`fcLrwU1)ZKAs8dL>BCm
zS+a^}*(QxO$8>fbvp8>)%5}?hu2|)9%Q2IimSUc<&gEtMd|tOI;x(HR-nA^|6U$=m
z+Sl-vRV`oIRq?%jJwMsi@T*N7|8i{NUpCDT3+o_dr;C)WA#!#)$lDm8;%vq#J2Or>
zTB2)bilK`wdNvjqIapw2<A}4f9S-*PxZ2v`<KRGmvj;&guEaRH6J_T`vW+(>PJU$A
z`jYJ&K%Px71rA}9*o9GJ8%?uQG);D~wA(%`oIt-zB4f76j5@|MZ=1-nQz}a?8SFS^
zu;ZM;Ij3x{*ktp#OD2yy=X29Ohv!}LdDXFqHyw(3$Dy3}?2Gxxsg%2p)qL(y%UAXd
zd}mw7eVYb;v8m;OV*~$o=tQv3P6vUrAqSmwP;fFt(as1}S2I-Yj8JzmM$^>{U3*K+
zT&*y2w8Pfb0Xrvq9G#qSb8y7d#TkD)55io$33u}(+Qo-hw?I-{A1;JEr(g<QLMe0%
zqRK9k3a3aK-NI>gji%K_NUv)&L#}a5I3+Xckixvv!^#<)bxmW(F@+0`xm<9{<BCHL
z*X;AS;gZj@P9@xOE#g(zBJMbq@TOZCAG%fYu6;S5IoI=rT^(OJ)$xr}9pBqG^P_7U
z|8i~QzxJ&N_P86e-^Bna4}A{0>T|@^0wp&~R9%fZ<!*+qs}=g5))=^3W8&$EwWAXb
z9<I2$I^pT)fw!9{fu7z3I(iWK5bNwif{QQd9{!|z29e<zio`vLB99Qtox>^jjHSjS
zng-7}T3wSEa8IDuS;UBA3KO2mOgg8r?2*ZaQwlpSd0ceO;F6P=%Wh(Bxa9Jbb1~1j
zh<VPXgjbx(dBw4UcU@|D%e|71oNM{iv6jENRr7a`X6|`5@`F<=_gy=9;L*yTjy(tj
zuEt2a=pp4{hJu$N$2^Qtb~i`W-3C=pdo<jw(RH^$&)W$z7kkW|?QwE*!PVIbXJ>D`
zU3~F%_aM;2n`q}iBE24hLrM1zK;#lmhD$iPZlQ=hL#gtJrqU&jM%Ne`ofGNw64K+I
z!mxV+<E}|ex@I!tmBoTbD(lWUoOR7*$63r3?_93B=JS|a2~Rsqc*?twXFN)H-m9Ef
zJSw^4Qo&oUmAvO&&*$z9eBo8cSDuZ0>)gx_?j79s?&4S1ZvN}lgJ7?lF$cU&+3#hF
ztd|9f9_AePG3A7hE$W`OXn8uI>uryrhbxvoE|~keVe93Jo4YffzCHwadJ*XDOR%3W
zp>Dy%dH5sp^&{CUm{gBovc1D8@QI<&BZ5lzXe!(jsP&1Z-d#wmUo5@8NsPFsG3uSk
zs9z?tZduHFWwY#)&8AN-Tiykn_sr#zPce^qm2%5d!gF3_JmXi%^S%|_@vi0_uWH`+
zY2+iX8b0@_=X0-GzVdA4-ov?d^0Rw8zxj3YACGPX0$+Uuo<_)cm~hzF9K`@@RK2ZH
z@wY?6+a4`12lV{yG4pc3)YAbA4^Qm8+;H}H#lzQ=fB+u?{rw5^2_nSDpE$1|gkIq!
zc|?-t9ZZ%_3=;on3jL$0@QI?{H<lWI5sd*Uw0I`d;hD^!w}@f?G^YHrne@zN)i<9-
z-+VT`i`enc;fjZZt9}Js@hRo0fMTBWmhg;kC9n8Z@w#_8Z+O)5K|li^c{TEhe;uFt
zHS(Qj2jBTL@x5mYzxuZGr$--u`t%@>^0z?7+Xz{2V-ES)ax~BuC2wm^_}g>J&kk)r
zTl9k+F%5RX!p|MMKzAH{-Ej)={vX)KCxAd-e**nNi0}?2Dkzwwz;F_SBT4lYk{u93
zk&lpKzeGyBlc@EMr8X#zHopWq{4?nEO=U1JjbWd3#=Nsw@D{Tekjtu1A#1^6HhuGX
z#J7+~{EN9BRKepx#XRX<%Jcr!{3WQC*ZnHF6VSxlLAAW^-M~ja&3qQr!QX?L_&%tU
zpM84y(Z7S=gZug2dkDdvP!j~crbq``Bj;z2Qm8G*0v%8bw&P5I6WT$}=mj}p=;wr$
zpEq`XzSso$;uPeGr@tQoenABK1rgyJOju|L!jK3O{X$6yjvzHqNLFAZdA_lT{e(#T
zlBxAepe{IpCf`(AeUs@9%4Q%igK@uHrUSB=^vz|}FOOya0@ebG*$pXX*RPa|ex+Os
ztl$a%Ql9p&<d%OGuLRcdMsOpq2Q>0tU^DLqxAR$G8+U!%`FlVM-}`p(y<b1~Lp%8+
zxR3w%Km4@9t&k2hLpszJg-}c6L!CGgVZ*UtM^1*@p%d<bexMg-q3)Q5xndsZfptg#
zE}_17gaqOd8bUyrAK`&Pga$_t85&A*XgJB?QHTPf$qA08AS8~0z$D6oMN|eRQx}j#
zQ=o|EuvEH2G8qZUWh7k8L|`scq4_L@i`j?}vmTbuPN0PIp(R`jt>k)888^a8c`mq~
zXF?izF}#*nLmIdfSj#(s5790BHK3g@B0Bjdpq1}KI`}@YkKZD?`8}eS|Aq`A5QLbs
zH^hbmAy&u)+i*148r4WwR3aSF40c5;#1-9e7feHau?%;^E-V1+r~n+Id~u5k#3MYE
z;IIfnL!*d@3@1J$irC0lMA1=Xh9@A7N+2&pNKu4{;*eD8!_uh<Nv1tqL~BR}Jt67z
zMPxD_E@nC^kJ-oq7Q*vbj4EO+O2UQ6VlIS9xEfW%6OlFC3@hi!$VP65)bV_DGcScS
z@lHe|Z-q7TZgeM~hjsIHbQ^ag+xaG9fO{c5+z%PzkMMr}2pLBph_OLB#+rjdTNGj(
zI2PuLqR<7kXcyGO+|UYh!$|0XX{a}rVIJ5Cy>JxzVILKMOL!Oop#cO5BMFHNCMsM=
zY-lX;;X+cw5=aY;MjRGLenc|jutX%G$&^QlsE^E`RhU6bcrLwBxr{_*F&0(CbaXCL
z;bP{5#heY3un{9+C!&Ijk>y;8DC3E!dTxf+^ITXh&&D+Km#`*Y61MPqSSKGuw(!@8
zPW~Fz%jZ#jd@JncUQ7?)3w!w~x|jQ*1N=K|5`iGj4(T{+q@x{?k8|N@yc<d}&YX&I
zLp9O`&1he=W8E-|@y8^_7Ym^u&XN8&M+V^$8Gwf{h`{(T0^_2H62=l28AVb|45?8`
zq{a!!jZG#;7*AnDI#rRWR0}hyi%zFKCY$ycF&*)FjKt(J9-GH>Q~{F_1<b}3b2g@u
z?WhViqbs=-QNi`7TCPXeax<=mr-V(s5ZTC!(QUjL+sr${F7Cv1^Ko1ccOyFZJf@TH
zV!QZ8IKa<w!~8RPkl!N4_;>s$f;};|>=D{<Al8W^iFPPPyK*$v6V(_`PDi<+6XlCu
zj1T&;KA1-bVlMQ<F~JY#m~h<VL-9zAA|N4@z!)J>aZ$uZ#Sj~lNSZJiQH+R;_*4qx
zGAK>Vpd>n->V$OaW7BAf%BDLmpN{BUhN2}*B#0S}&Sx^Qh(%!~OL66FM%S<tRmzq4
zS}qCexE52(t+)oBiEZThm{$H0)xv9WO}rD+$p`W6d>qxqr?H)U9@ouR34{D2c945<
zgFJ{I<biO6KV!xb>=9WbNOIvotOGJaM~;eIP>OZoRH7?qVm;9m`d}pV$1ph%tGEy>
z<AbnG2*5rz4CmM=0^+0aPmCrgDVnhOC}NYMiBC!(B`J>dxCFA}GRP67QI?QJadI{l
zNjWsfWzv+CPkVeJ191}i;`14dEo3ylfZ4=KRuhX^imzlxRK-q0C70srxRzMQwYXYt
zCN%S0d>b#swenJY6R(O|c}LX2y9r%<kTk&EgaJNF8sdwDQNBqS;TO>u58{XTHGZ5w
z;-?;h9oQ4+z@Y>;<l;S0O!el3$erU!-l(T~qb2f3KhX!1ct1>2gRoBt!!bD=`_xce
z62tIMjr|`uFg1>d#8?s%lMyA0NJ>f~Gd`W%gcKyAY)VC`lqF|Tlafz!LME-E0$LM`
z=uRl4M^wN_QW+C*Ma-vEGM`+*a&j4Gld9QDu4Om1noEgIJSwW?>G%eoNp9gUiOsy2
z)XvMIZeA00^G<3X?~A&)8{fwlNh5rjJi<Q`Cb*wC#Dl~ceix1MXTmsweaWs!rMe=W
z;*Lz33rZqij;45_n&g9KN+233{^%w7p`Q|fRcZv*q9`2FqHqz#;Fc1DZ&D=w$wGqC
zVhKqR5u1{LFfEzn^b}IkQ^-ycQJ9=gX?iXti5Zk<WYdtCOM@tn?&M<nM8ynblrflE
z&Uli9*_3jYQz}?bE@vyPfvv<QE@rfFIlYC)65Dtzy^Uv6+PR(5&GVv8UP@}`PDVF(
zGKTmhZIF+W2KXvvfNwG;_&$AtAJZoIMKsQ@$+P^KHitlv<;sB+PxgyEIFjy(g2<Z_
z$pM^53qmc^AMNx|bTR@lN{_%iJs8W3DC{z$a7+{8mL|j}E8+jZ>4`*Siik^3CO$QZ
zgw%Ahk~7K8N=KZYMM-KVB^kNYrsUC-nM0GPh}P61dNK>>$tYtat%Q-(Ql>J>SxBp9
zEwz#D)LOPOYB-<K%p;jiJf7Lat>n)C6@DS5gBLS;c`3DzJ6YX)kU7N1Swq~-7~o6M
z2w$X+b1!3pf25D{Tk1T&Wli$mta$``bKH^6_Tq4^53<=_C}n!0lIDX-P9PdNf#_xj
zVU!bsepWChIgwapN8pqli9==#ZmF^OWGCUDDkLN=maw#BqBGJFWv7sqlSO7`2Dw=o
z<mKcbPR*k{wSdZ;LK-v0G^Uo&nN~=5P9?)R#f)WCF_~4%Tv`>2Sq-dY)U%#e!){J3
z7cyG7mfgnnv^E}3ZRb{M2QQ>`aXYJv*E73#J*$ro(+Bx5dzg<i2f3R)!QISh{*f`m
zFBvoZoHffovljVp&cniDXZGd0vOmic*?dnFv;9!b4n!?Glr!RB&g6z-m=}ymek7Lp
z(U@mMVkeHpB_j?maWp=8arkAY5RjKdcy1C2;tXOlM5N@VBg#xCGdq|3j7&<h#FUH0
zROA=ZlwU$qMj;)!W%TBkGmulwP;L#A*)_~$)v%aX&6>E0^_(WoXEyRkW(SvZI(R&<
zjhh+0Jd@S_KkSQneY}x3$XnS%yq7n|2YG{hnlr{1;xX=K&+tvw4EHkT`8jie-}9FF
zJ%1U2AlD1&951Bv{W+W)fMP)aC-Qtz%?m?4Ck(BeFtqc6G0h3Xs2~#ayg01Ii8$xQ
z;8q~SFFT&V`~*VsMMPvJ5toxqd|o<9g?XeDW|NgCCO1D9ac&`Hg+<gAl+ajMOnqSy
zow?=oWK}VgQ_g_6oSCd@X7ig^&aPoOzmBtc&73c6;X+m?k7RdoC9j943c9(O*UyXj
z{oKwS;HBJA-W8AWR>3eIWKHsM_84F1jq^>`BwuGw@sGS|ekqvaLEaMo&7ViGFV78`
zq5uvR`*9>M5V^cil#2p6nIC|fI24V7aCGv7m=uR$njei_ZVb)^iMZwo@hDEfqd1v>
zq9j5jA|l1<2n$n*&CMVoKb!R8EHWfH<cTE|iHndF7E+O0N^P-(dPy1W1r_v5D(TCs
zU_e~ONNyu@k|q|#t*jNbu$I@(ZhkWtCEZ+-bn$3W7f<DOa!WG6b43F@pF70M#bdl(
zJjgqF<9v`i$w#@9d?6X<3&|AU<t=i*aF$;r%luln#sl#p0zsiKd-MG`obQ7|X)sE~
z0URq0=R|1)8saFlN+ZycL}Qd6jZsM=_W7|`OOkObO~I`w6|bUn{ECtY6=xAsm`-#_
zHgWmcB$tR0m59kLlpv85Qy>;oSyDo^xSWQfQd$a1=*+LAJHL{Vq8diTjf{!wSS)E~
zA-|cG!Y0m&yV#L*vs=*4)#6T`DD38m(m|ds9^jeces1Rv@k-$&@03jNmUx1XN@w|`
zWRAZTFY-m<6kkgg`6+*ipG#JFP`b+R#cK!zrM~Ph4&*>d0P>}NC>4jGS`o~#(hxLD
zglLsTVN?-`eqjt&WzpD`Bw|+~!nrgBmogC^WhsP|r4uO0B)lk#$np&0C1TPFbIB~p
zC96<OPDwt+g{4%Klu}b%Ms;xw&4snJ7njppUP*s>6{E$Cj26{1Szga<MF%T|&8(Mn
zv0c>0uB3x&6@6SS>gTc2KAw~e^FqlmFBcB;hGdx6%cuFUc#;pw=lQgFj=xD3xmz~R
z-%IEDsdW8+b$>5i=0U{<f_+s12+I68ToQszaVT=7L7b?J;zV&6r^|$#k;J209*bU;
z5VOieY^vgME*0Tao`_3H65gdE0!vZ}tjr{$B!}p#0usxLNT?_xt-OSs@<MV;ODHTZ
zp`@ycs^U@_sw!x$tfi%_mY$MYhD%x)tEy*I($1`;nT4t*){5I%FYRTkq@QzDojg+6
z&DDxwo~Y>MnbJ{iS55Mlig8{oo#Nff8Qw0Q<NeYFJ}+71v+{Yqs$AmRl4X98tZ=_{
zgZq_R{8_e+Kv3q7bagNXYr{BL8O*WjaFokqI9?sWnbL>QSoBMi&?`;GyfhZ8(gdt4
z(y^~d!?`pY&zdxR%X0`Q%ORvJpXjoDgylIT)D)6cQ%rVcDMjT)6xLQyTwYFnMHvk>
z<usL6(_Ga+PiZY9)lH06H!@z+!E8+%%hjzcmbbE5-OWyQ7w2n-xLh^NjoLwOR`&B$
z^#p$@ALga130|oh=Z(^7-mjVE!|HiHs$S-+@>Tv`InTX{Wqv8&;K$lcey`r-U)7rk
z_SFX<Qya?u%3u!Hhj6Se66MNR)T$!TtV~3=Iu3)nSPUv-u_#Z%sxk?ix(r;(v+%4)
z!>cxfkoqh_YjTOKFCw}sm-wn8(&`IItt%#@vIKE$8RF_Ps;bJUEw7}mwt?olIy!1=
z>8xv{x4wn(x@N|!+L^9tWu?58mHIxmYkN6Y-_7~@0WQ}K^F;LkH!6pDx@Meb>&CcU
zH_2<2Q@mBZ$cL4)d|a{2->Me*tbUy@$~XA7<}5!}Zu3+57WZqm_<xmK2n0>R>}d?*
zP;E3vnqp9Fh~QX*5cNhO>Q%9vsS%;mn1n%18fNtw*j1%qTc3(cT^63T>G;*<;a8tc
zV0|{>4Pv5d@=2&IB%x74T3rR%Rh5XVD=4Wiqqw?)nuZ2y>YHe4XrQ&GfzIkC2I^WE
zX=-J>u7$apHf9?-SgjdgqiKN6>OL;i4e)4PKaVyHbE9dLr|YJ<-8jR`wd1^0H_2PI
zi@aMi&j*dmd|tK2mkq0YQ?tqUjjQ}nzrp>Q4Ib2N@n`)-1bgZt*wYlj!KO%L8idHz
zM{%?vhT{!!s5K{`+ayA_CJnu&46N!hv8YMGu_*=Drd-^bvhixjBCx)Qz=i^%8jFZ(
zDI%$<nB<mXG8&4>Xf7qMsf>b}ddh05scvkdwzh%Bnnv2|Tj*|VWTdf;p_U$|n>v}R
z?Psy3pVhi<*6RAW*f`3$mSL{djB~AFgr^$Exm7dEi;Yvf(m2J-wF|u7GS9p93;eZq
zozI&V`KorEyLFrVP_xPpE$8{AVVeid7x-7>MFe}>LfO|G#-XNI4%Nq@Tpy2Os}QvY
z5vLkr(QZvZuO$h+=1k06)39sJ!l5MxhxQEI8guce7vs}VNLXtzArA{TNr-JMBBi;4
ztfo@3n#w3@FQ=fT9!YaG6%DmCwbjzz-b`~#69a86^fz`h(%i;OLno7sgRD09v06XK
zX6qp58wYu$euQiFQ(S8r<!1W?&$LYQY}+i)w=D2_>jG~#EpVrGg%4U6`LunNuiDo6
zs&$<o+Bf;3;R64x-{tqFbNtz|i$Ks8ji4=z10C_mHVIMah(on0juXuZXtboD)s=#F
zYYN8A*_d`@VbPX}?L%yn7_W{TJemvfZOSL4IiIkOV&Xa_#J5XG>8M83QiZss7D-1v
z;?4%jI%}wGs-v;Jk;bNGTHBlHYieV-wVlECcE(#enQQH4si~jEwgJ{U#@T5b=6ur#
z*W1Uq(LTx3T@yUjKE<=m)4b5O%<EmVyxIPL*bmz``J`!uFIvv>Me8~4b)M&^&U5^;
zZHM2w&hekNs|W<0(d=uF;9yr2hg%a-?1<%PPZG!4<2l)rh;~~h+O3(Gv}a<}nTADI
z4vsxpICSLU-dTiaTOqz}62jYyiEJ$;zO|CL))JCBYRG6SC%e6YypAf$TAL_utD~l+
znWoMTntM9w?Cznrr<<YHK8CtG8SU<8wxyrt_I?(-Mp*9|<zn|Z7uv_T)HTiZmN{;8
z&huQ`BF}Zt^J>ouZ*(m3dd~)LcWm-O#|9s@ta7(~o4>d3@b|V&?)N;xPdyj7-*TDX
z+jkL2^$L;ch~Z#oJPPeXj`qcJv^|XzovEDaNJFDjgm!N>#vN&xbc(TQ&%(Atj9Y&$
zu3bg=wigi6Uru0ODKR|~qS{MI=&2;Js~%Bz4Y}>ri2EBT>}f#K*+6YqC(RuX*Gg-D
zD_wmZ4E78%*4xiae?JQyy)1MMveGloM#nH0+ef(4H^rsCNv?Iya-(mS=Q?J1zH^S3
zx)*u5cY!zC&vK_{g}?T0@=@mopLbp0+m3Di(Y3?(9T)hydzbqiSNWsw^25Rj?C*<b
ze^)GWJtC9`L?{iUa;iH6js8@0Iy2Dk%R|368?%8->^ift?a9HVy9n>T0s^|r@b9c7
zyjMa*PYnr!WyB8Fk=S2JT30Q3J&hFfHzFBqprogR+Wt1`ds}Gi>7jj~oxXv7db_$A
zALwDav!D5{Ayx;5S?rr)ZD5q0zELi8PI0+wmM6NFc&dAbCwo_Uv44SAJD0dKc$U}u
zH+a8ulaD)hxZ8P_uX{H6ZeWM+I(PX;_b$J6U*wOjOZ?e$34vfZn!SBVNDaj!*B_7a
zPzox&X{ZmTqcM_+PEQv4y}6i<WMSM}fOTIkb|d+?_7>wgEWvNMjKCoYAp<2u4ptD;
zTT9Y#Bcg#CG6x&T8)~MgubJY$4oZ94sP5~adZ3f$;chy5y67M2qko`}@xcMc`v#dE
z9%iL?l(WM#Z1&EuJ3Py!zG)sESmH+SGB<~oxH+=Uivw%C(!0c+o(*0b+~U37b9~af
z#otCY`Ml>6-}Rs8>!C;ZrRNg=9J<2&fyeoy_bP%tLy1TaByngY0foUNlt)rf9?as{
zKq_iuS!fK3G3Xa#G@OIkh#2$XBJ2k9aqgGkF;Ik0Um5;mRRr|a5;;^u^k^ONLk%Pi
zw~#$pPyS#FlCc&fqwPpWTB#lBrLn)0`k^k`M|<cP>Sb_Xkde_rM*ByZ92{Y8Y?9^C
zaW)3$xHvM;`Mx<W4$ScA=sZvMukhT!0=I|Pcxh;jS4PkB#@Kn@8QtQ;(R17#zR2H(
zclfe@mwTg^xIg#^KaO4H&w*?FzoF|01QW3cMnp&rWgs`0iQ-r)D#O_vAI;&+uo#_T
zG1`N9=#A%NIZ}kxP(Ic}Mc7Xi;XPiA|4<3OBb9_t)DtmTL&A7H!qFxYMq5aoXd`R1
zot*JbiYD499qyuHvYYyeep<%6=^7oOXKaN2p>akgMi?ELWM*QVrO8Q_CgwOhGRf}H
z9OouhxH7TK_2G4%o><`4_*q^UTIH3&HSP><@W$9S?+<P9;rJ!)j$Gi&(F=S%e38G8
zT;|8I>-;iuh2Ms*^2g*;2n3_?>={dD|7Z$wqv<G*q;X<68@0(i)F-mg9(jn)$9T91
z^N~`_rzJR!R^m2Qf%8};{^OMdOjZ#*QccL{Lu?&MQ+1?FG?F#if_SuzoRLlnr`jl)
z>Y{G6kJ_moTE=_+2ksjkXLx#&iIGVrrl*)0n`UKtnzLh5>`czGJ2lUxkrl3vEpTmo
zg~z5hd3yLPw<mUZeq@U~6I;A9z0HRs=lNvp9G^~I=F{n2?oM3chl%U_F!3lqjy=Xd
zr=H|rV~-)&Gnc`>NfA<0BIIY&P@2g=buyciV_BS@E<j_f0R6E-^ruU(nv-BLRe|kf
z1+G)2cu$n$H(N=_cq1WW)x=D+ARKEUd7_!bu{K0gU1X27lRMc#>2x2G$$n}l251-?
zp?P9}*10iy$H(ZI8ewo|lCha-=BLJ49GhWrc8-n7S#~Ct*qvD6^6Uan%$()s)E3Xq
zZgYEPi<ieXxHG=X+Y=XfXZ$=LPhRD-nG1Y6c9Ab9uk!uub$%Fsf`86D%5PIQ`E&Yl
z1p8()**lxX{^=a#CNq(n%0Y1<AGN7GPAy6}GbKiUu>k$Wa*P+su$rsFajqJdnKGQ`
zs_>kzCwQibz{xs7W}1kZZy{->iKNL6G8Ws&UudIXv5&H;PO9ensF>=ZcB+s1`EfcX
zN9bIfpnqYEk=apZ7H625TVQp1j-}aU)+Sfjo?YYo!V(u3Hh6SqjVBhjd1~$)&n#^4
zm-$^@o!;T?sq=g|d6AE%ukp#`b-tRq#<w#!xVQKO_hzs2VDc&MPv7GA#U~L6=Cj#5
zo6e!R91bt$qd1ezi5W2}GkIt%7NEIYi2hO;hI6HuEmmQ(RF3sbEe;E{c+WN9z0^d=
zd?P{2wS+7*5jWR{aH*4&xmL0kJIGw<Ab+Wsg2h29r-!MZAE0S@oc8%4y5^?nm>H*M
zVUpqH8D<uyn4X?uVR4?bbMx#h&a*kQ&hEk{mzFoVF@2Vsi|2T9{sPa>oa4orU0zzg
z%sX?Jd2i_vKAgMANAp+seC|5mE?(uk<;VDO;X1#}-QfQ64IV5#gFvv9gVbs^`xi2i
zpU**lA%_!d`KYc*&|J<(Z>1QWg-XokD=?X_z;?b8$E9+d=Ns{wt07>miI9Z`!j~I}
zSZX9@rH$l;4ie|O$yjVBZ?&78#X*V|d#GF*q-JrHy2WAIR>o*qouF@VlKzzm1{bFo
zS(#>fb&=KidDfOzSzlP<!r~Ga=GM5fxXRU)b3DCxfoGOBd1me$FU(!y^_5G!zI>4n
z<}dT^>Z5$R`Z#}EeVi}n9_QZD4SraDnt!g`;*W(}{CDLhf<4Q*>|4*_z(xTFm-10u
zEad279;eoeIJqD}d$AJTr4kI*DzRLz#(t$5=k;n_R_kzEuE&45j-bURBGwv-T5KnF
zwTJlSUQ#zYN!#cobG;w&#xP||15_>yQ?)ut-O>n68xyoFkI}I>&B)pmBkPNdEiN*>
zJkRXPI;$(otSzo`acPYU3un2sa-Qq!+dQ>?p63=H;r9APZm(S7rIic3yLgp%Hm>l=
z;uStwc#^Lc9^>2P8+^U;1m7<_$xka!^XtYf{=0D#fnYt0J<D0ht`~CXtc0Um5>z(|
zIkr-U`bs%xRw~h5DMxRu6yvQrtd{GrKU<6YMiU;Zt$3_8<GbEL=tdV|8$HCYb|G5r
zC1tG((bf?8n|<W24^eh@l#0zU>eq&7*c_)}eU|p+8TwZz>0Mi3Vs)0WttA%L7Fbx`
zU}@tln`bxK-Q3~g<~c5JZE$t{0#7cV<GIcAJiB?BzpP#1rM2t4wsw`bw;tuat*d;p
z_5^pAZ*X_(X}&polONWf=AX;Y^4r;4{AcA^1ben}klxPb@OB=D*YZ(X6QjCX#L4X<
z)HjRK*{MQns}zInI?UE;v0tmgZnFjZwH92r>j^m9iO+f`5$oNAueK7m(@*l|Afk;P
zvNs0FTOB~MHcs*85XI|5RBcbwusK7^#sqCUi}Y_zF}S+O=-L7!JIgGtFR-|^!pin4
zTU%S~uCH@>YnzMPJ6vDA$Ybj}+}yd!3uiC!;^t*u-?+?cXRq+~&UN11ev*&2p5V*P
z8{9qnG+(dZ;>WdHJXpWQpJ!j<-|H_S*n2JysjXZNo-5$+b^%If3psY7h*KL?sGhAt
z`$7#m=WEd0sKR)s5sS?xoG&!sveAI|g+~0(w&AngM(|EMVdpy$ZuB7B8X)Py2$|b`
zWS$!&cW0R53nNr*jZ?QXO~ckW4d-TP-I}6zW1gO^MaIu9GkI=}>9fl$Zfvu-xz6gw
zHs{XmaB=4%mo98`ZF`5Ow=eMA*<GI7y2L9RS9s&X4PM)LjJGy#@Zs6V`Rmp#zSwz^
zZ!g^D-q~CHvhytWx1QtI3orAZ?H3UUHjCJ|E#biV66DWGklQIn@qz@ki{+d-UxoI$
za<q4A&_7p?@n$V{=NhozYR7G>3FmX|cyD*$ztu&=#XiE$cN4SQMf~Onsk_67cKXS@
zFi6hUFeN)vNOotaIX6wyxhWcVXK2}+rT6?IgXb3+xwyd8xm9M*tuuRWm8I=1Hg>kS
zuzjB0tqWY)yucINyWBc|jc3na=lRXYdFA|Lyng;FZ*Je<&bg=gVCNY=+kBSKx1Zz7
zt>^jr;xqi?+--i`y3Oy~ukicsYX}7ABplc+K=xu82QNuD_DBUME|+lXkupy2)}nK%
z27~iWn4E9KY_}Qf^NrX&(uVWp7Cd)4@ZIep<a{@wyZwai4iL37Lc;Dai5G_vT^vVz
zX`GzP6BO@EQGR}siVKs}J~Btc&j0U_&i|Vr3_gxWrxTpIsT1+>b`uZOsV|Q?*kq!P
zJyxAgx8dY*>Tv25#mPWGZYT(pLZS4g7xYe>q|JRcM{_sL(KKnB^hl5NNE_Ow2jJ&<
z;Sb+G;Qji1&#+UN&*9p9zN<dN$=YJF>ng~tEv2NkoFZX074_BBR#zgdszy>LLQ>m^
zMkt}Vp$SWslopW$dxH#DwG>a4mSCNpo+>>9LLGh8dPb{_j8qv&)i{{1vN0#R43=!<
zs)jGQR`NO5ivP>?wO_JS^fh-hY~?obx7=N`jR$MDvb<&|%j<XZxM(N87VqQv`hBbv
z9blDsFE7_0CQWjLw?xNytNtkOh_m=d!*SkgIKhX)96qbd;@_fNzN*XN8(|^a>WbJc
zE@4+)DTf=%IZ|83k@^xcYf8wLRFT(E$yrGimBJb-g|*bx)=^(0K`w4YRxd#(5u+EY
zFp1T;Yh?I@N`gWKokA6%1|u<vg`rwA!(s!8IwMmJEi5$HnG@L&2*m$JP``nzq#L=R
zaT7NSH*$+~GfRbAxl_D@Wuomo(6Eb#B-?mIx`)S`cJu4T{rpz6ht>7ztgb)EEA{ET
zE;`B^4afMK@EGq%PVt`j6ze3Jd{}>)PsF)=-gufXrTP3vQpk2;F59Gq91xXqL{vnE
z<Sbc@Rh$r2lG|88Nn<rdl4?q&RaA&;5jKetiklEONKiK@(23+&q)J*OGTc%P-X;Sb
zLN!52GhGrLy+SL!!e+)Atc(lIOg1=~k-E6p;6NZyY~)J$*IX^y#80K0`Kfp-w>53z
z4*6#8lx^kSrtLhe_?8F6dwE2@k0%-rutL6<mD0nkmLBHCrUSerKFI5`?|4m`!5fXo
z_^aYL?<r2PzUdU}#i#jLR=~!_d^U&+*(@()r>u}2qEdD?7O}6XoD5kNnTkp><>lmy
zswk9JQYfyaLR?3cqye!=f>0zu*(5<Dl3<ieu_)9y#9BNOEk3E9fLupFYNSVMBqFjh
zD6ugtb}}Y)lWg)Z+vp)B_aV4a`4vA>Ze)>kBa4+=`KfXXOJtk5wQ(D_HEm;=Y8$_l
z?PIxgCyz+ed9vvMD^%&MXiR6NES(pm$9PeZNtz^sKdZ8Mv+)$~O0rqkn9F)u7V9PX
ze5@?wQ&m1+$<MG!R>Edg342s!>~E@MpQ3`pvMMs<)tr=7ks}jQ(pXPnV=ZO!dTOMN
zG{~C}Hpx*+WGI?c=;T_Om1^uwdfXBfE~OezQ!`yEE1ilKqAEKvm6IWbm4wpDgwn~h
zqLl@e2Z2ETB|nmH;%d#;Trb<q4YL2TRI`oSG~2jSzLUEY`*~Qlhh>UAJgM5xlbZcJ
zqdm;?@}sO$Wbm@)2!Bu>CQW*hG<6n#Rc5hHeVX^xS^S?ikM+tN{-r783t1jt$;#NG
zC}gv?h`sU>_R1?bs43&1x{~ASYBFV26sW5x(MmX@mQX5{P@!p}Rv|;GRUlEx&`A~O
zrCRhV9d<=C9)%viR)<evq*HCATVbR}ZDvqwWkA+SLTYD1?O|5d#)2k*;40NO{8+u2
zMXD{_Am7eSx*hynxtrVMd%07$gS%7*xKDYI2Q_<mM0tQ`wFh}tbAaDy53x#~$r{xO
zUQ(anHGLLus&n|8{3LHH^H`@TWSy>vk8}lmq{!tfMIm47&ahQq!WKm_d(<WDRaUcK
zbB-elAz8{=vQ#2+bP@{HV$RCNRH{XsQ%k5*HX_zE(x{Z7lq*rmby#$2j7mK=off~`
zj8ASOc)76NO258^0hOI0wVm^FCn>#~d2Ku2tGo!VFl^z+y3PE=_+PHoZ{ud&H!M-_
zW=Zp2?osXHZsR^4)b8N{%|0GiAK@wWL7q`%vO;r+RfgldpvmABV<u^u6Qmh(__I2f
zzZwcztIOs+eLf#H7xJ00n9q#`e4#62b8{J6n=9C<F5`f%oc;P5j;QK5rmH7MTf=FC
zh$2H1<!UJvdJ(lo8KPzxBDIVry%wEDi$-I>U@&6W>Tv2zxQs1y=&S@)HlivA0~$Aj
zs#ZpHF2+<oX4C=ZbROpPm%+x(T%p^}PqaI@LA#5abl<YHc|UjPc5shoA9ow~^2_GK
zJf=OwW5x`g(jVnF#$&A1X7D@HQC`#^;}zp^()78c>GOEYl*2mxY2Gsw^MT<EA8HEu
zNL$92h7vY57qiJ+%6451d-b&(FxB#1b0tR%4II@-IALz2z|=s#S;iToh;maCbp{o+
z1_cc!J&k5PDw7eNS%b0Jf=z41)@;FRGSX(W5Y}7hZg$h7@etQI8Pa-~Z1ysx^)s(&
zXTj8o;ELw|vdFrHtIfMvY}m`q*4^A<-plQlgWO@*%Uvz$Jk)%Mhs;M=-h7b9%}033
zc${agCs<|9<b~$rtZ6>YtA;$%EZMx(lFK`mBK~12WSu3SPxZxoYAok7Ln#{#=h)P8
zmd(~`cAG0nH`H*@+Q4Cb4Oz{#oHR6%XK0|%*hG;*!8v0SH3k*+1|^MF4Pt#WDy!}X
ztWn>Bxy69PY{k=T!Dn(4)O&~+-9#)7`V3CS&2C2Y0VYlDq?$vdn*9iVWd4S$>^u00
zc@H<(cXOk07dILYaJzLs_gMCGU-Nf7WJ~7(<3S!b9pf3x34UWc&U5CItT3KtwI!RE
zZCRwX<nx-Xh`(5K`AbUy?=+Y4p}mZMn$Gfxt&*>7W&Fo<mTk6kY&X}i!(Po!V>SDY
z4IFHiaKtR+L`wswtc?^j%Q$P2Q)$ysV^<=ws1VzmX|(E)n+#};dMsuuR=W{bivw4)
zn}E?q(9}xA?4sM^W4O7UQHzg+-OEHvm}zr}1xpu#E6v-vrsZ3%w(RFx%N}lY?cqj8
zI=8eO=1$9D?sFaBVb@_Ewq^2!<?@d5T+1m|ww&Vk&f~mn&EXF%`TWV2&Fi)t-gXtT
z)>Xv1mU7;Amhh3agbl7LHd@Z|rK^hn+AG*%u3}G1Eqg4r9JER}*dijsCL-G+;*>*9
ziBm?2OG~9o#W|aSdaIs#n;NmhfYRBFw#9_m(Spt5#BO)vv)T#R+URKU&}nrOv$xW3
z3o__zXWSWL+S0*-E64?F5P`t9lPg@`a+U1>KWp8^jn=)~>`Z5A>mhD;rL)X^gkLx^
zdBk>vN1aD`qBWDJTXT5MnZxf|PqNCB!<yF9{LyxXG<y+m+RyO!)^gT)&hde*lusR1
zd~UB`gR_#a?bU3t*0IG|%PzZ!-JVAFw>EOrEhfVy<G5W#UaOKqmy|-gp0gf3wH`IK
zPCZR-Jz}dFrPG4SVM6b;VX|AXdu+71?D*|2I_!Qz9xpu}5B;7H!}b6Pdw`UylPOz}
zIcpaJfoC@Y=WecR+s99w2l-jser~ZJV5#FMceftlZhIyVxifjN^*E2Xv-y=fhv(cU
z0bLHF@p#se%PMyvFF5k~gFTNm-dtXD6!T|qIe+t%@Q$mL_3pEL<T=Yn&a-Uv3i-0N
zicOvxzIE5I$63c7kBEJ435UE2GTd@bIU31!YB|%UrNphItW`_3ONY2kPrbu{yv>BF
z)r!hvM(46)cG|Fc?YLWgc-=k%9uE;uE3wuPz20^P+5#j!VJ2K%%(}W*a7PgcTK92P
z>s}VO?Pan15ZAj8u*7|cCB6*qb{*lDz7zZ+aGYgr$N7~zn<u<kJmbyb*S<Vfdh_{%
zznB->ig?vq$Q!LCyzMLJT~8(N`$|~vtK?&UEgyMn`7F@D22VBHydt*yMC@=&*w-fF
zuvf;hRwYOMGLCx{<he8yxfGPSjGPUasB<+_6VM}WGa?N*P`Fyq1#Fl-ZY*9Go>m8L
zkB7E44}N!$Zht#H-VXYG9Spm=Ncy`t@9k#R-NS<aa^d!U{J8BPSNjgJxHX;YJ%_oe
z^%%FdW^ji$i+kHoaKGmmkF{m-WP3KxdUAQHJ(u5ka(N+G%&I^xYl3I^Q)>Z#@}A*u
z!BW<FOIaJJVV$p<^{v%>8fajnzlN`ZLN@!wZ1y*@J0NFIP{jT=IY&H7vix#RdKBaY
z^%Mj&6b1~O^_Zy&nyB*_X>4sl95kZ{I5B!%=z>mcUN0`M2Uoj?wst=upO2_FOrJl@
zK%kqEK$JwFlSyw6bHNz1o*05F0(-bBaDYYrbgl~>;%4tbZVVsi4qpbh2ebHP_$13h
znJf#RX1VVqPy6zCsw0Qr`SMxm%j4xx0WSrLc-4P~G;c9)wU_Zudl~QhYk1#V$)~<b
zKJTdKi;$2_?G0=VHnBY@V~1D9KEI58AsLwgB`4bzWC!)+1=JMz^%VKEl(rkF@U<ZF
zIgqwHQFK_4hus)L9`qpxCZ7|l*Nw*;z#H)6Z||VX+d-edop`u|cp%J3xRa!}mpOkg
z-v@gTT-lk9AasOlLg_3HWpHEo7)v`dxV7UH_xLloFObPYohMk<b(-ZJ**w*m%d_o;
z{MMhxYJWa2b(E6kFJX<pls5vUtPNMNuA`iHLlwLq7V=?d9iLw=9IWT-b|G8BVz!4Q
z><uZ{-z8(eU&)cs<tfMs>B;WYQV=pz9BiSYy_t$&3k{(b8rq%6+8t;*TG0kv7(3fA
zb@;J{y|_Dqv<3VG!a+jq5&FBr^o6?_3U`ud?;_bA<$PC+R7XDoLGUQoM31tl^Dv8o
zhq&P~w(AskbYyTx*J+kTvUwny&BM`b9_=pRSCImqi<a<wxcG;?*ilYeq>?p}3SR4~
zWNo;dzjoHKE?mb49kqNC7V=q8!e<>qzU~yUDI(#UjwW`7r0fn$*&o$&B&6e5NX6->
zk=!m5XQC#GyRDRW*r|#*sOh#N3EOGxaG(kMFm`ycbbE1xz1YJ6+)*Ea4nJL8Av(Jw
z^mla9AB{5F(M=-UPbwT`D%eXZJcK|HPG?a#gKHv(xGr++2k_Ex7E3}|{7>(3?&`_o
z!B9RAMGJW>oX@X9#jNNl<agl$Rz}b8LT?#=>^VzXZw+sT&+&GTkaxSPdB3NY55f(6
z9BJTR;d(Yk<!tN~v#G0*?cGXtb!yqusb^oWnnPWBPWBi$*=eD$(@0UoNLj>4X^(@t
zt`_Q}4kRHL;)okvPb-F~2SYf3BhrpF+>Wz5Kp-3@9PK31*-a$cM=TO$psSCG-ae)~
z`#9e-%xv!<f**B#hoI{ai~BRUt}m0D`cAU6=LEOLPH<QBB=<#6@j!1j5A_uDSWgj8
z#fo^Qw}j_oWvuKe<)!X2{t&6*^~gEi=o9j0q=COg>RB5R@m_x|pG2GZq+iMxJxzSs
zBV}`!j4i!NcJ|9T5Yv+$QS)6y$FUw0IbBvxMO(=2HBugNQr2sss^39fw+Bg=m!_B>
zO@AAPeh<dp0OnW+jz|b!EQ~)Ap{pxGcV9mPU0n>t`iS=pkc<p78H<tXigPhGj6l$L
zoJEntT-$Sk>-vsyQ~zmh8OY-HNDjBf^0+^Gn)@QTJQ~gA(ZM1f?=9x(o?=!+%J_Y6
z39BPzyfRqDpQ2T~)?dTgzG~L?i&+;F@_z$OtdC0BFxbS#UIm+ar2J=4%l2L+d;1im
z52!fMr{~asf#dx~PWM>I>$6kPXQ5=!!MPq6H8DH2F(-|KE)+2zvVm4~u^@(l4s4MS
zo@fY9Z<JuP2me4fojp+oA_K$+`xxl$V`6ZCMDH-Ou@UA6;s^x8N4R1rgT;NvxppX%
z>-$b|ODvyT2Mf7(FpqnN@_BHekVj($JkeXovjfFE7eC92cqz}vD|u<~9BYPZ_~TF=
zuMXGqcC3zf`)hf3P{Kb4<@|F%%11E?8)J=p(W~K`Avrtyv}_yJv#Vdtfj%<_2drca
zo5&h4QrPR@%#ef9UOVT8J)9eIQZwvC*ysPDusR+>9rs}v2;u0B;OXteKiGqBxRbze
zl%9AWvA!YV!@Z0R4>B?^N-{RY{NNZDh7t$_u`GTxkj1qF*<3%I#VzrZEEz3eNi2`s
zM{>Atuz+90idY^i;>p+<o*FLa>3Ah8hHF?cT+WN5b-XlO$E#x^-iS;1YrKxX4TyMW
zNW}XijeHcB@X4T*4Fg&>46FENM8oE|hHv9K(&Gm9#|<1Evyl-ukrQhnci2YJP%EV|
z7iA+Zsz*K4jI`4<6hJW$LOv8iKNP|+&`HZs7|(DoZG(NZ4fYTo?WH$9L~L|`_(+`5
z;TXxG5hmi}OpT25{optP!T52miDz@&NH&YcviaHIDQ+3f;kNN&?u?(|-gpuB#Y<T>
zRL=6@GM*VNW5vi>R*qJ(YOsPeiAvTC*YU?u34b1vuy(kKzmJLddtAXk$7HOJH?m<!
z&A&$#Y#cQ3&7hubLmKuDo7gwjLi%_MhY}7lh8>(9bCMf(P&{hqY{Eh5ke72KZmLJU
zG>&<Zj0I4PU#{GVX}AN^U<B(}FU~}ij`0CP<Nb6E4--iYGc-6vd?-OOK1O16g84*(
zONnU&S5BPbn$go-JCe<H@jPx$=5bphms>`PxHnP8{UaqjI8n@_<0UK~t>CG#a-L1p
z^4swmRwrv&lMs<MS;HTbBGTfGyge!Aoe44TkIPw~RPnF4mJK6XzKW~aIHKk2aWy;Q
zCU%dT*)w8cU))S)(n8jRljEbUWXIdcA9YZaa8owkM#V&s`eXp{qz`Gl6I~*NaWaA_
z5y3vvk9({i&*&h&<PaU>gLIGgGmso6K03s3VwAD5QKlx&voJA5Dv?AW7(K<J$<thO
z{xm-w&*qjy5lbhFSUOS2ZIeaZd%l#1l4UGUmho7kiYF$@d3I9B%E>BLjf+?{DdFX$
zgjc4dygDV}%|sJ#Cl$P#l=9(}luwg-HjHZcY(mA?=M8Kcv#@j0%(qD^yAmxN9Ch;D
zxSgyi8=0ea^2XXIPIxIwv{N=7pk~TX{Zt6yXcywC4m6`tv=d=kk`c@kQS6gZeCK=d
zBx7_<#R*Lg5gi{THZjh~M1sV`B+1DH=M&S+PE8>YOy_XbbRpMG=dgIDn4eGNa^rLn
zcP7jDpHwM#rz*LBvWy2N&$4{7l3z^=d3sXFvorOqNY=4BDdvAC#JoNsBP}W7t%Q`d
z(=y(jRI`3k%O?p9pHJ)f^t_r4lNPp47}-2y<l7l5yOJgjCT(P<TpUZak~QrhFXgA`
zyr1%fhtfoVnp7v^$xb9w?KGyk(awa>PWNL;^kbhH#5L1T+f<CU=@`N3F?y$mh|G-B
ze}0U3YK-#}=b4(BVPSfji_@3EQ~6vuQ^?}UTo#=_!_VdlSduJYN$L!@O`l`gTqO^m
zFK795IgifN@x)v;D^fz9pQ~Z@jD(k_8c3TK^V*c0Kg~*cYpRLAoL8`J_VT5*d@!x&
zvy_IfCe3V|G_hsQ#?DC_JCb(xC*2&Ja&b86CM(rScFIHcY&!+BZIn!TshH}ddb*w3
z*)Bwr9Z2Uo(aiSIJQ+hb6~#W=i+!>WPjZCznL+%?VM3`P`ll!9PmM90nkF%sAd#G8
zYIcrPa`tlJe6F0&=emU=u1}S4)BG8JK68#GGbP-WDrMPBCCjF2d1$_xM^lwNxgg@#
zGa^<_*Yf<Fl-2WM(k@7NWmd(TQ*!>iAZOjQihnE^_{Wrvf6klubf%dNDI*)ETKLa}
z7Pd~C*gfT7@2r*dX$ME=TRE0;ae5&@!JL=k=^&+39hA%ms9p$CJ0GHcwu`2@K9uwQ
zXf6z*OZ8%!8N@w3gnKGZ@WKe;nF&HuWAx39(mOxJ*whq>g(T<a&NFl20&}T(1XrYr
zxMHD@t1lMvlerRZoH@&_3*{`Ct>oTI=eTF?EDv0&;=!339-FV>nHdSsTokeLqLANT
zkg)oqoV1H7(k>`TyQt)il!~<%wY)#C<AYfZpU&v`_hsyyl?^ivw$9qvnzHfjg;sW7
zvh!Wa&37|yPRzG+a=w+^l#k*CAH|nKoSSW@I@LwZOcd#C7vfY8%8M~{vja3Q3}Kv)
z<GeV8cP2sb(ip+Hak?&^r*C$G-b>SrUYsG3N;0*uz|^G$F3zVATzMgntLO7sbfJL7
zoa1K~in-}x3AcV<&0SP*|9mC)&kI>LSH<H<czmIOr@t5R`~?}SE-857LKFY{y^7Zt
zl)OHt<<0L6th;Dn9Y+3f(ZI(v^YH}}UtV(X#hjV17u;;c#dccRjfedgy=2b2IXM^L
zB<<wS`6#;Nr+B`d3OcE|T$gTym%5N#iXdAUL_gn;fdS0lk72tsLfiZ>-V2j-E+l?f
tWNw;%k_^nxF*!fOG%02-eotxv{vVst%N>$Zv=smV002ovPDHLkV1jp7Hqih8

literal 0
HcmV?d00001

diff --git a/core/artwork/thumbhash/testdata/solid.png b/core/artwork/thumbhash/testdata/solid.png
new file mode 100644
index 0000000000000000000000000000000000000000..3c53a36bfbe8af789592aece32ddcedddfdf3899
GIT binary patch
literal 209
zcmeAS@N?(olHy`uVBq!ia0vp^4j|0I1|(Ny7TyC=Gdx`!Ln`LHy<jNFpdfHygLs=k
z%R~N@lm*V;;?mz1*PB^6WH<0#kXpdJh3y5yT1Gl?-!hiQ6<N#gfBFvSMg~t;KbLh*
G2~7a1heg@|

literal 0
HcmV?d00001

diff --git a/core/artwork/thumbhash/testdata/square.png b/core/artwork/thumbhash/testdata/square.png
new file mode 100644
index 0000000000000000000000000000000000000000..a81000cbce450943a6b8143afdccf8dc8d27e2bf
GIT binary patch
literal 33071
zcmV)FK)=6<P)<h;3K|Lk000e1NJLTq003kF003kN1^@s6aN?Cz004mYNkl<Zc$_TO
z_g5Q+_4s`;%rJZJJp^KdKnRH;34uTegd~sv2{8m>8H|lFW*9Gq_ueaxSKK5{((FB)
zq!~>!n$e_gMw6yVoMtt%O~3EwIG^W-d+s0bI`4a~Kp=2og}@CjHvygk0bT+(yair_
z2)qb(_a#{1MW~w}aRM*m1cAi5`jFxpLXt};>8=r^3IfS>4<<_xNs&t=dG0Y3xW^(E
z#8B!MMVWgdm4Zanf)r{6iPQ_y(Fszhb4kY_$fC(rh(VBnNsx)vC7(_~E;d0PR`+}y
zZepB*A_iSc84;AS%C(qrfrK$v2@`H5tQW|cb}MH_AZM$46`NhvY<5+!Q&7Wp_ZoJ&
zD>)!gv0qTn5kV~n1&y3^ZQ!Vjj*|idx4M`(=dS0RtBETDGj|GFxa!u<U4l05ackrE
z?q=>6n0dh6&O?H3o)mQPtgD@;1>L+T=;b9r4==hpdDX?qn{I==;p*hif>pdN7~*e&
zK|XLF<^#78J`}9spMo`f=Cby;{iR?7H(Vz9(PftJT{rTx`xHM5=J`di5rNwZ0fH3*
zTvoW@;pT;x!27rH6|5xC)rT;5UqS@|gt-M1<>5nuAegun!6bS_AQXg>=^jj;TNIhD
zp@;<$6bqs#aZ5lfNJK73pvpZSnR_agf+T8JB%^W@q7|f|7o?$gOQmH+Hmx2Rv<q_R
zxQXGBhh313Ly&`AP)M&^0Yic!1_Z^d63AI2C}UJm#<+`|$rWX6bdxdXQqCqpIUC(7
z*(#`Jhr5C$7Ztk%TK2Bcu;0C&qi*#a6lgguXylA*Bj*Gr&InAL6BxKGFmh#uncG(w
zxyQBbH<aHCI=J7plSc#{Jnr7XL+&=7a<TKIpp!qi^z)31gFmhq{683%5nl0d@|N2W
zZ@91GFCJrDcN^!r+X(LqR`IdNYCaWA@K3iXZn#bImHQ<Ba-HI9w>iFZThD(58~8~u
z&wmAT2;AHSxUX=*bA=n;UY>Y)d*kcvOOTr%e(rt*y7?0A=}VlK4{>h3Bzpyr>=sU<
zM<B`GA!NElBfMFKYdE>?afrR5DDg~0>X}U0iWtgWlBjTtr^Y=6je8Qcp6S$iq@i(5
zr+GyNI`>SPy|OWQ<k9Y#gVno;4$orjUPbh}6*J^oOrK{dgI=YKc}N)Zk}&2iW74~l
zY0q+IykyL{mNVy~W~+A%3*HL0xz(}DL(Se5b?k9dv;SrlE9yDwTE|H*J!d@(oO5g8
ztfzrnJ<QzdY2Y?j6TkB|a<_|(-+Q%k)y=}gu3g;gVdGIx8&A1ex#rc&lP>){y`q=r
z-Fo@sihf@C|I2v8b&$7KjPbVTFz<M*;;&w-d2hu8*S#nC&|@_pdra`T_c}gxo#qRd
zX}<B8<16<K{OmEy_ioet=s6268xaWH+;I2t#Kql{6>gsRdVAuv@+OKu{+@wEdixNy
z(vJwQK;k_@Nmv<5^2%^hy@E*h3L$Mp3>j`wWO+tW;2ufA%4kYF<B)p9A$Lnf>Yjqq
zGZp0uAsY8oR6atqo+7j>b7=C+z~r5Y(JLQ|R{>TxF>P*nbi3u#=~Ik-MKKQVVg|g+
z7+6`%(8^L)uP9~Gvw{si6->HUGUZ*)2Jb3n-IOe>tYz6l$+CMLOK#QdbgN;nhmQST
zjU0As=AcJ2C)}Di>)ps1w^q)38M)+P;fkk)+uho^&7+m8ULD-yVdEb6Ztn54@zBaH
z9$wMQqi(%C<I&A?K7BmnGstruPF{2y=1=Z}yzVi`Yo0^A;W5s8?qj^^y_&yxjq;(_
zB!71s=L7F`eC9FD=Qj&+pWzF)Np5&f^Nr6O-+OH2KOUR-#b*vyZbsnd@68HN4_0`r
zz}v?IA1`nGJiQ3<^Cr+YfDoS`!ae<n^YtgjGlFE#KoWhTNb`s!%_o{{{}_Z`;pBQp
zk?j{vk#{U&&jgBBrc&;ihRi#e3g1MkJu<2G%A|H>7WICa=)HvKJaTC96=Cqor`;o)
zR^MVeeI>Meim`f?(BoB1pMMDs|58R)${6>lWMZX^wLS{g`N~-9t!C1rl1-kqZ1GaE
z*-OnfPc7R#YgzQDW#7sM_IYX9<5AB(F9S#YnmOgy!U>ON&iWX*;L*ZmPYbvCw{e?C
zJ6HWIT=leb)x*wxel{NTvGS-#_iyv0cQ?;?_VD=1L7rRb;6=Y7UhrDQOP<60$#axf
zy+?V~e~9<|$GGmfns+?b@R84IKJuL6eZMI_@?6X3{_FU1<t*QN%<^x)jePAr&v*W_
z{Nz2$|9t1cdn*D#pgZn?Zn$`@z}?RupTL#)_y*z^u#!OUAVLCz2=fUh)+d4l|3G2_
z!btLtBrza@6t4)fy&}o<PekOKK#^|}c>%E$tc*kIlSG-1kV^kVRNg`qfg-9_W>dd1
z3!S$JjZX#!-&~9<vuO6q!{lF#)n81TPZ2$VVtTy_>0T+r;a`l?zl32QDWm>nOa#gq
z_f@jiU&Yi)1=HS2=Dcdz<X6u|e+}CLYuL83ft|h$?DlD3zi%CT0`%+;Fmb@AnN!|I
zP6ik_yVArhD~;UhZQ}e&3zz*mx#DHxo`5dy_O)@BUkCU4J9xmmkH@@wc*MVp#{-AB
z=0C(WUnkG{_wka~FfVxz@W;Sayy-i{J2!X0TCT4g=dZqN`OtrYk5{hYAKnvu?mNvF
zUK{wzYnpGoHuAOKG+%qq@PpS@{_C^A4*?7OzkqEB+(SHY^>xR~#}l^@Pkem6@d^$i
z#K)H~-(bRg0tojFA<{39=zt)Se4<GTiX`1XhV-C#GJGS+4T&Z1CPqjclAvV7zA2Oi
zq*4+jq&z@~!Y3VNa5~k&8K``+(D~+~3&}z6TZGB45JNx#rT_`;{`r`LOXv&~(;Xtl
z;V-2pM2gc##z<fVWBzj12FRK4tz@lV1yjCirhTiJ_E$3RqhVuk4O@NHYzt~)$-jXe
zL3(!i>p2kAz+OKShx{8k=40kWU>j%r44m@o;F50}R|0L^7Szt2AvSIg?%@vKZmtG*
z^MFqu4+iz|fbRfL1vq)qXOPE3oIK+@$g@69{un&Qi-BXj?7NEBf=77Ocbs>E*YIAz
zTK*cio{#+3@sZDZ-uIp59|6;R;k%J90;l-ef10m+XZUyE7Jl-d=jWg;{Oq#;!3zjn
z0(}q!`rsMtjeD3s-hM%>3<@SNIGEtTU;_O^2n`A)A~1;PfM{X@qKFHLAvGkP)PQ)>
z1ER?cizUZDmVEy-iu_Y43Q0yDlul__DitB=$imW4hGbLipG{pz7BwNcXu`75g=S+6
z5o7Ty#uQRaONbP6NHOg}Vyt1sIKyN(Ln;{vtYFAr&Tz1j@ennmVQSX+RWT7(!*sBQ
z4T1G+4A!zWtd=c-I(CFMvdh1oeIbqP4%D$Pz`*_h1Bd-uIThN>u`n~|f?GHnV&-g+
zjSImxE(O}SBcz?XLp%9>n1icf-TXeFhX;ducqq7!Cjxr87S_*m0Ruc8=;TGe5nc{l
z&5QoS{4sPDuZNEDmfslfhD>oicmvl1*YSSH1RwZM^Y@?`{t>!?e+JF*S?Dxh1kLlW
z(9L`kwv}%~7x_74k)QpR_)q9I1cGo6Jc51ji15Zc%pbo%KLR2{@C^$iASi;+kVt~V
z!ifnDCov+1xbP^F!lOtGN+3NXiS*!TGD73Yj*KTeEP=v^WW<pf6o+I`7LkH9B$KKj
zA&Q_3Y9h0!4i?c6m`hzy0S!U<GzS;a5>!B2qy%el3HD$K-N6!iBFnHxmNFPr&T!yO
zj4Fo0s+b5>u`XP}hA<`TLR3tJ)i57f$Hrg{i$M)6hw9i7qGNZsfqj9^><Mb-a99(E
zLd+ZvH*zY>$nl64&IPq|A;QANkPfbdb#WoGlPi&3+#O-#&PWGWgSvPy)WQ9cLp%~O
z%)=r5Tnlvabl@P*MvU-6&?;Vz9OlKq)w~ip%Im>vcr$E*H^QcPJ7SXe!q)S*h;@7r
zypfM1=lN&EH2(<P%ol-k+z8*wjmRzh5Vo0bBNq4}Vk^G{?cmptB?N+CPXtlkc!m1m
z8REmrh+w=Ug9!)^A}lnJpztulLV}5m3MVoulDLp?(!wK2i@pgFOKNm7S&?xR1gDc5
zCZs4b8F7S=(x?ndLo$#>=O7EuMj4eubyOa;(S_)ub7>0CM;BU5OSFX6kRn>bB-p~s
zej96)6kAj&ePJ?sf-4vdl`$4o$#7I96VXc61lKSTQNv_#E$gEjm=0}VbBLDBp-n7D
zH?S0}XLm>wdxK5viZZc3+QiYY7EVN3I33l>sR#?VM748kbUT+ry0{YA%^i_eu7=%2
z>E*8QZte={=DuJj4~6ydSh(Xil&8X+JQ+U1Gtq-Q7ct5!A*=Xf#3-+aujAFwHM|<K
zfp;R-^Je%4-V58n2Vt{Z51r!uh*>_0oZ+9LoA@+*8#h80`8Hx3Uqx@@$M8jd2w&vK
z@MV6DSU@0%^+yonk7t|@9#Ot{g$3Xn6HGvC2tjdSM8rf86%$2lObpRs@x+EFk`$Lj
zLUb&mxMW1p$>fEllM|bYI4*_am=ubm(<qHhr#w7^%BXD0WAmwsEucCk3sqDu^)Ut1
z#}v^JTZk^Egyy&+EYT9$;)>~vm1B>Q(iI`6D?)}dt^!Atn!&It1|!w1idHibr(!Z%
z%S?0~vyo~xgz1=%(6TwandR69mf}n-MYOOx!pP3B77j<Xu`kNN(U>+)M0IdH+{!KC
z?VO71;&PmobCDffiFI%_yq`N`oZJ)P;O_8V9*FAa(Wqe_is<K|$RVB#8{t~`2+xJB
z<`0o;cp+|-7h=YFJ!UnpMQz~qn034vHO=+#^}HLqf%juJ@^SPuA4bmdS>#4Oi`mGH
zh%I~-y@hYWHuGKFGCxEv@}H=k{1CIm|Du)=xI_jbNc6)!DiqJyK)j<P2#5>DH!6t0
z$S8s%Ly3qABQ`OLxcDd%<6=mOjUzQKj+EGV(j$`)MW>J(ol16e8u`&Fh!e9Zi%X{@
zG6z{yK8kn|s)RzS<HTqa@~Dk0LKjttHok!71PPXyVvMm;I^rbQqsy_ylwplm&>tmd
zFhPMMTE(hJCBq3-jK|b57GJ|;oSL=qwM-?{vMI5Fjj_#aNzk!1&cM$2W|k9LSdKEW
zC&9q}C=2_e+Bp$#=5TBqXJX8pO|)}sqLs^W-CR!S;bOF%%Q5}j9^b{)o0UZN@nGT*
zk3_BF;b<q1MUHVTVVuWf$9W-kgclMgcs_QFS0X2QC2<XZik{;2m<_xeJI7m*lUz^O
zz<W{id=$Nfj}o`?Y3wFGi`~o@iJN}|`8sNu?_-wuDQc1L<Cpm{b_f5B-HpICAs9hy
zD4xlotcVZ7J2n`f<PZX*LkNhCCNMsR=-7B-qZ5csOe7{bf#k##5|dI%i%lmxF_GNp
z46<XA$%{@yk|aW!oQpIz8+lS5^7w32u|=p8i%`ZFqK+v>msm)Bash_qQVfY@m=a~Q
zCzfK3F2$atz@8|lE1`m}cm;!T6^z7GF_xfVIJ$=MBn{&U8a71NFrBPnI$6hbQUhC(
z^eiSfuqDC7QbG$$ab|YJHnT6jg*`DX>`St7Jh6jg@m5a9+c}$L<4k-P7ZV)Z8r#Li
zSO>SqcXM~_Aa}$$xf<`};rIdWiyh|iq*0zq9_6X{F`kJZ=lPg*JRdX4A7j_>THHEb
zN?yb3iR<}u(j4!_PV;umG}n`+xE?dZC((2KBW8||;}-cWW)uI4TmB8@%fw~Ai`~vo
zi97i@W|5!b_V7#cUIcDwAqW!v@s10`Ej}Fov><%qBJfQJBP1o9u=r?#6XS@Ai}|gN
z<dhUr<I_k=PC}THMrLv{*@>y-rDc$tm_cz|7R3qKh~x8+C5R}C%SD-5ggT)JRdNaS
z357JINzud=p-mE_kCS6bm10bkVvd*6kyJ)!s)Ek6N}S16^d_hnj#Dv`Qp0Gxnz7Vc
zR>#$|CP~M-ga&5fo7t4o%*F&0TjKRB#J8}RW@cx+h3(0v-#`wgw6ibG#)%Xw$5L$^
zO|f$(u9I8StlW~?!-YgUSJJw<n%vLbNlt#BG{n7${XCE|z@y2dJd`xXqlx1@5x<(}
z;>NiaH_G$L<Gh@-fmh=uc`13CH<BiKCuy3u<EFWux{<%eP4l;u8QxEw<D>XZe4e_Q
zPZGEBW$GedCN1!<q-DNMSmfK3C4P+C&3{w&^53-G2n1<C2!!Eyq=)049*J*C1paAJ
z_$7xCmJmx&N-UAWXkyaih)#<qAw7<i^u*sVQj*dUr6eOt6j6{aM4X&XadIw2DY=v;
zWmB4%i!3b<MM^Oh=|yPL3(=;C(FjY>3#DiiB^XjGXi1RMl2T4<iX3yIg7)-kdeSR!
zCMt2J)iRh|i!)u#P)aqUDLTed8(Ej4VKS|rxs*ocgiXw)HL^))V%yDAm2P2Y%FT1t
z#_rS(4hXI6OK9V0vW*i-R!%0{xHY|#TZBEF6*{<**2U%YUT#n7<BD*EJJJWZOE|*4
zDXV!jZ50nDjq_N-8lDu6@p#f&o=>0T#l&%5NuK7ll(oE;ILm9PGrXNV#XCv!yqi43
zd&!&lFmVg-Cv4-><R$)|wvEq|miQuJi7!(Z_;>m)eh}{9+r&Nml(LUs(s%P~!XX5L
z)Ck;Df^ZQ=;*%MIzc7rI=}`ov$KjWeNML#_VK+yVOl(R5(a8y<rlpXUoJexA2w_SV
z8R_YWgqaj2=aQG1NpVU6a#0Q?DMd(A3X!K3P?3@U8-zMViZ-=``eZrHnI$x*S7J^t
zqb*fNd#Z}|%xY}HN_vvj^roumORi%?q-G?wmeDjFYmyrn6V<Us*uX@lo+)87vnhIJ
zQ}xV?T3Jjtvz%#SIm673<TiGu+t@F%voE!a6PewdOz!54u!ocBy_`+&<9w=vOBp>}
z${6H#X@lIEHq2GwF!!Xc=An!+?#*1yL+N8YnX-zfGuQE4+62!DCwWe^j^~qS_*3e7
z-pHKfwe)FTPu;*<!i~I}v4wY2H}YZ1X8xA4$cGtQ`6y*GpNh6}BXfywQ+D!=a1URL
z_V9i3UjCiFm!C5B^1qDz2n3no2!z47iK6hzh{azRNkB#nzS#-*XT=ejnMhPd0x_aA
z;xZCR6eW|8kw~&IgG`~2^wcae(=y4<&Y~zio5IXY3es{YP0gh&vw-sKVpKvgiYy6g
zp@iCWDRo&A^y#HErb%c_t-_dIPHUEo_RK2m*-GqL)%0Z4V$Y~%AiWkxx|YGz21bOn
zjAk@3nbpYJtVT9uG_WyK&xWj4=CUo!r?s#t&BU^>h2<;@dqg&Nq**zf*~Q+>E{+O&
zIhJMRY^sB^qHa!Q^m8HG!EM4`E@lpLr)Y?)LML~oj&OhW7!Rb6@j%up9uST3WZF8O
z$XLzeY2!SXIl)V*)4Z55#cLTGc_Vc_Z>CQ1dfFD=6>a9N)Op^`*vfU`7CsVg;^XXX
ze3re$7sBoQOSGM@)0g=wb2tA^-@*53`}jG1A3q8Y@oVZ~1cKa9+;bvu&5LG5W*pwx
zu>@qq5hzL`K$uLpFqY8Vcw$8f#AOMI$xJ0VCynHcbW(*GWC?T0%FZGuBafWC9P%==
zDap*EIIDoN+!D%i3y=v5QDv2)%q>GBDyA;Gg8JN2bV510j0&1_m9*!U)1IrsmQhQ4
zmV)j)4P8Pl&b%5N!deEibc|-`8P98EO;$6LIZe!n49sL3nawt^F{7EqjCPhXI@p$N
zWjWi-p3DvoWOQ*L!_HA*7l-n?IG*d^R7N)^a(X$FHORRv2j_(YT*z>8DPxqoGKRUD
zGsHc@G42(v;(_dSJd(ABCo|UbjA$*73nzIYW0Gexr+Hp9$E&$>yppl;w|PBlGjC<i
z@pk4G-pSm;hgl2!J!hE@M9X}dwS!M`c5@?ZC;t-e=HH_2{9Cx2Z!!+?Q{HZV%{c&>
zdl3loqi`36;g%bNPi_RBxrz7}MB|ekPe6VQ;rVGqh|-D6O(7;Pk!VpWaXDF}<_Zz!
zWRsekOIBV6`JyaxvJ1$|&80Lq4@rIzC7DH(XBSeHQ$nSvjOuJTYEc=Q%u=)>8QMHK
zO*vIqa;j;~uc1w(!jfB!J->$D0yW)v)%1xp^yStwnA^mvEG?sXTGnNoSd-Jj`ut`#
z<d~QhHM3D<`t4+G$!ur2po1NmW_IVavqNO(P=S?01vXCP^l((v&2dp5r$r7<W%h9?
z)4`RzRb0*;;?B%f+$kF2YR)kCXHD=>&MF?sp5%f2NgmE$%M<yNJf1VnAF}88L)J!K
z%$wm=(Ht-5ZQ=ETIo`_I%6s|Scw02jd$~)zCtBu{>>Yd{THy1X1wIw+;0w`qZshLZ
zyPW;}kiVDj^A7N1&K`cqKgcinhY+|Hh9k%e!=or3pTY$E@}lr6OeP>F0e^8SfjKEe
z6(kX!mq?^Ilf*m`Y2q{z3e!m`$R#~TL{?57`T05I<%r2EDnwFLh*VreMNtWgoHAtM
zGE{|9s&mSy%_&1CmeZ77i6KXZNnB2=Sb?EHNo%g=x0BT+uBR)%n!a2e&g>?fxjI(m
z=o!h@GLh5Bc%G5*96f8Z4NMjonaww|S!`xL*UCac2RjQa>@4VJZ(#>Jb8YMq_i!|)
zo5Mw29LwwHWPTrK@*G?!7~xX(Ft_Claj9sG+j2&^A|B(8oC)sFALF6CwcKAY#X|*C
zJRzRonWA+(E}rD+!bzUVp5o=4O}tRFiPwr|c{OhfZxt=@u6T*J^0)GS{sQmjY~%gB
zU3^fuz~}k9`80ng|18+Ww>i7`I%gmM&e_d31$+2ee1IQ|j`05qP9Sj2kHEbs63>D}
zR+L2HQ=EvGI0nDGRKoI;2^FUiR+vIuk&xJ;ETScuq!ne5UYtp0K^CcbSqMw=C@2zB
zR8T}-p%_VC5%K~FWrZbFm6RYC%TVW+QC(O;eX)!Nu@X&@lID_XTJkC}6jjnzTt%z6
z23tuTU4=E+^Xlo7)Z;AB(pOl|P?4V1k_J}i8yGKYVO>Eh8}bay=Cv_fU}m<+%+`D>
zn+h##FKJ_YK{vaKJJ})WWq(O0`wIFwChp-xo`YirL!2ud=2XE5XNyO<EMCp+lGWUn
zKgyjYW877=ihJ|Md00Hjz4>c-EPtA(O4jjM{yH9)Oz~{tJlDi?yp+F%m-A+Lqj(Fi
z7H;MBf-Sr!-p0E{3tTVQ&R_GE_)xsSKMHp8S@90O$lJviMLW15-pyAfHxUl-op?Y0
zE#A*Bg@^dH;0OX2X*dE&0`7$|xD~|UCym3qFrMI&c)|*k2`)$_x<E)|X(ow9S;UG(
zBoqrtD9k3gFrRF3KBAHWvLyNBit`Xl@)1jlkxGgvD=J1_RE|t4qo%k5MQIh)k}7mX
za<mc^O=2}IMYR~j3XFwnTE!|lN*d@Xslg_0z$w+ySFHUFV^xWs;i5*?7MoZnHZxV!
z!j#y+2C0d8sfGFCHa1H-SuVD-P140;aWC78yV)=8<*?Y!KJm@%<b<T3V+H-(QZ&rD
z!d0A?uI932n2W_@{7yQ?osu=&Egs{(!g21CuH(_tDIP1C;vwmJ9uu$US?NuT8Lmm^
zc~QKP*Th?Sqhx_si?{Gr;S%o@ZR5IRC+|xZ_*=<#J}TYKr$x*BQ?i#&#ryfZXdj<T
z_VRV{VZJNa%a5hU_@U$oKb0Kf*W%*{1kzYs<k7fE67eXD!M8XbKWP#{l0<?^QwS={
zAh=9Oq&$=8vUHM*Gf6JZBT1TzsHBi=Nj7<sVsgv!$S=vKq@<K$sf3bJDJ5kkR7fhQ
zD3zfsE~mCsfvU8Uy5b7zN~<tRYiX8fXeq11EUCv*T938(W+nA>mT9q<HsdU9#8IYa
zNY?z@jFsw{C^0c5Yh#_*$fVrNoY=ywq>aUrE*2$SEXjLVl=iT*xRX7lJsd3U<#0(4
z$I6B{A|BzSd=;l<qns0uaaK0U<<c>3D_zTF$v9VvN4ZPBhO6=oJY2S(dy6M|ymXSs
z<#RkGo8#%SS*}TDxmL277t1#DvV1GAmn`z9;sxH8F7Q_IGVh6Z@owpE-jnU%Bk4Xq
zEZfCDqzCw1x|`3+4)LYzApa^o!ndVI_+EaTAH|3HNqT}`Wv3Ci%HnX5#^54NVr5AR
zJ{3v$%2EiDCJ`V{C%iPBsPa@IC0RsEvxqOxAWoi3N?8uc(j3y{d5Fr2$d#5-Bo&h{
zFQiajMsay5@^T4^k_xIyq^L{Fsg^5HNtM)9RMJ$grny2*i(Eykqz0p`4y(M5c3Cam
zQa$#HI-C`H2FjZmlA9Q-XkkQdV!X`2I*Eyi@;0W*+nAHLv#Gp;S=r6q#a4MIJLGm2
z%X-*Z(#szC0Q*XMI4J4mkYs?P(h<(ehd5V0#;s+mxF8$heEDiFl&s<Qk_m1vpX8ph
zwcK5@fd?fMJWxKz<K^plLV6Qq6VFKIcviNB=cJqYgJdJGme2D?=>mV2FY;%}5`QjP
z;x8r3yf4|#yRz+kRJNTDWV`shbRVC|_w&!PJ^V|4m>Xrs_)&VCpQOk5L3W&<WT&D0
zW+94bT&iMll_la)mB31Q3W4%;0_7sY6d8n6WD->=B&I5dgsNPkrP(AZ3P_a}kg3Qa
zqq2ZZc`2EdV)81AkSJsnN{f+J+$^M&GI<3R(lV-LRj3sTs;iVVRMnuBD$rNdVyMz!
zD%WDFXrNu*K)Xy!XJtLzie|dYn{k#kF<92ZP<bn3l}6S|+gU3!vQE~@`pR}@E3M4Q
zJK0p(&F0Duwv~6WtmtAv-p_VfAG@Rj>@6GQP~|WOtA;r$AK|oYgi{r(xkbL3^Ht+q
zE?>oM<&*qQHp!i`b=*<DhWlj`+*38hz2$Q}P&v<I<r{dSYMN_hb39iu$MY4Nc~Lsg
zpJdCtQofB>6+3xNvBaC@yLhW&nRn!S_?u!6A6M<?6U9D0Qtajn`9Z#r9_DM=L2gtY
z;793UzOOjVFJ(vgsp1&FmY+i4qKZc#OT|^5id$tmKFU;lDl-VF%D}H8gTRVhq7}J>
zD@DY}@`;h>kXD&Xsw|IWc|O9*0z}Fpaw;W=tHhMZi;*fSC{xKOmscW{D=Al0P+eY*
zqC$bHQbny?L!(MbV|fiGSq+xT1}ySg+ErT2Djl7Q2D+4uI4YXyuWF)CX24l)VwK9s
zh|<LB3L6s@9jvWtXT8kMw5o#{rJXI6T`VbkSde$IP|?k@Y>>UmLH1XSa7Z!4LHR09
zl@D@KxtdeTG0rN+xFB1_MdbvS6%$;RP4YX{2JTU<<sSJo_sM3sS2n|=$|)XJ&hUhM
z3(r-}aZS06YgLOpSFxEFDi-;pY>BsI3%sM+$vcW={-WB;yQ;msFW=9HH+R(m{vq4X
zC(5IIB|F6DRmb^Gb&_u@Pw`#lX@00Y%75f%q2e?GfjSvMMH24nbllWw_$WjKszmr!
zrV*;nBD6Ax2xS)0Rhh(B<PleqOPVsDl*$rPD+|e1OAu9*kgX^tzp|V{RXO4+Dbi{g
z6$&}>8YSh`3M#9ssH#w+R%mEYYpAQNMPJi^UfqDPx(TB~LyM{rYlR-Gx|yyT16|by
z94aG&3Nu5>7RFRY#uaT$)|eSrS(sLKGhN-urWz}=6`d?rce12(uvp_{yJ~>#)&1<K
zc5=9SkbPAn9IhPUuzHXaRpXqi80A*wDCa6xb56OMD;4XxLpjM+#d>a6%<=n*johzT
z&qL}d9#&8DxMCBJRc_>Q^+ukm`9F+5D3^GtavQHyE%4`>9lTb#lQ&d5c(ZCR?<@E4
zLB$^aUbTl0)Q9<8agcwikMo7%C|_2c;70W^zEd6J2h~}At~kSgR44hl<}3m?O$vhQ
zM7)*hxG98qs8aB+&B9M1B&0f*kg9yb)H#G{a)_-hAVHHyno3NvI-e9}0YX(F*~(%>
zwWZ`M%P7!PQc|rzT%$m$R#C35LatI#rBI^OXsA)BsMplcSX)m+bsf#hddx~a7LAtH
zDkB|Ljo380|2tVK3%$xV92x@ywI+sYtc=yPvQ}kdou-?0HFh?ry4h6Q%bcQ*O{#tt
zl}@&)`&h0WV25&m{Z)hPSFK`i?HEU@hdHbm;dIS7XEkd%T|LI-nhDM;r?^-%!PTk_
z+@s#W-Bla8TD6e}s-}3LYK8|?TX;ydnMbP@d7^eRPb(LBMzO$iitW6lSmq_=0<YBW
z;O*Kyyj8uIzbbd|uI2#mDfjV-YA+wx?&XuJgM6Ys#urtG__pQ*-_#uA+uAdHUwevQ
zYEJTl@+AMOxdnlsE)jt?19wd(E44!WYE$v9%OOaeL9iy9U`-aGsyt%q^NFo1B)YDI
zRCOuB+5$3bipf%!A=Jvqt-Cp8lxSs0>nbT$%PG@Vpr}_;uC7H@Q$?-1p8DEawDoH0
z)oPkm_2|`gG}r4fs|<8hH_}$uM2}Wax5k7++lHgYh_lARsMf-8eLExScGlF{7_YT5
zbF&OpCo^?@%-8p_wXU1Z_5Ezq4zR1fpPe;B?9vQyNHxF#?P`wKjdEPOieuVwPS;Ox
zp>~{e>b0ELtmjhwIxf|3;Le*Mwevinp5ejj%{)>w&x6`+Jgi#eam^x6tCx9NwZt=;
zC0<f5@sf6#m+Ke#bIm^9*6!o&x?TLGZa*K?@8fT({d}N4%7^tw_*i{{&on3bm+BZd
zG{^X+_B7wu9OuW{Tlhh9njbZ%_;1}g1cKTmTs3L9G^FEEmxZ@F2j7}3g6cEzuMrWZ
zEhMB~Or*Ae=-NVJYKlmz6O*DVCaq3PW^D;Vt%RJ~3i5Q7<kiS2s;fX&SB_L$g-oZU
zysj2yLmf356{@;w>NO2C)YjA3(1=m3r&X)RTx+7ep%F`cGo7`~bk&;Zt#8L!+eV+Z
zoe^z2gLR#ZXgV0Lv$Cen&O}2ObJ{*;)J|r!11#1Kv03e4yVk)@?Fc)yL+q*><bY<J
zeRX3Ts~_ixZk*HFHJsM1;auGs&Ni&&ymo?%>N$R=p5o5>dG4&4<!<#x?$>PMf%;jV
zsNcdPx+R{`ZsVDn?L4dA&hxbkJYT!SYxR40Nw<qXtM~GH-7em#-^*Xrhxwp>KOf#i
zsX59Ay2JcKbA%f;r}<KQly7QIapPtk>JxmcJI{}GxA05DdHz#>5rJz{DlQGFcxtm*
zp~=BllY>{Ih`_o60_(B}Ys?{BmrGcKgt*2ck{Tr>>q<$~i%F}OlB$s*tScw4v5M?E
z8Tr}@3hT>}HdIr76GW>(saH~|tD~wxO?6!j4NbM^^$los^|UnUFxDGsZD_<+r^j4x
zp{JpRE{z#SqZwztnL$k(t2B0owe76c+gPi!v$m;=37vzP#$GmRdzoo;vboX0HocP_
zO#>`94zfo-%+9)T4r<0Zq#gYY<8Z?SM;lgix^V+%HS4&waXnXV7E-r?+w14JQ$Ncc
z+Bxp6+sb{7Tez=bGY{$Jc~Y~)GmTq#yly*BYZiFEZh=2E?%+>N+j&K|oi`fy^J@Km
z-m5>z^~OWI({z}>HSOnp%|SlV9p+=rQ9jij<x9<RzR{lGOWg^+tv|^R+SB~3xrHAZ
zZsnK8+Yktv(hz9V@z!UsQlEvdF%xgS2)~AG0-K5mGv*Mc7Zcl9K&)O$oVM`)KpN#_
z8p_Eu$jE6bBiksWs7XbEUWvG|0%>z4Wev5IH>s#FYN%+eMrl-|(KS)i&`4urBU-(d
z#%4XO#zu@y&9v#wSadCP=*;vsnsGF=G1y?EzroC4Qx~JUcE%ceSlwi0LxY1UT^BQ2
z2lM(t=8Z#aGmNlc9A<mNC`*O`wi`y-qg}<p#!>b*ui=n!4W|w3INrFHQ_WM{qMhcP
zeumq0b6hq|bJaM{T}`vxVcg2yP20GyX$$vi=Xs=Yfu|Z5c~ZBP=Zrgf+PKU!+Fd-~
zxSiLU_wYu;F5b}X=N;{C-Zkvu9qm!x)g9q_!%?p54)Q_sDL!pD!l$~k+|VB9M#EXY
zGoIp`#&i6jJ<ETMm-*3f0rWRdmM#rfg9ulB9&XK9_~=CVw&dYw$iuHGmvFs==tc=q
zjfF(F6cTGHCfQI<no)+RrHrgbDI&d`Y=eTl#tJ053Z$lLN=!;hn`)4mYEU*-qiU)_
z-CRetQG-UOM`O@pFgBxWYQ&&##nNcNrZ-@2Y{A;xg0;~~kEx9wT_=NvP6iq~7}fW%
z#?;N2sh6pyex{5)%<B4?GYm7^>|~3nk0qUx1^oa!nnu}Y7~w$ETK4JIain>aBl;;$
zx2)k<%LYyw*K)RTii`RgE*WRItz`qZ={IxNO_b(Y?$$4GziFO_O^ZC(xP>Q8TX{ye
z$hF30UN9~5jA0+on|AQBVF!QI?d7$`{k+q7gm;?u@@DgKJ}@5SBi&&>X*tCQ#uNNg
zcZx4`XZT8Yl5h1V`Ob8jZ*}MRchfok({wApHlF8K{doieb2<V;4lb=Cyo{Onw&oGg
zTtG-m0l^kA;d(I<%_YQIiim11Bi>L#qD4Ylb2%AiIU;i<*{w2iOyv}`C@5@JBQa|z
zHB}>Tsim^D9;KlUm7x)pzJXeU4z;O?2D2W$z7dnffYD^2t;K}JV4}m^LU*$Thq)6+
zb0>plJ3|I5qo!U~H}|r(wU=>=lMSYRrki`%sCP2eGQ_6l5f+<=Sh5VTpdV+KafId8
z)$G@gbFg&{dreauZeGg?(|S%Drnsebk_*Q5Tx^}@ym6ijh8Zqf=DA|r#y!mo{Jv!q
z_qT52-j+okHg4sy<|UpoEbz2`2iGinct*dUmrQ$k$-JLeOb2<j<p}Q>_w%mt2-hu#
z`K$RD@3tP{@2zL}r1>}>nU3?B`4pd;PVtrD7QQy0<?H72d}F+o?=6@3$$XLj8gED7
zZplGl$i~H#iAP%wD~$yNm~sd(7ZKcANN`&*q3vZvwn>O>lag$flW3NZWR#KFRzY@)
z9ASGE1ttXrtxAg8swilwMQqd}Gc-_cu0?5Tq_VXUjj5SBlYtsT6B>&iLyHl;QIFne
z#L#BIW--xeY@ws2o!&M(z3o<pEOs2N-8fr&8E)%iw6%{>i<5~q2a~1&*0&EZ+cwOm
zn-Hz5*=AnNqHzt|+s4@5GQsY)aSpUku&-^3BQ0w<Wn9nEwmHtU&2o!ro{Mc$T(oTF
zcH=B}8s@miFwdRlt=wna%>9<_Jle9zW33B3W?JIOmhC)k-ov$)9Xw~;!3*t&c)_%r
zms|GnC({AmG#%zI#zVYkIL39$N&aR&%16did}uhyr-rk9ZamMY?PvMgbdm4cF7j2&
zMSg0%$WN9_{A|3$&!*qqEJTF6RfI=-4lB)h_?rvxY8B&WEg--uCc-Qs)LKGxTQLdd
zauUszq}mh+TNR|=+!htNHYEj?D#RTsN~~%mt@TJPYD(McklLCkZ_%M_Z${DDgtonj
z23r&Q)@F>BW}2;L^fn`gb~7FA9a!4iX}5IHY3-uh(t*>~i__AHv#pacYd7N^Jxp5q
zSl{AcL;DbuEkn$;3^Ut4#-eS6&28f>Sk|z!ZIpfH)$Fsb;c)8)4z{f2gn5SJEwh|4
zPjj+mmQ!t;xV2@DTP+*8y?rZ}EZextyujTp%lzKFjeBi7c&K$d540`uaK}y_@7Tk&
zw(UIIvYThD`*^{!hnLL<dBuE)*R1<_r{g&9ww>TT>nZ-)ae@z8j`B(CSw1nJ;gi<W
zd||o3jgHfN-g1_IS<drs>m|Nz{T;t_T;%7rJNdQ!5(2l50t6j}xVDM$GUwxADZ;C>
zgg}d!KzkV>mJ%ZD62k2jM0LuEvnoijDoAaYlWeUb%~nlrdo3cflI-?c3T+xB?P^NQ
zT4eS*sygeavg@g_Xwlg8R9ke^TAI+<Ea=T98toR0oh`I>v|zJ$&~ELdr_F|~qnj>s
z4~~vr`Z~LCcJ?vS-ou!EkTL5JYdRgQvyHH!ZGerIA-0-F*xI&+t>y`KSjO4eKFMDD
zdUkcJ<*<2*y=~JRw6Et_$3~8~O>;~8MsBff=DcN&%a+Ytwrt{d+ZJxOZ{_aJW$tNT
z;(psM9_n1?0m~j9w(j9t`#zrPJirSb`+3&Bo9C?i`BVELUg|u?8|?>q+jfLMTaWNg
z=L!B|JHv<OvwYHVnt#~O^LfW<ZnR(IQ_HP<ZoR-)_DlR|y})<o3;bxijsLaZ2DY1D
zR!1Q&b}?=}MXYQu!mmq$SErP~juL`8qy+Yq6J?VV-CahkO-gj9oCI4HX<g-{^(e@&
zS0b`0$m~&)-L0Xhvw`C7dWx+Y<Q-bdto0~*8d3HbsI}|Rb{VL(TF`fx(RH+9>@d^%
z8%QVC_BQN2c6zKfdhJ$vJFWC}^)PJhWuU#EQCkmdy89Tl4KrcuW4d#g8QUl`wqdq(
zjWXZ8nnl|<i(O;C?d7gD?CM_6;f{42>YU+_b&8X=^&D@X=8SEc(_LG*Xxql6&W&7b
z-^`WvC9ZZYa)*6^`#YAnr+WtvcJJol?%h1nzME${ck_gOKhJj^<VEWNUg_G;E4E|2
z(tU*2dQS41^*C>LoZ_91qrBgJiodp>=A(}Dd}KYt$6dE_qx&LXbzb1x?(=+Ozs$F`
z%lu@!#4jCJ_+Qs;{J)N?2wb|wxY&#FbQIv>$j7s{1Yd`gkj|T@N=is~1!0|1A|2&K
z*=0oADoN|9Af;DLs;!!IyAoknJvm)9<k)JFbk<U2)l$->r>s{;MXw&E&4{wsKvh=@
zsxCb`TPs?J38T$~-fF{aZNp-3r=_a{v(-vRmkpc4j?>YJqpO=fYd51^gADf!v(_=h
zWcL8$wo%sGM%iFn&5UgoGxibY9TRM|u4SobExWtdv%7Pe9rpF?>6+zG_eKtN&vUAC
zj<cPcIBTEflw%v0dN*-v*Ea6xS>%r1Meey-NbeGNb?xSU>rNi&T;@UhUY_dQ$>WZj
zW$fXa^$6FxkML5@QC{sm!Jm3h@S5W=uXUZ`ZR>IV+Ixa`dvD>d_H$gfU*LWFEqv@a
z&p#Zu@VWgm|FT}<hT{rf_xz4;yKdtb>z(}E^E<HJj=-faANT$|y!#9B>?*{ktB62*
z2|@kE1UV#xJIe{~lM>OdAhxTL<gRiO9W^9$)sWg>MRspJ!tQzsy0zrl)f79MD0S#5
z?a@-vqo>l|gz6@QqX|W~o|=9O^^P`lJti8RHcWl3wAihfyR5W0JF$0n(An3Cz28n>
zUmt_rT@3g2<LvKem3@ej?motyV@&mqu--AkOwTY=y{njWu4ZHZIyUu9u-&nSh2BY)
zyKiDlakzUuM|<Zv);-V3zBx|z%yPDGo?Ci1aiMDy7oD59-M*bmUE8_p+{vB&JGg3J
z;`ffd+}FLAC!D)^+`gM@&fPrQb%3XO_w$_NAb;pT#2@W9VNUX@^9*nG9^=n_CwR+o
zitEnPeAILHH;9jW&hq!Z^L*NKjvMw%eBN^#-}PPL-+g!RUDp+UvfslG-FNV_{cZ$;
z0Wq%5Qrw0LSkYgIZ+|fXy(Refl@i(`C45Lha8Cu{jw)h%D~at>lk8NGHl!i5S520)
zhOE9CL_<1?`n44HG$D30A#oaz_ctN!YeF{Ah-%1)#@ULd-$2b^D|P+tH1wD;^|xc{
z?WV1_gO>g-+8tfkdV6sU_0#R_p>MDUXU{OJ28S5z>toe`lhNKm*7uFEc5s}T{?*L)
zk1{v7n)#k_7M$x?c22N;Xf1pCr`XfKf!+P<+2@$$@J$TICQkHj;!MwGE;u%G*}2SR
z=XS32?Bq`84z4;Exa!!+)&9NQ*SDXCdJgcA;~<ap9_G=ZeLU5F6XYO&a2)6P!IQku
zdy?1tkMXAS46h9y=e>bjcyH(=?+={jgZ}gUeehO3aool~9hdm5{|a9?F7f5S@A!J?
zHoot<gCF|u=D&`s{HOmO{?mUi0)e9x*8vHxgC)2Pmf=5KhSx|Lfetyr{W5}_WrPk@
z67Hxba<GadXC(=JDum8zG6w3&aH`33)*u?xQ8?5<abF$9js~Oy1|-fFDhG`yhg(oP
zTB#l}pdN0ermqE!!%E{oCniTHmO&fFJ{ui<cFc}WditI8I{N4y8K7@un1R7TR*m#A
zJUqro-vH}|M*cq%>N~0pdjJ18&g<US)vI-nUbkMg)mvL@m)*Oi0}7>#1OiD2VTBPA
zAdG~BFcUJEAz=o>3?uA4+S*~Q+v~o1z4lhU_xt>v_V>r<ygvUw&hw2tJO+tCO58Cq
zijZhhkI6_0iz6*UN|qp=ys&t(BNEXF;?RaEFbGpAi%6#=EESVLjV)YBMR*3*&}?dt
ztEi69P=7p&rqDc^j_1=RD4_Lt0o~z+bcg8a4AatcOiQ1zn8ENOCWS>zhn6rITFOjF
zDYM5coDx`B46ERb(99V@HRlAie0I#nm!Xw>9a_nEp;dep?&2q5BR_{U@Uy_dzmL~*
zDZG*Yg}3l~#N|Q+FXI>XDp!f#;Ks-m+!Fdaw}{^2w$PQ_DR`IrBi`Y@@b|c1xRM7&
z@3ACm4Ua{x=gEloSQfT{r^7bzLf8ggirB)-;oEpUbQ`Y=ce6sUo7aU~SrN9Em4bb&
zj@-?=qW!E9`t$zfQbY&X84<vq2!Hkp133_RjC~Qo9E=PiDDoJGg~tdK1rsa?AuLKj
zs33~)Z~-ylF^D5X$VFn}gi$1kBq*ZfC_}}h3FRn-QZhr6QH92#4NoF3G#+huDtb{W
zCE*H6MCp`9sVEOsQ7O#C7N)@=$iNw;ram$YmmmkXD2Jvn9quSS?GXn0qI7tL#SC4>
z5a<~UGcXZZ#F(&@@rY8UMdh3jSvW1Qa4O8o2a#1=h^XRhST&zSRr6J3HD83*^F>58
zUkU2@XJj+~6gBc=R6Q3%8~Km0fnUQ~_`k50%OJ0FefV;&3V)NEBj4nf@He<4`YrB?
zS;e0tR&&4LT^@*9!-LV6cP)=bt>xkH_jy9_K2Jt$;i;%?EQ{RE3&QO@7rl$WMQ`V|
z=&igd+{zo#`*<sQH>)Cdu_|IOs|5Sl6tkE0kw@4f^k<9kDBA^r?2id#Z$uz_BLg`g
z48>m*PGI<Pj>kk093eyy9*H0#nwZFNMB&jyM@xu_i6$;eiab(=JVr)(OdJ`4L{deG
zs3Viej7laqGLgK<RE!a6Xd{v-j7p<SsKOkjqD+uQRd^;gK@QbXdDKR0Xb@;=3eUzB
zt)Wq%qbtTpyQq-Pm?C;&O7V&c8H_eC7+u1!sEmo2awY{O%m^x&jW%&IqJk3<W<HFz
zUwI!1syQ!o@>N6~p9*XFKB}H?qU-rSriot!E&L*E;bL?%7b6?_E!@K;kq5u4qu=0q
z@mt&|ew}NjZ*ybxTihslhdUzQ=FZ5q{8{u4cS+yjp{UjTC29i?OV;p^cmq#}H}Y8I
z2L3AEz>Cry{8hY@=Y>0XNwSkyMZ0-hx|cU%cC%WzhgHG@yc2Vf^`gUU5*=iV)SpeF
z!|W6vW{2nyyTk$PlOAPHWGDxP!5kEaaWpcVV2O|jk%)+BAp(&QkuaJViI|wESYm}T
z;v_N1MDfU@5=f4bk{Tr^OB_#TOx%^t6Q-dTrIR0>hEb}dBsvq5P)TuA78Nl$m?XJW
zO0uy<s&PeXa7l7$mgeD#%%wd#kM<}dZ7~ION0!nbRYaetoB@fM;b;?+!g8jgOBs(g
zF%xBCA;!c)R0XGmHckp_xFE4}Hma77BvpJRtmg}1BmWRJ@U^soe@dPFQ`Epu(T!XZ
zHt~nFh5w4XK-7-kRniq)D}Iw3WN&bt<ZW&dui#eEYHo>L!#z=}xKp-<`(svfZ}b`-
z7QN3>(K;T9+QQ?}>v>wbm8YWL=LOjoo{!$jbJE?sEZWVh(*3+9-ocxaJ*<e`$7-2B
zt7UsxEk4Bh*h6fH4P>+EAUnl}*eVHTchoWVh>vqPCWr&lFao3kf<*#CB%y@Kga~3U
z!w3*c#7LvXL`O@JNaIL|5tAU65ig5JDNZ0QDiL*55;@TdG*PMKiId5VQc@^VVHBrQ
zC`qI23QRUOkp{acm#XM2>Lfax(b+Ua<x?-sr$J)GBhu3@ExuBRS6YHsR778_k-?Z^
z#-t^T##kANu`v}}!D5V=6XI%4imN#hW#^=*j*rAOoR?H_K~}@((T#i))693VO?)q@
z=Lc~s-$%9clgz_^Vq5rC*2#aQt^5(&j^8!0f5$I&1=q+|b6xyuZj!IzmiU$2E?dXl
z;`Q7qTg(0OceyuiEe}iI<6+q*9*Nn?(=i))LcE1#vTZyk-oZ;TJ9$aIm)9iQSsuTG
zzsdZ0Lwt~T;t%kS>>%&O1+YeZkTvonY?cJDNfyjz$q}~7g4iKF&d&Hy{AD2=kc4nV
zBH*Yvih#IqLgYfi<D!X*jV3%U5^0PWu~ddcEI}rYLoSa+9-l~>OpaQdKt_BD>X-y_
zC5hyUm1xBZ3ZzPOVl~Cmbjrk8n8a$V@!6PS@~Di@!67N2E~bDwc`h!Qo+gQome^w2
zVoK?h7Sj=Dpi69INLGY5#*8o4%&5f5h@_l3shQb$J13<zoQkjF192rM#ST7-tK*Z{
zT0V(!@}=CtXJQB6N}Bm0ww0gcE&L#D<43WFUt&G{DsSaCSr@;{d-1y}{!RSkZ*#R|
zH8&={%MG#badW~t?oL?EU9s<Sf5Lm*C)>dNiR-vux{f8%%{(O8#!}fvo{(?iiTG_S
zlkDK-*qywZu#eXgckyQ2Zr)7v=gs*2tcX3pO6fk<$^u!N=+6du5bGqz*dh&JYitNR
zWkGC@3+I4Dz`?jM4kjMwpgf8rvPgpCM1)Bq5yVCjCXGcP6%(B(CMrITnAim3r12yq
z#*&&CPfDBul{A@jX#&}?>1blp$WKt9lVzZbRZ|?7hA~b_X<`=TiCI*{=3`CBp;D&7
zk*LQh&8IF=k4vt_CDG9yTS%MKK!>ahPizU@am5Tui}A*r8BZ`XnpnwnqJ{CeYUX5B
z%*I)ni?8BTLN%vjYxyYN!N<}@F36ktQs(5VxK_T7ZRTrP6F<qD_#v)?e<pbNC83kw
zq#gV(v7P_PJox#={T;u=6<ig!hMSZB&P}pa+?23}+mheo_QW;ZpR}I4<2SJ+ZXHV!
z*7KL-_gR{}gGUo~@?`QBo=|M(ugTk37PpV*<a@7F@<#GO-c%gst+@THjt}5n`C;Bo
zIKn!402^dSS(k8>E%FeyD8ks99LAoc5Oya<uvZ?*q2x%8B!+QF9z(DqhA>4W#}i_R
zN{S|27K<oBMpV26ae^GFJPx@cj^so+De?r;<>{m<Qcx?B$yBJxk*AR_Ps5m~Mi-}~
zP?m`?DVt(>HumIPEOOnIt(N6c8&`-cQBS?Bh}MK6niGp~CzRt(Fw>h*OlO>#fdni4
zaTbPTW_$`0V{vvS6}8MHRWci2$?1ezK1izJq`Za;ibg(6bZ{Zb$rlOrd@XnJkECY4
zN@(F*MF&4z#)xa>XL%35C3o{%LI=MmcH`%l_;;>P`8!v~ujIy*)!dZ)9ycgfb93T4
zZcliRJ5$$kPx2P-OWMi<iuYNn*vJ#fyI7jKjmJ{9@>j)9o=M!p3yHgVDQPb+B^=;y
z3Hw=|w4XQP53@YppH=aPc}H>d3dlwPXF!<0MF{IsgV~T2%=Y*&wk3zKD><B9iU{^5
z3ptV!jek-UN0WsdONimPLV_SshDZ@jj6#MuC4s2qcqFOGND|{vBqx)sNJbH#f-)(I
z%;a=52`bbn>0~D>(aP26<w}h5T#8cjFv&HPq-If(l!G-@k4>(nI#ow~Vj+%X11$*!
zG$a<$lw_nO-b_bIIbF#nx)mn+<W`1LtPCex8H=|wkz!#orHc84I%bm`%*$(7jIZaE
zyn(aw2F@q8@Nr5LpT@iRCZU<{Q{4O*-_Exw?ffggonKRX_({>me^R^opS*+rCU)U>
zjq>kYuUN@dY3sNqWi2-*zQ-+T?{in`TJBV?=bqF}+?Be8C28APqTI-m<n26~w3DY&
zxA9ccHl9}QV_DiRo=w}wOG*B`qCCKBN&8umc#zkX{=AhI$Qnf;E0qDPQ-rWV5zM;u
zAU39lvOOh)T?zqvQU&Zyi^4xGnuBQq4k<(gDWwD^NeESl2)m4uEFm&I7IC74C}lG8
zq<CUelSxu4NJ>v2QJF?cQZni!B^haH<R&S}PD)3Yo<Y7sO<}SceWIF@6b+`7%Y_tR
zP0Xh@DUZ6eLLBLO8d8ijr<T&3T1HD^IiBP)-05ZXDNGEclrxxW$EPqel5Arr$--!g
zjftdM7LuHtN^$W)S~Vw>F3zPlaVFitxukl|Cp!5o(aq<I7QRSn<D0~GeoSuV7iAm&
zQnd4v(!<5XUj9h#fz)pNu2!waPq~(Bm8-Z`xsIDMHgLOY9k-@$<{rgb?nznC1FDVu
zS-ph^(l@hIwT(wpck-lS8_N{ic{Y6?FDmx%tYQx@r|jj841boV@8b=nKPxf<S)mHx
z-ISxOO*_iE)BrYQ1o6J|7~7TM>`;fYRT0i^WjH&PVH{RQv0o+Ruu?)mnv{@K5y5Fv
zB9v0XQ{_aZ$`Gd~5|bh)R+WS_U4bkknS}H-l2VdM$w(tLHIr<$5_N_OO@@;E)C_c~
zYP9Mc^ywN(6$MnN3#drfVp8N`O)sEUS&TEK0Ee=a7F7w&>JnPj#k6IZajQ)9s_hJ<
zS?N!+GMG}yxT+SPs)jLT4fAQ0Os6|pNUP^$ii5LhPR=QsIh#_?$LTIEsG9gBrI{~N
zTlgxig@35K`60E7A5+`-Rqf^9N-w{ud%2V`z#l0-{QNT4;-_B2^~!g-F6}*TQEuXn
z%Y~>n@@M7y+@;*iJy{!hFl`f$sJ8JJ^==+d+s>m|yLl#UC(kJN@uG4U%To97oYJ3{
z)AqAGEr2&v{#P(oq#x$pv|!#z4PtdxAZs$i*_0a2CbfWVX<=+hjbeXh1P9W>*{c?C
zAWK9*W(<K@GD6bC9M6nLpp+uYlo6GdfLN7)C{2!Bor)|g5xFvn<cxGu)77M<XOfzw
zBtxktFEfkW^j!4mS?E<+7*$yqGIf}gIhfR1EU5*UR0Y&#>Zw&5s7WiKQB{H?tpsOA
zG48Z-I@BgQ(<|su+v!nR=uz76W!V``x8cjIVKl3nxzrjaQ>$6bbZ|oL<g~hp4>Mex
z&2n);*~ll#Mm|?H@kK@#UuSgiU6zOMRbBj&)x$qCy7)D%n~Uj#{5Rdp|J1|y`Ki|9
zr&`BVstsJHS;MXBP28;6#2uNNxIJ?d_b4}Wch)u@&}?RD&Tbx3ZDXlw7msD`W0}&Q
zC)5XcI%^LvsgCeM);?a*9OAW%qbyeju{`G(?`V#)S`)~-S;u%cCzN%nFgE9eu~{W#
zmr}@%>}d8Y!`Yt`#er-wM^sV{<%kGW#uAbvAviMup;AJmDuKw%IAXFCh&2hsDN~SS
zr;?nJj9i&QdPWLqIZD#hDpV>J*~(1v)hhCoY6^4mD9*^GFe?vpW*+5Pg;ZqgFl&mi
zXB6YeDZ;5Pr9pN1UqQ3F6i;ReU79l5Gc9yzEO@i5_*7N+GHV&itYkE&j!Bh+nd};-
zvuin#<KTnrMiw>ooXKwCtfrNZm2SSsXyr5YWsEMq(6sZls)L`EUVh2x=0|lGzvlGt
zi@KlRvj_M?(~qBD?rQvU)^NRg9oOZ&$Mx!s+>*78TQ%GHvt|o-<!t5t?Cty|YwMMB
z^;q^!9?#p$<9WMyDsMl}YWDHhoP#XOImGk10lb=Zh&MA2@`mOpf7cx6t?XmGl@-X^
ztRPmaBG{O7j4kR2HslJ~oEgS8bu`<v#q7=%u|GSK097o3Ik6m7NjR1pPf(7Okla{8
z)kz4ml8DJmMU<Ct1tU?FfkKr|sz!|>H<gs!3^MaF(WrCD%T=Mx%|?^0MVF<aNTa1V
zr+{LWfikrLtJ;Vy+d!?xKuvBL)v8kJa*AlkEW@QLzjCU&R3<vJt#oRt=*_OBC)>(k
zZXJW!b&Tb?nA9{dtEpv1?PNBqo)b9@e4uf1I<tun)gI1fxAIv|I~O!<e6I2Ey{3bI
zXgc^Yub&?@U0hW4^6%_EE@chzyK0c%a|ZGA)2_oWe-k(4yw6S9TliDX7H+-#vbS>Q
zWsKb2+^5;iy_%gotlh<9c?WnxyO*c)5AaOx9{!r+&og<4S(bm8*EENCS$l*xbAos~
zH<;J+gLpeDkazNq@vc_DdpQxT%L!v`P9z($qu8twvO7=6{@f_`<;CEC`CRFuIiiW>
za9#q(vlEEWBoUDxM|e&O(fLV;auSebry<TuMwX=}DJz4d>@<{`OqBT=lv)iLx;!#9
zd1&+V$<N89FfWH<T`q=f1IFBZiu3eX^YxhX3$bYp*mKHoXo{)LGU3Rtz^OCi(c1B7
zt#~w5bm*$+%c`V5+re;79RqpwOz7&E)-^Jl-@t;Vi4)lkoXBeCjIM?Ac}<+oZsXIu
zE<Vrh;EVirzRqpuOHD7|<#h5x-T*)6_Hj|y&!xO!{?K~4s2k=|)+l~{1#7uRx0W08
z-{)riR&Lg8=Z>6h+^yMqW$(=2!ULM!EXm))lAOIfsM*bv`aL|QJILd?hj~&Hz_Ymr
zSf)M13;9QQNq3Cb^+CK@5WoseD66$0tSN|KjW(S1IgxD4i(+GLG@JA>Y|9t1BVWjV
zeGLAW3(-nBkS8HP7tb+W0s&e%L7D`F+C(A>5{S-CK$@3EtTqj4eku}e8u0}gr06n8
z)u~9&(~zF8B2$}>Mw?AuZUGvt9<9!RUT?&pFQ6#TK(VeEv#t=k-axI+j6+jKO@1-1
z0yEAWJ8rF&W?dz%c{VyUwRGlI(XY4Dqp8A|Q_onQlcBsu#&R2((Yu(_H#4JgGpBFj
zjK;(1{ANDZweewoI~TNVd|BY(Q(YI|>%DxX?cuxJK7Py}<d^(G{+;jRqIQs9^G5ki
zKZ2j1VIx-?ws50iBi9yg=hpm<++f(s-MU@eX57J@#=ZPmyOVphyLdpmmj?|8S*ktA
z(!xVLraQpXx&WTP43QtibGk#kl6RE98G?92dz_WpFjnP-@~$C_l?5TJ(u#OLU%=Wz
z0q+-z*sK$>Ll@0{ql7(18T$<}95N;lP!LaWo{Ye}1VW7|2(>8)^$7@!X-Eo_h%u;<
z=c!33%p$Q+MY3K^l0ik9A&)FWCK-kKWESL-Ys^8PuSZ{4NU^~{iJ^c}T`{HlQY?9e
zn6%~Cjm1|mstu*o6j*67UIsDaE-=%kuc6&&r_WHsfU%Mxy%V3Vmhpl*#&u0h6uOww
zIhoQnvQXH->3lbf1#O%&wDNIY7w7Xj_|(|TS9!gBk?-Z(`~kkz_3?fF0RJ)!@NdH)
zKNpU1vCzkFIv@Y1o4gFN9>1b3T&vy4pNcneOVLhl*Y3Vj%RNQgxl6l)dv*I+Qn;J@
zb$fWwxQE9Lhk4YvpC^q+c}DBc)4D?}D+=a0UC@<6UNr{uc2OvA>BCuR3}t0OB<~c2
zu~r|>rh+IoYQ=0aMzd8P$@U@{dkSRi)5UP0FadvKEJ4L_1Q-;AXcIYBlz>o|OjMB)
zp*EE$qZ)C6l32YGi8d2iaVCkn4AQh3(hX{qIt^LIJhJpTXp0OK6zV9{6;h}zL~qnn
zT4bQqXr$awf~C-m-B>|ov6U*liP{1yO*$(LT08B<m2?!;;nr5sQ&>r-(TPu6&tOp<
z!-Wn;idz`dH!-7YVXCl&*`j6^^=*8h?c`jchcgA;d|KSW1$_sf7kBfywui3`J^Y{@
z;`^dOek$_vZ=;W2ipKb(XoBC2<6J5lzYOv|SC?+##-c6UP`H`f^jo;qu$|kDd$?7<
zpZf~;@@K;y?kn-<!Lq$PVmQE3{Q;gVI?7W;{ybwi%nQYbc&;p%mkR@U)eyof`Y_%u
zJjUyWFy1Z|@J?YQtBa#pRU~44X(XHUQnr<e*=iKCy)=$Jg;I8w$vIdW&p|^h0maE2
zE=wk)NKTkBk#IvI0%H;prD{aR6huX-NJ_Ghm#RrNs7W;Bkf>LaQKloUFb`Ep9(hIs
zdBsL@jXDe^MHCepG3rYwDk;ZOR8B>i8B0+a)um-r8qL%fS5m7tQ(st3V_6kVr8T(A
zYG^BR&}XP(K<}i#)X9*(j*(&qBZhjW%9@xlG%#1z%uI0;^TjPJ7Ityg(9YR14<DBF
z@lkOPpBuXP+&I8@g?)To*vGf}A$}+u<VV987Y#%FRyNF~qG>J_&fs^oX(QK_Z|7R$
zcCIbi%njxp++4Pm+l#kzYuRq@E8foo<$HOk=l~Cv?Bh}60Uj|0@_5lf9xFe{Go{CP
zruZn&mxS_iX()d)h4X4r7;hOvSYe7}xhax0#SyG5iDF%`i1$lHY$%Ooi!p}HC33cv
z#Imnk#_l312g;JzZ%ib}m_$I4oPhFFf=U&Hl%*3@t{|pNjkqKYQMsD95*4vUStONY
zlVHpy$(WDQlt)Hs0h#7}a!q=2OA5#@E=F5aindr!Sy?$HrgBP6C0NVKu$!$^6`80j
zH&I(;rq*0VLx~-CX&oMO6>UW|w3%w@Dyhd?R!5Jyf&NklK9iH7A~zG|txOiTGgaEk
zqOq0JC2gE2Y2%#9!}(G#AC>oVzO<hUB?EkE9^%`wA-*ae;9KJ;-y41WT0YEAB}4q%
zILRNz5iXTnK3U~kxxRD<Hx}>W+VUOTRJMyd%saWeVn26P?BOoUF77uS<N@<u9<12U
zl9GcgEeqnYiU6K2ImUCvfh?;y%8Mm|yjT*<YsJAVw}i36e4OQ_k-SwdU{yslD@$Wo
zS0Z9#sfhPYQZ^RHu)Q>fZKX1HTcqr*h~<zaj)SEs1eBz5q%?`6#Yr45Pa&crg$T2X
z$cl7?WogJtvXPdnh^xpYzC=SpX)en0Y|_jHWSVkOmK2~WDI~X~h=MXB`K4uO%|;4K
ziz%{{Vk#-YW+}s5VZ&N#!e+ALD7Dd8W~0$kMXRY2x21-TvKrbgHFTD_=&EoqSkcTt
zNi(CSMn+5AjGG&oDfTdLX=A3egGEaRr^>rIUvU|vi*pqNoG<R-6LT-$6c6*IX_#-#
z!+cjU%nxOw{Hx5zuO*}WQ8CVcOk-R!&*JB2*~~STom^A4l|R{caJ^**w^r=r_VPX4
zZS&`D+a4aU9pFLhK_0LiVTsM3N6bffsw|MFD~|HCDVP`RfxK9LoR@83{LL!hjj~8y
zvxc*>Jdzbw5${w8SX~j#YD*OBOft4q$avox!>)2Ud#v$nx5?ROOX9FKo+GwY4wt2J
z%$i7mIf)>vg3yX|BFsue73qk}a}ZlJ#9FeEnDbEBbfj1{D9yR3%JRvu>Co5=WSjJ8
z?1ktoWf-l+=q)9b*h?ugm1D74sjyq9G+VKn?bKCNP;IkPQ(i+$Sv7961CQN-+w7#x
z<e<;ypxfqR$n0Xk-oTixjj{4Zrp+D9TDzDsw=rk&FlTAww7ruLOx=8F@8^73A0J<?
z!aTrd_CCI{jqrnYoNw*p{8To<#flLwR!s1_X_DW~GyK<j8N{>&Kl^sBvhCt}%YJUL
z?dNv;?*ETrI>^1Y{oGfvj|a^Mc*yF{V-*K^(t4CfECDR54CYx|ATL-#SXLRzOO*m%
zuL$SWip!@flD8}ZR#!&yPE|CkDq~n%6~)F18SAQI*=85BsUnU&=0tW{;y6%|h<{}g
zM=a?av?vI&q!C=DAlROcz@{Y9l15}j4ibwBNmUMUmTVI2Iua~e<du5TDs`k<^U18p
zM`JRgv6YZ-E<s;WjLuw6fxUt<b2&!4nUYE?W!4HR&1URo3pHj7)n+R$a}AAV2Q8I#
zG+G?ED=)uBymlAf3KzXq%?z0u7_&DrY-?hwqK#>bhpDO#=1rX}nEE(d(apKa9!{GF
zIB)6We3g%{>;rsl8s(d+0lu>g^HaqL-<hZRrD}$Y)+v59&GUzKhD)Yd{I0It#Z}gA
zTvM}~8>)A6Tjefpwd~;z%jI)*h<hsoxW{&cdo2f9Qgf6?tjBn`Hkik(!8}$O%5#=5
zUbIKB%qrvsdnhkeNAPmBkhd-2tgyxKmQBJ+TNJCSM69ccWn*nT>#F0}V2@*$C5|2T
zM7CQL_}3({*OJUZODg`BbPiQz5NK5qQLRR3&nBu`NrWXAVQnU{_Dtffxx`wtk=5u(
zs4gU>Qcp&u0aaxIS(U}8ZDnNH4Crf0FxFI1SZ$)zX2x7qj>%Sm#a4l}#)iGRib`uO
zj@l|5b_Y%NTHI9*+N?FSR5sFWchXx~kGHac-kMehYnvIjw=-GW$%M6)*%}Xv);3O9
zx;a(b!?`LiXDr=UAU>-0@_AK1pIZm`+V10f>loiw5A&majPGhD`L$}Ae_vkfJil8O
z`ETtMe%IRea-D5Af3ol9I{Q9uvmfLp+X3#f@8?eYLGG^d=K)6$4^#*7a9sco)`al5
zEriGI$9bkUh^MQM^L$+hf2|Ypl1;#il|uej9l_f*0^Y2avZ^wgm39g5+2UATD`P{I
zgbj7^Y^#i8SFMaKbqVaVC9}6KjlFdW0%|T}s0gf85nP>4s3VPtIt`Kb93rbTiK)#*
zX4ett$RW|DLtdvNsZNK|ZXlzkn6%m=GV6@w)*8?_OcdD5C~%act2I$rWux3-#bmc)
zv70g3ELd!IY8^E=s_JptYH6u<;;e0;sj``l>K1xz4RlsE&}nPMYj2{jrj;>U7h|;@
z%v5$VY42vXs)Lg?oy=EuamvxhX<HBH>iYS};pHP+KcCu0_{=fF*OkNkqk5WeY!m!Y
zJ;A>!C;8bn$wkK^mn!GDR5_2IpKC9d-*r{{xT$&%x7F?C#@a*NRke@XodMii6~u$i
zKpw0PWJy&357h<maD5Pu*M{)8Bba4XLY}D(<JlSkuT}|ptvZs|okITRis4OHH19Yi
z{M{MHN{5Vf^%6E!#k0O9o-I`}HrFfIS)0m^S_M0+lpJy-v#&<Q(Rw9EYSKCGR1;K_
zLs*@fa91u7&O9QWdB~gv$m?>DR2Ps`l}}Q&f%JMUs_Ig*s!CAR8pw1OlU-{jx2BBz
z>QV}v77R6Z%vE;G&I-&mRw`Vz*z2pPb2_PZ*5h<F&|Fi8yQ+@1x)$2&o%A@|bUPXu
zsB5Cf>Bj5oV$9LbWPLYd^_@)B_cHJ5WU<Q2X=fiNTwYGOdO73h=R&pbN-3YX#`w%N
z$+ylCzN(+#r>Yr#sGH;`#{xe)=eSfo#c$3N{Nb3x&#&<S*VZ54>e@YA?>Nl$HHWy_
zwVyj04{?|C2=~<mad&+%_tpfnq%n|3Tt|7_ag0amLwU9~oM&nTyx17VbM+!#s*T{q
z8ZocdiFmU%mgNo+D_vq%HHukNCu4n$j1A6M);A`wttOEj4XJE%B(kGEiJh)w_SUB3
zU!TrVS0;yDX@oRn5MG->NKF>ut~{a|bckHpi0g8Y)o4kq(UVwLNQ%Qis#8x&V=<|&
zVscz&a%#)StF0i<VL|IGqu6Q3SXV)LjU7|1opOgAYhyLG#v1IkPF&79>KkflX>6di
zu90R(GwqHBI_lc-)VJYvxEZSHWVq48V0{-ub-j!^Jd8K?GgaHq$=Y5P>%E+C4sqJ$
z<3htI7aB+T$T`NB&T+n}ndUpk6kpfR@<ZJ;KQ~Nr(K*X6HB<bjZjN6Y=J>z*IsC3^
z*~N7Zf39lu=SJrtZgm~z)`kFXcLs7#%VF+pImEq}OQ{d!q2?eSX$<Aj`VgLQMDT2r
zkSAObJl_(|GG_$OHAnE8OTsJ7F}&uIv7$bPcN*eZ?UJ#wDS@?)1lHHbv9=+B?T$n?
zHzu&7C54?%B?nw->}yP6f1?Wj<_v<HRUB(p5#EqTc%vGjD;J?72Wh<)aYF$TmyU#H
z1B#|Xk{pF7oy90!M%4Ais2j`BIL+iVmy=&_CcnXsuDOCDhXqqhHRhIDDjc;~9M#ww
z>ZopTP+RZ9)!c;3bs5J+tFr-ja}#b?3q1{PyiIKkHg?eO>R{N>!*EkK<BmS29bHU0
zyE)<Xak_DU(=A>;Y#icjy^l{_gPd<3;>+d{K5ZQ5`^Fi5Xqw>%$0R>D&+>Eq48J(%
zx!AJ6e;ZCf%PIW)nhtPX>jAEAJ;Zel`?#qgkXzkHxwSc%yPATy+jW!&oT1#;dW@yb
z;Vfwm=gDRPk2FQ_SW6_&H3@j}GKMpf=iE`e(jeva1_>(~qWOEHgw?H5*0?0R*OJUS
zcRcHz@oa8Yu)&$kwuZ|ug*}ZK>~m+b&#fZBtt6mHLr}AZWA0o+8!`!L$|lO0hoB{g
zsK!FXZX;q>5%I195?hVLH|tTh7)Wh3qjHs#;jSR3rGjjy9c_b+JeLK7s~UZi1+%k~
zipDC+8!NFk*J5?nQ`z94+U3I0;K0%1qNTYRcS{3Z?k2jM-E=uS=xp@R=kCPY*vUv!
z7b6Xwj5ZB0-qOoV^C0sLeOFM<HV<*Gb%Zl56I^H*<CB(QE;vW{hijVeTITr1J;M(z
z^L*d3$VK-8zcw#&(YeU)EsOlG@hpCRZT?*CIl@(K2f3l?2)8yJ=9acV?raO<w)SA|
zY&_0`twG$|8qAWmU>@{@@lbOZkG4ecL~}S#H%IeaYXr}=h<M%|#cOUcue+mptx3w8
zjdE6b;#uWR<Q;cBYnl_;(2~T4<|H<H(%ICM#<sRp_O&ZH;K^W*N5wvO1_#^K9Bt0z
zXnP)^O<IKRe4^Y1#I)xjaT|$gEJWUFK;kJO&QpTCxsdcWGbwFlWVM*d^jJ_eSD<UR
zqG`8d@KjLPR*A9Mim|N@lcxrAOAVEc^;CKqscEgJy46WTb0aQy6D>^*c-)P2wzkpP
z)`q90gTD4IdRjdUdb|v{`x$QSW};<)*(M)TZC)1IMp$U_vDiAy`Id1`w@-4RahfkY
z(|qZf;T!iP-!#tfUGp^Gwa@Wm>pcJV%<@a)DSmA}%^!`Y_`l{;_+8^Z!gZbdxS{PR
zH?;+FOIHxLbsgqb&oOT6JjVU*Fdk?L;m@4{9%v2Wp>`opbVc!~Cz7W;0-kLV^IWTx
z7doSOsa?eD9x<<ZVp#5pV|lxT<sHeq)u~`rOCsyta@M=k*w~rM=C*XUdNSDVNn=k(
z7JJ*$@$bmtaJz<}E){`YSp>J`6V#fApi_&$osXzJpQv^t;#Mu<_5xzt3Q6iHL(y4;
zqP+s8rwnzc8D)!&oYr!(J8bAW%^2EjXj^JAwpL<nucV~aiOpS4Ws3uQixXQ{6Lp>@
zoNgD5?M*n_T4`=+qP?>nkK04Hr<-24hrzB6Mm$}Nwf8dI+Q)QTFXL`6^DRCWyGA(a
z8Rlf$DCa$sobya^wq=U*Z8Ln*KF#Nz8NO|qzf#G!tuy?q<pjUBoa9pL2V83VfIr&K
z@PD1B@w=+~FjspHa(%}UZtMu+#;#y)@Eqr^o<Q#I4CK!4F#g;X%93^g53~t+uq~XW
zZV^k}(LB~AVp)fj7dvBlzC*$*opJolBV)NIo)w-%-s+5JWmgg_J#nn<N#$KnG8@~I
z*wA+QsoCaHv!y+q9qlT1^<=WQQ^mnH6@l(7g1WLe+NmL=LqlkLA)y`}0=JInHXSlg
zG18tAq-{kgI?N<{%1LosNON1s>MSR_$3|9r6<W8Ag7z8=Jv9_|+bHR*#MJ4+)LD(G
z&4In!Nu{TS+O9@i-Hp_AwNT&FMr(T$P3<1q+#R?(yXfxeq^qqDpSv4hTR)?oe#W~7
z81ETmymN>}&j_>Kqs+NS_@I4))7_Jt>zv`kwi&+gOz?5%4FBkv;fu}%zUrLi`|eqO
z={Uu&o(2BZaf07^KIHfI(_HGfe6qTZa!uD^ZtMu=n%)3z?K#37-GSWEdyG4Kk8@v#
zfV;W{Jk%A=1ASpE=@jr#r+}xsggo9O;pv`eUhIzIuibIH+#%x?ubh|r5_z*Dme;*W
zEborzoz7I=?MmX^?j+WFQh2{l$@|?YZ1twHwJVby-I?s^%4ScGhJ8J`9PP>{uqU5@
zZY^OQxrF!W5q4-1b`>M;Ek)E_L~LIfGEXUS9VH}rO{DZ$P<Tuzdrf5ZS;*?EK-X&}
zx3?B!UoHB+I*NK+6nD8O?sa1Cs>j}YxsH0OdR)|c+Gyx%qN%qTS62tEeO-7w?Rffn
z>GpW(>g{3B+l{xY4_{v|<K7`Adxx0s_A%Wx$YReJa~>Zbct$zXH_7?FF+T2^<>Sr?
zzUZCei^~vw3w+bPz|WpJe)4|6k6mZ@PxmQ)?>x!Hp0nURkKa}O{#-o}z>R%@+}IPq
zEq%e<(H+EH-67o86UKer$GNXFjC*@UJkTA+Bi-RV)-T|xP6>~7$MS5qlxO>-ywoG*
zmCjgR>z4Coe>`t@CGmP!BJT{O@^-g^Ro$tq>rZ8Er;_&vlx*^5vZYte&aMphbY`)q
zQ^lU{90I!Y@$b_S=+zV2Q%HDUJ|UfjME2{5@EQ?&3yJ9|A-=a1S+|+Q?lO{ltR(i7
zliq6~t-p$l9y7VUHR!xH@_Q@E@2*1IUyq@;nxdXYOr6bGy$;NsE-HK6R|={1dZ_Pi
zr(vLjhVCxfd%9`&w$a|xMMqC3{r$ZR_4hE?+s}~Khp*Smly`)=zA<Kc2RS(~!Uw%$
zobpa^+B?aafoVSJndf}pB%gOq^G)|6-*{*Fwriemy{Gx5`y4;^oZ??yA9AVp1ODha
z!=-_<_+8Z#$W`8BTr(8NO+&}IzVA3U`NFw#D408aq5Qcgf<ODh_=_)!hrL1`84&SU
zuaKt(VtIB*#503pp6`q0d2bvq_+oiuD2X?G3jWqB=dHeYmU~lqw^zx#UInXrl&tls
z*mAjyo@{mvD%sJaVQ)_^{@#4{_2jXyKc6E58UlLr2^lhQd{9qFuYsuEBEtJhkoJ`k
zb9sj<kPMiJ_mz-1P)>^1PKwWjs^5m%TaCtRCC^udzNa3ouLk2#10{Vf%s$7JwfP#T
z>UC1p-$<RWnOd(KSD%}DUk9#%4qAsgaSwXw8tA~=+eMGB7jI8LgFRlx2L~AMA7k_~
zM*lD~gQLt3j&pKojK#i5&iE$zXmFl$zFEE)n&I=IIldX1=lg+qzVBV&+o4nZFmQ&S
zedoA1@BtSG&hmTj8Gax97{6=0hq-n*i0cNAapOoBH~Efp`(P-y3=6q!P{@75k=)fU
z;NGEdmiCER+8@KiLlPbxl<=5W%9CC(&w68d&X>R|{W4x3PU1CRGH(saS>aW%(wol8
z{uJIBN@KM*lTAJ)8wa!5(3i<}Zw6a^dF=CP*yGLO;E;wxzI+b%X*tqgz_F1+f(La(
z4C;v*&=ct^LfB^})?0?eXC`*ULPEcl)PV|8hwP;Js!8j!qa3=7QA5sPE!x2<bVD^5
z`dt(aG*UcRPw8MiHlLfyffj57P1JassrR<y7;L9;xSOWoZal+Xw0nE#8S>&C>Y}^9
zpFVFdLw&=H`^K0Y9A$E3l-Xe)v%X0dydx}*OmTW}f|Gqyd^|A2r@k4^_n+d^zD54w
zUF3_wll;SbmVf#_;K#lX`FY?1KYK6m%kU@s&-)3#_kV`p)dRs?H5$aVqaoZh7|N~V
z!QAKz<IZsbw+%*e??@C6j0(ALOu&+1DNDzqd16Sy)1%QmJ{r#xqX{e<kLRyra$Xr!
z@aj-Jua3)EKAy(g11YQ+Q?O<zot2|%R*hxw{%{)W2D8{akj<`PH9H2>>>SC)e<Yj3
zBf0pG7vevnC1^y;(E$Syqeg_jQUv4WL=2gcj8z~VFGey}M#5kjvH>$m118c2D@Ylu
zCT-k~X1Ipj@mli6s?ZKO(fR7pk2Inma9|p8Q99g+eV~o1fktct9aIguagDffjJMM;
z+KFqtgQkIQJVQOWeFO9i^f53pMBmT=gX2C%MtzKq4KX$1V`g-k*@0>1N2fS3JkE)M
zY0eKUa(3VZ7e;6KXmE~CM(6orY>}@<7Wr=E1HKtO$B!fD`El?pKl{$`@4=7xb>KYz
z^L>h+-$(#gPafl%u?TJ$3FfwuW8C38&dtN2+&(7YuE}uj^+odFkdP&#5|&QNcw$`6
zBa?AFJrvKfi8!7aPh#0v0xyoF@TxC`m&a21+gLhpO(gM_FO}63D%OmuSTmf)+R-dF
z59hLZD2pBAIqV$HVed#D{u6o*4(GCOsF1^B1q6&2a%`-CV`D}_M$3sBGZ8*gOyqDe
z(GynWBX$zUEW}NiQH)zj^jT4l)so?}kvUXL-lUWK$vSd}YtRkXQRr)+aHJ9ASSw`{
z&6s>{tiE>azAmcAJE$M)z%|rH{bU!;Q7>&Hy|j<_&^gje&-gGszF`K3M;P#pF+McP
z*vKd|<0DLt&agN<!~Endr-o)ZJu%Js;YH4mF7SzOo=-*>`C|MupO2p7i^-FGHF1V-
zhtBie$jAKX`;h<mKIT8;7x;bbWBzaGGyJZaJj!*WAzVLmj2p*={AotO9n%rqJ{rz#
z(*o|C5b(fABul1Zd3ajPL*o*j9GCL+sFbJ2;(2C5#`B}`yf~S}3nOw~97|^Tn1a_Q
zlUX^F%3EWp{Cz~l%E>g|ol^4NbPij_GTAno#jdejwoT@+drHgxsY3RS88|p*;P7M-
zfs;m#juaC#TE?-Na>B;VL`|58nYI!=YDGM4Lq1_4eyW1_87s=s8k7?bR1;3Jrt8R_
zaFR1ohjz?G-h>P7NF$|F%@mC_Q!>?zb*z=D$rfs+x~ZM+rf$kZ{a7!K(O%p$12m2G
z&^q0Zd%U0S>A@?7^iPe@KQhkv*d!w(Q;dzwFf%^R<irefqqEFSEwDH?!|ACLoEiIo
z^W&%acx;}Jrx*Eh;v8R%oZ+jfvwS;on(s$H;+N^O{Cn&Izt4QaZ!@2AY3c%g*UkrX
z)qDuoP73(bd?YtdhjP<g6nBkBardN<duJlKe=3^4%*FDT83{}0V_7;O;nDFp9-Bz!
zsR=pHOe%PBT+R#QDZDh9%<|b3UY}61d_0rC&t$M_KAlw)S*)MUWc`eaO_MonoXBO@
zd=9&3wCtVNvvWevo=F3T$BPJ>F%UdaMDR=zq0>f=k5>>eUPkn636fbG(UTR#OqxiT
zt3oknMKM)P;-n4rOf^~aHE3pBWKX)#&N|7TaG;%N#yH-9exeEUR0}0@?O0~ps2p#@
zHq$}XR44V*9XQ5&XqoH8J=;&y!~mVsgLvi#>6q`wJMLp(dX#~QF$QKP7?~VrYI2h4
zscGhBCt0|>b90=TTHwRkIWA0`;G?M%d^)$tr}Jm{$LvYIpFG14<LCKt?kqn}o#W#C
zC;UA7DVOFy<M;WmxHR(_etvVu@S6$e#@XZiX*P=Mrv=<LDY{a}-Ln$zn2hHBIVtzg
zMsxpyj0b0=EM1J}u_-xEEynZL`D9+4OW}pNRGynj=H=;RUS3r5)<P!Br&PQ>m%*BO
z4J#LOSwEA_#>H&5Ol7lmM$3+w9JVcJ*)x^L{>dWzXY~Xu7&tm#MBrjM0ShGrPnIE^
zF(H^LBYMVybk;`9jER^98<I&YaSOGi%+`=R>p(s2LN(by=3*n7DJS{!4HV2aP%!1f
zFxg7cWGiKpO_a`eP%+toZMKWbnNBJfdZ?M{pnjo?#sx183%#^W_t7!eN88L0z0(8q
zO${+LH^#`!2)>0W#wMqknVn>IZjSkdd1fzzOr7H7;v65$pXS5q1<uZ%<MY|md^LZD
zuV>Hl&D43mnLNi&lOOW);)nb?{{_EJU*O{6r(Bx*oZlC}!Ow42fZwSwu018<rjsIW
zJ`v8%^J4B^kZ}8A4EM~*xch{Jdr!%^e<qeCi}5@$FK6k=IG$ci;IFeOJa<yTvnQ0i
za!SD~C(?LzK83eVDS7i`I&aTqvF1b$?=IxBZdT2jSuN`pve`D1&$c-&yXN!RJEvv$
zoQ^#+diKo}61Y&zp_x*SovI*Y!Nl<sWkfDi5HV*#IA<nyrV7ct4asaRvXgdFPu7rn
z!iDmL6XlEp^=uQlr|QX@ZAClZMBa%8v<q&EPPS7r*Fx!>hw_CsDo<U;@KQJ1PwlC0
zYUX-zEe_y5)lbXZ0PQCR@GK6~J3ma{><GOlrx`ps%Fz5cL#Jk#n3-pOZl1+cbIhHb
z<<!Xq&Yqa()Z!`5%$(xGxexew;X^+Ae;w5MTh#^H$8jp#x5;VR8=D%ZvZiGo%W0-*
zuW6g=$!gksTCJwh)Z9f8L~ub-KtK^e6c9uf1wlX%!39AC&c2`XJ^Q}z2Yf%5{_wu;
zKj3wJ?lBFv5fx^M2D?~?TV%pFZYDaaBP!Mt5*wHho0yQANlTObOqzT?Q^tSd8u<dQ
zADzdIWApfpYzenWmvP6~QtlKj=U(Y@rioW@@8}vH7)@uoD1%2w*Yc=%9W!JZJRx7h
z6QV3;%GWbXoXy{*oA|ppm*>ZFcu}0gE8=`!lIQc*_-5Xf7x13EfcM3P{7anAr=z8O
zDB8)trA2%uE@F<Pl<&nm`C+_*x$;Wp%BuK}tdfP}6)YIr&oAS9Su$S5it&0@jn=bL
zbcjsRA#%nV$d%WVD{f$eq=jwc&1@AlQ8eC4vGgc~vUbWxJ1G-&Qz<)2)#!2d%6h1m
z_fakCq)FPtL1_;y;?p!s`{*1yNw@ekow74@%g!($Im2nmSq8^1aCUr%bJAf(Mu!=a
zjU$qYk;-I9#0nH*8S-%n`Y{>WQ3X1w2CH0wTdK!9s>UtR5R~f(%gqF(Mna<klVeU2
zV-C`;P|fEm*?g{1{LJ;DU${xRkekJenJQYwRQW=tN>_51_*d?htzw#THTTO_F<rHs
z2b61gRJDf3<rzGzSi|G89G;f1XQncjS>km(ugKw9aURc$xA2lEpVw6RysF&J>&nf%
zso2K5lI@q9Eh^yO;$l9L?Bq+uZa!1);w$AIzLoFd2gOdlRqW*_@opBV%2^=Z$6{3#
z3skkNkk+z7)<A~%(mEPQR~}%kxS4FxK{iWU*eGcrPkET_@)n9jZ4}FnvQvDFo$@xy
z6&+NFI@zl{My2uu`;^_(NPB4%^;0iDNsIU_t@1N;icZol9->D%OsDD`1CsL$$cGq^
zo@Y>XfwSUqMpPn(Bo~l~$C1b-$ixcNN*QXA8bPALD3YUBs<244SQP>`kqM{RfJdw+
zqA=o@2_#ew;!-n7g_X1^ss*IU7ICd&AvdUh;TqXuu2(JQHq{DlS1spG$ztx2Ea6`D
zYVK7n<K9asn$<ic$>NW)wM>_-;Ze<co>Hu3rX+_a<=M=X<T6XWnP(+=yr9_3OY%J4
zP;KEgO#!cKig;I5#9PvQK9Cjip{9tBq&xXgUd9))628(@@TIDPujQ3|BQ57Yl6{vK
zGG9`|LTNP%Rdp;?*0Drg%Sv?v%j9*ekTsDdZ6H&5m@H{C*@{LsOPa`2w6k5+%r?nU
zN~B#BN;)W0bWtJgVxROlmGWLHrN^n3_0XU>Nu%Tx4bnbZlxH|98RW2{pAPjP#}#Kd
zrWvG9aqe<wrDF`p&NCt(Wke-KBpc^~Qp%WAf<!7tA(5e0sWGTD2y!LDB?zT}Q>Div
z*WtKyl_mm86ETg0gwjk><|HL^k(Q=gM4DzESL=S|I_(l})Gp*E-LKrLSj^4p72Ksw
z=Xctb+@n~=-O3E^Rb=veO(qYh*D_t5$>XXlW~kQlq&A0{ifsO(%H^-}9G=nS@(<M(
zp3`sS1$hClD++j3UdU_u9lWbA<V|f6?<jWgzG4TnwI$3}?&32=33C(`e5KmW*NO_h
z(d_11WhFl-_VBZQFaOc)Ws$a)1?qz=(bTb2-blKpfed8}>56)?H3!L2G_YCI$R<TI
z+w`q$)^$>#Jw~avol<QVrK)Z!<=s@OJK3W?&H;HpHR_YpD|@Mv_fxMu%VEVC+T??@
zDo@j;J<D<Zd5&pD=+O>wS~1K?orodb1qQVj7*a?XRY(}uDv;~tNOW?fY6S|l4uf2c
zPN~GCRb$bbuxs@=^cGwSBVM^cSYyF2cM;RuN$9;y=p3Y7rT>+yl#97uKcA~rOSnP*
zD>tcDa-(56x2TsgRlkCJbZfXzm%%-Tl}uA*FioGuG))$N(q{0Ob}fI_Z{$(!MxIoy
z=NWAte^GAaIZZCl8uIwNs(_cY+jvox&r9keUR4(Iwt5?H=?nP4P{M5OZa&r&^P#$w
zPYmUJrLJI(ZZBUN_A^&m#kWEYbCrAfQCG(=s%jPq2U)7DXNj_r<(fKHYU^38uV<~Q
ziEMQfIoc-jgl2M7&1})OlV@n7K;2D=ww+?laY}W^DA#sUq3WVS*GG-Mk2?JcYW028
zYWr!_ouNh5e;K1gKS-DA99_a7y@oMPXh-PR40BQ?<&1EF(}poFC}mtQNEy}1kQo%H
z^a^Bx9GymiPNPRB=n!-oOiB|Doe8(WibJpyG&l&UZG@Co5?VV^y`7XQK-v`JJgzb?
z;#%D=Tx0r`>-8(SS+|nk>X&kxeht49R&u*BgS$;@xl6l_Y1(y6*Q{f@A)D#uT>fZW
z&kVx`W|%heXVV5|YI1qTkk2!^Z9H$-#Pfy%UKV!nigp_>>kD~Xx1Bdk#k^-M<$YZl
z9~n#dKq%!S&2Huxb~8uV%jd>@{GYa(AI#PKXsG5V?S6hV*RasIpLwPl7HDf(Bs8#0
z-@r=qK~@`@$<!PsTXUH8#>1>PwUK9PW0S6fE!s|s4eb;Ny%Y+)lxw@G&~;Iv?V&<5
zz<&Kn>UDio>-woT4A7(>piy^<BZku)F$~da8sWJ19Nqd0^lL`w(}_8)7cnHrId2$e
zM6Y64qh!RWK&+J^F{@CU4X6z&v_>@stq!AEK+p(SbOKhr1Gm;h&}1WIa1k@Rh?#7p
zOdjGICuvve7jdQjSFSTIWQu+T*IHL{t7!!{nU`~$A%olXtC=dKbEj?<_Zl;J(2~tV
z<{Tb2ZQzflbv$C-z>}t2o-l6a3H?_7N4JUpF>K-){bv4V%;RNUAukw;c*V4he;SK;
zTep*c>UZ#_zKD0NyZP8$%52?kKGIk4rFAc#n#=i8*vGe~O1?8z^PRPZd8S(at2@Aa
z;Sh_h4VPE4Sg0r6e3)fIGiwY-$Tl~VB{Y+1X=Q`CldXnUHd<TBHy>rYzLOn>6O@@c
zDKi|W%-m18;W$;+J`Na8P;DKg)_j&)^AOFt^R(*E(IyPhE{xG8oV)z8jvGhl5yYG{
zNjPN?aoQ;5yiv)hpkhp?WL!`pF>4VS)F^Zs^cF2zqkustU@_}4=}oxx4jfh^9*dcP
z-a|le;5T}S3vQx9fTYe%+7!zorr4Kry=^hqSQm4HZ7DYk>HOBXhFeVO++oV#c1s3#
z3Ryg0%VwG-i{INb`GbAqWsJuy8+lS#&ttY69=GQ5lzj_NJGL{^v6)%I4qh<j^RjIl
zFFFc&$yCZ)#uDDL6!D%=!oRG0m~Gq1hmO5`W-a4$(>}g1Rx(GZ;%n1><{ImmYp!Fi
z@gV;-*R#;tzyfnEOO4H}5Du}_)WRA|1L?LFGK6+=E}>Z4*<e3Lp1F-p<~H)}o#YF>
z6q$S3W$L8d)=jCckG+l)>=pXi@93k(e41Keh<fW88qMcvvY(;VJVL8*fp)8i4)ZYG
zb`i%dqYPMNoDsyFwW=7js~NIM7`Can;LtPfP$RKxPzV~7W(_)v1&v_BY_?(&EI6%B
zTvjV?s|SzCf#2aKW^)iX`-xj!qy#r<Y3`+5;l2d2imTnLxYoIv8yze8jWwOy9c#JG
zy^cH08Qf*g;=W5+vw6sx#e>#$JmSb@hBb#LoOwKL+saJyHlA{9VWxd6&$tTtyJI_l
zvuxu9XAy6>OL@&*%<Gmi-gNKgJ!b{8FE3;_vz>eR$g-D@E&KV>UBl=01AOJ!$2Ybr
zzPHu!le?B*oQGIwIlv;zK^B+~v((wl3VRdjmPS^akCJI=yIiiLooq`hn_Qi2v>zwW
z*1--(AEk~yb~*bfcJ#2v)yqC}KUMBN4%kmoWj)0q%P{rU5e_-e(O?^;**1I`rOP_Z
zF{hYg7AYs)B2L=HoHdI$;}mn=rr^9y&5&Epm{Y;HT|i>jBDI>4+sp_q9U7Mvi`{|I
zV!~o|;;~!snccV@9s(8*F}I(P)5D}S0QLxJX|82l?ODo|-gK_AF6S28N^Z5LGu6GC
z+db*r=FZ|C&uZ?oWpkHv0}ohp_@jLt4?44X#FfVk&t@KRZ{*L;e4e!CG0VG!=Ujz6
z?=9e2Yd+7pN_gH~$V-kg-msPMwyTUcJbQTGzKi#)dw9>imrvZ~%y#YPW7{77ZQsY|
z)>^)`*71#_j=8pKezMjv&vS_X+77Y6-NI69Gs~S#tg<$d?rvg*`zUMd?PNQ;$aQs-
zXYFL8w}X6l7kRdBioM+wy1FTJ_OjF2OR47!WzIqNcu!JkA7a1f6!qQ_Y8_{3bdJ(u
z9iq)PPN!2$heJY-Ym82(oNlX#UayjqRyBi8IfEVzgH8>j4jm(24RVJ8l~<3%YeeN1
z5FBQVRy%sD1HtOV?X}>xT5;JOm-D$jMD2bOUO$tbFmbz|v@6_;xjL|lE8NSN5?IN#
zo|W9>Tfr^<)!gF9<POIg?)GMKk8=a}I5T<Bw~1-~Z2siP<xh?+Jm%ZN<NnP&>fXu|
zo;;p)7ckSejhW8v{MA{+KRl(p<SpX0z)oIsmGf$#lsEmm_`p}jJHFk#@2liPe>ER_
z_VKCn0CQY5eB-QRj=O>H19kl1t>H&UBlA7Y{2XXzexQ*Bo<l71HnGgp#u|SIs{);5
zJC2g=?k3Z7jJ!Yx8~mMYaUUb!cY=I(AKSgX?DF-q)78gr#~>BXQ|$K-u-84z0smR5
zJww#H#yIF0rNuEqvvY(a{&Bh-qx5)WbUCFA1Vr?E6!bY|3_0Ws2jmQU^b9-IjC!?5
zJX(|vE$V;)x!;7|ZNm_-V|BW5IBZw~UR(h$e!r7|-;3YrCG7E$@<f^Ng-Ch*q@{UR
zafN3&SGremy=w*6c-L~XH-npltGUg;j^6}xx!b#zdtBK}3vA#I{v00iZRAg`4LsuA
z%5={*9`@$(*d+w-R%V3?dCs?kzxlTFLTDHN@b2Pe*Dl@&6!S`OCvOHydB<CM8RB2T
zeSF}m;#1FlW_xP+)Lq5r{#w599pvj^E#LVLGS^ef&+caC`RiE}ILv%sBa3}a{OUQ%
zl29vaLhYox+gTmzVy&l*tiW+{yeHTc=w_3@i@d-9`QB3$dip7H_fhKYXQ#KHs=#Tg
zUFWEBo#TN2Jaxe#8oeVN3SOWkI6{keoYs(pW5F>xgHn0|3VOV9dO{ioeOiV>Du#nP
zE`)T9dDTe#8piwril7x$(2m+~Lg_K0b2$)P7VJSgj*uHiz=zN4#O3i333!PGq9k2m
zCVXM=B}q#QFXPI<Dy|H#<a+-KZj5AbT_l6wdb9YAe;s%Dv-w>(hr4{a+#ky2!N7VR
zjOH;txRHm$TbU8s&J(_T9`hIQRB$^_hf8=mSir16G0#Sec`jJYOM!A;@RsvRXb-PO
z_wcTN4{rr3_%Kw>?9e_w@>lV3ppH+1HGJW#<{MuvUq>7GD%`+a??L|SKgf^4BP{f`
zvLxEVvd|HhdfQm#Yh#VKm6hIBvVzB18|)y{e~g?+4_l*sZ1eU~;O(W@H^7cyA0^SV
zltxdp$2UY(_#EYtvm6MX<v?_ln$ReXfeX|JM`;X+Xbz8Z#5YE}S4w+WMQ>EjfLB9*
zK*PzXk~1M4gI)upAw9zp6JnncncsxSXFwLUp$=Hk1e_QnHUzH?OUQvW;Kd&C;1Br-
z1w!~QttA*E5(<&<B}s*2q^0@ONsBJ$`rulw3$5ms_-byAt>>obC6KjDjc0Rvcs+N-
za=0h9p8LXEFN0hzRKVl$0v-u&<?(nCPlrmF8Q;cVVkOLq7xP@WjK2j-_(!mW*ZjMA
zIaJ0!!+ZEwxPrH%`<Wft$NT;Rd>p9alkh%12~{&Ea*)qsHOvVe<on1WevCCUFL;EX
zqK*6~)X0)h3yT7+Ec17;IMl_e&@nRNU99tWks0Y?L!_IHp-wgiyV)8zL4N!Mg@Haw
zqXQI2&QcOP#h&On$^t`_ht5zF9Hc5Z#KGt|O@Uz=A|hI%W3<O59Puk?_bce~%QzlZ
zb26adR7Azeh>n4Xf%7pvqag!hVLg(F1zEt3BIrOBvZ09BQHGruV_qy#7pABeXT*yu
z7Qhwq;0yXLLxchmVv!)xa0H?W(xyb$a7A)8Q=;iyoyz8hR0cOh)^l4jn_Hsm`E4qT
z--WZeKbpr~@eSM?+06Zsd>#trF(aJEqoFN4882W)qJXF4rOZkdF*8-l%y1F2LM6Ny
zFXh!p881dFc_p@+w<EiGH&)48(Q4jJ*6@C+hJPmy@M)}$&!Y$VD%8N7@BzM!9^~uf
zA-+o<;ivE+evBSrQLKqy63zS)>R@rSjm60}R;G@U5$Pp6)<IUXla0xf<Rtpp8XaJB
zw4Z|b3AUvMC=Cs=GkJ!R@L6`nhAB&)qbf4U{?G{ZsWIx}V;oA2)07;iH6f)XBBM1b
zp(~=IJ)z=6O3ulYih-z-(_uYBNeyS>MlOW3j3h0HLq=p#0cpyFEMY;P^q`M9(8p|8
zBOXk#0PchzYt)S=9L5!j5e|ik#)5<{EhH5to=B0F7GK4bWCmBq)44X0#dV1cZcSx!
zQ*u316YIDwk;l~N2JV~K%-xYK+#k#156L_pp4`lgQ~{4gwq5SYi4vYj6)`JT#xtp%
zJfAG*uki|Ai0|T+R2i=)D|vacoL48RcqdlH`^jqFiPiAG$$fmBtmE^^dOnWT@maEg
zZ=;9!F4e?$i3Yw)9AWN68}noB%ulwkIC_|csiQ279c5XhlQq#E)}%Vfoa`ny-b-fc
zB<tgSY)JKx7we-S(NAIYG)1w~>_`q#J~_<p#0Zt~Q7Yo+s7#Df6}>=ha)ic|jK-9h
zrlf@Cq=dGVjMkKtV{r|=2|axY4ZU%JQ<GW-k_OI242;GF&PPp`QO1%cR0$i(m<4&n
zi!kZLm<S+5y;zb#tg$ejR0MC*hd&x1Fc~HmPY|BG1QRDQF-cllB7-Yg%e9FNu4NrJ
zB{y(OJcpYnvzVINz#Z`|+?m|K-SLh5KE9dzQro$IqL68+BBoQ!^h5zqP{LD_J9+A2
zA<s+{Gjp<-zfN4j*v;Q2%6aADUS7Re!JF}F{yDjiH{yGF_hJ?AC9C)_RmVrv@JYOZ
zFE7^fIZb>q(a84`jm%9o^20<kKhwm#$qp7JkFqFnj74;?B+<c&i^oY%_K-2r%i4Gk
znaO@KIYD;v1X~k*Y~eJU<7e3sA7b0YY05ZFY3e)yhyZv0yDkn=9v@=wMG;jK<LtjE
z;SggqC8RXR<s7-F;AmV%M@mLVQce#VdQu9y(J+wGayD*cC?PO1Y2`w~#%RLG=%gKa
z!htI3L6fkeop7VZh3TRjLp*?y0A@niCIUDo;&|h6qVXj0c!XFgM*QL=Ovd?tw|;yA
T=2J6)00000NkvXXu0mjf9yvT#

literal 0
HcmV?d00001

diff --git a/core/artwork/thumbhash/testdata/thumbhash.js b/core/artwork/thumbhash/testdata/thumbhash.js
new file mode 100644
index 000000000..369b118ec
--- /dev/null
+++ b/core/artwork/thumbhash/testdata/thumbhash.js
@@ -0,0 +1,288 @@
+/**
+ * Encodes an RGBA image to a ThumbHash. RGB should not be premultiplied by A.
+ *
+ * @param w The width of the input image. Must be ≤100px.
+ * @param h The height of the input image. Must be ≤100px.
+ * @param rgba The pixels in the input image, row-by-row. Must have w*h*4 elements.
+ * @returns The ThumbHash as a Uint8Array.
+ */
+export function rgbaToThumbHash(w, h, rgba) {
+  // Encoding an image larger than 100x100 is slow with no benefit
+  if (w > 100 || h > 100) throw new Error(`${w}x${h} doesn't fit in 100x100`)
+  let { PI, round, max, cos, abs } = Math
+
+  // Determine the average color
+  let avg_r = 0, avg_g = 0, avg_b = 0, avg_a = 0
+  for (let i = 0, j = 0; i < w * h; i++, j += 4) {
+    let alpha = rgba[j + 3] / 255
+    avg_r += alpha / 255 * rgba[j]
+    avg_g += alpha / 255 * rgba[j + 1]
+    avg_b += alpha / 255 * rgba[j + 2]
+    avg_a += alpha
+  }
+  if (avg_a) {
+    avg_r /= avg_a
+    avg_g /= avg_a
+    avg_b /= avg_a
+  }
+
+  let hasAlpha = avg_a < w * h
+  let l_limit = hasAlpha ? 5 : 7 // Use fewer luminance bits if there's alpha
+  let lx = max(1, round(l_limit * w / max(w, h)))
+  let ly = max(1, round(l_limit * h / max(w, h)))
+  let l = [] // luminance
+  let p = [] // yellow - blue
+  let q = [] // red - green
+  let a = [] // alpha
+
+  // Convert the image from RGBA to LPQA (composite atop the average color)
+  for (let i = 0, j = 0; i < w * h; i++, j += 4) {
+    let alpha = rgba[j + 3] / 255
+    let r = avg_r * (1 - alpha) + alpha / 255 * rgba[j]
+    let g = avg_g * (1 - alpha) + alpha / 255 * rgba[j + 1]
+    let b = avg_b * (1 - alpha) + alpha / 255 * rgba[j + 2]
+    l[i] = (r + g + b) / 3
+    p[i] = (r + g) / 2 - b
+    q[i] = r - g
+    a[i] = alpha
+  }
+
+  // Encode using the DCT into DC (constant) and normalized AC (varying) terms
+  let encodeChannel = (channel, nx, ny) => {
+    let dc = 0, ac = [], scale = 0, fx = []
+    for (let cy = 0; cy < ny; cy++) {
+      for (let cx = 0; cx * ny < nx * (ny - cy); cx++) {
+        let f = 0
+        for (let x = 0; x < w; x++)
+          fx[x] = cos(PI / w * cx * (x + 0.5))
+        for (let y = 0; y < h; y++)
+          for (let x = 0, fy = cos(PI / h * cy * (y + 0.5)); x < w; x++)
+            f += channel[x + y * w] * fx[x] * fy
+        f /= w * h
+        if (cx || cy) {
+          ac.push(f)
+          scale = max(scale, abs(f))
+        } else {
+          dc = f
+        }
+      }
+    }
+    if (scale)
+      for (let i = 0; i < ac.length; i++)
+        ac[i] = 0.5 + 0.5 / scale * ac[i]
+    return [dc, ac, scale]
+  }
+  let [l_dc, l_ac, l_scale] = encodeChannel(l, max(3, lx), max(3, ly))
+  let [p_dc, p_ac, p_scale] = encodeChannel(p, 3, 3)
+  let [q_dc, q_ac, q_scale] = encodeChannel(q, 3, 3)
+  let [a_dc, a_ac, a_scale] = hasAlpha ? encodeChannel(a, 5, 5) : []
+
+  // Write the constants
+  let isLandscape = w > h
+  let header24 = round(63 * l_dc) | (round(31.5 + 31.5 * p_dc) << 6) | (round(31.5 + 31.5 * q_dc) << 12) | (round(31 * l_scale) << 18) | (hasAlpha << 23)
+  let header16 = (isLandscape ? ly : lx) | (round(63 * p_scale) << 3) | (round(63 * q_scale) << 9) | (isLandscape << 15)
+  let hash = [header24 & 255, (header24 >> 8) & 255, header24 >> 16, header16 & 255, header16 >> 8]
+  let ac_start = hasAlpha ? 6 : 5
+  let ac_index = 0
+  if (hasAlpha) hash.push(round(15 * a_dc) | (round(15 * a_scale) << 4))
+
+  // Write the varying factors
+  for (let ac of hasAlpha ? [l_ac, p_ac, q_ac, a_ac] : [l_ac, p_ac, q_ac])
+    for (let f of ac)
+      hash[ac_start + (ac_index >> 1)] |= round(15 * f) << ((ac_index++ & 1) << 2)
+  return new Uint8Array(hash)
+}
+
+/**
+ * Decodes a ThumbHash to an RGBA image. RGB is not be premultiplied by A.
+ *
+ * @param hash The bytes of the ThumbHash.
+ * @returns The width, height, and pixels of the rendered placeholder image.
+ */
+export function thumbHashToRGBA(hash) {
+  let { PI, min, max, cos, round } = Math
+
+  // Read the constants
+  let header24 = hash[0] | (hash[1] << 8) | (hash[2] << 16)
+  let header16 = hash[3] | (hash[4] << 8)
+  let l_dc = (header24 & 63) / 63
+  let p_dc = ((header24 >> 6) & 63) / 31.5 - 1
+  let q_dc = ((header24 >> 12) & 63) / 31.5 - 1
+  let l_scale = ((header24 >> 18) & 31) / 31
+  let hasAlpha = header24 >> 23
+  let p_scale = ((header16 >> 3) & 63) / 63
+  let q_scale = ((header16 >> 9) & 63) / 63
+  let isLandscape = header16 >> 15
+  let lx = max(3, isLandscape ? hasAlpha ? 5 : 7 : header16 & 7)
+  let ly = max(3, isLandscape ? header16 & 7 : hasAlpha ? 5 : 7)
+  let a_dc = hasAlpha ? (hash[5] & 15) / 15 : 1
+  let a_scale = (hash[5] >> 4) / 15
+
+  // Read the varying factors (boost saturation by 1.25x to compensate for quantization)
+  let ac_start = hasAlpha ? 6 : 5
+  let ac_index = 0
+  let decodeChannel = (nx, ny, scale) => {
+    let ac = []
+    for (let cy = 0; cy < ny; cy++)
+      for (let cx = cy ? 0 : 1; cx * ny < nx * (ny - cy); cx++)
+        ac.push((((hash[ac_start + (ac_index >> 1)] >> ((ac_index++ & 1) << 2)) & 15) / 7.5 - 1) * scale)
+    return ac
+  }
+  let l_ac = decodeChannel(lx, ly, l_scale)
+  let p_ac = decodeChannel(3, 3, p_scale * 1.25)
+  let q_ac = decodeChannel(3, 3, q_scale * 1.25)
+  let a_ac = hasAlpha && decodeChannel(5, 5, a_scale)
+
+  // Decode using the DCT into RGB
+  let ratio = thumbHashToApproximateAspectRatio(hash)
+  let w = round(ratio > 1 ? 32 : 32 * ratio)
+  let h = round(ratio > 1 ? 32 / ratio : 32)
+  let rgba = new Uint8Array(w * h * 4), fx = [], fy = []
+  for (let y = 0, i = 0; y < h; y++) {
+    for (let x = 0; x < w; x++, i += 4) {
+      let l = l_dc, p = p_dc, q = q_dc, a = a_dc
+
+      // Precompute the coefficients
+      for (let cx = 0, n = max(lx, hasAlpha ? 5 : 3); cx < n; cx++)
+        fx[cx] = cos(PI / w * (x + 0.5) * cx)
+      for (let cy = 0, n = max(ly, hasAlpha ? 5 : 3); cy < n; cy++)
+        fy[cy] = cos(PI / h * (y + 0.5) * cy)
+
+      // Decode L
+      for (let cy = 0, j = 0; cy < ly; cy++)
+        for (let cx = cy ? 0 : 1, fy2 = fy[cy] * 2; cx * ly < lx * (ly - cy); cx++, j++)
+          l += l_ac[j] * fx[cx] * fy2
+
+      // Decode P and Q
+      for (let cy = 0, j = 0; cy < 3; cy++) {
+        for (let cx = cy ? 0 : 1, fy2 = fy[cy] * 2; cx < 3 - cy; cx++, j++) {
+          let f = fx[cx] * fy2
+          p += p_ac[j] * f
+          q += q_ac[j] * f
+        }
+      }
+
+      // Decode A
+      if (hasAlpha)
+        for (let cy = 0, j = 0; cy < 5; cy++)
+          for (let cx = cy ? 0 : 1, fy2 = fy[cy] * 2; cx < 5 - cy; cx++, j++)
+            a += a_ac[j] * fx[cx] * fy2
+
+      // Convert to RGB
+      let b = l - 2 / 3 * p
+      let r = (3 * l - b + q) / 2
+      let g = r - q
+      rgba[i] = max(0, 255 * min(1, r))
+      rgba[i + 1] = max(0, 255 * min(1, g))
+      rgba[i + 2] = max(0, 255 * min(1, b))
+      rgba[i + 3] = max(0, 255 * min(1, a))
+    }
+  }
+  return { w, h, rgba }
+}
+
+/**
+ * Extracts the average color from a ThumbHash. RGB is not be premultiplied by A.
+ *
+ * @param hash The bytes of the ThumbHash.
+ * @returns The RGBA values for the average color. Each value ranges from 0 to 1.
+ */
+export function thumbHashToAverageRGBA(hash) {
+  let { min, max } = Math
+  let header = hash[0] | (hash[1] << 8) | (hash[2] << 16)
+  let l = (header & 63) / 63
+  let p = ((header >> 6) & 63) / 31.5 - 1
+  let q = ((header >> 12) & 63) / 31.5 - 1
+  let hasAlpha = header >> 23
+  let a = hasAlpha ? (hash[5] & 15) / 15 : 1
+  let b = l - 2 / 3 * p
+  let r = (3 * l - b + q) / 2
+  let g = r - q
+  return {
+    r: max(0, min(1, r)),
+    g: max(0, min(1, g)),
+    b: max(0, min(1, b)),
+    a
+  }
+}
+
+/**
+ * Extracts the approximate aspect ratio of the original image.
+ *
+ * @param hash The bytes of the ThumbHash.
+ * @returns The approximate aspect ratio (i.e. width / height).
+ */
+export function thumbHashToApproximateAspectRatio(hash) {
+  let header = hash[3]
+  let hasAlpha = hash[2] & 0x80
+  let isLandscape = hash[4] & 0x80
+  let lx = isLandscape ? hasAlpha ? 5 : 7 : header & 7
+  let ly = isLandscape ? header & 7 : hasAlpha ? 5 : 7
+  return lx / ly
+}
+
+/**
+ * Encodes an RGBA image to a PNG data URL. RGB should not be premultiplied by
+ * A. This is optimized for speed and simplicity and does not optimize for size
+ * at all. This doesn't do any compression (all values are stored uncompressed).
+ *
+ * @param w The width of the input image. Must be ≤100px.
+ * @param h The height of the input image. Must be ≤100px.
+ * @param rgba The pixels in the input image, row-by-row. Must have w*h*4 elements.
+ * @returns A data URL containing a PNG for the input image.
+ */
+export function rgbaToDataURL(w, h, rgba) {
+  let row = w * 4 + 1
+  let idat = 6 + h * (5 + row)
+  let bytes = [
+    137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82, 0, 0,
+    w >> 8, w & 255, 0, 0, h >> 8, h & 255, 8, 6, 0, 0, 0, 0, 0, 0, 0,
+    idat >>> 24, (idat >> 16) & 255, (idat >> 8) & 255, idat & 255,
+    73, 68, 65, 84, 120, 1
+  ]
+  let table = [
+    0, 498536548, 997073096, 651767980, 1994146192, 1802195444, 1303535960,
+    1342533948, -306674912, -267414716, -690576408, -882789492, -1687895376,
+    -2032938284, -1609899400, -1111625188
+  ]
+  let a = 1, b = 0
+  for (let y = 0, i = 0, end = row - 1; y < h; y++, end += row - 1) {
+    bytes.push(y + 1 < h ? 0 : 1, row & 255, row >> 8, ~row & 255, (row >> 8) ^ 255, 0)
+    for (b = (b + a) % 65521; i < end; i++) {
+      let u = rgba[i] & 255
+      bytes.push(u)
+      a = (a + u) % 65521
+      b = (b + a) % 65521
+    }
+  }
+  bytes.push(
+    b >> 8, b & 255, a >> 8, a & 255, 0, 0, 0, 0,
+    0, 0, 0, 0, 73, 69, 78, 68, 174, 66, 96, 130
+  )
+  for (let [start, end] of [[12, 29], [37, 41 + idat]]) {
+    let c = ~0
+    for (let i = start; i < end; i++) {
+      c ^= bytes[i]
+      c = (c >>> 4) ^ table[c & 15]
+      c = (c >>> 4) ^ table[c & 15]
+    }
+    c = ~c
+    bytes[end++] = c >>> 24
+    bytes[end++] = (c >> 16) & 255
+    bytes[end++] = (c >> 8) & 255
+    bytes[end++] = c & 255
+  }
+  return 'data:image/png;base64,' + btoa(String.fromCharCode(...bytes))
+}
+
+/**
+ * Decodes a ThumbHash to a PNG data URL. This is a convenience function that
+ * just calls "thumbHashToRGBA" followed by "rgbaToDataURL".
+ *
+ * @param hash The bytes of the ThumbHash.
+ * @returns A data URL containing a PNG for the rendered ThumbHash.
+ */
+export function thumbHashToDataURL(hash) {
+  let image = thumbHashToRGBA(hash)
+  return rgbaToDataURL(image.w, image.h, image.rgba)
+}
diff --git a/core/artwork/thumbhash/testdata/tiny.png b/core/artwork/thumbhash/testdata/tiny.png
new file mode 100644
index 0000000000000000000000000000000000000000..ab635e11a904d71fce72f9361aa4fb420e9f5d18
GIT binary patch
literal 70
zcmeAS@N?(olHy`uVBq!ia0vp^j3CUx1|;Q0k92}1TpU9x<|J=edE=8j1IrPnj0%CR
Qyg&&CPgg&ebxsLQ0L54j#Q*>R

literal 0
HcmV?d00001

diff --git a/core/artwork/thumbhash/thumbhash.go b/core/artwork/thumbhash/thumbhash.go
new file mode 100644
index 000000000..a255bec42
--- /dev/null
+++ b/core/artwork/thumbhash/thumbhash.go
@@ -0,0 +1,257 @@
+// Package thumbhash implements the ThumbHash encoding algorithm (https://github.com/evanw/thumbhash).
+package thumbhash
+
+import (
+	"errors"
+	"image"
+	"image/draw"
+	"math"
+
+	xdraw "golang.org/x/image/draw"
+)
+
+// maxInputSize is the algorithm's hard limit: larger inputs are rejected by every implementation.
+const maxInputSize = 100
+
+// term is one DCT coefficient's frequency pair, in the reference's triangular scan order.
+type term struct{ cx, cy int }
+
+// Encode returns the ThumbHash of img: 24 bytes when opaque, 25 with alpha. Output matches
+// evanw/thumbhash except where a coefficient lands on a quantization tie, where a nibble may differ by 1.
+func Encode(img image.Image) ([]byte, error) {
+	rgba := toNRGBA(downscale(img))
+	b := rgba.Bounds()
+	w, h := b.Dx(), b.Dy()
+	if w == 0 || h == 0 {
+		return nil, errors.New("thumbhash: empty image")
+	}
+
+	avgR, avgG, avgB, avgA := averageColor(rgba, w, h)
+	hasAlpha := avgA < float64(w*h)
+	if avgA > 0 {
+		avgR /= avgA
+		avgG /= avgA
+		avgB /= avgA
+	}
+
+	lLimit := 7.0
+	if hasAlpha {
+		lLimit = 5.0
+	}
+	maxWH := float64(max(w, h))
+	lx := max(1, int(math.Round(lLimit*float64(w)/maxWH)))
+	ly := max(1, int(math.Round(lLimit*float64(h)/maxWH)))
+
+	lTerms := terms(max(3, lx), max(3, ly))
+	pTerms := terms(3, 3)
+	qTerms := terms(3, 3)
+	var aTerms []term
+	if hasAlpha {
+		aTerms = terms(5, 5)
+	}
+
+	// The widest coefficient region wins: 3x3 chroma, 5x5 alpha, and luma's own lx by ly.
+	chan5 := 3
+	if hasAlpha {
+		chan5 = 5
+	}
+	nx := max(max(3, lx), chan5)
+	cosX := cosTable(nx, w)
+	cosY := cosTable(max(max(3, ly), chan5), h)
+
+	lAcc := make([]float64, len(lTerms))
+	pAcc := make([]float64, len(pTerms))
+	qAcc := make([]float64, len(qTerms))
+	aAcc := make([]float64, len(aTerms))
+	rowL := make([]float64, nx)
+	rowP := make([]float64, nx)
+	rowQ := make([]float64, nx)
+	rowA := make([]float64, nx)
+
+	for y := range h {
+		clear(rowL)
+		clear(rowP)
+		clear(rowQ)
+		clear(rowA)
+		row := rgba.Pix[y*rgba.Stride:]
+		for x := range w {
+			j := x * 4
+			alpha := float64(row[j+3]) / 255
+			r := avgR*(1-alpha) + alpha/255*float64(row[j])
+			g := avgG*(1-alpha) + alpha/255*float64(row[j+1])
+			bl := avgB*(1-alpha) + alpha/255*float64(row[j+2])
+			lv := (r + g + bl) / 3
+			pv := (r+g)/2 - bl
+			qv := r - g
+			for cx := range nx {
+				f := cosX[cx][x]
+				rowL[cx] += lv * f
+				rowP[cx] += pv * f
+				rowQ[cx] += qv * f
+			}
+			// hasAlpha is loop-invariant, so this costs a predicted branch rather than a quarter
+			// of the inner loop that opaque images never need.
+			if hasAlpha {
+				for cx := range nx {
+					rowA[cx] += alpha * cosX[cx][x]
+				}
+			}
+		}
+		accumulate(lAcc, lTerms, rowL, cosY, y)
+		accumulate(pAcc, pTerms, rowP, cosY, y)
+		accumulate(qAcc, qTerms, rowQ, cosY, y)
+		accumulate(aAcc, aTerms, rowA, cosY, y)
+	}
+
+	n := float64(w * h)
+	lDC, lAC, lScale := normalize(lAcc, n)
+	pDC, pAC, pScale := normalize(pAcc, n)
+	qDC, qAC, qScale := normalize(qAcc, n)
+	aDC, aAC, aScale := normalize(aAcc, n)
+
+	return pack(w, h, hasAlpha, lx, ly,
+		lDC, pDC, qDC, aDC, lScale, pScale, qScale, aScale, lAC, pAC, qAC, aAC), nil
+}
+
+// terms lists the (cx, cy) pairs of the reference's triangular coefficient region, in write order.
+func terms(nx, ny int) []term {
+	var ts []term
+	for cy := range ny {
+		for cx := 0; cx*ny < nx*(ny-cy); cx++ {
+			ts = append(ts, term{cx, cy})
+		}
+	}
+	return ts
+}
+
+// cosTable precomputes cos(pi/size * c * (i+0.5)) with the reference's exact expression, so the
+// table values are bit-identical to recomputing them per coefficient.
+func cosTable(n, size int) [][]float64 {
+	t := make([][]float64, n)
+	for c := range n {
+		t[c] = make([]float64, size)
+		for i := range size {
+			t[c][i] = math.Cos(math.Pi / float64(size) * float64(c) * (float64(i) + 0.5))
+		}
+	}
+	return t
+}
+
+func averageColor(rgba *image.NRGBA, w, h int) (r, g, b, a float64) {
+	for y := range h {
+		row := rgba.Pix[y*rgba.Stride:]
+		for x := range w {
+			j := x * 4
+			alpha := float64(row[j+3]) / 255
+			r += alpha / 255 * float64(row[j])
+			g += alpha / 255 * float64(row[j+1])
+			b += alpha / 255 * float64(row[j+2])
+			a += alpha
+		}
+	}
+	return r, g, b, a
+}
+
+// accumulate folds one row's per-cx sums into the term accumulators, so the pixel loop costs
+// nx multiplies per pixel instead of one per coefficient.
+func accumulate(acc []float64, ts []term, row []float64, cosY [][]float64, y int) {
+	for k, t := range ts {
+		acc[k] += row[t.cx] * cosY[t.cy][y]
+	}
+}
+
+// normalize splits the accumulators into DC and scaled AC terms, matching the reference: a constant
+// image leaves scale at 0, which skips normalization rather than mapping the terms to the midpoint.
+func normalize(acc []float64, n float64) (dc float64, ac []float64, scale float64) {
+	if len(acc) == 0 {
+		return 0, nil, 0
+	}
+	dc = acc[0] / n
+	ac = make([]float64, len(acc)-1)
+	for i, v := range acc[1:] {
+		ac[i] = v / n
+		scale = max(scale, math.Abs(ac[i]))
+	}
+	if scale > 0 {
+		for i := range ac {
+			ac[i] = 0.5 + 0.5/scale*ac[i]
+		}
+	}
+	return dc, ac, scale
+}
+
+func pack(w, h int, hasAlpha bool, lx, ly int,
+	lDC, pDC, qDC, aDC, lScale, pScale, qScale, aScale float64,
+	lAC, pAC, qAC, aAC []float64,
+) []byte {
+	isLandscape := 0
+	if w > h {
+		isLandscape = 1
+	}
+	alphaBit := 0
+	if hasAlpha {
+		alphaBit = 1
+	}
+	header24 := int(math.Round(63*lDC)) | int(math.Round(31.5+31.5*pDC))<<6 |
+		int(math.Round(31.5+31.5*qDC))<<12 | int(math.Round(31*lScale))<<18 | alphaBit<<23
+	lead := lx
+	if isLandscape == 1 {
+		lead = ly
+	}
+	header16 := lead | int(math.Round(63*pScale))<<3 | int(math.Round(63*qScale))<<9 | isLandscape<<15
+
+	acs := [][]float64{lAC, pAC, qAC}
+	acStart := 5
+	if hasAlpha {
+		acs = append(acs, aAC)
+		acStart = 6
+	}
+	acCount := 0
+	for _, ac := range acs {
+		acCount += len(ac)
+	}
+
+	hash := make([]byte, acStart+(acCount+1)/2)
+	hash[0] = byte(header24 & 255)
+	hash[1] = byte((header24 >> 8) & 255)
+	hash[2] = byte(header24 >> 16)
+	hash[3] = byte(header16 & 255)
+	hash[4] = byte(header16 >> 8)
+	if hasAlpha {
+		hash[5] = byte(int(math.Round(15*aDC)) | int(math.Round(15*aScale))<<4)
+	}
+	acIndex := 0
+	for _, ac := range acs {
+		for _, f := range ac {
+			hash[acStart+(acIndex>>1)] |= byte(int(math.Round(15*f)) << ((acIndex & 1) << 2))
+			acIndex++
+		}
+	}
+	return hash
+}
+
+// NRGBA, not RGBA: ThumbHash requires non-premultiplied RGB and the pipeline hands us a
+// premultiplied *image.RGBA, which draw.Draw un-premultiplies on the way in.
+func toNRGBA(img image.Image) *image.NRGBA {
+	// Conservative: a sub-image re-slices Pix so the loops would read it correctly too, but the
+	// copy costs nothing on the origin-anchored images the pipeline actually produces.
+	if nrgba, ok := img.(*image.NRGBA); ok && nrgba.Rect.Min == (image.Point{}) {
+		return nrgba
+	}
+	b := img.Bounds()
+	dst := image.NewNRGBA(image.Rect(0, 0, b.Dx(), b.Dy()))
+	draw.Draw(dst, dst.Bounds(), img, b.Min, draw.Src)
+	return dst
+}
+
+func downscale(img image.Image) image.Image {
+	b := img.Bounds()
+	w, h := b.Dx(), b.Dy()
+	if w <= maxInputSize && h <= maxInputSize {
+		return img
+	}
+	scale := float64(maxInputSize) / float64(max(w, h))
+	dst := image.NewNRGBA(image.Rect(0, 0, max(1, int(float64(w)*scale)), max(1, int(float64(h)*scale))))
+	xdraw.ApproxBiLinear.Scale(dst, dst.Bounds(), img, b, draw.Src, nil)
+	return dst
+}
diff --git a/core/artwork/thumbhash/thumbhash_suite_test.go b/core/artwork/thumbhash/thumbhash_suite_test.go
new file mode 100644
index 000000000..11a6f0e25
--- /dev/null
+++ b/core/artwork/thumbhash/thumbhash_suite_test.go
@@ -0,0 +1,17 @@
+package thumbhash_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestThumbHash(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "ThumbHash Suite")
+}
diff --git a/core/artwork/thumbhash/thumbhash_test.go b/core/artwork/thumbhash/thumbhash_test.go
new file mode 100644
index 000000000..4832c25bc
--- /dev/null
+++ b/core/artwork/thumbhash/thumbhash_test.go
@@ -0,0 +1,194 @@
+package thumbhash_test
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"image"
+	"image/color"
+	"image/draw"
+	_ "image/png"
+	"os"
+	"path/filepath"
+	"runtime"
+	"slices"
+
+	"github.com/navidrome/navidrome/core/artwork/thumbhash"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// testdataDir is resolved via runtime.Caller because tests.Init (thumbhash_suite_test.go) chdirs
+// the process to the repo root, which would break a plain relative "testdata" path.
+var testdataDir = func() string {
+	_, file, _, _ := runtime.Caller(0)
+	return filepath.Join(filepath.Dir(file), "testdata")
+}()
+
+// fixtureImage decodes a testdata PNG. NRGBA, not RGBA: ThumbHash needs non-premultiplied pixels,
+// and RGBA would silently premultiply every fixture that has alpha.
+func fixtureImage(name string) *image.NRGBA {
+	GinkgoHelper()
+	f, err := os.Open(filepath.Join(testdataDir, name))
+	Expect(err).ToNot(HaveOccurred())
+	defer f.Close()
+	src, _, err := image.Decode(f)
+	Expect(err).ToNot(HaveOccurred())
+	b := src.Bounds()
+	dst := image.NewNRGBA(image.Rect(0, 0, b.Dx(), b.Dy()))
+	draw.Draw(dst, dst.Bounds(), src, b.Min, draw.Src)
+	return dst
+}
+
+// headerOnlyFixtures have mathematically-zero AC content, so every AC nibble is float rounding
+// noise sitting on a quantization tie; only the header bytes carry signal.
+var headerOnlyFixtures = []string{"solid.png", "tiny.png"}
+
+func loadJSON[T any](name string) T {
+	GinkgoHelper()
+	data, err := os.ReadFile(filepath.Join(testdataDir, name))
+	Expect(err).ToNot(HaveOccurred())
+	var out T
+	Expect(json.Unmarshal(data, &out)).To(Succeed())
+	return out
+}
+
+func loadGoldens() map[string]string {
+	GinkgoHelper()
+	golden := loadJSON[map[string]string]("golden.json")
+	Expect(golden).ToNot(BeEmpty())
+	return golden
+}
+
+// mix is a stateless 32-bit finaliser matching gen_generated.mjs, so both languages build the
+// same synthetic pixels and only the reference's hashes need committing.
+func mix(n uint32) uint32 {
+	n = (n ^ (n >> 16)) * 2246822507
+	n = (n ^ (n >> 13)) * 3266489909
+	return n ^ (n >> 16)
+}
+
+func generatedImage(i int) *image.NRGBA {
+	w := 1 + int(mix(uint32(i)*3+1)%100)
+	h := 1 + int(mix(uint32(i)*3+2)%100)
+	img := image.NewNRGBA(image.Rect(0, 0, w, h))
+	for k := range img.Pix {
+		img.Pix[k] = byte(mix(uint32(i)*1000003 + uint32(k)))
+	}
+	if i%2 == 0 {
+		for k := 3; k < len(img.Pix); k += 4 {
+			img.Pix[k] = 255
+		}
+	}
+	return img
+}
+
+var _ = Describe("Encode", func() {
+	It("matches every golden vector", func() {
+		for name, want := range loadGoldens() {
+			if slices.Contains(headerOnlyFixtures, name) {
+				continue // see the dedicated header-only spec below
+			}
+			got, err := thumbhash.Encode(fixtureImage(name))
+			Expect(err).ToNot(HaveOccurred(), "fixture %s", name)
+			Expect(base64.StdEncoding.EncodeToString(got)).To(Equal(want), "fixture %s", name)
+		}
+	})
+
+	It("reproduces the well-conditioned header of the ill-conditioned fixtures", func() {
+		for _, name := range headerOnlyFixtures {
+			want, err := base64.StdEncoding.DecodeString(loadGoldens()[name])
+			Expect(err).ToNot(HaveOccurred(), "fixture %s", name)
+			got, err := thumbhash.Encode(fixtureImage(name))
+			Expect(err).ToNot(HaveOccurred(), "fixture %s", name)
+			Expect(got[:5]).To(Equal(want[:5]), "fixture %s header bytes", name)
+		}
+	})
+
+	// The PNG fixtures cannot reach every layout; these sweep random sizes, aspects and both the
+	// 7x7 no-alpha and 5x5-plus-alpha coefficient regions against the same reference.
+	It("matches the reference on 300 generated images", func() {
+		vectors := loadJSON[[]struct {
+			W, H int
+			Hash string
+		}]("generated.json")
+		Expect(vectors).ToNot(BeEmpty())
+		for i, want := range vectors {
+			img := generatedImage(i)
+			Expect(img.Bounds().Dx()).To(Equal(want.W), "vector %d width", i)
+			Expect(img.Bounds().Dy()).To(Equal(want.H), "vector %d height", i)
+			got, err := thumbhash.Encode(img)
+			Expect(err).ToNot(HaveOccurred(), "vector %d", i)
+			Expect(base64.StdEncoding.EncodeToString(got)).To(Equal(want.Hash), "vector %d (%dx%d)", i, want.W, want.H)
+		}
+	})
+
+	It("quantizes a uniform image's scales to zero", func() {
+		got, err := thumbhash.Encode(fixtureImage("solid.png"))
+		Expect(err).ToNot(HaveOccurred())
+		header24 := int(got[0]) | int(got[1])<<8 | int(got[2])<<16
+		header16 := int(got[3]) | int(got[4])<<8
+		Expect((header24>>18)&31).To(Equal(0), "lScale")
+		Expect((header16>>3)&63).To(Equal(0), "pScale")
+		Expect((header16>>9)&63).To(Equal(0), "qScale")
+	})
+
+	It("produces 24 bytes for a square opaque image", func() {
+		got, err := thumbhash.Encode(fixtureImage("square.png"))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(HaveLen(24))
+	})
+
+	It("produces 25 bytes when the image has alpha", func() {
+		got, err := thumbhash.Encode(fixtureImage("alpha.png"))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(HaveLen(25))
+	})
+
+	It("downscales an oversized image rather than failing", func() {
+		img := image.NewNRGBA(image.Rect(0, 0, 500, 300))
+		for i := range img.Pix {
+			img.Pix[i] = byte(i)
+		}
+		got, err := thumbhash.Encode(img)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(len(got)).To(BeNumerically(">=", 5))
+	})
+
+	It("encodes a 1x1 image", func() {
+		img := image.NewNRGBA(image.Rect(0, 0, 1, 1))
+		img.Set(0, 0, color.NRGBA{R: 60, G: 120, B: 180, A: 255})
+		got, err := thumbhash.Encode(img)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).ToNot(BeEmpty())
+	})
+
+	It("encodes a sub-image like an origin-anchored copy of the same region", func() {
+		parent := image.NewNRGBA(image.Rect(0, 0, 60, 50))
+		for i := range parent.Pix {
+			parent.Pix[i] = byte(i * 7 % 251)
+		}
+		region := image.Rect(10, 7, 40, 30)
+		cropped := image.NewNRGBA(image.Rect(0, 0, region.Dx(), region.Dy()))
+		draw.Draw(cropped, cropped.Bounds(), parent, region.Min, draw.Src)
+
+		got, err := thumbhash.Encode(parent.SubImage(region))
+		Expect(err).ToNot(HaveOccurred())
+		want, err := thumbhash.Encode(cropped)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(Equal(want))
+	})
+
+	It("rejects an empty image", func() {
+		_, err := thumbhash.Encode(image.NewRGBA(image.Rect(0, 0, 0, 0)))
+		Expect(err).To(HaveOccurred())
+	})
+
+	It("is deterministic", func() {
+		img := fixtureImage("square.png")
+		first, err := thumbhash.Encode(img)
+		Expect(err).ToNot(HaveOccurred())
+		second, err := thumbhash.Encode(img)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(first).To(Equal(second))
+	})
+})
diff --git a/core/image_upload.go b/core/artwork/uploader.go
similarity index 55%
rename from core/image_upload.go
rename to core/artwork/uploader.go
index eb61b225a..9c38ae2e5 100644
--- a/core/image_upload.go
+++ b/core/artwork/uploader.go
@@ -1,4 +1,4 @@
-package core
+package artwork
 
 import (
 	"context"
@@ -15,13 +15,7 @@ import (
 	"github.com/navidrome/navidrome/utils"
 )
 
-type ImageUploadService interface {
-	SetImage(ctx context.Context, entityType string, entityID string, name string, oldPath string, reader io.Reader, ext string) (filename string, err error)
-	RemoveImage(ctx context.Context, path string) error
-}
-
-// MaxImageUploadSize returns the configured MaxImageUploadSize in bytes, or the built-in default
-// when it's unset/invalid. Shared by every API that accepts image uploads.
+// MaxImageUploadSize returns the configured max upload size in bytes, or the built-in default.
 func MaxImageUploadSize() int64 {
 	if size, err := humanize.ParseBytes(conf.Server.MaxImageUploadSize); err == nil && size > 0 {
 		return int64(size)
@@ -30,13 +24,30 @@ func MaxImageUploadSize() int64 {
 	return int64(size)
 }
 
-type imageUploadService struct{}
-
-func NewImageUploadService() ImageUploadService {
-	return &imageUploadService{}
+// Uploader stores a user-uploaded entity image and invalidates that entity's artwork state.
+type Uploader interface {
+	SetImage(ctx context.Context, entityType string, entityID string, name string, oldPath string, reader io.Reader, ext string) (filename string, err error)
+	RemoveImage(ctx context.Context, path string) error
+	// EnqueueArtwork re-resolves the item's artwork. Call it AFTER persisting the new
+	// filename, or the worker resolves the old one.
+	EnqueueArtwork(ctx context.Context, entityType, entityID string)
 }
 
-func (s *imageUploadService) SetImage(ctx context.Context, entityType string, entityID string, name string, oldPath string, reader io.Reader, ext string) (string, error) {
+var uploadEntityKind = map[string]model.Kind{
+	consts.EntityArtist:   model.KindArtistArtwork,
+	consts.EntityPlaylist: model.KindPlaylistArtwork,
+	consts.EntityRadio:    model.KindRadioArtwork,
+}
+
+type uploader struct {
+	ds model.DataStore
+}
+
+func NewUploader(ds model.DataStore) Uploader {
+	return &uploader{ds: ds}
+}
+
+func (s *uploader) SetImage(ctx context.Context, entityType string, entityID string, name string, oldPath string, reader io.Reader, ext string) (string, error) {
 	filename := imageFilename(entityID, name, ext)
 	absPath := model.UploadedImagePath(entityType, filename)
 
@@ -44,14 +55,12 @@ func (s *imageUploadService) SetImage(ctx context.Context, entityType string, en
 		return "", fmt.Errorf("creating image directory: %w", err)
 	}
 
-	// Remove old image if it exists
 	if oldPath != "" {
 		if err := os.Remove(oldPath); err != nil && !os.IsNotExist(err) {
-			log.Warn(ctx, "Failed to remove old image", "path", oldPath, err)
+			log.Warn(ctx, "Artwork: Failed to remove old image", "path", oldPath, err)
 		}
 	}
 
-	// Save new image
 	f, err := os.Create(absPath)
 	if err != nil {
 		return "", fmt.Errorf("creating image file: %w", err)
@@ -61,11 +70,20 @@ func (s *imageUploadService) SetImage(ctx context.Context, entityType string, en
 	if _, err := io.Copy(f, reader); err != nil {
 		return "", fmt.Errorf("writing image file: %w", err)
 	}
-
 	return filename, nil
 }
 
-func (s *imageUploadService) RemoveImage(ctx context.Context, path string) error {
+func (s *uploader) EnqueueArtwork(ctx context.Context, entityType, id string) {
+	kind, ok := uploadEntityKind[entityType]
+	if !ok {
+		return
+	}
+	if err := Refresh(ctx, s.ds, kind, id); err != nil {
+		log.Warn(ctx, "Artwork: Could not refresh artwork after upload", "kind", kind, "id", id, err)
+	}
+}
+
+func (s *uploader) RemoveImage(ctx context.Context, path string) error {
 	if path == "" {
 		return nil
 	}
diff --git a/core/image_upload_test.go b/core/artwork/uploader_test.go
similarity index 60%
rename from core/image_upload_test.go
rename to core/artwork/uploader_test.go
index e7648df34..44f5ede26 100644
--- a/core/image_upload_test.go
+++ b/core/artwork/uploader_test.go
@@ -1,4 +1,4 @@
-package core_test
+package artwork
 
 import (
 	"context"
@@ -9,20 +9,26 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
-var _ = Describe("ImageUploadService", func() {
-	var svc core.ImageUploadService
+var _ = Describe("Uploader", func() {
+	var svc Uploader
 	var tmpDir string
+	var artRepo *tests.MockArtworkRepo
+	var queueRepo *tests.MockArtworkQueueRepo
 
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		tmpDir = GinkgoT().TempDir()
 		conf.Server.DataFolder = conf.NewDir(tmpDir)
-		svc = core.NewImageUploadService()
+		artRepo = tests.CreateMockArtworkRepo()
+		queueRepo = tests.CreateMockArtworkQueueRepo()
+		ds := &tests.MockDataStore{MockedArtwork: artRepo, MockedArtworkQueue: queueRepo}
+		svc = NewUploader(ds)
 	})
 
 	Describe("SetImage", func() {
@@ -69,6 +75,49 @@ var _ = Describe("ImageUploadService", func() {
 			_, err := svc.SetImage(ctx, consts.EntityArtist, "ar-1", "Name", "/nonexistent/path.jpg", reader, ".jpg")
 			Expect(err).ToNot(HaveOccurred())
 		})
+
+		It("does not touch artwork state or the queue (that is EnqueueArtwork's job, post-Put)", func() {
+			ctx := context.Background()
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "ar", ItemID: "ar-1", Hash: "oldhash", Source: "external",
+			})).To(Succeed())
+
+			_, err := svc.SetImage(ctx, consts.EntityArtist, "ar-1", "Pink Floyd", "", strings.NewReader("img"), ".jpg")
+			Expect(err).ToNot(HaveOccurred())
+
+			// SetImage only writes the file; the state row survives and nothing is queued until
+			// the caller has persisted the new filename and called EnqueueArtwork.
+			_, err = artRepo.GetItemArtwork(model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(queueRepo.DequeueBatch(1000)).To(BeEmpty())
+		})
+	})
+
+	Describe("EnqueueArtwork", func() {
+		It("clears artwork state and enqueues a Bump", func() {
+			ctx := context.Background()
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "ar", ItemID: "ar-1", Hash: "oldhash", Source: "external",
+			})).To(Succeed())
+
+			svc.EnqueueArtwork(ctx, consts.EntityArtist, "ar-1")
+
+			_, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+
+			queued, err := queueRepo.DequeueBatch(1000)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(queued).To(ContainElement(SatisfyAll(
+				HaveField("ItemKind", "ar"),
+				HaveField("ItemID", "ar-1"),
+				HaveField("Priority", model.ArtworkPriorityBump),
+			)))
+		})
+
+		It("is a no-op for an unknown entity type", func() {
+			svc.EnqueueArtwork(context.Background(), "unknown", "x-1")
+			Expect(queueRepo.DequeueBatch(1000)).To(BeEmpty())
+		})
 	})
 
 	Describe("RemoveImage", func() {
@@ -105,21 +154,21 @@ var _ = Describe("MaxImageUploadSize", func() {
 
 	It("returns the configured size when valid", func() {
 		conf.Server.MaxImageUploadSize = "20MB"
-		Expect(core.MaxImageUploadSize()).To(Equal(int64(20_000_000)))
+		Expect(MaxImageUploadSize()).To(Equal(int64(20_000_000)))
 	})
 
 	It("returns the default size when config is empty", func() {
 		conf.Server.MaxImageUploadSize = ""
-		Expect(core.MaxImageUploadSize()).To(Equal(int64(10_000_000)))
+		Expect(MaxImageUploadSize()).To(Equal(int64(10_000_000)))
 	})
 
 	It("returns the default size when config is invalid", func() {
 		conf.Server.MaxImageUploadSize = "not-a-size"
-		Expect(core.MaxImageUploadSize()).To(Equal(int64(10_000_000)))
+		Expect(MaxImageUploadSize()).To(Equal(int64(10_000_000)))
 	})
 
 	It("parses raw byte values", func() {
 		conf.Server.MaxImageUploadSize = "52428800"
-		Expect(core.MaxImageUploadSize()).To(Equal(int64(52_428_800)))
+		Expect(MaxImageUploadSize()).To(Equal(int64(52_428_800)))
 	})
 })
diff --git a/core/artwork/wire_providers.go b/core/artwork/wire_providers.go
index 63231b54a..54c2ad397 100644
--- a/core/artwork/wire_providers.go
+++ b/core/artwork/wire_providers.go
@@ -7,5 +7,7 @@ import (
 var Set = wire.NewSet(
 	NewArtwork,
 	GetImageCache,
-	NewCacheWarmer,
+	NewWorker,
+	GetImageStore,
+	NewUploader,
 )
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
new file mode 100644
index 000000000..3042c47b0
--- /dev/null
+++ b/core/artwork/worker.go
@@ -0,0 +1,318 @@
+package artwork
+
+import (
+	"bytes"
+	"cmp"
+	"context"
+	"io"
+	"math"
+	"math/rand/v2"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/ffmpeg"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server/events"
+	"github.com/navidrome/navidrome/utils/cache"
+)
+
+const (
+	workerPollInterval = 5 * time.Second
+	backoffBase        = 5 * time.Second
+	// giveUpAfter bounds the retry budget from enqueue; past it the item falls to the
+	// periodic stale-absent recheck.
+	giveUpAfter = 12 * time.Hour
+)
+
+// drainPool drains one class of work with its own slot budget, so a blocking kind cannot
+// occupy slots another kind needs.
+type drainPool struct {
+	name        string
+	kinds       []string
+	concurrency int
+}
+
+// Worker drains the artwork queue: each external agent is rate-limited and circuit-broken
+// independently, and pruneMu serializes prune against the store-write window.
+type Worker struct {
+	proc    *processor
+	cache   cache.FileCache
+	ffmpeg  ffmpeg.FFmpeg
+	broker  events.Broker
+	pruneMu sync.RWMutex
+	pools   []*drainPool
+	runCtx  context.Context
+
+	gatesMu sync.Mutex
+	gates   map[string]*extGate
+}
+
+func NewWorker(ds model.DataStore, store *ImageStore, ag *agents.Agents, ffmpeg ffmpeg.FFmpeg, broker events.Broker, imgCache cache.FileCache) *Worker {
+	w := &Worker{
+		proc:   &processor{ds: ds, store: store},
+		cache:  imgCache,
+		ffmpeg: ffmpeg,
+		broker: broker,
+		pools:  newDrainPools(),
+		runCtx: context.Background(),
+		gates:  map[string]*extGate{},
+	}
+	w.proc.resolver = newResolver(ds, ag, ffmpeg, w.gate)
+	w.proc.pruneLock = w.pruneMu.RLocker()
+	return w
+}
+
+// newDrainPools splits the drain by what bounds it: gate() holds a slot while waiting for its
+// rate-limit permit, so a sleeping lookup would crowd out a cover sitting on disk.
+func newDrainPools() []*drainPool {
+	budget := conf.MaxOpenConns() // floored at 4, so both remainders below stay positive
+	local := min(max(1, conf.Server.DevArtworkWorkerConcurrency), budget-1)
+	// More external slots than the rate allows would only sleep in the limiter.
+	external := min(max(2, 2*conf.Server.DevArtworkExternalMaxRPS), budget-local)
+	return []*drainPool{
+		{name: "local", kinds: localDrainKinds, concurrency: local},
+		{name: "external", kinds: externalDrainKinds, concurrency: external},
+	}
+}
+
+// Kind is a proxy for cost: an album that reaches an external agent still costs a local slot.
+var (
+	externalDrainKinds = []string{model.KindArtistArtwork.Prefix()}
+	localDrainKinds    = []string{
+		model.KindAlbumArtwork.Prefix(),
+		model.KindPlaylistArtwork.Prefix(),
+		model.KindRadioArtwork.Prefix(),
+		model.KindMediaFileArtwork.Prefix(),
+	}
+)
+
+// Run blocks draining the queue until ctx is cancelled.
+func (w *Worker) Run(ctx context.Context) error {
+	w.runCtx = ctx
+	var wg sync.WaitGroup
+	for _, p := range w.pools {
+		wg.Go(func() { w.runPool(ctx, p) })
+	}
+	wg.Wait()
+	return nil
+}
+
+func (w *Worker) runPool(ctx context.Context, p *drainPool) {
+	ticker := time.NewTicker(workerPollInterval)
+	defer ticker.Stop()
+	for {
+		n, err := w.drain(ctx, p.concurrency, p.kinds...)
+		if err != nil && ctx.Err() == nil {
+			log.Warn(ctx, "Artwork: Worker drain failed", "pool", p.name, err)
+		}
+		if ctx.Err() != nil {
+			return
+		}
+		if n > 0 {
+			continue
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+	}
+}
+
+// RunPrune runs prune under the worker's write lock, so no acquisition can place
+// a file while orphans are being reclaimed. This is the only sanctioned prune path.
+func (w *Worker) RunPrune(ctx context.Context) error {
+	w.pruneMu.Lock()
+	defer w.pruneMu.Unlock()
+	return prune(ctx, w.proc.ds, w.proc.store)
+}
+
+// Backfill enqueues every entity for re-resolution when the artwork config fingerprint changed,
+// artists first. It reports whether anything was enqueued.
+func (w *Worker) Backfill(ctx context.Context) (bool, error) {
+	return backfill(ctx, w.proc.ds)
+}
+
+// EnqueueStaleAbsentAll requeues known-absent entries older than staleAbsentAge.
+func (w *Worker) EnqueueStaleAbsentAll(ctx context.Context) error {
+	return enqueueStaleAbsentAll(ctx, w.proc.ds)
+}
+
+// EnqueueMissingAll requeues entities with no artwork state row: the safety net for anything
+// a scan never enqueued.
+func (w *Worker) EnqueueMissingAll(ctx context.Context) error {
+	return enqueueMissingAll(ctx, w.proc.ds)
+}
+
+func (w *Worker) drain(ctx context.Context, concurrency int, kinds ...string) (int, error) {
+	// Dequeue well past the pool size so a slow external lookup never idles the other slots.
+	// DequeueBatch does not mark rows taken, so this is one query per pass, not per slot.
+	items, err := w.proc.ds.ArtworkQueue(ctx).DequeueBatch(max(16, 4*concurrency), kinds...)
+	if err != nil {
+		return 0, err
+	}
+	if len(items) == 0 {
+		return 0, nil
+	}
+	drainStart := time.Now()
+	// Private playlists need an admin identity; resolved per drain because the worker can
+	// start before any admin exists.
+	ctx = auth.WithAdminUser(ctx, w.proc.ds)
+	sem := make(chan struct{}, concurrency)
+	var wg sync.WaitGroup
+	var refreshMu sync.Mutex
+	var refresh []model.ArtworkQueueItem
+	for _, item := range items {
+		select {
+		case sem <- struct{}{}:
+		case <-ctx.Done():
+			wg.Wait()
+			return len(items), nil
+		}
+		wg.Go(func() {
+			defer func() { <-sem }()
+			out, got := w.process(ctx, item)
+			// Absent counts as a visible change too: clients must drop a previously-served
+			// immutable cover.
+			if out == outcomeFound || out == outcomeFoundStale || out == outcomeAbsent {
+				refreshMu.Lock()
+				refresh = append(refresh, item)
+				refreshMu.Unlock()
+			}
+			// Post-outcome: the queue row is already settled, so warming the cache can't
+			// block or alter queue ops.
+			if got != nil {
+				w.precache(ctx, got)
+			}
+		})
+	}
+	wg.Wait()
+	w.broadcastRefresh(ctx, refresh)
+	log.Debug(ctx, "Artwork: Drained a batch", "kinds", kinds, "items", len(items),
+		"refreshed", len(refresh), "concurrency", concurrency, "elapsed", time.Since(drainStart))
+	return len(items), nil
+}
+
+// artworkKindToResource maps a kind to its UI resource name; media_file maps to "song", so
+// this can't derive from Kind.String().
+var artworkKindToResource = map[model.Kind]string{
+	model.KindAlbumArtwork:     "album",
+	model.KindArtistArtwork:    "artist",
+	model.KindPlaylistArtwork:  "playlist",
+	model.KindRadioArtwork:     "radio",
+	model.KindMediaFileArtwork: "song",
+}
+
+// broadcastRefresh emits one coalesced RefreshResource for the batch, so UIs re-fetch the
+// affected records and pick up the new coverArt id.
+func (w *Worker) broadcastRefresh(ctx context.Context, found []model.ArtworkQueueItem) {
+	if len(found) == 0 {
+		return
+	}
+	event := &events.RefreshResource{}
+	byResource := map[string][]string{}
+	for _, it := range found {
+		kind, _ := model.ParseKind(it.ItemKind)
+		if res, ok := artworkKindToResource[kind]; ok {
+			byResource[res] = append(byResource[res], it.ItemID)
+		}
+	}
+	if len(byResource) == 0 {
+		return
+	}
+	for res, ids := range byResource {
+		event = event.With(res, ids...)
+	}
+	w.broker.SendBroadcastMessage(ctx, event)
+}
+
+func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outcome, *acquired) {
+	item.ImageType = cmp.Or(item.ImageType, model.ImageTypePrimary)
+	out, got := w.proc.acquire(ctx, item)
+
+	queue := w.proc.ds.ArtworkQueue(ctx)
+	switch out {
+	case outcomeFound, outcomeAbsent:
+		// A scan that re-enqueued this row mid-flight reset its retry_at, so the row survives
+		// here and the next drain re-resolves it.
+		if err := queue.DeleteIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt); err != nil {
+			log.Warn(ctx, "Artwork: Could not delete processed queue item", "kind", item.ItemKind, "id", item.ItemID, err)
+		}
+	case outcomeFoundStale, outcomeFailed:
+		retryAt := time.Now().Add(backoff(item.Attempts))
+		if retryAt.Before(item.EnqueuedAt.Add(giveUpAfter)) {
+			// A mid-flight re-enqueue reset retry_at; stale backoff must not stomp its
+			// fresh, immediate eligibility.
+			if err := queue.MarkFailedIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt, retryAt); err != nil {
+				log.Warn(ctx, "Artwork: Could not reschedule failed queue item", "kind", item.ItemKind, "id", item.ItemID, err)
+			}
+			log.Debug(ctx, "Artwork: Rescheduled item", "kind", item.ItemKind, "id", item.ItemID,
+				"outcome", out, "attempts", item.Attempts+1, "retryIn", time.Until(retryAt),
+				"budgetLeft", time.Until(item.EnqueuedAt.Add(giveUpAfter)))
+			break
+		}
+		// Absent is only recoverable where a periodic recheck revisits it, so other kinds keep
+		// no row; art already being served is kept, as exhaustion means unreachable, not removed.
+		settled := "kept previous state"
+		if out == outcomeFailed && hasRecheckPath(item.ItemKind) && !w.hasResolvedArtwork(ctx, item) {
+			writeAbsent(ctx, w.proc.ds.Artwork(ctx), item)
+			settled = "recorded absent"
+		}
+		log.Info(ctx, "Artwork: Retry budget exhausted, giving up", "kind", item.ItemKind, "id", item.ItemID,
+			"outcome", out, "attempts", item.Attempts+1, "budget", giveUpAfter, "settled", settled)
+		if err := queue.DeleteIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt); err != nil {
+			log.Warn(ctx, "Artwork: Could not remove exhausted queue item", "kind", item.ItemKind, "id", item.ItemID, err)
+		}
+	}
+	return out, got
+}
+
+func (w *Worker) hasResolvedArtwork(ctx context.Context, item model.ArtworkQueueItem) bool {
+	kind, ok := model.ParseKind(item.ItemKind)
+	if !ok {
+		return false
+	}
+	ia, err := w.proc.ds.Artwork(ctx).GetItemArtwork(kind, item.ItemID, item.ImageType)
+	return err == nil && ia.Hash != ""
+}
+
+// precache warms the resize cache at the UI cover size from the bytes just acquired, so the
+// first UI request hits without re-reading the rows or the file.
+func (w *Worker) precache(ctx context.Context, got *acquired) {
+	if !conf.Server.EnableArtworkPrecache || w.cache == nil || w.cache.Disabled(ctx) {
+		return
+	}
+	precacheStart := time.Now()
+	// Same key as the serving path: square must match what the list surfaces request, or this
+	// warms a key nothing reads.
+	item := &resizedItem{
+		hash:   got.ia.Hash,
+		size:   conf.Server.UICoverArtSize,
+		square: true,
+		ffmpeg: w.ffmpeg,
+		open:   func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(got.data)), nil },
+	}
+	stream, err := w.cache.Get(ctx, item)
+	if err != nil {
+		log.Debug(ctx, "Artwork: Precache failed", "kind", got.ia.ItemKind, "id", got.ia.ItemID, err)
+		return
+	}
+	_, _ = io.Copy(io.Discard, stream)
+	_ = stream.Close()
+	log.Trace(ctx, "Artwork: Precached UI size", "kind", got.ia.ItemKind, "id", got.ia.ItemID,
+		"size", conf.Server.UICoverArtSize, "elapsed", time.Since(precacheStart))
+}
+
+// backoffFor returns min(5s×4^n, giveUpAfter) scaled by (1+jitter), with jitter in [-0.4, 0.4].
+func backoffFor(attempts int, jitter float64) time.Duration {
+	d := min(float64(backoffBase)*math.Pow(4, float64(attempts)), float64(giveUpAfter))
+	return time.Duration(d * (1 + jitter))
+}
+
+func backoff(attempts int) time.Duration {
+	return backoffFor(attempts, rand.Float64()*0.8-0.4) //nolint:gosec // retry jitter, not security-sensitive
+}
diff --git a/core/artwork/worker_soak_test.go b/core/artwork/worker_soak_test.go
new file mode 100644
index 000000000..eb7346102
--- /dev/null
+++ b/core/artwork/worker_soak_test.go
@@ -0,0 +1,146 @@
+package artwork
+
+import (
+	"context"
+	"io"
+	"os"
+	"runtime"
+	"testing"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Deliberately >2000: a leak guard favors a stable signal over speed.
+const soakCycles = 2200
+
+var _ = Describe("Worker soak", func() {
+	It("does not leak goroutines, heap, or fds over many acquisition cycles", func() {
+		if testing.Short() {
+			Skip("skipping soak test in short mode")
+		}
+		DeferCleanup(configtest.SetupConfig())
+
+		repoRoot, err := os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+
+		libRepo := &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		folderRepo := &fakeFolderRepo{result: []model.Folder{{
+			Path:       "tests/fixtures/artist/an-album",
+			ImageFiles: []string{"cover.jpg"},
+		}}}
+		ffm := tests.NewMockFFmpeg("")
+		ag := agents.GetAgents(&tests.MockDataStore{}, nil)
+		artRepo := tests.CreateMockArtworkRepo()
+		albumRepo := tests.CreateMockAlbumRepo()
+		albumRepo.SetData(model.Albums{
+			{ID: "al-folder", Name: "Folder Album", FolderIDs: []string{"f1"}},
+			{ID: "al-embed", Name: "Embedded Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},
+		})
+		ds := &tests.MockDataStore{
+			MockedFolder:  folderRepo,
+			MockedLibrary: libRepo,
+			MockedArtwork: artRepo,
+			MockedAlbum:   albumRepo,
+		}
+		store := NewImageStore(GinkgoT().TempDir())
+		proc := &processor{ds: ds, store: store, resolver: newResolver(ds, ag, ffm, nil)}
+		conf.Server.CoverArtPriority = "cover.jpg, embedded"
+
+		// Dangling refs mirror an entity deleted after being enqueued.
+		items := []model.ArtworkQueueItem{
+			{ItemKind: "al", ItemID: "al-folder"},
+			{ItemKind: "al", ItemID: "al-embed"},
+			{ItemKind: "al", ItemID: "al-does-not-exist"},
+			{ItemKind: "ra", ItemID: "ra-does-not-exist"},
+		}
+
+		fdCount := func() int {
+			if runtime.GOOS != "linux" {
+				return -1
+			}
+			entries, err := os.ReadDir("/proc/self/fd")
+			if err != nil {
+				return -1
+			}
+			return len(entries)
+		}
+
+		settleGoroutines := func() int {
+			// Background goroutines wind down late, so poll for two consecutive equal samples.
+			prev := -1
+			for range 100 {
+				runtime.GC()
+				n := runtime.NumGoroutine()
+				if n == prev {
+					return n
+				}
+				prev = n
+				time.Sleep(10 * time.Millisecond)
+			}
+			return prev
+		}
+
+		baselineGoroutines := settleGoroutines()
+		baselineFDs := fdCount()
+
+		var heapAt10Pct uint64
+		start := time.Now()
+		for i := range soakCycles {
+			it := items[i%len(items)]
+			out, _ := proc.acquire(context.Background(), it)
+
+			// Read-back exercises the surfaces a caller would use after acquisition.
+			if out == outcomeFound {
+				kind, _ := model.ParseKind(it.ItemKind)
+				ia, err := artRepo.GetItemArtwork(kind, it.ItemID, model.ImageTypePrimary)
+				Expect(err).ToNot(HaveOccurred(), "cycle %d: GetItemArtwork", i)
+				art, err := artRepo.GetImage(ia.Hash)
+				Expect(err).ToNot(HaveOccurred(), "cycle %d: GetImage", i)
+				rc, err := store.Open(ia.Hash, art.Mime)
+				switch {
+				case err == nil:
+					_, _ = io.Copy(io.Discard, rc)
+					rc.Close()
+				case os.IsNotExist(err):
+					// Folder-backed art has no store file; that's expected.
+				default:
+					Expect(err).ToNot(HaveOccurred(), "cycle %d: store.Open", i)
+				}
+			}
+
+			if i == soakCycles/10 {
+				runtime.GC()
+				var ms runtime.MemStats
+				runtime.ReadMemStats(&ms)
+				heapAt10Pct = ms.HeapAlloc
+			}
+		}
+		elapsed := time.Since(start)
+
+		finalGoroutines := settleGoroutines()
+		finalFDs := fdCount()
+
+		runtime.GC()
+		var ms runtime.MemStats
+		runtime.ReadMemStats(&ms)
+
+		GinkgoWriter.Printf("soak: cycles=%d elapsed=%s goroutines(baseline=%d final=%d) heap(10%%-mark=%d final=%d) fds(baseline=%d final=%d)\n",
+			soakCycles, elapsed, baselineGoroutines, finalGoroutines, heapAt10Pct, ms.HeapAlloc, baselineFDs, finalFDs)
+
+		Expect(finalGoroutines).To(BeNumerically("<=", baselineGoroutines), "goroutine count grew: baseline=%d final=%d", baselineGoroutines, finalGoroutines)
+		if heapAt10Pct > 0 {
+			Expect(ms.HeapAlloc).To(BeNumerically("<=", 2*heapAt10Pct), "heap did not plateau: 10%%-mark=%d final=%d (final > 2x 10%%-mark)", heapAt10Pct, ms.HeapAlloc)
+		}
+		if runtime.GOOS == "linux" && baselineFDs >= 0 {
+			Expect(finalFDs).To(BeNumerically("<=", baselineFDs), "fd count grew: baseline=%d final=%d", baselineFDs, finalFDs)
+		}
+	})
+})
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
new file mode 100644
index 000000000..1f3b52840
--- /dev/null
+++ b/core/artwork/worker_test.go
@@ -0,0 +1,813 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server/events"
+	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/cache"
+	"github.com/navidrome/navidrome/utils/slice"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"go.uber.org/goleak"
+)
+
+type recordingCache struct {
+	cache.FileCache
+	mu       sync.Mutex
+	keys     []string
+	disabled bool
+}
+
+func (c *recordingCache) Disabled(ctx context.Context) bool {
+	return c.disabled || c.FileCache.Disabled(ctx)
+}
+
+func (c *recordingCache) Get(ctx context.Context, arg cache.Item) (*cache.CachedStream, error) {
+	c.mu.Lock()
+	c.keys = append(c.keys, arg.Key())
+	c.mu.Unlock()
+	return c.FileCache.Get(ctx, arg)
+}
+
+func (c *recordingCache) getKeys() []string {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return slices.Clone(c.keys)
+}
+
+// Simulates a concurrent Enqueue between DequeueBatch and the worker's delete, so
+// DeleteIfUnchanged on the dequeued value no-ops.
+type reenqueueOnDequeue struct {
+	*tests.MockArtworkQueueRepo
+	done bool
+}
+
+func (r *reenqueueOnDequeue) DequeueBatch(n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
+	items, err := r.MockArtworkQueueRepo.DequeueBatch(n, kinds...)
+	if !r.done && len(items) > 0 {
+		r.done = true
+		for k, it := range r.Data {
+			if it.ItemKind == items[0].ItemKind && it.ItemID == items[0].ItemID {
+				it.RetryAt = items[0].RetryAt.Add(time.Minute)
+				r.Data[k] = it
+			}
+		}
+	}
+	return items, err
+}
+
+type fakeEventBroker struct {
+	http.Handler
+	mu     sync.Mutex
+	events []events.Event
+}
+
+func (f *fakeEventBroker) SendMessage(_ context.Context, event events.Event) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.events = append(f.events, event)
+}
+
+func (f *fakeEventBroker) SendBroadcastMessage(_ context.Context, event events.Event) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.events = append(f.events, event)
+}
+
+func (f *fakeEventBroker) getEvents() []events.Event {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return slices.Clone(f.events)
+}
+
+var _ events.Broker = (*fakeEventBroker)(nil)
+
+func findQueued(q *tests.MockArtworkQueueRepo, kind, id string) *model.ArtworkQueueItem {
+	for _, it := range q.Data {
+		if it.ItemKind == kind && it.ItemID == id {
+			return &it
+		}
+	}
+	return nil
+}
+
+var _ = Describe("Worker", func() {
+	var (
+		ctx        context.Context
+		ds         *tests.MockDataStore
+		folderRepo *fakeFolderRepo
+		libRepo    *tests.MockLibraryRepo
+		ffm        *tests.MockFFmpeg
+		ag         *agents.Agents
+		store      *ImageStore
+		artRepo    *tests.MockArtworkRepo
+		queueRepo  *tests.MockArtworkQueueRepo
+		broker     *fakeEventBroker
+		imgCache   *recordingCache
+		repoRoot   string
+		w          *Worker
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		ctx = context.Background()
+		var err error
+		repoRoot, err = os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		conf.Server.CacheFolder = conf.NewDir(GinkgoT().TempDir())
+
+		folderRepo = &fakeFolderRepo{}
+		libRepo = &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		ffm = tests.NewMockFFmpeg("")
+		ag = agents.GetAgents(&tests.MockDataStore{}, nil)
+		artRepo = tests.CreateMockArtworkRepo()
+		queueRepo = tests.CreateMockArtworkQueueRepo()
+		ds = &tests.MockDataStore{
+			MockedFolder:       folderRepo,
+			MockedLibrary:      libRepo,
+			MockedArtwork:      artRepo,
+			MockedArtworkQueue: queueRepo,
+		}
+		ds.MockedAlbum = tests.CreateMockAlbumRepo()
+		store = NewImageStore(GinkgoT().TempDir())
+		conf.Server.CoverArtPriority = "cover.jpg, embedded"
+		conf.Server.DevArtworkExternalMaxRPS = 1000 // keep the limiter out of the way of behavior tests
+		broker = &fakeEventBroker{}
+		imgCache = &recordingCache{FileCache: cache.NewFileCache("WorkerTest", "100MB", "images", 0,
+			func(ctx context.Context, arg cache.Item) (io.Reader, error) {
+				return arg.(artworkReader).Reader(ctx)
+			})}
+		Eventually(func() bool { return imgCache.Available(ctx) }).Should(BeTrue())
+		w = NewWorker(ds, store, ag, ffm, broker, imgCache)
+	})
+
+	Describe("drain", func() {
+		It("processes a seeded queue item and removes it from the queue", func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				ItemKind: "al", ItemID: "al1", Priority: model.ArtworkPriorityScan,
+			})).To(Succeed())
+
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Source).To(Equal("folder"))
+
+			count, err := queueRepo.Count()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(count).To(BeZero(), "a found item must be deleted from the queue")
+		})
+
+		It("processes an mf queue item, writing state and storing embedded bytes", func() {
+			conf.Server.EnableMediaFileCoverArt = true
+			ds.MockedMediaFile = tests.CreateMockMediaFileRepo()
+			ds.MockedMediaFile.(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+				{ID: "mf1", LibraryID: 0, Path: "tests/fixtures/artist/an-album/test.mp3", HasCoverArt: true},
+			})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				ItemKind: "mf", ItemID: "mf1", Priority: model.ArtworkPriorityBump,
+			})).To(Succeed())
+
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			ia, err := artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Source).To(Equal("embedded"))
+			Expect(ia.Hash).ToNot(BeEmpty())
+
+			art, err := artRepo.GetImage(ia.Hash)
+			Expect(err).ToNot(HaveOccurred())
+			r, err := store.Open(ia.Hash, art.Mime)
+			Expect(err).ToNot(HaveOccurred())
+			defer r.Close()
+			data, err := io.ReadAll(r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(data).ToNot(BeEmpty(), "embedded bytes must be written to the store")
+
+			count, err := queueRepo.Count()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(count).To(BeZero())
+		})
+
+		It("reschedules a failed item via MarkFailed with a backed-off retry_at", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al4", Name: "Album"}})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})).To(Succeed())
+
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			it := findQueued(queueRepo, "al", "al4")
+			Expect(it).ToNot(BeNil())
+			Expect(it.Attempts).To(Equal(1))
+			Expect(it.RetryAt).To(BeTemporally(">", time.Now()))
+
+			_, err = artRepo.GetItemArtwork(model.KindAlbumArtwork, "al4", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound), "a timeout must never settle on absent")
+		})
+
+		It("reschedules a found-stale item via MarkFailed while keeping its served state", func() {
+			conf.Server.CoverArtPriority = "external, cover.jpg"
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "alstale", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "alstale"})).To(Succeed())
+
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			it := findQueued(queueRepo, "al", "alstale")
+			Expect(it).ToNot(BeNil(), "a found-stale row must survive for a higher-priority retry")
+			Expect(it.Attempts).To(Equal(1))
+			Expect(it.RetryAt).To(BeTemporally(">", time.Now()))
+
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alstale", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Source).To(Equal("folder"), "the fallback art is served meanwhile")
+
+			evts := broker.getEvents()
+			Expect(evts).To(HaveLen(1), "the served fallback art must live-refresh the UI")
+			Expect(evts[0].(*events.RefreshResource).Data(evts[0])).To(ContainSubstring("alstale"))
+		})
+
+		It("keeps a row re-enqueued between dequeue and delete", func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al7", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+			racing := &reenqueueOnDequeue{MockArtworkQueueRepo: queueRepo}
+			ds.MockedArtworkQueue = racing
+			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				ItemKind: "al", ItemID: "al7", Priority: model.ArtworkPriorityScan,
+			})).To(Succeed())
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			// The concurrent re-enqueue changed retry_at, so the found-path delete was a no-op.
+			Expect(findQueued(queueRepo, "al", "al7")).ToNot(BeNil())
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al7", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Source).To(Equal("folder"))
+		})
+
+		It("keeps a fresh re-enqueue ahead of a stale failure backoff", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al8", Name: "Album"}})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			racing := &reenqueueOnDequeue{MockArtworkQueueRepo: queueRepo}
+			ds.MockedArtworkQueue = racing
+			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al8"})).To(Succeed())
+			dequeued := findQueued(queueRepo, "al", "al8").RetryAt
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			// The re-enqueue reset retry_at; the failure path must not stomp it nor bump attempts.
+			it := findQueued(queueRepo, "al", "al8")
+			Expect(it).ToNot(BeNil())
+			Expect(it.Attempts).To(BeZero())
+			Expect(it.RetryAt).To(BeTemporally("==", dequeued.Add(time.Minute)))
+		})
+
+		It("gives up and settles absent once the retry budget is exhausted", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al9", Name: "Album"}})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al9"})).To(Succeed())
+			// Age the row past the retry budget.
+			for k, v := range queueRepo.Data {
+				if v.ItemID == "al9" {
+					v.EnqueuedAt = time.Now().Add(-(giveUpAfter + time.Hour))
+					queueRepo.Data[k] = v
+				}
+			}
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			Expect(findQueued(queueRepo, "al", "al9")).To(BeNil())
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al9", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Hash).To(BeEmpty())
+		})
+
+		It("keeps already-served art when the retry budget is exhausted", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al10", Name: "Album"}})
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al10", ImageType: model.ImageTypePrimary,
+				Hash: "cafebabe", Source: "external:lastfm",
+			})).To(Succeed())
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al10"})).To(Succeed())
+			for k, v := range queueRepo.Data {
+				if v.ItemID == "al10" {
+					v.EnqueuedAt = time.Now().Add(-(giveUpAfter + time.Hour))
+					queueRepo.Data[k] = v
+				}
+			}
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			Expect(findQueued(queueRepo, "al", "al10")).To(BeNil())
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al10", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Hash).To(Equal("cafebabe"), "a persistent outage must not discard served art")
+		})
+
+		// Media files are excluded from recheckKinds, so an absent row here would never be
+		// revisited: a transient read error would look permanent.
+		It("does not settle absent on exhaustion for a kind with no recheck path", func() {
+			conf.Server.EnableMediaFileCoverArt = true
+			ds.MockedMediaFile = tests.CreateMockMediaFileRepo()
+			ds.MockedMediaFile.(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+				{ID: "mfX", LibraryID: 0, Path: "tests/fixtures/artist/an-album/gone.mp3", HasCoverArt: true},
+			})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mfX"})).To(Succeed())
+			for k, v := range queueRepo.Data {
+				if v.ItemID == "mfX" {
+					v.EnqueuedAt = time.Now().Add(-(giveUpAfter + time.Hour))
+					queueRepo.Data[k] = v
+				}
+			}
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			Expect(findQueued(queueRepo, "mf", "mfX")).To(BeNil(), "the row must stop retrying")
+			_, err = artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mfX", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound),
+				"no row leaves the track unresolved, so a later view can still recover it")
+		})
+
+		It("resolves a private playlist under an admin context instead of failing forever", func() {
+			ds.MockedUser = adminUserRepo()
+			vds := &visibilityPlaylistDS{
+				MockDataStore: ds,
+				private:       model.Playlist{ID: "plPriv", OwnerID: "admin"},
+				tracks:        &tests.MockPlaylistTrackRepo{},
+			}
+			w = NewWorker(vds, store, ag, ffm, broker, imgCache)
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plPriv"})).To(Succeed())
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			Expect(findQueued(queueRepo, "pl", "plPriv")).To(BeNil())
+			ia, err := artRepo.GetItemArtwork(model.KindPlaylistArtwork, "plPriv", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Hash).To(BeEmpty())
+		})
+
+		It("returns zero when the queue is empty", func() {
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(BeZero())
+		})
+
+		It("broadcasts a single refresh event for the found items in a batch", func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al1", Name: "Album 1", FolderIDs: []string{"f1"}},
+				{ID: "al2", Name: "Album 2", FolderIDs: []string{"f1"}},
+			})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1", Priority: model.ArtworkPriorityScan})).To(Succeed())
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2", Priority: model.ArtworkPriorityScan})).To(Succeed())
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar1", Priority: model.ArtworkPriorityScan})).To(Succeed())
+
+			n, err := w.drain(ctx, 3)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(3))
+
+			evts := broker.getEvents()
+			Expect(evts).To(HaveLen(1), "exactly one coalesced event per drain batch")
+			rr, ok := evts[0].(*events.RefreshResource)
+			Expect(ok).To(BeTrue())
+			data := rr.Data(rr)
+			Expect(data).To(ContainSubstring(`"album"`))
+			Expect(data).To(ContainSubstring("al1"))
+			Expect(data).To(ContainSubstring("al2"))
+			Expect(data).ToNot(ContainSubstring("artist"), "a failed (unresolved) artist must not be refreshed")
+			Expect(data).ToNot(ContainSubstring("ar1"))
+		})
+
+		DescribeTable("only lists the kinds it actually resolved",
+			func(kinds []string, wantSong bool) {
+				items := slice.Map(kinds, func(k string) model.ArtworkQueueItem {
+					return model.ArtworkQueueItem{ItemKind: k, ItemID: k + "1"}
+				})
+				w.broadcastRefresh(ctx, items)
+
+				evts := broker.getEvents()
+				Expect(evts).To(HaveLen(1))
+				data := evts[0].(*events.RefreshResource).Data(evts[0])
+				if wantSong {
+					Expect(data).To(ContainSubstring(`"song"`))
+				} else {
+					Expect(data).ToNot(ContainSubstring(`"song"`))
+				}
+			},
+			// An album's tracks inherit its art, but the dependent ids are unbounded: the client
+			// fans an album refresh out to the tracks it has loaded.
+			Entry("album alone does not name songs", []string{"al"}, false),
+			Entry("artist alone does not", []string{"ar"}, false),
+			Entry("playlist alone does not", []string{"pl"}, false),
+			Entry("album mixed with others still does not", []string{"ar", "al"}, false),
+			Entry("songs resolving on their own are listed by id", []string{"mf"}, true),
+		)
+
+		It("broadcasts a refresh when an item resolves to absent (removed cover)", func() {
+			conf.Server.CoverArtPriority = "cover.*" // local-only; no folder image → absent
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al3", Name: "Artless"}})
+			folderRepo.result = nil
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3", Priority: model.ArtworkPriorityScan})).To(Succeed())
+
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			evts := broker.getEvents()
+			Expect(evts).To(HaveLen(1), "a removed cover must live-refresh clients so they drop it")
+			Expect(evts[0].(*events.RefreshResource).Data(evts[0])).To(ContainSubstring("al3"))
+
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Hash).To(BeEmpty(), "the outcome was absent, not found")
+		})
+
+		It("does not broadcast when no item is found", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alx", Name: "Album"}})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "alx"})).To(Succeed())
+
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			Expect(broker.getEvents()).To(BeEmpty(), "a drain with no found items sends no event")
+		})
+	})
+
+	Describe("gate/breaker", func() {
+		It("opens after 5 consecutive external errors and short-circuits the step", func() {
+			var calls int
+			failing := func() (io.ReadCloser, string, error) {
+				calls++
+				return nil, "", errors.New("boom")
+			}
+			for range 5 {
+				_, _, err := w.gate("A", failing)
+				Expect(err).To(HaveOccurred())
+			}
+			Expect(calls).To(Equal(5))
+
+			_, _, err := w.gate("A", failing)
+			Expect(err).To(MatchError(errBreakerOpen))
+			Expect(calls).To(Equal(5), "an open breaker must not call the external step")
+		})
+
+		It("resets the failure count on a successful call", func() {
+			failing := func() (io.ReadCloser, string, error) { return nil, "", errors.New("boom") }
+			ok := func() (io.ReadCloser, string, error) { return io.NopCloser(nil), "p", nil }
+			for range 4 {
+				_, _, _ = w.gate("A", failing)
+			}
+			_, _, err := w.gate("A", ok)
+			Expect(err).ToNot(HaveOccurred())
+
+			var calls int
+			counting := func() (io.ReadCloser, string, error) {
+				calls++
+				return nil, "", errors.New("boom")
+			}
+			for range 5 {
+				_, _, _ = w.gate("A", counting)
+			}
+			Expect(calls).To(Equal(5), "the breaker should have re-closed after the success")
+		})
+
+		It("does not open the breaker on a run of agent not-found misses", func() {
+			// agents.ErrNotFound is a definitive miss, not a fault: artless items must not
+			// trip the breaker, or they would loop in retry instead of settling absent.
+			notFound := func() (io.ReadCloser, string, error) { return nil, "", agents.ErrNotFound }
+			for range breakerThreshold + 3 {
+				_, _, err := w.gate("A", notFound)
+				Expect(err).To(MatchError(agents.ErrNotFound), "a miss passes through, never errBreakerOpen")
+			}
+
+			var calls int
+			counting := func() (io.ReadCloser, string, error) {
+				calls++
+				return nil, "", errors.New("boom")
+			}
+			_, _, _ = w.gate("A", counting)
+			Expect(calls).To(Equal(1), "the breaker stayed closed, so the step still runs")
+		})
+
+		It("isolates each agent's breaker: one open gate does not block another", func() {
+			failing := func() (io.ReadCloser, string, error) { return nil, "", errors.New("boom") }
+			for range breakerThreshold {
+				_, _, _ = w.gate("A", failing)
+			}
+			_, _, err := w.gate("A", failing)
+			Expect(err).To(MatchError(errBreakerOpen), "agent A's breaker is open")
+
+			var bCalls int
+			bStep := func() (io.ReadCloser, string, error) {
+				bCalls++
+				return io.NopCloser(nil), "p", nil
+			}
+			for range breakerThreshold + 2 {
+				_, _, err := w.gate("B", bStep)
+				Expect(err).ToNot(HaveOccurred(), "agent B keeps being called while A is open")
+			}
+			Expect(bCalls).To(Equal(breakerThreshold + 2))
+		})
+	})
+
+	Describe("precache", func() {
+		BeforeEach(func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "alpc", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+			conf.Server.UICoverArtSize = 300
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				ItemKind: "al", ItemID: "alpc", Priority: model.ArtworkPriorityScan,
+			})).To(Succeed())
+		})
+
+		It("warms the resize cache at the UI cover size after a found acquisition", func() {
+			conf.Server.EnableArtworkPrecache = true
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			// The list surfaces request square covers, so warming any other key is wasted work.
+			Expect(imgCache.getKeys()).To(ContainElement(ContainSubstring(".300.true.")))
+		})
+
+		It("skips warming when precache is disabled", func() {
+			conf.Server.EnableArtworkPrecache = false
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			Expect(imgCache.getKeys()).To(BeEmpty())
+		})
+
+		// It warms from the bytes acquisition already held, so no state row or store file is needed.
+		It("warms from the acquired bytes without reading them back", func() {
+			conf.Server.EnableArtworkPrecache = true
+			ia := &model.ItemArtwork{
+				ItemKind: "al", ItemID: "unpersisted", ImageType: model.ImageTypePrimary,
+				Hash: "abcdef0123456789", UpdatedAt: time.Now(),
+			}
+
+			data, err := os.ReadFile("tests/fixtures/artist/an-album/cover.jpg")
+			Expect(err).ToNot(HaveOccurred())
+
+			w.precache(ctx, &acquired{ia: ia, mime: "image/jpeg", data: data})
+
+			// Nothing backs that hash on disk, so a hit can only come from the bytes handed in;
+			// the probe refuses to open, proving nothing is re-read.
+			probe := &resizedItem{
+				hash: ia.Hash, size: 300, square: true, ffmpeg: ffm,
+				open: func() (io.ReadCloser, error) { return nil, errors.New("precache must not re-read the source") },
+			}
+			stream, err := imgCache.Get(ctx, probe)
+			Expect(err).ToNot(HaveOccurred())
+			defer stream.Close()
+			Expect(io.ReadAll(stream)).ToNot(BeEmpty())
+		})
+	})
+
+	Describe("drain pools", func() {
+		// A kind in neither pool is never dequeued, with nothing to catch it at compile time.
+		It("covers every kind the worker can process, exactly once", func() {
+			var pooled []string
+			for _, p := range newDrainPools() {
+				pooled = append(pooled, p.kinds...)
+			}
+			for kind := range artworkKindToResource {
+				Expect(pooled).To(ContainElement(kind.Prefix()), "kind %q belongs to no drain pool", kind.Prefix())
+			}
+			Expect(pooled).To(HaveLen(len(artworkKindToResource)), "a kind is claimed by more than one pool")
+		})
+
+		// Artists resolve through a rate-limited agent that holds its slot while waiting, so one
+		// shared pool would park every album behind them.
+		It("resolves albums while artists are stuck on a slow agent", func() {
+			conf.Server.CoverArtPriority = "cover.jpg"
+			conf.Server.ArtistArtPriority = "external"
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alx", Name: "Album", FolderIDs: []string{"f1"}}})
+			ds.MockedArtist = tests.CreateMockArtistRepo()
+
+			// Every artist lookup blocks until released, standing in for the rate limiter.
+			block := make(chan struct{})
+			artists := model.Artists{}
+			for i := range 8 {
+				artists = append(artists, model.Artist{ID: fmt.Sprintf("arx%d", i), Name: "A"})
+			}
+			ds.MockedArtist.(*tests.MockArtistRepo).SetData(artists)
+			imageAgents(&fakeImageAgent{name: "slowAgent", block: block})
+
+			// Artists first, exactly as Backfill orders them.
+			for _, a := range artists {
+				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+					ItemKind: "ar", ItemID: a.ID, Priority: model.ArtworkPriorityBackfill,
+				})).To(Succeed())
+			}
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				ItemKind: "al", ItemID: "alx", Priority: model.ArtworkPriorityBackfill,
+			})).To(Succeed())
+
+			runCtx, cancel := context.WithCancel(ctx)
+			done := make(chan struct{})
+			go func() { defer close(done); _ = w.Run(runCtx) }()
+			// Join Run: a leaked pool goroutine would race the config snapshot Ginkgo restores.
+			DeferCleanup(func() {
+				cancel()
+				close(block) // unpark the blocked lookups so the pools can unwind
+				<-done
+			})
+
+			Eventually(func() bool {
+				ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alx", model.ImageTypePrimary)
+				return err == nil && ia.Hash != ""
+			}, 5*time.Second, 50*time.Millisecond).Should(BeTrue(),
+				"a blocked external pool must not hold up local artwork")
+
+			_, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "arx0", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound), "artists are still blocked, as intended")
+		})
+	})
+
+	Describe("batching", func() {
+		It("leaves undispatched items queued when cancelled mid-batch", func() {
+			for i := range 8 {
+				id := fmt.Sprintf("alc%d", i)
+				ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: id, Name: "Album"}})
+				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+					ItemKind: "al", ItemID: id, Priority: model.ArtworkPriorityScan,
+				})).To(Succeed())
+			}
+			cancelledCtx, cancel := context.WithCancel(ctx)
+			cancel()
+
+			_, err := w.drain(cancelledCtx, 1)
+			Expect(err).ToNot(HaveOccurred())
+
+			for i := range 8 {
+				id := fmt.Sprintf("alc%d", i)
+				Expect(findQueued(queueRepo, "al", id)).ToNot(BeNil(), "row "+id+" must survive a cancelled drain")
+			}
+		})
+
+		It("dequeues past the worker pool so one drain covers many items", func() {
+			for i := range 16 {
+				ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: fmt.Sprintf("alb%d", i), Name: "Album"}})
+				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+					ItemKind: "al", ItemID: fmt.Sprintf("alb%d", i), Priority: model.ArtworkPriorityScan,
+				})).To(Succeed())
+			}
+
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(16), "a batch sized to the pool would have stopped at 4")
+		})
+	})
+
+	Describe("RunPrune", func() {
+		It("runs a prune under the worker mutex", func() {
+			Expect(w.RunPrune(ctx)).To(Succeed())
+		})
+	})
+
+	Describe("Run", func() {
+		It("exits cleanly when the context is cancelled", func() {
+			runCtx, cancel := context.WithCancel(ctx)
+			done := make(chan error, 1)
+			go func() { done <- w.Run(runCtx) }()
+
+			cancel()
+			Eventually(done, time.Second).Should(Receive(BeNil()))
+		})
+
+		It("does not leak goroutines after Run exits", func() {
+			DeferCleanup(configtest.SetupConfig())
+
+			ignore := goleak.IgnoreCurrent()
+			DeferCleanup(func() { goleak.VerifyNone(GinkgoT(), ignore) })
+
+			localDS := &tests.MockDataStore{MockedArtworkQueue: tests.CreateMockArtworkQueueRepo()}
+			lw := NewWorker(localDS, NewImageStore(GinkgoT().TempDir()), agents.GetAgents(localDS, nil), tests.NewMockFFmpeg(""), &fakeEventBroker{}, imgCache)
+
+			runCtx, cancel := context.WithCancel(ctx)
+			done := make(chan error, 1)
+			go func() { done <- lw.Run(runCtx) }()
+
+			time.Sleep(20 * time.Millisecond) // let the loop settle on the idle select
+			cancel()
+			Eventually(done, 2*time.Second).Should(Receive(BeNil()))
+		})
+	})
+})
+
+var _ = Describe("backoff", func() {
+	It("returns the expected schedule with no jitter", func() {
+		for _, c := range []struct {
+			attempts int
+			want     time.Duration
+		}{
+			{0, 5 * time.Second},
+			{1, 20 * time.Second},
+			{2, 80 * time.Second},
+			{3, 320 * time.Second},
+			{4, 1280 * time.Second},
+			{5, 5120 * time.Second},
+			{6, 20480 * time.Second},
+			{7, 12 * time.Hour},
+			{8, 12 * time.Hour},
+		} {
+			Expect(backoffFor(c.attempts, 0)).To(Equal(c.want), "attempt %d", c.attempts)
+		}
+	})
+
+	It("applies jitter proportionally", func() {
+		base := backoffFor(2, 0)
+		Expect(backoffFor(2, 0.2)).To(Equal(time.Duration(float64(base) * 1.2)))
+		Expect(backoffFor(2, -0.2)).To(Equal(time.Duration(float64(base) * 0.8)))
+	})
+
+	It("keeps random jitter within +/-40%", func() {
+		lo := time.Duration(float64(320*time.Second) * 0.6)
+		hi := time.Duration(float64(320*time.Second) * 1.4)
+		for range 200 {
+			d := backoff(3)
+			Expect(d).To(BeNumerically(">=", lo))
+			Expect(d).To(BeNumerically("<=", hi))
+		}
+	})
+})
diff --git a/core/artwork/worker_timing_test.go b/core/artwork/worker_timing_test.go
new file mode 100644
index 000000000..f7315b20a
--- /dev/null
+++ b/core/artwork/worker_timing_test.go
@@ -0,0 +1,76 @@
+package artwork
+
+import (
+	"errors"
+	"io"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/gomega"
+)
+
+// Drives the real breaker state machine with the fake clock. Plain test: testing/synctest
+// needs a *testing.T, which Ginkgo doesn't give.
+func TestArtworkBreakerHalfOpen(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		g := NewWithT(t)
+		b := newBreaker()
+
+		for range breakerThreshold {
+			b.record("agentA", errors.New("boom"))
+		}
+		g.Expect(b.allow()).To(BeFalse(), "breaker opens after consecutive errors")
+
+		time.Sleep(breakerProbeAfter - time.Nanosecond)
+		g.Expect(b.allow()).To(BeFalse(), "still open before the probe interval")
+
+		time.Sleep(time.Nanosecond)
+		g.Expect(b.allow()).To(BeTrue(), "half-open: one probe is granted")
+		g.Expect(b.allow()).To(BeFalse(), "only a single probe per interval")
+
+		b.record("agentA", errors.New("boom")) // probe fails -> stay open
+		time.Sleep(breakerProbeAfter)
+		g.Expect(b.allow()).To(BeTrue(), "another probe after the next interval")
+
+		b.record("agentA", nil) // probe succeeds -> close
+		g.Expect(b.allow()).To(BeTrue(), "closed breaker admits freely")
+		g.Expect(b.allow()).To(BeTrue())
+	})
+}
+
+func TestArtworkGatePerAgentBreakerIsolation(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		g := NewWithT(t)
+		w := NewWorker(&tests.MockDataStore{}, NewImageStore(t.TempDir()),
+			agents.GetAgents(&tests.MockDataStore{}, nil), tests.NewMockFFmpeg(""), &fakeEventBroker{}, nil)
+
+		fail := func() (io.ReadCloser, string, error) { return nil, "", errors.New("boom") }
+		for range breakerThreshold {
+			_, _, _ = w.gate("A", fail)
+		}
+		_, _, err := w.gate("A", fail)
+		g.Expect(err).To(MatchError(errBreakerOpen), "A opens after consecutive errors")
+
+		// B has its own breaker, untouched by A being open.
+		var bCalls int
+		bStep := func() (io.ReadCloser, string, error) { bCalls++; return nil, "", errors.New("boom") }
+		for range breakerThreshold - 1 {
+			_, _, err := w.gate("B", bStep)
+			g.Expect(err).To(MatchError("boom"))
+		}
+		g.Expect(bCalls).To(Equal(breakerThreshold-1), "B keeps being called while A is open")
+
+		// After the probe window, A admits exactly one probe again.
+		time.Sleep(breakerProbeAfter)
+		var aCalls int
+		aFail := func() (io.ReadCloser, string, error) { aCalls++; return nil, "", errors.New("boom") }
+		_, _, _ = w.gate("A", aFail)
+		g.Expect(aCalls).To(Equal(1), "A grants a single probe after the interval")
+		_, _, err = w.gate("A", aFail)
+		g.Expect(err).To(MatchError(errBreakerOpen), "the probe failed, so A stays open")
+		g.Expect(aCalls).To(Equal(1))
+	})
+}
diff --git a/core/external/provider.go b/core/external/provider.go
index 869841e06..efd061c0c 100644
--- a/core/external/provider.go
+++ b/core/external/provider.go
@@ -4,7 +4,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"net/url"
 	"sort"
 	"strings"
 	"time"
@@ -35,8 +34,6 @@ type Provider interface {
 	UpdateArtistInfo(ctx context.Context, id string, count int, includeNotPresent bool) (*model.Artist, error)
 	SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error)
 	TopSongs(ctx context.Context, artist, artistId string, count int) (model.MediaFiles, error)
-	ArtistImage(ctx context.Context, id string) (*url.URL, error)
-	AlbumImage(ctx context.Context, id string) (*url.URL, error)
 }
 
 type provider struct {
@@ -258,7 +255,7 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 	// Call all registered agents and collect information
 	g := errgroup.Group{}
 	g.SetLimit(2)
-	g.Go(func() error { e.callGetImage(ctx, e.ag, &artist); return nil })
+	g.Go(func() error { _ = e.callGetImage(ctx, e.ag, &artist); return nil })
 	g.Go(func() error { e.callGetBiography(ctx, e.ag, &artist); return nil })
 	g.Go(func() error { e.callGetURL(ctx, e.ag, &artist); return nil })
 	g.Go(func() error { e.callGetSimilarArtists(ctx, e.ag, &artist, maxSimilarArtists, true); return nil })
@@ -370,76 +367,6 @@ func (e *provider) similarSongsFallback(ctx context.Context, id string, count in
 	return similarSongs, nil
 }
 
-func (e *provider) ArtistImage(ctx context.Context, id string) (*url.URL, error) {
-	artist, err := e.getArtist(ctx, id)
-	if err != nil {
-		return nil, 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)
-		}
-	}
-
-	if imageUrl == "" {
-		return nil, model.ErrNotFound
-	}
-	return url.Parse(imageUrl)
-}
-
-func (e *provider) AlbumImage(ctx context.Context, id string) (*url.URL, error) {
-	album, err := e.getAlbum(ctx, id)
-	if err != nil {
-		return nil, err
-	}
-
-	albumName := album.Name()
-	images, err := e.ag.GetAlbumImages(ctx, albumName, album.AlbumArtist, album.MbzAlbumID)
-	if err != nil {
-		switch {
-		case errors.Is(err, agents.ErrNotFound):
-			log.Trace(ctx, "Album not found in agent", "albumID", id, "name", albumName, "artist", album.AlbumArtist)
-			return nil, model.ErrNotFound
-		case errors.Is(err, context.Canceled):
-			log.Debug(ctx, "GetAlbumImages call canceled", err)
-		default:
-			log.Warn(ctx, "Error getting album images from agent", "albumID", id, "name", albumName, "artist", album.AlbumArtist, err)
-		}
-		return nil, err
-	}
-
-	if len(images) == 0 {
-		log.Warn(ctx, "Agent returned no images without error", "albumID", id, "name", albumName, "artist", album.AlbumArtist)
-		return nil, model.ErrNotFound
-	}
-
-	// Return the biggest image
-	var img agents.ExternalImage
-	for _, i := range images {
-		if img.Size <= i.Size {
-			img = i
-		}
-	}
-	if img.URL == "" {
-		return nil, model.ErrNotFound
-	}
-	return url.Parse(img.URL)
-}
-
 func (e *provider) TopSongs(ctx context.Context, artistName, id string, count int) (model.MediaFiles, error) {
 	artist, err := e.findArtist(ctx, artistName, id)
 	if err != nil {
@@ -524,10 +451,15 @@ func (e *provider) callGetBiography(ctx context.Context, agent agents.ArtistBiog
 	artist.Biography = strings.ReplaceAll(bio, "<a ", "<a target='_blank' ")
 }
 
-func (e *provider) callGetImage(ctx context.Context, agent agents.ArtistImageRetriever, artist *auxArtist) {
+// callGetImage populates artist's image URLs. A transient agent failure is
+// returned as-is; a definitive "no image" is normalized to model.ErrNotFound.
+func (e *provider) callGetImage(ctx context.Context, agent agents.ArtistImageRetriever, artist *auxArtist) error {
 	images, err := agent.GetArtistImages(ctx, artist.ID, artist.Name(), artist.MbzArtistID)
 	if err != nil {
-		return
+		if errors.Is(err, agents.ErrNotFound) {
+			return model.ErrNotFound
+		}
+		return err
 	}
 	sort.Slice(images, func(i, j int) bool { return images[i].Size > images[j].Size })
 
@@ -540,6 +472,7 @@ func (e *provider) callGetImage(ctx context.Context, agent agents.ArtistImageRet
 	if len(images) >= 3 {
 		artist.SmallImageUrl = images[2].URL
 	}
+	return nil
 }
 
 func (e *provider) callGetSimilarArtists(ctx context.Context, agent agents.ArtistSimilarRetriever, artist *auxArtist,
diff --git a/core/external/provider_albumimage_test.go b/core/external/provider_albumimage_test.go
deleted file mode 100644
index e801b7cce..000000000
--- a/core/external/provider_albumimage_test.go
+++ /dev/null
@@ -1,365 +0,0 @@
-package external_test
-
-import (
-	"context"
-	"errors"
-	"net/url"
-
-	"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"
-	. "github.com/onsi/gomega"
-	"github.com/stretchr/testify/mock"
-)
-
-var _ = Describe("Provider - AlbumImage", func() {
-	var ds *tests.MockDataStore
-	var provider Provider
-	var mockArtistRepo *mockArtistRepo
-	var mockAlbumRepo *mockAlbumRepo
-	var mockMediaFileRepo *mockMediaFileRepo
-	var mockAlbumAgent *mockAlbumInfoAgent
-	var ctx context.Context
-
-	BeforeEach(func() {
-		ctx = GinkgoT().Context()
-		DeferCleanup(configtest.SetupConfig())
-		conf.Server.Agents = "mockAlbum" // Configure mock agent
-
-		mockArtistRepo = newMockArtistRepo()
-		mockAlbumRepo = newMockAlbumRepo()
-		mockMediaFileRepo = newMockMediaFileRepo()
-
-		ds = &tests.MockDataStore{
-			MockedArtist:    mockArtistRepo,
-			MockedAlbum:     mockAlbumRepo,
-			MockedMediaFile: mockMediaFileRepo,
-		}
-
-		mockAlbumAgent = newMockAlbumInfoAgent()
-
-		agentsCombined := &mockAgents{albumInfoAgent: mockAlbumAgent}
-		provider = NewProvider(ds, agentsCombined, matcher.New(ds))
-
-		// Default mocks
-		// Mocks for GetEntityByID sequence (initial failed lookups)
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
-		mockArtistRepo.On("Get", "mf-1").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "mf-1").Return(nil, model.ErrNotFound).Once()
-
-		// Default mock for non-existent entities - Use Maybe() for flexibility
-		mockArtistRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Maybe()
-		mockAlbumRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Maybe()
-		mockMediaFileRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Maybe()
-	})
-
-	It("returns the largest image URL when successful", func() {
-		// Arrange
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once() // Expect GetEntityByID sequence
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Once()
-		// Explicitly mock agent call for this test
-		mockAlbumAgent.On("GetAlbumImages", ctx, "Album One", "", "").
-			Return([]agents.ExternalImage{
-				{URL: "http://example.com/large.jpg", Size: 1000},
-				{URL: "http://example.com/medium.jpg", Size: 500},
-				{URL: "http://example.com/small.jpg", Size: 200},
-			}, nil).Once()
-
-		expectedURL, _ := url.Parse("http://example.com/large.jpg")
-		imgURL, err := provider.AlbumImage(ctx, "album-1")
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL))
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "album-1") // From GetEntityByID
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockArtistRepo.AssertNotCalled(GinkgoT(), "Get", "artist-1")                       // Artist lookup no longer happens in getAlbum
-		mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, "Album One", "", "") // Expect empty artist name
-	})
-
-	It("returns ErrNotFound if the album is not found in the DB", func() {
-		// Arrange: Explicitly expect the full GetEntityByID sequence for "not-found"
-		mockArtistRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Once()
-		mockMediaFileRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Once()
-
-		imgURL, err := provider.AlbumImage(ctx, "not-found")
-
-		Expect(err).To(MatchError("data not found"))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "not-found")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "not-found")
-		mockMediaFileRepo.AssertCalled(GinkgoT(), "Get", "not-found")
-		mockAlbumAgent.AssertNotCalled(GinkgoT(), "GetAlbumImages", mock.Anything, mock.Anything, mock.Anything)
-	})
-
-	It("returns the agent error if the agent fails", func() {
-		// Arrange
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once() // Expect GetEntityByID sequence
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Once()
-
-		agentErr := errors.New("agent failure")
-		// Explicitly mock agent call for this test
-		mockAlbumAgent.On("GetAlbumImages", ctx, "Album One", "", "").Return(nil, agentErr).Once() // Expect empty artist
-
-		imgURL, err := provider.AlbumImage(ctx, "album-1")
-
-		Expect(err).To(MatchError("agent failure"))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockArtistRepo.AssertNotCalled(GinkgoT(), "Get", "artist-1")
-		mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, "Album One", "", "") // Expect empty artist
-	})
-
-	It("returns ErrNotFound if the agent returns ErrNotFound", func() {
-		// Arrange
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once() // Expect GetEntityByID sequence
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Once()
-
-		// Explicitly mock agent call for this test
-		mockAlbumAgent.On("GetAlbumImages", ctx, "Album One", "", "").Return(nil, agents.ErrNotFound).Once() // Expect empty artist
-
-		imgURL, err := provider.AlbumImage(ctx, "album-1")
-
-		Expect(err).To(MatchError("data not found"))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, "Album One", "", "") // Expect empty artist
-	})
-
-	It("returns ErrNotFound if the agent returns no images", func() {
-		// Arrange
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once() // Expect GetEntityByID sequence
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Once()
-
-		// Explicitly mock agent call for this test
-		mockAlbumAgent.On("GetAlbumImages", ctx, "Album One", "", "").
-			Return([]agents.ExternalImage{}, nil).Once() // Expect empty artist
-
-		imgURL, err := provider.AlbumImage(ctx, "album-1")
-
-		Expect(err).To(MatchError("data not found"))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, "Album One", "", "") // Expect empty artist
-	})
-
-	It("returns context error if context is canceled", func() {
-		// Arrange
-		cctx, cancelCtx := context.WithCancel(ctx)
-		// Mock the necessary DB calls *before* canceling the context
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Once()
-		// Expect the agent call even if context is cancelled, returning the context error
-		mockAlbumAgent.On("GetAlbumImages", cctx, "Album One", "", "").Return(nil, context.Canceled).Once()
-		// Cancel the context *before* calling the function under test
-		cancelCtx()
-
-		imgURL, err := provider.AlbumImage(cctx, "album-1")
-
-		Expect(err).To(MatchError("context canceled"))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		// Agent should now be called, verify this expectation
-		mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", cctx, "Album One", "", "")
-	})
-
-	It("derives album ID from MediaFile ID", func() {
-		// Arrange: Mock full GetEntityByID for "mf-1" and recursive "album-1"
-		mockArtistRepo.On("Get", "mf-1").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "mf-1").Return(nil, model.ErrNotFound).Once()
-		mockMediaFileRepo.On("Get", "mf-1").Return(&model.MediaFile{ID: "mf-1", Title: "Track One", ArtistID: "artist-1", AlbumID: "album-1"}, nil).Once()
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Once()
-
-		// Explicitly mock agent call for this test
-		mockAlbumAgent.On("GetAlbumImages", ctx, "Album One", "", "").
-			Return([]agents.ExternalImage{
-				{URL: "http://example.com/large.jpg", Size: 1000},
-				{URL: "http://example.com/medium.jpg", Size: 500},
-				{URL: "http://example.com/small.jpg", Size: 200},
-			}, nil).Once()
-
-		expectedURL, _ := url.Parse("http://example.com/large.jpg")
-		imgURL, err := provider.AlbumImage(ctx, "mf-1")
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL))
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "mf-1")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "mf-1")
-		mockMediaFileRepo.AssertCalled(GinkgoT(), "Get", "mf-1")
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockArtistRepo.AssertNotCalled(GinkgoT(), "Get", "artist-1")
-		mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, "Album One", "", "")
-	})
-
-	It("handles different image orders from agent", func() {
-		// Arrange
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once() // Expect GetEntityByID sequence
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Once()
-		// Explicitly mock agent call for this test
-		mockAlbumAgent.On("GetAlbumImages", ctx, "Album One", "", "").
-			Return([]agents.ExternalImage{
-				{URL: "http://example.com/small.jpg", Size: 200},
-				{URL: "http://example.com/large.jpg", Size: 1000},
-				{URL: "http://example.com/medium.jpg", Size: 500},
-			}, nil).Once()
-
-		expectedURL, _ := url.Parse("http://example.com/large.jpg")
-		imgURL, err := provider.AlbumImage(ctx, "album-1")
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL)) // Should still pick the largest
-		mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, "Album One", "", "")
-	})
-
-	It("handles agent returning only one image", func() {
-		// Arrange
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once() // Expect GetEntityByID sequence
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Once()
-		// Explicitly mock agent call for this test
-		mockAlbumAgent.On("GetAlbumImages", ctx, "Album One", "", "").
-			Return([]agents.ExternalImage{
-				{URL: "http://example.com/single.jpg", Size: 700},
-			}, nil).Once()
-
-		expectedURL, _ := url.Parse("http://example.com/single.jpg")
-		imgURL, err := provider.AlbumImage(ctx, "album-1")
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL))
-		mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, "Album One", "", "")
-	})
-
-	It("returns ErrNotFound if deriving album ID fails", func() {
-		// Arrange: Mock full GetEntityByID for "mf-no-album" and recursive "not-found"
-		mockArtistRepo.On("Get", "mf-no-album").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "mf-no-album").Return(nil, model.ErrNotFound).Once()
-		mockMediaFileRepo.On("Get", "mf-no-album").Return(&model.MediaFile{ID: "mf-no-album", Title: "Track No Album", ArtistID: "artist-1", AlbumID: "not-found"}, nil).Once()
-		mockArtistRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Once()
-		mockMediaFileRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Once()
-
-		imgURL, err := provider.AlbumImage(ctx, "mf-no-album")
-
-		Expect(err).To(MatchError("data not found"))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "mf-no-album")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "mf-no-album")
-		mockMediaFileRepo.AssertCalled(GinkgoT(), "Get", "mf-no-album")
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "not-found")
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "not-found")
-		mockMediaFileRepo.AssertCalled(GinkgoT(), "Get", "not-found")
-		mockAlbumAgent.AssertNotCalled(GinkgoT(), "GetAlbumImages", mock.Anything, mock.Anything, mock.Anything)
-	})
-
-	Context("Unicode handling in album names", func() {
-		var albumWithEnDash *model.Album
-		var expectedURL *url.URL
-
-		const (
-			originalAlbumName   = "Raising Hell–Deluxe" // Album name with en dash
-			normalizedAlbumName = "Raising Hell-Deluxe" // Normalized version with hyphen
-		)
-
-		BeforeEach(func() {
-			// Test with en dash (–) in album name
-			albumWithEnDash = &model.Album{ID: "album-endash", Name: originalAlbumName, AlbumArtistID: "artist-1"}
-			mockArtistRepo.Mock = mock.Mock{} // Reset default expectations
-			mockAlbumRepo.Mock = mock.Mock{}  // Reset default expectations
-			mockArtistRepo.On("Get", "album-endash").Return(nil, model.ErrNotFound).Once()
-			mockAlbumRepo.On("Get", "album-endash").Return(albumWithEnDash, nil).Once()
-
-			expectedURL, _ = url.Parse("http://example.com/album.jpg")
-
-			// Mock the album agent to return an image for the album
-			mockAlbumAgent.On("GetAlbumImages", ctx, mock.AnythingOfType("string"), "", "").
-				Return([]agents.ExternalImage{
-					{URL: "http://example.com/album.jpg", Size: 1000},
-				}, nil).Once()
-		})
-
-		When("DevPreserveUnicodeInExternalCalls is true", func() {
-			BeforeEach(func() {
-				conf.Server.DevPreserveUnicodeInExternalCalls = true
-			})
-
-			It("preserves Unicode characters in album names", func() {
-				// Act
-				imgURL, err := provider.AlbumImage(ctx, "album-endash")
-
-				// Assert
-				Expect(err).ToNot(HaveOccurred())
-				Expect(imgURL).To(Equal(expectedURL))
-				mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-endash")
-				// This is the key assertion: ensure the original Unicode name is used
-				mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, originalAlbumName, "", "")
-			})
-		})
-
-		When("DevPreserveUnicodeInExternalCalls is false", func() {
-			BeforeEach(func() {
-				conf.Server.DevPreserveUnicodeInExternalCalls = false
-			})
-
-			It("normalizes Unicode characters", func() {
-				// Act
-				imgURL, err := provider.AlbumImage(ctx, "album-endash")
-
-				// Assert
-				Expect(err).ToNot(HaveOccurred())
-				Expect(imgURL).To(Equal(expectedURL))
-				mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-endash")
-				// This assertion ensures the normalized name is used (en dash → hyphen)
-				mockAlbumAgent.AssertCalled(GinkgoT(), "GetAlbumImages", ctx, normalizedAlbumName, "", "")
-			})
-		})
-	})
-})
-
-// mockAlbumInfoAgent implementation
-type mockAlbumInfoAgent struct {
-	mock.Mock
-	agents.AlbumInfoRetriever
-	agents.AlbumImageRetriever
-}
-
-func newMockAlbumInfoAgent() *mockAlbumInfoAgent {
-	m := new(mockAlbumInfoAgent)
-	m.On("AgentName").Return("mockAlbum").Maybe()
-	return m
-}
-
-func (m *mockAlbumInfoAgent) AgentName() string {
-	args := m.Called()
-	return args.String(0)
-}
-
-func (m *mockAlbumInfoAgent) GetAlbumInfo(ctx context.Context, name, artist, mbid string) (*agents.AlbumInfo, error) {
-	args := m.Called(ctx, name, artist, mbid)
-	if args.Get(0) == nil {
-		return nil, args.Error(1)
-	}
-	return args.Get(0).(*agents.AlbumInfo), args.Error(1)
-}
-
-func (m *mockAlbumInfoAgent) GetAlbumImages(ctx context.Context, name, artist, mbid string) ([]agents.ExternalImage, error) {
-	args := m.Called(ctx, name, artist, mbid)
-	if args.Get(0) == nil {
-		return nil, args.Error(1)
-	}
-	return args.Get(0).([]agents.ExternalImage), args.Error(1)
-}
-
-// Ensure mockAgent implements the interfaces
-var _ agents.AlbumInfoRetriever = (*mockAlbumInfoAgent)(nil)
-var _ agents.AlbumImageRetriever = (*mockAlbumInfoAgent)(nil)
diff --git a/core/external/provider_artistimage_test.go b/core/external/provider_artistimage_test.go
deleted file mode 100644
index 79612d651..000000000
--- a/core/external/provider_artistimage_test.go
+++ /dev/null
@@ -1,426 +0,0 @@
-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"
-	. "github.com/onsi/gomega"
-	"github.com/stretchr/testify/mock"
-)
-
-var _ = Describe("Provider - ArtistImage", func() {
-	var ds *tests.MockDataStore
-	var provider Provider
-	var mockArtistRepo *mockArtistRepo
-	var mockAlbumRepo *mockAlbumRepo
-	var mockMediaFileRepo *mockMediaFileRepo
-	var mockImageAgent *mockArtistImageAgent
-	var agentsCombined *mockAgents
-	var ctx context.Context
-
-	BeforeEach(func() {
-		DeferCleanup(configtest.SetupConfig())
-		conf.Server.Agents = "mockImage" // Configure only the mock agent
-		ctx = GinkgoT().Context()
-
-		mockArtistRepo = newMockArtistRepo()
-		mockAlbumRepo = newMockAlbumRepo()
-		mockMediaFileRepo = newMockMediaFileRepo()
-
-		ds = &tests.MockDataStore{
-			MockedArtist:    mockArtistRepo,
-			MockedAlbum:     mockAlbumRepo,
-			MockedMediaFile: mockMediaFileRepo,
-		}
-
-		mockImageAgent = newMockArtistImageAgent()
-
-		// Use the mockAgents from helper, setting the specific agent
-		agentsCombined = &mockAgents{
-			imageAgent: mockImageAgent,
-		}
-
-		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()
-		mockAlbumRepo.On("Get", "album-1").Return(&model.Album{ID: "album-1", Name: "Album One", AlbumArtistID: "artist-1"}, nil).Maybe()
-		mockMediaFileRepo.On("Get", "mf-1").Return(&model.MediaFile{ID: "mf-1", Title: "Track One", ArtistID: "artist-1"}, nil).Maybe()
-		// Default mock for non-existent entities
-		mockArtistRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Maybe()
-		mockAlbumRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Maybe()
-		mockMediaFileRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Maybe()
-
-		// Default successful image agent response
-		mockImageAgent.On("GetArtistImages", mock.Anything, "artist-1", "Artist One", "").
-			Return([]agents.ExternalImage{
-				{URL: "http://example.com/large.jpg", Size: 1000},
-				{URL: "http://example.com/medium.jpg", Size: 500},
-				{URL: "http://example.com/small.jpg", Size: 200},
-			}, nil).Maybe()
-	})
-
-	AfterEach(func() {
-		mockArtistRepo.AssertExpectations(GinkgoT())
-		mockAlbumRepo.AssertExpectations(GinkgoT())
-		mockMediaFileRepo.AssertExpectations(GinkgoT())
-		mockImageAgent.AssertExpectations(GinkgoT())
-	})
-
-	It("returns the largest image URL when successful", func() {
-		// Arrange
-		expectedURL, _ := url.Parse("http://example.com/large.jpg")
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "artist-1")
-
-		// Assert
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL))
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1")
-		mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-1", "Artist One", "")
-	})
-
-	It("returns ErrNotFound if the artist is not found in the DB", func() {
-		// Arrange
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "not-found")
-
-		// Assert
-		Expect(err).To(MatchError(model.ErrNotFound))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "not-found")
-		mockImageAgent.AssertNotCalled(GinkgoT(), "GetArtistImages", mock.Anything, mock.Anything, mock.Anything, mock.Anything)
-	})
-
-	It("returns the agent error if the agent fails", func() {
-		// Arrange
-		agentErr := errors.New("agent failure")
-		mockImageAgent.Mock = mock.Mock{} // Reset default expectation
-		mockImageAgent.On("GetArtistImages", ctx, "artist-1", "Artist One", "").Return(nil, agentErr).Once()
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "artist-1")
-
-		// Assert
-		Expect(err).To(MatchError(model.ErrNotFound)) // Corrected Expectation: The provider maps agent errors (other than canceled) to ErrNotFound if no image was found/populated
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1")
-		mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-1", "Artist One", "")
-	})
-
-	It("returns ErrNotFound if the agent returns ErrNotFound", func() {
-		// Arrange
-		mockImageAgent.Mock = mock.Mock{} // Reset default expectation
-		mockImageAgent.On("GetArtistImages", ctx, "artist-1", "Artist One", "").Return(nil, agents.ErrNotFound).Once()
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "artist-1")
-
-		// Assert
-		Expect(err).To(MatchError(model.ErrNotFound))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1")
-		mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-1", "Artist One", "")
-	})
-
-	It("returns ErrNotFound if the agent returns no images", func() {
-		// Arrange
-		mockImageAgent.Mock = mock.Mock{} // Reset default expectation
-		mockImageAgent.On("GetArtistImages", ctx, "artist-1", "Artist One", "").Return([]agents.ExternalImage{}, nil).Once()
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "artist-1")
-
-		// Assert
-		Expect(err).To(MatchError(model.ErrNotFound)) // Implementation maps empty result to ErrNotFound
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1")
-		mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-1", "Artist One", "")
-	})
-
-	It("returns context error if context is canceled before agent call", func() {
-		// Arrange
-		cctx, cancelCtx := context.WithCancel(context.Background())
-		mockArtistRepo.Mock = mock.Mock{} // Reset default expectation for artist repo as well
-		mockArtistRepo.On("Get", "artist-1").Return(&model.Artist{ID: "artist-1", Name: "Artist One"}, nil).Run(func(args mock.Arguments) {
-			cancelCtx() // Cancel context *during* the DB call simulation
-		}).Once()
-
-		// Act
-		imgURL, err := provider.ArtistImage(cctx, "artist-1")
-
-		// Assert
-		Expect(err).To(MatchError(context.Canceled))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1")
-	})
-
-	It("derives artist ID from MediaFile ID", func() {
-		// Arrange: Add mocks for the initial GetEntityByID lookups
-		mockArtistRepo.On("Get", "mf-1").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "mf-1").Return(nil, model.ErrNotFound).Once()
-		// Default mocks for MediaFileRepo.Get("mf-1") and ArtistRepo.Get("artist-1") handle the rest
-		expectedURL, _ := url.Parse("http://example.com/large.jpg")
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "mf-1")
-
-		// Assert
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL))
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "mf-1") // GetEntityByID sequence
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "mf-1")  // GetEntityByID sequence
-		mockMediaFileRepo.AssertCalled(GinkgoT(), "Get", "mf-1")
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1") // Should be called after getting MF
-		mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-1", "Artist One", "")
-	})
-
-	It("derives artist ID from Album ID", func() {
-		// Arrange: Add mock for the initial GetEntityByID lookup
-		mockArtistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
-		// Default mocks for AlbumRepo.Get("album-1") and ArtistRepo.Get("artist-1") handle the rest
-		expectedURL, _ := url.Parse("http://example.com/large.jpg")
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "album-1")
-
-		// Assert
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL))
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "album-1") // GetEntityByID sequence
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "album-1")
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1") // Should be called after getting Album
-		mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-1", "Artist One", "")
-	})
-
-	It("returns ErrNotFound if derived artist is not found", func() {
-		// Arrange
-		// Add mocks for the initial GetEntityByID lookups
-		mockArtistRepo.On("Get", "mf-bad-artist").Return(nil, model.ErrNotFound).Once()
-		mockAlbumRepo.On("Get", "mf-bad-artist").Return(nil, model.ErrNotFound).Once()
-		mockMediaFileRepo.On("Get", "mf-bad-artist").Return(&model.MediaFile{ID: "mf-bad-artist", ArtistID: "not-found"}, nil).Once()
-		// Add expectation for the recursive GetEntityByID call for the MediaFileRepo
-		mockMediaFileRepo.On("Get", "not-found").Return(nil, model.ErrNotFound).Maybe()
-		// The default mocks for ArtistRepo/AlbumRepo handle the final "not-found" lookups
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "mf-bad-artist")
-
-		// Assert
-		Expect(err).To(MatchError(model.ErrNotFound))
-		Expect(imgURL).To(BeNil())
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "mf-bad-artist") // GetEntityByID sequence
-		mockAlbumRepo.AssertCalled(GinkgoT(), "Get", "mf-bad-artist")  // GetEntityByID sequence
-		mockMediaFileRepo.AssertCalled(GinkgoT(), "Get", "mf-bad-artist")
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "not-found")
-		mockImageAgent.AssertNotCalled(GinkgoT(), "GetArtistImages", mock.Anything, mock.Anything, mock.Anything, mock.Anything)
-	})
-
-	It("handles different image orders from agent", func() {
-		// Arrange
-		mockImageAgent.Mock = mock.Mock{} // Reset default expectation
-		mockImageAgent.On("GetArtistImages", ctx, "artist-1", "Artist One", "").
-			Return([]agents.ExternalImage{
-				{URL: "http://example.com/small.jpg", Size: 200},
-				{URL: "http://example.com/large.jpg", Size: 1000},
-				{URL: "http://example.com/medium.jpg", Size: 500},
-			}, nil).Once()
-		expectedURL, _ := url.Parse("http://example.com/large.jpg")
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "artist-1")
-
-		// Assert
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL)) // Still picks the largest
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1")
-		mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-1", "Artist One", "")
-	})
-
-	It("handles agent returning only one image", func() {
-		// Arrange
-		mockImageAgent.Mock = mock.Mock{} // Reset default expectation
-		mockImageAgent.On("GetArtistImages", ctx, "artist-1", "Artist One", "").
-			Return([]agents.ExternalImage{
-				{URL: "http://example.com/medium.jpg", Size: 500},
-			}, nil).Once()
-		expectedURL, _ := url.Parse("http://example.com/medium.jpg")
-
-		// Act
-		imgURL, err := provider.ArtistImage(ctx, "artist-1")
-
-		// Assert
-		Expect(err).ToNot(HaveOccurred())
-		Expect(imgURL).To(Equal(expectedURL))
-		mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-1")
-		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
-		cachedArtist := &model.Artist{
-			ID:                    "artist-cached",
-			Name:                  "Cached Artist",
-			LargeImageUrl:         "http://example.com/cached-large.jpg",
-			ExternalInfoUpdatedAt: new(time.Now().Add(-1 * time.Minute)),
-		}
-		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
-		staleArtist := &model.Artist{
-			ID:                    "artist-expired",
-			Name:                  "Expired Artist",
-			LargeImageUrl:         "http://example.com/expired-large.jpg",
-			ExternalInfoUpdatedAt: new(time.Now().Add(-1 * time.Hour)),
-		}
-		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
-
-		const (
-			originalArtistName   = "Run–D.M.C." // Artist name with en dash
-			normalizedArtistName = "Run-D.M.C." // Normalized version with hyphen
-		)
-
-		BeforeEach(func() {
-			// Test with en dash (–) in artist name like "Run–D.M.C."
-			artistWithEnDash = &model.Artist{ID: "artist-endash", Name: originalArtistName}
-			mockArtistRepo.Mock = mock.Mock{} // Reset default expectations
-			mockArtistRepo.On("Get", "artist-endash").Return(artistWithEnDash, nil).Once()
-
-			expectedURL, _ = url.Parse("http://example.com/rundmc.jpg")
-
-			// Mock the image agent to return an image for the artist
-			mockImageAgent.On("GetArtistImages", ctx, "artist-endash", mock.AnythingOfType("string"), "").
-				Return([]agents.ExternalImage{
-					{URL: "http://example.com/rundmc.jpg", Size: 1000},
-				}, nil).Once()
-
-		})
-
-		When("DevPreserveUnicodeInExternalCalls is true", func() {
-			BeforeEach(func() {
-				conf.Server.DevPreserveUnicodeInExternalCalls = true
-			})
-			It("preserves Unicode characters in artist names", func() {
-				// Act
-				imgURL, err := provider.ArtistImage(ctx, "artist-endash")
-
-				// Assert
-				Expect(err).ToNot(HaveOccurred())
-				Expect(imgURL).To(Equal(expectedURL))
-				mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-endash")
-				// This is the key assertion: ensure the original Unicode name is used
-				mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-endash", originalArtistName, "")
-			})
-		})
-
-		When("DevPreserveUnicodeInExternalCalls is false", func() {
-			BeforeEach(func() {
-				conf.Server.DevPreserveUnicodeInExternalCalls = false
-			})
-
-			It("normalizes Unicode characters", func() {
-				// Act
-				imgURL, err := provider.ArtistImage(ctx, "artist-endash")
-
-				// Assert
-				Expect(err).ToNot(HaveOccurred())
-				Expect(imgURL).To(Equal(expectedURL))
-				mockArtistRepo.AssertCalled(GinkgoT(), "Get", "artist-endash")
-				// This assertion ensures the normalized name is used (en dash → hyphen)
-				mockImageAgent.AssertCalled(GinkgoT(), "GetArtistImages", ctx, "artist-endash", normalizedArtistName, "")
-			})
-		})
-	})
-})
-
-// mockArtistImageAgent implementation using testify/mock
-// This remains local as it's specific to testing the ArtistImage functionality
-type mockArtistImageAgent struct {
-	mock.Mock
-	agents.ArtistImageRetriever // Embed interface
-}
-
-// Constructor for the mock agent
-func newMockArtistImageAgent() *mockArtistImageAgent {
-	mock := new(mockArtistImageAgent)
-	// Set default AgentName if needed, although usually called via mockAgents
-	mock.On("AgentName").Return("mockImage").Maybe()
-	return mock
-}
-
-func (m *mockArtistImageAgent) AgentName() string {
-	args := m.Called()
-	return args.String(0)
-}
-
-func (m *mockArtistImageAgent) GetArtistImages(ctx context.Context, id, artistName, mbid string) ([]agents.ExternalImage, error) {
-	args := m.Called(ctx, id, artistName, mbid)
-	// Need careful type assertion for potentially nil slice
-	var res []agents.ExternalImage
-	if args.Get(0) != nil {
-		res = args.Get(0).([]agents.ExternalImage)
-	}
-	return res, args.Error(1)
-}
-
-// Ensure mockAgent implements the interface
-var _ agents.ArtistImageRetriever = (*mockArtistImageAgent)(nil)
diff --git a/core/playlists/import_test.go b/core/playlists/import_test.go
index f2866fb60..2a84d56b2 100644
--- a/core/playlists/import_test.go
+++ b/core/playlists/import_test.go
@@ -11,7 +11,7 @@ import (
 
 	"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/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/criteria"
@@ -43,7 +43,7 @@ var _ = Describe("Playlists - Import", func() {
 		var folder *model.Folder
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 			ds.MockedMediaFile = &mockedMediaFileRepo{}
 			libPath, _ := os.Getwd()
 			// Set up library with the actual library path that matches the folder
@@ -118,7 +118,7 @@ var _ = Describe("Playlists - Import", func() {
 
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3", "test.ogg"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
 				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
@@ -136,7 +136,7 @@ var _ = Describe("Playlists - Import", func() {
 
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
 				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
@@ -155,7 +155,7 @@ var _ = Describe("Playlists - Import", func() {
 
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
 				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
@@ -174,7 +174,7 @@ var _ = Describe("Playlists - Import", func() {
 
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
 				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
@@ -192,7 +192,7 @@ var _ = Describe("Playlists - Import", func() {
 
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
 				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
@@ -209,7 +209,7 @@ var _ = Describe("Playlists - Import", func() {
 
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
 				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
@@ -226,7 +226,7 @@ var _ = Describe("Playlists - Import", func() {
 
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
 				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
@@ -244,7 +244,7 @@ var _ = Describe("Playlists - Import", func() {
 
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
 				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
@@ -258,7 +258,7 @@ var _ = Describe("Playlists - Import", func() {
 				tmpDir := GinkgoT().TempDir()
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				m3u := "#EXTALBUMARTURL:https://example.com/new-cover.jpg\ntest.mp3\n"
 				plsFile := filepath.Join(tmpDir, "test.m3u")
@@ -285,7 +285,7 @@ var _ = Describe("Playlists - Import", func() {
 				tmpDir := GinkgoT().TempDir()
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				plsFile := filepath.Join(tmpDir, "test.m3u")
 				Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
@@ -311,7 +311,7 @@ var _ = Describe("Playlists - Import", func() {
 				tmpDir := GinkgoT().TempDir()
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				m3u := "test.mp3\n"
 				plsFile := filepath.Join(tmpDir, "test.m3u")
@@ -388,7 +388,7 @@ var _ = Describe("Playlists - Import", func() {
 				tmpDir := GinkgoT().TempDir()
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
 				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{}}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				// Create the playlist file on disk with the filesystem's normalization form
 				plsFile := tmpDir + "/" + filesystemName + ".m3u"
@@ -448,7 +448,7 @@ var _ = Describe("Playlists - Import", func() {
 						"def.mp3", // This is playlists/def.mp3 relative to plsDir
 					},
 				}
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 			})
 
 			It("handles relative paths that reference files in other libraries", func() {
@@ -604,7 +604,7 @@ var _ = Describe("Playlists - Import", func() {
 					},
 				}
 				// Recreate playlists service to pick up new mock
-				ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 				// Create playlist in music library that references both tracks
 				plsContent := "#PLAYLIST:Same Path Test\nalbum/track.mp3\n../classical/album/track.mp3"
@@ -662,7 +662,7 @@ var _ = Describe("Playlists - Import", func() {
 				},
 			}
 			ds.MockedFolder = mockFolderRepo
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 			plsContent := "#PLAYLIST:My Playlist\ntest.mp3\ntest.ogg\n"
 			plsFile := filepath.Join(tmpDir, "my-playlist.m3u")
@@ -681,7 +681,7 @@ var _ = Describe("Playlists - Import", func() {
 			libDir := filepath.Join(tmpDir, "music")
 			Expect(os.Mkdir(libDir, 0755)).To(Succeed())
 			mockLibRepo.SetData([]model.Library{{ID: 1, Path: libDir}})
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 			plsContent := "#PLAYLIST:External Playlist\n" + libDir + "/test.mp3\n"
 			plsFile := filepath.Join(tmpDir, "external.m3u")
@@ -704,7 +704,7 @@ var _ = Describe("Playlists - Import", func() {
 				},
 			}
 			ds.MockedFolder = mockFolderRepo
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 			plsFile := filepath.Join(tmpDir, "test.m3u")
 			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
@@ -724,7 +724,7 @@ var _ = Describe("Playlists - Import", func() {
 				},
 			}
 			ds.MockedFolder = mockFolderRepo
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 			plsFile := filepath.Join(tmpDir, "test.m3u")
 			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
@@ -744,7 +744,7 @@ var _ = Describe("Playlists - Import", func() {
 				},
 			}
 			ds.MockedFolder = mockFolderRepo
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 
 			plsFile := filepath.Join(tmpDir, "test.m3u")
 			Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
@@ -767,7 +767,7 @@ var _ = Describe("Playlists - Import", func() {
 		BeforeEach(func() {
 			repo = &mockedMediaFileFromListRepo{}
 			ds.MockedMediaFile = repo
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 			mockLibRepo.SetData([]model.Library{{ID: 1, Path: "/music"}, {ID: 2, Path: "/new"}})
 			ctx = request.WithUser(ctx, model.User{ID: "123"})
 		})
diff --git a/core/playlists/playlists.go b/core/playlists/playlists.go
index 1ef083bbb..656bde05e 100644
--- a/core/playlists/playlists.go
+++ b/core/playlists/playlists.go
@@ -52,11 +52,12 @@ type Playlists interface {
 	TracksRepository(ctx context.Context, playlistId string, refreshSmartPlaylist bool) rest.Repository
 }
 
-// ImageUploadService is a local interface satisfied by core.ImageUploadService.
-// Defined here to avoid an import cycle between core and core/playlists.
+// ImageUploadService is a local interface satisfied by artwork.Uploader.
+// Defined here to avoid an import cycle between core/artwork and core/playlists.
 type ImageUploadService interface {
 	SetImage(ctx context.Context, entityType string, entityID string, name string, oldPath string, reader io.Reader, ext string) (filename string, err error)
 	RemoveImage(ctx context.Context, path string) error
+	EnqueueArtwork(ctx context.Context, entityType, entityID string)
 }
 
 type playlists struct {
@@ -320,7 +321,11 @@ func (s *playlists) SetImage(ctx context.Context, playlistID string, reader io.R
 	}
 
 	pls.UploadedImage = filename
-	return s.ds.Playlist(ctx).Put(pls)
+	if err := s.ds.Playlist(ctx).Put(pls); err != nil {
+		return err
+	}
+	s.imgUpload.EnqueueArtwork(ctx, consts.EntityPlaylist, pls.ID)
+	return nil
 }
 
 func (s *playlists) RemoveImage(ctx context.Context, playlistID string) error {
@@ -334,5 +339,9 @@ func (s *playlists) RemoveImage(ctx context.Context, playlistID string) error {
 	}
 
 	pls.UploadedImage = ""
-	return s.ds.Playlist(ctx).Put(pls)
+	if err := s.ds.Playlist(ctx).Put(pls); err != nil {
+		return err
+	}
+	s.imgUpload.EnqueueArtwork(ctx, consts.EntityPlaylist, pls.ID)
+	return nil
 }
diff --git a/core/playlists/playlists_test.go b/core/playlists/playlists_test.go
index 0c9674bed..e8134b2ef 100644
--- a/core/playlists/playlists_test.go
+++ b/core/playlists/playlists_test.go
@@ -8,7 +8,7 @@ import (
 
 	"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/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/criteria"
@@ -42,7 +42,7 @@ var _ = Describe("Playlists", func() {
 				"pls-1": {ID: "pls-1", Name: "My Playlist", OwnerID: "user-1"},
 			}
 			mockPlsRepo.TracksRepo = mockTracks
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("allows owner to delete their playlist", func() {
@@ -82,7 +82,7 @@ var _ = Describe("Playlists", func() {
 				"pls-1": {ID: "pls-1", Name: "My Playlist", OwnerID: "user-1"},
 			}
 			mockPlsRepo.TracksRepo = mockTracks
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("returns the playlist's track repository", func() {
@@ -103,7 +103,7 @@ var _ = Describe("Playlists", func() {
 				"pls-smart": {ID: "pls-smart", Name: "Smart", OwnerID: "user-1",
 					Rules: &criteria.Criteria{Expression: criteria.Contains{"title": "test"}}},
 			}
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("creates a new playlist with owner set from context", func() {
@@ -161,7 +161,7 @@ var _ = Describe("Playlists", func() {
 					Rules: &criteria.Criteria{Expression: criteria.Contains{"title": "test"}}},
 			}
 			mockPlsRepo.TracksRepo = mockTracks
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("allows owner to update their playlist", func() {
@@ -219,7 +219,7 @@ var _ = Describe("Playlists", func() {
 				"pls-other": {ID: "pls-other", Name: "Other's", OwnerID: "other-user"},
 			}
 			mockPlsRepo.TracksRepo = mockTracks
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("allows owner to add tracks", func() {
@@ -267,7 +267,7 @@ var _ = Describe("Playlists", func() {
 					Rules: &criteria.Criteria{Expression: criteria.Contains{"title": "test"}}},
 			}
 			mockPlsRepo.TracksRepo = mockTracks
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("allows owner to remove tracks", func() {
@@ -301,7 +301,7 @@ var _ = Describe("Playlists", func() {
 					Rules: &criteria.Criteria{Expression: criteria.Contains{"title": "test"}}},
 			}
 			mockPlsRepo.TracksRepo = mockTracks
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("allows owner to reorder", func() {
@@ -330,7 +330,7 @@ var _ = Describe("Playlists", func() {
 				"pls-1":     {ID: "pls-1", Name: "My Playlist", OwnerID: "user-1"},
 				"pls-other": {ID: "pls-other", Name: "Other's", OwnerID: "other-user"},
 			}
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("saves image file and updates UploadedImage", func() {
@@ -400,7 +400,7 @@ var _ = Describe("Playlists", func() {
 				"pls-empty": {ID: "pls-empty", Name: "No Cover", OwnerID: "user-1"},
 				"pls-other": {ID: "pls-other", Name: "Other's", OwnerID: "other-user"},
 			}
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		It("removes file and clears UploadedImage", func() {
@@ -420,6 +420,24 @@ var _ = Describe("Playlists", func() {
 			Expect(mockPlsRepo.Last.UploadedImage).To(BeEmpty())
 		})
 
+		It("clears the resolved artwork state and re-queues after removing an upload", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+			Expect(ds.Artwork(ctx).PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "pl", ItemID: "pls-1", Hash: "oldhash", Source: "upload",
+			})).To(Succeed())
+
+			Expect(ps.RemoveImage(ctx, "pls-1")).To(Succeed())
+
+			_, err := ds.Artwork(ctx).GetItemArtwork(model.KindPlaylistArtwork, "pls-1", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+			queued, _ := ds.ArtworkQueue(ctx).DequeueBatch(100)
+			Expect(queued).To(ContainElement(SatisfyAll(
+				HaveField("ItemKind", "pl"),
+				HaveField("ItemID", "pls-1"),
+				HaveField("Priority", model.ArtworkPriorityBump),
+			)))
+		})
+
 		It("denies non-owner", func() {
 			ctx = request.WithUser(ctx, model.User{ID: "other-user", IsAdmin: false})
 			err := ps.RemoveImage(ctx, "pls-1")
diff --git a/core/playlists/rest_adapter_test.go b/core/playlists/rest_adapter_test.go
index 58a327bde..7ae376b07 100644
--- a/core/playlists/rest_adapter_test.go
+++ b/core/playlists/rest_adapter_test.go
@@ -5,7 +5,7 @@ import (
 	"time"
 
 	"github.com/deluan/rest"
-	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/criteria"
@@ -37,7 +37,7 @@ var _ = Describe("REST Adapter", func() {
 			mockPlsRepo.Data = map[string]*model.Playlist{
 				"pls-1": {ID: "pls-1", Name: "My Playlist", OwnerID: "user-1"},
 			}
-			ps = playlists.NewPlaylists(ds, core.NewImageUploadService())
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
 
 		Describe("Save", func() {
diff --git a/core/wire_providers.go b/core/wire_providers.go
index a2fffa34f..a09fcc108 100644
--- a/core/wire_providers.go
+++ b/core/wire_providers.go
@@ -24,8 +24,6 @@ var Set = wire.NewSet(
 	NewLibrary,
 	NewUser,
 	NewMaintenance,
-	NewImageUploadService,
-	wire.Bind(new(playlists.ImageUploadService), new(ImageUploadService)),
 	stream.NewTranscodeDecider,
 	agents.GetAgents,
 	external.NewProvider,
diff --git a/db/db.go b/db/db.go
index 4ca996fe5..11a05b456 100644
--- a/db/db.go
+++ b/db/db.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"embed"
+	"errors"
 	"fmt"
 	"time"
 
@@ -106,6 +107,17 @@ func Init(ctx context.Context) func() {
 	}
 }
 
+// ErrorCodes reports the SQLite result code and extended result code carried by err.
+// The extended code is what distinguishes errors that share a message: "database is locked"
+// is both SQLITE_BUSY, which busy_timeout retries, and SQLITE_BUSY_SNAPSHOT, which it never can.
+func ErrorCodes(err error) (code, extended int, ok bool) {
+	var se sqlite3.Error
+	if !errors.As(err, &se) {
+		return 0, 0, false
+	}
+	return int(se.Code), int(se.ExtendedCode), true
+}
+
 type statusLogger struct{ numPending int }
 
 func (*statusLogger) Fatalf(format string, v ...any) { log.Fatal(fmt.Sprintf(format, v...)) }
diff --git a/db/migrations/20260722023032_add_artwork_tables.sql b/db/migrations/20260722023032_add_artwork_tables.sql
new file mode 100644
index 000000000..e307d13e8
--- /dev/null
+++ b/db/migrations/20260722023032_add_artwork_tables.sql
@@ -0,0 +1,46 @@
+-- +goose Up
+CREATE TABLE artwork (
+  hash TEXT PRIMARY KEY,
+  mime TEXT NOT NULL,
+  width INTEGER NOT NULL DEFAULT 0,
+  height INTEGER NOT NULL DEFAULT 0,
+  size_bytes INTEGER NOT NULL DEFAULT 0,
+  blur_hash TEXT NOT NULL DEFAULT '',
+  thumb_hash TEXT NOT NULL DEFAULT '',
+  dominant_color TEXT NOT NULL DEFAULT '',
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE item_artwork (
+  item_kind TEXT NOT NULL,
+  item_id TEXT NOT NULL,
+  image_type TEXT NOT NULL DEFAULT 'primary',
+  hash TEXT NOT NULL DEFAULT '',
+  source TEXT NOT NULL DEFAULT '',
+  source_path TEXT NOT NULL DEFAULT '',
+  ref_mtime INTEGER NOT NULL DEFAULT 0,
+  attempted_at TIMESTAMP,
+  updated_at TIMESTAMP,
+  PRIMARY KEY (item_kind, item_id, image_type)
+) WITHOUT ROWID;
+CREATE INDEX ix_item_artwork_hash ON item_artwork(hash);
+
+CREATE TABLE artwork_queue (
+  item_kind TEXT NOT NULL,
+  item_id TEXT NOT NULL,
+  image_type TEXT NOT NULL DEFAULT 'primary',
+  priority INTEGER NOT NULL DEFAULT 0,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  retry_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  enqueued_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (item_kind, item_id, image_type)
+) WITHOUT ROWID;
+-- Ordered to match DequeueBatch (priority DESC, enqueued_at) so drains stop after n rows; retry_at makes it covering.
+-- item_kind leads: each drain pool dequeues only its own kinds, so it must seek straight to
+-- them rather than scan past another pool's backlog.
+CREATE INDEX ix_artwork_queue_drain ON artwork_queue(item_kind, priority DESC, enqueued_at, retry_at);
+
+-- +goose Down
+DROP TABLE artwork_queue;
+DROP TABLE item_artwork;
+DROP TABLE artwork;
diff --git a/go.mod b/go.mod
index 5488b41e4..b72f4035c 100644
--- a/go.mod
+++ b/go.mod
@@ -57,6 +57,7 @@ require (
 	github.com/tetratelabs/wazero v1.12.0
 	github.com/unrolled/secure v1.17.0
 	github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342
+	github.com/zeebo/xxh3 v1.1.0
 	go.senan.xyz/taglib v0.11.1
 	go.uber.org/goleak v1.3.0
 	golang.org/x/image v0.44.0
@@ -128,7 +129,6 @@ require (
 	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/tetratelabs/wabin v0.0.0-20230304001439-f6f874872834 // indirect
 	github.com/valyala/fastjson v1.6.10 // indirect
-	github.com/zeebo/xxh3 v1.1.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.10.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.3 // indirect
diff --git a/log/formatters.go b/log/formatters.go
index 0b27f3a43..5d864dae4 100644
--- a/log/formatters.go
+++ b/log/formatters.go
@@ -26,8 +26,15 @@ func ShortDur(d time.Duration) string {
 	default:
 		s = d.String()
 	}
-	s = strings.TrimSuffix(s, "0s")
-	return strings.TrimSuffix(s, "0m")
+	// Drop whole zero-valued trailing components ("4h0m0s" -> "4h"). The suffix has to include
+	// the preceding unit, or a value that merely ends in a zero digit loses it: "10s" -> "1".
+	if strings.HasSuffix(s, "m0s") {
+		s = strings.TrimSuffix(s, "0s")
+	}
+	if strings.HasSuffix(s, "h0m") {
+		s = strings.TrimSuffix(s, "0m")
+	}
+	return s
 }
 
 func StringerValue(s fmt.Stringer) string {
diff --git a/log/formatters_test.go b/log/formatters_test.go
index 6ed43a094..64d72bdbd 100644
--- a/log/formatters_test.go
+++ b/log/formatters_test.go
@@ -25,6 +25,12 @@ var _ = DescribeTable("ShortDur",
 	Entry("4m3s", 4*time.Minute+3*time.Second, "4m3s"),
 	Entry("4h", 4*time.Hour, "4h"),
 	Entry("4h", 4*time.Hour+2*time.Second, "4h"),
+	// A trailing zero digit is significant: only a whole zero-valued component may be dropped.
+	Entry("zero", time.Duration(0), "0s"),
+	Entry("10s", 10*time.Second, "10s"),
+	Entry("20s", 20*time.Second, "20s"),
+	Entry("1m30s", time.Minute+30*time.Second, "1m30s"),
+	Entry("2h30m", 2*time.Hour+30*time.Minute, "2h30m"),
 	Entry("4h2m", 4*time.Hour+2*time.Minute+5*time.Second+200*time.Millisecond, "4h2m"),
 )
 
diff --git a/model/album.go b/model/album.go
index 55df8c63c..f27ca12c0 100644
--- a/model/album.go
+++ b/model/album.go
@@ -13,6 +13,7 @@ import (
 
 type Album struct {
 	Annotations `structs:"-" hash:"ignore"`
+	ItemImage   `structs:"-" hash:"ignore"`
 
 	ID            string `structs:"id" json:"id"`
 	LibraryID     int    `structs:"library_id" json:"libraryId"`
@@ -142,6 +143,7 @@ type AlbumRepository interface {
 	UpdateExternalInfo(*Album) error
 	Get(id string) (*Album, error)
 	GetAll(...QueryOptions) (Albums, error)
+	GetAllIDs(...QueryOptions) ([]string, error)
 	GetCursor(...QueryOptions) (AlbumCursor, error)
 	GetYears(libraryIDs ...int) ([]int, error)
 
diff --git a/model/artist.go b/model/artist.go
index f9c4bffd5..f3704b669 100644
--- a/model/artist.go
+++ b/model/artist.go
@@ -11,6 +11,7 @@ import (
 
 type Artist struct {
 	Annotations `structs:"-"`
+	ItemImage   `structs:"-"`
 
 	ID string `structs:"id" json:"id"`
 
@@ -89,6 +90,7 @@ type ArtistRepository interface {
 	UpdateExternalInfo(a *Artist) error
 	Get(id string) (*Artist, error)
 	GetAll(options ...QueryOptions) (Artists, error)
+	GetAllIDs(options ...QueryOptions) ([]string, error)
 	GetCursor(options ...QueryOptions) (ArtistCursor, error)
 	GetIndex(includeMissing bool, libraryIds []int, roles ...Role) (ArtistIndexes, error)
 
diff --git a/model/artwork.go b/model/artwork.go
new file mode 100644
index 000000000..87b424f33
--- /dev/null
+++ b/model/artwork.go
@@ -0,0 +1,144 @@
+package model
+
+import "time"
+
+// Artwork is one unique image, identified by the XXH3-64 hash of its bytes.
+type Artwork struct {
+	Hash      string `structs:"hash"`
+	Mime      string `structs:"mime"`
+	Width     int    `structs:"width"`
+	Height    int    `structs:"height"`
+	SizeBytes int64  `structs:"size_bytes"`
+	BlurHash  string `structs:"blur_hash"`
+	ThumbHash string `structs:"thumb_hash"`
+	// DominantColor is "#rrggbb": a flat placeholder clients can paint before any decode.
+	DominantColor string    `structs:"dominant_color"`
+	CreatedAt     time.Time `structs:"created_at"`
+}
+
+const ImageTypePrimary = "primary"
+
+// ItemImage is per-entity artwork state hydrated at query time; never persisted.
+type ItemImage struct {
+	ImageHash   string `structs:"-" json:"imageHash,omitempty"`
+	ImageAbsent bool   `structs:"-" json:"imageAbsent,omitempty"`
+	// BlurHash is Jellyfin's; its mappers read this field directly, so it stays off native JSON.
+	BlurHash  string `structs:"-" json:"-"`
+	ThumbHash string `structs:"-" json:"thumbHash,omitempty"`
+	// DominantColor is the only placeholder needing no decode, so it can paint on the first frame.
+	DominantColor string `structs:"-" json:"dominantColor,omitempty"`
+	// A thumbhash's own aspect is quantised, so clients need these to shape the placeholder exactly.
+	ImageWidth  int `structs:"-" json:"imageWidth,omitempty"`
+	ImageHeight int `structs:"-" json:"imageHeight,omitempty"`
+}
+
+// AspectRatio is the image's width/height, or nil when the image or its dimensions are unknown.
+func (i ItemImage) AspectRatio() *float64 {
+	if i.ImageAbsent || i.ImageWidth <= 0 || i.ImageHeight <= 0 {
+		return nil
+	}
+	return new(float64(i.ImageWidth) / float64(i.ImageHeight))
+}
+
+// ItemArtwork is an entity's resolved artwork state. Hash=="" means known absent.
+type ItemArtwork struct {
+	ItemKind  string `structs:"item_kind"`
+	ItemID    string `structs:"item_id"`
+	ImageType string `structs:"image_type"`
+	Hash      string `structs:"hash"`
+	Source    string `structs:"source"`
+	// SourcePath is the backing file (folder/upload: the image; embedded: the audio file); "" otherwise.
+	SourcePath string `structs:"source_path"`
+	// RefMtime is SourcePath's mtime (unix-nanoseconds) at resolution; 0 when there is no SourcePath.
+	RefMtime int64 `structs:"ref_mtime"`
+	// Nullable in the schema, but every insert must set them: these non-pointer fields cannot scan NULL.
+	AttemptedAt time.Time `structs:"attempted_at"`
+	UpdatedAt   time.Time `structs:"updated_at"`
+}
+
+// ItemArtworkInfo is the list-hydration projection (item_artwork joined with artwork).
+type ItemArtworkInfo struct {
+	ItemID        string
+	Hash          string
+	BlurHash      string
+	ThumbHash     string
+	DominantColor string
+	Width         int
+	Height        int
+}
+
+// Absent reports a known-absent artwork state (resolved, no image).
+func (i ItemArtworkInfo) Absent() bool { return i.Hash == "" }
+
+// Image projects the hydration entry onto the entity-facing struct.
+func (i ItemArtworkInfo) Image() ItemImage {
+	return ItemImage{
+		ImageHash:     i.Hash,
+		ImageAbsent:   i.Absent(),
+		BlurHash:      i.BlurHash,
+		ThumbHash:     i.ThumbHash,
+		DominantColor: i.DominantColor,
+		ImageWidth:    i.Width,
+		ImageHeight:   i.Height,
+	}
+}
+
+type ArtworkQueueItem struct {
+	ItemKind   string    `structs:"item_kind"`
+	ItemID     string    `structs:"item_id"`
+	ImageType  string    `structs:"image_type"`
+	Priority   int       `structs:"priority"`
+	Attempts   int       `structs:"attempts"`
+	RetryAt    time.Time `structs:"retry_at"`
+	EnqueuedAt time.Time `structs:"enqueued_at"`
+}
+
+// Queue priorities: higher drains first.
+const (
+	ArtworkPriorityRecheck  = 0
+	ArtworkPriorityBackfill = 10
+	ArtworkPriorityScan     = 50
+	ArtworkPriorityBump     = 100
+)
+
+// Delete* takes the rows to remove; Purge* finds them itself and reports how many went.
+type ArtworkRepository interface {
+	GetImage(hash string) (*Artwork, error)
+	PutImage(a *Artwork) error
+	// PurgeOrphans deletes rows referenced by no item_artwork row and older than cutoff.
+	PurgeOrphans(createdBefore time.Time) (int64, error)
+	GetItemArtwork(kind Kind, id, imageType string) (*ItemArtwork, error)
+	PutItemArtwork(ia *ItemArtwork) error
+	DeleteForItems(kind Kind, ids []string) error
+	// GetInfoForItems hydrates a page in one batched query.
+	GetInfoForItems(kind Kind, ids []string) (map[string]ItemArtworkInfo, error)
+	// GetMimeByHash returns hash -> current mime for every stored artwork.
+	GetMimeByHash() (map[string]string, error)
+	// PurgeDanglingItems removes state rows whose entity no longer exists.
+	PurgeDanglingItems() (int64, error)
+}
+
+type ArtworkQueueRepository interface {
+	// Enqueue upserts; an existing row keeps the higher priority and has its retry_at reset.
+	Enqueue(items ...ArtworkQueueItem) error
+	// EnqueuePreservingBackoff upserts like Enqueue but preserves an existing row's retry_at, so a
+	// request-triggered read-through never resets a failed resolution's backoff.
+	EnqueuePreservingBackoff(items ...ArtworkQueueItem) error
+	// EnqueueStaleAbsent inserts queue rows (priority Recheck) for absent states older than cutoff.
+	EnqueueStaleAbsent(kind Kind, attemptedBefore time.Time) (int64, error)
+	// EnqueueAllMissing inserts queue rows for all entities with no item_artwork row, at the given priority.
+	EnqueueAllMissing(kind Kind, priority int) (int64, error)
+	// EnqueueIfMissing inserts only for items with no item_artwork row yet.
+	EnqueueIfMissing(items ...ArtworkQueueItem) error
+	// DequeueBatch returns up to n items with retry_at <= now, priority desc, enqueued_at asc.
+	// Restricted to the given kinds when any are passed, so one kind cannot block another's drain.
+	DequeueBatch(n int, kinds ...string) ([]ArtworkQueueItem, error)
+	// MarkFailedIfUnchanged applies the failure backoff only while retry_at still matches
+	// seenRetryAt, so a concurrent re-enqueue keeps its fresh eligibility.
+	MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time) error
+	// DeleteIfUnchanged deletes only while retry_at still matches, sparing a concurrent re-enqueue.
+	DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error
+	Count() (int64, error)
+	// PurgeDangling removes queue rows whose entity no longer exists.
+	PurgeDangling() (int64, error)
+}
diff --git a/model/artwork_id.go b/model/artwork_id.go
index 1bd146c1f..634a6442f 100644
--- a/model/artwork_id.go
+++ b/model/artwork_id.go
@@ -17,6 +17,11 @@ func (k Kind) String() string {
 	return k.name
 }
 
+// Prefix is the short token used in artwork ids and the item_artwork.item_kind column.
+func (k Kind) Prefix() string {
+	return k.prefix
+}
+
 var (
 	KindMediaFileArtwork = Kind{"mf", "media_file"}
 	KindArtistArtwork    = Kind{"ar", "artist"}
@@ -35,10 +40,18 @@ var artworkKindMap = map[string]Kind{
 	KindRadioArtwork.prefix:     KindRadioArtwork,
 }
 
+// ParseKind resolves an item_kind prefix (e.g. "al") to its Kind, reporting whether it was known.
+// Use it at string boundaries — URL params, the item_kind column — to enter the typed Kind domain.
+func ParseKind(prefix string) (Kind, bool) {
+	k, ok := artworkKindMap[prefix]
+	return k, ok
+}
+
 type ArtworkID struct {
 	Kind       Kind
 	ID         string
-	LastUpdate time.Time
+	Hash       string    // content-hash suffix; "" = unknown/none
+	LastUpdate time.Time // legacy: populated only when parsing old _<hexTimestamp> tokens
 }
 
 func (id ArtworkID) String() string {
@@ -46,14 +59,14 @@ func (id ArtworkID) String() string {
 		return ""
 	}
 	s := fmt.Sprintf("%s-%s", id.Kind.prefix, id.ID)
-	if lu := id.LastUpdate.Unix(); lu > 0 {
-		return fmt.Sprintf("%s_%x", s, lu)
+	if id.Hash != "" {
+		return s + "_" + id.Hash
 	}
-	return s + "_0"
+	return s
 }
 
 func NewArtworkID(kind Kind, id string, lastUpdate *time.Time) ArtworkID {
-	artID := ArtworkID{kind, id, time.Time{}}
+	artID := ArtworkID{Kind: kind, ID: id}
 	if lastUpdate != nil {
 		artID.LastUpdate = *lastUpdate
 	}
@@ -75,18 +88,34 @@ func ParseArtworkID(id string) (ArtworkID, error) {
 	}
 	parts = strings.SplitN(parts[1], "_", 2)
 	if len(parts) == 2 {
-		if parts[1] != "0" {
-			lastUpdate, err := strconv.ParseInt(parts[1], 16, 64)
-			if err != nil {
-				return ArtworkID{}, err
-			}
-			parsedID.LastUpdate = time.Unix(lastUpdate, 0)
-		}
 		parsedID.ID = parts[0]
+		suffix := parts[1]
+		switch {
+		// Hash detection must come first: a 16-hex value with the high bit set overflows int64.
+		case isImageHash(suffix):
+			parsedID.Hash = suffix
+		case suffix != "0":
+			if lastUpdate, err := strconv.ParseInt(suffix, 16, 64); err == nil {
+				parsedID.LastUpdate = time.Unix(lastUpdate, 0)
+			}
+		}
 	}
 	return parsedID, nil
 }
 
+// isImageHash reports whether s is a 16-char lowercase-hex XXH3-64 content hash.
+func isImageHash(s string) bool {
+	if len(s) != 16 {
+		return false
+	}
+	for _, c := range s {
+		if !(c >= '0' && c <= '9' || c >= 'a' && c <= 'f') {
+			return false
+		}
+	}
+	return true
+}
+
 func MustParseArtworkID(id string) ArtworkID {
 	artID, err := ParseArtworkID(id)
 	if err != nil {
@@ -112,40 +141,21 @@ func ParseDiscArtworkID(id string) (albumID string, discNumber int, err error) {
 }
 
 func artworkIDFromAlbum(al Album) ArtworkID {
-	return ArtworkID{
-		Kind:       KindAlbumArtwork,
-		ID:         al.ID,
-		LastUpdate: al.UpdatedAt,
-	}
+	return ArtworkID{Kind: KindAlbumArtwork, ID: al.ID, Hash: al.ImageHash}
 }
 
 func artworkIDFromMediaFile(mf MediaFile) ArtworkID {
-	return ArtworkID{
-		Kind:       KindMediaFileArtwork,
-		ID:         mf.ID,
-		LastUpdate: mf.UpdatedAt,
-	}
+	return ArtworkID{Kind: KindMediaFileArtwork, ID: mf.ID, Hash: mf.ImageHash}
 }
 
 func artworkIDFromPlaylist(pls Playlist) ArtworkID {
-	return ArtworkID{
-		Kind:       KindPlaylistArtwork,
-		ID:         pls.ID,
-		LastUpdate: pls.UpdatedAt,
-	}
+	return ArtworkID{Kind: KindPlaylistArtwork, ID: pls.ID, Hash: pls.ImageHash}
 }
 
 func artworkIDFromArtist(ar Artist) ArtworkID {
-	return ArtworkID{
-		Kind: KindArtistArtwork,
-		ID:   ar.ID,
-	}
+	return ArtworkID{Kind: KindArtistArtwork, ID: ar.ID, Hash: ar.ImageHash}
 }
 
 func artworkIDFromRadio(r Radio) ArtworkID {
-	return ArtworkID{
-		Kind:       KindRadioArtwork,
-		ID:         r.ID,
-		LastUpdate: r.UpdatedAt,
-	}
+	return ArtworkID{Kind: KindRadioArtwork, ID: r.ID, Hash: r.ImageHash}
 }
diff --git a/model/artwork_id_test.go b/model/artwork_id_test.go
index ad66f7bb5..af6a12ffb 100644
--- a/model/artwork_id_test.go
+++ b/model/artwork_id_test.go
@@ -9,14 +9,31 @@ import (
 )
 
 var _ = Describe("ArtworkID", func() {
+	Describe("String()", func() {
+		It("returns a bare id when there is no hash", func() {
+			id := model.ArtworkID{Kind: model.KindAlbumArtwork, ID: "1234"}
+			Expect(id.String()).To(Equal("al-1234"))
+		})
+		It("appends the hash suffix when set", func() {
+			id := model.ArtworkID{Kind: model.KindAlbumArtwork, ID: "1234", Hash: "abcdef0123456789"}
+			Expect(id.String()).To(Equal("al-1234_abcdef0123456789"))
+		})
+		It("never emits a legacy timestamp/_0 suffix", func() {
+			id := model.NewArtworkID(model.KindAlbumArtwork, "1234", new(time.Now()))
+			Expect(id.String()).To(Equal("al-1234"))
+		})
+		It("returns empty string for an empty id", func() {
+			Expect(model.ArtworkID{Kind: model.KindAlbumArtwork}.String()).To(BeEmpty())
+		})
+	})
+
 	Describe("NewArtworkID()", func() {
-		It("creates a valid parseable ArtworkID", func() {
+		It("round-trips Kind and ID through String()", func() {
 			id := model.NewArtworkID(model.KindAlbumArtwork, "1234", new(time.Now()))
 			parsedId, err := model.ParseArtworkID(id.String())
 			Expect(err).ToNot(HaveOccurred())
 			Expect(parsedId.Kind).To(Equal(id.Kind))
 			Expect(parsedId.ID).To(Equal(id.ID))
-			Expect(parsedId.LastUpdate.Unix()).To(Equal(id.LastUpdate.Unix()))
 		})
 		It("creates a valid ArtworkID without lastUpdate info", func() {
 			id := model.NewArtworkID(model.KindPlaylistArtwork, "1234", nil)
@@ -24,18 +41,16 @@ var _ = Describe("ArtworkID", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(parsedId.Kind).To(Equal(id.Kind))
 			Expect(parsedId.ID).To(Equal(id.ID))
-			Expect(parsedId.LastUpdate.Unix()).To(Equal(id.LastUpdate.Unix()))
 		})
 	})
+
 	Describe("ParseArtworkID - disc kind", func() {
 		It("parses a disc artwork ID with dc prefix", func() {
-			now := time.Now()
-			id := model.NewArtworkID(model.KindDiscArtwork, "albumid123:2", &now)
+			id := model.NewArtworkID(model.KindDiscArtwork, "albumid123:2", nil)
 			parsedId, err := model.ParseArtworkID(id.String())
 			Expect(err).ToNot(HaveOccurred())
 			Expect(parsedId.Kind).To(Equal(model.KindDiscArtwork))
 			Expect(parsedId.ID).To(Equal("albumid123:2"))
-			Expect(parsedId.LastUpdate.Unix()).To(Equal(now.Unix()))
 		})
 	})
 
@@ -67,6 +82,7 @@ var _ = Describe("ArtworkID", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(id.Kind).To(Equal(model.KindAlbumArtwork))
 			Expect(id.ID).To(Equal("1234"))
+			Expect(id.Hash).To(BeEmpty())
 		})
 		It("parses media file artwork ids", func() {
 			id, err := model.ParseArtworkID("mf-a6f8d2b1")
@@ -74,12 +90,45 @@ var _ = Describe("ArtworkID", func() {
 			Expect(id.Kind).To(Equal(model.KindMediaFileArtwork))
 			Expect(id.ID).To(Equal("a6f8d2b1"))
 		})
-		It("parses playlists artwork ids", func() {
+		It("parses playlist artwork ids with dashed UUID", func() {
 			id, err := model.ParseArtworkID("pl-18690de0-151b-4d86-81cb-f418a907315a")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(id.Kind).To(Equal(model.KindPlaylistArtwork))
 			Expect(id.ID).To(Equal("18690de0-151b-4d86-81cb-f418a907315a"))
 		})
+		It("captures a 16-hex suffix as Hash", func() {
+			id, err := model.ParseArtworkID("al-1234_abcdef0123456789")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(id.ID).To(Equal("1234"))
+			Expect(id.Hash).To(Equal("abcdef0123456789"))
+			Expect(id.LastUpdate.IsZero()).To(BeTrue())
+		})
+		It("captures a high-bit 16-hex suffix as Hash without error", func() {
+			id, err := model.ParseArtworkID("al-1234_ffffffffffffffff")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(id.ID).To(Equal("1234"))
+			Expect(id.Hash).To(Equal("ffffffffffffffff"))
+		})
+		It("parses a legacy hex-timestamp suffix as LastUpdate", func() {
+			id, err := model.ParseArtworkID("al-123_688a1b2c")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(id.ID).To(Equal("123"))
+			Expect(id.Hash).To(BeEmpty())
+			Expect(id.LastUpdate.Unix()).To(Equal(int64(0x688a1b2c)))
+		})
+		It("parses a legacy _0 suffix", func() {
+			id, err := model.ParseArtworkID("al-123_0")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(id.ID).To(Equal("123"))
+			Expect(id.Hash).To(BeEmpty())
+			Expect(id.LastUpdate.IsZero()).To(BeTrue())
+		})
+		It("silently drops a garbage suffix", func() {
+			id, err := model.ParseArtworkID("al-123_zz")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(id.ID).To(Equal("123"))
+			Expect(id.Hash).To(BeEmpty())
+		})
 		It("fails to parse malformed ids", func() {
 			_, err := model.ParseArtworkID("a6f8d2b1")
 			Expect(err).To(MatchError("invalid artwork id"))
diff --git a/model/artwork_test.go b/model/artwork_test.go
new file mode 100644
index 000000000..baf741e68
--- /dev/null
+++ b/model/artwork_test.go
@@ -0,0 +1,73 @@
+package model_test
+
+import (
+	"encoding/json"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func jsonOf(v any) map[string]any {
+	GinkgoHelper()
+	data, err := json.Marshal(v)
+	Expect(err).ToNot(HaveOccurred())
+	var out map[string]any
+	Expect(json.Unmarshal(data, &out)).To(Succeed())
+	return out
+}
+
+var _ = Describe("ItemImage JSON", func() {
+	It("exposes the artwork state a client needs to render a placeholder", func() {
+		al := model.Album{ID: "al-1", Name: "Album"}
+		al.ImageHash = "0123456789abcdef"
+		al.ThumbHash = "1QcSHQRn"
+		al.ImageWidth, al.ImageHeight = 1200, 800
+
+		Expect(jsonOf(al)).To(SatisfyAll(
+			HaveKeyWithValue("imageHash", "0123456789abcdef"),
+			HaveKeyWithValue("thumbHash", "1QcSHQRn"),
+			HaveKeyWithValue("imageWidth", BeNumerically("==", 1200)),
+			HaveKeyWithValue("imageHeight", BeNumerically("==", 800)),
+		))
+	})
+
+	It("keeps the blurhash off the native API, where nothing consumes it", func() {
+		al := model.Album{ID: "al-1", Name: "Album"}
+		al.BlurHash = "LEHV6nWB2yk8"
+		Expect(jsonOf(al)).ToNot(HaveKey("blurHash"))
+	})
+
+	It("omits every artwork field when the entity has none", func() {
+		out := jsonOf(model.Album{ID: "al-2", Name: "Album"})
+		for _, key := range []string{
+			"imageHash", "blurHash", "thumbHash", "imageAbsent", "imageWidth", "imageHeight",
+		} {
+			Expect(out).ToNot(HaveKey(key))
+		}
+	})
+
+	It("exposes known-absent artwork so clients can skip the request", func() {
+		ar := model.Artist{ID: "ar-1", Name: "Artist"}
+		ar.ImageAbsent = true
+		Expect(jsonOf(ar)).To(HaveKeyWithValue("imageAbsent", true))
+	})
+
+	Describe("AspectRatio", func() {
+		It("returns width/height", func() {
+			img := model.ItemImage{ImageHash: "abc", ImageWidth: 1200, ImageHeight: 800}
+			Expect(*img.AspectRatio()).To(BeNumerically("~", 1.5, 0.0001))
+		})
+
+		It("returns nil when a dimension is missing, so callers never guess a ratio", func() {
+			Expect(model.ItemImage{ImageHash: "abc"}.AspectRatio()).To(BeNil())
+			Expect(model.ItemImage{ImageHash: "abc", ImageWidth: 1200}.AspectRatio()).To(BeNil())
+			Expect(model.ItemImage{ImageHash: "abc", ImageHeight: 800}.AspectRatio()).To(BeNil())
+		})
+
+		It("returns nil for a known-absent image, whatever the dimensions say", func() {
+			img := model.ItemImage{ImageAbsent: true, ImageWidth: 1200, ImageHeight: 800}
+			Expect(img.AspectRatio()).To(BeNil())
+		})
+	})
+})
diff --git a/model/datastore.go b/model/datastore.go
index 94c3c3622..273ca714b 100644
--- a/model/datastore.go
+++ b/model/datastore.go
@@ -40,6 +40,8 @@ type DataStore interface {
 	ScrobbleBuffer(ctx context.Context) ScrobbleBufferRepository
 	Scrobble(ctx context.Context) ScrobbleRepository
 	Plugin(ctx context.Context) PluginRepository
+	Artwork(ctx context.Context) ArtworkRepository
+	ArtworkQueue(ctx context.Context) ArtworkQueueRepository
 
 	Resource(ctx context.Context, model any) ResourceRepository
 
diff --git a/model/mediafile.go b/model/mediafile.go
index 22ab7fbbe..ac1fad67b 100644
--- a/model/mediafile.go
+++ b/model/mediafile.go
@@ -24,6 +24,11 @@ import (
 type MediaFile struct {
 	Annotations  `structs:"-" hash:"ignore"`
 	Bookmarkable `structs:"-" hash:"ignore"`
+	ItemImage    `structs:"-" hash:"ignore"`
+
+	// AlbumImage is the parent album's artwork state, hydrated alongside the track's own so a
+	// song's Jellyfin album-art tag can be pixel-versioned without a second query.
+	AlbumImage ItemImage `structs:"-" json:"-" hash:"ignore"`
 
 	ID          string `structs:"id"  json:"id" hash:"ignore"`
 	PID         string `structs:"pid" json:"-" hash:"ignore"`
@@ -139,13 +144,15 @@ func (mf MediaFile) CoverArtID() ArtworkID {
 // otherwise it returns the album artwork ID.
 func (mf MediaFile) DiscCoverArtID() ArtworkID {
 	if mf.DiscNumber > 0 {
-		return NewArtworkID(KindDiscArtwork, DiscArtworkID(mf.AlbumID, mf.DiscNumber), nil)
+		return ArtworkID{Kind: KindDiscArtwork, ID: DiscArtworkID(mf.AlbumID, mf.DiscNumber), Hash: mf.ImageHash}
 	}
 	return mf.AlbumCoverArtID()
 }
 
+// AlbumCoverArtID uses AlbumImage, not the track's own ItemImage: an album id must carry the
+// album's content hash even when the track resolved art of its own.
 func (mf MediaFile) AlbumCoverArtID() ArtworkID {
-	return artworkIDFromAlbum(Album{ID: mf.AlbumID})
+	return artworkIDFromAlbum(Album{ID: mf.AlbumID, ItemImage: mf.AlbumImage})
 }
 
 func (mf MediaFile) StructuredLyrics() (LyricList, error) {
@@ -542,6 +549,11 @@ type MediaFileRepository interface {
 	GetRandom(options ...QueryOptions) (MediaFiles, error)
 	GetAllByTags(tag TagName, values []string, options ...QueryOptions) (MediaFiles, error)
 	GetCursor(options ...QueryOptions) (MediaFileCursor, error)
+	// GetAllIDs returns just the media_file IDs for the same row set as GetAll.
+	GetAllIDs(options ...QueryOptions) ([]string, error)
+	// GetCursorWithArtwork streams like GetCursor, hydrated, so callers that render images don't
+	// pay the scanner's per-row cost; it uses the same id pre-pass as the other cursors.
+	GetCursorWithArtwork(options ...QueryOptions) (MediaFileCursor, error)
 	Delete(id string) error
 	DeleteMissing(ids []string) error
 	DeleteAllMissing() (int64, error)
diff --git a/model/playlist.go b/model/playlist.go
index 185f6f942..9aa54bf13 100644
--- a/model/playlist.go
+++ b/model/playlist.go
@@ -13,6 +13,7 @@ import (
 
 type Playlist struct {
 	Annotations `structs:"-"`
+	ItemImage   `structs:"-"`
 
 	ID               string         `structs:"id" json:"id"`
 	Name             string         `structs:"name" json:"name"`
@@ -143,6 +144,7 @@ type PlaylistRepository interface {
 	Get(id string) (*Playlist, error)
 	GetWithTracks(id string, refreshSmartPlaylist, includeMissing bool) (*Playlist, error)
 	GetAll(options ...QueryOptions) (Playlists, error)
+	GetAllIDs(options ...QueryOptions) ([]string, error)
 	GetCursor(options ...QueryOptions) (PlaylistCursor, error)
 	FindByPath(path string) (*Playlist, error)
 	Delete(id string) error
diff --git a/model/radio.go b/model/radio.go
index 86f27c24c..466ff48b0 100644
--- a/model/radio.go
+++ b/model/radio.go
@@ -7,6 +7,8 @@ import (
 )
 
 type Radio struct {
+	ItemImage `structs:"-"`
+
 	ID            string    `structs:"id"              json:"id"`
 	StreamUrl     string    `structs:"stream_url"      json:"streamUrl"`
 	Name          string    `structs:"name"            json:"name"`
@@ -30,7 +32,9 @@ type RadioRepository interface {
 	ResourceRepository
 	CountAll(options ...QueryOptions) (int64, error)
 	Delete(id string) error
+	Exists(id string) (bool, error)
 	Get(id string) (*Radio, error)
 	GetAll(options ...QueryOptions) (Radios, error)
+	GetAllIDs(options ...QueryOptions) ([]string, error)
 	Put(u *Radio, colsToUpdate ...string) error
 }
diff --git a/model/radio_test.go b/model/radio_test.go
index 860331f17..6ae74c3f4 100644
--- a/model/radio_test.go
+++ b/model/radio_test.go
@@ -14,12 +14,11 @@ import (
 var _ = Describe("Radio", func() {
 	Describe("CoverArtID", func() {
 		It("returns a radio artwork ID", func() {
-			now := time.Now()
-			r := model.Radio{ID: "rd-1", UpdatedAt: now}
+			r := model.Radio{ID: "rd-1", UpdatedAt: time.Now()}
 			artID := r.CoverArtID()
 			Expect(artID.Kind).To(Equal(model.KindRadioArtwork))
 			Expect(artID.ID).To(Equal("rd-1"))
-			Expect(artID.LastUpdate).To(Equal(now))
+			Expect(artID.LastUpdate.IsZero()).To(BeTrue())
 		})
 	})
 
diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 2bb541003..1ebb09751 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -202,7 +202,9 @@ func (r *albumRepository) CountAll(options ...model.QueryOptions) (int64, error)
 }
 
 func (r *albumRepository) Exists(id string) (bool, error) {
-	return r.exists(Eq{"album.id": id})
+	// The exists() helper applies no library filter, so it would report rows the caller cannot see.
+	c, err := r.count(r.applyLibraryFilter(r.newSelect().Where(Eq{"album.id": id})))
+	return c > 0, err
 }
 
 func (r *albumRepository) Put(al *model.Album) error {
@@ -251,16 +253,36 @@ func (r *albumRepository) GetAll(options ...model.QueryOptions) (model.Albums, e
 	if err != nil {
 		return nil, err
 	}
-	return res.toModels(), nil
+	albums := res.toModels()
+	r.hydrateArtwork(albums)
+	return albums, nil
+}
+
+func (r *albumRepository) hydrateArtwork(albums model.Albums) {
+	hydrateItems(r.ctx, r.db, model.KindAlbumArtwork, albums,
+		func(a *model.Album) (string, *model.ItemImage) { return a.ID, &a.ItemImage })
+}
+
+// GetAllIDs returns the IDs of GetAll's row set, skipping its column projection and JSON decoding.
+func (r *albumRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+	sq := r.applyLibraryFilter(r.newSelect(options...).Columns("album.id"))
+	if filtersNeedAnnotation(sq) {
+		sq = r.withAnnotation(sq, "album.id")
+	}
+	ids := []string{}
+	err := r.queryAllSlice(sq, &ids)
+	return ids, err
 }
 
 func (r *albumRepository) GetCursor(options ...model.QueryOptions) (model.AlbumCursor, error) {
-	sq := r.selectAlbum(options...)
-	cursor, err := queryWithStableResults[dbAlbum](r.sqlRepository, sq)
+	ids, err := r.GetAllIDs(options...)
 	if err != nil {
 		return nil, err
 	}
-	return wrapAlbumCursor(cursor), nil
+	opts := chunkOptions(options, "album.id")
+	return model.AlbumCursor(streamByIDs(ids, func(chunk []string) (model.Albums, error) {
+		return r.GetAll(opts(chunk))
+	})), nil
 }
 
 func (r *albumRepository) GetYears(libraryIDs ...int) ([]int, error) {
@@ -405,7 +427,9 @@ func (r *albumRepository) Search(q string, options ...model.QueryOptions) (model
 	if err != nil {
 		return nil, fmt.Errorf("searching album %q: %w", q, err)
 	}
-	return res.toModels(), nil
+	albums := res.toModels()
+	r.hydrateArtwork(albums)
+	return albums, nil
 }
 
 func (r *albumRepository) Count(options ...rest.QueryOptions) (int64, error) {
diff --git a/persistence/album_repository_test.go b/persistence/album_repository_test.go
index 465617b10..1ead89529 100644
--- a/persistence/album_repository_test.go
+++ b/persistence/album_repository_test.go
@@ -13,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -84,6 +85,17 @@ var _ = Describe("AlbumRepository", func() {
 		})
 	})
 
+	Describe("GetAllIDs", func() {
+		It("returns the same id set as GetAll", func() {
+			want, err := albumRepo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(want).ToNot(BeEmpty())
+			ids, err := albumRepo.GetAllIDs()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ids).To(ConsistOf(slice.Map(want, func(a model.Album) string { return a.ID })))
+		})
+	})
+
 	Describe("GetAll", func() {
 		var GetAll = func(opts ...model.QueryOptions) (model.Albums, error) {
 			albums, err := albumRepo.GetAll(opts...)
@@ -977,6 +989,22 @@ var _ = Describe("AlbumRepository", func() {
 			Expect(got.RGAlbumPeak).To(BeNil())
 		})
 	})
+
+	// Exists must apply the same library filter as Get/GetAll/CountAll.
+	Describe("Exists library visibility", func() {
+		It("hides an album the user has no library access to", func() {
+			Expect(albumRepo.Put(&model.Album{ID: "vis-album", Name: "Vis", LibraryID: 1})).To(Succeed())
+			DeferCleanup(func() {
+				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": "vis-album"}))
+			})
+
+			Expect(albumRepo.Exists("vis-album")).To(BeTrue(), "admin sees it")
+
+			restricted := model.User{ID: "restricted_album_user", UserName: "ra", Name: "RA", Email: "ra@t.com"}
+			rctx := request.WithUser(GinkgoT().Context(), restricted)
+			Expect(NewAlbumRepository(rctx, GetDBXBuilder()).Exists("vis-album")).To(BeFalse())
+		})
+	})
 })
 
 func _p(id, name string, sortName ...string) model.Participant {
diff --git a/persistence/artist_repository.go b/persistence/artist_repository.go
index b542dedb4..67d0df448 100644
--- a/persistence/artist_repository.go
+++ b/persistence/artist_repository.go
@@ -6,7 +6,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"iter"
 	"os"
 	"slices"
 	"strings"
@@ -250,6 +249,7 @@ func (r *artistRepository) Get(id string) (*model.Artist, error) {
 		return nil, model.ErrNotFound
 	}
 	res := dba.toModels()
+	r.hydrateArtwork(res)
 	return &res[0], nil
 }
 
@@ -261,20 +261,37 @@ func (r *artistRepository) GetAll(options ...model.QueryOptions) (model.Artists,
 		return nil, err
 	}
 	res := dba.toModels()
+	r.hydrateArtwork(res)
 	return res, err
 }
 
+// GetAllIDs returns just the artist IDs for the same row set as GetAll, skipping the
+// heavy stats columns and JSON post-processing.
+func (r *artistRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+	sq := r.applyLibraryFilterToArtistQuery(r.newSelect(options...).Columns("artist.id")).GroupBy("artist.id")
+	if filtersNeedAnnotation(sq) {
+		sq = r.withAnnotation(sq, "artist.id")
+	}
+	ids := []string{}
+	err := r.queryAllSlice(sq, &ids)
+	return ids, err
+}
+
+// hydrateArtwork fills each artist's ImageHash/ImageAbsent from one batched item_artwork lookup.
+func (r *artistRepository) hydrateArtwork(artists model.Artists) {
+	hydrateItems(r.ctx, r.db, model.KindArtistArtwork, artists,
+		func(a *model.Artist) (string, *model.ItemImage) { return a.ID, &a.ItemImage })
+}
+
 func (r *artistRepository) GetCursor(options ...model.QueryOptions) (model.ArtistCursor, error) {
-	sel := r.selectArtist(options...)
-	cursor, err := queryWithStableResults[dbArtist](r.sqlRepository, sel)
+	ids, err := r.GetAllIDs(options...)
 	if err != nil {
 		return nil, err
 	}
-	return wrapArtistCursor(cursor), nil
-}
-
-func wrapArtistCursor(cursor iter.Seq2[dbArtist, error]) model.ArtistCursor {
-	return model.ArtistCursor(wrapCursor(cursor, func(a dbArtist) *model.Artist { return a.Artist }))
+	opts := chunkOptions(options, "artist.id")
+	return model.ArtistCursor(streamByIDs(ids, func(chunk []string) (model.Artists, error) {
+		return r.GetAll(opts(chunk))
+	})), nil
 }
 
 func (r *artistRepository) getIndexKey(a model.Artist) string {
@@ -635,7 +652,9 @@ func (r *artistRepository) Search(q string, options ...model.QueryOptions) (mode
 	if err != nil {
 		return nil, fmt.Errorf("searching artist %q: %w", q, err)
 	}
-	return res.toModels(), nil
+	artists := res.toModels()
+	r.hydrateArtwork(artists)
+	return artists, nil
 }
 
 // searchScope returns the library IDs the search must be restricted to, or nil to skip the filter
diff --git a/persistence/artist_repository_test.go b/persistence/artist_repository_test.go
index dc11ede36..25472ffe1 100644
--- a/persistence/artist_repository_test.go
+++ b/persistence/artist_repository_test.go
@@ -15,6 +15,7 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/utils"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -284,6 +285,17 @@ var _ = Describe("ArtistRepository", func() {
 			})
 		})
 
+		Describe("GetAllIDs", func() {
+			It("returns the same id set as GetAll", func() {
+				want, err := repo.GetAll()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(want).ToNot(BeEmpty())
+				ids, err := repo.GetAllIDs()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(ids).To(ConsistOf(slice.Map(want, func(a model.Artist) string { return a.ID })))
+			})
+		})
+
 		Describe("Basic Operations", func() {
 			Describe("Count", func() {
 				It("returns the number of artists in the DB", func() {
diff --git a/persistence/artwork_hydration.go b/persistence/artwork_hydration.go
new file mode 100644
index 000000000..fa9920f27
--- /dev/null
+++ b/persistence/artwork_hydration.go
@@ -0,0 +1,181 @@
+package persistence
+
+import (
+	"context"
+	"iter"
+	"slices"
+
+	. "github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/pocketbase/dbx"
+)
+
+// Keeps the id IN-list under SQLite's bound-parameter limit; a whole multiple of artworkBatchSize
+// so a page re-chunks into even hydration batches.
+const artworkChunkSize = artworkBatchSize * 3
+
+// streamByIDs yields rows in id chunks through the caller's hydrating fetch. Resolving ids first
+// keeps OFFSET out of the joined query.
+func streamByIDs[S ~[]T, T any](ids []string, fetch func(chunk []string) (S, error)) iter.Seq2[T, error] {
+	return func(yield func(T, error) bool) {
+		for chunk := range slices.Chunk(ids, artworkChunkSize) {
+			rows, err := fetch(chunk)
+			if err != nil {
+				var zero T
+				yield(zero, err)
+				return
+			}
+			for _, row := range rows {
+				if !yield(row, nil) {
+					return
+				}
+			}
+		}
+	}
+}
+
+// chunkOptions narrows options to a chunk of ids, dropping Max/Offset (the id pre-pass already
+// consumed them) and reusing Sort, which may be a seeded random expression by now.
+func chunkOptions(options []model.QueryOptions, idField string) func([]string) model.QueryOptions {
+	var base model.QueryOptions
+	if len(options) > 0 {
+		base = model.QueryOptions{Sort: options[0].Sort, Order: options[0].Order, Filters: options[0].Filters}
+	}
+	return func(chunk []string) model.QueryOptions {
+		opts := base
+		opts.Filters = Eq{idField: chunk}
+		if base.Filters != nil {
+			opts.Filters = And{base.Filters, opts.Filters}
+		}
+		return opts
+	}
+}
+
+// hydrateItemImages returns per-item artwork info in one batched query per kind. On error it logs
+// and returns an empty map, so the page still renders.
+func hydrateItemImages(ctx context.Context, db dbx.Builder, kind model.Kind, ids []string) map[string]model.ItemArtworkInfo {
+	if len(ids) == 0 {
+		return map[string]model.ItemArtworkInfo{}
+	}
+	infos, err := NewArtworkRepository(ctx, db).GetInfoForItems(kind, ids)
+	if err != nil {
+		log.Error(ctx, "Failed to hydrate artwork info onto page", "kind", kind, err)
+		return map[string]model.ItemArtworkInfo{}
+	}
+	return infos
+}
+
+// applyItemImage copies a hydration entry onto img; a missing entry leaves it zero (unresolved).
+func applyItemImage(infos map[string]model.ItemArtworkInfo, id string, img *model.ItemImage) {
+	if info, ok := infos[id]; ok {
+		*img = info.Image()
+	}
+}
+
+// hydrateItems fills every item's embedded ItemImage from one batched lookup. ref yields an
+// item's id and the ItemImage to fill, which is all that differs between the entity kinds.
+func hydrateItems[T any](ctx context.Context, db dbx.Builder, kind model.Kind, items []T,
+	ref func(*T) (string, *model.ItemImage)) {
+	ids := make([]string, len(items))
+	for i := range items {
+		ids[i], _ = ref(&items[i])
+	}
+	infos := hydrateItemImages(ctx, db, kind, ids)
+	for i := range items {
+		id, img := ref(&items[i])
+		applyItemImage(infos, id, img)
+	}
+}
+
+// hydrateMediaFileArtwork mirrors MediaFile.CoverArtID: an embedded-eligible file with resolved own
+// art uses it, else it falls back to the album's.
+func hydrateMediaFileArtwork(ctx context.Context, db dbx.Builder, mfs model.MediaFiles) {
+	if len(mfs) == 0 {
+		return
+	}
+	albumIDs := make([]string, len(mfs))
+	var eligibleIDs []string
+	for i := range mfs {
+		albumIDs[i] = mfs[i].AlbumID
+		if mfs[i].HasCoverArt && conf.Server.EnableMediaFileCoverArt {
+			eligibleIDs = append(eligibleIDs, mfs[i].ID)
+		}
+	}
+	albumInfos := hydrateItemImages(ctx, db, model.KindAlbumArtwork, albumIDs)
+	mfInfos := hydrateItemImages(ctx, db, model.KindMediaFileArtwork, eligibleIDs)
+	for i := range mfs {
+		mf := &mfs[i]
+		applyItemImage(albumInfos, mf.AlbumID, &mf.AlbumImage)
+		eligible := mf.HasCoverArt && conf.Server.EnableMediaFileCoverArt
+		ownInfo, ownResolved := mfInfos[mf.ID]
+		if eligible && ownResolved && !ownInfo.Absent() {
+			mf.ItemImage = ownInfo.Image()
+			continue
+		}
+		ownWontResolve := !eligible || (ownResolved && ownInfo.Absent())
+		// Inherit the album hash only when serving returns those exact bytes: a multi-disc track is
+		// served disc art, and an eligible-but-unresolved one still extracts its own embedded image.
+		if album, ok := albumInfos[mf.AlbumID]; ok && !album.Absent() {
+			if mf.DiscNumber == 0 && ownWontResolve {
+				mf.ItemImage = album.Image()
+			}
+			continue
+		}
+		// Mark absent only when serving would definitively yield a placeholder; disc art and
+		// still-extractable embedded art both keep a track requestable.
+		if mf.DiscNumber > 0 {
+			continue
+		}
+		if album, ok := albumInfos[mf.AlbumID]; ok && album.Absent() && ownWontResolve {
+			mf.ImageAbsent = true
+		}
+	}
+}
+
+// hydrateCursor hydrates a streamed cursor in batches, avoiding a per-row query.
+func hydrateCursor[T any](cursor iter.Seq2[T, error], hydrate func([]T)) iter.Seq2[T, error] {
+	return func(yield func(T, error) bool) {
+		buf := make([]T, 0, artworkBatchSize)
+		flush := func() bool {
+			hydrate(buf)
+			for i := range buf {
+				if !yield(buf[i], nil) {
+					return false
+				}
+			}
+			buf = buf[:0]
+			return true
+		}
+		for row, err := range cursor {
+			if err != nil {
+				var zero T
+				yield(zero, err)
+				return
+			}
+			buf = append(buf, row)
+			if len(buf) == artworkBatchSize && !flush() {
+				return
+			}
+		}
+		if len(buf) > 0 {
+			flush()
+		}
+	}
+}
+
+// hydratePlaylistTrackArtwork hydrates the MediaFile embedded in each playlist track.
+func hydratePlaylistTrackArtwork(ctx context.Context, db dbx.Builder, tracks model.PlaylistTracks) {
+	if len(tracks) == 0 {
+		return
+	}
+	mfs := make(model.MediaFiles, len(tracks))
+	for i := range tracks {
+		mfs[i] = tracks[i].MediaFile
+	}
+	hydrateMediaFileArtwork(ctx, db, mfs)
+	for i := range tracks {
+		tracks[i].MediaFile = mfs[i]
+	}
+}
diff --git a/persistence/artwork_hydration_test.go b/persistence/artwork_hydration_test.go
new file mode 100644
index 000000000..2b52d7d82
--- /dev/null
+++ b/persistence/artwork_hydration_test.go
@@ -0,0 +1,773 @@
+package persistence
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/slice"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/pocketbase/dbx"
+)
+
+// seedAnnotations gives each id distinct annotation values, writing them directly so that
+// SetRating's average_rating update does not outlive the cleanup.
+func seedAnnotations(itemType string, ids ...string) {
+	GinkgoHelper()
+	when := time.Date(2024, 3, 1, 12, 0, 0, 0, time.UTC)
+	for i, id := range ids {
+		_, err := GetDBXBuilder().NewQuery(`insert or replace into annotation
+			(user_id, item_id, item_type, play_count, play_date, rating, rated_at, starred, starred_at)
+			values ({:u}, {:id}, {:t}, {:pc}, {:d}, {:r}, {:d}, 1, {:d})`).
+			Bind(dbx.Params{"u": adminUser.ID, "id": id, "t": itemType,
+				"pc": i + 1, "r": 4 + i, "d": when.Add(time.Duration(i) * time.Hour)}).Execute()
+		Expect(err).ToNot(HaveOccurred())
+	}
+	DeferCleanup(func() {
+		for _, id := range ids {
+			_, err := GetDBXBuilder().NewQuery("delete from annotation where user_id={:u} and item_type={:t} and item_id={:id}").
+				Bind(dbx.Params{"u": adminUser.ID, "t": itemType, "id": id}).Execute()
+			Expect(err).ToNot(HaveOccurred())
+		}
+	})
+}
+
+var _ = Describe("Artwork hydration", func() {
+	var ctx context.Context
+	var aw model.ArtworkRepository
+
+	putInfo := func(kind, id, hash string) {
+		Expect(aw.PutItemArtwork(&model.ItemArtwork{
+			ItemKind: kind, ItemID: id, ImageType: model.ImageTypePrimary, Hash: hash,
+		})).To(Succeed())
+	}
+
+	BeforeEach(func() {
+		clearArtworkTables()
+		DeferCleanup(clearArtworkTables)
+		ctx = request.WithUser(log.NewContext(context.Background()), adminUser)
+		aw = NewArtworkRepository(ctx, GetDBXBuilder())
+	})
+
+	Describe("albums", func() {
+		var repo model.AlbumRepository
+		BeforeEach(func() { repo = NewAlbumRepository(ctx, GetDBXBuilder()) })
+
+		It("hydrates the found / known-absent / unresolved states", func() {
+			putInfo("al", albumSgtPeppers.ID, "althash11111111")
+			putInfo("al", albumAbbeyRoad.ID, "")
+			// albumRadioactivity: no row -> unresolved
+
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			byID := slice.ToMap(all, func(a model.Album) (string, model.Album) { return a.ID, a })
+
+			Expect(byID[albumSgtPeppers.ID].ImageHash).To(Equal("althash11111111"))
+			Expect(byID[albumSgtPeppers.ID].ImageAbsent).To(BeFalse())
+			Expect(byID[albumAbbeyRoad.ID].ImageHash).To(BeEmpty())
+			Expect(byID[albumAbbeyRoad.ID].ImageAbsent).To(BeTrue())
+			Expect(byID[albumRadioactivity.ID].ImageHash).To(BeEmpty())
+			Expect(byID[albumRadioactivity.ID].ImageAbsent).To(BeFalse())
+		})
+
+		It("hydrates Get", func() {
+			putInfo("al", albumSgtPeppers.ID, "gethash22222222")
+			got, err := repo.Get(albumSgtPeppers.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.ImageHash).To(Equal("gethash22222222"))
+		})
+
+		It("hydrates Search", func() {
+			putInfo("al", albumSgtPeppers.ID, "srchash33333333")
+			res, err := repo.Search("Peppers", model.QueryOptions{})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res).ToNot(BeEmpty())
+			Expect(res[0].ImageHash).To(Equal("srchash33333333"))
+		})
+
+		It("does not persist ImageHash/ImageAbsent on Put", func() {
+			al := albumSgtPeppers
+			al.ImageHash = "shouldnotpersist"
+			al.ImageAbsent = true
+			Expect(repo.(*albumRepository).Put(&al)).To(Succeed())
+
+			got, err := repo.Get(al.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.ImageHash).To(BeEmpty())
+			Expect(got.ImageAbsent).To(BeFalse())
+		})
+	})
+
+	Describe("artists", func() {
+		var repo model.ArtistRepository
+		BeforeEach(func() { repo = NewArtistRepository(ctx, GetDBXBuilder()) })
+
+		It("hydrates the found / known-absent / unresolved states", func() {
+			putInfo("ar", artistBeatles.ID, "arhash444444444")
+			putInfo("ar", artistKraftwerk.ID, "")
+			// artistCJK: no row -> unresolved
+
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			byID := slice.ToMap(all, func(a model.Artist) (string, model.Artist) { return a.ID, a })
+
+			Expect(byID[artistBeatles.ID].ImageHash).To(Equal("arhash444444444"))
+			Expect(byID[artistBeatles.ID].ImageAbsent).To(BeFalse())
+			Expect(byID[artistKraftwerk.ID].ImageHash).To(BeEmpty())
+			Expect(byID[artistKraftwerk.ID].ImageAbsent).To(BeTrue())
+			Expect(byID[artistCJK.ID].ImageHash).To(BeEmpty())
+			Expect(byID[artistCJK.ID].ImageAbsent).To(BeFalse())
+		})
+
+		It("hydrates Get", func() {
+			putInfo("ar", artistBeatles.ID, "arget5555555555")
+			got, err := repo.Get(artistBeatles.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.ImageHash).To(Equal("arget5555555555"))
+		})
+
+		It("hydrates Search", func() {
+			putInfo("ar", artistBeatles.ID, "arsrch666666666")
+			res, err := repo.Search("Beatles", model.QueryOptions{})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res).ToNot(BeEmpty())
+			Expect(res[0].ImageHash).To(Equal("arsrch666666666"))
+		})
+	})
+
+	Describe("playlists", func() {
+		var repo model.PlaylistRepository
+		BeforeEach(func() { repo = NewPlaylistRepository(ctx, GetDBXBuilder()) })
+
+		It("hydrates the found / known-absent states", func() {
+			putInfo("pl", plsBest.ID, "plhash777777777")
+			putInfo("pl", plsCool.ID, "")
+
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			byID := slice.ToMap(all, func(p model.Playlist) (string, model.Playlist) { return p.ID, p })
+
+			Expect(byID[plsBest.ID].ImageHash).To(Equal("plhash777777777"))
+			Expect(byID[plsBest.ID].ImageAbsent).To(BeFalse())
+			Expect(byID[plsCool.ID].ImageHash).To(BeEmpty())
+			Expect(byID[plsCool.ID].ImageAbsent).To(BeTrue())
+		})
+
+		It("hydrates Get", func() {
+			putInfo("pl", plsBest.ID, "plget8888888888")
+			got, err := repo.Get(plsBest.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.ImageHash).To(Equal("plget8888888888"))
+		})
+
+		It("hydrates the tracks reached through a playlist", func() {
+			Expect(aw.PutImage(&model.Artwork{Hash: "pltrackhash1234", Mime: "image/jpeg", BlurHash: "LPLBLURhash"})).To(Succeed())
+			putInfo("al", songDayInALife.AlbumID, "pltrackhash1234")
+
+			pls, err := repo.GetWithTracks(plsBest.ID, true, false)
+			Expect(err).ToNot(HaveOccurred())
+			tracks := pls.Tracks
+			Expect(tracks).ToNot(BeEmpty())
+			byID := slice.ToMap(tracks, func(t model.PlaylistTrack) (string, model.PlaylistTrack) { return t.MediaFile.ID, t })
+			Expect(byID).To(HaveKey(songDayInALife.ID))
+			Expect(byID[songDayInALife.ID].AlbumImage.ImageHash).To(Equal("pltrackhash1234"))
+			Expect(byID[songDayInALife.ID].BlurHash).To(Equal("LPLBLURhash"))
+
+			cursor, err := repo.Tracks(plsBest.ID, true).GetCursor()
+			Expect(err).ToNot(HaveOccurred())
+			var streamed *model.PlaylistTrack
+			for t, err := range cursor {
+				Expect(err).ToNot(HaveOccurred())
+				if t.MediaFile.ID == songDayInALife.ID {
+					streamed = &t
+				}
+			}
+			Expect(streamed).ToNot(BeNil())
+			Expect(streamed.AlbumImage.ImageHash).To(Equal("pltrackhash1234"),
+				"the streamed cursor Jellyfin uses must hydrate too")
+		})
+	})
+
+	Describe("radios", func() {
+		var repo model.RadioRepository
+		BeforeEach(func() { repo = NewRadioRepository(ctx, GetDBXBuilder()) })
+
+		It("hydrates the found / known-absent states", func() {
+			putInfo("ra", radioWithHomePage.ID, "rahash999999999")
+			putInfo("ra", radioWithoutHomePage.ID, "")
+
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			byID := slice.ToMap(all, func(rd model.Radio) (string, model.Radio) { return rd.ID, rd })
+
+			Expect(byID[radioWithHomePage.ID].ImageHash).To(Equal("rahash999999999"))
+			Expect(byID[radioWithHomePage.ID].ImageAbsent).To(BeFalse())
+			Expect(byID[radioWithoutHomePage.ID].ImageHash).To(BeEmpty())
+			Expect(byID[radioWithoutHomePage.ID].ImageAbsent).To(BeTrue())
+		})
+
+		It("hydrates Get", func() {
+			putInfo("ra", radioWithHomePage.ID, "ragetaaaaaaaaaa")
+			got, err := repo.Get(radioWithHomePage.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.ImageHash).To(Equal("ragetaaaaaaaaaa"))
+		})
+	})
+
+	Describe("mediafiles", func() {
+		var repo model.MediaFileRepository
+
+		setCover := func(id string, v bool) {
+			_, err := GetDBXBuilder().NewQuery("UPDATE media_file SET has_cover_art={:v} WHERE id={:id}").
+				Bind(dbx.Params{"v": v, "id": id}).Execute()
+			Expect(err).ToNot(HaveOccurred())
+		}
+
+		getByID := func() map[string]model.MediaFile {
+			all, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			return slice.ToMap(all, func(mf model.MediaFile) (string, model.MediaFile) { return mf.ID, mf })
+		}
+
+		BeforeEach(func() {
+			repo = NewMediaFileRepository(ctx, GetDBXBuilder())
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.EnableMediaFileCoverArt = true
+		})
+
+		It("resolves the embedded-eligible fallback matrix", func() {
+			setCover("1001", true) // eligible, own hash
+			setCover("1002", true) // eligible, but embedded art absent -> album
+			DeferCleanup(func() { setCover("1001", false); setCover("1002", false) })
+
+			putInfo("al", "101", "alh101xxxxxxxxxx") // song 1001's album (found)
+			putInfo("al", "102", "alh102xxxxxxxxxx") // song 1002's album (found)
+			putInfo("al", "103", "")                 // songs 1003/1004 album known-absent
+			putInfo("mf", "1001", "mfh1001xxxxxxxx")
+			putInfo("mf", "1002", "") // embedded resolved absent
+
+			byID := getByID()
+
+			Expect(byID["1001"].ImageHash).To(Equal("mfh1001xxxxxxxx"))
+			Expect(byID["1001"].ImageAbsent).To(BeFalse())
+			Expect(byID["1002"].ImageHash).To(Equal("alh102xxxxxxxxxx"))
+			Expect(byID["1002"].ImageAbsent).To(BeFalse())
+			Expect(byID["1003"].ImageHash).To(BeEmpty())
+			Expect(byID["1003"].ImageAbsent).To(BeTrue())
+			// 2002: not eligible, and its album has no row at all -> unresolved
+			Expect(byID["2002"].ImageHash).To(BeEmpty())
+			Expect(byID["2002"].ImageAbsent).To(BeFalse())
+		})
+
+		It("populates AlbumImage from hydrateArtwork regardless of which continue branch a track takes", func() {
+			setCover("1001", true) // eligible, resolves its own art -> own-art-wins continue
+			DeferCleanup(func() { setCover("1001", false) })
+
+			putInfo("al", "101", "alh101albimgxxxx") // 1001's album: own-art-wins branch
+			putInfo("al", "102", "alh102albimgxxxx") // 1002's album: single-disc inheritance branch
+			putInfo("al", "104", "")                 // 2002's album: known-absent, multi-disc branch
+			putInfo("mf", "1001", "mfh1001albimgxxx")
+
+			byID := getByID()
+
+			Expect(byID["1001"].ImageHash).To(Equal("mfh1001albimgxxx"))
+			Expect(byID["1001"].AlbumImage.ImageHash).To(Equal("alh101albimgxxxx"))
+
+			Expect(byID["1002"].ImageHash).To(Equal("alh102albimgxxxx"))
+			Expect(byID["1002"].AlbumImage.ImageHash).To(Equal("alh102albimgxxxx"))
+
+			Expect(byID["2002"].ImageHash).To(BeEmpty())
+			Expect(byID["2002"].ImageAbsent).To(BeFalse())
+			Expect(byID["2002"].AlbumImage.ImageAbsent).To(BeTrue())
+		})
+
+		It("carries both hashes and the dimensions alongside the hash in the own-art and inherited branches", func() {
+			setCover("1001", true) // eligible, resolves its own art -> own-art-wins branch
+			DeferCleanup(func() { setCover("1001", false) })
+
+			Expect(aw.PutImage(&model.Artwork{Hash: "mfh1001blurxxxxx", Mime: "image/jpeg", BlurHash: "LTRACKblur", ThumbHash: "THtrack", Width: 640, Height: 480})).To(Succeed())
+			Expect(aw.PutImage(&model.Artwork{Hash: "alh102blurxxxxxx", Mime: "image/jpeg", BlurHash: "LALBUMblur", ThumbHash: "THalbum", Width: 1200, Height: 800})).To(Succeed())
+			putInfo("mf", "1001", "mfh1001blurxxxxx")
+			putInfo("al", "102", "alh102blurxxxxxx") // 1002's album: single-disc inheritance branch
+
+			byID := getByID()
+
+			Expect(byID["1001"].ImageHash).To(Equal("mfh1001blurxxxxx"))
+			Expect(byID["1001"].BlurHash).To(Equal("LTRACKblur"))
+			Expect(byID["1001"].ThumbHash).To(Equal("THtrack"))
+			Expect(byID["1001"].ImageWidth).To(Equal(640))
+			Expect(byID["1001"].ImageHeight).To(Equal(480))
+
+			Expect(byID["1002"].ImageHash).To(Equal("alh102blurxxxxxx"))
+			Expect(byID["1002"].BlurHash).To(Equal("LALBUMblur"))
+			Expect(byID["1002"].ThumbHash).To(Equal("THalbum"))
+			Expect(byID["1002"].ImageWidth).To(Equal(1200))
+			Expect(byID["1002"].ImageHeight).To(Equal(800))
+		})
+
+		It("keeps an eligible file optimistic when its own art is unresolved, even if the album is absent", func() {
+			setCover("1004", true)
+			DeferCleanup(func() { setCover("1004", false) })
+			putInfo("al", "103", "") // album known-absent
+
+			byID := getByID()
+
+			// 1004's own embedded art is still unresolved, so coverArt must stay requestable.
+			Expect(byID["1004"].ImageAbsent).To(BeFalse())
+			Expect(byID["1004"].ImageHash).To(BeEmpty())
+			// 1003 is not eligible, so it still inherits the album's absence.
+			Expect(byID["1003"].ImageAbsent).To(BeTrue())
+		})
+
+		It("does not stamp a found album hash onto a multi-disc track (its dc- id is disc-served)", func() {
+			putInfo("al", "104", "alh104foundxxxxx") // songs 2002/2004 album is found
+
+			byID := getByID()
+
+			Expect(byID["2002"].ImageHash).To(BeEmpty())
+			Expect(byID["2002"].ImageAbsent).To(BeFalse())
+		})
+
+		It("keeps a multi-disc track requestable when its album is absent (disc art may resolve)", func() {
+			putInfo("al", "104", "") // songs 2002/2004 album known-absent
+
+			byID := getByID()
+
+			Expect(byID["2002"].ImageAbsent).To(BeFalse())
+			Expect(byID["2002"].ImageHash).To(BeEmpty())
+		})
+
+		// serveMediaFile serves this track's own embedded art, so the album's hash would
+		// advertise a content-version for bytes nobody will serve.
+		It("leaves the hash bare for an eligible file whose own art is unresolved", func() {
+			setCover("1004", true)
+			DeferCleanup(func() { setCover("1004", false) })
+			putInfo("al", "103", "alh103found11111")
+
+			byID := getByID()
+			Expect(byID["1004"].ImageAbsent).To(BeFalse())
+			Expect(byID["1004"].ImageHash).To(BeEmpty())
+			Expect(byID["1004"].AlbumImage.ImageHash).To(Equal("alh103found11111"),
+				"the album's own hash still hydrates, for AlbumCoverArtID")
+		})
+
+		It("uses album info for an eligible file when EnableMediaFileCoverArt is off", func() {
+			conf.Server.EnableMediaFileCoverArt = false
+			setCover("1001", true)
+			DeferCleanup(func() { setCover("1001", false) })
+
+			putInfo("al", "101", "alh101offxxxxxxx")
+			putInfo("mf", "1001", "mfh1001offxxxxx")
+
+			byID := getByID()
+			Expect(byID["1001"].ImageHash).To(Equal("alh101offxxxxxxx"))
+			Expect(byID["1001"].ImageAbsent).To(BeFalse())
+		})
+
+		It("hydrates Search", func() {
+			putInfo("al", "101", "alsrchhhhhhhhhhh")
+			res, err := repo.Search("A Day In A Life", model.QueryOptions{})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res).ToNot(BeEmpty())
+			Expect(res[0].ImageHash).To(Equal("alsrchhhhhhhhhhh"))
+		})
+	})
+
+	Describe("GetCursor", func() {
+		var albumRepo model.AlbumRepository
+		var artistRepo model.ArtistRepository
+		var playlistRepo model.PlaylistRepository
+		var onlyAlbums, onlyArtists, onlyPlaylists squirrel.Eq
+
+		scoped := func(opts model.QueryOptions, only squirrel.Eq) model.QueryOptions {
+			if opts.Filters == nil {
+				opts.Filters = only
+			} else {
+				opts.Filters = squirrel.And{only, opts.Filters}
+			}
+			return opts
+		}
+
+		BeforeEach(func() {
+			albumRepo = NewAlbumRepository(ctx, GetDBXBuilder())
+			artistRepo = NewArtistRepository(ctx, GetDBXBuilder())
+			playlistRepo = NewPlaylistRepository(ctx, GetDBXBuilder())
+			// Other specs leave rows behind, so scope every cursor spec to the fixtures.
+			onlyAlbums = squirrel.Eq{"album.id": []string{albumSgtPeppers.ID, albumAbbeyRoad.ID,
+				albumRadioactivity.ID, albumMultiDisc.ID, albumCJK.ID, albumPunctuation.ID}}
+			onlyArtists = squirrel.Eq{"artist.id": []string{artistKraftwerk.ID, artistBeatles.ID,
+				artistCJK.ID, artistPunctuation.ID}}
+			// Both fixture playlists share an owner, leaving the owner_name sort a single value to
+			// order by; this one is also private, which the non-admin visibility spec needs.
+			foreign := model.Playlist{Name: "Foreign", OwnerID: thirdUser.ID, OwnerName: thirdUser.UserName}
+			Expect(playlistRepo.Put(&foreign)).To(Succeed())
+			DeferCleanup(func() { Expect(playlistRepo.Delete(foreign.ID)).To(Succeed()) })
+			onlyPlaylists = squirrel.Eq{"playlist.id": []string{plsBest.ID, plsCool.ID, foreign.ID}}
+
+			// The suite annotates a single album and artist, leaving the annotation-backed sorts
+			// nothing to order.
+			seedAnnotations("album", albumSgtPeppers.ID, albumAbbeyRoad.ID)
+			seedAnnotations("artist", artistKraftwerk.ID, artistCJK.ID)
+
+			Expect(aw.PutImage(&model.Artwork{
+				Hash: "curhash11111111", Mime: "image/jpeg", BlurHash: "LEHV6nWB2yk8",
+			})).To(Succeed())
+			putInfo("al", albumSgtPeppers.ID, "curhash11111111")
+			putInfo("al", albumAbbeyRoad.ID, "")
+			putInfo("ar", artistBeatles.ID, "curhash11111111")
+			putInfo("pl", plsBest.ID, "curhash11111111")
+		})
+
+		It("hydrates every streamed album, like GetAll", func() {
+			opts := model.QueryOptions{Sort: "name", Filters: onlyAlbums}
+			want, err := albumRepo.GetAll(opts)
+			Expect(err).ToNot(HaveOccurred())
+
+			got := collectCursor(albumRepo.GetCursor(opts))
+
+			Expect(got).To(ConsistOf(want))
+			byID := map[string]model.Album{}
+			for _, al := range got {
+				byID[al.ID] = al
+			}
+			Expect(byID[albumSgtPeppers.ID].ImageHash).To(Equal("curhash11111111"))
+			Expect(byID[albumSgtPeppers.ID].BlurHash).To(Equal("LEHV6nWB2yk8"))
+			Expect(byID[albumAbbeyRoad.ID].ImageAbsent).To(BeTrue())
+			Expect(byID[albumRadioactivity.ID].ImageHash).To(BeEmpty())
+			Expect(byID[albumRadioactivity.ID].ImageAbsent).To(BeFalse())
+		})
+
+		It("hydrates every streamed artist, like GetAll", func() {
+			opts := model.QueryOptions{Sort: "name", Filters: onlyArtists}
+			want, err := artistRepo.GetAll(opts)
+			Expect(err).ToNot(HaveOccurred())
+
+			got := collectCursor(artistRepo.GetCursor(opts))
+
+			Expect(got).To(ConsistOf(want))
+			Expect(slice.Map(got, func(a model.Artist) string { return a.ImageHash })).
+				To(ContainElement("curhash11111111"))
+		})
+
+		It("hydrates every streamed playlist, like GetAll", func() {
+			opts := model.QueryOptions{Sort: "name", Filters: onlyPlaylists}
+			want, err := playlistRepo.GetAll(opts)
+			Expect(err).ToNot(HaveOccurred())
+
+			got := collectCursor(playlistRepo.GetCursor(opts))
+
+			Expect(got).To(ConsistOf(want))
+			Expect(slice.Map(got, func(p model.Playlist) string { return p.ImageHash })).
+				To(ContainElement("curhash11111111"))
+		})
+
+		It("honors Max and Offset exactly once", func() {
+			opts := model.QueryOptions{Sort: "name", Filters: onlyAlbums, Max: 2, Offset: 1}
+			want, err := albumRepo.GetAll(opts)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(want).To(HaveLen(2))
+
+			got := collectCursor(albumRepo.GetCursor(opts))
+
+			Expect(slice.Map(got, func(a model.Album) string { return a.ID })).
+				To(Equal(slice.Map(want, func(a model.Album) string { return a.ID })))
+		})
+
+		// The sorts the Jellyfin list endpoints issue; comparing sort keys, not ids, keeps ties out.
+		DescribeTable("orders albums like GetAll",
+			func(opts model.QueryOptions, key func(model.Album) string) {
+				opts = scoped(opts, onlyAlbums)
+				want, err := albumRepo.GetAll(opts)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(want).ToNot(BeEmpty())
+
+				got := collectCursor(albumRepo.GetCursor(opts))
+
+				Expect(slice.Map(got, key)).To(Equal(slice.Map(want, key)))
+				Expect(slice.Map(got, func(a model.Album) string { return a.ID })).
+					To(ConsistOf(slice.Map(want, func(a model.Album) string { return a.ID })))
+			},
+			Entry("by name", model.QueryOptions{Sort: "name"},
+				func(a model.Album) string { return a.OrderAlbumName }),
+			Entry("by artist", model.QueryOptions{Sort: "artist"},
+				func(a model.Album) string { return a.OrderAlbumArtistName }),
+			Entry("by recently added", model.QueryOptions{Sort: "recently_added", Order: "desc"},
+				func(a model.Album) string { return fmt.Sprint(a.CreatedAt) }),
+			Entry("by year", model.QueryOptions{Sort: "max_year"},
+				func(a model.Album) string { return fmt.Sprint(a.MaxYear) }),
+			Entry("by play count", model.QueryOptions{Sort: "play_count", Order: "desc"},
+				func(a model.Album) string { return fmt.Sprint(a.PlayCount) }),
+			Entry("by last played", model.QueryOptions{Sort: "play_date", Order: "desc"},
+				func(a model.Album) string { return fmt.Sprint(a.PlayDate) }),
+			Entry("by rating", model.QueryOptions{Sort: "rating", Order: "desc"},
+				func(a model.Album) string { return fmt.Sprint(a.Rating) }),
+			Entry("starred only", model.QueryOptions{Sort: "starred_at", Order: "desc",
+				Filters: squirrel.Eq{"starred": true}},
+				func(a model.Album) string { return fmt.Sprint(a.StarredAt) }),
+		)
+
+		DescribeTable("orders artists like GetAll",
+			func(opts model.QueryOptions, key func(model.Artist) string) {
+				opts = scoped(opts, onlyArtists)
+				want, err := artistRepo.GetAll(opts)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(want).ToNot(BeEmpty())
+
+				got := collectCursor(artistRepo.GetCursor(opts))
+
+				Expect(slice.Map(got, key)).To(Equal(slice.Map(want, key)))
+				Expect(slice.Map(got, func(a model.Artist) string { return a.ID })).
+					To(ConsistOf(slice.Map(want, func(a model.Artist) string { return a.ID })))
+			},
+			Entry("by name", model.QueryOptions{Sort: "name"},
+				func(a model.Artist) string { return a.OrderArtistName }),
+			Entry("by album count", model.QueryOptions{Sort: "album_count", Order: "desc"},
+				func(a model.Artist) string { return fmt.Sprint(a.AlbumCount) }),
+			Entry("by song count", model.QueryOptions{Sort: "song_count", Order: "desc"},
+				func(a model.Artist) string { return fmt.Sprint(a.SongCount) }),
+			Entry("by play count", model.QueryOptions{Sort: "play_count", Order: "desc"},
+				func(a model.Artist) string { return fmt.Sprint(a.PlayCount) }),
+			Entry("starred only", model.QueryOptions{Sort: "starred_at", Order: "desc",
+				Filters: squirrel.Eq{"starred": true}},
+				func(a model.Artist) string { return fmt.Sprint(a.StarredAt) }),
+		)
+
+		DescribeTable("orders playlists like GetAll",
+			func(opts model.QueryOptions, key func(model.Playlist) string) {
+				opts = scoped(opts, onlyPlaylists)
+				want, err := playlistRepo.GetAll(opts)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(want).ToNot(BeEmpty())
+
+				got := collectCursor(playlistRepo.GetCursor(opts))
+
+				Expect(slice.Map(got, key)).To(Equal(slice.Map(want, key)))
+				Expect(slice.Map(got, func(p model.Playlist) string { return p.ID })).
+					To(ConsistOf(slice.Map(want, func(p model.Playlist) string { return p.ID })))
+			},
+			Entry("by name", model.QueryOptions{Sort: "name"},
+				func(p model.Playlist) string { return p.Name }),
+			Entry("by creation date", model.QueryOptions{Sort: "created_at", Order: "desc"},
+				func(p model.Playlist) string { return fmt.Sprint(p.CreatedAt) }),
+			Entry("by owner", model.QueryOptions{Sort: "owner_name"},
+				func(p model.Playlist) string { return p.OwnerName }),
+		)
+
+		It("streams every album exactly once when sorted randomly", func() {
+			opts := model.QueryOptions{Sort: "random", Filters: onlyAlbums}
+			want, err := albumRepo.GetAll(opts)
+			Expect(err).ToNot(HaveOccurred())
+
+			got := collectCursor(albumRepo.GetCursor(opts))
+
+			Expect(slice.Map(got, func(a model.Album) string { return a.ID })).
+				To(ConsistOf(slice.Map(want, func(a model.Album) string { return a.ID })))
+		})
+
+		It("keeps a non-admin from streaming another user's private playlists", func() {
+			otherCtx := request.WithUser(log.NewContext(context.Background()), regularUser)
+			repo := NewPlaylistRepository(otherCtx, GetDBXBuilder())
+			opts := model.QueryOptions{Sort: "name", Filters: onlyPlaylists}
+
+			// Both phases must filter on their own: the id pre-pass and the chunk fetch.
+			Expect(repo.GetAllIDs(opts)).To(ConsistOf(plsBest.ID))
+			all, err := repo.GetAll(model.QueryOptions{Filters: onlyPlaylists})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(slice.Map(all, func(p model.Playlist) string { return p.ID })).To(ConsistOf(plsBest.ID))
+
+			got := collectCursor(repo.GetCursor(opts))
+
+			Expect(slice.Map(got, func(p model.Playlist) string { return p.Name })).
+				To(ConsistOf(plsBest.Name))
+		})
+	})
+
+	Describe("GetCursorWithArtwork", func() {
+		var mfRepo model.MediaFileRepository
+		var onlySongs squirrel.Eq
+
+		BeforeEach(func() {
+			mfRepo = NewMediaFileRepository(ctx, GetDBXBuilder())
+			putInfo("al", albumSgtPeppers.ID, "curhash11111111")
+			// Distinct titles only: other fixture songs share titles (e.g. "Antenna" x3), which
+			// would make the positional comparisons against GetAll pass by tie-order coincidence.
+			onlySongs = squirrel.Eq{"media_file.id": []string{songDayInALife.ID, songComeTogether.ID,
+				songRadioactivity.ID, songAntenna.ID, songDisc1Track01.ID, songCJK.ID, songPunctuation.ID}}
+		})
+
+		It("hydrates artwork onto every streamed track, unlike GetCursor", func() {
+			opts := model.QueryOptions{Sort: "title", Filters: onlySongs}
+			want, err := mfRepo.GetAll(opts)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(want).ToNot(BeEmpty())
+
+			cursor, err := mfRepo.GetCursorWithArtwork(opts)
+			Expect(err).ToNot(HaveOccurred())
+			var got model.MediaFiles
+			cursor(func(mf model.MediaFile, err error) bool {
+				Expect(err).ToNot(HaveOccurred())
+				got = append(got, mf)
+				return true
+			})
+
+			Expect(got).To(HaveLen(len(want)))
+			for i := range want {
+				Expect(got[i].ID).To(Equal(want[i].ID))
+				Expect(got[i].ImageHash).To(Equal(want[i].ImageHash))
+				Expect(got[i].ImageAbsent).To(Equal(want[i].ImageAbsent))
+				Expect(got[i].AlbumImage.ImageHash).To(Equal(want[i].AlbumImage.ImageHash))
+				Expect(got[i].AlbumImage.BlurHash).To(Equal(want[i].AlbumImage.BlurHash))
+			}
+			Expect(want).To(ContainElement(HaveField("AlbumImage.ImageHash", Not(BeEmpty()))),
+				"fixture must include at least one track with album artwork, or this proves nothing")
+		})
+
+		It("leaves the scanner's GetCursor unhydrated", func() {
+			cursor, err := mfRepo.GetCursor(model.QueryOptions{Sort: "title"})
+			Expect(err).ToNot(HaveOccurred())
+			var seen int
+			cursor(func(mf model.MediaFile, err error) bool {
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mf.AlbumImage.ImageHash).To(BeEmpty(), "GetCursor must stay unhydrated for the scanner")
+				seen++
+				return true
+			})
+			Expect(seen).To(BeNumerically(">", 0))
+		})
+
+		It("streams the same ids in the same order as GetAll", func() {
+			opts := model.QueryOptions{Sort: "title", Filters: onlySongs}
+			want, err := mfRepo.GetAll(opts)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(want).ToNot(BeEmpty())
+
+			got := collectCursor(mfRepo.GetCursorWithArtwork(opts))
+
+			Expect(slice.Map(got, func(mf model.MediaFile) string { return mf.ID })).
+				To(Equal(slice.Map(want, func(mf model.MediaFile) string { return mf.ID })))
+		})
+
+		It("honors Max and Offset exactly once", func() {
+			opts := model.QueryOptions{Sort: "title", Filters: onlySongs, Max: 2, Offset: 1}
+			want, err := mfRepo.GetAll(opts)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(want).To(HaveLen(2))
+
+			got := collectCursor(mfRepo.GetCursorWithArtwork(opts))
+
+			Expect(slice.Map(got, func(mf model.MediaFile) string { return mf.ID })).
+				To(Equal(slice.Map(want, func(mf model.MediaFile) string { return mf.ID })))
+		})
+	})
+
+	Describe("chunkOptions", func() {
+		It("carries Sort, Order and the caller's filters, but never Max/Offset", func() {
+			base := model.QueryOptions{Sort: "name", Order: "desc", Max: 10, Offset: 20,
+				Filters: squirrel.Eq{"missing": false}}
+
+			got := chunkOptions([]model.QueryOptions{base}, "album.id")([]string{"al-1", "al-2"})
+
+			Expect(got.Max).To(BeZero())
+			Expect(got.Offset).To(BeZero())
+			Expect(got.Sort).To(Equal("name"))
+			Expect(got.Order).To(Equal("desc"))
+			Expect(got.Filters).To(Equal(squirrel.And{
+				base.Filters, squirrel.Eq{"album.id": []string{"al-1", "al-2"}},
+			}))
+		})
+
+		It("filters by ids alone when the caller passed no filters", func() {
+			got := chunkOptions(nil, "artist.id")([]string{"ar-1"})
+			Expect(got.Filters).To(Equal(squirrel.Eq{"artist.id": []string{"ar-1"}}))
+		})
+	})
+
+	Describe("streamByIDs", func() {
+		It("fetches in chunks and yields every row in order", func() {
+			ids := make([]string, artworkChunkSize+3)
+			for i := range ids {
+				ids[i] = fmt.Sprintf("id-%d", i)
+			}
+			var chunks [][]string
+			got := collectCursor(streamByIDs(ids, func(chunk []string) ([]string, error) {
+				chunks = append(chunks, chunk)
+				return chunk, nil
+			}), nil)
+
+			Expect(chunks).To(HaveLen(2))
+			Expect(chunks[0]).To(HaveLen(artworkChunkSize))
+			Expect(chunks[1]).To(HaveLen(3))
+			Expect(got).To(Equal(ids))
+		})
+
+		It("yields the fetch error and stops", func() {
+			ids := make([]string, artworkChunkSize+1)
+			calls := 0
+			var errs []error
+			for _, err := range streamByIDs(ids, func(chunk []string) ([]string, error) {
+				calls++
+				return nil, errors.New("boom")
+			}) {
+				errs = append(errs, err)
+			}
+
+			Expect(calls).To(Equal(1))
+			Expect(errs).To(HaveLen(1))
+			Expect(errs[0]).To(MatchError("boom"))
+		})
+
+		It("stops fetching when the consumer breaks", func() {
+			ids := make([]string, artworkChunkSize+1)
+			calls := 0
+			for range streamByIDs(ids, func(chunk []string) ([]string, error) {
+				calls++
+				return chunk, nil
+			}) {
+				break
+			}
+
+			Expect(calls).To(Equal(1))
+		})
+	})
+
+	Describe("applyItemImage", func() {
+		It("copies hash, absence, blurhash and dimensions onto the item", func() {
+			infos := map[string]model.ItemArtworkInfo{
+				"al-1": {ItemID: "al-1", Hash: "0123456789abcdef", BlurHash: "LEHV6nWB2yk8", ThumbHash: "1QcSHQRn", Width: 1200, Height: 800},
+			}
+			var img model.ItemImage
+			applyItemImage(infos, "al-1", &img)
+			Expect(img.ImageHash).To(Equal("0123456789abcdef"))
+			Expect(img.ImageAbsent).To(BeFalse())
+			Expect(img.BlurHash).To(Equal("LEHV6nWB2yk8"))
+			Expect(img.ThumbHash).To(Equal("1QcSHQRn"))
+			Expect(img.ImageWidth).To(Equal(1200))
+			Expect(img.ImageHeight).To(Equal(800))
+		})
+
+		It("marks a hashless entry absent and carries no blurhash", func() {
+			infos := map[string]model.ItemArtworkInfo{"al-2": {ItemID: "al-2"}}
+			var img model.ItemImage
+			applyItemImage(infos, "al-2", &img)
+			Expect(img.ImageAbsent).To(BeTrue())
+			Expect(img.BlurHash).To(BeEmpty())
+			Expect(img.ThumbHash).To(BeEmpty())
+		})
+
+		It("leaves an unresolved item zero-valued", func() {
+			var img model.ItemImage
+			applyItemImage(map[string]model.ItemArtworkInfo{}, "al-3", &img)
+			Expect(img.ImageHash).To(BeEmpty())
+			Expect(img.ImageAbsent).To(BeFalse())
+			Expect(img.BlurHash).To(BeEmpty())
+		})
+	})
+})
diff --git a/persistence/artwork_queue_repository.go b/persistence/artwork_queue_repository.go
new file mode 100644
index 000000000..e5469fbea
--- /dev/null
+++ b/persistence/artwork_queue_repository.go
@@ -0,0 +1,149 @@
+package persistence
+
+import (
+	"cmp"
+	"context"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+
+	. "github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/model"
+	"github.com/pocketbase/dbx"
+)
+
+// Keeps each multi-row insert under SQLite's bind-variable limit (at most 7 vars per row).
+const enqueueChunkSize = 100
+
+// Every insert writes these, in this order; the INSERT..SELECT forms must project them to match.
+var enqueueColumns = []string{"item_kind", "item_id", "image_type", "priority", "attempts", "retry_at", "enqueued_at"}
+
+type artworkQueueRepository struct {
+	sqlRepository
+}
+
+func NewArtworkQueueRepository(ctx context.Context, db dbx.Builder) model.ArtworkQueueRepository {
+	r := &artworkQueueRepository{}
+	r.ctx = ctx
+	r.db = db
+	r.tableName = "artwork_queue"
+	return r
+}
+
+// Enqueue also resets enqueued_at, so a fresh request does not inherit an old row's spent retry budget.
+func (r *artworkQueueRepository) Enqueue(items ...model.ArtworkQueueItem) error {
+	return r.enqueue(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
+		priority = MAX(priority, excluded.priority), retry_at = excluded.retry_at,
+		attempts = 0, enqueued_at = excluded.enqueued_at`, items)
+}
+
+func (r *artworkQueueRepository) EnqueuePreservingBackoff(items ...model.ArtworkQueueItem) error {
+	return r.enqueue(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
+		priority = MAX(priority, excluded.priority)`, items)
+}
+
+func (r *artworkQueueRepository) EnqueueStaleAbsent(kind model.Kind, attemptedBefore time.Time) (int64, error) {
+	now := time.Now()
+	return r.insertIfNotQueued("", `SELECT item_kind, item_id, image_type, ?, 0, ?, ?
+		FROM `+itemArtworkTable+` WHERE item_kind = ? AND hash = '' AND attempted_at < ?`,
+		model.ArtworkPriorityRecheck, now, now, kind.Prefix(), attemptedBefore)
+}
+
+func (r *artworkQueueRepository) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {
+	entityTable, ok := artworkOwnerTables[kind]
+	if !ok {
+		return 0, fmt.Errorf("artwork queue: no entity table for kind %q", kind.Prefix())
+	}
+	now := time.Now()
+	return r.insertIfNotQueued("", `SELECT ?, id, ?, ?, 0, ?, ?
+		FROM `+entityTable+`
+		WHERE id NOT IN (SELECT item_id FROM `+itemArtworkTable+` WHERE item_kind = ?)`,
+		kind.Prefix(), model.ImageTypePrimary, priority, now, now, kind.Prefix())
+}
+
+func (r *artworkQueueRepository) EnqueueIfMissing(items ...model.ArtworkQueueItem) error {
+	now := time.Now()
+	for chunk := range slices.Chunk(items, enqueueChunkSize) {
+		rows := make([]string, 0, len(chunk))
+		args := make([]any, 0, len(chunk)*4+2)
+		for _, it := range chunk {
+			rows = append(rows, "(?,?,?,?)")
+			args = append(args, it.ItemKind, it.ItemID, cmp.Or(it.ImageType, model.ImageTypePrimary), it.Priority)
+		}
+		args = append(args, now, now)
+		_, err := r.insertIfNotQueued(
+			`WITH new_items(item_kind, item_id, image_type, priority) AS (VALUES `+strings.Join(rows, ",")+`) `,
+			`SELECT n.item_kind, n.item_id, n.image_type, n.priority, 0, ?, ?
+			FROM new_items n
+			WHERE NOT EXISTS (
+				SELECT 1 FROM `+itemArtworkTable+` ia
+				WHERE ia.item_kind = n.item_kind AND ia.item_id = n.item_id AND ia.image_type = n.image_type)`,
+			args...)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// insertIfNotQueued inserts the rows selected by the given SQL, optionally prefixed by a CTE. DO NOTHING is
+// deliberate: a recheck must not bump the priority or retry_at of an already-queued item.
+func (r *artworkQueueRepository) insertIfNotQueued(with, sql string, args ...any) (int64, error) {
+	return r.executeSQL(Expr(with+`INSERT INTO `+r.tableName+
+		` (`+strings.Join(enqueueColumns, ", ")+`) `+sql+
+		` ON CONFLICT (item_kind, item_id, image_type) DO NOTHING`, args...))
+}
+
+func (r *artworkQueueRepository) enqueue(conflict string, items []model.ArtworkQueueItem) error {
+	now := time.Now()
+	for chunk := range slices.Chunk(items, enqueueChunkSize) {
+		ins := Insert(r.tableName).Columns(enqueueColumns...)
+		for _, it := range chunk {
+			ins = ins.Values(it.ItemKind, it.ItemID, cmp.Or(it.ImageType, model.ImageTypePrimary), it.Priority, 0, now, now)
+		}
+		ins = ins.Suffix(conflict)
+		if _, err := r.executeSQL(ins); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (r *artworkQueueRepository) DequeueBatch(n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
+	sel := Select("*").From(r.tableName).
+		Where(LtOrEq{"retry_at": time.Now()}).
+		OrderBy("priority DESC", "enqueued_at ASC").
+		Limit(uint64(n))
+	if len(kinds) > 0 {
+		sel = sel.Where(Eq{"item_kind": kinds})
+	}
+	var res []model.ArtworkQueueItem
+	err := r.queryAll(sel, &res)
+	return res, err
+}
+
+func (r *artworkQueueRepository) MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time) error {
+	upd := Update(r.tableName).
+		Set("attempts", Expr("attempts + 1")).
+		Set("retry_at", retryAt).
+		Where(Eq{"item_kind": kind, "item_id": id, "image_type": imageType, "retry_at": seenRetryAt})
+	_, err := r.executeSQL(upd)
+	return err
+}
+
+func (r *artworkQueueRepository) DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error {
+	return r.delete(Eq{"item_kind": kind, "item_id": id, "image_type": imageType, "retry_at": retryAt})
+}
+
+func (r *artworkQueueRepository) PurgeDangling() (int64, error) {
+	return purgeDangling(r.sqlRepository)
+}
+
+func (r *artworkQueueRepository) Count() (int64, error) {
+	var res struct{ Count int64 }
+	err := r.queryOne(Select("count(*) as count").From(r.tableName), &res)
+	return res.Count, err
+}
+
+var _ model.ArtworkQueueRepository = (*artworkQueueRepository)(nil)
diff --git a/persistence/artwork_queue_repository_test.go b/persistence/artwork_queue_repository_test.go
new file mode 100644
index 000000000..6638a204e
--- /dev/null
+++ b/persistence/artwork_queue_repository_test.go
@@ -0,0 +1,284 @@
+package persistence
+
+import (
+	"context"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/pocketbase/dbx"
+)
+
+var _ = Describe("ArtworkQueueRepository", func() {
+	var repo model.ArtworkQueueRepository
+
+	item := func(kind, id string, prio int) model.ArtworkQueueItem {
+		return model.ArtworkQueueItem{ItemKind: kind, ItemID: id,
+			ImageType: model.ImageTypePrimary, Priority: prio}
+	}
+
+	// Writes the post-failure state directly: the production path, MarkFailedIfUnchanged, needs
+	// a retry_at only a dequeue can hand it.
+	backOff := func(kind, id string, retryAt time.Time) {
+		GinkgoHelper()
+		r := repo.(*artworkQueueRepository)
+		_, err := r.executeSQL(squirrel.Update(r.tableName).
+			Set("attempts", squirrel.Expr("attempts + 1")).
+			Set("retry_at", retryAt).
+			Where(squirrel.Eq{"item_kind": kind, "item_id": id, "image_type": model.ImageTypePrimary}))
+		Expect(err).ToNot(HaveOccurred())
+	}
+
+	remove := func(kind, id string) {
+		GinkgoHelper()
+		r := repo.(*artworkQueueRepository)
+		Expect(r.delete(squirrel.Eq{"item_kind": kind, "item_id": id, "image_type": model.ImageTypePrimary})).To(Succeed())
+	}
+
+	BeforeEach(func() {
+		clearArtworkTables()
+		DeferCleanup(clearArtworkTables)
+		repo = NewArtworkQueueRepository(context.Background(), GetDBXBuilder())
+	})
+
+	It("enqueues and dequeues by priority then FIFO", func() {
+		Expect(repo.Enqueue(item("al", "low", model.ArtworkPriorityBackfill))).To(Succeed())
+		Expect(repo.Enqueue(item("ar", "high", model.ArtworkPriorityBump))).To(Succeed())
+
+		got, err := repo.DequeueBatch(10)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(HaveLen(2))
+		Expect(got[0].ItemID).To(Equal("high"))
+	})
+
+	It("keeps the higher priority on duplicate enqueue", func() {
+		Expect(repo.Enqueue(item("al", "a1", model.ArtworkPriorityBump))).To(Succeed())
+		Expect(repo.Enqueue(item("al", "a1", model.ArtworkPriorityBackfill))).To(Succeed())
+		got, _ := repo.DequeueBatch(10)
+		Expect(got).To(HaveLen(1))
+		Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump))
+	})
+
+	It("EnqueuePreservingBackoff raises priority without resetting a backing-off row's retry_at", func() {
+		Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
+		backOff("al", "b1", time.Now().Add(time.Hour))
+		Expect(repo.DequeueBatch(10)).To(BeEmpty())
+
+		Expect(repo.EnqueuePreservingBackoff(item("al", "b1", model.ArtworkPriorityBump))).To(Succeed())
+		Expect(repo.DequeueBatch(10)).To(BeEmpty(), "bump must not reset retry_at")
+
+		// Enqueue (scan/manual), by contrast, resets retry_at and makes it eligible now.
+		Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
+		got, _ := repo.DequeueBatch(10)
+		Expect(got).To(HaveLen(1))
+		Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump), "bump's higher priority is preserved")
+	})
+
+	It("EnqueuePreservingBackoff inserts a brand-new row eligible immediately", func() {
+		Expect(repo.EnqueuePreservingBackoff(item("ar", "n1", model.ArtworkPriorityBump))).To(Succeed())
+		got, _ := repo.DequeueBatch(10)
+		Expect(got).To(HaveLen(1))
+		Expect(got[0].ItemID).To(Equal("n1"))
+	})
+
+	It("hides failed items until retry_at", func() {
+		Expect(repo.Enqueue(item("al", "f1", model.ArtworkPriorityScan))).To(Succeed())
+		backOff("al", "f1", time.Now().Add(time.Hour))
+
+		got, err := repo.DequeueBatch(10)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(BeEmpty())
+
+		backOff("al", "f1", time.Now().Add(-time.Minute))
+		got, _ = repo.DequeueBatch(10)
+		Expect(got).To(HaveLen(1))
+		Expect(got[0].Attempts).To(Equal(2))
+	})
+
+	It("MarkFailedIfUnchanged applies backoff only while retry_at is unchanged", func() {
+		Expect(repo.Enqueue(item("al", "m1", model.ArtworkPriorityScan))).To(Succeed())
+		// Anchor retry_at in the past so it can never collide with the re-enqueue's now.
+		backOff("al", "m1", time.Now().Add(-time.Hour))
+		got, err := repo.DequeueBatch(10)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(HaveLen(1))
+		original := got[0].RetryAt
+
+		// A concurrent scan re-enqueues, resetting retry_at to now.
+		Expect(repo.Enqueue(item("al", "m1", model.ArtworkPriorityScan))).To(Succeed())
+
+		future := time.Now().Add(48 * time.Hour)
+		Expect(repo.MarkFailedIfUnchanged("al", "m1", model.ImageTypePrimary, original, future)).To(Succeed())
+		got, _ = repo.DequeueBatch(10)
+		Expect(got).To(HaveLen(1), "the fresh re-enqueue stays immediately eligible")
+		Expect(got[0].Attempts).To(BeZero(), "re-enqueue clears attempts, and the stale failure must not bump them")
+		current := got[0].RetryAt
+
+		Expect(repo.MarkFailedIfUnchanged("al", "m1", model.ImageTypePrimary, current, future)).To(Succeed())
+		got, _ = repo.DequeueBatch(10)
+		Expect(got).To(BeEmpty(), "backed-off row is hidden until the future retry_at")
+		all, _ := repo.Count()
+		Expect(all).To(Equal(int64(1)))
+	})
+
+	It("Enqueue restarts the retry budget an existing row had spent", func() {
+		Expect(repo.Enqueue(item("al", "e1", model.ArtworkPriorityScan))).To(Succeed())
+		backOff("al", "e1", time.Now().Add(-time.Hour))
+		stale := time.Now().Add(-48 * time.Hour)
+		_, err := GetDBXBuilder().NewQuery("UPDATE artwork_queue SET enqueued_at = {:t} WHERE item_id = 'e1'").
+			Bind(dbx.Params{"t": stale}).Execute()
+		Expect(err).ToNot(HaveOccurred())
+
+		Expect(repo.Enqueue(item("al", "e1", model.ArtworkPriorityScan))).To(Succeed())
+
+		got, err := repo.DequeueBatch(10)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(HaveLen(1))
+		Expect(got[0].EnqueuedAt).To(BeTemporally("~", time.Now(), time.Minute),
+			"a re-request must not inherit a spent 12h window and give up on its first attempt")
+		Expect(got[0].Attempts).To(BeZero())
+	})
+
+	It("deletes on completion and counts", func() {
+		Expect(repo.Enqueue(item("al", "c1", 0))).To(Succeed())
+		n, _ := repo.Count()
+		Expect(n).To(Equal(int64(1)))
+		remove("al", "c1")
+		n, _ = repo.Count()
+		Expect(n).To(BeZero())
+	})
+
+	It("DeleteIfUnchanged deletes only while retry_at is unchanged", func() {
+		Expect(repo.Enqueue(item("al", "d1", model.ArtworkPriorityScan))).To(Succeed())
+		// Anchor retry_at in the past so it can never collide with the re-enqueue's now.
+		backOff("al", "d1", time.Now().Add(-time.Hour))
+		got, err := repo.DequeueBatch(10)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got).To(HaveLen(1))
+		original := got[0].RetryAt
+
+		// A concurrent scan re-enqueues, resetting retry_at to now.
+		Expect(repo.Enqueue(item("al", "d1", model.ArtworkPriorityScan))).To(Succeed())
+
+		// Deleting with the stale retry_at is a no-op: the re-enqueued row survives.
+		Expect(repo.DeleteIfUnchanged("al", "d1", model.ImageTypePrimary, original)).To(Succeed())
+		n, _ := repo.Count()
+		Expect(n).To(Equal(int64(1)))
+
+		got, _ = repo.DequeueBatch(10)
+		Expect(got).To(HaveLen(1))
+		Expect(repo.DeleteIfUnchanged("al", "d1", model.ImageTypePrimary, got[0].RetryAt)).To(Succeed())
+		n, _ = repo.Count()
+		Expect(n).To(BeZero())
+	})
+
+	It("purges queue rows whose entity no longer exists, per kind", func() {
+		Expect(repo.Enqueue(
+			item("al", albumSgtPeppers.ID, model.ArtworkPriorityScan),
+			item("al", "no-such-album", model.ArtworkPriorityScan),
+			item("ar", artistKraftwerk.ID, model.ArtworkPriorityScan),
+			item("ar", "no-such-artist", model.ArtworkPriorityScan),
+			item("pl", plsBest.ID, model.ArtworkPriorityScan),
+			item("pl", "no-such-playlist", model.ArtworkPriorityScan),
+			item("ra", radioWithHomePage.ID, model.ArtworkPriorityScan),
+			item("ra", "no-such-radio", model.ArtworkPriorityScan),
+			item("mf", songDayInALife.ID, model.ArtworkPriorityScan),
+			item("mf", "no-such-mediafile", model.ArtworkPriorityScan),
+		)).To(Succeed())
+
+		purged, err := repo.PurgeDangling()
+		Expect(err).ToNot(HaveOccurred())
+		Expect(purged).To(Equal(int64(5)))
+
+		got, _ := repo.DequeueBatch(100)
+		ids := slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })
+		Expect(ids).To(ConsistOf(albumSgtPeppers.ID, artistKraftwerk.ID, plsBest.ID, radioWithHomePage.ID, songDayInALife.ID))
+	})
+
+	It("enqueues stale absent states for recheck", func() {
+		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+		old := time.Now().Add(-48 * time.Hour)
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "stale1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "fresh1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "found1", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: old})).To(Succeed())
+
+		n, err := repo.EnqueueStaleAbsent(model.KindArtistArtwork, time.Now().Add(-24*time.Hour))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(n).To(Equal(int64(1)))
+
+		items, err := repo.DequeueBatch(10)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(items).To(HaveLen(1))
+		Expect(items[0].ItemID).To(Equal("stale1"))
+		Expect(items[0].Priority).To(Equal(model.ArtworkPriorityRecheck))
+	})
+
+	It("enqueues entities that have no item_artwork row at all", func() {
+		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: albumSgtPeppers.ID, ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: time.Now()})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: albumAbbeyRoad.ID, ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
+
+		n, err := repo.EnqueueAllMissing(model.KindAlbumArtwork, model.ArtworkPriorityRecheck)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(n).To(BeNumerically(">=", 1))
+
+		got, err := repo.DequeueBatch(1000)
+		Expect(err).ToNot(HaveOccurred())
+		ids := make([]string, 0, len(got))
+		for _, it := range got {
+			Expect(it.ItemKind).To(Equal("al"))
+			Expect(it.Priority).To(Equal(model.ArtworkPriorityRecheck))
+			ids = append(ids, it.ItemID)
+		}
+		Expect(ids).To(ContainElement(albumRadioactivity.ID), "an album with no row must be enqueued")
+		Expect(ids).ToNot(ContainElement(albumSgtPeppers.ID), "a resolved album must not be re-enqueued")
+		Expect(ids).ToNot(ContainElement(albumAbbeyRoad.ID), "an absent-state album must not be enqueued as missing")
+	})
+
+	It("EnqueueIfMissing skips items that already have an item_artwork row", func() {
+		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "resolved", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: time.Now()})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "absent", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
+
+		Expect(repo.EnqueueIfMissing(
+			item("al", "resolved", model.ArtworkPriorityScan),
+			item("al", "absent", model.ArtworkPriorityScan),
+			item("al", "brandnew", model.ArtworkPriorityScan),
+		)).To(Succeed())
+
+		got, err := repo.DequeueBatch(100)
+		Expect(err).ToNot(HaveOccurred())
+		ids := slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })
+		Expect(ids).To(ConsistOf("brandnew"), "only an item with no state row may be enqueued")
+	})
+
+	It("EnqueueIfMissing leaves an already-queued row untouched", func() {
+		Expect(repo.Enqueue(item("al", "queued", model.ArtworkPriorityBump))).To(Succeed())
+
+		Expect(repo.EnqueueIfMissing(item("al", "queued", model.ArtworkPriorityScan))).To(Succeed())
+
+		got, _ := repo.DequeueBatch(100)
+		Expect(got).To(HaveLen(1))
+		Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump), "the existing priority must survive")
+	})
+
+	It("does not disturb an already-queued entity when enqueueing missing rows", func() {
+		Expect(repo.Enqueue(item("al", albumRadioactivity.ID, model.ArtworkPriorityBump))).To(Succeed())
+
+		_, err := repo.EnqueueAllMissing(model.KindAlbumArtwork, model.ArtworkPriorityRecheck)
+		Expect(err).ToNot(HaveOccurred())
+
+		got, _ := repo.DequeueBatch(1000)
+		var count int
+		for _, it := range got {
+			if it.ItemID == albumRadioactivity.ID {
+				count++
+				Expect(it.Priority).To(Equal(model.ArtworkPriorityBump), "existing bump priority must survive")
+			}
+		}
+		Expect(count).To(Equal(1), "the already-queued row must not be duplicated")
+	})
+})
diff --git a/persistence/artwork_repository.go b/persistence/artwork_repository.go
new file mode 100644
index 000000000..22662b575
--- /dev/null
+++ b/persistence/artwork_repository.go
@@ -0,0 +1,176 @@
+package persistence
+
+import (
+	"cmp"
+	"context"
+	"slices"
+	"time"
+
+	. "github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/model"
+	"github.com/pocketbase/dbx"
+)
+
+const (
+	itemArtworkTable = "item_artwork"
+	artworkBatchSize = 200
+)
+
+type artworkRepository struct {
+	sqlRepository
+	items sqlRepository
+}
+
+func NewArtworkRepository(ctx context.Context, db dbx.Builder) model.ArtworkRepository {
+	r := &artworkRepository{}
+	r.ctx = ctx
+	r.db = db
+	r.tableName = "artwork"
+	r.items.ctx = ctx
+	r.items.db = db
+	r.items.tableName = itemArtworkTable
+	return r
+}
+
+func (r *artworkRepository) GetImage(hash string) (*model.Artwork, error) {
+	sel := Select("*").From(r.tableName).Where(Eq{"hash": hash})
+	var res model.Artwork
+	if err := r.queryOne(sel, &res); err != nil {
+		return nil, err
+	}
+	return &res, nil
+}
+
+func (r *artworkRepository) PutImage(a *model.Artwork) error {
+	// created_at is the last-acquisition-write time the prune grace window keys on.
+	a.CreatedAt = time.Now()
+	values, err := toSQLArgs(*a)
+	if err != nil {
+		return err
+	}
+	// created_at=excluded.created_at: reacquiring an orphan must reset the prune grace window.
+	ins := Insert(r.tableName).SetMap(values).Suffix(`ON CONFLICT (hash) DO UPDATE SET mime=excluded.mime, width=excluded.width,
+		height=excluded.height, size_bytes=excluded.size_bytes, blur_hash=excluded.blur_hash,
+		thumb_hash=excluded.thumb_hash, dominant_color=excluded.dominant_color,
+		created_at=excluded.created_at`)
+	_, err = r.executeSQL(ins)
+	return err
+}
+
+func (r *artworkRepository) GetMimeByHash() (map[string]string, error) {
+	sel := Select("hash", "mime").From(r.tableName)
+	var rows []struct {
+		Hash string
+		Mime string
+	}
+	if err := r.queryAll(sel, &rows); err != nil {
+		return nil, err
+	}
+	res := make(map[string]string, len(rows))
+	for _, row := range rows {
+		res[row.Hash] = row.Mime
+	}
+	return res, nil
+}
+
+func (r *artworkRepository) PurgeOrphans(createdBefore time.Time) (int64, error) {
+	del := Delete(r.tableName).Where(And{
+		Lt{"created_at": createdBefore},
+		Expr("hash NOT IN (SELECT hash FROM " + itemArtworkTable + " WHERE hash <> '')"),
+	})
+	return r.executeSQL(del)
+}
+
+// artworkOwnerTables maps an artwork kind to the table that owns the entity.
+var artworkOwnerTables = map[model.Kind]string{
+	model.KindAlbumArtwork:     "album",
+	model.KindArtistArtwork:    "artist",
+	model.KindPlaylistArtwork:  "playlist",
+	model.KindRadioArtwork:     "radio",
+	model.KindMediaFileArtwork: "media_file",
+}
+
+// purgeDangling deletes rows in r's table whose owning entity is gone, one statement per kind.
+func purgeDangling(r sqlRepository) (int64, error) {
+	var total int64
+	for kind, entityTable := range artworkOwnerTables {
+		del := Delete(r.tableName).Where(And{
+			Eq{"item_kind": kind.Prefix()},
+			Expr("item_id NOT IN (SELECT id FROM " + entityTable + ")"),
+		})
+		c, err := r.executeSQL(del)
+		if err != nil {
+			return total, err
+		}
+		total += c
+	}
+	return total, nil
+}
+
+func (r *artworkRepository) PurgeDanglingItems() (int64, error) {
+	return purgeDangling(r.items)
+}
+
+func (r *artworkRepository) GetItemArtwork(kind model.Kind, id, imageType string) (*model.ItemArtwork, error) {
+	sel := Select("*").From(itemArtworkTable).
+		Where(Eq{"item_kind": kind.Prefix(), "item_id": id, "image_type": imageType})
+	var res model.ItemArtwork
+	if err := r.items.queryOne(sel, &res); err != nil {
+		return nil, err
+	}
+	return &res, nil
+}
+
+func (r *artworkRepository) PutItemArtwork(ia *model.ItemArtwork) error {
+	ia.ImageType = cmp.Or(ia.ImageType, model.ImageTypePrimary)
+	ia.UpdatedAt = time.Now()
+	// PutItemArtwork records the outcome of an attempt, so an unset attempted_at is now.
+	if ia.AttemptedAt.IsZero() {
+		ia.AttemptedAt = ia.UpdatedAt
+	}
+	values, err := toSQLArgs(*ia)
+	if err != nil {
+		return err
+	}
+	ins := Insert(itemArtworkTable).SetMap(values).Suffix(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
+		hash=excluded.hash, source=excluded.source, source_path=excluded.source_path, ref_mtime=excluded.ref_mtime,
+		attempted_at=excluded.attempted_at, updated_at=excluded.updated_at`)
+	_, err = r.items.executeSQL(ins)
+	return err
+}
+
+func (r *artworkRepository) DeleteForItems(kind model.Kind, ids []string) error {
+	for chunk := range slices.Chunk(ids, artworkBatchSize) {
+		if err := r.items.delete(Eq{"item_kind": kind.Prefix(), "item_id": chunk}); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (r *artworkRepository) GetInfoForItems(kind model.Kind, ids []string) (map[string]model.ItemArtworkInfo, error) {
+	res := map[string]model.ItemArtworkInfo{}
+	for chunk := range slices.Chunk(ids, artworkBatchSize) {
+		sel := Select("ia.item_id", "ia.hash", "COALESCE(a.blur_hash, '') as blur_hash",
+			"COALESCE(a.thumb_hash, '') as thumb_hash",
+			"COALESCE(a.dominant_color, '') as dominant_color",
+			"COALESCE(a.width, 0) as width", "COALESCE(a.height, 0) as height").
+			From(itemArtworkTable + " ia").
+			LeftJoin("artwork a ON a.hash = ia.hash").
+			Where(And{
+				Eq{"ia.item_kind": kind.Prefix()},
+				Eq{"ia.image_type": model.ImageTypePrimary},
+				Eq{"ia.item_id": chunk},
+			})
+		var rows []model.ItemArtworkInfo
+		if err := r.items.queryAll(sel, &rows); err != nil {
+			return nil, err
+		}
+		for _, row := range rows {
+			res[row.ItemID] = row
+		}
+	}
+	return res, nil
+}
+
+var _ model.ArtworkRepository = (*artworkRepository)(nil)
diff --git a/persistence/artwork_repository_test.go b/persistence/artwork_repository_test.go
new file mode 100644
index 000000000..683dc2d0f
--- /dev/null
+++ b/persistence/artwork_repository_test.go
@@ -0,0 +1,248 @@
+package persistence
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/pocketbase/dbx"
+)
+
+func clearArtworkTables() {
+	db := GetDBXBuilder()
+	for _, t := range []string{"artwork_queue", "item_artwork", "artwork"} {
+		_, err := db.NewQuery("DELETE FROM " + t).Execute()
+		Expect(err).ToNot(HaveOccurred())
+	}
+}
+
+var _ = Describe("ArtworkRepository", func() {
+	var repo model.ArtworkRepository
+
+	BeforeEach(func() {
+		clearArtworkTables()
+		DeferCleanup(clearArtworkTables)
+		repo = NewArtworkRepository(context.Background(), GetDBXBuilder())
+	})
+
+	Context("image identity", func() {
+		It("stores and retrieves an artwork by hash", func() {
+			a := &model.Artwork{Hash: "abc123", Mime: "image/jpeg", Width: 500, Height: 500, SizeBytes: 1234, BlurHash: "LKO2?U%2Tw=w"}
+			Expect(repo.PutImage(a)).To(Succeed())
+
+			got, err := repo.GetImage("abc123")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Mime).To(Equal("image/jpeg"))
+			Expect(got.BlurHash).To(Equal("LKO2?U%2Tw=w"))
+			Expect(got.CreatedAt).ToNot(BeZero())
+		})
+
+		It("round-trips the thumbhash alongside the blurhash", func() {
+			a := &model.Artwork{Hash: "both1", Mime: "image/jpeg", BlurHash: "LKO2?U%2Tw=w",
+				ThumbHash: "1QcSHQRnh493V4dIh4eXh1h4kJUI", DominantColor: "#336699"}
+			Expect(repo.PutImage(a)).To(Succeed())
+
+			got, err := repo.GetImage("both1")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.BlurHash).To(Equal("LKO2?U%2Tw=w"))
+			Expect(got.ThumbHash).To(Equal("1QcSHQRnh493V4dIh4eXh1h4kJUI"))
+			Expect(got.DominantColor).To(Equal("#336699"))
+		})
+
+		It("overwrites the thumbhash on re-acquisition", func() {
+			Expect(repo.PutImage(&model.Artwork{Hash: "th2", Mime: "image/png", ThumbHash: "first", DominantColor: "#111111"})).To(Succeed())
+			Expect(repo.PutImage(&model.Artwork{Hash: "th2", Mime: "image/png", ThumbHash: "second", DominantColor: "#222222"})).To(Succeed())
+
+			got, err := repo.GetImage("th2")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.ThumbHash).To(Equal("second"))
+			Expect(got.DominantColor).To(Equal("#222222"))
+		})
+
+		It("is idempotent on Put (upsert by hash)", func() {
+			a := &model.Artwork{Hash: "dup1", Mime: "image/png"}
+			Expect(repo.PutImage(a)).To(Succeed())
+			a.BlurHash = "XYZ"
+			Expect(repo.PutImage(a)).To(Succeed())
+			got, _ := repo.GetImage("dup1")
+			Expect(got.BlurHash).To(Equal("XYZ"))
+		})
+
+		It("refreshes created_at when reacquiring an existing hash", func() {
+			Expect(repo.PutImage(&model.Artwork{Hash: "reacq", Mime: "image/jpeg"})).To(Succeed())
+			_, err := GetDBXBuilder().NewQuery("UPDATE artwork SET created_at={:t} WHERE hash='reacq'").
+				Bind(dbx.Params{"t": "2000-01-01 00:00:00"}).Execute()
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(repo.PutImage(&model.Artwork{Hash: "reacq", Mime: "image/png"})).To(Succeed())
+
+			got, err := repo.GetImage("reacq")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.CreatedAt).To(BeTemporally(">", time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)))
+		})
+
+		It("returns ErrNotFound for a missing hash", func() {
+			_, err := repo.GetImage("nope")
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
+		It("returns every stored hash with its current mime", func() {
+			Expect(repo.PutImage(&model.Artwork{Hash: "all1", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PutImage(&model.Artwork{Hash: "all2", Mime: "image/png"})).To(Succeed())
+			mimes, err := repo.GetMimeByHash()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(mimes).To(HaveKeyWithValue("all1", "image/jpeg"))
+			Expect(mimes).To(HaveKeyWithValue("all2", "image/png"))
+		})
+
+		It("deletes only unreferenced rows older than the cutoff, reporting the count", func() {
+			Expect(repo.PutImage(&model.Artwork{Hash: "d1", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PutImage(&model.Artwork{Hash: "dref", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "a1",
+				ImageType: model.ImageTypePrimary, Hash: "dref", Source: "folder"})).To(Succeed())
+
+			Expect(repo.PurgeOrphans(time.Now().Add(time.Minute))).To(BeNumerically("==", 1))
+
+			_, err := repo.GetImage("d1")
+			Expect(err).To(MatchError(model.ErrNotFound))
+			_, err = repo.GetImage("dref")
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("spares an unreferenced row younger than the cutoff", func() {
+			Expect(repo.PutImage(&model.Artwork{Hash: "young", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PurgeOrphans(time.Now().Add(-time.Hour))).To(BeNumerically("==", 0))
+			_, err := repo.GetImage("young")
+			Expect(err).ToNot(HaveOccurred())
+		})
+	})
+
+	Context("dangling state cleanup", func() {
+		It("purges item_artwork rows per kind whose entity no longer exists, summing counts", func() {
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: albumSgtPeppers.ID, ImageType: model.ImageTypePrimary, Hash: "keepAl"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "no-such-album", ImageType: model.ImageTypePrimary, Hash: "danglingAl"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: artistKraftwerk.ID, ImageType: model.ImageTypePrimary, Hash: "keepAr"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "no-such-artist", ImageType: model.ImageTypePrimary, Hash: "danglingAr"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "pl", ItemID: plsBest.ID, ImageType: model.ImageTypePrimary, Hash: "keepPl"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "pl", ItemID: "no-such-playlist", ImageType: model.ImageTypePrimary, Hash: "danglingPl"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ra", ItemID: radioWithHomePage.ID, ImageType: model.ImageTypePrimary, Hash: "keepRa"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ra", ItemID: "no-such-radio", ImageType: model.ImageTypePrimary, Hash: "danglingRa"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: songDayInALife.ID, ImageType: model.ImageTypePrimary, Hash: "keepMf"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: "no-such-mediafile", ImageType: model.ImageTypePrimary, Hash: "danglingMf"})).To(Succeed())
+
+			purged, err := repo.PurgeDanglingItems()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(purged).To(Equal(int64(5)))
+
+			for _, kept := range []model.ItemArtwork{
+				{ItemKind: "al", ItemID: albumSgtPeppers.ID},
+				{ItemKind: "ar", ItemID: artistKraftwerk.ID},
+				{ItemKind: "pl", ItemID: plsBest.ID},
+				{ItemKind: "ra", ItemID: radioWithHomePage.ID},
+				{ItemKind: "mf", ItemID: songDayInALife.ID},
+			} {
+				k, _ := model.ParseKind(kept.ItemKind)
+				_, err := repo.GetItemArtwork(k, kept.ItemID, model.ImageTypePrimary)
+				Expect(err).ToNot(HaveOccurred())
+			}
+			for _, gone := range []model.ItemArtwork{
+				{ItemKind: "al", ItemID: "no-such-album"},
+				{ItemKind: "ar", ItemID: "no-such-artist"},
+				{ItemKind: "pl", ItemID: "no-such-playlist"},
+				{ItemKind: "ra", ItemID: "no-such-radio"},
+				{ItemKind: "mf", ItemID: "no-such-mediafile"},
+			} {
+				k, _ := model.ParseKind(gone.ItemKind)
+				_, err := repo.GetItemArtwork(k, gone.ItemID, model.ImageTypePrimary)
+				Expect(err).To(MatchError(model.ErrNotFound))
+			}
+		})
+	})
+
+	Context("item state", func() {
+		It("upserts and reads state, including per-item provenance", func() {
+			ia := &model.ItemArtwork{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary,
+				Hash: "h1", Source: "folder", SourcePath: "/music/a/cover.jpg", RefMtime: 111, AttemptedAt: time.Now()}
+			Expect(repo.PutItemArtwork(ia)).To(Succeed())
+			ia.Source = "embedded"
+			ia.SourcePath = "/music/a/track.mp3"
+			ia.RefMtime = 222
+			Expect(repo.PutItemArtwork(ia)).To(Succeed())
+
+			got, err := repo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Source).To(Equal("embedded"))
+			Expect(got.SourcePath).To(Equal("/music/a/track.mp3"))
+			Expect(got.RefMtime).To(Equal(int64(222)))
+			Expect(got.UpdatedAt).ToNot(BeZero())
+		})
+
+		It("defaults attempted_at to now when unset", func() {
+			before := time.Now().Add(-time.Second)
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "noattempt",
+				ImageType: model.ImageTypePrimary, Hash: ""})).To(Succeed())
+			got, err := repo.GetItemArtwork(model.KindArtistArtwork, "noattempt", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.AttemptedAt).To(BeTemporally(">", before))
+		})
+
+		It("represents known-absent as empty hash", func() {
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "ar1",
+				ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
+			got, err := repo.GetItemArtwork(model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Hash).To(BeEmpty())
+		})
+
+		It("hydrates a page in one batch, including blurhash, dimensions and absence", func() {
+			Expect(repo.PutImage(&model.Artwork{Hash: "h9", Mime: "image/jpeg", BlurHash: "BH9",
+				DominantColor: "#abcdef", Width: 1200, Height: 800})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "x1", ImageType: model.ImageTypePrimary, Hash: "h9", Source: "folder"})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "x2", ImageType: model.ImageTypePrimary, Hash: "", Source: ""})).To(Succeed())
+
+			info, err := repo.GetInfoForItems(model.KindAlbumArtwork, []string{"x1", "x2", "x3"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(info).To(HaveLen(2))
+			Expect(info["x1"].Hash).To(Equal("h9"))
+			Expect(info["x1"].BlurHash).To(Equal("BH9"))
+			Expect(info["x1"].DominantColor).To(Equal("#abcdef"))
+			Expect(info["x1"].Width).To(Equal(1200))
+			Expect(info["x1"].Height).To(Equal(800))
+			Expect(info["x1"].Absent()).To(BeFalse())
+			Expect(info["x2"].Absent()).To(BeTrue())
+			_, unresolved := info["x3"]
+			Expect(unresolved).To(BeFalse())
+		})
+
+		It("deletes all rows for a single item", func() {
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "pl", ItemID: "p1", ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
+			Expect(repo.DeleteForItems(model.KindPlaylistArtwork, []string{"p1"})).To(Succeed())
+			_, err := repo.GetItemArtwork(model.KindPlaylistArtwork, "p1", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
+		It("deletes rows for many items in chunks, leaving others untouched", func() {
+			const n = artworkBatchSize + 5
+			ids := make([]string, n)
+			for i := range n {
+				id := fmt.Sprintf("mf-%d", i)
+				ids[i] = id
+				Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: id, ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
+			}
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: "keep", ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
+
+			Expect(repo.DeleteForItems(model.KindMediaFileArtwork, ids)).To(Succeed())
+
+			for _, id := range ids {
+				_, err := repo.GetItemArtwork(model.KindMediaFileArtwork, id, model.ImageTypePrimary)
+				Expect(err).To(MatchError(model.ErrNotFound))
+			}
+			kept, err := repo.GetItemArtwork(model.KindMediaFileArtwork, "keep", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(kept.ItemID).To(Equal("keep"))
+		})
+	})
+})
diff --git a/persistence/e2e/e2e_suite_test.go b/persistence/e2e/e2e_suite_test.go
index 1ff2139e6..2b617f5b0 100644
--- a/persistence/e2e/e2e_suite_test.go
+++ b/persistence/e2e/e2e_suite_test.go
@@ -13,7 +13,6 @@ import (
 	"github.com/Masterminds/squirrel"
 	"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"
@@ -275,8 +274,8 @@ var _ = BeforeSuite(func() {
 	ctx = request.WithUser(GinkgoT().Context(), adminUser)
 
 	buildTestFS()
-	s := scanner.New(ctx, initDS, artwork.NoopCacheWarmer(), events.NoopBroker(),
-		playlists.NewPlaylists(initDS, core.NewImageUploadService()), metrics.NewNoopInstance())
+	s := scanner.New(ctx, initDS, events.NoopBroker(),
+		playlists.NewPlaylists(initDS, artwork.NewUploader(initDS)), metrics.NewNoopInstance())
 	_, err = s.ScanAll(ctx, true)
 	Expect(err).ToNot(HaveOccurred())
 
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index ace61610c..df1472c2a 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -163,7 +163,9 @@ func (r *mediaFileRepository) CountBySuffix(options ...model.QueryOptions) (map[
 }
 
 func (r *mediaFileRepository) Exists(id string) (bool, error) {
-	return r.exists(Eq{"media_file.id": id})
+	// The exists() helper applies no library filter, so it would report rows the caller cannot see.
+	c, err := r.count(r.applyLibraryFilter(r.newSelect().Where(Eq{"media_file.id": id})))
+	return c > 0, err
 }
 
 func (r *mediaFileRepository) Put(m *model.MediaFile) error {
@@ -218,7 +220,13 @@ func (r *mediaFileRepository) GetAll(options ...model.QueryOptions) (model.Media
 	if err != nil {
 		return nil, err
 	}
-	return res.toModels(), nil
+	mfs := res.toModels()
+	r.hydrateArtwork(mfs)
+	return mfs, nil
+}
+
+func (r *mediaFileRepository) hydrateArtwork(mfs model.MediaFiles) {
+	hydrateMediaFileArtwork(r.ctx, r.db, mfs)
 }
 
 // GetRandom uses two passes so the random sort runs over a narrow rowid index instead of the
@@ -252,7 +260,9 @@ func (r *mediaFileRepository) GetRandom(options ...model.QueryOptions) (model.Me
 	if err := r.queryAll(sq, &res); err != nil {
 		return nil, err
 	}
-	return res.toModels(), nil
+	mfs := res.toModels()
+	r.hydrateArtwork(mfs)
+	return mfs, nil
 }
 
 func (r *mediaFileRepository) GetAllByTags(tag model.TagName, values []string, options ...model.QueryOptions) (model.MediaFiles, error) {
@@ -289,6 +299,29 @@ func (r *mediaFileRepository) GetCursor(options ...model.QueryOptions) (model.Me
 	return wrapMediaFileCursor(cursor), nil
 }
 
+// GetAllIDs returns the IDs of GetAll's row set, skipping its wide column projection.
+func (r *mediaFileRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+	sq := r.applyLibraryFilter(r.newSelect(options...).Columns("media_file.id"))
+	if filtersNeedAnnotation(sq) {
+		sq = r.withAnnotation(sq, "media_file.id")
+	}
+	ids := []string{}
+	err := r.queryAllSlice(sq, &ids)
+	return ids, err
+}
+
+// GetCursorWithArtwork streams the same rows as GetCursor, hydrated, via an id pre-pass.
+func (r *mediaFileRepository) GetCursorWithArtwork(options ...model.QueryOptions) (model.MediaFileCursor, error) {
+	ids, err := r.GetAllIDs(options...)
+	if err != nil {
+		return nil, err
+	}
+	opts := chunkOptions(options, "media_file.id")
+	return model.MediaFileCursor(streamByIDs(ids, func(chunk []string) (model.MediaFiles, error) {
+		return r.GetAll(opts(chunk))
+	})), nil
+}
+
 // FindByPaths finds media files by their paths.
 // The paths can be library-qualified (format: "libraryID:path") or unqualified ("path").
 // Library-qualified paths search within the specified library, while unqualified paths
@@ -487,7 +520,9 @@ func (r *mediaFileRepository) Search(q string, options ...model.QueryOptions) (m
 	if err != nil {
 		return nil, fmt.Errorf("searching media_file %q: %w", q, err)
 	}
-	return res.toModels(), nil
+	mfs := res.toModels()
+	r.hydrateArtwork(mfs)
+	return mfs, nil
 }
 
 func (r *mediaFileRepository) Count(options ...rest.QueryOptions) (int64, error) {
diff --git a/persistence/mediafile_repository_test.go b/persistence/mediafile_repository_test.go
index f6a744d8d..b9cba03ff 100644
--- a/persistence/mediafile_repository_test.go
+++ b/persistence/mediafile_repository_test.go
@@ -1093,4 +1093,40 @@ var _ = Describe("MediaRepository", func() {
 			_ = mr.Delete(newID)
 		})
 	})
+
+	Describe("AlbumImage hydration", func() {
+		It("carries the parent album's artwork state onto each track", func() {
+			mfs := model.MediaFiles{{ID: "mf-1", AlbumID: "al-1"}}
+			infos := map[string]model.ItemArtworkInfo{
+				"al-1": {ItemID: "al-1", Hash: "0123456789abcdef", BlurHash: "LEHV6nWB2yk8"},
+			}
+			applyItemImage(infos, mfs[0].AlbumID, &mfs[0].AlbumImage)
+
+			Expect(mfs[0].AlbumImage.ImageHash).To(Equal("0123456789abcdef"))
+			Expect(mfs[0].AlbumImage.BlurHash).To(Equal("LEHV6nWB2yk8"))
+			Expect(mfs[0].AlbumImage.ImageAbsent).To(BeFalse())
+		})
+
+		It("keeps the album state independent of the track's own art", func() {
+			mf := model.MediaFile{ID: "mf-2", AlbumID: "al-2"}
+			mf.ImageHash = "aaaaaaaaaaaaaaaa" // the track's own art
+			applyItemImage(
+				map[string]model.ItemArtworkInfo{"al-2": {ItemID: "al-2", Hash: "bbbbbbbbbbbbbbbb"}},
+				mf.AlbumID, &mf.AlbumImage,
+			)
+			Expect(mf.ImageHash).To(Equal("aaaaaaaaaaaaaaaa"))
+			Expect(mf.AlbumImage.ImageHash).To(Equal("bbbbbbbbbbbbbbbb"))
+		})
+	})
+
+	// Exists must apply the same library filter as Get/GetAll/CountAll.
+	Describe("Exists library visibility", func() {
+		It("hides a track the user has no library access to", func() {
+			restricted := model.User{ID: "restricted_mf_user", UserName: "rm", Name: "RM", Email: "rm@t.com"}
+			rctx := request.WithUser(GinkgoT().Context(), restricted)
+
+			Expect(mr.Exists(songAntenna.ID)).To(BeTrue(), "admin sees it")
+			Expect(NewMediaFileRepository(rctx, GetDBXBuilder()).Exists(songAntenna.ID)).To(BeFalse())
+		})
+	})
 })
diff --git a/persistence/persistence.go b/persistence/persistence.go
index 93f0e3e71..9d3a33cfc 100644
--- a/persistence/persistence.go
+++ b/persistence/persistence.go
@@ -97,6 +97,14 @@ func (s *SQLStore) Plugin(ctx context.Context) model.PluginRepository {
 	return NewPluginRepository(ctx, s.getDBXBuilder())
 }
 
+func (s *SQLStore) Artwork(ctx context.Context) model.ArtworkRepository {
+	return NewArtworkRepository(ctx, s.getDBXBuilder())
+}
+
+func (s *SQLStore) ArtworkQueue(ctx context.Context) model.ArtworkQueueRepository {
+	return NewArtworkQueueRepository(ctx, s.getDBXBuilder())
+}
+
 func (s *SQLStore) Resource(ctx context.Context, m any) model.ResourceRepository {
 	switch m.(type) {
 	case model.User:
diff --git a/persistence/playlist_repository.go b/persistence/playlist_repository.go
index c78e0df1e..081dab3fa 100644
--- a/persistence/playlist_repository.go
+++ b/persistence/playlist_repository.go
@@ -6,7 +6,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"iter"
 	"slices"
 	"time"
 
@@ -112,7 +111,8 @@ func (r *playlistRepository) Put(p *model.Playlist, cols ...string) error {
 		_, err := r.put(pls.ID, pls, cols...)
 		return err
 	}
-	if pls.ID == "" {
+	isNew := pls.ID == ""
+	if isNew {
 		pls.CreatedAt = time.Now()
 	}
 	pls.UpdatedAt = time.Now()
@@ -131,6 +131,12 @@ func (r *playlistRepository) Put(p *model.Playlist, cols ...string) error {
 	if len(pls.Tracks) > 0 {
 		return r.updateTracks(id, p.MediaFiles())
 	}
+	pls.ID = id // r.put assigns the generated id to p, not to this copy
+	if isNew {
+		// Even a trackless new playlist has art to find (an imported m3u can carry an
+		// ExternalImageURL); an update landing here changed only metadata, so leave its cover be.
+		r.enqueueCoverRebuild(id)
+	}
 	return r.refreshCounters(&pls.Playlist)
 }
 
@@ -172,7 +178,14 @@ func (r *playlistRepository) findBy(sql Sqlizer) (*model.Playlist, error) {
 		return nil, model.ErrNotFound
 	}
 
-	return &pls[0].Playlist, nil
+	list := model.Playlists{pls[0].Playlist}
+	r.hydrateArtwork(list)
+	return &list[0], nil
+}
+
+func (r *playlistRepository) hydrateArtwork(playlists model.Playlists) {
+	hydrateItems(r.ctx, r.db, model.KindPlaylistArtwork, playlists,
+		func(p *model.Playlist) (string, *model.ItemImage) { return p.ID, &p.ItemImage })
 }
 
 func (r *playlistRepository) GetAll(options ...model.QueryOptions) (model.Playlists, error) {
@@ -186,22 +199,34 @@ func (r *playlistRepository) GetAll(options ...model.QueryOptions) (model.Playli
 	for i, p := range res {
 		playlists[i] = p.Playlist
 	}
+	r.hydrateArtwork(playlists)
 	return playlists, err
 }
 
+// GetAllIDs returns the IDs of GetAll's row set, skipping its per-row processing.
+func (r *playlistRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+	// Joins a projection of user, not the table: its name/created_at columns would make an ORDER BY
+	// on the playlist's own ambiguous.
+	sq := r.newSelect(options...).Columns("playlist.id", "user.user_name as owner_name").
+		Join("(select id, user_name from user) user on user.id = owner_id").Where(r.userFilter())
+	if filtersNeedAnnotation(sq) {
+		sq = r.withAnnotation(sq, "playlist.id")
+	}
+	ids := []string{}
+	err := r.queryAllSlice(sq, &ids)
+	return ids, err
+}
+
 func (r *playlistRepository) GetCursor(options ...model.QueryOptions) (model.PlaylistCursor, error) {
-	// Same userFilter as GetAll: a cursor must not widen visibility beyond public/owned playlists.
-	sel := r.selectPlaylist(options...).Where(r.userFilter())
-	cursor, err := queryWithStableResults[dbPlaylist](r.sqlRepository, sel)
+	// Both passes apply userFilter, so a visibility change between them cannot widen the cursor.
+	ids, err := r.GetAllIDs(options...)
 	if err != nil {
 		return nil, err
 	}
-	return wrapPlaylistCursor(cursor), nil
-}
-
-// dbPlaylist embeds a value, not a pointer, so its model is never nil.
-func wrapPlaylistCursor(cursor iter.Seq2[dbPlaylist, error]) model.PlaylistCursor {
-	return model.PlaylistCursor(wrapCursor(cursor, func(p dbPlaylist) *model.Playlist { return &p.Playlist }))
+	opts := chunkOptions(options, "playlist.id")
+	return model.PlaylistCursor(streamByIDs(ids, func(chunk []string) (model.Playlists, error) {
+		return r.GetAll(opts(chunk))
+	})), nil
 }
 
 func (r *playlistRepository) GetPlaylists(mediaFileId string) (model.Playlists, error) {
@@ -220,6 +245,7 @@ func (r *playlistRepository) GetPlaylists(mediaFileId string) (model.Playlists,
 	for i, p := range res {
 		playlists[i] = p.Playlist
 	}
+	r.hydrateArtwork(playlists)
 	return playlists, nil
 }
 
@@ -264,6 +290,7 @@ func (r *playlistRepository) addTracks(playlistId string, startingPos int, media
 		}
 	}
 
+	r.enqueueCoverRebuild(playlistId)
 	return r.refreshCounters(&model.Playlist{ID: playlistId})
 }
 
@@ -300,6 +327,16 @@ func (r *playlistRepository) refreshCounters(pls *model.Playlist) error {
 	return nil
 }
 
+// enqueueCoverRebuild re-resolves the generated 2x2 grid. Call it only when the track set changes:
+// the grid samples albums at random, so rebuilding after a mere rename would change the cover.
+func (r *playlistRepository) enqueueCoverRebuild(id string) {
+	item := model.ArtworkQueueItem{ItemKind: model.KindPlaylistArtwork.Prefix(), ItemID: id,
+		ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityScan}
+	if err := NewArtworkQueueRepository(r.ctx, r.db).Enqueue(item); err != nil {
+		log.Warn(r.ctx, "could not enqueue playlist artwork after content change", "id", id, err)
+	}
+}
+
 // tracksQuery is shared by loadTracks and GetCursor, so both hydrate rows identically.
 func (r *playlistRepository) tracksQuery(query SelectBuilder, id string) SelectBuilder {
 	query = r.applyLibraryFilter(query, "f")
@@ -332,7 +369,9 @@ func (r *playlistRepository) loadTracks(query SelectBuilder, id string) (model.P
 	if err != nil {
 		return nil, err
 	}
-	return tracks.toModels(), err
+	res := tracks.toModels()
+	hydratePlaylistTrackArtwork(r.ctx, r.db, res)
+	return res, err
 }
 
 func (r *playlistRepository) Count(options ...rest.QueryOptions) (int64, error) {
@@ -433,6 +472,7 @@ func (r *playlistRepository) renumber(id string) error {
 	if err != nil {
 		return err
 	}
+	r.enqueueCoverRebuild(id)
 	return r.refreshCounters(&model.Playlist{ID: id})
 }
 
diff --git a/persistence/playlist_repository_test.go b/persistence/playlist_repository_test.go
index 00d4ff9f2..fc2d4ae3f 100644
--- a/persistence/playlist_repository_test.go
+++ b/persistence/playlist_repository_test.go
@@ -8,6 +8,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/pocketbase/dbx"
@@ -37,6 +38,17 @@ var _ = Describe("PlaylistRepository", func() {
 		})
 	})
 
+	Describe("GetAllIDs", func() {
+		It("returns the same id set as GetAll", func() {
+			want, err := repo.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(want).ToNot(BeEmpty())
+			ids, err := repo.GetAllIDs()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ids).To(ConsistOf(slice.Map(want, func(p model.Playlist) string { return p.ID })))
+		})
+	})
+
 	Describe("Exists", func() {
 		It("returns true for an existing playlist", func() {
 			Expect(repo.Exists(plsCool.ID)).To(BeTrue())
@@ -245,6 +257,59 @@ var _ = Describe("PlaylistRepository", func() {
 		Expect(repo.Exists(newPls.ID)).To(BeFalse())
 	})
 
+	It("enqueues a new empty playlist's artwork under its generated id, not an empty id", func() {
+		ctx := request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+		newPls := model.Playlist{Name: "Empty PL", OwnerID: "userid"} // no tracks → refreshCounters path
+		Expect(repo.Put(&newPls)).To(Succeed())
+		Expect(newPls.ID).ToNot(BeEmpty())
+		DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+
+		queued, err := NewArtworkQueueRepository(ctx, GetDBXBuilder()).DequeueBatch(1000)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(queued).To(ContainElement(SatisfyAll(HaveField("ItemKind", "pl"), HaveField("ItemID", newPls.ID))))
+		Expect(queued).ToNot(ContainElement(HaveField("ItemID", "")), "must not enqueue an empty playlist id")
+	})
+
+	// The grid samples albums at random, so re-resolving after a rename would change the cover.
+	It("does not enqueue artwork when only metadata changes", func() {
+		ctx := request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+		newPls := model.Playlist{Name: "Rename Me", OwnerID: "userid"}
+		Expect(repo.Put(&newPls)).To(Succeed())
+		DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+		// Clear the row creation just enqueued, so anything present afterwards came from the update.
+		queueRepo := NewArtworkQueueRepository(ctx, GetDBXBuilder())
+		queued, err := queueRepo.DequeueBatch(1000)
+		Expect(err).ToNot(HaveOccurred())
+		for _, q := range queued {
+			if q.ItemID == newPls.ID {
+				Expect(queueRepo.DeleteIfUnchanged(q.ItemKind, q.ItemID, q.ImageType, q.RetryAt)).To(Succeed())
+			}
+		}
+
+		newPls.Name = "Renamed"
+		newPls.Comment = "edited"
+		Expect(repo.Put(&newPls)).To(Succeed())
+
+		queued, err = queueRepo.DequeueBatch(1000)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(queued).ToNot(ContainElement(HaveField("ItemID", newPls.ID)))
+	})
+
+	It("enqueues the playlist's artwork when its track set changes", func() {
+		ctx := request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+		newPls := model.Playlist{Name: "Grid PL", OwnerID: "userid"}
+		newPls.AddMediaFilesByID([]string{"1001", "1002"})
+		Expect(repo.Put(&newPls)).To(Succeed())
+		DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+
+		queued, err := NewArtworkQueueRepository(ctx, GetDBXBuilder()).DequeueBatch(1000)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(queued).To(ContainElement(SatisfyAll(
+			HaveField("ItemKind", "pl"),
+			HaveField("ItemID", newPls.ID),
+		)))
+	})
+
 	Describe("GetAll", func() {
 		It("returns all playlists from DB", func() {
 			all, err := repo.GetAll()
@@ -341,4 +406,27 @@ var _ = Describe("PlaylistRepository", func() {
 			Expect(mediaFileIDs).To(Equal([]string{"1001", "1002"}))
 		})
 	})
+
+	// Exists is ctx-sensitive through userFilter, so callers that only want "does it still exist"
+	// -- the public image route serving a share -- must elevate, or a private playlist looks gone.
+	Describe("Exists visibility", func() {
+		It("hides a private playlist from an unauthenticated context", func() {
+			// "userid" is the fixture user; playlist.owner_id has a FK to user(id).
+			owner := model.User{ID: "userid", UserName: "userid"}
+			octx := request.WithUser(GinkgoT().Context(), owner)
+			ownerRepo := NewPlaylistRepository(octx, GetDBXBuilder())
+			pls := model.Playlist{Name: "Private One", OwnerID: owner.ID, Public: false}
+			Expect(ownerRepo.Put(&pls)).To(Succeed())
+			DeferCleanup(func() { _ = ownerRepo.Delete(pls.ID) })
+
+			Expect(ownerRepo.Exists(pls.ID)).To(BeTrue(), "the owner sees it")
+
+			anon := NewPlaylistRepository(GinkgoT().Context(), GetDBXBuilder())
+			Expect(anon.Exists(pls.ID)).To(BeFalse(), "no user: userFilter hides it")
+
+			admin := request.WithUser(GinkgoT().Context(), model.User{ID: "userid", IsAdmin: true})
+			Expect(NewPlaylistRepository(admin, GetDBXBuilder()).Exists(pls.ID)).To(BeTrue(),
+				"elevating is what the public image route relies on")
+		})
+	})
 })
diff --git a/persistence/playlist_track_repository.go b/persistence/playlist_track_repository.go
index e51ff8ea6..1a64efa20 100644
--- a/persistence/playlist_track_repository.go
+++ b/persistence/playlist_track_repository.go
@@ -130,8 +130,11 @@ func (r *playlistTrackRepository) GetCursor(options ...model.QueryOptions) (mode
 	if err != nil {
 		return nil, err
 	}
-	return model.PlaylistTrackCursor(wrapCursor(cursor, func(t dbPlaylistTrack) *model.PlaylistTrack {
+	tracks := wrapCursor(cursor, func(t dbPlaylistTrack) *model.PlaylistTrack {
 		return t.PlaylistTrack
+	})
+	return model.PlaylistTrackCursor(hydrateCursor(tracks, func(batch []model.PlaylistTrack) {
+		hydratePlaylistTrackArtwork(r.ctx, r.db, batch)
 	})), nil
 }
 
diff --git a/persistence/radio_repository.go b/persistence/radio_repository.go
index a073643db..b73487e40 100644
--- a/persistence/radio_repository.go
+++ b/persistence/radio_repository.go
@@ -7,6 +7,7 @@ import (
 
 	. "github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
+	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/pocketbase/dbx"
@@ -36,6 +37,11 @@ func (r *radioRepository) CountAll(options ...model.QueryOptions) (int64, error)
 	return r.count(sql, options...)
 }
 
+// Exists needs no library or ownership filter: radios are visible to every user.
+func (r *radioRepository) Exists(id string) (bool, error) {
+	return r.exists(Eq{"id": id})
+}
+
 func (r *radioRepository) Delete(id string) error {
 	if !r.isPermitted() {
 		return rest.ErrPermissionDenied
@@ -48,14 +54,37 @@ func (r *radioRepository) Get(id string) (*model.Radio, error) {
 	sel := r.newSelect().Where(Eq{"id": id}).Columns("*")
 	res := model.Radio{}
 	err := r.queryOne(sel, &res)
-	return &res, err
+	if err != nil {
+		return &res, err
+	}
+	list := model.Radios{res}
+	r.hydrateArtwork(list)
+	return &list[0], nil
 }
 
 func (r *radioRepository) GetAll(options ...model.QueryOptions) (model.Radios, error) {
 	sel := r.newSelect(options...).Columns("*")
 	res := model.Radios{}
 	err := r.queryAll(sel, &res)
-	return res, err
+	if err != nil {
+		return res, err
+	}
+	r.hydrateArtwork(res)
+	return res, nil
+}
+
+// hydrateArtwork fills each radio's ImageHash/ImageAbsent from one batched item_artwork lookup.
+func (r *radioRepository) hydrateArtwork(radios model.Radios) {
+	hydrateItems(r.ctx, r.db, model.KindRadioArtwork, radios,
+		func(rd *model.Radio) (string, *model.ItemImage) { return rd.ID, &rd.ItemImage })
+}
+
+// GetAllIDs returns just the radio IDs. Used by bulk enumeration (artwork backfill).
+func (r *radioRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+	sel := r.newSelect(options...).Columns("id")
+	ids := []string{}
+	err := r.queryAllSlice(sel, &ids)
+	return ids, err
 }
 
 func (r *radioRepository) Put(radio *model.Radio, colsToUpdate ...string) error {
@@ -72,7 +101,17 @@ func (r *radioRepository) Put(radio *model.Radio, colsToUpdate ...string) error
 		colsToUpdate = append(colsToUpdate, "UpdatedAt")
 	}
 	_, err := r.put(radio.ID, radio, colsToUpdate...)
-	return err
+	if err != nil {
+		return err
+	}
+	// Enqueue artwork resolution for the created/updated radio at Bump priority so a new
+	// radio's cover resolves proactively. Never fails the save.
+	item := model.ArtworkQueueItem{ItemKind: model.KindRadioArtwork.Prefix(), ItemID: radio.ID, ImageType: model.ImageTypePrimary,
+		Priority: model.ArtworkPriorityBump}
+	if err := NewArtworkQueueRepository(r.ctx, r.db).Enqueue(item); err != nil {
+		log.Warn(r.ctx, "could not enqueue radio artwork", "id", radio.ID, err)
+	}
+	return nil
 }
 
 func (r *radioRepository) Count(options ...rest.QueryOptions) (int64, error) {
diff --git a/persistence/radio_repository_test.go b/persistence/radio_repository_test.go
index 05628ca41..e2564455d 100644
--- a/persistence/radio_repository_test.go
+++ b/persistence/radio_repository_test.go
@@ -7,6 +7,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -78,6 +79,17 @@ var _ = Describe("RadioRepository", func() {
 			})
 		})
 
+		Describe("GetAllIDs", func() {
+			It("returns the same id set as GetAll", func() {
+				want, err := repo.GetAll()
+				Expect(err).To(BeNil())
+				Expect(want).ToNot(BeEmpty())
+				ids, err := repo.GetAllIDs()
+				Expect(err).To(BeNil())
+				Expect(ids).To(ConsistOf(slice.Map(want, func(r model.Radio) string { return r.ID })))
+			})
+		})
+
 		Describe("Put", func() {
 			It("successfully updates item", func() {
 				err := repo.Put(&model.Radio{
@@ -107,6 +119,27 @@ var _ = Describe("RadioRepository", func() {
 				Expect(err).To(BeNil())
 				Expect(all[2].StreamUrl).To(Equal("https://example.com:4533/app"))
 			})
+
+			It("enqueues artwork resolution for the saved radio", func() {
+				err := repo.Put(&model.Radio{
+					Name:      "Artwork radio",
+					StreamUrl: "https://example.com:4533/artwork",
+				})
+				Expect(err).To(BeNil())
+
+				all, err := repo.GetAll()
+				Expect(err).To(BeNil())
+				created := all[len(all)-1]
+
+				queueRepo := NewArtworkQueueRepository(context.Background(), GetDBXBuilder())
+				queued, err := queueRepo.DequeueBatch(1000)
+				Expect(err).To(BeNil())
+				Expect(queued).To(ContainElement(SatisfyAll(
+					HaveField("ItemKind", "ra"),
+					HaveField("ItemID", created.ID),
+					HaveField("Priority", model.ArtworkPriorityBump),
+				)))
+			})
 		})
 	})
 
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index d0cbb2946..33450fe9f 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -15,6 +15,7 @@ import (
 	. "github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	id2 "github.com/navidrome/navidrome/model/id"
@@ -597,9 +598,15 @@ func (r sqlRepository) delete(cond Sqlizer) error {
 
 func (r sqlRepository) logSQL(sql string, args dbx.Params, err error, rowsAffected int64, start time.Time) {
 	elapsed := time.Since(start)
+	fields := []any{r.ctx, "SQL: `" + sql + "`", "args", args, "rowsAffected", rowsAffected, "elapsedTime", elapsed}
 	if err == nil || errors.Is(err, context.Canceled) {
-		log.Trace(r.ctx, "SQL: `"+sql+"`", "args", args, "rowsAffected", rowsAffected, "elapsedTime", elapsed, err)
-	} else {
-		log.Error(r.ctx, "SQL: `"+sql+"`", "args", args, "rowsAffected", rowsAffected, "elapsedTime", elapsed, err)
+		log.Trace(append(fields, err)...)
+		return
 	}
+	// The result codes separate errors that share a message, notably SQLITE_BUSY from
+	// SQLITE_BUSY_SNAPSHOT, which no busy_timeout can retry.
+	if code, extended, ok := db.ErrorCodes(err); ok {
+		fields = append(fields, "sqliteCode", code, "sqliteExtended", extended)
+	}
+	log.Error(append(fields, err)...)
 }
diff --git a/scanner/controller.go b/scanner/controller.go
index 463718ba3..df5aeb6f9 100644
--- a/scanner/controller.go
+++ b/scanner/controller.go
@@ -11,7 +11,6 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playlists"
@@ -28,12 +27,11 @@ var (
 	ErrAlreadyScanning = errors.New("already scanning")
 )
 
-func New(rootCtx context.Context, ds model.DataStore, cw artwork.CacheWarmer, broker events.Broker,
+func New(rootCtx context.Context, ds model.DataStore, broker events.Broker,
 	pls playlists.Playlists, m metrics.Metrics) model.Scanner {
 	c := &controller{
 		rootCtx:            rootCtx,
 		ds:                 ds,
-		cw:                 cw,
 		broker:             broker,
 		pls:                pls,
 		metrics:            m,
@@ -49,7 +47,7 @@ func (s *controller) getScanner() scanner {
 	if s.devExternalScanner {
 		return &scannerExternal{}
 	}
-	return &scannerImpl{ds: s.ds, cw: s.cw, pls: s.pls}
+	return &scannerImpl{ds: s.ds, pls: s.pls}
 }
 
 // CallScan starts an in-process scan of specific library/folder pairs.
@@ -66,7 +64,7 @@ func CallScan(ctx context.Context, ds model.DataStore, pls playlists.Playlists,
 	progress := make(chan *ProgressInfo, 100)
 	go func() {
 		defer close(progress)
-		scanner := &scannerImpl{ds: ds, cw: artwork.NoopCacheWarmer(), pls: pls}
+		scanner := &scannerImpl{ds: ds, pls: pls}
 		scanner.scanFolders(ctx, fullScan, targets, progress)
 	}()
 	return progress, nil
@@ -97,7 +95,6 @@ type scanner interface {
 type controller struct {
 	rootCtx            context.Context
 	ds                 model.DataStore
-	cw                 artwork.CacheWarmer
 	broker             events.Broker
 	metrics            metrics.Metrics
 	pls                playlists.Playlists
diff --git a/scanner/controller_test.go b/scanner/controller_test.go
index e4814da64..7ffdd69d4 100644
--- a/scanner/controller_test.go
+++ b/scanner/controller_test.go
@@ -5,7 +5,6 @@ import (
 
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playlists"
@@ -32,7 +31,7 @@ var _ = Describe("Controller", func() {
 			DeferCleanup(configtest.SetupConfig())
 			ds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
 			ds.MockedProperty = &tests.MockedPropertyRepo{}
-			ctrl = scanner.New(ctx, ds, artwork.NoopCacheWarmer(), events.NoopBroker(), playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+			ctrl = scanner.New(ctx, ds, events.NoopBroker(), playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 		})
 
 		It("includes last scan error", func() {
diff --git a/scanner/phase_1_folders.go b/scanner/phase_1_folders.go
index 5e898590b..e853948e6 100644
--- a/scanner/phase_1_folders.go
+++ b/scanner/phase_1_folders.go
@@ -16,7 +16,6 @@ import (
 	ppl "github.com/google/go-pipeline/pkg/pipeline"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -26,7 +25,7 @@ import (
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
-func createPhaseFolders(ctx context.Context, state *scanState, ds model.DataStore, cw artwork.CacheWarmer) *phaseFolders {
+func createPhaseFolders(ctx context.Context, state *scanState, ds model.DataStore) *phaseFolders {
 	var jobs []*scanJob
 
 	// Create scan jobs for all libraries
@@ -37,7 +36,7 @@ func createPhaseFolders(ctx context.Context, state *scanState, ds model.DataStor
 			targetFolders = state.targets[lib.ID]
 		}
 
-		job, err := newScanJob(ctx, ds, cw, lib, state.fullScan, targetFolders)
+		job, err := newScanJob(ctx, ds, lib, state.fullScan, targetFolders)
 		if err != nil {
 			log.Error(ctx, "Scanner: Error creating scan context", "lib", lib.Name, err)
 			state.sendError(err)
@@ -52,14 +51,13 @@ func createPhaseFolders(ctx context.Context, state *scanState, ds model.DataStor
 type scanJob struct {
 	lib           model.Library
 	fs            storage.MusicFS
-	cw            artwork.CacheWarmer
 	lastUpdates   map[string]model.FolderUpdateInfo // Holds last update info for all (DB) folders in this library
 	targetFolders []string                          // Specific folders to scan (including all descendants)
 	lock          sync.Mutex
 	numFolders    atomic.Int64
 }
 
-func newScanJob(ctx context.Context, ds model.DataStore, cw artwork.CacheWarmer, lib model.Library, fullScan bool, targetFolders []string) (*scanJob, error) {
+func newScanJob(ctx context.Context, ds model.DataStore, lib model.Library, fullScan bool, targetFolders []string) (*scanJob, error) {
 	// Get folder updates, optionally filtered to specific target folders
 	lastUpdates, err := ds.Folder(ctx).GetFolderUpdateInfo(lib, targetFolders...)
 	if err != nil {
@@ -85,7 +83,6 @@ func newScanJob(ctx context.Context, ds model.DataStore, cw artwork.CacheWarmer,
 	return &scanJob{
 		lib:           lib,
 		fs:            fsys,
-		cw:            cw,
 		lastUpdates:   lastUpdates,
 		targetFolders: targetFolders,
 	}, nil
@@ -330,8 +327,8 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 	defer p.measure(entry)()
 	p.state.changesDetected.Store(true)
 
-	// Collect artwork IDs to pre-cache after the transaction commits
-	var artworkIDs []model.ArtworkID
+	// Collect artwork queue items for changed albums/artists, enqueued in the same transaction
+	var queueItems []model.ArtworkQueueItem
 
 	err := p.ds.WithTx(func(tx model.DataStore) error {
 		// Instantiate all repositories just once per folder
@@ -371,7 +368,10 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 				return err
 			}
 			if entry.artists[i].Name != consts.UnknownArtist && entry.artists[i].Name != consts.VariousArtists {
-				artworkIDs = append(artworkIDs, entry.artists[i].CoverArtID())
+				queueItems = append(queueItems, model.ArtworkQueueItem{
+					ItemKind: model.KindArtistArtwork.Prefix(), ItemID: entry.artists[i].ID, ImageType: model.ImageTypePrimary,
+					Priority: model.ArtworkPriorityScan,
+				})
 			}
 		}
 
@@ -383,7 +383,10 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 				return err
 			}
 			if entry.albums[i].Name != consts.UnknownAlbum {
-				artworkIDs = append(artworkIDs, entry.albums[i].CoverArtID())
+				queueItems = append(queueItems, model.ArtworkQueueItem{
+					ItemKind: model.KindAlbumArtwork.Prefix(), ItemID: entry.albums[i].ID, ImageType: model.ImageTypePrimary,
+					Priority: model.ArtworkPriorityScan,
+				})
 			}
 		}
 
@@ -396,6 +399,14 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 			}
 		}
 
+		// A re-imported track returns to unresolved so new embedded art is picked up lazily.
+		if len(entry.tracks) > 0 {
+			trackIDs := slice.Map(entry.tracks, func(t model.MediaFile) string { return t.ID })
+			if err := tx.Artwork(p.ctx).DeleteForItems(model.KindMediaFileArtwork, trackIDs); err != nil {
+				log.Warn(p.ctx, "Scanner: could not invalidate media_file artwork", "folder", entry.path, err)
+			}
+		}
+
 		// Mark all missing tracks as not available
 		if len(entry.missingTracks) > 0 {
 			err = mfRepo.MarkMissing(true, entry.missingTracks...)
@@ -415,19 +426,25 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 				return err
 			}
 		}
+
+		// Enqueue artwork resolution for changed albums/artists. Never fails the scan.
+		// A full scan re-imports every track, so a re-import is no evidence the art changed.
+		if len(queueItems) > 0 {
+			queue := tx.ArtworkQueue(p.ctx)
+			enqueue := queue.Enqueue
+			if p.state.fullScan {
+				enqueue = queue.EnqueueIfMissing
+			}
+			if err := enqueue(queueItems...); err != nil {
+				log.Warn(p.ctx, "Scanner: could not enqueue artwork resolution", "folder", entry.path, err)
+			}
+		}
 		return nil
 	}, "scanner: persist changes")
 	if err != nil {
 		log.Error(p.ctx, "Scanner: Error persisting changes to DB", "folder", entry.path, err)
 	}
 
-	// Pre-cache artwork after the transaction commits successfully
-	if err == nil {
-		for _, artID := range artworkIDs {
-			entry.job.cw.PreCache(artID)
-		}
-	}
-
 	return entry, err
 }
 
diff --git a/scanner/phase_4_playlists.go b/scanner/phase_4_playlists.go
index 8ba014235..baa8b749a 100644
--- a/scanner/phase_4_playlists.go
+++ b/scanner/phase_4_playlists.go
@@ -12,7 +12,6 @@ import (
 	ppl "github.com/google/go-pipeline/pkg/pipeline"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -24,18 +23,16 @@ type phasePlaylists struct {
 	scanState     *scanState
 	ds            model.DataStore
 	pls           playlists.Playlists
-	cw            artwork.CacheWarmer
 	refreshed     atomic.Uint32
 	pendingImport bool
 }
 
-func createPhasePlaylists(ctx context.Context, scanState *scanState, ds model.DataStore, pls playlists.Playlists, cw artwork.CacheWarmer) *phasePlaylists {
+func createPhasePlaylists(ctx context.Context, scanState *scanState, ds model.DataStore, pls playlists.Playlists) *phasePlaylists {
 	return &phasePlaylists{
 		ctx:       ctx,
 		scanState: scanState,
 		ds:        ds,
 		pls:       pls,
-		cw:        cw,
 	}
 }
 
@@ -148,7 +145,11 @@ func (p *phasePlaylists) processPlaylistsInFolder(folder *model.Folder) (*model.
 		} else {
 			log.Debug("Scanner: Imported playlist", "name", pls.Name, "lastUpdated", pls.UpdatedAt, "path", pls.Path, "numTracks", len(pls.Tracks), "elapsed", time.Since(started))
 		}
-		p.cw.PreCache(pls.CoverArtID())
+		item := model.ArtworkQueueItem{ItemKind: model.KindPlaylistArtwork.Prefix(), ItemID: pls.ID, ImageType: model.ImageTypePrimary,
+			Priority: model.ArtworkPriorityScan}
+		if err := p.ds.ArtworkQueue(p.ctx).Enqueue(item); err != nil {
+			log.Warn(p.ctx, "Scanner: could not enqueue playlist artwork", "id", pls.ID, err)
+		}
 		p.refreshed.Add(1)
 	}
 	return folder, nil
diff --git a/scanner/phase_4_playlists_test.go b/scanner/phase_4_playlists_test.go
index 49ffc7fb7..93ec1a36d 100644
--- a/scanner/phase_4_playlists_test.go
+++ b/scanner/phase_4_playlists_test.go
@@ -10,7 +10,6 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
@@ -27,7 +26,6 @@ var _ = Describe("phasePlaylists", func() {
 		folderRepo *mockFolderRepository
 		ds         *tests.MockDataStore
 		pls        *mockPlaylists
-		cw         artwork.CacheWarmer
 	)
 
 	var userRepo *tests.MockedUserRepo
@@ -48,9 +46,8 @@ var _ = Describe("phasePlaylists", func() {
 			MockedProperty: propRepo,
 		}
 		pls = &mockPlaylists{}
-		cw = artwork.NoopCacheWarmer()
 		state = &scanState{}
-		phase = createPhasePlaylists(ctx, state, ds, pls, cw)
+		phase = createPhasePlaylists(ctx, state, ds, pls)
 	})
 
 	Describe("description", func() {
@@ -193,6 +190,29 @@ var _ = Describe("phasePlaylists", func() {
 			Expect(phase.refreshed.Load()).To(Equal(uint32(2)))
 		})
 
+		It("enqueues artwork resolution for the imported playlist", func() {
+			libPath := GinkgoT().TempDir()
+			folder := &model.Folder{LibraryPath: libPath, Path: "path/to", Name: "folder"}
+			_ = os.MkdirAll(folder.AbsolutePath(), 0755)
+
+			file1 := filepath.Join(folder.AbsolutePath(), "playlist1.m3u")
+			_ = os.WriteFile(file1, []byte{}, 0600)
+
+			pls.On("ImportFromFolder", mock.Anything, folder, "playlist1.m3u").
+				Return(&model.Playlist{ID: "pl1"}, nil)
+
+			_, err := phase.processPlaylistsInFolder(folder)
+			Expect(err).ToNot(HaveOccurred())
+
+			queued, err := ds.ArtworkQueue(ctx).DequeueBatch(10)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(queued).To(ContainElement(SatisfyAll(
+				HaveField("ItemKind", "pl"),
+				HaveField("ItemID", "pl1"),
+				HaveField("Priority", model.ArtworkPriorityScan),
+			)))
+		})
+
 		It("reports an error if there is an error reading files", func() {
 			tests.SkipOnWindows("relies on Unix /etc filesystem")
 			progress := make(chan *ProgressInfo)
diff --git a/scanner/scanner.go b/scanner/scanner.go
index 27e2b19d2..29a1f9b4e 100644
--- a/scanner/scanner.go
+++ b/scanner/scanner.go
@@ -11,7 +11,6 @@ import (
 	ppl "github.com/google/go-pipeline/pkg/pipeline"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -21,7 +20,6 @@ import (
 
 type scannerImpl struct {
 	ds  model.DataStore
-	cw  artwork.CacheWarmer
 	pls playlists.Playlists
 }
 
@@ -136,7 +134,7 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 
 	err = run.Sequentially(
 		// Phase 1: Scan all libraries and import new/updated files
-		runPhase[*folderEntry](ctx, 1, createPhaseFolders(ctx, &state, s.ds, s.cw)),
+		runPhase[*folderEntry](ctx, 1, createPhaseFolders(ctx, &state, s.ds)),
 
 		// Phase 2: Process missing files, checking for moves
 		runPhase[*missingTracks](ctx, 2, createPhaseMissingTracks(ctx, &state, s.ds)),
@@ -147,7 +145,7 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 			runPhase[*model.Album](ctx, 3, createPhaseRefreshAlbums(ctx, &state, s.ds)),
 
 			// Phase 4: Import/update playlists
-			runPhase[*model.Folder](ctx, 4, createPhasePlaylists(ctx, &state, s.ds, s.pls, s.cw)),
+			runPhase[*model.Folder](ctx, 4, createPhasePlaylists(ctx, &state, s.ds, s.pls)),
 		),
 
 		// Final Steps (cannot be parallelized):
@@ -155,6 +153,9 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 		// Run GC if there were any changes (Remove dangling tracks, empty albums and artists, and orphan annotations)
 		s.runGC(ctx, &state),
 
+		// Queue artwork for entities that never resolved (after GC, so nothing dangling is queued)
+		s.runEnqueueMissingArtwork(ctx, &state),
+
 		// Refresh artist and tags stats
 		s.runRefreshStats(ctx, &state),
 
@@ -251,6 +252,29 @@ func (s *scannerImpl) runGC(ctx context.Context, state *scanState) func() error
 	}
 }
 
+// runEnqueueMissingArtwork is the safety net for entities phase 1 never enqueued.
+func (s *scannerImpl) runEnqueueMissingArtwork(ctx context.Context, state *scanState) func() error {
+	return func() error {
+		if !state.changesDetected.Load() {
+			log.Debug(ctx, "Scanner: No changes detected, skipping artwork enqueue")
+			return nil
+		}
+		start := time.Now()
+		queue := s.ds.ArtworkQueue(ctx)
+		var total int64
+		for _, kind := range []model.Kind{model.KindAlbumArtwork, model.KindArtistArtwork} {
+			n, err := queue.EnqueueAllMissing(kind, model.ArtworkPriorityScan)
+			if err != nil {
+				log.Error(ctx, "Scanner: Error enqueueing missing artwork", "kind", kind, err)
+				return fmt.Errorf("enqueueing missing artwork: %w", err)
+			}
+			total += n
+		}
+		log.Debug(ctx, "Scanner: Enqueued missing artwork", "items", total, "elapsed", time.Since(start))
+		return nil
+	}
+}
+
 func (s *scannerImpl) runRefreshStats(ctx context.Context, state *scanState) func() error {
 	return func() error {
 		if !state.changesDetected.Load() {
diff --git a/scanner/scanner_benchmark_test.go b/scanner/scanner_benchmark_test.go
index 8f0dcd340..ca1064631 100644
--- a/scanner/scanner_benchmark_test.go
+++ b/scanner/scanner_benchmark_test.go
@@ -12,7 +12,6 @@ import (
 	"github.com/dustin/go-humanize"
 	"github.com/google/uuid"
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playlists"
@@ -40,8 +39,8 @@ func BenchmarkScan(b *testing.B) {
 
 	ds := persistence.New(db.Db())
 	conf.Server.DevExternalScanner = false
-	s := scanner.New(context.Background(), ds, artwork.NoopCacheWarmer(), events.NoopBroker(),
-		playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+	s := scanner.New(context.Background(), ds, events.NoopBroker(),
+		playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 
 	fs := storagetest.FakeFS{}
 	storagetest.Register("fake", &fs)
diff --git a/scanner/scanner_multilibrary_test.go b/scanner/scanner_multilibrary_test.go
index 3ae50933c..c0d5d4ece 100644
--- a/scanner/scanner_multilibrary_test.go
+++ b/scanner/scanner_multilibrary_test.go
@@ -11,7 +11,6 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playlists"
@@ -78,8 +77,8 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 		}
 		Expect(ds.User(ctx).Put(&adminUser)).To(Succeed())
 
-		s = scanner.New(ctx, ds, artwork.NoopCacheWarmer(), events.NoopBroker(),
-			playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+		s = scanner.New(ctx, ds, events.NoopBroker(),
+			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 
 		// Create two test libraries (let DB auto-assign IDs)
 		lib1 = model.Library{Name: "Rock Collection", Path: "rock:///music"}
diff --git a/scanner/scanner_selective_test.go b/scanner/scanner_selective_test.go
index 17772bf9d..acaa8f850 100644
--- a/scanner/scanner_selective_test.go
+++ b/scanner/scanner_selective_test.go
@@ -10,7 +10,6 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playlists"
@@ -66,8 +65,8 @@ var _ = Describe("ScanFolders", Ordered, func() {
 		}
 		Expect(ds.User(ctx).Put(&adminUser)).To(Succeed())
 
-		s = scanner.New(ctx, ds, artwork.NoopCacheWarmer(), events.NoopBroker(),
-			playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+		s = scanner.New(ctx, ds, events.NoopBroker(),
+			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 
 		lib = model.Library{ID: 1, Name: "Fake Library", Path: "fake:///music"}
 		Expect(ds.Library(ctx).Put(&lib)).To(Succeed())
diff --git a/scanner/scanner_test.go b/scanner/scanner_test.go
index cc3720717..6098cbd66 100644
--- a/scanner/scanner_test.go
+++ b/scanner/scanner_test.go
@@ -13,7 +13,6 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playlists"
@@ -86,8 +85,8 @@ var _ = Describe("Scanner", Ordered, func() {
 		}
 		Expect(ds.User(ctx).Put(&adminUser)).To(Succeed())
 
-		s = scanner.New(ctx, ds, artwork.NoopCacheWarmer(), events.NoopBroker(),
-			playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+		s = scanner.New(ctx, ds, events.NoopBroker(),
+			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 
 		lib = model.Library{ID: 1, Name: "Fake Library", Path: "fake:///music"}
 		Expect(ds.Library(ctx).Put(&lib)).To(Succeed())
@@ -98,6 +97,22 @@ var _ = Describe("Scanner", Ordered, func() {
 		return err
 	}
 
+	// Stands in for the artwork worker: drains the queue and records every item as resolved,
+	// so a later scan can only queue genuine reprocessing.
+	resolveQueuedArtwork := func() []model.ArtworkQueueItem {
+		GinkgoHelper()
+		queued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+		Expect(err).ToNot(HaveOccurred())
+		for _, it := range queued {
+			Expect(ds.Artwork(ctx).PutItemArtwork(&model.ItemArtwork{
+				ItemKind: it.ItemKind, ItemID: it.ItemID, ImageType: it.ImageType,
+				Hash: "resolved", Source: "embedded", UpdatedAt: time.Now(),
+			})).To(Succeed())
+			Expect(ds.ArtworkQueue(ctx).DeleteIfUnchanged(it.ItemKind, it.ItemID, it.ImageType, it.RetryAt)).To(Succeed())
+		}
+		return queued
+	}
+
 	Context("Simple library, 'artis/album/track - title.mp3'", func() {
 		var help, revolver func(...map[string]any) *fstest.MapFile
 		var fsys storagetest.FakeFS
@@ -152,6 +167,40 @@ var _ = Describe("Scanner", Ordered, func() {
 					HaveField("SongCount", Equal(4)),
 				))
 			})
+			It("should enqueue artwork resolution for the scanned albums and artists", func() {
+				Expect(runScanner(ctx, true)).To(Succeed())
+
+				albums, _ := ds.Album(ctx).GetAll()
+				artists, _ := ds.Artist(ctx).GetAll(model.QueryOptions{Filters: squirrel.NotEq{"name": consts.UnknownArtist}})
+				queued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+				Expect(err).ToNot(HaveOccurred())
+
+				for _, al := range albums {
+					Expect(queued).To(ContainElement(SatisfyAll(
+						HaveField("ItemKind", "al"),
+						HaveField("ItemID", al.ID),
+						HaveField("Priority", model.ArtworkPriorityScan),
+					)))
+				}
+				for _, ar := range artists {
+					Expect(queued).To(ContainElement(SatisfyAll(
+						HaveField("ItemKind", "ar"),
+						HaveField("ItemID", ar.ID),
+						HaveField("Priority", model.ArtworkPriorityScan),
+					)))
+				}
+			})
+			It("should not re-enqueue already resolved artwork on a repeat full scan", func() {
+				Expect(runScanner(ctx, true)).To(Succeed())
+
+				Expect(resolveQueuedArtwork()).ToNot(BeEmpty())
+
+				Expect(runScanner(ctx, true)).To(Succeed())
+
+				requeued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(requeued).To(BeEmpty())
+			})
 		})
 		When("a file was changed", func() {
 			It("should update the media_file", func() {
@@ -169,6 +218,25 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(mf[0].Tags).To(HaveKeyWithValue(model.TagName("barcode"), []string{"123"}))
 			})
 
+			It("should re-enqueue the album artwork even though it already resolved", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
+				Expect(runScanner(ctx, true)).To(Succeed())
+
+				resolveQueuedArtwork()
+
+				fsys.UpdateTags("The Beatles/Help!/01 - Help!.mp3", _t{"producer": "George Martin"})
+				Expect(runScanner(ctx, false)).To(Succeed())
+
+				albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": "Help!"}})
+				Expect(err).ToNot(HaveOccurred())
+				requeued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(requeued).To(ContainElement(SatisfyAll(
+					HaveField("ItemKind", "al"),
+					HaveField("ItemID", albums[0].ID),
+				)))
+			})
+
 			It("should update the album", func() {
 				tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 				Expect(runScanner(ctx, true)).To(Succeed())
@@ -187,6 +255,26 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(albums[0].Participants.First(model.RoleProducer).Name).To(Equal("George Martin"))
 				Expect(albums[0].SongCount).To(Equal(3))
 			})
+
+			It("invalidates the media_file artwork state so new embedded art is picked up lazily", func() {
+				Expect(runScanner(ctx, true)).To(Succeed())
+
+				mf, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"title": "Help!"}})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mf).ToNot(BeEmpty())
+				trackID := mf[0].ID
+
+				Expect(ds.Artwork(ctx).PutItemArtwork(&model.ItemArtwork{
+					ItemKind: "mf", ItemID: trackID, ImageType: model.ImageTypePrimary,
+					Source: "embedded", Hash: "stalehash",
+				})).To(Succeed())
+
+				fsys.UpdateTags("The Beatles/Help!/01 - Help!.mp3", _t{"comment": "reimport"})
+				Expect(runScanner(ctx, true)).To(Succeed())
+
+				_, err = ds.Artwork(ctx).GetItemArtwork(model.KindMediaFileArtwork, trackID, model.ImageTypePrimary)
+				Expect(err).To(MatchError(model.ErrNotFound))
+			})
 		})
 	})
 
diff --git a/server/imghttp/headers.go b/server/imghttp/headers.go
new file mode 100644
index 000000000..9308bcdab
--- /dev/null
+++ b/server/imghttp/headers.go
@@ -0,0 +1,67 @@
+// Package imghttp holds the HTTP caching contract shared by the subsonic, public, and jellyfin
+// image handlers, so they apply identical headers without importing each other.
+package imghttp
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/navidrome/navidrome/core/artwork"
+)
+
+// WriteImageHeaders applies the artwork caching contract and reports whether a 304 was written
+// (the caller must then not write a body). requestedHash is the hash the client asserted, or "".
+func WriteImageHeaders(w http.ResponseWriter, r *http.Request, img *artwork.Image, requestedHash string) (wrote304 bool) {
+	h := w.Header()
+	// Placeholders are transient stand-ins for unresolved art: never cached, no validators.
+	if img.Placeholder {
+		h.Set("Cache-Control", "no-store")
+		return false
+	}
+
+	// The ETag versions the served representation, so a re-encoding config change invalidates a
+	// revalidating client's cache; full-size originals are their own pixel hash.
+	etag := img.ETag
+	if etag == "" {
+		etag = img.Hash
+	}
+	// An empty validator would be shared by every such response, 304ing clients that echo it back.
+	if etag != "" {
+		h.Set("ETag", `"`+etag+`"`)
+	}
+	if !img.LastUpdated.IsZero() {
+		h.Set("Last-Modified", img.LastUpdated.UTC().Format(http.TimeFormat))
+	}
+	// Immutable only when the client asked for the current pixel hash; anything else revalidates,
+	// so art that gets re-resolved is never pinned.
+	if requestedHash != "" && requestedHash == img.Hash {
+		h.Set("Cache-Control", "public, max-age=31536000, immutable")
+	} else {
+		h.Set("Cache-Control", "public, no-cache")
+	}
+
+	if etag != "" && ifNoneMatch(r.Header.Get("If-None-Match"), etag) {
+		w.WriteHeader(http.StatusNotModified)
+		return true
+	}
+	return false
+}
+
+// ifNoneMatch reports whether If-None-Match asserts hash, using RFC 9110 weak comparison.
+func ifNoneMatch(header, hash string) bool {
+	header = strings.TrimSpace(header)
+	if header == "" {
+		return false
+	}
+	if header == "*" {
+		return true
+	}
+	for tag := range strings.SplitSeq(header, ",") {
+		tag = strings.TrimSpace(tag)
+		tag = strings.TrimPrefix(tag, "W/")
+		if strings.Trim(tag, `"`) == hash {
+			return true
+		}
+	}
+	return false
+}
diff --git a/server/imghttp/headers_test.go b/server/imghttp/headers_test.go
new file mode 100644
index 000000000..2e8313faf
--- /dev/null
+++ b/server/imghttp/headers_test.go
@@ -0,0 +1,117 @@
+package imghttp_test
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"time"
+
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/server/imghttp"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+const testHash = "0123456789abcdef"
+const testRepTag = testHash + ".300.false.q75"
+
+var lastMod = time.Date(2024, 1, 2, 3, 4, 5, 0, time.UTC)
+
+func found() *artwork.Image {
+	return &artwork.Image{
+		ReadCloser:  io.NopCloser(strings.NewReader("IMG")),
+		Hash:        testHash,
+		LastUpdated: lastMod,
+	}
+}
+
+func placeholder() *artwork.Image {
+	return &artwork.Image{ReadCloser: io.NopCloser(strings.NewReader("PH")), Placeholder: true}
+}
+
+// A re-encoded response carries a representation ETag distinct from the pixel hash, so the
+// validator versions with the encode settings.
+func resized() *artwork.Image {
+	return &artwork.Image{
+		ReadCloser:  io.NopCloser(strings.NewReader("IMG")),
+		Hash:        testHash,
+		ETag:        testRepTag,
+		LastUpdated: lastMod,
+	}
+}
+
+func unvalidated() *artwork.Image {
+	return &artwork.Image{ReadCloser: io.NopCloser(strings.NewReader("IMG")), LastUpdated: lastMod}
+}
+
+var _ = Describe("WriteImageHeaders", func() {
+	type testCase struct {
+		img           *artwork.Image
+		requestedHash string
+		ifNoneMatch   string
+		want304       bool
+		wantCache     string
+		wantETag      string
+		wantLastMod   bool
+	}
+
+	DescribeTable("applies the artwork caching contract",
+		func(c testCase) {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/img", nil)
+			if c.ifNoneMatch != "" {
+				r.Header.Set("If-None-Match", c.ifNoneMatch)
+			}
+
+			Expect(imghttp.WriteImageHeaders(w, r, c.img, c.requestedHash)).To(Equal(c.want304))
+
+			h := w.Header()
+			Expect(h.Get("Cache-Control")).To(Equal(c.wantCache))
+			Expect(h.Get("ETag")).To(Equal(c.wantETag))
+			if c.img.Placeholder {
+				Expect(h.Get("ETag")).To(BeEmpty(), "placeholder must not set an ETag")
+				Expect(h.Get("Last-Modified")).To(BeEmpty(), "placeholder must not set Last-Modified")
+			}
+			Expect(h.Get("Last-Modified") != "").To(Equal(c.wantLastMod))
+			if c.want304 {
+				Expect(w.Code).To(Equal(http.StatusNotModified))
+				Expect(w.Body.Len()).To(BeZero(), "a 304 must have an empty body")
+			}
+		},
+		Entry("placeholder is never cached and carries no validators",
+			testCase{img: placeholder(), wantCache: "no-store"}),
+		Entry("found with matching requested hash is immutable",
+			testCase{img: found(), requestedHash: testHash, wantCache: "public, max-age=31536000, immutable", wantETag: `"` + testHash + `"`, wantLastMod: true}),
+		Entry("found with bare id revalidates via no-cache",
+			testCase{img: found(), wantCache: "public, no-cache", wantETag: `"` + testHash + `"`, wantLastMod: true}),
+		Entry("found with mismatched requested hash revalidates",
+			testCase{img: found(), requestedHash: "ffffffffffffffff", wantCache: "public, no-cache", wantETag: `"` + testHash + `"`, wantLastMod: true}),
+		Entry("resized keeps pixel-hash immutable but serves the representation ETag",
+			testCase{img: resized(), requestedHash: testHash, wantCache: "public, max-age=31536000, immutable", wantETag: `"` + testRepTag + `"`, wantLastMod: true}),
+		Entry("resized 304s on the representation ETag, not the pixel hash",
+			testCase{img: resized(), ifNoneMatch: `"` + testRepTag + `"`, want304: true, wantCache: "public, no-cache", wantETag: `"` + testRepTag + `"`, wantLastMod: true}),
+		Entry("resized does not 304 on a stale pixel-hash validator (config changed)",
+			testCase{img: resized(), ifNoneMatch: `"` + testHash + `"`, want304: false, wantCache: "public, no-cache", wantETag: `"` + testRepTag + `"`, wantLastMod: true}),
+		Entry("If-None-Match matching the hash yields 304",
+			testCase{img: found(), requestedHash: testHash, ifNoneMatch: `"` + testHash + `"`, want304: true, wantCache: "public, max-age=31536000, immutable", wantETag: `"` + testHash + `"`, wantLastMod: true}),
+		Entry("weak If-None-Match matches (weak comparison)",
+			testCase{img: found(), ifNoneMatch: `W/"` + testHash + `"`, want304: true, wantCache: "public, no-cache", wantETag: `"` + testHash + `"`, wantLastMod: true}),
+		Entry("If-None-Match with multiple values matches one",
+			testCase{img: found(), ifNoneMatch: `"deadbeefdeadbeef", W/"` + testHash + `", "cafecafecafecafe"`, want304: true, wantCache: "public, no-cache", wantETag: `"` + testHash + `"`, wantLastMod: true}),
+		Entry("If-None-Match star matches any current representation",
+			testCase{img: found(), ifNoneMatch: "*", want304: true, wantCache: "public, no-cache", wantETag: `"` + testHash + `"`, wantLastMod: true}),
+		Entry("non-matching If-None-Match serves body",
+			testCase{img: found(), ifNoneMatch: `"deadbeefdeadbeef"`, want304: false, wantCache: "public, no-cache", wantETag: `"` + testHash + `"`, wantLastMod: true}),
+		Entry("placeholder ignores If-None-Match and never 304s",
+			testCase{img: placeholder(), ifNoneMatch: "*", want304: false, wantCache: "no-store"}),
+
+		// With no validator, an emitted ETag would be the same empty tag on every such response,
+		// and matching it would 304 changed bytes.
+		Entry("omits the ETag entirely when there is no validator",
+			testCase{img: unvalidated(), wantCache: "public, no-cache", wantLastMod: true}),
+		Entry("never 304s an empty validator echoed back by the client",
+			testCase{img: unvalidated(), ifNoneMatch: `""`, want304: false,
+				wantCache: "public, no-cache", wantLastMod: true}),
+	)
+})
diff --git a/server/imghttp/imghttp_suite_test.go b/server/imghttp/imghttp_suite_test.go
new file mode 100644
index 000000000..7a747db5b
--- /dev/null
+++ b/server/imghttp/imghttp_suite_test.go
@@ -0,0 +1,17 @@
+package imghttp_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestImgHTTP(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "ImgHTTP Suite")
+}
diff --git a/server/jellyfin/dto/blurhash.go b/server/jellyfin/dto/blurhash.go
deleted file mode 100644
index aaf6ff2af..000000000
--- a/server/jellyfin/dto/blurhash.go
+++ /dev/null
@@ -1,36 +0,0 @@
-package dto
-
-import "hash/fnv"
-
-// base83Alphabet is the blurhash spec's base83 encoding alphabet; order is part of the spec.
-const base83Alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz#$%*+,-.:;=?@[]^_{|}~"
-
-// base83 encodes value as a fixed-width, big-endian base83 string of the given length.
-func base83(value, length int) string {
-	b := make([]byte, length)
-	for i := 1; i <= length; i++ {
-		digit := (value / pow83(length-i)) % 83
-		b[i-1] = base83Alphabet[digit]
-	}
-	return string(b)
-}
-
-func pow83(n int) int {
-	result := 1
-	for range n {
-		result *= 83
-	}
-	return result
-}
-
-// blurHash returns a valid 6-char blurhash for a solid color derived from seed. Finamp only needs a
-// well-formed, per-tag-stable value (it uses this as a download de-dup key and blur placeholder), so
-// a solid color unique to the tag satisfies both without decoding cover art.
-func blurHash(seed string) string {
-	h := fnv.New32a()
-	_, _ = h.Write([]byte(seed))
-	sum := h.Sum(nil)
-	r, g, b := int(sum[0]), int(sum[1]), int(sum[2])
-	dc := (r << 16) | (g << 8) | b
-	return "00" + base83(dc, 4)
-}
diff --git a/server/jellyfin/dto/blurhash_test.go b/server/jellyfin/dto/blurhash_test.go
deleted file mode 100644
index a6e36131d..000000000
--- a/server/jellyfin/dto/blurhash_test.go
+++ /dev/null
@@ -1,27 +0,0 @@
-package dto
-
-import (
-	"strings"
-
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("blurHash", func() {
-	It("returns a 6-char valid blurhash starting with the 1x1 component prefix", func() {
-		h := blurHash("x")
-		Expect(h).To(HaveLen(6))
-		Expect(h).To(HavePrefix("00"))
-		for _, c := range h {
-			Expect(strings.ContainsRune(base83Alphabet, c)).To(BeTrue(), "unexpected char %q", c)
-		}
-	})
-
-	It("is deterministic for the same seed", func() {
-		Expect(blurHash("cover-tag-1")).To(Equal(blurHash("cover-tag-1")))
-	})
-
-	It("differs for different seeds", func() {
-		Expect(blurHash("cover-tag-1")).ToNot(Equal(blurHash("cover-tag-2")))
-	})
-})
diff --git a/server/jellyfin/dto/dto.go b/server/jellyfin/dto/dto.go
index 9b2c35c69..5a2a4c2b1 100644
--- a/server/jellyfin/dto/dto.go
+++ b/server/jellyfin/dto/dto.go
@@ -81,12 +81,15 @@ type BaseItemDto struct {
 	// ImageBlurHashes is keyed by image type (e.g. "Primary") then image tag. Finamp uses it as a
 	// de-dup key for image downloads (and a placeholder); absent, it warns the server isn't
 	// calculating blurhashes.
-	ImageBlurHashes   map[string]map[string]string `json:"ImageBlurHashes,omitempty"`
-	BackdropImageTags []string                     `json:"BackdropImageTags"`
-	UserData          *UserItemDataDto             `json:"UserData,omitempty"`
-	MediaSources      []MediaSourceInfo            `json:"MediaSources,omitempty"`
-	Container         string                       `json:"Container,omitempty"`
-	CanDownload       bool                         `json:"CanDownload"`
+	ImageBlurHashes map[string]map[string]string `json:"ImageBlurHashes,omitempty"`
+	// PrimaryImageAspectRatio is width/height of the Primary image, attached only when the request's
+	// Fields asks for it; omitted rather than guessed, since a wrong ratio mis-shapes a placeholder.
+	PrimaryImageAspectRatio *float64          `json:"PrimaryImageAspectRatio,omitempty"`
+	BackdropImageTags       []string          `json:"BackdropImageTags"`
+	UserData                *UserItemDataDto  `json:"UserData,omitempty"`
+	MediaSources            []MediaSourceInfo `json:"MediaSources,omitempty"`
+	Container               string            `json:"Container,omitempty"`
+	CanDownload             bool              `json:"CanDownload"`
 }
 
 // PlaylistUserPermissions is the response shape for GET /Playlists/{id}/Users(/{userId}), which
diff --git a/server/jellyfin/dto/mappers.go b/server/jellyfin/dto/mappers.go
index 444a25cac..352fce11d 100644
--- a/server/jellyfin/dto/mappers.go
+++ b/server/jellyfin/dto/mappers.go
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"time"
 
+	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
 )
@@ -192,31 +193,68 @@ func SongToBaseItem(mf model.MediaFile, fields Fields) BaseItemDto {
 	} else if mf.Genre != "" {
 		item.Genres = []string{mf.Genre}
 	}
-	// Finamp resolves song art via AlbumId + a non-empty AlbumPrimaryImageTag.
-	if mf.AlbumID != "" {
-		item.AlbumPrimaryImageTag = mf.AlbumID
-		item.ImageBlurHashes = map[string]map[string]string{"Primary": {mf.AlbumID: blurHash(mf.AlbumID)}}
+	// Clients prefer ImageTags.Primary over AlbumId, so a track's own cover must win here.
+	if mf.ImageHash != "" && mf.ImageHash != mf.AlbumImage.ImageHash {
+		tag, blurs, ratio := primaryImage(mf.ItemImage, mf.ID, fields)
+		item.ImageTags = map[string]string{"Primary": tag}
+		item.ImageBlurHashes = blurs
+		item.PrimaryImageAspectRatio = ratio
+	} else if embeddedArtPending(mf) {
+		// Nothing enqueues media files: advertising the id is what makes a client ask, and that
+		// request is what extracts the embedded art and queues the track.
+		item.ImageTags = map[string]string{"Primary": mf.ID}
+	} else if mf.AlbumID != "" {
+		if tag, blurs, ratio := primaryImage(mf.AlbumImage, mf.AlbumID, fields); tag != "" {
+			item.AlbumPrimaryImageTag = tag
+			item.ImageBlurHashes = blurs
+			item.PrimaryImageAspectRatio = ratio
+		}
 	}
 	return item
 }
 
+func embeddedArtPending(mf model.MediaFile) bool {
+	return mf.HasCoverArt && conf.Server.EnableMediaFileCoverArt &&
+		mf.ImageHash == "" && !mf.ItemImage.ImageAbsent
+}
+
+// primaryImage never fakes a blurhash: clients key their cover cache on the value, which would
+// pin a stale cover forever.
+func primaryImage(img model.ItemImage, fallback string, fields Fields) (tag string, blurs map[string]map[string]string, ratio *float64) {
+	if img.ImageAbsent {
+		return "", nil, nil
+	}
+	tag = cmp.Or(img.ImageHash, fallback)
+	if img.BlurHash != "" {
+		blurs = map[string]map[string]string{"Primary": {tag: img.BlurHash}}
+	}
+	if fields.Has("PrimaryImageAspectRatio") {
+		ratio = img.AspectRatio()
+	}
+	return tag, blurs, ratio
+}
+
 func AlbumToBaseItem(al model.Album, fields Fields) BaseItemDto {
+	tag, blurs, ratio := primaryImage(al.ItemImage, al.ID, fields)
 	item := BaseItemDto{
-		Name:              al.Name,
-		Id:                EncodeID(al.ID),
-		Type:              "MusicAlbum",
-		IsFolder:          true,
-		ParentId:          EncodeID(al.AlbumArtistID),
-		AlbumArtist:       al.AlbumArtist,
-		Album:             al.Name,
-		ChildCount:        new(al.SongCount),
-		SongCount:         new(al.SongCount),
-		RunTimeTicks:      TicksFromSeconds(al.Duration),
-		DateCreated:       jellyfinDate(&al.CreatedAt),
-		ImageTags:         map[string]string{"Primary": al.ID},
-		ImageBlurHashes:   map[string]map[string]string{"Primary": {al.ID: blurHash(al.ID)}},
-		BackdropImageTags: []string{},
-		UserData:          UserData(al.Annotations, al.ID),
+		Name:                    al.Name,
+		Id:                      EncodeID(al.ID),
+		Type:                    "MusicAlbum",
+		IsFolder:                true,
+		ParentId:                EncodeID(al.AlbumArtistID),
+		AlbumArtist:             al.AlbumArtist,
+		Album:                   al.Name,
+		ChildCount:              new(al.SongCount),
+		SongCount:               new(al.SongCount),
+		RunTimeTicks:            TicksFromSeconds(al.Duration),
+		DateCreated:             jellyfinDate(&al.CreatedAt),
+		ImageBlurHashes:         blurs,
+		PrimaryImageAspectRatio: ratio,
+		BackdropImageTags:       []string{},
+		UserData:                UserData(al.Annotations, al.ID),
+	}
+	if tag != "" {
+		item.ImageTags = map[string]string{"Primary": tag}
 	}
 	if al.AlbumArtistID != "" {
 		item.AlbumArtists = []NameGuidPair{{Name: al.AlbumArtist, Id: EncodeID(al.AlbumArtistID)}}
@@ -246,20 +284,25 @@ func AlbumToBaseItem(al model.Album, fields Fields) BaseItemDto {
 	return item
 }
 
-func ArtistToBaseItem(ar model.Artist) BaseItemDto {
-	return BaseItemDto{
-		Name:              ar.Name,
-		Id:                EncodeID(ar.ID),
-		Type:              "MusicArtist",
-		IsFolder:          true,
-		AlbumCount:        new(ar.AlbumCount),
-		SongCount:         new(ar.SongCount),
-		DateCreated:       jellyfinDate(ar.CreatedAt),
-		ImageTags:         map[string]string{"Primary": ar.ID},
-		ImageBlurHashes:   map[string]map[string]string{"Primary": {ar.ID: blurHash(ar.ID)}},
-		BackdropImageTags: []string{},
-		UserData:          UserData(ar.Annotations, ar.ID),
+func ArtistToBaseItem(ar model.Artist, fields Fields) BaseItemDto {
+	tag, blurs, ratio := primaryImage(ar.ItemImage, ar.ID, fields)
+	item := BaseItemDto{
+		Name:                    ar.Name,
+		Id:                      EncodeID(ar.ID),
+		Type:                    "MusicArtist",
+		IsFolder:                true,
+		AlbumCount:              new(ar.AlbumCount),
+		SongCount:               new(ar.SongCount),
+		DateCreated:             jellyfinDate(ar.CreatedAt),
+		ImageBlurHashes:         blurs,
+		PrimaryImageAspectRatio: ratio,
+		BackdropImageTags:       []string{},
+		UserData:                UserData(ar.Annotations, ar.ID),
 	}
+	if tag != "" {
+		item.ImageTags = map[string]string{"Primary": tag}
+	}
+	return item
 }
 
 func GenreToBaseItem(g model.Genre) BaseItemDto {
@@ -282,26 +325,28 @@ func StudioToBaseItem(t model.Tag) BaseItemDto {
 }
 
 // PlaylistToBaseItem maps a playlist to a Playlist BaseItemDto.
-func PlaylistToBaseItem(p model.Playlist) BaseItemDto {
-	// Finamp caches covers keyed by blurHash, so the tag (and blurhash) must change with the cover.
-	// UpdatedAt versions it (Put bumps it on upload); over-invalidation only costs a refetch.
-	tag := fmt.Sprintf("%s-%x", p.ID, p.UpdatedAt.UnixMilli())
-	return BaseItemDto{
+func PlaylistToBaseItem(p model.Playlist, fields Fields) BaseItemDto {
+	tag, blurs, ratio := primaryImage(p.ItemImage, p.ID, fields)
+	item := BaseItemDto{
 		Name: p.Name,
 		Id:   EncodeID(p.ID),
 		Type: "Playlist",
 		// Synthetic path: Jellify only surfaces playlists whose Path contains "data" (real Jellyfin
 		// stores them under its data folder), so without this its Playlists tab hides them all.
-		Path:              "/data/playlists/" + p.ID,
-		IsFolder:          true,
-		MediaType:         "Audio",
-		ChildCount:        new(p.SongCount),
-		RunTimeTicks:      TicksFromSeconds(p.Duration),
-		ImageTags:         map[string]string{"Primary": tag},
-		ImageBlurHashes:   map[string]map[string]string{"Primary": {tag: blurHash(tag)}},
-		BackdropImageTags: []string{},
-		UserData:          UserData(p.Annotations, p.ID),
+		Path:                    "/data/playlists/" + p.ID,
+		IsFolder:                true,
+		MediaType:               "Audio",
+		ChildCount:              new(p.SongCount),
+		RunTimeTicks:            TicksFromSeconds(p.Duration),
+		ImageBlurHashes:         blurs,
+		PrimaryImageAspectRatio: ratio,
+		BackdropImageTags:       []string{},
+		UserData:                UserData(p.Annotations, p.ID),
 	}
+	if tag != "" {
+		item.ImageTags = map[string]string{"Primary": tag}
+	}
+	return item
 }
 
 // LyricDtoFromLyrics maps one lyric track to Jellyfin's LyricDto. Clients infer synced-vs-plain
diff --git a/server/jellyfin/dto/mappers_test.go b/server/jellyfin/dto/mappers_test.go
index c11f38eaf..a7b381c5c 100644
--- a/server/jellyfin/dto/mappers_test.go
+++ b/server/jellyfin/dto/mappers_test.go
@@ -4,6 +4,8 @@ import (
 	"encoding/json"
 	"time"
 
+	"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"
@@ -34,8 +36,8 @@ var _ = Describe("mappers", func() {
 		Expect(item.UserData.Played).To(BeTrue())
 		Expect(item.UserData.Key).To(Equal(EncodeID("song-1")))
 		Expect(item.UserData.ItemId).To(Equal(EncodeID("song-1")))
-		Expect(item.ImageBlurHashes["Primary"]).To(HaveKey(item.AlbumPrimaryImageTag))
-		Expect(item.ImageBlurHashes["Primary"][item.AlbumPrimaryImageTag]).To(HaveLen(6))
+		Expect(item.AlbumPrimaryImageTag).To(Equal("alb-1"))
+		Expect(item.ImageBlurHashes).To(BeNil())
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
 		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID("1"), Name: "genre 1"}, {Id: EncodeID("2"), Name: "genre 2"}}))
 	})
@@ -254,8 +256,8 @@ var _ = Describe("mappers", func() {
 		Expect(item.ArtistItems).To(Equal(item.AlbumArtists))
 		Expect(*item.ProductionYear).To(Equal(1999))
 		Expect(*item.ChildCount).To(Equal(10))
-		Expect(item.ImageBlurHashes["Primary"]).To(HaveKey(item.ImageTags["Primary"]))
-		Expect(item.ImageBlurHashes["Primary"][item.ImageTags["Primary"]]).To(HaveLen(6))
+		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "alb-1"))
+		Expect(item.ImageBlurHashes).To(BeNil())
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
 		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID("1"), Name: "genre 1"}, {Id: EncodeID("2"), Name: "genre 2"}}))
 	})
@@ -288,9 +290,74 @@ var _ = Describe("mappers", func() {
 		Expect(string(b)).ToNot(ContainSubstring("NormalizationGain"))
 	})
 
+	Describe("PrimaryImageAspectRatio", func() {
+		nonSquare := func() model.Album {
+			al := model.Album{ID: "al1", Name: "Album"}
+			al.ImageHash, al.ImageWidth, al.ImageHeight = "abc", 1200, 800
+			return al
+		}
+
+		It("is omitted unless the request asks for it", func() {
+			Expect(AlbumToBaseItem(nonSquare(), nil).PrimaryImageAspectRatio).To(BeNil())
+			b, err := json.Marshal(AlbumToBaseItem(nonSquare(), nil))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(string(b)).ToNot(ContainSubstring("PrimaryImageAspectRatio"))
+		})
+
+		It("carries the real ratio when asked", func() {
+			item := AlbumToBaseItem(nonSquare(), ParseFields("PrimaryImageAspectRatio"))
+			Expect(*item.PrimaryImageAspectRatio).To(BeNumerically("~", 1.5, 0.0001))
+		})
+
+		It("is omitted when the dimensions are unknown, rather than guessing square", func() {
+			al := model.Album{ID: "al1", Name: "Album"}
+			al.ImageHash = "abc"
+			item := AlbumToBaseItem(al, ParseFields("PrimaryImageAspectRatio"))
+			Expect(item.PrimaryImageAspectRatio).To(BeNil())
+		})
+
+		It("is omitted when the item has no image at all", func() {
+			al := model.Album{ID: "al1", Name: "Album"}
+			al.ImageAbsent = true
+			al.ImageWidth, al.ImageHeight = 1200, 800
+			item := AlbumToBaseItem(al, ParseFields("PrimaryImageAspectRatio"))
+			Expect(item.PrimaryImageAspectRatio).To(BeNil())
+		})
+
+		It("carries the ratio for an artist", func() {
+			ar := model.Artist{ID: "ar1", Name: "Artist"}
+			ar.ImageHash, ar.ImageWidth, ar.ImageHeight = "abc", 1000, 500
+			Expect(*ArtistToBaseItem(ar, ParseFields("PrimaryImageAspectRatio")).PrimaryImageAspectRatio).
+				To(BeNumerically("~", 2.0, 0.0001))
+		})
+
+		It("carries the ratio for a playlist", func() {
+			pl := model.Playlist{ID: "pl1", Name: "Playlist"}
+			pl.ImageHash, pl.ImageWidth, pl.ImageHeight = "abc", 400, 800
+			Expect(*PlaylistToBaseItem(pl, ParseFields("PrimaryImageAspectRatio")).PrimaryImageAspectRatio).
+				To(BeNumerically("~", 0.5, 0.0001))
+		})
+
+		It("carries the ratio for a song with its own art", func() {
+			mf := model.MediaFile{ID: "mf1", Title: "Song"}
+			mf.ImageHash, mf.ImageWidth, mf.ImageHeight = "abc", 300, 600
+			Expect(*SongToBaseItem(mf, ParseFields("PrimaryImageAspectRatio")).PrimaryImageAspectRatio).
+				To(BeNumerically("~", 0.5, 0.0001))
+		})
+
+		// A track without its own art shows the album's, so the ratio has to describe that image.
+		It("uses the album's dimensions for a track falling back to album art", func() {
+			mf := model.MediaFile{ID: "mf1", Title: "Song", AlbumID: "al1"}
+			mf.AlbumImage.ImageHash, mf.AlbumImage.ImageWidth, mf.AlbumImage.ImageHeight = "abc", 1200, 800
+			item := SongToBaseItem(mf, ParseFields("PrimaryImageAspectRatio"))
+			Expect(item.AlbumPrimaryImageTag).To(Equal("abc"))
+			Expect(*item.PrimaryImageAspectRatio).To(BeNumerically("~", 1.5, 0.0001))
+		})
+	})
+
 	It("maps an artist to a MusicArtist folder item", func() {
 		ar := model.Artist{ID: "art-1", Name: "AA", AlbumCount: 2, SongCount: 20}
-		item := ArtistToBaseItem(ar)
+		item := ArtistToBaseItem(ar, nil)
 		Expect(item.Type).To(Equal("MusicArtist"))
 		Expect(item.IsFolder).To(BeTrue())
 		Expect(item.Id).To(Equal(EncodeID("art-1")))
@@ -352,7 +419,7 @@ var _ = Describe("mappers", func() {
 			ID: "pl-1", Name: "Chill", SongCount: 7, Duration: 120,
 			Annotations: model.Annotations{Starred: true, Rating: 4, PlayCount: 2},
 		}
-		item := PlaylistToBaseItem(p)
+		item := PlaylistToBaseItem(p, nil)
 		Expect(item.Type).To(Equal("Playlist"))
 		Expect(item.IsFolder).To(BeTrue())
 		Expect(item.Id).To(Equal(EncodeID("pl-1")))
@@ -363,26 +430,202 @@ var _ = Describe("mappers", func() {
 		Expect(item.UserData.IsFavorite).To(BeTrue())
 		Expect(item.UserData.PlayCount).To(Equal(2))
 		Expect(*item.UserData.Rating).To(Equal(8.0))
-		tag := item.ImageTags["Primary"]
-		Expect(tag).ToNot(BeEmpty())
-		Expect(item.ImageBlurHashes["Primary"]).To(HaveKey(tag))
-		Expect(item.ImageBlurHashes["Primary"][tag]).To(HaveLen(6))
+		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "pl-1"))
+		Expect(item.ImageBlurHashes).To(BeNil())
 	})
 
-	It("changes the playlist image tag and blurhash when the playlist is updated (cover upload)", func() {
-		p := model.Playlist{ID: "pl-1", Name: "Chill", UpdatedAt: time.Date(2026, 7, 1, 0, 0, 0, 0, time.UTC)}
-		before := PlaylistToBaseItem(p)
-		p.UpdatedAt = time.Date(2026, 7, 2, 0, 0, 0, 0, time.UTC)
-		after := PlaylistToBaseItem(p)
+	It("changes the playlist image tag when the cover content changes", func() {
+		p := model.Playlist{ID: "pl-1", Name: "Chill"}
+		p.ImageHash = "1111111111111111"
+		before := PlaylistToBaseItem(p, nil)
+		p.ImageHash = "2222222222222222"
+		after := PlaylistToBaseItem(p, nil)
 
-		// Finamp caches covers keyed by blurHash, so tag and blurhash must change with the cover.
-		Expect(after.ImageTags["Primary"]).ToNot(Equal(before.ImageTags["Primary"]))
-		Expect(after.ImageBlurHashes["Primary"]).ToNot(Equal(before.ImageBlurHashes["Primary"]))
+		Expect(before.ImageTags["Primary"]).To(Equal("1111111111111111"))
+		Expect(after.ImageTags["Primary"]).To(Equal("2222222222222222"))
 	})
 
-	It("keeps the playlist image tag stable when nothing changed", func() {
+	It("keeps the playlist image tag stable across a metadata-only edit", func() {
 		p := model.Playlist{ID: "pl-1", UpdatedAt: time.Date(2026, 7, 1, 0, 0, 0, 0, time.UTC)}
-		Expect(PlaylistToBaseItem(p).ImageTags).To(Equal(PlaylistToBaseItem(p).ImageTags))
+		p.ImageHash = "1111111111111111"
+		before := PlaylistToBaseItem(p, nil)
+		p.UpdatedAt = time.Date(2026, 7, 2, 0, 0, 0, 0, time.UTC)
+		after := PlaylistToBaseItem(p, nil)
+
+		Expect(after.ImageTags["Primary"]).To(Equal(before.ImageTags["Primary"]))
+	})
+
+	// Nothing enqueues media files, so a track's own art only resolves when a client requests it;
+	// advertising just the album image would leave that cover unreachable.
+	Describe("unresolved embedded art", func() {
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.EnableMediaFileCoverArt = true
+		})
+
+		It("advertises the track id so the client triggers the read-through", func() {
+			mf := model.MediaFile{ID: "mf-1", AlbumID: "alb-1", HasCoverArt: true}
+			mf.AlbumImage.ImageHash = "0123456789abcdef"
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "mf-1"))
+			Expect(item.ImageBlurHashes).To(BeNil(), "no resolved image means no blurhash to send")
+			Expect(item.AlbumPrimaryImageTag).To(BeEmpty())
+		})
+
+		It("falls back to the album when the track has no art of its own", func() {
+			mf := model.MediaFile{ID: "mf-2", AlbumID: "alb-1", HasCoverArt: false}
+			mf.AlbumImage.ImageHash = "0123456789abcdef"
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.ImageTags).To(BeEmpty())
+			Expect(item.AlbumPrimaryImageTag).To(Equal("0123456789abcdef"))
+		})
+
+		It("falls back to the album once the track's art is known absent", func() {
+			mf := model.MediaFile{ID: "mf-3", AlbumID: "alb-1", HasCoverArt: true}
+			mf.ItemImage.ImageAbsent = true
+			mf.AlbumImage.ImageHash = "0123456789abcdef"
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.ImageTags).To(BeEmpty())
+			Expect(item.AlbumPrimaryImageTag).To(Equal("0123456789abcdef"))
+		})
+
+		It("falls back to the album when per-track art is disabled", func() {
+			conf.Server.EnableMediaFileCoverArt = false
+			mf := model.MediaFile{ID: "mf-4", AlbumID: "alb-1", HasCoverArt: true}
+			mf.AlbumImage.ImageHash = "0123456789abcdef"
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.ImageTags).To(BeEmpty())
+			Expect(item.AlbumPrimaryImageTag).To(Equal("0123456789abcdef"))
+		})
+	})
+
+	Describe("primary image tags", func() {
+		It("uses the content hash as the tag and emits the real blurhash", func() {
+			al := model.Album{ID: "alb-1", Name: "Album"}
+			al.ImageHash = "0123456789abcdef"
+			al.BlurHash = "LEHV6nWB2yk8"
+
+			item := AlbumToBaseItem(al, nil)
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "0123456789abcdef"))
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("0123456789abcdef", "LEHV6nWB2yk8"))
+		})
+
+		It("omits the blurhash entirely when none was computed", func() {
+			al := model.Album{ID: "alb-2", Name: "Album"}
+			al.ImageHash = "0123456789abcdef"
+
+			item := AlbumToBaseItem(al, nil)
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "0123456789abcdef"))
+			Expect(item.ImageBlurHashes).To(BeNil(), "a synthesized blurhash pins stale covers in Finamp")
+		})
+
+		It("omits tags for known-absent artwork", func() {
+			al := model.Album{ID: "alb-3", Name: "Album"}
+			al.ImageAbsent = true
+
+			item := AlbumToBaseItem(al, nil)
+			Expect(item.ImageTags).To(BeEmpty())
+			Expect(item.ImageBlurHashes).To(BeNil())
+		})
+
+		It("falls back to the entity id while artwork is still unresolved", func() {
+			item := AlbumToBaseItem(model.Album{ID: "alb-4", Name: "Album"}, nil)
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "alb-4"))
+			Expect(item.ImageBlurHashes).To(BeNil())
+		})
+
+		It("versions an artist's tag by content hash", func() {
+			ar := model.Artist{ID: "art-1", Name: "Artist"}
+			ar.ImageHash = "fedcba9876543210"
+			ar.BlurHash = "L6PZfSi_.AyE"
+
+			item := ArtistToBaseItem(ar, nil)
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "fedcba9876543210"))
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("fedcba9876543210", "L6PZfSi_.AyE"))
+		})
+	})
+
+	Describe("song and playlist image tags", func() {
+		It("versions a song's album tag by the album's content hash", func() {
+			mf := model.MediaFile{ID: "song-1", Title: "Song", AlbumID: "alb-1"}
+			mf.AlbumImage.ImageHash = "0123456789abcdef"
+			mf.AlbumImage.BlurHash = "LEHV6nWB2yk8"
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.AlbumPrimaryImageTag).To(Equal("0123456789abcdef"))
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("0123456789abcdef", "LEHV6nWB2yk8"))
+		})
+
+		It("never synthesizes a song blurhash when the album has none", func() {
+			mf := model.MediaFile{ID: "song-2", Title: "Song", AlbumID: "alb-2"}
+			mf.AlbumImage.ImageHash = "0123456789abcdef"
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.AlbumPrimaryImageTag).To(Equal("0123456789abcdef"))
+			Expect(item.ImageBlurHashes).To(BeNil())
+		})
+
+		It("omits a song's album tag when the album art is known absent", func() {
+			mf := model.MediaFile{ID: "song-3", Title: "Song", AlbumID: "alb-3"}
+			mf.AlbumImage.ImageAbsent = true
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.AlbumPrimaryImageTag).To(BeEmpty())
+			Expect(item.ImageBlurHashes).To(BeNil())
+		})
+
+		It("versions a playlist tag by content hash instead of UpdatedAt", func() {
+			pl := model.Playlist{ID: "pl-1", Name: "Playlist"}
+			pl.ImageHash = "abcdef0123456789"
+
+			item := PlaylistToBaseItem(pl, nil)
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "abcdef0123456789"))
+		})
+	})
+
+	Describe("per-song artwork", func() {
+		It("emits the track's own Primary tag when it has distinct art", func() {
+			mf := model.MediaFile{ID: "song-own", Title: "Song", AlbumID: "alb-1"}
+			mf.ImageHash = "aaaaaaaaaaaaaaaa"
+			mf.BlurHash = "LTRACKblur"
+			mf.AlbumImage.ImageHash = "bbbbbbbbbbbbbbbb"
+			mf.AlbumImage.BlurHash = "LALBUMblur"
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "aaaaaaaaaaaaaaaa"))
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveLen(1),
+				"exactly one Primary entry: Go sorts map keys, so a second entry could pair the wrong blurhash with imageId")
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("aaaaaaaaaaaaaaaa", "LTRACKblur"))
+		})
+
+		It("falls back to the album tag when the track has no distinct art", func() {
+			mf := model.MediaFile{ID: "song-inherit", Title: "Song", AlbumID: "alb-1"}
+			mf.ImageHash = "bbbbbbbbbbbbbbbb"
+			mf.BlurHash = "LALBUMblur"
+			mf.AlbumImage.ImageHash = "bbbbbbbbbbbbbbbb"
+			mf.AlbumImage.BlurHash = "LALBUMblur"
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.ImageTags).To(BeEmpty(), "an inherited cover is the album's image, not the track's")
+			Expect(item.AlbumPrimaryImageTag).To(Equal("bbbbbbbbbbbbbbbb"))
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveLen(1))
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("bbbbbbbbbbbbbbbb", "LALBUMblur"))
+		})
+
+		It("omits the track tag when its own art is known absent", func() {
+			mf := model.MediaFile{ID: "song-absent", Title: "Song", AlbumID: "alb-1"}
+			mf.ImageAbsent = true
+			mf.AlbumImage.ImageAbsent = true
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.ImageTags).To(BeEmpty())
+			Expect(item.AlbumPrimaryImageTag).To(BeEmpty())
+			Expect(item.ImageBlurHashes).To(BeNil())
+		})
 	})
 })
 
diff --git a/server/jellyfin/e2e/e2e_suite_test.go b/server/jellyfin/e2e/e2e_suite_test.go
index 31d98d1d9..ca1308e9e 100644
--- a/server/jellyfin/e2e/e2e_suite_test.go
+++ b/server/jellyfin/e2e/e2e_suite_test.go
@@ -33,7 +33,6 @@ import (
 	"strings"
 	"testing"
 	"testing/fstest"
-	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -327,7 +326,7 @@ func setupTestDB() {
 		decider,
 		core.NewPlayers(ds),
 		scrobbler.NewPlayTracker(ds, events.NoopBroker(), nil),
-		playlists.NewPlaylists(ds, core.NewImageUploadService()),
+		playlists.NewPlaylists(ds, artwork.NewUploader(ds)),
 		providerFake,
 		sonicSvc,
 		lyrics.NewLyrics(ds, nil),
@@ -406,18 +405,18 @@ type spyArtwork struct {
 	data    []byte
 }
 
-func (s *spyArtwork) Get(context.Context, model.ArtworkID, int, bool) (io.ReadCloser, time.Time, error) {
-	return nil, time.Time{}, model.ErrNotFound
+func (s *spyArtwork) Get(context.Context, model.ArtworkID, int, bool) (*artwork.Image, error) {
+	return nil, model.ErrNotFound
 }
 
-func (s *spyArtwork) GetOrPlaceholder(c context.Context, id string, _ int, _ bool) (io.ReadCloser, time.Time, error) {
+func (s *spyArtwork) GetOrPlaceholder(c context.Context, id string, _ int, _ bool) (*artwork.Image, error) {
 	s.lastID = id
 	s.lastCtx = c
 	d := s.data
 	if d == nil {
 		d = []byte("IMG")
 	}
-	return io.NopCloser(bytes.NewReader(d)), time.Time{}, nil
+	return &artwork.Image{ReadCloser: io.NopCloser(bytes.NewReader(d))}, nil
 }
 
 var _ artwork.Artwork = &spyArtwork{}
diff --git a/server/jellyfin/e2e/playlists_test.go b/server/jellyfin/e2e/playlists_test.go
index d2ff49db9..08d6f4f6f 100644
--- a/server/jellyfin/e2e/playlists_test.go
+++ b/server/jellyfin/e2e/playlists_test.go
@@ -6,8 +6,8 @@ import (
 	jpeglib "image/jpeg"
 	"net/http"
 	"os"
-	"time"
 
+	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -215,26 +215,26 @@ var _ = Describe("Playlists", func() {
 				To(Equal(http.StatusNotImplemented))
 		})
 
-		// Guards the whole chain: SetImage must go through a full Put (which bumps UpdatedAt), and the
-		// tag must be versioned by it, or clients keep their blurhash-keyed cover cache forever.
-		It("rotates the playlist's image tag and blurhash after a cover upload", func() {
+		// An upload must clear the resolved artwork state, or clients keep serving the stale cover
+		// from their tag-keyed cache until the next scan.
+		It("clears the resolved image tag after a cover upload", func() {
 			plID := createPlaylist("Cover Tag", nil)
+			Expect(ds.Artwork(ctx).PutItemArtwork(&model.ItemArtwork{
+				ItemKind: model.KindPlaylistArtwork.Prefix(), ItemID: plID, Hash: "1111111111111111",
+			})).To(Succeed())
+
 			imageTag := func() string {
 				q := queryResult(get("/Items?ids=" + enc(plID)))
 				Expect(q.Items).To(HaveLen(1))
 				return q.Items[0].ImageTags["Primary"]
 			}
-			before := imageTag()
-			Expect(before).ToNot(BeEmpty())
+			Expect(imageTag()).To(Equal("1111111111111111"))
 
-			time.Sleep(2 * time.Millisecond) // UpdatedAt has millisecond resolution in the tag
 			Expect(upload(adminUser, "/Items/"+enc(plID)+"/Images/Primary", "image/jpeg", jpeg).Code).
 				To(Equal(http.StatusNoContent))
 
-			after := imageTag()
-			Expect(after).ToNot(Equal(before))
-			q := queryResult(get("/Items?ids=" + enc(plID)))
-			Expect(q.Items[0].ImageBlurHashes["Primary"]).To(HaveKey(after))
+			// The upload re-queues resolution instead of resolving inline, so the tag goes bare.
+			Expect(imageTag()).ToNot(Equal("1111111111111111"))
 		})
 	})
 
diff --git a/server/jellyfin/images.go b/server/jellyfin/images.go
index 0ec34f491..b844e7c74 100644
--- a/server/jellyfin/images.go
+++ b/server/jellyfin/images.go
@@ -16,10 +16,11 @@ import (
 	"github.com/dustin/go-humanize"
 	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/server/imghttp"
 	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	_ "golang.org/x/image/webp"
 )
@@ -32,7 +33,7 @@ func (api *Router) getItemImage(w http.ResponseWriter, r *http.Request) {
 	size, _ := strconv.Atoi(r.URL.Query().Get("maxwidth"))
 
 	artID := api.resolveArtworkID(ctx, itemId)
-	reader, _, err := api.artwork.GetOrPlaceholder(ctx, artID, size, false)
+	img, err := api.artwork.GetOrPlaceholder(ctx, artID, size, false)
 	switch {
 	case errors.Is(err, context.Canceled):
 		return
@@ -41,9 +42,27 @@ func (api *Router) getItemImage(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Not Found", http.StatusNotFound)
 		return
 	}
-	defer reader.Close()
+	defer img.Close()
+	if imghttp.WriteImageHeaders(w, r, img, hashFromTag(r)) {
+		return
+	}
 	// Leave Content-Type unset so net/http sniffs it (covers may be PNG/WebP/JPEG).
-	_, _ = io.Copy(w, reader)
+	_, _ = io.Copy(w, img)
+}
+
+// hashFromTag returns the ?tag query param when it is exactly a 16-char lowercase-hex content
+// hash (what Finamp/Jellyfin clients append), so a matching request can be served immutable.
+func hashFromTag(r *http.Request) string {
+	tag := r.URL.Query().Get("tag")
+	if len(tag) != 16 {
+		return ""
+	}
+	for _, c := range tag {
+		if !(c >= '0' && c <= '9' || c >= 'a' && c <= 'f') {
+			return ""
+		}
+	}
+	return tag
 }
 
 // resolveArtworkID maps a Jellyfin item id to a Navidrome ArtworkID, probing
@@ -79,7 +98,7 @@ func (api *Router) postItemImage(w http.ResponseWriter, r *http.Request) {
 	}
 	// The limit caps the decoded image (native endpoint semantics); Jellyfin clients base64-encode
 	// the wire body (4/3 bigger), so the read cap allows for inflation.
-	limit := core.MaxImageUploadSize()
+	limit := artwork.MaxImageUploadSize()
 	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, limit*4/3+4))
 	if err != nil {
 		log.Warn(ctx, "Jellyfin API: cover upload rejected: body exceeds MaxImageUploadSize",
diff --git a/server/jellyfin/images_test.go b/server/jellyfin/images_test.go
index e435b99fd..bdd47e956 100644
--- a/server/jellyfin/images_test.go
+++ b/server/jellyfin/images_test.go
@@ -33,16 +33,21 @@ type fakeArtwork struct {
 	recvId  string
 	recvCtx context.Context
 	data    []byte
+	hash    string
 }
 
-func (f *fakeArtwork) GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (io.ReadCloser, time.Time, error) {
+func (f *fakeArtwork) GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (*artwork.Image, error) {
 	f.recvId = id
 	f.recvCtx = ctx
 	data := f.data
 	if data == nil {
 		data = []byte("IMG")
 	}
-	return io.NopCloser(bytes.NewReader(data)), time.Now(), nil
+	return &artwork.Image{
+		ReadCloser:  io.NopCloser(bytes.NewReader(data)),
+		Hash:        f.hash,
+		LastUpdated: time.Now(),
+	}, nil
 }
 
 func newImageRequest(itemId string) (*httptest.ResponseRecorder, *http.Request) {
@@ -70,6 +75,19 @@ var _ = Describe("Images", func() {
 		Expect(fa.recvId).To(ContainSubstring("a1"))
 	})
 
+	// resolveArtworkID probes the entity tables, so a deleted item yields no artwork id at all.
+	It("asks for no artwork once the item is deleted, rather than its lingering state", func() {
+		ds := &tests.MockDataStore{} // no albums/artists/tracks/playlists at all
+		fa := &fakeArtwork{}
+		api := &Router{ds: ds, artwork: fa}
+
+		w, r := newImageRequest(dto.EncodeID("deleted-item"))
+		api.getItemImage(w, r)
+
+		Expect(fa.recvId).To(BeEmpty(), "an empty artwork id can only yield a placeholder")
+		Expect(w.Body.String()).ToNot(ContainSubstring("deleted-item"))
+	})
+
 	It("sniffs the Content-Type instead of hardcoding it", func() {
 		ds := &tests.MockDataStore{}
 		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
@@ -115,6 +133,38 @@ var _ = Describe("Images", func() {
 		Expect(ok).To(BeTrue())
 		Expect(u.IsAdmin).To(BeTrue())
 	})
+
+	It("serves immutable when the tag param asserts the current hash", func() {
+		const hash = "0123456789abcdef"
+		ds := &tests.MockDataStore{}
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+		fa := &fakeArtwork{hash: hash}
+		api := &Router{ds: ds, artwork: fa}
+
+		w, r := newImageRequest(dto.EncodeID("a1"))
+		q := r.URL.Query()
+		q.Set("tag", hash)
+		r.URL.RawQuery = q.Encode()
+		api.getItemImage(w, r)
+
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Header().Get("Cache-Control")).To(Equal("public, max-age=31536000, immutable"))
+		Expect(w.Header().Get("ETag")).To(Equal(`"` + hash + `"`))
+	})
+
+	It("revalidates via no-cache when no tag is provided", func() {
+		const hash = "0123456789abcdef"
+		ds := &tests.MockDataStore{}
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+		fa := &fakeArtwork{hash: hash}
+		api := &Router{ds: ds, artwork: fa}
+
+		w, r := newImageRequest(dto.EncodeID("a1"))
+		api.getItemImage(w, r)
+
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Header().Get("Cache-Control")).To(Equal("public, no-cache"))
+	})
 })
 
 // Real image fixtures: postItemImage validates uploads by decoding them.
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index 7cf2a17ba..631530b6d 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -588,7 +588,7 @@ func (api *Router) listSongs(ctx context.Context, opts model.QueryOptions, q ite
 	// A full-library request (Finamp's sync, with MediaSources) is tens of thousands of fat rows.
 	total, _ := repo.CountAll(model.QueryOptions{Filters: opts.Filters})
 	open := streamCursor(func() (func(func(model.MediaFile, error) bool), error) {
-		return repo.GetCursor(opts)
+		return repo.GetCursorWithArtwork(opts)
 	}, toItem)
 	return streamed(open, int(total), opts.Offset), nil
 }
@@ -598,6 +598,7 @@ func (api *Router) listSongs(ctx context.Context, opts model.QueryOptions, q ite
 // genreIds isn't applied to search — a name lookup, like role (see below).
 func (api *Router) listArtists(ctx context.Context, opts model.QueryOptions, q itemsQuery, role model.Role) (itemsResult, error) {
 	repo := api.ds.Artist(ctx)
+	toItem := func(ar model.Artist) dto.BaseItemDto { return dto.ArtistToBaseItem(ar, q.fields) }
 
 	// Artist Search does its own library scoping: it consumes a sole Eq{"library_id": ...} filter as a
 	// search scope (artists have no library_id column). A compound or join-based filter
@@ -613,7 +614,7 @@ func (api *Router) listArtists(ctx context.Context, opts model.QueryOptions, q i
 		if err != nil {
 			return itemsResult{}, err
 		}
-		return materialized(result(slice.Map(artists, dto.ArtistToBaseItem), total, opts.Offset)), nil
+		return materialized(result(slice.Map(artists, toItem), total, opts.Offset)), nil
 	}
 
 	if q.favOnly {
@@ -629,7 +630,7 @@ func (api *Router) listArtists(ctx context.Context, opts model.QueryOptions, q i
 	total, _ := repo.CountAll(model.QueryOptions{Filters: opts.Filters})
 	open := streamCursor(func() (func(func(model.Artist, error) bool), error) {
 		return repo.GetCursor(opts)
-	}, dto.ArtistToBaseItem)
+	}, toItem)
 	return streamed(open, int(total), opts.Offset), nil
 }
 
@@ -663,7 +664,7 @@ func (api *Router) listPlaylists(ctx context.Context, opts model.QueryOptions, q
 	}
 	open := streamCursor(func() (func(func(model.Playlist, error) bool), error) {
 		return repo.GetCursor(opts)
-	}, dto.PlaylistToBaseItem)
+	}, func(p model.Playlist) dto.BaseItemDto { return dto.PlaylistToBaseItem(p, q.fields) })
 	return streamed(open, int(total), opts.Offset), nil
 }
 
@@ -698,7 +699,7 @@ func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fi
 	if ar, err := api.ds.Artist(ctx).Get(id); err == nil {
 		// TODO: an artist spans multiple libraries (library_artist), so there's no single
 		// LibraryID to gate here; artist access relies on list-time scoping and persistence.
-		return dto.ArtistToBaseItem(*ar), true
+		return dto.ArtistToBaseItem(*ar, fields), true
 	}
 	if mf, err := api.ds.MediaFile(ctx).Get(id); err == nil {
 		if !u.HasLibraryAccess(mf.LibraryID) {
@@ -708,7 +709,7 @@ func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fi
 	}
 	// api.playlists.Get enforces ownership/visibility, so a non-owned or missing id falls through.
 	if pl, err := api.playlists.Get(ctx, id); err == nil {
-		return dto.PlaylistToBaseItem(*pl), true
+		return dto.PlaylistToBaseItem(*pl, fields), true
 	}
 	return dto.BaseItemDto{}, false
 }
diff --git a/server/jellyfin/similar.go b/server/jellyfin/similar.go
index 661fb95cc..2698073bf 100644
--- a/server/jellyfin/similar.go
+++ b/server/jellyfin/similar.go
@@ -138,7 +138,7 @@ func (api *Router) similarArtists(ctx context.Context, id string, limit int) dto
 		return result(nil, 0, 0)
 	}
 	present := slice.Filter(artist.SimilarArtists, func(a model.Artist) bool { return a.ID != "" })
-	items := slice.Map(present, dto.ArtistToBaseItem)
+	items := slice.Map(present, func(a model.Artist) dto.BaseItemDto { return dto.ArtistToBaseItem(a, nil) })
 	return result(items, len(items), 0)
 }
 
diff --git a/server/nativeapi/artists.go b/server/nativeapi/artists.go
index daa918d00..193f88eda 100644
--- a/server/nativeapi/artists.go
+++ b/server/nativeapi/artists.go
@@ -46,7 +46,11 @@ func (api *Router) uploadArtistImage() http.HandlerFunc {
 		}
 		ar.UploadedImage = filename
 		ar.UpdatedAt = new(time.Now())
-		return api.ds.Artist(ctx).Put(ar, "uploaded_image", "updated_at")
+		if err := api.ds.Artist(ctx).Put(ar, "uploaded_image", "updated_at"); err != nil {
+			return err
+		}
+		api.imgUpload.EnqueueArtwork(ctx, consts.EntityArtist, ar.ID)
+		return nil
 	})
 }
 
@@ -65,6 +69,10 @@ func (api *Router) deleteArtistImage() http.HandlerFunc {
 		}
 		ar.UploadedImage = ""
 		ar.UpdatedAt = new(time.Now())
-		return api.ds.Artist(ctx).Put(ar, "uploaded_image", "updated_at")
+		if err := api.ds.Artist(ctx).Put(ar, "uploaded_image", "updated_at"); err != nil {
+			return err
+		}
+		api.imgUpload.EnqueueArtwork(ctx, consts.EntityArtist, ar.ID)
+		return nil
 	})
 }
diff --git a/server/nativeapi/artwork.go b/server/nativeapi/artwork.go
new file mode 100644
index 000000000..3583c2db7
--- /dev/null
+++ b/server/nativeapi/artwork.go
@@ -0,0 +1,42 @@
+package nativeapi
+
+import (
+	"net/http"
+	"slices"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+var refreshableArtworkKinds = []model.Kind{
+	model.KindAlbumArtwork,
+	model.KindArtistArtwork,
+	model.KindPlaylistArtwork,
+	model.KindRadioArtwork,
+	model.KindMediaFileArtwork,
+}
+
+func (api *Router) addArtworkRoute(r chi.Router) {
+	r.Post("/artwork/{kind}/{id}/refresh", api.refreshArtwork())
+}
+
+// State is deliberately cleared so a wrong pick disappears immediately (placeholder until re-resolved).
+func (api *Router) refreshArtwork() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		ctx := r.Context()
+		kind, _ := model.ParseKind(chi.URLParam(r, "kind"))
+		id := chi.URLParam(r, "id")
+		if !slices.Contains(refreshableArtworkKinds, kind) {
+			http.Error(w, "invalid artwork kind", http.StatusBadRequest)
+			return
+		}
+		if err := artwork.Refresh(ctx, api.ds, kind, id); err != nil {
+			log.Error(ctx, "Error refreshing artwork", "kind", kind, "id", id, err)
+			http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
+			return
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}
+}
diff --git a/server/nativeapi/artwork_test.go b/server/nativeapi/artwork_test.go
new file mode 100644
index 000000000..b26a94e6a
--- /dev/null
+++ b/server/nativeapi/artwork_test.go
@@ -0,0 +1,95 @@
+package nativeapi
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Artwork API", func() {
+	var ds *tests.MockDataStore
+	var artRepo *tests.MockArtworkRepo
+	var queueRepo *tests.MockArtworkQueueRepo
+	var router http.Handler
+	var adminToken, userToken string
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.EnableSharing = false
+		artRepo = tests.CreateMockArtworkRepo()
+		queueRepo = tests.CreateMockArtworkQueueRepo()
+		ds = &tests.MockDataStore{MockedArtwork: artRepo, MockedArtworkQueue: queueRepo}
+		auth.Init(ds)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil)
+		router = server.JWTVerifier(nativeRouter)
+
+		adminUser := model.User{ID: "admin-1", UserName: "admin", IsAdmin: true, NewPassword: "adminpass"}
+		regularUser := model.User{ID: "user-1", UserName: "regular", IsAdmin: false, NewPassword: "userpass"}
+		Expect(ds.User(context.TODO()).Put(&adminUser)).To(Succeed())
+		Expect(ds.User(context.TODO()).Put(&regularUser)).To(Succeed())
+
+		var err error
+		adminToken, err = auth.CreateToken(&adminUser)
+		Expect(err).ToNot(HaveOccurred())
+		userToken, err = auth.CreateToken(&regularUser)
+		Expect(err).ToNot(HaveOccurred())
+	})
+
+	Describe("POST /api/artwork/{kind}/{id}/refresh", func() {
+		It("clears state and enqueues a Bump for admins", func() {
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al-1", Hash: "oldhash", Source: "external",
+			})).To(Succeed())
+
+			req := createAuthenticatedRequest("POST", "/artwork/al/al-1/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusNoContent))
+
+			_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+
+			queued, err := queueRepo.DequeueBatch(1000)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(queued).To(ContainElement(SatisfyAll(
+				HaveField("ItemKind", "al"),
+				HaveField("ItemID", "al-1"),
+				HaveField("Priority", model.ArtworkPriorityBump),
+			)))
+		})
+
+		It("returns 400 for an invalid kind", func() {
+			req := createAuthenticatedRequest("POST", "/artwork/xx/id-1/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusBadRequest))
+		})
+
+		It("denies access to regular users", func() {
+			req := createAuthenticatedRequest("POST", "/artwork/al/al-1/refresh", nil, userToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusForbidden))
+		})
+
+		It("denies access without authentication", func() {
+			req := createUnauthenticatedRequest("POST", "/artwork/al/al-1/refresh", nil)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusUnauthorized))
+		})
+	})
+})
diff --git a/server/nativeapi/image_upload.go b/server/nativeapi/image_upload.go
index 077eac35e..c4ff62e42 100644
--- a/server/nativeapi/image_upload.go
+++ b/server/nativeapi/image_upload.go
@@ -14,7 +14,7 @@ import (
 	"strings"
 
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -31,7 +31,7 @@ func checkImageUploadPermission(w http.ResponseWriter, r *http.Request) bool {
 }
 
 func handleImageUpload(saveFn func(ctx context.Context, reader io.Reader, ext string) error) http.HandlerFunc {
-	maxImageSize := core.MaxImageUploadSize()
+	maxImageSize := artwork.MaxImageUploadSize()
 	return func(w http.ResponseWriter, r *http.Request) {
 		ctx := r.Context()
 		if !checkImageUploadPermission(w, r) {
diff --git a/server/nativeapi/native_api.go b/server/nativeapi/native_api.go
index 5a7023eb6..f97bd26b2 100644
--- a/server/nativeapi/native_api.go
+++ b/server/nativeapi/native_api.go
@@ -13,6 +13,7 @@ import (
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/metrics"
 	playlistsvc "github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/log"
@@ -44,10 +45,10 @@ type Router struct {
 	users         core.User
 	maintenance   core.Maintenance
 	pluginManager PluginManager
-	imgUpload     core.ImageUploadService
+	imgUpload     artwork.Uploader
 }
 
-func New(ds model.DataStore, share core.Share, playlists playlistsvc.Playlists, insights metrics.Insights, libraryService core.Library, userService core.User, maintenance core.Maintenance, pluginManager PluginManager, imgUpload core.ImageUploadService) *Router {
+func New(ds model.DataStore, share core.Share, playlists playlistsvc.Playlists, insights metrics.Insights, libraryService core.Library, userService core.User, maintenance core.Maintenance, pluginManager PluginManager, imgUpload artwork.Uploader) *Router {
 	r := &Router{ds: ds, share: share, playlists: playlists, insights: insights, libs: libraryService, users: userService, maintenance: maintenance, pluginManager: pluginManager, imgUpload: imgUpload}
 	r.Handler = r.routes()
 	return r
@@ -91,6 +92,7 @@ func (api *Router) routes() http.Handler {
 			api.addConfigRoute(r)
 			api.addUserLibraryRoute(r)
 			api.addPluginRoute(r)
+			api.addArtworkRoute(r)
 			api.RX(r, "/library", api.libs.NewRepository, true)
 		})
 	})
diff --git a/server/nativeapi/radios.go b/server/nativeapi/radios.go
index 701c6c926..3e88af287 100644
--- a/server/nativeapi/radios.go
+++ b/server/nativeapi/radios.go
@@ -47,7 +47,11 @@ func (api *Router) uploadRadioImage() http.HandlerFunc {
 			return err
 		}
 		radio.UploadedImage = filename
-		return api.ds.Radio(ctx).Put(radio, "UploadedImage")
+		if err := api.ds.Radio(ctx).Put(radio, "UploadedImage"); err != nil {
+			return err
+		}
+		api.imgUpload.EnqueueArtwork(ctx, consts.EntityRadio, radio.ID)
+		return nil
 	})
 }
 
@@ -65,6 +69,10 @@ func (api *Router) deleteRadioImage() http.HandlerFunc {
 			return err
 		}
 		radio.UploadedImage = ""
-		return api.ds.Radio(ctx).Put(radio, "UploadedImage")
+		if err := api.ds.Radio(ctx).Put(radio, "UploadedImage"); err != nil {
+			return err
+		}
+		api.imgUpload.EnqueueArtwork(ctx, consts.EntityRadio, radio.ID)
+		return nil
 	})
 }
diff --git a/server/public/handle_images.go b/server/public/handle_images.go
index 633665e0f..6416190bd 100644
--- a/server/public/handle_images.go
+++ b/server/public/handle_images.go
@@ -11,6 +11,8 @@ import (
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/server/imghttp"
 	"github.com/navidrome/navidrome/utils/req"
 )
 
@@ -37,10 +39,13 @@ func (pub *Router) handleImages(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "invalid request", http.StatusBadRequest)
 		return
 	}
+	// The token is the authorization, so the entity check must ask "is it still there", not
+	// "may this user see it" -- the latter would hide a shared private playlist.
+	ctx = request.WithUser(ctx, model.User{IsAdmin: true})
 	size := p.IntOr("size", 0)
 	square := p.BoolOr("square", false)
 
-	imgReader, lastUpdate, err := pub.artwork.Get(ctx, artId, size, square)
+	img, err := pub.artwork.Get(ctx, artId, size, square)
 	switch {
 	case errors.Is(err, context.Canceled):
 		return
@@ -58,10 +63,11 @@ func (pub *Router) handleImages(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	defer imgReader.Close()
-	w.Header().Set("Cache-Control", "public, max-age=315360000")
-	w.Header().Set("Last-Modified", lastUpdate.Format(http.TimeFormat))
-	cnt, err := io.Copy(w, imgReader)
+	defer img.Close()
+	if imghttp.WriteImageHeaders(w, r, img, artId.Hash) {
+		return
+	}
+	cnt, err := io.Copy(w, img)
 	if err != nil {
 		log.Warn(ctx, "Error sending image", "count", cnt, err)
 	}
diff --git a/server/public/handle_images_test.go b/server/public/handle_images_test.go
index 669f879a6..d77b6f427 100644
--- a/server/public/handle_images_test.go
+++ b/server/public/handle_images_test.go
@@ -1,8 +1,18 @@
 package public
 
 import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+
 	"github.com/go-chi/jwtauth/v5"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -23,3 +33,56 @@ var _ = Describe("decodeArtworkID", func() {
 		Expect(err).To(HaveOccurred())
 	})
 })
+
+type fakeArtwork struct {
+	artwork.Artwork
+	img *artwork.Image
+	err error
+}
+
+func (f *fakeArtwork) Get(context.Context, model.ArtworkID, int, bool) (*artwork.Image, error) {
+	return f.img, f.err
+}
+
+var _ = Describe("handleImages", func() {
+	var w *httptest.ResponseRecorder
+
+	newImageRequest := func(claimID string) *http.Request {
+		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("super secret"), nil)
+		token, _ := auth.CreatePublicToken(auth.Claims{ID: claimID})
+		return httptest.NewRequest("GET", "/img?:id="+url.QueryEscape(token), nil)
+	}
+
+	// The handler re-checks that the entity behind the token still exists, so "1" must be live.
+	var ds *tests.MockDataStore
+
+	BeforeEach(func() {
+		w = httptest.NewRecorder()
+		albumRepo := tests.CreateMockAlbumRepo()
+		albumRepo.SetData(model.Albums{{ID: "1"}})
+		ds = &tests.MockDataStore{MockedAlbum: albumRepo}
+	})
+
+	It("returns 404 when the artwork is unavailable", func() {
+		pub := &Router{ds: ds, artwork: &fakeArtwork{err: artwork.ErrUnavailable}}
+		pub.handleImages(w, newImageRequest("al-1"))
+		Expect(w.Code).To(Equal(http.StatusNotFound))
+	})
+
+	It("returns 404 when the artwork is not found", func() {
+		pub := &Router{ds: ds, artwork: &fakeArtwork{err: model.ErrNotFound}}
+		pub.handleImages(w, newImageRequest("al-1"))
+		Expect(w.Code).To(Equal(http.StatusNotFound))
+	})
+
+	It("serves the image immutable when the token asserts the current hash", func() {
+		const hash = "0123456789abcdef"
+		img := &artwork.Image{ReadCloser: io.NopCloser(bytes.NewReader([]byte("IMG"))), Hash: hash}
+		pub := &Router{ds: ds, artwork: &fakeArtwork{img: img}}
+		pub.handleImages(w, newImageRequest("al-1_"+hash))
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Header().Get("Cache-Control")).To(Equal("public, max-age=31536000, immutable"))
+		Expect(w.Header().Get("ETag")).To(Equal(`"` + hash + `"`))
+	})
+
+})
diff --git a/server/subsonic/browsing.go b/server/subsonic/browsing.go
index 59d267321..d32a5c857 100644
--- a/server/subsonic/browsing.go
+++ b/server/subsonic/browsing.go
@@ -230,9 +230,11 @@ func (api *Router) GetAlbumInfo(r *http.Request) (*responses.Subsonic, error) {
 	response := newResponse()
 	response.AlbumInfo = &responses.AlbumInfo{}
 	response.AlbumInfo.Notes = album.Description
-	response.AlbumInfo.SmallImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 300)
-	response.AlbumInfo.MediumImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 600)
-	response.AlbumInfo.LargeImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 1200)
+	if !album.ImageAbsent {
+		response.AlbumInfo.SmallImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 300)
+		response.AlbumInfo.MediumImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 600)
+		response.AlbumInfo.LargeImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 1200)
+	}
 
 	response.AlbumInfo.LastFmUrl = album.ExternalUrl
 	response.AlbumInfo.MusicBrainzID = album.MbzAlbumID
@@ -295,9 +297,11 @@ func (api *Router) getArtistInfo(r *http.Request) (*responses.ArtistInfoBase, *m
 
 	base := responses.ArtistInfoBase{}
 	base.Biography = artist.Biography
-	base.SmallImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 300)
-	base.MediumImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 600)
-	base.LargeImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 1200)
+	if !artist.ImageAbsent {
+		base.SmallImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 300)
+		base.MediumImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 600)
+		base.LargeImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 1200)
+	}
 	base.LastFmUrl = artist.ExternalUrl
 	base.MusicBrainzID = artist.MbzArtistID
 
@@ -454,7 +458,7 @@ func (api *Router) buildAlbumDirectory(ctx context.Context, album *model.Album)
 		dir.AverageRating = album.AverageRating
 	}
 	dir.SongCount = int32(album.SongCount)
-	dir.CoverArt = album.CoverArtID().String()
+	dir.CoverArt = coverArtOrEmpty(album.CoverArtID(), album.ImageAbsent)
 	if album.Starred {
 		dir.Starred = album.StarredAt
 	}
diff --git a/server/subsonic/browsing_test.go b/server/subsonic/browsing_test.go
index b8f510aed..d34da2f37 100644
--- a/server/subsonic/browsing_test.go
+++ b/server/subsonic/browsing_test.go
@@ -6,6 +6,7 @@ import (
 	"net/http/httptest"
 
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
@@ -157,4 +158,57 @@ var _ = Describe("Browsing", func() {
 			Expect(response.Artist).ToNot(BeNil())
 		})
 	})
+
+	Describe("GetAlbumInfo", func() {
+		It("emits image URLs when the album artwork is unresolved", func() {
+			api.provider = &fakeInfoProvider{album: &model.Album{ID: "al-1"}}
+			r := httptest.NewRequest("GET", "/rest/getAlbumInfo?id=al-1", nil)
+			resp, err := api.GetAlbumInfo(r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp.AlbumInfo.SmallImageUrl).ToNot(BeEmpty())
+			Expect(resp.AlbumInfo.LargeImageUrl).ToNot(BeEmpty())
+		})
+		It("omits image URLs when the album artwork is known absent", func() {
+			api.provider = &fakeInfoProvider{album: &model.Album{ID: "al-1", ItemImage: model.ItemImage{ImageAbsent: true}}}
+			r := httptest.NewRequest("GET", "/rest/getAlbumInfo?id=al-1", nil)
+			resp, err := api.GetAlbumInfo(r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp.AlbumInfo.SmallImageUrl).To(BeEmpty())
+			Expect(resp.AlbumInfo.MediumImageUrl).To(BeEmpty())
+			Expect(resp.AlbumInfo.LargeImageUrl).To(BeEmpty())
+		})
+	})
+
+	Describe("GetArtistInfo", func() {
+		It("emits image URLs when the artist artwork is unresolved", func() {
+			api.provider = &fakeInfoProvider{artist: &model.Artist{ID: "ar-1"}}
+			r := httptest.NewRequest("GET", "/rest/getArtistInfo?id=ar-1", nil)
+			resp, err := api.GetArtistInfo(r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp.ArtistInfo.SmallImageUrl).ToNot(BeEmpty())
+		})
+		It("omits image URLs when the artist artwork is known absent", func() {
+			api.provider = &fakeInfoProvider{artist: &model.Artist{ID: "ar-1", ItemImage: model.ItemImage{ImageAbsent: true}}}
+			r := httptest.NewRequest("GET", "/rest/getArtistInfo?id=ar-1", nil)
+			resp, err := api.GetArtistInfo(r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp.ArtistInfo.SmallImageUrl).To(BeEmpty())
+			Expect(resp.ArtistInfo.MediumImageUrl).To(BeEmpty())
+			Expect(resp.ArtistInfo.LargeImageUrl).To(BeEmpty())
+		})
+	})
 })
+
+type fakeInfoProvider struct {
+	external.Provider
+	album  *model.Album
+	artist *model.Artist
+}
+
+func (f *fakeInfoProvider) UpdateAlbumInfo(context.Context, string) (*model.Album, error) {
+	return f.album, nil
+}
+
+func (f *fakeInfoProvider) UpdateArtistInfo(context.Context, string, int, bool) (*model.Artist, error) {
+	return f.artist, nil
+}
diff --git a/server/subsonic/e2e/e2e_suite_test.go b/server/subsonic/e2e/e2e_suite_test.go
index 97d7fb40a..8998731a4 100644
--- a/server/subsonic/e2e/e2e_suite_test.go
+++ b/server/subsonic/e2e/e2e_suite_test.go
@@ -311,12 +311,12 @@ func parseJSONResponse(w *httptest.ResponseRecorder) *responses.Subsonic {
 // noopArtwork implements artwork.Artwork
 type noopArtwork struct{}
 
-func (n noopArtwork) Get(context.Context, model.ArtworkID, int, bool) (io.ReadCloser, time.Time, error) {
-	return nil, time.Time{}, model.ErrNotFound
+func (n noopArtwork) Get(context.Context, model.ArtworkID, int, bool) (*artwork.Image, error) {
+	return nil, model.ErrNotFound
 }
 
-func (n noopArtwork) GetOrPlaceholder(_ context.Context, _ string, _ int, _ bool) (io.ReadCloser, time.Time, error) {
-	return io.NopCloser(io.LimitReader(nil, 0)), time.Time{}, nil
+func (n noopArtwork) GetOrPlaceholder(_ context.Context, _ string, _ int, _ bool) (*artwork.Image, error) {
+	return &artwork.Image{ReadCloser: io.NopCloser(io.LimitReader(nil, 0))}, nil
 }
 
 // noopArchiver implements core.Archiver
@@ -357,14 +357,6 @@ func (n noopProvider) TopSongs(context.Context, string, string, int) (model.Medi
 	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
-}
-
 // Compile-time interface checks
 var (
 	_ artwork.Artwork   = noopArtwork{}
@@ -416,8 +408,8 @@ func setupTestDB() {
 	// Create the Subsonic Router with real DS, streamer spy, and real Decider
 	streamerSpy = &harness.SpyStreamer{}
 	decider := stream.NewTranscodeDecider(ds, harness.NoopFFmpeg{})
-	s := scanner.New(ctx, ds, artwork.NoopCacheWarmer(), events.NoopBroker(),
-		playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+	s := scanner.New(ctx, ds, events.NoopBroker(),
+		playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 	router = subsonic.New(
 		ds,
 		noopArtwork{},
@@ -427,7 +419,7 @@ func setupTestDB() {
 		noopProvider{},
 		s,
 		events.NoopBroker(),
-		playlists.NewPlaylists(ds, core.NewImageUploadService()),
+		playlists.NewPlaylists(ds, artwork.NewUploader(ds)),
 		scrobbler.NewPlayTracker(ds, events.NoopBroker(), nil),
 		core.NewShare(ds),
 		playback.PlaybackServer(nil),
diff --git a/server/subsonic/e2e/subsonic_artwork_test.go b/server/subsonic/e2e/subsonic_artwork_test.go
new file mode 100644
index 000000000..619619810
--- /dev/null
+++ b/server/subsonic/e2e/subsonic_artwork_test.go
@@ -0,0 +1,328 @@
+package e2e
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	_ "github.com/navidrome/navidrome/adapters/gotaglib" // registers the "taglib" local-storage extractor
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/lyrics"
+	"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/storage/local" // registers the "file" storage scheme
+	"github.com/navidrome/navidrome/core/stream"
+	"github.com/navidrome/navidrome/db"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/persistence"
+	"github.com/navidrome/navidrome/resources"
+	"github.com/navidrome/navidrome/scanner"
+	"github.com/navidrome/navidrome/server/events"
+	"github.com/navidrome/navidrome/server/public"
+	"github.com/navidrome/navidrome/server/subsonic"
+	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/tests/harness"
+	"github.com/navidrome/navidrome/utils/cache"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"go.senan.xyz/taglib"
+)
+
+// The serving path streams folder-backed originals via os.Open, which a fake FS cannot back, so
+// this suite scans a small REAL on-disk library and drives the real worker and artwork.Artwork.
+var _ = Describe("Artwork Serving", Ordered, func() {
+	var (
+		artRouter   *subsonic.Router
+		pubRouter   *public.Router
+		artSvc      artwork.Artwork
+		worker      *artwork.Worker
+		artfulID    string
+		artlessID   string
+		artfulHash  string
+		placeholder []byte
+	)
+
+	albumCoverInList := func(albumID string) string {
+		GinkgoHelper()
+		resp := doReq("getAlbumList2", "type", "alphabeticalByName", "size", "500")
+		Expect(resp.AlbumList2).ToNot(BeNil())
+		for _, al := range resp.AlbumList2.Album {
+			if al.Id == albumID {
+				return al.CoverArt
+			}
+		}
+		Fail("album " + albumID + " not found in getAlbumList2")
+		return ""
+	}
+
+	getCover := func(params ...string) *httptest.ResponseRecorder {
+		GinkgoHelper()
+		w := httptest.NewRecorder()
+		r := buildReq(adminUser, "getCoverArt", params...)
+		artRouter.ServeHTTP(w, r)
+		return w
+	}
+
+	BeforeAll(func() {
+		DeferCleanup(configtest.SetupConfig())
+		DeferCleanup(func() { Eventually(scanner.IsScanning).Should(BeFalse()) })
+		ctx = request.WithUser(GinkgoT().Context(), adminUser)
+
+		musicDir := GinkgoT().TempDir()
+		writeArtworkTrack(musicDir, "Artful Artist", "Artful Album", "01 - Come Together", true)
+		writeArtworkTrack(musicDir, "Artless Artist", "Artless Album", "01 - Lonely", false)
+
+		conf.Server.MusicFolder = musicDir
+		conf.Server.DevExternalScanner = false
+		conf.Server.DevEnableMediaFileProbe = false
+		conf.Server.CoverArtPriority = "cover.jpg"
+		conf.Server.ArtistArtPriority = "artist.png" // offline: artists resolve absent, out of scope here
+		conf.Server.EnableMediaFileCoverArt = false
+		conf.Server.DevArtworkWorkerConcurrency = 1
+		conf.Server.CacheFolder = conf.NewDir(GinkgoT().TempDir())
+		conf.Server.EnableSharing = true
+		conf.Server.DevArtworkMaxRequests = 100
+		conf.Server.DevArtworkThrottleBacklogLimit = 100
+		conf.Server.DevArtworkThrottleBacklogTimeout = time.Minute
+
+		goldenDB.Restore()
+		ds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
+		auth.Init(ds)
+
+		// Re-scanning already-populated data deadlocks the parallel album-refresh phase at the
+		// harness's MaxOpenConns=1, so wipe the golden content and import this library fresh.
+		wipeScannedContent()
+		artLib := model.Library{Name: "Artwork Library", Path: musicDir}
+		Expect(ds.Library(ctx).Put(&artLib)).To(Succeed())
+		Expect(ds.User(ctx).SetUserLibraries(adminUser.ID, []int{artLib.ID})).To(Succeed())
+
+		s := scanner.New(ctx, ds, events.NoopBroker(),
+			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
+		_, err := s.ScanAll(ctx, true)
+		Expect(err).ToNot(HaveOccurred())
+
+		// Focus the worker on the entities under test.
+		_, err = db.Db().Exec("DELETE FROM artwork_queue")
+		Expect(err).ToNot(HaveOccurred())
+
+		artfulID = albumIDByName("Artful Album")
+		artlessID = albumIDByName("Artless Album")
+
+		ph, err := resources.FS().Open(consts.PlaceholderAlbumArt)
+		Expect(err).ToNot(HaveOccurred())
+		placeholder, err = io.ReadAll(ph)
+		Expect(err).ToNot(HaveOccurred())
+		_ = ph.Close()
+
+		store := artwork.NewImageStore(GinkgoT().TempDir())
+		imgCache := newDummyImageCache(ctx)
+		ffm := harness.NoopFFmpeg{}
+		artSvc = artwork.NewArtwork(ds, imgCache, store, ffm)
+		worker = artwork.NewWorker(ds, store, agents.GetAgents(ds, nil), ffm, events.NoopBroker(), imgCache)
+
+		artRouter = buildArtworkRouter(artSvc)
+		router = artRouter // so the shared doReq/doRawReq helpers hit the artwork-wired router
+		pubRouter = public.New(ds, artSvc, streamerSpy, core.NewShare(ds), noopArchiver{})
+	})
+
+	It("emits a bare optimistic coverArt id before the queue is drained", func() {
+		Expect(albumCoverInList(artfulID)).To(Equal("al-" + artfulID))
+		Expect(albumCoverInList(artlessID)).To(Equal("al-" + artlessID))
+	})
+
+	It("drains the queue: folder art is acquired, the artless album settles absent", func() {
+		// Enqueues the way the serving paths do, so the drain is driven by a plain queue row.
+		for _, id := range []string{artfulID, artlessID} {
+			Expect(ds.ArtworkQueue(ctx).EnqueuePreservingBackoff(model.ArtworkQueueItem{
+				ItemKind: model.KindAlbumArtwork.Prefix(), ItemID: id,
+				ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBump,
+			})).To(Succeed())
+		}
+		runWorkerUntil(ctx, worker, func() bool {
+			found, err := ds.Artwork(ctx).GetItemArtwork(model.KindAlbumArtwork, artfulID, model.ImageTypePrimary)
+			if err != nil || found.Hash == "" {
+				return false
+			}
+			absent, err := ds.Artwork(ctx).GetItemArtwork(model.KindAlbumArtwork, artlessID, model.ImageTypePrimary)
+			return err == nil && absent.Hash == ""
+		})
+		ia, err := ds.Artwork(ctx).GetItemArtwork(model.KindAlbumArtwork, artfulID, model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("folder"))
+		artfulHash = ia.Hash
+		Expect(artfulHash).ToNot(BeEmpty())
+	})
+
+	It("promotes the list id to the hash suffix and omits the absent album's coverArt", func() {
+		Expect(albumCoverInList(artfulID)).To(Equal("al-" + artfulID + "_" + artfulHash))
+		Expect(albumCoverInList(artlessID)).To(BeEmpty())
+	})
+
+	It("serves the found album's bytes with revalidation headers for a bare id", func() {
+		w := getCover("id", "al-"+artfulID)
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Body.Bytes()).To(Equal(readArtworkFixture("cover.jpg")))
+		Expect(w.Header().Get("ETag")).To(Equal(`"` + artfulHash + `"`))
+		Expect(w.Header().Get("Cache-Control")).To(Equal("public, no-cache"))
+	})
+
+	It("serves the found album immutably when the exact hash is requested", func() {
+		w := getCover("id", "al-"+artfulID+"_"+artfulHash)
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Body.Bytes()).To(Equal(readArtworkFixture("cover.jpg")))
+		Expect(w.Header().Get("Cache-Control")).To(Equal("public, max-age=31536000, immutable"))
+	})
+
+	It("returns 304 with an empty body when the client already holds the hash", func() {
+		w := httptest.NewRecorder()
+		r := buildReq(adminUser, "getCoverArt", "id", "al-"+artfulID)
+		r.Header.Set("If-None-Match", `"`+artfulHash+`"`)
+		artRouter.ServeHTTP(w, r)
+		Expect(w.Code).To(Equal(http.StatusNotModified))
+		Expect(w.Body.Bytes()).To(BeEmpty())
+	})
+
+	It("serves the placeholder with no-store for an absent album", func() {
+		w := getCover("id", "al-"+artlessID)
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Body.Bytes()).To(Equal(placeholder))
+		Expect(w.Header().Get("Cache-Control")).To(Equal("no-store"))
+	})
+
+	// Only adminUser was granted this library, so regularUser must get the placeholder even
+	// though the artwork state and bytes are perfectly servable by id.
+	It("serves the placeholder for an album in a library the caller cannot see", func() {
+		w := httptest.NewRecorder()
+		artRouter.ServeHTTP(w, buildReq(regularUser, "getCoverArt", "id", "al-"+artfulID))
+
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Body.Bytes()).To(Equal(placeholder), "must not leak the real cover")
+		Expect(w.Header().Get("Cache-Control")).To(Equal("no-store"))
+
+		Expect(getCover("id", "al-"+artfulID).Body.Bytes()).ToNot(Equal(placeholder))
+	})
+
+	// An id naming no entity is a different answer from an album with no art: no placeholder.
+	It("answers error 70 for an id that matches no entity", func() {
+		w := getCover("id", "al-nosuchalbum")
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Body.String()).To(ContainSubstring(`"code":70`))
+		Expect(w.Body.Bytes()).ToNot(Equal(placeholder))
+	})
+
+	It("serves /share/img immutably for a JWT whose payload carries the hash", func() {
+		token, err := auth.CreateExpiringPublicToken(time.Now().Add(time.Hour),
+			auth.Claims{ID: "al-" + artfulID + "_" + artfulHash})
+		Expect(err).ToNot(HaveOccurred())
+
+		w := httptest.NewRecorder()
+		pubRouter.ServeHTTP(w, httptest.NewRequest("GET", "/img/"+token, nil))
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Body.Bytes()).To(Equal(readArtworkFixture("cover.jpg")))
+		Expect(w.Header().Get("Cache-Control")).To(Equal("public, max-age=31536000, immutable"))
+	})
+
+	It("returns 404 from /share/img for an absent entity", func() {
+		token, err := auth.CreateExpiringPublicToken(time.Now().Add(time.Hour),
+			auth.Claims{ID: "al-" + artlessID})
+		Expect(err).ToNot(HaveOccurred())
+
+		w := httptest.NewRecorder()
+		pubRouter.ServeHTTP(w, httptest.NewRequest("GET", "/img/"+token, nil))
+		Expect(w.Code).To(Equal(http.StatusNotFound))
+	})
+})
+
+// buildArtworkRouter mirrors setupTestDB's Subsonic wiring but with the real artwork.Artwork.
+func buildArtworkRouter(art artwork.Artwork) *subsonic.Router {
+	decider := stream.NewTranscodeDecider(ds, harness.NoopFFmpeg{})
+	s := scanner.New(ctx, ds, events.NoopBroker(),
+		playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
+	return subsonic.New(
+		ds, art, streamerSpy, noopArchiver{}, core.NewPlayers(ds), noopProvider{}, s,
+		events.NoopBroker(), playlists.NewPlaylists(ds, artwork.NewUploader(ds)),
+		scrobbler.NewPlayTracker(ds, events.NoopBroker(), nil), core.NewShare(ds),
+		playback.PlaybackServer(nil), metrics.NewNoopInstance(), lyrics.NewLyrics(ds, nil), decider, nil,
+	)
+}
+
+// wipeScannedContent clears all scanned content so the next scan is a clean import. FKs are
+// disabled for the bulk delete, mirroring harness.Restore.
+func wipeScannedContent() {
+	GinkgoHelper()
+	_, err := db.Db().Exec("PRAGMA foreign_keys = OFF")
+	Expect(err).ToNot(HaveOccurred())
+	for _, t := range []string{"media_file", "album", "artist", "folder", "item_artwork", "artwork_queue", "artwork", "library"} {
+		_, err = db.Db().Exec(`DELETE FROM "` + t + `"`)
+		Expect(err).ToNot(HaveOccurred(), "wiping %s", t)
+	}
+	_, err = db.Db().Exec("PRAGMA foreign_keys = ON")
+	Expect(err).ToNot(HaveOccurred())
+}
+
+func albumIDByName(name string) string {
+	GinkgoHelper()
+	albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": name}})
+	Expect(err).ToNot(HaveOccurred())
+	Expect(albums).To(HaveLen(1), "expected exactly one album named %q", name)
+	return albums[0].ID
+}
+
+// Distinct ALBUM/ALBUMARTIST tags keep the generated albums from merging into one.
+func writeArtworkTrack(root, artist, album, title string, withCover bool) {
+	GinkgoHelper()
+	dir := filepath.Join(root, artist, album)
+	Expect(os.MkdirAll(dir, 0o755)).To(Succeed())
+	mp3 := filepath.Join(dir, title+".mp3")
+	Expect(os.WriteFile(mp3, readArtworkFixture("test.mp3"), 0o600)).To(Succeed())
+	Expect(taglib.WriteTags(mp3, map[string][]string{
+		"ALBUM": {album}, "ALBUMARTIST": {artist}, "ARTIST": {artist}, "TITLE": {title},
+	}, taglib.Clear)).To(Succeed())
+	if withCover {
+		Expect(os.WriteFile(filepath.Join(dir, "cover.jpg"), readArtworkFixture("cover.jpg"), 0o600)).To(Succeed())
+	}
+}
+
+func readArtworkFixture(name string) []byte {
+	GinkgoHelper()
+	data, err := os.ReadFile(filepath.Join("tests", "fixtures", "artist", "an-album", name))
+	Expect(err).ToNot(HaveOccurred())
+	return data
+}
+
+// size=0 requests stream originals and never invoke the reader, so this resize cache only has
+// to satisfy the constructor.
+func newDummyImageCache(ctx context.Context) cache.FileCache {
+	GinkgoHelper()
+	c := cache.NewFileCache("SubsonicArtworkE2E", "100MB", "images", 0,
+		func(context.Context, cache.Item) (io.Reader, error) {
+			return nil, errors.New("resize not exercised in subsonic artwork e2e")
+		})
+	Eventually(func() bool { return c.Available(ctx) }).Should(BeTrue())
+	return c
+}
+
+func runWorkerUntil(ctx context.Context, worker *artwork.Worker, until func() bool) {
+	GinkgoHelper()
+	runCtx, cancel := context.WithCancel(ctx)
+	done := make(chan error, 1)
+	go func() { done <- worker.Run(runCtx) }()
+	Eventually(until, 10*time.Second, 20*time.Millisecond).Should(BeTrue())
+	cancel()
+	Eventually(done, 2*time.Second).Should(Receive(BeNil()))
+}
diff --git a/server/subsonic/e2e/subsonic_multilibrary_test.go b/server/subsonic/e2e/subsonic_multilibrary_test.go
index e652cf492..98f87ca17 100644
--- a/server/subsonic/e2e/subsonic_multilibrary_test.go
+++ b/server/subsonic/e2e/subsonic_multilibrary_test.go
@@ -6,7 +6,6 @@ import (
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playlists"
@@ -53,8 +52,8 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 		adminWithLibs = *loadedAdmin
 
 		// Run incremental scan to import lib2 content (lib1 files unchanged → skipped)
-		s := scanner.New(ctx, ds, artwork.NoopCacheWarmer(), events.NoopBroker(),
-			playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+		s := scanner.New(ctx, ds, events.NoopBroker(),
+			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 		_, err = s.ScanAll(ctx, false)
 		Expect(err).ToNot(HaveOccurred())
 
diff --git a/server/subsonic/e2e/subsonic_sonic_similarity_test.go b/server/subsonic/e2e/subsonic_sonic_similarity_test.go
index 775fefe89..c0cb1d359 100644
--- a/server/subsonic/e2e/subsonic_sonic_similarity_test.go
+++ b/server/subsonic/e2e/subsonic_sonic_similarity_test.go
@@ -9,6 +9,7 @@ import (
 	"github.com/Masterminds/squirrel"
 	"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/matcher"
 	"github.com/navidrome/navidrome/core/metrics"
@@ -43,7 +44,7 @@ func buildSonicRouter(provider sonic.Provider) *subsonic.Router {
 		noopProvider{},
 		nil, // scanner
 		events.NoopBroker(),
-		playlists.NewPlaylists(ds, core.NewImageUploadService()),
+		playlists.NewPlaylists(ds, artwork.NewUploader(ds)),
 		scrobbler.NewPlayTracker(ds, events.NoopBroker(), nil),
 		core.NewShare(ds),
 		playback.PlaybackServer(nil),
diff --git a/server/subsonic/helpers.go b/server/subsonic/helpers.go
index b986200ae..e367cdee5 100644
--- a/server/subsonic/helpers.go
+++ b/server/subsonic/helpers.go
@@ -95,13 +95,24 @@ func getArtistAlbumCount(a *model.Artist) int32 {
 	}
 }
 
+// coverArtOrEmpty stamps the (hash-suffixed) coverArt id, or omits it (empty
+// string + the field's omitempty tag) when artwork is known absent.
+func coverArtOrEmpty(id model.ArtworkID, absent bool) string {
+	if absent {
+		return ""
+	}
+	return id.String()
+}
+
 func toArtist(r *http.Request, a model.Artist) responses.Artist {
 	artist := responses.Artist{
-		Id:             a.ID,
-		Name:           a.Name,
-		UserRating:     int32(a.Rating),
-		CoverArt:       a.CoverArtID().String(),
-		ArtistImageUrl: publicurl.ImageURL(r, a.CoverArtID(), 600),
+		Id:         a.ID,
+		Name:       a.Name,
+		UserRating: int32(a.Rating),
+		CoverArt:   coverArtOrEmpty(a.CoverArtID(), a.ImageAbsent),
+	}
+	if !a.ImageAbsent {
+		artist.ArtistImageUrl = publicurl.ImageURL(r, a.CoverArtID(), 600)
 	}
 	if conf.Server.Subsonic.EnableAverageRating {
 		artist.AverageRating = a.AverageRating
@@ -114,12 +125,14 @@ func toArtist(r *http.Request, a model.Artist) responses.Artist {
 
 func toArtistID3(r *http.Request, a model.Artist) responses.ArtistID3 {
 	artist := responses.ArtistID3{
-		Id:             a.ID,
-		Name:           a.Name,
-		AlbumCount:     getArtistAlbumCount(&a),
-		CoverArt:       a.CoverArtID().String(),
-		ArtistImageUrl: publicurl.ImageURL(r, a.CoverArtID(), 600),
-		UserRating:     int32(a.Rating),
+		Id:         a.ID,
+		Name:       a.Name,
+		AlbumCount: getArtistAlbumCount(&a),
+		CoverArt:   coverArtOrEmpty(a.CoverArtID(), a.ImageAbsent),
+		UserRating: int32(a.Rating),
+	}
+	if !a.ImageAbsent {
+		artist.ArtistImageUrl = publicurl.ImageURL(r, a.CoverArtID(), 600)
 	}
 	if conf.Server.Subsonic.EnableAverageRating {
 		artist.AverageRating = a.AverageRating
@@ -208,7 +221,7 @@ func childFromMediaFile(ctx context.Context, mf model.MediaFile) responses.Child
 	child.Size = mf.Size
 	child.Suffix = mf.Suffix
 	child.BitRate = int32(mf.BitRate)
-	child.CoverArt = mf.CoverArtID().String()
+	child.CoverArt = coverArtOrEmpty(mf.CoverArtID(), mf.ImageAbsent)
 	child.ContentType = mf.ContentType()
 
 	if ok && player.ReportRealPath {
@@ -369,7 +382,7 @@ func childFromAlbum(ctx context.Context, al model.Album) responses.Child {
 	child.Artist = al.AlbumArtist
 	child.Year = int32(cmp.Or(al.MaxOriginalYear, al.MaxYear))
 	child.Genre = al.Genre
-	child.CoverArt = al.CoverArtID().String()
+	child.CoverArt = coverArtOrEmpty(al.CoverArtID(), al.ImageAbsent)
 	child.Created = new(albumCreatedAt(al))
 	child.Parent = al.AlbumArtistID
 	child.ArtistId = al.AlbumArtistID
@@ -460,7 +473,7 @@ func buildAlbumID3(ctx context.Context, album model.Album) responses.AlbumID3 {
 	dir.Name = album.FullName()
 	dir.Artist = album.AlbumArtist
 	dir.ArtistId = album.AlbumArtistID
-	dir.CoverArt = album.CoverArtID().String()
+	dir.CoverArt = coverArtOrEmpty(album.CoverArtID(), album.ImageAbsent)
 	dir.SongCount = int32(album.SongCount)
 	dir.Duration = int32(album.Duration)
 	dir.PlayCount = album.PlayCount
diff --git a/server/subsonic/helpers_test.go b/server/subsonic/helpers_test.go
index 8db624649..69fda4681 100644
--- a/server/subsonic/helpers_test.go
+++ b/server/subsonic/helpers_test.go
@@ -321,6 +321,82 @@ var _ = Describe("helpers", func() {
 		})
 	})
 
+	Describe("artwork coverArt emission", func() {
+		const hash = "0123456789abcdef"
+		ctx := context.Background()
+
+		DescribeTable("coverArtOrEmpty",
+			func(id model.ArtworkID, absent bool, expected string) {
+				Expect(coverArtOrEmpty(id, absent)).To(Equal(expected))
+			},
+			Entry("emits the bare id when unresolved", model.ArtworkID{Kind: model.KindAlbumArtwork, ID: "1"}, false, "al-1"),
+			Entry("emits the hash-suffixed id when resolved", model.ArtworkID{Kind: model.KindAlbumArtwork, ID: "1", Hash: hash}, false, "al-1_"+hash),
+			Entry("omits (empty) when known absent", model.ArtworkID{Kind: model.KindAlbumArtwork, ID: "1", Hash: hash}, true, ""),
+		)
+
+		Describe("childFromAlbum", func() {
+			It("suffixes coverArt with the content hash when resolved", func() {
+				al := model.Album{ID: "al-1", ItemImage: model.ItemImage{ImageHash: hash}}
+				Expect(childFromAlbum(ctx, al).CoverArt).To(Equal("al-al-1_" + hash))
+			})
+			It("omits coverArt when known absent", func() {
+				al := model.Album{ID: "al-1", ItemImage: model.ItemImage{ImageAbsent: true}}
+				Expect(childFromAlbum(ctx, al).CoverArt).To(BeEmpty())
+			})
+			It("emits the bare id when unresolved", func() {
+				al := model.Album{ID: "al-1"}
+				Expect(childFromAlbum(ctx, al).CoverArt).To(Equal("al-al-1"))
+			})
+		})
+
+		Describe("childFromMediaFile", func() {
+			// An al- id must carry the album's hash (AlbumImage), never the track's own.
+			It("suffixes coverArt with the album's content hash when resolved", func() {
+				mf := model.MediaFile{ID: "mf-1", AlbumID: "al-1", AlbumImage: model.ItemImage{ImageHash: hash}}
+				Expect(childFromMediaFile(ctx, mf).CoverArt).To(Equal("al-al-1_" + hash))
+			})
+
+			It("does not stamp a track's own art hash onto the album id", func() {
+				mf := model.MediaFile{ID: "mf-1", AlbumID: "al-1",
+					ItemImage:  model.ItemImage{ImageHash: "0000ownarthash00"},
+					AlbumImage: model.ItemImage{ImageHash: hash}}
+				Expect(childFromMediaFile(ctx, mf).CoverArt).To(Equal("al-al-1_" + hash))
+			})
+			It("omits coverArt when known absent", func() {
+				mf := model.MediaFile{ID: "mf-1", AlbumID: "al-1", ItemImage: model.ItemImage{ImageAbsent: true}}
+				Expect(childFromMediaFile(ctx, mf).CoverArt).To(BeEmpty())
+			})
+			It("emits the bare id when unresolved", func() {
+				mf := model.MediaFile{ID: "mf-1", AlbumID: "al-1"}
+				Expect(childFromMediaFile(ctx, mf).CoverArt).To(Equal("al-al-1"))
+			})
+		})
+
+		Describe("toArtist / toArtistID3", func() {
+			r := httptest.NewRequest("GET", "/test", nil)
+			It("emits both coverArt and imageUrl when resolved", func() {
+				a := model.Artist{ID: "ar-1", ItemImage: model.ItemImage{ImageHash: hash}}
+				artist := toArtist(r, a)
+				Expect(artist.CoverArt).To(Equal("ar-ar-1_" + hash))
+				Expect(artist.ArtistImageUrl).ToNot(BeEmpty())
+			})
+			It("omits coverArt and imageUrl when known absent", func() {
+				a := model.Artist{ID: "ar-1", ItemImage: model.ItemImage{ImageAbsent: true}}
+				artist := toArtist(r, a)
+				Expect(artist.CoverArt).To(BeEmpty())
+				Expect(artist.ArtistImageUrl).To(BeEmpty())
+
+				id3 := toArtistID3(r, a)
+				Expect(id3.CoverArt).To(BeEmpty())
+				Expect(id3.ArtistImageUrl).To(BeEmpty())
+			})
+			It("emits an imageUrl when unresolved", func() {
+				a := model.Artist{ID: "ar-1"}
+				Expect(toArtist(r, a).ArtistImageUrl).ToNot(BeEmpty())
+			})
+		})
+	})
+
 	Describe("osChildFromMediaFile", func() {
 		var mf model.MediaFile
 		var ctx context.Context
diff --git a/server/subsonic/media_retrieval.go b/server/subsonic/media_retrieval.go
index 089a1fdda..8a5152a9d 100644
--- a/server/subsonic/media_retrieval.go
+++ b/server/subsonic/media_retrieval.go
@@ -13,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/resources"
+	"github.com/navidrome/navidrome/server/imghttp"
 	"github.com/navidrome/navidrome/server/subsonic/responses"
 	"github.com/navidrome/navidrome/utils/gravatar"
 	"github.com/navidrome/navidrome/utils/req"
@@ -66,7 +67,7 @@ func (api *Router) GetCoverArt(w http.ResponseWriter, r *http.Request) (*respons
 	size := p.IntOr("size", 0)
 	square := p.BoolOr("square", false)
 
-	imgReader, lastUpdate, err := api.artwork.GetOrPlaceholder(ctx, id, size, square)
+	img, err := api.artwork.GetOrPlaceholder(ctx, id, size, square)
 	switch {
 	case errors.Is(err, context.Canceled):
 		return nil, nil
@@ -78,11 +79,13 @@ func (api *Router) GetCoverArt(w http.ResponseWriter, r *http.Request) (*respons
 		return nil, err
 	}
 
-	defer imgReader.Close()
-	w.Header().Set("cache-control", "public, max-age=315360000")
-	w.Header().Set("last-modified", lastUpdate.Format(http.TimeFormat))
+	defer img.Close()
 
-	cnt, err := io.Copy(w, imgReader)
+	artID, _ := model.ParseArtworkID(id)
+	if imghttp.WriteImageHeaders(w, r, img, artID.Hash) {
+		return nil, nil
+	}
+	cnt, err := io.Copy(w, img)
 	if err != nil {
 		log.Warn(ctx, "Error sending image", "count", cnt, err)
 	}
diff --git a/server/subsonic/media_retrieval_test.go b/server/subsonic/media_retrieval_test.go
index 9331dfbe4..7610c866a 100644
--- a/server/subsonic/media_retrieval_test.go
+++ b/server/subsonic/media_retrieval_test.go
@@ -17,6 +17,7 @@ import (
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/lyrics"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -30,8 +31,14 @@ var _ = Describe("MediaRetrievalController", func() {
 	var w *httptest.ResponseRecorder
 
 	BeforeEach(func() {
+		albumRepo := &tests.MockAlbumRepo{}
+		albumRepo.SetData(model.Albums{{ID: "34"}}) // the id the specs request, made accessible
+		radioRepo := tests.CreateMockedRadioRepo()
+		Expect(radioRepo.Put(&model.Radio{ID: "rd1", Name: "Radio"})).To(Succeed())
 		ds = &tests.MockDataStore{
 			MockedMediaFile: mockRepo,
+			MockedAlbum:     albumRepo,
+			MockedRadio:     radioRepo,
 		}
 		artwork = &fakeArtwork{data: "image data"}
 		router = New(ds, artwork, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, lyrics.NewLyrics(ds, nil), nil, nil)
@@ -60,6 +67,22 @@ var _ = Describe("MediaRetrievalController", func() {
 			Expect(w.Body.String()).To(Equal(artwork.data))
 		})
 
+		// The service applies the library filter from the caller's context, so elevating here
+		// would bypass it.
+		It("passes the caller's context to the service rather than elevating", func() {
+			r := newGetRequest("id=al-34")
+			usr := model.User{ID: "u1", UserName: "u1"}
+			r = r.WithContext(request.WithUser(r.Context(), usr))
+
+			_, err := router.GetCoverArt(w, r)
+
+			Expect(err).ToNot(HaveOccurred())
+			got, ok := request.UserFrom(artwork.recvCtx)
+			Expect(ok).To(BeTrue(), "the service must see who is asking")
+			Expect(got.ID).To(Equal("u1"))
+			Expect(got.IsAdmin).To(BeFalse(), "the handler must not elevate")
+		})
+
 		It("should fail when the file is not found", func() {
 			artwork.err = model.ErrNotFound
 			r := newGetRequest("id=34", "size=128", "square=true")
@@ -108,6 +131,53 @@ var _ = Describe("MediaRetrievalController", func() {
 				Expect(w.Body.String()).To(BeEmpty())
 			})
 		})
+
+		Describe("caching headers", func() {
+			const hash = "0123456789abcdef"
+
+			It("sets an ETag and no-cache for a bare id", func() {
+				artwork.hash = hash
+				r := newGetRequest("id=al-34")
+				_, err := router.GetCoverArt(w, r)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(w.Header().Get("ETag")).To(Equal(`"` + hash + `"`))
+				Expect(w.Header().Get("Cache-Control")).To(Equal("public, no-cache"))
+				Expect(w.Body.String()).To(Equal(artwork.data))
+			})
+
+			It("marks the response immutable when the id asserts the current hash", func() {
+				artwork.hash = hash
+				r := newGetRequest("id=al-34_" + hash)
+				_, err := router.GetCoverArt(w, r)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(w.Header().Get("Cache-Control")).To(Equal("public, max-age=31536000, immutable"))
+			})
+
+			It("returns 304 with no body when If-None-Match matches", func() {
+				artwork.hash = hash
+				r := newGetRequest("id=al-34")
+				r.Header.Set("If-None-Match", `"`+hash+`"`)
+				_, err := router.GetCoverArt(w, r)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(w.Code).To(Equal(304))
+				Expect(w.Body.Len()).To(BeZero())
+			})
+
+			It("never caches a placeholder", func() {
+				artwork.placeholder = true
+				r := newGetRequest("id=al-missing")
+				_, err := router.GetCoverArt(w, r)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(w.Code).To(Equal(200))
+				Expect(w.Header().Get("Cache-Control")).To(Equal("no-store"))
+				Expect(w.Header().Get("ETag")).To(BeEmpty())
+				Expect(w.Body.String()).To(Equal(artwork.data))
+			})
+		})
 	})
 
 	Describe("GetLyrics", func() {
@@ -188,25 +258,35 @@ var _ = Describe("MediaRetrievalController", func() {
 type fakeArtwork struct {
 	artwork.Artwork
 	data          string
+	hash          string
+	lastUpdated   time.Time
+	placeholder   bool
 	err           error
 	ctxCancelFunc func()
 	recvId        string
 	recvSize      int
 	recvSquare    bool
+	recvCtx       context.Context
 }
 
-func (c *fakeArtwork) GetOrPlaceholder(_ context.Context, id string, size int, square bool) (io.ReadCloser, time.Time, error) {
+func (c *fakeArtwork) GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (*artwork.Image, error) {
+	c.recvCtx = ctx
 	if c.err != nil {
-		return nil, time.Time{}, c.err
+		return nil, c.err
 	}
 	c.recvId = id
 	c.recvSize = size
 	c.recvSquare = square
 	if c.ctxCancelFunc != nil {
 		c.ctxCancelFunc()
-		return nil, time.Time{}, context.Canceled
+		return nil, context.Canceled
 	}
-	return io.NopCloser(bytes.NewReader([]byte(c.data))), time.Time{}, nil
+	return &artwork.Image{
+		ReadCloser:  io.NopCloser(bytes.NewReader([]byte(c.data))),
+		Hash:        c.hash,
+		LastUpdated: c.lastUpdated,
+		Placeholder: c.placeholder,
+	}, nil
 }
 
 type mockedMediaFile struct {
diff --git a/server/subsonic/playlists.go b/server/subsonic/playlists.go
index 17ba1b2c9..bd53528d9 100644
--- a/server/subsonic/playlists.go
+++ b/server/subsonic/playlists.go
@@ -151,7 +151,7 @@ func (api *Router) buildPlaylist(ctx context.Context, p model.Playlist) response
 	pls.Comment = p.Comment
 	pls.Owner = p.OwnerName
 	pls.Public = p.Public
-	pls.CoverArt = p.CoverArtID().String()
+	pls.CoverArt = coverArtOrEmpty(p.CoverArtID(), p.ImageAbsent)
 	pls.OpenSubsonicPlaylist = buildOSPlaylist(ctx, p)
 
 	return pls
diff --git a/server/subsonic/playlists_test.go b/server/subsonic/playlists_test.go
index f0a2f8ac5..a7c9e2ec7 100644
--- a/server/subsonic/playlists_test.go
+++ b/server/subsonic/playlists_test.go
@@ -129,6 +129,19 @@ var _ = Describe("buildPlaylist", func() {
 			})
 		})
 
+		Context("artwork emission", func() {
+			It("suffixes coverArt with the content hash when resolved", func() {
+				playlist.ImageHash = "0123456789abcdef"
+				result := router.buildPlaylist(ctx, playlist)
+				Expect(result.CoverArt).To(Equal("pl-pls-1_0123456789abcdef"))
+			})
+			It("omits coverArt when known absent", func() {
+				playlist.ImageAbsent = true
+				result := router.buildPlaylist(ctx, playlist)
+				Expect(result.CoverArt).To(BeEmpty())
+			})
+		})
+
 		Context("with legacy client", func() {
 			BeforeEach(func() {
 				conf.Server.Subsonic.LegacyClients = "legacy-client"
diff --git a/server/subsonic/radio.go b/server/subsonic/radio.go
index 4fbd6a53d..1fb266f1d 100644
--- a/server/subsonic/radio.go
+++ b/server/subsonic/radio.go
@@ -74,10 +74,10 @@ func (api *Router) GetInternetRadios(r *http.Request) (*responses.Subsonic, erro
 		if strings.Contains(conf.Server.Subsonic.LegacyClients, player.Client) {
 			continue
 		}
-		// Add coverArt if not legacy client
+		// Add coverArt if not legacy client; only radios have an uploaded image as their sole art source
 		var coverArt string
 		if g.UploadedImage != "" {
-			coverArt = g.CoverArtID().String()
+			coverArt = coverArtOrEmpty(g.CoverArtID(), g.ImageAbsent)
 		}
 		res[i].OpenSubsonicRadio = &responses.OpenSubsonicRadio{
 			CoverArt: coverArt,
diff --git a/server/subsonic/radio_test.go b/server/subsonic/radio_test.go
index e959ebe29..aa805abbf 100644
--- a/server/subsonic/radio_test.go
+++ b/server/subsonic/radio_test.go
@@ -71,10 +71,25 @@ var _ = Describe("Radio", func() {
 				Expect(err).ToNot(HaveOccurred())
 				Expect(response.InternetRadioStations.Radios).To(HaveLen(2))
 				Expect(response.InternetRadioStations.Radios[0].OpenSubsonicRadio).ToNot(BeNil())
-				Expect(response.InternetRadioStations.Radios[0].CoverArt).To(Equal("ra-rd-1_0"))
+				Expect(response.InternetRadioStations.Radios[0].CoverArt).To(Equal("ra-rd-1"))
 				Expect(response.InternetRadioStations.Radios[1].OpenSubsonicRadio).ToNot(BeNil())
 				Expect(response.InternetRadioStations.Radios[1].CoverArt).To(BeEmpty())
 			})
+
+			It("suffixes coverArt with the content hash when resolved and omits it when known absent", func() {
+				radioRepo.All = model.Radios{
+					{ID: "rd-1", Name: "Radio 1", UploadedImage: "rd-1_cover.jpg", ItemImage: model.ItemImage{ImageHash: "0123456789abcdef"}},
+					{ID: "rd-2", Name: "Radio 2", UploadedImage: "rd-2_cover.jpg", ItemImage: model.ItemImage{ImageAbsent: true}},
+				}
+				r := httptest.NewRequest("GET", "/rest/getInternetRadios", nil)
+				r = r.WithContext(ctx)
+
+				response, err := api.GetInternetRadios(r)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(response.InternetRadioStations.Radios[0].CoverArt).To(Equal("ra-rd-1_0123456789abcdef"))
+				Expect(response.InternetRadioStations.Radios[1].CoverArt).To(BeEmpty())
+			})
 		})
 
 		Context("with a legacy client", func() {
@@ -129,7 +144,7 @@ var _ = Describe("Radio", func() {
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(response.InternetRadioStations.Radios[0].OpenSubsonicRadio).ToNot(BeNil())
-				Expect(response.InternetRadioStations.Radios[0].CoverArt).To(Equal("ra-rd-1_0"))
+				Expect(response.InternetRadioStations.Radios[0].CoverArt).To(Equal("ra-rd-1"))
 			})
 		})
 
diff --git a/server/subsonic/searching.go b/server/subsonic/searching.go
index 5d4989ae5..cc787f041 100644
--- a/server/subsonic/searching.go
+++ b/server/subsonic/searching.go
@@ -110,11 +110,13 @@ func (api *Router) Search2(r *http.Request) (*responses.Subsonic, error) {
 	searchResult2 := &responses.SearchResult2{}
 	searchResult2.Artist = slice.Map(as, func(artist model.Artist) responses.Artist {
 		a := responses.Artist{
-			Id:             artist.ID,
-			Name:           artist.Name,
-			UserRating:     int32(artist.Rating),
-			CoverArt:       artist.CoverArtID().String(),
-			ArtistImageUrl: publicurl.ImageURL(r, artist.CoverArtID(), 600),
+			Id:         artist.ID,
+			Name:       artist.Name,
+			UserRating: int32(artist.Rating),
+			CoverArt:   coverArtOrEmpty(artist.CoverArtID(), artist.ImageAbsent),
+		}
+		if !artist.ImageAbsent {
+			a.ArtistImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 600)
 		}
 		if artist.Starred {
 			a.Starred = artist.StarredAt
diff --git a/server/subsonic/searching_test.go b/server/subsonic/searching_test.go
index 4e72bd2e6..d31a50cfa 100644
--- a/server/subsonic/searching_test.go
+++ b/server/subsonic/searching_test.go
@@ -1,6 +1,8 @@
 package subsonic
 
 import (
+	"net/http"
+
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/model"
@@ -209,4 +211,32 @@ var _ = Describe("Search", func() {
 			})
 		})
 	})
+
+	Describe("artwork emission", func() {
+		newSearchRequest := func() *http.Request {
+			r := newGetRequest("query=test")
+			ctx := request.WithUser(r.Context(), model.User{ID: "user1", Libraries: []model.Library{{ID: 1}}})
+			return r.WithContext(ctx)
+		}
+
+		It("omits coverArt and imageUrl for a known-absent artist", func() {
+			mockArtistRepo.SetData(model.Artists{
+				{ID: "ar-1", Name: "Absent Artist", ItemImage: model.ItemImage{ImageAbsent: true}},
+			})
+			resp, err := router.Search2(newSearchRequest())
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp.SearchResult2.Artist).To(HaveLen(1))
+			Expect(resp.SearchResult2.Artist[0].CoverArt).To(BeEmpty())
+			Expect(resp.SearchResult2.Artist[0].ArtistImageUrl).To(BeEmpty())
+		})
+
+		It("emits coverArt and imageUrl for an unresolved artist", func() {
+			mockArtistRepo.SetData(model.Artists{{ID: "ar-1", Name: "Unresolved Artist"}})
+			resp, err := router.Search2(newSearchRequest())
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp.SearchResult2.Artist).To(HaveLen(1))
+			Expect(resp.SearchResult2.Artist[0].CoverArt).To(Equal("ar-ar-1"))
+			Expect(resp.SearchResult2.Artist[0].ArtistImageUrl).ToNot(BeEmpty())
+		})
+	})
 })
diff --git a/tests/harness/harness.go b/tests/harness/harness.go
index ff5ce8919..5949c4fae 100644
--- a/tests/harness/harness.go
+++ b/tests/harness/harness.go
@@ -13,7 +13,6 @@ import (
 	"testing/fstest"
 
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/core/ffmpeg"
@@ -74,8 +73,8 @@ func SetupDB(ctx context.Context, users ...*model.User) *DB {
 		u.Libraries = loaded.Libraries
 	}
 
-	s := scanner.New(ctx, ds, artwork.NoopCacheWarmer(), events.NoopBroker(),
-		playlists.NewPlaylists(ds, core.NewImageUploadService()), metrics.NewNoopInstance())
+	s := scanner.New(ctx, ds, events.NoopBroker(),
+		playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 	_, err := s.ScanAll(ctx, true)
 	Expect(err).ToNot(HaveOccurred())
 
@@ -87,17 +86,12 @@ func SetupDB(ctx context.Context, users ...*model.User) *DB {
 	return h
 }
 
-// Restore reloads every table from the golden snapshot via ATTACH DATABASE — much faster than a
-// rescan. FTS shadow tables are skipped; they are kept in sync by their content tables' triggers.
-func (h *DB) Restore() {
-	sqlDB := db.Db()
-	_, err := sqlDB.Exec("PRAGMA foreign_keys = OFF")
-	Expect(err).ToNot(HaveOccurred())
-	_, err = sqlDB.Exec("ATTACH DATABASE ? AS snapshot", h.SnapshotPath)
-	Expect(err).ToNot(HaveOccurred())
-
-	rows, err := sqlDB.Query("SELECT name FROM main.sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '%_fts' AND name NOT LIKE '%_fts_%'")
+// ResettableTables lists the tables a per-spec reset may write. FTS shadow tables are excluded:
+// their content tables' triggers keep them in sync, and writing them directly corrupts the index.
+func ResettableTables() []string {
+	rows, err := db.Db().Query("SELECT name FROM main.sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '%_fts' AND name NOT LIKE '%_fts_%'")
 	Expect(err).ToNot(HaveOccurred())
+	defer rows.Close()
 	var tables []string
 	for rows.Next() {
 		var name string
@@ -105,12 +99,37 @@ func (h *DB) Restore() {
 		tables = append(tables, name)
 	}
 	Expect(rows.Err()).ToNot(HaveOccurred())
-	rows.Close()
+	return tables
+}
+
+// TruncateDB empties every resettable table, leaving the migrated schema in place — for suites
+// whose specs each build their own library, so the schema is not re-migrated per spec.
+func TruncateDB(tables []string) {
+	sqlDB := db.Db()
+	_, err := sqlDB.Exec("PRAGMA foreign_keys = OFF")
+	Expect(err).ToNot(HaveOccurred())
+	defer func() { _, _ = sqlDB.Exec("PRAGMA foreign_keys = ON") }()
 
 	for _, table := range tables {
 		// Table names come from sqlite_master, not user input.
 		_, err = sqlDB.Exec(`DELETE FROM main."` + table + `"`) //nolint:gosec
 		Expect(err).ToNot(HaveOccurred())
+	}
+}
+
+// Restore reloads every table from the golden snapshot via ATTACH DATABASE — much faster than a
+// rescan.
+func (h *DB) Restore() {
+	sqlDB := db.Db()
+	_, err := sqlDB.Exec("PRAGMA foreign_keys = OFF")
+	Expect(err).ToNot(HaveOccurred())
+	_, err = sqlDB.Exec("ATTACH DATABASE ? AS snapshot", h.SnapshotPath)
+	Expect(err).ToNot(HaveOccurred())
+
+	for _, table := range ResettableTables() {
+		// Table names come from sqlite_master, not user input.
+		_, err = sqlDB.Exec(`DELETE FROM main."` + table + `"`) //nolint:gosec
+		Expect(err).ToNot(HaveOccurred())
 		_, err = sqlDB.Exec(`INSERT INTO main."` + table + `" SELECT * FROM snapshot."` + table + `"`) //nolint:gosec
 		Expect(err).ToNot(HaveOccurred())
 	}
diff --git a/tests/mock_album_repo.go b/tests/mock_album_repo.go
index cc7d66b4d..ff6f9cff6 100644
--- a/tests/mock_album_repo.go
+++ b/tests/mock_album_repo.go
@@ -2,10 +2,12 @@ package tests
 
 import (
 	"errors"
+	"sync"
 	"time"
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 func CreateMockAlbumRepo() *MockAlbumRepo {
@@ -20,6 +22,7 @@ type MockAlbumRepo struct {
 	All                     model.Albums
 	Err                     bool
 	Options                 model.QueryOptions
+	optionsMu               sync.Mutex
 	SearchQuery             string            // last query passed to Search
 	ReassignAnnotationCalls map[string]string // prevID -> newID
 	CopyAttributesCalls     map[string]string // fromID -> toID
@@ -68,7 +71,10 @@ func (m *MockAlbumRepo) Put(al *model.Album) error {
 
 func (m *MockAlbumRepo) GetAll(qo ...model.QueryOptions) (model.Albums, error) {
 	if len(qo) > 0 {
+		// Recording the last options is a read-path write, and callers resolve concurrently.
+		m.optionsMu.Lock()
 		m.Options = qo[0]
+		m.optionsMu.Unlock()
 	}
 	if m.Err {
 		return nil, errors.New("unexpected error")
@@ -76,6 +82,14 @@ func (m *MockAlbumRepo) GetAll(qo ...model.QueryOptions) (model.Albums, error) {
 	return m.All, nil
 }
 
+func (m *MockAlbumRepo) GetAllIDs(qo ...model.QueryOptions) ([]string, error) {
+	all, err := m.GetAll(qo...)
+	if err != nil {
+		return nil, err
+	}
+	return slice.Map(all, func(a model.Album) string { return a.ID }), nil
+}
+
 func (m *MockAlbumRepo) GetCursor(qo ...model.QueryOptions) (model.AlbumCursor, error) {
 	res, err := m.GetAll(qo...)
 	if err != nil {
diff --git a/tests/mock_artist_repo.go b/tests/mock_artist_repo.go
index e6ea7aea4..9691a6584 100644
--- a/tests/mock_artist_repo.go
+++ b/tests/mock_artist_repo.go
@@ -6,6 +6,7 @@ import (
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 func CreateMockArtistRepo() *MockArtistRepo {
@@ -113,6 +114,14 @@ func (m *MockArtistRepo) GetAll(options ...model.QueryOptions) (model.Artists, e
 	return allArtists, nil
 }
 
+func (m *MockArtistRepo) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+	all, err := m.GetAll(options...)
+	if err != nil {
+		return nil, err
+	}
+	return slice.Map(all, func(a model.Artist) string { return a.ID }), nil
+}
+
 func (m *MockArtistRepo) GetCursor(options ...model.QueryOptions) (model.ArtistCursor, error) {
 	res, err := m.GetAll(options...)
 	if err != nil {
diff --git a/tests/mock_artwork_queue_repo.go b/tests/mock_artwork_queue_repo.go
new file mode 100644
index 000000000..1b097ca32
--- /dev/null
+++ b/tests/mock_artwork_queue_repo.go
@@ -0,0 +1,258 @@
+package tests
+
+import (
+	"cmp"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+)
+
+type MockArtworkQueueRepo struct {
+	model.ArtworkQueueRepository
+	// mu guards Data: the worker drains this mock concurrently.
+	mu   sync.Mutex
+	Data map[string]model.ArtworkQueueItem // keyed by iaKey(kind, id, imageType)
+	Err  error
+	// ItemArtworkSource, when set, backs EnqueueStaleAbsent with real item_artwork state.
+	ItemArtworkSource *MockArtworkRepo
+	// ExistingIDs is keyed by item_kind; a nil per-kind map means PurgeDangling keeps that kind.
+	ExistingIDs map[string]map[string]bool
+}
+
+func CreateMockArtworkQueueRepo() *MockArtworkQueueRepo {
+	return &MockArtworkQueueRepo{Data: map[string]model.ArtworkQueueItem{}}
+}
+
+func (m *MockArtworkQueueRepo) Enqueue(items ...model.ArtworkQueueItem) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	m.enqueueLocked(items)
+	return nil
+}
+
+func (m *MockArtworkQueueRepo) enqueueLocked(items []model.ArtworkQueueItem) {
+	now := time.Now()
+	for _, it := range items {
+		if it.ImageType == "" {
+			it.ImageType = model.ImageTypePrimary
+		}
+		k := iaKey(it.ItemKind, it.ItemID, it.ImageType)
+		// Mirror the SQL: retry_at/enqueued_at are server-set, never taken from the caller.
+		if prev, ok := m.Data[k]; ok {
+			prev.Priority = max(prev.Priority, it.Priority)
+			prev.RetryAt = now
+			prev.Attempts = 0
+			prev.EnqueuedAt = now
+			m.Data[k] = prev
+			continue
+		}
+		it.Attempts = 0
+		it.RetryAt = now
+		it.EnqueuedAt = now
+		m.Data[k] = it
+	}
+}
+
+// EnqueueIfMissing mirrors the SQL anti-join: skip anything that already has an item_artwork row.
+func (m *MockArtworkQueueRepo) EnqueueIfMissing(items ...model.ArtworkQueueItem) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	var fresh []model.ArtworkQueueItem
+	for _, it := range items {
+		k := iaKey(it.ItemKind, it.ItemID, cmp.Or(it.ImageType, model.ImageTypePrimary))
+		if m.ItemArtworkSource != nil {
+			if _, ok := m.ItemArtworkSource.ItemData[k]; ok {
+				continue
+			}
+		}
+		if _, ok := m.Data[k]; ok { // DO NOTHING
+			continue
+		}
+		fresh = append(fresh, it)
+	}
+	m.enqueueLocked(fresh)
+	return nil
+}
+
+func (m *MockArtworkQueueRepo) DequeueBatch(n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	var res []model.ArtworkQueueItem
+	now := time.Now()
+	for _, it := range m.Data {
+		if !it.RetryAt.After(now) && (len(kinds) == 0 || slices.Contains(kinds, it.ItemKind)) {
+			res = append(res, it)
+		}
+	}
+	slices.SortFunc(res, func(a, b model.ArtworkQueueItem) int {
+		return cmp.Or(cmp.Compare(b.Priority, a.Priority), a.EnqueuedAt.Compare(b.EnqueuedAt))
+	})
+	if len(res) > n {
+		res = res[:n]
+	}
+	return res, nil
+}
+
+func (m *MockArtworkQueueRepo) MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	k := iaKey(kind, id, imageType)
+	if it, ok := m.Data[k]; ok && it.RetryAt.Equal(seenRetryAt) {
+		it.Attempts++
+		it.RetryAt = retryAt
+		m.Data[k] = it
+	}
+	return nil
+}
+
+func (m *MockArtworkQueueRepo) DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	k := iaKey(kind, id, imageType)
+	if it, ok := m.Data[k]; ok && it.RetryAt.Equal(retryAt) {
+		delete(m.Data, k)
+	}
+	return nil
+}
+
+func (m *MockArtworkQueueRepo) PurgeDangling() (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return 0, m.Err
+	}
+	var purged int64
+	for k, it := range m.Data {
+		existing := m.ExistingIDs[it.ItemKind]
+		if existing == nil {
+			continue
+		}
+		if !existing[it.ItemID] {
+			delete(m.Data, k)
+			purged++
+		}
+	}
+	return purged, nil
+}
+
+func (m *MockArtworkQueueRepo) Count() (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return 0, m.Err
+	}
+	return int64(len(m.Data)), nil
+}
+
+func (m *MockArtworkQueueRepo) EnqueuePreservingBackoff(items ...model.ArtworkQueueItem) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	now := time.Now()
+	for _, it := range items {
+		if it.ImageType == "" {
+			it.ImageType = model.ImageTypePrimary
+		}
+		k := iaKey(it.ItemKind, it.ItemID, it.ImageType)
+		// Preserve an existing row's retry_at: a bump raises priority without resetting backoff.
+		if prev, ok := m.Data[k]; ok {
+			prev.Priority = max(prev.Priority, it.Priority)
+			m.Data[k] = prev
+			continue
+		}
+		it.Attempts = 0
+		it.RetryAt = now
+		it.EnqueuedAt = now
+		m.Data[k] = it
+	}
+	return nil
+}
+
+func (m *MockArtworkQueueRepo) EnqueueStaleAbsent(kind model.Kind, attemptedBefore time.Time) (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil || m.ItemArtworkSource == nil {
+		return 0, m.Err
+	}
+	now := time.Now()
+	var inserted int64
+	for _, ia := range m.ItemArtworkSource.ItemData {
+		if ia.ItemKind != kind.Prefix() || ia.Hash != "" || !ia.AttemptedAt.Before(attemptedBefore) {
+			continue
+		}
+		k := iaKey(ia.ItemKind, ia.ItemID, ia.ImageType)
+		if _, ok := m.Data[k]; ok { // DO NOTHING: never touch existing queue rows
+			continue
+		}
+		m.Data[k] = model.ArtworkQueueItem{
+			ItemKind:   ia.ItemKind,
+			ItemID:     ia.ItemID,
+			ImageType:  ia.ImageType,
+			Priority:   model.ArtworkPriorityRecheck,
+			RetryAt:    now,
+			EnqueuedAt: now,
+		}
+		inserted++
+	}
+	return inserted, nil
+}
+
+// EnqueueMissing mirrors the SQL set-difference insert: ExistingIDs[kind] minus ItemArtworkSource.
+func (m *MockArtworkQueueRepo) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return 0, m.Err
+	}
+	hasRow := func(id string) bool {
+		if m.ItemArtworkSource == nil {
+			return false
+		}
+		for _, ia := range m.ItemArtworkSource.ItemData {
+			if ia.ItemKind == kind.Prefix() && ia.ItemID == id {
+				return true
+			}
+		}
+		return false
+	}
+	now := time.Now()
+	var inserted int64
+	for id := range m.ExistingIDs[kind.Prefix()] {
+		if hasRow(id) {
+			continue
+		}
+		k := iaKey(kind.Prefix(), id, model.ImageTypePrimary)
+		if _, ok := m.Data[k]; ok { // DO NOTHING: never touch existing queue rows
+			continue
+		}
+		m.Data[k] = model.ArtworkQueueItem{
+			ItemKind:   kind.Prefix(),
+			ItemID:     id,
+			ImageType:  model.ImageTypePrimary,
+			Priority:   priority,
+			RetryAt:    now,
+			EnqueuedAt: now,
+		}
+		inserted++
+	}
+	return inserted, nil
+}
diff --git a/tests/mock_artwork_repo.go b/tests/mock_artwork_repo.go
new file mode 100644
index 000000000..2ace0daba
--- /dev/null
+++ b/tests/mock_artwork_repo.go
@@ -0,0 +1,175 @@
+package tests
+
+import (
+	"maps"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
+)
+
+type MockArtworkRepo struct {
+	model.ArtworkRepository
+	// mu guards the maps so the worker's concurrent drain can hit this mock race-free.
+	mu       sync.Mutex
+	Data     map[string]model.Artwork
+	ItemData map[string]model.ItemArtwork // keyed by iaKey(kind, id, imageType)
+	Err      error
+	// ExistingIDs, keyed by item_kind, backs PurgeDanglingItems; nil map keeps everything.
+	ExistingIDs map[string]map[string]bool
+}
+
+func CreateMockArtworkRepo() *MockArtworkRepo {
+	return &MockArtworkRepo{Data: map[string]model.Artwork{}, ItemData: map[string]model.ItemArtwork{}}
+}
+
+func iaKey(kind, id, imageType string) string { return kind + "|" + id + "|" + imageType }
+
+func (m *MockArtworkRepo) GetImage(hash string) (*model.Artwork, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	if a, ok := m.Data[hash]; ok {
+		return &a, nil
+	}
+	return nil, model.ErrNotFound
+}
+
+func (m *MockArtworkRepo) PutImage(a *model.Artwork) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	// Mirrors the SQL repository: every upsert refreshes created_at. Age fixtures via Data directly.
+	a.CreatedAt = time.Now()
+	m.Data[a.Hash] = *a
+	return nil
+}
+
+func (m *MockArtworkRepo) GetMimeByHash() (map[string]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	mimes := make(map[string]string, len(m.Data))
+	for h, a := range m.Data {
+		mimes[h] = a.Mime
+	}
+	return mimes, nil
+}
+
+func (m *MockArtworkRepo) PurgeDanglingItems() (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return 0, m.Err
+	}
+	var purged int64
+	for k, ia := range m.ItemData {
+		// A nil per-kind map means that kind isn't tracked by the test, so keep it.
+		existing := m.ExistingIDs[ia.ItemKind]
+		if existing == nil {
+			continue
+		}
+		if !existing[ia.ItemID] {
+			delete(m.ItemData, k)
+			purged++
+		}
+	}
+	return purged, nil
+}
+
+func (m *MockArtworkRepo) PurgeOrphans(createdBefore time.Time) (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return 0, m.Err
+	}
+	var deleted int64
+	for h, a := range m.Data {
+		if m.referenced(h) || !a.CreatedAt.Before(createdBefore) {
+			continue
+		}
+		delete(m.Data, h)
+		deleted++
+	}
+	return deleted, nil
+}
+
+func (m *MockArtworkRepo) referenced(hash string) bool {
+	for _, ia := range m.ItemData {
+		if ia.Hash == hash {
+			return true
+		}
+	}
+	return false
+}
+
+func (m *MockArtworkRepo) GetItemArtwork(kind model.Kind, id, imageType string) (*model.ItemArtwork, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	if ia, ok := m.ItemData[iaKey(kind.Prefix(), id, imageType)]; ok {
+		return &ia, nil
+	}
+	return nil, model.ErrNotFound
+}
+
+func (m *MockArtworkRepo) PutItemArtwork(ia *model.ItemArtwork) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	if ia.ImageType == "" {
+		ia.ImageType = model.ImageTypePrimary
+	}
+	ia.UpdatedAt = time.Now()
+	if ia.AttemptedAt.IsZero() {
+		ia.AttemptedAt = ia.UpdatedAt
+	}
+	m.ItemData[iaKey(ia.ItemKind, ia.ItemID, ia.ImageType)] = *ia
+	return nil
+}
+
+func (m *MockArtworkRepo) DeleteForItems(kind model.Kind, ids []string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	idSet := slice.ToSet(ids)
+	maps.DeleteFunc(m.ItemData, func(_ string, ia model.ItemArtwork) bool {
+		_, ok := idSet[ia.ItemID]
+		return ok && ia.ItemKind == kind.Prefix()
+	})
+	return nil
+}
+
+func (m *MockArtworkRepo) GetInfoForItems(kind model.Kind, ids []string) (map[string]model.ItemArtworkInfo, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	res := map[string]model.ItemArtworkInfo{}
+	for _, id := range ids {
+		if ia, ok := m.ItemData[iaKey(kind.Prefix(), id, model.ImageTypePrimary)]; ok {
+			info := model.ItemArtworkInfo{ItemID: id, Hash: ia.Hash}
+			if a, ok := m.Data[ia.Hash]; ok {
+				info.BlurHash, info.ThumbHash = a.BlurHash, a.ThumbHash
+				info.DominantColor = a.DominantColor
+				info.Width, info.Height = a.Width, a.Height
+			}
+			res[id] = info
+		}
+	}
+	return res, nil
+}
diff --git a/tests/mock_data_store.go b/tests/mock_data_store.go
index e016a28de..32f56a4f0 100644
--- a/tests/mock_data_store.go
+++ b/tests/mock_data_store.go
@@ -28,6 +28,8 @@ type MockDataStore struct {
 	MockedScrobble       model.ScrobbleRepository
 	MockedRadio          model.RadioRepository
 	MockedPlugin         model.PluginRepository
+	MockedArtwork        model.ArtworkRepository
+	MockedArtworkQueue   model.ArtworkQueueRepository
 	scrobbleBufferMu     sync.Mutex
 	repoMu               sync.Mutex
 
@@ -37,6 +39,8 @@ type MockDataStore struct {
 }
 
 func (db *MockDataStore) Library(ctx context.Context) model.LibraryRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedLibrary != nil {
 		return db.MockedLibrary
 	}
@@ -48,6 +52,8 @@ func (db *MockDataStore) Library(ctx context.Context) model.LibraryRepository {
 }
 
 func (db *MockDataStore) Folder(ctx context.Context) model.FolderRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedFolder != nil {
 		return db.MockedFolder
 	}
@@ -59,6 +65,8 @@ func (db *MockDataStore) Folder(ctx context.Context) model.FolderRepository {
 }
 
 func (db *MockDataStore) Tag(ctx context.Context) model.TagRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedTag != nil {
 		return db.MockedTag
 	}
@@ -70,6 +78,8 @@ func (db *MockDataStore) Tag(ctx context.Context) model.TagRepository {
 }
 
 func (db *MockDataStore) Album(ctx context.Context) model.AlbumRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedAlbum != nil {
 		return db.MockedAlbum
 	}
@@ -81,6 +91,8 @@ func (db *MockDataStore) Album(ctx context.Context) model.AlbumRepository {
 }
 
 func (db *MockDataStore) Artist(ctx context.Context) model.ArtistRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedArtist != nil {
 		return db.MockedArtist
 	}
@@ -92,11 +104,11 @@ func (db *MockDataStore) Artist(ctx context.Context) model.ArtistRepository {
 }
 
 func (db *MockDataStore) MediaFile(ctx context.Context) model.MediaFileRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.RealDS != nil && db.MockedMediaFile == nil {
 		return db.RealDS.MediaFile(ctx)
 	}
-	db.repoMu.Lock()
-	defer db.repoMu.Unlock()
 	if db.MockedMediaFile == nil {
 		db.MockedMediaFile = CreateMockMediaFileRepo()
 	}
@@ -104,6 +116,8 @@ func (db *MockDataStore) MediaFile(ctx context.Context) model.MediaFileRepositor
 }
 
 func (db *MockDataStore) Genre(ctx context.Context) model.GenreRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedGenre != nil {
 		return db.MockedGenre
 	}
@@ -115,6 +129,8 @@ func (db *MockDataStore) Genre(ctx context.Context) model.GenreRepository {
 }
 
 func (db *MockDataStore) Playlist(ctx context.Context) model.PlaylistRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedPlaylist != nil {
 		return db.MockedPlaylist
 	}
@@ -126,6 +142,8 @@ func (db *MockDataStore) Playlist(ctx context.Context) model.PlaylistRepository
 }
 
 func (db *MockDataStore) PlayQueue(ctx context.Context) model.PlayQueueRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedPlayQueue != nil {
 		return db.MockedPlayQueue
 	}
@@ -137,6 +155,8 @@ func (db *MockDataStore) PlayQueue(ctx context.Context) model.PlayQueueRepositor
 }
 
 func (db *MockDataStore) UserProps(ctx context.Context) model.UserPropsRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedUserProps != nil {
 		return db.MockedUserProps
 	}
@@ -148,6 +168,8 @@ func (db *MockDataStore) UserProps(ctx context.Context) model.UserPropsRepositor
 }
 
 func (db *MockDataStore) Property(ctx context.Context) model.PropertyRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedProperty != nil {
 		return db.MockedProperty
 	}
@@ -159,6 +181,8 @@ func (db *MockDataStore) Property(ctx context.Context) model.PropertyRepository
 }
 
 func (db *MockDataStore) Share(ctx context.Context) model.ShareRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedShare != nil {
 		return db.MockedShare
 	}
@@ -170,6 +194,8 @@ func (db *MockDataStore) Share(ctx context.Context) model.ShareRepository {
 }
 
 func (db *MockDataStore) User(ctx context.Context) model.UserRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedUser != nil {
 		return db.MockedUser
 	}
@@ -181,6 +207,8 @@ func (db *MockDataStore) User(ctx context.Context) model.UserRepository {
 }
 
 func (db *MockDataStore) Transcoding(ctx context.Context) model.TranscodingRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedTranscoding != nil {
 		return db.MockedTranscoding
 	}
@@ -192,6 +220,8 @@ func (db *MockDataStore) Transcoding(ctx context.Context) model.TranscodingRepos
 }
 
 func (db *MockDataStore) Player(ctx context.Context) model.PlayerRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedPlayer != nil {
 		return db.MockedPlayer
 	}
@@ -203,6 +233,8 @@ func (db *MockDataStore) Player(ctx context.Context) model.PlayerRepository {
 }
 
 func (db *MockDataStore) ScrobbleBuffer(ctx context.Context) model.ScrobbleBufferRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.RealDS != nil && db.MockedScrobbleBuffer == nil {
 		return db.RealDS.ScrobbleBuffer(ctx)
 	}
@@ -215,6 +247,8 @@ func (db *MockDataStore) ScrobbleBuffer(ctx context.Context) model.ScrobbleBuffe
 }
 
 func (db *MockDataStore) Scrobble(ctx context.Context) model.ScrobbleRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedScrobble != nil {
 		return db.MockedScrobble
 	}
@@ -226,6 +260,8 @@ func (db *MockDataStore) Scrobble(ctx context.Context) model.ScrobbleRepository
 }
 
 func (db *MockDataStore) Radio(ctx context.Context) model.RadioRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedRadio != nil {
 		return db.MockedRadio
 	}
@@ -237,6 +273,8 @@ func (db *MockDataStore) Radio(ctx context.Context) model.RadioRepository {
 }
 
 func (db *MockDataStore) Plugin(ctx context.Context) model.PluginRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
 	if db.MockedPlugin != nil {
 		return db.MockedPlugin
 	}
@@ -247,6 +285,42 @@ func (db *MockDataStore) Plugin(ctx context.Context) model.PluginRepository {
 	return db.MockedPlugin
 }
 
+func (db *MockDataStore) Artwork(ctx context.Context) model.ArtworkRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
+	return db.artworkLocked(ctx)
+}
+
+// artworkLocked is the body of Artwork for callers already holding repoMu; repoMu is a plain
+// Mutex, so re-entering through the exported method would deadlock.
+func (db *MockDataStore) artworkLocked(ctx context.Context) model.ArtworkRepository {
+	if db.MockedArtwork != nil {
+		return db.MockedArtwork
+	}
+	if db.RealDS != nil {
+		return db.RealDS.Artwork(ctx)
+	}
+	db.MockedArtwork = CreateMockArtworkRepo()
+	return db.MockedArtwork
+}
+
+func (db *MockDataStore) ArtworkQueue(ctx context.Context) model.ArtworkQueueRepository {
+	db.repoMu.Lock()
+	defer db.repoMu.Unlock()
+	if db.MockedArtworkQueue != nil {
+		return db.MockedArtworkQueue
+	}
+	if db.RealDS != nil {
+		return db.RealDS.ArtworkQueue(ctx)
+	}
+	q := CreateMockArtworkQueueRepo()
+	if aw, ok := db.artworkLocked(ctx).(*MockArtworkRepo); ok {
+		q.ItemArtworkSource = aw
+	}
+	db.MockedArtworkQueue = q
+	return db.MockedArtworkQueue
+}
+
 func (db *MockDataStore) WithTx(block func(tx model.DataStore) error, label ...string) error {
 	return block(db)
 }
diff --git a/tests/mock_mediafile_repo.go b/tests/mock_mediafile_repo.go
index 990b91d7c..d993af1a8 100644
--- a/tests/mock_mediafile_repo.go
+++ b/tests/mock_mediafile_repo.go
@@ -123,6 +123,18 @@ func (m *MockMediaFileRepo) GetCursor(qo ...model.QueryOptions) (model.MediaFile
 	}, nil
 }
 
+func (m *MockMediaFileRepo) GetCursorWithArtwork(qo ...model.QueryOptions) (model.MediaFileCursor, error) {
+	return m.GetCursor(qo...)
+}
+
+func (m *MockMediaFileRepo) GetAllIDs(qo ...model.QueryOptions) ([]string, error) {
+	all, err := m.GetAll(qo...)
+	if err != nil {
+		return nil, err
+	}
+	return slice.Map(all, func(mf model.MediaFile) string { return mf.ID }), nil
+}
+
 func (m *MockMediaFileRepo) Put(mf *model.MediaFile) error {
 	if m.Err {
 		return errors.New("error")
diff --git a/tests/mock_playlist_repo.go b/tests/mock_playlist_repo.go
index 8f8842c8e..ee645e984 100644
--- a/tests/mock_playlist_repo.go
+++ b/tests/mock_playlist_repo.go
@@ -7,6 +7,7 @@ import (
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 func CreateMockPlaylistRepo() *MockPlaylistRepo {
@@ -52,6 +53,14 @@ func (m *MockPlaylistRepo) GetAll(options ...model.QueryOptions) (model.Playlist
 	return m.All, nil
 }
 
+func (m *MockPlaylistRepo) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+	all, err := m.GetAll(options...)
+	if err != nil {
+		return nil, err
+	}
+	return slice.Map(all, func(p model.Playlist) string { return p.ID }), nil
+}
+
 func (m *MockPlaylistRepo) GetCursor(options ...model.QueryOptions) (model.PlaylistCursor, error) {
 	res, err := m.GetAll(options...)
 	if err != nil {
diff --git a/tests/mock_playlist_track_repo.go b/tests/mock_playlist_track_repo.go
index 2835baadd..83751bb28 100644
--- a/tests/mock_playlist_track_repo.go
+++ b/tests/mock_playlist_track_repo.go
@@ -14,6 +14,7 @@ type MockPlaylistTrackRepo struct {
 	Reordered  bool
 	AddCount   int
 	Err        error
+	AlbumIDs   []string // stubbed result for GetAlbumIDs, ignoring options
 }
 
 func (m *MockPlaylistTrackRepo) SetData(tracks model.PlaylistTracks) {
@@ -66,6 +67,13 @@ func (m *MockPlaylistTrackRepo) GetCursor(options ...model.QueryOptions) (model.
 	}, nil
 }
 
+func (m *MockPlaylistTrackRepo) GetAlbumIDs(...model.QueryOptions) ([]string, error) {
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	return m.AlbumIDs, nil
+}
+
 func (m *MockPlaylistTrackRepo) GetMediaFileIDs(options ...model.QueryOptions) ([]string, error) {
 	if m.Err != nil {
 		return nil, m.Err
diff --git a/tests/mock_radio_repository.go b/tests/mock_radio_repository.go
index c50a529e5..2baeadc5c 100644
--- a/tests/mock_radio_repository.go
+++ b/tests/mock_radio_repository.go
@@ -5,6 +5,7 @@ import (
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 type MockedRadioRepo struct {
@@ -16,7 +17,7 @@ type MockedRadioRepo struct {
 }
 
 func CreateMockedRadioRepo() *MockedRadioRepo {
-	return &MockedRadioRepo{}
+	return &MockedRadioRepo{Data: map[string]*model.Radio{}}
 }
 
 func (m *MockedRadioRepo) SetError(err bool) {
@@ -73,6 +74,14 @@ func (m *MockedRadioRepo) GetAll(qo ...model.QueryOptions) (model.Radios, error)
 	return m.All, nil
 }
 
+func (m *MockedRadioRepo) GetAllIDs(qo ...model.QueryOptions) ([]string, error) {
+	all, err := m.GetAll(qo...)
+	if err != nil {
+		return nil, err
+	}
+	return slice.Map(all, func(r model.Radio) string { return r.ID }), nil
+}
+
 func (m *MockedRadioRepo) Put(radio *model.Radio, _ ...string) error {
 	if m.Err {
 		return errors.New("error")
diff --git a/ui/src/album/AlbumDetails.jsx b/ui/src/album/AlbumDetails.jsx
index cec66eb8b..f55d94ffc 100644
--- a/ui/src/album/AlbumDetails.jsx
+++ b/ui/src/album/AlbumDetails.jsx
@@ -2,7 +2,6 @@ import { useEffect, useState } from 'react'
 import {
   Card,
   CardContent,
-  CardMedia,
   Collapse,
   makeStyles,
   Typography,
@@ -21,6 +20,7 @@ import Lightbox from 'react-image-lightbox'
 import config from '../config'
 import 'react-image-lightbox/style.css'
 import subsonic from '../subsonic'
+import { Artwork } from '../common/Artwork'
 import {
   ArtistLinkField,
   CollapsibleComment,
@@ -30,7 +30,6 @@ import {
   RatingField,
   SizeField,
   useAlbumsPerPage,
-  useImageLoadingState,
 } from '../common'
 import { formatFullDate, intersperse } from '../utils'
 import AlbumExternalLinks from './AlbumExternalLinks'
@@ -88,9 +87,6 @@ const useStyles = makeStyles(
       backgroundColor: 'transparent',
       transition: 'opacity 0.3s ease-in-out',
     },
-    coverLoading: {
-      opacity: 0.5,
-    },
     loveButton: {
       top: theme.spacing(-0.2),
       left: theme.spacing(0.5),
@@ -223,15 +219,7 @@ const AlbumDetails = (props) => {
   const classes = useStyles()
   const [expanded, setExpanded] = useState(false)
   const [albumInfo, setAlbumInfo] = useState()
-  const {
-    imageLoading,
-    imageError,
-    isLightboxOpen,
-    handleImageLoad,
-    handleImageError,
-    handleOpenLightbox,
-    handleCloseLightbox,
-  } = useImageLoadingState(record.id)
+  const [isLightboxOpen, setLightboxOpen] = useState(false)
 
   let notes = albumInfo?.notes || record.notes
 
@@ -254,27 +242,18 @@ const AlbumDetails = (props) => {
       })
   }, [record])
 
-  const imageUrl = subsonic.getCoverArtUrl(record, config.uiCoverArtSize)
   const fullImageUrl = subsonic.getCoverArtUrl(record)
 
   return (
     <Card className={classes.root}>
       <div className={classes.cardContents}>
         <div className={classes.coverParent}>
-          <CardMedia
-            key={record.id}
-            component={'img'}
-            src={imageUrl}
-            width="400"
-            height="400"
-            className={`${classes.cover} ${imageLoading ? classes.coverLoading : ''}`}
-            onClick={handleOpenLightbox}
-            onLoad={handleImageLoad}
-            onError={handleImageError}
+          <Artwork
+            record={record}
+            fit="contain"
+            className={classes.cover}
             title={record.name}
-            style={{
-              cursor: imageError ? 'default' : 'pointer',
-            }}
+            onClick={() => setLightboxOpen(true)}
           />
         </div>
         <div className={classes.details}>
@@ -363,13 +342,13 @@ const AlbumDetails = (props) => {
           </Collapse>
         </div>
       )}
-      {isLightboxOpen && !imageError && (
+      {isLightboxOpen && (
         <Lightbox
           imagePadding={50}
           animationDuration={200}
           imageTitle={record.name}
           mainSrc={fullImageUrl}
-          onCloseRequest={handleCloseLightbox}
+          onCloseRequest={() => setLightboxOpen(false)}
         />
       )}
     </Card>
diff --git a/ui/src/album/AlbumGridView.jsx b/ui/src/album/AlbumGridView.jsx
index 33db9e40f..2e4cb10ba 100644
--- a/ui/src/album/AlbumGridView.jsx
+++ b/ui/src/album/AlbumGridView.jsx
@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { useRef } from 'react'
 import {
   GridList,
   GridListTile,
@@ -11,19 +11,18 @@ import withWidth from '@material-ui/core/withWidth'
 import { Link } from 'react-router-dom'
 import { linkToRecord, useListContext, Loading } from 'react-admin'
 import { withContentRect } from 'react-measure'
+import { useRollChanged } from './useRollChanged'
 import { useDrag } from 'react-dnd'
-import subsonic from '../subsonic'
 import {
   AlbumContextMenu,
   PlayButton,
   ArtistLinkField,
   OverflowTooltip,
-  useImageUrl,
 } from '../common'
-import config from '../config'
 import { DraggableTypes } from '../consts'
 import clsx from 'clsx'
 import { AlbumDatesField } from './AlbumDatesField.jsx'
+import { Artwork } from '../common/Artwork'
 
 const useStyles = makeStyles(
   (theme) => ({
@@ -105,12 +104,12 @@ const useCoverStyles = makeStyles({
     display: 'inline-block',
     width: '100%',
     objectFit: 'contain',
+    // The image fills this box absolutely, so it lends no height: a remount that has not been
+    // re-measured yet would collapse the tile and blank the cover for a frame.
+    aspectRatio: '1',
     height: (props) => props.height,
     transition: 'opacity 0.3s ease-in-out',
   },
-  coverLoading: {
-    opacity: 0,
-  },
 })
 
 const getColsForWidth = (width) => {
@@ -138,16 +137,14 @@ const Cover = withContentRect('bounds')(({
     [record],
   )
 
-  const url = subsonic.getCoverArtUrl(record, config.uiCoverArtSize, true)
-  const { imgUrl, loading: imageLoading } = useImageUrl(url)
-
   return (
     <div ref={measureRef} className={classes.coverContainer}>
       <div ref={dragAlbumRef}>
-        <img
-          src={imgUrl || undefined}
-          alt={record.name}
-          className={`${classes.cover} ${imageLoading ? classes.coverLoading : ''}`}
+        <Artwork
+          record={record}
+          square
+          className={classes.cover}
+          title={record.name}
         />
       </div>
     </div>
@@ -237,9 +234,21 @@ const LoadedAlbumGrid = ({ ids, data, basePath, width }) => {
   )
 }
 
-const AlbumGridView = ({ albumListType, loaded, loading, ...props }) => {
-  const hide =
-    (loading && albumListType === 'random') || !props.data || !props.ids
+const AlbumGridView = ({
+  albumListType,
+  loaded,
+  loading,
+  seed,
+  shownSeed,
+  ...props
+}) => {
+  // ArtistShow renders this grid too, with no roll to track, so own a ref when none is passed.
+  const ownSeed = useRef(null)
+  // A re-roll replaces every album, so the previous roll must not linger while it loads.
+  const rerolling =
+    useRollChanged(shownSeed ?? ownSeed, seed, loading) &&
+    albumListType === 'random'
+  const hide = rerolling || !props.data || !props.ids
   return hide ? <Loading /> : <LoadedAlbumGrid {...props} />
 }
 
diff --git a/ui/src/album/AlbumGridView.test.jsx b/ui/src/album/AlbumGridView.test.jsx
new file mode 100644
index 000000000..1f06c3fd7
--- /dev/null
+++ b/ui/src/album/AlbumGridView.test.jsx
@@ -0,0 +1,18 @@
+import { render } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import AlbumGridView from './AlbumGridView'
+
+// react-admin's Link/useListContext need a router and a store; the grid body is not under test here.
+vi.mock('react-admin', () => ({
+  linkToRecord: () => '/album/1',
+  useListContext: () => ({}),
+  Loading: () => <div data-testid="loading" />,
+}))
+describe('AlbumGridView', () => {
+  // ArtistShow renders the grid through ReferenceManyField, which passes no seed tracking.
+  it('renders without a shownSeed ref', () => {
+    expect(() =>
+      render(<AlbumGridView data={{}} ids={[]} basePath="/album" width="md" />),
+    ).not.toThrow()
+  })
+})
diff --git a/ui/src/album/AlbumList.jsx b/ui/src/album/AlbumList.jsx
index cd73fa0c3..3cb8a648e 100644
--- a/ui/src/album/AlbumList.jsx
+++ b/ui/src/album/AlbumList.jsx
@@ -1,4 +1,4 @@
-import { cloneElement } from 'react'
+import { cloneElement, useRef } from 'react'
 import { useSelector } from 'react-redux'
 import { Redirect, useLocation } from 'react-router-dom'
 import {
@@ -30,6 +30,7 @@ import {
 import AlbumListActions from './AlbumListActions'
 import AlbumTableView from './AlbumTableView'
 import AlbumGridView from './AlbumGridView'
+import { useRollChanged } from './useRollChanged'
 import albumLists from './albumLists'
 import {
   getStoredDefaultView,
@@ -186,9 +187,10 @@ const AlbumListTitle = ({ albumListType }) => {
   return <Title subTitle={title} args={{ smart_count: 2 }} />
 }
 
-const AlbumListPagination = ({ albumListType, ...rest }) => {
+const AlbumListPagination = ({ albumListType, seed, shownSeed, ...rest }) => {
   const { loading } = useListContext()
-  if (loading && albumListType === 'random') {
+  const rerolling = useRollChanged(shownSeed, seed, loading)
+  if (rerolling && albumListType === 'random') {
     return null
   }
   return <Pagination {...rest} />
@@ -198,6 +200,7 @@ const randomStartingSeed = Math.random().toString()
 
 const AlbumList = (props) => {
   const { width } = props
+  const shownSeed = useRef(null)
   const albumView = useSelector((state) => state.albumView)
   const [perPage, perPageOptions] = useAlbumsPerPage(width)
   const location = useLocation()
@@ -260,13 +263,20 @@ const AlbumList = (props) => {
           <AlbumListPagination
             rowsPerPageOptions={perPageOptions}
             albumListType={albumListType}
+            seed={seed}
+            shownSeed={shownSeed}
           />
         }
         title={<AlbumListTitle albumListType={albumListType} />}
       >
         <ScrollRestorer>
           {albumView.grid ? (
-            <AlbumGridView albumListType={albumListType} {...props} />
+            <AlbumGridView
+              albumListType={albumListType}
+              seed={seed}
+              shownSeed={shownSeed}
+              {...props}
+            />
           ) : (
             <AlbumTableView {...props} />
           )}
diff --git a/ui/src/album/AlbumTableView.jsx b/ui/src/album/AlbumTableView.jsx
index d1a89d512..051d5988e 100644
--- a/ui/src/album/AlbumTableView.jsx
+++ b/ui/src/album/AlbumTableView.jsx
@@ -14,7 +14,7 @@ import { makeStyles } from '@material-ui/core/styles'
 import { useDrag } from 'react-dnd'
 import {
   ArtistLinkField,
-  CoverArtAvatar,
+  ArtworkAvatar,
   DurationField,
   RangeField,
   SimpleList,
@@ -164,7 +164,7 @@ const AlbumTableView = ({
       )}
       leftIcon={(r) => (
         <span style={{ marginRight: '8px' }}>
-          <CoverArtAvatar record={r} variant="square" />
+          <ArtworkAvatar record={r} variant="square" />
         </span>
       )}
       linkType={'show'}
@@ -173,7 +173,7 @@ const AlbumTableView = ({
     />
   ) : (
     <AlbumDatagrid rowClick={'show'} classes={{ row: classes.row }} {...rest}>
-      <CoverArtAvatar source="id" variant="square" />
+      <ArtworkAvatar source="id" variant="square" />
       <TextField source="name" />
       {columns}
       <AlbumContextMenu
diff --git a/ui/src/album/useRollChanged.jsx b/ui/src/album/useRollChanged.jsx
new file mode 100644
index 000000000..b364bdc6b
--- /dev/null
+++ b/ui/src/album/useRollChanged.jsx
@@ -0,0 +1,13 @@
+import { useRef } from 'react'
+
+// Reports that the albums on screen belong to a different roll than the one loading: only a seed
+// change is a re-roll. `shown` is owned above the grid, which a refresh remounts under the new seed.
+export const useRollChanged = (shown, seed, loading) => {
+  const wasLoading = useRef(loading)
+
+  if (!loading && (shown.current === null || wasLoading.current)) {
+    shown.current = seed
+  }
+  wasLoading.current = loading
+  return shown.current !== seed
+}
diff --git a/ui/src/album/useRollChanged.test.jsx b/ui/src/album/useRollChanged.test.jsx
new file mode 100644
index 000000000..0745efb08
--- /dev/null
+++ b/ui/src/album/useRollChanged.test.jsx
@@ -0,0 +1,73 @@
+import { renderHook } from '@testing-library/react-hooks'
+import { describe, it, expect } from 'vitest'
+import { useRollChanged } from './useRollChanged'
+
+describe('useRollChanged', () => {
+  // Passing `shown` in mimics AlbumList owning it across a remount.
+  const setup = (props, shown = { current: null }) => ({
+    shown,
+    ...renderHook(({ seed, loading }) => useRollChanged(shown, seed, loading), {
+      initialProps: props,
+    }),
+  })
+
+  it('reports a change while a load is in flight on a fresh mount', () => {
+    const { result } = setup({ seed: 's1', loading: true })
+    expect(result.current).toBe(true)
+  })
+
+  it('reports no change when mounted with data already in hand', () => {
+    const { result } = setup({ seed: 's1', loading: false })
+    expect(result.current).toBe(false)
+  })
+
+  it('stays false while loading a filter change on the same roll', () => {
+    const { result, rerender } = setup({ seed: 's1', loading: false })
+    rerender({ seed: 's1', loading: true })
+    expect(result.current).toBe(false)
+  })
+
+  it('goes true while loading after the seed changes', () => {
+    const { result, rerender } = setup({ seed: 's1', loading: false })
+    rerender({ seed: 's2', loading: true })
+    expect(result.current).toBe(true)
+  })
+
+  it('clears once the new roll has loaded', () => {
+    const { result, rerender } = setup({ seed: 's1', loading: false })
+    rerender({ seed: 's2', loading: true })
+    expect(result.current).toBe(true)
+    rerender({ seed: 's2', loading: false })
+    expect(result.current).toBe(false)
+  })
+
+  // The seed can land a render before loading flips; the new roll must not be recorded as shown.
+  it('still reports a change when the seed arrives before loading starts', () => {
+    const { result, rerender } = setup({ seed: 's1', loading: false })
+    rerender({ seed: 's2', loading: false })
+    expect(result.current).toBe(true)
+  })
+
+  // Refresh remounts the grid under the new seed a render before the refetch starts.
+  it('reports a change when a refresh remounts the grid before loading starts', () => {
+    const { shown, unmount } = setup({ seed: 's1', loading: false })
+    expect(shown.current).toBe('s1')
+    unmount()
+
+    const remounted = setup({ seed: 's2', loading: false }, shown)
+    expect(remounted.result.current).toBe(true)
+
+    remounted.rerender({ seed: 's2', loading: true })
+    expect(remounted.result.current).toBe(true)
+    remounted.rerender({ seed: 's2', loading: false })
+    expect(remounted.result.current).toBe(false)
+  })
+
+  it('reports no change when a remount keeps the same roll', () => {
+    const { shown, unmount } = setup({ seed: 's1', loading: false })
+    unmount()
+
+    const remounted = setup({ seed: 's1', loading: false }, shown)
+    expect(remounted.result.current).toBe(false)
+  })
+})
diff --git a/ui/src/artist/ArtistList.jsx b/ui/src/artist/ArtistList.jsx
index 4559aa8e6..f4147221e 100644
--- a/ui/src/artist/ArtistList.jsx
+++ b/ui/src/artist/ArtistList.jsx
@@ -22,7 +22,7 @@ import { useDrag } from 'react-dnd'
 import clsx from 'clsx'
 import {
   ArtistContextMenu,
-  CoverArtAvatar,
+  ArtworkAvatar,
   List,
   useGetHandleArtistClick,
   RatingField,
@@ -173,7 +173,7 @@ const ArtistListView = ({ hasShow, hasEdit, hasList, width, ...rest }) => {
     />
   ) : (
     <ArtistDatagrid rowClick={handleArtistLink} classes={{ row: classes.row }}>
-      <CoverArtAvatar source="id" />
+      <ArtworkAvatar source="id" />
       <TextField source="name" />
       <FunctionField
         source="albumCount"
diff --git a/ui/src/artist/ArtistSimpleList.jsx b/ui/src/artist/ArtistSimpleList.jsx
index 55b6b1a0b..9dcae0470 100644
--- a/ui/src/artist/ArtistSimpleList.jsx
+++ b/ui/src/artist/ArtistSimpleList.jsx
@@ -8,7 +8,7 @@ import ListItemSecondaryAction from '@material-ui/core/ListItemSecondaryAction'
 import ListItemText from '@material-ui/core/ListItemText'
 import { makeStyles } from '@material-ui/core/styles'
 import { sanitizeListRestProps } from 'react-admin'
-import { ArtistContextMenu, CoverArtAvatar, RatingField } from '../common'
+import { ArtistContextMenu, ArtworkAvatar, RatingField } from '../common'
 import config from '../config'
 
 const useStyles = makeStyles(
@@ -49,7 +49,7 @@ const ArtistSimpleList = ({
               <span key={id} onClick={() => linkType(id)}>
                 <ListItem className={classes.listItem} button={true}>
                   <ListItemAvatar>
-                    <CoverArtAvatar record={data[id]} />
+                    <ArtworkAvatar record={data[id]} />
                   </ListItemAvatar>
                   <ListItemText
                     style={{ marginLeft: '8px' }}
diff --git a/ui/src/artist/DesktopArtistDetails.jsx b/ui/src/artist/DesktopArtistDetails.jsx
index dda761097..9269dc8d7 100644
--- a/ui/src/artist/DesktopArtistDetails.jsx
+++ b/ui/src/artist/DesktopArtistDetails.jsx
@@ -3,20 +3,15 @@ import { Typography, Collapse } from '@material-ui/core'
 import { makeStyles } from '@material-ui/core'
 import Card from '@material-ui/core/Card'
 import CardContent from '@material-ui/core/CardContent'
-import CardMedia from '@material-ui/core/CardMedia'
 import ArtistExternalLinks from './ArtistExternalLink'
 import config from '../config'
-import {
-  LoveButton,
-  RatingField,
-  ImageUploadOverlay,
-  useImageLoadingState,
-} from '../common'
+import { LoveButton, RatingField, ImageUploadOverlay } from '../common'
 import Lightbox from 'react-image-lightbox'
 import ExpandInfoDialog from '../dialogs/ExpandInfoDialog'
 import AlbumInfo from '../album/AlbumInfo'
 import subsonic from '../subsonic'
 import { SafeHTML } from '../common/SafeHTML'
+import { Artwork } from '../common/Artwork'
 
 const useStyles = makeStyles(
   (theme) => ({
@@ -49,9 +44,6 @@ const useStyles = makeStyles(
       transition: 'opacity 0.3s ease-in-out',
       objectFit: 'cover',
     },
-    coverLoading: {
-      opacity: 0.5,
-    },
     artistImage: {
       maxHeight: '12rem',
       minHeight: '12rem',
@@ -91,35 +83,18 @@ const DesktopArtistDetails = ({ artistInfo, record, biography }) => {
   const [expanded, setExpanded] = useState(false)
   const classes = useStyles()
   const title = record.name
-  const {
-    imageLoading,
-    imageError,
-    isLightboxOpen,
-    handleImageLoad,
-    handleImageError,
-    handleOpenLightbox,
-    handleCloseLightbox,
-  } = useImageLoadingState(record.id)
+  const [isLightboxOpen, setLightboxOpen] = useState(false)
 
   return (
     <div className={classes.root}>
       <Card className={classes.artistDetail}>
         <Card className={classes.artistImage}>
-          {artistInfo && (
-            <CardMedia
-              key={record.id}
-              component="img"
-              src={subsonic.getCoverArtUrl(record, config.uiCoverArtSize)}
-              className={`${classes.cover} ${imageLoading ? classes.coverLoading : ''}`}
-              onClick={handleOpenLightbox}
-              onLoad={handleImageLoad}
-              onError={handleImageError}
-              title={title}
-              style={{
-                cursor: imageError ? 'default' : 'pointer',
-              }}
-            />
-          )}
+          <Artwork
+            record={record}
+            className={classes.cover}
+            title={title}
+            onClick={() => setLightboxOpen(true)}
+          />
           <ImageUploadOverlay
             entityType="artist"
             entityId={record.id}
@@ -175,13 +150,13 @@ const DesktopArtistDetails = ({ artistInfo, record, biography }) => {
             )}
           </Typography>
         </div>
-        {isLightboxOpen && !imageError && (
+        {isLightboxOpen && (
           <Lightbox
             imagePadding={50}
             animationDuration={200}
             imageTitle={record.name}
             mainSrc={subsonic.getCoverArtUrl(record)}
-            onCloseRequest={handleCloseLightbox}
+            onCloseRequest={() => setLightboxOpen(false)}
           />
         )}
       </Card>
diff --git a/ui/src/artist/MobileArtistDetails.jsx b/ui/src/artist/MobileArtistDetails.jsx
index e82d4c28a..0925b6f10 100644
--- a/ui/src/artist/MobileArtistDetails.jsx
+++ b/ui/src/artist/MobileArtistDetails.jsx
@@ -2,17 +2,12 @@ import React, { useState } from 'react'
 import { Typography, Collapse } from '@material-ui/core'
 import { makeStyles } from '@material-ui/core/styles'
 import Card from '@material-ui/core/Card'
-import CardMedia from '@material-ui/core/CardMedia'
 import config from '../config'
-import {
-  LoveButton,
-  RatingField,
-  ImageUploadOverlay,
-  useImageLoadingState,
-} from '../common'
+import { LoveButton, RatingField, ImageUploadOverlay } from '../common'
 import Lightbox from 'react-image-lightbox'
 import subsonic from '../subsonic'
 import { SafeHTML } from '../common/SafeHTML'
+import { Artwork } from '../common/Artwork'
 
 const useStyles = makeStyles(
   (theme) => ({
@@ -60,9 +55,6 @@ const useStyles = makeStyles(
       transition: 'opacity 0.3s ease-in-out',
       objectFit: 'cover',
     },
-    coverLoading: {
-      opacity: 0.5,
-    },
     artistImage: {
       marginLeft: '1em',
       maxHeight: '7rem',
@@ -88,41 +80,24 @@ const useStyles = makeStyles(
   { name: 'NDMobileArtistDetails' },
 )
 
-const MobileArtistDetails = ({ artistInfo, biography, record }) => {
+const MobileArtistDetails = ({ biography, record }) => {
   const img = subsonic.getCoverArtUrl(record, 800)
   const [expanded, setExpanded] = useState(false)
   const classes = useStyles({ img, expanded })
   const title = record.name
-  const {
-    imageLoading,
-    imageError,
-    isLightboxOpen,
-    handleImageLoad,
-    handleImageError,
-    handleOpenLightbox,
-    handleCloseLightbox,
-  } = useImageLoadingState(record.id)
+  const [isLightboxOpen, setLightboxOpen] = useState(false)
 
   return (
     <>
       <div className={classes.root}>
         <div className={classes.bgContainer}>
           <Card className={classes.artistImage}>
-            {artistInfo && (
-              <CardMedia
-                key={record.id}
-                component="img"
-                src={subsonic.getCoverArtUrl(record, config.uiCoverArtSize)}
-                className={`${classes.cover} ${imageLoading ? classes.coverLoading : ''}`}
-                onClick={handleOpenLightbox}
-                onLoad={handleImageLoad}
-                onError={handleImageError}
-                title={title}
-                style={{
-                  cursor: imageError ? 'default' : 'pointer',
-                }}
-              />
-            )}
+            <Artwork
+              record={record}
+              className={classes.cover}
+              title={title}
+              onClick={() => setLightboxOpen(true)}
+            />
             <ImageUploadOverlay
               entityType="artist"
               entityId={record.id}
@@ -165,13 +140,13 @@ const MobileArtistDetails = ({ artistInfo, biography, record }) => {
           </Typography>
         </Collapse>
       </div>
-      {isLightboxOpen && !imageError && (
+      {isLightboxOpen && (
         <Lightbox
           imagePadding={50}
           animationDuration={200}
           imageTitle={record.name}
           mainSrc={img}
-          onCloseRequest={handleCloseLightbox}
+          onCloseRequest={() => setLightboxOpen(false)}
         />
       )}
     </>
diff --git a/ui/src/common/Artwork.jsx b/ui/src/common/Artwork.jsx
new file mode 100644
index 000000000..21ac5e07b
--- /dev/null
+++ b/ui/src/common/Artwork.jsx
@@ -0,0 +1,127 @@
+import { useEffect, useRef, useState } from 'react'
+import PropTypes from 'prop-types'
+import clsx from 'clsx'
+import { makeStyles } from '@material-ui/core/styles'
+import config from '../config'
+import subsonic from '../subsonic'
+import { useImageUrl } from './useImageUrl'
+import { ThumbHashCanvas } from './ThumbHashCanvas'
+
+// Drives both the CSS transition and the timer that retires the placeholder, so they cannot drift.
+const fadeMs = 150
+
+const useStyles = makeStyles({
+  // className supplies the size and shape; overflow:hidden clips the fills to it.
+  root: {
+    position: 'relative',
+    display: 'inline-flex',
+    overflow: 'hidden',
+  },
+  fill: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    width: '100%',
+    height: '100%',
+  },
+  img: {
+    opacity: 0,
+    transition: `opacity ${fadeMs}ms ease-out`,
+    '@media (prefers-reduced-motion: reduce)': { transition: 'none' },
+  },
+  imgVisible: { opacity: 1 },
+  // Already-decoded blobs appear at once: fading them in would re-animate on every remount.
+  imgInstant: { opacity: 1, transition: 'none' },
+})
+
+// Renders a cover through the shared useImageUrl blob cache, so it survives remounts without
+// re-fetching. The image mounts only once its blob is ready, so it never renders broken.
+export const Artwork = ({
+  record,
+  size = config.uiCoverArtSize,
+  square = false,
+  fit = 'cover',
+  className,
+  title,
+  onClick,
+}) => {
+  const classes = useStyles()
+  const url = record ? subsonic.getCoverArtUrl(record, size, square) : ''
+  const { imgUrl, fromCache } = useImageUrl(url)
+
+  const [decoded, setDecoded] = useState(false)
+  const [faded, setFaded] = useState(false)
+  const frame = useRef(0)
+  useEffect(() => {
+    setDecoded(false)
+    setFaded(false)
+    return () => cancelAnimationFrame(frame.current)
+  }, [url])
+
+  // Two frames: a blob decodes from memory, so onLoad can beat the first paint of opacity 0,
+  // leaving the transition no start value and popping some tiles in while others fade.
+  const handleLoad = () => {
+    frame.current = requestAnimationFrame(() => {
+      frame.current = requestAnimationFrame(() => setDecoded(true))
+    })
+  }
+
+  // Timer, not transitionend: under prefers-reduced-motion there is no transition to end.
+  useEffect(() => {
+    if (!decoded || faded) return undefined
+    const timer = setTimeout(() => setFaded(true), fadeMs)
+    return () => clearTimeout(timer)
+  }, [decoded, faded])
+
+  if (!record) return null
+
+  // A blob already cached paints on the first frame, so it skips the fade.
+  const instant = fromCache
+  // Kept mounted until the fade ends; swapping on blob arrival would flash an empty container.
+  const showPlaceholder = !!record.thumbHash && !instant && !faded
+  // A square request is padded, not cropped, so `contain` keeps placeholder and image aligned.
+  const effectiveFit = square ? 'contain' : fit
+  const ratio = record.imageWidth / record.imageHeight
+  const handleClick = imgUrl && onClick ? onClick : undefined
+  return (
+    <div
+      className={clsx(classes.root, className)}
+      onClick={handleClick}
+      style={{ cursor: handleClick ? 'pointer' : 'default' }}
+    >
+      {showPlaceholder && (
+        <ThumbHashCanvas
+          hash={record.thumbHash}
+          ratio={ratio}
+          fit={effectiveFit}
+          className={classes.fill}
+        />
+      )}
+      {imgUrl && (
+        <img
+          src={imgUrl}
+          alt={title}
+          title={title}
+          className={clsx(
+            classes.fill,
+            classes.img,
+            instant && classes.imgInstant,
+            decoded && classes.imgVisible,
+          )}
+          style={{ objectFit: effectiveFit }}
+          onLoad={handleLoad}
+        />
+      )}
+    </div>
+  )
+}
+
+Artwork.propTypes = {
+  record: PropTypes.object,
+  size: PropTypes.number,
+  square: PropTypes.bool,
+  fit: PropTypes.oneOf(['cover', 'contain']),
+  className: PropTypes.string,
+  title: PropTypes.string,
+  onClick: PropTypes.func,
+}
diff --git a/ui/src/common/Artwork.test.jsx b/ui/src/common/Artwork.test.jsx
new file mode 100644
index 000000000..18b3c916f
--- /dev/null
+++ b/ui/src/common/Artwork.test.jsx
@@ -0,0 +1,232 @@
+import { render, fireEvent, act } from '@testing-library/react'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('./useImageUrl', () => ({ useImageUrl: vi.fn() }))
+vi.mock('../subsonic', () => ({
+  default: {
+    // Mirrors the real hash suffix, so a refreshed record yields a different URL.
+    getCoverArtUrl: (record) =>
+      '/rest/getCoverArt?id=al-1' +
+      (record.imageHash ? `_${record.imageHash}` : ''),
+  },
+}))
+vi.mock('../config', () => ({ default: { uiCoverArtSize: 300 } }))
+
+import { useImageUrl } from './useImageUrl'
+import { Artwork } from './Artwork'
+
+const withArt = {
+  id: 'al-1',
+  name: 'Album',
+  thumbHash: 'H/gNBxpwh4dwd3eIiHd3iHeHeJ+dcH8I',
+}
+
+describe('Artwork', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // jsdom has no 2D context; stub it so ThumbHashCanvas bails cleanly without console noise
+    HTMLCanvasElement.prototype.getContext = vi.fn(() => null)
+  })
+
+  it('renders nothing without a record', () => {
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: false })
+    const { container } = render(<Artwork record={null} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('shows the placeholder and no <img> while loading', () => {
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+    const { container } = render(<Artwork record={withArt} title="Album" />)
+    expect(container.querySelector('canvas')).not.toBeNull()
+    expect(container.querySelector('img')).toBeNull()
+  })
+
+  it('shows neither a broken <img> nor a canvas while loading a record with no thumbhash', () => {
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+    const { container } = render(<Artwork record={{ id: 'al-2', name: 'X' }} />)
+    expect(container.querySelector('img')).toBeNull()
+    expect(container.querySelector('canvas')).toBeNull()
+  })
+
+  // The placeholder has to land exactly where the image will, or it jumps when the image swaps in.
+  it('shapes the placeholder like the artwork and fits it like the image', () => {
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+    const nonSquare = { ...withArt, imageWidth: 1200, imageHeight: 800 }
+    const { container } = render(
+      <Artwork record={nonSquare} fit="contain" title="Album" />,
+    )
+    const canvas = container.querySelector('canvas')
+    expect(canvas.width).toBe(32)
+    expect(canvas.height).toBe(21)
+    expect(canvas.style.objectFit).toBe('contain')
+  })
+
+  // A square request is padded, not cropped, so the placeholder has to letterbox with it.
+  it('letterboxes the placeholder when the server pads a non-square image to a square', () => {
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+    const nonSquare = { ...withArt, imageWidth: 1200, imageHeight: 800 }
+    const { container } = render(<Artwork record={nonSquare} square />)
+    const canvas = container.querySelector('canvas')
+    expect(canvas.width).toBe(32)
+    expect(canvas.height).toBe(21)
+    expect(canvas.style.objectFit).toBe('contain')
+  })
+
+  // The padded square is aspect-fit, so `square` overrides fit="cover" as it does for the canvas.
+  it('fits the image itself with contain when the server padded to a square', () => {
+    useImageUrl.mockReturnValue({
+      imgUrl: 'blob:abc',
+      loading: false,
+      fromCache: true,
+    })
+    const { container } = render(
+      <Artwork record={withArt} square fit="cover" title="Album" />,
+    )
+    expect(container.querySelector('img').style.objectFit).toBe('contain')
+  })
+
+  it('fills the box for square artwork, the overwhelmingly common case', () => {
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+    const sq = { ...withArt, imageWidth: 600, imageHeight: 600 }
+    const { container } = render(<Artwork record={sq} square />)
+    const canvas = container.querySelector('canvas')
+    expect(canvas.width).toBe(32)
+    expect(canvas.height).toBe(32)
+  })
+
+  // Without dimensions the placeholder falls back to the aspect the hash itself carries.
+  it('falls back to the hash own aspect when the record has no dimensions', () => {
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+    const { container } = render(<Artwork record={withArt} />)
+    const canvas = container.querySelector('canvas')
+    expect(canvas.width).toBe(32)
+    expect(canvas.height).toBe(32)
+  })
+
+  it('mounts the image only once its blob is ready', () => {
+    useImageUrl.mockReturnValue({
+      imgUrl: 'blob:abc',
+      loading: false,
+      fromCache: true,
+    })
+    const { container } = render(<Artwork record={withArt} title="Album" />)
+    const img = container.querySelector('img')
+    expect(img).not.toBeNull()
+    expect(img.getAttribute('src')).toBe('blob:abc')
+  })
+
+  it('keeps the placeholder under the image until the fade ends', () => {
+    vi.useFakeTimers()
+    try {
+      useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+      const { container, rerender } = render(<Artwork record={withArt} />)
+
+      useImageUrl.mockReturnValue({
+        imgUrl: 'blob:abc',
+        loading: false,
+        fromCache: false,
+      })
+      rerender(<Artwork record={withArt} />)
+      const img = container.querySelector('img')
+      expect(img).not.toBeNull()
+      expect(container.querySelector('canvas')).not.toBeNull()
+
+      // The clock ends the fade, not transitionend, which never fires under reduced-motion.
+      act(() => {
+        fireEvent.load(img)
+      })
+      expect(container.querySelector('canvas')).not.toBeNull()
+      act(() => {
+        fireEvent.transitionEnd(img)
+      })
+      expect(container.querySelector('canvas')).not.toBeNull()
+      // Two frames pass before the fade starts, so opacity 0 gets painted first.
+      act(() => {
+        vi.advanceTimersByTime(32)
+      })
+      expect(container.querySelector('canvas')).not.toBeNull()
+      act(() => {
+        vi.advanceTimersByTime(150)
+      })
+      expect(container.querySelector('canvas')).toBeNull()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('does not fade an image that was already cached on mount', () => {
+    useImageUrl.mockReturnValue({
+      imgUrl: 'blob:abc',
+      loading: false,
+      fromCache: true,
+    })
+    const { container } = render(<Artwork record={withArt} />)
+    expect(container.querySelector('canvas')).toBeNull()
+    expect(container.querySelector('img').className).toContain('imgInstant')
+  })
+
+  it('keeps the placeholder visible when the image never decodes', () => {
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+    const { container, rerender } = render(<Artwork record={withArt} />)
+    useImageUrl.mockReturnValue({
+      imgUrl: 'blob:abc',
+      loading: false,
+      fromCache: false,
+    })
+    rerender(<Artwork record={withArt} />)
+
+    expect(container.querySelector('canvas')).not.toBeNull()
+  })
+
+  it('fires onClick only when the image is loaded', () => {
+    const onClick = vi.fn()
+    useImageUrl.mockReturnValue({ imgUrl: null, loading: true })
+    const { container, rerender } = render(
+      <Artwork record={withArt} onClick={onClick} />,
+    )
+    container.firstChild.click()
+    expect(onClick).not.toHaveBeenCalled()
+
+    useImageUrl.mockReturnValue({
+      imgUrl: 'blob:abc',
+      loading: false,
+      fromCache: false,
+    })
+    rerender(<Artwork record={withArt} onClick={onClick} />)
+    container.firstChild.click()
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows the placeholder for a cached fetch failure, which has no blob', () => {
+    useImageUrl.mockReturnValue({
+      imgUrl: null,
+      loading: false,
+      error: true,
+      fromCache: false,
+    })
+    const { container } = render(<Artwork record={withArt} />)
+    expect(container.querySelector('img')).toBeNull()
+    expect(container.querySelector('canvas')).not.toBeNull()
+  })
+
+  it('falls back to the placeholder when a refresh swaps in an uncached hash', () => {
+    useImageUrl.mockReturnValue({
+      imgUrl: 'blob:old',
+      loading: false,
+      fromCache: true,
+    })
+    const cached = { ...withArt, imageHash: 'aaaa' }
+    const { container, rerender } = render(<Artwork record={cached} />)
+    expect(container.querySelector('canvas')).toBeNull()
+
+    useImageUrl.mockReturnValue({
+      imgUrl: null,
+      loading: true,
+      fromCache: false,
+    })
+    rerender(<Artwork record={{ ...withArt, imageHash: 'bbbb' }} />)
+
+    expect(container.querySelector('img')).toBeNull()
+    expect(container.querySelector('canvas')).not.toBeNull()
+  })
+})
diff --git a/ui/src/common/ArtworkAvatar.jsx b/ui/src/common/ArtworkAvatar.jsx
new file mode 100644
index 000000000..7691050c6
--- /dev/null
+++ b/ui/src/common/ArtworkAvatar.jsx
@@ -0,0 +1,40 @@
+import { useRecordContext } from 'react-admin'
+import { makeStyles } from '@material-ui/core/styles'
+import clsx from 'clsx'
+import config from '../config'
+import { Artwork } from './Artwork'
+
+const useStyles = makeStyles({
+  avatar: {
+    width: '55px',
+    height: '55px',
+  },
+  square: {
+    borderRadius: '4px',
+  },
+  circular: {
+    borderRadius: '50%',
+  },
+})
+
+export const ArtworkAvatar = ({ record: recordProp, variant = 'circular' }) => {
+  const classes = useStyles()
+  const recordContext = useRecordContext()
+  const record = recordProp || recordContext
+  if (!record) return null
+  const square = variant !== 'circular'
+  return (
+    <Artwork
+      record={record}
+      size={config.uiCoverArtSize}
+      square={square}
+      className={clsx(
+        classes.avatar,
+        square ? classes.square : classes.circular,
+      )}
+      title={record.name}
+    />
+  )
+}
+
+ArtworkAvatar.defaultProps = { label: '', sortable: false }
diff --git a/ui/src/common/CoverArtAvatar.jsx b/ui/src/common/CoverArtAvatar.jsx
deleted file mode 100644
index f70403774..000000000
--- a/ui/src/common/CoverArtAvatar.jsx
+++ /dev/null
@@ -1,52 +0,0 @@
-import { useRecordContext } from 'react-admin'
-import { Avatar } from '@material-ui/core'
-import { makeStyles } from '@material-ui/core/styles'
-import clsx from 'clsx'
-import config from '../config'
-import subsonic from '../subsonic'
-import { useImageUrl } from './useImageUrl'
-
-const useStyles = makeStyles({
-  avatar: {
-    width: '55px',
-    height: '55px',
-  },
-  avatarEmpty: {
-    backgroundColor: 'transparent',
-  },
-  square: {
-    borderRadius: '4px',
-  },
-})
-
-export const CoverArtAvatar = ({
-  record: recordProp,
-  variant = 'circular',
-}) => {
-  const classes = useStyles()
-  const recordContext = useRecordContext()
-  const record = recordProp || recordContext
-  const square = variant !== 'circular'
-  const url = record
-    ? subsonic.getCoverArtUrl(record, config.uiCoverArtSize, square)
-    : null
-  const { imgUrl } = useImageUrl(url)
-  if (!record) return null
-  return (
-    <Avatar
-      src={imgUrl || undefined}
-      variant={variant}
-      className={clsx(
-        classes.avatar,
-        square && classes.square,
-        !imgUrl && classes.avatarEmpty,
-      )}
-      alt={record.name}
-    >
-      {/* Empty child prevents default person icon while loading */}
-      {!imgUrl && <span />}
-    </Avatar>
-  )
-}
-
-CoverArtAvatar.defaultProps = { label: '', sortable: false }
diff --git a/ui/src/common/ThumbHashCanvas.jsx b/ui/src/common/ThumbHashCanvas.jsx
new file mode 100644
index 000000000..03d349313
--- /dev/null
+++ b/ui/src/common/ThumbHashCanvas.jsx
@@ -0,0 +1,75 @@
+import { useEffect, useRef } from 'react'
+import PropTypes from 'prop-types'
+import { decode, naturalSize } from '../utils/thumbhash'
+
+// A thumbhash carries no detail beyond a few dozen pixels; CSS upscales the canvas.
+const DECODE_SIZE = 32
+
+// bitmapSize prefers the artwork's true ratio, falling back to the aspect the hash itself carries,
+// which is quantised to a ratio of small integers and so only approximates the image.
+const bitmapSize = (hash, ratio) => {
+  if (!(ratio > 0) || !Number.isFinite(ratio)) {
+    try {
+      return naturalSize(hash)
+    } catch {
+      return { width: DECODE_SIZE, height: DECODE_SIZE }
+    }
+  }
+  return ratio >= 1
+    ? {
+        width: DECODE_SIZE,
+        height: Math.max(1, Math.round(DECODE_SIZE / ratio)),
+      }
+    : {
+        width: Math.max(1, Math.round(DECODE_SIZE * ratio)),
+        height: DECODE_SIZE,
+      }
+}
+
+export const ThumbHashCanvas = ({ hash, ratio, fit, className, style }) => {
+  const canvasRef = useRef(null)
+  const { width, height } = bitmapSize(hash, ratio)
+
+  useEffect(() => {
+    if (!hash || !canvasRef.current) {
+      return
+    }
+    const ctx = canvasRef.current.getContext('2d')
+    if (!ctx) {
+      return
+    }
+    // Clear first so a hash change that fails to decode never leaves a stale frame.
+    ctx.clearRect(0, 0, width, height)
+    try {
+      const pixels = decode(hash, width, height)
+      const imageData = ctx.createImageData(width, height)
+      imageData.data.set(pixels)
+      ctx.putImageData(imageData, 0, 0)
+    } catch {
+      // A malformed hash simply leaves the canvas blank.
+    }
+  }, [hash, width, height])
+
+  if (!hash) {
+    return null
+  }
+  return (
+    <canvas
+      ref={canvasRef}
+      width={width}
+      height={height}
+      className={className}
+      style={{ ...style, objectFit: fit }}
+      aria-hidden="true"
+    />
+  )
+}
+
+ThumbHashCanvas.propTypes = {
+  hash: PropTypes.string,
+  // Aspect ratio (width / height) of the image this stands in for; the hash's own when omitted.
+  ratio: PropTypes.number,
+  fit: PropTypes.oneOf(['cover', 'contain']),
+  className: PropTypes.string,
+  style: PropTypes.object,
+}
diff --git a/ui/src/common/ThumbHashCanvas.test.jsx b/ui/src/common/ThumbHashCanvas.test.jsx
new file mode 100644
index 000000000..b1f53fe5c
--- /dev/null
+++ b/ui/src/common/ThumbHashCanvas.test.jsx
@@ -0,0 +1,95 @@
+import { render } from '@testing-library/react'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { ThumbHashCanvas } from './ThumbHashCanvas'
+
+// Golden hashes from core/artwork/thumbhash/testdata/golden.json.
+const SQUARE = 'H/gNBxpwh4dwd3eIiHd3iHeHeJ+dcH8I'
+const LANDSCAPE = '3wcOFJpwh4eBh3d4iIePgAj3hw=='
+
+describe('ThumbHashCanvas', () => {
+  // jsdom has no real 2D context; stub it (tracked) so specs can assert the draw path ran.
+  let ctxMock
+  let getContextSpy
+  beforeEach(() => {
+    ctxMock = {
+      clearRect: vi.fn(),
+      createImageData: vi.fn((w, h) => ({
+        data: new Uint8ClampedArray(w * h * 4),
+      })),
+      putImageData: vi.fn(),
+    }
+    getContextSpy = vi
+      .spyOn(HTMLCanvasElement.prototype, 'getContext')
+      .mockReturnValue(ctxMock)
+  })
+  afterEach(() => {
+    getContextSpy.mockRestore()
+  })
+
+  it('renders nothing without a hash', () => {
+    const { container } = render(<ThumbHashCanvas hash="" />)
+    expect(container.querySelector('canvas')).toBeNull()
+  })
+
+  it('decodes a valid hash and draws non-trivial pixel data', () => {
+    const { container } = render(<ThumbHashCanvas hash={SQUARE} />)
+    expect(container.querySelector('canvas')).not.toBeNull()
+    expect(ctxMock.putImageData).toHaveBeenCalledTimes(1)
+    const [imageData] = ctxMock.putImageData.mock.calls[0]
+    expect(imageData.data.some((byte) => byte !== 0)).toBe(true)
+  })
+
+  it('decodes into a bitmap shaped like the image, so the blur is not distorted', () => {
+    const { container } = render(
+      <ThumbHashCanvas hash={SQUARE} ratio={1200 / 800} />,
+    )
+    expect(ctxMock.createImageData).toHaveBeenCalledWith(32, 21)
+    const canvas = container.querySelector('canvas')
+    expect(canvas.width).toBe(32)
+    expect(canvas.height).toBe(21)
+  })
+
+  it('shapes a portrait ratio the other way round', () => {
+    render(<ThumbHashCanvas hash={SQUARE} ratio={0.5} />)
+    expect(ctxMock.createImageData).toHaveBeenCalledWith(16, 32)
+  })
+
+  it('never collapses an extreme ratio to a zero-sized bitmap', () => {
+    render(<ThumbHashCanvas hash={SQUARE} ratio={200} />)
+    expect(ctxMock.createImageData).toHaveBeenCalledWith(32, 1)
+  })
+
+  // Unlike a blurhash, a thumbhash carries its own approximate aspect, so an unknown ratio
+  // falls back to that rather than to a square.
+  it('falls back to the hash own aspect when the ratio is unknown', () => {
+    render(<ThumbHashCanvas hash={LANDSCAPE} ratio={0} />)
+    expect(ctxMock.createImageData).toHaveBeenCalledWith(32, 18)
+  })
+
+  it('applies the object-fit it is given, so it lands where the image will', () => {
+    const { container } = render(
+      <ThumbHashCanvas hash={SQUARE} ratio={1.5} fit="contain" />,
+    )
+    expect(container.querySelector('canvas').style.objectFit).toBe('contain')
+  })
+
+  it('renders a canvas without throwing on a malformed hash, and draws nothing', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { container } = render(
+      <ThumbHashCanvas hash="!!!not-a-thumbhash!!!" />,
+    )
+    expect(container.querySelector('canvas')).not.toBeNull()
+    expect(ctxMock.putImageData).not.toHaveBeenCalled()
+    spy.mockRestore()
+  })
+
+  it('clears the canvas when a hash change fails to decode', () => {
+    const { rerender } = render(<ThumbHashCanvas hash={SQUARE} />)
+    expect(ctxMock.putImageData).toHaveBeenCalledTimes(1)
+
+    rerender(<ThumbHashCanvas hash="!!!not-a-thumbhash!!!" />)
+
+    expect(ctxMock.clearRect).toHaveBeenCalledTimes(2)
+    expect(ctxMock.putImageData).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/ui/src/common/index.js b/ui/src/common/index.js
index c88ea3e9c..7b5b376f3 100644
--- a/ui/src/common/index.js
+++ b/ui/src/common/index.js
@@ -46,6 +46,6 @@ export * from './ParticipantsInfo'
 export * from './OverflowTooltip'
 export * from './useSearchRefocus'
 export * from './ImageUploadOverlay'
-export * from './CoverArtAvatar'
+export * from './ArtworkAvatar'
 export * from './useImageLoadingState'
 export * from './useImageUrl'
diff --git a/ui/src/common/useImageUrl.js b/ui/src/common/useImageUrl.js
index 9bcc70d74..8a7f2bcc7 100644
--- a/ui/src/common/useImageUrl.js
+++ b/ui/src/common/useImageUrl.js
@@ -43,6 +43,18 @@ export const useImageUrl = (url) => {
   const [error, setError] = useState(cached?.error || false)
   const abortedRef = useRef(false)
 
+  // Resync during render: otherwise imgUrl holds the previous url's blob for one render, so only
+  // fromCache can answer "already cached" - and a remembered failure has no blob to paint.
+  const [fromCache, setFromCache] = useState(!!cached?.blobUrl)
+  const [trackedUrl, setTrackedUrl] = useState(url)
+  if (trackedUrl !== url) {
+    setTrackedUrl(url)
+    setImgUrl(cached?.blobUrl || null)
+    setLoading(!!url && !cached)
+    setError(cached?.error || false)
+    setFromCache(!!cached?.blobUrl)
+  }
+
   useEffect(() => {
     abortedRef.current = false
 
@@ -140,5 +152,5 @@ export const useImageUrl = (url) => {
     }
   }, [url])
 
-  return { imgUrl, loading, error }
+  return { imgUrl, loading, error, fromCache }
 }
diff --git a/ui/src/common/useImageUrl.test.js b/ui/src/common/useImageUrl.test.js
index 976317105..818732d06 100644
--- a/ui/src/common/useImageUrl.test.js
+++ b/ui/src/common/useImageUrl.test.js
@@ -200,6 +200,7 @@ describe('useImageUrl', () => {
     expect(global.fetch).toHaveBeenCalledTimes(1)
     expect(result2.current.imgUrl).toBe('blob:mock-url')
     expect(result2.current.loading).toBe(false)
+    expect(result2.current.fromCache).toBe(true)
   })
 
   it('should cache errors and not re-fetch broken URLs', async () => {
@@ -230,5 +231,7 @@ describe('useImageUrl', () => {
     expect(result2.current.error).toBe(true)
     expect(result2.current.imgUrl).toBeNull()
     expect(result2.current.loading).toBe(false)
+    // A remembered failure has no blob, so callers must not treat it as instantly painted.
+    expect(result2.current.fromCache).toBe(false)
   })
 })
diff --git a/ui/src/common/useResourceRefresh.jsx b/ui/src/common/useResourceRefresh.jsx
index eabff6f92..b59ae8e88 100644
--- a/ui/src/common/useResourceRefresh.jsx
+++ b/ui/src/common/useResourceRefresh.jsx
@@ -63,6 +63,9 @@ import { useRefresh, useDataProvider } from 'react-admin'
  * - Global refresh: { '*': '*' } or { someResource: ['*'] }
  * - Specific resources: { album: ['id1', 'id2'], song: ['id3'] }
  */
+// Resources whose records are media files, and so inherit their album's artwork.
+const trackResources = ['song', 'playlistTrack']
+
 export const useResourceRefresh = (...visibleResources) => {
   const [lastTime, setLastTime] = useState(Date.now())
   const refresh = useRefresh()
@@ -70,6 +73,7 @@ export const useResourceRefresh = (...visibleResources) => {
   const refreshData = useSelector(
     (state) => state.activity?.refresh || { lastReceived: lastTime },
   )
+  const loadedResources = useSelector((state) => state.admin?.resources)
   const { resources, lastReceived } = refreshData
 
   if (lastReceived <= lastTime) {
@@ -77,21 +81,49 @@ export const useResourceRefresh = (...visibleResources) => {
   }
   setLastTime(lastReceived)
 
-  if (
+  const isWatched = (r) =>
+    visibleResources.length === 0 || visibleResources.includes(r)
+  // A wildcard on a resource this component does not show is somebody else's business: reloading
+  // the page for it throws away the list the user is looking at.
+  const hasWildcard =
     resources &&
     (resources['*'] === '*' ||
-      Object.values(resources).find((v) => v.find((v2) => v2 === '*')))
-  ) {
+      Object.entries(resources).some(
+        ([r, ids]) => isWatched(r) && ids.includes?.('*'),
+      ))
+
+  if (hasWildcard) {
     refresh()
     return
   }
-  if (resources) {
-    Object.keys(resources).forEach((r) => {
-      if (visibleResources.length === 0 || visibleResources?.includes(r)) {
-        if (resources[r]?.length > 0) {
-          dataProvider.getMany(r, { ids: resources[r] })
+  if (!resources) {
+    return
+  }
+  Object.keys(resources).forEach((r) => {
+    if (isWatched(r)) {
+      if (resources[r]?.length > 0) {
+        // Only refetch records already in the store; ones the UI never loaded will
+        // arrive fresh (with the new artwork) when navigated to, so fetching them is wasteful.
+        const loaded = loadedResources?.[r]?.data || {}
+        const ids = resources[r].filter((id) => loaded[id] !== undefined)
+        if (ids.length > 0) {
+          dataProvider.getMany(r, { ids })
         }
       }
+    }
+  })
+
+  // A track with no art of its own is served its album's, so an album's new coverArt id moves its
+  // tracks' too. The dependent ids are unbounded server-side, but the store knows which are loaded.
+  if (resources.album?.length > 0) {
+    const albumIds = new Set(resources.album)
+    trackResources.filter(isWatched).forEach((r) => {
+      const ids = Object.values(loadedResources?.[r]?.data || {})
+        .filter((t) => albumIds.has(t?.albumId))
+        .map((t) => t.id)
+      if (ids.length > 0) {
+        dataProvider.getMany(r, { ids })
+      }
     })
   }
 }
diff --git a/ui/src/common/useResourceRefresh.test.js b/ui/src/common/useResourceRefresh.test.js
index eabd478db..ccd729836 100644
--- a/ui/src/common/useResourceRefresh.test.js
+++ b/ui/src/common/useResourceRefresh.test.js
@@ -38,6 +38,27 @@ describe('useResourceRefresh', () => {
   const useDataProviderMock = () => ({ getMany })
   let lastTime
 
+  // Applies each real selector against a constructed store, so both useSelector
+  // calls in the hook (refresh payload + loaded records) resolve correctly.
+  const mockStore = ({ refresh: refreshPayload, loaded = {} }) => {
+    const state = {
+      activity: { refresh: refreshPayload },
+      admin: { resources: loaded },
+    }
+    vi.spyOn(Redux, 'useSelector').mockImplementation((selector) =>
+      selector(state),
+    )
+  }
+
+  // Turns id lists into the react-admin store shape: { album: { data: { 'al-1': {...} } } }
+  const asStore = (byResource) =>
+    Object.fromEntries(
+      Object.entries(byResource).map(([r, ids]) => [
+        r,
+        { data: Object.fromEntries(ids.map((id) => [id, { id }])) },
+      ]),
+    )
+
   beforeEach(() => {
     vi.spyOn(React, 'useState').mockImplementation(useStateMock)
     vi.spyOn(RA, 'useRefresh').mockImplementation(useRefreshMock)
@@ -50,8 +71,7 @@ describe('useResourceRefresh', () => {
   })
 
   it('stores last time checked, to avoid redundant runs', () => {
-    const useSelectorMock = () => ({ lastReceived: lastTime })
-    vi.spyOn(Redux, 'useSelector').mockImplementation(useSelectorMock)
+    mockStore({ refresh: { lastReceived: lastTime } })
 
     useResourceRefresh()
 
@@ -60,8 +80,7 @@ describe('useResourceRefresh', () => {
 
   it("does not run again if lastTime didn't change", () => {
     vi.spyOn(React, 'useState').mockImplementation(() => [lastTime, setState])
-    const useSelectorMock = () => ({ lastReceived: lastTime })
-    vi.spyOn(Redux, 'useSelector').mockImplementation(useSelectorMock)
+    mockStore({ refresh: { lastReceived: lastTime } })
 
     useResourceRefresh()
 
@@ -70,11 +89,9 @@ describe('useResourceRefresh', () => {
 
   describe('No visible resources specified', () => {
     it('triggers a UI refresh when received a "any" resource refresh', () => {
-      const useSelectorMock = () => ({
-        lastReceived: lastTime,
-        resources: { '*': '*' },
+      mockStore({
+        refresh: { lastReceived: lastTime, resources: { '*': '*' } },
       })
-      vi.spyOn(Redux, 'useSelector').mockImplementation(useSelectorMock)
 
       useResourceRefresh()
 
@@ -83,11 +100,9 @@ describe('useResourceRefresh', () => {
     })
 
     it('triggers a UI refresh when received an "any" id', () => {
-      const useSelectorMock = () => ({
-        lastReceived: lastTime,
-        resources: { album: ['*'] },
+      mockStore({
+        refresh: { lastReceived: lastTime, resources: { album: ['*'] } },
       })
-      vi.spyOn(Redux, 'useSelector').mockImplementation(useSelectorMock)
 
       useResourceRefresh()
 
@@ -95,12 +110,14 @@ describe('useResourceRefresh', () => {
       expect(getMany).not.toHaveBeenCalled()
     })
 
-    it('triggers a refetch of the resources received', () => {
-      const useSelectorMock = () => ({
-        lastReceived: lastTime,
-        resources: { album: ['al-1', 'al-2'], song: ['sg-1', 'sg-2'] },
+    it('refetches only the received resources already loaded in the store', () => {
+      mockStore({
+        refresh: {
+          lastReceived: lastTime,
+          resources: { album: ['al-1', 'al-2'], song: ['sg-1', 'sg-2'] },
+        },
+        loaded: asStore({ album: ['al-1', 'al-2'], song: ['sg-1', 'sg-2'] }),
       })
-      vi.spyOn(Redux, 'useSelector').mockImplementation(useSelectorMock)
 
       useResourceRefresh()
 
@@ -109,15 +126,42 @@ describe('useResourceRefresh', () => {
       expect(getMany).toHaveBeenCalledWith('album', { ids: ['al-1', 'al-2'] })
       expect(getMany).toHaveBeenCalledWith('song', { ids: ['sg-1', 'sg-2'] })
     })
+
+    it('skips ids that are not loaded in the store', () => {
+      mockStore({
+        refresh: {
+          lastReceived: lastTime,
+          resources: { album: ['al-1', 'al-2', 'al-3'] },
+        },
+        loaded: asStore({ album: ['al-2'] }),
+      })
+
+      useResourceRefresh()
+
+      expect(getMany).toHaveBeenCalledTimes(1)
+      expect(getMany).toHaveBeenCalledWith('album', { ids: ['al-2'] })
+    })
+
+    it('does not fetch when none of the received ids are loaded', () => {
+      mockStore({
+        refresh: {
+          lastReceived: lastTime,
+          resources: { artist: ['ar-1', 'ar-2'] },
+        },
+        loaded: asStore({ artist: ['ar-9'] }),
+      })
+
+      useResourceRefresh()
+
+      expect(getMany).not.toHaveBeenCalled()
+    })
   })
 
   describe('Visible resources specified', () => {
     it('triggers a UI refresh when received a "any" resource refresh', () => {
-      const useSelectorMock = () => ({
-        lastReceived: lastTime,
-        resources: { '*': '*' },
+      mockStore({
+        refresh: { lastReceived: lastTime, resources: { '*': '*' } },
       })
-      vi.spyOn(Redux, 'useSelector').mockImplementation(useSelectorMock)
 
       useResourceRefresh('album')
 
@@ -125,12 +169,101 @@ describe('useResourceRefresh', () => {
       expect(getMany).not.toHaveBeenCalled()
     })
 
-    it('triggers a refetch of the resources received if they are visible', () => {
-      const useSelectorMock = () => ({
-        lastReceived: lastTime,
-        resources: { album: ['al-1', 'al-2'], song: ['sg-1', 'sg-2'] },
+    it('does not refresh the page when the wildcard is on a resource it does not watch', () => {
+      // Guards other senders: a wildcard on an unwatched resource must not reload this list.
+      mockStore({
+        refresh: {
+          lastReceived: lastTime,
+          resources: { album: ['al-1', 'al-2'], song: ['*'] },
+        },
+        loaded: asStore({ album: ['al-1', 'al-2'] }),
+      })
+
+      useResourceRefresh('album')
+
+      expect(refresh).not.toHaveBeenCalled()
+      expect(getMany).toHaveBeenCalledWith('album', { ids: ['al-1', 'al-2'] })
+    })
+
+    it('refetches the loaded songs of a refreshed album', () => {
+      // A track with no art of its own is served its album's, so its coverArt id moves with the
+      // album's. The backend cannot know which tracks are loaded; the store can.
+      mockStore({
+        refresh: { lastReceived: lastTime, resources: { album: ['al-1'] } },
+        loaded: {
+          album: { data: { 'al-1': { id: 'al-1' } } },
+          song: {
+            data: {
+              'sg-1': { id: 'sg-1', albumId: 'al-1' },
+              'sg-2': { id: 'sg-2', albumId: 'al-2' },
+            },
+          },
+        },
+      })
+
+      useResourceRefresh('song')
+
+      expect(refresh).not.toHaveBeenCalled()
+      expect(getMany).toHaveBeenCalledWith('song', { ids: ['sg-1'] })
+    })
+
+    it('fans an album refresh out to loaded playlist tracks, which have their own ids', () => {
+      mockStore({
+        refresh: { lastReceived: lastTime, resources: { album: ['al-1'] } },
+        loaded: {
+          playlistTrack: {
+            data: {
+              'pt-1': { id: 'pt-1', albumId: 'al-1' },
+              'pt-2': { id: 'pt-2', albumId: 'al-2' },
+            },
+          },
+        },
+      })
+
+      useResourceRefresh('playlistTrack', 'song', 'playlist')
+
+      expect(refresh).not.toHaveBeenCalled()
+      expect(getMany).toHaveBeenCalledWith('playlistTrack', { ids: ['pt-1'] })
+    })
+
+    it('does not fan out to track resources the component does not show', () => {
+      mockStore({
+        refresh: { lastReceived: lastTime, resources: { album: ['al-1'] } },
+        loaded: {
+          album: { data: { 'al-1': { id: 'al-1' } } },
+          song: { data: { 'sg-1': { id: 'sg-1', albumId: 'al-1' } } },
+        },
+      })
+
+      useResourceRefresh('album')
+
+      expect(refresh).not.toHaveBeenCalled()
+      expect(getMany).toHaveBeenCalledTimes(1)
+      expect(getMany).toHaveBeenCalledWith('album', { ids: ['al-1'] })
+    })
+
+    it('does not refetch songs when no loaded song belongs to the refreshed album', () => {
+      mockStore({
+        refresh: { lastReceived: lastTime, resources: { album: ['al-9'] } },
+        loaded: {
+          song: { data: { 'sg-1': { id: 'sg-1', albumId: 'al-1' } } },
+        },
+      })
+
+      useResourceRefresh('song')
+
+      expect(refresh).not.toHaveBeenCalled()
+      expect(getMany).not.toHaveBeenCalled()
+    })
+
+    it('refetches the received resources if they are visible and loaded', () => {
+      mockStore({
+        refresh: {
+          lastReceived: lastTime,
+          resources: { album: ['al-1', 'al-2'], song: ['sg-1', 'sg-2'] },
+        },
+        loaded: asStore({ album: ['al-1', 'al-2'], song: ['sg-1', 'sg-2'] }),
       })
-      vi.spyOn(Redux, 'useSelector').mockImplementation(useSelectorMock)
 
       useResourceRefresh('song')
 
diff --git a/ui/src/playlist/PlaylistDetails.jsx b/ui/src/playlist/PlaylistDetails.jsx
index 894809ce0..5d0f6631e 100644
--- a/ui/src/playlist/PlaylistDetails.jsx
+++ b/ui/src/playlist/PlaylistDetails.jsx
@@ -1,10 +1,5 @@
-import {
-  Card,
-  CardContent,
-  CardMedia,
-  Typography,
-  useMediaQuery,
-} from '@material-ui/core'
+import { useState } from 'react'
+import { Card, CardContent, Typography, useMediaQuery } from '@material-ui/core'
 import { makeStyles } from '@material-ui/core/styles'
 import { useTranslate } from 'react-admin'
 import Lightbox from 'react-image-lightbox'
@@ -17,10 +12,9 @@ import {
   SizeField,
   isWritable,
   OverflowTooltip,
-  useImageLoadingState,
 } from '../common'
-import config from '../config'
 import subsonic from '../subsonic'
+import { Artwork } from '../common/Artwork'
 
 const useStyles = makeStyles(
   (theme) => ({
@@ -75,9 +69,6 @@ const useStyles = makeStyles(
       backgroundColor: 'transparent',
       transition: 'opacity 0.3s ease-in-out',
     },
-    coverLoading: {
-      opacity: 0.5,
-    },
     title: {
       overflow: 'hidden',
       textOverflow: 'ellipsis',
@@ -107,37 +98,21 @@ const PlaylistDetails = (props) => {
   const translate = useTranslate()
   const classes = useStyles()
   const isDesktop = useMediaQuery((theme) => theme.breakpoints.up('lg'))
-  const {
-    imageLoading,
-    imageError,
-    isLightboxOpen,
-    handleImageLoad,
-    handleImageError,
-    handleOpenLightbox,
-    handleCloseLightbox,
-  } = useImageLoadingState(record.id)
+  const [isLightboxOpen, setLightboxOpen] = useState(false)
 
-  const imageUrl = subsonic.getCoverArtUrl(record, config.uiCoverArtSize, true)
   const fullImageUrl = subsonic.getCoverArtUrl(record)
 
   return (
     <Card className={classes.root}>
       <div className={classes.cardContents}>
         <div className={classes.coverParent}>
-          <CardMedia
-            key={record.id} // Force re-render when playlist changes
-            component={'img'}
-            src={imageUrl}
-            width="400"
-            height="400"
-            className={`${classes.cover} ${imageLoading ? classes.coverLoading : ''}`}
-            onClick={handleOpenLightbox}
-            onLoad={handleImageLoad}
-            onError={handleImageError}
+          <Artwork
+            record={record}
+            square
+            fit="contain"
+            className={classes.cover}
             title={record.name}
-            style={{
-              cursor: imageError ? 'default' : 'pointer',
-            }}
+            onClick={() => setLightboxOpen(true)}
           />
           {isWritable(record.ownerId) && (
             <ImageUploadOverlay
@@ -187,13 +162,13 @@ const PlaylistDetails = (props) => {
           </CardContent>
         </div>
       </div>
-      {isLightboxOpen && !imageError && (
+      {isLightboxOpen && (
         <Lightbox
           imagePadding={50}
           animationDuration={200}
           imageTitle={record.name}
           mainSrc={fullImageUrl}
-          onCloseRequest={handleCloseLightbox}
+          onCloseRequest={() => setLightboxOpen(false)}
         />
       )}
     </Card>
diff --git a/ui/src/playlist/PlaylistList.jsx b/ui/src/playlist/PlaylistList.jsx
index 642d90dd5..d2b17b108 100644
--- a/ui/src/playlist/PlaylistList.jsx
+++ b/ui/src/playlist/PlaylistList.jsx
@@ -20,7 +20,7 @@ import Switch from '@material-ui/core/Switch'
 import { makeStyles } from '@material-ui/core/styles'
 import { useMediaQuery } from '@material-ui/core'
 import {
-  CoverArtAvatar,
+  ArtworkAvatar,
   DurationField,
   List,
   LoveButton,
@@ -197,7 +197,7 @@ const PlaylistList = (props) => {
       bulkActionButtons={!isXsmall && <PlaylistListBulkActions />}
     >
       <Datagrid rowClick="show" isRowSelectable={(r) => isWritable(r?.ownerId)}>
-        <CoverArtAvatar source="id" variant="square" />
+        <ArtworkAvatar source="id" variant="square" />
         <TextField source="name" />
         {columns}
         <Writable>
diff --git a/ui/src/playlist/PlaylistShow.jsx b/ui/src/playlist/PlaylistShow.jsx
index 4e269be18..4c2fea315 100644
--- a/ui/src/playlist/PlaylistShow.jsx
+++ b/ui/src/playlist/PlaylistShow.jsx
@@ -35,7 +35,7 @@ const PlaylistShowLayout = (props) => {
   const { loading, ...context } = useShowContext(props)
   const { record } = context
   const classes = useStyles()
-  useResourceRefresh('song')
+  useResourceRefresh('playlistTrack', 'song')
 
   return (
     <>
diff --git a/ui/src/playlist/PlaylistSongs.jsx b/ui/src/playlist/PlaylistSongs.jsx
index bbe38b4d5..4718a7cf4 100644
--- a/ui/src/playlist/PlaylistSongs.jsx
+++ b/ui/src/playlist/PlaylistSongs.jsx
@@ -100,7 +100,8 @@ const PlaylistSongs = ({ playlistId, readOnly, actions, ...props }) => {
   const dataProvider = useDataProvider()
   const notify = useNotify()
   const version = useVersion()
-  useResourceRefresh('song', 'playlist')
+  // The rows are stored as playlistTrack, not song: their ids are playlist entries.
+  useResourceRefresh('playlistTrack', 'song', 'playlist')
 
   useEffect(() => {
     setPage(1)
diff --git a/ui/src/radio/RadioList.jsx b/ui/src/radio/RadioList.jsx
index ccdb9f1ef..0cfb2cd68 100644
--- a/ui/src/radio/RadioList.jsx
+++ b/ui/src/radio/RadioList.jsx
@@ -18,11 +18,10 @@ import {
   List,
   defaultRowsPerPageOptions,
   getStoredPerPage,
-  useImageUrl,
   ToggleFieldsMenu,
   useSelectedFields,
 } from '../common'
-import subsonic from '../subsonic'
+import { Artwork } from '../common/Artwork'
 import { StreamField } from './StreamField'
 import { setTrack } from '../actions'
 import { songFromRadio } from './helper'
@@ -83,15 +82,32 @@ const RadioListActions = ({
 
 const avatarStyle = { width: 40, height: 40 }
 
+const useCoverStyles = makeStyles({
+  cover: { width: 40, height: 40, borderRadius: '4px' },
+})
+
 const CoverArtField = ({ record }) => {
-  const directUrl = record?.uploadedImage
-    ? subsonic.getCoverArtUrl(record, 40, true)
-    : null
-  const { imgUrl } = useImageUrl(directUrl)
+  const classes = useCoverStyles()
   if (!record) return null
-  const src = imgUrl || RADIO_PLACEHOLDER_IMAGE
+  // Radios resolve art only from an uploaded image; otherwise show the generic radio icon.
+  if (record.uploadedImage) {
+    return (
+      <Artwork
+        record={record}
+        size={40}
+        square
+        className={classes.cover}
+        title={record.name}
+      />
+    )
+  }
   return (
-    <Avatar src={src} variant="rounded" style={avatarStyle} alt={record.name} />
+    <Avatar
+      src={RADIO_PLACEHOLDER_IMAGE}
+      variant="rounded"
+      style={avatarStyle}
+      alt={record.name}
+    />
   )
 }
 CoverArtField.defaultProps = { label: '' }
diff --git a/ui/src/subsonic/index.js b/ui/src/subsonic/index.js
index 7d93972e0..9f0ad28d7 100644
--- a/ui/src/subsonic/index.js
+++ b/ui/src/subsonic/index.js
@@ -81,25 +81,27 @@ const getAvatarUrl = (username, size) =>
   )
 
 const getCoverArtUrl = (record, size, square) => {
+  const suffix = record.imageHash ? '_' + record.imageHash : ''
   const options = {
-    ...(record.updatedAt && { _: record.updatedAt }),
+    // A hash-suffixed url is already pixel-versioned; the buster would defeat immutable caching.
+    ...(!record.imageHash && record.updatedAt && { _: record.updatedAt }),
     ...(size && { size }),
     ...(square && { square }),
   }
 
   // TODO Move this logic to server
   if (record.album) {
-    return baseUrl(url('getCoverArt', 'mf-' + record.id, options))
+    return baseUrl(url('getCoverArt', 'mf-' + record.id + suffix, options))
   } else if (record.albumArtist) {
-    return baseUrl(url('getCoverArt', 'al-' + record.id, options))
+    return baseUrl(url('getCoverArt', 'al-' + record.id + suffix, options))
   } else if (record.sync !== undefined) {
     // This is a playlist
-    return baseUrl(url('getCoverArt', 'pl-' + record.id, options))
+    return baseUrl(url('getCoverArt', 'pl-' + record.id + suffix, options))
   } else if (record.streamUrl !== undefined) {
     // This is a radio station
-    return baseUrl(url('getCoverArt', 'ra-' + record.id, options))
+    return baseUrl(url('getCoverArt', 'ra-' + record.id + suffix, options))
   } else {
-    return baseUrl(url('getCoverArt', 'ar-' + record.id, options))
+    return baseUrl(url('getCoverArt', 'ar-' + record.id + suffix, options))
   }
 }
 
diff --git a/ui/src/subsonic/index.test.js b/ui/src/subsonic/index.test.js
index ad4764c24..32c699a41 100644
--- a/ui/src/subsonic/index.test.js
+++ b/ui/src/subsonic/index.test.js
@@ -120,6 +120,47 @@ describe('getCoverArtUrl', () => {
     expect(url).toContain('ar-test-123')
     expect(url).not.toContain('_=')
   })
+
+  it('appends the content hash to the artwork id', () => {
+    const url = subsonic.getCoverArtUrl({
+      id: 'album-123',
+      albumArtist: 'AA',
+      imageHash: '0123456789abcdef',
+    })
+    expect(url).toContain('al-album-123_0123456789abcdef')
+  })
+
+  it('drops the updatedAt buster once the url is hash-versioned', () => {
+    const url = subsonic.getCoverArtUrl({
+      id: 'album-123',
+      albumArtist: 'AA',
+      updatedAt: '2023-01-01T00:00:00Z',
+      imageHash: '0123456789abcdef',
+    })
+    expect(url).toContain('al-album-123_0123456789abcdef')
+    expect(url).not.toContain('_=')
+  })
+
+  it('keeps the updatedAt buster while artwork is unresolved', () => {
+    const url = subsonic.getCoverArtUrl({
+      id: 'album-123',
+      albumArtist: 'AA',
+      updatedAt: '2023-01-01T00:00:00Z',
+    })
+    expect(url).toContain('al-album-123')
+    expect(url).toContain('_=')
+  })
+
+  it('still builds a url for known-absent artwork so the server placeholder renders', () => {
+    // Returning '' here made <img src=undefined> render as a broken icon; the server serves a
+    // proper placeholder for absent art, so the client must still request it.
+    const url = subsonic.getCoverArtUrl({
+      id: 'album-123',
+      albumArtist: 'AA',
+      imageAbsent: true,
+    })
+    expect(url).toContain('al-album-123')
+  })
 })
 
 describe('getDiscCoverArtUrl', () => {
diff --git a/ui/src/utils/thumbhash.js b/ui/src/utils/thumbhash.js
new file mode 100644
index 000000000..f4ec673d2
--- /dev/null
+++ b/ui/src/utils/thumbhash.js
@@ -0,0 +1,138 @@
+// ThumbHash decoder (https://github.com/evanw/thumbhash), kept byte-compatible with the reference:
+// core/artwork/thumbhash/testdata/thumbhash.js pins the pixels the specs assert on.
+
+const toBytes = (hash) => {
+  if (typeof hash !== 'string' || hash === '') {
+    throw new Error('thumbhash: empty hash')
+  }
+  const binary = atob(hash)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  if (bytes.length < 5) {
+    throw new Error('thumbhash: hash too short')
+  }
+  return bytes
+}
+
+// header unpacks the fixed 5-byte prefix plus the optional alpha byte.
+const header = (bytes) => {
+  const header24 = bytes[0] | (bytes[1] << 8) | (bytes[2] << 16)
+  const header16 = bytes[3] | (bytes[4] << 8)
+  const hasAlpha = header24 >> 23 !== 0
+  if (hasAlpha && bytes.length < 6) {
+    throw new Error('thumbhash: hash too short for alpha')
+  }
+  const isLandscape = header16 >> 15 !== 0
+  const alphaLimit = hasAlpha ? 5 : 7
+  return {
+    lDC: (header24 & 63) / 63,
+    pDC: ((header24 >> 6) & 63) / 31.5 - 1,
+    qDC: ((header24 >> 12) & 63) / 31.5 - 1,
+    lScale: ((header24 >> 18) & 31) / 31,
+    hasAlpha,
+    pScale: ((header16 >> 3) & 63) / 63,
+    qScale: ((header16 >> 9) & 63) / 63,
+    lx: Math.max(3, isLandscape ? alphaLimit : header16 & 7),
+    ly: Math.max(3, isLandscape ? header16 & 7 : alphaLimit),
+    aDC: hasAlpha ? (bytes[5] & 15) / 15 : 1,
+    aScale: hasAlpha ? (bytes[5] >> 4) / 15 : 0,
+  }
+}
+
+// naturalSize is the reference decoder's own output size: 32 on the long edge, at the aspect the
+// hash approximates. Callers with the true dimensions should decode at those instead.
+export const naturalSize = (hash) => {
+  const { lx, ly } = header(toBytes(hash))
+  const ratio = lx / ly
+  return ratio > 1
+    ? { width: 32, height: Math.round(32 / ratio) }
+    : { width: Math.round(32 * ratio), height: 32 }
+}
+
+const cosTable = (n, size) => {
+  const table = new Float64Array(n * size)
+  for (let c = 0; c < n; c++) {
+    for (let i = 0; i < size; i++) {
+      table[c * size + i] = Math.cos((Math.PI / size) * (i + 0.5) * c)
+    }
+  }
+  return table
+}
+
+export const decode = (hash, width, height) => {
+  const bytes = toBytes(hash)
+  const h = header(bytes)
+  if (!(width > 0) || !(height > 0)) {
+    throw new Error('thumbhash: width and height must be positive')
+  }
+
+  const acStart = h.hasAlpha ? 6 : 5
+  let acIndex = 0
+  const channel = (nx, ny, scale) => {
+    const ac = []
+    for (let cy = 0; cy < ny; cy++) {
+      for (let cx = cy ? 0 : 1; cx * ny < nx * (ny - cy); cx++) {
+        const byte = bytes[acStart + (acIndex >> 1)] ?? 0
+        ac.push((((byte >> ((acIndex++ & 1) << 2)) & 15) / 7.5 - 1) * scale)
+      }
+    }
+    return ac
+  }
+  // The 1.25x chroma boost is the reference's quantisation compensation, not a free parameter.
+  const lAC = channel(h.lx, h.ly, h.lScale)
+  const pAC = channel(3, 3, h.pScale * 1.25)
+  const qAC = channel(3, 3, h.qScale * 1.25)
+  const aAC = h.hasAlpha ? channel(5, 5, h.aScale) : []
+
+  const nx = Math.max(h.lx, h.hasAlpha ? 5 : 3)
+  const ny = Math.max(h.ly, h.hasAlpha ? 5 : 3)
+  const fx = cosTable(nx, width)
+  const fy = cosTable(ny, height)
+
+  const pixels = new Uint8ClampedArray(width * height * 4)
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      let l = h.lDC
+      let p = h.pDC
+      let q = h.qDC
+      let a = h.aDC
+
+      for (let cy = 0, j = 0; cy < h.ly; cy++) {
+        const fy2 = fy[cy * height + y] * 2
+        for (let cx = cy ? 0 : 1; cx * h.ly < h.lx * (h.ly - cy); cx++, j++) {
+          l += lAC[j] * fx[cx * width + x] * fy2
+        }
+      }
+      for (let cy = 0, j = 0; cy < 3; cy++) {
+        const fy2 = fy[cy * height + y] * 2
+        for (let cx = cy ? 0 : 1; cx < 3 - cy; cx++, j++) {
+          const f = fx[cx * width + x] * fy2
+          p += pAC[j] * f
+          q += qAC[j] * f
+        }
+      }
+      if (h.hasAlpha) {
+        for (let cy = 0, j = 0; cy < 5; cy++) {
+          const fy2 = fy[cy * height + y] * 2
+          for (let cx = cy ? 0 : 1; cx < 5 - cy; cx++, j++) {
+            a += aAC[j] * fx[cx * width + x] * fy2
+          }
+        }
+      }
+
+      const b = l - (2 / 3) * p
+      const r = (3 * l - b + q) / 2
+      const g = r - q
+      const idx = 4 * x + y * width * 4
+      // Explicit floor: the reference writes into a Uint8Array, which truncates, while the
+      // Uint8ClampedArray that createImageData needs would round.
+      pixels[idx] = Math.floor(Math.max(0, 255 * Math.min(1, r)))
+      pixels[idx + 1] = Math.floor(Math.max(0, 255 * Math.min(1, g)))
+      pixels[idx + 2] = Math.floor(Math.max(0, 255 * Math.min(1, b)))
+      pixels[idx + 3] = Math.floor(Math.max(0, 255 * Math.min(1, a)))
+    }
+  }
+  return pixels
+}
diff --git a/ui/src/utils/thumbhash.test.js b/ui/src/utils/thumbhash.test.js
new file mode 100644
index 000000000..6abb4d7e4
--- /dev/null
+++ b/ui/src/utils/thumbhash.test.js
@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest'
+import { decode, naturalSize } from './thumbhash'
+
+// Digests pinned from evanw/thumbhash's reference decoder (vendored at
+// core/artwork/thumbhash/testdata/thumbhash.js), so any drift from it fails here.
+const fnv = (bytes) => {
+  let h = 2166136261 >>> 0
+  for (const b of bytes) {
+    h ^= b
+    h = Math.imul(h, 16777619) >>> 0
+  }
+  return h.toString(16)
+}
+
+const REFERENCE = [
+  ['alpha', 'JOiFBQ4nkIexh3p4iA8uB+lYhIeAh3d4dw==', 32, 32, '500141bc'],
+  ['landscape', '3wcOFJpwh4eBh3d4iIePgAj3hw==', 32, 18, '18465aed'],
+  ['portrait', '3/cNFBqBB4iId4d3d4iAjwj4hw==', 18, 32, '56500cc1'],
+  ['solid', 'HoUBBwB4eHeHd3hweId3h3h4B2+Ih4gA', 32, 32, '39cc5c5'],
+  ['square', 'H/gNBxpwh4dwd3eIiHd3iHeHeJ+dcH8I', 32, 32, '740d8afc'],
+  ['tiny', 'HoU9tx4I9wiIh4hwj3CI+AiIcH/494cP', 32, 32, 'f2555987'],
+]
+
+describe('thumbhash decode', () => {
+  it.each(REFERENCE)(
+    'reproduces the reference pixels for %s',
+    (_name, hash, w, h, digest) => {
+      expect(fnv(decode(hash, w, h))).toEqual(digest)
+    },
+  )
+
+  it.each(REFERENCE)(
+    'reports the reference natural size for %s',
+    (_name, hash, w, h) => {
+      expect(naturalSize(hash)).toEqual({ width: w, height: h })
+    },
+  )
+
+  it('decodes to any requested grid, not just the natural one', () => {
+    const [, hash] = REFERENCE[4]
+    const pixels = decode(hash, 8, 5)
+    expect(pixels).toHaveLength(8 * 5 * 4)
+    // Opaque hash: every alpha byte is saturated.
+    for (let i = 3; i < pixels.length; i += 4) {
+      expect(pixels[i]).toBe(255)
+    }
+  })
+
+  it('carries alpha through for a hash that has it', () => {
+    const [, hash, w, h] = REFERENCE[0]
+    const pixels = decode(hash, w, h)
+    const alphas = new Set()
+    for (let i = 3; i < pixels.length; i += 4) {
+      alphas.add(pixels[i])
+    }
+    expect(alphas.size).toBeGreaterThan(1)
+  })
+
+  it.each([
+    ['empty', ''],
+    ['too short to hold a header', 'AAAA'],
+    ['not base64', '!!!not-a-thumbhash!!!'],
+  ])('throws on a hash that is %s', (_name, hash) => {
+    expect(() => decode(hash, 32, 32)).toThrow()
+  })
+})
diff --git a/utils/cache/file_caches.go b/utils/cache/file_caches.go
index ed2374696..33fa046df 100644
--- a/utils/cache/file_caches.go
+++ b/utils/cache/file_caches.go
@@ -2,8 +2,10 @@ package cache
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"path/filepath"
 	"sync"
 	"sync/atomic"
@@ -158,6 +160,13 @@ func (fc *fileCache) Get(ctx context.Context, arg Item) (*CachedStream, error) {
 
 	key := arg.Key()
 	r, w, err := fc.cache.Get(key)
+	if errors.Is(err, fs.ErrNotExist) {
+		// The entry outlived its data file. Drop it and retry, or every future Get
+		// for this key fails for the rest of the process's life.
+		log.Debug(ctx, "Cache entry lost its data file. Re-fetching", "cache", fc.name, "key", key)
+		_ = fc.invalidate(ctx, key)
+		r, w, err = fc.cache.Get(key)
+	}
 	if err != nil {
 		return nil, err
 	}
diff --git a/utils/cache/file_caches_test.go b/utils/cache/file_caches_test.go
index edcfbc6b9..7ce1b0393 100644
--- a/utils/cache/file_caches_test.go
+++ b/utils/cache/file_caches_test.go
@@ -7,6 +7,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync/atomic"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -278,6 +279,92 @@ var _ = Describe("File Caches", func() {
 				}).Should(BeTrue())
 			})
 		})
+
+		Context("entry outliving its data file", func() {
+			It("re-fetches when the data file vanished behind the cache's back", func() {
+				var calls atomic.Int32
+				fc := callNewFileCache("test", "10MB", "test", 0, func(ctx context.Context, arg Item) (io.Reader, error) {
+					calls.Add(1)
+					return strings.NewReader("payload"), nil
+				})
+
+				s, err := fc.Get(context.Background(), &testArg{"vanish"})
+				Expect(err).To(BeNil())
+				Expect(io.ReadAll(s)).To(Equal([]byte("payload")))
+				Expect(s.Close()).To(Succeed())
+
+				dataPath := fcSpreadFS(fc).KeyMapper((&testArg{"vanish"}).Key())
+				Eventually(func() error { _, e := os.Stat(dataPath); return e }).Should(Succeed())
+				Expect(os.Remove(dataPath)).To(Succeed())
+
+				s2, err := fc.Get(context.Background(), &testArg{"vanish"})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(io.ReadAll(s2)).To(Equal([]byte("payload")))
+				_ = s2.Close()
+				Expect(calls.Load()).To(BeNumerically("==", 2))
+			})
+
+			It("survives an invalidated entry's deferred file removal", func() {
+				// invalidate() drops the map entry but defers the unlink until readers close;
+				// a Get in that window re-creates the file, which the deferred unlink then eats.
+				var n atomic.Int32
+				fc := callNewFileCache("test", "10MB", "test", 0, func(ctx context.Context, arg Item) (io.Reader, error) {
+					if n.Add(1) == 1 {
+						return &partialThenErrReader{data: []byte("PARTIAL"), err: errors.New("died")}, nil
+					}
+					return strings.NewReader("GOOD"), nil
+				})
+
+				key := (&testArg{"deferred"}).Key()
+				s1, err := fc.Get(context.Background(), &testArg{"deferred"})
+				Expect(err).To(BeNil())
+
+				// The failed write invalidates the entry; the removal now waits on s1.
+				Eventually(func() bool { return fc.cache.Exists(key) }).Should(BeFalse())
+
+				s2, err := fc.Get(context.Background(), &testArg{"deferred"})
+				Expect(err).To(BeNil())
+				Expect(io.ReadAll(s2)).To(Equal([]byte("GOOD")))
+				Expect(s2.Close()).To(Succeed())
+
+				Expect(s1.Close()).To(Succeed())
+
+				dataPath := fcSpreadFS(fc).KeyMapper(key)
+				Eventually(func() bool {
+					_, e := os.Stat(dataPath)
+					return os.IsNotExist(e)
+				}).Should(BeTrue(), "expected the deferred removal to take the re-created file")
+
+				s3, err := fc.Get(context.Background(), &testArg{"deferred"})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(io.ReadAll(s3)).To(Equal([]byte("GOOD")))
+				_ = s3.Close()
+			})
+
+			It("re-fetches when an adopted entry's data file vanished", func() {
+				// Entries adopted on startup take a different code path than in-process ones.
+				var calls atomic.Int32
+				fc := callNewFileCache("test", "10MB", "test", 0, func(ctx context.Context, arg Item) (io.Reader, error) {
+					calls.Add(1)
+					return strings.NewReader("payload"), nil
+				})
+				dataPath := fcSpreadFS(fc).KeyMapper((&testArg{"adopted"}).Key())
+				Expect(os.MkdirAll(filepath.Dir(dataPath), 0755)).To(Succeed())
+				Expect(os.WriteFile(dataPath, []byte("payload"), 0600)).To(Succeed())
+				Expect(fcSpreadFS(fc).MarkComplete(dataPath)).To(Succeed())
+
+				adopted := callNewFileCache("test2", "10MB", "test", 0, func(ctx context.Context, arg Item) (io.Reader, error) {
+					calls.Add(1)
+					return strings.NewReader("payload"), nil
+				})
+				Expect(os.Remove(dataPath)).To(Succeed())
+
+				s, err := adopted.Get(context.Background(), &testArg{"adopted"})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(io.ReadAll(s)).To(Equal([]byte("payload")))
+				_ = s.Close()
+			})
+		})
 	})
 })
 
diff --git a/utils/cache/spread_fs.go b/utils/cache/spread_fs.go
index 647439790..11801b324 100644
--- a/utils/cache/spread_fs.go
+++ b/utils/cache/spread_fs.go
@@ -128,7 +128,7 @@ func (sfs *spreadFS) Create(name string) (stream.File, error) {
 	if err != nil {
 		return nil, err
 	}
-	return os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0600)
+	return createDataFile(name)
 }
 
 func (sfs *spreadFS) Open(name string) (stream.File, error) {
diff --git a/utils/cache/spread_fs_test.go b/utils/cache/spread_fs_test.go
index 0f88d3a58..d0b54567d 100644
--- a/utils/cache/spread_fs_test.go
+++ b/utils/cache/spread_fs_test.go
@@ -1,10 +1,13 @@
 package cache
 
 import (
+	"io"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 
+	"github.com/djherbis/stream"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -39,6 +42,39 @@ var _ = Describe("Spread FS", func() {
 		})
 	})
 
+	Describe("Create", func() {
+		It("leaves an already-open reader's bytes intact", func() {
+			// Shrinking a file an older stream still serves spins its reader at a premature EOF.
+			if runtime.GOOS == "windows" {
+				Skip("Windows cannot unlink a file with open handles, so Create reuses the inode")
+			}
+			name := filepath.Join(rootDir, "aa", "bb", "data")
+			s, err := stream.NewStream(name, fs)
+			Expect(err).To(BeNil())
+			_, err = s.Write([]byte("PARTIAL"))
+			Expect(err).To(BeNil())
+			r, err := s.NextReader()
+			Expect(err).To(BeNil())
+			Expect(s.Close()).To(Succeed())
+
+			f, err := fs.Create(name)
+			Expect(err).To(BeNil())
+			_, err = f.Write([]byte("GOOD"))
+			Expect(err).To(BeNil())
+			Expect(f.Close()).To(Succeed())
+
+			done := make(chan []byte, 1)
+			go func() {
+				b, _ := io.ReadAll(r)
+				done <- b
+			}()
+			Eventually(done).Should(Receive(Equal([]byte("PARTIAL"))))
+			Expect(r.Close()).To(Succeed())
+
+			Expect(os.ReadFile(name)).To(Equal([]byte("GOOD")))
+		})
+	})
+
 	Describe("MarkComplete / Remove markers", func() {
 		It("creates a .complete marker for a data file", func() {
 			data := fs.KeyMapper("song1")
diff --git a/utils/cache/spread_fs_unix.go b/utils/cache/spread_fs_unix.go
new file mode 100644
index 000000000..c7cb19cf8
--- /dev/null
+++ b/utils/cache/spread_fs_unix.go
@@ -0,0 +1,18 @@
+//go:build !windows
+
+package cache
+
+import (
+	"os"
+
+	"github.com/djherbis/stream"
+)
+
+// createDataFile unlinks instead of truncating, so a re-created entry gets a fresh
+// inode and readers still holding the old one see its full contents.
+func createDataFile(name string) (stream.File, error) {
+	if err := os.Remove(name); err != nil && !os.IsNotExist(err) {
+		return nil, err
+	}
+	return os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
+}
diff --git a/utils/cache/spread_fs_windows.go b/utils/cache/spread_fs_windows.go
new file mode 100644
index 000000000..ca4186d65
--- /dev/null
+++ b/utils/cache/spread_fs_windows.go
@@ -0,0 +1,15 @@
+//go:build windows
+
+package cache
+
+import (
+	"os"
+
+	"github.com/djherbis/stream"
+)
+
+// createDataFile truncates in place: Windows refuses to unlink a file another handle
+// has open, and failing the create would break every miss on a path with a live reader.
+func createDataFile(name string) (stream.File, error) {
+	return os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0600)
+}

From 7993fb9158196c0ee33136ce54dee07a26dfd215 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 10 Aug 2026 11:42:27 -0400
Subject: [PATCH 022/200] perf(persistence): use *_artists join tables for
 artist participant filters (#5930)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* perf(persistence): use *_artists join tables for artist participant filters

The artist_id/artists_id, role_<role>_id and role_total_id filters, plus the
AlbumsByArtistID/AlbumsByContributingArtistID/SongsByArtistID helpers, scanned
every album or media_file row through json_tree(participants, ...), which no
index can serve — the cause of multi-second artist pages on large libraries
(discussion #5929). Rewrite them to semi-join the album_artists and
media_file_artists tables via a shared ParticipantIDFilter helper. The join
tables are written in the same transaction as the participants JSON, so
results are unchanged.

album_artists' unique constraint led with album_id, so artist-driven lookups
had no usable index. Rebuild the table with the constraint reordered to
(artist_id, album_id, role, sub_role), mirroring media_file_artists, instead
of adding a fourth index: measured within 4% of a dedicated covering index
(geomean -92.5% vs json_tree on a 96k-track production copy) while saving
~7MiB and per-scan write amplification. Album-side consumers (participant
rewrites, FK cascades, markMissing) keep using album_artists_album_id, and
updateParticipants' ON CONFLICT target already names artist_id first. The
rebuild is linear work: 1.1s on a 113k-row production copy.

* chore(gitignore): add temp benchmark files to ignore list

* fix(persistence): clear album_artists when an album is saved without participants

albumRepository.Put skipped updateParticipants when the Participants map was empty, so a hypothetical save with no participants would write {} to the JSON column but leave stale album_artists rows behind, now visible through the semi-join filters. No current caller can hit this (albums built by MediaFiles.ToAlbum always have participants), but make Put unconditional anyway, matching mediaFileRepository.Put, so the join table always moves with the JSON. Raised by Codex review on #5930.
---
 .gitignore                                    |  3 +
 ...eorder_album_artists_unique_constraint.sql | 59 +++++++++++++
 persistence/album_repository.go               | 19 ++--
 persistence/album_repository_test.go          | 87 ++++++++++++++++---
 persistence/mediafile_repository.go           |  6 +-
 persistence/sql_participations.go             | 24 +++++
 server/filter/filters.go                      | 22 ++---
 server/jellyfin/items_test.go                 |  6 +-
 8 files changed, 184 insertions(+), 42 deletions(-)
 create mode 100644 db/migrations/20260810143445_reorder_album_artists_unique_constraint.sql

diff --git a/.gitignore b/.gitignore
index 3567a7d90..6459ded9b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,3 +41,6 @@ openspec/
 go.work*
 .worktrees/
 .playwright-mcp/
+
+# Temp benchmark files
+zz_*_test.go
\ No newline at end of file
diff --git a/db/migrations/20260810143445_reorder_album_artists_unique_constraint.sql b/db/migrations/20260810143445_reorder_album_artists_unique_constraint.sql
new file mode 100644
index 000000000..fd1598e93
--- /dev/null
+++ b/db/migrations/20260810143445_reorder_album_artists_unique_constraint.sql
@@ -0,0 +1,59 @@
+-- +goose Up
+-- +goose StatementBegin
+-- Lead the unique constraint with artist_id (mirroring media_file_artists) so artist-driven
+-- filters and the artist-delete cascade get an index seek; album_id lookups keep album_artists_album_id.
+CREATE TABLE album_artists_tmp
+(
+    album_id  varchar not null
+        REFERENCES album (id)
+            ON DELETE CASCADE,
+    artist_id varchar not null
+        REFERENCES artist (id)
+            ON DELETE CASCADE,
+    role      varchar default '' not null,
+    sub_role  varchar default '' not null,
+    CONSTRAINT album_artists
+        UNIQUE (artist_id, album_id, role, sub_role)
+);
+
+INSERT INTO album_artists_tmp(album_id, artist_id, role, sub_role)
+SELECT album_id, artist_id, role, sub_role
+FROM album_artists;
+
+DROP TABLE album_artists;
+ALTER TABLE album_artists_tmp RENAME TO album_artists;
+
+CREATE INDEX album_artists_album_id
+    ON album_artists (album_id);
+CREATE INDEX album_artists_role
+    ON album_artists (role);
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+CREATE TABLE album_artists_tmp
+(
+    album_id  varchar not null
+        REFERENCES album (id)
+            ON DELETE CASCADE,
+    artist_id varchar not null
+        REFERENCES artist (id)
+            ON DELETE CASCADE,
+    role      varchar default '' not null,
+    sub_role  varchar default '' not null,
+    CONSTRAINT album_artists
+        UNIQUE (album_id, artist_id, role, sub_role)
+);
+
+INSERT INTO album_artists_tmp(album_id, artist_id, role, sub_role)
+SELECT album_id, artist_id, role, sub_role
+FROM album_artists;
+
+DROP TABLE album_artists;
+ALTER TABLE album_artists_tmp RENAME TO album_artists;
+
+CREATE INDEX album_artists_album_id
+    ON album_artists (album_id);
+CREATE INDEX album_artists_role
+    ON album_artists (role);
+-- +goose StatementEnd
diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 1ebb09751..91e90127c 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -172,24 +172,22 @@ func yearFilter(_ string, value any) Sqlizer {
 }
 
 func artistFilter(_ string, value any) Sqlizer {
-	return Or{
-		Exists("json_tree(participants, '$.albumartist')", Eq{"value": value}),
-		Exists("json_tree(participants, '$.artist')", Eq{"value": value}),
-	}
+	return ParticipantIDFilter("album", value, model.RoleAlbumArtist, model.RoleArtist)
 }
 
 func artistRoleFilter(name string, value any) Sqlizer {
 	roleName := strings.TrimSuffix(strings.TrimPrefix(name, "role_"), "_id")
 
 	// Check if the role name is valid. If not, return an invalid filter
-	if _, ok := model.AllRoles[roleName]; !ok {
+	role, ok := model.AllRoles[roleName]
+	if !ok {
 		return Gt{"": nil}
 	}
-	return Exists(fmt.Sprintf("json_tree(participants, '$.%s')", roleName), Eq{"value": value})
+	return ParticipantIDFilter("album", value, role)
 }
 
 func allRolesFilter(_ string, value any) Sqlizer {
-	return Like{"participants": fmt.Sprintf(`%%"%s"%%`, value)}
+	return ParticipantIDFilter("album", value)
 }
 
 func (r *albumRepository) CountAll(options ...model.QueryOptions) (int64, error) {
@@ -214,12 +212,7 @@ func (r *albumRepository) Put(al *model.Album) error {
 		return err
 	}
 	al.ID = id
-	if len(al.Participants) > 0 {
-		if err = r.updateParticipants(al.ID, al.Participants); err != nil {
-			return err
-		}
-	}
-	return nil
+	return r.updateParticipants(al.ID, al.Participants)
 }
 
 // TODO Move external metadata to a separated table
diff --git a/persistence/album_repository_test.go b/persistence/album_repository_test.go
index 1ead89529..061083949 100644
--- a/persistence/album_repository_test.go
+++ b/persistence/album_repository_test.go
@@ -527,19 +527,16 @@ var _ = Describe("AlbumRepository", func() {
 
 	Describe("artistRoleFilter", func() {
 		DescribeTable("creates correct SQL expressions for artist roles",
-			func(filterName, artistID, expectedSQL string) {
+			func(filterName, artistID, expectedRole string) {
 				sqlizer := artistRoleFilter(filterName, artistID)
 				sql, args, err := sqlizer.ToSql()
 				Expect(err).ToNot(HaveOccurred())
-				Expect(sql).To(Equal(expectedSQL))
-				Expect(args).To(Equal([]any{artistID}))
+				Expect(sql).To(Equal("album.id IN (SELECT album_id FROM album_artists WHERE artist_id = ? AND role IN (?))"))
+				Expect(args).To(Equal([]any{artistID, expectedRole}))
 			},
-			Entry("artist role", "role_artist_id", "123",
-				"exists (select 1 from json_tree(participants, '$.artist') where value = ?)"),
-			Entry("albumartist role", "role_albumartist_id", "456",
-				"exists (select 1 from json_tree(participants, '$.albumartist') where value = ?)"),
-			Entry("composer role", "role_composer_id", "789",
-				"exists (select 1 from json_tree(participants, '$.composer') where value = ?)"),
+			Entry("artist role", "role_artist_id", "123", "artist"),
+			Entry("albumartist role", "role_albumartist_id", "456", "albumartist"),
+			Entry("composer role", "role_composer_id", "789", "composer"),
 		)
 
 		It("works with the actual filter map", func() {
@@ -553,8 +550,8 @@ var _ = Describe("AlbumRepository", func() {
 				sqlizer := filterFunc(filterName, "test-id")
 				sql, args, err := sqlizer.ToSql()
 				Expect(err).ToNot(HaveOccurred())
-				Expect(sql).To(Equal(fmt.Sprintf("exists (select 1 from json_tree(participants, '$.%s') where value = ?)", roleName)))
-				Expect(args).To(Equal([]any{"test-id"}))
+				Expect(sql).To(Equal("album.id IN (SELECT album_id FROM album_artists WHERE artist_id = ? AND role IN (?))"))
+				Expect(args).To(Equal([]any{"test-id", roleName}))
 			}
 		})
 
@@ -644,6 +641,74 @@ var _ = Describe("AlbumRepository", func() {
 			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
 		})
 
+		It("finds albums through the participant-based filters", func() {
+			artist := &model.Artist{ID: "filter-artist-1", Name: "Filter Artist", OrderArtistName: "filter artist"}
+			Expect(createArtistWithLibrary(artistRepo, artist, 1)).To(Succeed())
+
+			album := &model.Album{
+				LibraryID:     1,
+				ID:            "filter-album-1",
+				Name:          "Filter Album",
+				AlbumArtistID: artist.ID,
+				AlbumArtist:   artist.Name,
+				Participants: model.Participants{
+					model.RoleAlbumArtist: {{Artist: model.Artist{ID: artist.ID, Name: artist.Name}}},
+					model.RoleComposer:    {{Artist: model.Artist{ID: artist.ID, Name: artist.Name}}},
+				},
+			}
+			Expect(albumRepo.Put(album)).To(Succeed())
+
+			byArtist, err := albumRepo.GetAll(model.QueryOptions{Filters: artistFilter("artist_id", artist.ID)})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(byArtist).To(HaveLen(1))
+			Expect(byArtist[0].ID).To(Equal(album.ID))
+
+			byComposer, err := albumRepo.GetAll(model.QueryOptions{Filters: artistRoleFilter("role_composer_id", artist.ID)})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(byComposer).To(HaveLen(1))
+
+			byLyricist, err := albumRepo.GetAll(model.QueryOptions{Filters: artistRoleFilter("role_lyricist_id", artist.ID)})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(byLyricist).To(BeEmpty())
+
+			byAnyRole, err := albumRepo.GetAll(model.QueryOptions{Filters: allRolesFilter("role_total_id", artist.ID)})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(byAnyRole).To(HaveLen(1))
+
+			count, err := albumRepo.CountAll(model.QueryOptions{Filters: artistFilter("artist_id", artist.ID)})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(count).To(Equal(int64(1)))
+
+			_, _ = artistRepo.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
+			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+		})
+
+		It("clears album_artists rows when saved with empty participants", func() {
+			artist := &model.Artist{ID: "clear-artist-1", Name: "Clear Artist", OrderArtistName: "clear artist"}
+			Expect(createArtistWithLibrary(artistRepo, artist, 1)).To(Succeed())
+
+			album := &model.Album{
+				LibraryID:     1,
+				ID:            "clear-album-1",
+				Name:          "Clear Album",
+				AlbumArtistID: artist.ID,
+				AlbumArtist:   artist.Name,
+				Participants: model.Participants{
+					model.RoleAlbumArtist: {{Artist: model.Artist{ID: artist.ID, Name: artist.Name}}},
+				},
+			}
+			DeferCleanup(func() {
+				_, _ = artistRepo.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
+				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+			})
+			Expect(albumRepo.Put(album)).To(Succeed())
+			verifyAlbumArtists(album.ID, []albumArtistRecord{{ArtistID: artist.ID, Role: "albumartist", SubRole: ""}})
+
+			album.Participants = model.Participants{}
+			Expect(albumRepo.Put(album)).To(Succeed())
+			verifyAlbumArtists(album.ID, []albumArtistRecord{})
+		})
+
 		It("filters out invalid artist IDs leaving only valid participants in database", func() {
 			// Create two real artists in the database
 			artist1 := &model.Artist{
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index df1472c2a..f372b30f5 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -113,7 +113,7 @@ var mediaFileFilter = sync.OnceValue(func() map[string]filterFunc {
 		"has_rating": annotationBoolFilter("rating"),
 		"genre_id":   tagIDFilter,
 		"missing":    booleanFilter,
-		"artists_id": artistFilter,
+		"artists_id": mediaFileArtistFilter,
 		"library_id": libraryIdFilter,
 		"path":       startsWithFilter("media_file.path"),
 	}
@@ -126,6 +126,10 @@ var mediaFileFilter = sync.OnceValue(func() map[string]filterFunc {
 	return filters
 })
 
+func mediaFileArtistFilter(_ string, value any) Sqlizer {
+	return ParticipantIDFilter("media_file", value, model.RoleAlbumArtist, model.RoleArtist)
+}
+
 func mediaFileRecentlyAddedSort() string {
 	if conf.Server.RecentlyAddedByModTime {
 		return "media_file.updated_at, media_file.id"
diff --git a/persistence/sql_participations.go b/persistence/sql_participations.go
index 38b0203fa..746abed01 100644
--- a/persistence/sql_participations.go
+++ b/persistence/sql_participations.go
@@ -22,6 +22,30 @@ type flatParticipant struct {
 	SubRole  string `json:"sub_role,omitempty"`
 }
 
+// ParticipantIDFilter matches rows of table where the artist participates in any of the given roles
+// (any role when empty). Semi-joins <table>_artists; json_tree over the JSON is far slower at scale.
+func ParticipantIDFilter(table string, artistID any, roles ...model.Role) Sqlizer {
+	return participantIDFilter(table, artistID, false, roles)
+}
+
+// NotParticipantIDFilter is the negation of ParticipantIDFilter.
+func NotParticipantIDFilter(table string, artistID any, roles ...model.Role) Sqlizer {
+	return participantIDFilter(table, artistID, true, roles)
+}
+
+func participantIDFilter(table string, artistID any, negate bool, roles []model.Role) Sqlizer {
+	sel := Select(table + "_id").From(table + "_artists").Where(Eq{"artist_id": artistID})
+	if len(roles) > 0 {
+		sel = sel.Where(Eq{"role": slice.Map(roles, func(r model.Role) string { return r.String() })})
+	}
+	sql, args, _ := sel.ToSql()
+	op := " IN ("
+	if negate {
+		op = " NOT IN ("
+	}
+	return Expr(table+".id"+op+sql+")", args...)
+}
+
 func marshalParticipants(participants model.Participants) string {
 	dbParticipants := make(map[model.Role][]participant)
 	for role, artists := range participants {
diff --git a/server/filter/filters.go b/server/filter/filters.go
index 067f7b1f9..62d8f0523 100644
--- a/server/filter/filters.go
+++ b/server/filter/filters.go
@@ -47,17 +47,13 @@ func AlbumsByArtist() Options {
 }
 
 func AlbumsByArtistID(artistId string) Options {
-	filters := []Sqlizer{
-		persistence.Exists("json_tree(participants, '$.albumartist')", Eq{"value": artistId}),
-	}
+	roles := []model.Role{model.RoleAlbumArtist}
 	if conf.Server.Subsonic.ArtistParticipations {
-		filters = append(filters,
-			persistence.Exists("json_tree(participants, '$.artist')", Eq{"value": artistId}),
-		)
+		roles = append(roles, model.RoleArtist)
 	}
 	return addDefaultFilters(Options{
 		Sort:    "max_year",
-		Filters: Or(filters),
+		Filters: persistence.ParticipantIDFilter("album", artistId, roles...),
 	})
 }
 
@@ -68,8 +64,8 @@ func AlbumsByContributingArtistID(artistId string) Options {
 	return addDefaultFilters(Options{
 		Sort: "max_year",
 		Filters: And{
-			persistence.Exists("json_tree(participants, '$.artist')", Eq{"value": artistId}),
-			persistence.NotExists("json_tree(participants, '$.albumartist')", Eq{"value": artistId}),
+			persistence.ParticipantIDFilter("album", artistId, model.RoleArtist),
+			persistence.NotParticipantIDFilter("album", artistId, model.RoleAlbumArtist),
 		},
 	})
 }
@@ -104,13 +100,11 @@ func SongsByAlbum(albumId string) Options {
 }
 
 // SongsByArtistID matches media files where the artist participates as album or track artist, in
-// album order. Semi-joins media_file_artists; scanning the participants JSON is ~10x slower at scale.
+// album order.
 func SongsByArtistID(artistId string) Options {
 	return addDefaultFilters(Options{
-		Sort: "album",
-		Filters: Expr(
-			"media_file.id IN (SELECT media_file_id FROM media_file_artists WHERE artist_id = ? AND role IN (?, ?))",
-			artistId, model.RoleArtist.String(), model.RoleAlbumArtist.String()),
+		Sort:    "album",
+		Filters: persistence.ParticipantIDFilter("media_file", artistId, model.RoleArtist, model.RoleAlbumArtist),
 	})
 }
 
diff --git a/server/jellyfin/items_test.go b/server/jellyfin/items_test.go
index 401145461..4eddcc654 100644
--- a/server/jellyfin/items_test.go
+++ b/server/jellyfin/items_test.go
@@ -219,7 +219,7 @@ var _ = Describe("Items", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
 			sql, _, err := albumRepo.Options.Filters.ToSql()
 			Expect(err).NotTo(HaveOccurred())
-			Expect(sql).To(ContainSubstring("json_tree"))
+			Expect(sql).To(ContainSubstring("album_artists"))
 		})
 
 		It("lists artists when IncludeItemTypes=MusicArtist", func() {
@@ -708,7 +708,7 @@ var _ = Describe("Items", func() {
 				Expect(w.Code).To(Equal(http.StatusOK))
 				sql, args, err := albumRepo.Options.Filters.ToSql()
 				Expect(err).NotTo(HaveOccurred())
-				Expect(sql).NotTo(ContainSubstring("json_tree")) // not treated as an artist-parent filter
+				Expect(sql).NotTo(ContainSubstring("album_artists")) // not treated as an artist-parent filter
 				Expect(sql).To(ContainSubstring("library_id"))
 				Expect(args).To(ContainElement(2))
 			})
@@ -724,7 +724,7 @@ var _ = Describe("Items", func() {
 				sql, args, err := albumRepo.Options.Filters.ToSql()
 				Expect(err).NotTo(HaveOccurred())
 				// Falls back to treating "99" as an (empty-matching) artist-parent id...
-				Expect(sql).To(ContainSubstring("json_tree"))
+				Expect(sql).To(ContainSubstring("album_artists"))
 				// ...while still scoping to the user's own accessible libraries.
 				Expect(sql).To(ContainSubstring("library_id"))
 				Expect(args).To(ContainElement(1))

From 7736bbb545da8c3fdfb3dadcd68cb7b1714baf86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 10 Aug 2026 14:10:05 -0400
Subject: [PATCH 023/200] fix(cache): write the completion marker before
 closing the cache writer (#5927)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(cache): write the completion marker before closing the cache writer

Readers of an in-progress cache write see EOF the moment the writer closes,
but the .complete marker was created after the close, on the background
goroutine — so a fully-read stream did not mean the cache was done touching
disk. The new artwork precache spec ends right at EOF, and its
GinkgoT().TempDir() cleanup raced the marker creation, failing the Windows CI
job with 'unlinkat ...: The directory is not empty' (the race also reproduces
on macOS, 2 of 3 runs, with the tightened test).

Writing the marker after a clean copy but before Close makes reader-EOF imply
every on-disk write for the entry is finished. A failed writer Close still
invalidates the entry, which removes both the marker and the data file. The
existing marker test now asserts the marker exists immediately at EOF instead
of Eventually.

* fix(artwork): never dispatch queue items after the drain context is cancelled

The 10x Windows stress run for the previous commit surfaced a second flake in
the same package: 'leaves undispatched items queued when cancelled mid-batch'
lost row alc7 in 4 of 10 runs. In drain, when a semaphore slot is free and the
context is already cancelled, both cases of the blocking select are ready and
Go picks one at random — so a cancelled drain could still dispatch items. A
non-blocking Done check before the select gives cancellation priority.

The race was invisible on Linux/macOS only by accident: the spec seeded the
album repo with a single album (each SetData overwrote the last), so only the
final row (alc7) resolved to absent and got deleted when dispatched; the
others fell on the retry path and survived. Nanosecond enqueue timestamps
made alc0 always first out of the mock dequeue, masking the race, while
Windows' coarse clock ties the timestamps and randomizes the order. The spec
now seeds all eight albums, which made the race reproduce locally on the
first try (row alc0) and now guards the fix on every platform.

* test: give cache-init waits a 10s timeout for loaded CI runners

A 10x parallel Windows stress run timed out one artwork spec in BeforeEach:
the FileCache init goroutine (mkdir + reload walk) took over Gomega's default
1s Eventually timeout under shared-runner disk contention. Bump the three
identical init waits (two artwork suites and the utils/cache helper) to 10s.

* test(scanner): widen watcher debounce margins for loaded CI runners

The watcher debouncing spec asserts 'no scan yet' inside 20ms Consistently
windows while the debounce wait was only 50ms — a 2.5x margin that a loaded
Windows runner blows through by delaying the timer-reset notification, firing
the scan early (failed all three FlakeAttempts in a 10x stress run). Raise the
test debounce wait to 200ms (10x the observation windows) and the scan-fired
Eventually timeouts to 2s to match.

* refactor(artwork): collapse drain cancellation into a single exit path

Replace the non-blocking ctx pre-check plus duplicated select exit with one
select and a ctx.Err() check after it. Besides removing the duplication, this
closes the residual race: a cancellation landing between the two selects could
still let the blocking select randomly pick the free semaphore slot and
dispatch the item. Now a dispatch is only possible when the context was live
after slot acquisition.

* style: trim flaky-test fix comments to single lines

Compress each two-line comment added by this PR to the one line that carries
the invariant; drop the narration around it.
---
 core/artwork/artwork_test.go    |  2 +-
 core/artwork/worker.go          |  5 ++++-
 core/artwork/worker_test.go     |  8 ++++++--
 scanner/watcher_test.go         | 19 ++++++++++---------
 utils/cache/file_caches.go      | 10 ++++++----
 utils/cache/file_caches_test.go | 10 +++++-----
 6 files changed, 32 insertions(+), 22 deletions(-)

diff --git a/core/artwork/artwork_test.go b/core/artwork/artwork_test.go
index c6b848101..7de5475d6 100644
--- a/core/artwork/artwork_test.go
+++ b/core/artwork/artwork_test.go
@@ -106,7 +106,7 @@ var _ = Describe("Artwork", func() {
 			func(ctx context.Context, arg cache.Item) (io.Reader, error) {
 				return arg.(artworkReader).Reader(ctx)
 			})
-		Eventually(func() bool { return imgCache.Available(ctx) }).Should(BeTrue())
+		Eventually(func() bool { return imgCache.Available(ctx) }, 10*time.Second).Should(BeTrue())
 		svc = NewArtwork(ds, imgCache, store, ffm)
 	})
 
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index 3042c47b0..3ded52629 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -170,8 +170,11 @@ func (w *Worker) drain(ctx context.Context, concurrency int, kinds ...string) (i
 		select {
 		case sem <- struct{}{}:
 		case <-ctx.Done():
+		}
+		// select picks randomly when both cases are ready, so re-check to never dispatch after cancellation.
+		if ctx.Err() != nil {
 			wg.Wait()
-			return len(items), nil
+			return len(items), nil //nolint:nilerr // a cancelled drain is a clean stop, not an error
 		}
 		wg.Go(func() {
 			defer func() { <-sem }()
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index 1f3b52840..5b6e42885 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -151,7 +151,8 @@ var _ = Describe("Worker", func() {
 			func(ctx context.Context, arg cache.Item) (io.Reader, error) {
 				return arg.(artworkReader).Reader(ctx)
 			})}
-		Eventually(func() bool { return imgCache.Available(ctx) }).Should(BeTrue())
+		// Init walks the cache dir on a goroutine; loaded CI runners can take >1s.
+		Eventually(func() bool { return imgCache.Available(ctx) }, 10*time.Second).Should(BeTrue())
 		w = NewWorker(ds, store, ag, ffm, broker, imgCache)
 	})
 
@@ -706,13 +707,16 @@ var _ = Describe("Worker", func() {
 
 	Describe("batching", func() {
 		It("leaves undispatched items queued when cancelled mid-batch", func() {
+			// Every album must resolve, so any dispatched item deletes its row regardless of dequeue order.
+			albums := model.Albums{}
 			for i := range 8 {
 				id := fmt.Sprintf("alc%d", i)
-				ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: id, Name: "Album"}})
+				albums = append(albums, model.Album{ID: id, Name: "Album"})
 				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
 					ItemKind: "al", ItemID: id, Priority: model.ArtworkPriorityScan,
 				})).To(Succeed())
 			}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(albums)
 			cancelledCtx, cancel := context.WithCancel(ctx)
 			cancel()
 
diff --git a/scanner/watcher_test.go b/scanner/watcher_test.go
index 15e49e195..12c94602c 100644
--- a/scanner/watcher_test.go
+++ b/scanner/watcher_test.go
@@ -26,7 +26,8 @@ var _ = Describe("Watcher", func() {
 
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
-		conf.Server.Scanner.WatcherWait = 50 * time.Millisecond // Short wait for tests
+		// Must dwarf the 20ms Consistently windows below, or a loaded runner's delayed timer reset flakes the debouncing spec.
+		conf.Server.Scanner.WatcherWait = 200 * time.Millisecond
 
 		ctx, cancel = context.WithCancel(GinkgoT().Context())
 		DeferCleanup(cancel)
@@ -91,7 +92,7 @@ var _ = Describe("Watcher", func() {
 					return nil
 				}
 				return calls[0].Targets
-			}, 500*time.Millisecond, 10*time.Millisecond).Should(HaveLen(2))
+			}, 2*time.Second, 10*time.Millisecond).Should(HaveLen(2))
 
 			// Verify targets
 			calls := mockScanner.GetScanFoldersCalls()
@@ -111,7 +112,7 @@ var _ = Describe("Watcher", func() {
 			// Wait for watcher to process and trigger scan
 			Eventually(func() int {
 				return mockScanner.GetScanFoldersCallCount()
-			}, 500*time.Millisecond, 10*time.Millisecond).Should(Equal(1))
+			}, 2*time.Second, 10*time.Millisecond).Should(Equal(1))
 
 			// Verify the target
 			calls := mockScanner.GetScanFoldersCalls()
@@ -129,7 +130,7 @@ var _ = Describe("Watcher", func() {
 			// Wait for watcher to process and trigger scan
 			Eventually(func() int {
 				return mockScanner.GetScanFoldersCallCount()
-			}, 500*time.Millisecond, 10*time.Millisecond).Should(Equal(1))
+			}, 2*time.Second, 10*time.Millisecond).Should(Equal(1))
 
 			// Verify only one target despite multiple file/folder changes
 			calls := mockScanner.GetScanFoldersCalls()
@@ -170,7 +171,7 @@ var _ = Describe("Watcher", func() {
 			// Now wait for the debounce timer to expire and trigger scan
 			Eventually(func() int {
 				return mockScanner.GetScanFoldersCallCount()
-			}, 500*time.Millisecond, 10*time.Millisecond).Should(Equal(1))
+			}, 2*time.Second, 10*time.Millisecond).Should(Equal(1))
 		})
 
 		It("triggers scan after quiet period", func() {
@@ -183,7 +184,7 @@ var _ = Describe("Watcher", func() {
 			// Wait for quiet period
 			Eventually(func() int {
 				return mockScanner.GetScanFoldersCallCount()
-			}, 500*time.Millisecond, 10*time.Millisecond).Should(Equal(1))
+			}, 2*time.Second, 10*time.Millisecond).Should(Equal(1))
 		})
 	})
 
@@ -205,7 +206,7 @@ var _ = Describe("Watcher", func() {
 			// Wait for scan
 			Eventually(func() int {
 				return mockScanner.GetScanFoldersCallCount()
-			}, 500*time.Millisecond, 10*time.Millisecond).Should(Equal(1))
+			}, 2*time.Second, 10*time.Millisecond).Should(Equal(1))
 
 			// Should scan the library root
 			calls := mockScanner.GetScanFoldersCalls()
@@ -222,7 +223,7 @@ var _ = Describe("Watcher", func() {
 			// Wait for scan
 			Eventually(func() int {
 				return mockScanner.GetScanFoldersCallCount()
-			}, 500*time.Millisecond, 10*time.Millisecond).Should(Equal(1))
+			}, 2*time.Second, 10*time.Millisecond).Should(Equal(1))
 
 			// Should have only one target
 			calls := mockScanner.GetScanFoldersCalls()
@@ -266,7 +267,7 @@ var _ = Describe("Watcher", func() {
 					return nil
 				}
 				return calls[0].Targets
-			}, 500*time.Millisecond, 10*time.Millisecond).Should(HaveLen(2))
+			}, 2*time.Second, 10*time.Millisecond).Should(HaveLen(2))
 
 			// Verify library IDs are different
 			calls := mockScanner.GetScanFoldersCalls()
diff --git a/utils/cache/file_caches.go b/utils/cache/file_caches.go
index 33fa046df..dff9e4e7a 100644
--- a/utils/cache/file_caches.go
+++ b/utils/cache/file_caches.go
@@ -183,12 +183,11 @@ func (fc *fileCache) Get(ctx context.Context, arg Item) (*CachedStream, error) {
 			return nil, err
 		}
 		go func() {
-			if err := copyAndClose(w, reader); err != nil {
+			if err := fc.copyAndClose(ctx, key, w, reader); err != nil {
 				log.Debug(ctx, "Error storing file in cache", "cache", fc.name, "key", key, err)
 				_ = fc.invalidate(ctx, key)
 			} else {
 				log.Trace(ctx, "File successfully stored in cache", "cache", fc.name, "key", key)
-				fc.markComplete(ctx, key)
 			}
 		}()
 	}
@@ -243,7 +242,8 @@ func getFinalCachedSize(r fscache.ReadAtCloser) int64 {
 	return -1
 }
 
-func copyAndClose(w io.WriteCloser, r io.Reader) error {
+// copyAndClose marks the entry complete before closing w, so EOF implies the entry is settled on disk.
+func (fc *fileCache) copyAndClose(ctx context.Context, key string, w io.WriteCloser, r io.Reader) error {
 	_, err := io.Copy(w, r)
 	if err != nil {
 		err = fmt.Errorf("copying data to cache: %w", err)
@@ -253,7 +253,9 @@ func copyAndClose(w io.WriteCloser, r io.Reader) error {
 			err = multierror.Append(err, fmt.Errorf("closing source stream: %w", cErr))
 		}
 	}
-
+	if err == nil {
+		fc.markComplete(ctx, key)
+	}
 	if cErr := w.Close(); cErr != nil {
 		err = multierror.Append(err, fmt.Errorf("closing cache writer: %w", cErr))
 	}
diff --git a/utils/cache/file_caches_test.go b/utils/cache/file_caches_test.go
index 7ce1b0393..974200656 100644
--- a/utils/cache/file_caches_test.go
+++ b/utils/cache/file_caches_test.go
@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"strings"
 	"sync/atomic"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -18,7 +19,7 @@ import (
 // Call NewFileCache and wait for it to be ready
 func callNewFileCache(name, cacheSize, cacheFolder string, maxItems int, getReader ReadFunc) *fileCache {
 	fc := NewFileCache(name, cacheSize, cacheFolder, maxItems, getReader).(*fileCache)
-	Eventually(func() bool { return fc.ready.Load() }).Should(BeTrue())
+	Eventually(func() bool { return fc.ready.Load() }, 10*time.Second).Should(BeTrue())
 	return fc
 }
 
@@ -114,11 +115,10 @@ var _ = Describe("File Caches", func() {
 			_, _ = io.ReadAll(s)
 			_ = s.Close()
 
+			// EOF must imply the entry is settled on disk (Windows temp-dir cleanups rely on it).
 			dataPath := fcSpreadFS(fc).KeyMapper((&testArg{"markme"}).Key())
-			Eventually(func() bool {
-				_, statErr := os.Stat(dataPath + ".complete")
-				return statErr == nil
-			}).Should(BeTrue())
+			_, statErr := os.Stat(dataPath + ".complete")
+			Expect(statErr).ToNot(HaveOccurred())
 		})
 
 		It("serves a concurrent reader from an in-progress write and marks complete once", func() {

From d0807070606ebb331839aa6c54a61853d857cfdd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 10 Aug 2026 21:21:44 -0400
Subject: [PATCH 024/200] fix(jellyfin): return a mixed, globally-limited list
 for multi-type /Items requests (#5935)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(jellyfin): allow random sort for artist/genre/playlist item types

* feat(jellyfin): add round-robin interleave helper for merged item types

* fix(jellyfin): mix and globally limit multi-type Items requests

Run per-type queries in parallel and round-robin interleave the results so a
request for multiple IncludeItemTypes (e.g. Finamp's random favorite) returns a
mixed, globally-limited page instead of one type's rows followed by the next.

* fix(jellyfin): dedupe repeated IncludeItemTypes to avoid duplicate items and redundant queries

* refactor(jellyfin): dedupe via slice.Unique and extract queryTypeWindow helper

* perf(jellyfin): serve random multi-type pages from offset 0

A random merge reshuffles every request, so paginating it is meaningless — page N
is just another fresh draw (as in real Jellyfin). Serving from offset 0 caps the
per-type fetch at limit instead of offset+limit, avoiding deep-offset blow-up for
the random case (Finamp's random-favorite quick action).

* refactor(jellyfin): resolve random-merge via applySort; simplify merge signatures

Detect the random-page shortcut by resolving each type's sort through applySort
(matching how the sort is actually chosen) instead of string-matching SortBy, and
only when every type is random. Drop the always-zero window param from
mergeTypesStreaming and derive the window inside mergeTypesPaged.
---
 server/jellyfin/items.go      | 131 ++++++++++++++++++++++++++--------
 server/jellyfin/items_test.go | 109 +++++++++++++++++++++++++++-
 2 files changed, 206 insertions(+), 34 deletions(-)

diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index 631530b6d..b14a272bb 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -18,6 +18,7 @@ import (
 	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	"github.com/navidrome/navidrome/utils/req"
 	"github.com/navidrome/navidrome/utils/slice"
+	"golang.org/x/sync/errgroup"
 )
 
 // notMissing excludes items whose backing files are all gone ("missing" is a real column on
@@ -330,52 +331,97 @@ func (api *Router) playlistTracksRepo(ctx context.Context, q itemsQuery) (model.
 }
 
 func (api *Router) mergeTypes(ctx context.Context, q itemsQuery) (itemsResult, error) {
-	// Each per-type query needs at most offset+limit rows (the worst case where one type fills the
-	// whole [offset, offset+limit) window). Totals are unaffected — they come from CountAll.
-	window := 0
-	if q.limit > 0 {
-		window = q.offset + q.limit
+	if q.limit == 0 {
+		return api.mergeTypesStreaming(ctx, q)
 	}
-	// A search can't stream, so the window is what each type materializes and StartIndex would drive
-	// it without bound. Only below the window are the merged rows the true order, hence the clip
-	// below too. Non-search stays unbounded in StartIndex: a known gap, fixable with per-type counts.
-	if q.search != "" {
-		window = min(window, maxSearchLimit)
+	// A random page doesn't stack on the previous one (the order reshuffles each request), so serving
+	// from 0 is an equivalent fresh draw and avoids materializing offset+limit rows per type.
+	offset := q.offset
+	if randomlySorted(q) {
+		offset = 0
 	}
+	return api.mergeTypesPaged(ctx, q, offset)
+}
+
+// randomlySorted reports whether every merged type resolves to a random sort — the case where a page
+// is an independent draw, so the offset can be collapsed to 0. Resolving via applySort (rather than
+// matching the raw SortBy) keeps this in step with how each type's sort is actually chosen.
+func randomlySorted(q itemsQuery) bool {
+	for _, itemType := range q.types {
+		var opts model.QueryOptions
+		applySort(&opts, itemType, q.sortBy, q.sortOrder)
+		if opts.Sort != "random" {
+			return false
+		}
+	}
+	return true
+}
+
+// mergeTypesStreaming keeps the unbounded path lazy: chaining the per-type cursors yields their rows
+// in order minus the first offset, without pulling every row into memory.
+func (api *Router) mergeTypesStreaming(ctx context.Context, q itemsQuery) (itemsResult, error) {
 	var results []itemsResult
 	total := 0
 	for _, itemType := range q.types {
-		var opts model.QueryOptions
-		opts.Max = window
-		applySort(&opts, itemType, q.sortBy, q.sortOrder)
-		res, err := api.queryItemsOfType(ctx, itemType, opts, q)
+		res, err := api.queryTypeWindow(ctx, itemType, 0, q)
 		if err != nil {
 			return itemsResult{}, err
 		}
 		results = append(results, res)
 		total += res.total
 	}
-	if q.limit == 0 {
-		// No cap above, so merging in memory would pull every row of every type. The merged page is
-		// just their rows in order minus the first offset — what chaining the cursors yields.
-		return chained(results, total, q.offset), nil
+	return chained(results, total, q.offset), nil
+}
+
+// queryTypeWindow queries one type for the merge paths, capping it to window rows with the sort applied.
+func (api *Router) queryTypeWindow(ctx context.Context, itemType string, window int, q itemsQuery) (itemsResult, error) {
+	var opts model.QueryOptions
+	opts.Max = window
+	applySort(&opts, itemType, q.sortBy, q.sortOrder)
+	return api.queryItemsOfType(ctx, itemType, opts, q)
+}
+
+// mergeTypesPaged runs each type's query concurrently, then round-robins the per-type rows so the limited page
+// is a mix rather than one type's rows followed by the next.
+func (api *Router) mergeTypesPaged(ctx context.Context, q itemsQuery, offset int) (itemsResult, error) {
+	// Each per-type query needs at most offset+limit rows (worst case: one type fills the whole window).
+	window := offset + q.limit
+	if q.search != "" {
+		window = min(window, maxSearchLimit)
 	}
-	var items []dto.BaseItemDto
-	for _, res := range results {
-		typeItems, err := res.collect()
-		if err != nil {
-			return itemsResult{}, err
-		}
-		items = append(items, typeItems...)
+	lists := make([][]dto.BaseItemDto, len(q.types))
+	totals := make([]int, len(q.types))
+	g, ctx := errgroup.WithContext(ctx)
+	for i, itemType := range q.types {
+		g.Go(func() error {
+			res, err := api.queryTypeWindow(ctx, itemType, window, q)
+			if err != nil {
+				return err
+			}
+			items, err := res.collect()
+			if err != nil {
+				return err
+			}
+			lists[i] = items
+			totals[i] = res.total
+			return nil
+		})
 	}
+	if err := g.Wait(); err != nil {
+		return itemsResult{}, err
+	}
+	total := 0
+	for _, t := range totals {
+		total += t
+	}
+	items := interleave(lists)
 	if q.search != "" {
 		// Past the window the merged order isn't the true one, so drop it rather than serve another
-		// type's rows. The total is what's pageable overall, not this page, or a client paging on it
-		// would stop after the first page.
+		// type's rows. The total is what's pageable overall, so a client paging on it won't stop early.
 		items = items[:min(window, len(items))]
 		total = min(total, maxSearchLimit)
 	}
-	return materialized(result(paginate(items, q.offset, q.limit), total, q.offset)), nil
+	return materialized(result(paginate(items, offset, q.limit), total, q.offset)), nil
 }
 
 func (api *Router) queryItemsOfType(ctx context.Context, itemType string, opts model.QueryOptions, q itemsQuery) (itemsResult, error) {
@@ -440,6 +486,8 @@ func parseTypes(types string) []string {
 			recognized = append(recognized, t)
 		}
 	}
+	// Dedupe: a repeated type would duplicate items in the merge and spawn a redundant query.
+	recognized = slice.Unique(recognized)
 	if len(recognized) == 0 {
 		return []string{"MusicAlbum"}
 	}
@@ -459,6 +507,25 @@ func paginate(items []dto.BaseItemDto, offset, limit int) []dto.BaseItemDto {
 	return items
 }
 
+// interleave merges per-type item lists round-robin: one item from each list in turn, preserving
+// each list's own order, so no single type dominates the head of a mixed-type result.
+func interleave(lists [][]dto.BaseItemDto) []dto.BaseItemDto {
+	total, maxLen := 0, 0
+	for _, l := range lists {
+		total += len(l)
+		maxLen = max(maxLen, len(l))
+	}
+	out := make([]dto.BaseItemDto, 0, total)
+	for i := 0; i < maxLen; i++ {
+		for _, l := range lists {
+			if i < len(l) {
+				out = append(out, l[i])
+			}
+		}
+	}
+	return out
+}
+
 // Search can't stream (Search returns a slice), so it needs both a default and a ceiling: without
 // the ceiling, Limit=999999 still materializes every match.
 const (
@@ -818,9 +885,8 @@ func applySort(opts *model.QueryOptions, itemType, sortBy, order string) {
 	}
 }
 
-// sortColumnsByType maps lowercased-SortBy -> repo-sort-key per item type. Each repository maps
-// logical fields to different real columns (e.g. media_file has "title" not "name"; artist has no
-// "random").
+// sortColumnsByType maps lowercased-SortBy -> repo-sort-key per item type (repos map logical fields
+// to different real columns, e.g. media_file has "title" not "name").
 var sortColumnsByType = map[string]map[string]string{
 	"Audio": {
 		"sortname": "title", "name": "title",
@@ -848,6 +914,7 @@ var sortColumnsByType = map[string]map[string]string{
 		"playcount":       "play_count",
 		"dateplayed":      "play_date",
 		"communityrating": "rating",
+		"random":          "random",
 	},
 	"MusicAlbum": {
 		"sortname": "name", "name": "name", "album": "name",
@@ -862,10 +929,12 @@ var sortColumnsByType = map[string]map[string]string{
 	},
 	"MusicGenre": {
 		"sortname": "name", "name": "name",
+		"random": "random",
 	},
 	"Playlist": {
 		"sortname": "name", "name": "name",
 		"datecreated": "created_at",
+		"random":      "random",
 	},
 }
 
diff --git a/server/jellyfin/items_test.go b/server/jellyfin/items_test.go
index 4eddcc654..d8b9e60e8 100644
--- a/server/jellyfin/items_test.go
+++ b/server/jellyfin/items_test.go
@@ -462,9 +462,9 @@ var _ = Describe("Items", func() {
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
-			// Clipped to the window, and still the real row at that index — not the album behind it.
+			// Clipped to the window; the interleaved album takes one slot, shifting this song in by one.
 			Expect(res.Items).To(HaveLen(1))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(songs[maxSearchLimit-1].ID)))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(songs[maxSearchLimit-2].ID)))
 		})
 
 		It("bounds an unbounded multi-type search to the default in total, not per type", func() {
@@ -500,7 +500,8 @@ var _ = Describe("Items", func() {
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.Items).ToNot(BeEmpty())
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(songs[defaultSearchLimit+50].ID)))
+			// The interleaved album takes one slot ahead of it, shifting this song in by one.
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(songs[defaultSearchLimit+49].ID)))
 		})
 
 		It("reports a search total beyond the fetched page instead of the page length", func() {
@@ -748,6 +749,68 @@ var _ = Describe("Items", func() {
 				Expect(sql).NotTo(ContainSubstring("library_id"))
 			})
 		})
+
+		Describe("mixed IncludeItemTypes merge", func() {
+			BeforeEach(func() {
+				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}, {ID: "a2", Name: "Two"}})
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "S1"}, {ID: "s2", Title: "S2"}})
+			})
+
+			It("returns a mix of both types, not all of one", func() {
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&Recursive=true&Limit=4", nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				var res dto.QueryResult
+				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+				Expect(res.Items).To(HaveLen(4))
+				Expect(res.TotalRecordCount).To(Equal(4))
+				types := map[string]int{}
+				for _, it := range res.Items {
+					types[it.Type]++
+				}
+				Expect(types["Audio"]).To(Equal(2))
+				Expect(types["MusicAlbum"]).To(Equal(2))
+			})
+
+			It("interleaves types round-robin (Audio first, per IncludeItemTypes order)", func() {
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&Recursive=true&Limit=4", nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				var res dto.QueryResult
+				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+				got := []string{res.Items[0].Type, res.Items[1].Type, res.Items[2].Type, res.Items[3].Type}
+				Expect(got).To(Equal([]string{"Audio", "MusicAlbum", "Audio", "MusicAlbum"}))
+			})
+
+			It("honors Limit across the merged set", func() {
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&Recursive=true&Limit=1", nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				var res dto.QueryResult
+				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+				Expect(res.Items).To(HaveLen(1))
+				Expect(res.TotalRecordCount).To(Equal(4))
+			})
+
+			It("serves a full random page from offset 0 regardless of StartIndex", func() {
+				// A deep StartIndex on a random merge must not materialize offset+limit rows; since random
+				// reshuffles per request, offset 0 is an equivalent fresh draw. Old behavior returned empty.
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&SortBy=Random&Recursive=true&StartIndex=1000&Limit=4", nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				var res dto.QueryResult
+				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+				Expect(res.Items).To(HaveLen(4))
+			})
+
+			It("propagates a per-type query error", func() {
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetError(true)
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&Recursive=true&Limit=4", nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				Expect(w.Code).To(Equal(http.StatusInternalServerError))
+			})
+		})
 	})
 
 	Describe("getItem", func() {
@@ -896,4 +959,44 @@ var _ = Describe("Items", func() {
 			Expect(args).To(ContainElements(1, 2))
 		})
 	})
+
+	Describe("applySort random for all merge types", func() {
+		DescribeTable("maps Random -> random",
+			func(itemType string) {
+				var opts model.QueryOptions
+				applySort(&opts, itemType, "Random", "")
+				Expect(opts.Sort).To(Equal("random"))
+			},
+			Entry("Audio", "Audio"),
+			Entry("MusicAlbum", "MusicAlbum"),
+			Entry("MusicArtist", "MusicArtist"),
+			Entry("MusicGenre", "MusicGenre"),
+			Entry("Playlist", "Playlist"),
+		)
+	})
+
+	Describe("interleave", func() {
+		It("round-robins one item per list in turn", func() {
+			lists := [][]dto.BaseItemDto{
+				{{Id: "a0"}, {Id: "a1"}, {Id: "a2"}},
+				{{Id: "b0"}, {Id: "b1"}},
+			}
+			got := interleave(lists)
+			ids := make([]string, len(got))
+			for i, it := range got {
+				ids[i] = it.Id
+			}
+			Expect(ids).To(Equal([]string{"a0", "b0", "a1", "b1", "a2"}))
+		})
+
+		It("returns empty for no lists", func() {
+			Expect(interleave(nil)).To(BeEmpty())
+		})
+	})
+
+	Describe("parseTypes", func() {
+		It("dedupes repeated types, preserving first-seen order", func() {
+			Expect(parseTypes("Audio,MusicAlbum,Audio")).To(Equal([]string{"Audio", "MusicAlbum"}))
+		})
+	})
 })

From 8e0ff1a23504252d8d9b0ef35656ef7eedb74258 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Mon, 10 Aug 2026 21:30:14 -0400
Subject: [PATCH 025/200] fix(jellyfin): resolve genre id as a MusicGenre item

The Jellyfin /Items/{id} endpoint resolved albums, artists, songs and
playlists by id but not genres, so a genre id returned 404. Finamp's
genre "See all" fetches the genre as the track list's parent item, and
that 404 crashed its screen to a blank page after the tracks flashed in.

Add a Genre lookup to resolveItemByID (backed by a new GenreRepository.Get)
so a genre id returns its MusicGenre BaseItemDto, matching real Jellyfin.
---
 model/genre.go                  |  1 +
 persistence/genre_repository.go | 10 +++++++---
 server/jellyfin/items.go        |  5 ++++-
 server/jellyfin/items_test.go   | 15 +++++++++++++++
 tests/mock_genre_repo.go        | 11 +++++++++++
 5 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/model/genre.go b/model/genre.go
index bb05e747e..fa5b6ec62 100644
--- a/model/genre.go
+++ b/model/genre.go
@@ -11,4 +11,5 @@ type Genres []Genre
 
 type GenreRepository interface {
 	GetAll(...QueryOptions) (Genres, error)
+	Get(id string) (*Genre, error)
 }
diff --git a/persistence/genre_repository.go b/persistence/genre_repository.go
index 22443284f..0bb22c21b 100644
--- a/persistence/genre_repository.go
+++ b/persistence/genre_repository.go
@@ -30,15 +30,19 @@ func (r *genreRepository) GetAll(opt ...model.QueryOptions) (model.Genres, error
 	return res, err
 }
 
-// Override ResourceRepository methods to return Genre objects instead of Tag objects
-
-func (r *genreRepository) Read(id string) (any, error) {
+func (r *genreRepository) Get(id string) (*model.Genre, error) {
 	sel := r.selectGenre().Where(Eq{"tag.id": id})
 	var res model.Genre
 	err := r.queryOne(sel, &res)
 	return &res, err
 }
 
+// Override ResourceRepository methods to return Genre objects instead of Tag objects
+
+func (r *genreRepository) Read(id string) (any, error) {
+	return r.Get(id)
+}
+
 func (r *genreRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
 	return r.GetAll(r.parseRestOptions(r.ctx, options...))
 }
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index b14a272bb..9b85b8a62 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -736,7 +736,7 @@ func (api *Router) listPlaylists(ctx context.Context, opts model.QueryOptions, q
 }
 
 // resolveItemByID resolves a decoded navidrome id to its BaseItemDto, trying library view, album,
-// artist, song and playlist in turn. Albums and songs report not-found when the user lacks access
+// artist, song, playlist and genre in turn. Albums and songs report not-found when the user lacks access
 // to their library, so an id can't probe content outside the user's libraries.
 func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fields) (dto.BaseItemDto, bool) {
 	// The synthetic playlists folder must resolve by the id we advertised, not 404.
@@ -778,6 +778,9 @@ func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fi
 	if pl, err := api.playlists.Get(ctx, id); err == nil {
 		return dto.PlaylistToBaseItem(*pl, fields), true
 	}
+	if g, err := api.ds.Genre(ctx).Get(id); err == nil {
+		return dto.GenreToBaseItem(*g), true
+	}
 	return dto.BaseItemDto{}, false
 }
 
diff --git a/server/jellyfin/items_test.go b/server/jellyfin/items_test.go
index d8b9e60e8..3213379e5 100644
--- a/server/jellyfin/items_test.go
+++ b/server/jellyfin/items_test.go
@@ -917,6 +917,21 @@ var _ = Describe("Items", func() {
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
+		// Finamp's genre "See all" fetches the genre by id; a 404 white-screens it (see resolveItemByID).
+		It("resolves a genre id as a MusicGenre item", func() {
+			Expect(ds.Genre(context.Background()).(*tests.MockedGenreRepo).Put(&model.Genre{ID: "g1", Name: "Rock"})).To(Succeed())
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("g1"), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID("g1"))
+			invoke(api.getItem, w, r)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			var item dto.BaseItemDto
+			Expect(json.Unmarshal(w.Body.Bytes(), &item)).To(Succeed())
+			Expect(item.Id).To(Equal(dto.EncodeID("g1")))
+			Expect(item.Name).To(Equal("Rock"))
+			Expect(item.Type).To(Equal("MusicGenre"))
+		})
+
 		It("resolves a library-view id for an admin even though their Libraries slice is empty", func() {
 			ds.Library(context.Background()).(*tests.MockLibraryRepo).SetData(model.Libraries{{ID: 1, Name: "Music Library"}})
 			w := httptest.NewRecorder()
diff --git a/tests/mock_genre_repo.go b/tests/mock_genre_repo.go
index 50796efc0..ad3ee1a6a 100644
--- a/tests/mock_genre_repo.go
+++ b/tests/mock_genre_repo.go
@@ -32,6 +32,17 @@ func (r *MockedGenreRepo) GetAll(options ...model.QueryOptions) (model.Genres, e
 	return all, nil
 }
 
+func (r *MockedGenreRepo) Get(id string) (*model.Genre, error) {
+	if r.Error != nil {
+		return nil, r.Error
+	}
+	r.init()
+	if g, ok := r.Data[id]; ok {
+		return &g, nil
+	}
+	return nil, model.ErrNotFound
+}
+
 func (r *MockedGenreRepo) Put(g *model.Genre) error {
 	if r.Error != nil {
 		return r.Error

From 95b8d9dd041f53935f82eb9bca3f485d5b5f6a0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 11 Aug 2026 08:00:50 -0400
Subject: [PATCH 026/200] perf(genre): index genre filtering via join tables
 across all APIs (#5940)

Filtering by genre scanned every media_file/album row and JSON-parsed its
`tags` column (a per-row json_tree(tags) EXISTS) with no usable index, so
Finamp's genre screen took 1.9-6.5s per tap against a ~97k-track library.
Album and album-artist genre queries had the same unindexed shape.

Add normalized media_file_tags and album_tags join tables (genre only for
now, via an indexedTagNames allowlist), populated by a new updateTags in
Put (mirroring updateParticipants) and backfilled in the migration. Genre
filtering across the Jellyfin, Subsonic and native APIs now runs as an
index-backed semi-join through shared TagIDSemiJoin/TagNameSemiJoin helpers
instead of a full scan. On a copy of the production DB the per-request cost
for a typical genre drops from ~330ms to sub-millisecond, adding ~10MB.
---
 ...60811023338_add_item_genre_tag_indexes.sql |  34 ++++++
 persistence/album_repository.go               |   7 +-
 persistence/item_tags_test.go                 | 108 ++++++++++++++++++
 persistence/mediafile_repository.go           |   7 +-
 persistence/sql_tags.go                       |  71 ++++++++++++
 server/filter/filters.go                      |  33 ++----
 server/jellyfin/items.go                      |   4 +-
 server/subsonic/album_lists.go                |   4 +-
 8 files changed, 238 insertions(+), 30 deletions(-)
 create mode 100644 db/migrations/20260811023338_add_item_genre_tag_indexes.sql
 create mode 100644 persistence/item_tags_test.go

diff --git a/db/migrations/20260811023338_add_item_genre_tag_indexes.sql b/db/migrations/20260811023338_add_item_genre_tag_indexes.sql
new file mode 100644
index 000000000..1a7d75190
--- /dev/null
+++ b/db/migrations/20260811023338_add_item_genre_tag_indexes.sql
@@ -0,0 +1,34 @@
+-- +goose Up
+create table if not exists media_file_tags(
+    media_file_id varchar not null
+        references media_file (id) on delete cascade,
+    tag_id varchar not null
+        references tag (id) on delete cascade,
+    constraint media_file_tags unique (media_file_id, tag_id)
+);
+create index if not exists media_file_tags_tag_id on media_file_tags (tag_id);
+
+create table if not exists album_tags(
+    album_id varchar not null
+        references album (id) on delete cascade,
+    tag_id varchar not null
+        references tag (id) on delete cascade,
+    constraint album_tags unique (album_id, tag_id)
+);
+create index if not exists album_tags_tag_id on album_tags (tag_id);
+
+-- Backfill genre rows from the per-row `tags` JSON. json_tree over the "$.genre" subtree yields one
+-- row per node; the "id" key nodes carry the tag ids. Single scan per table, no correlated subquery.
+insert or ignore into media_file_tags (media_file_id, tag_id)
+select mf.id, jt.value
+from media_file mf, json_tree(mf.tags, '$.genre') jt
+where jt.key = 'id' and jt.atom is not null;
+
+insert or ignore into album_tags (album_id, tag_id)
+select al.id, jt.value
+from album al, json_tree(al.tags, '$.genre') jt
+where jt.key = 'id' and jt.atom is not null;
+
+-- +goose Down
+drop table if exists media_file_tags;
+drop table if exists album_tags;
diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 91e90127c..486099fc5 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -133,7 +133,7 @@ var albumFilters = sync.OnceValue(func() map[string]filterFunc {
 		"starred":         annotationBoolFilter("starred"),
 		"has_rating":      annotationBoolFilter("rating"),
 		"missing":         booleanFilter,
-		"genre_id":        tagIDFilter,
+		"genre_id":        genreFilter(AlbumGenres),
 		"role_total_id":   allRolesFilter,
 		"library_id":      libraryIdFilter,
 	}
@@ -212,7 +212,10 @@ func (r *albumRepository) Put(al *model.Album) error {
 		return err
 	}
 	al.ID = id
-	return r.updateParticipants(al.ID, al.Participants)
+	if err := r.updateParticipants(al.ID, al.Participants); err != nil {
+		return err
+	}
+	return r.updateTags(al.ID, al.Tags)
 }
 
 // TODO Move external metadata to a separated table
diff --git a/persistence/item_tags_test.go b/persistence/item_tags_test.go
new file mode 100644
index 000000000..a2317a1a5
--- /dev/null
+++ b/persistence/item_tags_test.go
@@ -0,0 +1,108 @@
+package persistence
+
+import (
+	"github.com/deluan/rest"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/pocketbase/dbx"
+)
+
+var _ = Describe("item genre tag indexes", func() {
+	var conn *dbx.DB
+	var mr model.MediaFileRepository
+	var ar model.AlbumRepository
+	var rock, jazz model.Tag
+
+	BeforeEach(func() {
+		ctx := request.WithUser(GinkgoT().Context(), model.User{ID: "userid"})
+		conn = GetDBXBuilder()
+		mr = NewMediaFileRepository(ctx, conn)
+		ar = NewAlbumRepository(ctx, conn)
+		// Test-only genre values, so they can't collide with the golden fixtures.
+		rock = model.NewTag(model.TagGenre, "GenreIdxRock")
+		jazz = model.NewTag(model.TagGenre, "GenreIdxJazz")
+		// The join tables FK to tag(id); the scanner adds tags before saving items.
+		Expect(NewTagRepository(ctx, conn).Add(1, rock, jazz)).To(Succeed())
+		// The suite shares one golden DB with no per-test restore, so undo the rows we add
+		// (media_file/album deletes cascade to the *_tags join rows; tag deletes cascade too).
+		DeferCleanup(func() {
+			_, _ = conn.NewQuery("DELETE FROM media_file WHERE id LIKE 'mf-%'").Execute()
+			_, _ = conn.NewQuery("DELETE FROM album WHERE id LIKE 'al-%'").Execute()
+			_, _ = conn.NewQuery("DELETE FROM tag WHERE id={:r} OR id={:j}").
+				Bind(dbx.Params{"r": rock.ID, "j": jazz.ID}).Execute()
+		})
+	})
+
+	tagIDsFor := func(table, col, id string) []string {
+		var rows []struct {
+			TagID string `db:"tag_id"`
+		}
+		err := conn.NewQuery("SELECT tag_id FROM " + table + " WHERE " + col + "={:id}").
+			Bind(dbx.Params{"id": id}).All(&rows)
+		Expect(err).ToNot(HaveOccurred())
+		ids := make([]string, len(rows))
+		for i, r := range rows {
+			ids[i] = r.TagID
+		}
+		return ids
+	}
+
+	Describe("media files", func() {
+		It("writes a media_file_tags row for each genre when the track is saved", func() {
+			mf := model.MediaFile{ID: "mf-g1", LibraryID: 1, Path: "/m/g1.mp3", Title: "G1",
+				Tags: model.Tags{model.TagGenre: []string{rock.TagValue, jazz.TagValue}}}
+			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(tagIDsFor("media_file_tags", "media_file_id", "mf-g1")).To(ConsistOf(rock.ID, jazz.ID))
+		})
+
+		It("replaces the rows when the genres change", func() {
+			mf := model.MediaFile{ID: "mf-g2", LibraryID: 1, Path: "/m/g2.mp3", Title: "G2",
+				Tags: model.Tags{model.TagGenre: []string{rock.TagValue}}}
+			Expect(mr.Put(&mf)).To(Succeed())
+			mf.Tags = model.Tags{model.TagGenre: []string{jazz.TagValue}}
+			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(tagIDsFor("media_file_tags", "media_file_id", "mf-g2")).To(ConsistOf(jazz.ID))
+		})
+
+		It("clears the rows when all genres are removed", func() {
+			mf := model.MediaFile{ID: "mf-g3", LibraryID: 1, Path: "/m/g3.mp3", Title: "G3",
+				Tags: model.Tags{model.TagGenre: []string{rock.TagValue}}}
+			Expect(mr.Put(&mf)).To(Succeed())
+			mf.Tags = model.Tags{}
+			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(tagIDsFor("media_file_tags", "media_file_id", "mf-g3")).To(BeEmpty())
+		})
+	})
+
+	Describe("albums", func() {
+		It("writes an album_tags row for each genre when the album is saved", func() {
+			al := model.Album{ID: "al-g1", LibraryID: 1, Name: "AG1",
+				Tags: model.Tags{model.TagGenre: []string{rock.TagValue, jazz.TagValue}}}
+			Expect(ar.Put(&al)).To(Succeed())
+			Expect(tagIDsFor("album_tags", "album_id", "al-g1")).To(ConsistOf(rock.ID, jazz.ID))
+		})
+	})
+
+	// The native (REST) API filters by genre_id; it must resolve through the join table too.
+	Describe("native genre_id filter", func() {
+		It("filters media files by genre_id", func() {
+			mf := model.MediaFile{ID: "mf-nat1", LibraryID: 1, Path: "/m/nat1.mp3", Title: "Nat1",
+				Tags: model.Tags{model.TagGenre: []string{rock.TagValue}}}
+			Expect(mr.Put(&mf)).To(Succeed())
+			res, err := mr.(model.ResourceRepository).ReadAll(rest.QueryOptions{Filters: map[string]any{"genre_id": rock.ID}})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.(model.MediaFiles)).To(ContainElement(HaveField("ID", "mf-nat1")))
+		})
+
+		It("filters albums by genre_id", func() {
+			al := model.Album{ID: "al-nat1", LibraryID: 1, Name: "ANat1",
+				Tags: model.Tags{model.TagGenre: []string{rock.TagValue}}}
+			Expect(ar.Put(&al)).To(Succeed())
+			res, err := ar.(model.ResourceRepository).ReadAll(rest.QueryOptions{Filters: map[string]any{"genre_id": rock.ID}})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.(model.Albums)).To(ContainElement(HaveField("ID", "al-nat1")))
+		})
+	})
+})
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index f372b30f5..f37e394cc 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -111,7 +111,7 @@ var mediaFileFilter = sync.OnceValue(func() map[string]filterFunc {
 		"title":      fullTextFilter("media_file", "mbz_recording_id", "mbz_release_track_id"),
 		"starred":    annotationBoolFilter("starred"),
 		"has_rating": annotationBoolFilter("rating"),
-		"genre_id":   tagIDFilter,
+		"genre_id":   genreFilter(SongGenres),
 		"missing":    booleanFilter,
 		"artists_id": mediaFileArtistFilter,
 		"library_id": libraryIdFilter,
@@ -181,7 +181,10 @@ func (r *mediaFileRepository) Put(m *model.MediaFile) error {
 		return err
 	}
 	m.ID = id
-	return r.updateParticipants(m.ID, m.Participants)
+	if err := r.updateParticipants(m.ID, m.Participants); err != nil {
+		return err
+	}
+	return r.updateTags(m.ID, m.Tags)
 }
 
 func (r *mediaFileRepository) UpdateProbeData(id string, data string) error {
diff --git a/persistence/sql_tags.go b/persistence/sql_tags.go
index 5177bc8e4..11f9fe00e 100644
--- a/persistence/sql_tags.go
+++ b/persistence/sql_tags.go
@@ -48,6 +48,77 @@ func marshalTags(tags model.Tags) string {
 	return string(res)
 }
 
+// indexedTagNames are the tag types materialized into the <table>_tags join tables, so filtering by
+// them is an index-backed semi-join instead of a per-row json_tree(tags) scan. Genre only for now.
+var indexedTagNames = []model.TagName{model.TagGenre}
+
+// updateTags rewrites this item's <table>_tags rows from its in-memory tags, mirroring
+// updateParticipants (delete-then-insert in the same Put; JOIN to tag skips not-yet-saved ids).
+func (r sqlRepository) updateTags(itemID string, tags model.Tags) error {
+	del := Delete(r.tableName + "_tags").Where(Eq{r.tableName + "_id": itemID})
+	if _, err := r.executeSQL(del); err != nil {
+		return err
+	}
+	var tagIDs []string
+	for _, name := range indexedTagNames {
+		for _, value := range tags.Values(name) {
+			tagIDs = append(tagIDs, model.NewTag(name, value).ID)
+		}
+	}
+	if len(tagIDs) == 0 {
+		return nil
+	}
+	idsJSON, err := json.Marshal(tagIDs)
+	if err != nil {
+		return fmt.Errorf("marshaling tag ids: %w", err)
+	}
+	query := fmt.Sprintf(`
+		INSERT INTO %[1]s_tags (%[1]s_id, tag_id)
+		SELECT ?, value FROM json_each(?)
+		JOIN tag ON tag.id = value
+		ON CONFLICT (%[1]s_id, tag_id) DO NOTHING`, r.tableName)
+	_, err = r.executeSQL(Expr(query, itemID, string(idsJSON)))
+	return err
+}
+
+// genreFilterDef builds indexed genre filters for one item type. Callers use the exported SongGenres / AlbumGenres instances.
+type genreFilterDef struct{ idCol, table, joinCol string }
+
+var (
+	SongGenres  = genreFilterDef{"media_file.id", "media_file_tags", "media_file_id"}
+	AlbumGenres = genreFilterDef{"album.id", "album_tags", "album_id"}
+)
+
+// ByID matches items tagged with any of the given genre tag ids (scalar or slice).
+func (g genreFilterDef) ByID(tagIDs any) Sqlizer {
+	sub, args, _ := Select(g.joinCol).From(g.table).Where(Eq{"tag_id": tagIDs}).ToSql()
+	return Expr(g.idCol+" IN ("+sub+")", args...)
+}
+
+// ByName matches by genre name (Subsonic passes a name, not an id), resolved through the tag
+// dictionary, which is uniquely indexed on (tag_name, tag_value).
+func (g genreFilterDef) ByName(genre string) Sqlizer {
+	sub, args, _ := Select("jt." + g.joinCol).From(g.table + " jt").
+		Join("tag on tag.id = jt.tag_id").
+		Where(And{Eq{"tag.tag_name": "genre"}, Like{"tag.tag_value": genre}}).ToSql()
+	return Expr(g.idCol+" IN ("+sub+")", args...)
+}
+
+// AlbumArtistsByGenreID matches album artists of albums tagged with any of the genre ids. It's a
+// two-table join (album_artists ⨝ album_tags), so it doesn't fit the single-table genreFilterDef.
+func AlbumArtistsByGenreID(tagIDs []string) Sqlizer {
+	sub, args, _ := Select("aa.artist_id").From("album_artists aa").
+		Join("album_tags at on at.album_id = aa.album_id").
+		Where(And{Eq{"aa.role": "albumartist"}, Eq{"at.tag_id": tagIDs}}).ToSql()
+	return Expr("artist.id IN ("+sub+")", args...)
+}
+
+func genreFilter(filter genreFilterDef) func(_ string, v any) Sqlizer {
+	return func(_ string, v any) Sqlizer {
+		return filter.ByID(v)
+	}
+}
+
 // tagIDFilter matches rows whose tags JSON contains the tag id(s); a "<name>_id" key maps to "$.<name>".
 func tagIDFilter(name string, idValue any) Sqlizer {
 	name = strings.TrimSuffix(name, "_id")
diff --git a/server/filter/filters.go b/server/filter/filters.go
index 62d8f0523..9014bb799 100644
--- a/server/filter/filters.go
+++ b/server/filter/filters.go
@@ -112,7 +112,7 @@ func SongsByGenreAndYearRange(genre string, fromYear, toYear int) Options {
 	options := Options{}
 	ff := And{}
 	if genre != "" {
-		ff = append(ff, filterByGenre(genre))
+		ff = append(ff, persistence.SongGenres.ByName(genre))
 	}
 	if fromYear != 0 {
 		ff = append(ff, GtOrEq{"year": fromYear})
@@ -171,16 +171,17 @@ func ArtistsByRole(opts Options, role model.Role) Options {
 	return opts
 }
 
-func ByGenre(genre string) Options {
-	return addDefaultFilters(Options{
-		Sort:    "name",
-		Filters: filterByGenre(genre),
-	})
+// SongsByGenreID / AlbumsByGenreID (by tag id) and AlbumsByGenre / SongsByGenre (by name, wrapped
+// as Options for Subsonic) delegate to the persistence genre filters, which own the join schema.
+func SongsByGenreID(genreIds []string) Sqlizer  { return persistence.SongGenres.ByID(genreIds) }
+func AlbumsByGenreID(genreIds []string) Sqlizer { return persistence.AlbumGenres.ByID(genreIds) }
+
+func AlbumsByGenre(genre string) Options {
+	return addDefaultFilters(Options{Sort: "name", Filters: persistence.AlbumGenres.ByName(genre)})
 }
 
-// ByGenreID matches items (albums or songs) tagged with any of the given genre tag ids.
-func ByGenreID(genreIds []string) Sqlizer {
-	return genreTagFilter(Eq{"value": genreIds})
+func SongsByGenre(genre string) Options {
+	return addDefaultFilters(Options{Sort: "name", Filters: persistence.SongGenres.ByName(genre)})
 }
 
 // ByAlbumID matches media files belonging to any of the given albums.
@@ -198,14 +199,8 @@ func SongsByYears(years []int) Sqlizer {
 	return Eq{"year": years}
 }
 
-// ArtistsByGenreID matches artists credited as album artist on an album with any of the given
-// genre tag ids. Non-correlated semi-join: the correlated EXISTS form rescans albums per artist row.
 func ArtistsByGenreID(genreIds []string) Sqlizer {
-	return Expr(
-		`artist.id IN (SELECT jt.value FROM album, json_tree(album.participants, '$.albumartist') jt
-			WHERE jt.atom IS NOT NULL AND ?)`,
-		genreTagFilter(Eq{"value": genreIds}),
-	)
+	return persistence.AlbumArtistsByGenreID(genreIds)
 }
 
 // tagIDFilter builds an EXISTS over the given tag role's entries in the tags JSON, matching each
@@ -214,17 +209,11 @@ func tagIDFilter(tagName string, cond Sqlizer) Sqlizer {
 	return persistence.Exists(`json_tree(tags, "$.`+tagName+`")`, And{NotEq{"atom": nil}, cond})
 }
 
-func genreTagFilter(cond Sqlizer) Sqlizer { return tagIDFilter("genre", cond) }
-
 // ByStudioID matches items (albums or songs) whose record-label tag id is in ids.
 func ByStudioID(ids []string) Sqlizer {
 	return tagIDFilter("recordlabel", Eq{"value": ids})
 }
 
-func filterByGenre(genre string) Sqlizer {
-	return genreTagFilter(Like{"value": genre})
-}
-
 func ByRating() Options {
 	return addDefaultFilters(Options{Sort: "rating", Order: "desc", Filters: Gt{"rating": 0}})
 }
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index 9b85b8a62..fed5bbbc8 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -577,7 +577,7 @@ func (api *Router) listAlbums(ctx context.Context, opts model.QueryOptions, q it
 		filters = append(filters, notMissing)
 	}
 	if len(q.genreIds) > 0 {
-		filters = append(filters, filter.ByGenreID(q.genreIds))
+		filters = append(filters, filter.AlbumsByGenreID(q.genreIds))
 	}
 	if len(q.years) > 0 {
 		filters = append(filters, filter.AlbumsByYears(q.years))
@@ -624,7 +624,7 @@ func (api *Router) listSongs(ctx context.Context, opts model.QueryOptions, q ite
 		filters = append(filters, filter.ByAlbumID(q.albumIds))
 	}
 	if len(q.genreIds) > 0 {
-		filters = append(filters, filter.ByGenreID(q.genreIds))
+		filters = append(filters, filter.SongsByGenreID(q.genreIds))
 	}
 	if len(q.years) > 0 {
 		filters = append(filters, filter.SongsByYears(q.years))
diff --git a/server/subsonic/album_lists.go b/server/subsonic/album_lists.go
index 041a3b8f2..ba5f88a68 100644
--- a/server/subsonic/album_lists.go
+++ b/server/subsonic/album_lists.go
@@ -46,7 +46,7 @@ func (api *Router) getAlbumList(r *http.Request) (model.Albums, int64, error) {
 		if err != nil {
 			return nil, 0, err
 		}
-		opts = filter.ByGenre(genre)
+		opts = filter.AlbumsByGenre(genre)
 	case "byYear":
 		fromYear, err := p.Int("fromYear")
 		if err != nil {
@@ -267,7 +267,7 @@ func (api *Router) GetSongsByGenre(r *http.Request) (*responses.Subsonic, error)
 	if err != nil {
 		return nil, err
 	}
-	opts := filter.ByGenre(genre)
+	opts := filter.SongsByGenre(genre)
 	opts = filter.ApplyLibraryFilter(opts, musicFolderIds)
 
 	ctx := r.Context()

From c4126fa674a0ac48731207ff395c08d41644833f Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Tue, 11 Aug 2026 09:14:17 -0400
Subject: [PATCH 027/200] fix(jellyfin): emit SortName for artists and albums,
 honoring PreferSortTags

Finamp's A-Z fast scroll re-derives each item's sort key client-side from
SortName, paging until it reaches the tapped letter. We only emitted SortName
for songs, so Finamp fell back to reconstructing a key from the display name,
which diverges from the order_* key the list is actually sorted by (curly
quotes, non-English articles). The scan then believed it had passed the
letter and scrolled back to the top instead of loading further pages.

Emit SortName for artists and albums using the same key the persistence
layer sorts by, via a sortName helper that mirrors Subsonic's PreferSortTags
handling: order_* names by default, sort tags when the config is enabled.
The song mapper now honors the config too, instead of always preferring the
sort tag. Also parse Fields in the /Artists* handlers, which ignored the
parameter entirely, so no field-gated data could ever be returned there.
---
 server/jellyfin/browsing.go          |  1 +
 server/jellyfin/dto/mappers.go       | 17 +++++++++-
 server/jellyfin/dto/mappers_test.go  | 49 +++++++++++++++++++++++++---
 server/jellyfin/e2e/browsing_test.go | 19 +++++++++++
 4 files changed, 81 insertions(+), 5 deletions(-)

diff --git a/server/jellyfin/browsing.go b/server/jellyfin/browsing.go
index 29fe48c2b..faf43d352 100644
--- a/server/jellyfin/browsing.go
+++ b/server/jellyfin/browsing.go
@@ -35,6 +35,7 @@ func (api *Router) listArtistsByRole(w http.ResponseWriter, r *http.Request, rol
 		scopeIDs: scopeIDs,
 		genreIds: decodedQueryIDs(r, "genreids"),
 		search:   searchTerm(p),
+		fields:   dto.ParseFields(p.Strings("fields")...),
 	}
 	if q.search != "" {
 		opts.Max = clampLimit(opts.Max, defaultSearchLimit, maxSearchLimit)
diff --git a/server/jellyfin/dto/mappers.go b/server/jellyfin/dto/mappers.go
index 352fce11d..31cdba1dd 100644
--- a/server/jellyfin/dto/mappers.go
+++ b/server/jellyfin/dto/mappers.go
@@ -10,6 +10,15 @@ import (
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
+// sortName must match the persistence ORDER BY key (see setSortMappings): Finamp's A-Z jump
+// scans SortName client-side, and any mismatch with the server's sort order scrolls to the top.
+func sortName(sortTag, orderName, displayName string) string {
+	if conf.Server.PreferSortTags {
+		return cmp.Or(sortTag, orderName, displayName)
+	}
+	return cmp.Or(orderName, displayName)
+}
+
 // Jellyfin wire times are ticks: 100ns units, i.e. 10,000 per millisecond.
 const ticksPerMillis = 10_000
 
@@ -152,7 +161,7 @@ func SongToBaseItem(mf model.MediaFile, fields Fields) BaseItemDto {
 		item.MediaSources = []MediaSourceInfo{MediaSourceFromMediaFile(mf)}
 	}
 	if fields.Has("SortName") {
-		item.SortName = cmp.Or(mf.SortTitle, mf.OrderTitle, mf.Title)
+		item.SortName = sortName(mf.SortTitle, mf.OrderTitle, mf.Title)
 	}
 	// Real Jellyfin splits Artists/ArtistItems per track artist (AlbumArtists stays a single credit).
 	// Participants holds the per-artist list; fall back to the flattened display fields when absent.
@@ -281,6 +290,9 @@ func AlbumToBaseItem(al model.Album, fields Fields) BaseItemDto {
 	// The album's own ReplayGain gain (dB at the RG2 -18 LUFS reference) — same
 	// convention as tracks; clients read it off the album item as NormalizationGain.
 	item.NormalizationGain = al.RGAlbumGain
+	if fields.Has("SortName") {
+		item.SortName = sortName(al.SortAlbumName, al.OrderAlbumName, al.Name)
+	}
 	return item
 }
 
@@ -302,6 +314,9 @@ func ArtistToBaseItem(ar model.Artist, fields Fields) BaseItemDto {
 	if tag != "" {
 		item.ImageTags = map[string]string{"Primary": tag}
 	}
+	if fields.Has("SortName") {
+		item.SortName = sortName(ar.SortArtistName, ar.OrderArtistName, ar.Name)
+	}
 	return item
 }
 
diff --git a/server/jellyfin/dto/mappers_test.go b/server/jellyfin/dto/mappers_test.go
index a7b381c5c..77b78e55f 100644
--- a/server/jellyfin/dto/mappers_test.go
+++ b/server/jellyfin/dto/mappers_test.go
@@ -46,10 +46,9 @@ var _ = Describe("mappers", func() {
 		mf := model.MediaFile{ID: "s1", Title: "Song", Size: 2_500_000, Suffix: "mp3", Duration: 60,
 			SortTitle: "sort song", Lyrics: `[{"line":[{"value":"la"}]}]`}
 
-		It("omits MediaSources and SortName when Fields does not ask for them", func() {
+		It("omits MediaSources when Fields does not ask for them", func() {
 			item := SongToBaseItem(mf, nil)
 			Expect(item.MediaSources).To(BeNil())
-			Expect(item.SortName).To(BeEmpty())
 		})
 
 		It("includes MediaSources only when Fields=MediaSources", func() {
@@ -58,8 +57,50 @@ var _ = Describe("mappers", func() {
 			Expect(item.MediaSources[0].Size).To(Equal(int64(2_500_000)))
 		})
 
-		It("includes SortName (from the sort title) only when Fields=SortName", func() {
-			Expect(SongToBaseItem(mf, ParseFields("SortName")).SortName).To(Equal("sort song"))
+		// SortName must match the server sort order — see the sortName helper.
+		Describe("SortName", func() {
+			song := model.MediaFile{ID: "s1", Title: "The Song", SortTitle: "Song, The", OrderTitle: "song"}
+			ar := model.Artist{ID: "art-1", Name: "The B-52's", SortArtistName: "B-52's, The", OrderArtistName: "b-52's"}
+			al := model.Album{ID: "alb-1", Name: "The Wall", SortAlbumName: "Wall, The", OrderAlbumName: "wall"}
+
+			BeforeEach(func() {
+				DeferCleanup(configtest.SetupConfig())
+			})
+
+			It("is omitted unless Fields=SortName", func() {
+				Expect(SongToBaseItem(song, nil).SortName).To(BeEmpty())
+				Expect(ArtistToBaseItem(ar, nil).SortName).To(BeEmpty())
+				Expect(AlbumToBaseItem(al, nil).SortName).To(BeEmpty())
+			})
+
+			It("uses the order names by default, ignoring sort tags", func() {
+				Expect(SongToBaseItem(song, ParseFields("SortName")).SortName).To(Equal("song"))
+				Expect(ArtistToBaseItem(ar, ParseFields("SortName")).SortName).To(Equal("b-52's"))
+				Expect(AlbumToBaseItem(al, ParseFields("SortName")).SortName).To(Equal("wall"))
+			})
+
+			Context("with PreferSortTags", func() {
+				BeforeEach(func() {
+					conf.Server.PreferSortTags = true
+				})
+
+				It("prefers the sort tags", func() {
+					Expect(SongToBaseItem(song, ParseFields("SortName")).SortName).To(Equal("Song, The"))
+					Expect(ArtistToBaseItem(ar, ParseFields("SortName")).SortName).To(Equal("B-52's, The"))
+					Expect(AlbumToBaseItem(al, ParseFields("SortName")).SortName).To(Equal("Wall, The"))
+				})
+
+				It("falls back to the order name when there is no sort tag", func() {
+					Expect(ArtistToBaseItem(model.Artist{ID: "a", Name: "The X", OrderArtistName: "x"},
+						ParseFields("SortName")).SortName).To(Equal("x"))
+				})
+			})
+
+			It("falls back to the display name when order name and sort tag are empty", func() {
+				Expect(SongToBaseItem(model.MediaFile{ID: "s", Title: "T"}, ParseFields("SortName")).SortName).To(Equal("T"))
+				Expect(ArtistToBaseItem(model.Artist{ID: "a", Name: "N"}, ParseFields("SortName")).SortName).To(Equal("N"))
+				Expect(AlbumToBaseItem(model.Album{ID: "al", Name: "A"}, ParseFields("SortName")).SortName).To(Equal("A"))
+			})
 		})
 
 		It("sets HasLyrics from the media file's lyrics", func() {
diff --git a/server/jellyfin/e2e/browsing_test.go b/server/jellyfin/e2e/browsing_test.go
index be6d6bb5d..14ab8b62b 100644
--- a/server/jellyfin/e2e/browsing_test.go
+++ b/server/jellyfin/e2e/browsing_test.go
@@ -2,6 +2,7 @@ package e2e
 
 import (
 	"net/http"
+	"slices"
 	"sort"
 	"time"
 
@@ -79,6 +80,24 @@ var _ = Describe("Browsing", func() {
 			Expect(names(q.Items)).To(ConsistOf("The Beatles", "Led Zeppelin", "Miles Davis", "Solo Artist"))
 		})
 
+		// Finamp's A-Z jump scans SortName client-side, so it must follow the response order.
+		It("returns artists' SortName matching the server sort order when Fields=SortName", func() {
+			plain := queryResult(get("/Artists/AlbumArtists?Recursive=true&SortBy=SortName"))
+			for _, it := range plain.Items {
+				Expect(it.SortName).To(BeEmpty())
+			}
+			q := queryResult(get("/Artists/AlbumArtists?Recursive=true&SortBy=SortName&Fields=SortName"))
+			Expect(q.Items).ToNot(BeEmpty())
+			sortNames := make([]string, 0, len(q.Items))
+			for _, it := range q.Items {
+				Expect(it.SortName).ToNot(BeEmpty())
+				sortNames = append(sortNames, it.SortName)
+			}
+			Expect(slices.IsSorted(sortNames)).To(BeTrue(), "SortName values must follow the response order: %v", sortNames)
+			// "The Beatles" must be filed under B, exposing the article-stripped key to clients.
+			Expect(sortNames).To(ContainElement("beatles"))
+		})
+
 		It("lists all genres", func() {
 			q := queryResult(get("/Items?IncludeItemTypes=MusicGenre&Recursive=true"))
 			Expect(q.TotalRecordCount).To(Equal(3))

From 9e95b19a4faa325d106630a7c19cd71f31db43b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 11 Aug 2026 10:42:39 -0400
Subject: [PATCH 028/200] feat(artwork): make the artwork image size cap
 configurable (#5931)

* feat(artwork): make the artwork image size cap configurable

Replace the hardcoded 20MB cap on resolved image reads with a new
MaxImageSize config option. Load floors it at MaxImageUploadSize so an
accepted upload can never be too large for the resolver to read back.

* fix(conf): reject zero-valued byte-size options at startup

ParseBytes accepts "0", but parseSize silently substitutes the default
for it, so the accepted config would differ from the effective limit.

* fix(conf): reject byte-size options that overflow int64

A raw value above math.MaxInt64 parses as a valid uint64 but wraps to a
negative int64 in parseSize, giving readCapped a non-positive LimitReader
bound so every artwork read comes back empty.
---
 conf/configuration.go          | 31 +++++++++++++++++++++----
 conf/configuration_test.go     | 42 +++++++++++++++++++++++-----------
 conf/export_test.go            |  2 +-
 consts/consts.go               |  1 +
 core/artwork/processor.go      | 13 +++++++----
 core/artwork/processor_test.go | 13 ++++++++++-
 core/artwork/resolve_test.go   |  2 +-
 core/artwork/uploader.go       |  8 +++++--
 8 files changed, 85 insertions(+), 27 deletions(-)

diff --git a/conf/configuration.go b/conf/configuration.go
index 5122b15eb..fbbaaf252 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -5,6 +5,7 @@ import (
 	"encoding"
 	"encoding/json"
 	"fmt"
+	"math"
 	"net/url"
 	"os"
 	"path/filepath"
@@ -90,6 +91,7 @@ type configOptions struct {
 	EnableUserEditing               bool
 	EnableArtworkUpload             bool
 	MaxImageUploadSize              string
+	MaxImageSize                    string
 	EnableSharing                   bool
 	ShareURL                        string
 	DefaultShareExpiration          time.Duration
@@ -421,7 +423,8 @@ func Load(noConfigDump bool) {
 		validateBackupSchedule,
 		validatePlaylistsPath,
 		validatePurgeMissingOption,
-		validateMaxImageUploadSize,
+		validateByteSize("MaxImageUploadSize", Server.MaxImageUploadSize),
+		validateByteSize("MaxImageSize", Server.MaxImageSize),
 		validateURL("ExtAuth.LogoutURL", Server.ExtAuth.LogoutURL),
 	)
 	if err != nil {
@@ -481,6 +484,14 @@ func Load(noConfigDump bool) {
 		Server.UICoverArtSize = newValue
 	}
 
+	// Floor MaxImageSize at MaxImageUploadSize so accepted uploads can always be read back.
+	imgSize, _ := humanize.ParseBytes(Server.MaxImageSize)
+	uploadSize, _ := humanize.ParseBytes(Server.MaxImageUploadSize)
+	if imgSize < uploadSize {
+		log.Warn("MaxImageSize must be at least MaxImageUploadSize, raising", "value", Server.MaxImageSize, "newValue", Server.MaxImageUploadSize)
+		Server.MaxImageSize = Server.MaxImageUploadSize
+	}
+
 	// Call init hooks
 	for _, hook := range hooks {
 		hook()
@@ -806,11 +817,20 @@ func validatePurgeMissingOption() error {
 	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)
+func validateByteSize(name, value string) func() error {
+	return func() error {
+		size, err := humanize.ParseBytes(value)
+		if err != nil {
+			return fmt.Errorf("invalid %s %q: use values like '10MB', '1GB', or raw bytes like '10485760': %w", name, value, err)
+		}
+		if size == 0 {
+			return fmt.Errorf("invalid %s %q: must be greater than zero", name, value)
+		}
+		if size > math.MaxInt64 {
+			return fmt.Errorf("invalid %s %q: value is too large", name, value)
+		}
+		return nil
 	}
-	return nil
 }
 
 func validateEnforceNonRootUser() error {
@@ -980,6 +1000,7 @@ func setViperDefaults() {
 	viper.SetDefault("uiplaybackreportinterval", consts.DefaultUIPlaybackReportInterval)
 	viper.SetDefault("enableartworkupload", true)
 	viper.SetDefault("maximageuploadsize", consts.DefaultMaxImageUploadSize)
+	viper.SetDefault("maximagesize", consts.DefaultMaxImageSize)
 	viper.SetDefault("enablesharing", true)
 	viper.SetDefault("shareurl", "")
 	viper.SetDefault("defaultshareexpiration", 8760*time.Hour)
diff --git a/conf/configuration_test.go b/conf/configuration_test.go
index 4eaa8e3d8..ac6477572 100644
--- a/conf/configuration_test.go
+++ b/conf/configuration_test.go
@@ -336,19 +336,10 @@ var _ = Describe("Configuration", func() {
 
 	})
 
-	Describe("ValidateMaxImageUploadSize", func() {
-		BeforeEach(func() {
-			viper.Reset()
-			conf.SetViperDefaults()
-			viper.SetDefault("datafolder", GinkgoT().TempDir())
-			viper.SetDefault("loglevel", "error")
-			conf.ResetConf()
-		})
-
+	Describe("ValidateByteSize", func() {
 		DescribeTable("accepts valid size values",
 			func(input string) {
-				conf.Server.MaxImageUploadSize = input
-				Expect(conf.ValidateMaxImageUploadSize()).To(Succeed())
+				Expect(conf.ValidateByteSize("MaxImageSize", input)()).To(Succeed())
 			},
 			Entry("megabytes", "10MB"),
 			Entry("gigabytes", "1GB"),
@@ -359,14 +350,39 @@ var _ = Describe("Configuration", func() {
 
 		DescribeTable("rejects invalid size values",
 			func(input string) {
-				conf.Server.MaxImageUploadSize = input
-				Expect(conf.ValidateMaxImageUploadSize()).To(MatchError(ContainSubstring("invalid MaxImageUploadSize")))
+				Expect(conf.ValidateByteSize("MaxImageSize", input)()).To(MatchError(ContainSubstring("invalid MaxImageSize")))
 			},
 			Entry("garbage string", "not-a-size"),
 			Entry("negative-looking", "-10MB"),
+			Entry("zero", "0"),
+			Entry("zero with unit", "0MB"),
+			Entry("overflows int64", "9223372036854775808"),
 		)
 	})
 
+	Describe("MaxImageSize floor", func() {
+		BeforeEach(func() {
+			viper.Reset()
+			conf.SetViperDefaults()
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("loglevel", "error")
+			conf.ResetConf()
+		})
+
+		It("is raised to MaxImageUploadSize when configured lower", func() {
+			viper.SetDefault("maximagesize", "5MB")
+			viper.SetDefault("maximageuploadsize", "50MB")
+			conf.Load(true)
+			Expect(conf.Server.MaxImageSize).To(Equal("50MB"))
+		})
+
+		It("keeps a larger MaxImageSize unchanged", func() {
+			viper.SetDefault("maximagesize", "30MB")
+			conf.Load(true)
+			Expect(conf.Server.MaxImageSize).To(Equal("30MB"))
+		})
+	})
+
 	Describe("EnforceNonRootUser", func() {
 		It("defaults to false", func() {
 			conf.Load(true)
diff --git a/conf/export_test.go b/conf/export_test.go
index cbb64b3d0..d1e1a6f99 100644
--- a/conf/export_test.go
+++ b/conf/export_test.go
@@ -14,7 +14,7 @@ var NormalizeSearchBackend = normalizeSearchBackend
 
 var ToPascalCase = toPascalCase
 
-var ValidateMaxImageUploadSize = validateMaxImageUploadSize
+var ValidateByteSize = validateByteSize
 
 func SetRuntimeInfoForTest(goos string, euid int) func() {
 	oldGOOS := currentGOOS
diff --git a/consts/consts.go b/consts/consts.go
index 46906b8b5..aed8ecf66 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -112,6 +112,7 @@ const (
 const (
 	DefaultUICoverArtSize     = 300
 	DefaultMaxImageUploadSize = "10MB"
+	DefaultMaxImageSize       = "20MB"
 )
 
 // Prometheus options
diff --git a/core/artwork/processor.go b/core/artwork/processor.go
index c3cf15b71..6ce76bf45 100644
--- a/core/artwork/processor.go
+++ b/core/artwork/processor.go
@@ -13,6 +13,8 @@ import (
 	"sync"
 	"time"
 
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/artwork/blurhash"
 	"github.com/navidrome/navidrome/core/artwork/dominant"
 	"github.com/navidrome/navidrome/core/artwork/thumbhash"
@@ -51,7 +53,9 @@ const thumbnailSize = 100
 
 // maxImageBytes caps a resolved image read: a user-editable ExternalImageURL could point at
 // an arbitrarily large endpoint.
-const maxImageBytes = 20 << 20
+func maxImageBytes() int64 {
+	return parseSize(conf.Server.MaxImageSize, consts.DefaultMaxImageSize)
+}
 
 // maxImagePixels guards against decompression bombs: a tiny file can declare a canvas that
 // image.Decode would expand into gigabytes.
@@ -202,12 +206,13 @@ func writeAbsent(ctx context.Context, repo model.ArtworkRepository, item model.A
 }
 
 func readCapped(r io.Reader) ([]byte, error) {
-	data, err := io.ReadAll(io.LimitReader(r, maxImageBytes+1))
+	limit := maxImageBytes()
+	data, err := io.ReadAll(io.LimitReader(r, limit+1))
 	if err != nil {
 		return nil, err
 	}
-	if len(data) > maxImageBytes {
-		return nil, fmt.Errorf("image exceeds size cap %d", maxImageBytes)
+	if int64(len(data)) > limit {
+		return nil, fmt.Errorf("image exceeds size cap %d", limit)
 	}
 	return data, nil
 }
diff --git a/core/artwork/processor_test.go b/core/artwork/processor_test.go
index d326dde09..8d30975cd 100644
--- a/core/artwork/processor_test.go
+++ b/core/artwork/processor_test.go
@@ -394,7 +394,7 @@ var _ = Describe("processor.acquire", func() {
 		imgPath := filepath.Join(tmpDir, "artwork", "radio", "big_test.jpg")
 		f, err := os.Create(imgPath)
 		Expect(err).ToNot(HaveOccurred())
-		Expect(f.Truncate(maxImageBytes + 1)).To(Succeed())
+		Expect(f.Truncate(maxImageBytes() + 1)).To(Succeed())
 		Expect(f.Close()).To(Succeed())
 
 		radioRepo := tests.CreateMockedRadioRepo()
@@ -493,3 +493,14 @@ var _ = Describe("makeThumbnail", func() {
 		Expect(thumb.Pix[3]).To(BeNumerically("==", 128))
 	})
 })
+
+var _ = Describe("maxImageBytes", func() {
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+	})
+
+	It("reads MaxImageSize from config", func() {
+		conf.Server.MaxImageSize = "30MB"
+		Expect(maxImageBytes()).To(Equal(int64(30_000_000)))
+	})
+})
diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.go
index fc1a6a3ff..9a0962cf2 100644
--- a/core/artwork/resolve_test.go
+++ b/core/artwork/resolve_test.go
@@ -625,7 +625,7 @@ var _ = Describe("decodeTile", func() {
 	})
 
 	It("rejects a tile larger than the size cap", func() {
-		data := bytes.Repeat([]byte{0}, maxImageBytes+1)
+		data := bytes.Repeat([]byte{0}, int(maxImageBytes())+1)
 		_, err := decodeTile(io.NopCloser(bytes.NewReader(data)))
 		Expect(err).To(HaveOccurred())
 	})
diff --git a/core/artwork/uploader.go b/core/artwork/uploader.go
index 9c38ae2e5..76526af3c 100644
--- a/core/artwork/uploader.go
+++ b/core/artwork/uploader.go
@@ -17,10 +17,14 @@ import (
 
 // MaxImageUploadSize returns the configured max upload size in bytes, or the built-in default.
 func MaxImageUploadSize() int64 {
-	if size, err := humanize.ParseBytes(conf.Server.MaxImageUploadSize); err == nil && size > 0 {
+	return parseSize(conf.Server.MaxImageUploadSize, consts.DefaultMaxImageUploadSize)
+}
+
+func parseSize(value, fallback string) int64 {
+	if size, err := humanize.ParseBytes(value); err == nil && size > 0 {
 		return int64(size)
 	}
-	size, _ := humanize.ParseBytes(consts.DefaultMaxImageUploadSize)
+	size, _ := humanize.ParseBytes(fallback)
 	return int64(size)
 }
 

From 036c9cab9671505c83fce6523f55d97b152b3b32 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 11 Aug 2026 18:34:27 -0400
Subject: [PATCH 029/200] feat(jellyfin): send a synthetic placeholder blurhash
 for unresolved artwork (#5941)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(artwork): let callers pin the blurhash component counts

* feat(artwork): synthesize a unique placeholder blurhash from a seed

* fix(artwork): base the synthetic-hash no-collision guarantee on the prefix, not length

The prior comment and test claimed a synthetic value could never collide with a
real one because it's always shorter. That's false: components() targets ~16
tiles by scaling one axis down as the other hits the 9 cap, so an extreme
aspect ratio (e.g. 10x200) collapses to 1x9 = 9 components, which encodes to
the same 22 characters as a 3x3 synthetic hash. The old test only exercised a
square 64x64 gradient, so it never caught this.

The real guarantee is structural, not length-based: the first character encodes
shape as (xComp-1)+(yComp-1)*9, and components() derives xf*yf = 16 exactly
before flooring/capping (xf = sqrt(16w/h), yf = xf*h/w = sqrt(16h/w), so
xf*yf = sqrt(256) = 16). Two factors both in [2,3) can't multiply to 16, so
Encode can never derive 3x3 - the synthetic prefix 'K' is structurally
exclusive to Synthetic. Replaced the length-based test with one that sweeps
extreme aspect ratios and asserts no real encode ever produces prefix 'K',
alongside the assertion that Synthetic always does.

* feat(artwork): tint a synthetic blurhash from a base colour

Parses baseColor into HSL and clamps saturation/lightness so the tint
stays muted; per-cell hashing (unchanged) is what keeps a shared tint
across an album's tracks from colliding, as the new 1M-seed spec
proves under a single fixed colour.

* fix(artwork): trim over-long comment in synthetic blurhash test

Review flagged the collision spec's comment for exceeding the 2-line
budget; the Finamp rationale it restated already lives in the design
doc and commit history.

* feat(jellyfin): send a synthetic blurhash for unresolved artwork

Clients render nothing where a placeholder belongs when ImageBlurHashes
is omitted for pending artwork. primaryImage now synthesizes a value
(seeded on the tag, so a cover swap re-keys it) whenever a tag is
present but no blurhash has been computed yet. Known-absent artwork
(ImageAbsent) is unaffected: it still emits neither tag nor blurhash,
since GetOrPlaceholder would otherwise pin a shared placeholder under a
distinct cache key for a year.

* fix(jellyfin): avoid computing a synthetic blurhash when a real one exists

cmp.Or evaluates both arguments before choosing between them, so
blurhash.Synthetic ran (and was discarded) on every call even when
img.BlurHash was already set. That's the common case in production:
artwork_repository.go populates BlurHash from persisted values once a
scan resolves it, so a healthy library paid the synthesis cost (xxh3
hashing, HSL conversion, image alloc, DCT encode) on every mapped item
for a value it never used. Branch on emptiness first instead.

* feat(jellyfin): tint a pending track's placeholder with its album's colour

primaryImage never reaches the embeddedArtPending branch of
SongToBaseItem, since there is no resolved image yet to feed it. Seed
the synthetic blurhash on mf.ID (so the value stays unique and the
client still issues the read-through request) but tint it with the
album's DominantColor, which is already hydrated on MediaFile at no
extra cost.

* style(artwork): trim synthetic blurhash comments to the budget

* docs(jellyfin): fix stale blurhash README bullet + two review nits

The "Blurhashes are synthetic" bullet under Known limitations described
dto/blurhash.go, which was deleted when the real core/artwork-computed
blurhash + synthetic-fallback pipeline landed; every claim in it was
false. Replaced it with an accurate paragraph in the Images section,
since the described behaviour is now the finished design, not a gap.

Also: fix a doc/body comment mismatch in blurhash.go (component counts
are 2..9, not 1..9), and deduplicate the inline DC-extraction logic in
synthetic_test.go by reusing the existing dcOf helper.

* refactor(artwork): slice the synthetic cell jitter on byte boundaries

The three perturbations came off one hash with mismatched masks and shifts
(0xFF at 0, 0x3F at 8, 0x3F at 14), so a reader had to do the arithmetic to
confirm the fields did not overlap. Only 20 of the 64 bits were in use either
way, so the narrower fields bought nothing.

Uniform byte slices at 0/8/16 are non-overlapping by inspection and give each
field the full 8 bits. Both 1,000,000-seed collision specs still measure
1,000,000 distinct values. Also drops the local `n` alias, which was a second
name for synthComponents inside a 15-line function.

* docs(jellyfin): fix the blurhash paragraph's opening sentence

It opened with "follow the same principle", pointing back at the preceding
paragraph on admin-context artwork resolution — an unrelated subject, so the
reader looks for a connection that is not there.

* fix(artwork): render the synthetic grid larger than its component count

The 3x3 cell grid was handed straight to the encoder as a 3x3 image, so the
source had exactly as many samples as basis functions. Blurhash normalises its
coefficients by 1/(w*h) and 2/(w*h), which assumes many samples per component,
so the AC terms came out far too large. At the bottom-right corner the x and y
bases are both [1, -0.5, -0.5], everything lines up negative, and the result
clamped to black — a dark blob on every synthetic placeholder.

Rendering the same nine colours bilinearly at 8x8 first removes it: measured
over three seeds, the darkest corner goes from 13 to 74 and the darkest pixel
from 1 to 63. 8px is the smallest size that clears the artefact; 12 and 16 are
visually indistinguishable and cost 1.7x and 2.7x more.

The interpolation is hand-rolled rather than x/image's scaler, which allocated
528 times per call against 14 for this. Both 1,000,000-seed collision specs
still measure 1,000,000 distinct values.

* refactor(artwork): tidy the synthetic upscale helpers

cellWeight nudged its upper bound with a 1e-9 epsilon so int() could never
land on the last cell. Clamping the coordinate and then the index says the
same thing without a magic constant, and makes the clamp-don't-extrapolate
intent explicit — edge pixels map outside the cell centres, so the fraction
would otherwise run past 1.

The grid type is spelled once as colorGrid rather than repeated in the local
and the upscale signature, and encodeAt's doc now states the source-size
contract that Synthetic depends on, so the next caller sees it at the
function rather than only in synthetic.go.

Output is unchanged: all seven sample hashes match byte for byte.

* perf(artwork): make the synthetic upscale separable

Both axes are square and constant-sized, so the per-pixel cell index and
weight were the same 8 values recomputed 64 times per call. They are now
built once by sync.OnceValue, matching the srgbToLinearTable pattern.

The interpolation is also separable: stretching each of the 3 grid rows
horizontally once and then blending rows vertically does 264 lerps where
the per-pixel form did 576.

upscale drops from 347ns to 260ns, Synthetic from 1780ns to 1669ns. Output
is byte-identical across all seven sample hashes — same operations in the
same order, only hoisted.

* refactor(artwork): let a caller supply the cosine basis

encodeAt built its cosine tables inline, so Synthetic rebuilt bit-identical
ones on every call — its shape is always 3 components over 8 pixels. Splitting
the table construction into cosBasis and the encoder proper into encodePixels
lets Synthetic build the basis once via sync.OnceValue, and leaves encodeAt's
signature and behaviour untouched.

Synthetic drops from 14 allocations to 6 (1669ns to 1508ns). The time saving
is small and this path only runs while artwork is still unresolved; the
allocation cut is the point, alongside a shorter encodeAt.

Every hash is unchanged: nine real Encode outputs spanning square, 10x200,
200x10, 1x50 and a real JPEG, plus all seven synthetic samples, all byte for
byte identical before and after.
---
 core/artwork/blurhash/blurhash.go       |  41 +++---
 core/artwork/blurhash/synthetic.go      | 172 ++++++++++++++++++++++++
 core/artwork/blurhash/synthetic_test.go | 103 ++++++++++++++
 server/jellyfin/README.md               |  18 ++-
 server/jellyfin/dto/mappers.go          |  15 ++-
 server/jellyfin/dto/mappers_test.go     |  54 ++++++--
 6 files changed, 364 insertions(+), 39 deletions(-)
 create mode 100644 core/artwork/blurhash/synthetic.go
 create mode 100644 core/artwork/blurhash/synthetic_test.go

diff --git a/core/artwork/blurhash/blurhash.go b/core/artwork/blurhash/blurhash.go
index ca5bf7026..28d3409f3 100644
--- a/core/artwork/blurhash/blurhash.go
+++ b/core/artwork/blurhash/blurhash.go
@@ -32,23 +32,32 @@ func Encode(img image.Image) (string, error) {
 	}
 	// Pre-downscale: its rounding can flip a component count, and the hash is a client cache key.
 	xComp, yComp := components(img.Bounds().Dx(), img.Bounds().Dy())
-	src := pixelsOf(downscale(img))
-	w, h := src.w, src.h
+	return encodeAt(img, xComp, yComp), nil
+}
 
-	cosX := make([][]float64, xComp)
-	for i := range cosX {
-		cosX[i] = make([]float64, w)
-		for x := range cosX[i] {
-			cosX[i][x] = math.Cos(math.Pi * float64(i) * float64(x) / float64(w))
-		}
-	}
-	cosY := make([][]float64, yComp)
-	for j := range cosY {
-		cosY[j] = make([]float64, h)
-		for y := range cosY[j] {
-			cosY[j][y] = math.Cos(math.Pi * float64(j) * float64(y) / float64(h))
+// encodeAt encodes img at the given component counts (each 2..9). Callers guarantee non-empty
+// bounds, and a source far larger than the counts: too few samples overshoot the AC terms.
+func encodeAt(img image.Image, xComp, yComp int) string {
+	src := pixelsOf(downscale(img))
+	return encodePixels(src, xComp, yComp, cosBasis(xComp, src.w), cosBasis(yComp, src.h))
+}
+
+// cosBasis is the cosine basis for comp components sampled across n pixels. It depends only
+// on its arguments, so a caller with a fixed shape can build it once and reuse it.
+func cosBasis(comp, n int) [][]float64 {
+	basis := make([][]float64, comp)
+	for i := range basis {
+		basis[i] = make([]float64, n)
+		for x := range basis[i] {
+			basis[i][x] = math.Cos(math.Pi * float64(i) * float64(x) / float64(n))
 		}
 	}
+	return basis
+}
+
+// encodePixels is the encoder proper; cosX and cosY must match src's dimensions.
+func encodePixels(src pixels, xComp, yComp int, cosX, cosY [][]float64) string {
+	w, h := src.w, src.h
 
 	lin := srgbToLinearTable()
 	factors := make([][3]float64, xComp*yComp)
@@ -86,7 +95,7 @@ func Encode(img image.Image) (string, error) {
 	var sb strings.Builder
 	sb.WriteString(encode83((xComp-1)+(yComp-1)*9, 1))
 
-	// Derived counts are at least 1x9, so there is always at least one AC factor.
+	// Every caller passes at least 2 components, so there is always at least one AC factor.
 	ac := factors[1:]
 	actualMax := 0.0
 	for _, f := range ac {
@@ -101,7 +110,7 @@ func Encode(img image.Image) (string, error) {
 	for _, f := range ac {
 		sb.WriteString(encode83(quantAC(f[0], maxVal)*19*19+quantAC(f[1], maxVal)*19+quantAC(f[2], maxVal), 2))
 	}
-	return sb.String(), nil
+	return sb.String()
 }
 
 // pixels is direct Pix access for the pixel loop, avoiding a per-pixel allocation via image.At.
diff --git a/core/artwork/blurhash/synthetic.go b/core/artwork/blurhash/synthetic.go
new file mode 100644
index 000000000..1e15507d8
--- /dev/null
+++ b/core/artwork/blurhash/synthetic.go
@@ -0,0 +1,172 @@
+package blurhash
+
+import (
+	"image"
+	"math"
+	"strconv"
+	"sync"
+
+	"github.com/zeebo/xxh3"
+)
+
+// A real hash never has 3x3 components: components() always targets ~16 tiles.
+const synthComponents = 3
+
+// Encoding a source no bigger than the component grid overshoots the AC coefficients,
+// clamping the corners to black; the encoder assumes many samples per component.
+const synthSourceSize = 8
+
+type colorGrid = [synthComponents * synthComponents][3]float64
+
+// Synthetic returns a blurhash unique to seed, for artwork whose real hash does not exist
+// yet. baseColor ("#rrggbb") sets the hue family; "" derives it from the seed.
+func Synthetic(seed, baseColor string) string {
+	hue, sat, light := baseTone(baseColor, xxh3.HashStringSeed(seed, 0))
+
+	var grid colorGrid
+	for i := range grid {
+		// Each cell hashes the seed separately, so one tint shared by many items still
+		// yields one value per item.
+		bits := xxh3.HashStringSeed(seed, uint64(i)+1)
+		dh := (byteFrac(bits, 0) - 0.5) * 60
+		ds := (byteFrac(bits, 8) - 0.5) * 0.16
+		dl := (byteFrac(bits, 16) - 0.5) * 0.30
+		r, g, b := hslToRGB(hue+dh, clamp01(sat+ds), clamp01(light+dl))
+		grid[i] = [3]float64{float64(r), float64(g), float64(b)}
+	}
+	// The shape is fixed, so the cosine basis is reused instead of rebuilt per call.
+	basis := synthBasis()
+	return encodePixels(pixelsOf(upscale(&grid)), synthComponents, synthComponents, basis, basis)
+}
+
+// synthBasis is the cosine basis for the fixed synthetic shape. Square, so one serves both axes.
+var synthBasis = sync.OnceValue(func() [][]float64 {
+	return cosBasis(synthComponents, synthSourceSize)
+})
+
+// upscale renders the cell grid bilinearly at synthSourceSize. Hand-rolled because
+// x/image's scaler allocates per call, and this runs once per mapped item.
+func upscale(grid *colorGrid) *image.NRGBA {
+	const n, size = synthComponents, synthSourceSize
+	axis := axisWeights()
+
+	// Separable: each grid row is stretched horizontally once, then rows blend vertically.
+	// Doing it per pixel instead would repeat every horizontal lerp `size` times.
+	var rows [n][size][3]float64
+	for r := range n {
+		for x, a := range axis {
+			for c := range 3 {
+				rows[r][x][c] = grid[r*n+a.cell][c]*(1-a.frac) + grid[r*n+a.cell+1][c]*a.frac
+			}
+		}
+	}
+
+	img := image.NewNRGBA(image.Rect(0, 0, size, size))
+	for y, a := range axis {
+		top, bot := &rows[a.cell], &rows[a.cell+1]
+		for x := range size {
+			p := img.Pix[y*img.Stride+x*4:]
+			for c := range 3 {
+				p[c] = uint8(top[x][c]*(1-a.frac) + bot[x][c]*a.frac + 0.5)
+			}
+			p[3] = 255
+		}
+	}
+	return img
+}
+
+// axisWeights maps each source pixel to its lower cell and the fraction toward the next.
+// Both axes are square and constant-sized, so one table serves both and outlives the call.
+var axisWeights = sync.OnceValue(func() *[synthSourceSize]struct {
+	cell int
+	frac float64
+} {
+	var t [synthSourceSize]struct {
+		cell int
+		frac float64
+	}
+	for i := range t {
+		// Edge pixels fall outside the cell centres, so both ends clamp rather than extrapolate.
+		f := min(max((float64(i)+0.5)*synthComponents/synthSourceSize-0.5, 0), synthComponents-1)
+		t[i].cell = min(int(f), synthComponents-2)
+		t[i].frac = f - float64(t[i].cell)
+	}
+	return &t
+})
+
+func byteFrac(bits uint64, shift int) float64 {
+	return float64(bits>>shift&0xFF) / 255
+}
+
+// baseTone clamps saturation and lightness away from the extremes, so a placeholder
+// never reads as neon or as solid black.
+func baseTone(baseColor string, hueBits uint64) (hue, sat, light float64) {
+	if r, g, b, ok := parseHex(baseColor); ok {
+		h, s, l := rgbToHSL(r, g, b)
+		return h, min(max(s, 0.10), 0.35), min(max(l, 0.15), 0.75)
+	}
+	return float64(hueBits&0x1FF) / 512 * 360, 0.22, 0.40
+}
+
+func parseHex(s string) (r, g, b uint8, ok bool) {
+	if len(s) != 7 || s[0] != '#' {
+		return 0, 0, 0, false
+	}
+	v, err := strconv.ParseUint(s[1:], 16, 32)
+	if err != nil {
+		return 0, 0, 0, false
+	}
+	return uint8(v >> 16), uint8(v >> 8), uint8(v), true
+}
+
+func rgbToHSL(r, g, b uint8) (h, s, l float64) {
+	rf, gf, bf := float64(r)/255, float64(g)/255, float64(b)/255
+	mx, mn := max(rf, gf, bf), min(rf, gf, bf)
+	l = (mx + mn) / 2
+	if mx == mn {
+		return 0, 0, l
+	}
+	d := mx - mn
+	s = d / (1 - math.Abs(2*l-1))
+	switch mx {
+	case rf:
+		h = math.Mod((gf-bf)/d, 6)
+	case gf:
+		h = (bf-rf)/d + 2
+	default:
+		h = (rf-gf)/d + 4
+	}
+	h *= 60
+	if h < 0 {
+		h += 360
+	}
+	return h, s, l
+}
+
+func hslToRGB(h, s, l float64) (uint8, uint8, uint8) {
+	h = math.Mod(math.Mod(h, 360)+360, 360)
+	c := (1 - math.Abs(2*l-1)) * s
+	hp := h / 60
+	x := c * (1 - math.Abs(math.Mod(hp, 2)-1))
+	var r, g, b float64
+	switch int(hp) {
+	case 0:
+		r, g, b = c, x, 0
+	case 1:
+		r, g, b = x, c, 0
+	case 2:
+		r, g, b = 0, c, x
+	case 3:
+		r, g, b = 0, x, c
+	case 4:
+		r, g, b = x, 0, c
+	default:
+		r, g, b = c, 0, x
+	}
+	m := l - c/2
+	return to8(r + m), to8(g + m), to8(b + m)
+}
+
+func clamp01(v float64) float64 { return min(max(v, 0), 1) }
+
+func to8(v float64) uint8 { return uint8(math.Round(clamp01(v) * 255)) }
diff --git a/core/artwork/blurhash/synthetic_test.go b/core/artwork/blurhash/synthetic_test.go
new file mode 100644
index 000000000..671c1cd30
--- /dev/null
+++ b/core/artwork/blurhash/synthetic_test.go
@@ -0,0 +1,103 @@
+package blurhash_test
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/navidrome/navidrome/core/artwork/blurhash"
+	"github.com/zeebo/xxh3"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Synthetic", func() {
+	It("returns a well-formed 3x3 blurhash", func() {
+		h := blurhash.Synthetic("alb-1", "")
+		// 3x3 encodes as (3-1)+(3-1)*9 = 20, which is base83 'K'; length is 1+1+4+8*2.
+		Expect(h).To(HaveLen(22))
+		Expect(h).To(HavePrefix("K"))
+		for _, c := range h {
+			Expect(strings.ContainsRune(alphabet, c)).To(BeTrue(), "unexpected char %q", c)
+		}
+	})
+
+	It("keeps its prefix exclusive to real encodes, across aspect ratios", func() {
+		Expect(blurhash.Synthetic("alb-1", "")).To(HavePrefix("K"))
+
+		ratios := []struct{ w, h int }{
+			{10, 200}, {200, 10}, {1, 50}, {50, 1}, {64, 64}, {100, 300}, {300, 100},
+		}
+		for _, r := range ratios {
+			encoded, err := blurhash.Encode(gradientImage(r.w, r.h))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(encoded).ToNot(HavePrefix("K"), "real encode at %dx%d produced the synthetic prefix", r.w, r.h)
+		}
+	})
+
+	It("is deterministic for one seed", func() {
+		Expect(blurhash.Synthetic("alb-1", "")).To(Equal(blurhash.Synthetic("alb-1", "")))
+	})
+
+	It("differs across seeds", func() {
+		Expect(blurhash.Synthetic("alb-1", "")).ToNot(Equal(blurhash.Synthetic("alb-2", "")))
+	})
+
+	dcOf := func(hash string) (int, int, int) {
+		dc := decode83(hash[2:6])
+		return dc >> 16 & 0xFF, dc >> 8 & 0xFF, dc & 0xFF
+	}
+
+	It("decodes to a muted DC colour", func() {
+		r, g, b := dcOf(blurhash.Synthetic("alb-1", ""))
+		spread := max(r, g, b) - min(r, g, b)
+		Expect(spread).To(BeNumerically("<", 120), "saturation is capped, so no channel should run away")
+		Expect(max(r, g, b)).To(BeNumerically("<", 240), "lightness is capped below white")
+		Expect(min(r, g, b)).To(BeNumerically(">", 10), "lightness is capped above black")
+	})
+
+	It("keeps 1,000,000 seeds effectively distinct", func() {
+		const count = 1_000_000
+		seen := make(map[uint64]struct{}, count)
+		for i := range count {
+			seen[xxh3.HashString(blurhash.Synthetic(fmt.Sprintf("item-%d", i), ""))] = struct{}{}
+		}
+		Expect(len(seen)).To(BeNumerically(">=", 999_900))
+	})
+
+	It("leans the DC towards a red tint", func() {
+		r, g, b := dcOf(blurhash.Synthetic("alb-1", "#c04040"))
+		Expect(r).To(BeNumerically(">", g))
+		Expect(r).To(BeNumerically(">", b))
+	})
+
+	It("leans the DC towards a blue tint", func() {
+		r, g, b := dcOf(blurhash.Synthetic("alb-1", "#4040c0"))
+		Expect(b).To(BeNumerically(">", r))
+		Expect(b).To(BeNumerically(">", g))
+	})
+
+	It("changes the value when only the tint changes", func() {
+		Expect(blurhash.Synthetic("alb-1", "#c04040")).ToNot(Equal(blurhash.Synthetic("alb-1", "#4040c0")))
+	})
+
+	It("falls back to the seed hue for an unparseable tint", func() {
+		Expect(blurhash.Synthetic("alb-1", "not-a-colour")).To(Equal(blurhash.Synthetic("alb-1", "")))
+	})
+
+	It("tracks a dark tint's lightness", func() {
+		dark, _, _ := dcOf(blurhash.Synthetic("alb-1", "#101820"))
+		light, _, _ := dcOf(blurhash.Synthetic("alb-1", "#e8f0f8"))
+		Expect(dark).To(BeNumerically("<", light))
+	})
+
+	// A shared tint must not become a shared value: the seed alone carries uniqueness.
+	It("keeps 1,000,000 seeds distinct under a single fixed tint", func() {
+		const count = 1_000_000
+		seen := make(map[uint64]struct{}, count)
+		for i := range count {
+			seen[xxh3.HashString(blurhash.Synthetic(fmt.Sprintf("track-%d", i), "#3a5f7d"))] = struct{}{}
+		}
+		Expect(len(seen)).To(BeNumerically(">=", 999_900))
+	})
+})
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 13ec79aa8..b07aaee8d 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -180,6 +180,14 @@ warmer uses — so user-scoped items like private playlists still resolve their
 falling back to the placeholder. Album, artist, media-file and playlist ids are all resolved to
 their Navidrome `ArtworkID`.
 
+Blurhashes come in three tiers. A real blurhash is computed once in
+`core/artwork` from the decoded image and stored per artwork row; the mappers read it whenever it
+exists. While artwork is still unresolved, `dto/mappers.go` instead emits a synthetic 3x3 blurhash
+(`core/artwork/blurhash.Synthetic`), seeded on the image tag so it's effectively unique per image
+and can never collide with a real hash's leading byte, giving clients a valid cache key while art
+loads. A track awaiting embedded-art extraction has its synthetic hash tinted from the parent
+album's dominant colour. Known-absent artwork emits no tag and no blurhash at all.
+
 ## Finamp saved-queue id truncation
 
 Real Jellyfin item ids are GUIDs — 128-bit values, always 32 hex characters. Finamp relies on that
@@ -330,16 +338,6 @@ make test PKG=./server/jellyfin/...
   Access control for artists is enforced by scoping the `Artists`/`Items?IncludeItemTypes=MusicArtist`
   *list* to the user's libraries, plus the persistence layer's own defense-in-depth; a client
   that already has an artist id from elsewhere is not re-checked against library membership.
-- **Blurhashes are synthetic, not computed from the artwork (follow-up).** `ImageBlurHashes` is
-  populated by `dto/blurhash.go`, which derives a well-formed **1-component (solid color)**
-  blurhash by hashing the item id — it never looks at the actual image. Real Jellyfin computes a
-  multi-component blurhash from the cover's pixels (downscaled to 128×128) once at scan time and
-  stores it per image, so its placeholder approximates the art. Ours satisfies the protocol
-  (Finamp gets a valid value to use as a de-dup key and a placeholder, no missing-blurhash
-  warning) but renders as a flat color while art loads. A proper implementation would compute the
-  real blurhash in the `core/artwork` pipeline (where the image is already decoded), cache it
-  keyed like the artwork, and have the mappers read it — keeping the synthetic value as a fallback
-  for art that hasn't been rendered yet.
 - **The WebSocket only keep-alives; it pushes no events (follow-up).** `GET socket` sends a
   `ForceKeepAlive` and answers `KeepAlive` pings so real-time clients (Finamp) settle into a
   working session instead of 404-loop-reconnecting, but it never pushes anything. A follow-up
diff --git a/server/jellyfin/dto/mappers.go b/server/jellyfin/dto/mappers.go
index 31cdba1dd..d2bdb1b2e 100644
--- a/server/jellyfin/dto/mappers.go
+++ b/server/jellyfin/dto/mappers.go
@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/artwork/blurhash"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
 )
@@ -212,6 +213,8 @@ func SongToBaseItem(mf model.MediaFile, fields Fields) BaseItemDto {
 		// Nothing enqueues media files: advertising the id is what makes a client ask, and that
 		// request is what extracts the embedded art and queues the track.
 		item.ImageTags = map[string]string{"Primary": mf.ID}
+		hash := blurhash.Synthetic(mf.ID, mf.AlbumImage.DominantColor)
+		item.ImageBlurHashes = map[string]map[string]string{"Primary": {mf.ID: hash}}
 	} else if mf.AlbumID != "" {
 		if tag, blurs, ratio := primaryImage(mf.AlbumImage, mf.AlbumID, fields); tag != "" {
 			item.AlbumPrimaryImageTag = tag
@@ -227,15 +230,19 @@ func embeddedArtPending(mf model.MediaFile) bool {
 		mf.ImageHash == "" && !mf.ItemImage.ImageAbsent
 }
 
-// primaryImage never fakes a blurhash: clients key their cover cache on the value, which would
-// pin a stale cover forever.
+// primaryImage synthesizes a blurhash when none was computed yet: clients key their cover
+// cache on the value, so it must be unique per image, never shared or reused.
 func primaryImage(img model.ItemImage, fallback string, fields Fields) (tag string, blurs map[string]map[string]string, ratio *float64) {
 	if img.ImageAbsent {
 		return "", nil, nil
 	}
 	tag = cmp.Or(img.ImageHash, fallback)
-	if img.BlurHash != "" {
-		blurs = map[string]map[string]string{"Primary": {tag: img.BlurHash}}
+	if tag != "" {
+		hash := img.BlurHash
+		if hash == "" {
+			hash = blurhash.Synthetic(tag, "")
+		}
+		blurs = map[string]map[string]string{"Primary": {tag: hash}}
 	}
 	if fields.Has("PrimaryImageAspectRatio") {
 		ratio = img.AspectRatio()
diff --git a/server/jellyfin/dto/mappers_test.go b/server/jellyfin/dto/mappers_test.go
index 77b78e55f..451e1e08b 100644
--- a/server/jellyfin/dto/mappers_test.go
+++ b/server/jellyfin/dto/mappers_test.go
@@ -6,6 +6,7 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/artwork/blurhash"
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -37,7 +38,7 @@ var _ = Describe("mappers", func() {
 		Expect(item.UserData.Key).To(Equal(EncodeID("song-1")))
 		Expect(item.UserData.ItemId).To(Equal(EncodeID("song-1")))
 		Expect(item.AlbumPrimaryImageTag).To(Equal("alb-1"))
-		Expect(item.ImageBlurHashes).To(BeNil())
+		Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("alb-1", blurhash.Synthetic("alb-1", "")))
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
 		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID("1"), Name: "genre 1"}, {Id: EncodeID("2"), Name: "genre 2"}}))
 	})
@@ -298,7 +299,7 @@ var _ = Describe("mappers", func() {
 		Expect(*item.ProductionYear).To(Equal(1999))
 		Expect(*item.ChildCount).To(Equal(10))
 		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "alb-1"))
-		Expect(item.ImageBlurHashes).To(BeNil())
+		Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("alb-1", blurhash.Synthetic("alb-1", "")))
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
 		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID("1"), Name: "genre 1"}, {Id: EncodeID("2"), Name: "genre 2"}}))
 	})
@@ -472,7 +473,7 @@ var _ = Describe("mappers", func() {
 		Expect(item.UserData.PlayCount).To(Equal(2))
 		Expect(*item.UserData.Rating).To(Equal(8.0))
 		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "pl-1"))
-		Expect(item.ImageBlurHashes).To(BeNil())
+		Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("pl-1", blurhash.Synthetic("pl-1", "")))
 	})
 
 	It("changes the playlist image tag when the cover content changes", func() {
@@ -507,13 +508,37 @@ var _ = Describe("mappers", func() {
 		It("advertises the track id so the client triggers the read-through", func() {
 			mf := model.MediaFile{ID: "mf-1", AlbumID: "alb-1", HasCoverArt: true}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
+			mf.AlbumImage.DominantColor = "#3a5f7d"
 
 			item := SongToBaseItem(mf, nil)
 			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "mf-1"))
-			Expect(item.ImageBlurHashes).To(BeNil(), "no resolved image means no blurhash to send")
+			Expect(item.ImageBlurHashes["Primary"]).To(
+				HaveKeyWithValue("mf-1", blurhash.Synthetic("mf-1", "#3a5f7d")))
 			Expect(item.AlbumPrimaryImageTag).To(BeEmpty())
 		})
 
+		// The client's image request is what extracts the embedded art. Reusing the album's
+		// value would let it answer from cache and never send it.
+		It("gives the track a value distinct from its album's", func() {
+			mf := model.MediaFile{ID: "mf-3", AlbumID: "alb-1", HasCoverArt: true}
+			mf.AlbumImage.ImageHash = "0123456789abcdef"
+			mf.AlbumImage.BlurHash = "LEHV6nWB2yk8"
+			mf.AlbumImage.DominantColor = "#3a5f7d"
+
+			track := SongToBaseItem(mf, nil).ImageBlurHashes["Primary"]["mf-3"]
+			album := AlbumToBaseItem(model.Album{ID: "alb-1", ItemImage: mf.AlbumImage}, nil).
+				ImageBlurHashes["Primary"]["0123456789abcdef"]
+			Expect(track).ToNot(BeEmpty())
+			Expect(track).ToNot(Equal(album))
+		})
+
+		It("still emits a value when the album has no dominant colour", func() {
+			mf := model.MediaFile{ID: "mf-4", AlbumID: "alb-1", HasCoverArt: true}
+
+			item := SongToBaseItem(mf, nil)
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("mf-4", blurhash.Synthetic("mf-4", "")))
+		})
+
 		It("falls back to the album when the track has no art of its own", func() {
 			mf := model.MediaFile{ID: "mf-2", AlbumID: "alb-1", HasCoverArt: false}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
@@ -555,13 +580,14 @@ var _ = Describe("mappers", func() {
 			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("0123456789abcdef", "LEHV6nWB2yk8"))
 		})
 
-		It("omits the blurhash entirely when none was computed", func() {
+		It("synthesizes a blurhash when none was computed", func() {
 			al := model.Album{ID: "alb-2", Name: "Album"}
 			al.ImageHash = "0123456789abcdef"
 
 			item := AlbumToBaseItem(al, nil)
 			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "0123456789abcdef"))
-			Expect(item.ImageBlurHashes).To(BeNil(), "a synthesized blurhash pins stale covers in Finamp")
+			Expect(item.ImageBlurHashes["Primary"]).To(
+				HaveKeyWithValue("0123456789abcdef", blurhash.Synthetic("0123456789abcdef", "")))
 		})
 
 		It("omits tags for known-absent artwork", func() {
@@ -573,10 +599,19 @@ var _ = Describe("mappers", func() {
 			Expect(item.ImageBlurHashes).To(BeNil())
 		})
 
+		It("keeps known-absent artwork free of any synthesized value", func() {
+			al := model.Album{ID: "alb-5", Name: "Album"}
+			al.ImageAbsent = true
+
+			item := AlbumToBaseItem(al, nil)
+			Expect(item.ImageBlurHashes).To(BeNil(),
+				"there is no image to key a cache on, and nothing will ever re-key it")
+		})
+
 		It("falls back to the entity id while artwork is still unresolved", func() {
 			item := AlbumToBaseItem(model.Album{ID: "alb-4", Name: "Album"}, nil)
 			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "alb-4"))
-			Expect(item.ImageBlurHashes).To(BeNil())
+			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("alb-4", blurhash.Synthetic("alb-4", "")))
 		})
 
 		It("versions an artist's tag by content hash", func() {
@@ -601,13 +636,14 @@ var _ = Describe("mappers", func() {
 			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("0123456789abcdef", "LEHV6nWB2yk8"))
 		})
 
-		It("never synthesizes a song blurhash when the album has none", func() {
+		It("synthesizes a song's album blurhash when the album has none", func() {
 			mf := model.MediaFile{ID: "song-2", Title: "Song", AlbumID: "alb-2"}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
 
 			item := SongToBaseItem(mf, nil)
 			Expect(item.AlbumPrimaryImageTag).To(Equal("0123456789abcdef"))
-			Expect(item.ImageBlurHashes).To(BeNil())
+			Expect(item.ImageBlurHashes["Primary"]).To(
+				HaveKeyWithValue("0123456789abcdef", blurhash.Synthetic("0123456789abcdef", "")))
 		})
 
 		It("omits a song's album tag when the album art is known absent", func() {

From 8978c7b9facee94d52e371d367a1f74394439dd9 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 12 Aug 2026 11:46:23 -0400
Subject: [PATCH 030/200] Revert "feat(jellyfin): send a synthetic placeholder
 blurhash for unresolved artwork (#5941)"

This reverts commit 036c9cab9671505c83fce6523f55d97b152b3b32.
---
 core/artwork/blurhash/blurhash.go       |  39 +++---
 core/artwork/blurhash/synthetic.go      | 172 ------------------------
 core/artwork/blurhash/synthetic_test.go | 103 --------------
 server/jellyfin/README.md               |  18 +--
 server/jellyfin/dto/mappers.go          |  15 +--
 server/jellyfin/dto/mappers_test.go     |  54 ++------
 6 files changed, 38 insertions(+), 363 deletions(-)
 delete mode 100644 core/artwork/blurhash/synthetic.go
 delete mode 100644 core/artwork/blurhash/synthetic_test.go

diff --git a/core/artwork/blurhash/blurhash.go b/core/artwork/blurhash/blurhash.go
index 28d3409f3..ca5bf7026 100644
--- a/core/artwork/blurhash/blurhash.go
+++ b/core/artwork/blurhash/blurhash.go
@@ -32,32 +32,23 @@ func Encode(img image.Image) (string, error) {
 	}
 	// Pre-downscale: its rounding can flip a component count, and the hash is a client cache key.
 	xComp, yComp := components(img.Bounds().Dx(), img.Bounds().Dy())
-	return encodeAt(img, xComp, yComp), nil
-}
-
-// encodeAt encodes img at the given component counts (each 2..9). Callers guarantee non-empty
-// bounds, and a source far larger than the counts: too few samples overshoot the AC terms.
-func encodeAt(img image.Image, xComp, yComp int) string {
 	src := pixelsOf(downscale(img))
-	return encodePixels(src, xComp, yComp, cosBasis(xComp, src.w), cosBasis(yComp, src.h))
-}
+	w, h := src.w, src.h
 
-// cosBasis is the cosine basis for comp components sampled across n pixels. It depends only
-// on its arguments, so a caller with a fixed shape can build it once and reuse it.
-func cosBasis(comp, n int) [][]float64 {
-	basis := make([][]float64, comp)
-	for i := range basis {
-		basis[i] = make([]float64, n)
-		for x := range basis[i] {
-			basis[i][x] = math.Cos(math.Pi * float64(i) * float64(x) / float64(n))
+	cosX := make([][]float64, xComp)
+	for i := range cosX {
+		cosX[i] = make([]float64, w)
+		for x := range cosX[i] {
+			cosX[i][x] = math.Cos(math.Pi * float64(i) * float64(x) / float64(w))
+		}
+	}
+	cosY := make([][]float64, yComp)
+	for j := range cosY {
+		cosY[j] = make([]float64, h)
+		for y := range cosY[j] {
+			cosY[j][y] = math.Cos(math.Pi * float64(j) * float64(y) / float64(h))
 		}
 	}
-	return basis
-}
-
-// encodePixels is the encoder proper; cosX and cosY must match src's dimensions.
-func encodePixels(src pixels, xComp, yComp int, cosX, cosY [][]float64) string {
-	w, h := src.w, src.h
 
 	lin := srgbToLinearTable()
 	factors := make([][3]float64, xComp*yComp)
@@ -95,7 +86,7 @@ func encodePixels(src pixels, xComp, yComp int, cosX, cosY [][]float64) string {
 	var sb strings.Builder
 	sb.WriteString(encode83((xComp-1)+(yComp-1)*9, 1))
 
-	// Every caller passes at least 2 components, so there is always at least one AC factor.
+	// Derived counts are at least 1x9, so there is always at least one AC factor.
 	ac := factors[1:]
 	actualMax := 0.0
 	for _, f := range ac {
@@ -110,7 +101,7 @@ func encodePixels(src pixels, xComp, yComp int, cosX, cosY [][]float64) string {
 	for _, f := range ac {
 		sb.WriteString(encode83(quantAC(f[0], maxVal)*19*19+quantAC(f[1], maxVal)*19+quantAC(f[2], maxVal), 2))
 	}
-	return sb.String()
+	return sb.String(), nil
 }
 
 // pixels is direct Pix access for the pixel loop, avoiding a per-pixel allocation via image.At.
diff --git a/core/artwork/blurhash/synthetic.go b/core/artwork/blurhash/synthetic.go
deleted file mode 100644
index 1e15507d8..000000000
--- a/core/artwork/blurhash/synthetic.go
+++ /dev/null
@@ -1,172 +0,0 @@
-package blurhash
-
-import (
-	"image"
-	"math"
-	"strconv"
-	"sync"
-
-	"github.com/zeebo/xxh3"
-)
-
-// A real hash never has 3x3 components: components() always targets ~16 tiles.
-const synthComponents = 3
-
-// Encoding a source no bigger than the component grid overshoots the AC coefficients,
-// clamping the corners to black; the encoder assumes many samples per component.
-const synthSourceSize = 8
-
-type colorGrid = [synthComponents * synthComponents][3]float64
-
-// Synthetic returns a blurhash unique to seed, for artwork whose real hash does not exist
-// yet. baseColor ("#rrggbb") sets the hue family; "" derives it from the seed.
-func Synthetic(seed, baseColor string) string {
-	hue, sat, light := baseTone(baseColor, xxh3.HashStringSeed(seed, 0))
-
-	var grid colorGrid
-	for i := range grid {
-		// Each cell hashes the seed separately, so one tint shared by many items still
-		// yields one value per item.
-		bits := xxh3.HashStringSeed(seed, uint64(i)+1)
-		dh := (byteFrac(bits, 0) - 0.5) * 60
-		ds := (byteFrac(bits, 8) - 0.5) * 0.16
-		dl := (byteFrac(bits, 16) - 0.5) * 0.30
-		r, g, b := hslToRGB(hue+dh, clamp01(sat+ds), clamp01(light+dl))
-		grid[i] = [3]float64{float64(r), float64(g), float64(b)}
-	}
-	// The shape is fixed, so the cosine basis is reused instead of rebuilt per call.
-	basis := synthBasis()
-	return encodePixels(pixelsOf(upscale(&grid)), synthComponents, synthComponents, basis, basis)
-}
-
-// synthBasis is the cosine basis for the fixed synthetic shape. Square, so one serves both axes.
-var synthBasis = sync.OnceValue(func() [][]float64 {
-	return cosBasis(synthComponents, synthSourceSize)
-})
-
-// upscale renders the cell grid bilinearly at synthSourceSize. Hand-rolled because
-// x/image's scaler allocates per call, and this runs once per mapped item.
-func upscale(grid *colorGrid) *image.NRGBA {
-	const n, size = synthComponents, synthSourceSize
-	axis := axisWeights()
-
-	// Separable: each grid row is stretched horizontally once, then rows blend vertically.
-	// Doing it per pixel instead would repeat every horizontal lerp `size` times.
-	var rows [n][size][3]float64
-	for r := range n {
-		for x, a := range axis {
-			for c := range 3 {
-				rows[r][x][c] = grid[r*n+a.cell][c]*(1-a.frac) + grid[r*n+a.cell+1][c]*a.frac
-			}
-		}
-	}
-
-	img := image.NewNRGBA(image.Rect(0, 0, size, size))
-	for y, a := range axis {
-		top, bot := &rows[a.cell], &rows[a.cell+1]
-		for x := range size {
-			p := img.Pix[y*img.Stride+x*4:]
-			for c := range 3 {
-				p[c] = uint8(top[x][c]*(1-a.frac) + bot[x][c]*a.frac + 0.5)
-			}
-			p[3] = 255
-		}
-	}
-	return img
-}
-
-// axisWeights maps each source pixel to its lower cell and the fraction toward the next.
-// Both axes are square and constant-sized, so one table serves both and outlives the call.
-var axisWeights = sync.OnceValue(func() *[synthSourceSize]struct {
-	cell int
-	frac float64
-} {
-	var t [synthSourceSize]struct {
-		cell int
-		frac float64
-	}
-	for i := range t {
-		// Edge pixels fall outside the cell centres, so both ends clamp rather than extrapolate.
-		f := min(max((float64(i)+0.5)*synthComponents/synthSourceSize-0.5, 0), synthComponents-1)
-		t[i].cell = min(int(f), synthComponents-2)
-		t[i].frac = f - float64(t[i].cell)
-	}
-	return &t
-})
-
-func byteFrac(bits uint64, shift int) float64 {
-	return float64(bits>>shift&0xFF) / 255
-}
-
-// baseTone clamps saturation and lightness away from the extremes, so a placeholder
-// never reads as neon or as solid black.
-func baseTone(baseColor string, hueBits uint64) (hue, sat, light float64) {
-	if r, g, b, ok := parseHex(baseColor); ok {
-		h, s, l := rgbToHSL(r, g, b)
-		return h, min(max(s, 0.10), 0.35), min(max(l, 0.15), 0.75)
-	}
-	return float64(hueBits&0x1FF) / 512 * 360, 0.22, 0.40
-}
-
-func parseHex(s string) (r, g, b uint8, ok bool) {
-	if len(s) != 7 || s[0] != '#' {
-		return 0, 0, 0, false
-	}
-	v, err := strconv.ParseUint(s[1:], 16, 32)
-	if err != nil {
-		return 0, 0, 0, false
-	}
-	return uint8(v >> 16), uint8(v >> 8), uint8(v), true
-}
-
-func rgbToHSL(r, g, b uint8) (h, s, l float64) {
-	rf, gf, bf := float64(r)/255, float64(g)/255, float64(b)/255
-	mx, mn := max(rf, gf, bf), min(rf, gf, bf)
-	l = (mx + mn) / 2
-	if mx == mn {
-		return 0, 0, l
-	}
-	d := mx - mn
-	s = d / (1 - math.Abs(2*l-1))
-	switch mx {
-	case rf:
-		h = math.Mod((gf-bf)/d, 6)
-	case gf:
-		h = (bf-rf)/d + 2
-	default:
-		h = (rf-gf)/d + 4
-	}
-	h *= 60
-	if h < 0 {
-		h += 360
-	}
-	return h, s, l
-}
-
-func hslToRGB(h, s, l float64) (uint8, uint8, uint8) {
-	h = math.Mod(math.Mod(h, 360)+360, 360)
-	c := (1 - math.Abs(2*l-1)) * s
-	hp := h / 60
-	x := c * (1 - math.Abs(math.Mod(hp, 2)-1))
-	var r, g, b float64
-	switch int(hp) {
-	case 0:
-		r, g, b = c, x, 0
-	case 1:
-		r, g, b = x, c, 0
-	case 2:
-		r, g, b = 0, c, x
-	case 3:
-		r, g, b = 0, x, c
-	case 4:
-		r, g, b = x, 0, c
-	default:
-		r, g, b = c, 0, x
-	}
-	m := l - c/2
-	return to8(r + m), to8(g + m), to8(b + m)
-}
-
-func clamp01(v float64) float64 { return min(max(v, 0), 1) }
-
-func to8(v float64) uint8 { return uint8(math.Round(clamp01(v) * 255)) }
diff --git a/core/artwork/blurhash/synthetic_test.go b/core/artwork/blurhash/synthetic_test.go
deleted file mode 100644
index 671c1cd30..000000000
--- a/core/artwork/blurhash/synthetic_test.go
+++ /dev/null
@@ -1,103 +0,0 @@
-package blurhash_test
-
-import (
-	"fmt"
-	"strings"
-
-	"github.com/navidrome/navidrome/core/artwork/blurhash"
-	"github.com/zeebo/xxh3"
-
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Synthetic", func() {
-	It("returns a well-formed 3x3 blurhash", func() {
-		h := blurhash.Synthetic("alb-1", "")
-		// 3x3 encodes as (3-1)+(3-1)*9 = 20, which is base83 'K'; length is 1+1+4+8*2.
-		Expect(h).To(HaveLen(22))
-		Expect(h).To(HavePrefix("K"))
-		for _, c := range h {
-			Expect(strings.ContainsRune(alphabet, c)).To(BeTrue(), "unexpected char %q", c)
-		}
-	})
-
-	It("keeps its prefix exclusive to real encodes, across aspect ratios", func() {
-		Expect(blurhash.Synthetic("alb-1", "")).To(HavePrefix("K"))
-
-		ratios := []struct{ w, h int }{
-			{10, 200}, {200, 10}, {1, 50}, {50, 1}, {64, 64}, {100, 300}, {300, 100},
-		}
-		for _, r := range ratios {
-			encoded, err := blurhash.Encode(gradientImage(r.w, r.h))
-			Expect(err).ToNot(HaveOccurred())
-			Expect(encoded).ToNot(HavePrefix("K"), "real encode at %dx%d produced the synthetic prefix", r.w, r.h)
-		}
-	})
-
-	It("is deterministic for one seed", func() {
-		Expect(blurhash.Synthetic("alb-1", "")).To(Equal(blurhash.Synthetic("alb-1", "")))
-	})
-
-	It("differs across seeds", func() {
-		Expect(blurhash.Synthetic("alb-1", "")).ToNot(Equal(blurhash.Synthetic("alb-2", "")))
-	})
-
-	dcOf := func(hash string) (int, int, int) {
-		dc := decode83(hash[2:6])
-		return dc >> 16 & 0xFF, dc >> 8 & 0xFF, dc & 0xFF
-	}
-
-	It("decodes to a muted DC colour", func() {
-		r, g, b := dcOf(blurhash.Synthetic("alb-1", ""))
-		spread := max(r, g, b) - min(r, g, b)
-		Expect(spread).To(BeNumerically("<", 120), "saturation is capped, so no channel should run away")
-		Expect(max(r, g, b)).To(BeNumerically("<", 240), "lightness is capped below white")
-		Expect(min(r, g, b)).To(BeNumerically(">", 10), "lightness is capped above black")
-	})
-
-	It("keeps 1,000,000 seeds effectively distinct", func() {
-		const count = 1_000_000
-		seen := make(map[uint64]struct{}, count)
-		for i := range count {
-			seen[xxh3.HashString(blurhash.Synthetic(fmt.Sprintf("item-%d", i), ""))] = struct{}{}
-		}
-		Expect(len(seen)).To(BeNumerically(">=", 999_900))
-	})
-
-	It("leans the DC towards a red tint", func() {
-		r, g, b := dcOf(blurhash.Synthetic("alb-1", "#c04040"))
-		Expect(r).To(BeNumerically(">", g))
-		Expect(r).To(BeNumerically(">", b))
-	})
-
-	It("leans the DC towards a blue tint", func() {
-		r, g, b := dcOf(blurhash.Synthetic("alb-1", "#4040c0"))
-		Expect(b).To(BeNumerically(">", r))
-		Expect(b).To(BeNumerically(">", g))
-	})
-
-	It("changes the value when only the tint changes", func() {
-		Expect(blurhash.Synthetic("alb-1", "#c04040")).ToNot(Equal(blurhash.Synthetic("alb-1", "#4040c0")))
-	})
-
-	It("falls back to the seed hue for an unparseable tint", func() {
-		Expect(blurhash.Synthetic("alb-1", "not-a-colour")).To(Equal(blurhash.Synthetic("alb-1", "")))
-	})
-
-	It("tracks a dark tint's lightness", func() {
-		dark, _, _ := dcOf(blurhash.Synthetic("alb-1", "#101820"))
-		light, _, _ := dcOf(blurhash.Synthetic("alb-1", "#e8f0f8"))
-		Expect(dark).To(BeNumerically("<", light))
-	})
-
-	// A shared tint must not become a shared value: the seed alone carries uniqueness.
-	It("keeps 1,000,000 seeds distinct under a single fixed tint", func() {
-		const count = 1_000_000
-		seen := make(map[uint64]struct{}, count)
-		for i := range count {
-			seen[xxh3.HashString(blurhash.Synthetic(fmt.Sprintf("track-%d", i), "#3a5f7d"))] = struct{}{}
-		}
-		Expect(len(seen)).To(BeNumerically(">=", 999_900))
-	})
-})
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index b07aaee8d..13ec79aa8 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -180,14 +180,6 @@ warmer uses — so user-scoped items like private playlists still resolve their
 falling back to the placeholder. Album, artist, media-file and playlist ids are all resolved to
 their Navidrome `ArtworkID`.
 
-Blurhashes come in three tiers. A real blurhash is computed once in
-`core/artwork` from the decoded image and stored per artwork row; the mappers read it whenever it
-exists. While artwork is still unresolved, `dto/mappers.go` instead emits a synthetic 3x3 blurhash
-(`core/artwork/blurhash.Synthetic`), seeded on the image tag so it's effectively unique per image
-and can never collide with a real hash's leading byte, giving clients a valid cache key while art
-loads. A track awaiting embedded-art extraction has its synthetic hash tinted from the parent
-album's dominant colour. Known-absent artwork emits no tag and no blurhash at all.
-
 ## Finamp saved-queue id truncation
 
 Real Jellyfin item ids are GUIDs — 128-bit values, always 32 hex characters. Finamp relies on that
@@ -338,6 +330,16 @@ make test PKG=./server/jellyfin/...
   Access control for artists is enforced by scoping the `Artists`/`Items?IncludeItemTypes=MusicArtist`
   *list* to the user's libraries, plus the persistence layer's own defense-in-depth; a client
   that already has an artist id from elsewhere is not re-checked against library membership.
+- **Blurhashes are synthetic, not computed from the artwork (follow-up).** `ImageBlurHashes` is
+  populated by `dto/blurhash.go`, which derives a well-formed **1-component (solid color)**
+  blurhash by hashing the item id — it never looks at the actual image. Real Jellyfin computes a
+  multi-component blurhash from the cover's pixels (downscaled to 128×128) once at scan time and
+  stores it per image, so its placeholder approximates the art. Ours satisfies the protocol
+  (Finamp gets a valid value to use as a de-dup key and a placeholder, no missing-blurhash
+  warning) but renders as a flat color while art loads. A proper implementation would compute the
+  real blurhash in the `core/artwork` pipeline (where the image is already decoded), cache it
+  keyed like the artwork, and have the mappers read it — keeping the synthetic value as a fallback
+  for art that hasn't been rendered yet.
 - **The WebSocket only keep-alives; it pushes no events (follow-up).** `GET socket` sends a
   `ForceKeepAlive` and answers `KeepAlive` pings so real-time clients (Finamp) settle into a
   working session instead of 404-loop-reconnecting, but it never pushes anything. A follow-up
diff --git a/server/jellyfin/dto/mappers.go b/server/jellyfin/dto/mappers.go
index d2bdb1b2e..31cdba1dd 100644
--- a/server/jellyfin/dto/mappers.go
+++ b/server/jellyfin/dto/mappers.go
@@ -6,7 +6,6 @@ import (
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core/artwork/blurhash"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
 )
@@ -213,8 +212,6 @@ func SongToBaseItem(mf model.MediaFile, fields Fields) BaseItemDto {
 		// Nothing enqueues media files: advertising the id is what makes a client ask, and that
 		// request is what extracts the embedded art and queues the track.
 		item.ImageTags = map[string]string{"Primary": mf.ID}
-		hash := blurhash.Synthetic(mf.ID, mf.AlbumImage.DominantColor)
-		item.ImageBlurHashes = map[string]map[string]string{"Primary": {mf.ID: hash}}
 	} else if mf.AlbumID != "" {
 		if tag, blurs, ratio := primaryImage(mf.AlbumImage, mf.AlbumID, fields); tag != "" {
 			item.AlbumPrimaryImageTag = tag
@@ -230,19 +227,15 @@ func embeddedArtPending(mf model.MediaFile) bool {
 		mf.ImageHash == "" && !mf.ItemImage.ImageAbsent
 }
 
-// primaryImage synthesizes a blurhash when none was computed yet: clients key their cover
-// cache on the value, so it must be unique per image, never shared or reused.
+// primaryImage never fakes a blurhash: clients key their cover cache on the value, which would
+// pin a stale cover forever.
 func primaryImage(img model.ItemImage, fallback string, fields Fields) (tag string, blurs map[string]map[string]string, ratio *float64) {
 	if img.ImageAbsent {
 		return "", nil, nil
 	}
 	tag = cmp.Or(img.ImageHash, fallback)
-	if tag != "" {
-		hash := img.BlurHash
-		if hash == "" {
-			hash = blurhash.Synthetic(tag, "")
-		}
-		blurs = map[string]map[string]string{"Primary": {tag: hash}}
+	if img.BlurHash != "" {
+		blurs = map[string]map[string]string{"Primary": {tag: img.BlurHash}}
 	}
 	if fields.Has("PrimaryImageAspectRatio") {
 		ratio = img.AspectRatio()
diff --git a/server/jellyfin/dto/mappers_test.go b/server/jellyfin/dto/mappers_test.go
index 451e1e08b..77b78e55f 100644
--- a/server/jellyfin/dto/mappers_test.go
+++ b/server/jellyfin/dto/mappers_test.go
@@ -6,7 +6,6 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
-	"github.com/navidrome/navidrome/core/artwork/blurhash"
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -38,7 +37,7 @@ var _ = Describe("mappers", func() {
 		Expect(item.UserData.Key).To(Equal(EncodeID("song-1")))
 		Expect(item.UserData.ItemId).To(Equal(EncodeID("song-1")))
 		Expect(item.AlbumPrimaryImageTag).To(Equal("alb-1"))
-		Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("alb-1", blurhash.Synthetic("alb-1", "")))
+		Expect(item.ImageBlurHashes).To(BeNil())
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
 		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID("1"), Name: "genre 1"}, {Id: EncodeID("2"), Name: "genre 2"}}))
 	})
@@ -299,7 +298,7 @@ var _ = Describe("mappers", func() {
 		Expect(*item.ProductionYear).To(Equal(1999))
 		Expect(*item.ChildCount).To(Equal(10))
 		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "alb-1"))
-		Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("alb-1", blurhash.Synthetic("alb-1", "")))
+		Expect(item.ImageBlurHashes).To(BeNil())
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
 		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID("1"), Name: "genre 1"}, {Id: EncodeID("2"), Name: "genre 2"}}))
 	})
@@ -473,7 +472,7 @@ var _ = Describe("mappers", func() {
 		Expect(item.UserData.PlayCount).To(Equal(2))
 		Expect(*item.UserData.Rating).To(Equal(8.0))
 		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "pl-1"))
-		Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("pl-1", blurhash.Synthetic("pl-1", "")))
+		Expect(item.ImageBlurHashes).To(BeNil())
 	})
 
 	It("changes the playlist image tag when the cover content changes", func() {
@@ -508,37 +507,13 @@ var _ = Describe("mappers", func() {
 		It("advertises the track id so the client triggers the read-through", func() {
 			mf := model.MediaFile{ID: "mf-1", AlbumID: "alb-1", HasCoverArt: true}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
-			mf.AlbumImage.DominantColor = "#3a5f7d"
 
 			item := SongToBaseItem(mf, nil)
 			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "mf-1"))
-			Expect(item.ImageBlurHashes["Primary"]).To(
-				HaveKeyWithValue("mf-1", blurhash.Synthetic("mf-1", "#3a5f7d")))
+			Expect(item.ImageBlurHashes).To(BeNil(), "no resolved image means no blurhash to send")
 			Expect(item.AlbumPrimaryImageTag).To(BeEmpty())
 		})
 
-		// The client's image request is what extracts the embedded art. Reusing the album's
-		// value would let it answer from cache and never send it.
-		It("gives the track a value distinct from its album's", func() {
-			mf := model.MediaFile{ID: "mf-3", AlbumID: "alb-1", HasCoverArt: true}
-			mf.AlbumImage.ImageHash = "0123456789abcdef"
-			mf.AlbumImage.BlurHash = "LEHV6nWB2yk8"
-			mf.AlbumImage.DominantColor = "#3a5f7d"
-
-			track := SongToBaseItem(mf, nil).ImageBlurHashes["Primary"]["mf-3"]
-			album := AlbumToBaseItem(model.Album{ID: "alb-1", ItemImage: mf.AlbumImage}, nil).
-				ImageBlurHashes["Primary"]["0123456789abcdef"]
-			Expect(track).ToNot(BeEmpty())
-			Expect(track).ToNot(Equal(album))
-		})
-
-		It("still emits a value when the album has no dominant colour", func() {
-			mf := model.MediaFile{ID: "mf-4", AlbumID: "alb-1", HasCoverArt: true}
-
-			item := SongToBaseItem(mf, nil)
-			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("mf-4", blurhash.Synthetic("mf-4", "")))
-		})
-
 		It("falls back to the album when the track has no art of its own", func() {
 			mf := model.MediaFile{ID: "mf-2", AlbumID: "alb-1", HasCoverArt: false}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
@@ -580,14 +555,13 @@ var _ = Describe("mappers", func() {
 			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("0123456789abcdef", "LEHV6nWB2yk8"))
 		})
 
-		It("synthesizes a blurhash when none was computed", func() {
+		It("omits the blurhash entirely when none was computed", func() {
 			al := model.Album{ID: "alb-2", Name: "Album"}
 			al.ImageHash = "0123456789abcdef"
 
 			item := AlbumToBaseItem(al, nil)
 			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "0123456789abcdef"))
-			Expect(item.ImageBlurHashes["Primary"]).To(
-				HaveKeyWithValue("0123456789abcdef", blurhash.Synthetic("0123456789abcdef", "")))
+			Expect(item.ImageBlurHashes).To(BeNil(), "a synthesized blurhash pins stale covers in Finamp")
 		})
 
 		It("omits tags for known-absent artwork", func() {
@@ -599,19 +573,10 @@ var _ = Describe("mappers", func() {
 			Expect(item.ImageBlurHashes).To(BeNil())
 		})
 
-		It("keeps known-absent artwork free of any synthesized value", func() {
-			al := model.Album{ID: "alb-5", Name: "Album"}
-			al.ImageAbsent = true
-
-			item := AlbumToBaseItem(al, nil)
-			Expect(item.ImageBlurHashes).To(BeNil(),
-				"there is no image to key a cache on, and nothing will ever re-key it")
-		})
-
 		It("falls back to the entity id while artwork is still unresolved", func() {
 			item := AlbumToBaseItem(model.Album{ID: "alb-4", Name: "Album"}, nil)
 			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "alb-4"))
-			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("alb-4", blurhash.Synthetic("alb-4", "")))
+			Expect(item.ImageBlurHashes).To(BeNil())
 		})
 
 		It("versions an artist's tag by content hash", func() {
@@ -636,14 +601,13 @@ var _ = Describe("mappers", func() {
 			Expect(item.ImageBlurHashes["Primary"]).To(HaveKeyWithValue("0123456789abcdef", "LEHV6nWB2yk8"))
 		})
 
-		It("synthesizes a song's album blurhash when the album has none", func() {
+		It("never synthesizes a song blurhash when the album has none", func() {
 			mf := model.MediaFile{ID: "song-2", Title: "Song", AlbumID: "alb-2"}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
 
 			item := SongToBaseItem(mf, nil)
 			Expect(item.AlbumPrimaryImageTag).To(Equal("0123456789abcdef"))
-			Expect(item.ImageBlurHashes["Primary"]).To(
-				HaveKeyWithValue("0123456789abcdef", blurhash.Synthetic("0123456789abcdef", "")))
+			Expect(item.ImageBlurHashes).To(BeNil())
 		})
 
 		It("omits a song's album tag when the album art is known absent", func() {

From 752b38609c1599e15dc4fb3eef55fbb6f340f516 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 12 Aug 2026 11:59:56 -0400
Subject: [PATCH 031/200] feat(artist): add Share and Download actions to the
 Artist detail page (#5944)

* feat(ui): add Share button to artist detail page

* feat(ui): add Download button to artist detail page

* fix(ui): scope artist share/download to album-artist content

Gate the artist Share/Download actions on album-artist stats and show the
album-artist size, since ZipArtist and the share query only cover
album_artist_id songs. Previously the total (role-inclusive) size was shown
and guest-only artists could produce an empty archive. Applies to the artist
toolbar, the shared context menu, and the download dialog title.

* fix: match artist download/share to album-artist participation

ZipArtist and the artist share query filtered the deprecated album_artist_id
column, which only stores the first album artist of a track. Secondary
album-artists (co-credited but not first) got an empty download/share even
though the UI offered it. Filter by the album-artist role participation
instead, matching the artist's album-artist stats used to gate the actions.
Also cover the artist-specific size branch of the download dialog.

* fix(share): scope artist shares to the owner's libraries

The artist share query broadened to album-artist participation, which could
pull a secondary album artist's tracks from libraries the (non-admin) share
owner cannot access into the public share. Load the artist share as the owner
so their library access is applied, mirroring how playlist shares already work.
Adds a repository test covering co-album-artist inclusion and library scoping.

* test(share): assert album participation branch of artist shares

Link the co-album-artist fixtures to albums and assert share.Albums (used by
Subsonic getShares) includes the accessible album and excludes the one in a
library the owner cannot access, so the album participation + scoping branch
is covered too.

* fix: exclude missing files from artist download/share actions

An artist's stats still count files that went missing, so the toolbar/context
menu could offer Download/Share for an artist whose files are all gone, while
the share query (missing=false) returns nothing and downloads open dead paths.
Hide the actions when the artist is missing and exclude missing files from
ZipArtist, matching the share semantics.

* refactor: dedupe artist download-size and share-owner lookups

Extract the 'album-artist download size (or none when missing)' rule into a
single artistDownloadSize() helper shared by the toolbar, context menu, and
download dialog, and factor the duplicated share-owner context lookup into a
shareRepository.ownerContext() method used by both the artist and playlist
share cases.

* refactor(ui): move artistDownloadSize helper to common

utils is for domain-agnostic, potentially portable code; this helper is
Navidrome-specific (artist stats shape), so it belongs in common. Consumers
import it directly from common/artist to avoid pulling in the common barrel.
---
 core/archiver.go                           |  9 ++-
 core/archiver_test.go                      |  8 ++-
 persistence/share_repository.go            | 36 +++++++---
 persistence/share_repository_test.go       | 83 ++++++++++++++++++++++
 ui/src/artist/ArtistActions.jsx            | 41 +++++++++++
 ui/src/artist/ArtistActions.test.jsx       | 65 ++++++++++++++++-
 ui/src/common/ContextMenus.jsx             | 10 ++-
 ui/src/common/ContextMenus.test.jsx        | 78 ++++++++++++++++++++
 ui/src/common/artist.js                    |  6 ++
 ui/src/common/artist.test.js               | 24 +++++++
 ui/src/common/index.js                     |  1 +
 ui/src/dialogs/DownloadMenuDialog.jsx      | 11 ++-
 ui/src/dialogs/DownloadMenuDialog.test.jsx | 58 +++++++++++++++
 13 files changed, 411 insertions(+), 19 deletions(-)
 create mode 100644 ui/src/common/ContextMenus.test.jsx
 create mode 100644 ui/src/common/artist.js
 create mode 100644 ui/src/common/artist.test.js
 create mode 100644 ui/src/dialogs/DownloadMenuDialog.test.jsx

diff --git a/core/archiver.go b/core/archiver.go
index 8c42f8f49..c9436279e 100644
--- a/core/archiver.go
+++ b/core/archiver.go
@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/core/stream"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
 	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/navidrome/navidrome/utils/str"
 )
@@ -40,7 +41,13 @@ func (a *archiver) ZipAlbum(ctx context.Context, id string, format string, bitra
 }
 
 func (a *archiver) ZipArtist(ctx context.Context, id string, format string, bitrate int, out io.Writer) error {
-	return a.zipAlbums(ctx, id, format, bitrate, out, squirrel.Eq{"album_artist_id": id})
+	// Match by album-artist participation, not the deprecated album_artist_id
+	// column (first album artist only), so co-album-artists are included too.
+	filter := squirrel.And{
+		persistence.ParticipantIDFilter("media_file", id, model.RoleAlbumArtist),
+		squirrel.Eq{"missing": false},
+	}
+	return a.zipAlbums(ctx, id, format, bitrate, out, filter)
 }
 
 func (a *archiver) zipAlbums(ctx context.Context, id string, format string, bitrate int, out io.Writer, filters squirrel.Sqlizer) error {
diff --git a/core/archiver_test.go b/core/archiver_test.go
index 2ba8f1fc0..461af1800 100644
--- a/core/archiver_test.go
+++ b/core/archiver_test.go
@@ -11,6 +11,7 @@ import (
 	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/stream"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/stretchr/testify/mock"
@@ -69,8 +70,11 @@ var _ = Describe("Archiver", func() {
 
 			mfRepo := &mockMediaFileRepository{}
 			mfRepo.On("GetAll", []model.QueryOptions{{
-				Filters: squirrel.Eq{"album_artist_id": "1"},
-				Sort:    "album",
+				Filters: squirrel.And{
+					persistence.ParticipantIDFilter("media_file", "1", model.RoleAlbumArtist),
+					squirrel.Eq{"missing": false},
+				},
+				Sort: "album",
 			}}).Return(mfs, nil)
 
 			ds.On("MediaFile", mock.Anything).Return(mfRepo)
diff --git a/persistence/share_repository.go b/persistence/share_repository.go
index 0013e782b..4b6dc9240 100644
--- a/persistence/share_repository.go
+++ b/persistence/share_repository.go
@@ -82,13 +82,20 @@ func (r *shareRepository) loadMedia(share *model.Share) error {
 	}
 	switch share.ResourceType {
 	case "artist":
-		albumRepo := NewAlbumRepository(r.ctx, r.db)
-		share.Albums, err = albumRepo.GetAll(model.QueryOptions{Filters: noMissing(Eq{"album_artist_id": ids}), Sort: "artist"})
+		// Match by album-artist participation, not the deprecated album_artist_id
+		// column (first album artist only), so co-album-artists are included too.
+		// Load as the share owner so their library access is applied.
+		ctx, err := r.ownerContext(share)
 		if err != nil {
 			return err
 		}
-		mfRepo := NewMediaFileRepository(r.ctx, r.db)
-		share.Tracks, err = mfRepo.GetAll(model.QueryOptions{Filters: noMissing(Eq{"album_artist_id": ids}), Sort: "artist"})
+		albumRepo := NewAlbumRepository(ctx, r.db)
+		share.Albums, err = albumRepo.GetAll(model.QueryOptions{Filters: noMissing(ParticipantIDFilter("album", ids, model.RoleAlbumArtist)), Sort: "artist"})
+		if err != nil {
+			return err
+		}
+		mfRepo := NewMediaFileRepository(ctx, r.db)
+		share.Tracks, err = mfRepo.GetAll(model.QueryOptions{Filters: noMissing(ParticipantIDFilter("media_file", ids, model.RoleAlbumArtist)), Sort: "artist"})
 		return err
 	case "album":
 		albumRepo := NewAlbumRepository(r.ctx, r.db)
@@ -101,14 +108,10 @@ func (r *shareRepository) loadMedia(share *model.Share) error {
 		return err
 	case "playlist":
 		// Load tracks as the share owner so their library access is applied.
-		owner, err := NewUserRepository(r.ctx, r.db).Get(share.UserID)
+		ctx, err := r.ownerContext(share)
 		if err != nil {
-			return fmt.Errorf("loading share owner %q: %w", share.UserID, err)
+			return err
 		}
-		if owner == nil {
-			return fmt.Errorf("share owner %q not found", share.UserID)
-		}
-		ctx := request.WithUser(r.ctx, *owner)
 		plsRepo := NewPlaylistRepository(ctx, r.db)
 		// Tracks returns nil when the playlist is no longer visible to the owner
 		// (e.g. it was made private after the share was created); leave the share
@@ -133,6 +136,19 @@ func (r *shareRepository) loadMedia(share *model.Share) error {
 	return nil
 }
 
+// ownerContext returns a context scoped to the share owner, so repository
+// queries apply the owner's library access when a public share is rendered.
+func (r *shareRepository) ownerContext(share *model.Share) (context.Context, error) {
+	owner, err := NewUserRepository(r.ctx, r.db).Get(share.UserID)
+	if err != nil {
+		return nil, fmt.Errorf("loading share owner %q: %w", share.UserID, err)
+	}
+	if owner == nil {
+		return nil, fmt.Errorf("share owner %q not found", share.UserID)
+	}
+	return request.WithUser(r.ctx, *owner), nil
+}
+
 func sortByIdPosition(mfs model.MediaFiles, ids []string) model.MediaFiles {
 	m := map[string]int{}
 	for i, mf := range mfs {
diff --git a/persistence/share_repository_test.go b/persistence/share_repository_test.go
index 3ae456031..3af91b2af 100644
--- a/persistence/share_repository_test.go
+++ b/persistence/share_repository_test.go
@@ -228,6 +228,89 @@ var _ = Describe("ShareRepository", func() {
 		})
 	})
 
+	Describe("Artist share library scoping", func() {
+		var otherLib model.Library
+		var owner model.User
+		const primaryID = "share-aa-primary"
+		const secondaryID = "share-aa-secondary"
+
+		BeforeEach(func() {
+			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
+			b := GetDBXBuilder()
+
+			// A second library the owner has no access to
+			lr := NewLibraryRepository(adminCtx, b)
+			otherLib = model.Library{ID: 0, Name: "Artist Share Other Library", Path: "/share/artist/other"}
+			Expect(lr.Put(&otherLib)).To(Succeed())
+
+			ar := NewArtistRepository(adminCtx, b)
+			Expect(createArtistWithLibrary(ar, &model.Artist{ID: primaryID, Name: "AA Primary", OrderArtistName: "aa primary"}, 1)).To(Succeed())
+			Expect(createArtistWithLibrary(ar, &model.Artist{ID: secondaryID, Name: "AA Secondary", OrderArtistName: "aa secondary"}, 1)).To(Succeed())
+
+			// Secondary is a co-album-artist (not the first): album_artist_id points at
+			// primary, so the legacy-column filter would miss both tracks.
+			aaParticipants := model.Participants{model.RoleAlbumArtist: {
+				{Artist: model.Artist{ID: primaryID, Name: "AA Primary"}},
+				{Artist: model.Artist{ID: secondaryID, Name: "AA Secondary"}},
+			}}
+			alr := NewAlbumRepository(adminCtx, b)
+			Expect(alr.Put(&model.Album{ID: "art-album-ok", LibraryID: 1, Name: "Art Album OK", AlbumArtistID: primaryID, AlbumArtist: "AA Primary", Participants: aaParticipants})).To(Succeed())
+			Expect(alr.Put(&model.Album{ID: "art-album-other", LibraryID: otherLib.ID, Name: "Art Album Other", AlbumArtistID: primaryID, AlbumArtist: "AA Primary", Participants: aaParticipants})).To(Succeed())
+
+			mr := NewMediaFileRepository(adminCtx, b)
+			Expect(mr.Put(&model.MediaFile{ID: "art-ok", LibraryID: 1, AlbumID: "art-album-ok", Path: "a/ok.mp3", Title: "ArtOK", AlbumArtistID: primaryID, Participants: aaParticipants})).To(Succeed())
+			Expect(mr.Put(&model.MediaFile{ID: "art-other", LibraryID: otherLib.ID, AlbumID: "art-album-other", Path: "a/other.mp3", Title: "ArtOther", AlbumArtistID: primaryID, Participants: aaParticipants})).To(Succeed())
+
+			// Non-admin owner with access to library 1 only
+			owner = createUserWithLibraries("artist-share-owner", []int{1})
+			ur := NewUserRepository(adminCtx, b)
+			Expect(ur.Put(&owner)).To(Succeed())
+			Expect(ur.SetUserLibraries(owner.ID, []int{1})).To(Succeed())
+
+			_, err := b.NewQuery(`
+				INSERT INTO share (id, user_id, description, resource_type, resource_ids, created_at, updated_at)
+				VALUES ({:id}, {:user}, {:desc}, {:type}, {:ids}, {:created}, {:updated})
+			`).Bind(map[string]any{
+				"id": "art-share", "user": owner.ID, "desc": "Artist scope share",
+				"type": "artist", "ids": secondaryID, "created": time.Now(), "updated": time.Now(),
+			}).Execute()
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		AfterEach(func() {
+			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
+			b := GetDBXBuilder()
+			_, _ = b.NewQuery(`DELETE FROM share WHERE id = 'art-share'`).Execute()
+			mr := NewMediaFileRepository(adminCtx, b).(*mediaFileRepository)
+			_, _ = mr.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": []string{"art-ok", "art-other"}}))
+			alr := NewAlbumRepository(adminCtx, b).(*albumRepository)
+			_, _ = alr.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"art-album-ok", "art-album-other"}}))
+			ar := NewArtistRepository(adminCtx, b).(*artistRepository)
+			_, _ = ar.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": []string{primaryID, secondaryID}}))
+			lr := NewLibraryRepository(adminCtx, b).(*libraryRepository)
+			_ = lr.delete(squirrel.Eq{"id": otherLib.ID})
+			_ = NewUserRepository(adminCtx, b).Delete(owner.ID)
+		})
+
+		It("includes co-album-artist tracks the owner can access and excludes those they cannot", func() {
+			// Read as admin (mimics the public-share render path); loadMedia must still
+			// scope to the owner's libraries.
+			adminRepo := NewShareRepository(request.WithUser(log.NewContext(GinkgoT().Context()), adminUser), GetDBXBuilder())
+			share, err := adminRepo.Get("art-share")
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(share.Tracks).To(ContainElement(HaveField("ID", "art-ok")),
+				"a co-album-artist track (not matched by album_artist_id) must be included")
+			Expect(share.Tracks).ToNot(ContainElement(HaveField("ID", "art-other")),
+				"a track outside the owner's libraries must not appear in the share")
+
+			Expect(share.Albums).To(ContainElement(HaveField("ID", "art-album-ok")),
+				"a co-album-artist album must be included")
+			Expect(share.Albums).ToNot(ContainElement(HaveField("ID", "art-album-other")),
+				"an album outside the owner's libraries must not appear in the share")
+		})
+	})
+
 	Describe("Ownership Checks", func() {
 		var ownerUser = model.User{ID: "2222", UserName: "regular-user"}
 		var otherUser = model.User{ID: "3333", UserName: "third-user"}
diff --git a/ui/src/artist/ArtistActions.jsx b/ui/src/artist/ArtistActions.jsx
index 0b48f232d..2f329a034 100644
--- a/ui/src/artist/ArtistActions.jsx
+++ b/ui/src/artist/ArtistActions.jsx
@@ -13,9 +13,19 @@ import {
 } from 'react-admin'
 import ShuffleIcon from '@material-ui/icons/Shuffle'
 import PlayArrowIcon from '@material-ui/icons/PlayArrow'
+import ShareIcon from '@material-ui/icons/Share'
+import CloudDownloadOutlinedIcon from '@material-ui/icons/CloudDownloadOutlined'
 import { IoIosRadio } from 'react-icons/io'
 import { playShuffle, playTopSongs } from './actions.js'
 import { playSimilar } from '../common/playbackActions.js'
+import {
+  openShareMenu,
+  openDownloadMenu,
+  DOWNLOAD_MENU_ARTIST,
+} from '../actions'
+import config from '../config'
+import { formatBytes } from '../utils'
+import { artistDownloadSize } from '../common/artist'
 
 const useStyles = makeStyles((theme) => ({
   toolbar: {
@@ -62,6 +72,9 @@ const ArtistActions = ({ className, record, ...rest }) => {
   const [loadingAction, setLoadingAction] = React.useState(null)
   const isLoading = !!loadingAction
 
+  const albumArtistSize = artistDownloadSize(record)
+  const hasAlbumArtistContent = Boolean(albumArtistSize)
+
   const handlePlay = React.useCallback(async () => {
     setLoadingAction('play')
     try {
@@ -101,6 +114,14 @@ const ArtistActions = ({ className, record, ...rest }) => {
     }
   }, [dispatch, notify, record])
 
+  const handleShare = React.useCallback(() => {
+    dispatch(openShareMenu([record.id], 'artist', record.name))
+  }, [dispatch, record])
+
+  const handleDownload = React.useCallback(() => {
+    dispatch(openDownloadMenu(record, DOWNLOAD_MENU_ARTIST))
+  }, [dispatch, record])
+
   return (
     <TopToolbar
       className={`${className} ${classes.toolbar}`}
@@ -133,6 +154,26 @@ const ArtistActions = ({ className, record, ...rest }) => {
         loading={loadingAction === 'radio'}
         icon={<IoIosRadio className={classes.radioIcon} />}
       />
+      {config.enableSharing && hasAlbumArtistContent && (
+        <LoadingButton
+          onClick={handleShare}
+          label={translate('ra.action.share')}
+          className={classes.button}
+          size={isMobile ? 'small' : 'medium'}
+          icon={<ShareIcon />}
+        />
+      )}
+      {config.enableDownloads && hasAlbumArtistContent && (
+        <LoadingButton
+          onClick={handleDownload}
+          label={`${translate('ra.action.download')} (${formatBytes(
+            albumArtistSize,
+          )})`}
+          className={classes.button}
+          size={isMobile ? 'small' : 'medium'}
+          icon={<CloudDownloadOutlinedIcon />}
+        />
+      )}
     </TopToolbar>
   )
 }
diff --git a/ui/src/artist/ArtistActions.test.jsx b/ui/src/artist/ArtistActions.test.jsx
index a11ee50e3..ad25177b3 100644
--- a/ui/src/artist/ArtistActions.test.jsx
+++ b/ui/src/artist/ArtistActions.test.jsx
@@ -4,6 +4,11 @@ import { TestContext } from 'ra-test'
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 import ArtistActions from './ArtistActions'
 import subsonic from '../subsonic'
+import {
+  openShareMenu,
+  openDownloadMenu,
+  DOWNLOAD_MENU_ARTIST,
+} from '../actions'
 import { ThemeProvider, createTheme } from '@material-ui/core/styles'
 
 const mockDispatch = vi.fn()
@@ -13,6 +18,11 @@ vi.mock('../subsonic', () => ({
   default: { getSimilarSongs2: vi.fn(), getTopSongs: vi.fn() },
 }))
 
+const { mockConfig } = vi.hoisted(() => ({
+  mockConfig: { enableSharing: true, enableDownloads: true },
+}))
+vi.mock('../config', () => ({ default: mockConfig }))
+
 const mockNotify = vi.fn()
 const mockGetList = vi.fn().mockResolvedValue({ data: [{ id: 's1' }] })
 
@@ -27,7 +37,11 @@ vi.mock('react-admin', async (importOriginal) => {
 })
 
 describe('ArtistActions', () => {
-  const defaultRecord = { id: 'ar1', name: 'Artist' }
+  const defaultRecord = {
+    id: 'ar1',
+    name: 'Artist',
+    stats: { albumartist: { songCount: 3, albumCount: 1, size: 1024 } },
+  }
 
   const renderArtistActions = (record = defaultRecord) => {
     const theme = createTheme()
@@ -48,6 +62,8 @@ describe('ArtistActions', () => {
     vi.clearAllMocks()
     // Mock console.error to suppress error logging in tests
     vi.spyOn(console, 'error').mockImplementation(() => {})
+    mockConfig.enableSharing = true
+    mockConfig.enableDownloads = true
 
     const songWithReplayGain = {
       id: 'rec1',
@@ -227,4 +243,51 @@ describe('ArtistActions', () => {
       expect(mockDispatch).not.toHaveBeenCalled()
     })
   })
+
+  describe('Share action', () => {
+    it('shows the share button and dispatches openShareMenu when clicked', () => {
+      renderArtistActions()
+      fireEvent.click(screen.getByText('ra.action.share'))
+      expect(mockDispatch).toHaveBeenCalledWith(
+        openShareMenu(['ar1'], 'artist', 'Artist'),
+      )
+    })
+
+    it('hides the share button when sharing is disabled', () => {
+      mockConfig.enableSharing = false
+      renderArtistActions()
+      expect(screen.queryByText('ra.action.share')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Download action', () => {
+    it('shows the download button with album-artist size and dispatches openDownloadMenu when clicked', () => {
+      renderArtistActions()
+      expect(screen.getByText('ra.action.download (1 KB)')).toBeInTheDocument()
+      fireEvent.click(screen.getByText(/ra\.action\.download/))
+      expect(mockDispatch).toHaveBeenCalledWith(
+        openDownloadMenu(defaultRecord, DOWNLOAD_MENU_ARTIST),
+      )
+    })
+
+    it('hides the download button when downloads are disabled', () => {
+      mockConfig.enableDownloads = false
+      renderArtistActions()
+      expect(screen.queryByText(/ra\.action\.download/)).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Album-artist gating', () => {
+    it('hides Share and Download for artists with no album-artist content', () => {
+      renderArtistActions({ id: 'ar1', name: 'Artist', stats: {} })
+      expect(screen.queryByText('ra.action.share')).not.toBeInTheDocument()
+      expect(screen.queryByText(/ra\.action\.download/)).not.toBeInTheDocument()
+    })
+
+    it('hides Share and Download for a missing artist', () => {
+      renderArtistActions({ ...defaultRecord, missing: true })
+      expect(screen.queryByText('ra.action.share')).not.toBeInTheDocument()
+      expect(screen.queryByText(/ra\.action\.download/)).not.toBeInTheDocument()
+    })
+  })
 })
diff --git a/ui/src/common/ContextMenus.jsx b/ui/src/common/ContextMenus.jsx
index 47c9c6786..7ad8c735c 100644
--- a/ui/src/common/ContextMenus.jsx
+++ b/ui/src/common/ContextMenus.jsx
@@ -24,6 +24,7 @@ import {
 import { LoveButton } from './LoveButton'
 import config from '../config'
 import { formatBytes } from '../utils'
+import { artistDownloadSize } from './artist'
 
 const useStyles = makeStyles({
   noWrap: {
@@ -70,6 +71,9 @@ const ContextMenu = ({
   const notify = useNotify()
   const [anchorEl, setAnchorEl] = useState(null)
 
+  const isArtist = resource === 'artist'
+  const downloadSize = isArtist ? artistDownloadSize(record) : record?.size
+
   const options = {
     play: {
       enabled: true,
@@ -103,7 +107,7 @@ const ContextMenu = ({
     },
     ...(!hideShare && {
       share: {
-        enabled: config.enableSharing,
+        enabled: config.enableSharing && (!isArtist || downloadSize),
         needData: false,
         label: translate('ra.action.share'),
         action: (record) =>
@@ -111,9 +115,9 @@ const ContextMenu = ({
       },
     }),
     download: {
-      enabled: config.enableDownloads && record.size,
+      enabled: config.enableDownloads && downloadSize,
       needData: false,
-      label: `${translate('ra.action.download')} (${formatBytes(record.size)})`,
+      label: `${translate('ra.action.download')} (${formatBytes(downloadSize)})`,
       action: () => {
         dispatch(
           openDownloadMenu(
diff --git a/ui/src/common/ContextMenus.test.jsx b/ui/src/common/ContextMenus.test.jsx
new file mode 100644
index 000000000..72a98b64b
--- /dev/null
+++ b/ui/src/common/ContextMenus.test.jsx
@@ -0,0 +1,78 @@
+import React from 'react'
+import { render, fireEvent, screen } from '@testing-library/react'
+import { TestContext } from 'ra-test'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { ThemeProvider, createTheme } from '@material-ui/core/styles'
+import { AlbumContextMenu, ArtistContextMenu } from './ContextMenus'
+
+const mockDispatch = vi.fn()
+vi.mock('react-redux', () => ({ useDispatch: () => mockDispatch }))
+
+const { mockConfig } = vi.hoisted(() => ({
+  mockConfig: {
+    enableSharing: true,
+    enableDownloads: true,
+    enableFavourites: false,
+  },
+}))
+vi.mock('../config', () => ({ default: mockConfig }))
+
+vi.mock('react-admin', async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    useNotify: () => vi.fn(),
+    useDataProvider: () => ({ getList: vi.fn() }),
+    useTranslate: () => (x) => x,
+  }
+})
+
+describe('ContextMenus', () => {
+  const renderMenu = (Menu, record) => {
+    render(
+      <TestContext>
+        <ThemeProvider theme={createTheme()}>
+          <Menu record={record} />
+        </ThemeProvider>
+      </TestContext>,
+    )
+    fireEvent.click(screen.getByLabelText('more'))
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockConfig.enableSharing = true
+    mockConfig.enableDownloads = true
+  })
+
+  describe('ArtistContextMenu', () => {
+    const withAlbumArtist = {
+      id: 'ar1',
+      name: 'Artist',
+      stats: { albumartist: { songCount: 3, albumCount: 1, size: 1024 } },
+    }
+
+    it('shows the album-artist size on the download item', () => {
+      renderMenu(ArtistContextMenu, withAlbumArtist)
+      expect(screen.getByText('ra.action.download (1 KB)')).toBeInTheDocument()
+    })
+
+    it('hides download and share for artists with no album-artist content', () => {
+      renderMenu(ArtistContextMenu, { id: 'ar1', name: 'Artist', stats: {} })
+      expect(screen.queryByText(/ra\.action\.download/)).not.toBeInTheDocument()
+      expect(screen.queryByText('ra.action.share')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('AlbumContextMenu', () => {
+    it('uses the total size on the album download item', () => {
+      renderMenu(AlbumContextMenu, {
+        id: 'al1',
+        name: 'Album',
+        duration: 100,
+        size: 1024 * 1024,
+      })
+      expect(screen.getByText('ra.action.download (1 MB)')).toBeInTheDocument()
+    })
+  })
+})
diff --git a/ui/src/common/artist.js b/ui/src/common/artist.js
new file mode 100644
index 000000000..370700160
--- /dev/null
+++ b/ui/src/common/artist.js
@@ -0,0 +1,6 @@
+// Size of an artist's downloadable album-artist content, or undefined when there
+// is nothing to download (a missing artist, or no album-artist songs). Download
+// and Share only cover album-artist songs, so callers gate on this, not the
+// role-inclusive total.
+export const artistDownloadSize = (record) =>
+  record?.missing ? undefined : record?.stats?.albumartist?.size
diff --git a/ui/src/common/artist.test.js b/ui/src/common/artist.test.js
new file mode 100644
index 000000000..eff9935a6
--- /dev/null
+++ b/ui/src/common/artist.test.js
@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest'
+import { artistDownloadSize } from './artist'
+
+describe('artistDownloadSize', () => {
+  it('returns the album-artist size', () => {
+    expect(
+      artistDownloadSize({ stats: { albumartist: { size: 1024 } } }),
+    ).toEqual(1024)
+  })
+
+  it('returns undefined for a missing artist', () => {
+    expect(
+      artistDownloadSize({
+        missing: true,
+        stats: { albumartist: { size: 1024 } },
+      }),
+    ).toBeUndefined()
+  })
+
+  it('returns undefined when there is no album-artist content', () => {
+    expect(artistDownloadSize({ stats: {} })).toBeUndefined()
+    expect(artistDownloadSize(undefined)).toBeUndefined()
+  })
+})
diff --git a/ui/src/common/index.js b/ui/src/common/index.js
index 7b5b376f3..047f5b3cf 100644
--- a/ui/src/common/index.js
+++ b/ui/src/common/index.js
@@ -1,4 +1,5 @@
 export * from './AddToPlaylistButton'
+export * from './artist'
 export * from './ArtistLinkField'
 export * from './BatchPlayButton'
 export * from './BitrateField'
diff --git a/ui/src/dialogs/DownloadMenuDialog.jsx b/ui/src/dialogs/DownloadMenuDialog.jsx
index 2104cbcad..61e84a08a 100644
--- a/ui/src/dialogs/DownloadMenuDialog.jsx
+++ b/ui/src/dialogs/DownloadMenuDialog.jsx
@@ -8,8 +8,9 @@ import {
   DialogTitle,
 } from '@material-ui/core'
 import subsonic from '../subsonic'
-import { closeDownloadMenu } from '../actions'
+import { closeDownloadMenu, DOWNLOAD_MENU_ARTIST } from '../actions'
 import { formatBytes } from '../utils'
+import { artistDownloadSize } from '../common/artist'
 import { useTranscodingOptions } from './useTranscodingOptions'
 
 const DownloadMenuDialog = () => {
@@ -22,6 +23,12 @@ const DownloadMenuDialog = () => {
   const { TranscodingOptionsInput, format, maxBitRate, originalFormat } =
     useTranscodingOptions()
 
+  // Artist downloads only include album-artist songs, so show that size
+  const downloadSize =
+    recordType === DOWNLOAD_MENU_ARTIST
+      ? artistDownloadSize(record)
+      : record?.size
+
   const handleClose = (e) => {
     dispatch(closeDownloadMenu())
     e.stopPropagation()
@@ -55,7 +62,7 @@ const DownloadMenuDialog = () => {
               smart_count: 1,
             }).toLocaleLowerCase(),
             name: record?.name || record?.title,
-            size: formatBytes(record?.size),
+            size: formatBytes(downloadSize),
           })}
       </DialogTitle>
       <DialogContent>
diff --git a/ui/src/dialogs/DownloadMenuDialog.test.jsx b/ui/src/dialogs/DownloadMenuDialog.test.jsx
new file mode 100644
index 000000000..b9ce7f077
--- /dev/null
+++ b/ui/src/dialogs/DownloadMenuDialog.test.jsx
@@ -0,0 +1,58 @@
+import * as React from 'react'
+import { TestContext } from 'ra-test'
+import { render, screen, cleanup } from '@testing-library/react'
+import { describe, afterEach, it, expect, vi } from 'vitest'
+import DownloadMenuDialog from './DownloadMenuDialog'
+import { DOWNLOAD_MENU_ALBUM, DOWNLOAD_MENU_ARTIST } from '../actions'
+
+vi.mock('./useTranscodingOptions', () => ({
+  useTranscodingOptions: () => ({
+    TranscodingOptionsInput: () => null,
+    format: '',
+    maxBitRate: 0,
+    originalFormat: true,
+  }),
+}))
+
+vi.mock('react-admin', async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    useTranslate: () => (key, opts) =>
+      opts?.size ? `${key}:${opts.name}:${opts.size}` : key,
+  }
+})
+
+const renderDialog = (record, recordType) =>
+  render(
+    <TestContext
+      initialState={{ downloadMenuDialog: { open: true, record, recordType } }}
+    >
+      <DownloadMenuDialog />
+    </TestContext>,
+  )
+
+describe('DownloadMenuDialog', () => {
+  afterEach(cleanup)
+
+  it('shows the album-artist size (not the total) for an artist download', () => {
+    renderDialog(
+      {
+        id: 'ar1',
+        name: 'Artist',
+        size: 999999999,
+        stats: { albumartist: { size: 1024 } },
+      },
+      DOWNLOAD_MENU_ARTIST,
+    )
+    expect(screen.getByText(/:Artist:1 KB$/)).toBeInTheDocument()
+  })
+
+  it('shows the total size for an album download', () => {
+    renderDialog(
+      { id: 'al1', name: 'Album', size: 1024 * 1024 },
+      DOWNLOAD_MENU_ALBUM,
+    )
+    expect(screen.getByText(/:Album:1 MB$/)).toBeInTheDocument()
+  })
+})

From 5a4a3099f1a65e31c9c1201674067987ae9fe990 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 12 Aug 2026 14:55:04 -0400
Subject: [PATCH 032/200] fix(cli): accept absolute paths in selective scan
 --target (#5947)

* fix(scanner): accept absolute paths in selective scan --target

The scanner's fs.FS only accepts paths relative to the library root, so an
absolute --target path (e.g. 2:/jukebox/collection) failed with an opaque
"invalid argument" error. Rebase absolute targets onto the library root
before scanning; relative paths are unchanged.

Fixes #5943

* refactor(scanner): simplify libraryRelativePath with IsLocal and slice.ToMap

* fix(scanner): make libraryRelativePath cross-platform

Windows CI failed: the tests hardcoded Unix-style absolute paths, which are
not absolute on Windows, and filepath.Rel yields backslash-separated paths
that the io/fs-based scanner FS rejects. Build the test paths with
filepath.Abs so they are absolute on every OS, and normalize the rebased
result with filepath.ToSlash.

* fix(scanner): resolve relative library root before rebasing target

filepath.Rel cannot rebase an absolute target onto a relative library root
(e.g. the default MusicFolder=./music), so an absolute --target was left
unchanged and rejected by the rooted io/fs. Make the library root absolute
first; it resolves against the same cwd as the scanner's fs.
---
 model/scanner.go                 |  2 +-
 scanner/scanner.go               | 28 ++++++++++++++++++++++-
 scanner/scanner_internal_test.go | 39 ++++++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/model/scanner.go b/model/scanner.go
index 54f81037c..36c9007fb 100644
--- a/model/scanner.go
+++ b/model/scanner.go
@@ -12,7 +12,7 @@ import (
 // NOTE: This struct is used as a map key, so it should only contain comparable types.
 type ScanTarget struct {
 	LibraryID  int
-	FolderPath string // Relative path within the library, or "" for entire library
+	FolderPath string // Path within the library (relative or absolute), or "" for entire library
 }
 
 func (st ScanTarget) String() string {
diff --git a/scanner/scanner.go b/scanner/scanner.go
index 29a1f9b4e..d73007bdd 100644
--- a/scanner/scanner.go
+++ b/scanner/scanner.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"maps"
+	"path/filepath"
 	"slices"
 	"sync/atomic"
 	"time"
@@ -51,6 +52,27 @@ func (s *scanState) sendError(err error) {
 	s.sendProgress(&ProgressInfo{Error: err.Error()})
 }
 
+// libraryRelativePath rebases an absolute scan target path onto the library root, since the
+// scanner's fs.FS only accepts paths relative to it. Relative paths, and absolute paths outside
+// the library root, are returned unchanged.
+func libraryRelativePath(libPath, folderPath string) string {
+	if !filepath.IsAbs(folderPath) {
+		return folderPath
+	}
+	// The library root may be relative (e.g. the default "./music"); it must be made absolute
+	// to match against an absolute target, and it resolves against the same cwd as the scanner's fs.
+	absLib, err := filepath.Abs(libPath)
+	if err != nil {
+		return folderPath
+	}
+	rel, err := filepath.Rel(absLib, folderPath)
+	if err != nil || !filepath.IsLocal(rel) {
+		return folderPath
+	}
+	// The scanner's fs.FS is an io/fs, which always uses forward slashes.
+	return filepath.ToSlash(rel)
+}
+
 func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []model.ScanTarget, progress chan<- *ProgressInfo) {
 	startTime := time.Now()
 
@@ -77,8 +99,12 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 		// Selective scan: filter libraries and build targets map
 		state.targets = make(map[int][]string)
 
+		libPaths := slice.ToMap(allLibs, func(lib model.Library) (int, string) {
+			return lib.ID, lib.Path
+		})
+
 		for _, target := range targets {
-			folderPath := target.FolderPath
+			folderPath := libraryRelativePath(libPaths[target.LibraryID], target.FolderPath)
 			if folderPath == "" {
 				folderPath = "."
 			}
diff --git a/scanner/scanner_internal_test.go b/scanner/scanner_internal_test.go
index e8abb7c7d..0778bd6ec 100644
--- a/scanner/scanner_internal_test.go
+++ b/scanner/scanner_internal_test.go
@@ -4,6 +4,8 @@ package scanner
 import (
 	"context"
 	"errors"
+	"os"
+	"path/filepath"
 	"sync/atomic"
 
 	ppl "github.com/google/go-pipeline/pkg/pipeline"
@@ -11,6 +13,43 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+var _ = Describe("libraryRelativePath", func() {
+	// Paths are built with filepath so the "absolute" cases stay absolute on every OS
+	// (a Unix-style "/foo" is not absolute on Windows).
+	libRoot, _ := filepath.Abs(filepath.Join("jukebox", "collection"))
+	outside, _ := filepath.Abs(filepath.Join("somewhere", "else"))
+
+	It("returns a relative path unchanged", func() {
+		Expect(libraryRelativePath(libRoot, "_Collection")).To(Equal("_Collection"))
+	})
+
+	It("rebases an absolute target when the library root is relative", func() {
+		cwd, err := os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		Expect(libraryRelativePath(filepath.Join("music", "library"), filepath.Join(cwd, "music", "library", "rock"))).To(Equal("rock"))
+	})
+
+	It("rebases an absolute path that equals the library root to '.'", func() {
+		Expect(libraryRelativePath(libRoot, libRoot)).To(Equal("."))
+	})
+
+	It("rebases an absolute path under the library root", func() {
+		Expect(libraryRelativePath(libRoot, filepath.Join(libRoot, "_Collection"))).To(Equal("_Collection"))
+	})
+
+	It("handles a trailing slash on the library path", func() {
+		Expect(libraryRelativePath(libRoot+string(filepath.Separator), filepath.Join(libRoot, "_Collection"))).To(Equal("_Collection"))
+	})
+
+	It("leaves an absolute path outside the library root unchanged", func() {
+		Expect(libraryRelativePath(libRoot, outside)).To(Equal(outside))
+	})
+
+	It("returns an empty path unchanged", func() {
+		Expect(libraryRelativePath(libRoot, "")).To(Equal(""))
+	})
+})
+
 type mockPhase struct {
 	num           int
 	produceFunc   func() ppl.Producer[int]

From c66ef04dd3111712a44d60d5895d8b77216baba7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 12 Aug 2026 19:02:34 -0400
Subject: [PATCH 033/200] refactor(jellyfin): emit real 128-bit GUIDs as item
 ids (#5942)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* test(jellyfin): use canonical ids in dto fixtures

Fixtures used short placeholder strings, which are not valid Navidrome ids. Deriving them from
id.NewHash keeps the labels readable while exercising the real id shape.

* test(jellyfin): use canonical ids in handler fixtures

Fixtures used short placeholder strings, which are not valid Navidrome ids. Deriving them from
id.NewHash keeps the labels readable while exercising the real id shape. Playlist entry positions
stay decimal, matching the integer playlist_tracks.id column.

* test(jellyfin): use canonical ids in e2e fixtures

Fixtures used short placeholder strings, which are not valid Navidrome ids. Deriving them from
id.NewHash keeps the labels readable while exercising the real id shape.

* test(jellyfin): use canonical ids in audiomuse fixtures

audiomuse_test.go passes ids as bare function args (mf(id, ...), call(query, user)) rather than
via ID: struct-literal fields, so the original grep-built file list missed it. Same conversion as
the rest of the fixtures: fake labels through id.NewHash via testID.

* test(jellyfin): convert remaining nonexistent-id sentinels in e2e tests

Reviewer swept for enc("literal") sites the brief's dto.EncodeID grep missed. These "does not
exist" fixtures must stay well-formed GUIDs under the strict codec, or the test degrades from
"resolves to nothing" to "empty path segment".

* refactor(jellyfin): emit real 128-bit GUIDs as item ids

Navidrome ids are now a canonical 22-char base62 encoding of exactly 128 bits, so they map
losslessly onto Jellyfin GUIDs. Previously the API hex-encoded the id string itself, producing
44 hex chars where Jellyfin uses 32.

Integer library ids, the synthetic playlists folder, and playlist entry positions (a
playlist_tracks.id, an integer column) aren't 128-bit values, so they get a reserved GUID space
tagged by kind. DecodeID is now strict: malformed input returns an empty string instead of
passing through unchanged.

BREAKING: Jellyfin clients see entirely new item ids.

* fix(jellyfin): 404 malformed playlist ids instead of silently creating

updatePlaylist decoded a malformed playlistId to "", the same sentinel core/playlists.Create
uses to mean "make a new playlist" — the overload createPlaylist deliberately relies on. A
malformed id now 404s before reaching Create.

Also tightens id-codec test fixtures: several tests set chi params to a raw canonical id, which
now decodes to "" and only passed because the fakes ignore the id argument; and a batch of
not-found sentinels now use well-formed-but-nonexistent GUIDs so they exercise the intended path
instead of the malformed-id path. READMEs "lossless" claim softened to note the reserved space.

* refactor(jellyfin): drop the id truncation workaround

Finamp's saved-queue packing keeps the first 16 bytes of each item id. That was lossy only
because our ids were 44 hex chars; now they are 32, so the packing round-trips exactly and the
server-side prefix recovery is dead code.

Removes an indexed range scan per restored queue and the ambiguous-prefix path that could
resolve to the wrong item.

* fix(jellyfin): emit ServerId and PlaySessionId in Jellyfin's id format

Jellyfin serializes GUIDs without dashes; ServerId was emitting the dashed UUID form. A
ServerId persisted before this change is normalized on read rather than rewritten.

PlaySessionId was emitting a raw internal id instead of the encoded form.

BREAKING: the ServerId change makes clients treat the server as new, so users re-login once.

* fix(jellyfin): 404 on undecodable id filters instead of widening the query

DecodeID collapsed an absent param and an undecodable one into the empty string, and downstream
an empty id means no filter. A client sending a stale pre-upgrade id therefore had its filter
silently dropped: ParentId, ArtistIds and AlbumArtistIds each returned the whole library instead
of a scoped result. Every existing client hits this on first launch after the id format changes.

Scalar id params now distinguish the two cases and report not-found. List-valued params already
failed closed. EncodeID logs a diagnostic when a non-empty id is not canonical, which should not
happen post-migration and would otherwise ship an unaddressable item silently.

* test(jellyfin): drop comments that restate the spec names

* refactor(jellyfin): decode reserved GUIDs from bytes, not hex strings

DecodeID already had the 16 decoded bytes, then re-derived the kind tag and payload by slicing the
hex string and parsing it a second time. Reading them off the byte slice matches how the format is
specified and removes the duplicate parse.

Bounding the payload inside encodeReserved gives both encoders the 32-char guarantee, which only
EncodePlaylistEntryID enforced before.

Playlist entries now decode through DecodePlaylistEntryID, which rejects other kinds. The tag was
being encoded and then discarded, so a song id passed as an EntryId reached RemoveTracks as a
playlist_tracks position.

Drops the per-field log.Warn from EncodeID: it sat in a leaf codec without a ctx and would emit
once per item per request on exactly the bad-data population it was meant to surface.

* refactor(jellyfin): make DecodeID report whether the id was decodable

DecodeID returned the empty string for both an absent param and an undecodable one, and
downstream an empty id means no filter. That conflation is what let a stale id widen /Items to
the whole library; it had been patched at two call sites, leaving three different policies for an
undecodable id in one package and ~16 handlers correct only because a repo Get("") happens to fail.

Returning (string, bool) makes the ambiguity unrepresentable, and the compiler forces each of the
~22 sites to decide. URL params share one itemIDParam helper that 404s; id lists go through
DecodeIDs, which is all-or-nothing because dropping bad entries would empty a list and make its
len() > 0 filter gate vanish — the original bug by another route.

A well-formed but unknown id is still 200 with zero results; only malformed ids 404. Malformed
ids now also 404 on the image and similar/instant-mix routes, which previously answered with a
placeholder or an empty list.
---
 server/jellyfin/README.md               |  44 ++-
 server/jellyfin/annotations.go          |  16 +-
 server/jellyfin/annotations_test.go     | 146 +++++-----
 server/jellyfin/api_test.go             |   4 +-
 server/jellyfin/audiomuse.go            |  20 +-
 server/jellyfin/audiomuse_test.go       |  70 +++--
 server/jellyfin/auth_test.go            |   6 +-
 server/jellyfin/browsing.go             |  25 +-
 server/jellyfin/browsing_test.go        |  49 +++-
 server/jellyfin/dto/dto_suite_test.go   |   5 +
 server/jellyfin/dto/ids.go              | 146 +++++++++-
 server/jellyfin/dto/ids_test.go         | 162 +++++++++--
 server/jellyfin/dto/mappers.go          |   5 +-
 server/jellyfin/dto/mappers_test.go     | 204 ++++++-------
 server/jellyfin/e2e/annotations_test.go |   4 +-
 server/jellyfin/e2e/audiomuse_test.go   |   4 +-
 server/jellyfin/e2e/auth_test.go        |   8 +-
 server/jellyfin/e2e/browsing_test.go    | 132 ++++++---
 server/jellyfin/e2e/e2e_suite_test.go   |  13 +-
 server/jellyfin/e2e/lyrics_test.go      |   2 +-
 server/jellyfin/e2e/multiuser_test.go   |   2 +-
 server/jellyfin/e2e/playlists_test.go   |  54 +++-
 server/jellyfin/e2e/search_test.go      |   3 +-
 server/jellyfin/e2e/similar_test.go     |  59 ++--
 server/jellyfin/e2e/streaming_test.go   |   4 +-
 server/jellyfin/images.go               |  21 +-
 server/jellyfin/images_test.go          | 124 ++++----
 server/jellyfin/items.go                | 104 ++++---
 server/jellyfin/items_test.go           | 366 +++++++++++++++---------
 server/jellyfin/jellyfin_suite_test.go  |   5 +
 server/jellyfin/library.go              |  34 ++-
 server/jellyfin/lyrics_test.go          |  38 +--
 server/jellyfin/middlewares_test.go     |   6 +-
 server/jellyfin/playlists.go            |  68 +++--
 server/jellyfin/playlists_test.go       | 171 +++++------
 server/jellyfin/sessions.go             |   9 +-
 server/jellyfin/sessions_test.go        |  34 ++-
 server/jellyfin/similar.go              |  16 +-
 server/jellyfin/similar_test.go         |  32 +--
 server/jellyfin/socket_test.go          |   4 +-
 server/jellyfin/stream.go               |   7 +-
 server/jellyfin/stream_test.go          | 100 +++----
 server/jellyfin/system.go               |  17 +-
 server/jellyfin/system_test.go          |  20 +-
 server/jellyfin/truncated_ids.go        | 113 --------
 server/jellyfin/users_test.go           |  14 +-
 46 files changed, 1549 insertions(+), 941 deletions(-)
 delete mode 100644 server/jellyfin/truncated_ids.go

diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 13ec79aa8..195173c2a 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -85,15 +85,6 @@ player id is the device id from `X-Emby-Authorization` (`DeviceId="..."`); the p
 client/device info (e.g. the `GET socket` handshake, which authenticates via `?api_key=` only) is
 skipped, so it doesn't create a nameless player.
 
-## ID encoding
-
-Navidrome item ids are **hex-encoded at the API boundary** (`dto.EncodeID`/`DecodeID`): every id
-is hex-encoded on the way out and hex-decoded on the way in. This is required because some clients
-parse ids as radix-16 — Finamp's queue `packIds`, for instance, does `int.parse(chunk, radix:16)`,
-which chokes on Navidrome's base62 ids (e.g. `5QFKvMsJrd57QE2Le2dKKo`). Because a base62 id can
-itself be valid hex, correctness depends on every emit path encoding and every receive path
-decoding — see `dto/ids.go`.
-
 ## Multi-library behavior
 
 Jellyfin has no native concept of multiple music libraries the way Navidrome does, so each
@@ -180,26 +171,25 @@ warmer uses — so user-scoped items like private playlists still resolve their
 falling back to the placeholder. Album, artist, media-file and playlist ids are all resolved to
 their Navidrome `ArtworkID`.
 
-## Finamp saved-queue id truncation
+## Item ids are GUIDs
 
-Real Jellyfin item ids are GUIDs — 128-bit values, always 32 hex characters. Finamp relies on that
-when persisting its play queue across restarts: `packIds()` bit-packs every id into exactly 16
-bytes. Navidrome ids are 22-character base62 strings, not 32-hex GUIDs, which means Finamp silently
-stores only the first 16 characters of each id and asks for those **truncated ids** back when
-restoring the queue — item lookups, then streaming, images, favorites and playback reports for the
-restored tracks.
+Jellyfin item ids are GUIDs, serialized as 32 lowercase hex chars with no dashes
+(`Guid.ToString("N")`). Navidrome ids are canonical 22-char base62 encodings of a 128-bit value,
+so `dto.EncodeID`/`dto.DecodeID` map between the two via `model/id` — losslessly except for the
+~2⁻⁹⁶ chance an id's 128-bit value falls in the reserved space below (leading 12 bytes all zero).
 
-This API compensates server-side (`truncated_ids.go`): a 16-character id — a length no Navidrome
-id uses — is resolved to the full id by unique-prefix lookup (an indexed range scan;
-ambiguity is detected and fails safe). The `/Items?ids=` batch response echoes the id **as
-requested**, because Finamp matches restored items back to its stored ids, and the other item
-endpoints accept truncated ids transparently.
+Three emitted ids aren't 128-bit values: integer library ids, the synthetic playlists folder, and
+`PlaylistItemId` (a playlist *entry position* — `playlist_tracks.id` is an `integer` column).
+They use a reserved GUID space — 12 zero bytes, a non-zero kind tag, a 24-bit payload — so
+library `1` is `00000000000000000000000001000001`. The tag is never zero, because Jellyfin
+serializes the all-zero GUID as `null`.
 
-**Proper fix (upstream):** Finamp's `packIds()`/`_unpackIds()` (`lib/models/finamp_models.dart`)
-should handle ids that aren't 32-hex GUIDs — e.g. store variable-length ids when any id in the
-queue doesn't match the GUID shape. Jellyfin-compatible servers aren't guaranteed to use GUID ids,
-so this is worth a Finamp issue/PR; once a fixed release is widespread, this compatibility layer
-can be removed.
+`DecodeID` accepts dashed and uppercase GUIDs (Jellyfin's `Guid.Parse` does) and returns
+`ok=false` for anything malformed — including "" — which handlers surface as a 404.
+
+The wire format must stay GUID-shaped for this reason: Finamp's saved-queue persistence bit-packs
+each item id into exactly 16 bytes (`packIds()` in `lib/models/finamp_models.dart`), so a 32-hex
+GUID round-trips exactly, whereas a longer id would be silently truncated.
 
 ## Streaming and transcoding
 
@@ -242,7 +232,7 @@ plugin being loaded, like the Subsonic `sonicSimilarity` OpenSubsonic extension.
   loaded; otherwise `{"path": [{author, item_id, title, tempo?}], "total_distance": <float>}` (200), or 400
   with `start_song_id and end_song_id are required.` when either id is missing.
 
-`item_id`/`start_song_id`/`end_song_id` are the hex-encoded ids Navidrome hands Jellyfin clients.
+`item_id`/`start_song_id`/`end_song_id` are the GUID-form ids Navidrome hands Jellyfin clients.
 `tempo` comes from the track's BPM when known; the richer AudioMuse per-track features
 (`energy`, `key`, `mood_vector`, `scale`, `other_features`) are not provided. In multi-library
 setups, `find_path`'s `path` and `total_distance` only reflect hops through tracks in libraries
diff --git a/server/jellyfin/annotations.go b/server/jellyfin/annotations.go
index f2c2f546e..ec84f65e0 100644
--- a/server/jellyfin/annotations.go
+++ b/server/jellyfin/annotations.go
@@ -5,7 +5,6 @@ import (
 	"math"
 	"net/http"
 
-	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/events"
@@ -49,7 +48,10 @@ func (api *Router) resolveAnnotated(w http.ResponseWriter, r *http.Request, id s
 // fetches this per item to render played/favourite indicators; resolveItemByID enforces the
 // library-access gate.
 func (api *Router) getUserItemData(w http.ResponseWriter, r *http.Request) {
-	id := api.resolveItemID(r.Context(), dto.DecodeID(chi.URLParam(r, "itemId")))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	item, ok := api.resolveItemByID(r.Context(), id, nil)
 	if !ok {
 		http.Error(w, "Not Found", http.StatusNotFound)
@@ -64,7 +66,10 @@ func (api *Router) getUserItemData(w http.ResponseWriter, r *http.Request) {
 }
 
 func (api *Router) setFavorite(w http.ResponseWriter, r *http.Request, starred bool) {
-	id := api.resolveItemID(r.Context(), dto.DecodeID(chi.URLParam(r, "itemId")))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	repo, resource := api.resolveAnnotated(w, r, id)
 	if repo == nil {
 		return
@@ -84,7 +89,10 @@ func (api *Router) unmarkFavorite(w http.ResponseWriter, r *http.Request) {
 }
 
 func (api *Router) setItemRating(w http.ResponseWriter, r *http.Request, rating int) {
-	id := api.resolveItemID(r.Context(), dto.DecodeID(chi.URLParam(r, "itemId")))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	repo, resource := api.resolveAnnotated(w, r, id)
 	if repo == nil {
 		return
diff --git a/server/jellyfin/annotations_test.go b/server/jellyfin/annotations_test.go
index 9e811a379..dd1487011 100644
--- a/server/jellyfin/annotations_test.go
+++ b/server/jellyfin/annotations_test.go
@@ -21,7 +21,7 @@ var _ = Describe("Annotations", func() {
 	var broker *fakeEventBroker
 	// alice has access to library 1 only.
 	ctxUser := func() context.Context {
-		return request.WithUser(context.Background(), model.User{ID: "u1", UserName: "alice", Libraries: model.Libraries{{ID: 1, Name: "Music"}}})
+		return request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: model.Libraries{{ID: 1, Name: "Music"}}})
 	}
 
 	BeforeEach(func() {
@@ -33,98 +33,98 @@ var _ = Describe("Annotations", func() {
 	Describe("markFavorite / unmarkFavorite", func() {
 		It("stars a song and returns IsFavorite=true", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/s1", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var d dto.UserItemDataDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &d)).To(Succeed())
 			Expect(d.IsFavorite).To(BeTrue())
-			Expect(mfRepo.Data["s1"].Starred).To(BeTrue())
+			Expect(mfRepo.Data[testID("s1")].Starred).To(BeTrue())
 		})
 
 		It("stars an album and returns IsFavorite=true", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID("a1"), nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var d dto.UserItemDataDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &d)).To(Succeed())
 			Expect(d.IsFavorite).To(BeTrue())
-			Expect(albumRepo.Data["a1"].Starred).To(BeTrue())
+			Expect(albumRepo.Data[testID("a1")].Starred).To(BeTrue())
 		})
 
 		It("stars an artist without checking library access (artists span multiple libraries)", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			// alice only has access to library 1, but artists aren't gated per-library.
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/ar1", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "ar1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("ar1")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var d dto.UserItemDataDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &d)).To(Succeed())
 			Expect(d.IsFavorite).To(BeTrue())
-			Expect(artistRepo.Data["ar1"].Starred).To(BeTrue())
+			Expect(artistRepo.Data[testID("ar1")].Starred).To(BeTrue())
 		})
 
 		It("stars a visible playlist", func() {
 			playlistRepo := ds.Playlist(context.Background()).(*tests.MockPlaylistRepo)
-			playlistRepo.SetData(model.Playlists{{ID: "p1", Name: "Mix", OwnerID: "u1"}})
+			playlistRepo.SetData(model.Playlists{{ID: testID("p1"), Name: "Mix", OwnerID: testID("u1")}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID("p1"), nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("p1"))
+			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("p1")), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("p1")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(playlistRepo.Starred["p1"]).To(BeTrue())
+			Expect(playlistRepo.Starred[testID("p1")]).To(BeTrue())
 		})
 
 		It("unstars a song and returns IsFavorite=false", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1, Annotations: model.Annotations{Starred: true}}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1, Annotations: model.Annotations{Starred: true}}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("DELETE", "/Users/u1/FavoriteItems/s1", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.unmarkFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var d dto.UserItemDataDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &d)).To(Succeed())
 			Expect(d.IsFavorite).To(BeFalse())
-			Expect(mfRepo.Data["s1"].Starred).To(BeFalse())
+			Expect(mfRepo.Data[testID("s1")].Starred).To(BeFalse())
 		})
 
 		It("returns 404 and does not star an album in a library the user can't access", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 2}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID("a1"), nil).WithContext(ctxUser()) // only has access to library 1
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser()) // only has access to library 1
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
-			Expect(albumRepo.Data["a1"].Starred).To(BeFalse())
+			Expect(albumRepo.Data[testID("a1")].Starred).To(BeFalse())
 		})
 
 		It("returns 404 and does not star a song in a library the user can't access", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 2}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 2}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/s1", nil).WithContext(ctxUser()) // only has access to library 1
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
-			Expect(mfRepo.Data["s1"].Starred).To(BeFalse())
+			Expect(mfRepo.Data[testID("s1")].Starred).To(BeFalse())
 		})
 
 		It("returns 404 when the id doesn't match any entity", func() {
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/missing", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "missing")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("missing")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
@@ -133,39 +133,39 @@ var _ = Describe("Annotations", func() {
 			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetError(true)
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/x1", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "x1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("x1")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusInternalServerError))
 		})
 
 		It("emits a refreshResource event when starring a song", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/s1", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.markFavorite, w, r)
 			Expect(broker.Events).To(HaveLen(1))
-			Expect(broker.Events[0].Data(broker.Events[0])).To(Equal(`{"song":["s1"]}`))
+			Expect(broker.Events[0].Data(broker.Events[0])).To(Equal(`{"song":["` + testID("s1") + `"]}`))
 		})
 
 		It("emits a refreshResource event when starring an album", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID("a1"), nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.markFavorite, w, r)
 			Expect(broker.Events).To(HaveLen(1))
-			Expect(broker.Events[0].Data(broker.Events[0])).To(Equal(`{"album":["a1"]}`))
+			Expect(broker.Events[0].Data(broker.Events[0])).To(Equal(`{"album":["` + testID("a1") + `"]}`))
 		})
 
 		It("does not emit an event when the item is not accessible", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 2}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID("a1"), nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.markFavorite, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 			Expect(broker.Events).To(BeEmpty())
@@ -175,13 +175,13 @@ var _ = Describe("Annotations", func() {
 	Describe("setRating / removeRating", func() {
 		It("maps a Jellyfin 0-10 rating to Navidrome's 0-5 scale", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=8", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(mfRepo.Data["s1"].Rating).To(Equal(4))
+			Expect(mfRepo.Data[testID("s1")].Rating).To(Equal(4))
 			var d dto.UserItemDataDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &d)).To(Succeed())
 			Expect(d.Rating).NotTo(BeNil())
@@ -190,35 +190,35 @@ var _ = Describe("Annotations", func() {
 
 		It("rates an album", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID("a1")+"/Rating?Rating=10", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID(testID("a1"))+"/Rating?Rating=10", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(albumRepo.Data["a1"].Rating).To(Equal(5))
+			Expect(albumRepo.Data[testID("a1")].Rating).To(Equal(5))
 		})
 
 		It("rates a visible playlist", func() {
 			playlistRepo := ds.Playlist(context.Background()).(*tests.MockPlaylistRepo)
-			playlistRepo.SetData(model.Playlists{{ID: "p1", Name: "Mix", OwnerID: "u1"}})
+			playlistRepo.SetData(model.Playlists{{ID: testID("p1"), Name: "Mix", OwnerID: testID("u1")}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID("p1")+"/Rating?Rating=8", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("p1"))
+			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID(testID("p1"))+"/Rating?Rating=8", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("p1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(playlistRepo.Ratings["p1"]).To(Equal(4))
+			Expect(playlistRepo.Ratings[testID("p1")]).To(Equal(4))
 		})
 
 		It("removes a rating", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1, Annotations: model.Annotations{Rating: 4}}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1, Annotations: model.Annotations{Rating: 4}}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("DELETE", "/Users/u1/Items/s1/Rating", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.removeRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(mfRepo.Data["s1"].Rating).To(Equal(0))
+			Expect(mfRepo.Data[testID("s1")].Rating).To(Equal(0))
 			var d dto.UserItemDataDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &d)).To(Succeed())
 			Expect(d.Rating).To(BeNil())
@@ -226,79 +226,79 @@ var _ = Describe("Annotations", func() {
 
 		It("returns 404 and does not rate an album in a library the user can't access", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 2}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID("a1")+"/Rating?Rating=10", nil).WithContext(ctxUser()) // only has access to library 1
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID(testID("a1"))+"/Rating?Rating=10", nil).WithContext(ctxUser()) // only has access to library 1
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
-			Expect(albumRepo.Data["a1"].Rating).To(Equal(0))
+			Expect(albumRepo.Data[testID("a1")].Rating).To(Equal(0))
 		})
 
 		It("rounds an odd rating to the nearest star instead of truncating", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=9", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(mfRepo.Data["s1"].Rating).To(Equal(5))
+			Expect(mfRepo.Data[testID("s1")].Rating).To(Equal(5))
 		})
 
 		It("stores the minimum star for Rating=1 instead of clearing the rating", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1, Annotations: model.Annotations{Rating: 4}}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1, Annotations: model.Annotations{Rating: 4}}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=1", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(mfRepo.Data["s1"].Rating).To(Equal(1))
+			Expect(mfRepo.Data[testID("s1")].Rating).To(Equal(1))
 		})
 
 		It("accepts a fractional rating (UserItemDataDto.Rating is a double)", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=7.5", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(mfRepo.Data["s1"].Rating).To(Equal(4))
+			Expect(mfRepo.Data[testID("s1")].Rating).To(Equal(4))
 		})
 
 		It("clamps a Rating above 10 to Navidrome's max (5)", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=100", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(mfRepo.Data["s1"].Rating).To(Equal(5))
+			Expect(mfRepo.Data[testID("s1")].Rating).To(Equal(5))
 		})
 
 		It("clamps a negative Rating to Navidrome's min (0)", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=-5", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.setRating, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(mfRepo.Data["s1"].Rating).To(Equal(0))
+			Expect(mfRepo.Data[testID("s1")].Rating).To(Equal(0))
 		})
 
 		It("emits a refreshResource event when rating a song", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=8", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.setRating, w, r)
 			Expect(broker.Events).To(HaveLen(1))
-			Expect(broker.Events[0].Data(broker.Events[0])).To(Equal(`{"song":["s1"]}`))
+			Expect(broker.Events[0].Data(broker.Events[0])).To(Equal(`{"song":["` + testID("s1") + `"]}`))
 		})
 	})
 })
diff --git a/server/jellyfin/api_test.go b/server/jellyfin/api_test.go
index e8e9cbd4b..fe69c8321 100644
--- a/server/jellyfin/api_test.go
+++ b/server/jellyfin/api_test.go
@@ -48,8 +48,8 @@ var _ = Describe("Router", func() {
 		ds := &tests.MockDataStore{}
 		auth.Init(ds)
 		ur := ds.User(GinkgoT().Context()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: "u1", UserName: "alice", NewPassword: "secret"})).To(Succeed())
-		token, err := auth.CreateToken(&model.User{ID: "u1", UserName: "alice"})
+		Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
+		token, err := auth.CreateToken(&model.User{ID: testID("u1"), UserName: "alice"})
 		Expect(err).ToNot(HaveOccurred())
 
 		fp := &fakePlayers{}
diff --git a/server/jellyfin/audiomuse.go b/server/jellyfin/audiomuse.go
index b01a4bf92..4cc1a2cc5 100644
--- a/server/jellyfin/audiomuse.go
+++ b/server/jellyfin/audiomuse.go
@@ -62,12 +62,13 @@ func (api *Router) audioMuseSimilarTracks(w http.ResponseWriter, r *http.Request
 	tracks := []audioMuseSimilarTrack{}
 
 	itemID := p.StringOr("item_id", "")
-	if itemID == "" {
+	id, ok := dto.DecodeID(itemID)
+	if !ok {
+		// Every other failure here (no provider, no match) degrades to an empty list rather than an
+		// error, so a malformed id does too instead of being the one path that 404s.
 		api.ok(w, r, tracks)
 		return
 	}
-
-	id := api.resolveItemID(ctx, dto.DecodeID(itemID))
 	n := min(p.IntOr("n", 10), maxSimilarLimit) // cap a user-controlled count, like clampLimit
 	eliminateDuplicates := p.BoolOr("eliminate_duplicates", true)
 
@@ -129,11 +130,16 @@ func (api *Router) audioMuseFindPath(w http.ResponseWriter, r *http.Request) {
 	}
 
 	resp := audioMusePathResponse{Path: []audioMusePathTrack{}}
+	startDecoded, startOk := dto.DecodeID(startID)
+	endDecoded, endOk := dto.DecodeID(endID)
+	if !startOk || !endOk {
+		// This endpoint already 400s when an endpoint id is absent, so an unusable one reports the
+		// same way rather than looking like a successful search that found no path.
+		http.Error(w, "start_song_id and end_song_id must be valid item ids.", http.StatusBadRequest)
+		return
+	}
 	maxSteps := min(p.IntOr("max_steps", 25), maxSimilarLimit) // cap a user-controlled count
-	matches, err := api.sonic.FindSonicPath(ctx,
-		api.resolveItemID(ctx, dto.DecodeID(startID)),
-		api.resolveItemID(ctx, dto.DecodeID(endID)),
-		maxSteps)
+	matches, err := api.sonic.FindSonicPath(ctx, startDecoded, endDecoded, maxSteps)
 	if err != nil {
 		api.ok(w, r, resp)
 		return
diff --git a/server/jellyfin/audiomuse_test.go b/server/jellyfin/audiomuse_test.go
index e9d6d4e85..6815753fd 100644
--- a/server/jellyfin/audiomuse_test.go
+++ b/server/jellyfin/audiomuse_test.go
@@ -118,28 +118,28 @@ var _ = Describe("AudioMuse similar_tracks", func() {
 
 	It("maps matches, decodes the seed id, encodes item ids, copies distance", func() {
 		fake.similar = []sonic.SimilarMatch{
-			{MediaFile: mf("mf1", "A", "T1", 1), Similarity: 0.3},
-			{MediaFile: mf("mf2", "B", "T2", 1), Similarity: 0.5},
+			{MediaFile: mf(testID("mf1"), "A", "T1", 1), Similarity: 0.3},
+			{MediaFile: mf(testID("mf2"), "B", "T2", 1), Similarity: 0.5},
 		}
-		w := call("item_id="+dto.EncodeID("seed")+"&n=5", model.User{IsAdmin: true})
+		w := call("item_id="+dto.EncodeID(testID("seed"))+"&n=5", model.User{IsAdmin: true})
 
 		Expect(w.Code).To(Equal(200))
-		Expect(fake.gotID).To(Equal("seed"))
+		Expect(fake.gotID).To(Equal(testID("seed")))
 		Expect(fake.gotCount).To(Equal(5))
 		var body []audioMuseSimilarTrack
 		Expect(json.Unmarshal(w.Body.Bytes(), &body)).To(Succeed())
 		Expect(body).To(HaveLen(2))
 		Expect(body[0]).To(Equal(audioMuseSimilarTrack{
-			Author: "A", Distance: 0.3, ItemID: dto.EncodeID("mf1"), Title: "T1",
+			Author: "A", Distance: 0.3, ItemID: dto.EncodeID(testID("mf1")), Title: "T1",
 		}))
 	})
 
 	It("collapses to one track per artist when eliminate_duplicates defaults on", func() {
 		fake.similar = []sonic.SimilarMatch{
-			{MediaFile: mf("mf1", "A", "T1", 1), Similarity: 0.3},
-			{MediaFile: mf("mf2", "A", "T2", 1), Similarity: 0.5},
+			{MediaFile: mf(testID("mf1"), "A", "T1", 1), Similarity: 0.3},
+			{MediaFile: mf(testID("mf2"), "A", "T2", 1), Similarity: 0.5},
 		}
-		w := call("item_id="+dto.EncodeID("seed"), model.User{IsAdmin: true})
+		w := call("item_id="+dto.EncodeID(testID("seed")), model.User{IsAdmin: true})
 		var body []audioMuseSimilarTrack
 		Expect(json.Unmarshal(w.Body.Bytes(), &body)).To(Succeed())
 		Expect(body).To(HaveLen(1))
@@ -147,18 +147,18 @@ var _ = Describe("AudioMuse similar_tracks", func() {
 
 	It("keeps same-artist tracks when eliminate_duplicates=false", func() {
 		fake.similar = []sonic.SimilarMatch{
-			{MediaFile: mf("mf1", "A", "T1", 1), Similarity: 0.3},
-			{MediaFile: mf("mf2", "A", "T2", 1), Similarity: 0.5},
+			{MediaFile: mf(testID("mf1"), "A", "T1", 1), Similarity: 0.3},
+			{MediaFile: mf(testID("mf2"), "A", "T2", 1), Similarity: 0.5},
 		}
-		w := call("item_id="+dto.EncodeID("seed")+"&eliminate_duplicates=false", model.User{IsAdmin: true})
+		w := call("item_id="+dto.EncodeID(testID("seed"))+"&eliminate_duplicates=false", model.User{IsAdmin: true})
 		var body []audioMuseSimilarTrack
 		Expect(json.Unmarshal(w.Body.Bytes(), &body)).To(Succeed())
 		Expect(body).To(HaveLen(2))
 	})
 
 	It("filters out tracks in libraries the user cannot access", func() {
-		fake.similar = []sonic.SimilarMatch{{MediaFile: mf("mf1", "A", "T1", 2), Similarity: 0.3}}
-		w := call("item_id="+dto.EncodeID("seed"), model.User{Libraries: model.Libraries{{ID: 1}}})
+		fake.similar = []sonic.SimilarMatch{{MediaFile: mf(testID("mf1"), "A", "T1", 2), Similarity: 0.3}}
+		w := call("item_id="+dto.EncodeID(testID("seed")), model.User{Libraries: model.Libraries{{ID: 1}}})
 		Expect(strings.TrimSpace(w.Body.String())).To(Equal("[]"))
 	})
 
@@ -169,16 +169,25 @@ var _ = Describe("AudioMuse similar_tracks", func() {
 		Expect(fake.gotID).To(Equal(""))
 	})
 
+	// A malformed item_id degrades the same way as a missing one (200, empty array) rather than
+	// 404ing: every other failure on this endpoint already degrades gracefully.
+	It("returns an empty array without calling the engine when item_id is malformed", func() {
+		w := call("item_id=not-a-valid-id", model.User{IsAdmin: true})
+		Expect(w.Code).To(Equal(200))
+		Expect(strings.TrimSpace(w.Body.String())).To(Equal("[]"))
+		Expect(fake.gotID).To(Equal(""))
+	})
+
 	It("returns 404 when no sonic provider is loaded", func() {
 		fake.provider = false
-		w := call("item_id="+dto.EncodeID("seed"), model.User{IsAdmin: true})
+		w := call("item_id="+dto.EncodeID(testID("seed")), model.User{IsAdmin: true})
 		Expect(w.Code).To(Equal(404))
 	})
 
 	It("returns an empty array when the engine errors", func() {
 		fake.similarErr = errors.New("boom")
-		fake.similar = []sonic.SimilarMatch{{MediaFile: mf("mf1", "A", "T1", 1), Similarity: 0.3}}
-		w := call("item_id="+dto.EncodeID("seed"), model.User{IsAdmin: true})
+		fake.similar = []sonic.SimilarMatch{{MediaFile: mf(testID("mf1"), "A", "T1", 1), Similarity: 0.3}}
+		w := call("item_id="+dto.EncodeID(testID("seed")), model.User{IsAdmin: true})
 		Expect(w.Code).To(Equal(200))
 		Expect(strings.TrimSpace(w.Body.String())).To(Equal("[]"))
 	})
@@ -198,53 +207,60 @@ var _ = Describe("AudioMuse find_path", func() {
 	})
 
 	It("returns 400 with the exact message when start_song_id is missing", func() {
-		w := call("end_song_id="+dto.EncodeID("e"), model.User{IsAdmin: true})
+		w := call("end_song_id="+dto.EncodeID(testID("e")), model.User{IsAdmin: true})
 		Expect(w.Code).To(Equal(400))
 		Expect(strings.TrimSpace(w.Body.String())).To(Equal("start_song_id and end_song_id are required."))
 	})
 
 	It("returns 400 when end_song_id is missing", func() {
-		w := call("start_song_id="+dto.EncodeID("s"), model.User{IsAdmin: true})
+		w := call("start_song_id="+dto.EncodeID(testID("s")), model.User{IsAdmin: true})
 		Expect(w.Code).To(Equal(400))
 	})
 
 	It("maps the path, decodes ids, sums total_distance, fills tempo from BPM", func() {
 		bpm := 120
-		withBPM := mf("mf1", "A", "T1", 1)
+		withBPM := mf(testID("mf1"), "A", "T1", 1)
 		withBPM.BPM = &bpm
 		fake.path = []sonic.SimilarMatch{
 			{MediaFile: withBPM, Similarity: 1.5},
-			{MediaFile: mf("mf2", "B", "T2", 1), Similarity: 2.0},
+			{MediaFile: mf(testID("mf2"), "B", "T2", 1), Similarity: 2.0},
 		}
-		w := call("start_song_id="+dto.EncodeID("s")+"&end_song_id="+dto.EncodeID("e")+"&max_steps=10", model.User{IsAdmin: true})
+		w := call("start_song_id="+dto.EncodeID(testID("s"))+"&end_song_id="+dto.EncodeID(testID("e"))+"&max_steps=10", model.User{IsAdmin: true})
 
 		Expect(w.Code).To(Equal(200))
-		Expect(fake.gotStart).To(Equal("s"))
-		Expect(fake.gotEnd).To(Equal("e"))
+		Expect(fake.gotStart).To(Equal(testID("s")))
+		Expect(fake.gotEnd).To(Equal(testID("e")))
 		Expect(fake.gotCount).To(Equal(10))
 		var body audioMusePathResponse
 		Expect(json.Unmarshal(w.Body.Bytes(), &body)).To(Succeed())
 		Expect(body.Path).To(HaveLen(2))
 		Expect(body.TotalDistance).To(Equal(3.5))
-		Expect(body.Path[0].ItemID).To(Equal(dto.EncodeID("mf1")))
+		Expect(body.Path[0].ItemID).To(Equal(dto.EncodeID(testID("mf1"))))
 		Expect(*body.Path[0].Tempo).To(Equal(120.0))
 		Expect(body.Path[1].Tempo).To(BeNil())
 	})
 
 	It("returns 404 when no sonic provider is loaded", func() {
 		fake.provider = false
-		w := call("start_song_id="+dto.EncodeID("s")+"&end_song_id="+dto.EncodeID("e"), model.User{IsAdmin: true})
+		w := call("start_song_id="+dto.EncodeID(testID("s"))+"&end_song_id="+dto.EncodeID(testID("e")), model.User{IsAdmin: true})
 		Expect(w.Code).To(Equal(404))
 	})
 
 	It("returns an empty path object when the engine errors", func() {
 		fake.pathErr = errors.New("boom")
-		fake.path = []sonic.SimilarMatch{{MediaFile: mf("mf1", "A", "T1", 1), Similarity: 1.0}}
-		w := call("start_song_id="+dto.EncodeID("s")+"&end_song_id="+dto.EncodeID("e"), model.User{IsAdmin: true})
+		fake.path = []sonic.SimilarMatch{{MediaFile: mf(testID("mf1"), "A", "T1", 1), Similarity: 1.0}}
+		w := call("start_song_id="+dto.EncodeID(testID("s"))+"&end_song_id="+dto.EncodeID(testID("e")), model.User{IsAdmin: true})
 		Expect(w.Code).To(Equal(200))
 		var body audioMusePathResponse
 		Expect(json.Unmarshal(w.Body.Bytes(), &body)).To(Succeed())
 		Expect(body.Path).To(BeEmpty())
 		Expect(body.TotalDistance).To(Equal(0.0))
 	})
+
+	It("400s without calling the engine when an id is malformed", func() {
+		w := call("start_song_id=not-a-valid-id&end_song_id="+dto.EncodeID(testID("e")), model.User{IsAdmin: true})
+		Expect(w.Code).To(Equal(http.StatusBadRequest))
+		Expect(fake.gotStart).To(Equal(""))
+		Expect(fake.gotEnd).To(Equal(""))
+	})
 })
diff --git a/server/jellyfin/auth_test.go b/server/jellyfin/auth_test.go
index b51420f1a..5a613f828 100644
--- a/server/jellyfin/auth_test.go
+++ b/server/jellyfin/auth_test.go
@@ -22,7 +22,7 @@ var _ = Describe("AuthenticateByName", func() {
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
 		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: "u1", UserName: "alice", NewPassword: "secret"})).To(Succeed())
+		Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
 		api = &Router{ds: ds}
 	})
 
@@ -68,7 +68,7 @@ var _ = Describe("AuthenticateByName", func() {
 
 	It("reflects an administrator in the User.Policy", func() {
 		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: "admin1", UserName: "root", NewPassword: "secret", IsAdmin: true})).To(Succeed())
+		Expect(ur.Put(&model.User{ID: testID("admin1"), UserName: "root", NewPassword: "secret", IsAdmin: true})).To(Succeed())
 
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("POST", "/Users/AuthenticateByName",
@@ -92,7 +92,7 @@ var _ = Describe("AuthenticateByName", func() {
 
 	It("rejects an empty password even for a user with an empty stored password with 401", func() {
 		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: "e", UserName: "empty", NewPassword: ""})).To(Succeed())
+		Expect(ur.Put(&model.User{ID: testID("e"), UserName: "empty", NewPassword: ""})).To(Succeed())
 
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("POST", "/Users/AuthenticateByName",
diff --git a/server/jellyfin/browsing.go b/server/jellyfin/browsing.go
index faf43d352..9acd8d5a8 100644
--- a/server/jellyfin/browsing.go
+++ b/server/jellyfin/browsing.go
@@ -28,12 +28,21 @@ func (api *Router) listArtistsByRole(w http.ResponseWriter, r *http.Request, rol
 	opts := model.QueryOptions{Offset: p.IntOr("startindex", 0), Max: p.IntOr("limit", 0)}
 	applySort(&opts, "MusicArtist", p.StringOr("sortby", ""), p.StringOr("sortorder", ""))
 
-	scopeIDs, _ := parentIDScope(ctx, r)
+	scopeIDs, _, ok := parentIDScope(ctx, r)
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
+	genreIds, ok := decodedQueryIDs(r, "genreids")
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
 	// Only the fields listArtists reads; /Artists has no favorites filter, so favOnly stays false.
 	// Finamp's artist tab sends GenreIds when a genre filter is active.
 	q := itemsQuery{
 		scopeIDs: scopeIDs,
-		genreIds: decodedQueryIDs(r, "genreids"),
+		genreIds: genreIds,
 		search:   searchTerm(p),
 		fields:   dto.ParseFields(p.Strings("fields")...),
 	}
@@ -67,7 +76,11 @@ func (api *Router) getGenres(w http.ResponseWriter, r *http.Request) {
 func (api *Router) getStudios(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	p := req.Params(r)
-	scope, _ := parentIDScope(ctx, r)
+	scope, _, ok := parentIDScope(ctx, r)
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
 	opts := model.QueryOptions{Sort: "tag_value", Filters: libraryScopeFilter(scope)}
 	labels, err := api.ds.Tag(ctx).GetAll(model.TagRecordLabel, opts)
 	if err != nil {
@@ -83,7 +96,11 @@ func (api *Router) getStudios(w http.ResponseWriter, r *http.Request) {
 // library when accessible. Tags/OfficialRatings have no music source, so they are always empty.
 func (api *Router) getQueryFiltersLegacy(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	scope, _ := parentIDScope(ctx, r)
+	scope, _, ok := parentIDScope(ctx, r)
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
 	genreOpts := model.QueryOptions{Sort: "name", Filters: libraryScopeFilter(scope)}
 	genres, err := api.ds.Genre(ctx).GetAll(genreOpts)
 	if err != nil {
diff --git a/server/jellyfin/browsing_test.go b/server/jellyfin/browsing_test.go
index e346b56cb..2825c03e8 100644
--- a/server/jellyfin/browsing_test.go
+++ b/server/jellyfin/browsing_test.go
@@ -18,12 +18,12 @@ var _ = Describe("Browsing", func() {
 	var api *Router
 	var ds *tests.MockDataStore
 	ctxUser := func(libs model.Libraries) context.Context {
-		return request.WithUser(context.Background(), model.User{ID: "u1", UserName: "alice", Libraries: libs})
+		return request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: libs})
 	}
 
 	// admin has no explicit Libraries; access is granted via the IsAdmin bypass, not membership.
 	ctxAdmin := func() context.Context {
-		return request.WithUser(context.Background(), model.User{ID: "admin", IsAdmin: true, Libraries: nil})
+		return request.WithUser(context.Background(), model.User{ID: testID("admin"), IsAdmin: true, Libraries: nil})
 	}
 
 	BeforeEach(func() {
@@ -33,7 +33,7 @@ var _ = Describe("Browsing", func() {
 
 	Describe("getArtists", func() {
 		It("lists artists via /Artists", func() {
-			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: "ar1", Name: "A"}})
+			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "A"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
 			invoke(api.getArtists, w, r)
@@ -45,7 +45,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("handles /Artists/AlbumArtists the same way", func() {
-			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: "ar1", Name: "A"}})
+			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "A"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists/AlbumArtists", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
 			invoke(api.getArtists, w, r)
@@ -57,7 +57,7 @@ var _ = Describe("Browsing", func() {
 
 		It("scopes results to the user's accessible libraries", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1}, {ID: 2}}
 			r := httptest.NewRequest("GET", "/Artists", nil).WithContext(ctxUser(libs))
@@ -71,10 +71,10 @@ var _ = Describe("Browsing", func() {
 
 		It("scopes to a single library when ParentId is an accessible library id", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1}, {ID: 2}}
-			r := httptest.NewRequest("GET", "/Artists?ParentId=2", nil).WithContext(ctxUser(libs))
+			r := httptest.NewRequest("GET", "/Artists?ParentId="+dto.EncodeLibraryID(2), nil).WithContext(ctxUser(libs))
 			invoke(api.getArtists, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			sql, args, err := artistRepo.Options.Filters.ToSql()
@@ -86,10 +86,10 @@ var _ = Describe("Browsing", func() {
 
 		It("does not let ParentId=<inaccessible library id> narrow the scope", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1}} // no access to library 99
-			r := httptest.NewRequest("GET", "/Artists?ParentId=99", nil).WithContext(ctxUser(libs))
+			r := httptest.NewRequest("GET", "/Artists?ParentId="+dto.EncodeLibraryID(99), nil).WithContext(ctxUser(libs))
 			invoke(api.getArtists, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			sql, args, err := artistRepo.Options.Filters.ToSql()
@@ -101,7 +101,7 @@ var _ = Describe("Browsing", func() {
 
 		It("forwards SearchTerm to the repo's Search method", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists?SearchTerm=art", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
 			invoke(api.getArtists, w, r)
@@ -113,7 +113,7 @@ var _ = Describe("Browsing", func() {
 
 		It("bounds a search the client left unbounded, and clamps an oversized one", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists?SearchTerm=art", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
@@ -130,7 +130,7 @@ var _ = Describe("Browsing", func() {
 
 		It("forwards StartIndex/Limit as Offset/Max", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists?StartIndex=5&Limit=10", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
 			invoke(api.getArtists, w, r)
@@ -141,7 +141,7 @@ var _ = Describe("Browsing", func() {
 
 		It("does not restrict results for an admin user", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists", nil).WithContext(ctxAdmin())
 			invoke(api.getArtists, w, r)
@@ -155,6 +155,15 @@ var _ = Describe("Browsing", func() {
 			Expect(err).NotTo(HaveOccurred())
 			Expect(sql).NotTo(ContainSubstring("library_artist.library_id"))
 		})
+
+		It("404s a malformed ParentId instead of listing every library's artists", func() {
+			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/Artists?ParentId=not-a-valid-id", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
+			invoke(api.getArtists, w, r)
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
 	})
 
 	Describe("getGenres", func() {
@@ -199,6 +208,13 @@ var _ = Describe("Browsing", func() {
 			Expect(w.Code).To(Equal(http.StatusOK))
 			Expect(tagRepo.Options.Filters).To(BeNil())
 		})
+
+		It("404s a malformed ParentId instead of listing every library's studios", func() {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/Studios?ParentId=not-a-valid-id", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
+			invoke(api.getStudios, w, r)
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
 	})
 
 	Describe("getQueryFiltersLegacy", func() {
@@ -222,5 +238,12 @@ var _ = Describe("Browsing", func() {
 			Expect(w.Code).To(Equal(http.StatusOK))
 			Expect(genreRepo.Options.Filters).To(BeNil())
 		})
+
+		It("404s a malformed ParentId instead of listing every library's filters", func() {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/Items/Filters?ParentId=not-a-valid-id", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
+			invoke(api.getQueryFiltersLegacy, w, r)
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
 	})
 })
diff --git a/server/jellyfin/dto/dto_suite_test.go b/server/jellyfin/dto/dto_suite_test.go
index 1d8ec47e4..a4eebb0d3 100644
--- a/server/jellyfin/dto/dto_suite_test.go
+++ b/server/jellyfin/dto/dto_suite_test.go
@@ -4,6 +4,7 @@ import (
 	"testing"
 
 	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -15,3 +16,7 @@ func TestDto(t *testing.T) {
 	RegisterFailHandler(Fail)
 	RunSpecs(t, "Jellyfin DTO Suite")
 }
+
+// testID maps a readable label to a deterministic canonical id, so fixtures exercise the same
+// id shape production uses.
+func testID(label string) string { return id.NewHash("jellyfin-test", label) }
diff --git a/server/jellyfin/dto/ids.go b/server/jellyfin/dto/ids.go
index 2ac7e2a79..2c8b5317b 100644
--- a/server/jellyfin/dto/ids.go
+++ b/server/jellyfin/dto/ids.go
@@ -1,23 +1,143 @@
 package dto
 
-import "encoding/hex"
+import (
+	"bytes"
+	"encoding/hex"
+	"strconv"
+	"strings"
 
-// EncodeID renders a Navidrome id as lowercase hex; Jellyfin clients parse ids as radix-16 (e.g.
-// Finamp's queue packing) and crash on Navidrome's base62 ids if emitted as-is.
-func EncodeID(id string) string {
-	if id == "" {
+	"github.com/navidrome/navidrome/model/id"
+)
+
+// guidLen is the length of a Jellyfin GUID on the wire: 16 bytes as lowercase hex, no dashes
+// (what Guid.ToString("N") produces).
+const guidLen = 32
+
+// Reserved GUIDs stand in for ids that aren't 128-bit values: 12 zero bytes, a non-zero kind tag,
+// then a 24-bit payload. The tag is never zero because Jellyfin serializes the all-zero GUID as null.
+const (
+	kindIdx    = 12
+	maxPayload = 1<<24 - 1
+)
+
+const (
+	kindLibrary byte = iota + 1
+	kindPlaylistsFolder
+	kindPlaylistEntry
+)
+
+var zeroPrefix [kindIdx]byte
+
+// PlaylistsFolderID is the internal id of the synthetic "playlists library" folder. It can't be
+// mistaken for a real id, which is always 22-char base62.
+const PlaylistsFolderID = "playlists"
+
+// PlaylistsFolderGUID is the wire form of PlaylistsFolderID.
+var PlaylistsFolderGUID = encodeReserved(kindPlaylistsFolder, 0)
+
+// EncodeID renders a canonical Navidrome id as a Jellyfin GUID. Anything that isn't one encodes
+// to "" rather than to a shape clients can't parse.
+func EncodeID(ndID string) string {
+	b, err := id.Decode(ndID)
+	if err != nil {
 		return ""
 	}
-	return hex.EncodeToString([]byte(id))
+	return hex.EncodeToString(b)
 }
 
-// DecodeID reverses EncodeID; non-hex input is returned unchanged, so it's safe on any inbound id.
-func DecodeID(id string) string {
-	if id == "" {
+// EncodeLibraryID renders a library's integer id in the reserved GUID space.
+func EncodeLibraryID(libID int) string {
+	return encodeReserved(kindLibrary, libID)
+}
+
+// EncodePlaylistEntryID renders a playlist entry's position (model.PlaylistTrack.ID, an integer
+// column) in the reserved GUID space. Clients echo it back to remove one occurrence of a song.
+func EncodePlaylistEntryID(entryID string) string {
+	n, err := strconv.Atoi(entryID)
+	if err != nil {
 		return ""
 	}
-	if b, err := hex.DecodeString(id); err == nil && len(b) > 0 {
-		return string(b)
-	}
-	return id
+	return encodeReserved(kindPlaylistEntry, n)
+}
+
+func encodeReserved(kind byte, payload int) string {
+	if payload < 0 || payload > maxPayload {
+		return ""
+	}
+	var b [16]byte
+	b[kindIdx] = kind
+	b[13], b[14], b[15] = byte(payload>>16), byte(payload>>8), byte(payload)
+	return hex.EncodeToString(b[:])
+}
+
+// DecodeID maps an inbound GUID back to the identifier the rest of the API uses: a canonical id,
+// a decimal library id, or PlaylistsFolderID. ok is false for anything that isn't a well-formed
+// GUID — including the empty string — so an undecodable id can't reach a caller as "no filter".
+// Dashed and uppercase forms are accepted, as Jellyfin's Guid.Parse accepts them. Playlist entries
+// decode through DecodePlaylistEntryID instead, so a position can't reach a caller expecting an
+// entity id.
+func DecodeID(guid string) (string, bool) {
+	b, ok := decodeGUID(guid)
+	if !ok {
+		return "", false
+	}
+	kind, payload, reserved := reservedFields(b)
+	if !reserved {
+		return id.Encode(b), true
+	}
+	switch kind {
+	case kindLibrary:
+		return strconv.Itoa(payload), true
+	case kindPlaylistsFolder:
+		return PlaylistsFolderID, true
+	}
+	return "", false
+}
+
+// DecodeIDs decodes a list of GUIDs, all-or-nothing: ok is false if any entry is malformed, so a
+// caller can't mistake "every entry failed" for "no filter" (see DecodeID).
+func DecodeIDs(guids []string) ([]string, bool) {
+	out := make([]string, len(guids))
+	for i, guid := range guids {
+		decoded, ok := DecodeID(guid)
+		if !ok {
+			return nil, false
+		}
+		out[i] = decoded
+	}
+	return out, true
+}
+
+// DecodePlaylistEntryID decodes a playlist entry GUID to its position. It rejects every other kind,
+// so an entity id can't be taken for a playlist_tracks row.
+func DecodePlaylistEntryID(guid string) (string, bool) {
+	b, ok := decodeGUID(guid)
+	if !ok {
+		return "", false
+	}
+	if kind, payload, reserved := reservedFields(b); reserved && kind == kindPlaylistEntry {
+		return strconv.Itoa(payload), true
+	}
+	return "", false
+}
+
+func decodeGUID(guid string) ([16]byte, bool) {
+	guid = strings.ToLower(strings.ReplaceAll(guid, "-", ""))
+	if len(guid) != guidLen {
+		return [16]byte{}, false
+	}
+	bs, err := hex.DecodeString(guid)
+	if err != nil {
+		return [16]byte{}, false
+	}
+	return [16]byte(bs), true
+}
+
+// reservedFields reports the kind tag and payload of a reserved GUID; reserved is false for the
+// entity GUIDs that make up almost all traffic.
+func reservedFields(b [16]byte) (kind byte, payload int, reserved bool) {
+	if !bytes.Equal(b[:kindIdx], zeroPrefix[:]) {
+		return 0, 0, false
+	}
+	return b[kindIdx], int(b[13])<<16 | int(b[14])<<8 | int(b[15]), true
 }
diff --git a/server/jellyfin/dto/ids_test.go b/server/jellyfin/dto/ids_test.go
index d85786d99..c95dbd790 100644
--- a/server/jellyfin/dto/ids_test.go
+++ b/server/jellyfin/dto/ids_test.go
@@ -1,35 +1,161 @@
 package dto
 
 import (
+	"encoding/hex"
+	"strconv"
+	"strings"
+
+	"github.com/navidrome/navidrome/model/id"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
 var _ = Describe("id codec", func() {
-	It("round-trips a base62 id", func() {
-		id := "5QFKvMsJrd57QE2Le2dKKo"
-		Expect(DecodeID(EncodeID(id))).To(Equal(id))
+	Describe("canonical ids", func() {
+		It("round-trips a random id", func() {
+			ndID := id.NewRandom()
+			decoded, ok := DecodeID(EncodeID(ndID))
+			Expect(ok).To(BeTrue())
+			Expect(decoded).To(Equal(ndID))
+		})
+
+		It("round-trips a hash id", func() {
+			ndID := id.NewHash("artist", "Weird Al")
+			decoded, ok := DecodeID(EncodeID(ndID))
+			Expect(ok).To(BeTrue())
+			Expect(decoded).To(Equal(ndID))
+		})
+
+		It("emits exactly 32 lowercase hex chars", func() {
+			for range 20 {
+				Expect(EncodeID(id.NewRandom())).To(MatchRegexp("^[0-9a-f]{32}$"))
+			}
+		})
+
+		It("accepts a dashed GUID, matching Jellyfin's Guid.Parse", func() {
+			ndID := id.NewRandom()
+			guid := EncodeID(ndID)
+			dashed := guid[0:8] + "-" + guid[8:12] + "-" + guid[12:16] + "-" + guid[16:20] + "-" + guid[20:32]
+			decoded, ok := DecodeID(dashed)
+			Expect(ok).To(BeTrue())
+			Expect(decoded).To(Equal(ndID))
+		})
+
+		It("accepts an uppercase GUID", func() {
+			ndID := id.NewRandom()
+			decoded, ok := DecodeID(strings.ToUpper(EncodeID(ndID)))
+			Expect(ok).To(BeTrue())
+			Expect(decoded).To(Equal(ndID))
+		})
 	})
 
-	It("passes a raw (non-hex) id through DecodeID unchanged", func() {
-		Expect(DecodeID("5QFKvMsJrd57QE2Le2dKKo")).To(Equal("5QFKvMsJrd57QE2Le2dKKo"))
+	Describe("reserved space", func() {
+		DescribeTable("round-trips library ids",
+			func(libID int, guid string) {
+				Expect(EncodeLibraryID(libID)).To(Equal(guid))
+				decoded, ok := DecodeID(guid)
+				Expect(ok).To(BeTrue())
+				Expect(decoded).To(Equal(strconv.Itoa(libID)))
+			},
+			Entry("first library", 1, "00000000000000000000000001000001"),
+			Entry("double digit", 42, "0000000000000000000000000100002a"),
+			Entry("max payload", 0xffffff, "00000000000000000000000001ffffff"),
+		)
+
+		It("round-trips the playlists folder", func() {
+			Expect(PlaylistsFolderGUID).To(Equal("00000000000000000000000002000000"))
+			decoded, ok := DecodeID(PlaylistsFolderGUID)
+			Expect(ok).To(BeTrue())
+			Expect(decoded).To(Equal(PlaylistsFolderID))
+		})
+
+		DescribeTable("round-trips playlist entry positions",
+			func(entryID, guid string) {
+				Expect(EncodePlaylistEntryID(entryID)).To(Equal(guid))
+				decoded, ok := DecodePlaylistEntryID(guid)
+				Expect(ok).To(BeTrue())
+				Expect(decoded).To(Equal(entryID))
+			},
+			Entry("first entry", "1", "00000000000000000000000003000001"),
+			Entry("later entry", "300", "0000000000000000000000000300012c"),
+		)
+
+		It("rejects a non-integer playlist entry id", func() {
+			Expect(EncodePlaylistEntryID("s1")).To(Equal(""))
+			Expect(EncodePlaylistEntryID("")).To(Equal(""))
+			Expect(EncodePlaylistEntryID("-1")).To(Equal(""))
+		})
+
+		It("rejects a payload wider than the reserved 24 bits", func() {
+			Expect(EncodeLibraryID(1 << 24)).To(Equal(""))
+			Expect(EncodeLibraryID(-1)).To(Equal(""))
+			Expect(EncodePlaylistEntryID("16777216")).To(Equal(""))
+		})
+
+		It("keeps library and playlist-entry GUIDs distinct for the same number", func() {
+			Expect(EncodeLibraryID(3)).ToNot(Equal(EncodePlaylistEntryID("3")))
+		})
+
+		It("does not let one reserved kind decode as another", func() {
+			_, ok := DecodeID(EncodePlaylistEntryID("3"))
+			Expect(ok).To(BeFalse())
+			_, ok = DecodePlaylistEntryID(EncodeLibraryID(3))
+			Expect(ok).To(BeFalse())
+			_, ok = DecodePlaylistEntryID(PlaylistsFolderGUID)
+			Expect(ok).To(BeFalse())
+		})
+
+		It("rejects an unknown kind tag", func() {
+			_, ok := DecodeID("000000000000000000000000ff000000")
+			Expect(ok).To(BeFalse())
+		})
+
+		It("never emits the all-zero GUID, which Jellyfin serializes as null", func() {
+			Expect(EncodeLibraryID(0)).ToNot(Equal("00000000000000000000000000000000"))
+			Expect(PlaylistsFolderGUID).ToNot(Equal("00000000000000000000000000000000"))
+		})
 	})
 
-	It("produces valid lowercase hex", func() {
-		encoded := EncodeID("song-1")
-		Expect(encoded).To(MatchRegexp("^[0-9a-f]+$"))
-		Expect(encoded).To(HaveLen(len("song-1") * 2))
+	Describe("malformed input", func() {
+		DescribeTable("DecodeID reports ok=false",
+			func(input string) {
+				decoded, ok := DecodeID(input)
+				Expect(ok).To(BeFalse())
+				Expect(decoded).To(BeEmpty())
+			},
+			Entry("empty", ""),
+			Entry("too short", "abc123"),
+			Entry("too long", "000000000000000000000000010000011"),
+			Entry("non-hex chars", "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"),
+			Entry("a raw base62 id", id.NewRandom()),
+			Entry("the old 44-char hex format", hex.EncodeToString([]byte("5QFKvMsJrd57QE2Le2dKKo"))),
+		)
+
+		It("encodes a non-canonical id to the empty string", func() {
+			Expect(EncodeID("")).To(Equal(""))
+			Expect(EncodeID("playlists")).To(Equal(""))
+			Expect(EncodeID("42")).To(Equal(""))
+		})
 	})
 
-	It("round-trips the empty string", func() {
-		Expect(EncodeID("")).To(Equal(""))
-		Expect(DecodeID("")).To(Equal(""))
-	})
+	Describe("DecodeIDs", func() {
+		It("decodes every entry when all are well-formed", func() {
+			a, b := id.NewRandom(), id.NewRandom()
+			decoded, ok := DecodeIDs([]string{EncodeID(a), EncodeID(b)})
+			Expect(ok).To(BeTrue())
+			Expect(decoded).To(Equal([]string{a, b}))
+		})
 
-	It("decodes a hex-looking raw id incorrectly only when re-encoded consistently (encode/decode is always internally consistent)", func() {
-		// "a1" happens to be valid hex on its own; DecodeID can't tell a coincidental hex
-		// string apart from one we encoded. Callers must always encode ids on emission and
-		// decode them on receipt so this ambiguity never surfaces in practice.
-		Expect(DecodeID(EncodeID("a1"))).To(Equal("a1"))
+		It("is all-or-nothing: one malformed entry fails the whole list", func() {
+			decoded, ok := DecodeIDs([]string{EncodeID(id.NewRandom()), "not-a-guid"})
+			Expect(ok).To(BeFalse())
+			Expect(decoded).To(BeNil())
+		})
+
+		It("succeeds on an empty list", func() {
+			decoded, ok := DecodeIDs(nil)
+			Expect(ok).To(BeTrue())
+			Expect(decoded).To(BeEmpty())
+		})
 	})
 })
diff --git a/server/jellyfin/dto/mappers.go b/server/jellyfin/dto/mappers.go
index 31cdba1dd..1ebf66ca1 100644
--- a/server/jellyfin/dto/mappers.go
+++ b/server/jellyfin/dto/mappers.go
@@ -138,6 +138,7 @@ func UserData(a model.Annotations, itemID string) *UserItemDataDto {
 // only when the request's Fields asks for them, mirroring real Jellyfin (which omits both from a
 // plain list response); a nil fields set means neither.
 func SongToBaseItem(mf model.MediaFile, fields Fields) BaseItemDto {
+	albumID := EncodeID(mf.AlbumID)
 	item := BaseItemDto{
 		Name:              mf.Title,
 		Id:                EncodeID(mf.ID),
@@ -146,9 +147,9 @@ func SongToBaseItem(mf model.MediaFile, fields Fields) BaseItemDto {
 		IsFolder:          false,
 		LocationType:      "FileSystem",
 		HasLyrics:         mf.HasEmbeddedLyrics(),
-		ParentId:          EncodeID(mf.AlbumID),
+		ParentId:          albumID,
 		Album:             mf.Album,
-		AlbumId:           EncodeID(mf.AlbumID),
+		AlbumId:           albumID,
 		AlbumArtist:       mf.AlbumArtist,
 		RunTimeTicks:      TicksFromSeconds(mf.Duration),
 		DateCreated:       jellyfinDate(&mf.CreatedAt),
diff --git a/server/jellyfin/dto/mappers_test.go b/server/jellyfin/dto/mappers_test.go
index 77b78e55f..576482e61 100644
--- a/server/jellyfin/dto/mappers_test.go
+++ b/server/jellyfin/dto/mappers_test.go
@@ -14,10 +14,10 @@ import (
 var _ = Describe("mappers", func() {
 	It("maps a song to an Audio BaseItemDto", func() {
 		mf := model.MediaFile{
-			ID: "song-1", Title: "Song", Album: "Alb", AlbumID: "alb-1",
+			ID: testID("song-1"), Title: "Song", Album: "Alb", AlbumID: testID("alb-1"),
 			Artist: "Art", AlbumArtist: "AA", TrackNumber: 3, DiscNumber: 1,
 			Year: 1999, Duration: 60, Size: 2_500_000,
-			Genres: []model.Genre{{ID: "1", Name: "genre 1"}, {ID: "2", Name: "genre 2"}},
+			Genres: []model.Genre{{ID: testID("1"), Name: "genre 1"}, {ID: testID("2"), Name: "genre 2"}},
 		}
 		mf.PlayCount = 2
 		mf.Starred = true
@@ -26,24 +26,24 @@ var _ = Describe("mappers", func() {
 		Expect(item.MediaType).To(Equal("Audio"))
 		Expect(item.IsFolder).To(BeFalse())
 		Expect(item.LocationType).To(Equal("FileSystem"))
-		Expect(item.Id).To(Equal(EncodeID("song-1")))
-		Expect(item.AlbumId).To(Equal(EncodeID("alb-1")))
-		Expect(item.ParentId).To(Equal(EncodeID("alb-1")))
+		Expect(item.Id).To(Equal(EncodeID(testID("song-1"))))
+		Expect(item.AlbumId).To(Equal(EncodeID(testID("alb-1"))))
+		Expect(item.ParentId).To(Equal(EncodeID(testID("alb-1"))))
 		Expect(item.RunTimeTicks).To(Equal(int64(600_000_000)))
 		Expect(*item.IndexNumber).To(Equal(3))
 		Expect(item.UserData.IsFavorite).To(BeTrue())
 		Expect(item.UserData.PlayCount).To(Equal(2))
 		Expect(item.UserData.Played).To(BeTrue())
-		Expect(item.UserData.Key).To(Equal(EncodeID("song-1")))
-		Expect(item.UserData.ItemId).To(Equal(EncodeID("song-1")))
-		Expect(item.AlbumPrimaryImageTag).To(Equal("alb-1"))
+		Expect(item.UserData.Key).To(Equal(EncodeID(testID("song-1"))))
+		Expect(item.UserData.ItemId).To(Equal(EncodeID(testID("song-1"))))
+		Expect(item.AlbumPrimaryImageTag).To(Equal(testID("alb-1")))
 		Expect(item.ImageBlurHashes).To(BeNil())
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
-		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID("1"), Name: "genre 1"}, {Id: EncodeID("2"), Name: "genre 2"}}))
+		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID(testID("1")), Name: "genre 1"}, {Id: EncodeID(testID("2")), Name: "genre 2"}}))
 	})
 
 	Describe("Fields gating (matches real Jellyfin)", func() {
-		mf := model.MediaFile{ID: "s1", Title: "Song", Size: 2_500_000, Suffix: "mp3", Duration: 60,
+		mf := model.MediaFile{ID: testID("s1"), Title: "Song", Size: 2_500_000, Suffix: "mp3", Duration: 60,
 			SortTitle: "sort song", Lyrics: `[{"line":[{"value":"la"}]}]`}
 
 		It("omits MediaSources when Fields does not ask for them", func() {
@@ -59,9 +59,9 @@ var _ = Describe("mappers", func() {
 
 		// SortName must match the server sort order — see the sortName helper.
 		Describe("SortName", func() {
-			song := model.MediaFile{ID: "s1", Title: "The Song", SortTitle: "Song, The", OrderTitle: "song"}
-			ar := model.Artist{ID: "art-1", Name: "The B-52's", SortArtistName: "B-52's, The", OrderArtistName: "b-52's"}
-			al := model.Album{ID: "alb-1", Name: "The Wall", SortAlbumName: "Wall, The", OrderAlbumName: "wall"}
+			song := model.MediaFile{ID: testID("s1"), Title: "The Song", SortTitle: "Song, The", OrderTitle: "song"}
+			ar := model.Artist{ID: testID("art-1"), Name: "The B-52's", SortArtistName: "B-52's, The", OrderArtistName: "b-52's"}
+			al := model.Album{ID: testID("alb-1"), Name: "The Wall", SortAlbumName: "Wall, The", OrderAlbumName: "wall"}
 
 			BeforeEach(func() {
 				DeferCleanup(configtest.SetupConfig())
@@ -91,85 +91,85 @@ var _ = Describe("mappers", func() {
 				})
 
 				It("falls back to the order name when there is no sort tag", func() {
-					Expect(ArtistToBaseItem(model.Artist{ID: "a", Name: "The X", OrderArtistName: "x"},
+					Expect(ArtistToBaseItem(model.Artist{ID: testID("a"), Name: "The X", OrderArtistName: "x"},
 						ParseFields("SortName")).SortName).To(Equal("x"))
 				})
 			})
 
 			It("falls back to the display name when order name and sort tag are empty", func() {
-				Expect(SongToBaseItem(model.MediaFile{ID: "s", Title: "T"}, ParseFields("SortName")).SortName).To(Equal("T"))
-				Expect(ArtistToBaseItem(model.Artist{ID: "a", Name: "N"}, ParseFields("SortName")).SortName).To(Equal("N"))
-				Expect(AlbumToBaseItem(model.Album{ID: "al", Name: "A"}, ParseFields("SortName")).SortName).To(Equal("A"))
+				Expect(SongToBaseItem(model.MediaFile{ID: testID("s"), Title: "T"}, ParseFields("SortName")).SortName).To(Equal("T"))
+				Expect(ArtistToBaseItem(model.Artist{ID: testID("a"), Name: "N"}, ParseFields("SortName")).SortName).To(Equal("N"))
+				Expect(AlbumToBaseItem(model.Album{ID: testID("al"), Name: "A"}, ParseFields("SortName")).SortName).To(Equal("A"))
 			})
 		})
 
 		It("sets HasLyrics from the media file's lyrics", func() {
 			Expect(SongToBaseItem(mf, nil).HasLyrics).To(BeTrue())
-			Expect(SongToBaseItem(model.MediaFile{ID: "s2", Title: "No Lyrics"}, nil).HasLyrics).To(BeFalse())
+			Expect(SongToBaseItem(model.MediaFile{ID: testID("s2"), Title: "No Lyrics"}, nil).HasLyrics).To(BeFalse())
 			// "[]" is the no-lyrics sentinel, not a truthy value.
-			Expect(SongToBaseItem(model.MediaFile{ID: "s3", Title: "Empty Lyrics", Lyrics: "[]"}, nil).HasLyrics).To(BeFalse())
+			Expect(SongToBaseItem(model.MediaFile{ID: testID("s3"), Title: "Empty Lyrics", Lyrics: "[]"}, nil).HasLyrics).To(BeFalse())
 		})
 	})
 
 	It("omits ImageBlurHashes when a song has no album", func() {
-		mf := model.MediaFile{ID: "song-noalbum", Title: "Song", Duration: 60}
+		mf := model.MediaFile{ID: testID("song-noalbum"), Title: "Song", Duration: 60}
 		item := SongToBaseItem(mf, nil)
 		Expect(item.AlbumPrimaryImageTag).To(BeEmpty())
 		Expect(item.ImageBlurHashes).To(BeNil())
 	})
 
 	It("sets DateCreated from the media file's CreatedAt", func() {
-		mf := model.MediaFile{ID: "s1", Title: "Song", CreatedAt: time.Date(2024, 1, 15, 10, 30, 0, 0, time.UTC)}
+		mf := model.MediaFile{ID: testID("s1"), Title: "Song", CreatedAt: time.Date(2024, 1, 15, 10, 30, 0, 0, time.UTC)}
 		Expect(SongToBaseItem(mf, nil).DateCreated).To(Equal("2024-01-15T10:30:00Z"))
 	})
 
 	It("omits DateCreated when CreatedAt is the zero time", func() {
-		Expect(SongToBaseItem(model.MediaFile{ID: "s1", Title: "Song"}, nil).DateCreated).To(BeEmpty())
+		Expect(SongToBaseItem(model.MediaFile{ID: testID("s1"), Title: "Song"}, nil).DateCreated).To(BeEmpty())
 	})
 
 	It("sets ArtistItems and AlbumArtists (encoded ids) from the track and album artist", func() {
 		mf := model.MediaFile{
-			ID: "s1", Title: "Song",
-			Artist: "The Band", ArtistID: "ar-1",
-			AlbumArtist: "Various", AlbumArtistID: "ar-2",
+			ID: testID("s1"), Title: "Song",
+			Artist: "The Band", ArtistID: testID("ar-1"),
+			AlbumArtist: "Various", AlbumArtistID: testID("ar-2"),
 		}
 		item := SongToBaseItem(mf, nil)
-		Expect(item.ArtistItems).To(Equal([]NameGuidPair{{Name: "The Band", Id: EncodeID("ar-1")}}))
-		Expect(item.AlbumArtists).To(Equal([]NameGuidPair{{Name: "Various", Id: EncodeID("ar-2")}}))
+		Expect(item.ArtistItems).To(Equal([]NameGuidPair{{Name: "The Band", Id: EncodeID(testID("ar-1"))}}))
+		Expect(item.AlbumArtists).To(Equal([]NameGuidPair{{Name: "Various", Id: EncodeID(testID("ar-2"))}}))
 	})
 
 	It("omits ArtistItems when the track has no artist id", func() {
-		Expect(SongToBaseItem(model.MediaFile{ID: "s1", Title: "Song", Artist: "X"}, nil).ArtistItems).To(BeNil())
+		Expect(SongToBaseItem(model.MediaFile{ID: testID("s1"), Title: "Song", Artist: "X"}, nil).ArtistItems).To(BeNil())
 	})
 
 	It("omits Artists when the track has no artist name or participants", func() {
-		Expect(SongToBaseItem(model.MediaFile{ID: "s1", Title: "Song"}, nil).Artists).To(BeNil())
+		Expect(SongToBaseItem(model.MediaFile{ID: testID("s1"), Title: "Song"}, nil).Artists).To(BeNil())
 	})
 
 	It("splits Artists and ArtistItems per track artist from Participants", func() {
 		mf := model.MediaFile{
-			ID: "s1", Title: "Oooh",
-			Artist: "De La Soul feat. Redman", ArtistID: "ar-delasoul",
-			AlbumArtist: "De La Soul", AlbumArtistID: "ar-delasoul",
+			ID: testID("s1"), Title: "Oooh",
+			Artist: "De La Soul feat. Redman", ArtistID: testID("ar-delasoul"),
+			AlbumArtist: "De La Soul", AlbumArtistID: testID("ar-delasoul"),
 		}
 		mf.Participants = model.Participants{
 			model.RoleArtist: model.ParticipantList{
-				{Artist: model.Artist{ID: "ar-delasoul", Name: "De La Soul"}},
-				{Artist: model.Artist{ID: "ar-redman", Name: "Redman"}},
+				{Artist: model.Artist{ID: testID("ar-delasoul"), Name: "De La Soul"}},
+				{Artist: model.Artist{ID: testID("ar-redman"), Name: "Redman"}},
 			},
 		}
 		item := SongToBaseItem(mf, nil)
 		Expect(item.Artists).To(Equal([]string{"De La Soul", "Redman"}))
 		Expect(item.ArtistItems).To(Equal([]NameGuidPair{
-			{Name: "De La Soul", Id: EncodeID("ar-delasoul")},
-			{Name: "Redman", Id: EncodeID("ar-redman")},
+			{Name: "De La Soul", Id: EncodeID(testID("ar-delasoul"))},
+			{Name: "Redman", Id: EncodeID(testID("ar-redman"))},
 		}))
 		// AlbumArtists stays single, matching real Jellyfin.
-		Expect(item.AlbumArtists).To(Equal([]NameGuidPair{{Name: "De La Soul", Id: EncodeID("ar-delasoul")}}))
+		Expect(item.AlbumArtists).To(Equal([]NameGuidPair{{Name: "De La Soul", Id: EncodeID(testID("ar-delasoul"))}}))
 	})
 
 	It("serializes normalization gains with Jellyfin's exact key casing", func() {
-		mf := model.MediaFile{ID: "s1", Title: "Song",
+		mf := model.MediaFile{ID: testID("s1"), Title: "Song",
 			RGTrackGain: new(-3.5), RGAlbumGain: new(-4.25)}
 		b, err := json.Marshal(SongToBaseItem(mf, nil))
 		Expect(err).ToNot(HaveOccurred())
@@ -178,16 +178,16 @@ var _ = Describe("mappers", func() {
 	})
 
 	It("omits normalization gains when the file has no ReplayGain tags", func() {
-		b, err := json.Marshal(SongToBaseItem(model.MediaFile{ID: "s1", Title: "Song"}, nil))
+		b, err := json.Marshal(SongToBaseItem(model.MediaFile{ID: testID("s1"), Title: "Song"}, nil))
 		Expect(err).ToNot(HaveOccurred())
 		// Substring check covers both keys (AlbumNormalizationGain contains NormalizationGain).
 		Expect(string(b)).ToNot(ContainSubstring("NormalizationGain"))
 	})
 
 	It("builds a MediaSourceInfo from a media file", func() {
-		mf := model.MediaFile{ID: "s1", Size: 5242880, Suffix: "mp3", BitRate: 320, Duration: 100}
+		mf := model.MediaFile{ID: testID("s1"), Size: 5242880, Suffix: "mp3", BitRate: 320, Duration: 100}
 		src := MediaSourceFromMediaFile(mf)
-		Expect(src.Id).To(Equal(EncodeID("s1")))
+		Expect(src.Id).To(Equal(EncodeID(testID("s1"))))
 		Expect(src.Size).To(Equal(int64(5242880)))
 		Expect(src.Container).To(Equal("mp3"))
 		Expect(src.Bitrate).To(Equal(320_000))
@@ -198,7 +198,7 @@ var _ = Describe("mappers", func() {
 
 	It("populates MediaStreams with a single Audio stream so Finamp can size downloads", func() {
 		mf := model.MediaFile{
-			ID: "s1", Size: 5242880, Suffix: "mp3", BitRate: 320, Duration: 100,
+			ID: testID("s1"), Size: 5242880, Suffix: "mp3", BitRate: 320, Duration: 100,
 			Channels: 2, SampleRate: 44100, Codec: "mp3",
 		}
 		src := MediaSourceFromMediaFile(mf)
@@ -213,7 +213,7 @@ var _ = Describe("mappers", func() {
 	})
 
 	It("serializes all Finamp-required MediaSourceInfo bools and arrays, never as null", func() {
-		mf := model.MediaFile{ID: "s1", Size: 5242880, Suffix: "mp3", BitRate: 320, Duration: 100}
+		mf := model.MediaFile{ID: testID("s1"), Size: 5242880, Suffix: "mp3", BitRate: 320, Duration: 100}
 		src := MediaSourceFromMediaFile(mf)
 		b, err := json.Marshal(src)
 		Expect(err).ToNot(HaveOccurred())
@@ -241,7 +241,7 @@ var _ = Describe("mappers", func() {
 
 	Describe("Lyric media stream advertising", func() {
 		It("adds a Lyric media stream when the file has embedded lyrics", func() {
-			mf := model.MediaFile{ID: "s1", Lyrics: `[{"line":[{"value":"la"}]}]`}
+			mf := model.MediaFile{ID: testID("s1"), Lyrics: `[{"line":[{"value":"la"}]}]`}
 			src := MediaSourceFromMediaFile(mf)
 			Expect(src.MediaStreams).To(HaveLen(2))
 			Expect(src.MediaStreams[0].Type).To(Equal("Audio"))
@@ -251,20 +251,20 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("emits only the Audio stream without lyrics", func() {
-			src := MediaSourceFromMediaFile(model.MediaFile{ID: "s1"})
+			src := MediaSourceFromMediaFile(model.MediaFile{ID: testID("s1")})
 			Expect(src.MediaStreams).To(HaveLen(1))
 			Expect(src.MediaStreams[0].Type).To(Equal("Audio"))
 		})
 
 		It("emits only the Audio stream for the post-scan empty-lyrics sentinel", func() {
-			src := MediaSourceFromMediaFile(model.MediaFile{ID: "s1", Lyrics: "[]"})
+			src := MediaSourceFromMediaFile(model.MediaFile{ID: testID("s1"), Lyrics: "[]"})
 			Expect(src.MediaStreams).To(HaveLen(1))
 		})
 	})
 
 	It("omits IndexNumber and ParentIndexNumber when track/disc numbers are untagged", func() {
 		mf := model.MediaFile{
-			ID: "song-2", Title: "Song", Album: "Alb", AlbumID: "alb-1",
+			ID: testID("song-2"), Title: "Song", Album: "Alb", AlbumID: testID("alb-1"),
 			Artist: "Art", AlbumArtist: "AA", TrackNumber: 0, DiscNumber: 0,
 			Duration: 60,
 		}
@@ -276,7 +276,7 @@ var _ = Describe("mappers", func() {
 	It("maps PlayDate to UserData.LastPlayedDate", func() {
 		playDate := time.Date(2023, 5, 17, 12, 30, 0, 0, time.UTC)
 		mf := model.MediaFile{
-			ID: "song-3", Title: "Song", Album: "Alb", AlbumID: "alb-1",
+			ID: testID("song-3"), Title: "Song", Album: "Alb", AlbumID: testID("alb-1"),
 			Artist: "Art", AlbumArtist: "AA", Duration: 60,
 		}
 		mf.PlayDate = &playDate
@@ -286,25 +286,25 @@ var _ = Describe("mappers", func() {
 	})
 
 	It("maps an album to a MusicAlbum folder item", func() {
-		al := model.Album{ID: "alb-1", Name: "Alb", AlbumArtist: "AA", AlbumArtistID: "art-1", MaxYear: 1999, SongCount: 10, Genres: []model.Genre{{ID: "1", Name: "genre 1"}, {ID: "2", Name: "genre 2"}}}
+		al := model.Album{ID: testID("alb-1"), Name: "Alb", AlbumArtist: "AA", AlbumArtistID: testID("art-1"), MaxYear: 1999, SongCount: 10, Genres: []model.Genre{{ID: testID("1"), Name: "genre 1"}, {ID: testID("2"), Name: "genre 2"}}}
 		item := AlbumToBaseItem(al, nil)
 		Expect(item.Type).To(Equal("MusicAlbum"))
 		Expect(item.IsFolder).To(BeTrue())
-		Expect(item.Id).To(Equal(EncodeID("alb-1")))
-		Expect(item.ParentId).To(Equal(EncodeID("art-1")))
+		Expect(item.Id).To(Equal(EncodeID(testID("alb-1"))))
+		Expect(item.ParentId).To(Equal(EncodeID(testID("art-1"))))
 		Expect(item.AlbumArtists).To(HaveLen(1))
-		Expect(item.AlbumArtists[0].Id).To(Equal(EncodeID("art-1")))
+		Expect(item.AlbumArtists[0].Id).To(Equal(EncodeID(testID("art-1"))))
 		Expect(item.ArtistItems).To(Equal(item.AlbumArtists))
 		Expect(*item.ProductionYear).To(Equal(1999))
 		Expect(*item.ChildCount).To(Equal(10))
-		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "alb-1"))
+		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", testID("alb-1")))
 		Expect(item.ImageBlurHashes).To(BeNil())
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
-		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID("1"), Name: "genre 1"}, {Id: EncodeID("2"), Name: "genre 2"}}))
+		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID(testID("1")), Name: "genre 1"}, {Id: EncodeID(testID("2")), Name: "genre 2"}}))
 	})
 
 	It("populates album Studios from record-label tags only when Fields=Studios", func() {
-		al := model.Album{ID: "alb-2", Name: "Alb2"}
+		al := model.Album{ID: testID("alb-2"), Name: "Alb2"}
 		al.Tags = model.Tags{model.TagRecordLabel: []string{"Columbia", "Legacy"}}
 
 		Expect(AlbumToBaseItem(al, nil).Studios).To(BeEmpty())
@@ -317,7 +317,7 @@ var _ = Describe("mappers", func() {
 	})
 
 	It("sets NormalizationGain on the album from its ReplayGain", func() {
-		al := model.Album{ID: "al1", Name: "Album", RGAlbumGain: new(-6.0)}
+		al := model.Album{ID: testID("al1"), Name: "Album", RGAlbumGain: new(-6.0)}
 		b, err := json.Marshal(AlbumToBaseItem(al, nil))
 		Expect(err).ToNot(HaveOccurred())
 		Expect(string(b)).To(ContainSubstring(`"NormalizationGain":-6`))
@@ -326,14 +326,14 @@ var _ = Describe("mappers", func() {
 	})
 
 	It("omits NormalizationGain when the album has no ReplayGain", func() {
-		b, err := json.Marshal(AlbumToBaseItem(model.Album{ID: "al1", Name: "Album"}, nil))
+		b, err := json.Marshal(AlbumToBaseItem(model.Album{ID: testID("al1"), Name: "Album"}, nil))
 		Expect(err).ToNot(HaveOccurred())
 		Expect(string(b)).ToNot(ContainSubstring("NormalizationGain"))
 	})
 
 	Describe("PrimaryImageAspectRatio", func() {
 		nonSquare := func() model.Album {
-			al := model.Album{ID: "al1", Name: "Album"}
+			al := model.Album{ID: testID("al1"), Name: "Album"}
 			al.ImageHash, al.ImageWidth, al.ImageHeight = "abc", 1200, 800
 			return al
 		}
@@ -351,14 +351,14 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("is omitted when the dimensions are unknown, rather than guessing square", func() {
-			al := model.Album{ID: "al1", Name: "Album"}
+			al := model.Album{ID: testID("al1"), Name: "Album"}
 			al.ImageHash = "abc"
 			item := AlbumToBaseItem(al, ParseFields("PrimaryImageAspectRatio"))
 			Expect(item.PrimaryImageAspectRatio).To(BeNil())
 		})
 
 		It("is omitted when the item has no image at all", func() {
-			al := model.Album{ID: "al1", Name: "Album"}
+			al := model.Album{ID: testID("al1"), Name: "Album"}
 			al.ImageAbsent = true
 			al.ImageWidth, al.ImageHeight = 1200, 800
 			item := AlbumToBaseItem(al, ParseFields("PrimaryImageAspectRatio"))
@@ -366,21 +366,21 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("carries the ratio for an artist", func() {
-			ar := model.Artist{ID: "ar1", Name: "Artist"}
+			ar := model.Artist{ID: testID("ar1"), Name: "Artist"}
 			ar.ImageHash, ar.ImageWidth, ar.ImageHeight = "abc", 1000, 500
 			Expect(*ArtistToBaseItem(ar, ParseFields("PrimaryImageAspectRatio")).PrimaryImageAspectRatio).
 				To(BeNumerically("~", 2.0, 0.0001))
 		})
 
 		It("carries the ratio for a playlist", func() {
-			pl := model.Playlist{ID: "pl1", Name: "Playlist"}
+			pl := model.Playlist{ID: testID("pl1"), Name: "Playlist"}
 			pl.ImageHash, pl.ImageWidth, pl.ImageHeight = "abc", 400, 800
 			Expect(*PlaylistToBaseItem(pl, ParseFields("PrimaryImageAspectRatio")).PrimaryImageAspectRatio).
 				To(BeNumerically("~", 0.5, 0.0001))
 		})
 
 		It("carries the ratio for a song with its own art", func() {
-			mf := model.MediaFile{ID: "mf1", Title: "Song"}
+			mf := model.MediaFile{ID: testID("mf1"), Title: "Song"}
 			mf.ImageHash, mf.ImageWidth, mf.ImageHeight = "abc", 300, 600
 			Expect(*SongToBaseItem(mf, ParseFields("PrimaryImageAspectRatio")).PrimaryImageAspectRatio).
 				To(BeNumerically("~", 0.5, 0.0001))
@@ -388,7 +388,7 @@ var _ = Describe("mappers", func() {
 
 		// A track without its own art shows the album's, so the ratio has to describe that image.
 		It("uses the album's dimensions for a track falling back to album art", func() {
-			mf := model.MediaFile{ID: "mf1", Title: "Song", AlbumID: "al1"}
+			mf := model.MediaFile{ID: testID("mf1"), Title: "Song", AlbumID: testID("al1")}
 			mf.AlbumImage.ImageHash, mf.AlbumImage.ImageWidth, mf.AlbumImage.ImageHeight = "abc", 1200, 800
 			item := SongToBaseItem(mf, ParseFields("PrimaryImageAspectRatio"))
 			Expect(item.AlbumPrimaryImageTag).To(Equal("abc"))
@@ -397,73 +397,73 @@ var _ = Describe("mappers", func() {
 	})
 
 	It("maps an artist to a MusicArtist folder item", func() {
-		ar := model.Artist{ID: "art-1", Name: "AA", AlbumCount: 2, SongCount: 20}
+		ar := model.Artist{ID: testID("art-1"), Name: "AA", AlbumCount: 2, SongCount: 20}
 		item := ArtistToBaseItem(ar, nil)
 		Expect(item.Type).To(Equal("MusicArtist"))
 		Expect(item.IsFolder).To(BeTrue())
-		Expect(item.Id).To(Equal(EncodeID("art-1")))
+		Expect(item.Id).To(Equal(EncodeID(testID("art-1"))))
 		Expect(*item.AlbumCount).To(Equal(2))
 	})
 
 	It("maps a genre to a MusicGenre folder item", func() {
-		g := model.Genre{ID: "genre-1", Name: "Rock"}
+		g := model.Genre{ID: testID("genre-1"), Name: "Rock"}
 		item := GenreToBaseItem(g)
 		Expect(item.Type).To(Equal("MusicGenre"))
 		Expect(item.IsFolder).To(BeTrue())
-		Expect(item.Id).To(Equal(EncodeID("genre-1")))
+		Expect(item.Id).To(Equal(EncodeID(testID("genre-1"))))
 		Expect(item.Name).To(Equal("Rock"))
 	})
 
 	It("maps a tag to a Studio BaseItemDto", func() {
-		item := StudioToBaseItem(model.Tag{ID: "t1", TagValue: "Blue Note"})
+		item := StudioToBaseItem(model.Tag{ID: testID("t1"), TagValue: "Blue Note"})
 		Expect(item.Type).To(Equal("Studio"))
 		Expect(item.Name).To(Equal("Blue Note"))
-		Expect(item.Id).To(Equal(EncodeID("t1")))
+		Expect(item.Id).To(Equal(EncodeID(testID("t1"))))
 	})
 
 	Describe("premiereDate", func() {
 		// Finamp re-sorts "Latest Releases" client-side by PremiereDate; absent values sort arbitrarily.
 		It("serializes a full date", func() {
-			mf := model.MediaFile{ID: "s1", Title: "Song", Date: "2007-02-01", Year: 2007}
+			mf := model.MediaFile{ID: testID("s1"), Title: "Song", Date: "2007-02-01", Year: 2007}
 			item := SongToBaseItem(mf, nil)
 			Expect(*item.PremiereDate).To(Equal("2007-02-01T00:00:00Z"))
 		})
 
 		It("pads a year-only date so clients can parse it", func() {
-			mf := model.MediaFile{ID: "s1", Title: "Song", Date: "2007", Year: 2007}
+			mf := model.MediaFile{ID: testID("s1"), Title: "Song", Date: "2007", Year: 2007}
 			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("2007-01-01T00:00:00Z"))
 		})
 
 		It("pads a year-month date", func() {
-			mf := model.MediaFile{ID: "s1", Title: "Song", Date: "2007-02"}
+			mf := model.MediaFile{ID: testID("s1"), Title: "Song", Date: "2007-02"}
 			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("2007-02-01T00:00:00Z"))
 		})
 
 		It("falls back to the year when no date tag exists", func() {
-			mf := model.MediaFile{ID: "s1", Title: "Song", Year: 1999}
+			mf := model.MediaFile{ID: testID("s1"), Title: "Song", Year: 1999}
 			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("1999-01-01T00:00:00Z"))
 		})
 
 		It("is omitted when the track has no date at all", func() {
-			Expect(SongToBaseItem(model.MediaFile{ID: "s1", Title: "Song"}, nil).PremiereDate).To(BeNil())
+			Expect(SongToBaseItem(model.MediaFile{ID: testID("s1"), Title: "Song"}, nil).PremiereDate).To(BeNil())
 		})
 
 		It("is set on albums from their date, falling back to MaxYear", func() {
-			Expect(*AlbumToBaseItem(model.Album{ID: "a1", Date: "2013-09-06"}, nil).PremiereDate).To(Equal("2013-09-06T00:00:00Z"))
-			Expect(*AlbumToBaseItem(model.Album{ID: "a2", MaxYear: 2013}, nil).PremiereDate).To(Equal("2013-01-01T00:00:00Z"))
-			Expect(AlbumToBaseItem(model.Album{ID: "a3"}, nil).PremiereDate).To(BeNil())
+			Expect(*AlbumToBaseItem(model.Album{ID: testID("a1"), Date: "2013-09-06"}, nil).PremiereDate).To(Equal("2013-09-06T00:00:00Z"))
+			Expect(*AlbumToBaseItem(model.Album{ID: testID("a2"), MaxYear: 2013}, nil).PremiereDate).To(Equal("2013-01-01T00:00:00Z"))
+			Expect(AlbumToBaseItem(model.Album{ID: testID("a3")}, nil).PremiereDate).To(BeNil())
 		})
 	})
 
 	It("maps a playlist to a Playlist BaseItemDto", func() {
 		p := model.Playlist{
-			ID: "pl-1", Name: "Chill", SongCount: 7, Duration: 120,
+			ID: testID("pl-1"), Name: "Chill", SongCount: 7, Duration: 120,
 			Annotations: model.Annotations{Starred: true, Rating: 4, PlayCount: 2},
 		}
 		item := PlaylistToBaseItem(p, nil)
 		Expect(item.Type).To(Equal("Playlist"))
 		Expect(item.IsFolder).To(BeTrue())
-		Expect(item.Id).To(Equal(EncodeID("pl-1")))
+		Expect(item.Id).To(Equal(EncodeID(testID("pl-1"))))
 		Expect(item.Name).To(Equal("Chill"))
 		Expect(item.MediaType).To(Equal("Audio"))
 		Expect(*item.ChildCount).To(Equal(7))
@@ -471,12 +471,12 @@ var _ = Describe("mappers", func() {
 		Expect(item.UserData.IsFavorite).To(BeTrue())
 		Expect(item.UserData.PlayCount).To(Equal(2))
 		Expect(*item.UserData.Rating).To(Equal(8.0))
-		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "pl-1"))
+		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", testID("pl-1")))
 		Expect(item.ImageBlurHashes).To(BeNil())
 	})
 
 	It("changes the playlist image tag when the cover content changes", func() {
-		p := model.Playlist{ID: "pl-1", Name: "Chill"}
+		p := model.Playlist{ID: testID("pl-1"), Name: "Chill"}
 		p.ImageHash = "1111111111111111"
 		before := PlaylistToBaseItem(p, nil)
 		p.ImageHash = "2222222222222222"
@@ -487,7 +487,7 @@ var _ = Describe("mappers", func() {
 	})
 
 	It("keeps the playlist image tag stable across a metadata-only edit", func() {
-		p := model.Playlist{ID: "pl-1", UpdatedAt: time.Date(2026, 7, 1, 0, 0, 0, 0, time.UTC)}
+		p := model.Playlist{ID: testID("pl-1"), UpdatedAt: time.Date(2026, 7, 1, 0, 0, 0, 0, time.UTC)}
 		p.ImageHash = "1111111111111111"
 		before := PlaylistToBaseItem(p, nil)
 		p.UpdatedAt = time.Date(2026, 7, 2, 0, 0, 0, 0, time.UTC)
@@ -505,17 +505,17 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("advertises the track id so the client triggers the read-through", func() {
-			mf := model.MediaFile{ID: "mf-1", AlbumID: "alb-1", HasCoverArt: true}
+			mf := model.MediaFile{ID: testID("mf-1"), AlbumID: testID("alb-1"), HasCoverArt: true}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
 
 			item := SongToBaseItem(mf, nil)
-			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "mf-1"))
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", testID("mf-1")))
 			Expect(item.ImageBlurHashes).To(BeNil(), "no resolved image means no blurhash to send")
 			Expect(item.AlbumPrimaryImageTag).To(BeEmpty())
 		})
 
 		It("falls back to the album when the track has no art of its own", func() {
-			mf := model.MediaFile{ID: "mf-2", AlbumID: "alb-1", HasCoverArt: false}
+			mf := model.MediaFile{ID: testID("mf-2"), AlbumID: testID("alb-1"), HasCoverArt: false}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
 
 			item := SongToBaseItem(mf, nil)
@@ -524,7 +524,7 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("falls back to the album once the track's art is known absent", func() {
-			mf := model.MediaFile{ID: "mf-3", AlbumID: "alb-1", HasCoverArt: true}
+			mf := model.MediaFile{ID: testID("mf-3"), AlbumID: testID("alb-1"), HasCoverArt: true}
 			mf.ItemImage.ImageAbsent = true
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
 
@@ -535,7 +535,7 @@ var _ = Describe("mappers", func() {
 
 		It("falls back to the album when per-track art is disabled", func() {
 			conf.Server.EnableMediaFileCoverArt = false
-			mf := model.MediaFile{ID: "mf-4", AlbumID: "alb-1", HasCoverArt: true}
+			mf := model.MediaFile{ID: testID("mf-4"), AlbumID: testID("alb-1"), HasCoverArt: true}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
 
 			item := SongToBaseItem(mf, nil)
@@ -546,7 +546,7 @@ var _ = Describe("mappers", func() {
 
 	Describe("primary image tags", func() {
 		It("uses the content hash as the tag and emits the real blurhash", func() {
-			al := model.Album{ID: "alb-1", Name: "Album"}
+			al := model.Album{ID: testID("alb-1"), Name: "Album"}
 			al.ImageHash = "0123456789abcdef"
 			al.BlurHash = "LEHV6nWB2yk8"
 
@@ -556,7 +556,7 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("omits the blurhash entirely when none was computed", func() {
-			al := model.Album{ID: "alb-2", Name: "Album"}
+			al := model.Album{ID: testID("alb-2"), Name: "Album"}
 			al.ImageHash = "0123456789abcdef"
 
 			item := AlbumToBaseItem(al, nil)
@@ -565,7 +565,7 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("omits tags for known-absent artwork", func() {
-			al := model.Album{ID: "alb-3", Name: "Album"}
+			al := model.Album{ID: testID("alb-3"), Name: "Album"}
 			al.ImageAbsent = true
 
 			item := AlbumToBaseItem(al, nil)
@@ -574,13 +574,13 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("falls back to the entity id while artwork is still unresolved", func() {
-			item := AlbumToBaseItem(model.Album{ID: "alb-4", Name: "Album"}, nil)
-			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", "alb-4"))
+			item := AlbumToBaseItem(model.Album{ID: testID("alb-4"), Name: "Album"}, nil)
+			Expect(item.ImageTags).To(HaveKeyWithValue("Primary", testID("alb-4")))
 			Expect(item.ImageBlurHashes).To(BeNil())
 		})
 
 		It("versions an artist's tag by content hash", func() {
-			ar := model.Artist{ID: "art-1", Name: "Artist"}
+			ar := model.Artist{ID: testID("art-1"), Name: "Artist"}
 			ar.ImageHash = "fedcba9876543210"
 			ar.BlurHash = "L6PZfSi_.AyE"
 
@@ -592,7 +592,7 @@ var _ = Describe("mappers", func() {
 
 	Describe("song and playlist image tags", func() {
 		It("versions a song's album tag by the album's content hash", func() {
-			mf := model.MediaFile{ID: "song-1", Title: "Song", AlbumID: "alb-1"}
+			mf := model.MediaFile{ID: testID("song-1"), Title: "Song", AlbumID: testID("alb-1")}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
 			mf.AlbumImage.BlurHash = "LEHV6nWB2yk8"
 
@@ -602,7 +602,7 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("never synthesizes a song blurhash when the album has none", func() {
-			mf := model.MediaFile{ID: "song-2", Title: "Song", AlbumID: "alb-2"}
+			mf := model.MediaFile{ID: testID("song-2"), Title: "Song", AlbumID: testID("alb-2")}
 			mf.AlbumImage.ImageHash = "0123456789abcdef"
 
 			item := SongToBaseItem(mf, nil)
@@ -611,7 +611,7 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("omits a song's album tag when the album art is known absent", func() {
-			mf := model.MediaFile{ID: "song-3", Title: "Song", AlbumID: "alb-3"}
+			mf := model.MediaFile{ID: testID("song-3"), Title: "Song", AlbumID: testID("alb-3")}
 			mf.AlbumImage.ImageAbsent = true
 
 			item := SongToBaseItem(mf, nil)
@@ -620,7 +620,7 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("versions a playlist tag by content hash instead of UpdatedAt", func() {
-			pl := model.Playlist{ID: "pl-1", Name: "Playlist"}
+			pl := model.Playlist{ID: testID("pl-1"), Name: "Playlist"}
 			pl.ImageHash = "abcdef0123456789"
 
 			item := PlaylistToBaseItem(pl, nil)
@@ -630,7 +630,7 @@ var _ = Describe("mappers", func() {
 
 	Describe("per-song artwork", func() {
 		It("emits the track's own Primary tag when it has distinct art", func() {
-			mf := model.MediaFile{ID: "song-own", Title: "Song", AlbumID: "alb-1"}
+			mf := model.MediaFile{ID: testID("song-own"), Title: "Song", AlbumID: testID("alb-1")}
 			mf.ImageHash = "aaaaaaaaaaaaaaaa"
 			mf.BlurHash = "LTRACKblur"
 			mf.AlbumImage.ImageHash = "bbbbbbbbbbbbbbbb"
@@ -644,7 +644,7 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("falls back to the album tag when the track has no distinct art", func() {
-			mf := model.MediaFile{ID: "song-inherit", Title: "Song", AlbumID: "alb-1"}
+			mf := model.MediaFile{ID: testID("song-inherit"), Title: "Song", AlbumID: testID("alb-1")}
 			mf.ImageHash = "bbbbbbbbbbbbbbbb"
 			mf.BlurHash = "LALBUMblur"
 			mf.AlbumImage.ImageHash = "bbbbbbbbbbbbbbbb"
@@ -658,7 +658,7 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("omits the track tag when its own art is known absent", func() {
-			mf := model.MediaFile{ID: "song-absent", Title: "Song", AlbumID: "alb-1"}
+			mf := model.MediaFile{ID: testID("song-absent"), Title: "Song", AlbumID: testID("alb-1")}
 			mf.ImageAbsent = true
 			mf.AlbumImage.ImageAbsent = true
 
@@ -673,7 +673,7 @@ var _ = Describe("mappers", func() {
 var _ = Describe("LyricDtoFromLyrics", func() {
 	ms := func(v int64) *int64 { return &v }
 
-	mf := model.MediaFile{ID: "s1", Title: "Song", Artist: "Artist", Album: "Album", Duration: 100}
+	mf := model.MediaFile{ID: testID("s1"), Title: "Song", Artist: "Artist", Album: "Album", Duration: 100}
 
 	It("maps synced lyrics with tick conversion", func() {
 		l := model.Lyrics{
diff --git a/server/jellyfin/e2e/annotations_test.go b/server/jellyfin/e2e/annotations_test.go
index b1ad850e3..182fd5436 100644
--- a/server/jellyfin/e2e/annotations_test.go
+++ b/server/jellyfin/e2e/annotations_test.go
@@ -79,7 +79,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("returns 404 when favoriting an unknown item", func() {
-			Expect(post("/Users/admin-1/FavoriteItems/"+enc("nope"), "").Code).To(Equal(http.StatusNotFound))
+			Expect(post("/Users/admin-1/FavoriteItems/"+enc(testID("nope")), "").Code).To(Equal(http.StatusNotFound))
 		})
 	})
 
@@ -102,7 +102,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("returns 404 for an unknown item", func() {
-			Expect(get("/UserItems/" + enc("nope") + "/UserData").Code).To(Equal(http.StatusNotFound))
+			Expect(get("/UserItems/" + enc(testID("nope")) + "/UserData").Code).To(Equal(http.StatusNotFound))
 		})
 	})
 
diff --git a/server/jellyfin/e2e/audiomuse_test.go b/server/jellyfin/e2e/audiomuse_test.go
index 383dbab83..074c8e1a4 100644
--- a/server/jellyfin/e2e/audiomuse_test.go
+++ b/server/jellyfin/e2e/audiomuse_test.go
@@ -61,7 +61,9 @@ var _ = Describe("AudioMuse endpoints", func() {
 			parseInto(get("/AudioMuseAI/similar_tracks?item_id="+enc(songID("Come Together"))+"&n=10"), &body)
 			Expect(body).To(HaveLen(2))
 			Expect([]string{body[0].Title, body[1].Title}).To(ConsistOf("Something", "So What"))
-			Expect(dto.DecodeID(body[0].ItemID)).To(Equal(songID(body[0].Title)))
+			decoded, ok := dto.DecodeID(body[0].ItemID)
+			Expect(ok).To(BeTrue())
+			Expect(decoded).To(Equal(songID(body[0].Title)))
 		})
 
 		It("collapses to one track per artist by default", func() {
diff --git a/server/jellyfin/e2e/auth_test.go b/server/jellyfin/e2e/auth_test.go
index 7128972ba..806b0e5e7 100644
--- a/server/jellyfin/e2e/auth_test.go
+++ b/server/jellyfin/e2e/auth_test.go
@@ -27,9 +27,9 @@ var _ = Describe("Authentication", func() {
 			Expect(res.AccessToken).ToNot(BeEmpty())
 			Expect(res.User).ToNot(BeNil())
 			Expect(res.User.Name).To(Equal("admin"))
-			Expect(res.User.Id).To(Equal(enc("admin-1")))
+			Expect(res.User.Id).To(Equal(enc(testID("admin-1"))))
 			Expect(res.User.Policy.IsAdministrator).To(BeTrue())
-			Expect(res.ServerId).ToNot(BeEmpty())
+			Expect(res.ServerId).To(MatchRegexp("^[0-9a-f]{32}$"))
 
 			// The returned token must actually authenticate a protected request.
 			r := httptest.NewRequest("GET", "/Users/Me", nil)
@@ -84,7 +84,7 @@ var _ = Describe("Authentication", func() {
 			users := publicUsers()
 			Expect(users).To(HaveLen(1))
 			Expect(users[0].Name).To(Equal("regular"))
-			Expect(users[0].Id).To(Equal(enc("regular-1")))
+			Expect(users[0].Id).To(Equal(enc(testID("regular-1"))))
 			Expect(users[0].Policy).To(BeNil()) // must not leak admin status pre-login
 		})
 	})
@@ -94,7 +94,7 @@ var _ = Describe("Authentication", func() {
 			var u dto.UserDto
 			parseInto(getAs(regularUser, "/Users/Me"), &u)
 			Expect(u.Name).To(Equal("regular"))
-			Expect(u.Id).To(Equal(enc("regular-1")))
+			Expect(u.Id).To(Equal(enc(testID("regular-1"))))
 		})
 
 		It("returns the caller from GET /Users/{userId}", func() {
diff --git a/server/jellyfin/e2e/browsing_test.go b/server/jellyfin/e2e/browsing_test.go
index 14ab8b62b..004090de6 100644
--- a/server/jellyfin/e2e/browsing_test.go
+++ b/server/jellyfin/e2e/browsing_test.go
@@ -46,7 +46,7 @@ var _ = Describe("Browsing", func() {
 				Expect(it.Type).To(Equal("Audio"))
 				Expect(it.MediaType).To(Equal("Audio"))
 				Expect(it.LocationType).To(Equal("FileSystem"))
-				Expect(it.ServerId).ToNot(BeEmpty()) // real Jellyfin always sets it
+				Expect(it.ServerId).To(MatchRegexp("^[0-9a-f]{32}$")) // real Jellyfin always sets it, no-dash GUID form
 				Expect(it.AlbumId).ToNot(BeEmpty())
 			}
 		})
@@ -151,7 +151,7 @@ var _ = Describe("Browsing", func() {
 	// Finamp's download sync asks a library for the tracks outside any album this way; answering
 	// with every track would stream the whole library.
 	Describe("Recursive=false", func() {
-		lib1 := enc("1")
+		lib1 := dto.EncodeLibraryID(1)
 
 		It("returns no songs for a library parent", func() {
 			q := queryResult(get("/Items?IncludeItemTypes=Audio&ParentId=" + lib1 + "&Recursive=false"))
@@ -173,7 +173,7 @@ var _ = Describe("Browsing", func() {
 	// Finamp's artist screen sends ParentId=<libraryId> (scoping) plus AlbumArtistIds/ArtistIds
 	// for the actual artist filter, not ParentId=<artistId>.
 	Describe("artist filtering (AlbumArtistIds / ArtistIds)", func() {
-		lib1 := enc("1")
+		lib1 := dto.EncodeLibraryID(1)
 
 		It("filters albums by AlbumArtistIds", func() {
 			q := queryResult(get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&ParentId=" + lib1 + "&AlbumArtistIds=" + enc(artistID("The Beatles"))))
@@ -209,6 +209,87 @@ var _ = Describe("Browsing", func() {
 		})
 	})
 
+	// A malformed id must 404, not silently drop the filter and widen the query to the whole
+	// library; a well-formed but unknown one must still fail closed to zero results.
+	Describe("stale and malformed id filtering", func() {
+		lib1 := dto.EncodeLibraryID(1)
+
+		It("404s a malformed ParentId instead of listing every song", func() {
+			w := get("/Items?IncludeItemTypes=Audio&ParentId=not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns zero songs, not the whole library, for a well-formed but unknown ParentId", func() {
+			q := queryResult(get("/Items?IncludeItemTypes=Audio&ParentId=" + enc(testID("no-such-album"))))
+			Expect(q.TotalRecordCount).To(BeZero())
+			Expect(q.Items).To(BeEmpty())
+		})
+
+		It("404s a malformed AlbumArtistIds instead of listing every album", func() {
+			w := get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&ParentId=" + lib1 + "&AlbumArtistIds=not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns zero albums, not every album, for a well-formed but unknown AlbumArtistIds", func() {
+			q := queryResult(get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&ParentId=" + lib1 + "&AlbumArtistIds=" + enc(testID("no-such-artist"))))
+			Expect(q.TotalRecordCount).To(BeZero())
+			Expect(q.Items).To(BeEmpty())
+		})
+
+		It("404s a malformed ArtistIds instead of listing every song", func() {
+			w := get("/Items?IncludeItemTypes=Audio&Recursive=true&ParentId=" + lib1 + "&ArtistIds=not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns zero songs, not every song, for a well-formed but unknown ArtistIds", func() {
+			q := queryResult(get("/Items?IncludeItemTypes=Audio&Recursive=true&ParentId=" + lib1 + "&ArtistIds=" + enc(testID("no-such-artist"))))
+			Expect(q.TotalRecordCount).To(BeZero())
+			Expect(q.Items).To(BeEmpty())
+		})
+
+		It("404s a malformed Ids entry instead of batch-fetching nothing", func() {
+			w := get("/Items?Ids=not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("404s when only one of several Ids entries is malformed", func() {
+			w := get("/Items?Ids=" + enc(songID("Something")) + ",not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns zero items, not an error, for a well-formed but unknown Ids entry", func() {
+			q := queryResult(get("/Items?Ids=" + enc(testID("no-such-item"))))
+			Expect(q.TotalRecordCount).To(BeZero())
+			Expect(q.Items).To(BeEmpty())
+		})
+
+		It("404s a malformed GenreIds entry instead of listing every album", func() {
+			w := get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&GenreIds=not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("404s when only one of several GenreIds entries is malformed", func() {
+			w := get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&GenreIds=" + enc(genreID("Jazz")) + ",not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("404s a malformed AlbumIds entry instead of listing every song", func() {
+			w := get("/Items?IncludeItemTypes=Audio&Recursive=true&AlbumIds=not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("404s a malformed StudioIds entry instead of listing every album", func() {
+			w := get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&StudioIds=not-a-valid-id")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns zero albums, not every album, for a well-formed but unknown StudioIds", func() {
+			q := queryResult(get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&StudioIds=" + enc(testID("no-such-studio"))))
+			Expect(q.TotalRecordCount).To(BeZero())
+			Expect(q.Items).To(BeEmpty())
+		})
+	})
+
 	// Feishin fetches an album's tracks with AlbumIds=<albumId>&IncludeItemTypes=Audio&Recursive=true.
 	Describe("album filtering (AlbumIds)", func() {
 		It("filters songs by AlbumIds", func() {
@@ -224,7 +305,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("returns nothing for an unknown album id", func() {
-			q := queryResult(get("/Items?IncludeItemTypes=Audio&Recursive=true&AlbumIds=" + enc("no-such-album")))
+			q := queryResult(get("/Items?IncludeItemTypes=Audio&Recursive=true&AlbumIds=" + enc(testID("no-such-album"))))
 			Expect(q.Items).To(BeEmpty())
 			Expect(q.TotalRecordCount).To(Equal(0))
 		})
@@ -261,16 +342,16 @@ var _ = Describe("Browsing", func() {
 
 		It("returns filter lists scoped to a ParentId library", func() {
 			var filters dto.QueryFiltersLegacy
-			parseInto(get("/Items/Filters?ParentId="+enc("1")+"&IncludeItemTypes=Audio&Recursive=true"), &filters)
+			parseInto(get("/Items/Filters?ParentId="+dto.EncodeLibraryID(1)+"&IncludeItemTypes=Audio&Recursive=true"), &filters)
 			Expect(filters.Years).To(ContainElements(1959, 1965))
-			studios := queryResult(get("/Studios?ParentId=" + enc("1")))
+			studios := queryResult(get("/Studios?ParentId=" + dto.EncodeLibraryID(1)))
 			Expect(names(studios.Items)).To(ContainElement("Columbia"))
 		})
 	})
 
 	// Finamp's genre screen sends ParentId=<libraryId> (scoping) plus GenreIds=<genreId>.
 	Describe("genre filtering (GenreIds)", func() {
-		lib1 := enc("1")
+		lib1 := dto.EncodeLibraryID(1)
 
 		It("filters albums by GenreIds", func() {
 			q := queryResult(get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&ParentId=" + lib1 + "&GenreIds=" + enc(genreID("Jazz"))))
@@ -295,7 +376,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("returns nothing for an unknown genre id", func() {
-			q := queryResult(get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&GenreIds=" + enc("no-such-genre")))
+			q := queryResult(get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&GenreIds=" + enc(testID("no-such-genre"))))
 			Expect(q.Items).To(BeEmpty())
 			Expect(q.TotalRecordCount).To(Equal(0))
 		})
@@ -317,7 +398,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("returns no artists for an unknown genre id", func() {
-			q := queryResult(get("/Artists/AlbumArtists?GenreIds=" + enc("no-such-genre")))
+			q := queryResult(get("/Artists/AlbumArtists?GenreIds=" + enc(testID("no-such-genre"))))
 			Expect(q.Items).To(BeEmpty())
 		})
 	})
@@ -327,7 +408,7 @@ var _ = Describe("Browsing", func() {
 	// binds them case-insensitively; these guard that our dispatcher does too, and that browsing an
 	// album with only parentId (no IncludeItemTypes, as Jellify does) returns its tracks.
 	Describe("camelCase query params (Jellify / JS SDK)", func() {
-		lib1 := enc("1")
+		lib1 := dto.EncodeLibraryID(1)
 
 		It("filters albums by camelCase albumArtistIds", func() {
 			q := queryResult(get("/Items?includeItemTypes=MusicAlbum&recursive=true&parentId=" + lib1 + "&albumArtistIds=" + enc(artistID("The Beatles"))))
@@ -364,35 +445,6 @@ var _ = Describe("Browsing", func() {
 			Expect(names(q.Items)).To(ConsistOf("Abbey Road", "IV"))
 		})
 
-		// Finamp restores its saved queue with ids truncated to 16 bytes (see README).
-		Describe("Finamp-truncated ids (saved queue restore)", func() {
-			It("resolves a truncated id by unique prefix and echoes the requested id", func() {
-				full := songID("Come Together")
-				truncated := full[:16]
-				q := queryResult(get("/Items?ids=" + enc(truncated)))
-				Expect(names(q.Items)).To(ConsistOf("Come Together"))
-				// Finamp matches restored items by its stored ids, so the requested id must be echoed.
-				Expect(q.Items[0].Id).To(Equal(enc(truncated)))
-			})
-
-			It("batch-resolves a mixed list of truncated and full ids, keeping order", func() {
-				ids := enc(songID("Come Together")[:16]) + "," + enc(songID("So What")) + "," + enc(songID("Help!")[:16])
-				q := queryResult(get("/Items?ids=" + ids))
-				Expect(names(q.Items)).To(Equal([]string{"Come Together", "So What", "Help!"}))
-			})
-
-			It("streams a track by its truncated id", func() {
-				full := songID("So What")
-				w := get("/Audio/" + enc(full[:16]) + "/stream")
-				Expect(w.Code).To(Equal(http.StatusOK))
-				Expect(streamerSpy.LastMediaFile.ID).To(Equal(full))
-			})
-
-			It("still 404s for a truncated id matching nothing", func() {
-				Expect(get("/Audio/" + enc("zzzzzzzzzzzzzzzz") + "/stream").Code).To(Equal(http.StatusNotFound))
-			})
-		})
-
 		It("applies Limit while reporting the full TotalRecordCount", func() {
 			q := queryResult(get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true&Limit=2"))
 			Expect(q.Items).To(HaveLen(2))
@@ -496,7 +548,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("returns 404 for an unknown id", func() {
-			Expect(get("/Items/" + enc("does-not-exist")).Code).To(Equal(http.StatusNotFound))
+			Expect(get("/Items/" + enc(testID("does-not-exist"))).Code).To(Equal(http.StatusNotFound))
 		})
 	})
 
diff --git a/server/jellyfin/e2e/e2e_suite_test.go b/server/jellyfin/e2e/e2e_suite_test.go
index ca1308e9e..1ee19ea01 100644
--- a/server/jellyfin/e2e/e2e_suite_test.go
+++ b/server/jellyfin/e2e/e2e_suite_test.go
@@ -51,6 +51,7 @@ import (
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/persistence"
 	"github.com/navidrome/navidrome/server/events"
@@ -70,6 +71,10 @@ func TestJellyfinE2E(t *testing.T) {
 	RunSpecs(t, "Jellyfin API E2E Suite")
 }
 
+// testID maps a readable label to a deterministic canonical id, so fixtures exercise the same
+// id shape production uses.
+func testID(label string) string { return id.NewHash("jellyfin-test", label) }
+
 // Easy aliases for the storagetest package
 type _t = map[string]any
 
@@ -91,14 +96,14 @@ var (
 	dataFolder        string
 
 	adminUser = model.User{
-		ID:       "admin-1",
+		ID:       testID("admin-1"),
 		UserName: "admin",
 		Name:     "Admin User",
 		IsAdmin:  true,
 	}
 
 	regularUser = model.User{
-		ID:       "regular-1",
+		ID:       testID("regular-1"),
 		UserName: "regular",
 		Name:     "Regular User",
 		IsAdmin:  false,
@@ -219,7 +224,9 @@ func createPlaylistAs(user model.User, name string, encodedIds ...string) string
 	var res map[string]string
 	parseInto(postAs(user, "/Playlists", string(body)), &res)
 	Expect(res["Id"]).ToNot(BeEmpty())
-	return dto.DecodeID(res["Id"])
+	id, ok := dto.DecodeID(res["Id"])
+	Expect(ok).To(BeTrue())
+	return id
 }
 
 // --- Seeded-id lookup helpers (return Navidrome ids; wrap with enc() for URLs) ---
diff --git a/server/jellyfin/e2e/lyrics_test.go b/server/jellyfin/e2e/lyrics_test.go
index 279f288b8..a49019bbf 100644
--- a/server/jellyfin/e2e/lyrics_test.go
+++ b/server/jellyfin/e2e/lyrics_test.go
@@ -53,7 +53,7 @@ var _ = Describe("Lyrics", func() {
 		})
 
 		It("returns 404 for a fabricated id", func() {
-			Expect(get("/Audio/" + enc("nope") + "/Lyrics").Code).To(Equal(http.StatusNotFound))
+			Expect(get("/Audio/" + enc(testID("nope")) + "/Lyrics").Code).To(Equal(http.StatusNotFound))
 		})
 	})
 
diff --git a/server/jellyfin/e2e/multiuser_test.go b/server/jellyfin/e2e/multiuser_test.go
index 015d82d91..d3a521332 100644
--- a/server/jellyfin/e2e/multiuser_test.go
+++ b/server/jellyfin/e2e/multiuser_test.go
@@ -18,7 +18,7 @@ var _ = Describe("Multi-user access control", func() {
 		})
 
 		It("hides all content from a user with no library access", func() {
-			noAccess := model.User{ID: "noaccess-1", UserName: "noaccess", Name: "No Access", NewPassword: "password"}
+			noAccess := model.User{ID: testID("noaccess-1"), UserName: "noaccess", Name: "No Access", NewPassword: "password"}
 			Expect(ds.User(ctx).Put(&noAccess)).To(Succeed())
 			loaded, err := ds.User(ctx).FindByUsername("noaccess")
 			Expect(err).ToNot(HaveOccurred())
diff --git a/server/jellyfin/e2e/playlists_test.go b/server/jellyfin/e2e/playlists_test.go
index 08d6f4f6f..50c2e17f2 100644
--- a/server/jellyfin/e2e/playlists_test.go
+++ b/server/jellyfin/e2e/playlists_test.go
@@ -46,6 +46,20 @@ var _ = Describe("Playlists", func() {
 			plID := createPlaylist("From Artist", []string{enc(artistID("The Beatles"))})
 			Expect(playlistItems(plID).TotalRecordCount).To(Equal(3)) // Abbey Road (2) + Help! (1)
 		})
+
+		// dto.DecodeIDs is all-or-nothing: a malformed entry must 404 the whole request, not get
+		// dropped while the well-formed entries are still used to create a playlist.
+		It("404s when one of the Ids is malformed, without creating a playlist", func() {
+			before, err := ds.Playlist(ctx).CountAll()
+			Expect(err).ToNot(HaveOccurred())
+
+			body := `{"Name":"ShouldNotExist","Ids":["` + enc(songID("So What")) + `","not-a-valid-id"]}`
+			Expect(post("/Playlists", body).Code).To(Equal(http.StatusNotFound))
+
+			after, err := ds.Playlist(ctx).CountAll()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(after).To(Equal(before))
+		})
 	})
 
 	Describe("items", func() {
@@ -81,6 +95,13 @@ var _ = Describe("Playlists", func() {
 			Expect(playlistItems(plID).TotalRecordCount).To(Equal(3))
 		})
 
+		It("404s when one of the ids to add is malformed, without adding any track", func() {
+			plID := createPlaylist("AddMalformed", nil)
+			url := "/Playlists/" + enc(plID) + "/Items?ids=" + enc(songID("So What")) + ",not-a-valid-id"
+			Expect(post(url, "").Code).To(Equal(http.StatusNotFound))
+			Expect(playlistItems(plID).TotalRecordCount).To(BeZero())
+		})
+
 		It("removes an entry by its PlaylistItemId", func() {
 			plID := createPlaylist("Remove", []string{enc(songID("Come Together")), enc(songID("Something"))})
 			entryID := playlistItems(plID).Items[0].PlaylistItemId
@@ -103,7 +124,7 @@ var _ = Describe("Playlists", func() {
 			var perms []dto.PlaylistUserPermissions
 			parseInto(get("/Playlists/"+enc(plID)+"/Users"), &perms)
 			Expect(perms).To(HaveLen(1))
-			Expect(perms[0].UserId).To(Equal(enc("admin-1")))
+			Expect(perms[0].UserId).To(Equal(enc(testID("admin-1"))))
 			Expect(perms[0].CanEdit).To(BeTrue())
 		})
 	})
@@ -135,12 +156,12 @@ var _ = Describe("Playlists", func() {
 			q := queryResult(get("/Items?includeItemTypes=ManualPlaylistsFolder&excludeItemTypes=CollectionFolder"))
 			Expect(q.Items).To(HaveLen(1))
 			Expect(q.Items[0].CollectionType).To(Equal("playlists"))
-			Expect(q.Items[0].Id).To(Equal(enc("playlists")))
+			Expect(q.Items[0].Id).To(Equal(dto.PlaylistsFolderGUID))
 		})
 
 		It("lists the user's playlists when browsing the folder by ParentId (no IncludeItemTypes)", func() {
 			createPlaylist("My Mix", nil)
-			q := queryResult(get("/Items?parentId=" + enc("playlists")))
+			q := queryResult(get("/Items?parentId=" + dto.PlaylistsFolderGUID))
 			Expect(names(q.Items)).To(ContainElement("My Mix"))
 			Expect(q.Items[0].Type).To(Equal("Playlist"))
 			// Jellify keeps only playlists whose Path contains "data".
@@ -149,10 +170,10 @@ var _ = Describe("Playlists", func() {
 
 		It("resolves the synthetic playlists folder by its own advertised id", func() {
 			var item dto.BaseItemDto
-			parseInto(get("/Items/"+enc("playlists")), &item)
+			parseInto(get("/Items/"+dto.PlaylistsFolderGUID), &item)
 			Expect(item.Type).To(Equal("ManualPlaylistsFolder"))
 			Expect(item.CollectionType).To(Equal("playlists"))
-			Expect(item.Id).To(Equal(enc("playlists")))
+			Expect(item.Id).To(Equal(dto.PlaylistsFolderGUID))
 		})
 	})
 
@@ -239,6 +260,15 @@ var _ = Describe("Playlists", func() {
 	})
 
 	Describe("update", func() {
+		It("404s when one of the replacement Ids is malformed, leaving the track list unchanged", func() {
+			plID := createPlaylist("UpdateMalformed", []string{enc(songID("Come Together"))})
+			body := `{"Ids":["` + enc(songID("So What")) + `","not-a-valid-id"]}`
+			Expect(post("/Playlists/"+enc(plID), body).Code).To(Equal(http.StatusNotFound))
+			q := playlistItems(plID)
+			Expect(q.TotalRecordCount).To(Equal(1))
+			Expect(names(q.Items)).To(ConsistOf("Come Together"))
+		})
+
 		It("makes a playlist public", func() {
 			plID := createPlaylist("Make Public", nil)
 			Expect(post("/Playlists/"+enc(plID), `{"Name":"Make Public","IsPublic":true}`).Code).To(Equal(http.StatusNoContent))
@@ -295,6 +325,20 @@ var _ = Describe("Playlists", func() {
 			post("/Playlists/"+enc(plID), `{"IsPublic":true}`) // make it visible to the regular user
 			Expect(postAs(regularUser, "/Playlists/"+enc(plID), `{"Name":"Hijacked"}`).Code).To(Equal(http.StatusForbidden))
 		})
+
+		// An id that decodes to "" would tell Create to make a new playlist instead of updating one —
+		// itemIDParam must 404 before that decode ever runs, not silently create one.
+		It("404s for a malformed playlist id, without creating a playlist", func() {
+			before, err := ds.Playlist(ctx).CountAll()
+			Expect(err).ToNot(HaveOccurred())
+
+			w := post("/Playlists/00000000000000000000000000000000", `{"Ids":["`+enc(songID("So What"))+`"]}`)
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+
+			after, err := ds.Playlist(ctx).CountAll()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(after).To(Equal(before))
+		})
 	})
 
 	Describe("delete", func() {
diff --git a/server/jellyfin/e2e/search_test.go b/server/jellyfin/e2e/search_test.go
index 6c26569fc..fa14f6811 100644
--- a/server/jellyfin/e2e/search_test.go
+++ b/server/jellyfin/e2e/search_test.go
@@ -3,6 +3,7 @@ package e2e
 import (
 	"fmt"
 
+	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -12,7 +13,7 @@ import (
 var _ = Describe("Search", func() {
 	BeforeEach(func() { setupTestDB() })
 
-	lib1 := func() string { return enc("1") } // Library id 1 encodes to "31"
+	lib1 := func() string { return dto.EncodeLibraryID(1) }
 
 	Describe("artists", func() {
 		It("searches all album artists", func() {
diff --git a/server/jellyfin/e2e/similar_test.go b/server/jellyfin/e2e/similar_test.go
index 43ef857fa..5f1a88a21 100644
--- a/server/jellyfin/e2e/similar_test.go
+++ b/server/jellyfin/e2e/similar_test.go
@@ -1,6 +1,8 @@
 package e2e
 
 import (
+	"net/http"
+
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -12,7 +14,7 @@ var _ = Describe("Similar", func() {
 	Describe("GET /Artists/{id}/Similar", func() {
 		It("returns the provider's similar artists, excluding ones not in the library", func() {
 			providerFake.similarArtists = model.Artists{
-				{ID: "z", Name: "Led Zeppelin"},
+				{ID: testID("z"), Name: "Led Zeppelin"},
 				{ID: "", Name: "Not In Library"}, // no id -> not present -> excluded
 			}
 			q := queryResult(get("/Artists/" + enc(artistID("The Beatles")) + "/Similar"))
@@ -25,11 +27,18 @@ var _ = Describe("Similar", func() {
 			Expect(q.Items).To(BeEmpty())
 			Expect(q.TotalRecordCount).To(Equal(0))
 		})
+
+		// Unlike an unresolvable-but-well-formed id (empty result above), a malformed itemId never
+		// reaches provider lookup at all — itemIDParam rejects it first.
+		It("404s a malformed itemId", func() {
+			w := get("/Artists/not-a-valid-id/Similar")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
 	})
 
 	Describe("GET /Items/{id}/Similar", func() {
 		It("returns similar songs for a track", func() {
-			providerFake.similarSongs = model.MediaFiles{{ID: "x1", Title: "Similar Song", LibraryID: 1}}
+			providerFake.similarSongs = model.MediaFiles{{ID: testID("x1"), Title: "Similar Song", LibraryID: 1}}
 			q := queryResult(get("/Items/" + enc(songID("So What")) + "/Similar"))
 			Expect(names(q.Items)).To(ConsistOf("Similar Song"))
 			Expect(q.Items[0].Type).To(Equal("Audio"))
@@ -37,8 +46,8 @@ var _ = Describe("Similar", func() {
 
 		It("excludes similar songs from libraries the user can't access", func() {
 			providerFake.similarSongs = model.MediaFiles{
-				{ID: "x1", Title: "In Library", LibraryID: 1},
-				{ID: "x2", Title: "Other Library", LibraryID: 2}, // regularUser has no access
+				{ID: testID("x1"), Title: "In Library", LibraryID: 1},
+				{ID: testID("x2"), Title: "Other Library", LibraryID: 2}, // regularUser has no access
 			}
 			q := queryResult(getAs(regularUser, "/Items/"+enc(songID("So What"))+"/Similar"))
 			Expect(names(q.Items)).To(ConsistOf("In Library"))
@@ -46,9 +55,9 @@ var _ = Describe("Similar", func() {
 
 		It("returns similar albums (derived from similar songs, de-duplicated) for an album", func() {
 			providerFake.similarSongs = model.MediaFiles{
-				{ID: "x1", AlbumID: albumID("IV")},
-				{ID: "x2", AlbumID: albumID("IV")}, // same album -> counted once
-				{ID: "x3", AlbumID: albumID("Kind of Blue")},
+				{ID: testID("x1"), AlbumID: albumID("IV")},
+				{ID: testID("x2"), AlbumID: albumID("IV")}, // same album -> counted once
+				{ID: testID("x3"), AlbumID: albumID("Kind of Blue")},
 			}
 			q := queryResult(get("/Items/" + enc(albumID("Abbey Road")) + "/Similar"))
 			Expect(names(q.Items)).To(Equal([]string{"IV", "Kind of Blue"}))
@@ -60,27 +69,32 @@ var _ = Describe("Similar", func() {
 			// provider similar-song at it.
 			otherLib := model.Library{ID: 2, Name: "Other Library", Path: "fake:///other"}
 			Expect(ds.Library(ctx).Put(&otherLib)).To(Succeed())
-			otherAlbum := model.Album{ID: "other-album", Name: "Other Album", LibraryID: 2}
+			otherAlbum := model.Album{ID: testID("other-album"), Name: "Other Album", LibraryID: 2}
 			Expect(ds.Album(ctx).Put(&otherAlbum)).To(Succeed())
 
 			providerFake.similarSongs = model.MediaFiles{
-				{ID: "x1", AlbumID: albumID("IV")}, // library 1 -> visible
-				{ID: "x2", AlbumID: "other-album"}, // library 2 -> filtered for regularUser
+				{ID: testID("x1"), AlbumID: albumID("IV")},         // library 1 -> visible
+				{ID: testID("x2"), AlbumID: testID("other-album")}, // library 2 -> filtered for regularUser
 			}
 			q := queryResult(getAs(regularUser, "/Items/"+enc(albumID("Abbey Road"))+"/Similar"))
 			Expect(names(q.Items)).To(ConsistOf("IV"))
 		})
 
 		It("returns an empty result (not 404) for an unknown item, so the client stops retrying", func() {
-			q := queryResult(get("/Items/" + enc("does-not-exist") + "/Similar"))
+			q := queryResult(get("/Items/" + enc(testID("does-not-exist")) + "/Similar"))
 			Expect(q.Items).To(BeEmpty())
 		})
+
+		It("404s a malformed itemId", func() {
+			w := get("/Items/not-a-valid-id/Similar")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
 	})
 
 	// Finamp plays exactly what InstantMix returns, so a track seed must lead its own mix.
 	Describe("GET /Items/{id}/InstantMix", func() {
 		It("returns the seed track first, followed by similar songs", func() {
-			providerFake.similarSongs = model.MediaFiles{{ID: "x1", Title: "Similar Song", LibraryID: 1}}
+			providerFake.similarSongs = model.MediaFiles{{ID: testID("x1"), Title: "Similar Song", LibraryID: 1}}
 			q := queryResult(get("/Items/" + enc(songID("So What")) + "/InstantMix?limit=19"))
 			Expect(names(q.Items)).To(Equal([]string{"So What", "Similar Song"}))
 			Expect(q.Items[0].Type).To(Equal("Audio"))
@@ -89,7 +103,7 @@ var _ = Describe("Similar", func() {
 		It("does not duplicate the seed when the provider returns it", func() {
 			providerFake.similarSongs = model.MediaFiles{
 				{ID: songID("So What"), Title: "So What", LibraryID: 1},
-				{ID: "x1", Title: "Similar Song", LibraryID: 1},
+				{ID: testID("x1"), Title: "Similar Song", LibraryID: 1},
 			}
 			q := queryResult(get("/Items/" + enc(songID("So What")) + "/InstantMix"))
 			Expect(names(q.Items)).To(Equal([]string{"So What", "Similar Song"}))
@@ -97,9 +111,9 @@ var _ = Describe("Similar", func() {
 
 		It("caps the mix at the requested limit", func() {
 			providerFake.similarSongs = model.MediaFiles{
-				{ID: "x1", Title: "S1", LibraryID: 1},
-				{ID: "x2", Title: "S2", LibraryID: 1},
-				{ID: "x3", Title: "S3", LibraryID: 1},
+				{ID: testID("x1"), Title: "S1", LibraryID: 1},
+				{ID: testID("x2"), Title: "S2", LibraryID: 1},
+				{ID: testID("x3"), Title: "S3", LibraryID: 1},
 			}
 			q := queryResult(get("/Items/" + enc(songID("So What")) + "/InstantMix?limit=2"))
 			Expect(names(q.Items)).To(Equal([]string{"So What", "S1"}))
@@ -107,21 +121,21 @@ var _ = Describe("Similar", func() {
 
 		It("excludes similar songs from libraries the user can't access", func() {
 			providerFake.similarSongs = model.MediaFiles{
-				{ID: "x1", Title: "In Library", LibraryID: 1},
-				{ID: "x2", Title: "Other Library", LibraryID: 2},
+				{ID: testID("x1"), Title: "In Library", LibraryID: 1},
+				{ID: testID("x2"), Title: "Other Library", LibraryID: 2},
 			}
 			q := queryResult(getAs(regularUser, "/Items/"+enc(songID("So What"))+"/InstantMix"))
 			Expect(names(q.Items)).To(Equal([]string{"So What", "In Library"}))
 		})
 
 		It("returns a mix of the provider's similar songs for an artist seed", func() {
-			providerFake.similarSongs = model.MediaFiles{{ID: "x1", Title: "Artist Mix Song", LibraryID: 1}}
+			providerFake.similarSongs = model.MediaFiles{{ID: testID("x1"), Title: "Artist Mix Song", LibraryID: 1}}
 			q := queryResult(get("/Items/" + enc(artistID("Miles Davis")) + "/InstantMix"))
 			Expect(names(q.Items)).To(Equal([]string{"Artist Mix Song"}))
 		})
 
 		It("returns an empty result (not 404) for an unknown item", func() {
-			w := get("/Items/" + enc("does-not-exist") + "/InstantMix")
+			w := get("/Items/" + enc(testID("does-not-exist")) + "/InstantMix")
 			Expect(w.Code).To(Equal(200))
 			Expect(queryResult(w).Items).To(BeEmpty())
 		})
@@ -130,5 +144,10 @@ var _ = Describe("Similar", func() {
 			q := queryResult(get("/Items/" + enc(songID("Help!")) + "/InstantMix"))
 			Expect(names(q.Items)).To(Equal([]string{"Help!"}))
 		})
+
+		It("404s a malformed itemId", func() {
+			w := get("/Items/not-a-valid-id/InstantMix")
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
 	})
 })
diff --git a/server/jellyfin/e2e/streaming_test.go b/server/jellyfin/e2e/streaming_test.go
index c096d904a..954981910 100644
--- a/server/jellyfin/e2e/streaming_test.go
+++ b/server/jellyfin/e2e/streaming_test.go
@@ -43,7 +43,7 @@ var _ = Describe("Streaming", func() {
 		})
 
 		It("returns 404 for an unknown track", func() {
-			Expect(get("/Audio/" + enc("nope") + "/stream").Code).To(Equal(http.StatusNotFound))
+			Expect(get("/Audio/" + enc(testID("nope")) + "/stream").Code).To(Equal(http.StatusNotFound))
 		})
 	})
 
@@ -98,7 +98,7 @@ var _ = Describe("Streaming", func() {
 			parseInto(get("/Items/"+enc(id)+"/PlaybackInfo"), &info)
 			Expect(info.MediaSources).To(HaveLen(1))
 			Expect(info.MediaSources[0].Id).ToNot(BeEmpty())
-			Expect(info.PlaySessionId).ToNot(BeEmpty())
+			Expect(info.PlaySessionId).To(MatchRegexp("^[0-9a-f]{32}$"))
 		})
 
 		It("returns a MediaSource via POST", func() {
diff --git a/server/jellyfin/images.go b/server/jellyfin/images.go
index b844e7c74..65f02d7a0 100644
--- a/server/jellyfin/images.go
+++ b/server/jellyfin/images.go
@@ -14,14 +14,12 @@ import (
 	"strconv"
 
 	"github.com/dustin/go-humanize"
-	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/imghttp"
-	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	_ "golang.org/x/image/webp"
 )
 
@@ -29,7 +27,10 @@ func (api *Router) getItemImage(w http.ResponseWriter, r *http.Request) {
 	// Public endpoint, like real Jellyfin's image routes: clients fetch cover URLs without credentials
 	// and item ids are unguessable, so resolution runs elevated to bypass the visibility filter.
 	ctx := request.WithUser(r.Context(), model.User{IsAdmin: true})
-	itemId := api.resolveItemID(ctx, dto.DecodeID(chi.URLParam(r, "itemId")))
+	itemId, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	size, _ := strconv.Atoi(r.URL.Query().Get("maxwidth"))
 
 	artID := api.resolveArtworkID(ctx, itemId)
@@ -84,11 +85,14 @@ func (api *Router) resolveArtworkID(ctx context.Context, itemId string) string {
 }
 
 // postItemImage handles cover upload. Only playlists are writable here; album/artist covers come
-// from scanning. The body is always drained first (even on the not-implemented path) because
-// Finamp writes it synchronously and sees a broken pipe if we respond before reading it.
+// from scanning. Past the auth and id gates the body is drained before answering — including on the
+// not-implemented path — because Finamp writes it synchronously and would see a broken pipe.
 func (api *Router) postItemImage(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := dto.DecodeID(chi.URLParam(r, "itemId"))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 
 	// Honor the same artwork-upload gate and size cap as the native endpoint.
 	u, _ := request.UserFrom(ctx)
@@ -143,7 +147,10 @@ func (api *Router) postItemImage(w http.ResponseWriter, r *http.Request) {
 // deleteItemImage removes a playlist's uploaded cover. Only playlists are supported.
 func (api *Router) deleteItemImage(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := dto.DecodeID(chi.URLParam(r, "itemId"))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 
 	if _, err := api.playlists.Get(ctx, id); err != nil {
 		http.Error(w, "Not Implemented", http.StatusNotImplemented)
diff --git a/server/jellyfin/images_test.go b/server/jellyfin/images_test.go
index bdd47e956..0e0d6220d 100644
--- a/server/jellyfin/images_test.go
+++ b/server/jellyfin/images_test.go
@@ -63,16 +63,29 @@ func newImageRequest(itemId string) (*httptest.ResponseRecorder, *http.Request)
 var _ = Describe("Images", func() {
 	It("streams album artwork", func() {
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 		fa := &fakeArtwork{}
 		api := &Router{ds: ds, artwork: fa}
 
-		w, r := newImageRequest(dto.EncodeID("a1"))
+		w, r := newImageRequest(dto.EncodeID(testID("a1")))
 		api.getItemImage(w, r)
 
 		Expect(w.Code).To(Equal(http.StatusOK))
 		Expect(w.Body.String()).To(Equal("IMG"))
-		Expect(fa.recvId).To(ContainSubstring("a1"))
+		Expect(fa.recvId).To(ContainSubstring(testID("a1")))
+	})
+
+	// A malformed itemId now 404s via itemIDParam instead of falling through to a placeholder image.
+	It("404s a malformed itemId instead of serving a placeholder", func() {
+		ds := &tests.MockDataStore{}
+		fa := &fakeArtwork{}
+		api := &Router{ds: ds, artwork: fa}
+
+		w, r := newImageRequest("not-a-valid-id")
+		api.getItemImage(w, r)
+
+		Expect(w.Code).To(Equal(http.StatusNotFound))
+		Expect(fa.recvId).To(BeEmpty(), "artwork resolution must not run for an undecodable id")
 	})
 
 	// resolveArtworkID probes the entity tables, so a deleted item yields no artwork id at all.
@@ -81,22 +94,23 @@ var _ = Describe("Images", func() {
 		fa := &fakeArtwork{}
 		api := &Router{ds: ds, artwork: fa}
 
-		w, r := newImageRequest(dto.EncodeID("deleted-item"))
+		w, r := newImageRequest(dto.EncodeID(testID("deleted-item")))
 		api.getItemImage(w, r)
 
+		// 200 here is what separates a well-formed unknown id from a malformed one, which 404s.
+		Expect(w.Code).To(Equal(http.StatusOK))
 		Expect(fa.recvId).To(BeEmpty(), "an empty artwork id can only yield a placeholder")
-		Expect(w.Body.String()).ToNot(ContainSubstring("deleted-item"))
 	})
 
 	It("sniffs the Content-Type instead of hardcoding it", func() {
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 
 		png := append([]byte{0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n'}, make([]byte, 512)...)
 		fa := &fakeArtwork{data: png}
 		api := &Router{ds: ds, artwork: fa}
 
-		w, r := newImageRequest(dto.EncodeID("a1"))
+		w, r := newImageRequest(dto.EncodeID(testID("a1")))
 		api.getItemImage(w, r)
 
 		Expect(w.Code).To(Equal(http.StatusOK))
@@ -105,15 +119,15 @@ var _ = Describe("Images", func() {
 
 	It("resolves a playlist's cover regardless of visibility, even for an anonymous caller", func() {
 		ds := &tests.MockDataStore{}
-		ds.Playlist(context.Background()).(*tests.MockPlaylistRepo).SetData(model.Playlists{{ID: "pl1", Name: "Mix", OwnerID: "someone"}})
+		ds.Playlist(context.Background()).(*tests.MockPlaylistRepo).SetData(model.Playlists{{ID: testID("pl1"), Name: "Mix", OwnerID: testID("someone")}})
 		fa := &fakeArtwork{}
 		api := &Router{ds: ds, artwork: fa}
 
-		w, r := newImageRequest(dto.EncodeID("pl1"))
+		w, r := newImageRequest(dto.EncodeID(testID("pl1")))
 		api.getItemImage(w, r)
 
 		Expect(w.Code).To(Equal(http.StatusOK))
-		Expect(fa.recvId).To(ContainSubstring("pl1"))
+		Expect(fa.recvId).To(ContainSubstring(testID("pl1")))
 	})
 
 	// This endpoint is public (no user in the request), so artwork must be resolved under an
@@ -121,11 +135,11 @@ var _ = Describe("Images", func() {
 	// silently falls back to the placeholder.
 	It("resolves artwork under an elevated admin context", func() {
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 		fa := &fakeArtwork{}
 		api := &Router{ds: ds, artwork: fa}
 
-		w, r := newImageRequest(dto.EncodeID("a1"))
+		w, r := newImageRequest(dto.EncodeID(testID("a1")))
 		api.getItemImage(w, r)
 
 		Expect(w.Code).To(Equal(http.StatusOK))
@@ -137,11 +151,11 @@ var _ = Describe("Images", func() {
 	It("serves immutable when the tag param asserts the current hash", func() {
 		const hash = "0123456789abcdef"
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 		fa := &fakeArtwork{hash: hash}
 		api := &Router{ds: ds, artwork: fa}
 
-		w, r := newImageRequest(dto.EncodeID("a1"))
+		w, r := newImageRequest(dto.EncodeID(testID("a1")))
 		q := r.URL.Query()
 		q.Set("tag", hash)
 		r.URL.RawQuery = q.Encode()
@@ -155,11 +169,11 @@ var _ = Describe("Images", func() {
 	It("revalidates via no-cache when no tag is provided", func() {
 		const hash = "0123456789abcdef"
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 		fa := &fakeArtwork{hash: hash}
 		api := &Router{ds: ds, artwork: fa}
 
-		w, r := newImageRequest(dto.EncodeID("a1"))
+		w, r := newImageRequest(dto.EncodeID(testID("a1")))
 		api.getItemImage(w, r)
 
 		Expect(w.Code).To(Equal(http.StatusOK))
@@ -199,21 +213,21 @@ var _ = Describe("postItemImage", func() {
 	var fp *fakePlaylists
 
 	BeforeEach(func() {
-		fp = &fakePlaylists{getByIDPls: &model.Playlist{ID: "pl1"}}
+		fp = &fakePlaylists{getByIDPls: &model.Playlist{ID: testID("pl1")}}
 		api = &Router{playlists: fp}
 	})
 
 	It("uploads a raw JPEG body and returns 204", func() {
 		body := jpegBytes()
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(body))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(body))
 		r.Header.Set("Content-Type", "image/jpeg")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
 		Expect(w.Code).To(Equal(http.StatusNoContent))
-		Expect(fp.setImagePlaylistID).To(Equal("pl1"))
+		Expect(fp.setImagePlaylistID).To(Equal(testID("pl1")))
 		Expect(fp.setImageBytes).To(Equal(body))
 		Expect(fp.setImageExt).To(Equal(".jpeg"))
 	})
@@ -222,9 +236,9 @@ var _ = Describe("postItemImage", func() {
 		raw := pngBytes()
 		encoded := base64.StdEncoding.EncodeToString(raw)
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader([]byte(encoded)))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader([]byte(encoded)))
 		r.Header.Set("Content-Type", "image/jpeg") // lies: the payload is a PNG
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -238,9 +252,9 @@ var _ = Describe("postItemImage", func() {
 		fp.getByIDErr = model.ErrNotFound
 		bodyReader := bytes.NewReader([]byte("some-bytes-that-must-be-drained"))
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("al1")+"/Images/Primary", bodyReader)
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("al1"))+"/Images/Primary", bodyReader)
 		r.Header.Set("Content-Type", "image/jpeg")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("al1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("al1")))
 
 		api.postItemImage(w, r)
 
@@ -251,9 +265,9 @@ var _ = Describe("postItemImage", func() {
 	It("returns 500 when the service fails", func() {
 		fp.setImageErr = errors.New("boom")
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(jpegBytes()))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(jpegBytes()))
 		r.Header.Set("Content-Type", "image/jpeg")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -263,9 +277,9 @@ var _ = Describe("postItemImage", func() {
 	It("accepts a raw WebP body", func() {
 		body := webpBytes()
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(body))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(body))
 		r.Header.Set("Content-Type", "image/webp")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -277,9 +291,9 @@ var _ = Describe("postItemImage", func() {
 	It("accepts a raw GIF body", func() {
 		body := gifBytes()
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(body))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(body))
 		r.Header.Set("Content-Type", "image/gif")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -292,9 +306,9 @@ var _ = Describe("postItemImage", func() {
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.MaxImageUploadSize = "16" // 16 bytes
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(jpegBytes()))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(jpegBytes()))
 		r.Header.Set("Content-Type", "image/jpeg")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -310,9 +324,9 @@ var _ = Describe("postItemImage", func() {
 		body := []byte(base64.StdEncoding.EncodeToString(img))
 		Expect(len(body)).To(BeNumerically(">", len(img)))
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(body))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(body))
 		r.Header.Set("Content-Type", "image/png")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -326,9 +340,9 @@ var _ = Describe("postItemImage", func() {
 		conf.Server.MaxImageUploadSize = strconv.Itoa(len(img) - 1)
 		body := []byte(base64.StdEncoding.EncodeToString(img))
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(body))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(body))
 		r.Header.Set("Content-Type", "image/png")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -338,9 +352,9 @@ var _ = Describe("postItemImage", func() {
 
 	It("rejects a body that is neither an image nor base64 with 400", func() {
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", strings.NewReader("!!not base64!!"))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", strings.NewReader("!!not base64!!"))
 		r.Header.Set("Content-Type", "image/jpeg")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -351,9 +365,9 @@ var _ = Describe("postItemImage", func() {
 	It("rejects bytes that sniff as an image but don't decode (e.g. a truncated or renamed file)", func() {
 		body := []byte{0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 'J', 'F', 'I', 'F'} // JPEG magic, not a JPEG
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(body))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(body))
 		r.Header.Set("Content-Type", "image/jpeg")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.postItemImage(w, r)
 
@@ -365,10 +379,10 @@ var _ = Describe("postItemImage", func() {
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.EnableArtworkUpload = false
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(jpegBytes()))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(jpegBytes()))
 		r.Header.Set("Content-Type", "image/jpeg")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
-		r = r.WithContext(request.WithUser(r.Context(), model.User{ID: "u1", IsAdmin: false}))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
+		r = r.WithContext(request.WithUser(r.Context(), model.User{ID: testID("u1"), IsAdmin: false}))
 
 		api.postItemImage(w, r)
 
@@ -380,10 +394,10 @@ var _ = Describe("postItemImage", func() {
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.EnableArtworkUpload = false
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", bytes.NewReader(jpegBytes()))
+		r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", bytes.NewReader(jpegBytes()))
 		r.Header.Set("Content-Type", "image/jpeg")
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
-		r = r.WithContext(request.WithUser(r.Context(), model.User{ID: "admin", IsAdmin: true}))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
+		r = r.WithContext(request.WithUser(r.Context(), model.User{ID: testID("admin"), IsAdmin: true}))
 
 		api.postItemImage(w, r)
 
@@ -393,24 +407,24 @@ var _ = Describe("postItemImage", func() {
 
 var _ = Describe("deleteItemImage", func() {
 	It("removes the playlist image and returns 204", func() {
-		fp := &fakePlaylists{getByIDPls: &model.Playlist{ID: "pl1"}}
+		fp := &fakePlaylists{getByIDPls: &model.Playlist{ID: testID("pl1")}}
 		api := &Router{playlists: fp}
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("DELETE", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", nil)
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r := httptest.NewRequest("DELETE", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", nil)
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.deleteItemImage(w, r)
 
 		Expect(w.Code).To(Equal(http.StatusNoContent))
-		Expect(fp.removeImagePlaylistID).To(Equal("pl1"))
+		Expect(fp.removeImagePlaylistID).To(Equal(testID("pl1")))
 	})
 
 	It("returns 501 for a non-playlist item", func() {
 		fp := &fakePlaylists{getByIDErr: model.ErrNotFound}
 		api := &Router{playlists: fp}
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("DELETE", "/Items/"+dto.EncodeID("al1")+"/Images/Primary", nil)
-		r = withChiURLParam(r, "itemId", dto.EncodeID("al1"))
+		r := httptest.NewRequest("DELETE", "/Items/"+dto.EncodeID(testID("al1"))+"/Images/Primary", nil)
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("al1")))
 
 		api.deleteItemImage(w, r)
 
@@ -418,11 +432,11 @@ var _ = Describe("deleteItemImage", func() {
 	})
 
 	It("returns 500 when the service fails", func() {
-		fp := &fakePlaylists{getByIDPls: &model.Playlist{ID: "pl1"}, removeImageErr: errors.New("boom")}
+		fp := &fakePlaylists{getByIDPls: &model.Playlist{ID: testID("pl1")}, removeImageErr: errors.New("boom")}
 		api := &Router{playlists: fp}
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("DELETE", "/Items/"+dto.EncodeID("pl1")+"/Images/Primary", nil)
-		r = withChiURLParam(r, "itemId", dto.EncodeID("pl1"))
+		r := httptest.NewRequest("DELETE", "/Items/"+dto.EncodeID(testID("pl1"))+"/Images/Primary", nil)
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("pl1")))
 
 		api.deleteItemImage(w, r)
 
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index fed5bbbc8..de0da88eb 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -2,6 +2,7 @@ package jellyfin
 
 import (
 	"context"
+	"errors"
 	"io"
 	"iter"
 	"net/http"
@@ -10,7 +11,6 @@ import (
 	"strings"
 
 	"github.com/Masterminds/squirrel"
-	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -34,6 +34,10 @@ func searchTerm(p *req.Values) string {
 func (api *Router) getItems(w http.ResponseWriter, r *http.Request) {
 	res, err := api.queryItems(r.Context(), r)
 	if err != nil {
+		if errors.Is(err, model.ErrNotFound) {
+			http.Error(w, "Not Found", http.StatusNotFound)
+			return
+		}
 		api.internalError(w, r, err)
 		return
 	}
@@ -229,12 +233,37 @@ type itemsQuery struct {
 
 // parseItemsQuery also resolves the entity types (inferring them from the parent when
 // IncludeItemTypes is absent) and the library scope. Query keys are read lowercase because
-// normalizeQueryKeys folded them (Jellyfin binds case-insensitively).
-func (api *Router) parseItemsQuery(ctx context.Context, r *http.Request) itemsQuery {
+// normalizeQueryKeys folded them (Jellyfin binds case-insensitively). A non-empty id param that
+// fails to decode reports model.ErrNotFound rather than silently dropping the filter (see decodeFilterParam).
+func (api *Router) parseItemsQuery(ctx context.Context, r *http.Request) (itemsQuery, error) {
 	p := req.Params(r)
+	parentId, ok := decodeFilterParam(p.StringOr("parentid", ""))
+	if !ok {
+		return itemsQuery{}, model.ErrNotFound
+	}
+	// Any malformed entry in one of these id lists must 404, not silently drop out of the filter
+	// (see dto.DecodeIDs) — an all-malformed list would otherwise widen the query to everything.
+	ids, ok := decodedQueryIDs(r, "ids")
+	if !ok {
+		return itemsQuery{}, model.ErrNotFound
+	}
+	// Finamp's genre screen sends ParentId=<libraryId> for scoping plus GenreIds for the genre.
+	genreIds, ok := decodedQueryIDs(r, "genreids")
+	if !ok {
+		return itemsQuery{}, model.ErrNotFound
+	}
+	// Feishin fetches an album's tracks with AlbumIds instead of ParentId.
+	albumIds, ok := decodedQueryIDs(r, "albumids")
+	if !ok {
+		return itemsQuery{}, model.ErrNotFound
+	}
+	studioIds, ok := decodedQueryIDs(r, "studioids")
+	if !ok {
+		return itemsQuery{}, model.ErrNotFound
+	}
 	q := itemsQuery{
 		fields:    dto.ParseFields(p.Strings("fields")...),
-		ids:       decodedQueryIDs(r, "ids"),
+		ids:       ids,
 		rawTypes:  p.StringOr("includeitemtypes", ""),
 		search:    searchTerm(p),
 		sortBy:    p.StringOr("sortby", ""),
@@ -243,20 +272,22 @@ func (api *Router) parseItemsQuery(ctx context.Context, r *http.Request) itemsQu
 		limit:     p.IntOr("limit", 0),
 		// Clients express "favorites only" two ways: Filters=IsFavorite and the standalone
 		// isFavorite=true param (Finamp's "Favourite tracks" widget uses the latter).
-		favOnly:  strings.Contains(p.StringOr("filters", ""), "IsFavorite") || p.BoolOr("isfavorite", false),
-		parentId: dto.DecodeID(p.StringOr("parentid", "")),
-		// Finamp's genre screen sends ParentId=<libraryId> for scoping plus GenreIds for the genre.
-		genreIds: decodedQueryIDs(r, "genreids"),
-		// Feishin fetches an album's tracks with AlbumIds instead of ParentId.
-		albumIds:  decodedQueryIDs(r, "albumids"),
+		favOnly:   strings.Contains(p.StringOr("filters", ""), "IsFavorite") || p.BoolOr("isfavorite", false),
+		parentId:  parentId,
+		genreIds:  genreIds,
+		albumIds:  albumIds,
 		years:     parseYears(r),
-		studioIds: decodedQueryIDs(r, "studioids"),
+		studioIds: studioIds,
 	}
 	// An artist's page filters by artist, not ParentId: Finamp sends ParentId=<libraryId> for scoping
 	// plus AlbumArtistIds/ArtistIds/contributingArtistIds for the artist.
 	albumArtistScope := firstNonEmpty(p.StringOr("albumartistids", ""), p.StringOr("artistids", ""))
 	contributingScope := p.StringOr("contributingartistids", "")
-	q.artistId = firstDecodedID(firstNonEmpty(albumArtistScope, contributingScope))
+	artistId, ok := firstDecodedID(firstNonEmpty(albumArtistScope, contributingScope))
+	if !ok {
+		return itemsQuery{}, model.ErrNotFound
+	}
+	q.artistId = artistId
 	q.contributingOnly = albumArtistScope == "" && contributingScope != ""
 
 	q.types = parseTypes(q.rawTypes)
@@ -272,7 +303,7 @@ func (api *Router) parseItemsQuery(ctx context.Context, r *http.Request) itemsQu
 	// (Jellify opens albums this way). An artist parent keeps parseTypes' MusicAlbum default (browse
 	// its albums).
 	if q.rawTypes == "" && q.parentId != "" && !q.isLibraryParent {
-		if q.parentId == playlistsFolderID {
+		if q.parentId == dto.PlaylistsFolderID {
 			// Browsing into the synthetic playlists folder lists the user's playlists.
 			q.types = []string{"Playlist"}
 		} else if _, err := api.ds.Album(ctx).Get(q.parentId); err == nil {
@@ -285,14 +316,17 @@ func (api *Router) parseItemsQuery(ctx context.Context, r *http.Request) itemsQu
 	if q.isLibraryParent || len(q.types) > 1 {
 		q.entityParent = ""
 	}
-	return q
+	return q, nil
 }
 
 // queryItems is the /Items dispatcher: it resolves the request to entity types and queries each via
 // the matching listXxx, merging multi-type results into one paginated list (as Finamp's favorites
 // screen requests).
 func (api *Router) queryItems(ctx context.Context, r *http.Request) (itemsResult, error) {
-	q := api.parseItemsQuery(ctx, r)
+	q, err := api.parseItemsQuery(ctx, r)
+	if err != nil {
+		return itemsResult{}, err
+	}
 	switch {
 	// /Items?ids= is a batch-fetch-by-id that bypasses the type dispatch.
 	case len(q.ids) > 0:
@@ -322,7 +356,7 @@ func (api *Router) queryItems(ctx context.Context, r *http.Request) (itemsResult
 // ok is false when ParentId isn't a visible playlist, so the caller falls through to the type
 // dispatch: ParentId is usually an album or artist.
 func (api *Router) playlistTracksRepo(ctx context.Context, q itemsQuery) (model.PlaylistTrackRepository, bool) {
-	if q.parentId == "" || q.isLibraryParent || q.parentId == playlistsFolderID {
+	if q.parentId == "" || q.isLibraryParent || q.parentId == dto.PlaylistsFolderID {
 		return nil, false
 	}
 	// Tracks enforces visibility.
@@ -450,18 +484,20 @@ func firstNonEmpty(vals ...string) string {
 	return ""
 }
 
-// firstDecodedID decodes the first id from a (possibly comma-separated) Jellyfin id list.
-func firstDecodedID(s string) string {
+// firstDecodedID decodes the first id from a (possibly comma-separated) Jellyfin id list, reporting
+// whether it decoded successfully (see decodeFilterParam).
+func firstDecodedID(s string) (string, bool) {
 	if s == "" {
-		return ""
+		return "", true
 	}
 	first, _, _ := strings.Cut(s, ",")
-	return dto.DecodeID(strings.TrimSpace(first))
+	return decodeFilterParam(strings.TrimSpace(first))
 }
 
-// decodedQueryIDs reads an id-list param in both client spellings (see queryIDs), decoding each id.
-func decodedQueryIDs(r *http.Request, key string) []string {
-	return slice.Map(queryIDs(r, key), dto.DecodeID)
+// decodedQueryIDs reads an id-list param in both client spellings (see queryIDs). ok is false if
+// any entry is malformed, so a dropped entry can't shrink the list into an empty, no-op filter.
+func decodedQueryIDs(r *http.Request, key string) ([]string, bool) {
+	return dto.DecodeIDs(queryIDs(r, key))
 }
 
 // parseYears reads Years= as a discrete list, accepting comma-separated and repeated params.
@@ -740,7 +776,7 @@ func (api *Router) listPlaylists(ctx context.Context, opts model.QueryOptions, q
 // to their library, so an id can't probe content outside the user's libraries.
 func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fields) (dto.BaseItemDto, bool) {
 	// The synthetic playlists folder must resolve by the id we advertised, not 404.
-	if id == playlistsFolderID {
+	if id == dto.PlaylistsFolderID {
 		return playlistsFolder(), true
 	}
 	u, _ := request.UserFrom(ctx)
@@ -802,14 +838,11 @@ func (api *Router) songsByIDs(ctx context.Context, ids []string) map[string]mode
 }
 
 // itemsByIDs resolves a decoded id list, keeping input order and skipping unresolvable ids.
-// A Finamp-truncated id is resolved by prefix but echoed as requested — Finamp matches restored
-// queue items against its stored (truncated) ids.
 func (api *Router) itemsByIDs(ctx context.Context, ids []string, fields dto.Fields) dto.QueryResult {
 	u, _ := request.UserFrom(ctx)
-	fullIDs := api.resolveItemIDs(ctx, ids)
-	songs := api.songsByIDs(ctx, fullIDs)
+	songs := api.songsByIDs(ctx, ids)
 	var items []dto.BaseItemDto
-	for i, id := range fullIDs {
+	for _, id := range ids {
 		var item dto.BaseItemDto
 		if mf, ok := songs[id]; ok {
 			if !u.HasLibraryAccess(mf.LibraryID) {
@@ -819,16 +852,16 @@ func (api *Router) itemsByIDs(ctx context.Context, ids []string, fields dto.Fiel
 		} else if item, ok = api.resolveItemByID(ctx, id, fields); !ok {
 			continue
 		}
-		if id != ids[i] {
-			item.Id = dto.EncodeID(ids[i])
-		}
 		items = append(items, item)
 	}
 	return result(items, len(items), 0)
 }
 
 func (api *Router) getItem(w http.ResponseWriter, r *http.Request) {
-	id := api.resolveItemID(r.Context(), dto.DecodeID(chi.URLParam(r, "itemId")))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	fields := dto.ParseFields(req.Params(r).Strings("fields")...)
 	if item, ok := api.resolveItemByID(r.Context(), id, fields); ok {
 		api.ok(w, r, item)
@@ -841,7 +874,10 @@ func (api *Router) getItem(w http.ResponseWriter, r *http.Request) {
 // scanning), so a non-playlist id 404s. core/playlists.Delete enforces ownership.
 func (api *Router) deleteItem(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := dto.DecodeID(chi.URLParam(r, "itemId"))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	if err := api.playlists.Delete(ctx, id); err != nil {
 		api.playlistError(w, r, err)
 		return
diff --git a/server/jellyfin/items_test.go b/server/jellyfin/items_test.go
index 3213379e5..b227ab719 100644
--- a/server/jellyfin/items_test.go
+++ b/server/jellyfin/items_test.go
@@ -6,6 +6,8 @@ import (
 	"fmt"
 	"net/http"
 	"net/http/httptest"
+	"slices"
+	"strings"
 
 	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/model"
@@ -30,14 +32,14 @@ var _ = Describe("Items", func() {
 	var fp *fakePlaylists
 	// alice has access to library 1 only; used by tests that don't care about scoping.
 	ctxUser := func() context.Context {
-		return request.WithUser(context.Background(), model.User{ID: "u1", UserName: "alice", Libraries: model.Libraries{{ID: 1, Name: "Music"}}})
+		return request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: model.Libraries{{ID: 1, Name: "Music"}}})
 	}
 	ctxUserWithLibraries := func(libs model.Libraries) context.Context {
-		return request.WithUser(context.Background(), model.User{ID: "u1", UserName: "alice", Libraries: libs})
+		return request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: libs})
 	}
 	// admin has no explicit Libraries; access is granted via the IsAdmin bypass, not membership.
 	ctxAdmin := func() context.Context {
-		return request.WithUser(context.Background(), model.User{ID: "admin", IsAdmin: true, Libraries: nil})
+		return request.WithUser(context.Background(), model.User{ID: testID("admin"), IsAdmin: true, Libraries: nil})
 	}
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
@@ -47,7 +49,7 @@ var _ = Describe("Items", func() {
 
 	Describe("getItems", func() {
 		It("lists albums when IncludeItemTypes=MusicAlbum", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}, {ID: "a2", Name: "Two"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&Recursive=true", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -60,44 +62,44 @@ var _ = Describe("Items", func() {
 		})
 
 		It("lists an album's songs when ParentId is an album and type is Audio", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "Song", AlbumID: "a1"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", AlbumID: testID("a1")}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("a1")+"&IncludeItemTypes=Audio", nil).WithContext(ctxUser())
+			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("a1"))+"&IncludeItemTypes=Audio", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.Items).To(HaveLen(1))
 			Expect(res.Items[0].Type).To(Equal("Audio"))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("s1")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
 		})
 
 		It("lists a playlist's tracks when ParentId is a playlist, whatever the type", func() {
-			fp.getPls = &model.Playlist{ID: "pl1", Tracks: model.PlaylistTracks{
-				{ID: "1", MediaFileID: "s1", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s1"}},
-				{ID: "2", MediaFileID: "s2", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s2"}},
+			fp.getPls = &model.Playlist{ID: testID("pl1"), Tracks: model.PlaylistTracks{
+				{ID: "1", MediaFileID: testID("s1"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s1")}},
+				{ID: "2", MediaFileID: testID("s2"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s2")}},
 			}}
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("pl1")+"&IncludeItemTypes=Audio", nil).
+			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("pl1"))+"&IncludeItemTypes=Audio", nil).
 				WithContext(ctxUser())
 			invoke(api.getItems, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.Items).To(HaveLen(2))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("s1")))
-			Expect(res.Items[0].PlaylistItemId).To(Equal(dto.EncodeID("1")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
+			Expect(res.Items[0].PlaylistItemId).To(Equal(dto.EncodePlaylistEntryID("1")))
 			Expect(res.TotalRecordCount).To(Equal(2))
 		})
 
 		It("pages a playlist parent's tracks in the query, not in memory", func() {
-			fp.getPls = &model.Playlist{ID: "pl1", Tracks: model.PlaylistTracks{
-				{ID: "1", MediaFileID: "s1", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s1"}},
-				{ID: "2", MediaFileID: "s2", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s2"}},
-				{ID: "3", MediaFileID: "s3", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s3"}},
+			fp.getPls = &model.Playlist{ID: testID("pl1"), Tracks: model.PlaylistTracks{
+				{ID: "1", MediaFileID: testID("s1"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s1")}},
+				{ID: "2", MediaFileID: testID("s2"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s2")}},
+				{ID: "3", MediaFileID: testID("s3"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s3")}},
 			}}
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("pl1")+"&StartIndex=1&Limit=1", nil).
+			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("pl1"))+"&StartIndex=1&Limit=1", nil).
 				WithContext(ctxUser())
 			invoke(api.getItems, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
@@ -105,24 +107,24 @@ var _ = Describe("Items", func() {
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.TotalRecordCount).To(Equal(3))
 			Expect(res.Items).To(HaveLen(1))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("s2")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s2"))))
 			Expect(fp.tracksRepo.Options.Offset).To(Equal(1))
 			Expect(fp.tracksRepo.Options.Max).To(Equal(1))
 		})
 
 		It("falls through to the type dispatch when ParentId is not a playlist", func() {
 			fp.getErr = model.ErrNotFound
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", AlbumID: "a1"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), AlbumID: testID("a1")}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("a1")+"&IncludeItemTypes=Audio", nil).
+			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("a1"))+"&IncludeItemTypes=Audio", nil).
 				WithContext(ctxUser())
 			invoke(api.getItems, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.Items).To(HaveLen(1))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("s1")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
 		})
 
 		It("returns 500 when the song cursor fails to open, instead of a truncated 200", func() {
@@ -137,13 +139,13 @@ var _ = Describe("Items", func() {
 		// looking for tracks outside any album; answering with every track streams the whole library.
 		Describe("Recursive=false", func() {
 			BeforeEach(func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", AlbumID: "a1"}})
+				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), AlbumID: testID("a1")}})
 			})
 
 			It("returns no songs for a library parent, as tracks are never its direct children", func() {
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("1")+"&IncludeItemTypes=Audio&Recursive=false", nil).
+				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeLibraryID(1)+"&IncludeItemTypes=Audio&Recursive=false", nil).
 					WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				Expect(w.Code).To(Equal(http.StatusOK))
@@ -155,7 +157,7 @@ var _ = Describe("Items", func() {
 
 			It("drops only Audio from a multi-type library query", func() {
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("1")+"&IncludeItemTypes=Audio,MusicAlbum&Recursive=false", nil).
+				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeLibraryID(1)+"&IncludeItemTypes=Audio,MusicAlbum&Recursive=false", nil).
 					WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				var res dto.QueryResult
@@ -166,7 +168,7 @@ var _ = Describe("Items", func() {
 
 			It("still lists albums for a library parent, as they are its direct children", func() {
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("1")+"&IncludeItemTypes=MusicAlbum&Recursive=false", nil).
+				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeLibraryID(1)+"&IncludeItemTypes=MusicAlbum&Recursive=false", nil).
 					WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				var res dto.QueryResult
@@ -177,13 +179,13 @@ var _ = Describe("Items", func() {
 			It("still lists an album's tracks, as they are its direct children", func() {
 				fp.getErr = model.ErrNotFound
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("a1")+"&IncludeItemTypes=Audio&Recursive=false", nil).
+				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("a1"))+"&IncludeItemTypes=Audio&Recursive=false", nil).
 					WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				var res dto.QueryResult
 				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 				Expect(res.Items).To(HaveLen(1))
-				Expect(res.Items[0].Id).To(Equal(dto.EncodeID("s1")))
+				Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
 			})
 
 			It("keeps returning every song when no parent scopes the query", func() {
@@ -199,7 +201,7 @@ var _ = Describe("Items", func() {
 			// `recursive ?? false`, so an omitted Recursive is a non-recursive request.
 			It("treats an omitted Recursive as false, like Jellyfin", func() {
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("1")+"&IncludeItemTypes=Audio", nil).
+				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeLibraryID(1)+"&IncludeItemTypes=Audio", nil).
 					WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				var res dto.QueryResult
@@ -209,9 +211,9 @@ var _ = Describe("Items", func() {
 		})
 
 		It("lists an artist's albums when ParentId is an artist and type is MusicAlbum", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One", AlbumArtistID: "ar1"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", AlbumArtistID: testID("ar1")}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("ar1")+"&IncludeItemTypes=MusicAlbum", nil).WithContext(ctxUser())
+			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("ar1"))+"&IncludeItemTypes=MusicAlbum", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
@@ -223,7 +225,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("lists artists when IncludeItemTypes=MusicArtist", func() {
-			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicArtist", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -244,7 +246,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("lists playlists when IncludeItemTypes=Playlist", func() {
-			ds.Playlist(context.Background()).(*tests.MockPlaylistRepo).SetData(model.Playlists{{ID: "p1", Name: "My Mix", SongCount: 5}})
+			ds.Playlist(context.Background()).(*tests.MockPlaylistRepo).SetData(model.Playlists{{ID: testID("p1"), Name: "My Mix", SongCount: 5}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Playlist", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -253,13 +255,13 @@ var _ = Describe("Items", func() {
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.Items).To(HaveLen(1))
 			Expect(res.Items[0].Type).To(Equal("Playlist"))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("p1")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("p1"))))
 			Expect(res.TotalRecordCount).To(Equal(1))
 		})
 
 		It("merges results from every requested type in IncludeItemTypes", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "Song"}})
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -274,11 +276,11 @@ var _ = Describe("Items", func() {
 
 		It("merges favorite songs, albums, and playlists", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song"}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			playlistRepo := ds.Playlist(context.Background()).(*tests.MockPlaylistRepo)
-			playlistRepo.SetData(model.Playlists{{ID: "p1", Name: "My Mix", Annotations: model.Annotations{Starred: true}}})
+			playlistRepo.SetData(model.Playlists{{ID: testID("p1"), Name: "My Mix", Annotations: model.Annotations{Starred: true}}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum,Playlist&Filters=IsFavorite", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -298,8 +300,8 @@ var _ = Describe("Items", func() {
 		})
 
 		It("applies StartIndex/Limit to the merged multi-type result set", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "Song"}, {ID: "s2", Title: "Song2"}})
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}, {ID: "a2", Name: "Two"}})
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}, {ID: testID("s2"), Title: "Song2"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&StartIndex=1&Limit=2", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -313,9 +315,9 @@ var _ = Describe("Items", func() {
 
 		It("caps each per-type query at StartIndex+Limit instead of fetching everything", func() {
 			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-			mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song"}, {ID: "s2", Title: "Song2"}})
+			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}, {ID: testID("s2"), Title: "Song2"}})
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}, {ID: "a2", Name: "Two"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&StartIndex=1&Limit=2", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -327,7 +329,7 @@ var _ = Describe("Items", func() {
 
 		It("applies a starred filter when Filters=IsFavorite", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&Filters=IsFavorite", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -339,7 +341,7 @@ var _ = Describe("Items", func() {
 
 		It("forwards SearchTerm to the repo's Search method", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=one", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -351,7 +353,7 @@ var _ = Describe("Items", func() {
 
 		It("caps a search the client left unbounded", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=one", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -361,7 +363,7 @@ var _ = Describe("Items", func() {
 
 		It("honors an explicit search Limit up to the ceiling", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=one&Limit=500", nil).
 				WithContext(ctxUser())
@@ -372,7 +374,7 @@ var _ = Describe("Items", func() {
 
 		It("clamps a search Limit that would materialize the library", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=one&Limit=999999", nil).
 				WithContext(ctxUser())
@@ -383,7 +385,7 @@ var _ = Describe("Items", func() {
 
 		It("treats an all-whitespace SearchTerm as no search, streaming the unfiltered list", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}, {ID: "a2", Name: "Two"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=%20%20", nil).
 				WithContext(ctxUser())
@@ -398,10 +400,10 @@ var _ = Describe("Items", func() {
 		It("reports a multi-type search total past the page, so clients keep paging", func() {
 			songs := make(model.MediaFiles, defaultSearchLimit*2)
 			for i := range songs {
-				songs[i] = model.MediaFile{ID: fmt.Sprintf("s%05d", i), Title: "Song"}
+				songs[i] = model.MediaFile{ID: testID(fmt.Sprintf("s%05d", i)), Title: "Song"}
 			}
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&Limit=10", nil).
 				WithContext(ctxUser())
@@ -415,8 +417,8 @@ var _ = Describe("Items", func() {
 
 		It("bounds the multi-type search window however large StartIndex is", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "Song"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&StartIndex=500000&Limit=1", nil).
 				WithContext(ctxUser())
@@ -431,10 +433,10 @@ var _ = Describe("Items", func() {
 			// past that window the merged order is no longer the true one.
 			songs := make(model.MediaFiles, maxSearchLimit+1)
 			for i := range songs {
-				songs[i] = model.MediaFile{ID: fmt.Sprintf("s%05d", i), Title: "Song"}
+				songs[i] = model.MediaFile{ID: testID(fmt.Sprintf("s%05d", i)), Title: "Song"}
 			}
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET",
 				fmt.Sprintf("/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&StartIndex=%d&Limit=1", maxSearchLimit),
@@ -450,10 +452,12 @@ var _ = Describe("Items", func() {
 		It("serves the last page below the ceiling in full", func() {
 			songs := make(model.MediaFiles, maxSearchLimit+1)
 			for i := range songs {
-				songs[i] = model.MediaFile{ID: fmt.Sprintf("s%05d", i), Title: "Song"}
+				songs[i] = model.MediaFile{ID: testID(fmt.Sprintf("s%05d", i)), Title: "Song"}
 			}
+			// The mock repo returns rows sorted by ID; reorder to match so index-based assertions hold.
+			slices.SortFunc(songs, func(a, b model.MediaFile) int { return strings.Compare(a.ID, b.ID) })
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET",
 				fmt.Sprintf("/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&StartIndex=%d&Limit=10", maxSearchLimit-1),
@@ -470,10 +474,10 @@ var _ = Describe("Items", func() {
 		It("bounds an unbounded multi-type search to the default in total, not per type", func() {
 			songs := make(model.MediaFiles, defaultSearchLimit*2)
 			for i := range songs {
-				songs[i] = model.MediaFile{ID: fmt.Sprintf("s%05d", i), Title: "Song"}
+				songs[i] = model.MediaFile{ID: testID(fmt.Sprintf("s%05d", i)), Title: "Song"}
 			}
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song", nil).
 				WithContext(ctxUser())
@@ -487,10 +491,12 @@ var _ = Describe("Items", func() {
 		It("pages an unbounded multi-type search past the default without dropping matches", func() {
 			songs := make(model.MediaFiles, defaultSearchLimit*2)
 			for i := range songs {
-				songs[i] = model.MediaFile{ID: fmt.Sprintf("s%05d", i), Title: "Song"}
+				songs[i] = model.MediaFile{ID: testID(fmt.Sprintf("s%05d", i)), Title: "Song"}
 			}
+			// The mock repo returns rows sorted by ID; reorder to match so index-based assertions hold.
+			slices.SortFunc(songs, func(a, b model.MediaFile) int { return strings.Compare(a.ID, b.ID) })
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET",
 				fmt.Sprintf("/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&StartIndex=%d", defaultSearchLimit+50),
@@ -506,7 +512,7 @@ var _ = Describe("Items", func() {
 
 		It("reports a search total beyond the fetched page instead of the page length", func() {
 			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{
-				{ID: "r1", Name: "Alpha"}, {ID: "r2", Name: "Beta"}, {ID: "r3", Name: "Gamma"},
+				{ID: testID("r1"), Name: "Alpha"}, {ID: testID("r2"), Name: "Beta"}, {ID: testID("r3"), Name: "Gamma"},
 			})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicArtist&SearchTerm=a&Limit=1", nil).WithContext(ctxUser())
@@ -520,7 +526,7 @@ var _ = Describe("Items", func() {
 
 		It("forwards StartIndex/Limit as Offset/Max", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&StartIndex=5&Limit=10", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -533,31 +539,31 @@ var _ = Describe("Items", func() {
 			// Finamp's download/sync fetches a track's BaseItemDto via /Items?ids=<id>; without
 			// this, queryItems ignored Ids and returned the default type-dispatched list instead.
 			It("returns exactly the requested item when Ids has a single id", func() {
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?Ids="+dto.EncodeID("s1"), nil).WithContext(ctxUser())
+				r := httptest.NewRequest("GET", "/Items?Ids="+dto.EncodeID(testID("s1")), nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				Expect(w.Code).To(Equal(http.StatusOK))
 				var res dto.QueryResult
 				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 				Expect(res.Items).To(HaveLen(1))
-				Expect(res.Items[0].Id).To(Equal(dto.EncodeID("s1")))
+				Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
 				Expect(res.Items[0].Name).To(Equal("Song"))
 				Expect(res.TotalRecordCount).To(Equal(1))
 			})
 
 			It("returns items of different types for a lowercase ids param with multiple ids", func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}})
+				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?ids="+dto.EncodeID("a1")+","+dto.EncodeID("s1"), nil).WithContext(ctxUser())
+				r := httptest.NewRequest("GET", "/Items?ids="+dto.EncodeID(testID("a1"))+","+dto.EncodeID(testID("s1")), nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				Expect(w.Code).To(Equal(http.StatusOK))
 				var res dto.QueryResult
 				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 				Expect(res.Items).To(HaveLen(2))
 				ids := []string{res.Items[0].Id, res.Items[1].Id}
-				Expect(ids).To(ConsistOf(dto.EncodeID("a1"), dto.EncodeID("s1")))
+				Expect(ids).To(ConsistOf(dto.EncodeID(testID("a1")), dto.EncodeID(testID("s1"))))
 				types := []string{res.Items[0].Type, res.Items[1].Type}
 				Expect(types).To(ConsistOf("MusicAlbum", "Audio"))
 				Expect(res.TotalRecordCount).To(Equal(2))
@@ -565,9 +571,9 @@ var _ = Describe("Items", func() {
 
 			It("resolves song ids with one batched IN query, not a Get per id", func() {
 				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-				mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 1}, {ID: "s2", Title: "Song2", LibraryID: 1}})
+				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}, {ID: testID("s2"), Title: "Song2", LibraryID: 1}})
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?ids="+dto.EncodeID("s1")+","+dto.EncodeID("s2"), nil).WithContext(ctxUser())
+				r := httptest.NewRequest("GET", "/Items?ids="+dto.EncodeID(testID("s1"))+","+dto.EncodeID(testID("s2")), nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				Expect(w.Code).To(Equal(http.StatusOK))
 				var res dto.QueryResult
@@ -576,20 +582,20 @@ var _ = Describe("Items", func() {
 				sql, args, err := mfRepo.Options.Filters.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(ContainSubstring("media_file.id IN"))
-				Expect(args).To(ConsistOf("s1", "s2"))
+				Expect(args).To(ConsistOf(testID("s1"), testID("s2")))
 			})
 
 			It("omits an id in a library the user can't access, without erroring the whole batch", func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 2}}) // alice only has access to library 1
+				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 2}}) // alice only has access to library 1
 				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?Ids="+dto.EncodeID("a1")+","+dto.EncodeID("s1"), nil).WithContext(ctxUser())
+				r := httptest.NewRequest("GET", "/Items?Ids="+dto.EncodeID(testID("a1"))+","+dto.EncodeID(testID("s1")), nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
 				Expect(w.Code).To(Equal(http.StatusOK))
 				var res dto.QueryResult
 				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 				Expect(res.Items).To(HaveLen(1))
-				Expect(res.Items[0].Id).To(Equal(dto.EncodeID("a1")))
+				Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("a1"))))
 				Expect(res.TotalRecordCount).To(Equal(1))
 			})
 		})
@@ -597,7 +603,7 @@ var _ = Describe("Items", func() {
 		Describe("sorting", func() {
 			It("maps SortBy=PlayCount to the play_count column", func() {
 				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SortBy=PlayCount", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -607,7 +613,7 @@ var _ = Describe("Items", func() {
 
 			It("maps SortBy=DatePlayed to the play_date column", func() {
 				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-				mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song"}})
+				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&SortBy=DatePlayed", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -617,7 +623,7 @@ var _ = Describe("Items", func() {
 
 			It("uses the first recognized key in a comma-separated SortBy list", func() {
 				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SortBy=DateCreated,SortName", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -627,7 +633,7 @@ var _ = Describe("Items", func() {
 
 			It("skips unrecognized keys in a comma-separated SortBy list to find one that is", func() {
 				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-				mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song"}})
+				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&SortBy=Unknown1,Unknown2,SortName", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -637,7 +643,7 @@ var _ = Describe("Items", func() {
 
 			It("maps Finamp's album view SortBy (ParentIndexNumber,IndexNumber) to disc+track order", func() {
 				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-				mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song"}})
+				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&SortBy=ParentIndexNumber,IndexNumber,SortName", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -647,7 +653,7 @@ var _ = Describe("Items", func() {
 
 			It("leaves Sort at the repo default when no SortBy key is recognized", func() {
 				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SortBy=SeriesSortName", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -659,7 +665,7 @@ var _ = Describe("Items", func() {
 		Describe("library scoping", func() {
 			It("scopes a MusicAlbum listing (no ParentId) to the user's accessible libraries", func() {
 				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}, {ID: 2}}
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum", nil).WithContext(ctxUserWithLibraries(libs))
@@ -673,7 +679,7 @@ var _ = Describe("Items", func() {
 
 			It("scopes a Audio listing (no ParentId) to the user's accessible libraries", func() {
 				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-				mfRepo.SetData(model.MediaFiles{{ID: "s1", Title: "Song"}})
+				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}, {ID: 2}}
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio", nil).WithContext(ctxUserWithLibraries(libs))
@@ -687,7 +693,7 @@ var _ = Describe("Items", func() {
 
 			It("scopes a MusicArtist listing to the user's accessible libraries", func() {
 				artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
-				artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+				artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}, {ID: 2}}
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicArtist", nil).WithContext(ctxUserWithLibraries(libs))
@@ -701,10 +707,10 @@ var _ = Describe("Items", func() {
 
 			It("treats a numeric ParentId matching an accessible library as a library scope, not an artist id", func() {
 				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}, {ID: 2}}
-				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("2")+"&IncludeItemTypes=MusicAlbum", nil).WithContext(ctxUserWithLibraries(libs))
+				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeLibraryID(2)+"&IncludeItemTypes=MusicAlbum", nil).WithContext(ctxUserWithLibraries(libs))
 				invoke(api.getItems, w, r)
 				Expect(w.Code).To(Equal(http.StatusOK))
 				sql, args, err := albumRepo.Options.Filters.ToSql()
@@ -716,10 +722,10 @@ var _ = Describe("Items", func() {
 
 			It("does not let ParentId=<inaccessible library id> scope results to that library", func() {
 				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: "a1", Name: "One"}})
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}} // no access to library 99
-				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID("99")+"&IncludeItemTypes=MusicAlbum", nil).WithContext(ctxUserWithLibraries(libs))
+				r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeLibraryID(99)+"&IncludeItemTypes=MusicAlbum", nil).WithContext(ctxUserWithLibraries(libs))
 				invoke(api.getItems, w, r)
 				Expect(w.Code).To(Equal(http.StatusOK))
 				sql, args, err := albumRepo.Options.Filters.ToSql()
@@ -734,7 +740,7 @@ var _ = Describe("Items", func() {
 
 			It("does not restrict a default MusicAlbum listing for an admin user", func() {
 				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}, {ID: "a2", Name: "Two", LibraryID: 2}})
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}, {ID: testID("a2"), Name: "Two", LibraryID: 2}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum", nil).WithContext(ctxAdmin())
 				invoke(api.getItems, w, r)
@@ -750,10 +756,63 @@ var _ = Describe("Items", func() {
 			})
 		})
 
+		// A malformed id must 404, not silently drop the filter; a well-formed but unknown one must
+		// still reach the entity filter, not the unfiltered default.
+		Describe("stale and malformed id filtering", func() {
+			It("404s a malformed ParentId instead of listing every song", func() {
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&ParentId=not-a-valid-id", nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				Expect(w.Code).To(Equal(http.StatusNotFound))
+			})
+
+			It("404s a malformed AlbumArtistIds instead of listing every album", func() {
+				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&AlbumArtistIds=not-a-valid-id", nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				Expect(w.Code).To(Equal(http.StatusNotFound))
+			})
+
+			It("404s a malformed ArtistIds instead of listing every song", func() {
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&ArtistIds=not-a-valid-id", nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				Expect(w.Code).To(Equal(http.StatusNotFound))
+			})
+
+			It("still applies the artist filter (rather than dropping it) for a well-formed but unknown AlbumArtistIds", func() {
+				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&AlbumArtistIds="+dto.EncodeID(testID("no-such-artist")), nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				Expect(w.Code).To(Equal(http.StatusOK))
+				sql, _, err := albumRepo.Options.Filters.ToSql()
+				Expect(err).NotTo(HaveOccurred())
+				Expect(sql).To(ContainSubstring("album_artists"))
+			})
+
+			It("still applies the album filter (rather than dropping it) for a well-formed but unknown ParentId", func() {
+				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&ParentId="+dto.EncodeID(testID("no-such-album")), nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				Expect(w.Code).To(Equal(http.StatusOK))
+				sql, args, err := mfRepo.Options.Filters.ToSql()
+				Expect(err).NotTo(HaveOccurred())
+				Expect(sql).To(ContainSubstring("album_id"))
+				Expect(args).To(ContainElement(testID("no-such-album")))
+			})
+		})
+
 		Describe("mixed IncludeItemTypes merge", func() {
 			BeforeEach(func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}, {ID: "a2", Name: "Two"}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "S1"}, {ID: "s2", Title: "S2"}})
+				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "S1"}, {ID: testID("s2"), Title: "S2"}})
 			})
 
 			It("returns a mix of both types, not all of one", func() {
@@ -815,54 +874,54 @@ var _ = Describe("Items", func() {
 
 	Describe("getItem", func() {
 		It("returns an album by id", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("a1"), nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var item dto.BaseItemDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &item)).To(Succeed())
-			Expect(item.Id).To(Equal(dto.EncodeID("a1")))
+			Expect(item.Id).To(Equal(dto.EncodeID(testID("a1"))))
 			Expect(item.Type).To(Equal("MusicAlbum"))
 		})
 
 		It("returns 404 when the id doesn't match any entity", func() {
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/missing", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "missing")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("missing")))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
 		It("returns 404 for an album in a library the user can't access", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 2}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("a1"), nil).WithContext(ctxUser()) // only has access to library 1
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser()) // only has access to library 1
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
 		It("returns 404 for a song in a library the user can't access", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1", Title: "Song", LibraryID: 2}})
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 2}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("s1"), nil).WithContext(ctxUser()) // only has access to library 1
-			r = withChiURLParam(r, "itemId", dto.EncodeID("s1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("s1")), nil).WithContext(ctxUser()) // only has access to library 1
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
 		It("returns an album to an admin even when it's outside their (empty) Libraries", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 2}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("a1"), nil).WithContext(ctxAdmin()) // admin, Libraries: nil
-			r = withChiURLParam(r, "itemId", dto.EncodeID("a1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxAdmin()) // admin, Libraries: nil
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var item dto.BaseItemDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &item)).To(Succeed())
-			Expect(item.Id).To(Equal(dto.EncodeID("a1")))
+			Expect(item.Id).To(Equal(dto.EncodeID(testID("a1"))))
 		})
 
 		// Finamp fetches a /UserViews entry (Id=library id) as a plain item to resolve the
@@ -870,13 +929,13 @@ var _ = Describe("Items", func() {
 		It("resolves a library-view id (from /UserViews) as a CollectionFolder item", func() {
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1, Name: "Music Library"}}
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("1"), nil).WithContext(ctxUserWithLibraries(libs))
-			r = withChiURLParam(r, "itemId", dto.EncodeID("1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeLibraryID(1), nil).WithContext(ctxUserWithLibraries(libs))
+			r = withChiURLParam(r, "itemId", dto.EncodeLibraryID(1))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var item dto.BaseItemDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &item)).To(Succeed())
-			Expect(item.Id).To(Equal(dto.EncodeID("1")))
+			Expect(item.Id).To(Equal(dto.EncodeLibraryID(1)))
 			Expect(item.Name).To(Equal("Music Library"))
 			Expect(item.Type).To(Equal("CollectionFolder"))
 			Expect(item.CollectionType).To(Equal("music"))
@@ -886,8 +945,8 @@ var _ = Describe("Items", func() {
 		It("does not resolve a library-view id the user has no access to", func() {
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 2, Name: "Other"}} // no access to library 1
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("1"), nil).WithContext(ctxUserWithLibraries(libs))
-			r = withChiURLParam(r, "itemId", dto.EncodeID("1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeLibraryID(1), nil).WithContext(ctxUserWithLibraries(libs))
+			r = withChiURLParam(r, "itemId", dto.EncodeLibraryID(1))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
@@ -895,15 +954,15 @@ var _ = Describe("Items", func() {
 		// Finamp's SyncBuffer fetches a playlist by id as a plain item; without this probe it
 		// 404s with "Could not fetch BaseItemDto <playlist> from server."
 		It("resolves a playlist id via the playlists service", func() {
-			fp.getByIDPls = &model.Playlist{ID: "p1", Name: "My Mix", SongCount: 5}
+			fp.getByIDPls = &model.Playlist{ID: testID("p1"), Name: "My Mix", SongCount: 5}
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("p1"), nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("p1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("p1")), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("p1")))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var item dto.BaseItemDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &item)).To(Succeed())
-			Expect(item.Id).To(Equal(dto.EncodeID("p1")))
+			Expect(item.Id).To(Equal(dto.EncodeID(testID("p1"))))
 			Expect(item.Name).To(Equal("My Mix"))
 			Expect(item.Type).To(Equal("Playlist"))
 		})
@@ -911,23 +970,23 @@ var _ = Describe("Items", func() {
 		It("returns 404 for a non-owned or absent playlist id", func() {
 			fp.getByIDErr = model.ErrNotFound
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("p1"), nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("p1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("p1")), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("p1")))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
 		// Finamp's genre "See all" fetches the genre by id; a 404 white-screens it (see resolveItemByID).
 		It("resolves a genre id as a MusicGenre item", func() {
-			Expect(ds.Genre(context.Background()).(*tests.MockedGenreRepo).Put(&model.Genre{ID: "g1", Name: "Rock"})).To(Succeed())
+			Expect(ds.Genre(context.Background()).(*tests.MockedGenreRepo).Put(&model.Genre{ID: testID("g1"), Name: "Rock"})).To(Succeed())
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("g1"), nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("g1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("g1")), nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("g1")))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var item dto.BaseItemDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &item)).To(Succeed())
-			Expect(item.Id).To(Equal(dto.EncodeID("g1")))
+			Expect(item.Id).To(Equal(dto.EncodeID(testID("g1"))))
 			Expect(item.Name).To(Equal("Rock"))
 			Expect(item.Type).To(Equal("MusicGenre"))
 		})
@@ -935,13 +994,13 @@ var _ = Describe("Items", func() {
 		It("resolves a library-view id for an admin even though their Libraries slice is empty", func() {
 			ds.Library(context.Background()).(*tests.MockLibraryRepo).SetData(model.Libraries{{ID: 1, Name: "Music Library"}})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("1"), nil).WithContext(ctxAdmin())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("1"))
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeLibraryID(1), nil).WithContext(ctxAdmin())
+			r = withChiURLParam(r, "itemId", dto.EncodeLibraryID(1))
 			invoke(api.getItem, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var item dto.BaseItemDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &item)).To(Succeed())
-			Expect(item.Id).To(Equal(dto.EncodeID("1")))
+			Expect(item.Id).To(Equal(dto.EncodeLibraryID(1)))
 			Expect(item.Name).To(Equal("Music Library"))
 			Expect(item.Type).To(Equal("CollectionFolder"))
 		})
@@ -949,7 +1008,7 @@ var _ = Describe("Items", func() {
 
 	Describe("getLatest", func() {
 		It("returns a bare array of the newest albums", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}})
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Users/u1/Items/Latest", nil).WithContext(ctxUser())
 			invoke(api.getLatest, w, r)
@@ -957,12 +1016,12 @@ var _ = Describe("Items", func() {
 			var items []dto.BaseItemDto
 			Expect(json.Unmarshal(w.Body.Bytes(), &items)).To(Succeed())
 			Expect(items).To(HaveLen(1))
-			Expect(items[0].Id).To(Equal(dto.EncodeID("a1")))
+			Expect(items[0].Id).To(Equal(dto.EncodeID(testID("a1"))))
 		})
 
 		It("scopes to the user's accessible libraries", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: "a1", Name: "One", LibraryID: 1}})
+			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1}, {ID: 2}}
 			r := httptest.NewRequest("GET", "/Users/u1/Items/Latest", nil).WithContext(ctxUserWithLibraries(libs))
@@ -1014,4 +1073,47 @@ var _ = Describe("Items", func() {
 			Expect(parseTypes("Audio,MusicAlbum,Audio")).To(Equal([]string{"Audio", "MusicAlbum"}))
 		})
 	})
+
+	Describe("decodeFilterParam", func() {
+		It("reports ok for an absent param, decoding to \"\"", func() {
+			id, ok := decodeFilterParam("")
+			Expect(id).To(BeEmpty())
+			Expect(ok).To(BeTrue())
+		})
+
+		It("reports ok for a well-formed id, whether or not it exists", func() {
+			id, ok := decodeFilterParam(dto.EncodeID(testID("a1")))
+			Expect(id).To(Equal(testID("a1")))
+			Expect(ok).To(BeTrue())
+		})
+
+		It("reports not ok for a non-empty param that fails to decode", func() {
+			id, ok := decodeFilterParam("not-a-valid-id")
+			Expect(id).To(BeEmpty())
+			Expect(ok).To(BeFalse())
+		})
+	})
+
+	Describe("decodedQueryIDs", func() {
+		It("decodes every entry when all are well-formed", func() {
+			r := httptest.NewRequest("GET", "/Items?ids="+dto.EncodeID(testID("a1"))+","+dto.EncodeID(testID("a2")), nil)
+			ids, ok := decodedQueryIDs(r, "ids")
+			Expect(ok).To(BeTrue())
+			Expect(ids).To(Equal([]string{testID("a1"), testID("a2")}))
+		})
+
+		It("reports not ok and an empty list, not a partially-decoded one, for a mix of valid and malformed entries", func() {
+			r := httptest.NewRequest("GET", "/Items?ids="+dto.EncodeID(testID("a1"))+",not-a-valid-id", nil)
+			ids, ok := decodedQueryIDs(r, "ids")
+			Expect(ok).To(BeFalse())
+			Expect(ids).To(BeEmpty())
+		})
+
+		It("reports ok for an absent param, decoding to an empty list", func() {
+			r := httptest.NewRequest("GET", "/Items", nil)
+			ids, ok := decodedQueryIDs(r, "ids")
+			Expect(ok).To(BeTrue())
+			Expect(ids).To(BeEmpty())
+		})
+	})
 })
diff --git a/server/jellyfin/jellyfin_suite_test.go b/server/jellyfin/jellyfin_suite_test.go
index aab9628a0..2ae7da6e2 100644
--- a/server/jellyfin/jellyfin_suite_test.go
+++ b/server/jellyfin/jellyfin_suite_test.go
@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -17,6 +18,10 @@ func TestJellyfinApi(t *testing.T) {
 	RunSpecs(t, "Jellyfin API Suite")
 }
 
+// testID maps a readable label to a deterministic canonical id, so fixtures exercise the same
+// id shape production uses.
+func testID(label string) string { return id.NewHash("jellyfin-test", label) }
+
 // invoke runs a handler through normalizeQueryKeys, mirroring the router. These unit tests call
 // handlers directly (with withChiURLParam for path params) instead of routing, so without this the
 // case-insensitive query folding real requests get would be skipped and PascalCase params dropped.
diff --git a/server/jellyfin/library.go b/server/jellyfin/library.go
index 2830f1105..b21603843 100644
--- a/server/jellyfin/library.go
+++ b/server/jellyfin/library.go
@@ -6,6 +6,7 @@ import (
 	"strconv"
 
 	"github.com/Masterminds/squirrel"
+	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/jellyfin/dto"
@@ -33,9 +34,36 @@ func resolveLibraryScope(ctx context.Context, parentId string) (scopeIDs []int,
 	return accessibleLibraryIDs(ctx), false
 }
 
+// decodeFilterParam separates an absent param from an undecodable one: dropping the filter for a
+// stale id would silently widen the query to the whole library. It is the only place that opts
+// into treating "absent" as fine — every other caller of dto.DecodeID must 404 on ok=false.
+func decodeFilterParam(raw string) (id string, ok bool) {
+	if raw == "" {
+		return "", true
+	}
+	return dto.DecodeID(raw)
+}
+
+// itemIDParam decodes a chi URL id param, writing 404 and reporting false when it isn't a
+// well-formed GUID. Handlers must return immediately when ok is false.
+func itemIDParam(w http.ResponseWriter, r *http.Request, key string) (string, bool) {
+	id, ok := dto.DecodeID(chi.URLParam(r, key))
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return "", false
+	}
+	return id, true
+}
+
 // parentIDScope resolves the request's ParentId param to a library scope (see resolveLibraryScope).
-func parentIDScope(ctx context.Context, r *http.Request) (scopeIDs []int, isLibraryParent bool) {
-	return resolveLibraryScope(ctx, dto.DecodeID(req.Params(r).StringOr("parentid", "")))
+// ok is false when a non-empty ParentId fails to decode (see decodeFilterParam).
+func parentIDScope(ctx context.Context, r *http.Request) (scopeIDs []int, isLibraryParent bool, ok bool) {
+	parentId, ok := decodeFilterParam(req.Params(r).StringOr("parentid", ""))
+	if !ok {
+		return nil, false, false
+	}
+	scopeIDs, isLibraryParent = resolveLibraryScope(ctx, parentId)
+	return scopeIDs, isLibraryParent, true
 }
 
 // libraryScopeFilter restricts a tag query to the given library scope. Empty scope means
@@ -51,7 +79,7 @@ func libraryScopeFilter(scope []int) squirrel.Sqlizer {
 // Shared by getUserViews and getItem, since Finamp fetches a UserView's id as a plain item.
 func libraryView(lib model.Library) dto.BaseItemDto {
 	return dto.BaseItemDto{
-		Id:                dto.EncodeID(strconv.Itoa(lib.ID)),
+		Id:                dto.EncodeLibraryID(lib.ID),
 		Name:              lib.Name,
 		Type:              "CollectionFolder",
 		CollectionType:    "music",
diff --git a/server/jellyfin/lyrics_test.go b/server/jellyfin/lyrics_test.go
index 402d14ed0..2cf53a280 100644
--- a/server/jellyfin/lyrics_test.go
+++ b/server/jellyfin/lyrics_test.go
@@ -53,8 +53,8 @@ var _ = Describe("getLyrics", func() {
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
 		ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-			{ID: "s1", Title: "Song", LibraryID: 1},
-			{ID: "s2", Title: "Silent Song", LibraryID: 1},
+			{ID: testID("s1"), Title: "Song", LibraryID: 1},
+			{ID: testID("s2"), Title: "Silent Song", LibraryID: 1},
 		})
 		fake = &fakeLyricsService{lyrics: map[string]model.LyricList{}}
 		api = &Router{
@@ -66,7 +66,7 @@ var _ = Describe("getLyrics", func() {
 
 	doRequest := func(id string) *httptest.ResponseRecorder {
 		w := httptest.NewRecorder()
-		ctx := request.WithUser(context.Background(), model.User{ID: "u1", Libraries: model.Libraries{{ID: 1}}})
+		ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), Libraries: model.Libraries{{ID: 1}}})
 		// Clients send hex-encoded ids (matching real traffic and the other handler tests).
 		enc := dto.EncodeID(id)
 		r := httptest.NewRequest("GET", "/Audio/"+enc+"/Lyrics", nil).WithContext(ctx)
@@ -76,10 +76,10 @@ var _ = Describe("getLyrics", func() {
 	}
 
 	It("returns 200 with a LyricDto for a track with synced lyrics", func() {
-		fake.lyrics["s1"] = model.LyricList{
+		fake.lyrics[testID("s1")] = model.LyricList{
 			{Kind: "main", Synced: true, Line: []model.Line{{Start: p(1000), Value: "hello"}}},
 		}
-		w := doRequest("s1")
+		w := doRequest(testID("s1"))
 
 		Expect(w.Code).To(Equal(http.StatusOK))
 		var res dto.LyricDto
@@ -91,11 +91,11 @@ var _ = Describe("getLyrics", func() {
 	})
 
 	It("serves the main-kind lyric when a translation is also present", func() {
-		fake.lyrics["s1"] = model.LyricList{
+		fake.lyrics[testID("s1")] = model.LyricList{
 			{Kind: "translation", Synced: true, Line: []model.Line{{Start: p(1000), Value: "bonjour"}}},
 			{Kind: "main", Synced: true, Line: []model.Line{{Start: p(1000), Value: "hello"}}},
 		}
-		w := doRequest("s1")
+		w := doRequest(testID("s1"))
 
 		Expect(w.Code).To(Equal(http.StatusOK))
 		var res dto.LyricDto
@@ -105,13 +105,13 @@ var _ = Describe("getLyrics", func() {
 	})
 
 	It("returns 404 when the service returns no lyrics", func() {
-		w := doRequest("s2")
+		w := doRequest(testID("s2"))
 		Expect(w.Code).To(Equal(http.StatusNotFound))
 	})
 
 	It("returns 404 when the main lyric has no lines", func() {
-		fake.lyrics["s1"] = model.LyricList{{Kind: "main", Lang: "eng"}}
-		w := doRequest("s1")
+		fake.lyrics[testID("s1")] = model.LyricList{{Kind: "main", Lang: "eng"}}
+		w := doRequest(testID("s1"))
 		Expect(w.Code).To(Equal(http.StatusNotFound))
 	})
 
@@ -121,35 +121,35 @@ var _ = Describe("getLyrics", func() {
 	})
 
 	It("caches results so a second request doesn't re-invoke the service", func() {
-		fake.lyrics["s1"] = model.LyricList{
+		fake.lyrics[testID("s1")] = model.LyricList{
 			{Kind: "main", Synced: true, Line: []model.Line{{Start: p(1000), Value: "hello"}}},
 		}
-		Expect(doRequest("s1").Code).To(Equal(http.StatusOK))
-		Expect(doRequest("s1").Code).To(Equal(http.StatusOK))
+		Expect(doRequest(testID("s1")).Code).To(Equal(http.StatusOK))
+		Expect(doRequest(testID("s1")).Code).To(Equal(http.StatusOK))
 		Expect(fake.calls).To(Equal(1))
 	})
 
 	It("caches empty results too", func() {
-		Expect(doRequest("s2").Code).To(Equal(http.StatusNotFound))
-		Expect(doRequest("s2").Code).To(Equal(http.StatusNotFound))
+		Expect(doRequest(testID("s2")).Code).To(Equal(http.StatusNotFound))
+		Expect(doRequest(testID("s2")).Code).To(Equal(http.StatusNotFound))
 		Expect(fake.calls).To(Equal(1))
 	})
 
 	It("completes and caches the fetch even when the request context is cancelled", func() {
-		fake.lyrics["s1"] = model.LyricList{
+		fake.lyrics[testID("s1")] = model.LyricList{
 			{Kind: "main", Synced: true, Line: []model.Line{{Start: p(1000), Value: "hello"}}},
 		}
 		ctx, cancel := context.WithCancel(context.Background())
 		cancel()
 
-		list := api.cachedLyrics(ctx, &model.MediaFile{ID: "s1"})
+		list := api.cachedLyrics(ctx, &model.MediaFile{ID: testID("s1")})
 		Expect(list).ToNot(BeEmpty())
-		Expect(doRequest("s1").Code).To(Equal(http.StatusOK))
+		Expect(doRequest(testID("s1")).Code).To(Equal(http.StatusOK))
 		Expect(fake.calls).To(Equal(1))
 	})
 
 	It("bounds the detached fetch with a timeout", func() {
-		Expect(doRequest("s2").Code).To(Equal(http.StatusNotFound))
+		Expect(doRequest(testID("s2")).Code).To(Equal(http.StatusNotFound))
 		Expect(fake.hadDeadline).To(BeTrue())
 	})
 })
diff --git a/server/jellyfin/middlewares_test.go b/server/jellyfin/middlewares_test.go
index f3aa65d6f..b17b9a4ec 100644
--- a/server/jellyfin/middlewares_test.go
+++ b/server/jellyfin/middlewares_test.go
@@ -24,12 +24,12 @@ var _ = Describe("authenticate middleware", func() {
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
 		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: "u1", UserName: "alice", NewPassword: "secret"})).To(Succeed())
+		Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
 		api = &Router{ds: ds}
 	})
 
 	tokenFor := func(name string) string {
-		t, err := auth.CreateToken(&model.User{ID: "u1", UserName: name})
+		t, err := auth.CreateToken(&model.User{ID: testID("u1"), UserName: name})
 		Expect(err).ToNot(HaveOccurred())
 		return t
 	}
@@ -129,7 +129,7 @@ var _ = Describe("withPlayer middleware", func() {
 	})
 
 	It("injects the player's server-forced transcoding into the context", func() {
-		players.trc = &model.Transcoding{ID: "t1", TargetFormat: "opus"}
+		players.trc = &model.Transcoding{ID: testID("t1"), TargetFormat: "opus"}
 		_, trc, hasTrc := callWith()
 		Expect(hasTrc).To(BeTrue())
 		Expect(trc.TargetFormat).To(Equal("opus"))
diff --git a/server/jellyfin/playlists.go b/server/jellyfin/playlists.go
index 9afee5ac3..805b369c8 100644
--- a/server/jellyfin/playlists.go
+++ b/server/jellyfin/playlists.go
@@ -17,16 +17,11 @@ import (
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
-// playlistsFolderID is the reserved id of the synthetic "playlists library" folder. Clients resolve
-// it via a ManualPlaylistsFolder query, then list playlists with ParentId set to it. The literal
-// can't collide with real ids (those are hashes).
-const playlistsFolderID = "playlists"
-
 // playlistsFolder is the item returned for a ManualPlaylistsFolder query. CollectionType must be
 // "playlists" — how the client identifies it; without it Jellify's playlist-library query loops.
 func playlistsFolder() dto.BaseItemDto {
 	return dto.BaseItemDto{
-		Id:             dto.EncodeID(playlistsFolderID),
+		Id:             dto.PlaylistsFolderGUID,
 		Name:           "Playlists",
 		Type:           "ManualPlaylistsFolder",
 		CollectionType: "playlists",
@@ -61,7 +56,12 @@ func (api *Router) createPlaylist(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Bad Request", http.StatusBadRequest)
 		return
 	}
-	ids := api.expandContainerIDs(r.Context(), slice.Map(body.Ids, dto.DecodeID))
+	decoded, ok := dto.DecodeIDs(body.Ids)
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
+	ids := api.expandContainerIDs(r.Context(), decoded)
 	id, err := api.playlists.Create(r.Context(), "", body.Name, ids)
 	if err != nil {
 		api.internalError(w, r, err)
@@ -80,7 +80,10 @@ type updatePlaylistRequest struct {
 
 func (api *Router) updatePlaylist(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := dto.DecodeID(chi.URLParam(r, "playlistId"))
+	id, ok := itemIDParam(w, r, "playlistId")
+	if !ok {
+		return
+	}
 	var body updatePlaylistRequest
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 		http.Error(w, "Bad Request", http.StatusBadRequest)
@@ -96,7 +99,12 @@ func (api *Router) updatePlaylist(w http.ResponseWriter, r *http.Request) {
 				return
 			}
 		} else {
-			ids := api.expandContainerIDs(ctx, slice.Map(*body.Ids, dto.DecodeID))
+			decoded, ok := dto.DecodeIDs(*body.Ids)
+			if !ok {
+				http.Error(w, "Not Found", http.StatusNotFound)
+				return
+			}
+			ids := api.expandContainerIDs(ctx, decoded)
 			if _, err := api.playlists.Create(ctx, id, "", ids); err != nil {
 				api.playlistError(w, r, err)
 				return
@@ -146,7 +154,7 @@ func (api *Router) playlistTrackPage(repo model.PlaylistTrackRepository, fields
 // individually removable.
 func trackToBaseItem(t model.PlaylistTrack, fields dto.Fields) dto.BaseItemDto {
 	item := dto.SongToBaseItem(t.MediaFile, fields)
-	item.PlaylistItemId = dto.EncodeID(t.ID)
+	item.PlaylistItemId = dto.EncodePlaylistEntryID(t.ID)
 	return item
 }
 
@@ -155,7 +163,10 @@ func trackToBaseItem(t model.PlaylistTrack, fields dto.Fields) dto.BaseItemDto {
 // be probed.
 func (api *Router) getPlaylist(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := dto.DecodeID(chi.URLParam(r, "playlistId"))
+	id, ok := itemIDParam(w, r, "playlistId")
+	if !ok {
+		return
+	}
 	pls, err := api.playlists.Get(ctx, id)
 	if err != nil {
 		http.Error(w, "Not Found", http.StatusNotFound)
@@ -184,7 +195,10 @@ func (api *Router) getPlaylist(w http.ResponseWriter, r *http.Request) {
 // playlist id can't probe for private playlists.
 func (api *Router) getPlaylistItems(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := dto.DecodeID(chi.URLParam(r, "playlistId"))
+	id, ok := itemIDParam(w, r, "playlistId")
+	if !ok {
+		return
+	}
 	repo, err := api.playlists.Tracks(ctx, id)
 	if err != nil {
 		http.Error(w, "Not Found", http.StatusNotFound)
@@ -232,7 +246,7 @@ func (api *Router) expandContainerIDs(ctx context.Context, ids []string) []strin
 		} else if pl, err := api.playlists.GetWithTracks(ctx, id); err == nil {
 			out = append(out, slice.Map(pl.Tracks, func(t model.PlaylistTrack) string { return t.MediaFileID })...)
 		} else {
-			out = append(out, id) // unknown id — pass through unchanged
+			out = append(out, id) // well-formed but unresolved — left for the caller's write to handle
 		}
 	}
 	return out
@@ -251,8 +265,16 @@ func (api *Router) songIDs(ctx context.Context, opts model.QueryOptions) []strin
 // AddTracks enforces ownership; any error maps to 404.
 func (api *Router) addToPlaylist(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := dto.DecodeID(chi.URLParam(r, "playlistId"))
-	ids := api.expandContainerIDs(ctx, slice.Map(queryIDs(r, "ids"), dto.DecodeID))
+	id, ok := itemIDParam(w, r, "playlistId")
+	if !ok {
+		return
+	}
+	decoded, ok := dto.DecodeIDs(queryIDs(r, "ids"))
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
+	ids := api.expandContainerIDs(ctx, decoded)
 	if _, err := api.playlists.AddTracks(ctx, id, ids); err != nil {
 		http.Error(w, "Not Found", http.StatusNotFound)
 		return
@@ -265,8 +287,20 @@ func (api *Router) addToPlaylist(w http.ResponseWriter, r *http.Request) {
 // ownership; any error maps to 404.
 func (api *Router) removeFromPlaylist(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := dto.DecodeID(chi.URLParam(r, "playlistId"))
-	ids := slice.Map(queryIDs(r, "entryids"), dto.DecodeID)
+	id, ok := itemIDParam(w, r, "playlistId")
+	if !ok {
+		return
+	}
+	raw := queryIDs(r, "entryids")
+	ids := make([]string, 0, len(raw))
+	for _, entryGUID := range raw {
+		entry, ok := dto.DecodePlaylistEntryID(entryGUID)
+		if !ok {
+			http.Error(w, "Not Found", http.StatusNotFound)
+			return
+		}
+		ids = append(ids, entry)
+	}
 	if err := api.playlists.RemoveTracks(ctx, id, ids); err != nil {
 		http.Error(w, "Not Found", http.StatusNotFound)
 		return
diff --git a/server/jellyfin/playlists_test.go b/server/jellyfin/playlists_test.go
index 7770cb6db..3599cc784 100644
--- a/server/jellyfin/playlists_test.go
+++ b/server/jellyfin/playlists_test.go
@@ -67,7 +67,7 @@ func (f *fakePlaylists) Create(_ context.Context, _ string, name string, ids []s
 	if f.createErr != nil {
 		return "", f.createErr
 	}
-	return "pl-new", nil
+	return testID("pl-new"), nil
 }
 
 // Get defaults to model.ErrNotFound when getByIDPls/getByIDErr aren't set, matching the real
@@ -145,15 +145,15 @@ var _ = Describe("Playlists", func() {
 	Describe("createPlaylist", func() {
 		It("creates a playlist and returns its id", func() {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Playlists", strings.NewReader(`{"Name":"Mix","Ids":["s1","s2"]}`)).
+			r := httptest.NewRequest("POST", "/Playlists", strings.NewReader(`{"Name":"Mix","Ids":["`+dto.EncodeID(testID("s1"))+`","`+dto.EncodeID(testID("s2"))+`"]}`)).
 				WithContext(context.Background())
 			invoke(api.createPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res map[string]string
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
-			Expect(res["Id"]).To(Equal(dto.EncodeID("pl-new")))
+			Expect(res["Id"]).To(Equal(dto.EncodeID(testID("pl-new"))))
 			Expect(fp.createdName).To(Equal("Mix"))
-			Expect(fp.createdIds).To(Equal([]string{"s1", "s2"}))
+			Expect(fp.createdIds).To(Equal([]string{testID("s1"), testID("s2")}))
 		})
 
 		It("returns 400 on an invalid JSON body", func() {
@@ -177,48 +177,48 @@ var _ = Describe("Playlists", func() {
 	Describe("getPlaylistItems", func() {
 		It("maps playlist tracks to Audio BaseItemDtos, tagging each with its PlaylistItemId", func() {
 			fp.getPls = &model.Playlist{
-				ID: "pl1",
+				ID: testID("pl1"),
 				Tracks: model.PlaylistTracks{
-					{ID: "1", MediaFileID: "s1", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s1", Title: "Song One"}},
-					{ID: "2", MediaFileID: "s2", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s2", Title: "Song Two"}},
+					{ID: "1", MediaFileID: testID("s1"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s1"), Title: "Song One"}},
+					{ID: "2", MediaFileID: testID("s2"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s2"), Title: "Song Two"}},
 				},
 			}
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Playlists/pl1/Items", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1")+"/Items", nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			api.getPlaylistItems(w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.TotalRecordCount).To(Equal(2))
 			Expect(res.Items).To(HaveLen(2))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("s1")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
 			Expect(res.Items[0].Type).To(Equal("Audio"))
-			Expect(res.Items[0].PlaylistItemId).To(Equal(dto.EncodeID("1")))
-			Expect(res.Items[1].Id).To(Equal(dto.EncodeID("s2")))
-			Expect(res.Items[1].PlaylistItemId).To(Equal(dto.EncodeID("2")))
+			Expect(res.Items[0].PlaylistItemId).To(Equal(dto.EncodePlaylistEntryID("1")))
+			Expect(res.Items[1].Id).To(Equal(dto.EncodeID(testID("s2"))))
+			Expect(res.Items[1].PlaylistItemId).To(Equal(dto.EncodePlaylistEntryID("2")))
 		})
 
 		It("pages with StartIndex/Limit, pushing them down to the query", func() {
 			fp.getPls = &model.Playlist{
-				ID: "pl1",
+				ID: testID("pl1"),
 				Tracks: model.PlaylistTracks{
-					{ID: "1", MediaFileID: "s1", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s1"}},
-					{ID: "2", MediaFileID: "s2", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s2"}},
-					{ID: "3", MediaFileID: "s3", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s3"}},
+					{ID: "1", MediaFileID: testID("s1"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s1")}},
+					{ID: "2", MediaFileID: testID("s2"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s2")}},
+					{ID: "3", MediaFileID: testID("s3"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s3")}},
 				},
 			}
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Playlists/pl1/Items?StartIndex=1&Limit=1", nil).
+			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1")+"/Items?StartIndex=1&Limit=1", nil).
 				WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.getPlaylistItems, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.TotalRecordCount).To(Equal(3))
 			Expect(res.Items).To(HaveLen(1))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("s2")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s2"))))
 			Expect(fp.tracksRepo.Options.Offset).To(Equal(1))
 			Expect(fp.tracksRepo.Options.Max).To(Equal(1))
 		})
@@ -227,7 +227,7 @@ var _ = Describe("Playlists", func() {
 			fp.getErr = model.ErrNotFound
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Playlists/missing/Items", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "missing")
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("missing")))
 			api.getPlaylistItems(w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
@@ -245,73 +245,73 @@ var _ = Describe("Playlists", func() {
 
 		createWith := func(id string) {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Playlists", strings.NewReader(`{"Name":"Mix","Ids":["`+id+`"]}`)).
+			r := httptest.NewRequest("POST", "/Playlists", strings.NewReader(`{"Name":"Mix","Ids":["`+dto.EncodeID(id)+`"]}`)).
 				WithContext(ctx)
 			invoke(api.createPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 		}
 
 		It("passes a bare song id through unchanged", func() {
-			ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1"}})
-			createWith("s1")
-			Expect(fp.createdIds).To(Equal([]string{"s1"}))
+			ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1")}})
+			createWith(testID("s1"))
+			Expect(fp.createdIds).To(Equal([]string{testID("s1")}))
 		})
 
 		It("expands an album id into its songs, filtered by album", func() {
-			ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al1"}})
+			ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("al1")}})
 			ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", AlbumID: "al1"}, {ID: "s2", AlbumID: "al1"},
+				{ID: testID("s1"), AlbumID: testID("al1")}, {ID: testID("s2"), AlbumID: testID("al1")},
 			})
-			createWith("al1")
-			Expect(fp.createdIds).To(Equal([]string{"s1", "s2"}))
-			Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Options.Filters).To(Equal(filter.SongsByAlbum("al1").Filters))
+			createWith(testID("al1"))
+			Expect(fp.createdIds).To(Equal([]string{testID("s1"), testID("s2")}))
+			Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Options.Filters).To(Equal(filter.SongsByAlbum(testID("al1")).Filters))
 		})
 
 		It("expands an artist id into its songs", func() {
-			ds.Artist(ctx).(*tests.MockArtistRepo).SetData(model.Artists{{ID: "ar1"}})
-			ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: "s1"}, {ID: "s2"}})
-			createWith("ar1")
-			Expect(fp.createdIds).To(Equal([]string{"s1", "s2"}))
-			Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Options.Filters).To(Equal(filter.SongsByArtistID("ar1").Filters))
+			ds.Artist(ctx).(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1")}})
+			ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1")}, {ID: testID("s2")}})
+			createWith(testID("ar1"))
+			Expect(fp.createdIds).To(Equal([]string{testID("s1"), testID("s2")}))
+			Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Options.Filters).To(Equal(filter.SongsByArtistID(testID("ar1")).Filters))
 		})
 
 		It("expands a playlist id into its tracks' media file ids", func() {
-			fp.getPls = &model.Playlist{ID: "pl9", Tracks: model.PlaylistTracks{
-				{ID: "1", MediaFileID: "s3"}, {ID: "2", MediaFileID: "s4"},
+			fp.getPls = &model.Playlist{ID: testID("pl9"), Tracks: model.PlaylistTracks{
+				{ID: "1", MediaFileID: testID("s3")}, {ID: "2", MediaFileID: testID("s4")},
 			}}
-			createWith("pl9")
-			Expect(fp.createdIds).To(Equal([]string{"s3", "s4"}))
+			createWith(testID("pl9"))
+			Expect(fp.createdIds).To(Equal([]string{testID("s3"), testID("s4")}))
 		})
 	})
 
 	Describe("getPlaylist", func() {
 		It("returns OpenAccess from Public and item ids (encoded media file ids, not entry ids)", func() {
 			pls := &model.Playlist{
-				ID:     "pl1",
+				ID:     testID("pl1"),
 				Public: true,
 				Tracks: model.PlaylistTracks{
-					{ID: "1", MediaFileID: "s1", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s1"}},
-					{ID: "2", MediaFileID: "s2", PlaylistID: "pl1", MediaFile: model.MediaFile{ID: "s2"}},
+					{ID: "1", MediaFileID: testID("s1"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s1")}},
+					{ID: "2", MediaFileID: testID("s2"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s2")}},
 				},
 			}
 			fp.getPls, fp.getByIDPls = pls, pls
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Playlists/pl1", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1"), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.getPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.PlaylistInfo
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.OpenAccess).To(BeTrue())
 			Expect(res.Shares).To(BeEmpty())
-			Expect(res.ItemIds).To(Equal([]string{dto.EncodeID("s1"), dto.EncodeID("s2")}))
+			Expect(res.ItemIds).To(Equal([]string{dto.EncodeID(testID("s1")), dto.EncodeID(testID("s2"))}))
 		})
 
 		It("returns 404 for a non-owned or absent playlist", func() {
 			fp.getErr = model.ErrNotFound
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Playlists/missing", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "missing")
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("missing")))
 			invoke(api.getPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
@@ -325,29 +325,29 @@ var _ = Describe("Playlists", func() {
 
 		It("deletes the playlist and returns 204", func() {
 			w := httptest.NewRecorder()
-			api.deleteItem(w, deleteReq("pl1"))
+			api.deleteItem(w, deleteReq(testID("pl1")))
 			Expect(w.Code).To(Equal(http.StatusNoContent))
-			Expect(fp.deletePlaylistID).To(Equal("pl1"))
+			Expect(fp.deletePlaylistID).To(Equal(testID("pl1")))
 		})
 
 		It("returns 403 when the user doesn't own the playlist", func() {
 			fp.deleteErr = model.ErrNotAuthorized
 			w := httptest.NewRecorder()
-			api.deleteItem(w, deleteReq("pl1"))
+			api.deleteItem(w, deleteReq(testID("pl1")))
 			Expect(w.Code).To(Equal(http.StatusForbidden))
 		})
 
 		It("returns 404 for a missing playlist or non-playlist id", func() {
 			fp.deleteErr = model.ErrNotFound
 			w := httptest.NewRecorder()
-			api.deleteItem(w, deleteReq("al1"))
+			api.deleteItem(w, deleteReq(testID("al1")))
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
 		It("returns 500 on an unexpected error", func() {
 			fp.deleteErr = errors.New("boom")
 			w := httptest.NewRecorder()
-			api.deleteItem(w, deleteReq("pl1"))
+			api.deleteItem(w, deleteReq(testID("pl1")))
 			Expect(w.Code).To(Equal(http.StatusInternalServerError))
 		})
 	})
@@ -355,39 +355,39 @@ var _ = Describe("Playlists", func() {
 	Describe("addToPlaylist", func() {
 		It("adds tracks by song id from the lowercase ids param real Jellyfin clients send", func() {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Playlists/pl1/Items?ids=s1,s2", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("POST", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?ids="+dto.EncodeID(testID("s1"))+","+dto.EncodeID(testID("s2")), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.addToPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNoContent))
-			Expect(fp.addPlaylistID).To(Equal("pl1"))
-			Expect(fp.addIds).To(Equal([]string{"s1", "s2"}))
+			Expect(fp.addPlaylistID).To(Equal(testID("pl1")))
+			Expect(fp.addIds).To(Equal([]string{testID("s1"), testID("s2")}))
 		})
 
 		It("accepts a PascalCase Ids param (case-folded by the middleware)", func() {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Playlists/pl1/Items?Ids=s1,s2", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("POST", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?Ids="+dto.EncodeID(testID("s1"))+","+dto.EncodeID(testID("s2")), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.addToPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNoContent))
-			Expect(fp.addIds).To(Equal([]string{"s1", "s2"}))
+			Expect(fp.addIds).To(Equal([]string{testID("s1"), testID("s2")}))
 		})
 
 		It("returns 404 when the service rejects the request (not found/not owned)", func() {
 			fp.addErr = model.ErrNotAuthorized
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Playlists/pl1/Items?ids=s1", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("POST", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?ids="+dto.EncodeID(testID("s1")), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.addToPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
 		It("passes no ids (not a spurious empty string) when the ids param is absent", func() {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Playlists/pl1/Items", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("POST", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items", nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.addToPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNoContent))
-			Expect(fp.addPlaylistID).To(Equal("pl1"))
+			Expect(fp.addPlaylistID).To(Equal(testID("pl1")))
 			Expect(fp.addIds).To(BeEmpty())
 		})
 	})
@@ -395,39 +395,48 @@ var _ = Describe("Playlists", func() {
 	Describe("removeFromPlaylist", func() {
 		It("removes entries by the lowercase entryIds param real Jellyfin clients send (playlist-track position ids, not song ids)", func() {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("DELETE", "/Playlists/pl1/Items?entryIds=1,2", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("DELETE", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?entryIds="+dto.EncodePlaylistEntryID("1")+","+dto.EncodePlaylistEntryID("2"), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.removeFromPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNoContent))
-			Expect(fp.removePlaylistID).To(Equal("pl1"))
+			Expect(fp.removePlaylistID).To(Equal(testID("pl1")))
 			Expect(fp.removeIds).To(Equal([]string{"1", "2"}))
 		})
 
 		It("accepts a PascalCase EntryIds param (case-folded by the middleware)", func() {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("DELETE", "/Playlists/pl1/Items?EntryIds=1,2", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("DELETE", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?EntryIds="+dto.EncodePlaylistEntryID("1")+","+dto.EncodePlaylistEntryID("2"), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.removeFromPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNoContent))
 			Expect(fp.removeIds).To(Equal([]string{"1", "2"}))
 		})
 
+		It("404s an entryId that is a song id rather than a playlist-entry position", func() {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("DELETE", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?entryIds="+dto.EncodeID(testID("s1")), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
+			invoke(api.removeFromPlaylist, w, r)
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+			Expect(fp.removeIds).To(BeEmpty())
+		})
+
 		It("returns 404 when the service rejects the request (not found/not owned)", func() {
 			fp.removeErr = model.ErrNotFound
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("DELETE", "/Playlists/pl1/Items?entryIds=1", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("DELETE", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?entryIds="+dto.EncodePlaylistEntryID("1"), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.removeFromPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
 		It("passes no ids (not a spurious empty string) when the entryIds param is absent", func() {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("DELETE", "/Playlists/pl1/Items", nil).WithContext(context.Background())
-			r = withChiURLParam(r, "playlistId", "pl1")
+			r := httptest.NewRequest("DELETE", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items", nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			invoke(api.removeFromPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusNoContent))
-			Expect(fp.removePlaylistID).To(Equal("pl1"))
+			Expect(fp.removePlaylistID).To(Equal(testID("pl1")))
 			Expect(fp.removeIds).To(BeEmpty())
 		})
 	})
@@ -435,30 +444,30 @@ var _ = Describe("Playlists", func() {
 	Describe("getPlaylistUsers", func() {
 		It("returns the current user with CanEdit true", func() {
 			w := httptest.NewRecorder()
-			ctx := request.WithUser(context.Background(), model.User{ID: "u1", UserName: "alice"})
-			r := httptest.NewRequest("GET", "/Playlists/pl1/Users", nil).WithContext(ctx)
-			r = withChiURLParam(r, "playlistId", "pl1")
+			ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice"})
+			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1")+"/Users", nil).WithContext(ctx)
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
 			api.getPlaylistUsers(w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res []dto.PlaylistUserPermissions
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
-			Expect(res).To(Equal([]dto.PlaylistUserPermissions{{UserId: dto.EncodeID("u1"), CanEdit: true}}))
+			Expect(res).To(Equal([]dto.PlaylistUserPermissions{{UserId: dto.EncodeID(testID("u1")), CanEdit: true}}))
 		})
 	})
 
 	Describe("getPlaylistUser", func() {
 		It("returns CanEdit true for the requested user", func() {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Playlists/pl1/Users/u1", nil).WithContext(context.Background())
+			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1")+"/Users/"+testID("u1"), nil).WithContext(context.Background())
 			rctx := chi.NewRouteContext()
-			rctx.URLParams.Add("playlistId", "pl1")
-			rctx.URLParams.Add("userId", "u1")
+			rctx.URLParams.Add("playlistId", testID("pl1"))
+			rctx.URLParams.Add("userId", testID("u1"))
 			r = r.WithContext(context.WithValue(r.Context(), chi.RouteCtxKey, rctx))
 			api.getPlaylistUser(w, r)
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.PlaylistUserPermissions
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
-			Expect(res).To(Equal(dto.PlaylistUserPermissions{UserId: "u1", CanEdit: true}))
+			Expect(res).To(Equal(dto.PlaylistUserPermissions{UserId: testID("u1"), CanEdit: true}))
 		})
 	})
 })
diff --git a/server/jellyfin/sessions.go b/server/jellyfin/sessions.go
index f83e5182d..a145e7359 100644
--- a/server/jellyfin/sessions.go
+++ b/server/jellyfin/sessions.go
@@ -21,14 +21,19 @@ type playbackReport struct {
 
 // decodeReport reads the playback report body. ItemId falls back to a query param (some clients send
 // it there) and is decoded here since it flows straight into scrobbler lookups by media file id.
-// Finamp reports restored-queue playback with truncated ids, hence resolveItemID.
+// These endpoints always answer 204 (see reportPlaybackStart), so a malformed id isn't a request
+// failure; it just can't identify a track, same as an absent one.
 func (api *Router) decodeReport(r *http.Request) playbackReport {
 	var body playbackReport
 	_ = json.NewDecoder(r.Body).Decode(&body)
 	if body.ItemId == "" {
 		body.ItemId = r.URL.Query().Get("itemid")
 	}
-	body.ItemId = api.resolveItemID(r.Context(), dto.DecodeID(body.ItemId))
+	if id, ok := dto.DecodeID(body.ItemId); ok {
+		body.ItemId = id
+	} else {
+		body.ItemId = ""
+	}
 	return body
 }
 
diff --git a/server/jellyfin/sessions_test.go b/server/jellyfin/sessions_test.go
index 24f945efd..05151c39a 100644
--- a/server/jellyfin/sessions_test.go
+++ b/server/jellyfin/sessions_test.go
@@ -11,6 +11,7 @@ import (
 	"github.com/navidrome/navidrome/core/scrobbler"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -57,8 +58,8 @@ var _ = Describe("Sessions", func() {
 	var pt *fakePlayTracker
 
 	authed := func(r *http.Request) *http.Request {
-		ctx := request.WithUser(context.Background(), model.User{ID: "u1", UserName: "alice"})
-		ctx = request.WithPlayer(ctx, model.Player{ID: "p1", Client: "Finamp"})
+		ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice"})
+		ctx = request.WithPlayer(ctx, model.Player{ID: testID("p1"), Client: "Finamp"})
 		return r.WithContext(ctx)
 	}
 
@@ -70,35 +71,46 @@ var _ = Describe("Sessions", func() {
 	Describe("reportPlaybackStart", func() {
 		It("reports playback start with the item id and position", func() {
 			w := httptest.NewRecorder()
-			r := authed(httptest.NewRequest("POST", "/Sessions/Playing", strings.NewReader(`{"ItemId":"s1","PositionTicks":10000000}`)))
+			r := authed(httptest.NewRequest("POST", "/Sessions/Playing", strings.NewReader(`{"ItemId":"`+dto.EncodeID(testID("s1"))+`","PositionTicks":10000000}`)))
 
 			invoke(api.reportPlaybackStart, w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNoContent))
 			Expect(pt.reported).To(HaveLen(1))
-			Expect(pt.reported[0].MediaId).To(Equal("s1"))
+			Expect(pt.reported[0].MediaId).To(Equal(testID("s1")))
 			Expect(pt.reported[0].PositionMs).To(Equal(int64(1000)))
 			Expect(pt.reported[0].State).To(Equal(scrobbler.StatePlaying))
-			Expect(pt.reported[0].ClientId).To(Equal("p1"))
+			Expect(pt.reported[0].ClientId).To(Equal(testID("p1")))
 			Expect(pt.reported[0].ClientName).To(Equal("Finamp"))
 		})
 
 		It("falls back to the ItemId query param when the body has none", func() {
 			w := httptest.NewRecorder()
-			r := authed(httptest.NewRequest("POST", "/Sessions/Playing?ItemId=s2", nil))
+			r := authed(httptest.NewRequest("POST", "/Sessions/Playing?ItemId="+dto.EncodeID(testID("s2")), nil))
 
 			invoke(api.reportPlaybackStart, w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNoContent))
 			Expect(pt.reported).To(HaveLen(1))
-			Expect(pt.reported[0].MediaId).To(Equal("s2"))
+			Expect(pt.reported[0].MediaId).To(Equal(testID("s2")))
+		})
+
+		It("still reports (with an empty MediaId) for a malformed ItemId, rather than failing the request", func() {
+			w := httptest.NewRecorder()
+			r := authed(httptest.NewRequest("POST", "/Sessions/Playing", strings.NewReader(`{"ItemId":"not-a-valid-id","PositionTicks":10000000}`)))
+
+			invoke(api.reportPlaybackStart, w, r)
+
+			Expect(w.Code).To(Equal(http.StatusNoContent))
+			Expect(pt.reported).To(HaveLen(1))
+			Expect(pt.reported[0].MediaId).To(BeEmpty())
 		})
 	})
 
 	Describe("reportPlaybackProgress", func() {
 		It("reports the playing state when not paused", func() {
 			w := httptest.NewRecorder()
-			r := authed(httptest.NewRequest("POST", "/Sessions/Playing/Progress", strings.NewReader(`{"ItemId":"s1","PositionTicks":20000000,"IsPaused":false}`)))
+			r := authed(httptest.NewRequest("POST", "/Sessions/Playing/Progress", strings.NewReader(`{"ItemId":"`+dto.EncodeID(testID("s1"))+`","PositionTicks":20000000,"IsPaused":false}`)))
 
 			invoke(api.reportPlaybackProgress, w, r)
 
@@ -110,7 +122,7 @@ var _ = Describe("Sessions", func() {
 
 		It("reports the paused state when IsPaused is true", func() {
 			w := httptest.NewRecorder()
-			r := authed(httptest.NewRequest("POST", "/Sessions/Playing/Progress", strings.NewReader(`{"ItemId":"s1","PositionTicks":20000000,"IsPaused":true}`)))
+			r := authed(httptest.NewRequest("POST", "/Sessions/Playing/Progress", strings.NewReader(`{"ItemId":"`+dto.EncodeID(testID("s1"))+`","PositionTicks":20000000,"IsPaused":true}`)))
 
 			invoke(api.reportPlaybackProgress, w, r)
 
@@ -123,14 +135,14 @@ var _ = Describe("Sessions", func() {
 	Describe("reportPlaybackStopped", func() {
 		It("reports the stopped state and lets the scrobbler apply its play threshold", func() {
 			w := httptest.NewRecorder()
-			r := authed(httptest.NewRequest("POST", "/Sessions/Playing/Stopped", strings.NewReader(`{"ItemId":"s1","PositionTicks":600000000}`)))
+			r := authed(httptest.NewRequest("POST", "/Sessions/Playing/Stopped", strings.NewReader(`{"ItemId":"`+dto.EncodeID(testID("s1"))+`","PositionTicks":600000000}`)))
 
 			invoke(api.reportPlaybackStopped, w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNoContent))
 
 			Expect(pt.reported).To(HaveLen(1))
-			Expect(pt.reported[0].MediaId).To(Equal("s1"))
+			Expect(pt.reported[0].MediaId).To(Equal(testID("s1")))
 			Expect(pt.reported[0].State).To(Equal(scrobbler.StateStopped))
 			Expect(pt.reported[0].PositionMs).To(Equal(int64(60000)))
 			// IgnoreScrobble stays false so ReportPlayback's own StateStopped threshold decides
diff --git a/server/jellyfin/similar.go b/server/jellyfin/similar.go
index 2698073bf..3e0b3b11b 100644
--- a/server/jellyfin/similar.go
+++ b/server/jellyfin/similar.go
@@ -6,7 +6,6 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -56,7 +55,10 @@ func (api *Router) awaitSimilar(ctx context.Context, id string, limit int, fetch
 // external.Provider that powers Subsonic's getArtistInfo2. Only artists present in the library are
 // returned. Any provider error degrades to an empty result, not a 404 the client would keep retrying.
 func (api *Router) getSimilarArtists(w http.ResponseWriter, r *http.Request) {
-	id := api.resolveItemID(r.Context(), dto.DecodeID(chi.URLParam(r, "itemId")))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	limit := clampLimit(req.Params(r).IntOr("limit", 0), defaultSimilarLimit, maxSimilarLimit)
 	api.ok(w, r, api.awaitSimilar(r.Context(), id, limit, func(ctx context.Context) dto.QueryResult {
 		return api.similarArtists(ctx, id, limit)
@@ -68,7 +70,10 @@ func (api *Router) getSimilarArtists(w http.ResponseWriter, r *http.Request) {
 // result (not 404) so the client stops retrying.
 func (api *Router) getSimilarItems(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := api.resolveItemID(ctx, dto.DecodeID(chi.URLParam(r, "itemId")))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	limit := clampLimit(req.Params(r).IntOr("limit", 0), defaultSimilarLimit, maxSimilarLimit)
 
 	entity, err := model.GetEntityByID(ctx, api.ds, id)
@@ -93,7 +98,10 @@ func (api *Router) getSimilarItems(w http.ResponseWriter, r *http.Request) {
 // results, never a 404 the client would surface as an error.
 func (api *Router) getInstantMix(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	id := api.resolveItemID(ctx, dto.DecodeID(chi.URLParam(r, "itemId")))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
 	limit := clampLimit(req.Params(r).IntOr("limit", 0), defaultSimilarLimit, maxInstantMixLimit)
 
 	entity, err := model.GetEntityByID(ctx, api.ds, id)
diff --git a/server/jellyfin/similar_test.go b/server/jellyfin/similar_test.go
index 302566195..dc8c1e605 100644
--- a/server/jellyfin/similar_test.go
+++ b/server/jellyfin/similar_test.go
@@ -34,7 +34,7 @@ var _ = Describe("awaitSimilar", func() {
 	})
 
 	It("returns the fetch result when it completes within the wait", func() {
-		res := api.awaitSimilar(ctxFor("u1"), "id1", 20, func(context.Context) dto.QueryResult {
+		res := api.awaitSimilar(ctxFor(testID("u1")), "id1", 20, func(context.Context) dto.QueryResult {
 			return result([]dto.BaseItemDto{{Name: "fast"}}, 1, 0)
 		})
 		Expect(res.Items).To(HaveLen(1))
@@ -45,7 +45,7 @@ var _ = Describe("awaitSimilar", func() {
 		shortenWait()
 		release := make(chan struct{})
 		DeferCleanup(func() { close(release) })
-		res := api.awaitSimilar(ctxFor("u1"), "id2", 20, func(context.Context) dto.QueryResult {
+		res := api.awaitSimilar(ctxFor(testID("u1")), "id2", 20, func(context.Context) dto.QueryResult {
 			<-release // hung provider; would finish caching in the background
 			return result([]dto.BaseItemDto{{Name: "late"}}, 1, 0)
 		})
@@ -64,8 +64,8 @@ var _ = Describe("awaitSimilar", func() {
 		}
 		// Both calls time out, but the flight can't complete before release closes, so the
 		// second call must join it rather than start a new fetch.
-		api.awaitSimilar(ctxFor("u1"), "id3", 20, fetch)
-		api.awaitSimilar(ctxFor("u1"), "id3", 20, fetch)
+		api.awaitSimilar(ctxFor(testID("u1")), "id3", 20, fetch)
+		api.awaitSimilar(ctxFor(testID("u1")), "id3", 20, fetch)
 		close(release)
 		Eventually(calls.Load).Should(Equal(int32(1)))
 		Consistently(calls.Load, "50ms").Should(Equal(int32(1)))
@@ -77,15 +77,15 @@ var _ = Describe("awaitSimilar", func() {
 			calls.Add(1)
 			return result(nil, 0, 0)
 		}
-		api.awaitSimilar(ctxFor("u1"), "id4", 20, fetch)
-		api.awaitSimilar(ctxFor("u2"), "id4", 20, fetch)
+		api.awaitSimilar(ctxFor(testID("u1")), "id4", 20, fetch)
+		api.awaitSimilar(ctxFor(testID("u2")), "id4", 20, fetch)
 		Expect(calls.Load()).To(Equal(int32(2)))
 	})
 
 	It("hands the fetch a deadline-bounded background context", func() {
 		var deadline time.Time
 		var hasDeadline bool
-		api.awaitSimilar(ctxFor("u1"), "id5", 20, func(ctx context.Context) dto.QueryResult {
+		api.awaitSimilar(ctxFor(testID("u1")), "id5", 20, func(ctx context.Context) dto.QueryResult {
 			deadline, hasDeadline = ctx.Deadline()
 			return result(nil, 0, 0)
 		})
@@ -123,16 +123,16 @@ var _ = Describe("getInstantMix", func() {
 
 		ds := &tests.MockDataStore{}
 		ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-			{ID: "s1", Title: "Seed Song", LibraryID: 1},
+			{ID: testID("s1"), Title: "Seed Song", LibraryID: 1},
 		})
 		release := make(chan struct{})
 		DeferCleanup(func() { close(release) })
 		api := &Router{ds: ds, provider: &blockingProvider{release: release}}
 
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("s1")+"/InstantMix", nil).
-			WithContext(request.WithUser(context.Background(), model.User{ID: "u1", Libraries: model.Libraries{{ID: 1}}}))
-		r = withChiURLParam(r, "itemId", dto.EncodeID("s1"))
+		r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("s1"))+"/InstantMix", nil).
+			WithContext(request.WithUser(context.Background(), model.User{ID: testID("u1"), Libraries: model.Libraries{{ID: 1}}}))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 		api.getInstantMix(w, r)
 
 		var res dto.QueryResult
@@ -145,18 +145,18 @@ var _ = Describe("getInstantMix", func() {
 	// queue, so InstantMix gets its own, higher ceiling.
 	It("honors a mix-sized limit above the Similar ceiling", func() {
 		const want = 250
-		songs := model.MediaFiles{{ID: "s1", Title: "Seed Song", LibraryID: 1}}
+		songs := model.MediaFiles{{ID: testID("s1"), Title: "Seed Song", LibraryID: 1}}
 		for i := range want + 50 { // more than requested, so only the limit bounds the result
-			songs = append(songs, model.MediaFile{ID: fmt.Sprintf("t%d", i), Title: fmt.Sprintf("Track %d", i), LibraryID: 1})
+			songs = append(songs, model.MediaFile{ID: testID(fmt.Sprintf("t%d", i)), Title: fmt.Sprintf("Track %d", i), LibraryID: 1})
 		}
 		ds := &tests.MockDataStore{}
 		ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
 		api := &Router{ds: ds, provider: &fakeSimilarProvider{songs: songs[1:]}}
 
 		w := httptest.NewRecorder()
-		r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID("s1")+"/InstantMix?limit="+strconv.Itoa(want), nil).
-			WithContext(request.WithUser(context.Background(), model.User{ID: "u1", Libraries: model.Libraries{{ID: 1}}}))
-		r = withChiURLParam(r, "itemId", dto.EncodeID("s1"))
+		r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("s1"))+"/InstantMix?limit="+strconv.Itoa(want), nil).
+			WithContext(request.WithUser(context.Background(), model.User{ID: testID("u1"), Libraries: model.Libraries{{ID: 1}}}))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 		api.getInstantMix(w, r)
 
 		var res dto.QueryResult
diff --git a/server/jellyfin/socket_test.go b/server/jellyfin/socket_test.go
index 8c509fe91..401c791fd 100644
--- a/server/jellyfin/socket_test.go
+++ b/server/jellyfin/socket_test.go
@@ -88,9 +88,9 @@ var _ = Describe("handleSocket", func() {
 			ds = &tests.MockDataStore{}
 			auth.Init(ds)
 			ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-			Expect(ur.Put(&model.User{ID: "u1", UserName: "alice", NewPassword: "secret"})).To(Succeed())
+			Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
 
-			t, err := auth.CreateToken(&model.User{ID: "u1", UserName: "alice"})
+			t, err := auth.CreateToken(&model.User{ID: testID("u1"), UserName: "alice"})
 			Expect(err).ToNot(HaveOccurred())
 			token = t
 
diff --git a/server/jellyfin/stream.go b/server/jellyfin/stream.go
index 022c00c96..86746f89a 100644
--- a/server/jellyfin/stream.go
+++ b/server/jellyfin/stream.go
@@ -23,7 +23,10 @@ import (
 // Shared by getPlaybackInfo and streamAudio so a guessed id can't probe or stream another library.
 func (api *Router) mediaFileForRequest(w http.ResponseWriter, r *http.Request) (*model.MediaFile, bool) {
 	ctx := r.Context()
-	id := api.resolveItemID(ctx, dto.DecodeID(chi.URLParam(r, "itemId")))
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return nil, false
+	}
 	mf, err := api.ds.MediaFile(ctx).Get(id)
 	if err != nil {
 		http.Error(w, "Not Found", http.StatusNotFound)
@@ -62,7 +65,7 @@ func (api *Router) getPlaybackInfo(w http.ResponseWriter, r *http.Request) {
 		src.TranscodingSubProtocol = "http"
 		src.TranscodingUrl = consts.URLPathJellyfinAPI + "/Audio/" + src.Id + "/universal?static=true&api_key=" + url.QueryEscape(token)
 	}
-	api.ok(w, r, dto.PlaybackInfoResponse{MediaSources: []dto.MediaSourceInfo{src}, PlaySessionId: mf.ID})
+	api.ok(w, r, dto.PlaybackInfoResponse{MediaSources: []dto.MediaSourceInfo{src}, PlaySessionId: dto.EncodeID(mf.ID)})
 }
 
 // streamAudio serves /Audio/{itemId}/stream[.container] and /Audio/{itemId}/universal,
diff --git a/server/jellyfin/stream_test.go b/server/jellyfin/stream_test.go
index f77c10ec1..d6220d33f 100644
--- a/server/jellyfin/stream_test.go
+++ b/server/jellyfin/stream_test.go
@@ -26,7 +26,7 @@ var _ = Describe("Stream", func() {
 
 	// alice has access to library 1 only.
 	ctxUser := func() context.Context {
-		return request.WithUser(context.Background(), model.User{ID: "u1", UserName: "alice", Libraries: model.Libraries{{ID: 1, Name: "Music"}}})
+		return request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: model.Libraries{{ID: 1, Name: "Music"}}})
 	}
 
 	BeforeEach(func() {
@@ -43,30 +43,30 @@ var _ = Describe("Stream", func() {
 	Describe("getPlaybackInfo", func() {
 		It("returns a media source for an accessible track", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", Duration: 100, Size: 1000, LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", Duration: 100, Size: 1000, LibraryID: 1},
 			})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("s1")+"/PlaybackInfo", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("s1"))
+			r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("s1"))+"/PlaybackInfo", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			api.getPlaybackInfo(w, r)
 
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.PlaybackInfoResponse
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.MediaSources).To(HaveLen(1))
-			Expect(res.MediaSources[0].Id).To(Equal(dto.EncodeID("s1")))
+			Expect(res.MediaSources[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
 			Expect(res.MediaSources[0].Container).To(Equal("mp3"))
 			Expect(res.MediaSources[0].Size).To(Equal(int64(1000)))
-			Expect(res.PlaySessionId).ToNot(BeEmpty())
+			Expect(res.PlaySessionId).To(MatchRegexp("^[0-9a-f]{32}$"))
 		})
 
 		It("returns 404 for a track in a library the user can't access", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 2},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 2},
 			})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Items/s1/PlaybackInfo", nil).WithContext(ctxUser()) // only has access to library 1
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("s1"))+"/PlaybackInfo", nil).WithContext(ctxUser()) // only has access to library 1
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			api.getPlaybackInfo(w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNotFound))
@@ -75,7 +75,7 @@ var _ = Describe("Stream", func() {
 		It("returns 404 when the id doesn't match any media file", func() {
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Items/missing/PlaybackInfo", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "missing")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("missing")))
 			api.getPlaybackInfo(w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNotFound))
@@ -83,8 +83,8 @@ var _ = Describe("Stream", func() {
 
 		playbackInfo := func() dto.PlaybackInfoResponse {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("s1")+"/PlaybackInfo", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("s1"))
+			r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("s1"))+"/PlaybackInfo", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			api.getPlaybackInfo(w, r)
 			var res dto.PlaybackInfoResponse
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
@@ -103,10 +103,10 @@ var _ = Describe("Stream", func() {
 
 		It("advertises a Lyric stream for plugin/sidecar-sourced lyrics not embedded in the file", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			api.lyrics = &fakeLyricsService{lyrics: map[string]model.LyricList{
-				"s1": {{Kind: "main", Synced: true, Line: []model.Line{{Value: "hello"}}}},
+				testID("s1"): {{Kind: "main", Synced: true, Line: []model.Line{{Value: "hello"}}}},
 			}}
 
 			Expect(lyricStreams(playbackInfo())).To(HaveLen(1))
@@ -114,7 +114,7 @@ var _ = Describe("Stream", func() {
 
 		It("advertises no Lyric stream when the pipeline finds nothing", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 
 			Expect(lyricStreams(playbackInfo())).To(BeEmpty())
@@ -122,10 +122,10 @@ var _ = Describe("Stream", func() {
 
 		It("advertises no Lyric stream when the lyrics endpoint would 404 (main lyric has no lines)", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			api.lyrics = &fakeLyricsService{lyrics: map[string]model.LyricList{
-				"s1": {{Kind: "main", Lang: "eng"}},
+				testID("s1"): {{Kind: "main", Lang: "eng"}},
 			}}
 
 			Expect(lyricStreams(playbackInfo())).To(BeEmpty())
@@ -133,10 +133,10 @@ var _ = Describe("Stream", func() {
 
 		It("doesn't duplicate the Lyric stream when lyrics are already embedded", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 1, Lyrics: `[{"lang":"xxx","line":[]}]`},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1, Lyrics: `[{"lang":"xxx","line":[]}]`},
 			})
 			api.lyrics = &fakeLyricsService{lyrics: map[string]model.LyricList{
-				"s1": {{Kind: "main", Synced: true, Line: []model.Line{{Value: "hello"}}}},
+				testID("s1"): {{Kind: "main", Synced: true, Line: []model.Line{{Value: "hello"}}}},
 			}}
 
 			Expect(lyricStreams(playbackInfo())).To(HaveLen(1))
@@ -146,20 +146,20 @@ var _ = Describe("Stream", func() {
 			// Own ID: an erroring loader isn't cached, but a shared ID could still pick up
 			// another test's cached (non-error) result and mask this assertion.
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s-err", Title: "Song", Suffix: "mp3", Duration: 100, Size: 1000, LibraryID: 1},
+				{ID: testID("s-err"), Title: "Song", Suffix: "mp3", Duration: 100, Size: 1000, LibraryID: 1},
 			})
 			api.lyrics = &fakeLyricsService{err: errors.New("boom")}
 
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID("s-err")+"/PlaybackInfo", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", dto.EncodeID("s-err"))
+			r := httptest.NewRequest("POST", "/Items/"+dto.EncodeID(testID("s-err"))+"/PlaybackInfo", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s-err")))
 			api.getPlaybackInfo(w, r)
 
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.PlaybackInfoResponse
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.MediaSources).To(HaveLen(1))
-			Expect(res.MediaSources[0].Id).To(Equal(dto.EncodeID("s-err")))
+			Expect(res.MediaSources[0].Id).To(Equal(dto.EncodeID(testID("s-err"))))
 			Expect(lyricStreams(res)).To(BeEmpty())
 		})
 	})
@@ -167,12 +167,12 @@ var _ = Describe("Stream", func() {
 	Describe("streamAudio", func() {
 		It("invokes the transcode decider and streamer for an accessible track", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			streamer.content = "audio-bytes"
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Audio/s1/stream", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("GET", "/Audio/"+dto.EncodeID(testID("s1"))+"/stream", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.streamAudio, w, r)
 
 			Expect(w.Code).To(Equal(http.StatusOK))
@@ -183,11 +183,11 @@ var _ = Describe("Stream", func() {
 
 		It("returns 404 for a track in a library the user can't access, without invoking the streamer or decider", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 2},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 2},
 			})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Audio/s1/stream", nil).WithContext(ctxUser()) // only has access to library 1
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("GET", "/Audio/"+dto.EncodeID(testID("s1"))+"/stream", nil).WithContext(ctxUser()) // only has access to library 1
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.streamAudio, w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNotFound))
@@ -198,7 +198,7 @@ var _ = Describe("Stream", func() {
 		It("returns 404 when the id doesn't match any media file, without invoking the streamer or decider", func() {
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Audio/missing/stream", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "missing")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("missing")))
 			invoke(api.streamAudio, w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNotFound))
@@ -208,11 +208,11 @@ var _ = Describe("Stream", func() {
 
 		It("converts the bps audioBitRate param to kbps", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "flac", LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "flac", LibraryID: 1},
 			})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Audio/s1/stream?audiobitrate=320000", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("GET", "/Audio/"+dto.EncodeID(testID("s1"))+"/stream?audiobitrate=320000", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.streamAudio, w, r)
 
 			Expect(decider.req.BitRate).To(Equal(320))
@@ -220,11 +220,11 @@ var _ = Describe("Stream", func() {
 
 		It("uses the audioCodec param as target format when no container is given", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "flac", LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "flac", LibraryID: 1},
 			})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Audio/s1/stream?audiocodec=aac", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("GET", "/Audio/"+dto.EncodeID(testID("s1"))+"/stream?audiocodec=aac", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.streamAudio, w, r)
 
 			Expect(decider.req.Format).To(Equal("aac"))
@@ -232,12 +232,12 @@ var _ = Describe("Stream", func() {
 
 		It("returns 500 and logs when the streamer fails", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			streamer.err = errors.New("boom")
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Audio/s1/stream", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("GET", "/Audio/"+dto.EncodeID(testID("s1"))+"/stream", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.streamAudio, w, r)
 
 			Expect(w.Code).To(Equal(http.StatusInternalServerError))
@@ -247,14 +247,14 @@ var _ = Describe("Stream", func() {
 	Describe("streamHls", func() {
 		BeforeEach(func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "dsf", Duration: 100.5, LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "dsf", Duration: 100.5, LibraryID: 1},
 			})
 		})
 
 		hls := func(query string, ctx context.Context) *httptest.ResponseRecorder {
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Audio/s1/main.m3u8"+query, nil).WithContext(ctx)
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("GET", "/Audio/"+dto.EncodeID(testID("s1"))+"/main.m3u8"+query, nil).WithContext(ctx)
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			invoke(api.streamHls, w, r)
 			return w
 		}
@@ -302,7 +302,7 @@ var _ = Describe("Stream", func() {
 
 		It("returns 404 for a track in a library the user can't access", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "dsf", LibraryID: 2},
+				{ID: testID("s1"), Title: "Song", Suffix: "dsf", LibraryID: 2},
 			})
 			Expect(hls("", ctxUser()).Code).To(Equal(http.StatusNotFound))
 		})
@@ -316,12 +316,12 @@ var _ = Describe("Stream", func() {
 	Describe("streamFile", func() {
 		It("invokes the decider with a raw/direct-play request and the streamer for an accessible track", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 1},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			streamer.content = "audio-bytes"
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/s1/File", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("s1"))+"/File", nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			api.streamFile(w, r)
 
 			Expect(w.Code).To(Equal(http.StatusOK))
@@ -333,11 +333,11 @@ var _ = Describe("Stream", func() {
 
 		It("returns 404 for a track in a library the user can't access, without invoking the streamer or decider", func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
-				{ID: "s1", Title: "Song", Suffix: "mp3", LibraryID: 2},
+				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 2},
 			})
 			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items/s1/File", nil).WithContext(ctxUser()) // only has access to library 1
-			r = withChiURLParam(r, "itemId", "s1")
+			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("s1"))+"/File", nil).WithContext(ctxUser()) // only has access to library 1
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
 			api.streamFile(w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNotFound))
@@ -348,7 +348,7 @@ var _ = Describe("Stream", func() {
 		It("returns 404 when the id doesn't match any media file, without invoking the streamer or decider", func() {
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/missing/File", nil).WithContext(ctxUser())
-			r = withChiURLParam(r, "itemId", "missing")
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("missing")))
 			api.streamFile(w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNotFound))
diff --git a/server/jellyfin/system.go b/server/jellyfin/system.go
index 6f0c359d4..ea553fd87 100644
--- a/server/jellyfin/system.go
+++ b/server/jellyfin/system.go
@@ -2,10 +2,12 @@ package jellyfin
 
 import (
 	"context"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"net/http"
 	"path"
+	"strings"
 
 	"github.com/google/uuid"
 	"github.com/navidrome/navidrome/conf"
@@ -42,25 +44,32 @@ func (api *Router) serverID(ctx context.Context) string {
 		return api.serverIDVal
 	}
 	if api.ds == nil {
-		api.serverIDVal = uuid.NewString()
+		api.serverIDVal = newServerID()
 		return api.serverIDVal
 	}
 	id, err := api.ds.Property(ctx).Get(consts.JellyfinServerIDKey)
 	switch {
 	case errors.Is(err, model.ErrNotFound):
-		id = uuid.NewString()
+		id = newServerID()
 		if err := api.ds.Property(ctx).Put(consts.JellyfinServerIDKey, id); err != nil {
 			log.Error(ctx, "Jellyfin API: could not persist server id", err)
 			return id
 		}
 	case err != nil:
 		log.Error(ctx, "Jellyfin API: could not read server id", err)
-		return uuid.NewString()
+		return newServerID()
 	}
-	api.serverIDVal = id
+	// Ids persisted before this change are dashed; normalize on read rather than rewriting the DB.
+	api.serverIDVal = strings.ReplaceAll(id, "-", "")
 	return api.serverIDVal
 }
 
+// newServerID returns a UUID in Jellyfin's no-dash GUID form (Guid.ToString("N")).
+func newServerID() string {
+	u := uuid.New()
+	return hex.EncodeToString(u[:])
+}
+
 func (api *Router) publicInfo(r *http.Request) dto.PublicSystemInfo {
 	return dto.PublicSystemInfo{
 		LocalAddress:           localAddress(r),
diff --git a/server/jellyfin/system_test.go b/server/jellyfin/system_test.go
index 7846e4a20..a7f7df6a4 100644
--- a/server/jellyfin/system_test.go
+++ b/server/jellyfin/system_test.go
@@ -125,21 +125,33 @@ var _ = Describe("System", func() {
 		})
 
 		It("does not overwrite or pin over a stored id when the property read fails transiently", func() {
-			Expect(ds.Property(ctx).Put(consts.JellyfinServerIDKey, "stable-id")).To(Succeed())
+			Expect(ds.Property(ctx).Put(consts.JellyfinServerIDKey, "6ba7b8109dad11d180b400c04fd430c8")).To(Succeed())
 
 			r := &Router{ds: ds}
 			props := ds.Property(ctx).(*tests.MockedPropertyRepo)
 			props.Error = errors.New("database is locked")
 			degraded := r.serverID(ctx)
 			Expect(degraded).ToNot(BeEmpty())
-			Expect(degraded).ToNot(Equal("stable-id")) // temporary value, not the (unreadable) stored one
+			Expect(degraded).ToNot(Equal("6ba7b8109dad11d180b400c04fd430c8")) // temporary value, not the (unreadable) stored one
 			props.Error = nil
 
 			// Once the DB recovers, the stored id is intact and served again.
-			Expect(r.serverID(ctx)).To(Equal("stable-id"))
+			Expect(r.serverID(ctx)).To(Equal("6ba7b8109dad11d180b400c04fd430c8"))
 			stored, err := ds.Property(ctx).Get(consts.JellyfinServerIDKey)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(stored).To(Equal("stable-id"))
+			Expect(stored).To(Equal("6ba7b8109dad11d180b400c04fd430c8"))
+		})
+
+		It("returns Jellyfin's no-dash GUID form", func() {
+			r := &Router{ds: ds}
+			Expect(r.serverID(ctx)).To(MatchRegexp("^[0-9a-f]{32}$"))
+		})
+
+		It("strips dashes from an already-persisted id", func() {
+			Expect(ds.Property(ctx).Put(
+				consts.JellyfinServerIDKey, "1b4e28ba-2fa1-11d2-883f-0016d3cca427")).To(Succeed())
+			r := &Router{ds: ds}
+			Expect(r.serverID(ctx)).To(Equal("1b4e28ba2fa111d2883f0016d3cca427"))
 		})
 	})
 })
diff --git a/server/jellyfin/truncated_ids.go b/server/jellyfin/truncated_ids.go
deleted file mode 100644
index bb3e4ce9b..000000000
--- a/server/jellyfin/truncated_ids.go
+++ /dev/null
@@ -1,113 +0,0 @@
-package jellyfin
-
-import (
-	"context"
-	"slices"
-
-	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/utils/slice"
-)
-
-// truncatedIDLen is what Finamp's saved-queue persistence cuts item ids to (16 bytes, assuming
-// Jellyfin GUIDs). All Navidrome ids are 22 chars (share ids 10), so length alone flags a
-// truncated id. See README.
-//
-// Handlers taking an item id resolve it via resolveItemID/resolveItemIDs; playlist-write handlers
-// and ParentId scoping don't (a restored queue never edits playlists or browses by container id).
-const truncatedIDLen = 16
-
-// resolveItemID maps a truncated item id back to the full id via unique-prefix lookup. The id is
-// returned unchanged when it isn't truncation-shaped, matches nothing, or is ambiguous.
-func (api *Router) resolveItemID(ctx context.Context, id string) string {
-	if len(id) != truncatedIDLen {
-		return id
-	}
-	probes := []func() []string{
-		func() []string { return idsMatching(api.ds.MediaFile(ctx).GetAll, "media_file.id", id, mediaFileID) },
-		func() []string { return idsMatching(api.ds.Album(ctx).GetAll, "album.id", id, albumID) },
-		func() []string { return idsMatching(api.ds.Artist(ctx).GetAll, "artist.id", id, artistID) },
-		func() []string { return idsMatching(api.ds.Playlist(ctx).GetAll, "playlist.id", id, playlistID) },
-	}
-	for _, probe := range probes {
-		switch ids := probe(); len(ids) {
-		case 0:
-			continue
-		case 1:
-			log.Trace(ctx, "Jellyfin API: resolved truncated item id", "truncated", id, "full", ids[0])
-			return ids[0]
-		default:
-			log.Warn(ctx, "Jellyfin API: truncated item id is ambiguous", "truncated", id)
-			return id
-		}
-	}
-	return id
-}
-
-// resolveItemIDs is the batch form of resolveItemID for id lists (queue restore sends hundreds of
-// truncated ids): all media-file prefixes are resolved with one chunked range query, and only the
-// leftovers (containers, unknowns) fall back to the per-id probes.
-func (api *Router) resolveItemIDs(ctx context.Context, ids []string) []string {
-	var truncated []string
-	for _, id := range ids {
-		if len(id) == truncatedIDLen {
-			truncated = append(truncated, id)
-		}
-	}
-	if len(truncated) == 0 {
-		return ids
-	}
-
-	byPrefix := make(map[string][]string, len(truncated))
-	for chunk := range slice.CollectChunks(slices.Values(truncated), 100) {
-		ranges := make(squirrel.Or, len(chunk))
-		for i, p := range chunk {
-			ranges[i] = squirrel.And{squirrel.GtOrEq{"media_file.id": p}, squirrel.Lt{"media_file.id": p + "\x7f"}}
-		}
-		mfs, err := api.ds.MediaFile(ctx).GetAll(model.QueryOptions{Filters: ranges})
-		if err != nil {
-			log.Error(ctx, "Jellyfin API: error batch-resolving truncated ids", err)
-			break
-		}
-		for _, mf := range mfs {
-			p := mf.ID[:truncatedIDLen]
-			byPrefix[p] = append(byPrefix[p], mf.ID)
-		}
-	}
-
-	out := make([]string, len(ids))
-	for i, id := range ids {
-		switch full := byPrefix[id]; {
-		case len(full) == 1:
-			out[i] = full[0]
-		case len(id) == truncatedIDLen:
-			out[i] = api.resolveItemID(ctx, id) // ambiguous or not a song: per-id probes decide
-		default:
-			out[i] = id
-		}
-	}
-	return out
-}
-
-// idsMatching returns the ids of up to two rows whose id starts with prefix (two is enough to
-// detect ambiguity). '\x7f' is above every character the id alphabets use.
-func idsMatching[S ~[]T, T any](getAll func(...model.QueryOptions) (S, error), column, prefix string, id func(T) string) []string {
-	rows, err := getAll(model.QueryOptions{
-		Filters: squirrel.And{squirrel.GtOrEq{column: prefix}, squirrel.Lt{column: prefix + "\x7f"}},
-		Max:     2,
-	})
-	if err != nil {
-		return nil
-	}
-	ids := make([]string, len(rows))
-	for i, row := range rows {
-		ids[i] = id(row)
-	}
-	return ids
-}
-
-func mediaFileID(mf model.MediaFile) string { return mf.ID }
-func albumID(al model.Album) string         { return al.ID }
-func artistID(ar model.Artist) string       { return ar.ID }
-func playlistID(pl model.Playlist) string   { return pl.ID }
diff --git a/server/jellyfin/users_test.go b/server/jellyfin/users_test.go
index 6a1597b70..3e53d598f 100644
--- a/server/jellyfin/users_test.go
+++ b/server/jellyfin/users_test.go
@@ -19,7 +19,7 @@ import (
 var _ = Describe("Users", func() {
 	var api *Router
 	authedWithLibraries := func(r *http.Request, libs model.Libraries) *http.Request {
-		ctx := request.WithUser(context.Background(), model.User{ID: "u1", UserName: "alice", Libraries: libs})
+		ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: libs})
 		return r.WithContext(ctx)
 	}
 	BeforeEach(func() { api = &Router{ds: &tests.MockDataStore{}} })
@@ -35,13 +35,13 @@ var _ = Describe("Users", func() {
 			Expect(res.Items).To(HaveLen(2))
 			Expect(res.TotalRecordCount).To(Equal(2))
 
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("1")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeLibraryID(1)))
 			Expect(res.Items[0].Name).To(Equal("Music"))
 			Expect(res.Items[0].Type).To(Equal("CollectionFolder"))
 			Expect(res.Items[0].CollectionType).To(Equal("music"))
 			Expect(res.Items[0].IsFolder).To(BeTrue())
 
-			Expect(res.Items[1].Id).To(Equal(dto.EncodeID("2")))
+			Expect(res.Items[1].Id).To(Equal(dto.EncodeLibraryID(2)))
 			Expect(res.Items[1].Name).To(Equal("Podcasts"))
 		})
 
@@ -53,7 +53,7 @@ var _ = Describe("Users", func() {
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.Items).To(HaveLen(1))
-			Expect(res.Items[0].Id).To(Equal(dto.EncodeID("1")))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeLibraryID(1)))
 		})
 
 		It("returns no views for a user with no library access", func() {
@@ -92,8 +92,8 @@ var _ = Describe("Users", func() {
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
 			ur = api.ds.User(context.Background()).(*tests.MockedUserRepo)
-			Expect(ur.Put(&model.User{ID: "u1", UserName: "alice"})).To(Succeed())
-			Expect(ur.Put(&model.User{ID: "u2", UserName: "bob"})).To(Succeed())
+			Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice"})).To(Succeed())
+			Expect(ur.Put(&model.User{ID: testID("u2"), UserName: "bob"})).To(Succeed())
 		})
 
 		It("returns an empty list when the config is unset", func() {
@@ -106,7 +106,7 @@ var _ = Describe("Users", func() {
 			users := publicUsers()
 			Expect(users).To(HaveLen(2))
 			Expect(users[0].Name).To(Equal("bob"))
-			Expect(users[0].Id).To(Equal(dto.EncodeID("u2")))
+			Expect(users[0].Id).To(Equal(dto.EncodeID(testID("u2"))))
 			Expect(users[1].Name).To(Equal("alice"))
 			// The public list must not expose Policy/Configuration to unauthenticated callers.
 			Expect(users[0].Policy).To(BeNil())

From 6c3e7e268be20f7a090542dfd2a65781b3ef2ab7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 12 Aug 2026 23:02:13 -0400
Subject: [PATCH 034/200] feat(instant-mix): support album, playlist and genre
 sources (#5948)

* feat(agents): local agent genre-hint similar songs fallback

* feat(external): playlist instant mix via seed-track sampling

* test(external): cover playlist mix never-empty fallback and maxSeeds cap

Adds coverage for the empty-match seed fallback and the maxSeeds
call cap on GetSimilarSongsByTrack, per code review finding.

* feat(external): genre instant mix via seed-track sampling

* feat(external): album instant mix falls back to AudioMuse track similarity

* feat(external): artist instant mix falls back to seed-track sampling

* fix(jellyfin): route genre seeds through instant mix instead of empty

* feat(jellyfin): add /Albums/{id}/Similar route for albumMix radio

* perf(external): bound playlist seed sampling to a random N

samplePlaylistTracks loaded an entire playlist's joined rows just to keep
5 random seeds; push the bound and randomization into the query instead,
matching the other samplers (GetRandom/GetAllByTags with Max).

Fixing this surfaced a real bug: resetSeededRandom's SEEDEDRAND rewrite
assumed every table's id is TEXT, but playlist_tracks.id is an INTEGER
position, so the random sort silently dropped every row. Cast the id to
TEXT before hashing (no-op for the other, TEXT-id tables).

Also trims a changelog-flavored comment and a duplicated rationale in
server/jellyfin/similar_test.go.

* refactor(external): parallelize seed mix and dedup mix helpers

Run the up-to-5 per-seed GetSimilarSongsByTrack calls concurrently (errgroup),
route the four container cases through a shared seedMix helper, flatten the
genre lookup, and sample playlist seeds without forcing a smart-playlist
rebuild. Share the media-file->Song mapping in the local agent.

* perf(agents): use the indexed genre filter for local similarity

Replace GetAllByTags (a json_tree scan of every media_file row) with the
media_file_tags semi-join from #5940, deriving the seed's genre tag ids
locally since they hash from (name, value).

Also carry the library id and the recording MBID on the returned songs:
the matcher resolves by id first and looks up mbz_recording_id, so the
release-track id it got before matched nothing and the local fallback
silently returned no songs.

* refactor: drop redundant MBID and fold mixFromSeeds into seedMix

The local agent returns library tracks, so the id alone resolves them in the
matcher's first phase; the MBID was never consulted. mixFromSeeds had no
caller other than seedMix.

* docs: trim redundant comments

* fix(jellyfin): adopt the GUID id codec in the merged similar routes

getSimilarAlbums still used resolveItemID/DecodeID, which #5942 replaced with
itemIDParam; its tests passed raw ids that the strict codec now rejects.

* fix(external): guard non-positive counts and blend every seed

A negative Subsonic count reached matched[:count] and panicked. The matcher
also keeps input order and stops at count, so seed-grouped results let the
first seed fill the whole mix; interleaving gives every seed a share.

Drops the duplicate playlist-track mock in favour of tests.MockPlaylistTrackRepo,
which pages like the real repository and records the query options.

* fix(external): refresh smart playlists before sampling seeds

A smart playlist materializes no playlist_tracks until it is evaluated, so
sampling without the refresh mixed an empty seed set. The refresh is a no-op
for regular playlists, inside the refresh delay, and for non-owners.

* fix(external): skip missing tracks and a nil playlist-track repo when sampling

Tracks() logs and returns a nil repository when its own lookup fails, so the
chained GetAll panicked. Seeds can also reach the mix verbatim when the agents
find nothing, so a missing file would surface as an unplayable entry.

* fix(jellyfin): never report the seed album as its own similar album

The sampled-seed fallback returns the album's own tracks, which similarAlbums
mapped straight back to the requested album, often as the only result.

* test(agents): assert the genre predicate instead of relying on the mock

MockMediaFileRepo ignores QueryOptions.Filters, so the spec passed even with
no genre filter at all. It now checks the generated predicate carries the
seed's own tag id, the indexed join and the missing exclusion.

* fix(external): clamp the requested count before it becomes a query limit

Subsonic passes the client's count through unbounded. At MaxInt64 the local
agent's count+1 overflows negative, and GetRandom omits the SQL limit unless
Max is positive, so one request would hydrate every matching track. 500 is
what the widest caller (similarAlbums, limit*5) legitimately asks for.

* fix(external): deduplicate playlist seeds by media file

A playlist can hold the same file at several positions, so sampling its rows
could seed the mix twice: a wasted agent call, and a duplicate track whenever
the seed fallback kicks in.

* fix(external): drop tracks two seeds both recommend

The matcher re-emits a track when two inputs are identical, so overlapping
recommendations took several slots in the mix. Match the whole merged set and
dedup before trimming. Playlist sampling now over-fetches before its own
dedup, so repeated positions cannot collapse the seed count.

* test(external): make the seed-blend assertion independent of the shuffle

It matched four tracks and kept two at random, so both could come from the
first seed once in six runs. Keeping three of the four makes a seed-two track
unavoidable.

* fix(external): seed artist mixes from every credited role

media_file.artist_id is the deprecated primary artist, so an artist credited
only on the album, as on compilations, sampled no seeds at all. Use the same
participant filter the artist listings use.

* refactor(external): drop the now-vestigial seed interleaving

Matching the whole merged set removed the early truncation the interleave
guarded against, and the shuffle before the trim makes input order irrelevant.
Its comment described the old behaviour.

* test(agents): give the id-mapping fixture a matching genre

The related track carried no genre, so the real query would never return it;
the spec only passed because the mock ignores QueryOptions.Filters.

* test(agents): drop the MBID from the id-mapping fixture

Local agent candidates are non-missing library rows, so the matcher always
resolves them in its id phase and never reads the MBID. The field guarded a
regression that could not change behaviour.

* test(agents): remove unnecessary comment about MBID in GetArtistTopSongs test

* fix(jellyfin): only let a not-found entity fall through in getInstantMix

Discarding the error conflated a genre id, which never resolves, with a real
lookup failure, which then made a provider call that fails the same way.

* test: pin the invariants the specs only appeared to cover

The missing filter was asserted by substring, so flipping it to true passed
everywhere, including the spec named for it. Matching the whole merged set,
the local agent's over-fetch, and its no-genres early return had no coverage
at all; each is now pinned by a spec that fails when the code is broken.

* test: make the remaining specs say what they actually guard

The playlist-track spec named a sort whitelist it does not exercise; it guards
the integer-id CAST, so it now asserts no rows are dropped. The maxSeeds cap
passed with either bound removed, and the over-fetch was pinned by its literal
value rather than the duplicate positions it exists for. Also drops setup the
count guard returns before reaching.

* fix(external): fall back when the agent's picks are not in this library

A non-empty answer whose songs are all absent locally matched nothing and was
returned as-is, so the mix came back empty with sampleable source tracks
sitting right there.

* refactor(external): name the agent-then-fallback flow once

Each entity case repeated the same error and emptiness plumbing around the
matcher. mixFromAgent states it once and each case supplies only what differs:
how to ask, and what to do when the answer is unusable.
---
 core/agents/agents_test.go                    |   4 +-
 core/agents/local_agent.go                    |  53 +-
 core/agents/local_agent_test.go               |  96 ++++
 core/external/extdata_helper_test.go          |  13 +
 core/external/provider.go                     | 186 ++++++-
 core/external/provider_similarsongs_test.go   | 468 +++++++++++++++++-
 persistence/playlist_track_repository.go      |   1 +
 persistence/playlist_track_repository_test.go |  14 +
 persistence/sql_base_repository.go            |   4 +-
 server/jellyfin/api.go                        |   1 +
 server/jellyfin/similar.go                    |  21 +-
 server/jellyfin/similar_test.go               |  67 +++
 tests/mock_playlist_repo.go                   |  24 +-
 13 files changed, 891 insertions(+), 61 deletions(-)
 create mode 100644 core/agents/local_agent_test.go

diff --git a/core/agents/agents_test.go b/core/agents/agents_test.go
index e3087f995..e79b2b3c8 100644
--- a/core/agents/agents_test.go
+++ b/core/agents/agents_test.go
@@ -34,10 +34,10 @@ var _ = Describe("Agents", func() {
 		})
 
 		It("calls the placeholder GetArtistImages", func() {
-			mfRepo.SetData(model.MediaFiles{{ID: "1", Title: "One", MbzReleaseTrackID: "111"}, {ID: "2", Title: "Two", MbzReleaseTrackID: "222"}})
+			mfRepo.SetData(model.MediaFiles{{ID: "1", Title: "One"}, {ID: "2", Title: "Two"}})
 			songs, err := ag.GetArtistTopSongs(ctx, "123", "John Doe", "mb123", 2)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(songs).To(ConsistOf([]Song{{Name: "One", MBID: "111"}, {Name: "Two", MBID: "222"}}))
+			Expect(songs).To(ConsistOf([]Song{{ID: "1", Name: "One"}, {ID: "2", Name: "Two"}}))
 		})
 	})
 
diff --git a/core/agents/local_agent.go b/core/agents/local_agent.go
index ce8f9f07c..1cb9060a1 100644
--- a/core/agents/local_agent.go
+++ b/core/agents/local_agent.go
@@ -5,6 +5,8 @@ import (
 
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 const LocalAgentName = "local"
@@ -37,14 +39,51 @@ func (p *localAgent) GetArtistTopSongs(ctx context.Context, id, artistName, mbid
 	if err != nil {
 		return nil, err
 	}
-	var result []Song
-	for _, s := range top {
-		result = append(result, Song{
-			Name: s.Title,
-			MBID: s.MbzReleaseTrackID,
-		})
+	return songsFrom(top), nil
+}
+
+func (p *localAgent) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
+	seed, err := p.ds.MediaFile(ctx).Get(id)
+	if err != nil {
+		return nil, err
 	}
-	return result, nil
+	// Tag ids derive from (name, value), so the seed's genre ids need no extra query.
+	genreIDs := slice.Map(seed.Tags.Flatten(model.TagGenre), func(t model.Tag) string { return t.ID })
+	if len(genreIDs) == 0 {
+		return nil, nil
+	}
+	// Ask for extra so we can drop the seed itself and still fill the count.
+	candidates, err := p.ds.MediaFile(ctx).GetRandom(model.QueryOptions{
+		Filters: squirrel.And{
+			persistence.SongGenres.ByID(genreIDs),
+			squirrel.Eq{"missing": false},
+		},
+		Max: count + 1,
+	})
+	if err != nil {
+		return nil, err
+	}
+	filtered := make(model.MediaFiles, 0, len(candidates))
+	for _, s := range candidates {
+		if s.ID == id {
+			continue
+		}
+		filtered = append(filtered, s)
+		if len(filtered) >= count {
+			break
+		}
+	}
+	return songsFrom(filtered), nil
+}
+
+func songsFrom(mfs model.MediaFiles) []Song {
+	if len(mfs) == 0 {
+		return nil
+	}
+
+	return slice.Map(mfs, func(mf model.MediaFile) Song {
+		return Song{ID: mf.ID, Name: mf.Title}
+	})
 }
 
 func init() {
diff --git a/core/agents/local_agent_test.go b/core/agents/local_agent_test.go
new file mode 100644
index 000000000..50a0ce297
--- /dev/null
+++ b/core/agents/local_agent_test.go
@@ -0,0 +1,96 @@
+package agents
+
+import (
+	"context"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/slice"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("localAgent GetSimilarSongsByTrack", func() {
+	var ds *tests.MockDataStore
+	var mfRepo *tests.MockMediaFileRepo
+	var agent *localAgent
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		mfRepo = &tests.MockMediaFileRepo{}
+		ds = &tests.MockDataStore{MockedMediaFile: mfRepo}
+		agent = &localAgent{ds: ds}
+	})
+
+	It("excludes the seed track from its own similars", func() {
+		seed := model.MediaFile{ID: "seed-1", Title: "Seed", Tags: model.Tags{model.TagGenre: []string{"Rock"}}}
+		related := model.MediaFile{ID: "rel-1", Title: "Related", Tags: model.Tags{model.TagGenre: []string{"Rock"}}}
+		// SetData keys by ID; a duplicate "seed-1" entry would clobber the real seed.
+		mfRepo.SetData(model.MediaFiles{seed, related})
+
+		songs, err := agent.GetSimilarSongsByTrack(ctx, "seed-1", "Seed", "", "", 10)
+
+		Expect(err).ToNot(HaveOccurred())
+		names := slice.Map(songs, func(s Song) string { return s.Name })
+		Expect(names).ToNot(ContainElement("Seed"))
+	})
+
+	// The mock ignores QueryOptions.Filters, so assert the predicate itself: otherwise this spec
+	// would pass just as well with no genre filter at all.
+	It("queries the indexed genre join for the seed's own genres, skipping missing files", func() {
+		rock := model.NewTag(model.TagGenre, "Rock")
+		seed := model.MediaFile{ID: "seed-4", Title: "Seed", Tags: model.Tags{model.TagGenre: []string{"Rock"}}}
+		mfRepo.SetData(model.MediaFiles{seed})
+
+		_, err := agent.GetSimilarSongsByTrack(ctx, "seed-4", "Seed", "", "", 10)
+		Expect(err).ToNot(HaveOccurred())
+
+		sql, args, sqlErr := mfRepo.Options.Filters.ToSql()
+		Expect(sqlErr).ToNot(HaveOccurred())
+		Expect(sql).To(ContainSubstring("media_file_tags"), "must use the indexed join, not a json_tree scan")
+		Expect(sql).To(ContainSubstring("missing"))
+		Expect(args).To(ContainElement(false), "must exclude missing files, not select them")
+		Expect(args).To(ContainElement(rock.ID), "must filter on the seed's own genre tag id")
+		Expect(args).ToNot(ContainElement(model.NewTag(model.TagGenre, "Jazz").ID))
+	})
+
+	It("returns the library id so the matcher can resolve the song", func() {
+		seed := model.MediaFile{ID: "seed-3", Title: "Seed", Tags: model.Tags{model.TagGenre: []string{"Rock"}}}
+		// Without the id the matcher falls through to its MBID/title phases and resolves nothing,
+		// so the local fallback silently returns an empty mix.
+		related := model.MediaFile{ID: "rel-3", Title: "Related", Tags: model.Tags{model.TagGenre: []string{"Rock"}}}
+		mfRepo.SetData(model.MediaFiles{seed, related})
+
+		songs, err := agent.GetSimilarSongsByTrack(ctx, "seed-3", "Seed", "", "", 10)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(ContainElement(Song{ID: "rel-3", Name: "Related"}))
+	})
+
+	It("asks for one extra candidate so dropping the seed still fills the count", func() {
+		// The mock returns rows sorted by id, so the seed comes first and would consume the only
+		// slot if the query did not over-fetch.
+		seed := model.MediaFile{ID: "a-seed", Title: "Seed", Tags: model.Tags{model.TagGenre: []string{"Rock"}}}
+		related := model.MediaFile{ID: "b-rel", Title: "Related", Tags: model.Tags{model.TagGenre: []string{"Rock"}}}
+		mfRepo.SetData(model.MediaFiles{seed, related})
+
+		songs, err := agent.GetSimilarSongsByTrack(ctx, "a-seed", "Seed", "", "", 1)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(HaveLen(1))
+		Expect(songs[0].Name).To(Equal("Related"))
+	})
+
+	It("returns nil when the seed track has no genres", func() {
+		seed := model.MediaFile{ID: "seed-2", Title: "NoGenre"}
+		mfRepo.SetData(model.MediaFiles{seed})
+
+		songs, err := agent.GetSimilarSongsByTrack(ctx, "seed-2", "NoGenre", "", "", 10)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(songs).To(BeEmpty())
+		// Without the early return an empty tag filter would scan the whole library.
+		Expect(mfRepo.Options).To(Equal(model.QueryOptions{}), "must not query at all")
+	})
+})
diff --git a/core/external/extdata_helper_test.go b/core/external/extdata_helper_test.go
index 8fabf4490..d68147168 100644
--- a/core/external/extdata_helper_test.go
+++ b/core/external/extdata_helper_test.go
@@ -110,6 +110,19 @@ func (m *mockMediaFileRepo) GetAll(options ...model.QueryOptions) (model.MediaFi
 	return args.Get(0).(model.MediaFiles), args.Error(1)
 }
 
+// GetRandom implements model.MediaFileRepository.
+func (m *mockMediaFileRepo) GetRandom(options ...model.QueryOptions) (model.MediaFiles, error) {
+	argsSlice := make([]any, len(options))
+	for i, v := range options {
+		argsSlice[i] = v
+	}
+	args := m.Called(argsSlice...)
+	if args.Get(0) == nil {
+		return nil, args.Error(1)
+	}
+	return args.Get(0).(model.MediaFiles), args.Error(1)
+}
+
 // SetError is a helper to set up a generic error for GetAll.
 func (m *mockMediaFileRepo) SetError(hasError bool) {
 	if hasError {
diff --git a/core/external/provider.go b/core/external/provider.go
index efd061c0c..383e7d4c9 100644
--- a/core/external/provider.go
+++ b/core/external/provider.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"math/rand/v2"
 	"sort"
 	"strings"
 	"time"
@@ -14,6 +15,7 @@ import (
 	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
 	"github.com/navidrome/navidrome/utils"
 	. "github.com/navidrome/navidrome/utils/gg"
 	"github.com/navidrome/navidrome/utils/random"
@@ -23,7 +25,11 @@ import (
 )
 
 const (
-	maxSimilarArtists  = 100
+	maxSimilarArtists = 100
+	maxSeeds          = 5
+	// Subsonic passes the client's count through unbounded, and it ends up as a SQL limit. 500 is
+	// what the widest caller (similarAlbums, limit*5) legitimately asks for.
+	maxSimilarSongs    = 500
 	refreshDelay       = 5 * time.Second
 	refreshTimeout     = 15 * time.Second
 	refreshQueueLength = 2000
@@ -278,32 +284,188 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 }
 
 func (e *provider) SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error) {
+	// Subsonic passes the client's count straight through: a non-positive one has no valid
+	// interpretation, and an enormous one overflows the +1 in the local agent's query limit.
+	if count <= 0 {
+		return nil, nil
+	}
+	count = min(count, maxSimilarSongs)
 	entity, err := model.GetEntityByID(ctx, e.ds, id)
 	if err != nil {
-		return nil, err
+		// Genre ids don't resolve via GetEntityByID; look them up before giving up.
+		if !errors.Is(err, model.ErrNotFound) {
+			return nil, err
+		}
+		genre, err := e.ds.Genre(ctx).Get(id)
+		if err != nil {
+			return nil, err
+		}
+		return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
+			return e.sampleGenreTracks(ctx, genre, maxSeeds)
+		})
 	}
 
-	var songs []agents.Song
-
-	// Try entity-specific similarity first
+	// Try entity-specific similarity first, then fall back to seed-track sampling.
 	switch v := entity.(type) {
 	case *model.MediaFile:
-		songs, err = e.ag.GetSimilarSongsByTrack(ctx, v.ID, v.Title, v.Artist, v.MbzRecordingID, count)
+		return e.mixFromAgent(ctx, count,
+			func() ([]agents.Song, error) {
+				return e.ag.GetSimilarSongsByTrack(ctx, v.ID, v.Title, v.Artist, v.MbzRecordingID, count)
+			},
+			func() (model.MediaFiles, error) {
+				return e.similarSongsFallback(ctx, id, count)
+			})
 	case *model.Album:
-		songs, err = e.ag.GetSimilarSongsByAlbum(ctx, v.ID, v.Name, v.AlbumArtist, v.MbzAlbumID, count)
+		return e.mixFromAgent(ctx, count,
+			func() ([]agents.Song, error) {
+				return e.ag.GetSimilarSongsByAlbum(ctx, v.ID, v.Name, v.AlbumArtist, v.MbzAlbumID, count)
+			},
+			func() (model.MediaFiles, error) {
+				return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
+					return e.sampleAlbumTracks(ctx, v.ID, maxSeeds)
+				})
+			})
 	case *model.Artist:
-		songs, err = e.ag.GetSimilarSongsByArtist(ctx, v.ID, v.Name, v.MbzArtistID, count)
+		return e.mixFromAgent(ctx, count,
+			func() ([]agents.Song, error) {
+				return e.ag.GetSimilarSongsByArtist(ctx, v.ID, v.Name, v.MbzArtistID, count)
+			},
+			func() (model.MediaFiles, error) {
+				if res, ferr := e.similarSongsFallback(ctx, id, count); ferr == nil && len(res) > 0 {
+					return res, nil
+				}
+				return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
+					return e.sampleArtistTracks(ctx, v.ID, maxSeeds)
+				})
+			})
+	case *model.Playlist:
+		return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
+			return e.samplePlaylistTracks(ctx, v.ID, maxSeeds)
+		})
 	default:
 		log.Warn(ctx, "Unknown entity type", "id", id, "type", fmt.Sprintf("%T", entity))
 		return nil, model.ErrNotFound
 	}
+}
 
-	if err == nil && len(songs) > 0 {
-		return e.matcher.MatchSongs(ctx, songs, count)
+// mixFromAgent returns the agent's recommendations matched to library tracks, or the fallback
+// when the agent errors or none of its picks are in the library.
+func (e *provider) mixFromAgent(ctx context.Context, count int, fetch func() ([]agents.Song, error), fallback func() (model.MediaFiles, error)) (model.MediaFiles, error) {
+	songs, err := fetch()
+	if err == nil {
+		matched, merr := e.matcher.MatchSongs(ctx, songs, count)
+		if merr != nil {
+			return nil, merr
+		}
+		if len(matched) > 0 {
+			return matched, nil
+		}
 	}
+	return fallback()
+}
 
-	// Fallback to existing similar artists + top songs algorithm
-	return e.similarSongsFallback(ctx, id, count)
+// seedMix samples seed tracks, runs each through the agent chain's per-track similarity and merges
+// the results, falling back to the seeds themselves so the result is never empty.
+func (e *provider) seedMix(ctx context.Context, count int, sample func() (model.MediaFiles, error)) (model.MediaFiles, error) {
+	seeds, err := sample()
+	if err != nil {
+		return nil, err
+	}
+	if len(seeds) == 0 {
+		return nil, nil
+	}
+	seeds = seeds[:min(len(seeds), maxSeeds)]
+
+	// The per-seed similarity calls are independent and hit the (possibly remote) agent chain, so
+	// run them concurrently. Best-effort: a seed that errors just contributes nothing.
+	perSeed := make([][]agents.Song, len(seeds))
+	var g errgroup.Group
+	for i, seed := range seeds {
+		g.Go(func() error {
+			if s, err := e.ag.GetSimilarSongsByTrack(ctx, seed.ID, seed.Title, seed.Artist, seed.MbzRecordingID, count); err == nil {
+				perSeed[i] = s
+			}
+			return nil
+		})
+	}
+	_ = g.Wait()
+
+	var songs []agents.Song
+	for _, s := range perSeed {
+		songs = append(songs, s...)
+	}
+	// Match the whole merged set, not just count of it: the matcher re-emits a track when two
+	// seeds recommend it identically, so the duplicates have to be dropped before trimming. Every
+	// seed reaches the shuffle, so no seed can crowd out the others.
+	matched, err := e.matcher.MatchSongs(ctx, songs, len(songs))
+	if err != nil {
+		return nil, err
+	}
+	matched = dedupByID(matched)
+	if len(matched) == 0 {
+		matched = seeds
+	}
+	rand.Shuffle(len(matched), func(i, j int) { matched[i], matched[j] = matched[j], matched[i] })
+	if len(matched) > count {
+		matched = matched[:count]
+	}
+	return matched, nil
+}
+
+func (e *provider) samplePlaylistTracks(ctx context.Context, playlistID string, n int) (model.MediaFiles, error) {
+	// Refresh: a smart playlist materializes no tracks until it is evaluated, so skipping it would
+	// mix an empty seed set. It is a no-op for regular playlists and inside the refresh delay.
+	repo := e.ds.Playlist(ctx).Tracks(playlistID, true)
+	if repo == nil {
+		return nil, model.ErrNotFound
+	}
+	// A playlist can hold the same file at several positions, so over-fetch and dedup: a repeated
+	// seed wastes an agent call and can reach the mix twice through the seed fallback.
+	tracks, err := repo.GetAll(model.QueryOptions{
+		Sort:    "random",
+		Max:     n * 4,
+		Filters: squirrel.Eq{"missing": false},
+	})
+	if err != nil {
+		return nil, err
+	}
+	mfs := dedupByID(tracks.MediaFiles())
+	return mfs[:min(len(mfs), n)], nil
+}
+
+func dedupByID(mfs model.MediaFiles) model.MediaFiles {
+	seen := make(map[string]struct{}, len(mfs))
+	return slice.Filter(mfs, func(mf model.MediaFile) bool {
+		if _, dup := seen[mf.ID]; dup {
+			return false
+		}
+		seen[mf.ID] = struct{}{}
+		return true
+	})
+}
+
+func (e *provider) sampleAlbumTracks(ctx context.Context, albumID string, n int) (model.MediaFiles, error) {
+	return e.sampleTracks(ctx, squirrel.Eq{"album_id": albumID}, n)
+}
+
+func (e *provider) sampleArtistTracks(ctx context.Context, artistID string, n int) (model.MediaFiles, error) {
+	// media_file.artist_id is the deprecated primary artist, so it misses an artist credited only
+	// on the album, as on compilations. Same filter the artist listings use.
+	filter := persistence.ParticipantIDFilter("media_file", artistID, model.RoleArtist, model.RoleAlbumArtist)
+	return e.sampleTracks(ctx, filter, n)
+}
+
+func (e *provider) sampleGenreTracks(ctx context.Context, genre *model.Genre, n int) (model.MediaFiles, error) {
+	return e.sampleTracks(ctx, persistence.SongGenres.ByID(genre.ID), n)
+}
+
+// sampleTracks returns up to n random present tracks. Seeds can end up in the mix verbatim, so
+// missing files would surface as unplayable entries.
+func (e *provider) sampleTracks(ctx context.Context, filter squirrel.Sqlizer, n int) (model.MediaFiles, error) {
+	return e.ds.MediaFile(ctx).GetRandom(model.QueryOptions{
+		Filters: squirrel.And{filter, squirrel.Eq{"missing": false}},
+		Max:     n,
+	})
 }
 
 // similarSongsFallback uses the original similar artists + top songs algorithm. The idea is to
diff --git a/core/external/provider_similarsongs_test.go b/core/external/provider_similarsongs_test.go
index 563003f83..5617269b3 100644
--- a/core/external/provider_similarsongs_test.go
+++ b/core/external/provider_similarsongs_test.go
@@ -3,6 +3,8 @@ package external_test
 import (
 	"context"
 	"errors"
+	"math"
+	"slices"
 	"strings"
 
 	"github.com/Masterminds/squirrel"
@@ -11,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/stretchr/testify/mock"
@@ -26,6 +29,9 @@ var _ = Describe("Provider - SimilarSongs", func() {
 	var artistRepo *mockArtistRepo
 	var mediaFileRepo *mockMediaFileRepo
 	var albumRepo *mockAlbumRepo
+	var playlistRepo *tests.MockPlaylistRepo
+	var playlistTrackRepo *tests.MockPlaylistTrackRepo
+	var genreRepo *tests.MockedGenreRepo
 	var ctx context.Context
 
 	BeforeEach(func() {
@@ -34,11 +40,17 @@ var _ = Describe("Provider - SimilarSongs", func() {
 		artistRepo = newMockArtistRepo()
 		mediaFileRepo = newMockMediaFileRepo()
 		albumRepo = newMockAlbumRepo()
+		playlistTrackRepo = &tests.MockPlaylistTrackRepo{}
+		playlistRepo = tests.CreateMockPlaylistRepo()
+		playlistRepo.TracksRepo = playlistTrackRepo
+		genreRepo = &tests.MockedGenreRepo{}
 
 		ds = &tests.MockDataStore{
 			MockedArtist:    artistRepo,
 			MockedMediaFile: mediaFileRepo,
 			MockedAlbum:     albumRepo,
+			MockedPlaylist:  playlistRepo,
+			MockedGenre:     genreRepo,
 		}
 
 		mockAgent = &mockSimilarArtistAgent{}
@@ -203,46 +215,68 @@ var _ = Describe("Provider - SimilarSongs", func() {
 				Expect(songs[0].ID).To(Equal("matched-1"))
 			})
 
-			It("falls back when GetSimilarSongsByAlbum returns ErrNotFound", func() {
+			It("falls back to sampled album tracks when GetSimilarSongsByAlbum returns ErrNotFound", func() {
 				album := model.Album{ID: "album-1", Name: "Album", AlbumArtist: "Artist", AlbumArtistID: "artist-1"}
-				artist := model.Artist{ID: "artist-1", Name: "Artist"}
-				song := model.MediaFile{ID: "song-1", Title: "Song One", ArtistID: "artist-1", MbzRecordingID: "mbid-1"}
+				seed := model.MediaFile{ID: "seed-1", Title: "Seed", Artist: "Artist"}
 
-				// GetEntityByID for the initial call tries Artist, Album, Playlist, then MediaFile
 				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
 				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
 
 				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "album-1", "Album", "Artist", "", mock.Anything).
 					Return(nil, agents.ErrNotFound).Once()
 
-				// Fallback calls getArtist(id) which calls GetEntityByID again - this time it finds the album
-				// and recursively calls getArtist(v.AlbumArtistID)
-				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
-				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
+				mediaFileRepo.On("GetRandom", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					sql, args, err := opt.Filters.ToSql()
+					return err == nil && strings.Contains(sql, "album_id") &&
+						strings.Contains(sql, "missing") && slices.Contains(args, any(false)) && slices.Contains(args, any("album-1"))
+				})).Return(model.MediaFiles{seed}, nil).Once()
 
-				// Then it recurses with the artist-1 ID
-				artistRepo.On("Get", "artist-1").Return(&artist, nil).Maybe()
-				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-					return opt.Max == 1 && opt.Filters != nil
-				})).Return(model.Artists{artist}, nil).Maybe()
-
-				mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist", "", 15).
-					Return([]agents.Artist{}, nil).Once()
-
-				artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
-					return opt.Max == 0 && opt.Filters != nil
-				})).Return(model.Artists{}, nil).Once()
-
-				mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist", "", mock.Anything).
-					Return([]agents.Song{{Name: "Song One", MBID: "mbid-1"}}, nil).Once()
-
-				mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song}, nil).Once()
+				// seedMix falls back to the seed itself when the agent finds nothing.
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "seed-1", "Seed", "Artist", "", mock.Anything).
+					Return([]agents.Song{}, nil).Once()
 
 				songs, err := provider.SimilarSongs(ctx, "album-1", 5)
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(songs).To(HaveLen(1))
-				Expect(songs[0].ID).To(Equal("song-1"))
+				Expect(songs[0].ID).To(Equal("seed-1"))
+			})
+		})
+
+		Context("when ID is an Album and the album agent returns nothing (AudioMuse-only)", func() {
+			It("samples the album's tracks and returns their track-similars", func() {
+				album := model.Album{ID: "al-1", Name: "The Album", AlbumArtist: "A"}
+				artistRepo.On("Get", "al-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "al-1").Return(&album, nil).Once()
+
+				// AudioMuse doesn't implement album similarity -> empty.
+				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "al-1", "The Album", "A", "", 5).
+					Return([]agents.Song{}, nil).Once()
+
+				// sampleAlbumTracks -> GetRandom(album_id) -> one seed track
+				mediaFileRepo.On("GetRandom", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					sql, args, err := opt.Filters.ToSql()
+					return err == nil && strings.Contains(sql, "album_id") &&
+						strings.Contains(sql, "missing") && slices.Contains(args, any(false)) && slices.Contains(args, any("al-1"))
+				})).Return(model.MediaFiles{{ID: "s1", Title: "Seed", Artist: "A"}}, nil).Once()
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed", "A", "", 5).
+					Return([]agents.Song{{Name: "AudioMuseResult", Artists: []agents.Artist{{Name: "A"}}}}, nil).Once()
+
+				// Matcher resolves "AudioMuseResult" -> a real MediaFile credited to artist "A".
+				aArtist := model.Artist{ID: "a1", Name: "A", OrderArtistName: "a"}
+				matchedTrack := model.MediaFile{
+					ID: "m1", Title: "AudioMuseResult", Artist: "A",
+					Participants: model.Participants{model.RoleArtist: model.ParticipantList{{Artist: aArtist}}},
+				}
+				artistRepo.On("GetAll", mock.Anything).Return(model.Artists{aArtist}, nil).Maybe()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{matchedTrack}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "al-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).ToNot(BeEmpty())
+				Expect(songs[0].ID).To(Equal("m1"))
 			})
 		})
 
@@ -280,6 +314,381 @@ var _ = Describe("Provider - SimilarSongs", func() {
 				Expect(songs[0].ID).To(Equal("matched-1"))
 			})
 		})
+
+		Context("when ID is an Artist and both the artist agent and the similar-artists fallback are empty", func() {
+			It("samples the artist's tracks and returns their track-similars", func() {
+				artist := model.Artist{ID: "ar-1", Name: "The Artist"}
+				// Get is called twice: once to resolve the entity, once inside similarSongsFallback.
+				artistRepo.On("Get", "ar-1").Return(&artist, nil).Maybe()
+
+				agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "ar-1", "The Artist", "", 5).
+					Return([]agents.Song{}, nil).Once()
+				// similarSongsFallback: no similar artists, no top songs -> empty (allow its lookups).
+				mockAgent.On("GetSimilarArtists", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Artist{}, nil).Maybe()
+				mockAgent.On("GetArtistTopSongs", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{}, nil).Maybe()
+
+				// Seeds come from the participant join covering both roles, so an artist credited
+				// only on the album (compilations, classical) still yields seeds.
+				mediaFileRepo.On("GetRandom", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					sql, args, err := opt.Filters.ToSql()
+					return err == nil && strings.Contains(sql, "media_file_artists") &&
+						strings.Contains(sql, "missing") && slices.Contains(args, any(false)) && slices.Contains(args, any("ar-1")) &&
+						slices.Contains(args, any(model.RoleAlbumArtist.String())) && slices.Contains(args, any(model.RoleArtist.String()))
+				})).Return(model.MediaFiles{{ID: "s1", Title: "Seed"}}, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed", "", "", 5).
+					Return([]agents.Song{{Name: "Result"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{{ID: "m1", Title: "Result"}}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "ar-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).ToNot(BeEmpty())
+			})
+		})
+
+		Context("when ID is a Playlist", func() {
+			It("samples playlist tracks and returns their track-similars", func() {
+				pls := model.Playlist{ID: "pl-1", Name: "My List"}
+				seedTrack := model.MediaFile{ID: "s1", Title: "Seed One", Artist: "A"}
+
+				// GetEntityByID order: Artist, Album, Playlist(hit)
+				artistRepo.On("Get", "pl-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-1").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+
+				// samplePlaylistTracks -> Tracks(...).GetAll -> one seed track, bounded+randomized in SQL
+				playlistTrackRepo.SetData(model.PlaylistTracks{
+					{MediaFile: seedTrack},
+				})
+
+				// seedMix -> GetSimilarSongsByTrack for the seed
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed One", "A", "", 5).
+					Return([]agents.Song{{Name: "Similar", Artists: []agents.Artist{{Name: "A"}}}}, nil).Once()
+
+				// Matcher resolves "Similar" -> a real MediaFile (allow the matcher's lookups).
+				artistRepo.On("GetAll", mock.Anything).Return(model.Artists{{ID: "a1", Name: "A"}}, nil).Maybe()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{{ID: "m1", Title: "Similar"}}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "pl-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).ToNot(BeEmpty())
+			})
+
+			It("asks for a smart-playlist refresh so an unevaluated one still yields seeds", func() {
+				// A smart playlist materializes no playlist_tracks until it is evaluated, so sampling
+				// without the refresh would mix an empty seed set.
+				pls := model.Playlist{ID: "pl-smart", Name: "Smart"}
+				artistRepo.On("Get", "pl-smart").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-smart").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				playlistTrackRepo.SetData(model.PlaylistTracks{
+					{MediaFile: model.MediaFile{ID: "s1", Title: "Seed One"}},
+				})
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "pl-smart", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).ToNot(BeEmpty())
+				Expect(playlistRepo.TracksRefreshed).To(BeTrue())
+			})
+
+			It("returns an error instead of panicking when the track repository is unavailable", func() {
+				// Tracks() logs and returns a nil repository when its own lookup fails.
+				pls := model.Playlist{ID: "pl-nil", Name: "Gone"}
+				artistRepo.On("Get", "pl-nil").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-nil").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				playlistRepo.TracksRepo = nil
+
+				_, err := provider.SimilarSongs(ctx, "pl-nil", 5)
+
+				Expect(err).To(MatchError(model.ErrNotFound))
+			})
+
+			It("does not seed a mix with missing tracks", func() {
+				pls := model.Playlist{ID: "pl-missing", Name: "Missing"}
+				artistRepo.On("Get", "pl-missing").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-missing").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				playlistTrackRepo.SetData(model.PlaylistTracks{
+					{MediaFile: model.MediaFile{ID: "s1", Title: "Seed One"}},
+				})
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{}, nil).Maybe()
+
+				_, err := provider.SimilarSongs(ctx, "pl-missing", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				sql, args, sqlErr := playlistTrackRepo.Options.Filters.ToSql()
+				Expect(sqlErr).ToNot(HaveOccurred())
+				Expect(sql).To(ContainSubstring("missing"))
+				Expect(args).To(ContainElement(false), "must exclude missing files, not select them")
+			})
+
+			It("keeps a later seed's picks when an earlier seed overlaps it", func() {
+				// The matcher stops once it has count matches, and it re-emits the shared track, so
+				// matching only count of the merged set would spend slots on the duplicate.
+				pls := model.Playlist{ID: "pl-overlap2", Name: "Overlap2"}
+				artistRepo.On("Get", "pl-overlap2").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-overlap2").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				playlistTrackRepo.SetData(model.PlaylistTracks{
+					{MediaFile: model.MediaFile{ID: "s1", Title: "Seed One"}},
+					{MediaFile: model.MediaFile{ID: "s2", Title: "Seed Two"}},
+				})
+				shared := agents.Song{ID: "x", Name: "X"}
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed One", "", "", 3).
+					Return([]agents.Song{shared}, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s2", "Seed Two", "", "", 3).
+					Return([]agents.Song{shared, {ID: "y", Name: "Y"}, {ID: "z", Name: "Z"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{
+					{ID: "x", Title: "X"}, {ID: "y", Title: "Y"}, {ID: "z", Title: "Z"},
+				}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "pl-overlap2", 3)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(3), "the duplicate must not cost a slot")
+			})
+
+			It("returns a track once when two seeds recommend it", func() {
+				// The matcher re-emits a track when two inputs are identical, so overlapping
+				// recommendations would otherwise take two slots in the mix.
+				pls := model.Playlist{ID: "pl-overlap", Name: "Overlap"}
+				artistRepo.On("Get", "pl-overlap").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-overlap").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				playlistTrackRepo.SetData(model.PlaylistTracks{
+					{MediaFile: model.MediaFile{ID: "s1", Title: "Seed One"}},
+					{MediaFile: model.MediaFile{ID: "s2", Title: "Seed Two"}},
+				})
+				shared := agents.Song{ID: "m1", Name: "Shared"}
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed One", "", "", 5).
+					Return([]agents.Song{shared}, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s2", "Seed Two", "", "", 5).
+					Return([]agents.Song{shared}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{{ID: "m1", Title: "Shared"}}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "pl-overlap", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1), "the shared recommendation must appear once")
+			})
+
+			It("does not seed a mix twice with a track the playlist repeats", func() {
+				pls := model.Playlist{ID: "pl-dup", Name: "Dupes"}
+				artistRepo.On("Get", "pl-dup").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-dup").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				// The same file at two positions, which playlists allow.
+				dup := model.MediaFile{ID: "s1", Title: "Seed One"}
+				playlistTrackRepo.SetData(model.PlaylistTracks{{MediaFile: dup}, {MediaFile: dup}})
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed One", "", "", 5).
+					Return([]agents.Song{}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "pl-dup", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1), "the repeated track must appear once")
+				agentsCombined.AssertNumberOfCalls(GinkgoT(), "GetSimilarSongsByTrack", 1)
+			})
+
+			It("clamps an enormous count before it reaches the queries", func() {
+				// count+1 in the local agent overflows on MaxInt64, and GetRandom omits the SQL
+				// limit unless Max is positive, so the query would hydrate the whole library.
+				pls := model.Playlist{ID: "pl-huge", Name: "Huge"}
+				artistRepo.On("Get", "pl-huge").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-huge").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				playlistTrackRepo.SetData(model.PlaylistTracks{
+					{MediaFile: model.MediaFile{ID: "s1", Title: "Seed One"}},
+				})
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed One", "", "", 500).
+					Return([]agents.Song{}, nil).Once()
+
+				_, err := provider.SimilarSongs(ctx, "pl-huge", math.MaxInt64)
+
+				Expect(err).ToNot(HaveOccurred())
+				agentsCombined.AssertExpectations(GinkgoT())
+			})
+
+			It("does not panic when the caller asks for a non-positive count", func() {
+				// Subsonic passes count straight through, so a negative one reaches the provider.
+				// The guard returns before any lookup, so no repository setup is needed.
+				songs, err := provider.SimilarSongs(ctx, "pl-neg", -1)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(BeEmpty())
+			})
+
+			It("blends results from every seed, not just the first", func() {
+				pls := model.Playlist{ID: "pl-blend", Name: "Blend"}
+				artistRepo.On("Get", "pl-blend").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-blend").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				playlistTrackRepo.SetData(model.PlaylistTracks{
+					{MediaFile: model.MediaFile{ID: "s1", Title: "Seed One"}},
+					{MediaFile: model.MediaFile{ID: "s2", Title: "Seed Two"}},
+				})
+
+				// Each seed returns a full count's worth, as a real similarity agent does. Asking for
+				// one more than seed one can supply makes this independent of the final shuffle:
+				// three of the four matches always include a seed-two track.
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed One", "", "", 3).
+					Return([]agents.Song{{ID: "a1", Name: "A1"}, {ID: "a2", Name: "A2"}}, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s2", "Seed Two", "", "", 3).
+					Return([]agents.Song{{ID: "b1", Name: "B1"}, {ID: "b2", Name: "B2"}}, nil).Once()
+
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{
+					{ID: "a1", Title: "A1"}, {ID: "a2", Title: "A2"},
+					{ID: "b1", Title: "B1"}, {ID: "b2", Title: "B2"},
+				}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "pl-blend", 3)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(3))
+				ids := slice.Map(songs, func(mf model.MediaFile) string { return mf.ID })
+				Expect(ids).To(ContainElement(BeElementOf("b1", "b2")), "seed two must be represented in the mix")
+			})
+
+			It("falls back to the seed tracks themselves when no similar songs are found", func() {
+				pls := model.Playlist{ID: "pl-2", Name: "Fallback List"}
+				seed1 := model.MediaFile{ID: "s1", Title: "Seed One", Artist: "A"}
+				seed2 := model.MediaFile{ID: "s2", Title: "Seed Two", Artist: "B"}
+
+				artistRepo.On("Get", "pl-2").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-2").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+
+				playlistTrackRepo.SetData(model.PlaylistTracks{
+					{MediaFile: seed1},
+					{MediaFile: seed2},
+				})
+
+				// Both seeds come back empty, so the mix must fall back to the seeds themselves.
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed One", "A", "", 5).
+					Return([]agents.Song{}, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s2", "Seed Two", "B", "", 5).
+					Return([]agents.Song{}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "pl-2", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(2))
+				Expect([]string{songs[0].ID, songs[1].ID}).To(ConsistOf("s1", "s2"))
+			})
+
+			It("samples the album when the agent's picks are not in this library", func() {
+				// Last.fm answers from its own catalogue, so a small library can match none of it.
+				// An unmatched non-empty answer must not shortcut the sampling fallback.
+				album := model.Album{ID: "al-nm", Name: "NoMatch", AlbumArtist: "A"}
+				artistRepo.On("Get", "al-nm").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "al-nm").Return(&album, nil).Once()
+				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "al-nm", "NoMatch", "A", "", 5).
+					Return([]agents.Song{{Name: "Not In Library"}}, nil).Once()
+				artistRepo.On("GetAll", mock.Anything).Return(model.Artists{}, nil).Maybe()
+
+				// The matcher resolves nothing; the sampled seed is what reaches the mix.
+				mediaFileRepo.On("GetRandom", mock.Anything).
+					Return(model.MediaFiles{{ID: "s1", Title: "Album Track"}}, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Album Track", "", "", 5).
+					Return([]agents.Song{}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "al-nm", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(1))
+				Expect(songs[0].ID).To(Equal("s1"))
+			})
+
+			It("caps agent calls at maxSeeds when the repository ignores the bound", func() {
+				// Isolates seedMix's own cap: the album sampler bounds the query with Max, so this
+				// exercises the guard by having the repo hand back more rows than were asked for.
+				album := model.Album{ID: "al-cap", Name: "Cap", AlbumArtist: "A"}
+				artistRepo.On("Get", "al-cap").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "al-cap").Return(&album, nil).Once()
+				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "al-cap", "Cap", "A", "", 5).
+					Return([]agents.Song{}, nil).Once()
+
+				var overflow model.MediaFiles
+				for _, id := range []string{"t1", "t2", "t3", "t4", "t5", "t6", "t7", "t8"} {
+					overflow = append(overflow, model.MediaFile{ID: id, Title: id})
+				}
+				mediaFileRepo.On("GetRandom", mock.Anything).Return(overflow, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, 5).
+					Return([]agents.Song{}, nil)
+
+				_, err := provider.SimilarSongs(ctx, "al-cap", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				agentsCombined.AssertNumberOfCalls(GinkgoT(), "GetSimilarSongsByTrack", 5)
+			})
+
+			It("still finds maxSeeds distinct seeds when the leading positions repeat", func() {
+				// The sampler over-fetches for exactly this case: a page bounded at maxSeeds could
+				// be entirely one repeated file and collapse to a single seed.
+				pls := model.Playlist{ID: "pl-3", Name: "Big List"}
+				dup := model.MediaFile{ID: "dup", Title: "Dup", Artist: "A"}
+				tracks := model.PlaylistTracks{
+					{MediaFile: dup}, {MediaFile: dup}, {MediaFile: dup}, {MediaFile: dup}, {MediaFile: dup},
+				}
+				for _, id := range []string{"seed-1", "seed-2", "seed-3", "seed-4", "seed-5"} {
+					tracks = append(tracks, model.PlaylistTrack{
+						MediaFile: model.MediaFile{ID: id, Title: id, Artist: "A"},
+					})
+				}
+
+				artistRepo.On("Get", "pl-3").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "pl-3").Return(nil, model.ErrNotFound).Once()
+				playlistRepo.SetData(model.Playlists{pls})
+				playlistTrackRepo.SetData(tracks)
+
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, 5).
+					Return([]agents.Song{}, nil)
+
+				songs, err := provider.SimilarSongs(ctx, "pl-3", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).To(HaveLen(5))
+				Expect(playlistTrackRepo.Options.Sort).To(Equal("random"))
+				agentsCombined.AssertNumberOfCalls(GinkgoT(), "GetSimilarSongsByTrack", 5)
+			})
+		})
+
+		Context("when ID is a Genre (not resolved by GetEntityByID)", func() {
+			It("samples genre songs and returns their track-similars", func() {
+				// GetEntityByID misses everywhere; the empty/auto-created mocks need no setup.
+				artistRepo.On("Get", "g-1").Return(nil, model.ErrNotFound).Once()
+				albumRepo.On("Get", "g-1").Return(nil, model.ErrNotFound).Once()
+				mediaFileRepo.On("Get", "g-1").Return(nil, model.ErrNotFound).Once()
+				genreRepo.Data = map[string]model.Genre{"g-1": {ID: "g-1", Name: "Jazz"}}
+
+				// sampleGenreTracks -> GetRandom with the indexed media_file_tags semi-join (not a json_tree scan)
+				mediaFileRepo.On("GetRandom", mock.MatchedBy(func(opt model.QueryOptions) bool {
+					if opt.Filters == nil {
+						return false
+					}
+					sql, args, err := opt.Filters.ToSql()
+					return err == nil && strings.Contains(sql, "media_file_tags") &&
+						!strings.Contains(sql, "json_tree") && strings.Contains(sql, "missing") && slices.Contains(args, any(false))
+				})).Return(model.MediaFiles{{ID: "s1", Title: "Seed"}}, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed", "", "", 5).
+					Return([]agents.Song{{Name: "Similar"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{{ID: "m1", Title: "Similar"}}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "g-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(songs).ToNot(BeEmpty())
+			})
+		})
 	})
 
 	It("returns similar songs from main artist and similar artists", func() {
@@ -412,6 +821,13 @@ var _ = Describe("Provider - SimilarSongs", func() {
 		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
 			Return(nil, errors.New("error getting top songs")).Once()
 
+		// Fallback yields nothing, so the sampling path is tried and also finds no tracks.
+		mediaFileRepo.On("GetRandom", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			sql, args, err := opt.Filters.ToSql()
+			return err == nil && strings.Contains(sql, "artist_id") &&
+				strings.Contains(sql, "missing") && slices.Contains(args, any(false)) && slices.Contains(args, any("artist-1"))
+		})).Return(model.MediaFiles{}, nil).Once()
+
 		songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
 
 		Expect(err).ToNot(HaveOccurred())
diff --git a/persistence/playlist_track_repository.go b/persistence/playlist_track_repository.go
index 1a64efa20..c1f6fcf69 100644
--- a/persistence/playlist_track_repository.go
+++ b/persistence/playlist_track_repository.go
@@ -57,6 +57,7 @@ func (r *playlistRepository) Tracks(playlistId string, refreshSmartPlaylist bool
 			"album_artist": "order_album_artist_name",
 			"album":        "order_album_name, album_id, disc_number, track_number, order_artist_name, title",
 			"title":        "order_title",
+			"random":       "random()",
 			// To make sure these fields will be whitelisted
 			"duration": "duration",
 			"year":     "year",
diff --git a/persistence/playlist_track_repository_test.go b/persistence/playlist_track_repository_test.go
index 36f9ae4a9..a5c67b92c 100644
--- a/persistence/playlist_track_repository_test.go
+++ b/persistence/playlist_track_repository_test.go
@@ -37,6 +37,20 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		})
 	})
 
+	Describe("GetAll", func() {
+		It("returns every row under a random sort, despite the integer id", func() {
+			// playlist_tracks.id is an INTEGER, so SEEDEDRAND drops every row unless it is cast to
+			// TEXT, and it fails silently: no error, just no rows.
+			all, err := repo.GetAll(model.QueryOptions{Sort: "random"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(all).To(HaveLen(2), "a random sort must not silently drop rows")
+
+			got, err := repo.GetAll(model.QueryOptions{Sort: "random", Max: 1})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got).To(HaveLen(1))
+		})
+	})
+
 	Describe("CountAll", func() {
 		It("returns the number of tracks in the playlist", func() {
 			Expect(repo.CountAll()).To(Equal(int64(2)))
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index 33450fe9f..428ba7a7b 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -284,7 +284,9 @@ func (r sqlRepository) resetSeededRandom(options []model.QueryOptions) {
 	if len(options) == 0 || options[0].Sort != "random" {
 		return
 	}
-	options[0].Sort = fmt.Sprintf("SEEDEDRAND('%s', %s.id)", r.seedKey(), r.tableName)
+	// CAST: playlist_tracks.id is an INTEGER (unlike other tables' TEXT ids); passing it to
+	// SEEDEDRAND's string param uncast silently drops every row (go-sqlite3 binding gotcha).
+	options[0].Sort = fmt.Sprintf("SEEDEDRAND('%s', CAST(%s.id AS TEXT))", r.seedKey(), r.tableName)
 	if options[0].Seed != "" {
 		hasher.SetSeed(r.seedKey(), options[0].Seed)
 		return
diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index 1f46c08b4..8a175df35 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -143,6 +143,7 @@ func (api *Router) routes() http.Handler {
 
 		r.Get("/artists/{itemId}/similar", api.getSimilarArtists)
 		r.Get("/items/{itemId}/similar", api.getSimilarItems)
+		r.Get("/albums/{itemId}/similar", api.getSimilarAlbums)
 		r.Get("/items/{itemId}/instantmix", api.getInstantMix)
 		r.Get("/genres", api.getGenres)
 		r.Get("/musicgenres", api.getGenres)
diff --git a/server/jellyfin/similar.go b/server/jellyfin/similar.go
index 3e0b3b11b..82d12f52b 100644
--- a/server/jellyfin/similar.go
+++ b/server/jellyfin/similar.go
@@ -2,6 +2,7 @@ package jellyfin
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net/http"
 	"time"
@@ -93,6 +94,19 @@ func (api *Router) getSimilarItems(w http.ResponseWriter, r *http.Request) {
 	}))
 }
 
+// getSimilarAlbums answers GET /Albums/{itemId}/Similar, powering Finamp's albumMix radio mode.
+func (api *Router) getSimilarAlbums(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	id, ok := itemIDParam(w, r, "itemId")
+	if !ok {
+		return
+	}
+	limit := clampLimit(req.Params(r).IntOr("limit", 0), defaultSimilarLimit, maxSimilarLimit)
+	api.ok(w, r, api.awaitSimilar(ctx, "albsim|"+id, limit, func(ctx context.Context) dto.QueryResult {
+		return api.similarAlbums(ctx, id, limit)
+	}))
+}
+
 // getInstantMix answers GET /Items/{itemId}/InstantMix. Finamp plays exactly what is returned, so
 // a track seed leads its own mix; provider errors and unknown seeds degrade to seed-only/empty
 // results, never a 404 the client would surface as an error.
@@ -104,8 +118,10 @@ func (api *Router) getInstantMix(w http.ResponseWriter, r *http.Request) {
 	}
 	limit := clampLimit(req.Params(r).IntOr("limit", 0), defaultSimilarLimit, maxInstantMixLimit)
 
+	// Genre ids don't resolve via GetEntityByID, so a not-found entity is fine: it is just "not a
+	// song" and the provider knows what to do with it. A real lookup failure still stops here.
 	entity, err := model.GetEntityByID(ctx, api.ds, id)
-	if err != nil {
+	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		api.ok(w, r, result(nil, 0, 0))
 		return
 	}
@@ -177,7 +193,8 @@ func (api *Router) similarAlbums(ctx context.Context, id string, limit int) dto.
 		return result(nil, 0, 0)
 	}
 	u, _ := request.UserFrom(ctx)
-	seen := make(map[string]bool, limit)
+	// An album is not similar to itself, and the sampled-seed fallback returns its own tracks.
+	seen := map[string]bool{id: true}
 	var items []dto.BaseItemDto
 	for _, s := range songs {
 		if s.AlbumID == "" || seen[s.AlbumID] {
diff --git a/server/jellyfin/similar_test.go b/server/jellyfin/similar_test.go
index dc8c1e605..cffcce0a8 100644
--- a/server/jellyfin/similar_test.go
+++ b/server/jellyfin/similar_test.go
@@ -164,4 +164,71 @@ var _ = Describe("getInstantMix", func() {
 		Expect(res.Items).To(HaveLen(want), "a Radio Mix-sized request must not be truncated to the Similar ceiling")
 		Expect(res.Items[0].Name).To(Equal("Seed Song"), "the seed must still lead the mix")
 	})
+
+	It("returns a mix for a genre id, which GetEntityByID can't resolve", func() {
+		ds := &tests.MockDataStore{}
+		songs := model.MediaFiles{
+			{ID: testID("m1"), Title: "Track 1", LibraryID: 1},
+			{ID: testID("m2"), Title: "Track 2", LibraryID: 1},
+		}
+		api := &Router{ds: ds, provider: &fakeSimilarProvider{songs: songs}}
+
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("g1"))+"/InstantMix", nil).
+			WithContext(request.WithUser(context.Background(), model.User{ID: testID("u1"), Libraries: model.Libraries{{ID: 1}}}))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("g1")))
+		api.getInstantMix(w, r)
+
+		Expect(w.Code).To(Equal(200))
+		var res dto.QueryResult
+		Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+		Expect(res.Items).To(HaveLen(2))
+	})
+})
+
+var _ = Describe("getSimilarAlbums", func() {
+	It("does not return the seed album as its own similar album", func() {
+		// With no external agent the provider falls back to the album's own tracks, which map
+		// straight back to the requested album.
+		ds := &tests.MockDataStore{}
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: testID("al-1"), Name: "Seed Album", LibraryID: 1},
+		})
+		api := &Router{ds: ds, provider: &fakeSimilarProvider{
+			songs: model.MediaFiles{{ID: testID("m1"), AlbumID: testID("al-1"), LibraryID: 1}},
+		}}
+
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest("GET", "/Albums/"+dto.EncodeID(testID("al-1"))+"/Similar?limit=10", nil).
+			WithContext(request.WithUser(context.Background(), model.User{ID: testID("u1"), Libraries: model.Libraries{{ID: 1}}}))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("al-1")))
+		api.getSimilarAlbums(w, r)
+
+		Expect(w.Code).To(Equal(200))
+		var res dto.QueryResult
+		Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+		Expect(res.Items).To(BeEmpty())
+	})
+
+	It("returns albums derived from the provider's similar songs", func() {
+		ds := &tests.MockDataStore{}
+		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: testID("al-2"), Name: "Other", LibraryID: 1},
+		})
+		api := &Router{ds: ds, provider: &fakeSimilarProvider{
+			songs: model.MediaFiles{{ID: testID("m1"), AlbumID: testID("al-2"), LibraryID: 1}},
+		}}
+
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest("GET", "/Albums/"+dto.EncodeID(testID("al-1"))+"/Similar?limit=10", nil).
+			WithContext(request.WithUser(context.Background(), model.User{ID: testID("u1"), Libraries: model.Libraries{{ID: 1}}}))
+		r = withChiURLParam(r, "itemId", dto.EncodeID(testID("al-1")))
+		api.getSimilarAlbums(w, r)
+
+		Expect(w.Code).To(Equal(200))
+		var res dto.QueryResult
+		Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+		Expect(res.Items).To(HaveLen(1))
+		Expect(res.Items[0].Name).To(Equal("Other"))
+	})
 })
diff --git a/tests/mock_playlist_repo.go b/tests/mock_playlist_repo.go
index ee645e984..f04ed98c6 100644
--- a/tests/mock_playlist_repo.go
+++ b/tests/mock_playlist_repo.go
@@ -19,16 +19,17 @@ func CreateMockPlaylistRepo() *MockPlaylistRepo {
 
 type MockPlaylistRepo struct {
 	model.PlaylistRepository
-	Data       map[string]*model.Playlist // keyed by ID
-	PathMap    map[string]*model.Playlist // keyed by path
-	All        model.Playlists
-	Options    model.QueryOptions
-	Last       *model.Playlist
-	Deleted    []string
-	Starred    map[string]bool // itemID -> starred
-	Ratings    map[string]int  // itemID -> rating
-	Err        bool
-	TracksRepo model.PlaylistTrackRepository
+	Data            map[string]*model.Playlist // keyed by ID
+	PathMap         map[string]*model.Playlist // keyed by path
+	All             model.Playlists
+	Options         model.QueryOptions
+	Last            *model.Playlist
+	Deleted         []string
+	Starred         map[string]bool // itemID -> starred
+	Ratings         map[string]int  // itemID -> rating
+	Err             bool
+	TracksRepo      model.PlaylistTrackRepository
+	TracksRefreshed bool
 }
 
 func (m *MockPlaylistRepo) SetError(err bool) {
@@ -163,7 +164,8 @@ func (m *MockPlaylistRepo) ReassignAnnotation(string, string) error {
 	return nil
 }
 
-func (m *MockPlaylistRepo) Tracks(_ string, _ bool) model.PlaylistTrackRepository {
+func (m *MockPlaylistRepo) Tracks(_ string, refreshSmartPlaylist bool) model.PlaylistTrackRepository {
+	m.TracksRefreshed = refreshSmartPlaylist
 	return m.TracksRepo
 }
 

From 757ca783d37ba6df1c2e186b3654bd01273d3b5d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 13 Aug 2026 18:50:34 -0400
Subject: [PATCH 035/200] fix(instant-mix): top short mixes up instead of
 returning what the first source found (#5951)

* fix(instant-mix): top short mixes up instead of returning what the first source found

SimilarSongs returned the first non-empty source's tracks, however few. For a
thinly-represented artist that meant a 3-track mix no matter the requested count:
the artist agent found nothing, the similar-artists fallback matched 3 library
tracks, and `len(res) > 0` kept seed-track sampling from ever running.

Clients treat that as a failed mix and retry with a bigger limit forever. Finamp
cycles limit 34 through 472 and starts over, ~1 request every 2s indefinitely,
each one re-hitting Last.fm, Deezer and AudioMuse.

Sources are now chained rather than raced: each one tops the mix up until it
holds count tracks, so the agent's picks, the similar-artists fallback and
seed-track sampling all contribute instead of the first one winning outright.

* refactor(external): move similar-songs code to its own file

provider.go held two distinct concerns: artist/album external metadata and the
similar-songs mix pipeline. The mix code was already one contiguous block, and
maxSeeds, maxSimilarSongs and dedupByID were used by nothing else.

Moved SimilarSongs and its helpers to provider_similarsongs.go, matching the
existing provider_similarsongs_test.go. Pure code motion: the moved block is
byte-for-byte unchanged and provider.go has no additions, only deletions.

* fix(instant-mix): dedup before deciding a mix is full

topUp measured res before deduplicating it. Matcher.MatchSongs deliberately
re-emits a library track when the same input song repeats, and the similar-artists
fallback can reach one track through several artists, so len(res) could equal count
while holding fewer unique tracks. That returned a mix with duplicates in it and
stopped the top-up early; the caller then deduplicated and handed back a short mix,
which is the client retry loop this branch set out to fix.

Deduplicate first, so the length check counts what the client will actually receive.

* perf(instant-mix): skip a fallback once the mix is already full

The artist path nested one topUp inside another, so the inner one measured only
similarSongsFallback's own result against the full count. With 49 agent matches and
one fallback match for count=50 the mix was already full, yet seed-track sampling
still ran and fired up to five GetSimilarSongsByTrack calls whose results the outer
topUp then truncated away.

topUp now takes the sources as a variadic list and re-checks the accumulated mix
before each one, so a later, costlier source only runs while the mix is still short.
That also flattens the artist case: the agent, the similar-artists fallback and
seed-track sampling are now three peers in one chain instead of two nested calls.

* fix(instant-mix): count distinct tracks when picking the fallback mix

similarSongsFallback stopped after count picks from the weighted chooser, but a
track can sit in that chooser once per artist listing it in their top songs, and
Pick removes the entry it returns. Repeats therefore consumed pick slots and left
unique candidates stranded, so the batch could come back short of count. On the
track path this is the only source, so that short mix reached the client and kept
the retry loop alive.

Track the ids already picked and keep drawing until count distinct tracks are held
or the chooser is empty.

* fix(instant-mix): match the whole agent response before trimming

MatchSongs was capped at count, and it re-emits a track when the same song repeats,
so [A, A, B] with count=2 returned [A, A] and never reached B. topUp then shrank
that to [A] and, with an empty or overlapping fallback, the mix stayed short even
though B had been available all along. seedMix already matched its full merged set
for this reason; mixFromAgent now does the same and leaves the trim to topUp.

Also drop the capacity hint on the picked-ids map. It was sized from the caller's
count, which CodeQL flags as an allocation sized by user input (go/uncontrolled-
allocation-size). SimilarSongs clamps count to maxSimilarSongs long before this
point, so the hint bought nothing worth the alert.

* refactor(instant-mix): tidy the mix chain and its specs

Quality pass over the new code, no behaviour change:

- topUp: drop the first-vs-last error bookkeeping (the value is only read when the
  mix is empty, so the distinction is unobservable) and the redundant nil guard
  (dedupByID returns nil for an empty result, so both branches already agreed).
- mixFromAgent: assign through the if-scoped err instead of a second error name.
- Hoist the similar-artists fallback closure written verbatim in two switch arms.
- Use map[string]struct{} in the pick loop, matching dedupByID in the same file.
- Trim three comments back within budget; two restated the line below them and one
  carried commit-message rationale.
- Tests: add an ids() helper for the ID assertion repeated seven times, and fold
  the track-entity stub block copied into three specs into stubTrackEntity. The
  block hard-coded .Twice() on GetEntityByID, which pinned an implementation
  detail no spec asserts.

* revert(instant-mix): inline the similar-artists fallback closure again

Hoisting it to a shared artistFallback var moved the call away from the arm that
uses it and saved nothing: each arm reads better spelling out its own sources.
---
 core/external/extdata_helper_test.go        |   5 +
 core/external/provider.go                   | 255 +----------------
 core/external/provider_similarsongs.go      | 299 ++++++++++++++++++++
 core/external/provider_similarsongs_test.go | 219 +++++++++++++-
 4 files changed, 515 insertions(+), 263 deletions(-)
 create mode 100644 core/external/provider_similarsongs.go

diff --git a/core/external/extdata_helper_test.go b/core/external/extdata_helper_test.go
index d68147168..f7a155cd9 100644
--- a/core/external/extdata_helper_test.go
+++ b/core/external/extdata_helper_test.go
@@ -6,6 +6,7 @@ import (
 
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/stretchr/testify/mock"
 )
 
@@ -324,3 +325,7 @@ func (m *mockAgents) GetSimilarSongsByArtist(ctx context.Context, id, name, mbid
 	}
 	return nil, args.Error(1)
 }
+
+func ids(mfs model.MediaFiles) []string {
+	return slice.Map(mfs, func(mf model.MediaFile) string { return mf.ID })
+}
diff --git a/core/external/provider.go b/core/external/provider.go
index 383e7d4c9..782c7c3aa 100644
--- a/core/external/provider.go
+++ b/core/external/provider.go
@@ -4,7 +4,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"math/rand/v2"
 	"sort"
 	"strings"
 	"time"
@@ -15,21 +14,15 @@ import (
 	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/persistence"
 	"github.com/navidrome/navidrome/utils"
 	. "github.com/navidrome/navidrome/utils/gg"
-	"github.com/navidrome/navidrome/utils/random"
 	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/navidrome/navidrome/utils/str"
 	"golang.org/x/sync/errgroup"
 )
 
 const (
-	maxSimilarArtists = 100
-	maxSeeds          = 5
-	// Subsonic passes the client's count through unbounded, and it ends up as a SQL limit. 500 is
-	// what the widest caller (similarAlbums, limit*5) legitimately asks for.
-	maxSimilarSongs    = 500
+	maxSimilarArtists  = 100
 	refreshDelay       = 5 * time.Second
 	refreshTimeout     = 15 * time.Second
 	refreshQueueLength = 2000
@@ -283,252 +276,6 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 	return artist, nil
 }
 
-func (e *provider) SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error) {
-	// Subsonic passes the client's count straight through: a non-positive one has no valid
-	// interpretation, and an enormous one overflows the +1 in the local agent's query limit.
-	if count <= 0 {
-		return nil, nil
-	}
-	count = min(count, maxSimilarSongs)
-	entity, err := model.GetEntityByID(ctx, e.ds, id)
-	if err != nil {
-		// Genre ids don't resolve via GetEntityByID; look them up before giving up.
-		if !errors.Is(err, model.ErrNotFound) {
-			return nil, err
-		}
-		genre, err := e.ds.Genre(ctx).Get(id)
-		if err != nil {
-			return nil, err
-		}
-		return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
-			return e.sampleGenreTracks(ctx, genre, maxSeeds)
-		})
-	}
-
-	// Try entity-specific similarity first, then fall back to seed-track sampling.
-	switch v := entity.(type) {
-	case *model.MediaFile:
-		return e.mixFromAgent(ctx, count,
-			func() ([]agents.Song, error) {
-				return e.ag.GetSimilarSongsByTrack(ctx, v.ID, v.Title, v.Artist, v.MbzRecordingID, count)
-			},
-			func() (model.MediaFiles, error) {
-				return e.similarSongsFallback(ctx, id, count)
-			})
-	case *model.Album:
-		return e.mixFromAgent(ctx, count,
-			func() ([]agents.Song, error) {
-				return e.ag.GetSimilarSongsByAlbum(ctx, v.ID, v.Name, v.AlbumArtist, v.MbzAlbumID, count)
-			},
-			func() (model.MediaFiles, error) {
-				return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
-					return e.sampleAlbumTracks(ctx, v.ID, maxSeeds)
-				})
-			})
-	case *model.Artist:
-		return e.mixFromAgent(ctx, count,
-			func() ([]agents.Song, error) {
-				return e.ag.GetSimilarSongsByArtist(ctx, v.ID, v.Name, v.MbzArtistID, count)
-			},
-			func() (model.MediaFiles, error) {
-				if res, ferr := e.similarSongsFallback(ctx, id, count); ferr == nil && len(res) > 0 {
-					return res, nil
-				}
-				return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
-					return e.sampleArtistTracks(ctx, v.ID, maxSeeds)
-				})
-			})
-	case *model.Playlist:
-		return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
-			return e.samplePlaylistTracks(ctx, v.ID, maxSeeds)
-		})
-	default:
-		log.Warn(ctx, "Unknown entity type", "id", id, "type", fmt.Sprintf("%T", entity))
-		return nil, model.ErrNotFound
-	}
-}
-
-// mixFromAgent returns the agent's recommendations matched to library tracks, or the fallback
-// when the agent errors or none of its picks are in the library.
-func (e *provider) mixFromAgent(ctx context.Context, count int, fetch func() ([]agents.Song, error), fallback func() (model.MediaFiles, error)) (model.MediaFiles, error) {
-	songs, err := fetch()
-	if err == nil {
-		matched, merr := e.matcher.MatchSongs(ctx, songs, count)
-		if merr != nil {
-			return nil, merr
-		}
-		if len(matched) > 0 {
-			return matched, nil
-		}
-	}
-	return fallback()
-}
-
-// seedMix samples seed tracks, runs each through the agent chain's per-track similarity and merges
-// the results, falling back to the seeds themselves so the result is never empty.
-func (e *provider) seedMix(ctx context.Context, count int, sample func() (model.MediaFiles, error)) (model.MediaFiles, error) {
-	seeds, err := sample()
-	if err != nil {
-		return nil, err
-	}
-	if len(seeds) == 0 {
-		return nil, nil
-	}
-	seeds = seeds[:min(len(seeds), maxSeeds)]
-
-	// The per-seed similarity calls are independent and hit the (possibly remote) agent chain, so
-	// run them concurrently. Best-effort: a seed that errors just contributes nothing.
-	perSeed := make([][]agents.Song, len(seeds))
-	var g errgroup.Group
-	for i, seed := range seeds {
-		g.Go(func() error {
-			if s, err := e.ag.GetSimilarSongsByTrack(ctx, seed.ID, seed.Title, seed.Artist, seed.MbzRecordingID, count); err == nil {
-				perSeed[i] = s
-			}
-			return nil
-		})
-	}
-	_ = g.Wait()
-
-	var songs []agents.Song
-	for _, s := range perSeed {
-		songs = append(songs, s...)
-	}
-	// Match the whole merged set, not just count of it: the matcher re-emits a track when two
-	// seeds recommend it identically, so the duplicates have to be dropped before trimming. Every
-	// seed reaches the shuffle, so no seed can crowd out the others.
-	matched, err := e.matcher.MatchSongs(ctx, songs, len(songs))
-	if err != nil {
-		return nil, err
-	}
-	matched = dedupByID(matched)
-	if len(matched) == 0 {
-		matched = seeds
-	}
-	rand.Shuffle(len(matched), func(i, j int) { matched[i], matched[j] = matched[j], matched[i] })
-	if len(matched) > count {
-		matched = matched[:count]
-	}
-	return matched, nil
-}
-
-func (e *provider) samplePlaylistTracks(ctx context.Context, playlistID string, n int) (model.MediaFiles, error) {
-	// Refresh: a smart playlist materializes no tracks until it is evaluated, so skipping it would
-	// mix an empty seed set. It is a no-op for regular playlists and inside the refresh delay.
-	repo := e.ds.Playlist(ctx).Tracks(playlistID, true)
-	if repo == nil {
-		return nil, model.ErrNotFound
-	}
-	// A playlist can hold the same file at several positions, so over-fetch and dedup: a repeated
-	// seed wastes an agent call and can reach the mix twice through the seed fallback.
-	tracks, err := repo.GetAll(model.QueryOptions{
-		Sort:    "random",
-		Max:     n * 4,
-		Filters: squirrel.Eq{"missing": false},
-	})
-	if err != nil {
-		return nil, err
-	}
-	mfs := dedupByID(tracks.MediaFiles())
-	return mfs[:min(len(mfs), n)], nil
-}
-
-func dedupByID(mfs model.MediaFiles) model.MediaFiles {
-	seen := make(map[string]struct{}, len(mfs))
-	return slice.Filter(mfs, func(mf model.MediaFile) bool {
-		if _, dup := seen[mf.ID]; dup {
-			return false
-		}
-		seen[mf.ID] = struct{}{}
-		return true
-	})
-}
-
-func (e *provider) sampleAlbumTracks(ctx context.Context, albumID string, n int) (model.MediaFiles, error) {
-	return e.sampleTracks(ctx, squirrel.Eq{"album_id": albumID}, n)
-}
-
-func (e *provider) sampleArtistTracks(ctx context.Context, artistID string, n int) (model.MediaFiles, error) {
-	// media_file.artist_id is the deprecated primary artist, so it misses an artist credited only
-	// on the album, as on compilations. Same filter the artist listings use.
-	filter := persistence.ParticipantIDFilter("media_file", artistID, model.RoleArtist, model.RoleAlbumArtist)
-	return e.sampleTracks(ctx, filter, n)
-}
-
-func (e *provider) sampleGenreTracks(ctx context.Context, genre *model.Genre, n int) (model.MediaFiles, error) {
-	return e.sampleTracks(ctx, persistence.SongGenres.ByID(genre.ID), n)
-}
-
-// sampleTracks returns up to n random present tracks. Seeds can end up in the mix verbatim, so
-// missing files would surface as unplayable entries.
-func (e *provider) sampleTracks(ctx context.Context, filter squirrel.Sqlizer, n int) (model.MediaFiles, error) {
-	return e.ds.MediaFile(ctx).GetRandom(model.QueryOptions{
-		Filters: squirrel.And{filter, squirrel.Eq{"missing": false}},
-		Max:     n,
-	})
-}
-
-// similarSongsFallback uses the original similar artists + top songs algorithm. The idea is to
-// get the artist of the given entity, retrieve similar artists, get their top songs, and pick
-// a weighted random selection of songs to return as similar songs.
-func (e *provider) similarSongsFallback(ctx context.Context, id string, count int) (model.MediaFiles, error) {
-	artist, err := e.getArtist(ctx, id)
-	if err != nil {
-		return nil, err
-	}
-
-	e.callGetSimilarArtists(ctx, e.ag, &artist, 15, false)
-	if utils.IsCtxDone(ctx) {
-		log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
-		return nil, ctx.Err()
-	}
-
-	weightedSongs := random.NewWeightedChooser[model.MediaFile]()
-	addArtist := func(a model.Artist, weightedSongs *random.WeightedChooser[model.MediaFile], count, artistWeight int) error {
-		if utils.IsCtxDone(ctx) {
-			log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
-			return ctx.Err()
-		}
-
-		topCount := max(count, 20)
-		topSongs, err := e.getMatchingTopSongs(ctx, e.ag, &auxArtist{Artist: a}, topCount)
-		if err != nil {
-			log.Warn(ctx, "Error getting artist's top songs", "artist", a.Name, err)
-			return nil
-		}
-
-		weight := topCount * (4 + artistWeight)
-		for _, mf := range topSongs {
-			weightedSongs.Add(mf, weight)
-			weight -= 4
-		}
-		return nil
-	}
-
-	err = addArtist(artist.Artist, weightedSongs, count, 10)
-	if err != nil {
-		return nil, err
-	}
-	for _, a := range artist.SimilarArtists {
-		err := addArtist(a, weightedSongs, count, 0)
-		if err != nil {
-			return nil, err
-		}
-	}
-
-	var similarSongs model.MediaFiles
-	for len(similarSongs) < count && weightedSongs.Size() > 0 {
-		s, err := weightedSongs.Pick()
-		if err != nil {
-			log.Warn(ctx, "Error getting weighted song", err)
-			continue
-		}
-		similarSongs = append(similarSongs, s)
-	}
-
-	return similarSongs, nil
-}
-
 func (e *provider) TopSongs(ctx context.Context, artistName, id string, count int) (model.MediaFiles, error) {
 	artist, err := e.findArtist(ctx, artistName, id)
 	if err != nil {
diff --git a/core/external/provider_similarsongs.go b/core/external/provider_similarsongs.go
new file mode 100644
index 000000000..22b20565b
--- /dev/null
+++ b/core/external/provider_similarsongs.go
@@ -0,0 +1,299 @@
+package external
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math/rand/v2"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
+	"github.com/navidrome/navidrome/utils"
+	"github.com/navidrome/navidrome/utils/random"
+	"github.com/navidrome/navidrome/utils/slice"
+	"golang.org/x/sync/errgroup"
+)
+
+const (
+	maxSeeds = 5
+	// Subsonic passes the client's count through unbounded, and it ends up as a SQL limit. 500 is
+	// what the widest caller (similarAlbums, limit*5) legitimately asks for.
+	maxSimilarSongs = 500
+)
+
+func (e *provider) SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error) {
+	// Subsonic passes the client's count straight through: a non-positive one has no valid
+	// interpretation, and an enormous one overflows the +1 in the local agent's query limit.
+	if count <= 0 {
+		return nil, nil
+	}
+	count = min(count, maxSimilarSongs)
+	entity, err := model.GetEntityByID(ctx, e.ds, id)
+	if err != nil {
+		// Genre ids don't resolve via GetEntityByID; look them up before giving up.
+		if !errors.Is(err, model.ErrNotFound) {
+			return nil, err
+		}
+		genre, err := e.ds.Genre(ctx).Get(id)
+		if err != nil {
+			return nil, err
+		}
+		return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
+			return e.sampleGenreTracks(ctx, genre, maxSeeds)
+		})
+	}
+
+	// Try entity-specific similarity first, then fall back to seed-track sampling.
+	switch v := entity.(type) {
+	case *model.MediaFile:
+		return e.mixFromAgent(ctx, count,
+			func() ([]agents.Song, error) {
+				return e.ag.GetSimilarSongsByTrack(ctx, v.ID, v.Title, v.Artist, v.MbzRecordingID, count)
+			},
+			func() (model.MediaFiles, error) {
+				return e.similarSongsFallback(ctx, id, count)
+			})
+	case *model.Album:
+		return e.mixFromAgent(ctx, count,
+			func() ([]agents.Song, error) {
+				return e.ag.GetSimilarSongsByAlbum(ctx, v.ID, v.Name, v.AlbumArtist, v.MbzAlbumID, count)
+			},
+			func() (model.MediaFiles, error) {
+				return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
+					return e.sampleAlbumTracks(ctx, v.ID, maxSeeds)
+				})
+			})
+	case *model.Artist:
+		return e.mixFromAgent(ctx, count,
+			func() ([]agents.Song, error) {
+				return e.ag.GetSimilarSongsByArtist(ctx, v.ID, v.Name, v.MbzArtistID, count)
+			},
+			func() (model.MediaFiles, error) {
+				return e.similarSongsFallback(ctx, id, count)
+			},
+			func() (model.MediaFiles, error) {
+				return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
+					return e.sampleArtistTracks(ctx, v.ID, maxSeeds)
+				})
+			})
+	case *model.Playlist:
+		return e.seedMix(ctx, count, func() (model.MediaFiles, error) {
+			return e.samplePlaylistTracks(ctx, v.ID, maxSeeds)
+		})
+	default:
+		log.Warn(ctx, "Unknown entity type", "id", id, "type", fmt.Sprintf("%T", entity))
+		return nil, model.ErrNotFound
+	}
+}
+
+// mixFromAgent returns the agent's recommendations matched to library tracks, topped up from the
+// fallbacks in order when they don't fill the mix on their own.
+func (e *provider) mixFromAgent(ctx context.Context, count int, fetch func() ([]agents.Song, error), fallbacks ...func() (model.MediaFiles, error)) (model.MediaFiles, error) {
+	var matched model.MediaFiles
+	if songs, err := fetch(); err == nil {
+		// Match the whole response: capping at count can stop before a later unique pick.
+		matched, err = e.matcher.MatchSongs(ctx, songs, len(songs))
+		if err != nil {
+			return nil, err
+		}
+	}
+	return topUp(ctx, matched, count, fallbacks...)
+}
+
+// topUp draws on each source in turn until the mix holds count distinct tracks.
+func topUp(ctx context.Context, res model.MediaFiles, count int, sources ...func() (model.MediaFiles, error)) (model.MediaFiles, error) {
+	// The matcher can re-emit a track, so a full-looking res may hold fewer than count unique ones.
+	res = dedupByID(res)
+	var lastErr error
+	for _, more := range sources {
+		if len(res) >= count {
+			break
+		}
+		extra, err := more()
+		if err != nil {
+			log.Debug(ctx, "Could not top up a short mix", "have", len(res), "want", count, err)
+			lastErr = err
+			continue
+		}
+		res = dedupByID(append(res, extra...))
+	}
+	if len(res) == 0 {
+		return nil, lastErr
+	}
+	return res[:min(len(res), count)], nil
+}
+
+// seedMix samples seed tracks, runs each through the agent chain's per-track similarity and merges
+// the results, falling back to the seeds themselves so the result is never empty.
+func (e *provider) seedMix(ctx context.Context, count int, sample func() (model.MediaFiles, error)) (model.MediaFiles, error) {
+	seeds, err := sample()
+	if err != nil {
+		return nil, err
+	}
+	if len(seeds) == 0 {
+		return nil, nil
+	}
+	seeds = seeds[:min(len(seeds), maxSeeds)]
+
+	// The per-seed similarity calls are independent and hit the (possibly remote) agent chain, so
+	// run them concurrently. Best-effort: a seed that errors just contributes nothing.
+	perSeed := make([][]agents.Song, len(seeds))
+	var g errgroup.Group
+	for i, seed := range seeds {
+		g.Go(func() error {
+			if s, err := e.ag.GetSimilarSongsByTrack(ctx, seed.ID, seed.Title, seed.Artist, seed.MbzRecordingID, count); err == nil {
+				perSeed[i] = s
+			}
+			return nil
+		})
+	}
+	_ = g.Wait()
+
+	var songs []agents.Song
+	for _, s := range perSeed {
+		songs = append(songs, s...)
+	}
+	// Match the whole merged set, not just count of it: the matcher re-emits a track when two
+	// seeds recommend it identically, so the duplicates have to be dropped before trimming. Every
+	// seed reaches the shuffle, so no seed can crowd out the others.
+	matched, err := e.matcher.MatchSongs(ctx, songs, len(songs))
+	if err != nil {
+		return nil, err
+	}
+	matched = dedupByID(matched)
+	if len(matched) == 0 {
+		matched = seeds
+	}
+	rand.Shuffle(len(matched), func(i, j int) { matched[i], matched[j] = matched[j], matched[i] })
+	if len(matched) > count {
+		matched = matched[:count]
+	}
+	return matched, nil
+}
+
+func (e *provider) samplePlaylistTracks(ctx context.Context, playlistID string, n int) (model.MediaFiles, error) {
+	// Refresh: a smart playlist materializes no tracks until it is evaluated, so skipping it would
+	// mix an empty seed set. It is a no-op for regular playlists and inside the refresh delay.
+	repo := e.ds.Playlist(ctx).Tracks(playlistID, true)
+	if repo == nil {
+		return nil, model.ErrNotFound
+	}
+	// A playlist can hold the same file at several positions, so over-fetch and dedup: a repeated
+	// seed wastes an agent call and can reach the mix twice through the seed fallback.
+	tracks, err := repo.GetAll(model.QueryOptions{
+		Sort:    "random",
+		Max:     n * 4,
+		Filters: squirrel.Eq{"missing": false},
+	})
+	if err != nil {
+		return nil, err
+	}
+	mfs := dedupByID(tracks.MediaFiles())
+	return mfs[:min(len(mfs), n)], nil
+}
+
+func dedupByID(mfs model.MediaFiles) model.MediaFiles {
+	seen := make(map[string]struct{}, len(mfs))
+	return slice.Filter(mfs, func(mf model.MediaFile) bool {
+		if _, dup := seen[mf.ID]; dup {
+			return false
+		}
+		seen[mf.ID] = struct{}{}
+		return true
+	})
+}
+
+func (e *provider) sampleAlbumTracks(ctx context.Context, albumID string, n int) (model.MediaFiles, error) {
+	return e.sampleTracks(ctx, squirrel.Eq{"album_id": albumID}, n)
+}
+
+func (e *provider) sampleArtistTracks(ctx context.Context, artistID string, n int) (model.MediaFiles, error) {
+	// media_file.artist_id is the deprecated primary artist, so it misses an artist credited only
+	// on the album, as on compilations. Same filter the artist listings use.
+	filter := persistence.ParticipantIDFilter("media_file", artistID, model.RoleArtist, model.RoleAlbumArtist)
+	return e.sampleTracks(ctx, filter, n)
+}
+
+func (e *provider) sampleGenreTracks(ctx context.Context, genre *model.Genre, n int) (model.MediaFiles, error) {
+	return e.sampleTracks(ctx, persistence.SongGenres.ByID(genre.ID), n)
+}
+
+// sampleTracks returns up to n random present tracks. Seeds can end up in the mix verbatim, so
+// missing files would surface as unplayable entries.
+func (e *provider) sampleTracks(ctx context.Context, filter squirrel.Sqlizer, n int) (model.MediaFiles, error) {
+	return e.ds.MediaFile(ctx).GetRandom(model.QueryOptions{
+		Filters: squirrel.And{filter, squirrel.Eq{"missing": false}},
+		Max:     n,
+	})
+}
+
+// similarSongsFallback uses the original similar artists + top songs algorithm. The idea is to
+// get the artist of the given entity, retrieve similar artists, get their top songs, and pick
+// a weighted random selection of songs to return as similar songs.
+func (e *provider) similarSongsFallback(ctx context.Context, id string, count int) (model.MediaFiles, error) {
+	artist, err := e.getArtist(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	e.callGetSimilarArtists(ctx, e.ag, &artist, 15, false)
+	if utils.IsCtxDone(ctx) {
+		log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
+		return nil, ctx.Err()
+	}
+
+	weightedSongs := random.NewWeightedChooser[model.MediaFile]()
+	addArtist := func(a model.Artist, weightedSongs *random.WeightedChooser[model.MediaFile], count, artistWeight int) error {
+		if utils.IsCtxDone(ctx) {
+			log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
+			return ctx.Err()
+		}
+
+		topCount := max(count, 20)
+		topSongs, err := e.getMatchingTopSongs(ctx, e.ag, &auxArtist{Artist: a}, topCount)
+		if err != nil {
+			log.Warn(ctx, "Error getting artist's top songs", "artist", a.Name, err)
+			return nil
+		}
+
+		weight := topCount * (4 + artistWeight)
+		for _, mf := range topSongs {
+			weightedSongs.Add(mf, weight)
+			weight -= 4
+		}
+		return nil
+	}
+
+	err = addArtist(artist.Artist, weightedSongs, count, 10)
+	if err != nil {
+		return nil, err
+	}
+	for _, a := range artist.SimilarArtists {
+		err := addArtist(a, weightedSongs, count, 0)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	// Count distinct tracks, not picks: a collaboration sits in the chooser once per artist that
+	// lists it, and letting those repeats consume the budget strands unique candidates.
+	var similarSongs model.MediaFiles
+	picked := map[string]struct{}{}
+	for len(similarSongs) < count && weightedSongs.Size() > 0 {
+		s, err := weightedSongs.Pick()
+		if err != nil {
+			log.Warn(ctx, "Error getting weighted song", err)
+			continue
+		}
+		if _, dup := picked[s.ID]; dup {
+			continue
+		}
+		picked[s.ID] = struct{}{}
+		similarSongs = append(similarSongs, s)
+	}
+
+	return similarSongs, nil
+}
diff --git a/core/external/provider_similarsongs_test.go b/core/external/provider_similarsongs_test.go
index 5617269b3..ac54495f4 100644
--- a/core/external/provider_similarsongs_test.go
+++ b/core/external/provider_similarsongs_test.go
@@ -13,7 +13,6 @@ import (
 	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
-	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/stretchr/testify/mock"
@@ -65,6 +64,18 @@ var _ = Describe("Provider - SimilarSongs", func() {
 		provider = NewProvider(ds, agentsCombined, matcher.New(ds))
 	})
 
+	// Resolves track-1 through the GetEntityByID probe order and on to its artist. Left permissive:
+	// no spec here asserts how many times the entity is looked up.
+	stubTrackEntity := func() {
+		track := model.MediaFile{ID: "track-1", Title: "Track", Artist: "Artist", ArtistID: "artist-1"}
+		artist := model.Artist{ID: "artist-1", Name: "Artist"}
+		artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Maybe()
+		albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Maybe()
+		mediaFileRepo.On("Get", "track-1").Return(&track, nil).Maybe()
+		artistRepo.On("Get", "artist-1").Return(&artist, nil).Maybe()
+		artistRepo.On("GetAll", mock.Anything).Return(model.Artists{artist}, nil).Maybe()
+	}
+
 	Describe("dispatch by entity type", func() {
 		Context("when ID is a MediaFile (track)", func() {
 			It("calls GetSimilarSongsByTrack and returns matched songs", func() {
@@ -83,7 +94,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 				albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Once()
 				mediaFileRepo.On("Get", "track-1").Return(&track, nil).Once()
 
-				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Just Can't Get Enough", "Depeche Mode", "track-mbid", 5).
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Just Can't Get Enough", "Depeche Mode", "track-mbid", 1).
 					Return([]agents.Song{
 						{Name: "Dreaming of Me", MBID: "", Artists: []agents.Artist{{Name: "Depeche Mode", MBID: "artist-mbid"}}},
 					}, nil).Once()
@@ -126,7 +137,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 					return false
 				})).Return(model.MediaFiles{matchedSong}, nil).Maybe()
 
-				songs, err := provider.SimilarSongs(ctx, "track-1", 5)
+				songs, err := provider.SimilarSongs(ctx, "track-1", 1)
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(songs).To(HaveLen(1))
@@ -176,6 +187,76 @@ var _ = Describe("Provider - SimilarSongs", func() {
 				Expect(songs).To(HaveLen(1))
 				Expect(songs[0].ID).To(Equal("song-1"))
 			})
+
+			It("tops the mix up with the fallback when the agent's picks alone are too few", func() {
+				stubTrackEntity()
+
+				// The agent knows one track of the three asked for.
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Track", "Artist", "", 3).
+					Return([]agents.Song{{Name: "Agent Pick", MBID: "mbid-agent"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).
+					Return(model.MediaFiles{{ID: "agent-1", Title: "Agent Pick", MbzRecordingID: "mbid-agent"}}, nil).Once()
+
+				mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist", "", 15).
+					Return([]agents.Artist{}, nil).Once()
+				mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "Song One", MBID: "mbid-1"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).
+					Return(model.MediaFiles{{ID: "song-1", Title: "Song One", MbzRecordingID: "mbid-1"}}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 3)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(ids(songs)).To(ConsistOf("agent-1", "song-1"))
+			})
+
+			It("reaches a unique pick that sits past the count-th repeat", func() {
+				stubTrackEntity()
+				mockAgent.On("GetSimilarArtists", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Artist{}, nil).Maybe()
+				mockAgent.On("GetArtistTopSongs", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{}, nil).Maybe()
+
+				// "Song B" sits past the second repeat, so a matcher capped at count never reaches it.
+				repeated := agents.Song{Name: "Song A", MBID: "mbid-a"}
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Track", "Artist", "", 2).
+					Return([]agents.Song{repeated, repeated, {Name: "Song B", MBID: "mbid-b"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{
+					{ID: "t-a", Title: "Song A", MbzRecordingID: "mbid-a"},
+					{ID: "t-b", Title: "Song B", MbzRecordingID: "mbid-b"},
+				}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 2)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(ids(songs)).To(ConsistOf("t-a", "t-b"))
+			})
+
+			It("keeps topping up when the agent's picks repeat a track", func() {
+				stubTrackEntity()
+
+				// The matcher re-emits a track when the same input song repeats, so these three
+				// picks resolve to only two distinct library tracks.
+				repeated := agents.Song{Name: "Song A", MBID: "mbid-a"}
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Track", "Artist", "", 3).
+					Return([]agents.Song{repeated, repeated, {Name: "Song B", MBID: "mbid-b"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{
+					{ID: "t-a", Title: "Song A", MbzRecordingID: "mbid-a"},
+					{ID: "t-b", Title: "Song B", MbzRecordingID: "mbid-b"},
+				}, nil).Once()
+
+				mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist", "", 15).
+					Return([]agents.Artist{}, nil).Once()
+				mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "Song C", MBID: "mbid-c"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).
+					Return(model.MediaFiles{{ID: "t-c", Title: "Song C", MbzRecordingID: "mbid-c"}}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "track-1", 3)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(ids(songs)).To(ConsistOf("t-a", "t-b", "t-c"))
+			})
 		})
 
 		Context("when ID is an Album", func() {
@@ -187,7 +268,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 				artistRepo.On("Get", "album-1").Return(nil, model.ErrNotFound).Once()
 				albumRepo.On("Get", "album-1").Return(&album, nil).Once()
 
-				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "album-1", "Speak & Spell", "Depeche Mode", "album-mbid", 5).
+				agentsCombined.On("GetSimilarSongsByAlbum", mock.Anything, "album-1", "Speak & Spell", "Depeche Mode", "album-mbid", 1).
 					Return([]agents.Song{
 						{Name: "New Life", MBID: "song-mbid", Artists: []agents.Artist{{Name: "Depeche Mode"}}},
 					}, nil).Once()
@@ -208,7 +289,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 					return hasEq
 				})).Return(model.MediaFiles{matchedSong}, nil).Once()
 
-				songs, err := provider.SimilarSongs(ctx, "album-1", 5)
+				songs, err := provider.SimilarSongs(ctx, "album-1", 1)
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(songs).To(HaveLen(1))
@@ -286,7 +367,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 				matchedSong := model.MediaFile{ID: "matched-1", Title: "Enjoy the Silence", Artist: "Depeche Mode", MbzRecordingID: "song-mbid"}
 
 				artistRepo.On("Get", "artist-1").Return(&artist, nil).Once()
-				agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Depeche Mode", "artist-mbid", 5).
+				agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "artist-1", "Depeche Mode", "artist-mbid", 1).
 					Return([]agents.Song{
 						{Name: "Enjoy the Silence", MBID: "song-mbid", Artists: []agents.Artist{{Name: "Depeche Mode"}}},
 					}, nil).Once()
@@ -307,7 +388,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 					return hasEq
 				})).Return(model.MediaFiles{matchedSong}, nil).Once()
 
-				songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
+				songs, err := provider.SimilarSongs(ctx, "artist-1", 1)
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(songs).To(HaveLen(1))
@@ -348,6 +429,72 @@ var _ = Describe("Provider - SimilarSongs", func() {
 			})
 		})
 
+		Context("when ID is an Artist and the similar-artists fallback can't fill the mix", func() {
+			It("tops the mix up with the artist's own track-similars", func() {
+				artist := model.Artist{ID: "ar-1", Name: "Thin Artist"}
+				topSong := model.MediaFile{ID: "top-1", Title: "Top Song", ArtistID: "ar-1", MbzRecordingID: "mbid-top"}
+
+				artistRepo.On("Get", "ar-1").Return(&artist, nil).Maybe()
+				artistRepo.On("GetAll", mock.Anything).Return(model.Artists{artist}, nil).Maybe()
+
+				agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "ar-1", "Thin Artist", "", 5).
+					Return([]agents.Song{}, nil).Once()
+
+				// No similar artist is in the library, so the fallback yields only the seed artist's
+				// own matching top song: one track for a mix of five.
+				mockAgent.On("GetSimilarArtists", mock.Anything, "ar-1", "Thin Artist", "", 15).
+					Return([]agents.Artist{}, nil).Once()
+				mockAgent.On("GetArtistTopSongs", mock.Anything, "ar-1", "Thin Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "Top Song", MBID: "mbid-top"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{topSong}, nil).Once()
+
+				mediaFileRepo.On("GetRandom", mock.Anything).
+					Return(model.MediaFiles{{ID: "s1", Title: "Seed", Artist: "Thin Artist"}}, nil).Once()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "s1", "Seed", "Thin Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "Mix Song", MBID: "mbid-mix"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).
+					Return(model.MediaFiles{{ID: "mix-1", Title: "Mix Song", MbzRecordingID: "mbid-mix"}}, nil).Once()
+
+				songs, err := provider.SimilarSongs(ctx, "ar-1", 5)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(ids(songs)).To(ConsistOf("top-1", "mix-1"))
+			})
+		})
+
+		Context("when ID is an Artist and the agent plus the similar-artists fallback already fill the mix", func() {
+			It("does not pay for seed-track sampling", func() {
+				artist := model.Artist{ID: "ar-1", Name: "The Artist"}
+				artistRepo.On("Get", "ar-1").Return(&artist, nil).Maybe()
+				artistRepo.On("GetAll", mock.Anything).Return(model.Artists{artist}, nil).Maybe()
+
+				agentsCombined.On("GetSimilarSongsByArtist", mock.Anything, "ar-1", "The Artist", "", 3).
+					Return([]agents.Song{{Name: "A", MBID: "mbid-a"}, {Name: "B", MBID: "mbid-b"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{
+					{ID: "t-a", Title: "A", MbzRecordingID: "mbid-a"},
+					{ID: "t-b", Title: "B", MbzRecordingID: "mbid-b"},
+				}, nil).Once()
+
+				// The similar-artists fallback supplies the third track, so the mix is full.
+				mockAgent.On("GetSimilarArtists", mock.Anything, "ar-1", "The Artist", "", 15).
+					Return([]agents.Artist{}, nil).Once()
+				mockAgent.On("GetArtistTopSongs", mock.Anything, "ar-1", "The Artist", "", mock.Anything).
+					Return([]agents.Song{{Name: "C", MBID: "mbid-c"}}, nil).Once()
+				mediaFileRepo.On("GetAll", mock.Anything).
+					Return(model.MediaFiles{{ID: "t-c", Title: "C", MbzRecordingID: "mbid-c"}}, nil).Once()
+
+				mediaFileRepo.On("GetRandom", mock.Anything).Return(model.MediaFiles{{ID: "seed"}}, nil).Maybe()
+				agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+					Return([]agents.Song{}, nil).Maybe()
+
+				songs, err := provider.SimilarSongs(ctx, "ar-1", 3)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(ids(songs)).To(ConsistOf("t-a", "t-b", "t-c"))
+				mediaFileRepo.AssertNotCalled(GinkgoT(), "GetRandom", mock.Anything)
+			})
+		})
+
 		Context("when ID is a Playlist", func() {
 			It("samples playlist tracks and returns their track-similars", func() {
 				pls := model.Playlist{ID: "pl-1", Name: "My List"}
@@ -553,7 +700,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 
 				Expect(err).ToNot(HaveOccurred())
 				Expect(songs).To(HaveLen(3))
-				ids := slice.Map(songs, func(mf model.MediaFile) string { return mf.ID })
+				ids := ids(songs)
 				Expect(ids).To(ContainElement(BeElementOf("b1", "b2")), "seed two must be represented in the mix")
 			})
 
@@ -750,6 +897,60 @@ var _ = Describe("Provider - SimilarSongs", func() {
 		}
 	})
 
+	It("keeps picking until the fallback holds count distinct tracks", func() {
+		// A collaboration in two artists' top songs lands in the chooser twice. Picking a fixed
+		// count of entries lets those duplicates eat the budget and strand unique candidates.
+		track := model.MediaFile{ID: "track-1", Title: "Track", Artist: "Artist One", ArtistID: "artist-1"}
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One"}
+		similarArtist := model.Artist{ID: "artist-3", Name: "Similar Artist"}
+
+		artistRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Twice()
+		albumRepo.On("Get", "track-1").Return(nil, model.ErrNotFound).Twice()
+		mediaFileRepo.On("Get", "track-1").Return(&track, nil).Twice()
+		artistRepo.On("Get", "artist-1").Return(&artist1, nil).Maybe()
+		artistRepo.On("Get", "artist-3").Return(&similarArtist, nil).Maybe()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			return opt.Max == 1 && opt.Filters != nil
+		})).Return(model.Artists{artist1}, nil).Maybe()
+
+		agentsCombined.On("GetSimilarSongsByTrack", mock.Anything, "track-1", "Track", "Artist One", "", 3).
+			Return([]agents.Song{}, nil).Once()
+
+		mockAgent.On("GetSimilarArtists", mock.Anything, "artist-1", "Artist One", "", 15).
+			Return([]agents.Artist{{Name: "Similar Artist"}}, nil).Once()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			_, ok := opt.Filters.(squirrel.Eq)
+			return opt.Max == 0 && ok
+		})).Return(model.Artists{}, nil).Once()
+		artistRepo.On("GetAll", mock.MatchedBy(func(opt model.QueryOptions) bool {
+			_, ok := opt.Filters.(squirrel.Or)
+			return opt.Max == 0 && ok
+		})).Return(model.Artists{similarArtist}, nil).Once()
+
+		shared := model.MediaFile{ID: "t-a", Title: "Shared", MbzRecordingID: "mbid-a"}
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-1", "Artist One", "", mock.Anything).
+			Return([]agents.Song{{Name: "Shared", MBID: "mbid-a"}}, nil).Once()
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).
+			Return(model.MediaFiles{shared}, nil).Once()
+
+		mockAgent.On("GetArtistTopSongs", mock.Anything, "artist-3", "Similar Artist", "", mock.Anything).
+			Return([]agents.Song{
+				{Name: "Shared", MBID: "mbid-a"},
+				{Name: "B", MBID: "mbid-b"},
+				{Name: "C", MBID: "mbid-c"},
+			}, nil).Once()
+		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{
+			shared,
+			{ID: "t-b", Title: "B", MbzRecordingID: "mbid-b"},
+			{ID: "t-c", Title: "C", MbzRecordingID: "mbid-c"},
+		}, nil).Once()
+
+		songs, err := provider.SimilarSongs(ctx, "track-1", 3)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ids(songs)).To(ConsistOf("t-a", "t-b", "t-c"))
+	})
+
 	It("returns ErrNotFound when artist is not found", func() {
 		artistRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
 		mediaFileRepo.On("Get", "artist-unknown-artist").Return(nil, model.ErrNotFound)
@@ -792,7 +993,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 
 		mediaFileRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.MediaFiles{song1}, nil).Once()
 
-		songs, err := provider.SimilarSongs(ctx, "artist-1", 5)
+		songs, err := provider.SimilarSongs(ctx, "artist-1", 1)
 
 		Expect(err).ToNot(HaveOccurred())
 		Expect(songs).To(HaveLen(1))

From 59a4ed8e794e73fd41f3af7000a34ac86e718858 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 13 Aug 2026 22:56:09 -0400
Subject: [PATCH 036/200] fix(plugins): stop reporting plugin call failures as
 not-found (#5953)

* fix(plugins): stop reporting plugin call failures as not-found

MetadataAgent joined agents.ErrNotFound onto every failed plugin call, so a
transport fault was indistinguishable from a definitive miss. The artwork
circuit breaker treats a not-found as a successful, definitive answer and
resets its failure counter, so it never opened for a failing plugin and kept
calling it on every request. Observed with the apple-music plugin against
prod: ~900 iTunes 429s in 27 minutes with the breaker never tripping.

Return the underlying error instead. The genuine empty-result branches still
return agents.ErrNotFound, and agent fallback is unaffected because
callAgentMethod/callAgentSliceMethod continue on any error, not only on
ErrNotFound.

* test(plugins): fold duplicate metadata agent error specs into one table

The error-handling container drove all 11 MetadataAgent methods twice: once
to assert the message, once to assert the failure is not an ErrNotFound. The
argument lists were identical, so each method cost two WASM instantiations for
one method's worth of coverage, and a new capability had to be registered in
two places to stay guarded.

Fold both assertions into a single DescribeTable, document the ErrNotFound
contract at the sentinel where agent implementers will read it, and collapse
breaker.record's hand-inlined predicate onto isTransientExternal, which it
already duplicated by hand with a keep-in-sync comment.

* fix(plugins): keep an unimplemented plugin method a definitive miss

Returning the raw plugin error made errNotImplemented and errFunctionNotFound
look like provider faults. Every MetadataAgent satisfies ArtistImageRetriever
and AlbumImageRetriever regardless of what the plugin actually exports, so
artwork resolution calls those stubs on a partially-implemented plugin: each
call counted toward the artwork circuit breaker and kept the item in the retry
queue instead of settling it absent.

Map both sentinels back onto agents.ErrNotFound, joined so the underlying
reason survives for diagnostics, and leave real call failures untouched. This
matches what ScrobblerPlugin already does for the same two sentinels.

The partial-implementation specs asserted only MatchError(errNotImplemented),
which the previous errors.Join satisfied incidentally, so nothing caught the
lost not-found semantics. They now assert both and are folded into one table.

* test(plugins): cover the missing-export arm of agentErr

The partial-metadata-agent fixture registers through the Go PDK, which exports
every method and answers with the not-implemented code, so no fixture reaches
the errFunctionNotFound branch. Building one would mean hand-writing Extism
exports to deliberately omit a function, which tests the manager's function
lookup rather than the mapping this PR added.

Cover agentErr directly instead: both sentinels classify as a definitive miss,
a call failure and a non-zero exit stay faults, and the underlying reason
survives in every case.

* fix(artwork): stop counting a cancelled run against the circuit breaker

callPluginFunction returns ctx.Err() when a plugin call is cancelled, and that
reached breaker.record as an ordinary error, so cancellations counted toward
the five consecutive failures that open a gate. A cancellation says nothing
about the provider, so it now neither counts nor clears the failure run.

Deliberately scoped to breaker.record rather than isTransientExternal: the
latter also drives whether the queue item is rescheduled, and a cancelled item
must still be retried rather than settling absent. context.DeadlineExceeded is
left counting as a fault, since a provider that blows the budget is one worth
backing off from.

Reachable today only at shutdown, where the in-memory breaker state is
discarded anyway. It becomes live the moment Worker.gate is used on a
request-scoped context, which is why it is worth closing now.
---
 core/agents/interfaces.go      |   2 +
 core/artwork/gate.go           |   8 +-
 core/artwork/worker_test.go    |  37 +++++
 plugins/metadata_agent.go      |  27 ++--
 plugins/metadata_agent_test.go | 262 ++++++++++++++++-----------------
 5 files changed, 187 insertions(+), 149 deletions(-)

diff --git a/core/agents/interfaces.go b/core/agents/interfaces.go
index d5f4a6580..7fc5de361 100644
--- a/core/agents/interfaces.go
+++ b/core/agents/interfaces.go
@@ -53,6 +53,8 @@ func (s Song) Equals(other Song) bool {
 }
 
 var (
+	// ErrNotFound means the provider answered and had nothing. Return the underlying error
+	// for a fault instead, or callers that back off on faults will treat it as definitive.
 	ErrNotFound = errors.New("not found")
 )
 
diff --git a/core/artwork/gate.go b/core/artwork/gate.go
index a64c11a20..ff77f733d 100644
--- a/core/artwork/gate.go
+++ b/core/artwork/gate.go
@@ -1,6 +1,7 @@
 package artwork
 
 import (
+	"context"
 	"errors"
 	"io"
 	"sync"
@@ -101,10 +102,13 @@ func (b *breaker) allow() bool {
 }
 
 func (b *breaker) record(name string, err error) {
+	// A cancelled run says nothing about the provider, so it neither counts nor clears.
+	if errors.Is(err, context.Canceled) {
+		return
+	}
 	b.mu.Lock()
 	defer b.mu.Unlock()
-	// A not-found is a definitive answer, not a fault; keep in sync with isTransientExternal.
-	if err == nil || errors.Is(err, model.ErrNotFound) || errors.Is(err, agents.ErrNotFound) {
+	if !isTransientExternal(err) {
 		if b.failures >= breakerThreshold {
 			log.Info("Artwork: Circuit breaker closed for agent", "agent", name)
 		}
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index 5b6e42885..9fad4b503 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -539,6 +539,43 @@ var _ = Describe("Worker", func() {
 			Expect(calls).To(Equal(5), "the breaker should have re-closed after the success")
 		})
 
+		It("does not open the breaker when the run is cancelled", func() {
+			cancelled := func() (io.ReadCloser, string, error) { return nil, "", context.Canceled }
+			for range breakerThreshold + 3 {
+				_, _, err := w.gate("A", cancelled)
+				Expect(err).To(MatchError(context.Canceled), "a cancellation passes through, never errBreakerOpen")
+			}
+
+			var calls int
+			counting := func() (io.ReadCloser, string, error) {
+				calls++
+				return nil, "", errors.New("boom")
+			}
+			_, _, _ = w.gate("A", counting)
+			Expect(calls).To(Equal(1), "the breaker stayed closed, so the step still runs")
+		})
+
+		It("ignores a cancellation mid-run, neither counting nor clearing the failures", func() {
+			failing := func() (io.ReadCloser, string, error) { return nil, "", errors.New("boom") }
+			cancelled := func() (io.ReadCloser, string, error) { return nil, "", context.Canceled }
+			for range breakerThreshold - 1 {
+				_, _, _ = w.gate("A", failing)
+			}
+			_, _, _ = w.gate("A", cancelled)
+
+			var calls int
+			counting := func() (io.ReadCloser, string, error) {
+				calls++
+				return nil, "", errors.New("boom")
+			}
+			_, _, _ = w.gate("A", counting)
+			Expect(calls).To(Equal(1), "the cancellation must not have counted as the final failure")
+
+			_, _, err := w.gate("A", counting)
+			Expect(err).To(MatchError(errBreakerOpen), "the cancellation must not have cleared the earlier failures")
+			Expect(calls).To(Equal(1), "an open breaker must not call the external step")
+		})
+
 		It("does not open the breaker on a run of agent not-found misses", func() {
 			// agents.ErrNotFound is a definitive miss, not a fault: artless items must not
 			// trip the breaker, or they would loop in retry instead of settling absent.
diff --git a/plugins/metadata_agent.go b/plugins/metadata_agent.go
index e5d6d43fc..607926438 100644
--- a/plugins/metadata_agent.go
+++ b/plugins/metadata_agent.go
@@ -50,6 +50,15 @@ func newMetadataAgent(p *plugin) *MetadataAgent {
 	return &MetadataAgent{name: p.name, plugin: p}
 }
 
+// agentErr keeps a plugin fault distinguishable from a definitive miss: a method the plugin
+// simply does not implement has answered, so it must not count against a caller's back-off.
+func agentErr(err error) error {
+	if errors.Is(err, errNotImplemented) || errors.Is(err, errFunctionNotFound) {
+		return errors.Join(agents.ErrNotFound, err)
+	}
+	return err
+}
+
 // MetadataAgent is an adapter that wraps an Extism plugin and implements
 // the agents interfaces for metadata retrieval.
 type MetadataAgent struct {
@@ -69,7 +78,7 @@ func (a *MetadataAgent) GetArtistMBID(ctx context.Context, id string, name strin
 	input := capabilities.ArtistMBIDRequest{ID: id, Name: name}
 	result, err := callPluginFunction[capabilities.ArtistMBIDRequest, *capabilities.ArtistMBIDResponse](ctx, a.plugin, FuncGetArtistMBID, input)
 	if err != nil {
-		return "", errors.Join(agents.ErrNotFound, err)
+		return "", agentErr(err)
 	}
 
 	if result == nil || result.MBID == "" {
@@ -84,7 +93,7 @@ func (a *MetadataAgent) GetArtistURL(ctx context.Context, id, name, mbid string)
 	input := capabilities.ArtistRequest{ID: id, Name: name, MBID: mbid}
 	result, err := callPluginFunction[capabilities.ArtistRequest, *capabilities.ArtistURLResponse](ctx, a.plugin, FuncGetArtistURL, input)
 	if err != nil {
-		return "", errors.Join(agents.ErrNotFound, err)
+		return "", agentErr(err)
 	}
 	if result == nil || result.URL == "" {
 		return "", agents.ErrNotFound
@@ -97,7 +106,7 @@ func (a *MetadataAgent) GetArtistBiography(ctx context.Context, id, name, mbid s
 	input := capabilities.ArtistRequest{ID: id, Name: name, MBID: mbid}
 	result, err := callPluginFunction[capabilities.ArtistRequest, *capabilities.ArtistBiographyResponse](ctx, a.plugin, FuncGetArtistBiography, input)
 	if err != nil {
-		return "", errors.Join(agents.ErrNotFound, err)
+		return "", agentErr(err)
 	}
 
 	if result == nil || result.Biography == "" {
@@ -112,7 +121,7 @@ func (a *MetadataAgent) GetSimilarArtists(ctx context.Context, id, name, mbid st
 	input := capabilities.SimilarArtistsRequest{ID: id, Name: name, MBID: mbid, Limit: int32(limit)}
 	result, err := callPluginFunction[capabilities.SimilarArtistsRequest, *capabilities.SimilarArtistsResponse](ctx, a.plugin, FuncGetSimilarArtists, input)
 	if err != nil {
-		return nil, errors.Join(agents.ErrNotFound, err)
+		return nil, agentErr(err)
 	}
 
 	if result == nil || len(result.Artists) == 0 {
@@ -132,7 +141,7 @@ func (a *MetadataAgent) GetArtistImages(ctx context.Context, id, name, mbid stri
 	input := capabilities.ArtistRequest{ID: id, Name: name, MBID: mbid}
 	result, err := callPluginFunction[capabilities.ArtistRequest, *capabilities.ArtistImagesResponse](ctx, a.plugin, FuncGetArtistImages, input)
 	if err != nil {
-		return nil, errors.Join(agents.ErrNotFound, err)
+		return nil, agentErr(err)
 	}
 
 	if result == nil || len(result.Images) == 0 {
@@ -152,7 +161,7 @@ func (a *MetadataAgent) GetArtistTopSongs(ctx context.Context, id, artistName, m
 	input := capabilities.TopSongsRequest{ID: id, Name: artistName, MBID: mbid, Count: int32(count)}
 	result, err := callPluginFunction[capabilities.TopSongsRequest, *capabilities.TopSongsResponse](ctx, a.plugin, FuncGetArtistTopSongs, input)
 	if err != nil {
-		return nil, errors.Join(agents.ErrNotFound, err)
+		return nil, agentErr(err)
 	}
 
 	if result == nil || len(result.Songs) == 0 {
@@ -167,7 +176,7 @@ func (a *MetadataAgent) GetAlbumInfo(ctx context.Context, name, artist, mbid str
 	input := capabilities.AlbumRequest{Name: name, Artist: artist, MBID: mbid}
 	result, err := callPluginFunction[capabilities.AlbumRequest, *capabilities.AlbumInfoResponse](ctx, a.plugin, FuncGetAlbumInfo, input)
 	if err != nil {
-		return nil, errors.Join(agents.ErrNotFound, err)
+		return nil, agentErr(err)
 	}
 
 	if result == nil {
@@ -187,7 +196,7 @@ func (a *MetadataAgent) GetAlbumImages(ctx context.Context, name, artist, mbid s
 	input := capabilities.AlbumRequest{Name: name, Artist: artist, MBID: mbid}
 	result, err := callPluginFunction[capabilities.AlbumRequest, *capabilities.AlbumImagesResponse](ctx, a.plugin, FuncGetAlbumImages, input)
 	if err != nil {
-		return nil, errors.Join(agents.ErrNotFound, err)
+		return nil, agentErr(err)
 	}
 
 	if result == nil || len(result.Images) == 0 {
@@ -205,7 +214,7 @@ func (a *MetadataAgent) GetAlbumImages(ctx context.Context, name, artist, mbid s
 func callSimilarSongsPluginFunction[T any](ctx context.Context, plugin *plugin, funcName string, input T) ([]agents.Song, error) {
 	result, err := callPluginFunction[T, *capabilities.SimilarSongsResponse](ctx, plugin, funcName, input)
 	if err != nil {
-		return nil, err
+		return nil, agentErr(err)
 	}
 	if result == nil || len(result.Songs) == 0 {
 		return nil, agents.ErrNotFound
diff --git a/plugins/metadata_agent_test.go b/plugins/metadata_agent_test.go
index a14db5d34..2dc67d41c 100644
--- a/plugins/metadata_agent_test.go
+++ b/plugins/metadata_agent_test.go
@@ -3,12 +3,36 @@
 package plugins
 
 import (
+	"errors"
+	"fmt"
+
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/plugins/capabilities"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
+// The partial-metadata-agent fixture registers through the Go PDK, which exports every method
+// and answers -2, so only errNotImplemented reaches agentErr through a real plugin. A plugin
+// that omits the export entirely yields errFunctionNotFound, covered here directly.
+var _ = Describe("agentErr", func() {
+	DescribeTable("classifies a plugin error as a miss or a fault",
+		func(err error, wantMiss bool) {
+			got := agentErr(err)
+			Expect(errors.Is(got, agents.ErrNotFound)).To(Equal(wantMiss))
+			Expect(got).To(MatchError(err), "the underlying reason must survive for diagnostics")
+		},
+		Entry("an unimplemented method is a miss",
+			fmt.Errorf("%w: %s", errNotImplemented, FuncGetArtistImages), true),
+		Entry("a missing export is a miss",
+			fmt.Errorf("%w: %s", errFunctionNotFound, FuncGetArtistImages), true),
+		Entry("a call failure is a fault",
+			fmt.Errorf("plugin call failed: %w", errors.New("returned status 429")), false),
+		Entry("a non-zero exit is a fault",
+			errors.New("plugin call exited with code 1"), false),
+	)
+})
+
 var _ = Describe("MetadataAgent", Ordered, func() {
 	var agent agents.Interface
 
@@ -166,82 +190,57 @@ var _ = Describe("MetadataAgent error handling", Ordered, func() {
 		Expect(ok).To(BeTrue())
 	})
 
-	It("returns error from GetArtistMBID", func() {
-		retriever := errorAgent.(agents.ArtistMBIDRetriever)
-		_, err := retriever.GetArtistMBID(GinkgoT().Context(), "artist-1", "Test")
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetArtistURL", func() {
-		retriever := errorAgent.(agents.ArtistURLRetriever)
-		_, err := retriever.GetArtistURL(GinkgoT().Context(), "artist-1", "Test", "mbid")
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetArtistBiography", func() {
-		retriever := errorAgent.(agents.ArtistBiographyRetriever)
-		_, err := retriever.GetArtistBiography(GinkgoT().Context(), "artist-1", "Test", "mbid")
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetArtistImages", func() {
-		retriever := errorAgent.(agents.ArtistImageRetriever)
-		_, err := retriever.GetArtistImages(GinkgoT().Context(), "artist-1", "Test", "mbid")
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetSimilarArtists", func() {
-		retriever := errorAgent.(agents.ArtistSimilarRetriever)
-		_, err := retriever.GetSimilarArtists(GinkgoT().Context(), "artist-1", "Test", "mbid", 5)
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetArtistTopSongs", func() {
-		retriever := errorAgent.(agents.ArtistTopSongsRetriever)
-		_, err := retriever.GetArtistTopSongs(GinkgoT().Context(), "artist-1", "Test", "mbid", 5)
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetAlbumInfo", func() {
-		retriever := errorAgent.(agents.AlbumInfoRetriever)
-		_, err := retriever.GetAlbumInfo(GinkgoT().Context(), "Album", "Artist", "mbid")
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetAlbumImages", func() {
-		retriever := errorAgent.(agents.AlbumImageRetriever)
-		_, err := retriever.GetAlbumImages(GinkgoT().Context(), "Album", "Artist", "mbid")
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetSimilarSongsByTrack", func() {
-		retriever := errorAgent.(agents.SimilarSongsByTrackRetriever)
-		_, err := retriever.GetSimilarSongsByTrack(GinkgoT().Context(), "track-1", "Test", "Artist", "mbid", 5)
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetSimilarSongsByAlbum", func() {
-		retriever := errorAgent.(agents.SimilarSongsByAlbumRetriever)
-		_, err := retriever.GetSimilarSongsByAlbum(GinkgoT().Context(), "album-1", "Album", "Artist", "mbid", 5)
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
-
-	It("returns error from GetSimilarSongsByArtist", func() {
-		retriever := errorAgent.(agents.SimilarSongsByArtistRetriever)
-		_, err := retriever.GetSimilarSongsByArtist(GinkgoT().Context(), "artist-1", "Artist", "mbid", 5)
-		Expect(err).To(HaveOccurred())
-		Expect(err.Error()).To(ContainSubstring("simulated plugin error"))
-	})
+	DescribeTable("surfaces the plugin failure, not a definitive not-found",
+		func(call func() error) {
+			err := call()
+			Expect(err).To(MatchError(ContainSubstring("simulated plugin error")))
+			Expect(err).ToNot(MatchError(agents.ErrNotFound))
+		},
+		Entry("GetArtistMBID", func() error {
+			_, err := errorAgent.(agents.ArtistMBIDRetriever).GetArtistMBID(GinkgoT().Context(), "artist-1", "Test")
+			return err
+		}),
+		Entry("GetArtistURL", func() error {
+			_, err := errorAgent.(agents.ArtistURLRetriever).GetArtistURL(GinkgoT().Context(), "artist-1", "Test", "mbid")
+			return err
+		}),
+		Entry("GetArtistBiography", func() error {
+			_, err := errorAgent.(agents.ArtistBiographyRetriever).GetArtistBiography(GinkgoT().Context(), "artist-1", "Test", "mbid")
+			return err
+		}),
+		Entry("GetSimilarArtists", func() error {
+			_, err := errorAgent.(agents.ArtistSimilarRetriever).GetSimilarArtists(GinkgoT().Context(), "artist-1", "Test", "mbid", 5)
+			return err
+		}),
+		Entry("GetArtistImages", func() error {
+			_, err := errorAgent.(agents.ArtistImageRetriever).GetArtistImages(GinkgoT().Context(), "artist-1", "Test", "mbid")
+			return err
+		}),
+		Entry("GetArtistTopSongs", func() error {
+			_, err := errorAgent.(agents.ArtistTopSongsRetriever).GetArtistTopSongs(GinkgoT().Context(), "artist-1", "Test", "mbid", 5)
+			return err
+		}),
+		Entry("GetAlbumInfo", func() error {
+			_, err := errorAgent.(agents.AlbumInfoRetriever).GetAlbumInfo(GinkgoT().Context(), "Album", "Artist", "mbid")
+			return err
+		}),
+		Entry("GetAlbumImages", func() error {
+			_, err := errorAgent.(agents.AlbumImageRetriever).GetAlbumImages(GinkgoT().Context(), "Album", "Artist", "mbid")
+			return err
+		}),
+		Entry("GetSimilarSongsByTrack", func() error {
+			_, err := errorAgent.(agents.SimilarSongsByTrackRetriever).GetSimilarSongsByTrack(GinkgoT().Context(), "track-1", "Test", "Artist", "mbid", 5)
+			return err
+		}),
+		Entry("GetSimilarSongsByAlbum", func() error {
+			_, err := errorAgent.(agents.SimilarSongsByAlbumRetriever).GetSimilarSongsByAlbum(GinkgoT().Context(), "album-1", "Album", "Artist", "mbid", 5)
+			return err
+		}),
+		Entry("GetSimilarSongsByArtist", func() error {
+			_, err := errorAgent.(agents.SimilarSongsByArtistRetriever).GetSimilarSongsByArtist(GinkgoT().Context(), "artist-1", "Artist", "mbid", 5)
+			return err
+		}),
+	)
 })
 
 var _ = Describe("MetadataAgent partial implementation", Ordered, func() {
@@ -268,68 +267,55 @@ var _ = Describe("MetadataAgent partial implementation", Ordered, func() {
 		Expect(bio).To(Equal("Partial agent biography for Test Artist"))
 	})
 
-	It("returns ErrNotFound for unimplemented method (GetArtistMBID)", func() {
-		retriever := partialAgent.(agents.ArtistMBIDRetriever)
-		_, err := retriever.GetArtistMBID(GinkgoT().Context(), "artist-1", "Test Artist")
-		Expect(err).To(MatchError(errNotImplemented))
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetArtistURL)", func() {
-		retriever := partialAgent.(agents.ArtistURLRetriever)
-		_, err := retriever.GetArtistURL(GinkgoT().Context(), "artist-1", "Test Artist", "mbid")
-		Expect(err).To(MatchError(errNotImplemented))
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetArtistImages)", func() {
-		retriever := partialAgent.(agents.ArtistImageRetriever)
-		_, err := retriever.GetArtistImages(GinkgoT().Context(), "artist-1", "Test Artist", "mbid")
-		Expect(err).To(MatchError(errNotImplemented))
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetSimilarArtists)", func() {
-		retriever := partialAgent.(agents.ArtistSimilarRetriever)
-		_, err := retriever.GetSimilarArtists(GinkgoT().Context(), "artist-1", "Test Artist", "mbid", 5)
-		Expect(err).To(MatchError(errNotImplemented))
-
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetArtistTopSongs)", func() {
-		retriever := partialAgent.(agents.ArtistTopSongsRetriever)
-		_, err := retriever.GetArtistTopSongs(GinkgoT().Context(), "artist-1", "Test Artist", "mbid", 5)
-		Expect(err).To(MatchError(errNotImplemented))
-
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetAlbumInfo)", func() {
-		retriever := partialAgent.(agents.AlbumInfoRetriever)
-		_, err := retriever.GetAlbumInfo(GinkgoT().Context(), "Album", "Artist", "mbid")
-		Expect(err).To(MatchError(errNotImplemented))
-
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetAlbumImages)", func() {
-		retriever := partialAgent.(agents.AlbumImageRetriever)
-		_, err := retriever.GetAlbumImages(GinkgoT().Context(), "Album", "Artist", "mbid")
-		Expect(err).To(MatchError(errNotImplemented))
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetSimilarSongsByTrack)", func() {
-		retriever := partialAgent.(agents.SimilarSongsByTrackRetriever)
-		_, err := retriever.GetSimilarSongsByTrack(GinkgoT().Context(), "track-1", "Test", "Artist", "mbid", 5)
-		Expect(err).To(MatchError(errNotImplemented))
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetSimilarSongsByAlbum)", func() {
-		retriever := partialAgent.(agents.SimilarSongsByAlbumRetriever)
-		_, err := retriever.GetSimilarSongsByAlbum(GinkgoT().Context(), "album-1", "Album", "Artist", "mbid", 5)
-		Expect(err).To(MatchError(errNotImplemented))
-	})
-
-	It("returns ErrNotFound for unimplemented method (GetSimilarSongsByArtist)", func() {
-		retriever := partialAgent.(agents.SimilarSongsByArtistRetriever)
-		_, err := retriever.GetSimilarSongsByArtist(GinkgoT().Context(), "artist-1", "Artist", "mbid", 5)
-		Expect(err).To(MatchError(errNotImplemented))
-	})
+	// An unimplemented optional method is a definitive miss. Reported as a fault it would
+	// count against the artwork circuit breaker and keep the item in the retry queue.
+	DescribeTable("reports an unimplemented method as a definitive not-found",
+		func(call func() error) {
+			err := call()
+			Expect(err).To(MatchError(errNotImplemented))
+			Expect(err).To(MatchError(agents.ErrNotFound))
+		},
+		Entry("GetArtistMBID", func() error {
+			_, err := partialAgent.(agents.ArtistMBIDRetriever).GetArtistMBID(GinkgoT().Context(), "artist-1", "Test Artist")
+			return err
+		}),
+		Entry("GetArtistURL", func() error {
+			_, err := partialAgent.(agents.ArtistURLRetriever).GetArtistURL(GinkgoT().Context(), "artist-1", "Test Artist", "mbid")
+			return err
+		}),
+		Entry("GetArtistImages", func() error {
+			_, err := partialAgent.(agents.ArtistImageRetriever).GetArtistImages(GinkgoT().Context(), "artist-1", "Test Artist", "mbid")
+			return err
+		}),
+		Entry("GetSimilarArtists", func() error {
+			_, err := partialAgent.(agents.ArtistSimilarRetriever).GetSimilarArtists(GinkgoT().Context(), "artist-1", "Test Artist", "mbid", 5)
+			return err
+		}),
+		Entry("GetArtistTopSongs", func() error {
+			_, err := partialAgent.(agents.ArtistTopSongsRetriever).GetArtistTopSongs(GinkgoT().Context(), "artist-1", "Test Artist", "mbid", 5)
+			return err
+		}),
+		Entry("GetAlbumInfo", func() error {
+			_, err := partialAgent.(agents.AlbumInfoRetriever).GetAlbumInfo(GinkgoT().Context(), "Album", "Artist", "mbid")
+			return err
+		}),
+		Entry("GetAlbumImages", func() error {
+			_, err := partialAgent.(agents.AlbumImageRetriever).GetAlbumImages(GinkgoT().Context(), "Album", "Artist", "mbid")
+			return err
+		}),
+		Entry("GetSimilarSongsByTrack", func() error {
+			_, err := partialAgent.(agents.SimilarSongsByTrackRetriever).GetSimilarSongsByTrack(GinkgoT().Context(), "track-1", "Test", "Artist", "mbid", 5)
+			return err
+		}),
+		Entry("GetSimilarSongsByAlbum", func() error {
+			_, err := partialAgent.(agents.SimilarSongsByAlbumRetriever).GetSimilarSongsByAlbum(GinkgoT().Context(), "album-1", "Album", "Artist", "mbid", 5)
+			return err
+		}),
+		Entry("GetSimilarSongsByArtist", func() error {
+			_, err := partialAgent.(agents.SimilarSongsByArtistRetriever).GetSimilarSongsByArtist(GinkgoT().Context(), "artist-1", "Artist", "mbid", 5)
+			return err
+		}),
+	)
 })
 
 var _ = Describe("songRefToAgentSong multi-artist", func() {

From aa0824e03bfd617caeddfe52a41a421a77e6289f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 14 Aug 2026 09:17:00 -0400
Subject: [PATCH 037/200] feat(jellyfin): add System/Endpoint so Finamp's
 connection test passes (#5955)

Finamp's connection test GETs /System/Endpoint and treats anything other
than a 200 carrying an IsInNetwork key as "not a Jellyfin server", so the
test failed against Navidrome and dual-connection setups could never
switch to the local address.

IsInNetwork mirrors Jellyfin's default LAN set (NetworkManager with no
LocalNetworkSubnets configured): loopback, the RFC 1918 ranges, fc00::/7
and fe80::/10. Notably that set omits 169.254.0.0/16, so Go's
IsLinkLocalUnicast is deliberately restricted to its IPv6 half.

IsLocal mirrors HttpContext.IsLocal(): the caller shares the connection's
local address, not merely "is loopback". It falls back to the loopback
check when the local address is unavailable.
---
 server/jellyfin/README.md          |  2 +-
 server/jellyfin/api.go             |  1 +
 server/jellyfin/dto/dto.go         |  6 ++++
 server/jellyfin/e2e/system_test.go | 16 +++++++++
 server/jellyfin/system.go          | 44 +++++++++++++++++++++++
 server/jellyfin/system_test.go     | 56 ++++++++++++++++++++++++++++++
 6 files changed, 124 insertions(+), 1 deletion(-)

diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 195173c2a..5759e6cc0 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -112,7 +112,7 @@ returns direct children only (no tracks — no track is a library's direct child
 
 | Area | Endpoints |
 |---|---|
-| Handshake / system | `GET System/Info/Public`, `GET System/Info` (authenticated), `GET`/`POST System/Ping`, `GET QuickConnect/Enabled` |
+| Handshake / system | `GET System/Info/Public`, `GET System/Info` (authenticated), `GET`/`POST System/Ping`, `GET System/Endpoint` (authenticated), `GET QuickConnect/Enabled` |
 | Auth | `POST Users/AuthenticateByName`, `GET Users/Public` |
 | Users | `GET UserViews`, `GET Users/{userId}/Views`, `GET Users/Me`, `GET Users/{userId}` |
 | Browsing | `GET Items`, `GET Users/{userId}/Items`, `GET Items/{itemId}`, `GET Users/{userId}/Items/{itemId}`, `GET Users/{userId}/Items/Latest`, `DELETE Items/{itemId}` (playlists only) |
diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index 8a175df35..d64366a63 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -104,6 +104,7 @@ func (api *Router) routes() http.Handler {
 		// player) even before the first playback report.
 		r.Use(api.withPlayer)
 		r.Get("/system/info", api.getSystemInfo)
+		r.Get("/system/endpoint", api.getEndpointInfo)
 		r.Get("/userviews", api.getUserViews)
 		r.Get("/users/{userId}/views", api.getUserViews)
 		r.Get("/users/me", api.getCurrentUser)
diff --git a/server/jellyfin/dto/dto.go b/server/jellyfin/dto/dto.go
index 5a2a4c2b1..58a6b919e 100644
--- a/server/jellyfin/dto/dto.go
+++ b/server/jellyfin/dto/dto.go
@@ -20,6 +20,12 @@ type SystemInfo struct {
 	CachePath              string `json:"CachePath,omitempty"`
 }
 
+// EndPointInfo describes the caller's network location (GET /System/Endpoint).
+type EndPointInfo struct {
+	IsLocal     bool `json:"IsLocal"`
+	IsInNetwork bool `json:"IsInNetwork"`
+}
+
 type NameGuidPair struct {
 	Name string `json:"Name"`
 	Id   string `json:"Id"`
diff --git a/server/jellyfin/e2e/system_test.go b/server/jellyfin/e2e/system_test.go
index c6f9145d5..ac8c350c4 100644
--- a/server/jellyfin/e2e/system_test.go
+++ b/server/jellyfin/e2e/system_test.go
@@ -51,6 +51,22 @@ var _ = Describe("System", func() {
 		})
 	})
 
+	Describe("GET /System/Endpoint", func() {
+		It("always reports IsInNetwork, which Finamp's connection test probes for", func() {
+			w := getAs(regularUser, "/System/Endpoint")
+			Expect(w.Code).To(Equal(http.StatusOK))
+			var info map[string]any
+			parseInto(w, &info)
+			Expect(info).To(HaveKey("IsInNetwork"))
+			Expect(info).To(HaveKey("IsLocal"))
+		})
+
+		It("rejects unauthenticated requests", func() {
+			w := rawReq("GET", "/System/Endpoint", "")
+			Expect(w.Code).To(Equal(http.StatusUnauthorized))
+		})
+	})
+
 	Describe("GET/POST /System/Ping", func() {
 		It("answers GET with a plain-text server name", func() {
 			w := rawReq("GET", "/System/Ping", "")
diff --git a/server/jellyfin/system.go b/server/jellyfin/system.go
index ea553fd87..8b847987f 100644
--- a/server/jellyfin/system.go
+++ b/server/jellyfin/system.go
@@ -5,7 +5,9 @@ import (
 	"encoding/hex"
 	"errors"
 	"fmt"
+	"net"
 	"net/http"
+	"net/netip"
 	"path"
 	"strings"
 
@@ -108,6 +110,48 @@ func (api *Router) ping(w http.ResponseWriter, r *http.Request) {
 	_, _ = w.Write([]byte(api.serverName()))
 }
 
+// getEndpointInfo answers /System/Endpoint, which Finamp's connection test uses to pick between a
+// dual-connection setup's addresses; a missing IsInNetwork reads to it as "not a Jellyfin server".
+func (api *Router) getEndpointInfo(w http.ResponseWriter, r *http.Request) {
+	remote := remoteIP(r)
+	api.ok(w, r, dto.EndPointInfo{
+		IsLocal:     isSameMachine(r, remote),
+		IsInNetwork: isInLocalNetwork(remote),
+	})
+}
+
+// isInLocalNetwork mirrors Jellyfin's default LAN set (NetworkManager.UpdateSettings with no
+// LocalNetworkSubnets configured): loopback, the RFC 1918 ranges, fc00::/7 and fe80::/10.
+func isInLocalNetwork(ip netip.Addr) bool {
+	return ip.IsLoopback() || ip.IsPrivate() || (ip.Is6() && ip.IsLinkLocalUnicast())
+}
+
+// isSameMachine mirrors Jellyfin's HttpContext.IsLocal(): the caller shares the connection's local
+// address. The local address is missing in tests and unreliable behind a proxy, so fall back to loopback.
+func isSameMachine(r *http.Request, remote netip.Addr) bool {
+	local, ok := r.Context().Value(http.LocalAddrContextKey).(net.Addr)
+	if !ok {
+		return remote.IsLoopback()
+	}
+	return parseIP(local.String()) == remote
+}
+
+// remoteIP parses RemoteAddr, which the RealIP middleware may have rewritten to a bare IP.
+func remoteIP(r *http.Request) netip.Addr {
+	return parseIP(r.RemoteAddr)
+}
+
+func parseIP(addr string) netip.Addr {
+	if h, _, err := net.SplitHostPort(addr); err == nil {
+		addr = h
+	}
+	ip, err := netip.ParseAddr(addr)
+	if err != nil {
+		return netip.Addr{}
+	}
+	return ip.Unmap()
+}
+
 func (api *Router) quickConnectEnabled(w http.ResponseWriter, r *http.Request) {
 	api.ok(w, r, false)
 }
diff --git a/server/jellyfin/system_test.go b/server/jellyfin/system_test.go
index a7f7df6a4..4b3ac240e 100644
--- a/server/jellyfin/system_test.go
+++ b/server/jellyfin/system_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"net"
 	"net/http"
 	"net/http/httptest"
 
@@ -88,6 +89,61 @@ var _ = Describe("System", func() {
 		Expect(w.Body.String()).To(HavePrefix("Navidrome"))
 	})
 
+	DescribeTable("reports the caller's network location on /System/Endpoint",
+		func(remoteAddr string, isLocal, isInNetwork bool) {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/System/Endpoint", nil)
+			r.RemoteAddr = remoteAddr
+			api.getEndpointInfo(w, r)
+
+			Expect(w.Code).To(Equal(http.StatusOK))
+			// Finamp's connection test only probes for the key's presence, so it must always be emitted.
+			Expect(w.Body.String()).To(ContainSubstring(`"IsInNetwork"`))
+			var info dto.EndPointInfo
+			Expect(json.Unmarshal(w.Body.Bytes(), &info)).To(Succeed())
+			Expect(info.IsLocal).To(Equal(isLocal))
+			Expect(info.IsInNetwork).To(Equal(isInNetwork))
+		},
+		Entry("loopback", "127.0.0.1:12345", true, true),
+		Entry("IPv6 loopback", "[::1]:12345", true, true),
+		Entry("LAN address", "192.168.1.20:54321", false, true),
+		Entry("bare IP, as left by the RealIP middleware", "10.0.0.5", false, true),
+		Entry("IPv4-mapped IPv6 LAN address", "[::ffff:172.16.0.9]:80", false, true),
+		Entry("IPv6 link-local", "[fe80::1]:80", false, true),
+		Entry("IPv6 unique-local", "[fd00::1]:80", false, true),
+		// Jellyfin's default LAN set omits 169.254.0.0/16, so we do too.
+		Entry("IPv4 link-local", "169.254.1.1:80", false, false),
+		Entry("public address", "8.8.8.8:443", false, false),
+		Entry("unparseable address", "not-an-ip", false, false),
+	)
+
+	It("reports IsLocal when the caller shares the connection's local address", func() {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest("GET", "/System/Endpoint", nil)
+		r.RemoteAddr = "192.168.1.20:54321"
+		ctx := context.WithValue(r.Context(), http.LocalAddrContextKey,
+			&net.TCPAddr{IP: net.ParseIP("192.168.1.20"), Port: 4533})
+		api.getEndpointInfo(w, r.WithContext(ctx))
+
+		var info dto.EndPointInfo
+		Expect(json.Unmarshal(w.Body.Bytes(), &info)).To(Succeed())
+		Expect(info.IsLocal).To(BeTrue())
+	})
+
+	It("does not report IsLocal for a different host on the same LAN", func() {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest("GET", "/System/Endpoint", nil)
+		r.RemoteAddr = "192.168.1.99:54321"
+		ctx := context.WithValue(r.Context(), http.LocalAddrContextKey,
+			&net.TCPAddr{IP: net.ParseIP("192.168.1.20"), Port: 4533})
+		api.getEndpointInfo(w, r.WithContext(ctx))
+
+		var info dto.EndPointInfo
+		Expect(json.Unmarshal(w.Body.Bytes(), &info)).To(Succeed())
+		Expect(info.IsLocal).To(BeFalse())
+		Expect(info.IsInNetwork).To(BeTrue())
+	})
+
 	It("reports quick connect as disabled", func() {
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("GET", "/QuickConnect/Enabled", nil)

From 95615bcb18ece3f88af0d4dccb0e9faa25fb3e21 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 14 Aug 2026 09:43:13 -0400
Subject: [PATCH 038/200] fix(artwork): serve images whose format has no
 registered decoder (#5952)

* fix(artwork): serve images whose format has no registered decoder

The new pipeline derives dimensions, mime and the placeholder hashes at
resolution time, so a decode became a precondition for recording artwork at
all. An image in a format Go has no decoder for therefore failed acquisition,
retried until the 12h budget ran out, and then settled as absent, serving a
placeholder from that point on. The old pipeline decoded only to resize and
fell back to the original bytes when that failed, so these covers used to work.

A local file is picked by matching an image extension, so bytes it cannot
decode are most likely a codec we lack: image.ErrFormat on a folder, upload or
embedded source now yields an Artwork row carrying just the hash and mime, and
the bytes stay servable. An external response carries no such guarantee, so it
still fails and retries rather than pinning a non-image body as a cover. A
corrupt image of a known format and an over-cap declared size still fail, so
the decompression bomb guard is unchanged. Absent rows recorded by earlier
builds are re-resolved by the existing stale-absent recheck within a day, so
no epoch bump is needed to repair them.

Reusing a stored image now re-decodes when it carries no dimensions, so a
row recorded while a decoder was missing can still be upgraded later.

Registers jxl, heic and heif in mime_types.yaml: image detection resolves the
extension through the host MIME table, and the Alpine release image ships no
/etc/mime.types, so those covers were never recorded in folder.ImageFiles
there and never reached the pipeline at all.

* fix(artwork): never record empty bytes as artwork

image.DecodeConfig returns image.ErrFormat for an empty payload just as it
does for a codec with no registered decoder, so a zero-byte cover file was
recorded as found artwork and served as an empty response instead of falling
back to the placeholder. A truncated image of a known format already fails
with unexpected EOF rather than ErrFormat, so only the empty case needed the
guard.
---
 core/artwork/e2e/acquire_serve_test.go |  23 ++++++
 core/artwork/processor.go              |  23 +++++-
 core/artwork/processor_test.go         | 108 ++++++++++++++++++++++++-
 resources/mime_types.yaml              |   3 +
 4 files changed, 154 insertions(+), 3 deletions(-)

diff --git a/core/artwork/e2e/acquire_serve_test.go b/core/artwork/e2e/acquire_serve_test.go
index d6c374e39..0a9363b5d 100644
--- a/core/artwork/e2e/acquire_serve_test.go
+++ b/core/artwork/e2e/acquire_serve_test.go
@@ -6,6 +6,7 @@ import (
 	"errors"
 	"io"
 	"os"
+	"path/filepath"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -116,6 +117,25 @@ var _ = Describe("Acquisition → serve loop", func() {
 		albumRepo.SetData(model.Albums{{ID: albumID, Name: "Album", FolderIDs: []string{"f1"}, LibraryID: 0}})
 	}
 
+	It("acquires and serves a cover whose format has no registered decoder (#5950)", func() {
+		libDir := GinkgoT().TempDir()
+		Expect(os.MkdirAll(filepath.Join(libDir, "an-album"), 0755)).To(Succeed())
+		Expect(os.WriteFile(filepath.Join(libDir, "an-album", "cover.jxl"), jxlFixture, 0600)).To(Succeed())
+
+		conf.Server.CoverArtPriority = "cover.*"
+		libRepo.SetData(model.Libraries{{ID: 0, Path: libDir}})
+		folderRepo.result = []model.Folder{{Path: "an-album", ImageFiles: []string{"cover.jxl"}}}
+		albumRepo.SetData(model.Albums{{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}, LibraryID: 0}})
+
+		bump("al", "al1")
+		runWorkerUntil(ctx, worker, itemFound(model.KindAlbumArtwork, "al1"))
+
+		img, err := svc.Get(ctx, model.MustParseArtworkID("al-al1"), 0, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(img.Placeholder).To(BeFalse())
+		Expect(readAll(img)).To(Equal(jxlFixture))
+	})
+
 	It("acquires album folder art and serves the exact bytes under its hash", func() {
 		seedFolderAlbum("al1")
 		bump("al", "al1")
@@ -317,6 +337,9 @@ func mustGet(img *artwork.Image, err error) *artwork.Image {
 }
 
 // Raw bytes on purpose: encoding a GIF here would register image/gif in the test binary, masking
+// jxlFixture is a JPEG XL bare codestream header: a real image format, with no stdlib decoder.
+var jxlFixture = []byte{0xff, 0x0a, 0x00, 0x10, 0x00}
+
 // the production import the spec above guards.
 var gifFixture = []byte{
 	0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x04, 0x00, 0x04, 0x00, 0x80, 0x00,
diff --git a/core/artwork/processor.go b/core/artwork/processor.go
index 6ce76bf45..4d38ced95 100644
--- a/core/artwork/processor.go
+++ b/core/artwork/processor.go
@@ -123,12 +123,20 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 
 	art, err := repo.GetImage(hash)
 	switch {
-	case err == nil:
+	case err == nil && art.Width > 0:
 		log.Debug(ctx, "Artwork: Reusing a known image, skipping decode", "kind", item.ItemKind,
 			"id", item.ItemID, "hash", hash)
-	case errors.Is(err, model.ErrNotFound):
+	// A row with no dimensions was stored when no decoder matched; retry in case one exists now.
+	case err == nil, errors.Is(err, model.ErrNotFound):
 		decodeStart := time.Now()
 		art, err = decodeArtwork(ctx, hash, data)
+		// Extension-matched local bytes we cannot decode are most likely a codec we lack; an
+		// external body carries no such guarantee, and empty bytes are no image at all.
+		if errors.Is(err, image.ErrFormat) && len(data) > 0 && isLocalSource(res.source) {
+			log.Debug(ctx, "Artwork: No decoder for this image format, storing it without placeholders",
+				"kind", item.ItemKind, "id", item.ItemID, "source", res.source, "bytes", len(data))
+			art, err = undecodedArtwork(hash), nil
+		}
 		if err != nil {
 			log.Warn(ctx, "Artwork: Failed to decode resolved image", "kind", item.ItemKind, "id", item.ItemID, err)
 			return outcomeFailed, nil
@@ -234,6 +242,12 @@ func decodeCapped(data []byte) (image.Image, string, error) {
 	return img, format, nil
 }
 
+// undecodedArtwork is the row for bytes no decoder matched: servable, but with no dimensions
+// and none of the placeholders a decode would have produced.
+func undecodedArtwork(hash string) *model.Artwork {
+	return &model.Artwork{Hash: hash, Mime: mimeForFormat("")}
+}
+
 // decodeArtwork builds a new Artwork row from raw bytes: dimensions, mime and the two
 // placeholder hashes, both encoded from one shared downscaled thumbnail.
 func decodeArtwork(ctx context.Context, hash string, data []byte) (*model.Artwork, error) {
@@ -288,6 +302,11 @@ func isFileBacked(source string) bool {
 	return source == "folder" || source == "upload"
 }
 
+// isLocalSource reports whether the bytes came off disk rather than off the network.
+func isLocalSource(source string) bool {
+	return isFileBacked(source) || source == "embedded"
+}
+
 // placeBytes reports the item's backing-file provenance and writes the bytes into the store
 // for the sources that have none.
 func placeBytes(store *ImageStore, art *model.Artwork, res resolution, data []byte) (sourcePath string, refMtime int64, err error) {
diff --git a/core/artwork/processor_test.go b/core/artwork/processor_test.go
index 8d30975cd..1ada8415d 100644
--- a/core/artwork/processor_test.go
+++ b/core/artwork/processor_test.go
@@ -1,6 +1,7 @@
 package artwork
 
 import (
+	"bytes"
 	"context"
 	"encoding/binary"
 	"errors"
@@ -24,6 +25,9 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+// jxlCodestream is a JPEG XL bare codestream header: a real image format, with no stdlib decoder.
+var jxlCodestream = []byte{0xff, 0x0a, 0x00, 0x10, 0x00}
+
 // DecodeConfig reads only the header, so the pixel data can be omitted entirely.
 func pngHeaderWithDims(w, h uint32) []byte {
 	ihdr := make([]byte, 13)
@@ -259,6 +263,59 @@ var _ = Describe("processor.acquire", func() {
 		Expect(ia.Source).To(Equal("folder"))
 	})
 
+	It("undecodable local file: acquires it anyway, with no placeholder metadata", func() {
+		libRoot := GinkgoT().TempDir()
+		Expect(os.MkdirAll(filepath.Join(libRoot, "album"), 0755)).To(Succeed())
+		Expect(os.WriteFile(filepath.Join(libRoot, "album", "cover.jpg"), jxlCodestream, 0600)).To(Succeed())
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(libRoot)}})
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alU", Name: "Album", FolderIDs: []string{"f1"}}})
+		folderRepo.result = []model.Folder{{Path: "album", ImageFiles: []string{"cover.jpg"}}}
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alU"})
+		Expect(out).To(Equal(outcomeFound))
+
+		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alU", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ia.Source).To(Equal("folder"))
+		art, err := artRepo.GetImage(ia.Hash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(art.Width).To(BeZero())
+		Expect(art.BlurHash).To(BeEmpty())
+	})
+
+	It("empty local file: fails without writing state", func() {
+		libRoot := GinkgoT().TempDir()
+		Expect(os.MkdirAll(filepath.Join(libRoot, "album"), 0755)).To(Succeed())
+		Expect(os.WriteFile(filepath.Join(libRoot, "album", "cover.jpg"), nil, 0600)).To(Succeed())
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(libRoot)}})
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alE", Name: "Album", FolderIDs: []string{"f1"}}})
+		folderRepo.result = []model.Folder{{Path: "album", ImageFiles: []string{"cover.jpg"}}}
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alE"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alE", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+
+	// An agent answering 200 with a non-image body must keep retrying, not pin garbage as a cover.
+	It("undecodable external body: fails without writing state", func() {
+		conf.Server.CoverArtPriority = "external"
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write([]byte("<html>rate limited</html>"))
+		}))
+		DeferCleanup(srv.Close)
+
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alX", Name: "Album"}})
+		imageAgents(&fakeImageAgent{name: "deezerFake", imgs: []agents.ExternalImage{{URL: srv.URL, Size: 500}}})
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alX"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alX", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+
 	It("found-external: persists source as external:<agentName> and stores the fetched bytes", func() {
 		conf.Server.CoverArtPriority = "external"
 		imgBytes, err := os.ReadFile(filepath.Join(repoRoot, "tests/fixtures/artist/an-album/cover.jpg"))
@@ -374,7 +431,8 @@ var _ = Describe("processor.acquire", func() {
 		conf.Server.DataFolder = conf.NewDir(tmpDir)
 		Expect(os.MkdirAll(filepath.Join(tmpDir, "artwork", "radio"), 0755)).To(Succeed())
 		imgPath := filepath.Join(tmpDir, "artwork", "radio", "ra1_test.jpg")
-		Expect(os.WriteFile(imgPath, []byte("not actually an image"), 0600)).To(Succeed())
+		// Truncated PNG: a known format, so this is a real decode failure, not a missing decoder.
+		Expect(os.WriteFile(imgPath, pngHeaderWithDims(100, 100), 0600)).To(Succeed())
 
 		radioRepo := tests.CreateMockedRadioRepo()
 		radioRepo.Data = map[string]*model.Radio{"ra1": {ID: "ra1", Name: "Radio", UploadedImage: "ra1_test.jpg"}}
@@ -428,6 +486,54 @@ var _ = Describe("processor.acquire", func() {
 		Expect(err.Error()).To(ContainSubstring("dimensions"))
 	})
 
+	It("unknown format: reports ErrFormat so the caller can decide", func() {
+		_, err := decodeArtwork(ctx, "jxl", jxlCodestream)
+		Expect(err).To(MatchError(image.ErrFormat))
+	})
+
+	It("undecodedArtwork: carries the hash and mime, and nothing a decode would add", func() {
+		art := undecodedArtwork("jxl")
+		Expect(art.Hash).To(Equal("jxl"))
+		Expect(art.Mime).To(Equal("application/octet-stream"))
+		Expect(art.Width).To(BeZero())
+		Expect(art.Height).To(BeZero())
+		Expect(art.BlurHash).To(BeEmpty())
+		Expect(art.ThumbHash).To(BeEmpty())
+		Expect(art.DominantColor).To(BeEmpty())
+	})
+
+	It("corrupt image of a known format: still fails", func() {
+		data := pngHeaderWithDims(100, 100) // header declares a decodable size, body is missing
+		_, err := decodeArtwork(ctx, "truncated", data)
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("decode image"))
+	})
+
+	// Without this a metadata-less row would be reused forever, so a decoder added later
+	// could never upgrade it.
+	It("metadata-less row: re-decodes on reuse instead of skipping", func() {
+		libRoot := GinkgoT().TempDir()
+		imgBytes, err := os.ReadFile(filepath.Join(repoRoot, "tests/fixtures/artist/an-album/cover.jpg"))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(os.MkdirAll(filepath.Join(libRoot, "album"), 0755)).To(Succeed())
+		Expect(os.WriteFile(filepath.Join(libRoot, "album", "cover.jpg"), imgBytes, 0600)).To(Succeed())
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(libRoot)}})
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alM", Name: "Album", FolderIDs: []string{"f1"}}})
+		folderRepo.result = []model.Folder{{Path: "album", ImageFiles: []string{"cover.jpg"}}}
+
+		hash, err := hashImage(bytes.NewReader(imgBytes))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(artRepo.PutImage(&model.Artwork{Hash: hash, Mime: "application/octet-stream"})).To(Succeed())
+
+		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alM"})
+		Expect(out).To(Equal(outcomeFound))
+
+		upgraded, err := artRepo.GetImage(hash)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(upgraded.Width).To(BeNumerically(">", 0))
+		Expect(upgraded.BlurHash).ToNot(BeEmpty())
+	})
+
 	It("store write failure: fails without writing state", func() {
 		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 			{ID: "al7", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},
diff --git a/resources/mime_types.yaml b/resources/mime_types.yaml
index f67b26af4..83abf2e5c 100644
--- a/resources/mime_types.yaml
+++ b/resources/mime_types.yaml
@@ -37,6 +37,9 @@ types:
   .webp: image/webp
   .png: image/png
   .bmp: image/bmp
+  .jxl: image/jxl
+  .heic: image/heic
+  .heif: image/heif
 
 # List of audio formats that are considered lossless
 lossless:

From b617a878b90a9834579c0a36e20dc1e10d13a6fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 14 Aug 2026 13:46:52 -0400
Subject: [PATCH 039/200] feat(insights): report the app store or hosting
 platform via ND_PLATFORM (#5956)

* feat(insights): report the app store or hosting platform via ND_PLATFORM

Insights had no way to tell where an instance is deployed. The existing `os.package` field is written only by our own packagers and holds just `deb`, `rpm` or `msi`, so it answers "which installer", not "which platform". Overloading it would mix two unrelated dimensions in the same field.

This adds a separate top-level `platform` field, self-declared by the deployer through the `ND_PLATFORM` environment variable. App stores and hosting providers (ZimaOS, PikaPods, TrueNAS, Unraid, and others) generally deploy our container image unmodified and can only inject environment variables, so an env var is the one marker they can all set. It is deliberately not a config option: it is a packager marker, not something users should tune, and it stays out of the config surface.

Both values are now whitespace-trimmed. The msi packager writes the file with `echo`, so `os.package` has been arriving as `"msi\n"` and sorting separately from `"msi"` in any aggregation.

* test(insights): isolate hostingPlatform specs from an inherited ND_PLATFORM

The spec asserting an empty result read the real environment, so it failed on any machine that already had ND_PLATFORM set. Unset it per-spec, using Setenv first so Ginkgo restores the original value on cleanup.
---
 core/metrics/insights.go               | 19 +++++--
 core/metrics/insights/data.go          |  4 +-
 core/metrics/insights_internal_test.go | 70 ++++++++++++++++++++++++++
 core/metrics/metrics_suite_test.go     | 17 +++++++
 4 files changed, 104 insertions(+), 6 deletions(-)
 create mode 100644 core/metrics/insights_internal_test.go
 create mode 100644 core/metrics/metrics_suite_test.go

diff --git a/core/metrics/insights.go b/core/metrics/insights.go
index 78391779a..66d0b89bd 100644
--- a/core/metrics/insights.go
+++ b/core/metrics/insights.go
@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"runtime/debug"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"time"
@@ -153,6 +154,17 @@ func getFSInfo(path string) *insights.FSInfo {
 	return &info
 }
 
+// installedPackage returns the official installer format used, as written by our own packagers.
+func installedPackage() string {
+	data, _ := os.ReadFile(filepath.Join(conf.Server.DataFolder.String(), ".package"))
+	return strings.TrimSpace(string(data))
+}
+
+// hostingPlatform is env-based, not a file, as app stores can only inject env vars into our image.
+func hostingPlatform() string {
+	return strings.TrimSpace(os.Getenv("ND_PLATFORM"))
+}
+
 var staticData = sync.OnceValue(func() insights.Data {
 	// Basic info
 	data := insights.Data{
@@ -165,11 +177,8 @@ var staticData = sync.OnceValue(func() insights.Data {
 	data.OS.Containerized = consts.InContainer
 
 	// Install info
-	packageFilename := filepath.Join(conf.Server.DataFolder.String(), ".package")
-	packageFileData, err := os.ReadFile(packageFilename)
-	if err == nil {
-		data.OS.Package = string(packageFileData)
-	}
+	data.OS.Package = installedPackage()
+	data.Platform = hostingPlatform()
 
 	// OS info
 	data.OS.Type = runtime.GOOS
diff --git a/core/metrics/insights/data.go b/core/metrics/insights/data.go
index 126d759bc..8559d4204 100644
--- a/core/metrics/insights/data.go
+++ b/core/metrics/insights/data.go
@@ -4,7 +4,9 @@ type Data struct {
 	InsightsID string `json:"id"`
 	Version    string `json:"version"`
 	Uptime     int64  `json:"uptime"`
-	Build      struct {
+	// Platform is the app store or hosting provider this instance runs on, self-declared via ND_PLATFORM
+	Platform string `json:"platform,omitempty"`
+	Build    struct {
 		// build settings used by the Go compiler
 		Settings  map[string]string `json:"settings"`
 		GoVersion string            `json:"goVersion"`
diff --git a/core/metrics/insights_internal_test.go b/core/metrics/insights_internal_test.go
new file mode 100644
index 000000000..74c8ce236
--- /dev/null
+++ b/core/metrics/insights_internal_test.go
@@ -0,0 +1,70 @@
+package metrics
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("installedPackage", func() {
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DataFolder = conf.NewDir(GinkgoT().TempDir())
+	})
+
+	It("returns empty when there's no .package file", func() {
+		Expect(installedPackage()).To(BeEmpty())
+	})
+
+	It("reads the .package file from the data folder", func() {
+		writePackageFile("deb")
+
+		Expect(installedPackage()).To(Equal("deb"))
+	})
+
+	It("trims surrounding whitespace, as the msi packager writes a trailing newline", func() {
+		writePackageFile("msi\n")
+
+		Expect(installedPackage()).To(Equal("msi"))
+	})
+
+	It("ignores ND_PLATFORM", func() {
+		GinkgoT().Setenv("ND_PLATFORM", "zimaos")
+
+		Expect(installedPackage()).To(BeEmpty())
+	})
+})
+
+var _ = Describe("hostingPlatform", func() {
+	BeforeEach(func() {
+		// Setenv registers the restore, then unset so an inherited value can't leak in
+		GinkgoT().Setenv("ND_PLATFORM", "")
+		Expect(os.Unsetenv("ND_PLATFORM")).To(Succeed())
+	})
+
+	It("returns empty when ND_PLATFORM is not set", func() {
+		Expect(hostingPlatform()).To(BeEmpty())
+	})
+
+	It("reads ND_PLATFORM", func() {
+		GinkgoT().Setenv("ND_PLATFORM", "zimaos")
+
+		Expect(hostingPlatform()).To(Equal("zimaos"))
+	})
+
+	It("trims surrounding whitespace", func() {
+		GinkgoT().Setenv("ND_PLATFORM", "  pikapods\n")
+
+		Expect(hostingPlatform()).To(Equal("pikapods"))
+	})
+})
+
+func writePackageFile(content string) {
+	GinkgoHelper()
+	path := filepath.Join(conf.Server.DataFolder.String(), ".package")
+	Expect(os.WriteFile(path, []byte(content), 0600)).To(Succeed())
+}
diff --git a/core/metrics/metrics_suite_test.go b/core/metrics/metrics_suite_test.go
new file mode 100644
index 000000000..bae622e90
--- /dev/null
+++ b/core/metrics/metrics_suite_test.go
@@ -0,0 +1,17 @@
+package metrics
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestMetrics(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Metrics Suite")
+}

From dc40bcaf808a40a2b5d6e62c9338e84f40ca9407 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 14 Aug 2026 21:07:56 -0400
Subject: [PATCH 040/200] feat(cli): add an artwork command group for
 diagnosing and re-driving artwork (#5957)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(artwork): add a resolution chain trace collector

* feat(artwork): trace the local priority chain

* fix(artwork): record priority candidates the chain never evaluated

* refactor(artwork): report never-evaluated candidates as skipped

* feat(artwork): trace external agents at the gate seam

* feat(artwork): add repository queries to enqueue by current source

* feat(artwork): expose a tracing resolver for the CLI

* feat(artwork): read a single queue row by item

The explain CLI must report whether an item is queued, at what priority and when it
retries; the queue repository could only be drained in eligibility batches, which
cannot see a row that is still backing off.

* feat(cli): add artwork explain

Prints why an item has the artwork it has: the stored state, its queue row, the
governing config, the resolver's priority-chain walk and the verdict. Offline by
default so a diagnostic run cannot add load to an external provider; --live asks
the agents for real. Playlists and radios do not walk a priority chain, so they
report that instead of an empty chain table.

* fix(artwork): trace an external tier that never reaches an agent

A configured 'external' token vanished from the chain when no enabled agent provided
images for that entity type, and for synthetic artists, leaving the trace unable to
say whether the tier was even considered.

* fix(cli): never state an artwork outcome the walk did not observe

A transient external failure traced as 'error' fell through to 'not resolved', which
is the most common state behind a missing-artwork report. It is now indeterminate, and
an offline win that a skipped higher-priority external candidate could have taken says
so instead of naming a winner the live chain might not pick.

* feat(cli): add artwork refresh

* feat(cli): add artwork reprocess

Bulk re-enqueues artwork by kind and/or by the source an item currently
resolves from, previewing the matched count and confirming before queueing.

The preview counts with CountBySource (rows matched) and reports separately
what EnqueueBySource inserted: its DO NOTHING conflict policy leaves an
already-queued row untouched, so the two numbers differ and the output must
not claim the skipped rows were re-queued.

An unknown --source is rejected against the sources present in item_artwork,
rather than silently matching nothing and printing a reassuring 0.

* fix(cli): cover the reprocess selection rule and validate sources table-wide

The reconciliation that makes --source alone target every kind was only
exercised through runReprocess, which no test calls: mutating it to
`all := reprocessAll` left the suite green. It is now reprocessSelectsAll,
covered for all three selectors.

Scoping source validation to the selected kinds made the same well-formed
filter valid or invalid depending on which other kinds were selected, and its
error read the same for a typo as for a source that simply does not apply to
the chosen kind. Validation is now table-wide: a typo still aborts, while a
valid-but-inapplicable source falls through to "Nothing matches".

Also: the prompt now counts only the kinds that reach an external agent as
external cost, and --dry-run on an empty selection reports a dry run.

* fix(cli): cover the reprocess --yes guard and preview the external cost

Mutating the --yes check to `if true` left the suite green, so the one bypass
of the confirmation was unverified. The choice is now reprocessConfirm(yes, in),
covered in both directions.

The external estimate only reached the operator through the prompt, which
--dry-run skips — hiding the number in the one mode that exists to show it
before committing. The preview now carries it, and the prompt drops the clause
when no lookup will be made.

An empty selection says so again under --dry-run.

* feat(artwork): add read-only queue and absent counters

Both are needed by the artwork status CLI: a queue breakdown by kind and priority, and
the absent totals split against the recheck cutoff.

* feat(cli): add artwork status

Reports the queue, where artwork currently resolves from, absent counts against the 24h
recheck window, and the stored config fingerprint versus the current one — the line that
turns 'why is my server re-resolving everything?' into one command.

fingerprint() and staleAbsentAge are exported so the CLI reports the values backfill
itself compares, instead of a second copy of the formula that can silently drift.

* fix(cli): lead the artwork status backfill line with the queued backlog

By the time anyone runs a diagnostic, backfill has usually already stored the new
fingerprint, so 'up to date' was printed while thousands of items churned through external
providers. The backlog is the finding; the fingerprint is context.

Also echoes the config inputs the fingerprint covers, so a change can be traced to the
setting that caused it, and pins the rendered rows: the Absent values, the queue TOTAL and
a queue-scoped kind/priority pair were all unasserted, so kindName and priorityName were
effectively untested. FingerprintInputs is now the single listing ConfigFingerprint hashes;
a pinned hash proves the value did not change.

* refactor(artwork): export the trace outcome vocabulary

The CLI hardcoded the outcome literals and the "external:" prefix, so renaming a
constant's value in core/artwork left cmd compiling and the suite green while
`artwork explain` silently degraded its verdict.

Renaming a value now fails the golden vocabulary test in core/artwork and the
explainResult tests in cmd.

* fix(cli): keep the re-enqueue warning when a backfill is already running

A stale stored fingerprint with items already queued is the worst state the
system can be in: a second full re-enqueue is pending on top of the one running.
The line carried the weakest wording of the three, and was untested.

* refactor(artwork): drop the unreachable breaker branch from the tracing gate

--live wires the tracing gate straight to passthroughGate, so errBreakerOpen can
never reach it; the test only passed by injecting a fake gate.

* refactor(artwork): delete the never-emitted not-reached outcome

Candidates after the winner are lower priority and say nothing about why a source
won; the ones that matter sit above it and are already recorded.

* refactor(artwork): make the trace nil-safe in one place only

add already handles a nil trace, so record's own guard was dead; Steps was the
odd one out and would panic where every other method tolerates nil.

* refactor(artwork): export the trace types directly

ChainTrace and TraceStep were unexported types re-exported through aliases,
which existed only so the CLI had a name to refer to them by. The types are
public API — Resolver.Steps returns []TraceStep and the CLI constructs a
ChainTrace — so name them that way and drop the indirection.

Encapsulation is unchanged: add, mu and steps stay unexported, so only this
package can write a step.

* refactor(cli): simplify parseArtworkKind with slices.Contains

Replaces a nested loop and a manual append with slices.Contains and the
repo's slice.Map helper. Same behaviour, same error message.

* fix(cli): print the absent artwork source under the name --source accepts

`artwork explain` rendered the stored empty source as "(absent)", while
`artwork reprocess --source` only accepts "absent", so pasting what explain
printed straight back into reprocess was rejected as an unknown source.

* refactor(artwork): own the kind list and the chain predicate in the package

Export RecheckKinds and add WalksPriorityChain so the CLI stops keeping its
own copies of both, and unexport externalCandidate, which nothing outside the
package consumes.

* refactor(cli): drop the artwork command's duplicated state and formatting

Reuse artwork.RecheckKinds and artwork.WalksPriorityChain, extract
newTabWriter and externalEstimate, fold reprocessSelectsAll into
selectedKinds, and derive the queue total and the walks-chain flag instead of
carrying them in the report structs.

* test(persistence): drop two artwork-queue specs that cannot fail

One seeded hash and source together and then asserted the two counts agree,
so its setup guaranteed the result; the other repeated the count-does-not-
enqueue property already covered by the CountBySource spec.

* refactor(artwork): rename Resolver to TracingResolver for clarity

* fix(cli): count playlists in the artwork reprocess external estimate

The estimate used WalksPriorityChain, which is true only for artist and album,
so a playlist-only reprocess reported "External lookups: none" and the
confirmation prompt dropped the external-cost warning. Playlists do reach the
network: through the m3u ExternalImageURL fetch when EnableM3UExternalAlbumArt
is on, and — verified by test — through the generated grid, whose tiles resolve
album art via the full album priority chain.

Adds artwork.MayFetchExternal, a config-aware predicate for "can this kind's
resolver reach the network", and uses it for the estimate. WalksPriorityChain
keeps its separate job of deciding whether explain prints a chain block.

* fix(cli): estimate artwork reprocess external lookups per agent, not per item

The reprocess prompt billed one external lookup per externally-capable item.
fetchArtistImage/fetchAlbumImage try every enabled image agent and stop early
only on a hit, and resolvePlaylist can fetch the m3u image and then resolve up
to four sampled albums for the grid, each walking the album agents again. The
number the operator confirmed could understate real provider traffic several
fold, in the prompt whose whole job is to stop a provider flood.

ExternalLookupsPerItem now multiplies by the visible image-agent count and adds
the playlist grid factor. It stays a floor: the CLI never calls Manager.Start(),
so the plugin registry is empty and plugin-provided agents are dropped by
getEnabledAgentNames. On an install with 5 agents of which 3 are plugins the
count is well under the truth, so the wording is now "at least N" rather than
"up to N" — a zero visible count still bills one lookup for the same reason.

Fixing the plugin visibility is out of scope: Manager.Start() needs a Subsonic
router and writes to the DB via syncPlugins, breaking this command group's
read-only guarantee.

* fix(cli): state the artwork reprocess estimate as an estimate, not a bound

Neither bound is true. A ceiling is false because plugin agents are invisible to
a CLI that never starts the plugin manager, and a floor is false because a local
hit ends the walk before any agent is asked and a hit on the first agent skips
the rest. "at least N" traded one wrong claim for another.

The line now names its blind spots instead:

  External lookups: ~340 estimated (plugin agents not counted; local hits may
  need fewer).

The same line is reused in the confirmation prompt, and the zero case still
reads "External lookups: none." with the prompt dropping the clause entirely.
The count itself is unchanged.

* fix(cli): account for every configured agent in artwork explain

The Agents: line printed the raw config while the Chain only showed the agents the CLI could
construct, with nothing explaining the gap: plugin agents are never registered in a CLI that does
not start the plugin manager, and a built-in without credentials returns nil. Three of five agents
could vanish, including ones ranked above the one shown.

Also treat a live external error before the winning hit like the already-handled would-try case:
the resolver serves such a hit provisionally and retries later, so the verdict is indeterminate.

The Result line is still not qualified when an unavailable agent might have won; that needs agent
ranking, and is left to the follow-up that makes the CLI load plugin agents for real.

* fix(cli): do not call an external artwork win indeterminate

explainResult qualified the verdict whenever an external OutcomeError
appeared before the winning hit. When a later external agent returns an
image, fetchArtistImage/fetchAlbumImage discard the earlier error, so
extError is false: the worker settles the item and schedules no retry.
Telling the operator it may resolve differently on a retry was wrong.

The warning is only correct when a lower-priority local source won while
an external error was recorded, which is the case that carries extError.

* fix(cli): accept --source absent when nothing is currently absent

validateSources checks the requested sources against the ones item_artwork
actually uses, to catch a typo. The reserved empty source (spelled 'absent' on
the CLI) is a valid filter even when it matches nothing, so a scheduled
'artwork reprocess --source absent --yes' stopped working the moment the
library finished resolving. Treat it as intrinsically valid and let the
existing zero-match path report it.

* feat(artwork): explain disc and media file artwork from the CLI

`artwork explain` rejected `dc` and `mf` because it validated against RecheckKinds,
the list of kinds the backfill revisits. Those are different questions: a kind with no
recheck path still has artwork someone can report as wrong.

Disc artwork now walks DiscArtPriority under a trace, so explain reports which entry won
and why the others lost, including entries that map to no source at all (external is
unsupported, a disc with no subtitle, an album folder with no images). Media file artwork
traces its single embedded candidate, separating "EnableMediaFileCoverArt is off" from
"the track has no embedded art" — stored state cannot tell those apart.

Each command now validates against the kinds it can actually serve: explain takes all six,
refresh takes artwork.RefreshableKinds (which nativeapi now shares instead of keeping its
own copy), reprocess still takes RecheckKinds. Disc artwork stays out of refresh: the
worker cannot resolve it, so the queue row would be rejected on every drain.

WalksPriorityChain becomes Explainable, and ResolveArtist/ResolveAlbum collapse into
Resolve(kind, id).

* refactor(artwork): one disc-artwork walk for serving and explain

resolveDisc duplicated the loop selectImageReader already ran: try each source in
priority order, take the first that yields an image. The serving path and the CLI
diverged on two details as a result — only selectImageReader checked ctx between
candidates and logged each attempt.

Both now call discArtworkReader.selectImage, which takes the chainState the CLI already
uses for the other kinds. The serving path passes an untraced one, whose nil trace makes
recording a no-op. selectImageReader had no other caller and is gone.

The disc tests move from fromDiscArtPriority to discCandidates, so they assert the skip
reason for an entry that maps to no source rather than that it silently vanished, and
cancellation mid-walk is now covered.

* fix(artwork): reject a nil reader in the resize cache instead of panicking

resizedItem.Reader closes what open() hands back, so an open() that reports "no image"
as (nil, nil) rather than an error takes the request down with a nil-pointer panic. Every
caller returns an error today, and no test covered it: the resolution e2e harness stubs
the resize reader out entirely, so no e2e path reaches this code at all.

Guard it and cover Reader directly.

* refactor(artwork): move the keeps-state fact into core, drop a redundant guard

keepsArtworkState lived in package cmd and re-derived by hand what RefreshableKinds
already encodes: the same five-of-six kinds. It is now artwork.KeepsState, beside the
list, with a test pinning the two together — nothing else stopped them drifting, and a
drift would have explain report stored state for a kind that keeps none.

serveDisc's closure also hand-rolled a nil-reader error that both consumers of open()
now produce themselves: serveSource for a full-size request, resizedItem.Reader for a
resized one.

* fix(artwork): route disc candidates through the shared resolvers

openCandidate ran its own source loop and threw the error away, so a disc track that
exists but cannot be parsed traced as "miss" — indistinguishable from a track with no
embedded art. fromTag and fromFFmpegTag already report that case as errSourceUnreadable;
only this loop was discarding it. Telling those two apart is what the trace is for.

Candidates now carry a resolve func instead of raw sources: embedded goes to
resolveEmbedded, and the folder-backed entries to resolveFolderSource, extracted from
resolveFolderFile so both callers classify an unopenable file the same way. openCandidate
and its absolute-path special case go away with it.

Disc's own fromExternalFile and fromDiscSubtitle still swallow open errors, so folder
candidates cannot report unreadable yet; that is a change to their error contracts.

* fix(artwork): report an unreadable local candidate as indeterminate

processor.acquire treats resolution.localError exactly as it treats extError: a fault is
not a definitive "no image", so it retries instead of settling absent. explainResult
qualified only the external case, so a chain that ended on an unreadable local candidate
printed "not resolved" — the one verdict that says the walk was conclusive.

The qualification belongs only to the unresolved branch. chainState.try stamps extErr onto
a hit and deliberately drops localErr, so an unreadable step followed by a hit is settled
as found and must not carry a warning; a test pins that.

Found by Codex on 5f65d7cfa.
---
 cmd/artwork.go                               | 778 ++++++++++++++++
 cmd/artwork_test.go                          | 899 +++++++++++++++++++
 cmd/plugin.go                                |   3 +-
 cmd/utils.go                                 |   7 +
 cmd/wire_gen.go                              |  12 +
 cmd/wire_injectors.go                        |   7 +
 core/artwork/agent_images.go                 |  17 +-
 core/artwork/agent_images_test.go            |  36 +
 core/artwork/artwork.go                      |  60 +-
 core/artwork/disc.go                         |  72 +-
 core/artwork/disc_test.go                    | 179 ++--
 core/artwork/housekeeping.go                 |  55 +-
 core/artwork/housekeeping_test.go            |  55 +-
 core/artwork/image_cache.go                  |   4 +
 core/artwork/image_cache_test.go             |  41 +
 core/artwork/resolve.go                      | 177 +++-
 core/artwork/resolve_test.go                 | 129 +++
 core/artwork/sources.go                      |  17 -
 core/artwork/trace.go                        |  99 ++
 core/artwork/trace_test.go                   | 628 +++++++++++++
 core/artwork/worker.go                       |   2 +-
 core/artwork/worker_test.go                  |   2 +-
 model/artwork.go                             |  26 +
 persistence/artwork_queue_repository.go      |  72 +-
 persistence/artwork_queue_repository_test.go | 138 +++
 server/nativeapi/artwork.go                  |  10 +-
 tests/mock_artwork_queue_repo.go             | 116 +++
 27 files changed, 3469 insertions(+), 172 deletions(-)
 create mode 100644 cmd/artwork.go
 create mode 100644 cmd/artwork_test.go
 create mode 100644 core/artwork/image_cache_test.go
 create mode 100644 core/artwork/trace.go
 create mode 100644 core/artwork/trace_test.go

diff --git a/cmd/artwork.go b/cmd/artwork.go
new file mode 100644
index 000000000..2b6a50164
--- /dev/null
+++ b/cmd/artwork.go
@@ -0,0 +1,778 @@
+package cmd
+
+import (
+	"cmp"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/db"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/spf13/cobra"
+)
+
+var explainLive bool
+
+var (
+	reprocessKinds   []string
+	reprocessSources []string
+	reprocessAll     bool
+	reprocessDryRun  bool
+	reprocessYes     bool
+)
+
+func init() {
+	artworkExplainCmd.Flags().BoolVar(&explainLive, "live", false,
+		"perform real external lookups instead of reporting what would be tried")
+	artworkReprocessCmd.Flags().StringSliceVar(&reprocessKinds, "kind", nil,
+		"kinds to reprocess ("+kindPrefixes(artwork.RecheckKinds)+"); repeatable")
+	artworkReprocessCmd.Flags().StringSliceVar(&reprocessSources, "source", nil,
+		"only items currently resolved from these sources (e.g. folder, external:deezer, absent)")
+	artworkReprocessCmd.Flags().BoolVar(&reprocessAll, "all", false, "reprocess every kind")
+	artworkReprocessCmd.Flags().BoolVar(&reprocessDryRun, "dry-run", false,
+		"report what would be queued and exit without queueing")
+	artworkReprocessCmd.Flags().BoolVarP(&reprocessYes, "yes", "y", false, "skip the confirmation prompt")
+	artworkCmd.AddCommand(artworkExplainCmd)
+	artworkCmd.AddCommand(artworkRefreshCmd)
+	artworkCmd.AddCommand(artworkReprocessCmd)
+	artworkCmd.AddCommand(artworkStatusCmd)
+	rootCmd.AddCommand(artworkCmd)
+}
+
+var artworkCmd = &cobra.Command{
+	Use:   "artwork",
+	Short: "Inspect and re-resolve artwork",
+}
+
+var artworkExplainCmd = &cobra.Command{
+	Use:   "explain <kind> <id>",
+	Short: "Explain why an item's artwork resolved the way it did",
+	Long: "Explain why an item's artwork resolved the way it did.\n\n" +
+		"<kind> is one of: " + kindPrefixes(explainKinds) + ".\n" +
+		"A disc artwork id is the album id and the disc number, joined by a colon: <albumID>:2",
+	Args: cobra.ExactArgs(2),
+	Run: func(cmd *cobra.Command, args []string) {
+		kind, err := parseArtworkKind(args[0], explainKinds)
+		if err != nil {
+			log.Fatal(cmd.Context(), err)
+		}
+		runExplain(cmd.Context(), kind, args[1])
+	},
+}
+
+var artworkRefreshCmd = &cobra.Command{
+	Use:   "refresh <kind> <id>...",
+	Short: "Clear an item's artwork state and re-resolve it",
+	Args:  cobra.MinimumNArgs(2),
+	Run: func(cmd *cobra.Command, args []string) {
+		kind, err := parseArtworkKind(args[0], artwork.RefreshableKinds)
+		if err != nil {
+			log.Fatal(cmd.Context(), err)
+		}
+		runRefresh(cmd.Context(), kind, args[1:])
+	},
+}
+
+var artworkReprocessCmd = &cobra.Command{
+	Use:   "reprocess",
+	Short: "Re-enqueue artwork in bulk, by kind and/or by the source it currently resolves from",
+	Args:  cobra.NoArgs,
+	Run: func(cmd *cobra.Command, args []string) {
+		runReprocess(cmd.Context())
+	},
+}
+
+var artworkStatusCmd = &cobra.Command{
+	Use:   "status",
+	Short: "Report the artwork queue, where artwork resolves from, and the backfill state",
+	Args:  cobra.NoArgs,
+	Run: func(cmd *cobra.Command, args []string) {
+		runStatus(cmd.Context())
+	},
+}
+
+func runStatus(ctx context.Context) {
+	defer db.Init(ctx)()
+	ds, ctx := getAdminContext(ctx)
+
+	rep, err := collectStatus(ctx, ds)
+	if err != nil {
+		log.Fatal(ctx, err)
+	}
+	fmt.Print(formatStatus(rep))
+}
+
+type sourceCount struct {
+	kind   model.Kind
+	source string
+	count  int64
+}
+
+type absentCount struct {
+	kind model.Kind
+	model.ArtworkAbsentStat
+}
+
+type statusReport struct {
+	queue   []model.ArtworkQueueStat
+	sources []sourceCount
+	absent  []absentCount
+	inputs  []artwork.FingerprintInput
+	stored  string
+	current string
+}
+
+func (r statusReport) queueTotal() int64 {
+	var n int64
+	for _, s := range r.queue {
+		n += s.Count
+	}
+	return n
+}
+
+func (r statusReport) backfillQueued() int64 {
+	var n int64
+	for _, s := range r.queue {
+		if s.Priority == model.ArtworkPriorityBackfill {
+			n += s.Count
+		}
+	}
+	return n
+}
+
+func collectStatus(ctx context.Context, ds model.DataStore) (statusReport, error) {
+	q := ds.ArtworkQueue(ctx)
+	var rep statusReport
+	var err error
+	if rep.queue, err = q.CountByKindAndPriority(); err != nil {
+		return rep, fmt.Errorf("breaking the artwork queue down by kind: %w", err)
+	}
+
+	cutoff := time.Now().Add(-artwork.StaleAbsentAge)
+	for _, k := range artwork.RecheckKinds {
+		sources, err := q.SourcesInUse(k)
+		if err != nil {
+			return rep, fmt.Errorf("listing the sources in use by %s artwork: %w", k, err)
+		}
+		slices.Sort(sources)
+		for _, s := range sources {
+			n, err := q.CountBySource(k, []string{s})
+			if err != nil {
+				return rep, fmt.Errorf("counting %s artwork resolved from %s: %w", k, displaySource(s), err)
+			}
+			rep.sources = append(rep.sources, sourceCount{kind: k, source: s, count: n})
+		}
+		stat, err := q.CountAbsent(k, cutoff)
+		if err != nil {
+			return rep, fmt.Errorf("counting absent %s artwork: %w", k, err)
+		}
+		rep.absent = append(rep.absent, absentCount{kind: k, ArtworkAbsentStat: stat})
+	}
+
+	rep.current, rep.inputs = artwork.ConfigFingerprint(), artwork.FingerprintInputs()
+	if rep.stored, err = ds.Property(ctx).DefaultGet(consts.ArtConfFingerprintPropertyKey, ""); err != nil {
+		return rep, fmt.Errorf("reading the stored artwork fingerprint: %w", err)
+	}
+	return rep, nil
+}
+
+func formatStatus(rep statusReport) string {
+	var sb strings.Builder
+	w := newTabWriter(&sb)
+
+	fmt.Fprintln(w, "Queue")
+	if len(rep.queue) == 0 {
+		fmt.Fprintln(w, "  (empty)")
+	} else {
+		fmt.Fprintln(w, "  KIND\tPRIORITY\tITEMS")
+		for _, s := range rep.queue {
+			fmt.Fprintf(w, "  %s\t%s\t%d\n", kindName(s.ItemKind), priorityName(s.Priority), s.Count)
+		}
+		fmt.Fprintf(w, "  TOTAL\t\t%d\n", rep.queueTotal())
+	}
+
+	fmt.Fprintln(w, "\nSources")
+	fmt.Fprintln(w, "  KIND\tSOURCE\tITEMS")
+	for _, s := range rep.sources {
+		fmt.Fprintf(w, "  %s\t%s\t%d\n", s.kind, displaySource(s.source), s.count)
+	}
+
+	fmt.Fprintln(w, "\nAbsent (resolved, no image found)")
+	fmt.Fprintln(w, "  KIND\tABSENT\tDUE FOR RECHECK")
+	for _, a := range rep.absent {
+		fmt.Fprintf(w, "  %s\t%d\t%d\n", a.kind, a.Total, a.Stale)
+	}
+	fmt.Fprintf(w, "  (rechecked once the last attempt is older than %gh)\n", artwork.StaleAbsentAge.Hours())
+
+	fmt.Fprintln(w, "\nBackfill")
+	fmt.Fprintf(w, "  State:\t%s\n", backfillState(rep))
+	fmt.Fprintf(w, "  Stored fingerprint:\t%s\n", cmp.Or(rep.stored, "(none)"))
+	fmt.Fprintf(w, "  Current fingerprint:\t%s\n", rep.current)
+	if len(rep.inputs) > 0 {
+		fmt.Fprintln(w, "  Fingerprint inputs (changing any of these re-resolves the whole library):")
+		for _, in := range rep.inputs {
+			fmt.Fprintf(w, "    %s:\t%s\n", in.Name, in.Value)
+		}
+	}
+
+	w.Flush()
+	return sb.String()
+}
+
+// backfillState leads with the queued backlog: by the time anyone runs this, backfill has usually
+// already stored the new fingerprint, and "up to date" would bury the flood it is still working through.
+func backfillState(rep statusReport) string {
+	pending := "fingerprint changed — every artist, album, playlist and radio will be re-enqueued on the next startup"
+	if n := rep.backfillQueued(); n > 0 {
+		if rep.stored != rep.current {
+			return fmt.Sprintf("backfill running: %d items queued, and %s", n, pending)
+		}
+		return fmt.Sprintf("backfill running: %d items queued (fingerprint up to date)", n)
+	}
+	if rep.stored != rep.current {
+		return pending
+	}
+	return "up to date"
+}
+
+func kindName(prefix string) string {
+	if k, ok := model.ParseKind(prefix); ok {
+		return k.String()
+	}
+	return prefix
+}
+
+func priorityName(p int) string {
+	switch p {
+	case model.ArtworkPriorityRecheck:
+		return "recheck"
+	case model.ArtworkPriorityBackfill:
+		return "backfill"
+	case model.ArtworkPriorityScan:
+		return "scan"
+	case model.ArtworkPriorityBump:
+		return "bump"
+	}
+	return strconv.Itoa(p)
+}
+
+func runReprocess(ctx context.Context) {
+	kinds, err := selectedKinds(reprocessKinds, reprocessSources, reprocessAll)
+	if err != nil {
+		log.Fatal(ctx, err)
+	}
+
+	defer db.Init(ctx)()
+	ds, ctx := getAdminContext(ctx)
+
+	if err := reprocessArtwork(ctx, ds, kinds, repositorySources(reprocessSources), imageAgentCount(ds),
+		reprocessDryRun, reprocessConfirm(reprocessYes, os.Stdin), os.Stdout); err != nil {
+		log.Fatal(ctx, err)
+	}
+}
+
+func selectedKinds(kinds, sources []string, all bool) ([]model.Kind, error) {
+	// A source filter on its own is already a complete selection, so it does not also need a kind.
+	if all || (len(kinds) == 0 && len(sources) > 0) {
+		return artwork.RecheckKinds, nil
+	}
+	if len(kinds) == 0 {
+		return nil, fmt.Errorf("no selector given: pass --kind, --source or --all")
+	}
+	out := make([]model.Kind, 0, len(kinds))
+	for _, k := range kinds {
+		kind, err := parseArtworkKind(k, artwork.RecheckKinds)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, kind)
+	}
+	// A repeated kind would be counted twice, overstating the cost the operator confirms.
+	return slice.Unique(out), nil
+}
+
+// absentSource is how the stored empty source — resolved, no image — is spelled on the CLI.
+const absentSource = "absent"
+
+func repositorySources(sources []string) []string {
+	return slice.Map(sources, func(s string) string {
+		if s == absentSource {
+			return ""
+		}
+		return s
+	})
+}
+
+func displaySource(s string) string { return cmp.Or(s, absentSource) }
+
+type confirmFunc func(out io.Writer, total, external int64) bool
+
+func reprocessConfirm(yes bool, in io.Reader) confirmFunc {
+	if yes {
+		return func(io.Writer, int64, int64) bool { return true }
+	}
+	return promptConfirm(in)
+}
+
+// externalEstimate claims no bound: a local hit ends the walk before any agent is asked, and plugin
+// agents are unregistered in a CLI that never starts the plugin manager.
+func externalEstimate(n int64) string {
+	if n == 0 {
+		return "none"
+	}
+	return fmt.Sprintf("~%d estimated (plugin agents not counted; local hits may need fewer)", n)
+}
+
+func externalLookupLine(n int64) string {
+	return fmt.Sprintf("External lookups: %s.", externalEstimate(n))
+}
+
+// imageAgentCount counts only the built-in image agents, for the same reason.
+func imageAgentCount(ds model.DataStore) artwork.ImageAgentCount {
+	ag := agents.GetAgents(ds, getPluginManager())
+	return artwork.ImageAgentCount{Artist: len(ag.ArtistImageAgents()), Album: len(ag.AlbumImageAgents())}
+}
+
+func promptConfirm(in io.Reader) confirmFunc {
+	return func(out io.Writer, total, external int64) bool {
+		var cost string
+		if external > 0 {
+			cost = fmt.Sprintf(" %s", externalLookupLine(external))
+		}
+		fmt.Fprintf(out, "\nThis will re-resolve %d items.%s Continue? [y/N] ", total, cost)
+		var answer string
+		if _, err := fmt.Fscanln(in, &answer); err != nil {
+			return false
+		}
+		answer = strings.ToLower(strings.TrimSpace(answer))
+		return answer == "y" || answer == "yes"
+	}
+}
+
+// validateSources rejects a typo'd source: matching nothing silently reads as "nothing to do" when
+// it means the filter was wrong. Checked table-wide, so a filter is never a typo for one --kind only.
+func validateSources(q model.ArtworkQueueRepository, sources []string) error {
+	if len(sources) == 0 {
+		return nil
+	}
+	var inUse []string
+	for _, k := range artwork.RecheckKinds {
+		found, err := q.SourcesInUse(k)
+		if err != nil {
+			return fmt.Errorf("listing the sources in use by %s artwork: %w", k, err)
+		}
+		inUse = slice.Unique(append(inUse, found...))
+	}
+	var unknown []string
+	for _, s := range sources {
+		if s != "" && !slices.Contains(inUse, s) { // the reserved absent source is valid even when nothing is absent
+			unknown = append(unknown, displaySource(s))
+		}
+	}
+	if len(unknown) == 0 {
+		return nil
+	}
+	valid := slice.Map(inUse, displaySource)
+	slices.Sort(valid)
+	return fmt.Errorf("no artwork resolves from %s; sources in use: %s",
+		strings.Join(unknown, ", "), cmp.Or(strings.Join(valid, ", "), "(none)"))
+}
+
+// reprocessArtwork previews from CountBySource — rows matched — then reports what EnqueueBySource
+// actually inserted; the two differ because an already-queued row is left untouched.
+func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kind, sources []string,
+	imageAgents artwork.ImageAgentCount, dryRun bool, confirm confirmFunc, out io.Writer) error {
+	q := ds.ArtworkQueue(ctx)
+	if err := validateSources(q, sources); err != nil {
+		return err
+	}
+
+	matched := make([]int64, len(kinds))
+	var total, external int64
+	for i, k := range kinds {
+		n, err := q.CountBySource(k, sources)
+		if err != nil {
+			return fmt.Errorf("counting %s artwork: %w", k, err)
+		}
+		matched[i] = n
+		total += n
+		external += n * artwork.ExternalLookupsPerItem(k, imageAgents)
+	}
+	printReprocessPreview(out, kinds, matched, total, external, sources)
+
+	switch {
+	case dryRun:
+		fmt.Fprintln(out, "\nDry run: nothing was queued.")
+		return nil
+	case total == 0:
+		fmt.Fprintln(out, "Nothing was queued.")
+		return nil
+	case !confirm(out, total, external):
+		fmt.Fprintln(out, "Aborted: nothing was queued.")
+		return nil
+	}
+
+	var queued int64
+	for i, k := range kinds {
+		if matched[i] == 0 {
+			continue
+		}
+		n, err := q.EnqueueBySource(k, sources, model.ArtworkPriorityRecheck)
+		if err != nil {
+			return fmt.Errorf("queueing %s artwork: %w", k, err)
+		}
+		queued += n
+		fmt.Fprintf(out, "%s: %d queued\n", k, n)
+	}
+	fmt.Fprintf(out, "Queued %d of %d matched items.\n", queued, total)
+	if skipped := total - queued; skipped > 0 {
+		fmt.Fprintf(out, "Already queued, left unchanged: %d (priority and retry backoff untouched).\n", skipped)
+	}
+	return nil
+}
+
+// printReprocessPreview also states the external estimate, which --dry-run must show because it
+// skips the prompt that would otherwise carry it.
+func printReprocessPreview(out io.Writer, kinds []model.Kind, matched []int64, total, external int64, sources []string) {
+	w := newTabWriter(out)
+	shown := slice.Map(sources, displaySource)
+	fmt.Fprintf(w, "Sources:\t%s\n\n", cmp.Or(strings.Join(shown, ", "), "(any)"))
+	fmt.Fprintln(w, "KIND\tMATCHED")
+	for i, k := range kinds {
+		fmt.Fprintf(w, "%s\t%d\n", k, matched[i])
+	}
+	fmt.Fprintf(w, "TOTAL\t%d\n", total)
+	w.Flush()
+
+	fmt.Fprintf(out, "\n%s\n", externalLookupLine(external))
+	if total == 0 {
+		fmt.Fprintln(out, "\nNothing matches this selection.")
+	}
+}
+
+func runRefresh(ctx context.Context, kind model.Kind, ids []string) {
+	defer db.Init(ctx)()
+	ds, ctx := getAdminContext(ctx)
+
+	if failed := refreshItems(ctx, ds, kind, ids, os.Stdout); failed > 0 {
+		log.Fatal(ctx, "Failed to refresh artwork", "kind", kind, "failed", failed, "total", len(ids))
+	}
+}
+
+// refreshItems keeps going after a failure — the ids are independent — and returns how many failed.
+func refreshItems(ctx context.Context, ds model.DataStore, kind model.Kind, ids []string, out io.Writer) int {
+	var failed int
+	for _, id := range ids {
+		// artwork.Refresh would happily queue an id that does not exist, orphaning a queue row.
+		if _, err := artworkItemName(ctx, ds, kind, id); err != nil {
+			log.Error(ctx, "Item not found", "kind", kind, "id", id, err)
+			failed++
+			continue
+		}
+		if err := artwork.Refresh(ctx, ds, kind, id); err != nil {
+			log.Error(ctx, "Error refreshing artwork", "kind", kind, "id", id, err)
+			failed++
+			continue
+		}
+		fmt.Fprintf(out, "%s/%s: queued\n", kind.Prefix(), id)
+	}
+	return failed
+}
+
+// explainKinds is every kind explain accepts: it reports stored state and config too, so a kind
+// with no chain to walk still has something to answer with.
+var explainKinds = []model.Kind{
+	model.KindArtistArtwork, model.KindAlbumArtwork, model.KindDiscArtwork,
+	model.KindMediaFileArtwork, model.KindPlaylistArtwork, model.KindRadioArtwork,
+}
+
+func kindPrefixes(kinds []model.Kind) string {
+	return strings.Join(slice.Map(kinds, func(k model.Kind) string { return k.Prefix() }), ", ")
+}
+
+func parseArtworkKind(s string, valid []model.Kind) (model.Kind, error) {
+	kind, ok := model.ParseKind(s)
+	if ok && slices.Contains(valid, kind) {
+		return kind, nil
+	}
+	return kind, fmt.Errorf("invalid kind %q, expected one of: %s", s, kindPrefixes(valid))
+}
+
+// explainAgents accounts for every configured agent: one the CLI cannot construct (a plugin, or a
+// built-in missing its credentials) never reaches the Chain, so the raw list alone overstates it.
+func explainAgents(configured string, available []string) string {
+	if strings.TrimSpace(configured) == "" {
+		return "(none)"
+	}
+	var unavailable bool
+	names := slice.Map(strings.Split(configured, ","), func(name string) string {
+		name = strings.TrimSpace(name)
+		if slices.Contains(available, name) {
+			return name
+		}
+		unavailable = true
+		return name + "*"
+	})
+	line := strings.Join(names, ", ")
+	if unavailable {
+		line += "  (* not available to the CLI)"
+	}
+	return line
+}
+
+// availableImageAgents names the agents that can actually supply an image for kind.
+func availableImageAgents(ds model.DataStore, kind model.Kind) []string {
+	ag := agents.GetAgents(ds, getPluginManager())
+	if kind == model.KindArtistArtwork {
+		return slice.Map(ag.ArtistImageAgents(), func(a agents.ArtistImageAgent) string { return a.Name })
+	}
+	return slice.Map(ag.AlbumImageAgents(), func(a agents.AlbumImageAgent) string { return a.Name })
+}
+
+// explainResult states the verdict of the walk. A skipped or failed external tier, or a local
+// candidate that would not open, leaves the outcome unknown: nothing observed that there is no artwork.
+func explainResult(source string, steps []artwork.TraceStep) string {
+	if source != "" {
+		for _, s := range steps {
+			if s.Outcome == artwork.OutcomeHit {
+				break
+			}
+			if s.Outcome == artwork.OutcomeWouldTry {
+				return "resolved from " + source +
+					" (offline: a higher-priority external candidate was not tried; re-run with --live)"
+			}
+			// An external winner discards the earlier error, so the resolver settles it with no retry.
+			if s.Outcome == artwork.OutcomeError && strings.HasPrefix(s.Candidate, artwork.ExternalPrefix) &&
+				!strings.HasPrefix(source, artwork.ExternalPrefix) {
+				return "resolved from " + source +
+					" (indeterminate: a higher-priority external lookup failed; this may resolve differently on a retry)"
+			}
+		}
+		return "resolved from " + source
+	}
+	for _, s := range steps {
+		switch {
+		case s.Outcome == artwork.OutcomeWouldTry:
+			return "indeterminate (external agents not called; re-run with --live)"
+		case s.Outcome == artwork.OutcomeError && strings.HasPrefix(s.Candidate, artwork.ExternalPrefix):
+			return "indeterminate (an external lookup failed; the item may resolve on a later attempt)"
+		// The worker treats an unreadable local candidate exactly as it treats a failed external one:
+		// it retries instead of settling absent, so the verdict must not read as a clean miss.
+		case s.Outcome == artwork.OutcomeUnreadable:
+			return "indeterminate (a candidate exists but could not be read; the worker retries rather than settling absent)"
+		}
+	}
+	return "not resolved"
+}
+
+// explainConfig names the setting that decides where a kind's artwork comes from, and its value.
+func explainConfig(kind model.Kind) (name, value string) {
+	switch kind {
+	case model.KindArtistArtwork:
+		return "ArtistArtPriority", conf.Server.ArtistArtPriority
+	case model.KindAlbumArtwork:
+		return "CoverArtPriority", conf.Server.CoverArtPriority
+	case model.KindDiscArtwork:
+		return "DiscArtPriority", conf.Server.DiscArtPriority
+	case model.KindMediaFileArtwork:
+		return "EnableMediaFileCoverArt", strconv.FormatBool(conf.Server.EnableMediaFileCoverArt)
+	}
+	return "", ""
+}
+
+type explainReport struct {
+	kind       model.Kind
+	id         string
+	name       string
+	stored     *model.ItemArtwork
+	queued     *model.ArtworkQueueItem
+	agents     string
+	steps      []artwork.TraceStep
+	source     string
+	resolveErr error
+}
+
+func formatExplain(rep explainReport) string {
+	var sb strings.Builder
+	w := newTabWriter(&sb)
+	explainable := artwork.Explainable(rep.kind)
+	stateful := artwork.KeepsState(rep.kind)
+
+	fmt.Fprintln(w, "Item")
+	fmt.Fprintf(w, "  Kind:\t%s (%s)\n", rep.kind, rep.kind.Prefix())
+	fmt.Fprintf(w, "  ID:\t%s\n", rep.id)
+	fmt.Fprintf(w, "  Name:\t%s\n", rep.name)
+
+	fmt.Fprintln(w, "\nStored")
+	switch {
+	case !stateful:
+		fmt.Fprintf(w, "  (%s artwork is resolved on every request and never recorded)\n", rep.kind)
+	case rep.stored == nil:
+		fmt.Fprintln(w, "  (no artwork state recorded)")
+	default:
+		fmt.Fprintf(w, "  Source:\t%s\n", displaySource(rep.stored.Source))
+		fmt.Fprintf(w, "  Hash:\t%s\n", cmp.Or(rep.stored.Hash, "(absent)"))
+		if rep.stored.SourcePath != "" {
+			fmt.Fprintf(w, "  Source path:\t%s\n", rep.stored.SourcePath)
+		}
+		fmt.Fprintf(w, "  Attempted at:\t%s\n", formatTime(rep.stored.AttemptedAt))
+	}
+
+	fmt.Fprintln(w, "\nQueue")
+	switch {
+	case !stateful:
+		fmt.Fprintln(w, "  (never queued)")
+	case rep.queued == nil:
+		fmt.Fprintln(w, "  (not queued)")
+	default:
+		fmt.Fprintf(w, "  Priority:\t%s (%d)\n", priorityName(rep.queued.Priority), rep.queued.Priority)
+		fmt.Fprintf(w, "  Attempts:\t%d\n", rep.queued.Attempts)
+		fmt.Fprintf(w, "  Retry at:\t%s\n", formatTime(rep.queued.RetryAt))
+	}
+
+	fmt.Fprintln(w, "\nConfig")
+	if setting, value := explainConfig(rep.kind); setting == "" {
+		fmt.Fprintln(w, "  (no artwork source configuration applies)")
+	} else {
+		fmt.Fprintf(w, "  %s:\t%s\n", setting, value)
+		if rep.agents != "" {
+			fmt.Fprintf(w, "  Agents:\t%s\n", rep.agents)
+		}
+	}
+
+	fmt.Fprintln(w, "\nChain")
+	if !explainable {
+		fmt.Fprintf(w, "  (%s artwork does not walk a priority chain)\n", rep.kind)
+	} else {
+		fmt.Fprintln(w, "  CANDIDATE\tOUTCOME\tDETAIL")
+		for _, s := range rep.steps {
+			// A row with an empty last cell would end tabwriter's column block, breaking alignment.
+			fmt.Fprintf(w, "  %s\t%s\t%s\n", s.Candidate, s.Outcome, cmp.Or(s.Detail, "-"))
+		}
+	}
+
+	fmt.Fprintln(w, "\nResult")
+	switch {
+	case rep.resolveErr != nil:
+		fmt.Fprintf(w, "  resolution failed: %s\n", rep.resolveErr)
+	case !explainable:
+		fmt.Fprintln(w, "  not evaluated (no chain was walked; see Stored above)")
+	default:
+		fmt.Fprintf(w, "  %s\n", explainResult(rep.source, rep.steps))
+	}
+
+	w.Flush()
+	return sb.String()
+}
+
+func formatTime(t time.Time) string {
+	if t.IsZero() {
+		return "-"
+	}
+	return t.Format(time.RFC3339)
+}
+
+func runExplain(ctx context.Context, kind model.Kind, id string) {
+	defer db.Init(ctx)()
+	ds, ctx := getAdminContext(ctx)
+
+	name, err := artworkItemName(ctx, ds, kind, id)
+	if err != nil {
+		log.Fatal(ctx, "Item not found", "kind", kind, "id", id, err)
+	}
+	rep := explainReport{kind: kind, id: id, name: name}
+	if artwork.KeepsState(kind) {
+		rep.stored, err = ds.Artwork(ctx).GetItemArtwork(kind, id, model.ImageTypePrimary)
+		if err != nil && !errors.Is(err, model.ErrNotFound) {
+			log.Fatal(ctx, "Failed to read artwork state", "kind", kind, "id", id, err)
+		}
+		rep.queued, err = ds.ArtworkQueue(ctx).Get(kind, id, model.ImageTypePrimary)
+		if err != nil && !errors.Is(err, model.ErrNotFound) {
+			log.Fatal(ctx, "Failed to read the artwork queue", "kind", kind, "id", id, err)
+		}
+	}
+
+	if artwork.Explainable(kind) {
+		if kind == model.KindArtistArtwork || kind == model.KindAlbumArtwork {
+			rep.agents = explainAgents(conf.Server.Agents, availableImageAgents(ds, kind))
+		}
+		trace := &artwork.ChainTrace{}
+		rep.source, rep.resolveErr = CreateArtworkResolver(trace, explainLive).Resolve(ctx, kind, id)
+		rep.steps = trace.Steps()
+	}
+
+	fmt.Print(formatExplain(rep))
+	// The steps taken before a failed walk are the diagnosis, so report them before exiting.
+	if rep.resolveErr != nil {
+		log.Fatal(ctx, "Failed to resolve artwork", "kind", kind, "id", id, rep.resolveErr)
+	}
+}
+
+// artworkItemName looks the entity up under its own kind, so a mismatched kind/id pair is
+// reported as not found instead of silently explaining another entity's artwork.
+func artworkItemName(ctx context.Context, ds model.DataStore, kind model.Kind, id string) (string, error) {
+	switch kind {
+	case model.KindArtistArtwork:
+		ar, err := ds.Artist(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return ar.Name, nil
+	case model.KindAlbumArtwork:
+		al, err := ds.Album(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return al.Name, nil
+	case model.KindPlaylistArtwork:
+		pls, err := ds.Playlist(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return pls.Name, nil
+	case model.KindRadioArtwork:
+		rd, err := ds.Radio(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return rd.Name, nil
+	case model.KindMediaFileArtwork:
+		mf, err := ds.MediaFile(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return mf.Title, nil
+	case model.KindDiscArtwork:
+		return discArtworkName(ctx, ds, id)
+	}
+	return "", fmt.Errorf("unsupported kind %q", kind.Prefix())
+}
+
+func discArtworkName(ctx context.Context, ds model.DataStore, id string) (string, error) {
+	albumID, discNumber, err := model.ParseDiscArtworkID(id)
+	if err != nil {
+		return "", err
+	}
+	al, err := ds.Album(ctx).Get(albumID)
+	if err != nil {
+		return "", err
+	}
+	name := fmt.Sprintf("%s (disc %d)", al.Name, discNumber)
+	// The subtitle is itself a DiscArtPriority candidate, so name it where the chain can be read against it.
+	if subtitle := strings.TrimSpace(al.Discs[discNumber]); subtitle != "" {
+		name += ": " + subtitle
+	}
+	return name, nil
+}
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
new file mode 100644
index 000000000..949fdb42a
--- /dev/null
+++ b/cmd/artwork_test.go
@@ -0,0 +1,899 @@
+package cmd
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("parseArtworkKind", func() {
+	It("accepts a supported kind", func() {
+		k, err := parseArtworkKind("ar", artwork.RecheckKinds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(k).To(Equal(model.KindArtistArtwork))
+	})
+
+	It("rejects an unknown kind and lists the valid ones", func() {
+		_, err := parseArtworkKind("zz", artwork.RecheckKinds)
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("ar"))
+		Expect(err.Error()).To(ContainSubstring("al"))
+	})
+
+	It("rejects a known kind the command does not accept", func() {
+		_, err := parseArtworkKind("mf", artwork.RecheckKinds)
+		Expect(err).To(HaveOccurred())
+	})
+
+	DescribeTable("accepts the kinds each command supports",
+		func(prefix string, valid []model.Kind) {
+			_, err := parseArtworkKind(prefix, valid)
+			Expect(err).ToNot(HaveOccurred())
+		},
+		Entry("explain reads disc artwork", "dc", explainKinds),
+		Entry("explain reads media file artwork", "mf", explainKinds),
+		// Disc artwork has no state to clear and the worker cannot resolve it, so refresh must not
+		// accept it: the queue row would be rejected on every drain.
+		Entry("refresh re-queues media files", "mf", artwork.RefreshableKinds),
+	)
+
+	It("rejects disc artwork for refresh", func() {
+		_, err := parseArtworkKind("dc", artwork.RefreshableKinds)
+		Expect(err).To(HaveOccurred())
+	})
+})
+
+var _ = Describe("explainResult", func() {
+	It("reports the winning source", func() {
+		steps := []artwork.TraceStep{{Candidate: "folder", Outcome: "hit", Detail: "/music/a.jpg"}}
+		Expect(explainResult("folder", steps)).To(ContainSubstring("resolved from folder"))
+	})
+
+	It("reports not resolved when every candidate was tried and missed", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "artist.*", Outcome: "miss"},
+			{Candidate: "external:deezer", Outcome: "miss"},
+		}
+		Expect(explainResult("", steps)).To(Equal("not resolved"))
+	})
+
+	It("reports indeterminate when a local candidate exists but could not be read", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "cover.*", Outcome: "miss"},
+			{Candidate: "embedded", Outcome: "unreadable"},
+		}
+		Expect(explainResult("", steps)).To(ContainSubstring("indeterminate"),
+			"the worker retries an unreadable candidate instead of settling absent, so this is not a clean miss")
+	})
+
+	It("does not qualify a hit that an earlier unreadable candidate preceded", func() {
+		// chainState.try stamps only the external error onto a hit and drops the local one, so the
+		// worker settles this as found; warning about it would be a false alarm.
+		steps := []artwork.TraceStep{
+			{Candidate: "embedded", Outcome: "unreadable"},
+			{Candidate: "cover.*", Outcome: "hit", Detail: "/music/cover.jpg"},
+		}
+		Expect(explainResult("folder", steps)).To(Equal("resolved from folder"))
+	})
+
+	It("reports indeterminate when an external lookup failed transiently", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "artist.*", Outcome: "miss"},
+			{Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},
+		}
+		Expect(explainResult("", steps)).To(ContainSubstring("indeterminate"),
+			"a failed network call is not evidence that the item has no artwork")
+	})
+
+	It("qualifies a win a skipped higher-priority external candidate could have taken", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "external:deezer", Outcome: "would-try"},
+			{Candidate: "artist.*", Outcome: "hit", Detail: "/music/artist.jpg"},
+		}
+		res := explainResult("artist.*", steps)
+		Expect(res).To(ContainSubstring("resolved from artist.*"))
+		Expect(res).To(ContainSubstring("--live"),
+			"offline, the winner is only the winner because the external tier was skipped")
+	})
+
+	It("does not qualify a win that no skipped candidate outranked", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "artist.*", Outcome: "hit"},
+			{Candidate: "external:deezer", Outcome: "would-try"},
+		}
+		Expect(explainResult("artist.*", steps)).To(Equal("resolved from artist.*"))
+	})
+
+	It("reports indeterminate when external agents were never called", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "artist.*", Outcome: "miss"},
+			{Candidate: "external:deezer", Outcome: "would-try"},
+		}
+		Expect(explainResult("", steps)).To(ContainSubstring("indeterminate"),
+			"an offline run must not claim an item is unresolvable when external agents were skipped")
+	})
+
+	It("qualifies a win a failed higher-priority external lookup could have taken", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},
+			{Candidate: "artist.*", Outcome: "hit", Detail: "/music/artist.jpg"},
+		}
+		res := explainResult("artist.*", steps)
+		Expect(res).To(ContainSubstring("resolved from artist.*"))
+		Expect(res).To(ContainSubstring("indeterminate"),
+			"the resolver serves this hit but retries later, so the winner is provisional")
+	})
+
+	It("does not qualify an external win that followed a failed external lookup", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},
+			{Candidate: "external:lastfm", Outcome: "hit", Detail: "http://img"},
+		}
+		Expect(explainResult("external:lastfm", steps)).To(Equal("resolved from external:lastfm"),
+			"a later agent supplying the image discards the earlier error, so there is no retry to warn about")
+	})
+
+	It("does not qualify a win that outranked the failed external lookup", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "artist.*", Outcome: "hit"},
+			{Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},
+		}
+		Expect(explainResult("artist.*", steps)).To(Equal("resolved from artist.*"))
+	})
+})
+
+var _ = Describe("explainAgents", func() {
+	It("accounts for every configured agent, marking the ones the CLI could not use", func() {
+		out := explainAgents("artist-nfo-metadata,apple-music,deezer,lastfm", []string{"deezer"})
+		for _, name := range []string{"artist-nfo-metadata", "apple-music", "deezer", "lastfm"} {
+			Expect(out).To(ContainSubstring(name),
+				"a configured agent missing from this line reads as if it had never been configured")
+		}
+		Expect(out).To(ContainSubstring("not available to the CLI"))
+	})
+
+	It("does not mark anything when every configured agent is available", func() {
+		out := explainAgents("deezer, lastfm", []string{"lastfm", "deezer"})
+		Expect(out).To(Equal("deezer, lastfm"))
+	})
+
+	It("reports an empty configuration as none, not as an unavailable agent", func() {
+		Expect(explainAgents("", nil)).To(Equal("(none)"))
+	})
+})
+
+var _ = Describe("formatExplain", func() {
+	var rep explainReport
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.ArtistArtPriority = "external, artist.*"
+		rep = explainReport{
+			kind:   model.KindArtistArtwork,
+			id:     "ar-1",
+			name:   "Radiohead",
+			agents: "lastfm,spotify",
+			steps: []artwork.TraceStep{
+				{Candidate: "upload", Outcome: "skipped", Detail: "no uploaded image"},
+				{Candidate: "external:deezer", Outcome: "would-try"},
+			},
+			source: "",
+		}
+	})
+
+	It("reports the item, its config and the chain it walked", func() {
+		out := formatExplain(rep)
+		Expect(out).To(ContainSubstring("Radiohead"))
+		Expect(out).To(ContainSubstring("ar-1"))
+		Expect(out).To(ContainSubstring("ArtistArtPriority"))
+		Expect(out).To(ContainSubstring("lastfm,spotify"))
+		Expect(out).To(ContainSubstring("external:deezer"))
+		Expect(out).To(ContainSubstring("would-try"))
+		Expect(out).To(ContainSubstring("indeterminate"))
+	})
+
+	It("reports the absence of stored state and of a queue row", func() {
+		out := formatExplain(rep)
+		Expect(out).To(ContainSubstring("no artwork state recorded"))
+		Expect(out).To(ContainSubstring("not queued"))
+	})
+
+	It("prints the stored state and the queue row when they exist", func() {
+		attempted := time.Date(2026, 8, 13, 10, 0, 0, 0, time.UTC)
+		rep.stored = &model.ItemArtwork{Source: "folder", Hash: "abc123",
+			SourcePath: "/music/cover.jpg", AttemptedAt: attempted}
+		rep.queued = &model.ArtworkQueueItem{Priority: model.ArtworkPriorityScan, Attempts: 2,
+			RetryAt: attempted.Add(time.Hour)}
+		rep.source = "folder"
+
+		out := formatExplain(rep)
+		Expect(out).To(ContainSubstring("abc123"))
+		Expect(out).To(ContainSubstring("/music/cover.jpg"))
+		Expect(out).To(ContainSubstring("2026-08-13T10:00:00Z"))
+		Expect(out).To(ContainSubstring("scan (50)"), "a bare 50 makes the operator look the priority up")
+		Expect(out).To(ContainSubstring("resolved from folder"))
+	})
+
+	It("marks a known-absent stored state instead of printing an empty hash", func() {
+		rep.stored = &model.ItemArtwork{AttemptedAt: time.Now()}
+		Expect(formatExplain(rep)).To(ContainSubstring("absent"))
+	})
+
+	It("reports a failed walk as failed, not as unresolved", func() {
+		rep.resolveErr = errors.New("no such directory")
+
+		out := formatExplain(rep)
+		Expect(out).To(ContainSubstring("resolution failed: no such directory"))
+		Expect(out).ToNot(ContainSubstring("indeterminate"))
+		Expect(out).To(ContainSubstring("would-try"), "the steps taken before the failure still print")
+	})
+
+	It("says a kind that does not walk a chain has no chain, without an empty table", func() {
+		conf.Server.CoverArtPriority = "cover.*, embedded"
+		rep.kind = model.KindPlaylistArtwork
+		rep.steps = nil
+		rep.agents = ""
+
+		out := formatExplain(rep)
+		Expect(out).To(ContainSubstring("does not walk a priority chain"))
+		Expect(out).ToNot(ContainSubstring("CANDIDATE"),
+			"an empty chain table reads as 'nothing was tried', which is false")
+		Expect(out).ToNot(ContainSubstring("not resolved"),
+			"nothing was resolved because nothing was attempted")
+		Expect(out).ToNot(ContainSubstring("CoverArtPriority"),
+			"the priority chain config does not govern this kind")
+	})
+
+	It("says disc artwork keeps no state instead of reporting it as unresolved state", func() {
+		conf.Server.DiscArtPriority = "cover.jpg, embedded"
+		rep = explainReport{
+			kind: model.KindDiscArtwork, id: "al-1:2", name: "OK Computer (disc 2)",
+			steps:  []artwork.TraceStep{{Candidate: "cover.jpg", Outcome: "hit", Detail: "/music/cover.jpg"}},
+			source: "folder",
+		}
+
+		out := formatExplain(rep)
+		Expect(out).To(ContainSubstring("never recorded"))
+		Expect(out).To(ContainSubstring("never queued"))
+		Expect(out).ToNot(ContainSubstring("no artwork state recorded"),
+			"a missing row would read as a lookup that failed, when disc artwork has no row by design")
+		Expect(out).To(ContainSubstring("DiscArtPriority"))
+		Expect(out).ToNot(ContainSubstring("Agents:"), "disc artwork never asks an agent")
+		Expect(out).To(ContainSubstring("resolved from folder"))
+	})
+
+	It("reports the setting that governs media file artwork", func() {
+		conf.Server.EnableMediaFileCoverArt = false
+		rep = explainReport{
+			kind: model.KindMediaFileArtwork, id: "mf-1", name: "Airbag",
+			steps: []artwork.TraceStep{
+				{Candidate: "embedded", Outcome: "skipped", Detail: "EnableMediaFileCoverArt is off"},
+			},
+		}
+
+		out := formatExplain(rep)
+		Expect(out).To(ContainSubstring("EnableMediaFileCoverArt"))
+		Expect(out).To(ContainSubstring("false"))
+		Expect(out).To(ContainSubstring("not resolved"))
+		Expect(out).To(ContainSubstring("no artwork state recorded"), "media files do keep state")
+	})
+})
+
+var _ = Describe("explainConfig", func() {
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DiscArtPriority = "cover.jpg"
+		conf.Server.EnableMediaFileCoverArt = true
+	})
+
+	DescribeTable("names the setting that decides where a kind's artwork comes from",
+		func(kind model.Kind, setting, value string) {
+			gotSetting, gotValue := explainConfig(kind)
+			Expect(gotSetting).To(Equal(setting))
+			Expect(gotValue).To(Equal(value))
+		},
+		Entry("disc", model.KindDiscArtwork, "DiscArtPriority", "cover.jpg"),
+		Entry("media file", model.KindMediaFileArtwork, "EnableMediaFileCoverArt", "true"),
+		Entry("playlist has none", model.KindPlaylistArtwork, "", ""),
+	)
+})
+
+var _ = Describe("discArtworkName", func() {
+	var ds *tests.MockDataStore
+
+	BeforeEach(func() {
+		albumRepo := tests.CreateMockAlbumRepo()
+		albumRepo.SetData(model.Albums{{ID: "al-1", Name: "Sandinista!", Discs: model.Discs{2: "Side Three"}}})
+		ds = &tests.MockDataStore{MockedAlbum: albumRepo}
+	})
+
+	It("names the album, the disc and its subtitle", func() {
+		name, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1:2")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(name).To(Equal("Sandinista! (disc 2): Side Three"))
+	})
+
+	It("omits the subtitle when the disc has none", func() {
+		name, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1:1")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(name).To(Equal("Sandinista! (disc 1)"))
+	})
+
+	It("rejects an id that is not <albumID>:<disc>", func() {
+		_, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1")
+		Expect(err).To(HaveOccurred())
+	})
+})
+
+var _ = Describe("artwork refresh command", func() {
+	It("requires at least a kind and one id", func() {
+		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar"})).To(HaveOccurred())
+		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar", "id1"})).ToNot(HaveOccurred())
+		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar", "id1", "id2"})).ToNot(HaveOccurred())
+	})
+})
+
+var _ = Describe("artwork reprocess selection", func() {
+	It("errors when no selector is given", func() {
+		_, err := selectedKinds(nil, nil, false)
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("--all"))
+	})
+
+	It("returns every kind for --all", func() {
+		ks, err := selectedKinds(nil, nil, true)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ks).To(ConsistOf(artwork.RecheckKinds))
+	})
+
+	It("returns every kind for a source filter given without a kind", func() {
+		ks, err := selectedKinds(nil, []string{"folder"}, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ks).To(ConsistOf(artwork.RecheckKinds), "--source alone is already a complete selection")
+	})
+
+	It("returns only the named kinds", func() {
+		ks, err := selectedKinds([]string{"ar"}, nil, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ks).To(Equal([]model.Kind{model.KindArtistArtwork}))
+	})
+
+	It("keeps a named kind selection alongside a source filter", func() {
+		ks, err := selectedKinds([]string{"ar"}, []string{"folder"}, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ks).To(Equal([]model.Kind{model.KindArtistArtwork}))
+	})
+
+	It("rejects an unknown kind", func() {
+		_, err := selectedKinds([]string{"zz"}, nil, false)
+		Expect(err).To(HaveOccurred())
+	})
+
+	It("counts a repeated kind once", func() {
+		ks, err := selectedKinds([]string{"ar", "ar"}, nil, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(ks).To(Equal([]model.Kind{model.KindArtistArtwork}))
+	})
+})
+
+var _ = Describe("explain/reprocess source round trip", func() {
+	ctx := context.Background()
+
+	// storedSource reads back the Source line explain printed, as an operator would copy it.
+	storedSource := func(out string) string {
+		GinkgoHelper()
+		for line := range strings.SplitSeq(out, "\n") {
+			if after, ok := strings.CutPrefix(strings.TrimSpace(line), "Source:"); ok {
+				return strings.TrimSpace(after)
+			}
+		}
+		Fail("explain printed no Source line")
+		return ""
+	}
+
+	It("names the absent state as reprocess --source accepts it", func() {
+		ds := &tests.MockDataStore{}
+		art := ds.Artwork(ctx).(*tests.MockArtworkRepo)
+		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: model.KindArtistArtwork.Prefix(),
+			ItemID: "ar-1", ImageType: model.ImageTypePrimary})).To(Succeed())
+
+		shown := storedSource(formatExplain(explainReport{kind: model.KindArtistArtwork, id: "ar-1",
+			stored: &model.ItemArtwork{AttemptedAt: time.Now()}}))
+
+		q := ds.ArtworkQueue(ctx)
+		Expect(validateSources(q, repositorySources([]string{shown}))).To(Succeed(),
+			"explain's spelling of a source must be pasteable into --source")
+		Expect(validateSources(q, repositorySources([]string{"(" + shown + ")"}))).ToNot(Succeed(),
+			"a parenthesised name would be rejected, so explain must not print one")
+	})
+})
+
+var _ = Describe("repositorySources", func() {
+	It("maps the user-facing absent name onto the stored empty source", func() {
+		Expect(repositorySources([]string{"absent", "folder"})).To(Equal([]string{"", "folder"}))
+	})
+
+	It("keeps an empty selection empty, meaning every source", func() {
+		Expect(repositorySources(nil)).To(BeEmpty())
+	})
+})
+
+var _ = Describe("promptConfirm", func() {
+	var out strings.Builder
+
+	BeforeEach(func() { out.Reset() })
+
+	It("states the external cost and accepts an explicit yes", func() {
+		Expect(promptConfirm(strings.NewReader("y\n"))(&out, 42, 7)).To(BeTrue())
+		Expect(out.String()).To(ContainSubstring("re-resolve 42 items"))
+		Expect(out.String()).To(ContainSubstring("External lookups: ~7 estimated"))
+	})
+
+	It("defaults to no on anything else", func() {
+		Expect(promptConfirm(strings.NewReader("\n"))(&out, 1, 1)).To(BeFalse())
+		Expect(promptConfirm(strings.NewReader("nope\n"))(&out, 1, 1)).To(BeFalse())
+		Expect(promptConfirm(strings.NewReader(""))(&out, 1, 1)).To(BeFalse())
+	})
+
+	It("drops the external clause when no lookup will be made", func() {
+		Expect(promptConfirm(strings.NewReader("y\n"))(&out, 3, 0)).To(BeTrue())
+		Expect(out.String()).To(ContainSubstring("re-resolve 3 items."))
+		Expect(out.String()).ToNot(ContainSubstring("External lookups"))
+	})
+})
+
+var _ = Describe("reprocessConfirm", func() {
+	var out strings.Builder
+
+	BeforeEach(func() { out.Reset() })
+
+	It("prompts when --yes was not given", func() {
+		Expect(reprocessConfirm(false, strings.NewReader("n\n"))(&out, 5, 5)).To(BeFalse())
+		Expect(out.String()).To(ContainSubstring("Continue?"))
+	})
+
+	It("bypasses the prompt only for --yes", func() {
+		Expect(reprocessConfirm(true, strings.NewReader(""))(&out, 5, 5)).To(BeTrue())
+		Expect(out.String()).To(BeEmpty(), "--yes must not print a prompt it never reads")
+	})
+})
+
+var _ = Describe("reprocessArtwork", func() {
+	var ds *tests.MockDataStore
+	var art *tests.MockArtworkRepo
+	var queue *tests.MockArtworkQueueRepo
+	var out strings.Builder
+	var imageAgents artwork.ImageAgentCount
+	ctx := context.Background()
+	kinds := []model.Kind{model.KindArtistArtwork, model.KindAlbumArtwork}
+	accept := func(io.Writer, int64, int64) bool { return true }
+	decline := func(io.Writer, int64, int64) bool { return false }
+
+	put := func(kind model.Kind, id, source string) {
+		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: kind.Prefix(), ItemID: id,
+			ImageType: model.ImageTypePrimary, Hash: "h" + id, Source: source})).To(Succeed())
+	}
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.CoverArtPriority = "cover.*, external"
+		conf.Server.ArtistArtPriority = "artist.*, external"
+		conf.Server.EnableM3UExternalAlbumArt = false
+		imageAgents = artwork.ImageAgentCount{Artist: 1, Album: 1}
+		ds = &tests.MockDataStore{}
+		art = ds.Artwork(ctx).(*tests.MockArtworkRepo)
+		queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)
+		out.Reset()
+		put(model.KindArtistArtwork, "ar-1", "external:deezer")
+		put(model.KindArtistArtwork, "ar-2", "")
+		put(model.KindAlbumArtwork, "al-1", "external:deezer")
+		put(model.KindAlbumArtwork, "al-2", "folder")
+	})
+
+	It("previews the per-kind breakdown and queues nothing on a dry run", func() {
+		Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, true, accept, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("external:deezer"))
+		Expect(out.String()).To(ContainSubstring("artist"))
+		Expect(out.String()).To(ContainSubstring("album"))
+		Expect(out.String()).To(ContainSubstring("TOTAL"))
+		Expect(out.String()).To(ContainSubstring("Dry run"))
+		Expect(queue.Count()).To(BeZero())
+	})
+
+	It("queues nothing when the operator declines", func() {
+		Expect(reprocessArtwork(ctx, ds, kinds, nil, imageAgents, false, decline, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("Aborted"))
+		Expect(queue.Count()).To(BeZero())
+	})
+
+	It("queues the matching items at recheck priority, leaving their artwork state alone", func() {
+		Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, false, accept, &out)).To(Succeed())
+
+		Expect(queue.Count()).To(Equal(int64(2)))
+		queued, err := queue.Get(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(queued.Priority).To(Equal(model.ArtworkPriorityRecheck))
+		_, err = queue.Get(model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound), "a non-matching source must not be queued")
+
+		stored, err := art.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(stored.Hash).To(Equal("hal-1"), "bulk reprocessing must not blank the current artwork")
+	})
+
+	It("targets the absent state", func() {
+		Expect(reprocessArtwork(ctx, ds, kinds, []string{""}, imageAgents, false, accept, &out)).To(Succeed())
+
+		Expect(queue.Count()).To(Equal(int64(1)))
+		_, err := queue.Get(model.KindArtistArtwork, "ar-2", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+	})
+
+	It("reports matched and queued separately when part of the set is already queued", func() {
+		Expect(queue.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-1",
+			ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBump})).To(Succeed())
+
+		Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, false, accept, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("Queued 1 of 2 matched items"))
+		Expect(out.String()).To(ContainSubstring("Already queued, left unchanged: 1"))
+		queued, err := queue.Get(model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(queued.Priority).To(Equal(model.ArtworkPriorityBump),
+			"an already-queued row keeps its priority and backoff")
+	})
+
+	It("stops at a selection that matches nothing instead of prompting", func() {
+		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindRadioArtwork}, nil, imageAgents, false,
+			func(io.Writer, int64, int64) bool {
+				Fail("must not prompt when there is nothing to queue")
+				return true
+			}, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("Nothing"))
+		Expect(queue.Count()).To(BeZero())
+	})
+
+	It("reports an empty selection as a dry run when one was asked for", func() {
+		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindRadioArtwork}, nil, imageAgents, true, accept, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("Nothing matches"))
+		Expect(out.String()).To(ContainSubstring("Dry run"))
+	})
+
+	It("shows the external estimate on a dry run, which never reaches the prompt", func() {
+		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindAlbumArtwork}, nil, imageAgents, true, accept, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("External lookups: ~2 estimated"))
+	})
+
+	It("bills every agent per item, not one lookup per item", func() {
+		imageAgents = artwork.ImageAgentCount{Artist: 2, Album: 3}
+		var external int64
+		capture := func(_ io.Writer, _, e int64) bool { external = e; return false }
+
+		Expect(reprocessArtwork(ctx, ds, kinds, nil, imageAgents, false, capture, &out)).To(Succeed())
+
+		Expect(external).To(Equal(int64(2*2+2*3)), "2 artists at 2 agents plus 2 albums at 3 agents")
+		Expect(out.String()).To(ContainSubstring("External lookups: ~10 estimated"))
+	})
+
+	It("names the estimate's blind spots instead of claiming a bound it cannot hold", func() {
+		Expect(reprocessArtwork(ctx, ds, kinds, nil, imageAgents, true, accept, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("plugin agents not counted"))
+		Expect(out.String()).To(ContainSubstring("local hits may need fewer"))
+		Expect(out.String()).ToNot(ContainSubstring("up to"), "plugin agents make any ceiling false")
+		Expect(out.String()).ToNot(ContainSubstring("at least"), "a local hit makes any floor false")
+	})
+
+	It("says so when the selection needs no external lookup", func() {
+		conf.Server.CoverArtPriority = "cover.*"
+		put(model.KindPlaylistArtwork, "pl-1", "playlist")
+
+		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindPlaylistArtwork}, nil, imageAgents, true, accept, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("External lookups: none"))
+	})
+
+	It("counts playlists as external cost when the m3u image fetch is enabled", func() {
+		conf.Server.CoverArtPriority = "cover.*"
+		conf.Server.EnableM3UExternalAlbumArt = true
+		put(model.KindPlaylistArtwork, "pl-1", "playlist")
+		var external int64
+		capture := func(_ io.Writer, _, e int64) bool { external = e; return false }
+
+		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindPlaylistArtwork}, nil, imageAgents, false, capture, &out)).To(Succeed())
+
+		Expect(external).To(Equal(int64(1)))
+		Expect(out.String()).To(ContainSubstring("External lookups: ~1 estimated"))
+	})
+
+	It("bills a playlist for every album its grid samples, at every agent", func() {
+		imageAgents = artwork.ImageAgentCount{Album: 3}
+		put(model.KindPlaylistArtwork, "pl-1", "playlist")
+		var external int64
+		capture := func(_ io.Writer, _, e int64) bool { external = e; return false }
+
+		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindPlaylistArtwork}, nil, imageAgents, false, capture, &out)).To(Succeed())
+
+		Expect(external).To(Equal(int64(artwork.PlaylistGridSamples*3)),
+			"one playlist samples 4 albums, each walking all 3 album agents")
+	})
+
+	It("counts only the kinds that call an external agent as external cost", func() {
+		put(model.KindRadioArtwork, "ra-1", "upload")
+		var total, external int64
+		capture := func(_ io.Writer, t, e int64) bool { total, external = t, e; return false }
+
+		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindAlbumArtwork, model.KindRadioArtwork},
+			nil, imageAgents, false, capture, &out)).To(Succeed())
+
+		Expect(total).To(Equal(int64(3)))
+		Expect(external).To(Equal(int64(2)), "radio artwork never reaches an external agent")
+	})
+
+	It("rejects an unknown source and names the ones in use", func() {
+		err := reprocessArtwork(ctx, ds, kinds, []string{"externa:deezer"}, imageAgents, true, accept, &out)
+
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("externa:deezer"))
+		Expect(err.Error()).To(ContainSubstring("external:deezer"))
+		Expect(err.Error()).To(ContainSubstring("folder"))
+		Expect(err.Error()).To(ContainSubstring("absent"), "the empty source prints under its user-facing name")
+		Expect(queue.Count()).To(BeZero())
+	})
+
+	It("accepts the absent filter with nothing absent, still rejecting a typo", func() {
+		put(model.KindArtistArtwork, "ar-2", "folder")
+
+		Expect(reprocessArtwork(ctx, ds, kinds, repositorySources([]string{absentSource}),
+			imageAgents, false, accept, &out)).To(Succeed(),
+			"a reserved source must stay valid once the library has none of it")
+		Expect(out.String()).To(ContainSubstring("Nothing matches"))
+		Expect(queue.Count()).To(BeZero())
+
+		Expect(reprocessArtwork(ctx, ds, kinds, repositorySources([]string{"absnt"}),
+			imageAgents, true, accept, &out)).ToNot(Succeed(), "a typo must still be rejected")
+	})
+
+	It("accepts a source another kind uses, letting the empty selection report itself", func() {
+		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindArtistArtwork}, []string{"folder"},
+			imageAgents, false, decline, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("Nothing matches"),
+			"a well-formed filter must not be reported as a typo because of the kinds selected")
+		Expect(queue.Count()).To(BeZero())
+	})
+})
+
+var _ = Describe("artwork status command", func() {
+	It("takes no arguments", func() {
+		Expect(artworkStatusCmd.Args(artworkStatusCmd, []string{})).ToNot(HaveOccurred())
+		Expect(artworkStatusCmd.Args(artworkStatusCmd, []string{"x"})).To(HaveOccurred())
+	})
+})
+
+var _ = Describe("collectStatus", func() {
+	var ds *tests.MockDataStore
+	var art *tests.MockArtworkRepo
+	var queue *tests.MockArtworkQueueRepo
+	ctx := context.Background()
+
+	BeforeEach(func() {
+		ds = &tests.MockDataStore{}
+		art = ds.Artwork(ctx).(*tests.MockArtworkRepo)
+		queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)
+		put := func(kind model.Kind, id, source, hash string, attempted time.Time) {
+			Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: kind.Prefix(), ItemID: id,
+				ImageType: model.ImageTypePrimary, Source: source, Hash: hash, AttemptedAt: attempted})).To(Succeed())
+		}
+		put(model.KindArtistArtwork, "ar-1", "external:deezer", "h1", time.Now())
+		put(model.KindArtistArtwork, "ar-2", "", "", time.Now().Add(-48*time.Hour))
+		put(model.KindArtistArtwork, "ar-3", "", "", time.Now())
+		put(model.KindAlbumArtwork, "al-1", "folder", "h2", time.Now())
+		Expect(queue.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-9",
+			ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBackfill})).To(Succeed())
+	})
+
+	It("reports the queue, the source distribution and the absent ages", func() {
+		rep, err := collectStatus(ctx, ds)
+		Expect(err).ToNot(HaveOccurred())
+
+		Expect(rep.queue).To(ConsistOf(model.ArtworkQueueStat{ItemKind: "ar",
+			Priority: model.ArtworkPriorityBackfill, Count: 1}))
+		Expect(rep.sources).To(ContainElements(
+			sourceCount{kind: model.KindArtistArtwork, source: "external:deezer", count: 1},
+			sourceCount{kind: model.KindArtistArtwork, source: "", count: 2},
+			sourceCount{kind: model.KindAlbumArtwork, source: "folder", count: 1},
+		))
+		Expect(rep.absent).To(ContainElement(absentCount{kind: model.KindArtistArtwork,
+			ArtworkAbsentStat: model.ArtworkAbsentStat{Total: 2, Stale: 1}}))
+	})
+
+	It("compares the stored fingerprint against the current one", func() {
+		Expect(ds.Property(ctx).Put(consts.ArtConfFingerprintPropertyKey, "old-fingerprint")).To(Succeed())
+
+		rep, err := collectStatus(ctx, ds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(rep.stored).To(Equal("old-fingerprint"))
+		Expect(rep.current).To(Equal(artwork.ConfigFingerprint()),
+			"the CLI must report the value backfill itself compares")
+	})
+
+	It("queues nothing", func() {
+		_, err := collectStatus(ctx, ds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(queue.Count()).To(Equal(int64(1)), "status must not enqueue anything")
+	})
+})
+
+var _ = Describe("formatStatus", func() {
+	var rep statusReport
+
+	BeforeEach(func() {
+		rep = statusReport{
+			queue: []model.ArtworkQueueStat{
+				{ItemKind: "ar", Priority: model.ArtworkPriorityBackfill, Count: 2},
+				{ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1},
+			},
+			sources: []sourceCount{
+				{kind: model.KindArtistArtwork, source: "external:deezer", count: 5},
+				{kind: model.KindArtistArtwork, source: "", count: 2},
+			},
+			absent: []absentCount{
+				{kind: model.KindArtistArtwork, ArtworkAbsentStat: model.ArtworkAbsentStat{Total: 2, Stale: 1}},
+			},
+			inputs:  []artwork.FingerprintInput{{Name: "Agents", Value: "deezer,lastfm"}},
+			stored:  "abc123",
+			current: "abc123",
+		}
+	})
+
+	// block isolates one section, so an assertion cannot be satisfied by a coincidence elsewhere.
+	block := func(out, header string) string {
+		GinkgoHelper()
+		_, after, found := strings.Cut(out, header+"\n")
+		Expect(found).To(BeTrue(), "the %q block must be printed", header)
+		body, _, _ := strings.Cut(after, "\n\n")
+		return body
+	}
+
+	It("names the kind and the priority of every queued row", func() {
+		queue := block(formatStatus(rep), "Queue")
+		Expect(queue).To(MatchRegexp(`artist\s+backfill\s+2`))
+		Expect(queue).To(MatchRegexp(`album\s+scan\s+1`))
+	})
+
+	It("totals the queue", func() {
+		Expect(block(formatStatus(rep), "Queue")).To(MatchRegexp(`TOTAL\s+3`))
+	})
+
+	It("counts each source, naming the empty one absent", func() {
+		sources := block(formatStatus(rep), "Sources")
+		Expect(sources).To(MatchRegexp(`artist\s+external:deezer\s+5`))
+		Expect(sources).To(MatchRegexp(`artist\s+absent\s+2`))
+	})
+
+	It("prints the absent total and how many are due for recheck", func() {
+		absent := block(formatStatus(rep), "Absent (resolved, no image found)")
+		Expect(absent).To(MatchRegexp(`artist\s+2\s+1`))
+	})
+
+	It("states the recheck window the absent counts are bucketed against", func() {
+		Expect(formatStatus(rep)).To(ContainSubstring("24h"))
+	})
+
+	It("leads with the queued backlog, which is the finding, not with the fingerprint verdict", func() {
+		out := block(formatStatus(rep), "Backfill")
+		Expect(out).To(MatchRegexp(`State:\s+backfill running: 2 items queued`),
+			"an operator scanning for trouble must not read 'up to date' while 2 items churn")
+		Expect(out).To(ContainSubstring("fingerprint up to date"))
+	})
+
+	It("keeps the re-enqueue warning while a backfill is already running", func() {
+		rep.stored = "older"
+
+		out := block(formatStatus(rep), "Backfill")
+		Expect(out).To(MatchRegexp(`State:\s+backfill running: 2 items queued`))
+		Expect(out).To(ContainSubstring("re-enqueued"),
+			"the stored fingerprint is still stale, so a second full re-enqueue is pending on top of this one")
+	})
+
+	It("reports up to date only once the backfill has drained", func() {
+		rep.queue = []model.ArtworkQueueStat{{ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1}}
+
+		Expect(block(formatStatus(rep), "Backfill")).To(MatchRegexp(`State:\s+up to date`))
+	})
+
+	It("echoes the config inputs a fingerprint change would have come from", func() {
+		out := block(formatStatus(rep), "Backfill")
+		Expect(out).To(MatchRegexp(`Agents:\s+deezer,lastfm`))
+		Expect(out).To(ContainSubstring("abc123"), "the fingerprint values themselves must be printed")
+	})
+
+	It("reports a changed fingerprint as a pending re-resolve of everything", func() {
+		rep.stored = "older"
+		rep.queue = nil
+
+		out := formatStatus(rep)
+		Expect(out).To(ContainSubstring("fingerprint changed"))
+		Expect(out).ToNot(ContainSubstring("up to date"))
+	})
+
+	It("reports a never-recorded fingerprint without printing an empty value", func() {
+		rep.stored = ""
+
+		out := formatStatus(rep)
+		Expect(out).To(ContainSubstring("(none)"))
+		Expect(out).To(ContainSubstring("fingerprint changed"))
+	})
+
+	It("says the queue is empty instead of printing a headless table", func() {
+		rep.queue = nil
+
+		out := formatStatus(rep)
+		Expect(out).To(ContainSubstring("empty"))
+		Expect(out).ToNot(ContainSubstring("PRIORITY"))
+	})
+})
+
+var _ = Describe("refreshItems", func() {
+	var ds *tests.MockDataStore
+	var queue *tests.MockArtworkQueueRepo
+	var art *tests.MockArtworkRepo
+	var out strings.Builder
+	ctx := context.Background()
+
+	BeforeEach(func() {
+		albums := tests.CreateMockAlbumRepo()
+		albums.SetData(model.Albums{{ID: "al-1"}, {ID: "al-3"}})
+		ds = &tests.MockDataStore{MockedAlbum: albums}
+		art = ds.Artwork(ctx).(*tests.MockArtworkRepo)
+		queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)
+		out.Reset()
+	})
+
+	It("clears the stored state and queues each id at Bump priority", func() {
+		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: model.KindAlbumArtwork.Prefix(),
+			ItemID: "al-1", ImageType: model.ImageTypePrimary, Hash: "abc123"})).To(Succeed())
+
+		Expect(refreshItems(ctx, ds, model.KindAlbumArtwork, []string{"al-1", "al-3"}, &out)).To(BeZero())
+
+		_, err := art.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+		queued, err := queue.Get(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(queued.Priority).To(Equal(model.ArtworkPriorityBump))
+		Expect(out.String()).To(Equal("al/al-1: queued\nal/al-3: queued\n"))
+	})
+
+	It("skips an id that does not exist instead of queuing it", func() {
+		Expect(refreshItems(ctx, ds, model.KindAlbumArtwork, []string{"al-2"}, &out)).To(Equal(1))
+
+		_, err := queue.Get(model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound), "a typo must not leave an orphan queue row")
+		Expect(out.String()).To(BeEmpty())
+	})
+
+	It("continues past a failing id and counts the failures", func() {
+		Expect(refreshItems(ctx, ds, model.KindAlbumArtwork,
+			[]string{"al-1", "al-2", "al-3"}, &out)).To(Equal(1))
+
+		Expect(out.String()).To(Equal("al/al-1: queued\nal/al-3: queued\n"),
+			"the ids after a failure are still refreshed")
+	})
+})
diff --git a/cmd/plugin.go b/cmd/plugin.go
index 6cce8ea5f..ded28e969 100644
--- a/cmd/plugin.go
+++ b/cmd/plugin.go
@@ -9,7 +9,6 @@ import (
 	"os"
 	"strconv"
 	"strings"
-	"text/tabwriter"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -314,7 +313,7 @@ func formatPluginList(list model.Plugins, format string) (string, error) {
 		return sb.String(), w.Error()
 	case "table":
 		var sb strings.Builder
-		w := tabwriter.NewWriter(&sb, 0, 4, 2, ' ', 0)
+		w := newTabWriter(&sb)
 		fmt.Fprintln(w, "ID\tNAME\tVERSION\tENABLED\tLAST ERROR")
 		for _, p := range list {
 			name, version := manifestSummary(p)
diff --git a/cmd/utils.go b/cmd/utils.go
index 81d646cf1..74da51828 100644
--- a/cmd/utils.go
+++ b/cmd/utils.go
@@ -4,6 +4,8 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
+	"text/tabwriter"
 
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/db"
@@ -13,6 +15,11 @@ import (
 	"github.com/navidrome/navidrome/persistence"
 )
 
+// newTabWriter keeps every CLI table on the same column settings.
+func newTabWriter(out io.Writer) *tabwriter.Writer {
+	return tabwriter.NewWriter(out, 0, 4, 2, ' ', 0)
+}
+
 func getAdminContext(ctx context.Context) (model.DataStore, context.Context) {
 	sqlDB := db.Db()
 	ds := persistence.New(sqlDB)
diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index 4bdd48422..49a99f8ca 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -223,6 +223,18 @@ func CreateArtworkWorker() *artwork.Worker {
 	return worker
 }
 
+func CreateArtworkResolver(trace *artwork.ChainTrace, live bool) *artwork.TracingResolver {
+	sqlDB := db.Db()
+	dataStore := persistence.New(sqlDB)
+	broker := events.GetBroker()
+	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
+	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
+	agentsAgents := agents.GetAgents(dataStore, manager)
+	fFmpeg := ffmpeg.New()
+	tracingResolver := artwork.NewTracingResolver(dataStore, agentsAgents, fFmpeg, trace, live)
+	return tracingResolver
+}
+
 func getPluginManager() *plugins.Manager {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
diff --git a/cmd/wire_injectors.go b/cmd/wire_injectors.go
index ae24b61fa..8bc404fb1 100644
--- a/cmd/wire_injectors.go
+++ b/cmd/wire_injectors.go
@@ -144,6 +144,13 @@ func CreateArtworkWorker() *artwork.Worker {
 	))
 }
 
+func CreateArtworkResolver(trace *artwork.ChainTrace, live bool) *artwork.TracingResolver {
+	panic(wire.Build(
+		allProviders,
+		artwork.NewTracingResolver,
+	))
+}
+
 func getPluginManager() *plugins.Manager {
 	panic(wire.Build(
 		allProviders,
diff --git a/core/artwork/agent_images.go b/core/artwork/agent_images.go
index c7032b62b..a6f746959 100644
--- a/core/artwork/agent_images.go
+++ b/core/artwork/agent_images.go
@@ -47,10 +47,17 @@ func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar
 	// Synthetic artists would otherwise get an unrelated agent result assigned to them.
 	switch ar.ID {
 	case consts.UnknownArtistID, consts.VariousArtistsID:
+		traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped, Detail: "synthetic artist"})
 		return nil, "", false
 	}
 	name := externalName(ar.Name)
-	for _, a := range ag.ArtistImageAgents() {
+	imageAgents := ag.ArtistImageAgents()
+	if len(imageAgents) == 0 {
+		traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped,
+			Detail: "no enabled agent provides artist images"})
+		return nil, "", false
+	}
+	for _, a := range imageAgents {
 		reader, _, err := gate(a.Name, func() (io.ReadCloser, string, error) {
 			imgs, err := a.Retriever.GetArtistImages(ctx, ar.ID, name, ar.MbzArtistID)
 			if err != nil {
@@ -76,7 +83,13 @@ func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar
 // fetchAlbumImage is the album counterpart of fetchArtistImage.
 func fetchAlbumImage(ctx context.Context, ag *agents.Agents, gate gateFunc, al model.Album) (r io.ReadCloser, agentName string, extErr bool) {
 	name, artist := externalName(al.Name), externalName(al.AlbumArtist)
-	for _, a := range ag.AlbumImageAgents() {
+	imageAgents := ag.AlbumImageAgents()
+	if len(imageAgents) == 0 {
+		traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped,
+			Detail: "no enabled agent provides album images"})
+		return nil, "", false
+	}
+	for _, a := range imageAgents {
 		reader, _, err := gate(a.Name, func() (io.ReadCloser, string, error) {
 			imgs, err := a.Retriever.GetAlbumImages(ctx, name, artist, al.MbzAlbumID)
 			if err != nil {
diff --git a/core/artwork/agent_images_test.go b/core/artwork/agent_images_test.go
index 716245c93..60a34352d 100644
--- a/core/artwork/agent_images_test.go
+++ b/core/artwork/agent_images_test.go
@@ -173,6 +173,30 @@ var _ = Describe("agent images", func() {
 			Expect(a.artistCalls).To(Equal(0), "synthetic artists never reach the agents")
 		})
 
+		It("records a skipped external candidate when no agent provides artist images", func() {
+			ag := imageAgents()
+			t := &ChainTrace{}
+
+			r, _, extErr := fetchArtistImage(withTrace(ctx, t), ag, passthroughGate, model.Artist{ID: "ar1"})
+			Expect(r).To(BeNil())
+			Expect(extErr).To(BeFalse())
+			Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "external", Outcome: OutcomeSkipped,
+				Detail: "no enabled agent provides artist images"}}),
+				"a configured external token must never be silently absent from the chain")
+		})
+
+		It("records a skipped external candidate for synthetic artists", func() {
+			a := &fakeImageAgent{name: "agentA", imgs: []agents.ExternalImage{img("/a", 100)}}
+			ag := imageAgents(a)
+			t := &ChainTrace{}
+
+			_, _, _ = fetchArtistImage(withTrace(ctx, t), ag, passthroughGate,
+				model.Artist{ID: consts.VariousArtistsID, Name: "Various Artists"})
+			Expect(t.Steps()).To(HaveLen(1))
+			Expect(t.Steps()[0].Outcome).To(Equal(OutcomeSkipped))
+			Expect(t.Steps()[0].Detail).To(ContainSubstring("synthetic"))
+		})
+
 		It("clears typographic characters from the query name unless preserving unicode", func() {
 			conf.Server.DevPreserveUnicodeInExternalCalls = false
 			a := &fakeImageAgent{name: "agentA"}
@@ -231,6 +255,18 @@ var _ = Describe("agent images", func() {
 			Expect(a.albumCalls).To(Equal(1))
 		})
 
+		It("records a skipped external candidate when no agent provides album images", func() {
+			ag := imageAgents()
+			t := &ChainTrace{}
+
+			r, _, extErr := fetchAlbumImage(withTrace(ctx, t), ag, passthroughGate, model.Album{Name: "Album"})
+			Expect(r).To(BeNil())
+			Expect(extErr).To(BeFalse())
+			Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "external", Outcome: OutcomeSkipped,
+				Detail: "no enabled agent provides album images"}}),
+				"a configured external token must never be silently absent from the chain")
+		})
+
 		It("reports extErr when the only agent fails transiently", func() {
 			a := &fakeImageAgent{name: "agentA", err: context.DeadlineExceeded}
 			ag := imageAgents(a)
diff --git a/core/artwork/artwork.go b/core/artwork/artwork.go
index 8ac8d9c9d..7edc80e99 100644
--- a/core/artwork/artwork.go
+++ b/core/artwork/artwork.go
@@ -11,6 +11,7 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -118,7 +119,7 @@ func (s *service) Get(ctx context.Context, artID model.ArtworkID, size int, squa
 }
 
 // requestRecheckAge throttles view-triggered rechecks so reopening a genuinely-absent page can't
-// hammer external services; below staleAbsentAge to catch younger absences.
+// hammer external services; below StaleAbsentAge to catch younger absences.
 const requestRecheckAge = time.Hour
 
 func (s *service) serveEntity(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
@@ -317,16 +318,15 @@ func (s *service) serveDisc(ctx context.Context, artID model.ArtworkID, size int
 		return nil, err
 	}
 	// Single-disc albums run the chain too: a disc can carry art distinct from the album cover.
-	selectImage := func() (io.ReadCloser, string, error) {
-		funcs := dr.fromDiscArtPriority(ctx, s.ffmpeg, conf.Server.DiscArtPriority)
-		return selectImageReader(ctx, artID, funcs...)
+	selectImage := func() (io.ReadCloser, error) {
+		res, err := dr.selectImage(ctx, s.ffmpeg, conf.Server.DiscArtPriority, &chainState{})
+		return res.reader, err
 	}
 	albumArtID := model.ArtworkID{Kind: model.KindAlbumArtwork, ID: dr.album.ID}
 	// Disc art has no state row, hence no content hash: keying on id, album mtime and
 	// DiscArtPriority lets a warm cache answer without running the chain or touching the disk.
 	key := fmt.Sprintf("%s|%d|%s", artID.ID, dr.cacheTime().UnixNano(), conf.Server.DiscArtPriority)
-	img, err := s.serveSource(ctx, key, "", dr.cacheTime(), size, square,
-		func() (io.ReadCloser, error) { rc, _, err := selectImage(); return rc, err })
+	img, err := s.serveSource(ctx, key, "", dr.cacheTime(), size, square, selectImage)
 	if err != nil {
 		if errors.Is(err, context.Canceled) {
 			return nil, err
@@ -386,6 +386,54 @@ func (s *service) parseArtworkID(ctx context.Context, id string) (model.ArtworkI
 	return model.ArtworkID{}, model.ErrNotFound
 }
 
+// TracingResolver is the CLI's read-only view of resolution: it walks the priority chain, records
+// the walk and reports the winning source, without ever writing artwork state.
+type TracingResolver struct {
+	inner *resolver
+	trace *ChainTrace
+}
+
+// NewTracingResolver builds a TracingResolver that records its priority-chain walk. With live
+// false the external tier is reported but never called.
+func NewTracingResolver(ds model.DataStore, ag *agents.Agents, ffm ffmpeg.FFmpeg, t *ChainTrace, live bool) *TracingResolver {
+	gate := offlineGate(t)
+	if live {
+		// A diagnostic must show the provider's real answer, and one item is at most one call
+		// per agent, so --live deliberately bypasses the rate limiter and circuit breaker.
+		gate = tracingGate(t, passthroughGate)
+	}
+	return &TracingResolver{inner: newResolver(ds, ag, ffm, gate), trace: t}
+}
+
+// Resolve walks kind's sources for id, recording the walk, and reports the winning source
+// ("" when none produced an image).
+func (r *TracingResolver) Resolve(ctx context.Context, kind model.Kind, id string) (string, error) {
+	switch kind {
+	case model.KindArtistArtwork:
+		return r.explain(ctx, r.inner.resolveArtist, id)
+	case model.KindAlbumArtwork:
+		return r.explain(ctx, r.inner.resolveAlbum, id)
+	case model.KindDiscArtwork:
+		return r.explain(ctx, r.inner.resolveDisc, id)
+	case model.KindMediaFileArtwork:
+		return r.explain(ctx, r.inner.resolveMediaFile, id)
+	}
+	return "", fmt.Errorf("artwork: %s artwork has no chain to explain", kind)
+}
+
+// explain discards the bytes: nothing downstream persists this resolution, so nothing else
+// would close the reader either.
+func (r *TracingResolver) explain(ctx context.Context, resolve func(context.Context, string) (resolution, error), id string) (string, error) {
+	res, err := resolve(withTrace(ctx, r.trace), id)
+	if err != nil {
+		return "", err
+	}
+	if res.reader != nil {
+		_ = res.reader.Close()
+	}
+	return res.source, nil
+}
+
 func unixMtime(mtime int64) time.Time {
 	if mtime <= 0 {
 		return time.Time{}
diff --git a/core/artwork/disc.go b/core/artwork/disc.go
index 21f596b60..acd8a3740 100644
--- a/core/artwork/disc.go
+++ b/core/artwork/disc.go
@@ -113,27 +113,71 @@ func newDiscArtworkReader(ctx context.Context, ds model.DataStore, artID model.A
 	}, nil
 }
 
-func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string) []sourceFunc {
-	var ff []sourceFunc
+// discCandidate is one DiscArtPriority entry. skip is set when the entry maps to no source at
+// all, so a chain walk can say why instead of leaving a configured entry unaccounted for.
+type discCandidate struct {
+	pattern string
+	resolve func() (resolution, bool)
+	skip    string
+}
+
+func (d *discArtworkReader) discCandidates(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string) []discCandidate {
+	folder := func(sf sourceFunc) func() (resolution, bool) {
+		return func() (resolution, bool) { return resolveFolderSource(d.lib, sf) }
+	}
+	var cc []discCandidate
 	for pattern := range strings.SplitSeq(strings.ToLower(priority), ",") {
 		pattern = strings.TrimSpace(pattern)
+		if pattern == "" {
+			continue
+		}
+		c := discCandidate{pattern: 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))
+			c.resolve = func() (resolution, bool) {
+				return resolveEmbedded(ctx, d.lib, ffmpeg, d.firstTrackRel)
 			}
-		case len(d.imgFiles) > 0:
-			ff = append(ff, d.fromExternalFile(ctx, pattern))
+		case pattern == externalCandidate:
+			c.skip = "external sources are not supported for disc artwork"
+		case pattern == "discsubtitle":
+			subtitle := strings.TrimSpace(d.album.Discs[d.discNumber])
+			if subtitle == "" {
+				c.skip = "disc has no subtitle"
+			} else {
+				c.resolve = folder(d.fromDiscSubtitle(ctx, subtitle))
+			}
+		case len(d.imgFiles) == 0:
+			c.skip = "no images in album folder"
+		default:
+			c.resolve = folder(d.fromExternalFile(ctx, pattern))
+		}
+		cc = append(cc, c)
+	}
+	return cc
+}
+
+// selectImage walks the DiscArtPriority entries and returns the first that yields an image.
+// chain records the walk; the serving path passes an untraced one and pays nothing for it.
+func (d *discArtworkReader) selectImage(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string,
+	chain *chainState) (resolution, error) {
+	for _, c := range d.discCandidates(ctx, ffmpeg, priority) {
+		if err := ctx.Err(); err != nil {
+			return resolution{}, err
+		}
+		if c.skip != "" {
+			chain.record(c.pattern, OutcomeSkipped, c.skip)
+			continue
+		}
+		start := time.Now()
+		res, ok := c.resolve()
+		log.Trace(ctx, "Artwork: Tried a disc artwork candidate", "albumID", d.album.ID,
+			"disc", d.discNumber, "pattern", c.pattern, "hit", ok, "path", res.sourcePath,
+			"elapsed", time.Since(start))
+		if res, ok = chain.try(c.pattern, res, ok); ok {
+			return res, nil
 		}
 	}
-	return ff
+	return chain.exhausted(), nil
 }
 
 // fromDiscSubtitle returns a sourceFunc that matches image files whose stem
diff --git a/core/artwork/disc_test.go b/core/artwork/disc_test.go
index 8264ee27b..8852741cf 100644
--- a/core/artwork/disc_test.go
+++ b/core/artwork/disc_test.go
@@ -6,6 +6,8 @@ import (
 	"path/filepath"
 
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -179,19 +181,19 @@ var _ = Describe("Disc Artwork Reader", func() {
 				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()
+			cc := reader.discCandidates(ctx, nil, "disc*.*, cover.*")
+			Expect(cc).To(HaveLen(2))
+			res, ok := cc[0].resolve()
+			Expect(ok).To(BeTrue())
+			Expect(res.sourcePath).To(Equal(reader.lib.Abs(f2)))
+			res.reader.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()
+			cc = reader.discCandidates(ctx, nil, "cover.*, disc*.*")
+			Expect(cc).To(HaveLen(2))
+			res, ok = cc[0].resolve()
+			Expect(ok).To(BeTrue())
+			Expect(res.sourcePath).To(Equal(reader.lib.Abs(f1)))
+			res.reader.Close()
 		})
 
 		DescribeTable("numbered match wins over shared fallback within a pattern",
@@ -428,64 +430,109 @@ var _ = Describe("Disc Artwork Reader", func() {
 	})
 
 	Describe("discArtworkReader", func() {
-		Describe("fromDiscArtPriority", func() {
-			var (
-				reader *discArtworkReader
-				tmpDir string
+		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},
+			}
+		})
+
+		Describe("selectImage", func() {
+			It("abandons the walk when the context is cancelled", func() {
+				ctx, cancel := context.WithCancel(context.Background())
+				cancel()
+
+				res, err := reader.selectImage(ctx, nil, "disc*.*, cover.*", &chainState{})
+
+				Expect(err).To(MatchError(context.Canceled))
+				Expect(res.reader).To(BeNil())
+			})
+
+			// "the track has no embedded art" and "the track is there but unreadable" are the two
+			// answers a wrong-artwork report needs told apart; only the second is worth retrying.
+			It("reports a track it cannot parse as unreadable, not as a miss", func() {
+				trace := &ChainTrace{}
+				track := filepath.Join(tmpDir, filepath.FromSlash(reader.firstTrackRel))
+				Expect(os.MkdirAll(filepath.Dir(track), 0755)).To(Succeed())
+				Expect(os.WriteFile(track, []byte("not audio"), 0600)).To(Succeed())
+
+				res, err := reader.selectImage(context.Background(), tests.NewMockFFmpeg(""), "embedded",
+					&chainState{trace: trace})
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(res.localError).To(BeTrue())
+				Expect(trace.Steps()).To(Equal([]TraceStep{{Candidate: "embedded", Outcome: OutcomeUnreadable}}))
+			})
+
+			It("reports a disc with no tracks to read as a miss", func() {
+				trace := &ChainTrace{}
+				reader.firstTrackRel = ""
+
+				res, err := reader.selectImage(context.Background(), tests.NewMockFFmpeg(""), "embedded",
+					&chainState{trace: trace})
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(res.localError).To(BeFalse(), "there was nothing to read, so nothing failed to read")
+				Expect(trace.Steps()).To(Equal([]TraceStep{{Candidate: "embedded", Outcome: OutcomeMiss}}))
+			})
+		})
+
+		Describe("discCandidates", func() {
+			It("returns a resolvable candidate for glob patterns", func() {
+				cc := reader.discCandidates(context.Background(), nil, "disc*.*")
+				Expect(cc).To(HaveLen(1))
+				Expect(cc[0].resolve).ToNot(BeNil())
+			})
+
+			It("returns one candidate per entry, in order", func() {
+				cc := reader.discCandidates(context.Background(), nil, "disc*.*, cd*.*, embedded")
+				Expect(slice.Map(cc, func(c discCandidate) string { return c.pattern })).
+					To(Equal([]string{"disc*.*", "cd*.*", "embedded"}))
+			})
+
+			It("skips an empty entry rather than building a glob that matches nothing", func() {
+				cc := reader.discCandidates(context.Background(), nil, "disc*.*,")
+				Expect(cc).To(HaveLen(1))
+			})
+
+			// The skip reasons below are what `artwork explain` prints, so an entry that maps to no
+			// source must say why instead of vanishing from the walk.
+			DescribeTable("keeps an entry that maps to no source, with its reason",
+				func(setup func(), priority, reason string) {
+					setup()
+					cc := reader.discCandidates(context.Background(), nil, priority)
+					Expect(cc).To(HaveLen(1))
+					Expect(cc[0].resolve).To(BeNil())
+					Expect(cc[0].skip).To(Equal(reason))
+				},
+				Entry("external is unsupported", func() {}, "external",
+					"external sources are not supported for disc artwork"),
+				Entry("no images in the album folder", func() { reader.imgFiles = nil }, "disc*.*",
+					"no images in album folder"),
+				Entry("the disc has no subtitle",
+					func() { reader.album = model.Album{Discs: model.Discs{2: ""}} }, "discsubtitle",
+					"disc has no subtitle"),
 			)
 
-			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))
+				cc := reader.discCandidates(context.Background(), nil, "discsubtitle")
+				Expect(cc).To(HaveLen(1))
+				Expect(cc[0].resolve).ToNot(BeNil())
 			})
 		})
 	})
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
index ce72a6c8e..ae1fc0a0d 100644
--- a/core/artwork/housekeeping.go
+++ b/core/artwork/housekeeping.go
@@ -6,6 +6,8 @@ import (
 	"encoding/hex"
 	"fmt"
 	"slices"
+	"strconv"
+	"strings"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -16,27 +18,54 @@ import (
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
-const staleAbsentAge = 24 * time.Hour
+// StaleAbsentAge is how long an absent state is trusted before a recheck retries it.
+const StaleAbsentAge = 24 * time.Hour
 
-// recheckKinds omits media files: they resolve embedded-only, at scan or on view.
-var recheckKinds = []model.Kind{
+// RecheckKinds omits media files: they resolve embedded-only, at scan or on view.
+var RecheckKinds = []model.Kind{
 	model.KindArtistArtwork, model.KindAlbumArtwork, model.KindPlaylistArtwork, model.KindRadioArtwork,
 }
 
+// KeepsState reports whether a kind is recorded in item_artwork and the artwork queue. Disc
+// artwork is read through on every request and cached by content key, so it has neither.
+func KeepsState(kind model.Kind) bool { return kind != model.KindDiscArtwork }
+
+// RefreshableKinds is every kind Refresh can clear and re-queue, so it holds exactly the kinds
+// KeepsState admits. Media files are absent from RecheckKinds but belong here: the worker
+// resolves them, it just never revisits them on its own.
+var RefreshableKinds = append(slices.Clone(RecheckKinds), model.KindMediaFileArtwork)
+
 // hasRecheckPath reports whether a periodic job will revisit this kind, making an absent settle recoverable.
 func hasRecheckPath(prefix string) bool {
 	kind, ok := model.ParseKind(prefix)
-	return ok && slices.Contains(recheckKinds, kind)
+	return ok && slices.Contains(RecheckKinds, kind)
 }
 
 // artworkEpoch invalidates all resolution state when bumped; bump it whenever resolution semantics change.
 const artworkEpoch = 1
 
-// fingerprint covers the inputs that affect resolution outcomes; a change invalidates stored state.
-func fingerprint() string {
-	raw := fmt.Sprintf("%s|%s|%s|%s|%t|%t|%d",
-		conf.Server.CoverArtPriority, conf.Server.ArtistArtPriority, conf.Server.ArtistImageFolder,
-		conf.Server.Agents, conf.Server.EnableExternalServices, conf.Server.EnableM3UExternalAlbumArt, artworkEpoch)
+// FingerprintInput is one config value the fingerprint covers, named after the setting it came from.
+type FingerprintInput struct {
+	Name  string
+	Value string
+}
+
+// FingerprintInputs is the single listing of what ConfigFingerprint hashes.
+func FingerprintInputs() []FingerprintInput {
+	return []FingerprintInput{
+		{"CoverArtPriority", conf.Server.CoverArtPriority},
+		{"ArtistArtPriority", conf.Server.ArtistArtPriority},
+		{"ArtistImageFolder", conf.Server.ArtistImageFolder},
+		{"Agents", conf.Server.Agents},
+		{"EnableExternalServices", strconv.FormatBool(conf.Server.EnableExternalServices)},
+		{"EnableM3UExternalAlbumArt", strconv.FormatBool(conf.Server.EnableM3UExternalAlbumArt)},
+	}
+}
+
+// ConfigFingerprint covers the inputs that affect resolution outcomes; a change invalidates stored state.
+func ConfigFingerprint() string {
+	values := slice.Map(FingerprintInputs(), func(i FingerprintInput) string { return i.Value })
+	raw := fmt.Sprintf("%s|%d", strings.Join(values, "|"), artworkEpoch)
 	sum := md5.Sum([]byte(raw)) //nolint:gosec // fingerprint, not security-sensitive
 	return hex.EncodeToString(sum[:])
 }
@@ -45,7 +74,7 @@ func fingerprint() string {
 func backfill(ctx context.Context, ds model.DataStore) (bool, error) {
 	start := time.Now()
 	ctx = auth.WithAdminUser(ctx, ds)
-	current := fingerprint()
+	current := ConfigFingerprint()
 	props := ds.Property(ctx)
 	stored, err := props.DefaultGet(consts.ArtConfFingerprintPropertyKey, "")
 	if err != nil {
@@ -95,9 +124,9 @@ func enqueueBackfillKind(ctx context.Context, ds model.DataStore, kind model.Kin
 }
 
 func enqueueStaleAbsentAll(ctx context.Context, ds model.DataStore) error {
-	cutoff := time.Now().Add(-staleAbsentAge)
+	cutoff := time.Now().Add(-StaleAbsentAge)
 	queue := ds.ArtworkQueue(ctx)
-	for _, kind := range recheckKinds {
+	for _, kind := range RecheckKinds {
 		if _, err := queue.EnqueueStaleAbsent(kind, cutoff); err != nil {
 			return err
 		}
@@ -108,7 +137,7 @@ func enqueueStaleAbsentAll(ctx context.Context, ds model.DataStore) error {
 // enqueueMissingAll is the safety net for entities a scan never enqueued (added between scans, or scanner off).
 func enqueueMissingAll(ctx context.Context, ds model.DataStore) error {
 	queue := ds.ArtworkQueue(ctx)
-	for _, kind := range recheckKinds {
+	for _, kind := range RecheckKinds {
 		if _, err := queue.EnqueueAllMissing(kind, model.ArtworkPriorityRecheck); err != nil {
 			return err
 		}
diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.go
index 3b75c5186..32a7688b4 100644
--- a/core/artwork/housekeeping_test.go
+++ b/core/artwork/housekeeping_test.go
@@ -52,6 +52,19 @@ func (o *orderTrackingQueueRepo) Enqueue(items ...model.ArtworkQueueItem) error
 	return o.MockArtworkQueueRepo.Enqueue(items...)
 }
 
+var _ = Describe("RefreshableKinds", func() {
+	// The two are meant to describe the same fact. Nothing but this test stops them from drifting,
+	// and a drift would have `artwork explain` report state for a kind that keeps none.
+	It("holds exactly the kinds that keep state", func() {
+		for _, k := range []model.Kind{
+			model.KindArtistArtwork, model.KindAlbumArtwork, model.KindPlaylistArtwork,
+			model.KindRadioArtwork, model.KindMediaFileArtwork, model.KindDiscArtwork,
+		} {
+			Expect(slices.Contains(RefreshableKinds, k)).To(Equal(KeepsState(k)), k.String())
+		}
+	})
+})
+
 var _ = Describe("Housekeeping", func() {
 	var (
 		ctx       context.Context
@@ -93,32 +106,54 @@ var _ = Describe("Housekeeping", func() {
 
 	Describe("Fingerprint", func() {
 		It("changes when a fingerprint-affecting config value changes", func() {
-			f1 := fingerprint()
+			f1 := ConfigFingerprint()
 			conf.Server.CoverArtPriority = "folder, embedded"
-			f2 := fingerprint()
+			f2 := ConfigFingerprint()
 			Expect(f1).NotTo(Equal(f2))
 		})
 
 		It("changes when ArtistImageFolder changes", func() {
 			conf.Server.ArtistImageFolder = "/before"
-			f1 := fingerprint()
+			f1 := ConfigFingerprint()
 			conf.Server.ArtistImageFolder = "/after"
-			Expect(fingerprint()).NotTo(Equal(f1))
+			Expect(ConfigFingerprint()).NotTo(Equal(f1))
 		})
 
 		It("changes when EnableM3UExternalAlbumArt is toggled", func() {
 			conf.Server.EnableM3UExternalAlbumArt = false
-			f1 := fingerprint()
+			f1 := ConfigFingerprint()
 			conf.Server.EnableM3UExternalAlbumArt = true
-			Expect(fingerprint()).NotTo(Equal(f1))
+			Expect(ConfigFingerprint()).NotTo(Equal(f1))
+		})
+
+		// Pinned: a changed formula re-resolves every library on upgrade, flooding external providers.
+		It("hashes a given config to a stable value", func() {
+			conf.Server.CoverArtPriority = "cover.*, embedded"
+			conf.Server.ArtistArtPriority = "artist.*, external"
+			conf.Server.ArtistImageFolder = ""
+			conf.Server.Agents = "lastfm,spotify"
+			conf.Server.EnableExternalServices = true
+			conf.Server.EnableM3UExternalAlbumArt = false
+
+			Expect(ConfigFingerprint()).To(Equal("7e537a22febc07d3d5ca40546e88da54"))
+		})
+
+		It("reports the config inputs it hashes, so a change can be traced to a setting", func() {
+			conf.Server.Agents = "lastfm,spotify"
+			conf.Server.CoverArtPriority = "cover.*, embedded"
+
+			Expect(FingerprintInputs()).To(ContainElements(
+				FingerprintInput{Name: "Agents", Value: "lastfm,spotify"},
+				FingerprintInput{Name: "CoverArtPriority", Value: "cover.*, embedded"},
+			))
 		})
 
 		It("does not change when the server version changes", func() {
 			original := consts.Version
 			DeferCleanup(func() { consts.Version = original })
-			f1 := fingerprint()
+			f1 := ConfigFingerprint()
 			consts.Version = original + "-next"
-			Expect(fingerprint()).To(Equal(f1),
+			Expect(ConfigFingerprint()).To(Equal(f1),
 				"the version must not invalidate artwork state: it would re-resolve every entity on every build")
 		})
 	})
@@ -126,7 +161,7 @@ var _ = Describe("Housekeeping", func() {
 	Describe("Backfill", func() {
 		It("enqueues nothing and returns false when the stored fingerprint matches", func() {
 			seedEntities()
-			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, fingerprint())).To(Succeed())
+			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, ConfigFingerprint())).To(Succeed())
 
 			did, err := backfill(ctx, ds)
 			Expect(err).ToNot(HaveOccurred())
@@ -150,7 +185,7 @@ var _ = Describe("Housekeeping", func() {
 
 			stored, err := propRepo.Get(consts.ArtConfFingerprintPropertyKey)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(stored).To(Equal(fingerprint()))
+			Expect(stored).To(Equal(ConfigFingerprint()))
 		})
 
 		It("enqueues a private playlist by resolving it under an admin context", func() {
diff --git a/core/artwork/image_cache.go b/core/artwork/image_cache.go
index 39938a755..b1970d21d 100644
--- a/core/artwork/image_cache.go
+++ b/core/artwork/image_cache.go
@@ -55,6 +55,10 @@ func (r *resizedItem) Reader(ctx context.Context) (io.ReadCloser, error) {
 	if err != nil {
 		return nil, err
 	}
+	// An open() that reports "no image" as a nil reader would otherwise panic on the Close below.
+	if orig == nil {
+		return nil, ErrUnavailable
+	}
 	defer orig.Close()
 	data, err := readCapped(orig)
 	if err != nil {
diff --git a/core/artwork/image_cache_test.go b/core/artwork/image_cache_test.go
new file mode 100644
index 000000000..a74c51088
--- /dev/null
+++ b/core/artwork/image_cache_test.go
@@ -0,0 +1,41 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("resizedItem", func() {
+	Describe("Reader", func() {
+		newItem := func(open func() (io.ReadCloser, error)) *resizedItem {
+			return &resizedItem{hash: "abc123", size: 300, open: open}
+		}
+
+		It("reports a nil reader as unavailable instead of panicking on it", func() {
+			// Every caller is expected to report "no image" as an error, but a nil reader reaches
+			// the deferred Close as a nil interface, which takes the whole request down.
+			_, err := newItem(func() (io.ReadCloser, error) { return nil, nil }).Reader(context.Background())
+			Expect(err).To(MatchError(ErrUnavailable))
+		})
+
+		It("propagates the open error", func() {
+			boom := errors.New("boom")
+			_, err := newItem(func() (io.ReadCloser, error) { return nil, boom }).Reader(context.Background())
+			Expect(err).To(MatchError(boom))
+		})
+
+		It("serves the original bytes when they cannot be resized", func() {
+			rc, err := newItem(func() (io.ReadCloser, error) {
+				return io.NopCloser(strings.NewReader("not an image")), nil
+			}).Reader(context.Background())
+			Expect(err).ToNot(HaveOccurred())
+			defer rc.Close()
+			Expect(io.ReadAll(rc)).To(Equal([]byte("not an image")))
+		})
+	})
+})
diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
index 11711469d..518b6e100 100644
--- a/core/artwork/resolve.go
+++ b/core/artwork/resolve.go
@@ -34,18 +34,31 @@ type resolution struct {
 
 // chainState carries what a priority walk has seen so far. A hit takes extErr with it so a
 // transient external failure still retries; localErr is dropped, as the scanner re-lists changes.
-type chainState struct{ extErr, localErr bool }
+type chainState struct {
+	extErr, localErr bool
+	trace            *ChainTrace // nil unless the CLI asked for a trace
+}
 
 // try stamps the accumulated external failure onto a hit, and records the miss otherwise.
-func (c *chainState) try(res resolution, ok bool) (resolution, bool) {
+func (c *chainState) try(candidate string, res resolution, ok bool) (resolution, bool) {
 	if ok {
 		res.extError = c.extErr
+		c.record(candidate, OutcomeHit, res.sourcePath)
 		return res, true
 	}
 	c.localErr = c.localErr || res.localError
+	if res.localError {
+		c.record(candidate, OutcomeUnreadable, "")
+	} else {
+		c.record(candidate, OutcomeMiss, "")
+	}
 	return resolution{}, false
 }
 
+func (c *chainState) record(candidate string, out Outcome, detail string) {
+	c.trace.add(TraceStep{Candidate: candidate, Outcome: out, Detail: detail})
+}
+
 // exhausted is the outcome when no source in the chain yielded an image.
 func (c *chainState) exhausted() resolution {
 	return resolution{extError: c.extErr, localError: c.localErr}
@@ -95,8 +108,69 @@ func (r *resolver) resolve(ctx context.Context, item model.ArtworkQueueItem) (re
 	}
 }
 
-// fetchExternalAlbum and fetchExternalArtist are the only places resolution touches the network,
-// so a local-only resolver is stopped here rather than at each point in the chain walk.
+// Explainable reports whether TracingResolver can walk this kind's sources and report which one
+// won; playlists and radios resolve from a fixed internal order, with nothing configured to explain.
+func Explainable(kind model.Kind) bool {
+	switch kind {
+	case model.KindArtistArtwork, model.KindAlbumArtwork, model.KindDiscArtwork, model.KindMediaFileArtwork:
+		return true
+	}
+	return false
+}
+
+// MayFetchExternal reports whether resolving this kind can issue an external request under the
+// current config. Playlists inherit the album chain: the generated grid resolves album art.
+func MayFetchExternal(kind model.Kind) bool {
+	switch kind {
+	case model.KindArtistArtwork:
+		return chainFetchesExternal(conf.Server.ArtistArtPriority)
+	case model.KindAlbumArtwork:
+		return chainFetchesExternal(conf.Server.CoverArtPriority)
+	case model.KindPlaylistArtwork:
+		return conf.Server.EnableM3UExternalAlbumArt || chainFetchesExternal(conf.Server.CoverArtPriority)
+	default:
+		return false
+	}
+}
+
+// ImageAgentCount is how many enabled agents provide artist and album images.
+type ImageAgentCount struct{ Artist, Album int }
+
+// ExternalLookupsPerItem reports what resolving one item of this kind can cost: every image agent is
+// tried, and a zero count still bills one, so agents the caller cannot see never read as free.
+func ExternalLookupsPerItem(kind model.Kind, agents ImageAgentCount) int64 {
+	if !MayFetchExternal(kind) {
+		return 0
+	}
+	switch kind {
+	case model.KindArtistArtwork:
+		return int64(max(agents.Artist, 1))
+	case model.KindAlbumArtwork:
+		return int64(max(agents.Album, 1))
+	case model.KindPlaylistArtwork:
+		var n int64
+		if conf.Server.EnableM3UExternalAlbumArt {
+			n++
+		}
+		if chainFetchesExternal(conf.Server.CoverArtPriority) {
+			n += PlaylistGridSamples * int64(max(agents.Album, 1))
+		}
+		return n
+	}
+	return 0
+}
+
+func chainFetchesExternal(priority string) bool {
+	for pattern := range strings.SplitSeq(strings.ToLower(priority), ",") {
+		if strings.TrimSpace(pattern) == externalCandidate {
+			return true
+		}
+	}
+	return false
+}
+
+// Album and artist fetches stop here when the resolver is local-only, rather than at each point in
+// the chain walk; resolvePlaylist gates the third network path, the m3u image URL, itself.
 func (r *resolver) fetchExternalAlbum(ctx context.Context, al model.Album) (io.ReadCloser, string, bool) {
 	if r.ext == nil {
 		return nil, "", false
@@ -126,24 +200,31 @@ func (r *resolver) resolveAlbum(ctx context.Context, albumID string) (resolution
 		return resolution{}, err
 	}
 
-	var chain chainState
+	chain := chainState{trace: traceFrom(ctx)}
 	for pattern := range strings.SplitSeq(strings.ToLower(conf.Server.CoverArtPriority), ",") {
 		pattern = strings.TrimSpace(pattern)
+		if pattern == "" {
+			continue
+		}
 		switch {
 		case pattern == "embedded":
-			if res, ok := chain.try(resolveEmbedded(ctx, lib, r.ffmpeg, al.EmbedArtPath)); ok {
+			res, ok := resolveEmbedded(ctx, lib, r.ffmpeg, al.EmbedArtPath)
+			if res, ok = chain.try(pattern, res, ok); ok {
 				return res, nil
 			}
-		case pattern == "external":
+		case pattern == externalCandidate:
 			if rd, name, isErr := r.fetchExternalAlbum(ctx, *al); rd != nil {
-				return resolution{reader: rd, source: "external:" + name}, nil
+				return resolution{reader: rd, source: ExternalPrefix + name}, nil
 			} else if isErr {
 				chain.extErr = true
 			}
 		case len(imgFiles) > 0:
-			if res, ok := chain.try(resolveFolderFile(ctx, lib, imgFiles, pattern)); ok {
+			res, ok := resolveFolderFile(ctx, lib, imgFiles, pattern)
+			if res, ok = chain.try(pattern, res, ok); ok {
 				return res, nil
 			}
+		default:
+			chain.record(pattern, OutcomeSkipped, "no images in album folder")
 		}
 	}
 	return chain.exhausted(), nil
@@ -155,9 +236,10 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resoluti
 	if err != nil {
 		return resolution{}, err
 	}
-	upload, ok := resolveLocalFile(ar.UploadedImagePath(), "upload")
-	if ok {
-		return upload, nil
+	chain := chainState{trace: traceFrom(ctx)}
+	upload, uploadOK := resolveLocalFile(ar.UploadedImagePath(), "upload")
+	if res, ok := chain.try("upload", upload, uploadOK); ok {
+		return res, nil
 	}
 	if upload.localError {
 		// The upload outranks every other source; falling through would persist a lower-priority
@@ -191,32 +273,43 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resoluti
 		}
 	}
 
-	var chain chainState
 	for pattern := range strings.SplitSeq(strings.ToLower(conf.Server.ArtistArtPriority), ",") {
 		pattern = strings.TrimSpace(pattern)
+		if pattern == "" {
+			continue
+		}
 		switch {
-		case pattern == "external":
+		case pattern == externalCandidate:
 			if rd, name, isErr := r.fetchExternalArtist(ctx, *ar); rd != nil {
-				return resolution{reader: rd, source: "external:" + name}, nil
+				return resolution{reader: rd, source: ExternalPrefix + name}, nil
 			} else if isErr {
 				chain.extErr = true
 			}
 		case pattern == "image-folder":
-			if res, ok := chain.try(resolveArtistImageFolder(ar)); ok {
+			res, ok := resolveArtistImageFolder(ar)
+			if res, ok = chain.try(pattern, res, ok); ok {
 				return res, nil
 			}
 		case strings.HasPrefix(pattern, "album/"):
 			if lib.FS == nil {
+				chain.record(pattern, OutcomeSkipped, "artist has no albums")
 				continue
 			}
-			if res, ok := chain.try(resolveFolderFile(ctx, lib, imgFiles, strings.TrimPrefix(pattern, "album/"))); ok {
+			res, ok := resolveFolderFile(ctx, lib, imgFiles, strings.TrimPrefix(pattern, "album/"))
+			if res, ok = chain.try(pattern, res, ok); ok {
 				return res, nil
 			}
 		default:
-			if lib.FS == nil || artistFolder == "" {
+			if lib.FS == nil {
+				chain.record(pattern, OutcomeSkipped, "artist has no albums")
 				continue
 			}
-			if res, ok := chain.try(resolveArtistFolderPattern(ctx, lib, artistFolder, pattern)); ok {
+			if artistFolder == "" {
+				chain.record(pattern, OutcomeSkipped, "no artist folder")
+				continue
+			}
+			res, ok := resolveArtistFolderPattern(ctx, lib, artistFolder, pattern)
+			if res, ok = chain.try(pattern, res, ok); ok {
 				return res, nil
 			}
 		}
@@ -224,6 +317,9 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resoluti
 	return chain.exhausted(), nil
 }
 
+// PlaylistGridSamples is how many albums resolvePlaylist samples to build the generated grid.
+const PlaylistGridSamples = 4
+
 // resolvePlaylist tries the uploaded image, the sidecar and ExternalImageURL, then a generated grid.
 func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (resolution, error) {
 	pl, err := r.ds.Playlist(ctx).Get(playlistID)
@@ -269,7 +365,8 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 		}
 	}
 
-	albumIDs, err := r.ds.Playlist(ctx).Tracks(pl.ID, false).GetAlbumIDs(model.QueryOptions{Max: 4, Sort: "random()"})
+	albumIDs, err := r.ds.Playlist(ctx).Tracks(pl.ID, false).
+		GetAlbumIDs(model.QueryOptions{Max: PlaylistGridSamples, Sort: "random()"})
 	if err != nil {
 		return resolution{}, err
 	}
@@ -295,7 +392,7 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 		if decErr == nil {
 			tiles = append(tiles, tile)
 		}
-		if len(tiles) == 4 {
+		if len(tiles) == PlaylistGridSamples {
 			break
 		}
 	}
@@ -337,15 +434,35 @@ func (r *resolver) resolveMediaFile(ctx context.Context, id string) (resolution,
 	if err != nil {
 		return resolution{}, err
 	}
-	if !conf.Server.EnableMediaFileCoverArt || !mf.HasCoverArt {
+	chain := chainState{trace: traceFrom(ctx)}
+	switch {
+	case !conf.Server.EnableMediaFileCoverArt:
+		chain.record("embedded", OutcomeSkipped, "EnableMediaFileCoverArt is off")
+		return resolution{}, nil
+	case !mf.HasCoverArt:
+		chain.record("embedded", OutcomeMiss, "the track has no embedded cover art")
 		return resolution{}, nil
 	}
 	lib, err := loadLibraryView(ctx, r.ds, mf.LibraryID)
 	if err != nil {
 		return resolution{}, err
 	}
-	res, _ := resolveEmbedded(ctx, lib, r.ffmpeg, mf.Path)
-	return res, nil
+	res, ok := resolveEmbedded(ctx, lib, r.ffmpeg, mf.Path)
+	if res, ok = chain.try("embedded", res, ok); ok {
+		return res, nil
+	}
+	return chain.exhausted(), nil
+}
+
+// resolveDisc walks conf.Server.DiscArtPriority. Disc artwork keeps no state row and is never
+// queued: the serving path reads it through on every request, so this only ever explains.
+func (r *resolver) resolveDisc(ctx context.Context, id string) (resolution, error) {
+	dr, err := newDiscArtworkReader(ctx, r.ds, model.ArtworkID{Kind: model.KindDiscArtwork, ID: id})
+	if err != nil {
+		return resolution{}, err
+	}
+	chain := chainState{trace: traceFrom(ctx)}
+	return dr.selectImage(ctx, r.ffmpeg, conf.Server.DiscArtPriority, &chain)
 }
 
 // resolveExternalStep runs a single external sourceFunc through the named gate. extErr excludes
@@ -353,7 +470,7 @@ func (r *resolver) resolveMediaFile(ctx context.Context, id string) (resolution,
 func resolveExternalStep(gate gateFunc, name string, sf sourceFunc) (res resolution, ok bool, extErr bool) {
 	r, path, err := gate(name, sf)
 	if r != nil {
-		return resolution{reader: r, source: "external", sourcePath: path}, true, false
+		return resolution{reader: r, source: externalCandidate, sourcePath: path}, true, false
 	}
 	return resolution{}, false, err != nil && !errors.Is(err, model.ErrNotFound)
 }
@@ -394,14 +511,20 @@ func resolveEmbedded(ctx context.Context, lib libraryView, ffm ffmpeg.FFmpeg, em
 	return resolution{localError: unreadable}, false
 }
 
-func resolveFolderFile(ctx context.Context, lib libraryView, imgFiles []string, pattern string) (resolution, bool) {
-	r, path, err := fromExternalFile(ctx, lib.FS, imgFiles, pattern)()
+// resolveFolderSource turns a source that yields a library-relative image path into a folder
+// resolution, keeping an existing-but-unopenable file distinct from an absent one.
+func resolveFolderSource(lib libraryView, sf sourceFunc) (resolution, bool) {
+	r, path, err := sf()
 	if r == nil {
 		return resolution{localError: errors.Is(err, errSourceUnreadable)}, false
 	}
 	return resolution{reader: r, source: "folder", sourcePath: lib.Abs(path), refMtime: mtimeViaFS(lib.FS, path)}, true
 }
 
+func resolveFolderFile(ctx context.Context, lib libraryView, imgFiles []string, pattern string) (resolution, bool) {
+	return resolveFolderSource(lib, fromExternalFile(ctx, lib.FS, imgFiles, pattern))
+}
+
 func resolveArtistImageFolder(ar *model.Artist) (resolution, bool) {
 	folder := conf.Server.ArtistImageFolder
 	if folder == "" {
diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.go
index 9a0962cf2..25fb727de 100644
--- a/core/artwork/resolve_test.go
+++ b/core/artwork/resolve_test.go
@@ -394,6 +394,28 @@ var _ = Describe("resolveItem", func() {
 			Entry("4 albums -> full grid", []string{"t1", "t2", "t3", "t4"}, tileSize-1),
 		)
 
+		// The grid samples album art through the full album chain, so a playlist reaches the
+		// network even with the m3u fetch off.
+		It("calls the album image agents for its grid tiles when m3u art is disabled", func() {
+			conf.Server.EnableM3UExternalAlbumArt = false
+			conf.Server.CoverArtPriority = "external"
+			folderRepo.result = nil
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "plgrid", Name: "Playlist"}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1", "t2"}}
+			ds.MockedPlaylist = plRepo
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("boom")})
+			var gatedNames []string
+			gate := func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+				gatedNames = append(gatedNames, name)
+				return f()
+			}
+
+			_, err := newResolver(ds, ag, ffm, gate).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plgrid"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(gatedNames).To(Equal([]string{"failAgent", "failAgent"}), "one lookup per sampled album")
+		})
+
 		It("resolves the uploaded image before the generated grid", func() {
 			tmpDir := GinkgoT().TempDir()
 			conf.Server.DataFolder = conf.NewDir(tmpDir)
@@ -630,3 +652,110 @@ var _ = Describe("decodeTile", func() {
 		Expect(err).To(HaveOccurred())
 	})
 })
+
+var _ = Describe("Explainable", func() {
+	It("is true for the kinds the resolver walks", func() {
+		Expect(Explainable(model.KindArtistArtwork)).To(BeTrue())
+		Expect(Explainable(model.KindAlbumArtwork)).To(BeTrue())
+		Expect(Explainable(model.KindDiscArtwork)).To(BeTrue())
+		Expect(Explainable(model.KindMediaFileArtwork)).To(BeTrue())
+	})
+
+	It("is false for the kinds resolved from a fixed internal order", func() {
+		Expect(Explainable(model.KindPlaylistArtwork)).To(BeFalse())
+		Expect(Explainable(model.KindRadioArtwork)).To(BeFalse())
+	})
+})
+
+var _ = Describe("MayFetchExternal", func() {
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.CoverArtPriority = "cover.*, embedded"
+		conf.Server.ArtistArtPriority = "artist.*"
+		conf.Server.EnableM3UExternalAlbumArt = false
+	})
+
+	It("is true for the kinds whose chain includes the external candidate", func() {
+		conf.Server.CoverArtPriority = "cover.*, external"
+		conf.Server.ArtistArtPriority = "artist.*, external"
+		Expect(MayFetchExternal(model.KindAlbumArtwork)).To(BeTrue())
+		Expect(MayFetchExternal(model.KindArtistArtwork)).To(BeTrue())
+	})
+
+	It("is false for a chain with no external candidate", func() {
+		Expect(MayFetchExternal(model.KindAlbumArtwork)).To(BeFalse())
+		Expect(MayFetchExternal(model.KindArtistArtwork)).To(BeFalse())
+	})
+
+	It("is true for playlists when the m3u image fetch is enabled", func() {
+		conf.Server.EnableM3UExternalAlbumArt = true
+		Expect(MayFetchExternal(model.KindPlaylistArtwork)).To(BeTrue())
+	})
+
+	It("is true for playlists whose grid tiles resolve through an external album chain", func() {
+		conf.Server.CoverArtPriority = "cover.*, external"
+		Expect(MayFetchExternal(model.KindPlaylistArtwork)).To(BeTrue())
+	})
+
+	It("is false for playlists with both paths off", func() {
+		Expect(MayFetchExternal(model.KindPlaylistArtwork)).To(BeFalse())
+	})
+
+	It("is false for the kinds that only read local files", func() {
+		conf.Server.CoverArtPriority = "external"
+		conf.Server.ArtistArtPriority = "external"
+		conf.Server.EnableM3UExternalAlbumArt = true
+		Expect(MayFetchExternal(model.KindRadioArtwork)).To(BeFalse())
+		Expect(MayFetchExternal(model.KindMediaFileArtwork)).To(BeFalse())
+	})
+})
+
+var _ = Describe("ExternalLookupsPerItem", func() {
+	count := ImageAgentCount{Artist: 3, Album: 2}
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.CoverArtPriority = "cover.*, external"
+		conf.Server.ArtistArtPriority = "artist.*, external"
+		conf.Server.EnableM3UExternalAlbumArt = false
+	})
+
+	It("bills one call per agent, since the walk only stops early on a hit", func() {
+		Expect(ExternalLookupsPerItem(model.KindArtistArtwork, count)).To(Equal(int64(3)))
+		Expect(ExternalLookupsPerItem(model.KindAlbumArtwork, count)).To(Equal(int64(2)))
+	})
+
+	It("bills a playlist for every album its grid samples", func() {
+		Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, count)).
+			To(Equal(int64(PlaylistGridSamples) * 2))
+	})
+
+	It("adds the m3u image fetch on top of the grid", func() {
+		conf.Server.EnableM3UExternalAlbumArt = true
+		Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, count)).
+			To(Equal(int64(PlaylistGridSamples)*2 + 1))
+	})
+
+	It("bills only the m3u fetch when the album chain stays local", func() {
+		conf.Server.CoverArtPriority = "cover.*"
+		conf.Server.EnableM3UExternalAlbumArt = true
+		Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, count)).To(Equal(int64(1)))
+	})
+
+	It("still bills a call when no agent is visible, which plugins never are offline", func() {
+		none := ImageAgentCount{}
+		Expect(ExternalLookupsPerItem(model.KindArtistArtwork, none)).To(Equal(int64(1)))
+		Expect(ExternalLookupsPerItem(model.KindAlbumArtwork, none)).To(Equal(int64(1)))
+		Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, none)).
+			To(Equal(int64(PlaylistGridSamples)))
+	})
+
+	It("is zero whenever the kind reaches no agent at all", func() {
+		conf.Server.CoverArtPriority = "cover.*"
+		conf.Server.ArtistArtPriority = "artist.*"
+		Expect(ExternalLookupsPerItem(model.KindArtistArtwork, count)).To(BeZero())
+		Expect(ExternalLookupsPerItem(model.KindAlbumArtwork, count)).To(BeZero())
+		Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, count)).To(BeZero())
+		Expect(ExternalLookupsPerItem(model.KindRadioArtwork, count)).To(BeZero())
+	})
+})
diff --git a/core/artwork/sources.go b/core/artwork/sources.go
index 885ca03cf..78b7dd68d 100644
--- a/core/artwork/sources.go
+++ b/core/artwork/sources.go
@@ -27,23 +27,6 @@ import (
 // to open it is not evidence the entity has no artwork, so callers must not settle on absent.
 var errSourceUnreadable = errors.New("artwork source unreadable")
 
-func selectImageReader(ctx context.Context, artID model.ArtworkID, extractFuncs ...sourceFunc) (io.ReadCloser, string, error) {
-	for _, f := range extractFuncs {
-		if ctx.Err() != nil {
-			return nil, "", ctx.Err()
-		}
-		start := time.Now()
-		r, path, err := f()
-		if r != nil {
-			msg := fmt.Sprintf("Artwork: Found %s artwork", artID.Kind)
-			log.Debug(ctx, msg, "artID", artID, "path", path, "source", f, "elapsed", time.Since(start))
-			return r, path, nil
-		}
-		log.Trace(ctx, "Artwork: Failed trying to extract artwork", "artID", artID, "source", f, "elapsed", time.Since(start), err)
-	}
-	return nil, "", fmt.Errorf("could not get `%s` cover art for %s: %w", artID.Kind, artID, ErrUnavailable)
-}
-
 type sourceFunc func() (r io.ReadCloser, path string, err error)
 
 func (f sourceFunc) String() string {
diff --git a/core/artwork/trace.go b/core/artwork/trace.go
new file mode 100644
index 000000000..5d02fa4ff
--- /dev/null
+++ b/core/artwork/trace.go
@@ -0,0 +1,99 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"io"
+	"slices"
+	"sync"
+)
+
+// Outcome is what the priority chain observed for one candidate; the CLI renders and branches on these.
+type Outcome string
+
+const (
+	OutcomeHit        Outcome = "hit"
+	OutcomeMiss       Outcome = "miss"
+	OutcomeUnreadable Outcome = "unreadable"
+	OutcomeSkipped    Outcome = "skipped"
+	OutcomeWouldTry   Outcome = "would-try"
+	OutcomeError      Outcome = "error"
+)
+
+const (
+	// externalCandidate labels the external tier itself, for the cases that never reach an agent.
+	externalCandidate = "external"
+	// ExternalPrefix qualifies a candidate or a stored source with the agent that produced it.
+	ExternalPrefix = externalCandidate + ":"
+)
+
+// TraceStep is one candidate the priority chain considered.
+type TraceStep struct {
+	Candidate string
+	Outcome   Outcome
+	Detail    string
+}
+
+// ChainTrace collects the walk of a single resolution. The artwork worker never attaches
+// one; only the CLI does, so resolution stays allocation-free in the hot path.
+type ChainTrace struct {
+	mu    sync.Mutex
+	steps []TraceStep
+}
+
+func (t *ChainTrace) add(step TraceStep) {
+	if t == nil {
+		return
+	}
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.steps = append(t.steps, step)
+}
+
+func (t *ChainTrace) Steps() []TraceStep {
+	if t == nil {
+		return nil
+	}
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return slices.Clone(t.steps)
+}
+
+type traceCtxKey struct{}
+
+func withTrace(ctx context.Context, t *ChainTrace) context.Context {
+	return context.WithValue(ctx, traceCtxKey{}, t)
+}
+
+func traceFrom(ctx context.Context) *ChainTrace {
+	t, _ := ctx.Value(traceCtxKey{}).(*ChainTrace)
+	return t
+}
+
+var errOfflineSkipped = errors.New("artwork: external lookup skipped (offline)")
+
+// tracingGate records each external agent's outcome without changing what the gate returns.
+func tracingGate(t *ChainTrace, inner gateFunc) gateFunc {
+	return func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+		r, path, err := inner(name, f)
+		candidate := ExternalPrefix + name
+		switch {
+		case r != nil:
+			t.add(TraceStep{Candidate: candidate, Outcome: OutcomeHit, Detail: path})
+		case isTransientExternal(err):
+			t.add(TraceStep{Candidate: candidate, Outcome: OutcomeError, Detail: err.Error()})
+		default:
+			t.add(TraceStep{Candidate: candidate, Outcome: OutcomeMiss})
+		}
+		return r, path, err
+	}
+}
+
+// offlineGate reports which agents would be asked without asking them, so a diagnostic
+// command cannot add load to a provider that is already rate-limiting us.
+func offlineGate(t *ChainTrace) gateFunc {
+	return func(name string, _ func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+		t.add(TraceStep{Candidate: ExternalPrefix + name, Outcome: OutcomeWouldTry})
+		return nil, "", errOfflineSkipped
+	}
+}
diff --git a/core/artwork/trace_test.go b/core/artwork/trace_test.go
new file mode 100644
index 000000000..5a54c9e91
--- /dev/null
+++ b/core/artwork/trace_test.go
@@ -0,0 +1,628 @@
+package artwork
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("trace vocabulary", func() {
+	// The CLI renders these verbatim and branches on them; a value change is a change to
+	// what `artwork explain` tells an operator, so it must be made deliberately.
+	It("pins the wire values the CLI reads", func() {
+		Expect([]Outcome{
+			OutcomeHit, OutcomeMiss, OutcomeUnreadable, OutcomeSkipped, OutcomeWouldTry, OutcomeError,
+		}).To(Equal([]Outcome{"hit", "miss", "unreadable", "skipped", "would-try", "error"}))
+		Expect(externalCandidate).To(Equal("external"))
+		Expect(ExternalPrefix).To(Equal("external:"))
+	})
+})
+
+var _ = Describe("chainTrace", func() {
+	It("returns nil when no trace is attached", func() {
+		Expect(traceFrom(context.Background())).To(BeNil())
+	})
+
+	It("collects steps in order", func() {
+		t := &ChainTrace{}
+		ctx := withTrace(context.Background(), t)
+
+		traceFrom(ctx).add(TraceStep{Candidate: "cover.*", Outcome: OutcomeMiss})
+		traceFrom(ctx).add(TraceStep{Candidate: "embedded", Outcome: OutcomeHit, Detail: "/music/a.flac"})
+
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "cover.*", Outcome: OutcomeMiss},
+			{Candidate: "embedded", Outcome: OutcomeHit, Detail: "/music/a.flac"},
+		}))
+
+		s := t.Steps()
+		s[0].Candidate = "mutated"
+		Expect(t.Steps()[0].Candidate).To(Equal("cover.*"))
+	})
+
+	It("does not panic when the trace is nil", func() {
+		var t *ChainTrace
+		Expect(func() { t.add(TraceStep{Candidate: "cover.*", Outcome: OutcomeMiss}) }).ToNot(Panic())
+		Expect(t.Steps()).To(BeEmpty(), "a nil trace collects nothing, so reading it must be as safe as writing it")
+	})
+
+	It("is safe to use concurrently", func() {
+		t := &ChainTrace{}
+		done := make(chan struct{})
+		for range 10 {
+			go func() {
+				defer GinkgoRecover()
+				t.add(TraceStep{Candidate: "x", Outcome: OutcomeMiss})
+				done <- struct{}{}
+			}()
+		}
+		for range 10 {
+			<-done
+		}
+		Expect(t.Steps()).To(HaveLen(10))
+	})
+})
+
+var _ = Describe("chainState tracing", func() {
+	It("records a miss when the candidate was absent", func() {
+		t := &ChainTrace{}
+		c := chainState{trace: t}
+
+		_, ok := c.try("cover.*", resolution{}, false)
+
+		Expect(ok).To(BeFalse())
+		Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "cover.*", Outcome: OutcomeMiss}}))
+	})
+
+	It("records unreadable when the candidate existed but could not be read", func() {
+		t := &ChainTrace{}
+		c := chainState{trace: t}
+
+		_, ok := c.try("cover.*", resolution{localError: true}, false)
+
+		Expect(ok).To(BeFalse())
+		Expect(t.Steps()).To(HaveLen(1))
+		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeUnreadable),
+			"a candidate that existed and failed to decode must be distinguishable from one that was absent")
+	})
+
+	It("records a hit with the backing path", func() {
+		t := &ChainTrace{}
+		c := chainState{trace: t}
+
+		res, ok := c.try("embedded", resolution{reader: nil, source: "embedded", sourcePath: "/music/a.flac"}, true)
+
+		Expect(ok).To(BeTrue())
+		Expect(res.source).To(Equal("embedded"))
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "embedded", Outcome: OutcomeHit, Detail: "/music/a.flac"},
+		}))
+	})
+})
+
+var _ = Describe("external gate tracing", func() {
+	hit := func() (io.ReadCloser, string, error) {
+		return io.NopCloser(strings.NewReader("x")), "http://img", nil
+	}
+	miss := func() (io.ReadCloser, string, error) { return nil, "", agents.ErrNotFound }
+	boom := func() (io.ReadCloser, string, error) { return nil, "", errors.New("returned status 429") }
+
+	It("records a hit with the image path", func() {
+		t := &ChainTrace{}
+		g := tracingGate(t, passthroughGate)
+
+		r, _, err := g("deezer", hit)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(r).ToNot(BeNil())
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "external:deezer", Outcome: OutcomeHit, Detail: "http://img"},
+		}))
+	})
+
+	It("records a miss for a not-found", func() {
+		t := &ChainTrace{}
+		_, _, _ = tracingGate(t, passthroughGate)("deezer", miss)
+		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeMiss))
+	})
+
+	It("records a miss for a model not-found", func() {
+		t := &ChainTrace{}
+		notFound := func() (io.ReadCloser, string, error) { return nil, "", model.ErrNotFound }
+		_, _, _ = tracingGate(t, passthroughGate)("deezer", notFound)
+		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeMiss),
+			"both not-found flavours are definitive answers, not faults")
+	})
+
+	It("records an error with its reason", func() {
+		t := &ChainTrace{}
+		_, _, _ = tracingGate(t, passthroughGate)("apple-music", boom)
+		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeError))
+		Expect(t.Steps()[0].Detail).To(ContainSubstring("429"))
+	})
+
+	It("never calls the agent in offline mode", func() {
+		t := &ChainTrace{}
+		called := false
+		counting := func() (io.ReadCloser, string, error) {
+			called = true
+			return hit()
+		}
+
+		_, _, err := offlineGate(t)("deezer", counting)
+
+		Expect(called).To(BeFalse(), "offline mode must not perform external requests")
+		Expect(err).To(MatchError(errOfflineSkipped))
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "external:deezer", Outcome: OutcomeWouldTry},
+		}))
+	})
+})
+
+var _ = Describe("resolveAlbum tracing", func() {
+	var (
+		ctx        context.Context
+		ds         *tests.MockDataStore
+		albumRepo  *tests.MockAlbumRepo
+		folderRepo *fakeFolderRepo
+		ffm        *tests.MockFFmpeg
+		ag         *agents.Agents
+		t          *ChainTrace
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.CoverArtPriority = "cover.jpg, embedded"
+		repoRoot, err := os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		libRepo := &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		albumRepo = tests.CreateMockAlbumRepo()
+		folderRepo = &fakeFolderRepo{}
+		ds = &tests.MockDataStore{
+			MockedAlbum:   albumRepo,
+			MockedFolder:  folderRepo,
+			MockedLibrary: libRepo,
+		}
+		ffm = tests.NewMockFFmpeg("")
+		ag = agents.GetAgents(&tests.MockDataStore{}, nil)
+		t = &ChainTrace{}
+		ctx = withTrace(context.Background(), t)
+	})
+
+	It("records a pattern skipped because the album folder holds no images", func() {
+		albumRepo.SetData(model.Albums{
+			{ID: "al1", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},
+		})
+
+		res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(res.reader).ToNot(BeNil())
+		defer res.reader.Close()
+		Expect(t.Steps()).To(HaveLen(2), "a configured pattern must appear even when the chain never evaluated it")
+		Expect(t.Steps()[0]).To(Equal(TraceStep{
+			Candidate: "cover.jpg", Outcome: OutcomeSkipped, Detail: "no images in album folder",
+		}))
+		Expect(t.Steps()[1].Candidate).To(Equal("embedded"))
+		Expect(t.Steps()[1].Outcome).To(Equal(OutcomeHit))
+	})
+
+	It("records an evaluated pattern that matched nothing as a miss, not a skip", func() {
+		folderRepo.result = []model.Folder{{
+			Path:       "tests/fixtures/artist/an-album",
+			ImageFiles: []string{"artist.png"},
+		}}
+		albumRepo.SetData(model.Albums{
+			{ID: "al3", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},
+		})
+
+		res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(res.reader).ToNot(BeNil())
+		defer res.reader.Close()
+		Expect(t.Steps()[0]).To(Equal(TraceStep{Candidate: "cover.jpg", Outcome: OutcomeMiss}),
+			"the folder was searched and held no cover.jpg, which is not the same as never looking")
+	})
+
+	It("ignores an empty priority token", func() {
+		conf.Server.CoverArtPriority = "cover.jpg,"
+		albumRepo.SetData(model.Albums{{ID: "al2", Name: "Album", FolderIDs: []string{"f1"}}})
+
+		_, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "cover.jpg", Outcome: OutcomeSkipped, Detail: "no images in album folder"},
+		}))
+	})
+})
+
+var _ = Describe("resolveArtist tracing", func() {
+	var (
+		ctx        context.Context
+		ds         *tests.MockDataStore
+		artistRepo *tests.MockArtistRepo
+		albumRepo  *tests.MockAlbumRepo
+		folderRepo *fakeFolderRepo
+		ffm        *tests.MockFFmpeg
+		ag         *agents.Agents
+		t          *ChainTrace
+		repoRoot   string
+	)
+
+	uploadPath := func(file string) string {
+		path := model.UploadedImagePath(consts.EntityArtist, file)
+		Expect(os.MkdirAll(filepath.Dir(path), 0o755)).To(Succeed())
+		Expect(os.WriteFile(path, []byte("uploaded artist image"), 0o600)).To(Succeed())
+		return path
+	}
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DataFolder = conf.NewDir(GinkgoT().TempDir())
+		conf.Server.ArtistArtPriority = "album/artist.*"
+		var err error
+		repoRoot, err = os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		libRepo := &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		artistRepo = tests.CreateMockArtistRepo()
+		albumRepo = tests.CreateMockAlbumRepo()
+		folderRepo = &fakeFolderRepo{}
+		ds = &tests.MockDataStore{
+			MockedArtist:  artistRepo,
+			MockedAlbum:   albumRepo,
+			MockedFolder:  folderRepo,
+			MockedLibrary: libRepo,
+		}
+		ffm = tests.NewMockFFmpeg("")
+		ag = agents.GetAgents(&tests.MockDataStore{}, nil)
+		t = &ChainTrace{}
+		ctx = withTrace(context.Background(), t)
+	})
+
+	It("records the upload short-circuit as a hit", func() {
+		path := uploadPath("ar1_test.jpg")
+		artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist", UploadedImage: "ar1_test.jpg"}})
+
+		res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar1"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(res.reader).ToNot(BeNil())
+		defer res.reader.Close()
+		Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "upload", Outcome: OutcomeHit, Detail: path}}))
+	})
+
+	It("records an upload miss before walking the chain", func() {
+		artistRepo.SetData(model.Artists{{ID: "ar2", Name: "Artist"}})
+
+		_, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar2"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(t.Steps()[0]).To(Equal(TraceStep{Candidate: "upload", Outcome: OutcomeMiss}))
+	})
+
+	It("labels each step with the configured priority token", func() {
+		folderRepo.result = []model.Folder{{
+			LibraryPath: testFileLibPath(repoRoot),
+			Path:        "tests/fixtures/artist/an-album",
+			ImageFiles:  []string{"artist.png"},
+		}}
+		artistRepo.SetData(model.Artists{{ID: "ar4", Name: "Artist"}})
+		albumRepo.All = model.Albums{{ID: "al9", Name: "Album", LibraryID: 0, FolderIDs: []string{"f1"}}}
+
+		res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar4"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(res.reader).ToNot(BeNil())
+		defer res.reader.Close()
+		Expect(t.Steps()).To(HaveLen(2))
+		Expect(t.Steps()[1].Candidate).To(Equal("album/artist.*"),
+			"the step must be labelled with the priority token, not the pattern it was rewritten into")
+		Expect(t.Steps()[1].Outcome).To(Equal(OutcomeHit))
+		Expect(filepath.ToSlash(t.Steps()[1].Detail)).To(HaveSuffix("tests/fixtures/artist/an-album/artist.png"))
+	})
+
+	It("records a configured pattern that could not be evaluated", func() {
+		artistRepo.SetData(model.Artists{{ID: "ar5", Name: "Artist"}})
+
+		_, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar5"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "upload", Outcome: OutcomeMiss},
+			{Candidate: "album/artist.*", Outcome: OutcomeSkipped, Detail: "artist has no albums"},
+		}), "a configured pattern that was never evaluated must still appear, and say why")
+	})
+
+	It("records why an artist folder pattern was skipped", func() {
+		conf.Server.ArtistArtPriority = "artist.*"
+		artistRepo.SetData(model.Artists{{ID: "ar6", Name: "Artist"}})
+		albumRepo.All = model.Albums{{ID: "al10", Name: "Album", LibraryID: 0, FolderIDs: []string{"f1"}}}
+
+		_, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar6"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "upload", Outcome: OutcomeMiss},
+			{Candidate: "artist.*", Outcome: OutcomeSkipped, Detail: "no artist folder"},
+		}))
+	})
+
+	It("records an upload that exists but cannot be read as unreadable", func() {
+		if runtime.GOOS == "windows" {
+			Skip("chmod does not restrict read access on Windows")
+		}
+		path := uploadPath("ar3_test.jpg")
+		Expect(os.Chmod(path, 0o000)).To(Succeed())
+		DeferCleanup(func() { _ = os.Chmod(path, 0o600) })
+		artistRepo.SetData(model.Artists{{ID: "ar3", Name: "Artist", UploadedImage: "ar3_test.jpg"}})
+
+		_, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar3"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(t.Steps()).To(HaveLen(1))
+		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeUnreadable),
+			"an upload that exists and will not open must not look like an absent upload")
+	})
+})
+
+var _ = Describe("NewTracingResolver", func() {
+	var (
+		ds          *tests.MockDataStore
+		albumRepo   *tests.MockAlbumRepo
+		artistRepo  *tests.MockArtistRepo
+		artworkRepo *tests.MockArtworkRepo
+		queueRepo   *tests.MockArtworkQueueRepo
+		ffm         *tests.MockFFmpeg
+		t           *ChainTrace
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.DataFolder = conf.NewDir(GinkgoT().TempDir())
+		conf.Server.CoverArtPriority = "external, embedded"
+		conf.Server.ArtistArtPriority = "external"
+		repoRoot, err := os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		libRepo := &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		albumRepo = tests.CreateMockAlbumRepo()
+		artistRepo = tests.CreateMockArtistRepo()
+		artworkRepo = tests.CreateMockArtworkRepo()
+		queueRepo = tests.CreateMockArtworkQueueRepo()
+		ds = &tests.MockDataStore{
+			MockedAlbum:        albumRepo,
+			MockedArtist:       artistRepo,
+			MockedFolder:       &fakeFolderRepo{},
+			MockedLibrary:      libRepo,
+			MockedArtwork:      artworkRepo,
+			MockedArtworkQueue: queueRepo,
+		}
+		ffm = tests.NewMockFFmpeg("")
+		t = &ChainTrace{}
+	})
+
+	Context("offline", func() {
+		var fake *fakeImageAgent
+
+		BeforeEach(func() {
+			fake = &fakeImageAgent{name: "offline-probe"}
+			albumRepo.SetData(model.Albums{{
+				ID: "al1", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"},
+			}})
+			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
+		})
+
+		It("reports the external tier without asking any agent", func() {
+			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(source).To(Equal("embedded"))
+			Expect(fake.albumCalls).To(BeZero(), "offline mode must not add load to an external provider")
+			Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:offline-probe", Outcome: OutcomeWouldTry}))
+		})
+
+		It("records the local chain steps too", func() {
+			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
+
+			Expect(err).ToNot(HaveOccurred())
+			last := t.Steps()[len(t.Steps())-1]
+			Expect(last.Candidate).To(Equal("embedded"), "the local chain must be traced, not just the external gate")
+			Expect(last.Outcome).To(Equal(OutcomeHit))
+		})
+
+		It("never persists artwork state", func() {
+			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(artworkRepo.ItemData).To(BeEmpty(),
+				"an offline resolution carries extError, which must never be recorded as a real provider failure")
+			Expect(queueRepo.Data).To(BeEmpty())
+		})
+
+		It("resolves an artist without persisting anything", func() {
+			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindArtistArtwork, "ar1")
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(source).To(BeEmpty())
+			Expect(fake.artistCalls).To(BeZero())
+			Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:offline-probe", Outcome: OutcomeWouldTry}))
+			Expect(artworkRepo.ItemData).To(BeEmpty())
+			Expect(queueRepo.Data).To(BeEmpty())
+		})
+
+		It("closes the reader it does not hand back", func() {
+			conf.Server.CoverArtPriority = "embedded"
+			ffm = tests.NewMockFFmpeg("fake image bytes")
+			albumRepo.SetData(model.Albums{{
+				ID: "al2", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/no-such-file.mp3", FolderIDs: []string{"f1"},
+			}})
+
+			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al2")
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(source).To(Equal("embedded"))
+			Expect(ffm.IsClosed()).To(BeTrue(), "nothing downstream closes it, so a leak is one file handle per invocation")
+		})
+
+		It("propagates a lookup error", func() {
+			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "nope")
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+	})
+
+	It("asks the agents when live is true", func() {
+		fake := &fakeImageAgent{name: "live-probe", err: agents.ErrNotFound}
+		albumRepo.SetData(model.Albums{{
+			ID: "al1", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"},
+		}})
+
+		_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(fake.albumCalls).To(Equal(1))
+		Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:live-probe", Outcome: OutcomeMiss}))
+	})
+})
+
+var _ = Describe("resolveDisc tracing", func() {
+	var (
+		ctx        context.Context
+		ds         *tests.MockDataStore
+		albumRepo  *tests.MockAlbumRepo
+		folderRepo *fakeFolderRepo
+		ffm        *tests.MockFFmpeg
+		t          *ChainTrace
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		repoRoot, err := os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		libRepo := &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		albumRepo = tests.CreateMockAlbumRepo()
+		albumRepo.SetData(model.Albums{{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}}})
+		folderRepo = &fakeFolderRepo{}
+		mfRepo := tests.CreateMockMediaFileRepo()
+		mfRepo.SetData(model.MediaFiles{{ID: "mf1", AlbumID: "al1", DiscNumber: 2, Path: "tests/fixtures/artist/an-album/test.mp3"}})
+		ds = &tests.MockDataStore{
+			MockedAlbum:     albumRepo,
+			MockedMediaFile: mfRepo,
+			MockedFolder:    folderRepo,
+			MockedLibrary:   libRepo,
+		}
+		ffm = tests.NewMockFFmpeg("")
+		t = &ChainTrace{}
+		ctx = withTrace(context.Background(), t)
+	})
+
+	It("accounts for every configured entry, including the ones that map to no source", func() {
+		conf.Server.DiscArtPriority = "external, discsubtitle, cover.jpg"
+
+		res, err := newResolver(ds, nil, ffm, nil).resolveDisc(ctx, model.DiscArtworkID("al1", 2))
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(res.reader).To(BeNil())
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "external", Outcome: OutcomeSkipped, Detail: "external sources are not supported for disc artwork"},
+			{Candidate: "discsubtitle", Outcome: OutcomeSkipped, Detail: "disc has no subtitle"},
+			{Candidate: "cover.jpg", Outcome: OutcomeSkipped, Detail: "no images in album folder"},
+		}))
+	})
+
+	It("records the entry that won and stops there", func() {
+		conf.Server.DiscArtPriority = "disc*.*, cover.jpg, embedded"
+		folderRepo.result = []model.Folder{{
+			Path:       "tests/fixtures/artist/an-album",
+			ImageFiles: []string{"cover.jpg"},
+		}}
+
+		res, err := newResolver(ds, nil, ffm, nil).resolveDisc(ctx, model.DiscArtworkID("al1", 2))
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(res.reader).ToNot(BeNil())
+		defer res.reader.Close()
+		Expect(res.source).To(Equal("folder"))
+		Expect(t.Steps()).To(HaveLen(2), "the walk must stop at the winner, and record nothing below it")
+		Expect(t.Steps()[0]).To(Equal(TraceStep{Candidate: "disc*.*", Outcome: OutcomeMiss}))
+		Expect(t.Steps()[1].Candidate).To(Equal("cover.jpg"))
+		Expect(t.Steps()[1].Outcome).To(Equal(OutcomeHit))
+		Expect(t.Steps()[1].Detail).To(HaveSuffix(filepath.FromSlash("tests/fixtures/artist/an-album/cover.jpg")))
+		Expect(t.Steps()[1].Detail).ToNot(Equal("tests/fixtures/artist/an-album/cover.jpg"),
+			"a library-relative path sends the operator looking in the wrong place")
+	})
+
+	It("reports an unparseable disc id rather than explaining another disc", func() {
+		conf.Server.DiscArtPriority = "cover.jpg"
+		_, err := newResolver(ds, nil, ffm, nil).resolveDisc(ctx, "al1")
+		Expect(err).To(HaveOccurred())
+	})
+})
+
+var _ = Describe("resolveMediaFile tracing", func() {
+	var (
+		ctx    context.Context
+		ds     *tests.MockDataStore
+		mfRepo *tests.MockMediaFileRepo
+		ffm    *tests.MockFFmpeg
+		t      *ChainTrace
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.EnableMediaFileCoverArt = true
+		repoRoot, err := os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		libRepo := &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})
+		mfRepo = tests.CreateMockMediaFileRepo()
+		mfRepo.SetData(model.MediaFiles{{
+			ID: "mf1", Title: "Song", HasCoverArt: true, Path: "tests/fixtures/artist/an-album/test.mp3",
+		}})
+		ds = &tests.MockDataStore{MockedMediaFile: mfRepo, MockedLibrary: libRepo}
+		ffm = tests.NewMockFFmpeg("")
+		t = &ChainTrace{}
+		ctx = withTrace(context.Background(), t)
+	})
+
+	It("separates a disabled setting from a track with nothing embedded", func() {
+		conf.Server.EnableMediaFileCoverArt = false
+
+		_, err := newResolver(ds, nil, ffm, nil).resolveMediaFile(ctx, "mf1")
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "embedded", Outcome: OutcomeSkipped, Detail: "EnableMediaFileCoverArt is off"},
+		}))
+	})
+
+	It("records a track with no embedded art as a miss", func() {
+		mfRepo.SetData(model.MediaFiles{{ID: "mf2", Title: "Song", HasCoverArt: false}})
+
+		_, err := newResolver(ds, nil, ffm, nil).resolveMediaFile(ctx, "mf2")
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(t.Steps()).To(Equal([]TraceStep{
+			{Candidate: "embedded", Outcome: OutcomeMiss, Detail: "the track has no embedded cover art"},
+		}))
+	})
+
+	It("records the embedded hit", func() {
+		res, err := newResolver(ds, nil, ffm, nil).resolveMediaFile(ctx, "mf1")
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(res.reader).ToNot(BeNil())
+		defer res.reader.Close()
+		Expect(res.source).To(Equal("embedded"))
+		Expect(t.Steps()).To(HaveLen(1))
+		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeHit))
+	})
+})
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index 3ded52629..be8495305 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -137,7 +137,7 @@ func (w *Worker) Backfill(ctx context.Context) (bool, error) {
 	return backfill(ctx, w.proc.ds)
 }
 
-// EnqueueStaleAbsentAll requeues known-absent entries older than staleAbsentAge.
+// EnqueueStaleAbsentAll requeues known-absent entries older than StaleAbsentAge.
 func (w *Worker) EnqueueStaleAbsentAll(ctx context.Context) error {
 	return enqueueStaleAbsentAll(ctx, w.proc.ds)
 }
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index 9fad4b503..53b6a43b2 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -362,7 +362,7 @@ var _ = Describe("Worker", func() {
 			Expect(ia.Hash).To(Equal("cafebabe"), "a persistent outage must not discard served art")
 		})
 
-		// Media files are excluded from recheckKinds, so an absent row here would never be
+		// Media files are excluded from RecheckKinds, so an absent row here would never be
 		// revisited: a transient read error would look permanent.
 		It("does not settle absent on exhaustion for a kind with no recheck path", func() {
 			conf.Server.EnableMediaFileCoverArt = true
diff --git a/model/artwork.go b/model/artwork.go
index 87b424f33..ea724265a 100644
--- a/model/artwork.go
+++ b/model/artwork.go
@@ -119,6 +119,8 @@ type ArtworkRepository interface {
 }
 
 type ArtworkQueueRepository interface {
+	// Get returns the pending row for an item, or ErrNotFound when it is not queued.
+	Get(kind Kind, id, imageType string) (*ArtworkQueueItem, error)
 	// Enqueue upserts; an existing row keeps the higher priority and has its retry_at reset.
 	Enqueue(items ...ArtworkQueueItem) error
 	// EnqueuePreservingBackoff upserts like Enqueue but preserves an existing row's retry_at, so a
@@ -130,6 +132,14 @@ type ArtworkQueueRepository interface {
 	EnqueueAllMissing(kind Kind, priority int) (int64, error)
 	// EnqueueIfMissing inserts only for items with no item_artwork row yet.
 	EnqueueIfMissing(items ...ArtworkQueueItem) error
+	// CountBySource reports how many items of a kind currently resolve from the given sources.
+	// An empty sources slice means every source; "" matches absent state.
+	CountBySource(kind Kind, sources []string) (int64, error)
+	// SourcesInUse lists the distinct sources items of a kind currently resolve from, "" included.
+	SourcesInUse(kind Kind) ([]string, error)
+	// EnqueueBySource inserts queue rows for items of a kind whose current source matches.
+	// It does not clear existing artwork state: the current image stays until it is replaced.
+	EnqueueBySource(kind Kind, sources []string, priority int) (int64, error)
 	// DequeueBatch returns up to n items with retry_at <= now, priority desc, enqueued_at asc.
 	// Restricted to the given kinds when any are passed, so one kind cannot block another's drain.
 	DequeueBatch(n int, kinds ...string) ([]ArtworkQueueItem, error)
@@ -139,6 +149,22 @@ type ArtworkQueueRepository interface {
 	// DeleteIfUnchanged deletes only while retry_at still matches, sparing a concurrent re-enqueue.
 	DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error
 	Count() (int64, error)
+	// CountByKindAndPriority reports the pending queue rows grouped by kind and priority.
+	CountByKindAndPriority() ([]ArtworkQueueStat, error)
+	// CountAbsent reports the absent states of a kind, and how many of those EnqueueStaleAbsent
+	// would pick up at the given cutoff.
+	CountAbsent(kind Kind, attemptedBefore time.Time) (ArtworkAbsentStat, error)
 	// PurgeDangling removes queue rows whose entity no longer exists.
 	PurgeDangling() (int64, error)
 }
+
+type ArtworkQueueStat struct {
+	ItemKind string
+	Priority int
+	Count    int64
+}
+
+type ArtworkAbsentStat struct {
+	Total int64
+	Stale int64
+}
diff --git a/persistence/artwork_queue_repository.go b/persistence/artwork_queue_repository.go
index e5469fbea..1ff754dc3 100644
--- a/persistence/artwork_queue_repository.go
+++ b/persistence/artwork_queue_repository.go
@@ -10,6 +10,7 @@ import (
 
 	. "github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/pocketbase/dbx"
 )
 
@@ -31,6 +32,16 @@ func NewArtworkQueueRepository(ctx context.Context, db dbx.Builder) model.Artwor
 	return r
 }
 
+func (r *artworkQueueRepository) Get(kind model.Kind, id, imageType string) (*model.ArtworkQueueItem, error) {
+	var res model.ArtworkQueueItem
+	err := r.queryOne(Select("*").From(r.tableName).
+		Where(Eq{"item_kind": kind.Prefix(), "item_id": id, "image_type": imageType}), &res)
+	if err != nil {
+		return nil, err
+	}
+	return &res, nil
+}
+
 // Enqueue also resets enqueued_at, so a fresh request does not inherit an old row's spent retry budget.
 func (r *artworkQueueRepository) Enqueue(items ...model.ArtworkQueueItem) error {
 	return r.enqueue(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
@@ -87,12 +98,49 @@ func (r *artworkQueueRepository) EnqueueIfMissing(items ...model.ArtworkQueueIte
 	return nil
 }
 
-// insertIfNotQueued inserts the rows selected by the given SQL, optionally prefixed by a CTE. DO NOTHING is
-// deliberate: a recheck must not bump the priority or retry_at of an already-queued item.
+// DO NOTHING is deliberate: a recheck must not bump the priority or retry_at of an already-queued item.
+const skipIfQueued = ` ON CONFLICT (item_kind, item_id, image_type) DO NOTHING`
+
+// insertIfNotQueued inserts the rows selected by the given SQL, optionally prefixed by a CTE.
 func (r *artworkQueueRepository) insertIfNotQueued(with, sql string, args ...any) (int64, error) {
 	return r.executeSQL(Expr(with+`INSERT INTO `+r.tableName+
-		` (`+strings.Join(enqueueColumns, ", ")+`) `+sql+
-		` ON CONFLICT (item_kind, item_id, image_type) DO NOTHING`, args...))
+		` (`+strings.Join(enqueueColumns, ", ")+`) `+sql+skipIfQueued, args...))
+}
+
+// artworkSourceFilter selects item_artwork rows of a kind; no sources means every source, "" the absent state.
+func artworkSourceFilter(kind model.Kind, sources []string) Sqlizer {
+	f := And{Eq{"item_kind": kind.Prefix()}}
+	if len(sources) > 0 {
+		f = append(f, Eq{"source": sources})
+	}
+	return f
+}
+
+func (r *artworkQueueRepository) CountBySource(kind model.Kind, sources []string) (int64, error) {
+	var res struct{ Count int64 }
+	err := r.queryOne(Select("count(*) as count").From(itemArtworkTable).
+		Where(artworkSourceFilter(kind, sources)), &res)
+	return res.Count, err
+}
+
+func (r *artworkQueueRepository) SourcesInUse(kind model.Kind) ([]string, error) {
+	var res []struct{ Source string }
+	err := r.queryAll(Select("distinct source").From(itemArtworkTable).
+		Where(Eq{"item_kind": kind.Prefix()}), &res)
+	if err != nil {
+		return nil, err
+	}
+	return slice.Map(res, func(s struct{ Source string }) string { return s.Source }), nil
+}
+
+// EnqueueBySource deliberately leaves item_artwork alone: clearing state in bulk would blank the
+// library's artwork until every item is resolved again.
+func (r *artworkQueueRepository) EnqueueBySource(kind model.Kind, sources []string, priority int) (int64, error) {
+	now := time.Now()
+	sel := Select("item_kind", "item_id", "image_type").
+		Column(Expr("?", priority)).Column("0").Column(Expr("?", now)).Column(Expr("?", now)).
+		From(itemArtworkTable).Where(artworkSourceFilter(kind, sources))
+	return r.executeSQL(Insert(r.tableName).Columns(enqueueColumns...).Select(sel).Suffix(skipIfQueued))
 }
 
 func (r *artworkQueueRepository) enqueue(conflict string, items []model.ArtworkQueueItem) error {
@@ -146,4 +194,20 @@ func (r *artworkQueueRepository) Count() (int64, error) {
 	return res.Count, err
 }
 
+func (r *artworkQueueRepository) CountByKindAndPriority() ([]model.ArtworkQueueStat, error) {
+	var res []model.ArtworkQueueStat
+	err := r.queryAll(Select("item_kind", "priority", "count(*) as count").From(r.tableName).
+		GroupBy("item_kind", "priority").OrderBy("item_kind", "priority desc"), &res)
+	return res, err
+}
+
+// CountAbsent matches EnqueueStaleAbsent on hash, so the stale count is what a recheck would queue.
+func (r *artworkQueueRepository) CountAbsent(kind model.Kind, attemptedBefore time.Time) (model.ArtworkAbsentStat, error) {
+	var res model.ArtworkAbsentStat
+	err := r.queryOne(Select("count(*) as total").
+		Column(Expr("coalesce(sum(attempted_at < ?), 0) as stale", attemptedBefore)).
+		From(itemArtworkTable).Where(Eq{"item_kind": kind.Prefix(), "hash": ""}), &res)
+	return res, err
+}
+
 var _ model.ArtworkQueueRepository = (*artworkQueueRepository)(nil)
diff --git a/persistence/artwork_queue_repository_test.go b/persistence/artwork_queue_repository_test.go
index 6638a204e..d11d89a1f 100644
--- a/persistence/artwork_queue_repository_test.go
+++ b/persistence/artwork_queue_repository_test.go
@@ -54,6 +54,22 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		Expect(got[0].ItemID).To(Equal("high"))
 	})
 
+	It("Get returns a queued row, including one still backing off", func() {
+		Expect(repo.Enqueue(item("ar", "g1", model.ArtworkPriorityScan))).To(Succeed())
+		backOff("ar", "g1", time.Now().Add(time.Hour))
+
+		got, err := repo.Get(model.KindArtistArtwork, "g1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(got.Priority).To(Equal(model.ArtworkPriorityScan))
+		Expect(got.Attempts).To(Equal(1))
+		Expect(got.RetryAt).To(BeTemporally(">", time.Now()))
+	})
+
+	It("Get reports ErrNotFound when the item is not queued", func() {
+		_, err := repo.Get(model.KindArtistArtwork, "nope", model.ImageTypePrimary)
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+
 	It("keeps the higher priority on duplicate enqueue", func() {
 		Expect(repo.Enqueue(item("al", "a1", model.ArtworkPriorityBump))).To(Succeed())
 		Expect(repo.Enqueue(item("al", "a1", model.ArtworkPriorityBackfill))).To(Succeed())
@@ -265,6 +281,89 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump), "the existing priority must survive")
 	})
 
+	Describe("EnqueueBySource", func() {
+		BeforeEach(func() {
+			artRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+			for _, ia := range []model.ItemArtwork{
+				{ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: "h1", Source: "external:deezer"},
+				{ItemKind: "ar", ItemID: "ar2", ImageType: model.ImageTypePrimary, Hash: "h2", Source: "external:lastfm"},
+				{ItemKind: "ar", ItemID: "ar3", ImageType: model.ImageTypePrimary, Hash: "", Source: ""},
+				{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "h4", Source: "external:deezer"},
+			} {
+				Expect(artRepo.PutItemArtwork(&ia)).To(Succeed())
+			}
+		})
+
+		It("enqueues only the matching source within the kind", func() {
+			n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(int64(1)), "al1 is a different kind and must not be touched")
+
+			got, err := repo.DequeueBatch(10)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })).To(ConsistOf("ar1"))
+		})
+
+		It("treats the empty source as absent", func() {
+			n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{""}, model.ArtworkPriorityRecheck)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(int64(1)))
+
+			got, _ := repo.DequeueBatch(10)
+			Expect(slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })).To(ConsistOf("ar3"))
+		})
+
+		It("enqueues every source when none is given", func() {
+			n, err := repo.EnqueueBySource(model.KindArtistArtwork, nil, model.ArtworkPriorityRecheck)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(int64(3)))
+		})
+
+		It("leaves the current artwork state in place", func() {
+			_, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
+			Expect(err).ToNot(HaveOccurred())
+
+			artRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+			ia, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Hash).To(Equal("h1"), "the current image must survive until it is replaced")
+			Expect(ia.Source).To(Equal("external:deezer"))
+		})
+
+		It("does not disturb an already-queued row", func() {
+			Expect(repo.Enqueue(item("ar", "ar1", model.ArtworkPriorityBump))).To(Succeed())
+
+			n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(BeZero())
+
+			got, _ := repo.DequeueBatch(10)
+			Expect(got).To(HaveLen(1))
+			Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump))
+		})
+
+		It("counts without enqueueing", func() {
+			n, err := repo.CountBySource(model.KindArtistArtwork, []string{"external:deezer"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(int64(1)))
+
+			queued, err := repo.Count()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(queued).To(BeZero(), "CountBySource must not enqueue")
+		})
+
+		It("counts the absent source and every source", func() {
+			Expect(repo.CountBySource(model.KindArtistArtwork, []string{""})).To(Equal(int64(1)))
+			Expect(repo.CountBySource(model.KindArtistArtwork, nil)).To(Equal(int64(3)))
+		})
+
+		It("lists the distinct sources in use by a kind", func() {
+			Expect(repo.SourcesInUse(model.KindArtistArtwork)).To(ConsistOf("", "external:deezer", "external:lastfm"))
+			Expect(repo.SourcesInUse(model.KindAlbumArtwork)).To(ConsistOf("external:deezer"))
+			Expect(repo.SourcesInUse(model.KindRadioArtwork)).To(BeEmpty())
+		})
+	})
+
 	It("does not disturb an already-queued entity when enqueueing missing rows", func() {
 		Expect(repo.Enqueue(item("al", albumRadioactivity.ID, model.ArtworkPriorityBump))).To(Succeed())
 
@@ -281,4 +380,43 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		}
 		Expect(count).To(Equal(1), "the already-queued row must not be duplicated")
 	})
+
+	Describe("status counters", func() {
+		It("groups queue rows by kind and priority", func() {
+			Expect(repo.Enqueue(item("ar", "a1", model.ArtworkPriorityBackfill))).To(Succeed())
+			Expect(repo.Enqueue(item("ar", "a2", model.ArtworkPriorityBackfill))).To(Succeed())
+			Expect(repo.Enqueue(item("ar", "a3", model.ArtworkPriorityBump))).To(Succeed())
+			Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
+
+			Expect(repo.CountByKindAndPriority()).To(ConsistOf(
+				model.ArtworkQueueStat{ItemKind: "ar", Priority: model.ArtworkPriorityBackfill, Count: 2},
+				model.ArtworkQueueStat{ItemKind: "ar", Priority: model.ArtworkPriorityBump, Count: 1},
+				model.ArtworkQueueStat{ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1},
+			))
+		})
+
+		It("reports an empty queue as no rows", func() {
+			Expect(repo.CountByKindAndPriority()).To(BeEmpty())
+		})
+
+		It("counts absent states and how many are due for recheck", func() {
+			awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+			old := time.Now().Add(-48 * time.Hour)
+			for _, ia := range []model.ItemArtwork{
+				{ItemKind: "ar", ItemID: "stale1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old},
+				{ItemKind: "ar", ItemID: "fresh1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()},
+				{ItemKind: "ar", ItemID: "found1", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: old},
+				{ItemKind: "al", ItemID: "stale2", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old},
+			} {
+				Expect(awRepo.PutItemArtwork(&ia)).To(Succeed())
+			}
+
+			Expect(repo.CountAbsent(model.KindArtistArtwork, time.Now().Add(-24*time.Hour))).
+				To(Equal(model.ArtworkAbsentStat{Total: 2, Stale: 1}))
+		})
+
+		It("reports a kind with no absent state as zero, not as an error", func() {
+			Expect(repo.CountAbsent(model.KindRadioArtwork, time.Now())).To(Equal(model.ArtworkAbsentStat{}))
+		})
+	})
 })
diff --git a/server/nativeapi/artwork.go b/server/nativeapi/artwork.go
index 3583c2db7..cfd943b1f 100644
--- a/server/nativeapi/artwork.go
+++ b/server/nativeapi/artwork.go
@@ -10,14 +10,6 @@ import (
 	"github.com/navidrome/navidrome/model"
 )
 
-var refreshableArtworkKinds = []model.Kind{
-	model.KindAlbumArtwork,
-	model.KindArtistArtwork,
-	model.KindPlaylistArtwork,
-	model.KindRadioArtwork,
-	model.KindMediaFileArtwork,
-}
-
 func (api *Router) addArtworkRoute(r chi.Router) {
 	r.Post("/artwork/{kind}/{id}/refresh", api.refreshArtwork())
 }
@@ -28,7 +20,7 @@ func (api *Router) refreshArtwork() http.HandlerFunc {
 		ctx := r.Context()
 		kind, _ := model.ParseKind(chi.URLParam(r, "kind"))
 		id := chi.URLParam(r, "id")
-		if !slices.Contains(refreshableArtworkKinds, kind) {
+		if !slices.Contains(artwork.RefreshableKinds, kind) {
 			http.Error(w, "invalid artwork kind", http.StatusBadRequest)
 			return
 		}
diff --git a/tests/mock_artwork_queue_repo.go b/tests/mock_artwork_queue_repo.go
index 1b097ca32..c8e915daa 100644
--- a/tests/mock_artwork_queue_repo.go
+++ b/tests/mock_artwork_queue_repo.go
@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 type MockArtworkQueueRepo struct {
@@ -25,6 +26,19 @@ func CreateMockArtworkQueueRepo() *MockArtworkQueueRepo {
 	return &MockArtworkQueueRepo{Data: map[string]model.ArtworkQueueItem{}}
 }
 
+func (m *MockArtworkQueueRepo) Get(kind model.Kind, id, imageType string) (*model.ArtworkQueueItem, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	it, ok := m.Data[iaKey(kind.Prefix(), id, imageType)]
+	if !ok {
+		return nil, model.ErrNotFound
+	}
+	return &it, nil
+}
+
 func (m *MockArtworkQueueRepo) Enqueue(items ...model.ArtworkQueueItem) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -161,6 +175,49 @@ func (m *MockArtworkQueueRepo) Count() (int64, error) {
 	return int64(len(m.Data)), nil
 }
 
+func (m *MockArtworkQueueRepo) CountByKindAndPriority() ([]model.ArtworkQueueStat, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	var res []model.ArtworkQueueStat
+	for _, it := range m.Data {
+		i := slices.IndexFunc(res, func(s model.ArtworkQueueStat) bool {
+			return s.ItemKind == it.ItemKind && s.Priority == it.Priority
+		})
+		if i < 0 {
+			res = append(res, model.ArtworkQueueStat{ItemKind: it.ItemKind, Priority: it.Priority, Count: 1})
+			continue
+		}
+		res[i].Count++
+	}
+	slices.SortFunc(res, func(a, b model.ArtworkQueueStat) int {
+		return cmp.Or(cmp.Compare(a.ItemKind, b.ItemKind), cmp.Compare(b.Priority, a.Priority))
+	})
+	return res, nil
+}
+
+// CountAbsent mirrors the SQL predicate: an absent state is one with no hash.
+func (m *MockArtworkQueueRepo) CountAbsent(kind model.Kind, attemptedBefore time.Time) (model.ArtworkAbsentStat, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	var res model.ArtworkAbsentStat
+	if m.Err != nil || m.ItemArtworkSource == nil {
+		return res, m.Err
+	}
+	for _, ia := range m.ItemArtworkSource.ItemData {
+		if ia.ItemKind != kind.Prefix() || ia.Hash != "" {
+			continue
+		}
+		res.Total++
+		if ia.AttemptedAt.Before(attemptedBefore) {
+			res.Stale++
+		}
+	}
+	return res, nil
+}
+
 func (m *MockArtworkQueueRepo) EnqueuePreservingBackoff(items ...model.ArtworkQueueItem) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -216,6 +273,65 @@ func (m *MockArtworkQueueRepo) EnqueueStaleAbsent(kind model.Kind, attemptedBefo
 	return inserted, nil
 }
 
+// matchingSource mirrors the SQL filter: no sources means every source, "" the absent state.
+func (m *MockArtworkQueueRepo) matchingSource(kind model.Kind, sources []string) []model.ItemArtwork {
+	if m.ItemArtworkSource == nil {
+		return nil
+	}
+	var res []model.ItemArtwork
+	for _, ia := range m.ItemArtworkSource.ItemData {
+		if ia.ItemKind == kind.Prefix() && (len(sources) == 0 || slices.Contains(sources, ia.Source)) {
+			res = append(res, ia)
+		}
+	}
+	return res
+}
+
+func (m *MockArtworkQueueRepo) CountBySource(kind model.Kind, sources []string) (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return 0, m.Err
+	}
+	return int64(len(m.matchingSource(kind, sources))), nil
+}
+
+func (m *MockArtworkQueueRepo) SourcesInUse(kind model.Kind) ([]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return nil, m.Err
+	}
+	sources := slice.Map(m.matchingSource(kind, nil), func(ia model.ItemArtwork) string { return ia.Source })
+	return slice.Unique(sources), nil
+}
+
+func (m *MockArtworkQueueRepo) EnqueueBySource(kind model.Kind, sources []string, priority int) (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return 0, m.Err
+	}
+	now := time.Now()
+	var inserted int64
+	for _, ia := range m.matchingSource(kind, sources) {
+		k := iaKey(ia.ItemKind, ia.ItemID, ia.ImageType)
+		if _, ok := m.Data[k]; ok { // DO NOTHING: never touch existing queue rows
+			continue
+		}
+		m.Data[k] = model.ArtworkQueueItem{
+			ItemKind:   ia.ItemKind,
+			ItemID:     ia.ItemID,
+			ImageType:  ia.ImageType,
+			Priority:   priority,
+			RetryAt:    now,
+			EnqueuedAt: now,
+		}
+		inserted++
+	}
+	return inserted, nil
+}
+
 // EnqueueMissing mirrors the SQL set-difference insert: ExistingIDs[kind] minus ItemArtworkSource.
 func (m *MockArtworkQueueRepo) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {
 	m.mu.Lock()

From 24311918c7825176b2603ae9a10278283ff7ebfd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 15 Aug 2026 10:36:14 -0400
Subject: [PATCH 041/200] fix(artwork): ramp the external circuit breaker back
 up instead of closing on one answer (#5961)

* fix(artwork): ramp the external circuit breaker back up instead of closing on one answer

The breaker went straight from open to fully closed on a single non-transient response,
so recovery was a burst: the agent resumed at the limiter's full rate until five
consecutive failures reopened it. A not-found counted as that response, and a provider
that is blocking still answers the occasional request, so the cycle never settled.

Observed on a production library over 100 minutes with apple-music blocked. Of 232
responses, 228 were 403 and 4 were not-found, and those four closed the breaker four
times. Each close was followed by another open 1 to 3 seconds later, with about five
requests in between:

  00:59:05 closed -> 00:59:06 opened
  01:23:13 closed -> 01:23:16 opened
  01:41:21 closed -> 01:41:24 opened

Closing now needs breakerRecoveries consecutive answers, one per probe interval, and any
failure discards the count. A not-found still counts, because the provider did answer, but
it can no longer close the breaker by itself.

Unrelated to the plugin loading in the rest of this PR; it came out of investigating why
iTunes kept returning 403 while the breaker was open.

* fix(artwork): count only current-episode probes toward breaker recovery

The worker drains concurrently, so when the breaker opens there are already calls past
allow(), queued in the rate limiter or waiting on a response. Their answers arrive after
the open and reached the recovery counter, so breakerRecoveries of them closed the breaker
with no probe interval elapsed at all: the burst the ramp exists to prevent.

allow() now returns the open episode a call was admitted under, zero when the breaker was
closed, and only an answer whose generation matches the current episode counts. The
generation also invalidates a probe whose answer lands after the breaker closed and
reopened, which a plain probe flag would credit to the wrong episode.

The token never crosses the gateFunc seam: allow and record are both called inside
Worker.gate, so passthroughGate, tracingGate and offlineGate are untouched.

The regression test needs no fake clock. The race is an ordering, not a duration, so it is
reproduced by calling allow and record in the order concurrency produces, which is
deterministic where a goroutine-based test would pass on a lucky schedule.

Found by Codex.

* test(artwork): move the breaker ordering spec into the Ginkgo suite

The ordering regression does not need a fake clock, so it does not need the plain
testing.T runner either. That runner is only used here because testing/synctest requires
it; every other spec belongs in the Ginkgo suite.

The three specs left in worker_timing_test.go all drive the fake clock.
---
 core/artwork/gate.go               | 60 ++++++++++++++++++++++--------
 core/artwork/gate_test.go          | 43 +++++++++++++++++++++
 core/artwork/worker_timing_test.go | 59 ++++++++++++++++++++++++-----
 3 files changed, 137 insertions(+), 25 deletions(-)
 create mode 100644 core/artwork/gate_test.go

diff --git a/core/artwork/gate.go b/core/artwork/gate.go
index ff77f733d..534bd8ce3 100644
--- a/core/artwork/gate.go
+++ b/core/artwork/gate.go
@@ -17,6 +17,11 @@ import (
 const (
 	breakerThreshold  = 5
 	breakerProbeAfter = time.Minute
+	// breakerRecoveries is how many consecutive answers an open breaker needs before it trusts the
+	// provider again. One is not enough: a provider that is rate-limiting or blocking us still
+	// answers the occasional request, and closing on the first of those puts the agent straight
+	// back to full rate, which is what earns the next block.
+	breakerRecoveries = 3
 )
 
 var errBreakerOpen = errors.New("artwork: external circuit breaker open")
@@ -44,7 +49,8 @@ type extGate struct {
 // gate runs a named external step through that agent's rate limiter and circuit breaker.
 func (w *Worker) gate(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
 	g := w.gateFor(name)
-	if !g.breaker.allow() {
+	allowed, gen := g.breaker.allow()
+	if !allowed {
 		log.Debug(w.runCtx, "Artwork: Skipping agent, circuit breaker open", "agent", name)
 		return nil, "", errBreakerOpen
 	}
@@ -55,7 +61,7 @@ func (w *Worker) gate(name string, f func() (io.ReadCloser, string, error)) (io.
 	}
 	callStart := time.Now()
 	r, path, err := f()
-	g.breaker.record(name, err)
+	g.breaker.record(name, gen, err)
 	log.Trace(w.runCtx, "Artwork: External agent call", "agent", name, "hit", r != nil,
 		"limiterWait", callStart.Sub(waitStart), "elapsed", time.Since(callStart), err)
 	return r, path, err
@@ -84,41 +90,65 @@ type breaker struct {
 	mu       sync.Mutex
 	failures int
 	openedAt time.Time
+	// recoveries counts consecutive good answers while open; a single failure discards them.
+	recoveries int
+	// generation identifies the current open episode, so an answer from a call admitted before
+	// the breaker opened cannot be mistaken for evidence that it has recovered.
+	generation int
 }
 
 func newBreaker() *breaker { return &breaker{} }
 
-func (b *breaker) allow() bool {
+// allow reports whether a call may proceed, and the open episode it was admitted under: zero
+// when the breaker was closed, the current generation when admitted as a half-open probe.
+func (b *breaker) allow() (bool, int) {
 	b.mu.Lock()
 	defer b.mu.Unlock()
 	if b.failures < breakerThreshold {
-		return true
+		return true, 0
 	}
 	if time.Since(b.openedAt) >= breakerProbeAfter {
 		b.openedAt = time.Now() // start a fresh probe window so only one caller passes
-		return true
+		return true, b.generation
 	}
-	return false
+	return false, 0
 }
 
-func (b *breaker) record(name string, err error) {
+func (b *breaker) record(name string, gen int, err error) {
 	// A cancelled run says nothing about the provider, so it neither counts nor clears.
 	if errors.Is(err, context.Canceled) {
 		return
 	}
 	b.mu.Lock()
 	defer b.mu.Unlock()
-	if !isTransientExternal(err) {
-		if b.failures >= breakerThreshold {
-			log.Info("Artwork: Circuit breaker closed for agent", "agent", name)
+	if isTransientExternal(err) {
+		b.recoveries = 0
+		b.failures++
+		if b.failures == breakerThreshold {
+			b.openedAt = time.Now()
+			b.generation++
+			log.Warn("Artwork: Circuit breaker opened for agent", "agent", name,
+				"consecutiveFailures", b.failures, "probeAfter", breakerProbeAfter, err)
 		}
+		return
+	}
+	if b.failures < breakerThreshold {
 		b.failures = 0
 		return
 	}
-	b.failures++
-	if b.failures == breakerThreshold {
-		b.openedAt = time.Now()
-		log.Warn("Artwork: Circuit breaker opened for agent", "agent", name,
-			"consecutiveFailures", b.failures, "probeAfter", breakerProbeAfter, err)
+	// Only a probe from this open episode is evidence of recovery. The worker drains concurrently,
+	// so answers keep arriving from calls admitted before the breaker opened; counting those would
+	// close it with no probe interval elapsed, which is the burst this exists to prevent.
+	if gen == 0 || gen != b.generation {
+		return
 	}
+	// A not-found counts because the provider did answer, but on its own it is thin evidence that
+	// a provider which just blocked us is well.
+	b.recoveries++
+	if b.recoveries < breakerRecoveries {
+		return
+	}
+	log.Info("Artwork: Circuit breaker closed for agent", "agent", name,
+		"consecutiveAnswers", b.recoveries)
+	b.failures, b.recoveries = 0, 0
 }
diff --git a/core/artwork/gate_test.go b/core/artwork/gate_test.go
new file mode 100644
index 000000000..abe723508
--- /dev/null
+++ b/core/artwork/gate_test.go
@@ -0,0 +1,43 @@
+package artwork
+
+import (
+	"errors"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// allowed drops the generation token when a caller only cares about admission.
+func allowed(b *breaker) bool { ok, _ := b.allow(); return ok }
+
+var _ = Describe("breaker", func() {
+	// The worker drains concurrently, so when the breaker opens there are already calls past
+	// allow(), queued in the rate limiter or waiting on a response. Their answers arrive
+	// afterwards. Counting those as recovery closes the breaker with no probe interval elapsed,
+	// which is the burst the ramp exists to prevent. No clock is involved: the race is an
+	// ordering, so it is reproduced by making the calls in the order concurrency produces.
+	It("ignores answers from calls admitted before it opened", func() {
+		b := newBreaker()
+
+		// A batch clears allow() while the breaker is still closed.
+		for range breakerThreshold + breakerRecoveries {
+			ok, gen := b.allow()
+			Expect(ok).To(BeTrue())
+			Expect(gen).To(BeZero(), "admitted with the breaker closed, so not a probe")
+		}
+
+		// The fast failures in that batch open it.
+		for range breakerThreshold {
+			b.record("agentA", 0, errors.New("blocked"))
+		}
+		Expect(allowed(b)).To(BeFalse(), "breaker is open")
+
+		// The slower answers from the same batch land now.
+		for range breakerRecoveries {
+			b.record("agentA", 0, nil)
+		}
+
+		Expect(allowed(b)).To(BeFalse(),
+			"answers from calls admitted before the breaker opened must not close it")
+	})
+})
diff --git a/core/artwork/worker_timing_test.go b/core/artwork/worker_timing_test.go
index f7315b20a..63f12d03c 100644
--- a/core/artwork/worker_timing_test.go
+++ b/core/artwork/worker_timing_test.go
@@ -20,24 +20,63 @@ func TestArtworkBreakerHalfOpen(t *testing.T) {
 		b := newBreaker()
 
 		for range breakerThreshold {
-			b.record("agentA", errors.New("boom"))
+			b.record("agentA", 0, errors.New("boom"))
 		}
-		g.Expect(b.allow()).To(BeFalse(), "breaker opens after consecutive errors")
+		g.Expect(allowed(b)).To(BeFalse(), "breaker opens after consecutive errors")
 
 		time.Sleep(breakerProbeAfter - time.Nanosecond)
-		g.Expect(b.allow()).To(BeFalse(), "still open before the probe interval")
+		g.Expect(allowed(b)).To(BeFalse(), "still open before the probe interval")
 
 		time.Sleep(time.Nanosecond)
-		g.Expect(b.allow()).To(BeTrue(), "half-open: one probe is granted")
-		g.Expect(b.allow()).To(BeFalse(), "only a single probe per interval")
+		ok, gen := b.allow()
+		g.Expect(ok).To(BeTrue(), "half-open: one probe is granted")
+		g.Expect(gen).ToNot(BeZero(), "a probe carries the open episode it belongs to")
+		g.Expect(allowed(b)).To(BeFalse(), "only a single probe per interval")
 
-		b.record("agentA", errors.New("boom")) // probe fails -> stay open
+		b.record("agentA", gen, errors.New("boom")) // probe fails -> stay open
 		time.Sleep(breakerProbeAfter)
-		g.Expect(b.allow()).To(BeTrue(), "another probe after the next interval")
+		ok, gen = b.allow()
+		g.Expect(ok).To(BeTrue(), "another probe after the next interval")
 
-		b.record("agentA", nil) // probe succeeds -> close
-		g.Expect(b.allow()).To(BeTrue(), "closed breaker admits freely")
-		g.Expect(b.allow()).To(BeTrue())
+		// One good answer must not reopen the floodgates: closing here is what let a burst out at
+		// full rate and got the provider to escalate from throttling to blocking.
+		b.record("agentA", gen, nil)
+		g.Expect(allowed(b)).To(BeFalse(), "a single good answer does not close the breaker")
+
+		for range breakerRecoveries - 1 {
+			time.Sleep(breakerProbeAfter)
+			ok, gen = b.allow()
+			g.Expect(ok).To(BeTrue())
+			b.record("agentA", gen, nil)
+		}
+		g.Expect(allowed(b)).To(BeTrue(), "closed breaker admits freely")
+		g.Expect(allowed(b)).To(BeTrue())
+	})
+}
+
+// The failure seen in production: while an agent was blocked, the occasional answer it did serve
+// reset the breaker, releasing a burst that immediately re-tripped it. Open and closed pairs were
+// seconds apart, over and over.
+func TestArtworkBreakerDoesNotCloseOnAnIsolatedAnswer(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		g := NewWithT(t)
+		b := newBreaker()
+		open := func() {
+			for range breakerThreshold {
+				b.record("agentA", 0, errors.New("blocked"))
+			}
+		}
+		open()
+
+		// A not-found is an answer, so it counts toward recovery, but never on its own.
+		for range breakerRecoveries * 2 {
+			time.Sleep(breakerProbeAfter)
+			ok, gen := b.allow()
+			g.Expect(ok).To(BeTrue(), "one probe per interval")
+			b.record("agentA", gen, agents.ErrNotFound)
+			b.record("agentA", 0, errors.New("blocked")) // the very next call is refused again
+			g.Expect(allowed(b)).To(BeFalse(), "an answer between failures must not close the breaker")
+		}
 	})
 }
 

From 5b87a60b5db07dbf4e4ea93d9766825a91995ef2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 15 Aug 2026 11:01:36 -0400
Subject: [PATCH 042/200] fix(plugins): load plugin agents in CLI commands
 (#5959)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(plugins): load plugin agents in CLI commands

A CLI that goes through core/agents saw only built-in agents: getEnabledAgentNames asks
Manager.PluginNames, which reads a map populated solely by Manager.Start, and only the
server calls that. On a plugin-using install the CLI's agent list was quietly short —
artwork explain --live could name deezer for an artist whose stored source was
external:apple-music, because apple-music was invisible to it.

Adds Manager.LoadPlugins, the read-only counterpart to Start: extism/wazero init plus
loadEnabledPlugins, without the folder sync, the error clearing, the cache purge or the
watcher. It follows what the read-only plugin commands already do — list, info and
validate read the DB and never start the manager — except that capabilities are detected
from the WASM exports, not declared in the manifest, so instantiating is the only accurate
source for what a plugin provides.

loadEnabledPlugins disabled a plugin and recorded LastError when a load failed. That is
right for the server and wrong for a diagnostic, so it is now gated on the read-only flag:
inspecting a plugin must not disable it.

No Subsonic router is required. Start log.Fatals without one, but the host function it
feeds already nil-checks and reports 'SubsonicAPI router not available' at call time, so a
plugin that reaches for it gets an error instead of the process dying. That Fatal's message
also claimed the DataStore was missing; it checks the router.

* fix(cli): correct the reprocess estimate's plugin caveat

imageAgentCount now receives a manager with plugins loaded, so the external estimate
already includes plugin image agents — but the disclaimer still said they were not
counted, which told operators the opposite of what the number meant.

Replaced rather than dropped: loadPluginAgents warns and continues when LoadPlugins
fails, and LoadPlugins is a no-op when plugins are disabled or no folder is set, so
there are still runs where plugin agents genuinely are not counted. The wording now
covers all three cases, and the stale comment above it said the CLI never starts the
plugin manager, which is what this branch changed.

Found by Codex on 648cf38e9.

* fix(plugins): load only the configured agents, and gate plugin init

Loading a plugin is not free: the service constructors create a KVStore or TaskQueue
database and a Storage directory for any plugin whose manifest declares those
permissions, and the plugin's own init then runs arbitrary code. loadEnabledPlugins
loads every enabled plugin, so inspecting artwork was starting scrobblers, schedulers
and lyrics plugins that could never supply an image.

Measured on a copy of a production library: 'artwork explain' created
apple-music/kvstore.db, nd-lyrics/kvstore.db and listenbrainz-daily-playlist/taskqueue.db.
The last one matters most — CreateQueue resets rows with status='running' to 'pending',
which against a live server sets up its in-flight tasks to run twice.

LoadPlugins now takes the names to load, and the artwork CLI passes the Agents list: a
plugin that is not a configured agent can never win, so there is nothing to gain by
instantiating it. The same two runs now create only apple-music, which is a configured
agent and therefore the cost of answering the question.

Init is gated separately on the caller's intent rather than on read-only. 'explain --live'
already means 'reach the provider', so it runs init; plain 'explain' and 'reprocess'
promise no external requests and must not. Documented in the --live flag help.

Found by Codex on 28eb39ac4.

* perf(cli): load plugin agents only when the selection can consult one

Explaining disc or media file artwork loaded every configured metadata plugin, though
neither resolver ever reaches an agent: resolveMediaFile is embedded-only and
discArtworkReader.selectImage refuses external outright. With --live that also ran plugin
init for a walk that provably cannot reach the network. The load now sits inside the
artist/album branch that already exists, so it is a move rather than a new condition.

reprocess did the same for a radio-only selection, whose estimate is unconditionally zero.
It is gated on needsImageAgents, which asks exactly what ExternalLookupsPerItem asks, so
the two cannot disagree. An artist/album test would look equivalent and would silently
zero the playlist estimate, whose generated grid resolves album art through those agents;
a test pins that, and reverting the predicate to a whitelist fails it.

Found by Codex on b78e67b07.

* docs(artwork): trim the comments this branch added to the project budget

Six blocks ran past the one-to-two line limit. The LoadPlugins doc was eleven lines over
three paragraphs, needsImageAgents spent two of its four explaining an alternative that was
rejected, and inspectOpts restated what LoadPlugins already says.

What went is reviewer-facing prose that belongs in a commit message: the enumeration of
what Start does that this skips, and why an artist/album predicate would have been wrong.
What stayed is the reasoning a future reader needs at that line, notably that instantiating
a plugin creates its declared services, and that playlists consume the album agent count.

* docs(artwork): correct the breaker comment after the recovery ramp

It still said a success re-closes the breaker, which stopped being true when closing
started requiring breakerRecoveries consecutive answers.

* refactor(plugins): rename the scoped-load options to transientLoad

inspect claimed the load was only looking, which is false when runInit is true: it
instantiates the plugin and runs its init, which may open sockets. transient is accurate
for every use of the field, and explains all three behaviours it gates. A load that will
not outlive the command has no business persisting findings, instantiating plugins it will
never consult, or starting background work it is about to tear down.
---
 cmd/artwork.go                   |  63 +++++++++++++---
 cmd/artwork_test.go              |  49 +++++++++++-
 core/artwork/gate.go             |   2 +-
 plugins/manager.go               |  65 ++++++++++++----
 plugins/manager_loader.go        |  29 ++++---
 plugins/manager_readonly_test.go | 125 +++++++++++++++++++++++++++++++
 6 files changed, 295 insertions(+), 38 deletions(-)
 create mode 100644 plugins/manager_readonly_test.go

diff --git a/cmd/artwork.go b/cmd/artwork.go
index 2b6a50164..e9c910f11 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -19,6 +19,7 @@ import (
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/plugins"
 	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/spf13/cobra"
 )
@@ -35,7 +36,8 @@ var (
 
 func init() {
 	artworkExplainCmd.Flags().BoolVar(&explainLive, "live", false,
-		"perform real external lookups instead of reporting what would be tried")
+		"perform real external lookups instead of reporting what would be tried; "+
+			"also initializes plugin agents, which may open external connections")
 	artworkReprocessCmd.Flags().StringSliceVar(&reprocessKinds, "kind", nil,
 		"kinds to reprocess ("+kindPrefixes(artwork.RecheckKinds)+"); repeatable")
 	artworkReprocessCmd.Flags().StringSliceVar(&reprocessSources, "source", nil,
@@ -277,7 +279,16 @@ func runReprocess(ctx context.Context) {
 	defer db.Init(ctx)()
 	ds, ctx := getAdminContext(ctx)
 
-	if err := reprocessArtwork(ctx, ds, kinds, repositorySources(reprocessSources), imageAgentCount(ds),
+	// Only a kind that can reach an agent needs the count, and loading a plugin creates its
+	// services. A preview must not reach the network, so init never runs here.
+	var imageAgents artwork.ImageAgentCount
+	if needsImageAgents(kinds) {
+		mgr := loadPluginAgents(ctx, false)
+		defer func() { _ = mgr.Stop() }()
+		imageAgents = imageAgentCount(ds, mgr)
+	}
+
+	if err := reprocessArtwork(ctx, ds, kinds, repositorySources(reprocessSources), imageAgents,
 		reprocessDryRun, reprocessConfirm(reprocessYes, os.Stdin), os.Stdout); err != nil {
 		log.Fatal(ctx, err)
 	}
@@ -326,25 +337,51 @@ func reprocessConfirm(yes bool, in io.Reader) confirmFunc {
 	return promptConfirm(in)
 }
 
-// externalEstimate claims no bound: a local hit ends the walk before any agent is asked, and plugin
-// agents are unregistered in a CLI that never starts the plugin manager.
+// externalEstimate claims no bound: a local hit ends the walk before any agent is asked, and the
+// plugin agents it counts are only the ones this process managed to load.
 func externalEstimate(n int64) string {
 	if n == 0 {
 		return "none"
 	}
-	return fmt.Sprintf("~%d estimated (plugin agents not counted; local hits may need fewer)", n)
+	return fmt.Sprintf("~%d estimated (plugin agents counted only when they load; local hits may need fewer)", n)
 }
 
 func externalLookupLine(n int64) string {
 	return fmt.Sprintf("External lookups: %s.", externalEstimate(n))
 }
 
-// imageAgentCount counts only the built-in image agents, for the same reason.
-func imageAgentCount(ds model.DataStore) artwork.ImageAgentCount {
-	ag := agents.GetAgents(ds, getPluginManager())
+func imageAgentCount(ds model.DataStore, mgr *plugins.Manager) artwork.ImageAgentCount {
+	ag := agents.GetAgents(ds, mgr)
 	return artwork.ImageAgentCount{Artist: len(ag.ArtistImageAgents()), Album: len(ag.AlbumImageAgents())}
 }
 
+// loadPluginAgents loads the plugins named in Agents, so the CLI resolves through the same agents a
+// running server would. A load failure is reported, not fatal: the built-in agents still answer.
+func loadPluginAgents(ctx context.Context, runInit bool) *plugins.Manager {
+	mgr := getPluginManager()
+	if err := mgr.LoadPlugins(ctx, configuredAgents(), runInit); err != nil {
+		log.Warn(ctx, "Could not load plugins; plugin-provided agents will be missing", err)
+	}
+	return mgr
+}
+
+// needsImageAgents asks exactly what ExternalLookupsPerItem asks, so the gate cannot disagree with
+// the estimate it guards. Playlists count: their generated grid resolves album art through agents.
+func needsImageAgents(kinds []model.Kind) bool {
+	return slices.ContainsFunc(kinds, artwork.MayFetchExternal)
+}
+
+// configuredAgents names the agents in priority order; one absent from it can never supply an image.
+func configuredAgents() []string {
+	var names []string
+	for name := range strings.SplitSeq(conf.Server.Agents, ",") {
+		if name = strings.TrimSpace(name); name != "" {
+			names = append(names, name)
+		}
+	}
+	return names
+}
+
 func promptConfirm(in io.Reader) confirmFunc {
 	return func(out io.Writer, total, external int64) bool {
 		var cost string
@@ -533,8 +570,8 @@ func explainAgents(configured string, available []string) string {
 }
 
 // availableImageAgents names the agents that can actually supply an image for kind.
-func availableImageAgents(ds model.DataStore, kind model.Kind) []string {
-	ag := agents.GetAgents(ds, getPluginManager())
+func availableImageAgents(ds model.DataStore, mgr *plugins.Manager, kind model.Kind) []string {
+	ag := agents.GetAgents(ds, mgr)
 	if kind == model.KindArtistArtwork {
 		return slice.Map(ag.ArtistImageAgents(), func(a agents.ArtistImageAgent) string { return a.Name })
 	}
@@ -705,8 +742,12 @@ func runExplain(ctx context.Context, kind model.Kind, id string) {
 	}
 
 	if artwork.Explainable(kind) {
+		// Only artist and album reach an agent, and the load must precede the resolver, which reads
+		// the same manager.
 		if kind == model.KindArtistArtwork || kind == model.KindAlbumArtwork {
-			rep.agents = explainAgents(conf.Server.Agents, availableImageAgents(ds, kind))
+			mgr := loadPluginAgents(ctx, explainLive)
+			defer func() { _ = mgr.Stop() }()
+			rep.agents = explainAgents(conf.Server.Agents, availableImageAgents(ds, mgr, kind))
 		}
 		trace := &artwork.ChainTrace{}
 		rep.source, rep.resolveErr = CreateArtworkResolver(trace, explainLive).Resolve(ctx, kind, id)
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index 949fdb42a..b28d8dac5 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -594,7 +594,9 @@ var _ = Describe("reprocessArtwork", func() {
 	It("names the estimate's blind spots instead of claiming a bound it cannot hold", func() {
 		Expect(reprocessArtwork(ctx, ds, kinds, nil, imageAgents, true, accept, &out)).To(Succeed())
 
-		Expect(out.String()).To(ContainSubstring("plugin agents not counted"))
+		// The count includes plugin agents once they load, so the caveat is about a failed load,
+		// not about plugins being invisible to the CLI.
+		Expect(out.String()).To(ContainSubstring("plugin agents counted only when they load"))
 		Expect(out.String()).To(ContainSubstring("local hits may need fewer"))
 		Expect(out.String()).ToNot(ContainSubstring("up to"), "plugin agents make any ceiling false")
 		Expect(out.String()).ToNot(ContainSubstring("at least"), "a local hit makes any floor false")
@@ -897,3 +899,48 @@ var _ = Describe("refreshItems", func() {
 			"the ids after a failure are still refreshed")
 	})
 })
+
+var _ = Describe("needsImageAgents", func() {
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.CoverArtPriority = "cover.*, external"
+		conf.Server.ArtistArtPriority = "artist.*, external"
+		conf.Server.EnableM3UExternalAlbumArt = false
+	})
+
+	It("is false for a selection no agent can serve", func() {
+		Expect(needsImageAgents([]model.Kind{model.KindRadioArtwork})).To(BeFalse())
+	})
+
+	// The generated playlist grid resolves album art through the image agents, so a playlist
+	// selection needs the count even though no agent is asked for a playlist image directly.
+	It("is true for playlists, whose grid tiles resolve through the album chain", func() {
+		Expect(needsImageAgents([]model.Kind{model.KindPlaylistArtwork})).To(BeTrue())
+	})
+
+	It("is true when any one of several kinds can reach an agent", func() {
+		Expect(needsImageAgents([]model.Kind{model.KindRadioArtwork, model.KindAlbumArtwork})).To(BeTrue())
+	})
+
+	It("is false once the chains no longer reach an agent", func() {
+		conf.Server.CoverArtPriority = "cover.*"
+		conf.Server.ArtistArtPriority = "artist.*"
+		Expect(needsImageAgents(artwork.RecheckKinds)).To(BeFalse())
+	})
+})
+
+var _ = Describe("configuredAgents", func() {
+	BeforeEach(func() { DeferCleanup(configtest.SetupConfig()) })
+
+	It("splits and trims the configured list", func() {
+		conf.Server.Agents = "lastfm, spotify ,deezer"
+		Expect(configuredAgents()).To(Equal([]string{"lastfm", "spotify", "deezer"}))
+	})
+
+	// An empty name would match no plugin, but it also must not make the list look non-empty:
+	// LoadPlugins treats an empty list as "load nothing".
+	It("drops empty entries rather than passing a name nothing can match", func() {
+		conf.Server.Agents = " , ,"
+		Expect(configuredAgents()).To(BeEmpty())
+	})
+})
diff --git a/core/artwork/gate.go b/core/artwork/gate.go
index 534bd8ce3..ebb65bcbe 100644
--- a/core/artwork/gate.go
+++ b/core/artwork/gate.go
@@ -85,7 +85,7 @@ func (w *Worker) gateFor(name string) *extGate {
 }
 
 // breaker opens after breakerThreshold consecutive errors and admits a single probe once
-// breakerProbeAfter has elapsed; a success re-closes it.
+// breakerProbeAfter has elapsed; it closes after breakerRecoveries consecutive answers.
 type breaker struct {
 	mu       sync.Mutex
 	failures int
diff --git a/plugins/manager.go b/plugins/manager.go
index b3a71ce6c..bab67e987 100644
--- a/plugins/manager.go
+++ b/plugins/manager.go
@@ -61,6 +61,9 @@ type Manager struct {
 	debounceTimers map[string]*time.Timer
 	debounceMu     sync.Mutex
 
+	// transient is set by LoadPlugins, and nil for a server Start.
+	transient *transientLoad
+
 	// SubsonicAPI host function dependencies (set once before Start, not modified after)
 	subsonicRouter SubsonicRouter
 	ds             model.DataStore
@@ -110,27 +113,14 @@ func (m *Manager) Start(ctx context.Context) error {
 	}
 
 	if m.subsonicRouter == nil {
-		log.Fatal(ctx, "Plugin manager requires DataStore to be configured")
+		log.Fatal(ctx, "Plugin manager requires the SubsonicAPI router to be configured")
 	}
 
-	// Set extism log level based on plugin-specific config or global log level
-	pluginLogLevel := conf.Server.Plugins.LogLevel
-	if pluginLogLevel == "" {
-		pluginLogLevel = conf.Server.LogLevel
-	}
-	extism.SetLogLevel(toExtismLogLevel(log.ParseLogLevel(pluginLogLevel)))
-
-	m.ctx, m.cancel = context.WithCancel(ctx)
-
-	// Initialize wazero compilation cache for better performance
 	cacheDir := filepath.Join(conf.Server.CacheFolder.MustPath(), "plugins")
 	purgeCacheBySize(ctx, cacheDir, conf.Server.Plugins.CacheSize)
 
-	var err error
-	m.cache, err = wazero.NewCompilationCacheWithDir(cacheDir)
-	if err != nil {
-		log.Error(ctx, "Failed to create wazero compilation cache", err)
-		return fmt.Errorf("creating wazero compilation cache: %w", err)
+	if err := m.initRuntime(ctx, cacheDir); err != nil {
+		return err
 	}
 
 	if conf.Server.Plugins.Folder.String() == "" {
@@ -171,6 +161,49 @@ func (m *Manager) Start(ctx context.Context) error {
 	return nil
 }
 
+// initRuntime prepares the extism/wazero runtime that instantiating a plugin needs.
+func (m *Manager) initRuntime(ctx context.Context, cacheDir string) error {
+	pluginLogLevel := conf.Server.Plugins.LogLevel
+	if pluginLogLevel == "" {
+		pluginLogLevel = conf.Server.LogLevel
+	}
+	extism.SetLogLevel(toExtismLogLevel(log.ParseLogLevel(pluginLogLevel)))
+
+	m.ctx, m.cancel = context.WithCancel(ctx)
+
+	var err error
+	m.cache, err = wazero.NewCompilationCacheWithDir(cacheDir)
+	if err != nil {
+		log.Error(ctx, "Failed to create wazero compilation cache", err)
+		return fmt.Errorf("creating wazero compilation cache: %w", err)
+	}
+	return nil
+}
+
+// transientLoad scopes a load that will not outlive the command asking for it; see LoadPlugins.
+type transientLoad struct {
+	only    []string
+	runInit bool
+}
+
+// LoadPlugins loads the plugins named in only, so a CLI sees the agents a server would. Each is
+// instantiated, creating any KVStore, TaskQueue or Storage it declares; call Stop when done.
+func (m *Manager) LoadPlugins(ctx context.Context, only []string, runInit bool) error {
+	if !conf.Server.Plugins.Enabled || conf.Server.Plugins.Folder.String() == "" || len(only) == 0 {
+		return nil
+	}
+	m.transient = &transientLoad{only: only, runInit: runInit}
+
+	cacheDir := filepath.Join(conf.Server.CacheFolder.MustPath(), "plugins")
+	if err := m.initRuntime(ctx, cacheDir); err != nil {
+		return err
+	}
+	if err := m.loadEnabledPlugins(ctx); err != nil {
+		return fmt.Errorf("loading enabled plugins: %w", err)
+	}
+	return nil
+}
+
 // Stop shuts down the plugin manager and releases all resources.
 func (m *Manager) Stop() error {
 	// Mark as stopped first to prevent new operations
diff --git a/plugins/manager_loader.go b/plugins/manager_loader.go
index 439c944f5..e5e3dbfc0 100644
--- a/plugins/manager_loader.go
+++ b/plugins/manager_loader.go
@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"slices"
 	"time"
 
 	extism "github.com/extism/go-sdk"
@@ -232,6 +233,11 @@ func (m *Manager) loadEnabledPlugins(ctx context.Context) error {
 		if !p.Enabled {
 			continue
 		}
+		// Instantiating a plugin creates its host services, so a transient load takes only the
+		// ones it may actually consult.
+		if m.transient != nil && !slices.Contains(m.transient.only, p.ID) {
+			continue
+		}
 
 		plugin := p // Capture for goroutine
 		g.Go(func() error {
@@ -246,19 +252,21 @@ func (m *Manager) loadEnabledPlugins(ctx context.Context) error {
 			}()
 
 			if err := m.loadPluginWithConfig(&plugin); err != nil {
-				// Store error in DB
-				plugin.LastError = err.Error()
-				plugin.Enabled = false
-				plugin.UpdatedAt = time.Now()
-				if putErr := repo.Put(&plugin); putErr != nil {
-					log.Error(ctx, "Failed to update plugin error in DB", "plugin", plugin.ID, putErr)
+				// A transient load must not disable the user's plugin just for looking at it.
+				if m.transient == nil {
+					plugin.LastError = err.Error()
+					plugin.Enabled = false
+					plugin.UpdatedAt = time.Now()
+					if putErr := repo.Put(&plugin); putErr != nil {
+						log.Error(ctx, "Failed to update plugin error in DB", "plugin", plugin.ID, putErr)
+					}
 				}
 				log.Error(ctx, "Failed to load plugin", "plugin", plugin.ID, err)
 				return nil
 			}
 
 			// Clear any previous error
-			if plugin.LastError != "" {
+			if plugin.LastError != "" && m.transient == nil {
 				plugin.LastError = ""
 				plugin.UpdatedAt = time.Now()
 				if putErr := repo.Put(&plugin); putErr != nil {
@@ -444,8 +452,11 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 	m.mu.Unlock()
 	loaded = true
 
-	// Call plugin init function
-	callPluginInit(ctx, m.plugins[p.ID])
+	// Init is the plugin's first chance to run arbitrary code: open sockets, create task queues,
+	// schedule work. Only a caller that already intends to reach the network asks for it.
+	if m.transient == nil || m.transient.runInit {
+		callPluginInit(ctx, m.plugins[p.ID])
+	}
 
 	return nil
 }
diff --git a/plugins/manager_readonly_test.go b/plugins/manager_readonly_test.go
new file mode 100644
index 000000000..9d16b76e9
--- /dev/null
+++ b/plugins/manager_readonly_test.go
@@ -0,0 +1,125 @@
+//go:build !windows
+
+package plugins
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Manager.LoadPlugins", func() {
+	var (
+		mgr    *Manager
+		repo   *tests.MockPluginRepo
+		tmpDir string
+	)
+
+	// newManager builds a manager over rows the caller can corrupt, with no Subsonic router: a CLI
+	// has none, and Start would log.Fatal on that.
+	newManager := func(rows model.Plugins) *Manager {
+		DeferCleanup(configtest.SetupConfig())
+		var err error
+		tmpDir, err = os.MkdirTemp("", "plugins-readonly-*")
+		Expect(err).ToNot(HaveOccurred())
+		DeferCleanup(func() { _ = os.RemoveAll(tmpDir) })
+
+		conf.Server.Plugins.Enabled = true
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
+		conf.Server.Plugins.AutoReload = false
+		conf.Server.CacheFolder = conf.NewDir(tmpDir)
+
+		if rows == nil {
+			rows = installTestPlugins(tmpDir, "test-metadata-agent"+PackageExtension)
+			for i := range rows {
+				rows[i].AllUsers = true
+			}
+		}
+		repo = tests.CreateMockPluginRepo()
+		repo.Permitted = true
+		repo.SetData(rows)
+		m := &Manager{
+			plugins: make(map[string]*plugin),
+			ds:      &tests.MockDataStore{MockedPlugin: repo},
+			metrics: noopMetricsRecorder{},
+		}
+		DeferCleanup(func() { _ = m.Stop() })
+		return m
+	}
+
+	It("detects capabilities without a Subsonic router configured", func() {
+		mgr = newManager(nil)
+
+		Expect(mgr.LoadPlugins(GinkgoT().Context(), []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
+
+		Expect(mgr.PluginNames(string(CapabilityMetadataAgent))).To(ContainElement("test-metadata-agent"))
+	})
+
+	Context("when a plugin cannot be loaded", func() {
+		brokenRows := func() model.Plugins {
+			return model.Plugins{{
+				ID: "broken", Path: filepath.Join(GinkgoT().TempDir(), "does-not-exist.ndp"),
+				Enabled: true, AllUsers: true,
+			}}
+		}
+
+		It("leaves the stored row untouched", func() {
+			mgr = newManager(brokenRows())
+
+			Expect(mgr.LoadPlugins(GinkgoT().Context(), []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
+
+			stored, err := repo.Get("broken")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(stored.Enabled).To(BeTrue(), "inspecting a plugin must never disable it")
+			Expect(stored.LastError).To(BeEmpty())
+		})
+
+		// Without this the test above would pass for the wrong reason. Start cannot be used: it
+		// syncs the folder first, dropping a row whose file is missing before any load.
+		It("still disables it when not read-only", func() {
+			mgr = newManager(brokenRows())
+
+			Expect(mgr.loadEnabledPlugins(GinkgoT().Context())).To(Succeed())
+
+			stored, err := repo.Get("broken")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(stored.Enabled).To(BeFalse())
+			Expect(stored.LastError).ToNot(BeEmpty())
+		})
+	})
+
+	// Loading a plugin creates its host services — a KVStore or task queue database on disk — so a
+	// plugin that could never supply an image must not be instantiated just to be ignored.
+	It("does not load a plugin that is not in the agent list", func() {
+		mgr = newManager(nil)
+
+		Expect(mgr.LoadPlugins(GinkgoT().Context(), []string{"some-other-agent"}, false)).To(Succeed())
+
+		Expect(mgr.PluginNames(string(CapabilityMetadataAgent))).To(BeEmpty())
+	})
+
+	It("does nothing when no agents are configured", func() {
+		mgr = newManager(nil)
+
+		Expect(mgr.LoadPlugins(GinkgoT().Context(), nil, false)).To(Succeed())
+
+		Expect(mgr.PluginNames(string(CapabilityMetadataAgent))).To(BeEmpty())
+		// Not even the wazero cache: with nothing to load there is nothing to compile.
+		Expect(filepath.Join(tmpDir, "plugins")).ToNot(BeADirectory())
+	})
+
+	It("does nothing when the plugin system is disabled", func() {
+		mgr = newManager(nil)
+		conf.Server.Plugins.Enabled = false
+
+		Expect(mgr.LoadPlugins(GinkgoT().Context(), []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
+
+		Expect(mgr.PluginNames(string(CapabilityMetadataAgent))).To(BeEmpty())
+	})
+})

From 82fde00eccfb36c89fd722b1dabcc8d2a902aebd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 15 Aug 2026 16:10:53 -0400
Subject: [PATCH 043/200] feat(scrobbler): add per-user scrobble filter (#5964)

* feat(scrobbler): add scrobble_filter column to user

* feat(scrobbler): validate scrobble filter criteria on user save

* refactor(persistence): make smart playlist join helpers package-level

* feat(scrobbler): add MediaFileRepository.MatchesCriteria

* feat(scrobbler): filter external scrobbles with per-user criteria

* feat(ui): add scrobble filter field to user form

* fix(scrobbler): default scrobble_filter to empty string for existing users

* refactor(scrobbler): also gate playback reports on the scrobble filter

Playback reports carry the same track metadata to plugin scrobblers, so a
filtered track leaked through that third dispatch path. Skip the filter
evaluation entirely when no scrobbler is active.

* refactor(persistence): move criteria join building into criteria_sql.go

The join set a criteria needs was decided in criteria_sql.go but built in
smart_playlist_repository.go, so both callers had to pair the two by hand.

* refactor(persistence): unexport smartPlaylistCriteria methods

The type never leaves the package, so the exported names advertised an API
that callers outside persistence could never reach. Also disambiguates
where/orderBy from squirrel's SelectBuilder methods of the same name.

* fix(ui): cap the scrobble filter field width

fullWidth stretched it across the whole page next to 256px inputs. Bounded
at 40em, with two rows and a resize handle so JSON rules stay readable.

* refactor(ui): move scrobble filter input in UserEdit component

* feat(ui): add pt-BR translations for the scrobble filter

* fix(scrobbler): take the filter verdict before incPlay

incPlay mutates play counts and dates a filter can test on, so evaluating at
dispatch time let one play decide differently on either side of the increment:
a track could be scrobbled despite matching, or lose only its stopped report
and strand presence plugins. Reject limit/offset too, rather than silently
ignoring part of a rule copied from a smart playlist.

* fix(scrobbler): filter the report from an expired session

The expiry callback runs with a stub user carrying no filter, so evaluating
there always returned false and leaked the track to plugin scrobblers. That is
the normal path for clients that never send stopped, such as legacy Subsonic
now-playing. Carry the last verdict on the session instead.

* refactor(scrobbler): skip the now-playing enqueue instead of threading the verdict

Queuing an entry only to drop it at dispatch also cancelled a pending
announcement for the previous, unfiltered track, since the queue is keyed by
player and a new entry replaces the old one.

* fix(scrobbler): evaluate the filter regardless of active scrobblers

The verdict is stored on the session and dispatched at expiry, so skipping
evaluation when no scrobbler was active let a plugin enabled mid-session
receive a filtered track. The empty-filter guard above already gives servers
without scrobbling the same free path, so the shortcut only ever applied to
users who had a filter set.
---
 core/scrobbler/play_tracker.go                |  69 +++++-
 core/scrobbler/play_tracker_test.go           | 200 ++++++++++++++++++
 core/scrobbler/playbackreport_worker.go       |  15 +-
 ...0260815015320_add_user_scrobble_filter.sql |   5 +
 model/mediafile.go                            |   4 +
 model/user.go                                 |   2 +
 persistence/criteria_sql.go                   |  45 +++-
 persistence/criteria_sql_benchmark_test.go    |   4 +-
 persistence/criteria_sql_test.go              |  88 ++++----
 persistence/mediafile_repository.go           |  18 ++
 persistence/mediafile_repository_test.go      |  28 +++
 persistence/smart_playlist_repository.go      |  46 +---
 persistence/user_repository.go                |  34 +++
 persistence/user_repository_test.go           |  66 ++++++
 resources/i18n/pt-br.json                     |   9 +-
 tests/mock_mediafile_repo.go                  |  10 +
 ui/src/i18n/en.json                           |   9 +-
 ui/src/user/UserEdit.jsx                      |  11 +
 ui/src/user/UserEdit.test.jsx                 |   6 +
 ui/src/user/userValidation.js                 |  10 +
 ui/src/user/userValidation.test.js            |  23 ++
 21 files changed, 590 insertions(+), 112 deletions(-)
 create mode 100644 db/migrations/20260815015320_add_user_scrobble_filter.sql

diff --git a/core/scrobbler/play_tracker.go b/core/scrobbler/play_tracker.go
index e21db42d2..63397f8f6 100644
--- a/core/scrobbler/play_tracker.go
+++ b/core/scrobbler/play_tracker.go
@@ -2,6 +2,7 @@ package scrobbler
 
 import (
 	"context"
+	"encoding/json"
 	"maps"
 	"slices"
 	"sync"
@@ -11,6 +12,7 @@ import (
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/utils/cache"
@@ -43,6 +45,10 @@ type PlaybackSession struct {
 	PositionMs   int64
 	PlaybackRate float64
 	LastReport   time.Time
+
+	// Verdict from the last report, for the expiry callback: its context carries only
+	// a stub user, so it cannot evaluate the filter itself.
+	filtered bool
 }
 
 type Submission struct {
@@ -68,8 +74,9 @@ type nowPlayingEntry struct {
 }
 
 type playbackReportEntry struct {
-	ctx  context.Context
-	info PlaybackSession
+	ctx      context.Context
+	info     PlaybackSession
+	filtered bool
 }
 
 type PlayTracker interface {
@@ -145,7 +152,7 @@ func newPlayTracker(ds model.DataStore, broker events.Broker, pluginManager Plug
 			log.Trace("Enqueueing PlaybackReport for expired session", "session", info)
 			info.State = StateExpired
 			info.LastReport = time.Now()
-			p.enqueuePlaybackReport(ctx, info)
+			p.enqueuePlaybackReport(ctx, info, info.filtered)
 		}
 	})
 
@@ -273,6 +280,10 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 
 	now := time.Now()
 
+	// One verdict per report, reused by every dispatch below, so a filter reading
+	// annotations cannot decide differently on either side of incPlay.
+	var filtered bool
+
 	switch params.State {
 	case StateStarting:
 		// Clients may send starting/playing unordered; a late "starting" must not downgrade
@@ -285,8 +296,10 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 		if err != nil {
 			return err
 		}
+		filtered = p.isFilteredOut(ctx, mf)
 		info := PlaybackSession{
 			MediaFile:    *mf,
+			filtered:     filtered,
 			Start:        now,
 			UserId:       user.ID,
 			Username:     user.UserName,
@@ -309,7 +322,7 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 		if err != nil {
 			log.Warn(ctx, "Error adding PlaybackSession to cache", "clientId", clientId, "mediaId", params.MediaId, "state", params.State, err)
 		}
-		p.enqueuePlaybackReport(ctx, info)
+		p.enqueuePlaybackReport(ctx, info, filtered)
 
 	case StatePlaying, StatePaused:
 		info, getErr := p.playMap.Get(clientId)
@@ -331,6 +344,8 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 		info.PositionMs = params.PositionMs
 		info.PlaybackRate = params.PlaybackRate
 		info.LastReport = now
+		filtered = p.isFilteredOut(ctx, &info.MediaFile)
+		info.filtered = filtered
 		ttl := 30 * time.Minute
 		if params.State == StatePlaying {
 			ttl = remainingTTL(info.MediaFile.Duration, params.PositionMs, params.PlaybackRate)
@@ -342,16 +357,19 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 		if err != nil {
 			log.Warn(ctx, "Error updating PlaybackSession in cache", "clientId", clientId, "mediaId", params.MediaId, "state", params.State, err)
 		}
-		p.enqueuePlaybackReport(ctx, info)
+		p.enqueuePlaybackReport(ctx, info, filtered)
 
 	case StateStopped:
 		var loadedMF *model.MediaFile
+		haveVerdict := false
 		if !params.IgnoreScrobble && player.ScrobbleEnabled {
 			mf, err := p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
 			if err != nil {
 				return err
 			}
 			loadedMF = mf
+			filtered = p.isFilteredOut(ctx, mf)
+			haveVerdict = true
 			trackDurationMs := int64(mf.Duration * 1000)
 			threshold := min(trackDurationMs*50/100, 240_000)
 			if params.PositionMs >= threshold {
@@ -359,7 +377,7 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 				if err != nil {
 					log.Warn(ctx, "Error updating play counts", "id", mf.ID, "track", mf.Title, "user", user.UserName, err)
 				}
-				p.dispatchScrobble(ctx, mf, now)
+				p.dispatchScrobble(ctx, mf, now, filtered)
 			}
 		}
 		p.sessionsMu.Lock()
@@ -397,7 +415,10 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 			}
 			stoppedInfo.MediaFile = *mf
 		}
-		p.enqueuePlaybackReport(ctx, stoppedInfo)
+		if !haveVerdict {
+			filtered = p.isFilteredOut(ctx, &stoppedInfo.MediaFile)
+		}
+		p.enqueuePlaybackReport(ctx, stoppedInfo, filtered)
 	}
 
 	if conf.Server.EnableNowPlaying {
@@ -413,7 +434,9 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 	// scrobbler plugins) returned by getActiveScrobblers; see dispatchNowPlaying.
 	if player.ScrobbleEnabled &&
 		(params.State == StateStarting || params.State == StatePlaying) {
-		if info, err := p.playMap.Get(clientId); err == nil {
+		if filtered {
+			log.Debug(ctx, "Ignoring external NowPlaying update for filtered track", "mediaId", params.MediaId)
+		} else if info, err := p.playMap.Get(clientId); err == nil {
 			p.enqueueNowPlaying(ctx, clientId, user.ID, &info.MediaFile, int(params.PositionMs/1000))
 		}
 	}
@@ -452,6 +475,7 @@ func (p *playTracker) Submit(ctx context.Context, submissions []Submission) erro
 			log.Error(ctx, "Cannot find track for scrobbling", "id", s.TrackID, "user", username, err)
 			continue
 		}
+		filtered := p.isFilteredOut(ctx, mf)
 		err = p.incPlay(ctx, mf, s.Timestamp)
 		if err != nil {
 			log.Error(ctx, "Error updating play counts", "id", mf.ID, "track", mf.Title, "user", username, err)
@@ -460,7 +484,7 @@ func (p *playTracker) Submit(ctx context.Context, submissions []Submission) erro
 			event.With("song", mf.ID).With("album", mf.AlbumID).With("artist", mf.AlbumArtistID)
 			log.Info(ctx, "Scrobbled", "title", mf.Title, "artist", mf.Artist, "user", username, "timestamp", s.Timestamp)
 			if player.ScrobbleEnabled {
-				p.dispatchScrobble(ctx, mf, s.Timestamp)
+				p.dispatchScrobble(ctx, mf, s.Timestamp, filtered)
 			}
 		}
 	}
@@ -494,11 +518,36 @@ func (p *playTracker) incPlay(ctx context.Context, track *model.MediaFile, times
 	})
 }
 
-func (p *playTracker) dispatchScrobble(ctx context.Context, t *model.MediaFile, playTime time.Time) {
+// Take this verdict before incPlay mutates what a filter reads, and independently of
+// which scrobblers are active: it can be stored on a session and dispatched much later.
+// Any parse or query failure fails open, because filtering must not break scrobbling.
+func (p *playTracker) isFilteredOut(ctx context.Context, t *model.MediaFile) bool {
+	u, _ := request.UserFrom(ctx)
+	if u.ScrobbleFilter == "" {
+		return false
+	}
+	var c criteria.Criteria
+	if err := json.Unmarshal([]byte(u.ScrobbleFilter), &c); err != nil {
+		log.Warn(ctx, "Invalid scrobble filter, ignoring", "user", u.UserName, err)
+		return false
+	}
+	match, err := p.ds.MediaFile(ctx).MatchesCriteria(t.ID, c)
+	if err != nil {
+		log.Warn(ctx, "Error evaluating scrobble filter, ignoring", "user", u.UserName, "track", t.Title, err)
+		return false
+	}
+	return match
+}
+
+func (p *playTracker) dispatchScrobble(ctx context.Context, t *model.MediaFile, playTime time.Time, filtered bool) {
 	if t.Artist == consts.UnknownArtist {
 		log.Debug(ctx, "Ignoring external Scrobble for track with unknown artist", "track", t.Title, "artist", t.Artist)
 		return
 	}
+	if filtered {
+		log.Debug(ctx, "Ignoring external Scrobble for filtered track", "track", t.Title, "artist", t.Artist)
+		return
+	}
 
 	allScrobblers := p.getActiveScrobblers()
 	u, _ := request.UserFrom(ctx)
diff --git a/core/scrobbler/play_tracker_test.go b/core/scrobbler/play_tracker_test.go
index f49d9a0bf..72f802c2e 100644
--- a/core/scrobbler/play_tracker_test.go
+++ b/core/scrobbler/play_tracker_test.go
@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/consts"
 
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/tests"
@@ -46,6 +47,26 @@ func (m *mockPluginLoader) LoadScrobbler(name string) (Scrobbler, bool) {
 	return s, ok
 }
 
+// flipOnPlayRepo reports one filter verdict before the play is counted and another
+// after, reproducing a filter that reads annotations incPlay mutates.
+type flipOnPlayRepo struct {
+	model.MediaFileRepository
+	before, after bool
+	played        atomic.Bool
+}
+
+func (r *flipOnPlayRepo) IncPlayCount(id string, ts time.Time) error {
+	r.played.Store(true)
+	return r.MediaFileRepository.IncPlayCount(id, ts)
+}
+
+func (r *flipOnPlayRepo) MatchesCriteria(string, criteria.Criteria) (bool, error) {
+	if r.played.Load() {
+		return r.after, nil
+	}
+	return r.before, nil
+}
+
 // slowMediaFileRepo widens the window between a report's session check and its
 // write, making check-then-write races reproducible.
 type slowMediaFileRepo struct {
@@ -320,6 +341,185 @@ var _ = Describe("PlayTracker", func() {
 		})
 	})
 
+	Describe("Scrobble filter", func() {
+		var repo *tests.MockMediaFileRepo
+
+		BeforeEach(func() {
+			ctx = request.WithUser(ctx, model.User{ID: "u-1", UserName: "user-1",
+				ScrobbleFilter: `{"all":[{"contains":{"title":"Track"}}]}`})
+			repo = ds.MediaFile(ctx).(*tests.MockMediaFileRepo)
+		})
+
+		It("does not send a matching track to the agent", func() {
+			repo.MatchesCriteriaValue = true
+
+			err := tracker.Submit(ctx, []Submission{{TrackID: "123", Timestamp: time.Now()}})
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(fake.ScrobbleCalled.Load()).To(BeFalse())
+		})
+
+		It("still increments play counts for a filtered track", func() {
+			repo.MatchesCriteriaValue = true
+
+			err := tracker.Submit(ctx, []Submission{{TrackID: "123", Timestamp: time.Now()}})
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(track.PlayCount).To(Equal(int64(1)))
+			Expect(album.PlayCount).To(Equal(int64(1)))
+		})
+
+		It("sends a non-matching track to the agent", func() {
+			repo.MatchesCriteriaValue = false
+
+			err := tracker.Submit(ctx, []Submission{{TrackID: "123", Timestamp: time.Now()}})
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(fake.ScrobbleCalled.Load()).To(BeTrue())
+		})
+
+		It("fails open when evaluation errors", func() {
+			repo.MatchesCriteriaErr = errors.New("boom")
+
+			err := tracker.Submit(ctx, []Submission{{TrackID: "123", Timestamp: time.Now()}})
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(fake.ScrobbleCalled.Load()).To(BeTrue())
+		})
+
+		It("fails open when the stored filter is not valid JSON", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "u-1", UserName: "user-1", ScrobbleFilter: `{broken`})
+			repo.MatchesCriteriaValue = true
+
+			err := tracker.Submit(ctx, []Submission{{TrackID: "123", Timestamp: time.Now()}})
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(fake.ScrobbleCalled.Load()).To(BeTrue())
+		})
+
+		It("does not send now-playing for a filtered track", func() {
+			repo.MatchesCriteriaValue = true
+
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", State: StateStarting, ClientId: "player-1", ClientName: "player"})
+
+			Expect(err).ToNot(HaveOccurred())
+			Consistently(func() bool { return fake.GetNowPlayingCalled() }).Should(BeFalse())
+		})
+
+		It("does not send playback reports for a filtered track", func() {
+			repo.MatchesCriteriaValue = true
+
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", State: StateStarting, ClientId: "player-1", ClientName: "player"})
+
+			Expect(err).ToNot(HaveOccurred())
+			Consistently(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeFalse())
+		})
+
+		It("sends playback reports for a non-matching track", func() {
+			repo.MatchesCriteriaValue = false
+
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", State: StateStarting, ClientId: "player-1", ClientName: "player"})
+
+			Expect(err).ToNot(HaveOccurred())
+			Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+		})
+
+		It("evaluates the filter even when no scrobbler is active yet", func() {
+			// The verdict is stored on the session and dispatched at expiry, by which
+			// time a plugin scrobbler may have been enabled.
+			tracker.builtinScrobblers = map[string]Scrobbler{}
+			repo.MatchesCriteriaValue = true
+
+			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+				MediaId: "123", State: StatePlaying, ClientId: "player-12", ClientName: "player"})
+
+			Expect(err).ToNot(HaveOccurred())
+			stored, getErr := tracker.playMap.Get("player-12")
+			Expect(getErr).ToNot(HaveOccurred())
+			Expect(stored.filtered).To(BeTrue())
+		})
+
+		Context("when incPlay itself flips the filter", func() {
+			// A filter on playCount or lastPlayed changes verdict the moment incPlay
+			// commits, so the verdict has to be taken before it, not at dispatch time.
+			var flip *flipOnPlayRepo
+
+			install := func(before, after bool) {
+				flip = &flipOnPlayRepo{MediaFileRepository: ds.MediaFile(ctx), before: before, after: after}
+				ds.(*tests.MockDataStore).MockedMediaFile = flip
+			}
+
+			It("does not scrobble a track the filter matched before the play was counted", func() {
+				install(true, false)
+
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", State: StateStopped, PositionMs: 120_000, ClientId: "player-1", ClientName: "player"})
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(flip.played.Load()).To(BeTrue(), "incPlay must still have run")
+				Expect(fake.ScrobbleCalled.Load()).To(BeFalse())
+			})
+
+			It("still sends the stopped report when the filter only starts matching after the play", func() {
+				install(false, true)
+
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", State: StateStopped, PositionMs: 120_000, ClientId: "player-1", ClientName: "player"})
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(flip.played.Load()).To(BeTrue(), "incPlay must still have run")
+				Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+			})
+
+			It("does not report an expired session for a filtered track", func() {
+				// The expiry callback runs with a stub user, so it cannot evaluate the
+				// filter itself and must reuse the verdict stored on the session.
+				info := PlaybackSession{
+					MediaFile: track, Start: time.Now(), UserId: "u-1", Username: "user-1",
+					PlayerId: "player-9", PlayerName: "test-player", State: StatePlaying, filtered: true,
+				}
+				_ = tracker.playMap.AddWithTTL("player-9", info, 10*time.Millisecond)
+
+				Consistently(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeFalse())
+			})
+
+			It("still reports an expired session for a track that is not filtered", func() {
+				info := PlaybackSession{
+					MediaFile: track, Start: time.Now(), UserId: "u-1", Username: "user-1",
+					PlayerId: "player-10", PlayerName: "test-player", State: StatePlaying, filtered: false,
+				}
+				_ = tracker.playMap.AddWithTTL("player-10", info, 10*time.Millisecond)
+
+				Eventually(func() bool { return fake.PlaybackReportCalled.Load() }).Should(BeTrue())
+			})
+
+			It("stores the verdict on the session so expiry can reuse it", func() {
+				repo.MatchesCriteriaValue = true
+
+				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
+					MediaId: "123", State: StatePlaying, ClientId: "player-11", ClientName: "player"})
+
+				Expect(err).ToNot(HaveOccurred())
+				stored, getErr := tracker.playMap.Get("player-11")
+				Expect(getErr).ToNot(HaveOccurred())
+				Expect(stored.filtered).To(BeTrue())
+			})
+
+			It("does not scrobble a Submit whose filter matched before the play was counted", func() {
+				install(true, false)
+
+				err := tracker.Submit(ctx, []Submission{{TrackID: "123", Timestamp: time.Now()}})
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(flip.played.Load()).To(BeTrue(), "incPlay must still have run")
+				Expect(fake.ScrobbleCalled.Load()).To(BeFalse())
+			})
+		})
+	})
+
 	Describe("ReportPlayback", func() {
 		const defaultClientId = "client-1"
 
diff --git a/core/scrobbler/playbackreport_worker.go b/core/scrobbler/playbackreport_worker.go
index 78ca6e0f7..799dac616 100644
--- a/core/scrobbler/playbackreport_worker.go
+++ b/core/scrobbler/playbackreport_worker.go
@@ -6,13 +6,14 @@ import (
 	"github.com/navidrome/navidrome/log"
 )
 
-func (p *playTracker) enqueuePlaybackReport(ctx context.Context, info PlaybackSession) {
+func (p *playTracker) enqueuePlaybackReport(ctx context.Context, info PlaybackSession, filtered bool) {
 	p.prMu.Lock()
 	defer p.prMu.Unlock()
 	ctx = context.WithoutCancel(ctx)
 	p.prQueue = append(p.prQueue, playbackReportEntry{
-		ctx:  ctx,
-		info: info,
+		ctx:      ctx,
+		info:     info,
+		filtered: filtered,
 	})
 	p.sendPlaybackReportSignal()
 }
@@ -44,12 +45,16 @@ func (p *playTracker) playbackReportWorker() {
 
 		allScrobblers := p.getActiveScrobblers()
 		for _, entry := range entries {
-			p.dispatchPlaybackReport(entry.ctx, entry.info, allScrobblers)
+			p.dispatchPlaybackReport(entry.ctx, entry.info, allScrobblers, entry.filtered)
 		}
 	}
 }
 
-func (p *playTracker) dispatchPlaybackReport(ctx context.Context, info PlaybackSession, allScrobblers map[string]Scrobbler) {
+func (p *playTracker) dispatchPlaybackReport(ctx context.Context, info PlaybackSession, allScrobblers map[string]Scrobbler, filtered bool) {
+	if filtered {
+		log.Debug(ctx, "Ignoring external PlaybackReport for filtered track", "track", info.MediaFile.Title, "state", info.State)
+		return
+	}
 	for name, s := range allScrobblers {
 		if !s.IsAuthorized(ctx, info.UserId) {
 			continue
diff --git a/db/migrations/20260815015320_add_user_scrobble_filter.sql b/db/migrations/20260815015320_add_user_scrobble_filter.sql
new file mode 100644
index 000000000..82ed95f3d
--- /dev/null
+++ b/db/migrations/20260815015320_add_user_scrobble_filter.sql
@@ -0,0 +1,5 @@
+-- +goose Up
+alter table user add column scrobble_filter varchar default '' not null;
+
+-- +goose Down
+alter table user drop column scrobble_filter;
diff --git a/model/mediafile.go b/model/mediafile.go
index ac1fad67b..888425d07 100644
--- a/model/mediafile.go
+++ b/model/mediafile.go
@@ -15,6 +15,7 @@ import (
 	"github.com/gohugoio/hashstructure"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/utils"
 	"github.com/navidrome/navidrome/utils/gg"
 	"github.com/navidrome/navidrome/utils/number"
@@ -548,6 +549,9 @@ type MediaFileRepository interface {
 	// filters as GetAll. Sort/Order are ignored.
 	GetRandom(options ...QueryOptions) (MediaFiles, error)
 	GetAllByTags(tag TagName, values []string, options ...QueryOptions) (MediaFiles, error)
+	// MatchesCriteria reports whether the media file matches the criteria's rule
+	// expression, using the logged user's annotations. Limit and offset are ignored.
+	MatchesCriteria(id string, c criteria.Criteria) (bool, error)
 	GetCursor(options ...QueryOptions) (MediaFileCursor, error)
 	// GetAllIDs returns just the media_file IDs for the same row set as GetAll.
 	GetAllIDs(options ...QueryOptions) ([]string, error)
diff --git a/model/user.go b/model/user.go
index 1c8541ccf..b6f792c9a 100644
--- a/model/user.go
+++ b/model/user.go
@@ -14,6 +14,8 @@ type User struct {
 	LastAccessAt *time.Time `structs:"last_access_at" json:"lastAccessAt"`
 	CreatedAt    time.Time  `structs:"created_at" json:"createdAt"`
 	UpdatedAt    time.Time  `structs:"updated_at" json:"updatedAt"`
+	// Smart-playlist criteria JSON; matching songs are not sent to external scrobblers
+	ScrobbleFilter string `structs:"scrobble_filter" json:"scrobbleFilter"`
 
 	// Library associations (many-to-many relationship)
 	Libraries Libraries `structs:"-" json:"libraries,omitempty"`
diff --git a/persistence/criteria_sql.go b/persistence/criteria_sql.go
index 70f9a1fb5..890f757d7 100644
--- a/persistence/criteria_sql.go
+++ b/persistence/criteria_sql.go
@@ -129,7 +129,7 @@ var smartPlaylistFields = map[string]smartPlaylistField{
 	"random":               {order: "random()"},
 }
 
-func (c smartPlaylistCriteria) Where() (squirrel.Sqlizer, error) {
+func (c smartPlaylistCriteria) where() (squirrel.Sqlizer, error) {
 	if c.Criteria.Expression == nil {
 		return squirrel.Expr("1 = 1"), nil
 	}
@@ -786,7 +786,7 @@ func fieldJoinType(name string) smartPlaylistJoinType {
 	return field.joinType
 }
 
-func (c smartPlaylistCriteria) ExpressionJoins() smartPlaylistJoinType {
+func (c smartPlaylistCriteria) expressionJoins() smartPlaylistJoinType {
 	var joins smartPlaylistJoinType
 	_ = criteria.Walk(c.Criteria.Expression, func(expr criteria.Expression) error {
 		for field := range criteria.Fields(expr) {
@@ -797,15 +797,50 @@ func (c smartPlaylistCriteria) ExpressionJoins() smartPlaylistJoinType {
 	return joins
 }
 
-func (c smartPlaylistCriteria) RequiredJoins() smartPlaylistJoinType {
-	joins := c.ExpressionJoins()
+func (c smartPlaylistCriteria) requiredJoins() smartPlaylistJoinType {
+	joins := c.expressionJoins()
 	for _, name := range c.Criteria.SortFieldNames() {
 		joins |= fieldJoinType(name)
 	}
 	return joins
 }
 
-func (c smartPlaylistCriteria) OrderBy() string {
+// applyExpressionJoins adds every join the criteria's WHERE clause resolves against.
+func (c smartPlaylistCriteria) applyExpressionJoins(sq squirrel.SelectBuilder, userID string) squirrel.SelectBuilder {
+	return c.applyJoins(sq, c.expressionJoins(), userID)
+}
+
+// applyRequiredJoins adds the WHERE joins plus any the ORDER BY resolves against.
+func (c smartPlaylistCriteria) applyRequiredJoins(sq squirrel.SelectBuilder, userID string) squirrel.SelectBuilder {
+	return c.applyJoins(sq, c.requiredJoins(), userID)
+}
+
+// applyJoins joins the media_file annotation unconditionally — annotation fields
+// COALESCE a missing row to a default, so the row has to be reachable to be absent.
+func (c smartPlaylistCriteria) applyJoins(sq squirrel.SelectBuilder, joins smartPlaylistJoinType, userID string) squirrel.SelectBuilder {
+	sq = sq.LeftJoin("annotation on ("+
+		"annotation.item_id = media_file.id"+
+		" AND annotation.item_type = 'media_file'"+
+		" AND annotation.user_id = ?)", userID)
+	if joins.has(smartPlaylistJoinAlbumAnnotation) {
+		sq = sq.LeftJoin("annotation AS album_annotation ON ("+
+			"album_annotation.item_id = media_file.album_id"+
+			" AND album_annotation.item_type = 'album'"+
+			" AND album_annotation.user_id = ?)", userID)
+	}
+	if joins.has(smartPlaylistJoinArtistAnnotation) {
+		sq = sq.LeftJoin("annotation AS artist_annotation ON ("+
+			"artist_annotation.item_id = media_file.artist_id"+
+			" AND artist_annotation.item_type = 'artist'"+
+			" AND artist_annotation.user_id = ?)", userID)
+	}
+	if joins.has(smartPlaylistJoinAlbum) {
+		sq = sq.LeftJoin("album ON album.id = media_file.album_id")
+	}
+	return sq
+}
+
+func (c smartPlaylistCriteria) orderBy() string {
 	sortFields := c.Criteria.OrderByFields()
 	parts := make([]string, 0, len(sortFields))
 	for _, sf := range sortFields {
diff --git a/persistence/criteria_sql_benchmark_test.go b/persistence/criteria_sql_benchmark_test.go
index 1dcf97871..523a5d825 100644
--- a/persistence/criteria_sql_benchmark_test.go
+++ b/persistence/criteria_sql_benchmark_test.go
@@ -124,7 +124,7 @@ func benchmarkCriteriaPipeline(b *testing.B, ctx context.Context, expr criteria.
 
 	// Build the full query matching buildSmartPlaylistQuery + addCriteria
 	sq := squirrel.Select("media_file.id").From("media_file")
-	cond, err := cSQL.Where()
+	cond, err := cSQL.where()
 	if err != nil {
 		b.Fatal(err)
 	}
@@ -132,7 +132,7 @@ func benchmarkCriteriaPipeline(b *testing.B, ctx context.Context, expr criteria.
 	if expr.Limit > 0 {
 		sq = sq.Limit(uint64(expr.Limit))
 	}
-	if order := cSQL.OrderBy(); order != "" {
+	if order := cSQL.orderBy(); order != "" {
 		sq = sq.OrderBy(order)
 	}
 
diff --git a/persistence/criteria_sql_test.go b/persistence/criteria_sql_test.go
index 0cd7187c5..8d0069b0d 100644
--- a/persistence/criteria_sql_test.go
+++ b/persistence/criteria_sql_test.go
@@ -20,7 +20,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 
 	DescribeTable("expressions",
 		func(expr criteria.Expression, expectedSQL string, expectedArgs ...any) {
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -204,7 +204,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 			sqlizer, err := newSmartPlaylistCriteria(
 				criteria.Criteria{Expression: criteria.InPlaylist{"id": "deadbeef-dead-beef"}},
 				withSmartPlaylistOwner(model.User{ID: "owner-id", IsAdmin: false}),
-			).Where()
+			).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -217,7 +217,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 			sqlizer, err := newSmartPlaylistCriteria(
 				criteria.Criteria{Expression: criteria.InPlaylist{"id": "deadbeef-dead-beef"}},
 				withSmartPlaylistOwner(model.User{ID: "admin-id", IsAdmin: true}),
-			).Where()
+			).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -228,7 +228,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 	})
 
 	It("builds relative date expressions", func() {
-		sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.InTheLast{"lastPlayed": 30}}).Where()
+		sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.InTheLast{"lastPlayed": 30}}).where()
 		Expect(err).ToNot(HaveOccurred())
 
 		sql, args, err := sqlizer.ToSql()
@@ -238,7 +238,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 	})
 
 	It("builds negated relative date expressions", func() {
-		sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.NotInTheLast{"lastPlayed": 30}}).Where()
+		sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.NotInTheLast{"lastPlayed": 30}}).where()
 		Expect(err).ToNot(HaveOccurred())
 
 		sql, args, err := sqlizer.ToSql()
@@ -248,76 +248,76 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 	})
 
 	It("returns an error for unknown fields", func() {
-		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.EndsWith{"unknown": "value"}}).Where()
+		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.EndsWith{"unknown": "value"}}).where()
 
 		Expect(err).To(MatchError("invalid field in criteria: unknown"))
 	})
 
 	It("returns an error when isMissing is used with a regular field", func() {
-		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.IsMissing{"year": true}}).Where()
+		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.IsMissing{"year": true}}).where()
 		Expect(err).To(MatchError(ContainSubstring("isMissing/isPresent operator is not supported for field")))
 	})
 
 	It("returns an error when isPresent is used with a regular field", func() {
-		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.IsPresent{"title": true}}).Where()
+		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.IsPresent{"title": true}}).where()
 		Expect(err).To(MatchError(ContainSubstring("isMissing/isPresent operator is not supported for field")))
 	})
 
 	It("returns an error when isMissing has a non-boolean value", func() {
-		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.IsMissing{"genre": "hello"}}).Where()
+		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.IsMissing{"genre": "hello"}}).where()
 		Expect(err).To(MatchError(ContainSubstring("invalid boolean value for 'missing' expression")))
 	})
 
 	It("returns an error for a range over a tag/role field", func() {
-		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.InTheRange{"rate": []int{1, 5}}}).Where()
+		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.InTheRange{"rate": []int{1, 5}}}).where()
 		Expect(err).To(MatchError(ContainSubstring("range operator not supported for tag/role field")))
 	})
 
 	It("returns a clear error for a malformed range value", func() {
-		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.InTheRange{"playCount": []int{1, 2, 3}}}).Where()
+		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.InTheRange{"playCount": []int{1, 2, 3}}}).where()
 		Expect(err).To(MatchError(ContainSubstring("must be a [min, max] pair")))
 	})
 
 	Describe("sort", func() {
 		It("sorts by regular fields", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "title"}).OrderBy()).To(Equal("media_file.title asc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "title"}).orderBy()).To(Equal("media_file.title asc"))
 		})
 
 		It("sorts by tag fields", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "genre"}).OrderBy()).To(Equal("COALESCE(json_extract(media_file.tags, '$.genre[0].value'), '') asc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "genre"}).orderBy()).To(Equal("COALESCE(json_extract(media_file.tags, '$.genre[0].value'), '') asc"))
 		})
 
 		It("sorts by role fields", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "artist"}).OrderBy()).To(Equal("COALESCE(json_extract(media_file.participants, '$.artist[0].name'), '') asc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "artist"}).orderBy()).To(Equal("COALESCE(json_extract(media_file.participants, '$.artist[0].name'), '') asc"))
 		})
 
 		It("casts numeric tags when sorting", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "rate"}).OrderBy()).To(Equal("CAST(COALESCE(json_extract(media_file.tags, '$.rate[0].value'), '') AS REAL) asc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "rate"}).orderBy()).To(Equal("CAST(COALESCE(json_extract(media_file.tags, '$.rate[0].value'), '') AS REAL) asc"))
 		})
 
 		It("sorts by albumtype alias", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "albumtype"}).OrderBy()).To(Equal("COALESCE(json_extract(media_file.tags, '$.releasetype[0].value'), '') asc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "albumtype"}).orderBy()).To(Equal("COALESCE(json_extract(media_file.tags, '$.releasetype[0].value'), '') asc"))
 		})
 
 		It("sorts by random", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "random"}).OrderBy()).To(Equal("random() asc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "random"}).orderBy()).To(Equal("random() asc"))
 		})
 
 		It("sorts by album columns bare, with no COALESCE default", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "-albumDateAdded,trackNumber"}).OrderBy()).
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "-albumDateAdded,trackNumber"}).orderBy()).
 				To(Equal("album.created_at desc, media_file.track_number asc"))
 		})
 
 		It("sorts by multiple fields", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "title,-rating"}).OrderBy()).To(Equal("media_file.title asc, COALESCE(annotation.rating, 0) desc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "title,-rating"}).orderBy()).To(Equal("media_file.title asc, COALESCE(annotation.rating, 0) desc"))
 		})
 
 		It("reverts order when order is desc", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "-date,artist", Order: "desc"}).OrderBy()).To(Equal("media_file.date asc, COALESCE(json_extract(media_file.participants, '$.artist[0].name'), '') desc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "-date,artist", Order: "desc"}).orderBy()).To(Equal("media_file.date asc, COALESCE(json_extract(media_file.participants, '$.artist[0].name'), '') desc"))
 		})
 
 		It("ignores invalid sort fields", func() {
-			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "bogus,title"}).OrderBy()).To(Equal("media_file.title asc"))
+			Expect(newSmartPlaylistCriteria(criteria.Criteria{Sort: "bogus,title"}).orderBy()).To(Equal("media_file.title asc"))
 		})
 	})
 
@@ -362,7 +362,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.Contains{"artist": "Kraftwerk"},
 				criteria.Contains{"artist": "Pink Floyd"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -376,7 +376,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.Contains{"artist": "Beatles"},
 				criteria.Contains{"composer": "Lennon"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, _, err := sqlizer.ToSql()
@@ -391,7 +391,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.NotContains{"artist": "Beatles"},
 				criteria.NotContains{"artist": "Kraftwerk"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, _, err := sqlizer.ToSql()
@@ -406,7 +406,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 			for i := range anyExprs {
 				anyExprs[i] = criteria.Contains{"artist": fmt.Sprintf("Artist%d", i)}
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: anyExprs}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: anyExprs}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -424,7 +424,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.Contains{"artist": "Beatles"},
 				criteria.Contains{"artist": "Kraftwerk"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -440,7 +440,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.Contains{"genre": "Metal"},
 				criteria.Contains{"genre": "Punk"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -454,7 +454,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.Contains{"genre": "Rock"},
 				criteria.Contains{"mood": "Happy"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, _, err := sqlizer.ToSql()
@@ -467,7 +467,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.NotContains{"genre": "Rock"},
 				criteria.NotContains{"genre": "Metal"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, _, err := sqlizer.ToSql()
@@ -482,7 +482,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.Contains{"genre": "Rock"},
 				criteria.Contains{"genre": "Metal"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -499,7 +499,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.IsNot{"artist": "Beatles"},
 				criteria.IsNot{"artist": "Kraftwerk"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -515,7 +515,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.NotContains{"artist": "Beatles"},
 				criteria.NotContains{"artist": "Kraftwerk"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -530,7 +530,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.NotContains{"genre": "Rock"},
 				criteria.NotContains{"genre": "Metal"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -547,7 +547,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.Contains{"artist": "Beatles"},
 				criteria.IsNot{"artist": "Kraftwerk"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, _, err := sqlizer.ToSql()
@@ -562,7 +562,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.IsNot{"artist": "Beatles"},
 				criteria.IsNot{"composer": "Lennon"},
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: expr}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, _, err := sqlizer.ToSql()
@@ -575,7 +575,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 			for i := range allExprs {
 				allExprs[i] = criteria.IsNot{"artist": fmt.Sprintf("Artist%d", i)}
 			}
-			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: allExprs}).Where()
+			sqlizer, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: allExprs}).where()
 			Expect(err).ToNot(HaveOccurred())
 
 			sql, args, err := sqlizer.ToSql()
@@ -591,14 +591,14 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "love"}}, Sort: "albumRating"}
 			cSQL := newSmartPlaylistCriteria(c)
 
-			Expect(cSQL.ExpressionJoins()).To(Equal(smartPlaylistJoinNone))
-			Expect(cSQL.RequiredJoins().has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
+			Expect(cSQL.expressionJoins()).To(Equal(smartPlaylistJoinNone))
+			Expect(cSQL.requiredJoins().has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
 		})
 
 		It("includes expression-based joins", func() {
 			c := criteria.Criteria{Expression: criteria.All{criteria.Gt{"albumRating": 3}}}
 
-			Expect(newSmartPlaylistCriteria(c).ExpressionJoins().has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
+			Expect(newSmartPlaylistCriteria(c).expressionJoins().has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
 		})
 
 		It("detects nested album and artist joins", func() {
@@ -607,7 +607,7 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 				criteria.Any{criteria.Gt{"artistPlayCount": 10}},
 			}}
 
-			joins := newSmartPlaylistCriteria(c).RequiredJoins()
+			joins := newSmartPlaylistCriteria(c).requiredJoins()
 			Expect(joins.has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
 			Expect(joins.has(smartPlaylistJoinArtistAnnotation)).To(BeTrue())
 		})
@@ -615,20 +615,20 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 		It("detects join types from sort fields with direction prefixes", func() {
 			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "love"}}, Sort: "-artistRating"}
 
-			Expect(newSmartPlaylistCriteria(c).RequiredJoins().has(smartPlaylistJoinArtistAnnotation)).To(BeTrue())
+			Expect(newSmartPlaylistCriteria(c).requiredJoins().has(smartPlaylistJoinArtistAnnotation)).To(BeTrue())
 		})
 
 		It("keeps a sort-only album join out of the expression joins", func() {
 			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "love"}}, Sort: "-albumDateAdded"}
 			cSQL := newSmartPlaylistCriteria(c)
 
-			Expect(cSQL.ExpressionJoins()).To(Equal(smartPlaylistJoinNone))
-			Expect(cSQL.RequiredJoins().has(smartPlaylistJoinAlbum)).To(BeTrue())
+			Expect(cSQL.expressionJoins()).To(Equal(smartPlaylistJoinNone))
+			Expect(cSQL.requiredJoins().has(smartPlaylistJoinAlbum)).To(BeTrue())
 		})
 
 		It("distinguishes the album join from the album annotation join", func() {
 			c := criteria.Criteria{Expression: criteria.All{criteria.Gt{"albumRating": 3}}}
-			joins := newSmartPlaylistCriteria(c).RequiredJoins()
+			joins := newSmartPlaylistCriteria(c).requiredJoins()
 
 			Expect(joins.has(smartPlaylistJoinAlbumAnnotation)).To(BeTrue())
 			Expect(joins.has(smartPlaylistJoinAlbum)).To(BeFalse())
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index f37e394cc..5f0addc5e 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -15,6 +15,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/navidrome/navidrome/utils/str"
 	"github.com/pocketbase/dbx"
@@ -517,6 +518,23 @@ var mediaFileSearchConfig = searchConfig{
 	MBIDFields:   []string{"mbz_recording_id", "mbz_release_track_id"},
 }
 
+func (r *mediaFileRepository) MatchesCriteria(id string, c criteria.Criteria) (bool, error) {
+	usr := loggedUser(r.ctx)
+	rulesSQL := newSmartPlaylistCriteria(c, withSmartPlaylistOwner(*usr))
+	cond, err := rulesSQL.where()
+	if err != nil {
+		return false, err
+	}
+	sq := Select("count(*) as count").From("media_file")
+	sq = rulesSQL.applyExpressionJoins(sq, usr.ID)
+	sq = sq.Where(And{Eq{"media_file.id": id}, cond})
+	var res struct{ Count int64 }
+	if err := r.queryOne(sq, &res); err != nil {
+		return false, err
+	}
+	return res.Count > 0, nil
+}
+
 func (r *mediaFileRepository) Search(q string, options ...model.QueryOptions) (model.MediaFiles, error) {
 	var opts model.QueryOptions
 	if len(options) > 0 {
diff --git a/persistence/mediafile_repository_test.go b/persistence/mediafile_repository_test.go
index b9cba03ff..ba89b5def 100644
--- a/persistence/mediafile_repository_test.go
+++ b/persistence/mediafile_repository_test.go
@@ -13,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/model/request"
 	. "github.com/onsi/ginkgo/v2"
@@ -1129,4 +1130,31 @@ var _ = Describe("MediaRepository", func() {
 			Expect(NewMediaFileRepository(rctx, GetDBXBuilder()).Exists(songAntenna.ID)).To(BeFalse())
 		})
 	})
+
+	Describe("MatchesCriteria", func() {
+		It("returns true when the track matches", func() {
+			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "Day"}}}
+			match, err := mr.MatchesCriteria(songDayInALife.ID, c)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(match).To(BeTrue())
+		})
+		It("returns false when the track does not match", func() {
+			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "Nickelback"}}}
+			match, err := mr.MatchesCriteria(songDayInALife.ID, c)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(match).To(BeFalse())
+		})
+		It("treats missing annotations as their COALESCE default", func() {
+			// unrated track: rating coalesces to 0, so "rating < 4" matches
+			c := criteria.Criteria{Expression: criteria.All{criteria.Lt{"rating": 4}}}
+			match, err := mr.MatchesCriteria(songDayInALife.ID, c)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(match).To(BeTrue())
+		})
+		It("returns an error for an invalid field", func() {
+			c := criteria.Criteria{Expression: criteria.All{criteria.Is{"bogusfield": 1}}}
+			_, err := mr.MatchesCriteria(songDayInALife.ID, c)
+			Expect(err).To(HaveOccurred())
+		})
+	})
 })
diff --git a/persistence/smart_playlist_repository.go b/persistence/smart_playlist_repository.go
index 5f84981b3..65ae4656b 100644
--- a/persistence/smart_playlist_repository.go
+++ b/persistence/smart_playlist_repository.go
@@ -119,13 +119,11 @@ func (r *playlistRepository) resolvePercentageLimit(pls *model.Playlist, rulesSQ
 		return nil
 	}
 
-	exprJoins := rulesSQL.ExpressionJoins()
 	countSq := Select("count(*) as count").From("media_file")
-	countSq = r.addMediaFileAnnotationJoin(countSq, userID)
-	countSq = r.addSmartPlaylistJoins(countSq, exprJoins, userID)
+	countSq = rulesSQL.applyExpressionJoins(countSq, userID)
 	countSq = r.applyLibraryFilter(countSq, "media_file")
 
-	cond, err := rulesSQL.Where()
+	cond, err := rulesSQL.where()
 	if err != nil {
 		log.Error(r.ctx, "Error building smart playlist criteria", "playlist", pls.Name, "id", pls.ID, err)
 		return err
@@ -146,50 +144,18 @@ func (r *playlistRepository) resolvePercentageLimit(pls *model.Playlist, rulesSQ
 // buildSmartPlaylistQuery constructs the SQL query to select media files matching the smart playlist criteria,
 // including the joins its fields require and library filtering.
 func (r *playlistRepository) buildSmartPlaylistQuery(pls *model.Playlist, rulesSQL smartPlaylistCriteria, userID string) SelectBuilder {
-	orderBy := rulesSQL.OrderBy()
+	orderBy := rulesSQL.orderBy()
 	sq := Select("row_number() over (order by "+orderBy+") as id", "'"+pls.ID+"' as playlist_id", "media_file.id as media_file_id").
 		From("media_file")
-	sq = r.addMediaFileAnnotationJoin(sq, userID)
-
-	requiredJoins := rulesSQL.RequiredJoins()
-	sq = r.addSmartPlaylistJoins(sq, requiredJoins, userID)
+	sq = rulesSQL.applyRequiredJoins(sq, userID)
 	sq = r.applyLibraryFilter(sq, "media_file")
 	return sq
 }
 
-// addMediaFileAnnotationJoin adds a left join to the annotation table for media files, filtering by user ID to include
-// user-specific annotations in the smart playlist criteria evaluation.
-func (r *playlistRepository) addMediaFileAnnotationJoin(sq SelectBuilder, userID string) SelectBuilder {
-	return sq.LeftJoin("annotation on ("+
-		"annotation.item_id = media_file.id"+
-		" AND annotation.item_type = 'media_file'"+
-		" AND annotation.user_id = ?)", userID)
-}
-
-// addSmartPlaylistJoins adds the left joins required by the criteria's fields.
-func (r *playlistRepository) addSmartPlaylistJoins(sq SelectBuilder, joins smartPlaylistJoinType, userID string) SelectBuilder {
-	if joins.has(smartPlaylistJoinAlbumAnnotation) {
-		sq = sq.LeftJoin("annotation AS album_annotation ON ("+
-			"album_annotation.item_id = media_file.album_id"+
-			" AND album_annotation.item_type = 'album'"+
-			" AND album_annotation.user_id = ?)", userID)
-	}
-	if joins.has(smartPlaylistJoinArtistAnnotation) {
-		sq = sq.LeftJoin("annotation AS artist_annotation ON ("+
-			"artist_annotation.item_id = media_file.artist_id"+
-			" AND artist_annotation.item_type = 'artist'"+
-			" AND artist_annotation.user_id = ?)", userID)
-	}
-	if joins.has(smartPlaylistJoinAlbum) {
-		sq = sq.LeftJoin("album ON album.id = media_file.album_id")
-	}
-	return sq
-}
-
 // addCriteria applies the where conditions, limit, offset, and order by clauses to the SQL query based on the
 // smart playlist criteria.
 func (r *playlistRepository) addCriteria(sql SelectBuilder, cSQL smartPlaylistCriteria) (SelectBuilder, error) {
-	cond, err := cSQL.Where()
+	cond, err := cSQL.where()
 	if err != nil {
 		return sql, err
 	}
@@ -197,7 +163,7 @@ func (r *playlistRepository) addCriteria(sql SelectBuilder, cSQL smartPlaylistCr
 	if cSQL.Criteria.Limit > 0 {
 		sql = sql.Limit(uint64(cSQL.Criteria.Limit)).Offset(uint64(cSQL.Criteria.Offset))
 	}
-	if order := cSQL.OrderBy(); order != "" {
+	if order := cSQL.orderBy(); order != "" {
 		sql = sql.OrderBy(order)
 	}
 	return sql, nil
diff --git a/persistence/user_repository.go b/persistence/user_repository.go
index 9decff4e5..3c030a640 100644
--- a/persistence/user_repository.go
+++ b/persistence/user_repository.go
@@ -16,6 +16,7 @@ import (
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/utils"
 	"github.com/navidrome/navidrome/utils/slice"
@@ -252,6 +253,9 @@ func (r *userRepository) Save(entity any) (string, error) {
 	if err := validateUsernameUnique(r, u); err != nil {
 		return "", err
 	}
+	if err := validateScrobbleFilter(u); err != nil {
+		return "", err
+	}
 	err := r.Put(u)
 	if err != nil {
 		return "", err
@@ -284,6 +288,9 @@ func (r *userRepository) Update(id string, entity any, _ ...string) error {
 	if err := validateUsernameUnique(r, u); err != nil {
 		return err
 	}
+	if err := validateScrobbleFilter(u); err != nil {
+		return err
+	}
 	err := r.Put(u)
 	if errors.Is(err, model.ErrNotFound) {
 		return rest.ErrNotFound
@@ -331,6 +338,33 @@ func validateUsernameUnique(r model.UserRepository, u *model.User) error {
 	return nil
 }
 
+func validateScrobbleFilter(u *model.User) error {
+	u.ScrobbleFilter = strings.TrimSpace(u.ScrobbleFilter)
+	if u.ScrobbleFilter == "" {
+		return nil
+	}
+	var c criteria.Criteria
+	if err := json.Unmarshal([]byte(u.ScrobbleFilter), &c); err != nil {
+		return invalidScrobbleFilter()
+	}
+	// A filter is a per-track test, so a result-set size means nothing here. Reject it
+	// rather than silently ignoring part of a rule copied from a smart playlist.
+	if c.Limit > 0 || c.LimitPercent > 0 || c.Offset > 0 || c.RefreshDelay > 0 {
+		return invalidScrobbleFilter()
+	}
+	// Building the WHERE clause is what validates field names and operators
+	if _, err := newSmartPlaylistCriteria(c).where(); err != nil {
+		return invalidScrobbleFilter()
+	}
+	return nil
+}
+
+func invalidScrobbleFilter() error {
+	return &rest.ValidationError{Errors: map[string]string{
+		"scrobbleFilter": "resources.user.validation.invalidScrobbleFilter",
+	}}
+}
+
 func (r *userRepository) Delete(id string) error {
 	usr := loggedUser(r.ctx)
 	if !usr.IsAdmin {
diff --git a/persistence/user_repository_test.go b/persistence/user_repository_test.go
index 6f8ab9161..ec417c193 100644
--- a/persistence/user_repository_test.go
+++ b/persistence/user_repository_test.go
@@ -70,6 +70,26 @@ var _ = Describe("UserRepository", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Password).To(Equal("newpass"))
 		})
+		It("persists and reads back the scrobble filter", func() {
+			usr := model.User{ID: "u-filter", UserName: "u-filter", Name: "Filter User",
+				ScrobbleFilter: `{"all":[{"contains":{"title":"????"}}]}`}
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			saved, err := repo.Get("u-filter")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(saved.ScrobbleFilter).To(Equal(`{"all":[{"contains":{"title":"????"}}]}`))
+		})
+		It("reads back a user row inserted without scrobble_filter", func() {
+			// Guards the column's NOT NULL DEFAULT '': rows predating the migration must stay scannable
+			_, err := GetDBXBuilder().NewQuery(
+				"insert into user (id, user_name, name, email, password, created_at, updated_at) " +
+					"values ('u-rawsql', 'u-rawsql', 'Raw', '', '', datetime('now'), datetime('now'))").Execute()
+			Expect(err).ToNot(HaveOccurred())
+
+			saved, err := repo.Get("u-rawsql")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(saved.ScrobbleFilter).To(Equal(""))
+		})
 	})
 
 	Describe("validatePasswordChange", func() {
@@ -607,6 +627,52 @@ var _ = Describe("UserRepository", func() {
 		})
 	})
 
+	Describe("validateScrobbleFilter", func() {
+		It("accepts an empty filter", func() {
+			u := &model.User{}
+			Expect(validateScrobbleFilter(u)).To(Succeed())
+		})
+		It("trims a whitespace-only filter to empty", func() {
+			u := &model.User{ScrobbleFilter: "   "}
+			Expect(validateScrobbleFilter(u)).To(Succeed())
+			Expect(u.ScrobbleFilter).To(Equal(""))
+		})
+		It("accepts valid criteria JSON", func() {
+			u := &model.User{ScrobbleFilter: `{"all":[{"lt":{"rating":4}}]}`}
+			Expect(validateScrobbleFilter(u)).To(Succeed())
+		})
+		It("rejects malformed JSON", func() {
+			u := &model.User{ScrobbleFilter: `{not json`}
+			var vErr *rest.ValidationError
+			err := validateScrobbleFilter(u)
+			Expect(errors.As(err, &vErr)).To(BeTrue())
+			Expect(vErr.Errors).To(HaveKey("scrobbleFilter"))
+		})
+		It("rejects criteria without rules", func() {
+			u := &model.User{ScrobbleFilter: `{"sort":"title"}`}
+			Expect(validateScrobbleFilter(u)).ToNot(Succeed())
+		})
+		It("rejects selection options that mean nothing for a single track", func() {
+			for _, f := range []string{
+				`{"all":[{"lt":{"rating":4}}],"limit":100}`,
+				`{"all":[{"lt":{"rating":4}}],"limitPercent":10}`,
+				`{"all":[{"lt":{"rating":4}}],"offset":5}`,
+				`{"all":[{"lt":{"rating":4}}],"refreshDelay":"1h"}`,
+			} {
+				u := &model.User{ScrobbleFilter: f}
+				Expect(validateScrobbleFilter(u)).ToNot(Succeed(), f)
+			}
+		})
+		It("accepts a sort, which cannot change a single-track match", func() {
+			u := &model.User{ScrobbleFilter: `{"all":[{"lt":{"rating":4}}],"sort":"title"}`}
+			Expect(validateScrobbleFilter(u)).To(Succeed())
+		})
+		It("rejects unknown fields", func() {
+			u := &model.User{ScrobbleFilter: `{"all":[{"is":{"bogusfield":1}}]}`}
+			Expect(validateScrobbleFilter(u)).ToNot(Succeed())
+		})
+	})
+
 	Describe("filters", func() {
 		It("qualifies id filter with table name", func() {
 			r := repo.(*userRepository)
diff --git a/resources/i18n/pt-br.json b/resources/i18n/pt-br.json
index b3b3bab2f..9a6338ae1 100644
--- a/resources/i18n/pt-br.json
+++ b/resources/i18n/pt-br.json
@@ -155,11 +155,13 @@
         "newPassword": "Nova Senha",
         "token": "Token",
         "lastAccessAt": "Últ. Acesso",
-        "libraries": "Bibliotecas"
+        "libraries": "Bibliotecas",
+        "scrobbleFilter": "Filtro de scrobble"
       },
       "helperTexts": {
         "name": "Alterações no seu nome só serão refletidas no próximo login",
-        "libraries": "Selecione bibliotecas específicas para este usuário, ou deixe vazio para usar bibliotecas padrão"
+        "libraries": "Selecione bibliotecas específicas para este usuário, ou deixe vazio para usar bibliotecas padrão",
+        "scrobbleFilter": "Músicas que correspondem a estas regras de playlist inteligente não são enviadas ao Last.fm, ListenBrainz ou plugins de scrobble. Usa a mesma sintaxe JSON e o mesmo comportamento das playlists inteligentes. Exemplo: {\"all\":[{\"lt\":{\"rating\":4}}]}. Deixe vazio para enviar scrobbles de todas as músicas. As contagens de reprodução locais não são afetadas."
       },
       "notifications": {
         "created": "Novo usuário criado",
@@ -173,7 +175,8 @@
         "adminAutoLibraries": "Usuários administradores têm acesso automático a todas as bibliotecas"
       },
       "validation": {
-        "librariesRequired": "Pelo menos uma biblioteca deve ser selecionada para usuários não-administradores"
+        "librariesRequired": "Pelo menos uma biblioteca deve ser selecionada para usuários não-administradores",
+        "invalidScrobbleFilter": "Devem ser regras válidas de playlist inteligente. Limite, deslocamento e intervalo de atualização não são suportados."
       }
     },
     "player": {
diff --git a/tests/mock_mediafile_repo.go b/tests/mock_mediafile_repo.go
index d993af1a8..58e84785b 100644
--- a/tests/mock_mediafile_repo.go
+++ b/tests/mock_mediafile_repo.go
@@ -9,6 +9,7 @@ import (
 
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/utils/slice"
 )
@@ -31,6 +32,8 @@ type MockMediaFileRepo struct {
 	// Add fields for cross-library move detection tests
 	FindRecentFilesByMBZTrackIDFunc func(missing model.MediaFile, since time.Time) (model.MediaFiles, error)
 	FindRecentFilesByPropertiesFunc func(missing model.MediaFile, since time.Time) (model.MediaFiles, error)
+	MatchesCriteriaValue            bool
+	MatchesCriteriaErr              error
 }
 
 func (m *MockMediaFileRepo) SetError(err bool) {
@@ -369,5 +372,12 @@ func (m *MockMediaFileRepo) FindRecentFilesByProperties(missing model.MediaFile,
 	return result, nil
 }
 
+func (m *MockMediaFileRepo) MatchesCriteria(string, criteria.Criteria) (bool, error) {
+	if m.MatchesCriteriaErr != nil {
+		return false, m.MatchesCriteriaErr
+	}
+	return m.MatchesCriteriaValue, nil
+}
+
 var _ model.MediaFileRepository = (*MockMediaFileRepo)(nil)
 var _ model.ResourceRepository = (*MockMediaFileRepo)(nil)
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index c0e226453..12968afbd 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -155,11 +155,13 @@
         "currentPassword": "Current Password",
         "newPassword": "New Password",
         "token": "Token",
-        "libraries": "Libraries"
+        "libraries": "Libraries",
+        "scrobbleFilter": "Scrobble filter"
       },
       "helperTexts": {
         "name": "Changes to your name will only be reflected on next login",
-        "libraries": "Select specific libraries for this user, or leave empty to use default libraries"
+        "libraries": "Select specific libraries for this user, or leave empty to use default libraries",
+        "scrobbleFilter": "Songs matching these smart playlist rules are not sent to Last.fm, ListenBrainz or scrobbler plugins. Uses the same JSON syntax and behavior as smart playlists. Example: {\"all\":[{\"lt\":{\"rating\":4}}]}. Leave empty to scrobble everything. Local play counts are not affected."
       },
       "notifications": {
         "created": "User created",
@@ -167,7 +169,8 @@
         "deleted": "User deleted"
       },
       "validation": {
-        "librariesRequired": "At least one library must be selected for non-admin users"
+        "librariesRequired": "At least one library must be selected for non-admin users",
+        "invalidScrobbleFilter": "Must be valid smart playlist rules. Limit, offset and refresh delay are not supported."
       },
       "message": {
         "listenBrainzToken": "Enter your ListenBrainz user token.",
diff --git a/ui/src/user/UserEdit.jsx b/ui/src/user/UserEdit.jsx
index d8302a9f9..c5d9c75a4 100644
--- a/ui/src/user/UserEdit.jsx
+++ b/ui/src/user/UserEdit.jsx
@@ -172,6 +172,17 @@ const UserEdit = (props) => {
           </FormDataConsumer>
         )}
 
+        <TextInput
+          source="scrobbleFilter"
+          multiline
+          minRows={2}
+          fullWidth
+          spellCheck={false}
+          style={{ maxWidth: '40em' }}
+          inputProps={{ style: { resize: 'vertical' } }}
+          helperText={translate('resources.user.helperTexts.scrobbleFilter')}
+        />
+
         <DateField variant="body1" source="lastLoginAt" showTime />
         <DateField variant="body1" source="lastAccessAt" showTime />
         <DateField variant="body1" source="updatedAt" showTime />
diff --git a/ui/src/user/UserEdit.test.jsx b/ui/src/user/UserEdit.test.jsx
index 1d8290569..74405cc13 100644
--- a/ui/src/user/UserEdit.test.jsx
+++ b/ui/src/user/UserEdit.test.jsx
@@ -127,6 +127,12 @@ describe('<UserEdit />', () => {
     expect(screen.getByTestId('date-field-createdAt')).toBeInTheDocument()
   })
 
+  it('should render the scrobble filter input', () => {
+    render(<UserEdit id="user1" permissions="admin" />)
+
+    expect(screen.getByTestId('text-input-scrobbleFilter')).toBeInTheDocument()
+  })
+
   it('should not render username input for non-admin users', () => {
     render(<UserEdit id="user1" permissions="user" />)
 
diff --git a/ui/src/user/userValidation.js b/ui/src/user/userValidation.js
index e90fd2acb..9eb1b8f05 100644
--- a/ui/src/user/userValidation.js
+++ b/ui/src/user/userValidation.js
@@ -15,5 +15,15 @@ export const validateUserForm = (values, translate) => {
     }
   }
 
+  if (values.scrobbleFilter && values.scrobbleFilter.trim() !== '') {
+    try {
+      JSON.parse(values.scrobbleFilter)
+    } catch {
+      errors.scrobbleFilter = translate(
+        'resources.user.validation.invalidScrobbleFilter',
+      )
+    }
+  }
+
   return errors
 }
diff --git a/ui/src/user/userValidation.test.js b/ui/src/user/userValidation.test.js
index 2ee473910..de52c17df 100644
--- a/ui/src/user/userValidation.test.js
+++ b/ui/src/user/userValidation.test.js
@@ -67,4 +67,27 @@ describe('User Validation Utilities', () => {
       )
     })
   })
+
+  describe('scrobbleFilter validation', () => {
+    it('accepts an empty filter', () => {
+      const errors = validateUserForm({ isAdmin: true }, mockTranslate)
+      expect(errors.scrobbleFilter).toBeUndefined()
+    })
+    it('accepts valid JSON', () => {
+      const errors = validateUserForm(
+        { isAdmin: true, scrobbleFilter: '{"all":[{"lt":{"rating":4}}]}' },
+        mockTranslate,
+      )
+      expect(errors.scrobbleFilter).toBeUndefined()
+    })
+    it('rejects malformed JSON', () => {
+      const errors = validateUserForm(
+        { isAdmin: true, scrobbleFilter: '{broken' },
+        mockTranslate,
+      )
+      expect(errors.scrobbleFilter).toEqual(
+        'resources.user.validation.invalidScrobbleFilter',
+      )
+    })
+  })
 })

From 42dfdf49da7e75f48eda3463754694e2c2362799 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 16 Aug 2026 10:18:10 -0400
Subject: [PATCH 044/200] feat(lyrics): support [bg:] tag and skip unknown tags
 in LRC files (#5966)

Unknown [name:value] tag lines (e.g. [al:], [by:]) were being glued onto the previous lyric line, producing junk cues like "\n[bg: " and stretching the line's timing. Now any unrecognized tag line is skipped whole, and the non-standard [bg:] background-vocal tag is parsed into cues attached to the preceding line under a bg agent, using the same agents representation the TTML parser emits for Apple-style background vocals.
---
 model/lyrics_lrc.go      | 103 +++++++++++++++++++++++++++++++--------
 model/lyrics_lrc_test.go |  43 ++++++++++++++++
 2 files changed, 127 insertions(+), 19 deletions(-)

diff --git a/model/lyrics_lrc.go b/model/lyrics_lrc.go
index 2cccb9d51..e5bd8d4f5 100644
--- a/model/lyrics_lrc.go
+++ b/model/lyrics_lrc.go
@@ -21,6 +21,12 @@ var (
 	timeRegex  = regexp.MustCompile(timeRegexString)
 	lrcIdRegex = regexp.MustCompile(`\[(ar|ti|offset|lang):([^]]+)]`)
 
+	// Non-standard background-vocal tag: [bg: <mm:ss.mm>word...] attaches to the preceding line
+	bgTagRegex = regexp.MustCompile(`^\[bg:(.*)]$`)
+
+	// Any other [name:value] line is a tag we don't support (e.g. [al:], [by:]) and must be skipped whole
+	unknownTagRegex = regexp.MustCompile(`^\[[A-Za-z][^]:]*:[^]]*]`)
+
 	// Enhanced LRC: inline word-level timing markers like <00:12.34>
 	enhancedLRCTimeString = `<([0-9]{1,2}:)?([0-9]{1,2}):([0-9]{1,2})(\.[0-9]{1,3})?>`
 	enhancedLRCRegex      = regexp.MustCompile(enhancedLRCTimeString)
@@ -40,7 +46,26 @@ func parseLRC(language, text string) (*Lyrics, error) {
 	priorLine := ""
 	validLine := false
 	repeated := false
+	hasBg := false
 	var timestamps []int64
+	var pendingBg []string
+
+	flushLine := func() {
+		value, cues := parseEnhancedLine(priorLine)
+		var merged bool
+		value, cues, merged = mergeBgLayers(value, cues, pendingBg)
+		hasBg = hasBg || merged
+		for idx := range timestamps {
+			startCopy := timestamps[idx]
+			structuredLines = append(structuredLines, Line{
+				Start: &startCopy,
+				Value: value,
+				Cue:   shiftELRCCues(cues, timestamps[idx]-timestamps[0]),
+			})
+		}
+		timestamps = nil
+		pendingBg = nil
+	}
 
 	for _, line := range lines {
 		line := strings.TrimSpace(line)
@@ -77,6 +102,17 @@ func parseLRC(language, text string) (*Lyrics, error) {
 				continue
 			}
 
+			if bgMatch := bgTagRegex.FindStringSubmatch(line); bgMatch != nil {
+				if validLine {
+					pendingBg = append(pendingBg, bgMatch[1])
+				}
+				continue
+			}
+
+			if unknownTagRegex.MatchString(line) {
+				continue
+			}
+
 			times := timeRegex.FindAllStringSubmatchIndex(line, -1)
 			if len(times) > 1 {
 				repeated = true
@@ -92,16 +128,7 @@ func parseLRC(language, text string) (*Lyrics, error) {
 			}
 
 			if validLine {
-				value, baseCues := parseEnhancedLine(priorLine)
-				for idx := range timestamps {
-					startCopy := timestamps[idx]
-					structuredLines = append(structuredLines, Line{
-						Start: &startCopy,
-						Value: value,
-						Cue:   shiftELRCCues(baseCues, timestamps[idx]-timestamps[0]),
-					})
-				}
-				timestamps = nil
+				flushLine()
 			}
 
 			end := 0
@@ -143,15 +170,11 @@ func parseLRC(language, text string) (*Lyrics, error) {
 	}
 
 	if validLine {
-		value, baseCues := parseEnhancedLine(priorLine)
-		for idx := range timestamps {
-			startCopy := timestamps[idx]
-			structuredLines = append(structuredLines, Line{
-				Start: &startCopy,
-				Value: value,
-				Cue:   shiftELRCCues(baseCues, timestamps[idx]-timestamps[0]),
-			})
-		}
+		flushLine()
+	}
+
+	if hasBg {
+		fillMainAgentID(structuredLines)
 	}
 
 	// If there are repeated values, there is no guarantee that they are in order
@@ -170,9 +193,51 @@ func parseLRC(language, text string) (*Lyrics, error) {
 		Offset:        offset,
 		Synced:        synced,
 	}
+	if hasBg {
+		lyrics.Agents = []Agent{
+			{ID: "main", Role: "main"},
+			{ID: backgroundAgentID("main"), Role: "bg"},
+		}
+	}
 	return &lyrics, nil
 }
 
+// mergeBgLayers appends parsed [bg:] content to a line's value and cues as a
+// background agent layer, mirroring the TTML background-vocal representation.
+func mergeBgLayers(value string, cues []Cue, bgLines []string) (string, []Cue, bool) {
+	merged := false
+	for _, bg := range bgLines {
+		bgValue, bgCues := parseEnhancedLine(bg)
+		if len(bgCues) == 0 {
+			continue
+		}
+		offset := 0
+		if value != "" {
+			offset = len(value) + 1
+			value += " "
+		}
+		value += bgValue
+		for _, c := range bgCues {
+			c.ByteStart += offset
+			c.ByteEnd += offset
+			c.AgentID = backgroundAgentID("main")
+			cues = append(cues, c)
+		}
+		merged = true
+	}
+	return value, cues, merged
+}
+
+func fillMainAgentID(lines []Line) {
+	for i := range lines {
+		for j := range lines[i].Cue {
+			if lines[i].Cue[j].AgentID == "" {
+				lines[i].Cue[j].AgentID = "main"
+			}
+		}
+	}
+}
+
 // parseEnhancedLine extracts word-level timing cues from Enhanced LRC inline markers
 // and computes UTF-8 byte offsets against the final stripped line value.
 func parseEnhancedLine(text string) (string, []Cue) {
diff --git a/model/lyrics_lrc_test.go b/model/lyrics_lrc_test.go
index 87514caf1..e8cd05352 100644
--- a/model/lyrics_lrc_test.go
+++ b/model/lyrics_lrc_test.go
@@ -147,6 +147,49 @@ var _ = Describe("parseLRC", func() {
 		}))
 	})
 
+	It("should skip unknown tag lines instead of merging them into the prior line", func() {
+		lyrics, err := parseLRC("xxx", "[00:01.00]<00:01.00>Some <00:01.50>lyrics\n[by: someone]\n[al: An album]\n[00:03.00]Next")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(lyrics.Synced).To(BeTrue())
+		Expect(lyrics.Line).To(HaveLen(2))
+
+		t1000, t1500, t3000 := int64(1000), int64(1500), int64(3000)
+		Expect(lyrics.Line[0].Value).To(Equal("Some lyrics"))
+		Expect(lyrics.Line[0].Cue).To(Equal([]Cue{
+			{Start: &t1000, End: &t1500, Value: "Some ", ByteStart: 0, ByteEnd: 4},
+			{Start: &t1500, End: &t3000, Value: "lyrics", ByteStart: 5, ByteEnd: 10},
+		}))
+		Expect(lyrics.Line[1].Value).To(Equal("Next"))
+	})
+
+	It("should attach [bg:] background vocals to the previous line as a bg agent layer", func() {
+		lyrics, err := parseLRC("xxx", "[00:52.00]<00:52.00>Main <00:52.50>line\n[bg: <00:53.00>Okay<00:53.50>]\n[00:55.00]Next")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(lyrics.Agents).To(Equal([]Agent{
+			{ID: "main", Role: "main"},
+			{ID: "__nd_bg__|main", Role: "bg"},
+		}))
+		Expect(lyrics.Line).To(HaveLen(2))
+
+		line := lyrics.Line[0]
+		Expect(line.Value).To(Equal("Main line Okay"))
+		Expect(line.Cue).To(Equal([]Cue{
+			{Start: new(int64(52000)), End: new(int64(52500)), Value: "Main ", ByteStart: 0, ByteEnd: 4, AgentID: "main"},
+			{Start: new(int64(52500)), End: new(int64(55000)), Value: "line", ByteStart: 5, ByteEnd: 8, AgentID: "main"},
+			{Start: new(int64(53000)), End: new(int64(53500)), Value: "Okay", ByteStart: 10, ByteEnd: 13, AgentID: "__nd_bg__|main"},
+		}))
+		Expect(lyrics.Line[1].Value).To(Equal("Next"))
+	})
+
+	It("should skip a [bg:] line that has no inline timing", func() {
+		lyrics, err := parseLRC("xxx", "[00:01.00]Hi\n[bg: untimed]\n[00:03.00]Next")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(lyrics.Agents).To(BeNil())
+		Expect(lyrics.Line).To(HaveLen(2))
+		Expect(lyrics.Line[0].Value).To(Equal("Hi"))
+		Expect(lyrics.Line[1].Value).To(Equal("Next"))
+	})
+
 	It("should handle mixed Enhanced and plain LRC lines", func() {
 		lyrics, err := parseLRC("xxx", "[00:01.00]<00:01.00>Some <00:01.50>lyrics\n[00:03.00]Plain line\n[00:05.00]<00:05.00>More <00:05.50>words")
 		Expect(err).ToNot(HaveOccurred())

From 5b758fc20cc11e16f0fddab19e5bb0714007e1a6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 16 Aug 2026 13:24:07 -0400
Subject: [PATCH 045/200] fix(artwork): re-resolve artwork when image files
 change on disk (#5965)

* fix(artwork): re-resolve artwork when image files change on disk

An image-only folder change (replaced, added, or deleted cover/artist
images, with no audio files touched) was detected by the scanner but never
reached the artwork queue, so clients kept seeing the old coverArt hash
until something else forced a re-resolution.

Phase 1 now diffs each changed folder's image list and imagesUpdatedAt
against the previously persisted folder row, and at the end of the phase
bulk-enqueues re-resolution for the affected entities: albums with tracks
in the folder or its direct children (covering disc subfolder layouts),
and, when an artist-pattern image is involved, artists with albums under
the folder's subtree, mirroring the artist resolver's upward search. The
artist mapping mirrors the resolver's sole-album-artist album selection.

New repository helpers keep the mapping set-based and light: folder
GetAllIDs, media_file GetAlbumIDsByFolder (distinct, indexed by
folder_id), and album GetSoleAlbumArtistIDs.

* refactor: simplify the image-change artwork enqueue after review

Load the previous folder image state through the existing GetFolderUpdateInfo
bulk pre-pass instead of a per-folder SELECT inside the persist transaction,
and skip the diff for new folders, whose artwork the scanner already enqueues
inline. Move the artist-image classification into core/artwork
(IsArtistImageFile) so the scanner shares the resolver's ArtistArtPriority
token grammar instead of re-parsing it (the copy mistreated image-folder as a
filename glob). Move the folder-subtree query into the folder repository
(GetSubtreeIDs) with LIKE escaping and expression-tree batching, share the
sole-album-artist predicate between the resolver and the album repository
(model.SoleAlbumArtistFilter), extract a chunked single-column query helper,
and deduplicate the ArtworkQueueItem literals behind scanArtworkItem.

* fix(persistence): keep slash-form paths in GetSubtreeIDs subtree predicates

The scanner hands GetSubtreeIDs io/fs slash-form paths, but filepath.Clean
rewrites them with backslashes on Windows while folder.path is stored with
forward slashes, so the descendant predicates matched nothing and nested
artist folders were never re-enqueued there. Normalize with path.Clean, like
HasAudioOutsideFolders does, and cover a nested path in the repo test.

* refactor(persistence): move the sole-album-artist rule into the album repository

SQLizer filters belong in the persistence package, not model. The rule
becomes an unexported filter shared by GetSoleAlbumArtistIDs and a new
GetBySoleAlbumArtist repository method, which the artist artwork resolver now
calls instead of building the squirrel filter itself.

* perf(scanner): resolve image-change artists in one query over album.folder_ids

The artist half of the image-change enqueue walked folder subtree IDs, then
media_file rows, then album rows, marshalling thousands of bound IDs through
the driver on each hop. Matching albums by their own folder_ids instead is one
statement, and folder_ids is the same source the artist resolver uses to
compute an artist's folders.

Benchmarked against a copy of the production DB (97k tracks, 10k folders,
7k albums): 87ms +/-196% -> 17.4ms +/-8%, 7.1MB -> 172KB, 103k -> 1.5k allocs.
The subtree predicate becomes a shared folderSubtreeFilter, so Folder
GetSubtreeIDs and Album GetSoleAlbumArtistIDs are no longer needed.

* fix(scanner): persist ancestor folders discovered by a quick scan

A quick scan skipped any new folder with no files of its own, so an artist
folder holding only album subfolders never got a row. Adding artist.jpg to it
later then produced no artwork enqueue: the entry was new, so the image diff
was skipped, and it has no tracks, so nothing was enqueued inline either.

Skip only genuinely empty new folders, matching what a full scan already
persists. This also fixes artist artwork resolving as absent for artists first
imported by a quick scan, since the resolver's folder climb needs that row.

Also normalizes the selective-scan preload paths with path.Clean, so its
descendant predicates match the stored slash-form paths on Windows.

* fix(persistence): chunk subtree paths and match artist globs by basename

Two regressions from earlier commits on this branch.

Collapsing the subtree query into a single statement dropped the chunking the
old GetSubtreeIDs had: each path expands into 3 OR terms and SQLite rejects an
expression tree deeper than 1000, measured at 166 paths. A library with more
artist-image folders than that (the prod copy has 158) would fail the whole
collect, dropping the album items with it, so the scanner now keeps them when
the artist query fails.

The artist-image classifier compared whole tokens after stripping album/, so a
directory-bearing glob like images/artist.* never matched the basenames the
scanner has. Match on path.Base, which is what album/artist.* already reduced
to; the resolver climbs parent folders, so an exact prefix is not knowable
here and a conservative match is the right failure direction.

* refactor(persistence): halve the repository surface this PR adds

Research on the four new repository methods found two were avoidable.

GetAlbumIDsByFolder now expands the changed folders to their direct children
in its own subquery, so Folder.GetAllIDs has no callers and is deleted, one
round trip per scan disappears, and the previously unchunked id/parent_id IN
lists are covered by the existing chunking.

GetBySoleAlbumArtist becomes an exported SoleAlbumArtistFilter, matching the
ParticipantIDFilter precedent for sharing a Sqlizer with core/, so the rule
still lives in persistence but AlbumRepository gains nothing and the mock shim
that ignored the artist filter is gone.

Also drops queryAllSliceChunked, now callerless, in favour of the file-local
slices.Chunk convention used by the sibling folder queries.

Rejected on measurement: matching the album path by album.folder_ids is exactly
equivalent (13975 pairs, zero difference) but has no index, so it scans every
album and runs 5-200x slower than the media_file route.

* refactor(persistence): stop reading the deprecated album_artist_id column

Both artist lookups this PR touches now go through participation, matching
the precedent in core/archiver.go and share_repository.go.

SoleAlbumArtistFilter uses ParticipantIDFilter, which is also faster: the
album_artists unique constraint is a covering index for it, while the old
column needed album_artist_album_id plus a row fetch.

GetSoleAlbumArtistIDsInSubtrees reads the sole artist out of the participants
JSON it already parses for the sole-artist check, rather than joining back to
album_artists, which measured ~1.6x slower on a prod-sized copy.

Verified equivalent on that copy: 6828 sole-artist albums and 1088 subtree
artists resolve identically via the column, the join and the JSON. The tests
now set a deliberately wrong album_artist_id so they fail if either query
starts reading it again.

* docs: trim comments that carry rationale belonging in commit messages

Five comments had grown past the budget with benchmark numbers, rejected
alternatives, and a duplicate of the constant's own explanation.

* refactor(scanner): move the image-change enqueue into phase_1_folders

The three functions were methods on phaseFolders, so they belong with the
type; phase_1_image_changes.go also read like a fifth phase, which it wasn't.

* refactor(scanner): extract the image-change collector into its own type

phaseFolders no longer owns the per-library map and the mapping methods; it
records into a collector and asks it to enqueue once. The collector keeps the
library alongside the folders, so enqueue needs only ctx and the datastore.

* refactor(scanner): simplify enqueue method by removing redundant datastore parameter

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

* docs(scanner): drop the stale zero-value claim on imageChangeCollector

The collector now takes its datastore at construction, so the zero value is
no longer usable.

* fix(scanner): pin the persist stage to concurrency 1 and guard the collector

The stage relied on go-pipeline defaulting to one worker; stating it at the
stage makes the constraint visible where someone would change it. The
collector takes a mutex too, so the type is safe on its own terms rather than
by configuration.

---------

Signed-off-by: Deluan <deluan@navidrome.org>
---
 core/artwork/resolve.go                  |  26 +++--
 core/artwork/resolve_test.go             |  25 +++++
 model/album.go                           |   3 +
 model/folder.go                          |   6 +-
 model/mediafile.go                       |   3 +
 persistence/album_repository.go          |  33 ++++++
 persistence/album_repository_test.go     |  75 +++++++++++++-
 persistence/folder_repository.go         |  49 +++++++--
 persistence/folder_repository_test.go    |  37 +++++++
 persistence/mediafile_repository.go      |  20 ++++
 persistence/mediafile_repository_test.go |  48 +++++++++
 scanner/folder_entry.go                  |  51 ++++++---
 scanner/folder_entry_test.go             |   6 +-
 scanner/image_changes.go                 | 112 ++++++++++++++++++++
 scanner/phase_1_folders.go               |  34 +++---
 scanner/scanner_test.go                  | 125 +++++++++++++++++++++++
 16 files changed, 602 insertions(+), 51 deletions(-)
 create mode 100644 scanner/image_changes.go

diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
index 518b6e100..d25f76460 100644
--- a/core/artwork/resolve.go
+++ b/core/artwork/resolve.go
@@ -9,13 +9,14 @@ import (
 	"io/fs"
 	"net/url"
 	"os"
+	"path"
 	"strings"
 
-	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
 )
 
 // resolution is one attempted acquisition outcome for an entity.
@@ -248,12 +249,7 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resoluti
 	}
 
 	// Only consider albums where the artist is the sole album artist.
-	als, err := r.ds.Album(ctx).GetAll(model.QueryOptions{
-		Filters: squirrel.And{
-			squirrel.Eq{"album_artist_id": artistID},
-			squirrel.Eq{"json_array_length(participants, '$.albumartist')": 1},
-		},
-	})
+	als, err := r.ds.Album(ctx).GetAll(model.QueryOptions{Filters: persistence.SoleAlbumArtistFilter(artistID)})
 	if err != nil {
 		return resolution{}, err
 	}
@@ -525,6 +521,22 @@ func resolveFolderFile(ctx context.Context, lib libraryView, imgFiles []string,
 	return resolveFolderSource(lib, fromExternalFile(ctx, lib.FS, imgFiles, pattern))
 }
 
+// IsArtistImageFile reports whether a file name matches any file-glob token of ArtistArtPriority.
+// Basename-only on purpose: the chain climbs parent folders, so a token's prefix is not fixed.
+func IsArtistImageFile(name string) bool {
+	name = strings.ToLower(name)
+	for pattern := range strings.SplitSeq(strings.ToLower(conf.Server.ArtistArtPriority), ",") {
+		pattern = strings.TrimSpace(pattern)
+		if pattern == "" || pattern == externalCandidate || pattern == "image-folder" {
+			continue
+		}
+		if ok, _ := path.Match(path.Base(pattern), name); ok {
+			return true
+		}
+	}
+	return false
+}
+
 func resolveArtistImageFolder(ar *model.Artist) (resolution, bool) {
 	folder := conf.Server.ArtistImageFolder
 	if folder == "" {
diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.go
index 25fb727de..8b4c11c8c 100644
--- a/core/artwork/resolve_test.go
+++ b/core/artwork/resolve_test.go
@@ -21,6 +21,31 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+var _ = Describe("IsArtistImageFile", func() {
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+	})
+
+	It("matches bare and album/-prefixed glob tokens, case-insensitively", func() {
+		conf.Server.ArtistArtPriority = "artist.*, album/artistfolder.*, external"
+		Expect(IsArtistImageFile("Artist.jpg")).To(BeTrue())
+		Expect(IsArtistImageFile("artistfolder.png")).To(BeTrue())
+		Expect(IsArtistImageFile("cover.jpg")).To(BeFalse())
+	})
+
+	It("matches a directory-bearing glob by its basename", func() {
+		conf.Server.ArtistArtPriority = "images/artist.*, external"
+		Expect(IsArtistImageFile("artist.jpg")).To(BeTrue())
+		Expect(IsArtistImageFile("cover.jpg")).To(BeFalse())
+	})
+
+	It("does not treat non-file tokens as globs", func() {
+		conf.Server.ArtistArtPriority = "image-folder, external"
+		Expect(IsArtistImageFile("image-folder")).To(BeFalse())
+		Expect(IsArtistImageFile("external")).To(BeFalse())
+	})
+})
+
 var _ = Describe("resolveItem", func() {
 	var (
 		ctx        context.Context
diff --git a/model/album.go b/model/album.go
index f27ca12c0..5a436fec0 100644
--- a/model/album.go
+++ b/model/album.go
@@ -144,6 +144,9 @@ type AlbumRepository interface {
 	Get(id string) (*Album, error)
 	GetAll(...QueryOptions) (Albums, error)
 	GetAllIDs(...QueryOptions) ([]string, error)
+	// GetSoleAlbumArtistIDsInSubtrees returns the sole album artists of the albums with folders in
+	// any of the given library-relative subtrees.
+	GetSoleAlbumArtistIDsInSubtrees(lib Library, paths ...string) ([]string, error)
 	GetCursor(...QueryOptions) (AlbumCursor, error)
 	GetYears(libraryIDs ...int) ([]int, error)
 
diff --git a/model/folder.go b/model/folder.go
index 81800c072..5207a9db0 100644
--- a/model/folder.go
+++ b/model/folder.go
@@ -76,8 +76,10 @@ func NewFolder(lib Library, folderPath string) *Folder {
 type FolderCursor iter.Seq2[Folder, error]
 
 type FolderUpdateInfo struct {
-	UpdatedAt time.Time
-	Hash      string
+	UpdatedAt       time.Time
+	Hash            string
+	ImageFiles      []string
+	ImagesUpdatedAt time.Time
 }
 
 type FolderRepository interface {
diff --git a/model/mediafile.go b/model/mediafile.go
index 888425d07..f4e767272 100644
--- a/model/mediafile.go
+++ b/model/mediafile.go
@@ -555,6 +555,9 @@ type MediaFileRepository interface {
 	GetCursor(options ...QueryOptions) (MediaFileCursor, error)
 	// GetAllIDs returns just the media_file IDs for the same row set as GetAll.
 	GetAllIDs(options ...QueryOptions) ([]string, error)
+	// GetAlbumIDsByFolder returns the distinct IDs of albums with non-missing tracks in the given
+	// folders or their direct children.
+	GetAlbumIDsByFolder(lib Library, folderIDs ...string) ([]string, error)
 	// GetCursorWithArtwork streams like GetCursor, hydrated, so callers that render images don't
 	// pay the scanner's per-row cost; it uses the same id pre-pass as the other cursors.
 	GetCursorWithArtwork(options ...QueryOptions) (MediaFileCursor, error)
diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 486099fc5..2f0621b73 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -270,6 +270,39 @@ func (r *albumRepository) GetAllIDs(options ...model.QueryOptions) ([]string, er
 	return ids, err
 }
 
+// soleAlbumArtistFilter matches albums with exactly one album artist. The artist artwork
+// resolver and the scanner's image-change enqueue must select the same albums.
+var soleAlbumArtistFilter = Eq{"json_array_length(participants, '$.albumartist')": 1}
+
+// SoleAlbumArtistFilter matches the albums where the given artist is the only album artist.
+// Matches by album-artist participation, not the deprecated album_artist_id column.
+func SoleAlbumArtistFilter(artistID string) Sqlizer {
+	return And{ParticipantIDFilter("album", artistID, model.RoleAlbumArtist), soleAlbumArtistFilter}
+}
+
+// GetSoleAlbumArtistIDsInSubtrees matches albums by their own folder_ids, which is the resolver's
+// notion of an album's folders.
+func (r *albumRepository) GetSoleAlbumArtistIDsInSubtrees(lib model.Library, paths ...string) ([]string, error) {
+	if len(paths) == 0 {
+		return nil, nil
+	}
+	ids := []string{}
+	// Repeated IDs across chunks are fine: the queue upserts by PK.
+	for chunk := range slices.Chunk(paths, subtreePathChunkSize) {
+		inSubtree := Exists("json_each(album.folder_ids) je join folder on folder.id = je.value",
+			folderSubtreeFilter(lib, chunk))
+		// Sole album artist, so participants[0] is the only one.
+		sq := Select("distinct json_extract(participants, '$.albumartist[0].id')").From("album").
+			Where(And{soleAlbumArtistFilter, inSubtree})
+		var chunkIDs []string
+		if err := r.queryAllSlice(sq, &chunkIDs); err != nil {
+			return nil, err
+		}
+		ids = append(ids, chunkIDs...)
+	}
+	return ids, nil
+}
+
 func (r *albumRepository) GetCursor(options ...model.QueryOptions) (model.AlbumCursor, error) {
 	ids, err := r.GetAllIDs(options...)
 	if err != nil {
diff --git a/persistence/album_repository_test.go b/persistence/album_repository_test.go
index 061083949..526642aa6 100644
--- a/persistence/album_repository_test.go
+++ b/persistence/album_repository_test.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"sort"
@@ -20,9 +21,10 @@ import (
 
 var _ = Describe("AlbumRepository", func() {
 	var albumRepo *albumRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
-		ctx := request.WithUser(GinkgoT().Context(), model.User{ID: "userid", UserName: "johndoe"})
+		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "userid", UserName: "johndoe"})
 		albumRepo = NewAlbumRepository(ctx, GetDBXBuilder()).(*albumRepository)
 	})
 
@@ -96,6 +98,77 @@ var _ = Describe("AlbumRepository", func() {
 		})
 	})
 
+	Describe("GetSoleAlbumArtistIDsInSubtrees", func() {
+		It("returns the sole album artists of albums with folders in the subtree", func() {
+			folderRepo := newFolderRepository(ctx, GetDBXBuilder())
+			lib, err := NewLibraryRepository(ctx, GetDBXBuilder()).Get(1)
+			Expect(err).ToNot(HaveOccurred())
+			inTree := model.NewFolder(*lib, "SubtreeAlbums/Artist")
+			outTree := model.NewFolder(*lib, "OtherTree/Artist")
+			Expect(folderRepo.Put(inTree)).To(Succeed())
+			Expect(folderRepo.Put(outTree)).To(Succeed())
+
+			// album_artist_id is deliberately wrong: the artist must come from participants
+			inAl := model.Album{ID: "subtree-in-al", Name: "In", LibraryID: 1, AlbumArtistID: "999", FolderIDs: []string{inTree.ID},
+				Participants: model.Participants{model.RoleAlbumArtist: []model.Participant{{Artist: artistKraftwerk}}}}
+			outAl := model.Album{ID: "subtree-out-al", Name: "Out", LibraryID: 1, AlbumArtistID: "3", FolderIDs: []string{outTree.ID},
+				Participants: model.Participants{model.RoleAlbumArtist: []model.Participant{{Artist: artistBeatles}}}}
+			duoAl := model.Album{ID: "subtree-duo-al", Name: "Duo", LibraryID: 1, AlbumArtistID: "5", FolderIDs: []string{inTree.ID},
+				Participants: model.Participants{model.RoleAlbumArtist: []model.Participant{{Artist: artistPunctuation}, {Artist: artistBeatles}}}}
+			for _, al := range []model.Album{inAl, outAl, duoAl} {
+				Expect(albumRepo.Put(&al)).To(Succeed())
+			}
+			DeferCleanup(func() {
+				_, _ = GetDBXBuilder().NewQuery("DELETE FROM album WHERE id LIKE 'subtree-%'").Execute()
+				_, _ = GetDBXBuilder().NewQuery("DELETE FROM folder WHERE path LIKE 'SubtreeAlbums%' OR path LIKE 'OtherTree%'").Execute()
+			})
+
+			ids, err := albumRepo.GetSoleAlbumArtistIDsInSubtrees(*lib, "SubtreeAlbums")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ids).To(ConsistOf("2")) // sole artist in the subtree; the duo and the outside album are excluded
+		})
+
+		It("stays under SQLite's expression tree depth limit with many paths", func() {
+			lib, err := NewLibraryRepository(ctx, GetDBXBuilder()).Get(1)
+			Expect(err).ToNot(HaveOccurred())
+			paths := make([]string, 200)
+			for i := range paths {
+				paths[i] = fmt.Sprintf("DepthProbe/Folder%d", i)
+			}
+
+			_, err = albumRepo.GetSoleAlbumArtistIDsInSubtrees(*lib, paths...)
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("returns nothing when given no paths", func() {
+			lib, err := NewLibraryRepository(ctx, GetDBXBuilder()).Get(1)
+			Expect(err).ToNot(HaveOccurred())
+			ids, err := albumRepo.GetSoleAlbumArtistIDsInSubtrees(*lib)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ids).To(BeEmpty())
+		})
+	})
+
+	Describe("SoleAlbumArtistFilter", func() {
+		It("matches only albums where the artist is the sole album artist", func() {
+			// album_artist_id is deliberately wrong: matching must come from participation
+			sole := model.Album{ID: "sole-artist-al", Name: "Sole", LibraryID: 1, AlbumArtistID: "999",
+				Participants: model.Participants{model.RoleAlbumArtist: []model.Participant{{Artist: artistKraftwerk}}}}
+			duo := model.Album{ID: "duo-artist-al", Name: "Duo", LibraryID: 1, AlbumArtistID: "999",
+				Participants: model.Participants{model.RoleAlbumArtist: []model.Participant{{Artist: artistKraftwerk}, {Artist: artistBeatles}}}}
+			Expect(albumRepo.Put(&sole)).To(Succeed())
+			Expect(albumRepo.Put(&duo)).To(Succeed())
+			DeferCleanup(func() {
+				_, _ = GetDBXBuilder().NewQuery("DELETE FROM album WHERE id IN ('sole-artist-al', 'duo-artist-al')").Execute()
+			})
+
+			als, err := albumRepo.GetAll(model.QueryOptions{Filters: SoleAlbumArtistFilter("2")})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(als).To(HaveLen(1))
+			Expect(als[0].ID).To(Equal(sole.ID))
+		})
+	})
+
 	Describe("GetAll", func() {
 		var GetAll = func(opts ...model.QueryOptions) (model.Albums, error) {
 			albums, err := albumRepo.GetAll(opts...)
diff --git a/persistence/folder_repository.go b/persistence/folder_repository.go
index 5da395a74..a4b73d9d6 100644
--- a/persistence/folder_repository.go
+++ b/persistence/folder_repository.go
@@ -6,9 +6,7 @@ import (
 	"fmt"
 	"iter"
 	"maps"
-	"os"
 	"path"
-	"path/filepath"
 	"slices"
 	"strings"
 	"time"
@@ -147,9 +145,8 @@ func (r folderRepository) getFolderUpdateInfoBatch(lib model.Library, targetPath
 	pathConditions := make(Or, 0, len(targetPaths)*2)
 
 	for _, targetPath := range targetPaths {
-		// Clean the path to normalize it. Paths stored in the folder table do not have leading/trailing slashes.
-		cleanPath := strings.TrimPrefix(targetPath, string(os.PathSeparator))
-		cleanPath = filepath.Clean(cleanPath)
+		// Slash-form like the stored paths; filepath.Clean would backslash them on Windows.
+		cleanPath := path.Clean(strings.TrimPrefix(targetPath, "/"))
 
 		// Include the target folder itself by ID
 		folderIDs = append(folderIDs, model.FolderID(lib, cleanPath))
@@ -172,11 +169,13 @@ func (r folderRepository) getFolderUpdateInfoBatch(lib model.Library, targetPath
 
 // queryFolderUpdateInfo executes the query and returns the result map
 func (r folderRepository) queryFolderUpdateInfo(where And) (map[string]model.FolderUpdateInfo, error) {
-	sq := r.newSelect().Columns("id", "updated_at", "hash").Where(where)
+	sq := r.newSelect().Columns("id", "updated_at", "hash", "image_files", "images_updated_at").Where(where)
 	var res []struct {
-		ID        string
-		UpdatedAt time.Time
-		Hash      string
+		ID              string
+		UpdatedAt       time.Time
+		Hash            string
+		ImageFiles      string
+		ImagesUpdatedAt time.Time
 	}
 	err := r.queryAll(sq, &res)
 	if err != nil {
@@ -184,11 +183,41 @@ func (r folderRepository) queryFolderUpdateInfo(where And) (map[string]model.Fol
 	}
 	m := make(map[string]model.FolderUpdateInfo, len(res))
 	for _, f := range res {
-		m[f.ID] = model.FolderUpdateInfo{UpdatedAt: f.UpdatedAt, Hash: f.Hash}
+		info := model.FolderUpdateInfo{UpdatedAt: f.UpdatedAt, Hash: f.Hash, ImagesUpdatedAt: f.ImagesUpdatedAt}
+		if f.ImageFiles != "" {
+			if err := json.Unmarshal([]byte(f.ImageFiles), &info.ImageFiles); err != nil {
+				return nil, fmt.Errorf("parsing folder image_files: %w", err)
+			}
+		}
+		m[f.ID] = info
 	}
 	return m, nil
 }
 
+// subtreePathChunkSize bounds how many paths one folderSubtreeFilter may expand into: each adds
+// 3 OR terms, and SQLite rejects an expression tree deeper than 1000 (measured: 166 paths).
+const subtreePathChunkSize = 100
+
+// folderSubtreeFilter matches the folders at the given library-relative paths and all their
+// descendants. A path of "" or "." selects the whole library, so it drops the path conditions.
+func folderSubtreeFilter(lib model.Library, paths []string) Sqlizer {
+	conds := make(Or, 0, len(paths)*3)
+	for _, p := range paths {
+		// Paths are io/fs slash-form; filepath.Clean would backslash them on Windows.
+		cleanPath := path.Clean(strings.TrimPrefix(p, "/"))
+		if cleanPath == "." {
+			return And{Eq{"folder.library_id": lib.ID}, Eq{"folder.missing": false}}
+		}
+		conds = append(conds,
+			Eq{"folder.id": model.FolderID(lib, cleanPath)},
+			// Direct children have path = cleanPath; deeper descendants match the prefix
+			Eq{"folder.path": cleanPath},
+			Expr(`folder.path LIKE ? ESCAPE '\'`, escapeLikePrefix(cleanPath)+"/%"),
+		)
+	}
+	return And{Eq{"folder.library_id": lib.ID}, Eq{"folder.missing": false}, conds}
+}
+
 // HasAudioOutsideFolders reports whether any folder in parent's subtree
 // (including parent itself) contains audio files and is not one of the given
 // folder IDs. LIKE wildcards in the parent path are escaped, so it is always
diff --git a/persistence/folder_repository_test.go b/persistence/folder_repository_test.go
index 8cd45f16b..b429cecb9 100644
--- a/persistence/folder_repository_test.go
+++ b/persistence/folder_repository_test.go
@@ -9,6 +9,7 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/pocketbase/dbx"
@@ -43,6 +44,42 @@ var _ = Describe("FolderRepository", func() {
 		_, _ = conn.NewQuery(fmt.Sprintf("DELETE FROM library WHERE id = %d", otherLib.ID)).Execute()
 	})
 
+	Describe("folderSubtreeFilter", func() {
+		var parent, child, grandchild, other *model.Folder
+
+		matching := func(paths ...string) []string {
+			GinkgoHelper()
+			folders, err := repo.GetAll(model.QueryOptions{Filters: folderSubtreeFilter(testLib, paths)})
+			Expect(err).ToNot(HaveOccurred())
+			return slice.Map(folders, func(f model.Folder) string { return f.ID })
+		}
+
+		BeforeEach(func() {
+			parent = model.NewFolder(testLib, "TestSubtree")
+			child = model.NewFolder(testLib, "TestSubtree/Child")
+			grandchild = model.NewFolder(testLib, "TestSubtree/Child/Grandchild")
+			other = model.NewFolder(testLib, "TestSubtreeOther")
+			for _, f := range []*model.Folder{parent, child, grandchild, other} {
+				Expect(repo.Put(f)).To(Succeed())
+			}
+			DeferCleanup(func() {
+				_, _ = conn.NewQuery("DELETE FROM folder WHERE name LIKE 'TestSubtree%' OR path LIKE 'TestSubtree%'").Execute()
+			})
+		})
+
+		It("matches a folder and all its descendants", func() {
+			Expect(matching("TestSubtree")).To(ConsistOf(parent.ID, child.ID, grandchild.ID))
+		})
+
+		It("matches the descendants of a nested slash-form path", func() {
+			Expect(matching("TestSubtree/Child")).To(ConsistOf(child.ID, grandchild.ID))
+		})
+
+		It("matches the whole library for the root path", func() {
+			Expect(matching(".")).To(ContainElements(parent.ID, child.ID, grandchild.ID, other.ID))
+		})
+	})
+
 	Describe("GetFolderUpdateInfo", func() {
 		Context("with no target paths", func() {
 			It("returns all folders in the library", func() {
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index 5f0addc5e..8146cba2f 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -318,6 +318,26 @@ func (r *mediaFileRepository) GetAllIDs(options ...model.QueryOptions) ([]string
 	return ids, err
 }
 
+func (r *mediaFileRepository) GetAlbumIDsByFolder(lib model.Library, folderIDs ...string) ([]string, error) {
+	ids := []string{}
+	for chunk := range slices.Chunk(folderIDs, 200) {
+		// A folder's own cover also covers albums whose tracks sit in its disc subfolders.
+		inFolders := Select("f.id").From("folder f").Where(And{
+			Eq{"f.library_id": lib.ID},
+			Eq{"f.missing": false},
+			Or{Eq{"f.id": chunk}, Eq{"f.parent_id": chunk}},
+		})
+		sq := Select("distinct album_id").From("media_file").
+			Where(And{Eq{"missing": false}, ConcatExpr("folder_id IN (", inFolders, ")")})
+		var chunkIDs []string
+		if err := r.queryAllSlice(sq, &chunkIDs); err != nil {
+			return nil, err
+		}
+		ids = append(ids, chunkIDs...)
+	}
+	return ids, nil
+}
+
 // GetCursorWithArtwork streams the same rows as GetCursor, hydrated, via an id pre-pass.
 func (r *mediaFileRepository) GetCursorWithArtwork(options ...model.QueryOptions) (model.MediaFileCursor, error) {
 	ids, err := r.GetAllIDs(options...)
diff --git a/persistence/mediafile_repository_test.go b/persistence/mediafile_repository_test.go
index ba89b5def..c1a91c5a5 100644
--- a/persistence/mediafile_repository_test.go
+++ b/persistence/mediafile_repository_test.go
@@ -30,6 +30,54 @@ var _ = Describe("MediaRepository", func() {
 		mr = NewMediaFileRepository(ctx, GetDBXBuilder())
 	})
 
+	Describe("GetAlbumIDsByFolder", func() {
+		var lib model.Library
+		var albumRoot, disc1, sibling *model.Folder
+
+		BeforeEach(func() {
+			ctx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid"})
+			libPtr, err := NewLibraryRepository(ctx, GetDBXBuilder()).Get(1)
+			Expect(err).ToNot(HaveOccurred())
+			lib = *libPtr
+
+			folderRepo := newFolderRepository(ctx, GetDBXBuilder())
+			albumRoot = model.NewFolder(lib, "ByFolder/Album")
+			disc1 = model.NewFolder(lib, "ByFolder/Album/CD1")
+			sibling = model.NewFolder(lib, "ByFolder/Other")
+			for _, f := range []*model.Folder{albumRoot, disc1, sibling} {
+				Expect(folderRepo.Put(f)).To(Succeed())
+			}
+			// Tracks live in the disc subfolder; the sibling album is the negative control.
+			Expect(mr.Put(&model.MediaFile{ID: "fol-mf-1", LibraryID: 1, AlbumID: "fol-al-1", FolderID: disc1.ID, Path: "t/1.mp3"})).To(Succeed())
+			Expect(mr.Put(&model.MediaFile{ID: "fol-mf-2", LibraryID: 1, AlbumID: "fol-al-1", FolderID: disc1.ID, Path: "t/2.mp3"})).To(Succeed())
+			Expect(mr.Put(&model.MediaFile{ID: "fol-mf-3", LibraryID: 1, AlbumID: "fol-al-2", FolderID: sibling.ID, Path: "t/3.mp3"})).To(Succeed())
+			Expect(mr.Put(&model.MediaFile{ID: "fol-mf-4", LibraryID: 1, AlbumID: "fol-al-3", FolderID: disc1.ID, Path: "t/4.mp3", Missing: true})).To(Succeed())
+			DeferCleanup(func() {
+				_, _ = GetDBXBuilder().NewQuery("DELETE FROM media_file WHERE id LIKE 'fol-mf-%'").Execute()
+				_, _ = GetDBXBuilder().NewQuery("DELETE FROM folder WHERE path LIKE 'ByFolder%' OR name = 'ByFolder'").Execute()
+			})
+		})
+
+		It("returns the distinct album IDs of non-missing tracks in the folder", func() {
+			ids, err := mr.GetAlbumIDsByFolder(lib, disc1.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ids).To(ConsistOf("fol-al-1"))
+		})
+
+		It("also matches albums whose tracks are in a direct child of the folder", func() {
+			// A cover in the album root must reach the album whose tracks sit in CD1
+			ids, err := mr.GetAlbumIDsByFolder(lib, albumRoot.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ids).To(ConsistOf("fol-al-1"))
+		})
+
+		It("does not match albums outside the folder", func() {
+			ids, err := mr.GetAlbumIDsByFolder(lib, albumRoot.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ids).ToNot(ContainElement("fol-al-2"))
+		})
+	})
+
 	Describe("GetCursor", func() {
 		It("yields the same media files as GetAll", func() {
 			opts := model.QueryOptions{Sort: "title"}
diff --git a/scanner/folder_entry.go b/scanner/folder_entry.go
index c7cc88ee1..0e893d6e6 100644
--- a/scanner/folder_entry.go
+++ b/scanner/folder_entry.go
@@ -10,21 +10,24 @@ import (
 	"slices"
 	"time"
 
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/chrono"
 )
 
-func newFolderEntry(job *scanJob, id, path string, updTime time.Time, hash string) *folderEntry {
+func newFolderEntry(job *scanJob, id, path string, info model.FolderUpdateInfo) *folderEntry {
 	f := &folderEntry{
-		id:         id,
-		job:        job,
-		path:       path,
-		audioFiles: make(map[string]fs.DirEntry),
-		imageFiles: make(map[string]fs.DirEntry),
-		albumIDMap: make(map[string]string),
-		updTime:    updTime,
-		prevHash:   hash,
+		id:                  id,
+		job:                 job,
+		path:                path,
+		audioFiles:          make(map[string]fs.DirEntry),
+		imageFiles:          make(map[string]fs.DirEntry),
+		albumIDMap:          make(map[string]string),
+		updTime:             info.UpdatedAt,
+		prevHash:            info.Hash,
+		prevImageFiles:      info.ImageFiles,
+		prevImagesUpdatedAt: info.ImagesUpdatedAt,
 	}
 	return f
 }
@@ -42,12 +45,15 @@ type folderEntry struct {
 	numSubFolders   int
 	imagesUpdatedAt time.Time
 	prevHash        string // Previous hash from DB
-	tracks          model.MediaFiles
-	albums          model.Albums
-	albumIDMap      map[string]string
-	artists         model.Artists
-	tags            model.TagList
-	missingTracks   []*model.MediaFile
+	// Previous image state from DB, to detect image-only changes
+	prevImageFiles      []string
+	prevImagesUpdatedAt time.Time
+	tracks              model.MediaFiles
+	albums              model.Albums
+	albumIDMap          map[string]string
+	artists             model.Artists
+	tags                model.TagList
+	missingTracks       []*model.MediaFile
 }
 
 func (f *folderEntry) hasNoFiles() bool {
@@ -69,6 +75,21 @@ func (f *folderEntry) isOutdated() bool {
 	return f.prevHash != f.hash()
 }
 
+// imagesChanged reports whether the folder's image files differ from the previously persisted
+// state, and whether an artist image is involved (present in the old or the new list).
+func (f *folderEntry) imagesChanged() (changed, artistImage bool) {
+	newNames := slices.Sorted(maps.Keys(f.imageFiles))
+	prevNames := slices.Sorted(slices.Values(f.prevImageFiles))
+	// Both empty also skips the timestamp check, which is noise for image-less folders.
+	if len(prevNames) == 0 && len(newNames) == 0 {
+		return false, false
+	}
+	if slices.Equal(prevNames, newNames) && f.prevImagesUpdatedAt.Equal(f.imagesUpdatedAt) {
+		return false, false
+	}
+	return true, slices.ContainsFunc(slices.Concat(prevNames, newNames), artwork.IsArtistImageFile)
+}
+
 func (f *folderEntry) toFolder() *model.Folder {
 	folder := model.NewFolder(f.job.lib, f.path)
 	folder.NumAudioFiles = len(f.audioFiles)
diff --git a/scanner/folder_entry_test.go b/scanner/folder_entry_test.go
index 0328c6653..e8e354b38 100644
--- a/scanner/folder_entry_test.go
+++ b/scanner/folder_entry_test.go
@@ -41,7 +41,7 @@ var _ = Describe("folder_entry", func() {
 				Hash:      "previous-hash",
 			}
 
-			entry := newFolderEntry(job, folderID, path, updateInfo.UpdatedAt, updateInfo.Hash)
+			entry := newFolderEntry(job, folderID, path, updateInfo)
 
 			Expect(entry.id).To(Equal(folderID))
 			Expect(entry.job).To(Equal(job))
@@ -76,7 +76,7 @@ var _ = Describe("folder_entry", func() {
 
 		BeforeEach(func() {
 			folderID := model.FolderID(lib, path)
-			entry = newFolderEntry(job, folderID, path, time.Time{}, "")
+			entry = newFolderEntry(job, folderID, path, model.FolderUpdateInfo{})
 		})
 
 		Describe("hasNoFiles", func() {
@@ -457,7 +457,7 @@ var _ = Describe("folder_entry", func() {
 			// Create new folder entry
 			folderPath := "music/rock/album"
 			folderID := model.FolderID(lib, folderPath)
-			entry := newFolderEntry(job, folderID, folderPath, time.Time{}, "")
+			entry := newFolderEntry(job, folderID, folderPath, model.FolderUpdateInfo{})
 
 			// Initially new and has no files
 			Expect(entry.isNew()).To(BeTrue())
diff --git a/scanner/image_changes.go b/scanner/image_changes.go
new file mode 100644
index 000000000..a9c4de365
--- /dev/null
+++ b/scanner/image_changes.go
@@ -0,0 +1,112 @@
+package scanner
+
+import (
+	"context"
+	"sync"
+
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+// imageChangedFolder records a folder whose image files changed during the scan, so the
+// affected albums/artists can be re-enqueued for artwork resolution at the end of phase 1.
+type imageChangedFolder struct {
+	id          string
+	path        string
+	artistImage bool
+}
+
+// imageChangeCollector gathers those folders per library while phase 1 persists them, then turns
+// them into artwork queue items once.
+type imageChangeCollector struct {
+	libs    map[int]model.Library
+	folders map[int][]imageChangedFolder
+	ds      model.DataStore
+	mutex   sync.Mutex
+}
+
+func (c *imageChangeCollector) record(lib model.Library, folder imageChangedFolder) {
+	c.mutex.Lock()
+	defer c.mutex.Unlock()
+	if c.folders == nil {
+		c.folders = map[int][]imageChangedFolder{}
+		c.libs = map[int]model.Library{}
+	}
+	c.libs[lib.ID] = lib
+	c.folders[lib.ID] = append(c.folders[lib.ID], folder)
+}
+
+// enqueue is best-effort: failures are logged and never fail the scan.
+func (c *imageChangeCollector) enqueue(ctx context.Context) {
+	c.mutex.Lock()
+	foldersMap, libsMap := c.folders, c.libs
+	c.folders, c.libs = nil, nil
+	c.mutex.Unlock()
+
+	for libID, folders := range foldersMap {
+		lib := libsMap[libID]
+		items, err := c.queueItems(ctx, lib, folders)
+		if err != nil {
+			log.Warn(ctx, "Scanner: could not map image changes to artwork items", "lib", lib.Name, err)
+			continue
+		}
+		if len(items) == 0 {
+			continue
+		}
+		if err := c.ds.ArtworkQueue(ctx).Enqueue(items...); err != nil {
+			log.Warn(ctx, "Scanner: could not enqueue artwork for image changes", "lib", lib.Name, err)
+			continue
+		}
+		log.Debug(ctx, "Scanner: Enqueued artwork resolution for image changes", "lib", lib.Name,
+			"changedFolders", len(folders), "items", len(items))
+	}
+}
+
+func (c *imageChangeCollector) queueItems(ctx context.Context, lib model.Library,
+	folders []imageChangedFolder,
+) ([]model.ArtworkQueueItem, error) {
+	folderIDs := make([]string, len(folders))
+	var artistFolderPaths []string
+	for i, f := range folders {
+		folderIDs[i] = f.id
+		if f.artistImage {
+			artistFolderPaths = append(artistFolderPaths, f.path)
+		}
+	}
+
+	var items []model.ArtworkQueueItem
+
+	albumIDs, err := c.ds.MediaFile(ctx).GetAlbumIDsByFolder(lib, folderIDs...)
+	if err != nil {
+		return nil, err
+	}
+	for _, id := range albumIDs {
+		items = append(items, scanArtworkItem(model.KindAlbumArtwork, id))
+	}
+
+	if len(artistFolderPaths) == 0 {
+		return items, nil
+	}
+	// The resolver climbs to the library root, so the subtree below the folder is the affected set.
+	// A failure here must not discard the album items already collected.
+	artistIDs, err := c.ds.Album(ctx).GetSoleAlbumArtistIDsInSubtrees(lib, artistFolderPaths...)
+	if err != nil {
+		log.Warn(ctx, "Scanner: could not map image changes to artists", "lib", lib.Name, err)
+		return items, nil
+	}
+	for _, id := range artistIDs {
+		if id == "" || id == consts.UnknownArtistID || id == consts.VariousArtistsID {
+			continue
+		}
+		items = append(items, scanArtworkItem(model.KindArtistArtwork, id))
+	}
+	return items, nil
+}
+
+func scanArtworkItem(kind model.Kind, id string) model.ArtworkQueueItem {
+	return model.ArtworkQueueItem{
+		ItemKind: kind.Prefix(), ItemID: id, ImageType: model.ImageTypePrimary,
+		Priority: model.ArtworkPriorityScan,
+	}
+}
diff --git a/scanner/phase_1_folders.go b/scanner/phase_1_folders.go
index e853948e6..82e91d5ad 100644
--- a/scanner/phase_1_folders.go
+++ b/scanner/phase_1_folders.go
@@ -45,7 +45,7 @@ func createPhaseFolders(ctx context.Context, state *scanState, ds model.DataStor
 		jobs = append(jobs, job)
 	}
 
-	return &phaseFolders{jobs: jobs, ctx: ctx, ds: ds, state: state}
+	return &phaseFolders{jobs: jobs, ctx: ctx, ds: ds, state: state, imageChanges: &imageChangeCollector{ds: ds}}
 }
 
 type scanJob struct {
@@ -105,7 +105,7 @@ func (j *scanJob) popLastUpdate(folderID string) model.FolderUpdateInfo {
 func (j *scanJob) createFolderEntry(path string) *folderEntry {
 	id := model.FolderID(j.lib, path)
 	info := j.popLastUpdate(id)
-	return newFolderEntry(j, id, path, info.UpdatedAt, info.Hash)
+	return newFolderEntry(j, id, path, info)
 }
 
 // phaseFolders represents the first phase of the scanning process, which is responsible
@@ -125,6 +125,7 @@ type phaseFolders struct {
 	ctx              context.Context
 	state            *scanState
 	prevAlbumPIDConf string
+	imageChanges     *imageChangeCollector
 }
 
 func (p *phaseFolders) description() string {
@@ -169,8 +170,10 @@ func (p *phaseFolders) producer() ppl.Producer[*folderEntry] {
 				// Check if folder is outdated
 				if folder.isOutdated() {
 					if !p.state.fullScan {
-						if folder.hasNoFiles() && folder.isNew() {
-							log.Trace(p.ctx, "Scanner: Skipping new folder with no files", "folder", folder.path, "lib", job.lib.Name)
+						// Ancestor folders need a row even with no files of their own: artwork
+						// resolution climbs them, and an image added later needs a state to diff.
+						if folder.isEmpty() && folder.isNew() {
+							log.Trace(p.ctx, "Scanner: Skipping new empty folder", "folder", folder.path, "lib", job.lib.Name)
 							continue
 						}
 						log.Debug(p.ctx, "Scanner: Detected changes in folder", "folder", folder.path, "lastUpdate", folder.modTime, "lib", job.lib.Name)
@@ -197,7 +200,8 @@ func (p *phaseFolders) measure(entry *folderEntry) func() time.Duration {
 func (p *phaseFolders) stages() []ppl.Stage[*folderEntry] {
 	return []ppl.Stage[*folderEntry]{
 		ppl.NewStage(p.processFolder, ppl.Name("process folder"), ppl.Concurrency(conf.Server.DevScannerThreads)),
-		ppl.NewStage(p.persistChanges, ppl.Name("persist changes")),
+		// persistChanges is not reentrant, so it always has to run with concurrency=1
+		ppl.NewStage(p.persistChanges, ppl.Name("persist changes"), ppl.Concurrency(1)),
 		ppl.NewStage(p.logFolder, ppl.Name("log results")),
 	}
 }
@@ -339,6 +343,15 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 		albumRepo := tx.Album(p.ctx)
 		mfRepo := tx.MediaFile(p.ctx)
 
+		// A new folder's albums/artists are enqueued below; only pre-existing folders need the diff.
+		if !entry.isNew() {
+			if changed, artistImage := entry.imagesChanged(); changed {
+				p.imageChanges.record(entry.job.lib, imageChangedFolder{
+					id: entry.id, path: entry.path, artistImage: artistImage,
+				})
+			}
+		}
+
 		// Save folder to DB
 		folder := entry.toFolder()
 		err := folderRepo.Put(folder)
@@ -368,10 +381,7 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 				return err
 			}
 			if entry.artists[i].Name != consts.UnknownArtist && entry.artists[i].Name != consts.VariousArtists {
-				queueItems = append(queueItems, model.ArtworkQueueItem{
-					ItemKind: model.KindArtistArtwork.Prefix(), ItemID: entry.artists[i].ID, ImageType: model.ImageTypePrimary,
-					Priority: model.ArtworkPriorityScan,
-				})
+				queueItems = append(queueItems, scanArtworkItem(model.KindArtistArtwork, entry.artists[i].ID))
 			}
 		}
 
@@ -383,10 +393,7 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 				return err
 			}
 			if entry.albums[i].Name != consts.UnknownAlbum {
-				queueItems = append(queueItems, model.ArtworkQueueItem{
-					ItemKind: model.KindAlbumArtwork.Prefix(), ItemID: entry.albums[i].ID, ImageType: model.ImageTypePrimary,
-					Priority: model.ArtworkPriorityScan,
-				})
+				queueItems = append(queueItems, scanArtworkItem(model.KindAlbumArtwork, entry.albums[i].ID))
 			}
 		}
 
@@ -518,6 +525,7 @@ func (p *phaseFolders) finalize(err error) error {
 		}
 		return nil
 	}, "scanner: finalize phaseFolders")
+	p.imageChanges.enqueue(p.ctx)
 	return errors.Join(err, errF)
 }
 
diff --git a/scanner/scanner_test.go b/scanner/scanner_test.go
index 6098cbd66..00f91699d 100644
--- a/scanner/scanner_test.go
+++ b/scanner/scanner_test.go
@@ -278,6 +278,131 @@ var _ = Describe("Scanner", Ordered, func() {
 		})
 	})
 
+	Context("Library with image files", func() {
+		var fsys storagetest.FakeFS
+		image := func(data string) *fstest.MapFile { return &fstest.MapFile{Data: []byte(data)} }
+
+		albumID := func(name string) string {
+			GinkgoHelper()
+			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": name}})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(albums).To(HaveLen(1))
+			return albums[0].ID
+		}
+		artistID := func(name string) string {
+			GinkgoHelper()
+			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"artist.name": name}})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(artists).To(HaveLen(1))
+			return artists[0].ID
+		}
+		queuedItems := func() []model.ArtworkQueueItem {
+			GinkgoHelper()
+			queued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+			Expect(err).ToNot(HaveOccurred())
+			return queued
+		}
+		queueItemFor := func(kind, id string) OmegaMatcher {
+			return ContainElement(SatisfyAll(
+				HaveField("ItemKind", kind),
+				HaveField("ItemID", id),
+				HaveField("Priority", model.ArtworkPriorityScan),
+			))
+		}
+
+		BeforeEach(func() {
+			revolver := template(_t{"albumartist": "The Beatles", "album": "Revolver", "year": 1966})
+			wall := template(_t{"albumartist": "Pink Floyd", "album": "The Wall", "year": 1979})
+			fsys = createFS(fstest.MapFS{
+				"The Beatles/artist.jpg":                        image("beatles-artist-v1"),
+				"The Beatles/Revolver/cover.jpg":                image("revolver-cover-v1"),
+				"The Beatles/Revolver/01 - Taxman.mp3":          revolver(track(1, "Taxman")),
+				"Pink Floyd/The Wall/cover.jpg":                 image("wall-cover-v1"),
+				"Pink Floyd/The Wall/CD1/01 - In the Flesh.mp3": wall(track(1, "In the Flesh?")),
+				"Pink Floyd/The Wall/CD2/01 - Hey You.mp3":      wall(track(1, "Hey You")),
+			})
+			Expect(runScanner(ctx, true)).To(Succeed())
+			resolveQueuedArtwork()
+		})
+
+		It("re-enqueues only the album whose cover was replaced in place", func() {
+			fsys.Add("The Beatles/Revolver/cover.jpg", image("revolver-cover-v2"))
+
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			queued := queuedItems()
+			Expect(queued).To(queueItemFor("al", albumID("Revolver")))
+			Expect(queued).ToNot(ContainElement(HaveField("ItemID", albumID("The Wall"))))
+			Expect(queued).ToNot(ContainElement(HaveField("ItemKind", "ar")))
+		})
+
+		It("re-enqueues the album when the cover above its disc folders changes", func() {
+			fsys.Add("Pink Floyd/The Wall/cover.jpg", image("wall-cover-v2"))
+
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			Expect(queuedItems()).To(queueItemFor("al", albumID("The Wall")))
+		})
+
+		It("re-enqueues the album when its cover is removed", func() {
+			fsys.Remove("The Beatles/Revolver/cover.jpg")
+
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			Expect(queuedItems()).To(queueItemFor("al", albumID("Revolver")))
+		})
+
+		It("enqueues the artist when an artist image is added to their folder", func() {
+			fsys.Add("Pink Floyd/artist.jpg", image("floyd-artist-v1"))
+
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			queued := queuedItems()
+			Expect(queued).To(queueItemFor("ar", artistID("Pink Floyd")))
+			Expect(queued).ToNot(ContainElement(HaveField("ItemID", artistID("The Beatles"))))
+		})
+
+		It("re-enqueues the artist when their artist image is replaced in place", func() {
+			fsys.Add("The Beatles/artist.jpg", image("beatles-artist-v2"))
+
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			Expect(queuedItems()).To(queueItemFor("ar", artistID("The Beatles")))
+		})
+
+		It("enqueues every artist under the folder when a shared artist image is added", func() {
+			fsys.Add("artist.png", image("shared-artist-v1"))
+
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			queued := queuedItems()
+			Expect(queued).To(queueItemFor("ar", artistID("The Beatles")))
+			Expect(queued).To(queueItemFor("ar", artistID("Pink Floyd")))
+		})
+
+		It("enqueues the artist when an image lands in a folder first seen by a quick scan", func() {
+			// A quick scan must persist an artist folder that holds only subfolders, or the
+			// artist.jpg added later has no previous state to diff against.
+			kraftwerk := template(_t{"albumartist": "Kraftwerk", "album": "Autobahn", "year": 1974})
+			files := fsys.MapFS
+			files["Kraftwerk/Autobahn/01 - Autobahn.mp3"] = kraftwerk(track(1, "Autobahn"))
+			fsys.SetFiles(files)
+			Expect(runScanner(ctx, false)).To(Succeed())
+			resolveQueuedArtwork()
+
+			fsys.Add("Kraftwerk/artist.jpg", image("kraftwerk-artist-v1"))
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			Expect(queuedItems()).To(queueItemFor("ar", artistID("Kraftwerk")))
+		})
+
+		It("does not enqueue anything on a repeat full scan with no image changes", func() {
+			Expect(runScanner(ctx, true)).To(Succeed())
+
+			Expect(queuedItems()).To(BeEmpty())
+		})
+	})
+
 	Context("Artist with atomic non-ASCII letters, 'GØGGS'", func() {
 		BeforeEach(func() {
 			goggs := template(_t{"albumartist": "GØGGS", "album": "Pre Strike Sweep", "year": 2018})

From ea1e2b95a70074a8e4e98074736f13f0b5ea72a5 Mon Sep 17 00:00:00 2001
From: hotorcelexo <IgorPolyakov@users.noreply.github.com>
Date: Sun, 16 Aug 2026 21:14:41 +0300
Subject: [PATCH 046/200] fix(db): keep album created_at in the driver's
 timestamp format when copying (#5867)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(db): keep album created_at in the driver's timestamp format when
copying

Signed-off-by: IgorPolyakov <igorpolyakov@protonmail.com>

* fix(db): move created_at renormalize migration after merged migrations

The migration was versioned 20260813140000, which is older than
20260815015320 (already merged). goose.UpContext runs without
WithAllowMissing, so any database that already applied the newer
migration would fail with "found 1 missing migrations" and db.Init
would log.Fatal on startup.

---------

Signed-off-by: IgorPolyakov <igorpolyakov@protonmail.com>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 ...816180040_renormalize_album_created_at.sql | 11 ++++++++
 persistence/album_repository.go               |  5 +++-
 persistence/album_repository_test.go          | 26 +++++++++++++++++++
 3 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 db/migrations/20260816180040_renormalize_album_created_at.sql

diff --git a/db/migrations/20260816180040_renormalize_album_created_at.sql b/db/migrations/20260816180040_renormalize_album_created_at.sql
new file mode 100644
index 000000000..9af7b2e5a
--- /dev/null
+++ b/db/migrations/20260816180040_renormalize_album_created_at.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+
+-- Repairs album.created_at values stored in RFC3339 T-format by CopyAttributes.
+-- These values sort incorrectly in "Recently Added", which compares timestamps as raw strings.
+
+UPDATE album SET created_at = replace(replace(created_at, 'T', ' '), 'Z', '+00:00')
+WHERE created_at LIKE '%T%';
+
+-- +goose Down
+
+SELECT 1;
diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 2f0621b73..5d7aad22e 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -329,8 +329,11 @@ func (r *albumRepository) GetYears(libraryIDs ...int) ([]int, error) {
 }
 
 func (r *albumRepository) CopyAttributes(fromID, toID string, columns ...string) error {
+	// Cast values to text so go-sqlite3 does not decode datetime columns as time.Time
+	// and reformat them as RFC3339 when written back.
+	sel := slice.Map(columns, func(c string) string { return fmt.Sprintf("cast(%[1]s as text) as %[1]s", c) })
 	var from dbx.NullStringMap
-	err := r.queryOne(Select(columns...).From(r.tableName).Where(Eq{"id": fromID}), &from)
+	err := r.queryOne(Select(sel...).From(r.tableName).Where(Eq{"id": fromID}), &from)
 	if err != nil {
 		return fmt.Errorf("getting album to copy fields from: %w", err)
 	}
diff --git a/persistence/album_repository_test.go b/persistence/album_repository_test.go
index 526642aa6..f6768768d 100644
--- a/persistence/album_repository_test.go
+++ b/persistence/album_repository_test.go
@@ -19,6 +19,16 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+// rawColumn returns a column exactly as stored, bypassing go-sqlite3's decoding of
+// `datetime` columns into time.Time.
+func rawColumn(r sqlRepository, id, column string) string {
+	var res struct{ Value string }
+	sel := squirrel.Select("cast(" + column + " as text) as value").
+		From(r.tableName).Where(squirrel.Eq{"id": id})
+	ExpectWithOffset(1, r.queryOne(sel, &res)).To(Succeed())
+	return res.Value
+}
+
 var _ = Describe("AlbumRepository", func() {
 	var albumRepo *albumRepository
 	var ctx context.Context
@@ -69,6 +79,22 @@ var _ = Describe("AlbumRepository", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.CreatedAt).To(BeTemporally("~", dstTime, time.Second))
 		})
+		It("returns not found and leaves destination untouched when source does not exist", func() {
+			err := albumRepo.CopyAttributes("copy-missing", "copy-dst", "created_at")
+			Expect(errors.Is(err, model.ErrNotFound)).To(BeTrue())
+			got, getErr := albumRepo.Get("copy-dst")
+			Expect(getErr).ToNot(HaveOccurred())
+			Expect(got.CreatedAt).To(BeTemporally("~", dstTime, time.Second))
+		})
+		It("keeps the copied created_at in the driver's space-separated format", func() {
+			// Copying through a Go string would rewrite it as RFC3339 ("2020-01-02T03:04:05Z"),
+			// which string-sorts above every space-format timestamp and pins the album to the
+			// top of "Recently Added".
+			Expect(albumRepo.CopyAttributes("copy-src", "copy-dst", "created_at")).To(Succeed())
+			Expect(rawColumn(albumRepo.sqlRepository, "copy-dst", "created_at")).
+				To(Equal(rawColumn(albumRepo.sqlRepository, "copy-src", "created_at")))
+			Expect(rawColumn(albumRepo.sqlRepository, "copy-dst", "created_at")).ToNot(ContainSubstring("T"))
+		})
 	})
 
 	Describe("GetCursor", func() {

From 65751d7665e3f1a85c96f661a10227a77bb655d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 17 Aug 2026 15:47:41 -0400
Subject: [PATCH 047/200] fix(playlists): chunk track deletes to stay under the
 SQLite variable limit (#5977)

PlaylistTrackRepository.Delete built a single IN clause with one bind variable per
track, so removing more tracks than SQLITE_MAX_VARIABLE_NUMBER (32766) failed with
"too many SQL variables". Clients that sync a large playlist by adding the desired
tracks and then removing the stale ones would get the add committed and the removal
rejected, leaving the playlist with both sets of tracks and growing it on every sync.

Delete now works in chunks of 200, the same size addTracks already uses, and renumbers
once after the last chunk. Both callers already run inside a transaction, so the
delete stays atomic.
---
 persistence/playlist_track_repository.go      | 11 ++--
 persistence/playlist_track_repository_test.go | 50 +++++++++++++++++++
 2 files changed, 58 insertions(+), 3 deletions(-)

diff --git a/persistence/playlist_track_repository.go b/persistence/playlist_track_repository.go
index c1f6fcf69..a5e1975fd 100644
--- a/persistence/playlist_track_repository.go
+++ b/persistence/playlist_track_repository.go
@@ -2,6 +2,7 @@ package persistence
 
 import (
 	"database/sql"
+	"slices"
 
 	. "github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
@@ -224,10 +225,14 @@ func (r *playlistTrackRepository) AddDiscs(discs []model.DiscID) (int, error) {
 	return r.addMediaFileIds(clauses)
 }
 
+// deleteChunkSize keeps each DELETE under SQLITE_MAX_VARIABLE_NUMBER, matching addTracks.
+const deleteChunkSize = 200
+
 func (r *playlistTrackRepository) Delete(ids ...string) error {
-	err := r.delete(And{Eq{"playlist_id": r.playlistId}, Eq{"id": ids}})
-	if err != nil {
-		return err
+	for chunk := range slices.Chunk(ids, deleteChunkSize) {
+		if err := r.delete(And{Eq{"playlist_id": r.playlistId}, Eq{"id": chunk}}); err != nil {
+			return err
+		}
 	}
 
 	return r.playlistRepo.renumber(r.playlistId)
diff --git a/persistence/playlist_track_repository_test.go b/persistence/playlist_track_repository_test.go
index a5c67b92c..88ddbff48 100644
--- a/persistence/playlist_track_repository_test.go
+++ b/persistence/playlist_track_repository_test.go
@@ -1,6 +1,8 @@
 package persistence
 
 import (
+	"strconv"
+
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -8,6 +10,9 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+// sqliteMaxVariables is SQLITE_MAX_VARIABLE_NUMBER as compiled into the driver
+const sqliteMaxVariables = 32766
+
 var _ = Describe("PlaylistTrackRepository", func() {
 	var repo model.PlaylistTrackRepository
 
@@ -72,4 +77,49 @@ var _ = Describe("PlaylistTrackRepository", func() {
 				To(Equal([]string{songRadioactivity.ID}))
 		})
 	})
+
+	Describe("Delete", func() {
+		var tracks model.PlaylistTrackRepository
+		const numTracks = deleteChunkSize*2 + 1
+
+		positionsUpTo := func(n int) []string {
+			positions := make([]string, 0, n)
+			for i := 1; i <= n; i++ {
+				positions = append(positions, strconv.Itoa(i))
+			}
+			return positions
+		}
+
+		BeforeEach(func() {
+			ctx := log.NewContext(GinkgoT().Context())
+			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+			plsRepo := NewPlaylistRepository(ctx, GetDBXBuilder())
+
+			pls := model.Playlist{Name: "Chunked Delete", OwnerID: "userid", OwnerName: "userid"}
+			Expect(plsRepo.Put(&pls)).To(Succeed())
+			DeferCleanup(func() { Expect(plsRepo.Delete(pls.ID)).To(Succeed()) })
+
+			tracks = plsRepo.Tracks(pls.ID, false)
+			songIds := make([]string, numTracks)
+			for i := range songIds {
+				songIds[i] = songDayInALife.ID
+			}
+			Expect(tracks.Add(songIds)).To(Equal(numTracks))
+		})
+
+		It("removes positions spanning several chunks, and renumbers what is left", func() {
+			Expect(tracks.Delete(positionsUpTo(numTracks - 1)...)).To(Succeed())
+
+			Expect(tracks.CountAll()).To(Equal(int64(1)))
+			remaining, err := tracks.GetAll(model.QueryOptions{Sort: "id"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(remaining[0].ID).To(Equal("1"), "the surviving track must be renumbered to position 1")
+		})
+
+		It("accepts more ids than SQLite allows as bind variables", func() {
+			Expect(tracks.Delete(positionsUpTo(sqliteMaxVariables + 100)...)).To(Succeed())
+
+			Expect(tracks.CountAll()).To(BeZero())
+		})
+	})
 })

From 4c0ab074a36f0450a4ac618e8a74ae8d18eeb4e7 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Mon, 17 Aug 2026 20:36:13 -0400
Subject: [PATCH 048/200] chore(deps): update module dependencies in `go.mod`
 and `go.sum` to latest versions

Signed-off-by: Deluan <deluan@navidrome.org>
---
 go.mod |  58 ++++++++++++------------
 go.sum | 136 ++++++++++++++++++++++++++++-----------------------------
 2 files changed, 96 insertions(+), 98 deletions(-)

diff --git a/go.mod b/go.mod
index b72f4035c..65a01a9b5 100644
--- a/go.mod
+++ b/go.mod
@@ -11,7 +11,7 @@ require (
 	github.com/bmatcuk/doublestar/v4 v4.10.0
 	github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf
 	github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55
-	github.com/dexterlb/mpvipc v0.0.0-20241005113212-7cdefca0e933
+	github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36
 	github.com/djherbis/atime v1.1.0
 	github.com/djherbis/fscache v0.10.2-0.20231127215153-442a07e326c4
 	github.com/djherbis/stream v1.4.0
@@ -26,7 +26,7 @@ require (
 	github.com/go-chi/jwtauth/v5 v5.4.0
 	github.com/go-viper/encoding/ini v0.1.1
 	github.com/go-viper/mapstructure/v2 v2.5.0
-	github.com/gohugoio/hashstructure v0.6.0
+	github.com/gohugoio/hashstructure v1.0.0
 	github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc
 	github.com/google/uuid v1.6.0
 	github.com/google/wire v0.7.0
@@ -35,37 +35,37 @@ require (
 	github.com/jellydator/ttlcache/v3 v3.4.1
 	github.com/kardianos/service v1.3.0
 	github.com/kr/pretty v0.3.1
-	github.com/lestrrat-go/jwx/v3 v3.1.1
-	github.com/mattn/go-sqlite3 v1.14.48
+	github.com/lestrrat-go/jwx/v3 v3.2.0
+	github.com/mattn/go-sqlite3 v1.14.50
 	github.com/microcosm-cc/bluemonday v1.0.27
 	github.com/mileusna/useragent v1.3.5
-	github.com/onsi/ginkgo/v2 v2.32.0
+	github.com/onsi/ginkgo/v2 v2.32.1
 	github.com/onsi/gomega v1.42.1
 	github.com/pelletier/go-toml/v2 v2.4.3
 	github.com/pmezard/go-difflib v1.0.0
 	github.com/pocketbase/dbx v1.12.0
-	github.com/pressly/goose/v3 v3.27.2
-	github.com/prometheus/client_golang v1.23.2
+	github.com/pressly/goose/v3 v3.27.3
+	github.com/prometheus/client_golang v1.24.1
 	github.com/rjeczalik/notify v0.9.3
 	github.com/robfig/cron/v3 v3.0.1
 	github.com/sabhiram/go-gitignore v0.0.0-20210923224102-525f6e181f06
-	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
-	github.com/sirupsen/logrus v1.9.4
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.3
+	github.com/sirupsen/logrus v1.10.0
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
-	github.com/stretchr/testify v1.11.1
+	github.com/stretchr/testify v1.12.0
 	github.com/tetratelabs/wazero v1.12.0
 	github.com/unrolled/secure v1.17.0
 	github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342
 	github.com/zeebo/xxh3 v1.1.0
 	go.senan.xyz/taglib v0.11.1
 	go.uber.org/goleak v1.3.0
-	golang.org/x/image v0.44.0
-	golang.org/x/net v0.57.0
+	golang.org/x/image v0.45.0
+	golang.org/x/net v0.58.0
 	golang.org/x/sync v0.22.0
 	golang.org/x/sys v0.47.0
 	golang.org/x/term v0.45.0
-	golang.org/x/text v0.40.0
+	golang.org/x/text v0.41.0
 	golang.org/x/time v0.15.0
 	gopkg.in/yaml.v3 v3.0.1
 )
@@ -79,22 +79,21 @@ require (
 	github.com/cespare/reflex v0.3.2 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/creack/pty v1.1.24 // indirect
-	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 // indirect
 	github.com/dylibso/observe-sdk/go v0.0.0-20240828172851-9145d8ad07e1 // indirect
-	github.com/ebitengine/purego v0.10.1 // indirect
+	github.com/ebitengine/purego v0.10.2 // indirect
 	github.com/fsnotify/fsnotify v1.10.1 // indirect
-	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/logr v1.4.4 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
 	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
-	github.com/google/pprof v0.0.0-20260709232956-b9395ee17fa0 // indirect
+	github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 // indirect
 	github.com/google/subcommands v1.2.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
-	github.com/ianlancetaylor/demangle v0.0.0-20260505044615-1ff4bf46051f // indirect
+	github.com/ianlancetaylor/demangle v0.0.0-20260724033716-83e58baca724 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 // indirect
 	github.com/klauspost/cpuid/v2 v2.4.0 // indirect
@@ -114,13 +113,13 @@ require (
 	github.com/ogier/pflag v0.0.1 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
-	github.com/prometheus/common v0.67.5 // indirect
-	github.com/prometheus/procfs v0.20.1 // indirect
-	github.com/rogpeppe/go-internal v1.15.0 // indirect
+	github.com/prometheus/common v0.70.1 // indirect
+	github.com/prometheus/procfs v0.21.1 // indirect
+	github.com/rogpeppe/go-internal v1.16.0 // indirect
 	github.com/sagikazarmark/locafero v0.12.0 // indirect
 	github.com/sanity-io/litter v1.5.8 // indirect
 	github.com/segmentio/asm v1.2.1 // indirect
-	github.com/sethvargo/go-retry v0.3.0 // indirect
+	github.com/sethvargo/go-retry v0.4.0 // indirect
 	github.com/sosodev/duration v1.3.1 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
@@ -129,15 +128,14 @@ require (
 	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/tetratelabs/wabin v0.0.0-20230304001439-f6f874872834 // indirect
 	github.com/valyala/fastjson v1.6.10 // indirect
-	go.opentelemetry.io/proto/otlp v1.10.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.11.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	go.yaml.in/yaml/v2 v2.4.3 // indirect
-	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.54.0 // indirect
-	golang.org/x/mod v0.38.0 // indirect
-	golang.org/x/telemetry v0.0.0-20260708182218-49f421fb7959 // indirect
-	golang.org/x/tools v0.48.0 // indirect
-	google.golang.org/protobuf v1.36.11 // indirect
+	go.yaml.in/yaml/v3 v3.0.5 // indirect
+	golang.org/x/crypto v0.55.0 // indirect
+	golang.org/x/mod v0.40.0 // indirect
+	golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5 // indirect
+	golang.org/x/tools v0.49.0 // indirect
+	google.golang.org/protobuf v1.36.12 // indirect
 	gopkg.in/ini.v1 v1.67.3 // indirect
 	gopkg.in/natefinch/npipe.v2 v2.0.0-20160621034901-c1b8fa8bdcce // indirect
 )
diff --git a/go.sum b/go.sum
index 29983a27d..c11f4bb20 100644
--- a/go.sum
+++ b/go.sum
@@ -27,8 +27,6 @@ github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfv
 github.com/davecgh/go-spew v0.0.0-20161028175848-04cdfd42973b/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
-github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
 github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3 h1:j7eSXqgtjhlNfwnMEzRdXnJGZTEw4I7J9TeQAll83bU=
@@ -37,8 +35,8 @@ github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcH
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf/go.mod h1:tSgDythFsl0QgS/PFWfIZqcJKnkADWneY80jaVRlqK8=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55 h1:wSCnggTs2f2ji6nFwQmfwgINcmSMj0xF0oHnoyRSPe4=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55/go.mod h1:ZNCLJfehvEf34B7BbLKjgpsL9lyW7q938w/GY1XgV4E=
-github.com/dexterlb/mpvipc v0.0.0-20241005113212-7cdefca0e933 h1:r4hxcT6GBIA/j8Ox4OXI5MNgMKfR+9plcAWYi1OnmOg=
-github.com/dexterlb/mpvipc v0.0.0-20241005113212-7cdefca0e933/go.mod h1:RkQWLNITKkXHLP7LXxZSgEq+uFWU25M5qW7qfEhL9Wc=
+github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36 h1:KtPfdSST6e0vJbMzMmVqPa5mO1u8vMBlybRCW2ieXpA=
+github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36/go.mod h1:RkQWLNITKkXHLP7LXxZSgEq+uFWU25M5qW7qfEhL9Wc=
 github.com/djherbis/atime v1.1.0 h1:rgwVbP/5by8BvvjBNrbh64Qz33idKT3pSnMSJsxhi0g=
 github.com/djherbis/atime v1.1.0/go.mod h1:28OF6Y8s3NQWwacXc5eZTsEsiMzp7LF8MbXE+XJPdBE=
 github.com/djherbis/fscache v0.10.2-0.20231127215153-442a07e326c4 h1:wdZllsLrDJtYfHiAKogB4PNHSDeO+v+5S3eqSWHGDlc=
@@ -53,8 +51,8 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/dylibso/observe-sdk/go v0.0.0-20240828172851-9145d8ad07e1 h1:idfl8M8rPW93NehFw5H1qqH8yG158t5POr+LX9avbJY=
 github.com/dylibso/observe-sdk/go v0.0.0-20240828172851-9145d8ad07e1/go.mod h1:C8DzXehI4zAbrdlbtOByKX6pfivJTBiV9Jjqv56Yd9Q=
-github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY=
-github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/ebitengine/purego v0.10.2 h1:W809HbnvzAxgdm+aOvlSekrM16wGCdT/e76+9tS7gzE=
+github.com/ebitengine/purego v0.10.2/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
 github.com/extism/go-sdk v1.7.1 h1:lWJos6uY+tRFdlIHR+SJjwFDApY7OypS/2nMhiVQ9Sw=
 github.com/extism/go-sdk v1.7.1/go.mod h1:IT+Xdg5AZM9hVtpFUA+uZCJMge/hbvshl8bwzLtFyKA=
 github.com/fatih/structs v1.1.0 h1:Q7juDM0QtcnhCpeyLGQKyg4TOIghuNXrkL32pHAUMxo=
@@ -79,8 +77,8 @@ github.com/go-chi/httprate v0.16.0 h1:8V5DH9j6pSK6UQoBsTpvMyFxycqaKEIToyPKzHJjUa
 github.com/go-chi/httprate v0.16.0/go.mod h1:A8lo+qRhk+s9LiuP5saS7XCGDXRXMcrueq0NfIuCa/I=
 github.com/go-chi/jwtauth/v5 v5.4.0 h1:Ieh0xMJsFvqylqJ02/mQHKzbbKO9DYNBh4DPKCwTwYI=
 github.com/go-chi/jwtauth/v5 v5.4.0/go.mod h1:w6yjqUUXz1b8+oiJel64Sz1KJwduQM6qUA5QNzO5+bQ=
-github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
-github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8=
+github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
 github.com/go-sql-driver/mysql v1.4.1/go.mod h1:zAC/RDZ24gD3HViQzih4MyKcchzm+sOG5ZlKdlhCg5w=
 github.com/go-sql-driver/mysql v1.10.0 h1:Q+1LV8DkHJvSYAdR83XzuhDaTykuDx0l6fkXxoWCWfw=
 github.com/go-sql-driver/mysql v1.10.0/go.mod h1:M+cqaI7+xxXGG9swrdeUIoPG3Y3KCkF0pZej+SK+nWk=
@@ -96,15 +94,15 @@ github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
 github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
 github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
-github.com/gohugoio/hashstructure v0.6.0 h1:7wMB/2CfXoThFYhdWRGv3u3rUM761Cq29CxUW+NltUg=
-github.com/gohugoio/hashstructure v0.6.0/go.mod h1:lapVLk9XidheHG1IQ4ZSbyYrXcaILU1ZEP/+vno5rBQ=
+github.com/gohugoio/hashstructure v1.0.0 h1:vWYuyzs1n0LdI0F54TJQeYAiB44fHX7H9hCp9X6gHKg=
+github.com/gohugoio/hashstructure v1.0.0/go.mod h1:FSbTK4QwxucJ2bC4Lvrs9a6x0DbQDXNoyBO+h4nlCgE=
 github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc h1:hd+uUVsB1vdxohPneMrhGH2YfQuH5hRIK9u4/XCeUtw=
 github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc/go.mod h1:SL66SJVysrh7YbDCP9tH30b8a9o/N2HeiQNUm85EKhc=
-github.com/google/pprof v0.0.0-20260709232956-b9395ee17fa0 h1:du0WGc8xSKq/++e0cglxhS/mXVqsR7+c7jLEi5Vqduw=
-github.com/google/pprof v0.0.0-20260709232956-b9395ee17fa0/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
 github.com/google/subcommands v1.2.0 h1:vWQspBTo2nEqTUFita5/KeEWlUL8kQObDFbub/EN9oE=
 github.com/google/subcommands v1.2.0/go.mod h1:ZjhPrFU+Olkh9WazFPsl27BQ4UPiG37m3yTrtFlrHVk=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -122,8 +120,8 @@ github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY
 github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
 github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
 github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
-github.com/ianlancetaylor/demangle v0.0.0-20260505044615-1ff4bf46051f h1:NW3E2QSchEk63/fjeEvWOa2cE02FSv9ox//VE/N4c8g=
-github.com/ianlancetaylor/demangle v0.0.0-20260505044615-1ff4bf46051f/go.mod h1:gx7rwoVhcfuVKG5uya9Hs3Sxj7EIvldVofAWIUtGouw=
+github.com/ianlancetaylor/demangle v0.0.0-20260724033716-83e58baca724 h1:QixF8Mcbe87ET7pK/fPbBJ9GXFddmEY8yYMepzMzo30=
+github.com/ianlancetaylor/demangle v0.0.0-20260724033716-83e58baca724/go.mod h1:gx7rwoVhcfuVKG5uya9Hs3Sxj7EIvldVofAWIUtGouw=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/jellydator/ttlcache/v3 v3.4.1 h1:bOdXmXiycyK6E6Qjyuj5vl+/vU3SCOoDs8a86NbHjAQ=
@@ -136,8 +134,8 @@ github.com/kardianos/service v1.3.0 h1:/LGy+xPP2TM+GLTiCZ2di7cy0Jd/qrawlTUfqKYFd
 github.com/kardianos/service v1.3.0/go.mod h1:E4V9ufUuY82F7Ztlu1eN9VXWIQxg8NoLQlmFe0MtrXc=
 github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 h1:Z9n2FFNUXsshfwJMBgNA0RU6/i7WVaAegv3PtuIHPMs=
 github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51/go.mod h1:CzGEWj7cYgsdH8dAjBGEr58BoE7ScuLd+fwFZ44+/x8=
-github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
-github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk=
+github.com/klauspost/compress v1.19.1/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/klauspost/cpuid/v2 v2.4.0 h1:S6Hrbc7+ywsr0r+RLapfGBHfyefhCTwEh3A0tV913Dw=
 github.com/klauspost/cpuid/v2 v2.4.0/go.mod h1:19jmZ9mjzoF//ddRSUsv0zfBTJWh3QJh9FNxZTMrGxU=
 github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
@@ -161,16 +159,16 @@ github.com/lestrrat-go/httpcc v1.0.1 h1:ydWCStUeJLkpYyjLDHihupbn2tYmZ7m22BGkcvZZ
 github.com/lestrrat-go/httpcc v1.0.1/go.mod h1:qiltp3Mt56+55GPVCbTdM9MlqhvzyuL6W/NMDA8vA5E=
 github.com/lestrrat-go/httprc/v3 v3.0.6 h1:4FpLQ18KK/ypPbVU3NLWJNRvH3kcYiqKqWfKGqNWxxI=
 github.com/lestrrat-go/httprc/v3 v3.0.6/go.mod h1:mSMtkZW92Z98M5YoNNztbRGxbXHql7tSitCvaxvo9l0=
-github.com/lestrrat-go/jwx/v3 v3.1.1 h1:yd9AdPmZ4INnQ7k42IrzXYpnEG803+SrQ6hdMvzHJzw=
-github.com/lestrrat-go/jwx/v3 v3.1.1/go.mod h1:uw/MN2M/Xiu4FhwcIwH11Zsh9JWx9SWzgALl7/uIEkU=
+github.com/lestrrat-go/jwx/v3 v3.2.0 h1:Jb3zBASTSZXz7gzzSAfYqxXF8KejvKC4xWoePLQqXCA=
+github.com/lestrrat-go/jwx/v3 v3.2.0/go.mod h1:38vQ8iWKq3qRSbilbzvzdQPuywhowwuR03lhkYskyrw=
 github.com/lestrrat-go/option/v2 v2.0.0 h1:XxrcaJESE1fokHy3FpaQ/cXW8ZsIdWcdFzzLOcID3Ss=
 github.com/lestrrat-go/option/v2 v2.0.0/go.mod h1:oSySsmzMoR0iRzCDCaUfsCzxQHUEuhOViQObyy7S6Vg=
 github.com/maruel/natural v1.3.0 h1:VsmCsBmEyrR46RomtgHs5hbKADGRVtliHTyCOLFBpsg=
 github.com/maruel/natural v1.3.0/go.mod h1:v+Rfd79xlw1AgVBjbO0BEQmptqb5HvL/k9GRHB7ZKEg=
-github.com/mattn/go-isatty v0.0.21 h1:xYae+lCNBP7QuW4PUnNG61ffM4hVIfm+zUzDuSzYLGs=
-github.com/mattn/go-isatty v0.0.21/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
-github.com/mattn/go-sqlite3 v1.14.48 h1:7XHIgl0a8HwOaiK4E47ozLkST78rR9+OtNGx27D/TFs=
-github.com/mattn/go-sqlite3 v1.14.48/go.mod h1:6JTjA44L93a0QCyJef5YvlPoKXntQPjzWv5gtm9sB6w=
+github.com/mattn/go-isatty v0.0.23 h1:cYwCQTQf3HB6xUC+BtyCLZNr7IzbOmoZbmssVNzSyiQ=
+github.com/mattn/go-isatty v0.0.23/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/mattn/go-sqlite3 v1.14.50 h1:dmdFvo1XG4MPzA4IkAmE9upVz/Nj31uRoM5+jC8hYbY=
+github.com/mattn/go-sqlite3 v1.14.50/go.mod h1:6JTjA44L93a0QCyJef5YvlPoKXntQPjzWv5gtm9sB6w=
 github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
 github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg=
 github.com/mfridman/tparse v0.18.0 h1:wh6dzOKaIwkUGyKgOntDW4liXSo37qg5AXbIhkMV3vE=
@@ -187,8 +185,8 @@ github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOF
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/ogier/pflag v0.0.1 h1:RW6JSWSu/RkSatfcLtogGfFgpim5p7ARQ10ECk5O750=
 github.com/ogier/pflag v0.0.1/go.mod h1:zkFki7tvTa0tafRvTBIZTvzYyAu6kQhPZFnshFFPE+g=
-github.com/onsi/ginkgo/v2 v2.32.0 h1:Hw7s2pVrQo/8Yz5N77qdnpHaoc+c6cC9WIV1Jce+J6E=
-github.com/onsi/ginkgo/v2 v2.32.0/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
+github.com/onsi/ginkgo/v2 v2.32.1 h1:6tlvcDm/3sE8lGJbZ4+d4mO3RLy24/tQWOFzVSQNIfw=
+github.com/onsi/ginkgo/v2 v2.32.1/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
 github.com/onsi/gomega v1.42.1 h1:iN1rCUX+44NZ1Dc97MPoeFYbFR0vh8zxoxMFwKdyZ6I=
 github.com/onsi/gomega v1.42.1/go.mod h1:REff/hsDsodHoKlWsP2mAPhu1+5/6hVYNf9rIEBpeSg=
 github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
@@ -201,16 +199,16 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pocketbase/dbx v1.12.0 h1:/oLErM+A0b4xI0PWTGPqSDVjzix48PqI/bng2l0PzoA=
 github.com/pocketbase/dbx v1.12.0/go.mod h1:xXRCIAKTHMgUCyCKZm55pUOdvFziJjQfXaWKhu2vhMs=
-github.com/pressly/goose/v3 v3.27.2 h1:FjKNzcmMdGrQlSIu5alMSmakQtJFBgtw+A0bb1p/LC8=
-github.com/pressly/goose/v3 v3.27.2/go.mod h1:qWW+/8dkVtJYjJrbIpwD5xxnEJTUKvxkQ9JKQp9LaIM=
-github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
-github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
+github.com/pressly/goose/v3 v3.27.3 h1:pIglVHjw99r4e/hDHHwbl9vfOsDMqUokfkXo6+n/RxA=
+github.com/pressly/goose/v3 v3.27.3/go.mod h1:Dag+xpV6o20HR2LFY1j0q6MDwc3f7vPUFDA77R+0yGY=
+github.com/prometheus/client_golang v1.24.1 h1:JnJkREXzWxUdCuPFpIWZiPispT9xVV59uiuyR2bPlnU=
+github.com/prometheus/client_golang v1.24.1/go.mod h1:F+oSRECHg4sse5ucfYpYDeIv/hu68Zo0uoHKetWnzcE=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
-github.com/prometheus/common v0.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4=
-github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw=
-github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEycfc=
-github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4UlK79eF5TGGo=
+github.com/prometheus/common v0.70.1 h1:1HvjP4D5oL3t8RsPlwxA9onvvStjtIHYE5XuuwOi/PY=
+github.com/prometheus/common v0.70.1/go.mod h1:VdFUQDMZK3VLkurFUVhia6uys/0suUp86TJz5qbJRhc=
+github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
+github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 github.com/rjeczalik/notify v0.9.3 h1:6rJAzHTGKXGj76sbRgDiDcYj/HniypXmSJo1SWakZeY=
@@ -218,8 +216,8 @@ github.com/rjeczalik/notify v0.9.3/go.mod h1:gF3zSOrafR9DQEWSE8TjfI9NkooDxbyT4Ug
 github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
 github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
-github.com/rogpeppe/go-internal v1.15.0 h1:D0RCU5rMAp+SpgkiNdrjfJ+LX4J1M32V2NeCY7EJ6hc=
-github.com/rogpeppe/go-internal v1.15.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
+github.com/rogpeppe/go-internal v1.16.0 h1:O9DK+vNMDVGLr2BeZqmpLeMjiMNkuXfcqntWbZV6S5g=
+github.com/rogpeppe/go-internal v1.16.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sabhiram/go-gitignore v0.0.0-20210923224102-525f6e181f06 h1:OkMGxebDjyw0ULyrTYWeN0UNCCkmCWfjPnIA2W6oviI=
 github.com/sabhiram/go-gitignore v0.0.0-20210923224102-525f6e181f06/go.mod h1:+ePHsJ1keEjQtpvf9HHw0f4ZeJ0TLRsxhunSI2hYJSs=
@@ -227,15 +225,15 @@ github.com/sagikazarmark/locafero v0.12.0 h1:/NQhBAkUb4+fH1jivKHWusDYFjMOOKU88ee
 github.com/sagikazarmark/locafero v0.12.0/go.mod h1:sZh36u/YSZ918v0Io+U9ogLYQJ9tLLBmM4eneO6WwsI=
 github.com/sanity-io/litter v1.5.8 h1:uM/2lKrWdGbRXDrIq08Lh9XtVYoeGtcQxk9rtQ7+rYg=
 github.com/sanity-io/litter v1.5.8/go.mod h1:9gzJgR2i4ZpjZHsKvUXIRQVk7P+yM3e+jAF7bU2UI5U=
-github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
-github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
 github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
-github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE=
-github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas=
+github.com/sethvargo/go-retry v0.4.0 h1:9qy1OoIAxBL+gBYnkTnTnWle5wlfsXQlwRzIbbpdqPw=
+github.com/sethvargo/go-retry v0.4.0/go.mod h1:tvsjdKG6xfiCx4LSiUZ06kcv38xvdVQwv8R6/VnnVWg=
 github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=
-github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
-github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
+github.com/sirupsen/logrus v1.10.0 h1:T8MxJJXVZkfcC5zSRMRAg2F8+lxjmUCGGWPzFxO+Msc=
+github.com/sirupsen/logrus v1.10.0/go.mod h1:FXZFonkDAnFozmO+5hGAFvB0Yg9/j2SIhA/QuIkP180=
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d h1:zE9ykElWQ6/NYmHa3jpm/yHnI4xSofP+UP6SpjHcSeM=
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
 github.com/smartystreets/goconvey v1.6.4 h1:fv0U8FUIMPNf1L9lnHLvLhgicrIVChEkdzIKYqbNC9s=
@@ -267,8 +265,9 @@ github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/stretchr/testify v1.12.0 h1:K6Mr6jO9JICuend/5xzTM03ydSV3vdNRYAdPSukj8uI=
+github.com/stretchr/testify v1.12.0/go.mod h1:bOYBZb5qJ00vPzWfIqBUZPaxK8jWiXc6d3ErP4Ca9Gw=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
 github.com/tetratelabs/wabin v0.0.0-20230304001439-f6f874872834 h1:ZF+QBjOI+tILZjBaFj3HgFonKXUcwgJ4djLb6i42S3Q=
@@ -293,27 +292,28 @@ github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
 github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
 github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
 github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
-go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g=
-go.opentelemetry.io/proto/otlp v1.10.0/go.mod h1:/CV4QoCR/S9yaPj8utp3lvQPoqMtxXdzn7ozvvozVqk=
+go.opentelemetry.io/proto/otlp v1.11.0 h1:5rrYs0Ykyj50sdU/JU0x8etU+LubXWb+gED6TbEdMIk=
+go.opentelemetry.io/proto/otlp v1.11.0/go.mod h1:SmVizdCOAm3XBtG1g1NnOdhW6jtddT72hLMhv8VwA8E=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
 go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
-go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
-go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=
-go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
+go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
+go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
+go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
-golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
-golang.org/x/image v0.44.0 h1:+tDekMZED9+LrtB3G5xzRggpVh9CARjZqROla3R3R+I=
-golang.org/x/image v0.44.0/go.mod h1:V8K3KE9KKKE+pLpQDOeN18w9oacNSvy1tDOirTu4xtY=
-golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
-golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
+golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M=
+golang.org/x/crypto v0.55.0/go.mod h1:uq0V9dE/fzQuJtbnL+2EhWOE63vo164FY8xqEnV9xis=
+golang.org/x/image v0.45.0 h1:FMb1nTbH5H9vF55SriQHgFw5GnNL9Jg6L25BwXKzhB0=
+golang.org/x/image v0.45.0/go.mod h1:n62x/7RqlwXDvGsSU4u6IUTUf6KghUZ9Bt7cG/T9Fx4=
+golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
+golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=
 golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
-golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE=
-golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU=
+golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
+golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
 golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
 golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20180926160741-c2ed4eda69e7/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
@@ -322,26 +322,26 @@ golang.org/x/sys v0.0.0-20190422165155-953cdadca894/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20220615213510-4f61da869c0c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
 golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/telemetry v0.0.0-20260708182218-49f421fb7959 h1:RJhm5l6Fo4rmEIcndxDllNhhf/fAx8qIm4t6A7vpm2A=
-golang.org/x/telemetry v0.0.0-20260708182218-49f421fb7959/go.mod h1:LV7u5Oco+Z/g6XI7PqN+EUUUGGkEcmB1uj2ceI0fOVg=
+golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5 h1:ZUSxONxc981v7AW7QUg+I9WwZzSTTJ019ENBYr5pV/Q=
+golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5/go.mod h1:LVehoXe41cL5SCVQilsV7Gg6BNG+Js6P9PhSbYTIUkQ=
 golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
 golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
-golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
-golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
+golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
-golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
-golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
+golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
+golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
 google.golang.org/appengine v1.6.5/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCIDZVag1xfc=
-google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
-google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
+google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
-gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=
+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/ini.v1 v1.67.3 h1:iM9Lhz5MRSGhHVGGwCuzG9KO8PoirCXj/m/qTmOJJQw=
 gopkg.in/ini.v1 v1.67.3/go.mod h1:x/cyOwCgZqOkJoDIJ3c1KNHMo10+nLGAhh+kn3Zizss=
 gopkg.in/natefinch/npipe.v2 v2.0.0-20160621034901-c1b8fa8bdcce h1:+JknDZhAj8YMt7GC73Ei8pv4MzjDUNPHgQWJdtMAaDU=
@@ -350,11 +350,11 @@ gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-modernc.org/libc v1.73.4 h1:+ra4Ui8ngyt8HDcO1FTDPWlkAh6yOdaO2yAoh8MddQA=
-modernc.org/libc v1.73.4/go.mod h1:DXZ3eO8qMCNn2SnmTNCiC71nJ9Rcq3PsnpU6Vc4rWK8=
+modernc.org/libc v1.74.3 h1:a4J+Z8aVaxPyjyxRAdJzw246PqpcFGvVPnfT/AuM5Ws=
+modernc.org/libc v1.74.3/go.mod h1:4H7h/MJ8wnjL8RAbp9v3OXgnk22X7MouHIhDbvP3gj4=
 modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
 modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
 modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
 modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
-modernc.org/sqlite v1.53.0 h1:20WG8N9q4ji/dEqGk4uiI0c6OPjSeLTNYGFCc3+7c1M=
-modernc.org/sqlite v1.53.0/go.mod h1:xoEpOIpGrgT48H5iiyt/YXPCZPEzlfmfFwtk8Lklw8s=
+modernc.org/sqlite v1.54.0 h1:JCxR4qwkJvOaqAoYcgDoO25Nc+ROg6EJ2LfBVzdrgog=
+modernc.org/sqlite v1.54.0/go.mod h1:4ntCLuNmnH8+GNqjka1wNg7KJd5/Hi5FYp8K+XQ7GZw=

From 4b1218eec0068ba8b119a970385aea5b0605660b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 18 Aug 2026 09:32:26 -0400
Subject: [PATCH 049/200] feat(ui): show translation completion percentage in
 the language selector (#5979)

The language selector now shows how complete each translation is, so users
can see at a glance which languages are lagging behind English. The native
API's translation resource gained a termCount field holding the number of
non-empty terms in each language file; the UI divides that by the term count
of the bundled English file to get the percentage.

The percentage is wrapped in a Unicode left-to-right isolate, otherwise it
renders as "(%61)" beside right-to-left names such as Arabic and Persian.
Sorting runs on the plain language name, before the percentage is appended.

This also fixes prepareLanguage() mutating the bundled English translations:
for the English locale it received the shared en object and aliased albumSong
and playlistTrack onto it, growing en by 94 keys at runtime. That inflated the
denominator and made every language read about 14 points low. The aliases now
go on the merged copy instead.
---
 server/nativeapi/translations.go           | 36 +++++++--
 server/nativeapi/translations_test.go      | 12 +++
 ui/src/i18n/provider.js                    | 11 +--
 ui/src/i18n/provider.test.js               | 19 +++++
 ui/src/i18n/useGetLanguageChoices.jsx      | 31 +++++++-
 ui/src/i18n/useGetLanguageChoices.test.jsx | 92 ++++++++++++++++++++++
 6 files changed, 184 insertions(+), 17 deletions(-)
 create mode 100644 ui/src/i18n/provider.test.js
 create mode 100644 ui/src/i18n/useGetLanguageChoices.test.jsx

diff --git a/server/nativeapi/translations.go b/server/nativeapi/translations.go
index 685713083..39d071279 100644
--- a/server/nativeapi/translations.go
+++ b/server/nativeapi/translations.go
@@ -17,9 +17,10 @@ import (
 )
 
 type translation struct {
-	ID   string `json:"id"`
-	Name string `json:"name"`
-	Data string `json:"data"`
+	ID        string `json:"id"`
+	Name      string `json:"name"`
+	Data      string `json:"data"`
+	TermCount int    `json:"termCount"`
 }
 
 func newTranslationRepository(context.Context) rest.Repository {
@@ -97,27 +98,46 @@ func loadTranslation(fsys fs.FS, fileName string) (translation translation, err
 	// Load translation from json file
 	file, err := fsys.Open(filePath)
 	if err != nil {
-		return
+		return translation, err
 	}
 	data, err := io.ReadAll(file)
 	if err != nil {
-		return
+		return translation, err
 	}
 	var out map[string]any
 	if err = json.Unmarshal(data, &out); err != nil {
-		return
+		return translation, err
 	}
 
 	// Compress JSON
 	buf := new(bytes.Buffer)
 	if err = json.Compact(buf, data); err != nil {
-		return
+		return translation, err
 	}
 
 	translation.Data = buf.String()
 	translation.Name = out["languageName"].(string)
 	translation.ID = id
-	return
+	translation.TermCount = countTranslatedTerms(out)
+	return translation, nil
+}
+
+// countTranslatedTerms counts non-empty leaf values, matching the UI's notion of a translated term
+func countTranslatedTerms(obj map[string]any) int {
+	count := 0
+	for _, v := range obj {
+		switch v := v.(type) {
+		case map[string]any:
+			count += countTranslatedTerms(v)
+		case string:
+			if v != "" {
+				count++
+			}
+		default:
+			count++
+		}
+	}
+	return count
 }
 
 var _ rest.Repository = (*translationRepository)(nil)
diff --git a/server/nativeapi/translations_test.go b/server/nativeapi/translations_test.go
index 6c834070c..77c088f6f 100644
--- a/server/nativeapi/translations_test.go
+++ b/server/nativeapi/translations_test.go
@@ -6,6 +6,7 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"testing/fstest"
 
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/resources"
@@ -45,5 +46,16 @@ var _ = Describe("Translations", func() {
 			var out map[string]any
 			Expect(json.Unmarshal([]byte(tr.Data), &out)).To(BeNil())
 		})
+
+		It("counts only non-empty leaf terms", func() {
+			fsys := fstest.MapFS{
+				"i18n/test.json": &fstest.MapFile{
+					Data: []byte(`{"languageName":"Test","a":"x","b":"","nested":{"c":"y","d":""}}`),
+				},
+			}
+			tr, err := loadTranslation(fsys, "test.json")
+			Expect(err).To(BeNil())
+			Expect(tr.TermCount).To(Equal(3))
+		})
 	})
 })
diff --git a/ui/src/i18n/provider.js b/ui/src/i18n/provider.js
index f17a5b4ac..58f1782bb 100644
--- a/ui/src/i18n/provider.js
+++ b/ui/src/i18n/provider.js
@@ -42,13 +42,14 @@ const removeEmpty = (obj) => {
 
 const prepareLanguage = (lang) => {
   removeEmpty(lang)
+  // Aliases below go on the merged copy: mutating `en` would corrupt the completion baseline
+  const merged = deepmerge(en, lang)
   // Make "albumSong" and "playlistTrack" resource use the same translations as "song"
-  lang.resources.albumSong = lang.resources.song
-  lang.resources.playlistTrack = lang.resources.song
+  merged.resources.albumSong = merged.resources.song
+  merged.resources.playlistTrack = merged.resources.song
   // ra.boolean.null should always be empty
-  lang.ra.boolean.null = ''
-  // Fallback to english translations
-  return deepmerge(en, lang)
+  merged.ra.boolean.null = ''
+  return merged
 }
 
 export default polyglotI18nProvider((locale) => {
diff --git a/ui/src/i18n/provider.test.js b/ui/src/i18n/provider.test.js
new file mode 100644
index 000000000..82b593788
--- /dev/null
+++ b/ui/src/i18n/provider.test.js
@@ -0,0 +1,19 @@
+import { describe, it, expect, vi } from 'vitest'
+import en from './en.json'
+
+vi.mock('../dataProvider', () => ({ default: { getOne: vi.fn() } }))
+
+const countLeaves = (obj) =>
+  Object.values(obj).reduce(
+    (sum, v) =>
+      sum + (typeof v === 'object' && v !== null ? countLeaves(v) : v ? 1 : 0),
+    0,
+  )
+
+describe('i18n provider', () => {
+  it('does not mutate the bundled English translations', async () => {
+    const before = countLeaves(en)
+    await import('./provider')
+    expect(countLeaves(en)).toEqual(before)
+  })
+})
diff --git a/ui/src/i18n/useGetLanguageChoices.jsx b/ui/src/i18n/useGetLanguageChoices.jsx
index 0c708691f..38f95e422 100644
--- a/ui/src/i18n/useGetLanguageChoices.jsx
+++ b/ui/src/i18n/useGetLanguageChoices.jsx
@@ -1,5 +1,22 @@
 // React Hook to get a list of all languages available. English is hardcoded
 import { useGetList } from 'react-admin'
+import en from './en.json'
+
+const countLeaves = (obj) =>
+  Object.values(obj).reduce(
+    (sum, v) =>
+      sum + (typeof v === 'object' && v !== null ? countLeaves(v) : v ? 1 : 0),
+    0,
+  )
+
+const enTermCount = countLeaves(en)
+
+const withPercentage = ({ id, name, termCount }) => {
+  if (!termCount) return { id, name }
+  const pct = Math.min(100, Math.round((100 * termCount) / enTermCount))
+  // Isolate the percentage, or it renders as "(%61)" next to a right-to-left name
+  return { id, name: `${name} ⁦(${pct}%)⁩` }
+}
 
 const useGetLanguageChoices = () => {
   const { ids, data, loaded, loading } = useGetList(
@@ -9,13 +26,19 @@ const useGetLanguageChoices = () => {
     {},
   )
 
-  const choices = [{ id: 'en', name: 'English' }]
+  const languages = [{ id: 'en', name: 'English', termCount: enTermCount }]
   if (loaded) {
-    ids.forEach((id) => choices.push({ id: id, name: data[id].name }))
+    ids.forEach((id) =>
+      languages.push({
+        id,
+        name: data[id].name,
+        termCount: data[id].termCount,
+      }),
+    )
   }
-  choices.sort((a, b) => a.name.localeCompare(b.name))
+  languages.sort((a, b) => a.name.localeCompare(b.name))
 
-  return { choices, loaded, loading }
+  return { choices: languages.map(withPercentage), loaded, loading }
 }
 
 export default useGetLanguageChoices
diff --git a/ui/src/i18n/useGetLanguageChoices.test.jsx b/ui/src/i18n/useGetLanguageChoices.test.jsx
new file mode 100644
index 000000000..b8214868e
--- /dev/null
+++ b/ui/src/i18n/useGetLanguageChoices.test.jsx
@@ -0,0 +1,92 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook } from '@testing-library/react-hooks'
+import { useGetList } from 'react-admin'
+import en from './en.json'
+import useGetLanguageChoices from './useGetLanguageChoices'
+
+vi.mock('react-admin', () => ({
+  useGetList: vi.fn(),
+}))
+
+const countLeaves = (obj) =>
+  Object.values(obj).reduce(
+    (sum, v) =>
+      sum + (typeof v === 'object' && v !== null ? countLeaves(v) : v ? 1 : 0),
+    0,
+  )
+const enTermCount = countLeaves(en)
+
+// The percentage is wrapped in a left-to-right isolate, so it reads the same
+// next to right-to-left language names
+const label = (pct) => `⁦(${pct}%)⁩`
+
+const mockLanguages = (languages) => {
+  const data = {}
+  languages.forEach((l) => (data[l.id] = l))
+  useGetList.mockReturnValue({
+    ids: languages.map((l) => l.id),
+    data,
+    loaded: true,
+    loading: false,
+  })
+}
+
+const choiceFor = (id) => {
+  const { result } = renderHook(() => useGetLanguageChoices())
+  return result.current.choices.find((c) => c.id === id)
+}
+
+describe('useGetLanguageChoices', () => {
+  it('appends the completion percentage to incomplete languages', () => {
+    const termCount = Math.round(enTermCount * 0.62)
+    mockLanguages([{ id: 'cs', name: 'Čeština', termCount }])
+
+    const pct = Math.round((100 * termCount) / enTermCount)
+    expect(choiceFor('cs').name).toEqual(`Čeština ${label(pct)}`)
+  })
+
+  it('shows 100% for a complete language', () => {
+    mockLanguages([{ id: 'de', name: 'Deutsch', termCount: enTermCount }])
+
+    expect(choiceFor('de').name).toEqual(`Deutsch ${label(100)}`)
+  })
+
+  it('caps the percentage at 100 when a language has extra terms', () => {
+    mockLanguages([
+      { id: 'pt', name: 'Português', termCount: enTermCount + 20 },
+    ])
+
+    expect(choiceFor('pt').name).toEqual(`Português ${label(100)}`)
+  })
+
+  it('isolates the percentage next to a right-to-left name', () => {
+    const termCount = Math.round(enTermCount * 0.61)
+    mockLanguages([{ id: 'ar', name: 'العربية', termCount }])
+
+    const pct = Math.round((100 * termCount) / enTermCount)
+    expect(choiceFor('ar').name).toEqual(`العربية ⁦(${pct}%)⁩`)
+  })
+
+  it('omits the percentage when the server does not send a term count', () => {
+    mockLanguages([{ id: 'fr', name: 'Français' }])
+
+    expect(choiceFor('fr').name).toEqual('Français')
+  })
+
+  it('shows 100% for the bundled English', () => {
+    mockLanguages([])
+
+    expect(choiceFor('en').name).toEqual(`English ${label(100)}`)
+  })
+
+  it('sorts by language name, ignoring the percentage', () => {
+    mockLanguages([
+      { id: 'no', name: 'Norsk', termCount: enTermCount },
+      { id: 'da', name: 'Dansk', termCount: 1 },
+    ])
+
+    const { result } = renderHook(() => useGetLanguageChoices())
+
+    expect(result.current.choices.map((c) => c.id)).toEqual(['da', 'en', 'no'])
+  })
+})

From 2e03766a9df84cb24303bd2ebc808402ad7c1a45 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 18 Aug 2026 20:58:55 -0400
Subject: [PATCH 050/200] fix(playlist): preserve smart playlist song count on
 re-import (#5907) (#5908)

* fix(playlist): preserve smart playlist counters on re-import (#5907)

* perf(playlist): skip re-importing unchanged NSP files (#5907)

* feat(playlist): also store content hash for M3U imports (unused for now)

* fix(playlist): return stored record when skipping unchanged NSP import

Skipping before copying the stored identity broke the ImportFile(sync=false)
contract: callers received an ID-less playlist and the requested Sync change
was silently dropped.

* refactor(playlist): hash imports once at the caller; protect smart counters in Put

Move content hashing out of both parsers into the code that owns the file
(parsePlaylist and ImportFile), removing the NSP double-buffer and the
duplicated hashing idiom. Put now drops song_count/duration/size for smart
playlists (PostMapArgs), disarming the counter-zeroing trap for all callers.

* fix(playlist): invalidate imported hash when rules are edited via API

Without this, a rules edit through the REST API kept the stored file hash,
so every scan skipped the unchanged file and never restored the file-backed
rules while sync was on.

* test(playlist): verify smart counters survive a re-import, end to end

The existing Put test seeds the stored counters with a raw SQL update, so it
pins the guard in PostMapArgs but not the pipeline around it. This test drives
the counters through a real evaluation instead: it saves a smart playlist, reads
it with GetWithTracks to populate song_count/duration/size, then saves the
playlist the way the scanner rebuilds it after parsing the .nsp file, with the
counters back at zero. Both routes fail without the guard, and the new one
covers the exact sequence reported in #5907.

Test taken from #5970, which diagnosed the same root cause independently.

Co-authored-by: Junker der Provinz <133605895+junkerderprovinz@users.noreply.github.com>

* test(playlist): build the service with artwork.NewUploader

The artwork pipeline in #5847 replaced core.NewImageUploadService() with
artwork.NewUploader(ds) and updated every call site it could see. The five call
sites this branch adds were written against the old constructor, so the merge
applied cleanly but left the package uncompilable.

* fix(db): re-stamp the imported_hash migration after the master merge

Master gained three migrations while this branch was open, the newest being
20260816180040. The original 20260808200333 stamp now sorts before them, so any
database already upgraded past that point would skip this migration entirely and
never get the imported_hash column. Same SQL, current timestamp.

* refactor(playlist): hash imported playlists with xxh3 and the id encoding

ImportedHash is a change detector, not a security boundary, so it does not need
a cryptographic digest. xxh3 is already a direct dependency and is used the same
way to fingerprint files in the artwork image store. Encoding the 128-bit digest
with id.Encode stores it in the same 22-char base62 form as every other id in the
schema, down from 64 hex chars.

No migration is needed: the imported_hash column has not shipped in a release, so
no database holds a value in the old format.

* refactor(playlist): extract the imported-playlist fingerprint helper

Both import paths encoded the hash inline, so how a playlist file is fingerprinted
lived in two places. A third import path that encoded it differently would silently
never match the stored value, turning the unchanged-file skip into a no-op.

---------

Co-authored-by: Junker der Provinz <133605895+junkerderprovinz@users.noreply.github.com>
---
 core/playlists/import.go                      |  32 +++-
 core/playlists/import_test.go                 | 143 ++++++++++++++++++
 core/playlists/rest_adapter.go                |   1 +
 core/playlists/rest_adapter_test.go           |  19 +++
 ...60818002312_add_playlist_imported_hash.sql |   5 +
 model/playlist.go                             |   1 +
 persistence/playlist_repository.go            |   4 +
 persistence/playlist_repository_test.go       |  27 ++++
 persistence/smart_playlist_repository_test.go |  35 +++++
 9 files changed, 264 insertions(+), 3 deletions(-)
 create mode 100644 db/migrations/20260818002312_add_playlist_imported_hash.sql

diff --git a/core/playlists/import.go b/core/playlists/import.go
index bafb870cd..e41f61bd1 100644
--- a/core/playlists/import.go
+++ b/core/playlists/import.go
@@ -12,8 +12,10 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/utils/ioutils"
+	"github.com/zeebo/xxh3"
 	"golang.org/x/text/unicode/norm"
 )
 
@@ -57,10 +59,12 @@ func (s *playlists) ImportFile(ctx context.Context, absolutePath string, sync bo
 	}
 	defer file.Close()
 
-	reader := ioutils.UTF8Reader(file)
+	hasher := xxh3.New()
+	reader := io.TeeReader(ioutils.UTF8Reader(file), hasher)
 	if err := s.parseM3U(ctx, pls, nil, reader); err != nil {
 		return nil, err
 	}
+	pls.ImportedHash = fingerprint(hasher)
 	if err := s.updatePlaylist(ctx, pls, sync); err != nil {
 		return nil, err
 	}
@@ -138,7 +142,9 @@ func (s *playlists) parsePlaylist(ctx context.Context, playlistFile string, fold
 	}
 	defer file.Close()
 
-	reader := ioutils.UTF8Reader(file)
+	// Hash the bytes the parser consumes, giving every imported playlist a content fingerprint
+	hasher := xxh3.New()
+	reader := io.TeeReader(ioutils.UTF8Reader(file), hasher)
 	extension := strings.ToLower(filepath.Ext(playlistFile))
 	switch extension {
 	case ".nsp":
@@ -146,7 +152,15 @@ func (s *playlists) parsePlaylist(ctx context.Context, playlistFile string, fold
 	default:
 		err = s.parseM3U(ctx, pls, folder, reader)
 	}
-	return pls, err
+	if err != nil {
+		return pls, err
+	}
+	pls.ImportedHash = fingerprint(hasher)
+	return pls, nil
+}
+
+func fingerprint(h *xxh3.Hasher) string {
+	return id.Encode(h.Sum128().Bytes())
 }
 
 // findByPathNormalized looks up a playlist by path, trying both NFC and NFD Unicode
@@ -179,6 +193,12 @@ func (s *playlists) updatePlaylist(ctx context.Context, newPls *model.Playlist,
 	}
 
 	if err == nil {
+		// Only smart playlists skip on an unchanged file; M3U must re-run so newly-added tracks resolve.
+		if !forceSync && newPls.IsSmartPlaylist() && newPls.ImportedHash != "" && newPls.ImportedHash == pls.ImportedHash {
+			log.Trace(ctx, "Playlist file unchanged since last import, skipping", "playlist", pls.Name, "path", pls.Path)
+			*newPls = *pls // callers must see the stored record, so e.g. ImportFile can still flip Sync
+			return nil
+		}
 		log.Info(ctx, "Updating synced playlist", "playlist", pls.Name, "path", newPls.Path)
 		newPls.ID = pls.ID
 		newPls.Name = pls.Name
@@ -187,6 +207,12 @@ func (s *playlists) updatePlaylist(ctx context.Context, newPls *model.Playlist,
 		newPls.Public = pls.Public
 		newPls.UploadedImage = pls.UploadedImage // Preserve manual upload
 		newPls.EvaluatedAt = nil                 // force re-evaluation on next read
+		if newPls.IsSmartPlaylist() {
+			// Tracks aren't materialized at parse time; carry the stored counters so callers see real values
+			newPls.SongCount = pls.SongCount
+			newPls.Duration = pls.Duration
+			newPls.Size = pls.Size
+		}
 	} else {
 		log.Info(ctx, "Adding synced playlist", "playlist", newPls.Name, "path", newPls.Path, "owner", owner.UserName)
 		newPls.OwnerID = owner.ID
diff --git a/core/playlists/import_test.go b/core/playlists/import_test.go
index 2a84d56b2..445561266 100644
--- a/core/playlists/import_test.go
+++ b/core/playlists/import_test.go
@@ -15,10 +15,12 @@ import (
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/criteria"
+	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
+	"github.com/zeebo/xxh3"
 	"golang.org/x/text/unicode/norm"
 )
 
@@ -307,6 +309,33 @@ var _ = Describe("Playlists - Import", func() {
 				Expect(pls.ID).To(BeEmpty())
 			})
 
+			It("stores a content hash but re-imports unchanged M3U playlists", func() {
+				tmpDir := GinkgoT().TempDir()
+				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
+
+				plsFile := filepath.Join(tmpDir, "test.m3u")
+				Expect(os.WriteFile(plsFile, []byte("test.mp3\n"), 0600)).To(Succeed())
+				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
+
+				first, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
+				Expect(err).ToNot(HaveOccurred())
+				Expect(first.ImportedHash).ToNot(BeEmpty())
+
+				// Re-import with a matching stored hash: M3U must still be re-imported, not skipped.
+				existingPls := &model.Playlist{
+					ID: "m3u-id", Name: "Test", Path: plsFile, Sync: true,
+					OwnerID: "123", ImportedHash: first.ImportedHash,
+				}
+				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+				mockPlsRepo.Last = nil
+
+				_, err = ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last).ToNot(BeNil())
+			})
+
 			It("clears ExternalImageURL on re-scan when directive is removed", func() {
 				tmpDir := GinkgoT().TempDir()
 				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
@@ -371,6 +400,85 @@ var _ = Describe("Playlists - Import", func() {
 				Expect(pls.Name).To(Equal("Recently Played"))
 				Expect(pls.Public).To(BeTrue()) // Should be true since server default is true
 			})
+
+			It("preserves counters when re-importing an existing smart playlist", func() {
+				tmpDir := GinkgoT().TempDir()
+				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
+
+				nsp := `{"name":"My Smart","all":[{"is":{"loved":true}}],"sort":"title","order":"asc"}`
+				plsFile := filepath.Join(tmpDir, "smart.nsp")
+				Expect(os.WriteFile(plsFile, []byte(nsp), 0600)).To(Succeed())
+
+				existingPls := &model.Playlist{
+					ID:        "smart-id",
+					Name:      "My Smart",
+					Path:      plsFile,
+					Sync:      true,
+					OwnerID:   "123",
+					SongCount: 42,
+					Duration:  123.4,
+					Size:      5000,
+				}
+				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+
+				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
+				_, err := ps.ImportFromFolder(ctx, plsFolder, "smart.nsp")
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last).ToNot(BeNil())
+				Expect(mockPlsRepo.Last.IsSmartPlaylist()).To(BeTrue())
+				Expect(mockPlsRepo.Last.SongCount).To(Equal(42))
+				Expect(mockPlsRepo.Last.Duration).To(Equal(float32(123.4)))
+				Expect(mockPlsRepo.Last.Size).To(Equal(int64(5000)))
+			})
+
+			It("skips re-import when the smart playlist file content is unchanged", func() {
+				tmpDir := GinkgoT().TempDir()
+				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
+
+				nsp := `{"name":"My Smart","all":[{"is":{"loved":true}}]}`
+				plsFile := filepath.Join(tmpDir, "smart.nsp")
+				Expect(os.WriteFile(plsFile, []byte(nsp), 0600)).To(Succeed())
+
+				existingPls := &model.Playlist{
+					ID: "smart-id", Name: "My Smart", Path: plsFile, Sync: true,
+					OwnerID: "123", SongCount: 42,
+					ImportedHash: hashOf(nsp),
+				}
+				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+
+				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
+				_, err := ps.ImportFromFolder(ctx, plsFolder, "smart.nsp")
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last).To(BeNil()) // Put never called: nothing re-written
+			})
+
+			It("re-imports when the smart playlist file content changed", func() {
+				tmpDir := GinkgoT().TempDir()
+				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
+
+				nsp := `{"name":"My Smart","all":[{"is":{"loved":true}}]}`
+				plsFile := filepath.Join(tmpDir, "smart.nsp")
+				Expect(os.WriteFile(plsFile, []byte(nsp), 0600)).To(Succeed())
+
+				existingPls := &model.Playlist{
+					ID: "smart-id", Name: "My Smart", Path: plsFile, Sync: true,
+					OwnerID: "123", SongCount: 42,
+					ImportedHash: hashOf("old content"),
+				}
+				mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+
+				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
+				_, err := ps.ImportFromFolder(ctx, plsFolder, "smart.nsp")
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last).ToNot(BeNil()) // Put called: file changed
+				Expect(mockPlsRepo.Last.ImportedHash).To(Equal(hashOf(nsp)))
+			})
 		})
 
 		DescribeTable("Playlist filename Unicode normalization (regression fix-playlist-filename-normalization)",
@@ -760,6 +868,37 @@ var _ = Describe("Playlists - Import", func() {
 			Expect(pls.ID).To(Equal("existing-id"))
 			Expect(pls.Sync).To(BeTrue())
 		})
+
+		It("unsyncs a synced smart playlist with sync=false even when content is unchanged", func() {
+			tmpDir := GinkgoT().TempDir()
+			mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+
+			mockFolderRepo := &mockFolderRepoForImport{
+				folder: &model.Folder{
+					ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: "",
+				},
+			}
+			ds.MockedFolder = mockFolderRepo
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
+
+			nsp := `{"name":"My Smart","all":[{"is":{"loved":true}}]}`
+			plsFile := filepath.Join(tmpDir, "smart.nsp")
+			Expect(os.WriteFile(plsFile, []byte(nsp), 0600)).To(Succeed())
+
+			existingPls := &model.Playlist{
+				ID: "smart-id", Name: "My Smart", Path: plsFile, Sync: true,
+				OwnerID: "123", SongCount: 42,
+				ImportedHash: hashOf(nsp),
+			}
+			mockPlsRepo.PathMap = map[string]*model.Playlist{plsFile: existingPls}
+
+			pls, err := ps.ImportFile(ctx, plsFile, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pls.ID).To(Equal("smart-id"))
+			Expect(pls.Sync).To(BeFalse())
+			Expect(mockPlsRepo.Last).ToNot(BeNil())
+			Expect(mockPlsRepo.Last.Sync).To(BeFalse())
+		})
 	})
 
 	Describe("ImportM3U", func() {
@@ -1083,3 +1222,7 @@ func (m *mockFolderRepoForImport) GetByPath(_ model.Library, _ string) (*model.F
 	}
 	return nil, model.ErrNotFound
 }
+
+func hashOf(content string) string {
+	return id.Encode(xxh3.Hash128([]byte(content)).Bytes())
+}
diff --git a/core/playlists/rest_adapter.go b/core/playlists/rest_adapter.go
index f34524e27..ca7cfb0cc 100644
--- a/core/playlists/rest_adapter.go
+++ b/core/playlists/rest_adapter.go
@@ -136,6 +136,7 @@ func (s *playlists) applyContentUpdate(ctx context.Context, current, entity *mod
 	if rulesChanged {
 		current.Rules = entity.Rules
 		current.EvaluatedAt = nil // force re-evaluation on next read
+		current.ImportedHash = "" // rules no longer match the source file; next scan must re-import it
 	}
 	if sent("sync") && current.Path != "" && current.Sync != entity.Sync {
 		current.Sync = entity.Sync
diff --git a/core/playlists/rest_adapter_test.go b/core/playlists/rest_adapter_test.go
index 7ae376b07..fbfab350c 100644
--- a/core/playlists/rest_adapter_test.go
+++ b/core/playlists/rest_adapter_test.go
@@ -160,6 +160,25 @@ var _ = Describe("REST Adapter", func() {
 				Expect(mockPlsRepo.Last.Rules).To(Equal(newRules))
 			})
 
+			It("invalidates the imported hash when rules change, so the next scan re-syncs the file", func() {
+				mockPlsRepo.Data["smart-1"] = &model.Playlist{
+					ID:           "smart-1",
+					Name:         "Smart Playlist",
+					OwnerID:      "user-1",
+					Path:         "/music/smart.nsp",
+					Sync:         true,
+					ImportedHash: hashOf("file content"),
+					Rules:        &criteria.Criteria{Expression: criteria.Contains{"title": "old"}},
+				}
+				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+				repo = ps.NewRepository(ctx).(rest.Persistable)
+				newRules := &criteria.Criteria{Expression: criteria.Contains{"title": "new"}}
+				pls := &model.Playlist{Rules: newRules}
+				err := repo.Update("smart-1", pls, "rules")
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockPlsRepo.Last.ImportedHash).To(BeEmpty())
+			})
+
 			It("allows toggling sync for file-backed playlists", func() {
 				originalTime := time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)
 				mockPlsRepo.Data["file-pls"] = &model.Playlist{
diff --git a/db/migrations/20260818002312_add_playlist_imported_hash.sql b/db/migrations/20260818002312_add_playlist_imported_hash.sql
new file mode 100644
index 000000000..aab729153
--- /dev/null
+++ b/db/migrations/20260818002312_add_playlist_imported_hash.sql
@@ -0,0 +1,5 @@
+-- +goose Up
+alter table playlist add imported_hash varchar default '' not null;
+
+-- +goose Down
+alter table playlist drop column imported_hash;
diff --git a/model/playlist.go b/model/playlist.go
index 9aa54bf13..55b94a640 100644
--- a/model/playlist.go
+++ b/model/playlist.go
@@ -31,6 +31,7 @@ type Playlist struct {
 	ExternalImageURL string         `structs:"external_image_url" json:"externalImageUrl,omitempty"`
 	CreatedAt        time.Time      `structs:"created_at" json:"createdAt"`
 	UpdatedAt        time.Time      `structs:"updated_at" json:"updatedAt"`
+	ImportedHash     string         `structs:"imported_hash" json:"-"`
 
 	// SmartPlaylist attributes
 	Rules       *criteria.Criteria `structs:"rules" json:"rules"`
diff --git a/persistence/playlist_repository.go b/persistence/playlist_repository.go
index 081dab3fa..cf54c6d5a 100644
--- a/persistence/playlist_repository.go
+++ b/persistence/playlist_repository.go
@@ -39,6 +39,10 @@ func (p dbPlaylist) PostMapArgs(args map[string]any) error {
 		if err != nil {
 			return fmt.Errorf("invalid criteria expression: %w", err)
 		}
+		// Smart playlist counters are owned by refreshCounters (evaluation), never by callers
+		delete(args, "song_count")
+		delete(args, "duration")
+		delete(args, "size")
 		return nil
 	}
 	delete(args, "rules")
diff --git a/persistence/playlist_repository_test.go b/persistence/playlist_repository_test.go
index fc2d4ae3f..9697e6fff 100644
--- a/persistence/playlist_repository_test.go
+++ b/persistence/playlist_repository_test.go
@@ -7,6 +7,7 @@ import (
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
@@ -230,6 +231,32 @@ var _ = Describe("PlaylistRepository", func() {
 		})
 	})
 
+	Describe("Put", func() {
+		It("does not overwrite counters when saving a smart playlist", func() {
+			pls := model.Playlist{Name: "Smart Counters", OwnerID: "userid", Rules: &criteria.Criteria{
+				Expression: criteria.All{criteria.Contains{"title": "love"}},
+			}}
+			Expect(repo.Put(&pls)).To(Succeed())
+			DeferCleanup(func() { Expect(repo.Delete(pls.ID)).To(Succeed()) })
+
+			// Simulate a previous evaluation having stored the counters
+			_, err := GetDBXBuilder().NewQuery("update playlist set song_count = 42, duration = 123, size = 456 where id = {:id}").
+				Bind(dbx.Params{"id": pls.ID}).Execute()
+			Expect(err).ToNot(HaveOccurred())
+
+			pls.SongCount = 0
+			pls.Duration = 0
+			pls.Size = 0
+			Expect(repo.Put(&pls)).To(Succeed())
+
+			saved, err := repo.Get(pls.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(saved.SongCount).To(Equal(42))
+			Expect(saved.Duration).To(Equal(float32(123)))
+			Expect(saved.Size).To(Equal(int64(456)))
+		})
+	})
+
 	It("Put/Exists/Delete", func() {
 		By("saves the playlist to the DB")
 		newPls := model.Playlist{Name: "Great!", OwnerID: "userid"}
diff --git a/persistence/smart_playlist_repository_test.go b/persistence/smart_playlist_repository_test.go
index e62436890..ddc155fab 100644
--- a/persistence/smart_playlist_repository_test.go
+++ b/persistence/smart_playlist_repository_test.go
@@ -58,6 +58,41 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 			})
 		})
 
+		Context("re-imported from disk", func() {
+			// The scanner re-imports every playlist in a touched folder, and a freshly parsed
+			// .nsp carries no counters — saving it must not wipe the ones already evaluated.
+			It("keeps the stored counters when a freshly parsed playlist is saved over it", func() {
+				rules = &criteria.Criteria{
+					Expression: criteria.All{
+						criteria.Contains{"title": "Antenna"},
+					},
+				}
+				pls := model.Playlist{Name: "Smart", OwnerID: "userid", Rules: rules, Path: "/music/smart.nsp", Sync: true}
+				Expect(repo.Put(&pls)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(pls.ID) })
+
+				evaluated, err := repo.GetWithTracks(pls.ID, true, false)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(evaluated.SongCount).To(BeNumerically(">", 0))
+
+				stored, err := repo.Get(pls.ID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(stored.SongCount).To(Equal(evaluated.SongCount))
+
+				reimported := model.Playlist{
+					ID: pls.ID, Name: pls.Name, OwnerID: "userid", Rules: rules,
+					Path: pls.Path, Sync: true,
+				}
+				Expect(repo.Put(&reimported)).To(Succeed())
+
+				afterImport, err := repo.Get(pls.ID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(afterImport.SongCount).To(Equal(stored.SongCount))
+				Expect(afterImport.Duration).To(Equal(stored.Duration))
+				Expect(afterImport.Size).To(Equal(stored.Size))
+			})
+		})
+
 		Context("child smart playlists", func() {
 			BeforeEach(func() {
 				DeferCleanup(configtest.SetupConfig())

From 7a11ca69bbfd3465ef4ce2af52966a97c51de77e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 19 Aug 2026 08:36:44 -0400
Subject: [PATCH 051/200] fix(jellyfin): honor the Filters, SortBy and
 MaxHeight params clients actually send (#5981)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(jellyfin): honor Filters=IsFavorite on /Artists and /Artists/AlbumArtists

listArtistsByRole hand-built its itemsQuery and never set favOnly, so the
favorites filter was silently dropped on both artist routes while /Items
honored it. Finamp's home screen asks for favorite artists once per load and
was served the entire artist list instead: 10,298 artists, 6.15 MB, 2.7s on
a real library, and the wrong data on screen.

Extract the favOnly parsing that parseItemsQuery already did into
parseFavOnly and use it in both places. listArtists now adds the starred
predicate to notMissing rather than replacing it, matching listAlbums and
listSongs, so a favorite artist whose files are gone stays excluded.

* fix(jellyfin): map SortBy=Runtime to duration for albums and songs

sortColumnsByType had no runtime/runtimeticks key for any type, so Finamp's
"Duration" sort silently misbehaved in two different ways.

Albums: Finamp sends a bare SortBy=Runtime. Nothing matched, opts.Sort stayed
empty, and applyOptions skips OrderBy entirely when Sort is empty — so the
query ran with no ORDER BY at all and Ascending and Descending returned
identical lists.

Songs: Finamp sends SortBy=Runtime,AlbumArtist,Album,SortName. applySort takes
the first *recognized* key, so Runtime was skipped and the list came back
sorted by album artist while looking correct.

Both repos already accept a duration sort (mediafile_repository maps it
explicitly; album_repository falls through to the column name), so no
migration is needed. Sorting 97k songs by duration costs a temp B-tree
(~114ms on a prod-sized copy) — the same cost the Subsonic and UI duration
sorts already pay, and correct where the previous behaviour was merely fast.

* fix(jellyfin): apply the played/unplayed filters and MaxHeight image bound

Filters was matched with a substring test for IsFavorite, so every other token
Jellyfin defines was silently dropped and the response kept rows it should
have excluded. Finamp sends Filters=IsUnplayed in normal use.

Replace the bool with a parsed itemFilters carrying nullable favorite and
played flags, so isFavorite=false and isPlayed=false are real filters rather
than indistinguishable from an absent param. Standalone params are read first
and the Filters list overrides them, the precedence real Jellyfin has.
IsFavoriteOrLikes now maps to favorites deliberately instead of by substring
accident; Likes, Dislikes, IsFolder, IsNotFolder and IsResumable have no
Navidrome equivalent and are dropped rather than half-applied. The negative
cases match NULL as well, since annotations are LEFT JOINed and an untouched
item has no row.

getItemImage read only maxwidth, so a client sending just MaxHeight got the
full-size original: measured against a real cover, maxHeight=100 returned
82,570 bytes where maxWidth=100 returned 3,316. Use the tighter of the two
bounds.

* refactor(jellyfin): share the plain-param parser between /Items and /Artists

listArtistsByRole hand-listed the itemsQuery fields it happened to need, which
is exactly how the favorites filter went missing: the literal has been amended
in four of the five commits that touched it. Extract listParams for the fields
that come straight from query params so both paths read one parser, and the
next supported param reaches every list path instead of only /Items.

Also from the cleanup pass: collapse imageSize to a single clamped comparison
and read its bounds through req.Params like the rest of the package, which
drops the strconv import; build the artist and playlist filter lists with the
flat append shape the album and song paths already use, instead of re-wrapping
opts.Filters into a nested And per predicate; drop a nil guard in
listPlaylists that no caller can reach, since both paths into queryItemsOfType
build QueryOptions without Filters.

applySort now logs when no SortBy key resolves at all — a miss inside a
fallback list is normal, but none matching means a silently ignored sort, the
failure mode that hid the Runtime bug. Its doc comment records why the
remaining keys cannot simply be joined.

Folds three duplicated test bodies into the tables that already parameterize
them, and covers the artist-parent album branch, which reaches notMissing
through filter.AlbumsByArtistID rather than the default branch.

* docs(jellyfin): correct how applySort describes Jellyfin's SortBy semantics

The comment claimed SortBy is a comma-separated fallback list. It is not:
RequestHelpers.GetOrderBy (10.10) builds one (ItemSortBy, SortOrder) pair per
key, so Jellyfin orders by every key in turn. Navidrome applies only the first
recognized one, which is a real divergence — secondary keys never break ties —
not the intended reading of the parameter.

The assertion that the keys cannot be joined was also wrong. buildSortOrder
does split its input on commas; what it maps is the whole string, so joining
raw Jellyfin key names misses the mappings. Mapping each key first and joining
the results would work, which makes multi-key sorting a real option rather
than a blocked one. Documenting the current behaviour as a known divergence
until then.

* fix(jellyfin): order by every recognized SortBy key, not just the first

Jellyfin orders by each SortBy key in turn, so "DatePlayed,SortName" means
break ties by name. Navidrome applied only the first recognized key and dropped
the rest, which is 28% of the sort traffic on a real server (23 of 82 requests
in 12h carry 2-5 keys). Most were harmless because the primary key dominates,
but PremiereDate,Album,ParentIndexNumber,IndexNumber,SortName came back
unordered within a year.

The keys cannot simply be joined: sortMapping keyed on the whole Sort string,
so a joined value missed every mapping and fell through to raw column names.
Make it resolve a comma list per part, but only when every part is a known key
— the four existing callers that pass raw column lists (core/matcher,
core/lyrics, core/maintenance, subsonic/browsing) all carry a part that is not
a mapping key, several with their own direction, so they keep falling through
exactly as before. Verified each one.

applySort now collects every recognized key, skipping duplicates so
ParentIndexNumber,IndexNumber does not repeat a column. random stays alone: the
repo matches it by exact string equality, so joining it would both break that
path and emit a bare 'random' column into the ORDER BY.

Verified against a prod-sized copy: every multi-key combination seen in real
traffic returns 200, and a secondary key now changes the order within a tied
year for songs. Albums are unchanged there, because their max_year mapping
already ended in ", name".

* fix(persistence): resolve sort mappings exactly once

Making sortMapping resolve a comma list per part broke an invariant it had
been relying on: idempotence. sanitizeSort mapped the sort key up front and
applyOptions then ran buildSortOrder over the result, so sortMapping was
already being handed its own output. That was harmless only while a mapped
value could never look like a key list.

media_file's rated_at maps to "rating, rated_at", and both parts are keys, so
the second pass expanded it to "rating, rating, rated_at". Found by
round-tripping every mapping in all four repositories; it was the only
collision, and the duplicate sort key was benign in SQL, but any future mapping
of that shape would silently change meaning.

sanitizeSort now validates without resolving, leaving buildSortOrder as the
single mapping point. The generated SQL is unchanged — the whole suite passes
apart from the two specs that asserted the old return value, which are updated
and joined by a round-trip guard covering exactly the rated_at shape.

Also use the paren-aware splitFunc that buildSortOrder already uses, so an
expression carrying commas inside its parentheses cannot be split apart.

* refactor(jellyfin,persistence): flatten the sort resolution paths

Cleanup pass over the branch, no behavior change.

sortMapping loses the len(parts)>1 guard, which existed only to pick between
two identical toSnakeCase exits; the single-key case now falls through the same
loop. lookupSortMapping hands back the snake_case form it had to derive so the
fallback stops recomputing it — toSnakeCase is two regexps, and on a miss it was
running twice per call. sanitizeSort now asks lookupSortMapping instead of
probing the map itself, so "is this a known sort key" has one answer; the two
had already drifted, since sanitizeSort tried one casing where the resolver
tries three.

applySort folds the nested random branch into the skip condition and the two
trailing length tests into one switch. setSortMappings documents the invariant
the comma-list rule depends on, where someone adding a mapping will read it.

The README line describing SortBy still said only the first key applied, which
the commit before last made false.

Tests: the twelve near-identical sorting specs become one DescribeTable of
(itemType, SortBy, want) triples, 124 lines to 36, and the applyOptions
round-trip assertion collapses to the buildSortOrder call its sibling uses.

* fix(jellyfin): keep annotation filters out of search, resolve sorts per part

Two findings from the Codex review on #5981.

The played/unplayed filters turned working requests into 500s when combined
with SearchTerm. Search runs a two-phase FTS query whose first phase selects
rowids with no annotation join, so a starred or play_count predicate there is
"no such column", not a filter. Measured against master: MusicAlbum with
SearchTerm and Filters=IsUnplayed went 200 -> 500, likewise IsPlayed and the
Audio equivalents. listAlbums and listSongs now skip those predicates on the
search path, matching what listArtists already did. That also clears the same
500 master already had for Filters=IsFavorite with SearchTerm.

sortMapping resolved a comma list only while every part was a known key, so a
list mixing a plain column with a mapped key kept neither: MusicAlbum
SortBy=Runtime,SortName arrives as "duration, name", and duration is a plain
album column, so name stayed raw instead of expanding to order_album_name.
Albums whose name differs from its sort form — 1,366 of 6,987 on a real
library — then ordered by the wrong secondary key, and PreferSortTags was
ignored. Each part is now resolved on its own, which is what setSortMappings
already documents for a single field. Verified every in-tree caller that passes
a raw column list still produces its original ORDER BY.

Codex also asked for the artist search path to apply the same filters. It
would 500 for the reason above, and wrapping the library scope in a compound
filter makes requestedLibraryIDs stop recognizing it, silently widening the
search past the requested ParentId.

* fix(jellyfin): honor the first SortOrder value for a multi-key sort

applySort compared the whole SortOrder string with "Descending", so a per-key
list like SortOrder=Descending,Ascending failed the match and every key,
including the primary, sorted ascending — the exact opposite of the request.
Take the first comma-separated value, which Jellyfin also uses for any key past
the end of the SortOrder list. True per-key directions can't be expressed
through the single opts.Sort string and are left out; no observed client sends
a SortOrder list.
---
 persistence/sql_base_repository.go      |  36 ++++-
 persistence/sql_base_repository_test.go |  59 +++++++-
 persistence/sql_restful.go              |  12 +-
 server/jellyfin/README.md               |   6 +-
 server/jellyfin/browsing.go             |  19 +--
 server/jellyfin/browsing_test.go        |  23 +++
 server/jellyfin/images.go               |  15 +-
 server/jellyfin/images_test.go          |  33 +++-
 server/jellyfin/items.go                | 149 +++++++++++++------
 server/jellyfin/items_test.go           | 190 +++++++++++++++---------
 10 files changed, 394 insertions(+), 148 deletions(-)

diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index 428ba7a7b..c61bca1a6 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -97,6 +97,8 @@ func (r *sqlRepository) registerModel(instance any, filters map[string]filterFun
 }
 
 // setSortMappings sets the mappings for the sort fields. If the sort field is not in the map, it will be used as is.
+// This applies per comma-separated part, so a key added here also defines that bare name wherever a
+// caller uses it inside a sort list.
 //
 // If PreferSortTags is enabled, it will map the order fields to the corresponding sort expression,
 // which gives precedence to sort tags.
@@ -147,17 +149,37 @@ func (r sqlRepository) applyOptions(sq SelectBuilder, options ...model.QueryOpti
 
 // TODO Change all sortMappings to have a consistent case
 func (r sqlRepository) sortMapping(sort string) string {
-	if mapping, ok := r.sortMappings[sort]; ok {
+	if mapping, _, ok := r.lookupSortMapping(sort); ok {
 		return mapping
 	}
-	if mapping, ok := r.sortMappings[toCamelCase(sort)]; ok {
-		return mapping
+	// Each part of a comma list is resolved on its own, so a mix of mapped keys and plain columns
+	// keeps the mappings the recognized parts have.
+	parts := strings.FieldsFunc(sort, splitFunc(','))
+	mapped := make([]string, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if partMapping, _, ok := r.lookupSortMapping(part); ok {
+			part = partMapping
+		} else {
+			part = toSnakeCase(part)
+		}
+		mapped = append(mapped, part)
 	}
-	sort = toSnakeCase(sort)
-	if mapping, ok := r.sortMappings[sort]; ok {
-		return mapping
+	return strings.Join(mapped, ", ")
+}
+
+// lookupSortMapping also returns the snake_case form when it had to derive one, so a caller's
+// fallback doesn't recompute it: toSnakeCase runs two regexps.
+func (r sqlRepository) lookupSortMapping(sort string) (mapping, snakeCased string, ok bool) {
+	if mapping, ok = r.sortMappings[sort]; ok {
+		return mapping, sort, true
 	}
-	return sort
+	if mapping, ok = r.sortMappings[toCamelCase(sort)]; ok {
+		return mapping, "", true
+	}
+	snakeCased = toSnakeCase(sort)
+	mapping, ok = r.sortMappings[snakeCased]
+	return mapping, snakeCased, ok
 }
 
 func (r sqlRepository) buildSortOrder(sort, order string) string {
diff --git a/persistence/sql_base_repository_test.go b/persistence/sql_base_repository_test.go
index 9c6c6007f..0f76eb6ab 100644
--- a/persistence/sql_base_repository_test.go
+++ b/persistence/sql_base_repository_test.go
@@ -92,14 +92,28 @@ var _ = Describe("sqlRepository", func() {
 				Expect(sort).To(BeEmpty())
 			})
 
-			It("returns the mapped value when sort key exists", func() {
+			// Validation only: buildSortOrder resolves the mapping, so mapping here too would hand
+			// sortMapping its own output and re-map values whose parts are themselves keys.
+			It("accepts a known sort key without resolving it", func() {
 				sort, _ := r.sanitizeSort("sort1", "")
-				Expect(sort).To(Equal("mappedSort1"))
+				Expect(sort).To(Equal("sort1"))
 			})
 
 			It("is case insensitive", func() {
 				sort, _ := r.sanitizeSort("Sort1", "")
-				Expect(sort).To(Equal("mappedSort1"))
+				Expect(sort).To(Equal("sort1"))
+			})
+
+			It("still resolves the mapping by the time the SQL is built", func() {
+				Expect(r.buildSortOrder("sort1", "asc")).To(Equal("mappedSort1 asc"))
+			})
+
+			// A mapping whose parts are themselves keys (media_file rated_at = "rating, rated_at")
+			// must survive the round trip through sanitizeSort and buildSortOrder unduplicated.
+			It("does not re-map a value whose parts are also keys", func() {
+				r.sortMappings = map[string]string{"rating": "rating", "rated_at": "rating, rated_at"}
+				sort, _ := r.sanitizeSort("rated_at", "")
+				Expect(r.buildSortOrder(sort, "asc")).To(Equal("rating asc, rated_at asc"))
 			})
 
 			It("returns the field if it is a valid field", func() {
@@ -135,6 +149,45 @@ var _ = Describe("sqlRepository", func() {
 		})
 	})
 
+	Describe("sortMapping", func() {
+		BeforeEach(func() {
+			r.sortMappings = map[string]string{
+				"name":           "order_album_name, order_album_artist_name",
+				"recently_added": "album.created_at, album.id",
+			}
+		})
+		It("maps a single key", func() {
+			Expect(r.sortMapping("recently_added")).To(Equal("album.created_at, album.id"))
+		})
+		It("maps every part of a comma list when all of them are known keys", func() {
+			Expect(r.sortMapping("recently_added, name")).
+				To(Equal("album.created_at, album.id, order_album_name, order_album_artist_name"))
+		})
+		It("resolves the known parts of a mixed list and leaves the rest as columns", func() {
+			Expect(r.sortMapping("recently_added, play_count")).
+				To(Equal("album.created_at, album.id, play_count"))
+		})
+		// Jellyfin's MusicAlbum SortBy=Runtime,SortName arrives as "duration, name"; duration is a
+		// plain album column while name is mapped, and the mapping must survive the mix.
+		It("keeps a mapping when an earlier part is a plain column", func() {
+			Expect(r.sortMapping("duration, name")).
+				To(Equal("duration, order_album_name, order_album_artist_name"))
+		})
+		It("leaves a raw column list with directions untouched", func() {
+			Expect(r.sortMapping("starred desc, rating desc")).To(Equal("starred desc, rating desc"))
+		})
+		It("does not split an expression on a comma inside its parentheses", func() {
+			Expect(r.sortMapping("coalesce(name, ''), title")).To(Equal("coalesce(name, ''), title"))
+			Expect(r.sortMapping("coalesce(nullif(a,''), b) desc, c")).To(Equal("coalesce(nullif(a,''), b) desc, c"))
+		})
+		It("keeps a mapping whose value nests commas inside parentheses", func() {
+			r.sortMappings["max_year"] = "coalesce(nullif(original_date,''), cast(max_year as text)), release_date"
+			Expect(r.sortMapping("max_year, name")).To(Equal(
+				"coalesce(nullif(original_date,''), cast(max_year as text)), release_date, " +
+					"order_album_name, order_album_artist_name"))
+		})
+	})
+
 	Describe("buildSortOrder", func() {
 		BeforeEach(func() {
 			r.sortMappings = map[string]string{}
diff --git a/persistence/sql_restful.go b/persistence/sql_restful.go
index 1dcabcec6..b1cfd2379 100644
--- a/persistence/sql_restful.go
+++ b/persistence/sql_restful.go
@@ -69,13 +69,11 @@ func (r *sqlRepository) parseRestOptions(ctx context.Context, options ...rest.Qu
 func (r sqlRepository) sanitizeSort(sort, order string) (string, string) {
 	if sort != "" {
 		sort = toSnakeCase(sort)
-		if mapped, ok := r.sortMappings[sort]; ok {
-			sort = mapped
-		} else {
-			if !r.isFieldWhiteListed(sort) {
-				log.Warn(r.ctx, "Ignoring sort not whitelisted", "sort", sort, "table", r.tableName)
-				sort = ""
-			}
+		// Validate only: buildSortOrder resolves the mapping later, and mapping here as well would
+		// feed sortMapping its own output.
+		if _, _, known := r.lookupSortMapping(sort); !known && !r.isFieldWhiteListed(sort) {
+			log.Warn(r.ctx, "Ignoring sort not whitelisted", "sort", sort, "table", r.tableName)
+			sort = ""
 		}
 	}
 	if order != "" {
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 5759e6cc0..dc3219dfa 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -104,7 +104,11 @@ album's tracks — Feishin fetches them this way instead of `ParentId`); `GenreI
 genre's albums or tracks — Finamp's genre screen sends it the same way; `/Artists/AlbumArtists`
 and `MusicArtist` queries accept it too, matching artists credited on an album of that genre);
 `SearchTerm`;
-favorites-only (`Filters=IsFavorite` or the standalone `isFavorite=true`); `SortBy`/`SortOrder`;
+`Filters` (`IsFavorite`, `IsFavoriteOrLikes`, `IsPlayed`, `IsUnplayed`) and the standalone
+`isFavorite`/`isPlayed` booleans it can also be expressed as — `Filters` wins when both are sent, as
+in Jellyfin; `Likes`, `Dislikes`, `IsFolder`, `IsNotFolder` and `IsResumable` have no Navidrome
+equivalent and are ignored; `SortBy`/`SortOrder` (every recognized key is applied in order, so secondary keys break ties;
+unrecognized keys are skipped, and `Random` always sorts alone);
 `StartIndex`/`Limit`; and `Ids` (batch fetch by id). `Recursive=false` with a library `ParentId`
 returns direct children only (no tracks — no track is a library's direct child).
 
diff --git a/server/jellyfin/browsing.go b/server/jellyfin/browsing.go
index 9acd8d5a8..25c44e748 100644
--- a/server/jellyfin/browsing.go
+++ b/server/jellyfin/browsing.go
@@ -24,10 +24,6 @@ func (api *Router) getAlbumArtists(w http.ResponseWriter, r *http.Request) {
 // when accessible (like queryItems) or all accessible libraries otherwise.
 func (api *Router) listArtistsByRole(w http.ResponseWriter, r *http.Request, role model.Role) {
 	ctx := r.Context()
-	p := req.Params(r)
-	opts := model.QueryOptions{Offset: p.IntOr("startindex", 0), Max: p.IntOr("limit", 0)}
-	applySort(&opts, "MusicArtist", p.StringOr("sortby", ""), p.StringOr("sortorder", ""))
-
 	scopeIDs, _, ok := parentIDScope(ctx, r)
 	if !ok {
 		http.Error(w, "Not Found", http.StatusNotFound)
@@ -38,14 +34,13 @@ func (api *Router) listArtistsByRole(w http.ResponseWriter, r *http.Request, rol
 		http.Error(w, "Not Found", http.StatusNotFound)
 		return
 	}
-	// Only the fields listArtists reads; /Artists has no favorites filter, so favOnly stays false.
-	// Finamp's artist tab sends GenreIds when a genre filter is active.
-	q := itemsQuery{
-		scopeIDs: scopeIDs,
-		genreIds: genreIds,
-		search:   searchTerm(p),
-		fields:   dto.ParseFields(p.Strings("fields")...),
-	}
+	// This route resolves its own scope, so it shares only the plain query params with /Items.
+	q := listParams(req.Params(r))
+	q.scopeIDs = scopeIDs
+	q.genreIds = genreIds
+
+	opts := model.QueryOptions{Offset: q.offset, Max: q.limit}
+	applySort(&opts, "MusicArtist", q.sortBy, q.sortOrder)
 	if q.search != "" {
 		opts.Max = clampLimit(opts.Max, defaultSearchLimit, maxSearchLimit)
 	}
diff --git a/server/jellyfin/browsing_test.go b/server/jellyfin/browsing_test.go
index 2825c03e8..657c7a42c 100644
--- a/server/jellyfin/browsing_test.go
+++ b/server/jellyfin/browsing_test.go
@@ -156,6 +156,29 @@ var _ = Describe("Browsing", func() {
 			Expect(sql).NotTo(ContainSubstring("library_artist.library_id"))
 		})
 
+		DescribeTable("restricts to favorites",
+			func(url string, handler func(*Router) http.HandlerFunc) {
+				artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+				artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", url, nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
+				invoke(handler(api), w, r)
+				Expect(w.Code).To(Equal(http.StatusOK))
+				sql, args, err := artistRepo.Options.Filters.ToSql()
+				Expect(err).NotTo(HaveOccurred())
+				Expect(sql).To(ContainSubstring("starred"))
+				// listArtists always ANDs notMissing, favorites filter or not.
+				Expect(sql).To(ContainSubstring("missing"))
+				Expect(args).To(ContainElement(true))
+			},
+			Entry("Filters=IsFavorite", "/Artists?Filters=IsFavorite",
+				func(a *Router) http.HandlerFunc { return a.getArtists }),
+			Entry("isFavorite=true", "/Artists?isFavorite=true",
+				func(a *Router) http.HandlerFunc { return a.getArtists }),
+			Entry("on /Artists/AlbumArtists", "/Artists/AlbumArtists?Filters=IsFavorite",
+				func(a *Router) http.HandlerFunc { return a.getAlbumArtists }),
+		)
+
 		It("404s a malformed ParentId instead of listing every library's artists", func() {
 			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
diff --git a/server/jellyfin/images.go b/server/jellyfin/images.go
index 65f02d7a0..fcf69c039 100644
--- a/server/jellyfin/images.go
+++ b/server/jellyfin/images.go
@@ -11,7 +11,6 @@ import (
 	_ "image/png"
 	"io"
 	"net/http"
-	"strconv"
 
 	"github.com/dustin/go-humanize"
 	"github.com/navidrome/navidrome/conf"
@@ -20,9 +19,20 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/imghttp"
+	"github.com/navidrome/navidrome/utils/req"
 	_ "golang.org/x/image/webp"
 )
 
+// imageSize picks the tighter of Jellyfin's two bounds, because Navidrome resizes on a single
+// dimension: reading only MaxWidth serves the full-size original to a client that sent MaxHeight.
+func imageSize(maxWidth, maxHeight int) int {
+	w, h := max(maxWidth, 0), max(maxHeight, 0)
+	if w == 0 || h == 0 {
+		return max(w, h)
+	}
+	return min(w, h)
+}
+
 func (api *Router) getItemImage(w http.ResponseWriter, r *http.Request) {
 	// Public endpoint, like real Jellyfin's image routes: clients fetch cover URLs without credentials
 	// and item ids are unguessable, so resolution runs elevated to bypass the visibility filter.
@@ -31,7 +41,8 @@ func (api *Router) getItemImage(w http.ResponseWriter, r *http.Request) {
 	if !ok {
 		return
 	}
-	size, _ := strconv.Atoi(r.URL.Query().Get("maxwidth"))
+	p := req.Params(r)
+	size := imageSize(p.IntOr("maxwidth", 0), p.IntOr("maxheight", 0))
 
 	artID := api.resolveArtworkID(ctx, itemId)
 	img, err := api.artwork.GetOrPlaceholder(ctx, artID, size, false)
diff --git a/server/jellyfin/images_test.go b/server/jellyfin/images_test.go
index 0e0d6220d..2f32e6ec9 100644
--- a/server/jellyfin/images_test.go
+++ b/server/jellyfin/images_test.go
@@ -30,14 +30,16 @@ import (
 
 type fakeArtwork struct {
 	artwork.Artwork
-	recvId  string
-	recvCtx context.Context
-	data    []byte
-	hash    string
+	recvId   string
+	recvSize int
+	recvCtx  context.Context
+	data     []byte
+	hash     string
 }
 
 func (f *fakeArtwork) GetOrPlaceholder(ctx context.Context, id string, size int, square bool) (*artwork.Image, error) {
 	f.recvId = id
+	f.recvSize = size
 	f.recvCtx = ctx
 	data := f.data
 	if data == nil {
@@ -61,6 +63,29 @@ func newImageRequest(itemId string) (*httptest.ResponseRecorder, *http.Request)
 }
 
 var _ = Describe("Images", func() {
+	// Real Jellyfin fits the image inside either bound, so a client that sends only MaxHeight must
+	// still get a resized image rather than the full-size original.
+	DescribeTable("derives the requested size from MaxWidth or MaxHeight",
+		func(query string, wantSize int) {
+			ds := &tests.MockDataStore{}
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			fa := &fakeArtwork{}
+			api := &Router{ds: ds, artwork: fa}
+
+			w, r := newImageRequest(dto.EncodeID(testID("a1")))
+			r.URL.RawQuery = query
+			api.getItemImage(w, r)
+
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(fa.recvSize).To(Equal(wantSize))
+		},
+		Entry("MaxWidth only", "maxwidth=300", 300),
+		Entry("MaxHeight only", "maxheight=300", 300),
+		Entry("both, smaller bound wins", "maxwidth=200&maxheight=300", 200),
+		Entry("both, smaller bound wins regardless of order", "maxwidth=300&maxheight=200", 200),
+		Entry("neither", "", 0),
+	)
+
 	It("streams album artwork", func() {
 		ds := &tests.MockDataStore{}
 		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index de0da88eb..eb5cd2a1a 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -31,6 +31,51 @@ func searchTerm(p *req.Values) string {
 	return strings.TrimSpace(p.StringOr("searchterm", ""))
 }
 
+// itemFilters is the parsed Filters=... list together with the standalone isFavorite/isPlayed params
+// clients may send instead. A nil field means the client asked for no filtering on that dimension.
+type itemFilters struct {
+	favorite *bool
+	played   *bool
+}
+
+// parseItemFilters reads the standalone params first and lets the Filters list win, matching real
+// Jellyfin. Tokens with no Navidrome equivalent (Likes, IsFolder, IsResumable) are dropped.
+func parseItemFilters(p *req.Values) itemFilters {
+	f := itemFilters{favorite: p.BoolPtr("isfavorite"), played: p.BoolPtr("isplayed")}
+	for token := range strings.SplitSeq(p.StringOr("filters", ""), ",") {
+		switch strings.TrimSpace(token) {
+		case "IsFavorite", "IsFavoriteOrLikes":
+			f.favorite = new(true)
+		case "IsPlayed":
+			f.played = new(true)
+		case "IsUnplayed":
+			f.played = new(false)
+		}
+	}
+	return f
+}
+
+// predicates renders the filters as annotation-column conditions. The negative cases have to match
+// NULL as well: annotations are LEFT JOINed, so an item nobody has touched has no row at all.
+func (f itemFilters) predicates() []squirrel.Sqlizer {
+	var out []squirrel.Sqlizer
+	if f.favorite != nil {
+		if *f.favorite {
+			out = append(out, squirrel.Eq{"starred": true})
+		} else {
+			out = append(out, squirrel.Or{squirrel.Eq{"starred": nil}, squirrel.Eq{"starred": false}})
+		}
+	}
+	if f.played != nil {
+		if *f.played {
+			out = append(out, squirrel.Gt{"play_count": 0})
+		} else {
+			out = append(out, squirrel.Or{squirrel.Eq{"play_count": nil}, squirrel.Eq{"play_count": 0}})
+		}
+	}
+	return out
+}
+
 func (api *Router) getItems(w http.ResponseWriter, r *http.Request) {
 	res, err := api.queryItems(r.Context(), r)
 	if err != nil {
@@ -214,7 +259,7 @@ type itemsQuery struct {
 	sortOrder string
 	offset    int
 	limit     int
-	favOnly   bool
+	filters   itemFilters
 	// parentId scopes the query. entityParent is the same id only when it names an entity (an artist
 	// for MusicAlbum, an album for Audio) rather than a library.
 	parentId        string
@@ -231,6 +276,19 @@ type itemsQuery struct {
 	studioIds        []string
 }
 
+// listParams reads the itemsQuery fields that come straight from query params.
+func listParams(p *req.Values) itemsQuery {
+	return itemsQuery{
+		fields:    dto.ParseFields(p.Strings("fields")...),
+		search:    searchTerm(p),
+		sortBy:    p.StringOr("sortby", ""),
+		sortOrder: p.StringOr("sortorder", ""),
+		offset:    p.IntOr("startindex", 0),
+		limit:     p.IntOr("limit", 0),
+		filters:   parseItemFilters(p),
+	}
+}
+
 // parseItemsQuery also resolves the entity types (inferring them from the parent when
 // IncludeItemTypes is absent) and the library scope. Query keys are read lowercase because
 // normalizeQueryKeys folded them (Jellyfin binds case-insensitively). A non-empty id param that
@@ -261,24 +319,14 @@ func (api *Router) parseItemsQuery(ctx context.Context, r *http.Request) (itemsQ
 	if !ok {
 		return itemsQuery{}, model.ErrNotFound
 	}
-	q := itemsQuery{
-		fields:    dto.ParseFields(p.Strings("fields")...),
-		ids:       ids,
-		rawTypes:  p.StringOr("includeitemtypes", ""),
-		search:    searchTerm(p),
-		sortBy:    p.StringOr("sortby", ""),
-		sortOrder: p.StringOr("sortorder", ""),
-		offset:    p.IntOr("startindex", 0),
-		limit:     p.IntOr("limit", 0),
-		// Clients express "favorites only" two ways: Filters=IsFavorite and the standalone
-		// isFavorite=true param (Finamp's "Favourite tracks" widget uses the latter).
-		favOnly:   strings.Contains(p.StringOr("filters", ""), "IsFavorite") || p.BoolOr("isfavorite", false),
-		parentId:  parentId,
-		genreIds:  genreIds,
-		albumIds:  albumIds,
-		years:     parseYears(r),
-		studioIds: studioIds,
-	}
+	q := listParams(p)
+	q.ids = ids
+	q.rawTypes = p.StringOr("includeitemtypes", "")
+	q.parentId = parentId
+	q.genreIds = genreIds
+	q.albumIds = albumIds
+	q.years = parseYears(r)
+	q.studioIds = studioIds
 	// An artist's page filters by artist, not ParentId: Finamp sends ParentId=<libraryId> for scoping
 	// plus AlbumArtistIds/ArtistIds/contributingArtistIds for the artist.
 	albumArtistScope := firstNonEmpty(p.StringOr("albumartistids", ""), p.StringOr("artistids", ""))
@@ -621,8 +669,10 @@ func (api *Router) listAlbums(ctx context.Context, opts model.QueryOptions, q it
 	if len(q.studioIds) > 0 {
 		filters = append(filters, filter.ByStudioID(q.studioIds))
 	}
-	if q.favOnly {
-		filters = append(filters, filter.ByStarred().Filters)
+	// Not on the search path: its first FTS phase selects rowids with no annotation join, so a
+	// starred/play_count predicate there is "no such column" rather than a filter.
+	if q.search == "" {
+		filters = append(filters, q.filters.predicates()...)
 	}
 	opts.Filters = filters
 	opts = filter.ApplyLibraryFilter(opts, q.scopeIDs)
@@ -668,8 +718,10 @@ func (api *Router) listSongs(ctx context.Context, opts model.QueryOptions, q ite
 	if len(q.studioIds) > 0 {
 		filters = append(filters, filter.ByStudioID(q.studioIds))
 	}
-	if q.favOnly {
-		filters = append(filters, filter.ByStarred().Filters)
+	// Not on the search path: its first FTS phase selects rowids with no annotation join, so a
+	// starred/play_count predicate there is "no such column" rather than a filter.
+	if q.search == "" {
+		filters = append(filters, q.filters.predicates()...)
 	}
 	opts.Filters = filters
 	opts = filter.ApplyLibraryFilter(opts, q.scopeIDs)
@@ -720,14 +772,12 @@ func (api *Router) listArtists(ctx context.Context, opts model.QueryOptions, q i
 		return materialized(result(slice.Map(artists, toItem), total, opts.Offset)), nil
 	}
 
-	if q.favOnly {
-		opts.Filters = filter.ArtistsByStarred().Filters
-	} else {
-		opts.Filters = notMissing
-	}
+	filters := squirrel.And{notMissing}
+	filters = append(filters, q.filters.predicates()...)
 	if len(q.genreIds) > 0 {
-		opts.Filters = squirrel.And{opts.Filters, filter.ArtistsByGenreID(q.genreIds)}
+		filters = append(filters, filter.ArtistsByGenreID(q.genreIds))
 	}
+	opts.Filters = filters
 	opts = filter.ArtistsByRole(opts, role)
 	opts = filter.ApplyArtistLibraryFilter(opts, q.scopeIDs)
 	total, _ := repo.CountAll(model.QueryOptions{Filters: opts.Filters})
@@ -752,13 +802,8 @@ func (api *Router) listGenres(ctx context.Context, opts model.QueryOptions) (ite
 // listPlaylists lists playlists visible to the current user. Visibility (public or owned) is
 // enforced by playlistRepository, not scopeIDs.
 func (api *Router) listPlaylists(ctx context.Context, opts model.QueryOptions, q itemsQuery) (itemsResult, error) {
-	if q.favOnly {
-		starred := squirrel.Eq{"starred": true}
-		if opts.Filters == nil {
-			opts.Filters = starred
-		} else {
-			opts.Filters = squirrel.And{opts.Filters, starred}
-		}
+	if preds := q.filters.predicates(); len(preds) > 0 {
+		opts.Filters = squirrel.And(preds)
 	}
 	repo := api.ds.Playlist(ctx)
 	total, err := repo.CountAll(model.QueryOptions{Filters: opts.Filters})
@@ -908,18 +953,32 @@ func result(items []dto.BaseItemDto, total, start int) dto.QueryResult {
 	return dto.QueryResult{Items: items, TotalRecordCount: total, StartIndex: start}
 }
 
-// applySort translates Jellyfin's SortBy/SortOrder into a valid model.QueryOptions sort key for the
-// item type. Clients send SortBy as a comma-separated fallback list (e.g. "DateCreated,SortName");
-// this uses the first recognized key. An unrecognized SortBy is left untouched (the repo's default),
-// not passed through raw where it could produce an invalid ORDER BY.
+// applySort keeps every recognized SortBy key, so secondary keys break ties as Jellyfin intends.
+// Unrecognized keys are skipped, not passed through raw where they could make an invalid ORDER BY.
 func applySort(opts *model.QueryOptions, itemType, sortBy, order string) {
+	var cols []string
 	for key := range strings.SplitSeq(sortBy, ",") {
-		if col, ok := sortColumn(itemType, strings.TrimSpace(key)); ok {
-			opts.Sort = col
+		col, ok := sortColumn(itemType, strings.TrimSpace(key))
+		// The repo matches random by exact string equality, so it can only ever sort alone.
+		if !ok || slices.Contains(cols, col) || (col == "random" && len(cols) > 0) {
+			continue
+		}
+		cols = append(cols, col)
+		if col == "random" {
 			break
 		}
 	}
-	if strings.EqualFold(order, "Descending") {
+	switch {
+	case len(cols) > 0:
+		opts.Sort = strings.Join(cols, ", ")
+	case sortBy != "":
+		log.Debug("Jellyfin API: no usable SortBy key, falling back to the default order",
+			"itemType", itemType, "sortBy", sortBy)
+	}
+	// Jellyfin allows a per-key SortOrder list, which one Order can't express; honor the first value
+	// for every key, as Jellyfin does for keys past the end of the list.
+	first, _, _ := strings.Cut(order, ",")
+	if strings.EqualFold(first, "Descending") {
 		opts.Order = "desc"
 	}
 }
@@ -941,6 +1000,8 @@ var sortColumnsByType = map[string]map[string]string{
 		"dateplayed":        "play_date",
 		"communityrating":   "rating",
 		"random":            "random",
+		"runtime":           "duration",
+		"runtimeticks":      "duration",
 		// Finamp's "Latest Releases" sorts by PremiereDate; "year" matches songs' ProductionYear.
 		"premieredate":   "year",
 		"productionyear": "year",
@@ -964,6 +1025,8 @@ var sortColumnsByType = map[string]map[string]string{
 		"playcount":       "play_count",
 		"dateplayed":      "play_date",
 		"communityrating": "rating",
+		"runtime":         "duration",
+		"runtimeticks":    "duration",
 		"premieredate":    "max_year", "productionyear": "max_year",
 	},
 	"MusicGenre": {
diff --git a/server/jellyfin/items_test.go b/server/jellyfin/items_test.go
index b227ab719..17180c36a 100644
--- a/server/jellyfin/items_test.go
+++ b/server/jellyfin/items_test.go
@@ -327,17 +327,75 @@ var _ = Describe("Items", func() {
 			Expect(albumRepo.Options.Max).To(Equal(3))
 		})
 
-		It("applies a starred filter when Filters=IsFavorite", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-			w := httptest.NewRecorder()
-			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&Filters=IsFavorite", nil).WithContext(ctxUser())
-			invoke(api.getItems, w, r)
-			Expect(w.Code).To(Equal(http.StatusOK))
-			sql, _, err := albumRepo.Options.Filters.ToSql()
-			Expect(err).NotTo(HaveOccurred())
-			Expect(sql).To(ContainSubstring("starred"))
-		})
+		DescribeTable("translates the Filters list and its standalone equivalents",
+			func(query string, wantSQL, notWantSQL []string) {
+				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&"+query, nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				Expect(w.Code).To(Equal(http.StatusOK))
+				sql, _, err := albumRepo.Options.Filters.ToSql()
+				Expect(err).NotTo(HaveOccurred())
+				for _, want := range wantSQL {
+					Expect(sql).To(ContainSubstring(want))
+				}
+				for _, not := range notWantSQL {
+					Expect(sql).NotTo(ContainSubstring(not))
+				}
+			},
+			Entry("IsFavorite", "Filters=IsFavorite", []string{"starred"}, nil),
+			Entry("IsFavorite,IsUnplayed combined", "Filters=IsFavorite,IsUnplayed",
+				[]string{"starred", "play_count"}, nil),
+			Entry("IsUnplayed", "Filters=IsUnplayed", []string{"play_count"}, []string{"starred"}),
+			Entry("IsPlayed", "Filters=IsPlayed", []string{"play_count"}, []string{"starred"}),
+			Entry("IsFavoriteOrLikes is treated as favorites", "Filters=IsFavoriteOrLikes", []string{"starred"}, nil),
+			Entry("isPlayed=false", "isPlayed=false", []string{"play_count"}, nil),
+			Entry("isFavorite=false still filters", "isFavorite=false", []string{"starred"}, nil),
+			// Jellyfin builds the query from the standalone params, then applies Filters over the top.
+			Entry("Filters wins over the standalone param", "isFavorite=false&Filters=IsFavorite",
+				[]string{"starred = "}, nil),
+			// No Navidrome equivalent: these must be dropped, not half-applied.
+			Entry("Likes is ignored", "Filters=Likes", nil, []string{"starred", "play_count"}),
+			Entry("IsResumable is ignored", "Filters=IsResumable", nil, []string{"starred", "play_count"}),
+			// The artist-parent branch gets notMissing from filter.AlbumsByArtistID, not the default
+			// branch, so favorites must not be the only predicate left on it.
+			Entry("keeps missing excluded under an artist parent",
+				"Filters=IsFavorite&ArtistIds="+dto.EncodeID(testID("ar1")),
+				[]string{"starred", "missing"}, nil),
+		)
+
+		// Search runs a two-phase FTS query whose first phase has no annotation join, so an
+		// annotation predicate there is "no such column: starred" -> 500.
+		DescribeTable("does not push annotation filters into a search",
+			func(itemType, filters string) {
+				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+				w := httptest.NewRecorder()
+				r := httptest.NewRequest("GET",
+					"/Items?IncludeItemTypes="+itemType+"&SearchTerm=one&Filters="+filters, nil).WithContext(ctxUser())
+				invoke(api.getItems, w, r)
+				Expect(w.Code).To(Equal(http.StatusOK))
+				var opts model.QueryOptions
+				if itemType == "MusicAlbum" {
+					opts = ds.Album(context.Background()).(*tests.MockAlbumRepo).Options
+				} else {
+					opts = ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).Options
+				}
+				if opts.Filters == nil {
+					return
+				}
+				sql, _, err := opts.Filters.ToSql()
+				Expect(err).NotTo(HaveOccurred())
+				Expect(sql).NotTo(ContainSubstring("starred"))
+				Expect(sql).NotTo(ContainSubstring("play_count"))
+			},
+			Entry("albums, IsFavorite", "MusicAlbum", "IsFavorite"),
+			Entry("albums, IsUnplayed", "MusicAlbum", "IsUnplayed"),
+			Entry("albums, IsPlayed", "MusicAlbum", "IsPlayed"),
+			Entry("songs, IsFavorite", "Audio", "IsFavorite"),
+			Entry("songs, IsUnplayed", "Audio", "IsUnplayed"),
+		)
 
 		It("forwards SearchTerm to the repo's Search method", func() {
 			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
@@ -601,65 +659,59 @@ var _ = Describe("Items", func() {
 		})
 
 		Describe("sorting", func() {
-			It("maps SortBy=PlayCount to the play_count column", func() {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SortBy=PlayCount", nil).WithContext(ctxUser())
-				invoke(api.getItems, w, r)
-				Expect(w.Code).To(Equal(http.StatusOK))
-				Expect(albumRepo.Options.Sort).To(Equal("play_count"))
-			})
+			DescribeTable("translates SortBy into the repo's sort keys",
+				func(itemType, sortBy, want string) {
+					albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+					albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+					mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+					mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+					w := httptest.NewRecorder()
+					r := httptest.NewRequest("GET", "/Items?IncludeItemTypes="+itemType+"&SortBy="+sortBy, nil).WithContext(ctxUser())
+					invoke(api.getItems, w, r)
+					Expect(w.Code).To(Equal(http.StatusOK))
+					got := mfRepo.Options.Sort
+					if itemType == "MusicAlbum" {
+						got = albumRepo.Options.Sort
+					}
+					Expect(got).To(Equal(want))
+				},
+				Entry("PlayCount", "MusicAlbum", "PlayCount", "play_count"),
+				Entry("DatePlayed", "Audio", "DatePlayed", "play_date"),
+				Entry("Runtime on albums", "MusicAlbum", "Runtime", "duration"),
+				Entry("RunTimeTicks alias", "MusicAlbum", "RunTimeTicks", "duration"),
+				// Finamp leads its track sort with Runtime: unless that resolves, the first recognized
+				// key is AlbumArtist and the list looks sorted while being sorted by the wrong thing.
+				Entry("Finamp's Runtime-led track sort", "Audio", "Runtime,AlbumArtist,Album,SortName",
+					"duration, album_artist, album, title"),
+				Entry("every recognized key, in order", "MusicAlbum", "DateCreated,SortName", "recently_added, name"),
+				Entry("a key repeating a column is dropped", "Audio",
+					"PremiereDate,Album,ParentIndexNumber,IndexNumber,SortName", "year, album, title"),
+				// random is matched by exact string equality in the repo, so it can never share a sort.
+				Entry("Random stays alone", "MusicAlbum", "Random,SortName", "random"),
+				Entry("unrecognized keys are skipped", "Audio", "Runtime,Nonsense,SortName", "duration, title"),
+				Entry("only the last key recognized", "Audio", "Unknown1,Unknown2,SortName", "title"),
+				Entry("Finamp's album view is disc+track", "Audio", "ParentIndexNumber,IndexNumber,SortName", "album, title"),
+				Entry("nothing recognized leaves the repo default", "MusicAlbum", "SeriesSortName", ""),
+			)
 
-			It("maps SortBy=DatePlayed to the play_date column", func() {
-				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
-				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&SortBy=DatePlayed", nil).WithContext(ctxUser())
-				invoke(api.getItems, w, r)
-				Expect(w.Code).To(Equal(http.StatusOK))
-				Expect(mfRepo.Options.Sort).To(Equal("play_date"))
-			})
-
-			It("uses the first recognized key in a comma-separated SortBy list", func() {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SortBy=DateCreated,SortName", nil).WithContext(ctxUser())
-				invoke(api.getItems, w, r)
-				Expect(w.Code).To(Equal(http.StatusOK))
-				Expect(albumRepo.Options.Sort).To(Equal("recently_added"))
-			})
-
-			It("skips unrecognized keys in a comma-separated SortBy list to find one that is", func() {
-				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
-				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&SortBy=Unknown1,Unknown2,SortName", nil).WithContext(ctxUser())
-				invoke(api.getItems, w, r)
-				Expect(w.Code).To(Equal(http.StatusOK))
-				Expect(mfRepo.Options.Sort).To(Equal("title"))
-			})
-
-			It("maps Finamp's album view SortBy (ParentIndexNumber,IndexNumber) to disc+track order", func() {
-				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
-				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
-				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&SortBy=ParentIndexNumber,IndexNumber,SortName", nil).WithContext(ctxUser())
-				invoke(api.getItems, w, r)
-				Expect(w.Code).To(Equal(http.StatusOK))
-				Expect(mfRepo.Options.Sort).To(Equal("album"))
-			})
-
-			It("leaves Sort at the repo default when no SortBy key is recognized", func() {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
-				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-				w := httptest.NewRecorder()
-				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SortBy=SeriesSortName", nil).WithContext(ctxUser())
-				invoke(api.getItems, w, r)
-				Expect(w.Code).To(Equal(http.StatusOK))
-				Expect(albumRepo.Options.Sort).To(Equal(""))
-			})
+			// Jellyfin allows a per-key SortOrder list; we cannot express that through one Order, so
+			// we honor the first value for all keys, matching Jellyfin's fallback for extra keys.
+			DescribeTable("reads the first SortOrder value for the whole sort",
+				func(sortOrder, want string) {
+					albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+					albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+					w := httptest.NewRecorder()
+					r := httptest.NewRequest("GET",
+						"/Items?IncludeItemTypes=MusicAlbum&SortBy=Runtime,SortName&SortOrder="+sortOrder, nil).WithContext(ctxUser())
+					invoke(api.getItems, w, r)
+					Expect(w.Code).To(Equal(http.StatusOK))
+					Expect(albumRepo.Options.Order).To(Equal(want))
+				},
+				Entry("ascending", "Ascending", ""),
+				Entry("descending", "Descending", "desc"),
+				Entry("descending leading a list", "Descending,Ascending", "desc"),
+				Entry("ascending leading a list", "Ascending,Descending", ""),
+			)
 		})
 
 		Describe("library scoping", func() {

From 1f3034f0229777c2023e861a4d9a92aaca1a1207 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 19 Aug 2026 08:47:53 -0400
Subject: [PATCH 052/200] fix(playlist): block track edits on synced playlists
 across all APIs (#5984)

* fix(playlist): block track edits on synced playlists across all APIs

A synced playlist's tracks come from its source file, so any track edit made
through the UI or an API was silently reverted on the next scan. Track mutations
funnel through two service guards, checkTracksEditable (incremental edits) and
Create (wholesale replace, used by Subsonic createPlaylist and Jellyfin's
replace path), which each duplicated the smart-playlist check. Both now consult
a shared model.Playlist.TracksEditable() predicate, so the native, Subsonic, and
Jellyfin paths are all locked: track edits return ErrNotAuthorized (403, or
Subsonic error 50) instead of being accepted and lost. Metadata-only edits
(name, comment, public, the sync flag itself) still go through checkWritable and
are unaffected. In the UI, a synced playlist's track list becomes read-only,
mirroring how smart playlists already behave.

* fix(playlist): return 409 Conflict for non-editable playlist track edits

The previous commit rejected track edits on smart and synced playlists with
ErrNotAuthorized (403). That conflates two different things: a 403 says the
caller lacks permission, but a synced or smart playlist's tracks are immutable
for everyone, including the owner and admins. It is a property of the resource,
not the caller.

Introduce ErrPlaylistNotEditable and return it from both track-edit guards. The
Native and Jellyfin APIs now map it to 409 Conflict; Subsonic maps it to error
50, the closest code it has (it has no read-only concept). The Native track
handlers previously mapped this rejection inconsistently (400 on add, 500 on
remove, 403 on reorder) through a new shared writePlaylistError helper. Genuine
authorization failures (non-owner, non-admin) still return ErrNotAuthorized.

* fix(playlist): surface synced read-only state in picker, Jellyfin, and OpenSubsonic

Follow-up to the track-edit lock: the read-only state was enforced but not
advertised consistently, so clients still offered edits that the server rejects.

- UI: the Add to Playlist picker filtered targets by isWritable only, offering
  synced playlists that then 409 on add. It now filters with canChangeTracks.
- Jellyfin: addToPlaylist/removeFromPlaylist hard-coded every error to 404, so a
  locked playlist reported "not found" instead of 409. They now return 409 for
  ErrPlaylistNotEditable while keeping the deliberate anti-probing 404 for every
  other error (a non-owner never reaches ErrPlaylistNotEditable, so 409 leaks
  nothing).
- OpenSubsonic: buildOSPlaylist marked only smart playlists readonly; owned
  synced playlists advertised readonly=false. Readonly now also covers
  !TracksEditable(), matching the existing smart-playlist treatment.

* fix(jellyfin): report CanEdit from playlist editability in permission probes

getPlaylistUsers and getPlaylistUser returned CanEdit: true unconditionally, so
Finamp (which probes this before showing edit controls) offered track editing on
synced/smart playlists whose add/remove requests now return 409. Both handlers
now fetch the playlist and set CanEdit from TracksEditable(), keeping the
deliberate non-owner looseness (CanEdit stays true for a normal playlist a
non-owner views) and mapping any lookup error to 404 like the sibling probes.

* fix(playlist): check ownership before editability when replacing tracks

Create checked TracksEditable() before ownership, so a non-owner replacing
another user's public smart/synced playlist (Jellyfin updatePlaylist with a
non-empty Ids list) received a 409 read-only conflict instead of a 403
authorization failure. The incremental guards check ownership first via
checkWritable; Create now matches that order. Subsonic is unaffected (both errors
map to code 50). Owners of their own smart/synced playlists still get the
read-only conflict.

* fix(jellyfin): return 403 for locked playlists, matching Jellyfin

Jellyfin itself refuses edits on its file-backed playlists with Forbid() (403):
PlaylistsController gates every mutation on OwnerUserId == caller or a share with
CanEdit, and playlists imported from .m3u files satisfy neither. Its CanEdit is
an ACL field, not a read-only marker, and Jellyfin core has no server-managed
playlist type at all.

Our Jellyfin routes exist to imitate that API, so ErrPlaylistNotEditable now maps
to 403 there instead of 409. The native API keeps 409 (a resource-state conflict
is the accurate REST answer where we define the contract) and Subsonic keeps
error 50, its closest code.

* chore(playlist): trim comments added by this branch

Several comments ran to three or four lines and carried rationale that belongs in
the commit history rather than the code: what Jellyfin does with its own
file-backed playlists, and restatements of the expressions directly below them.
Each block is now one or two lines covering only the non-obvious why.
---
 core/playlists/playlists.go                 | 13 +++--
 core/playlists/playlists_test.go            | 46 +++++++++++++--
 model/errors.go                             |  3 +
 model/playlist.go                           |  5 ++
 model/playlist_test.go                      | 15 +++++
 server/jellyfin/playlists.go                | 49 ++++++++++++----
 server/jellyfin/playlists_test.go           | 63 ++++++++++++++++++++-
 server/nativeapi/playlists.go               | 30 ++++++----
 server/nativeapi/playlists_test.go          | 14 +++++
 server/subsonic/api.go                      |  3 +-
 server/subsonic/playlists.go                |  2 +-
 server/subsonic/playlists_test.go           |  9 +++
 ui/src/common/playlistUtils.js              |  2 +-
 ui/src/common/playlistUtils.test.js         |  6 ++
 ui/src/dialogs/SelectPlaylistInput.jsx      |  5 +-
 ui/src/dialogs/SelectPlaylistInput.test.jsx |  9 +++
 16 files changed, 232 insertions(+), 42 deletions(-)

diff --git a/core/playlists/playlists.go b/core/playlists/playlists.go
index 656bde05e..9ae8f09cb 100644
--- a/core/playlists/playlists.go
+++ b/core/playlists/playlists.go
@@ -130,12 +130,13 @@ func (s *playlists) Create(ctx context.Context, playlistId string, name string,
 			if err != nil {
 				return err
 			}
-			if pls.IsSmartPlaylist() {
-				return model.ErrNotAuthorized
-			}
+			// Ownership first: a non-owner must get ErrNotAuthorized, not a read-only conflict.
 			if !usr.IsAdmin && pls.OwnerID != usr.ID {
 				return model.ErrNotAuthorized
 			}
+			if !pls.TracksEditable() {
+				return model.ErrPlaylistNotEditable
+			}
 		} else {
 			pls = &model.Playlist{Name: name}
 			pls.OwnerID = usr.ID
@@ -230,14 +231,14 @@ func (s *playlists) checkWritable(ctx context.Context, id string) (*model.Playli
 	return pls, nil
 }
 
-// checkTracksEditable verifies the user can modify tracks (ownership + not smart playlist).
+// checkTracksEditable verifies the user owns the playlist and its tracks are editable.
 func (s *playlists) checkTracksEditable(ctx context.Context, playlistID string) (*model.Playlist, error) {
 	pls, err := s.checkWritable(ctx, playlistID)
 	if err != nil {
 		return nil, err
 	}
-	if pls.IsSmartPlaylist() {
-		return nil, model.ErrNotAuthorized
+	if !pls.TracksEditable() {
+		return nil, model.ErrPlaylistNotEditable
 	}
 	return pls, nil
 }
diff --git a/core/playlists/playlists_test.go b/core/playlists/playlists_test.go
index e8134b2ef..dd182b3f1 100644
--- a/core/playlists/playlists_test.go
+++ b/core/playlists/playlists_test.go
@@ -102,6 +102,8 @@ var _ = Describe("Playlists", func() {
 				"pls-2": {ID: "pls-2", Name: "Other's", OwnerID: "other-user"},
 				"pls-smart": {ID: "pls-smart", Name: "Smart", OwnerID: "user-1",
 					Rules: &criteria.Criteria{Expression: criteria.Contains{"title": "test"}}},
+				"pls-synced":       {ID: "pls-synced", Name: "Synced", OwnerID: "user-1", Sync: true},
+				"pls-synced-other": {ID: "pls-synced-other", Name: "Other's Synced", OwnerID: "other-user", Sync: true, Public: true},
 			}
 			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
 		})
@@ -145,6 +147,18 @@ var _ = Describe("Playlists", func() {
 		It("denies replacing tracks on a smart playlist", func() {
 			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
 			_, err := ps.Create(ctx, "pls-smart", "", []string{"song-1"})
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
+		})
+
+		It("denies replacing tracks on a synced playlist", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+			_, err := ps.Create(ctx, "pls-synced", "", []string{"song-1"})
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
+		})
+
+		It("denies a non-owner with authorization, not a conflict, on a public synced playlist", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+			_, err := ps.Create(ctx, "pls-synced-other", "", []string{"song-1"})
 			Expect(err).To(MatchError(model.ErrNotAuthorized))
 		})
 	})
@@ -159,6 +173,7 @@ var _ = Describe("Playlists", func() {
 				"pls-other": {ID: "pls-other", Name: "Other's", OwnerID: "other-user"},
 				"pls-smart": {ID: "pls-smart", Name: "Smart", OwnerID: "user-1",
 					Rules: &criteria.Criteria{Expression: criteria.Contains{"title": "test"}}},
+				"pls-synced": {ID: "pls-synced", Name: "Synced", OwnerID: "user-1", Sync: true},
 			}
 			mockPlsRepo.TracksRepo = mockTracks
 			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
@@ -191,13 +206,13 @@ var _ = Describe("Playlists", func() {
 		It("denies adding tracks to a smart playlist", func() {
 			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
 			err := ps.Update(ctx, "pls-smart", nil, nil, nil, []string{"song-1"}, nil)
-			Expect(err).To(MatchError(model.ErrNotAuthorized))
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
 		})
 
 		It("denies removing tracks from a smart playlist", func() {
 			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
 			err := ps.Update(ctx, "pls-smart", nil, nil, nil, nil, []int{0})
-			Expect(err).To(MatchError(model.ErrNotAuthorized))
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
 		})
 
 		It("allows metadata updates on a smart playlist", func() {
@@ -205,6 +220,18 @@ var _ = Describe("Playlists", func() {
 			err := ps.Update(ctx, "pls-smart", new("Updated Smart"), nil, nil, nil, nil)
 			Expect(err).ToNot(HaveOccurred())
 		})
+
+		It("denies adding tracks to a synced playlist", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+			err := ps.Update(ctx, "pls-synced", nil, nil, nil, []string{"song-1"}, nil)
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
+		})
+
+		It("allows metadata updates on a synced playlist", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+			err := ps.Update(ctx, "pls-synced", new("Renamed Synced"), nil, nil, nil, nil)
+			Expect(err).ToNot(HaveOccurred())
+		})
 	})
 
 	Describe("AddTracks", func() {
@@ -216,7 +243,8 @@ var _ = Describe("Playlists", func() {
 				"pls-1": {ID: "pls-1", Name: "My Playlist", OwnerID: "user-1"},
 				"pls-smart": {ID: "pls-smart", Name: "Smart", OwnerID: "user-1",
 					Rules: &criteria.Criteria{Expression: criteria.Contains{"title": "test"}}},
-				"pls-other": {ID: "pls-other", Name: "Other's", OwnerID: "other-user"},
+				"pls-other":  {ID: "pls-other", Name: "Other's", OwnerID: "other-user"},
+				"pls-synced": {ID: "pls-synced", Name: "Synced", OwnerID: "user-1", Sync: true},
 			}
 			mockPlsRepo.TracksRepo = mockTracks
 			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
@@ -246,7 +274,13 @@ var _ = Describe("Playlists", func() {
 		It("denies editing smart playlists", func() {
 			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
 			_, err := ps.AddTracks(ctx, "pls-smart", []string{"song-1"})
-			Expect(err).To(MatchError(model.ErrNotAuthorized))
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
+		})
+
+		It("denies editing synced playlists", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+			_, err := ps.AddTracks(ctx, "pls-synced", []string{"song-1"})
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
 		})
 
 		It("returns error when playlist not found", func() {
@@ -280,7 +314,7 @@ var _ = Describe("Playlists", func() {
 		It("denies on smart playlist", func() {
 			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
 			err := ps.RemoveTracks(ctx, "pls-smart", []string{"track-1"})
-			Expect(err).To(MatchError(model.ErrNotAuthorized))
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
 		})
 
 		It("denies non-owner", func() {
@@ -314,7 +348,7 @@ var _ = Describe("Playlists", func() {
 		It("denies on smart playlist", func() {
 			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
 			err := ps.ReorderTrack(ctx, "pls-smart", 1, 3)
-			Expect(err).To(MatchError(model.ErrNotAuthorized))
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
 		})
 	})
 
diff --git a/model/errors.go b/model/errors.go
index 41029d316..0e2543378 100644
--- a/model/errors.go
+++ b/model/errors.go
@@ -9,4 +9,7 @@ var (
 	ErrExpired       = errors.New("access expired")
 	ErrNotAvailable  = errors.New("functionality not available")
 	ErrValidation    = errors.New("validation error")
+
+	// ErrPlaylistNotEditable: tracks are server-managed, so nobody can edit them (not an ACL failure).
+	ErrPlaylistNotEditable = errors.New("playlist tracks are not editable")
 )
diff --git a/model/playlist.go b/model/playlist.go
index 55b94a640..306401271 100644
--- a/model/playlist.go
+++ b/model/playlist.go
@@ -42,6 +42,11 @@ func (pls Playlist) IsSmartPlaylist() bool {
 	return pls.Rules != nil && pls.Rules.Expression != nil
 }
 
+// TracksEditable reports whether the track list is user-owned rather than server-managed.
+func (pls Playlist) TracksEditable() bool {
+	return !pls.IsSmartPlaylist() && !pls.Sync
+}
+
 // RefreshDelay returns the playlist's own refresh window when set, falling
 // back to the global SmartPlaylistRefreshDelay.
 func (pls Playlist) RefreshDelay() time.Duration {
diff --git a/model/playlist_test.go b/model/playlist_test.go
index d936129ce..d98c85716 100644
--- a/model/playlist_test.go
+++ b/model/playlist_test.go
@@ -73,4 +73,19 @@ var _ = Describe("Playlist", func() {
 			Expect(pls.RefreshDelay()).To(Equal(5 * time.Second))
 		})
 	})
+
+	Describe("TracksEditable", func() {
+		It("is true for a plain playlist", func() {
+			Expect(model.Playlist{}.TracksEditable()).To(BeTrue())
+		})
+
+		It("is false for a smart playlist", func() {
+			pls := model.Playlist{Rules: &criteria.Criteria{Expression: criteria.Is{"loved": true}}}
+			Expect(pls.TracksEditable()).To(BeFalse())
+		})
+
+		It("is false for a synced playlist", func() {
+			Expect(model.Playlist{Sync: true}.TracksEditable()).To(BeFalse())
+		})
+	})
 })
diff --git a/server/jellyfin/playlists.go b/server/jellyfin/playlists.go
index 805b369c8..ac790a821 100644
--- a/server/jellyfin/playlists.go
+++ b/server/jellyfin/playlists.go
@@ -29,11 +29,11 @@ func playlistsFolder() dto.BaseItemDto {
 	}
 }
 
-// playlistError maps core/playlists write errors to HTTP status: ownership -> 403, missing/invisible
-// -> 404 (never revealing another user's private playlist), else -> 500.
+// playlistError maps core/playlists write errors to HTTP status: ownership or locked -> 403,
+// missing/invisible -> 404 (never revealing another user's private playlist), else -> 500.
 func (api *Router) playlistError(w http.ResponseWriter, r *http.Request, err error) {
 	switch {
-	case errors.Is(err, model.ErrNotAuthorized):
+	case errors.Is(err, model.ErrNotAuthorized), errors.Is(err, model.ErrPlaylistNotEditable):
 		http.Error(w, "Forbidden", http.StatusForbidden)
 	case errors.Is(err, model.ErrNotFound):
 		http.Error(w, "Not Found", http.StatusNotFound)
@@ -262,7 +262,7 @@ func (api *Router) songIDs(ctx context.Context, opts model.QueryOptions) []strin
 }
 
 // addToPlaylist appends items by id, expanding containers into tracks (see expandContainerIDs).
-// AddTracks enforces ownership; any error maps to 404.
+// AddTracks enforces ownership; a locked playlist maps to 403, any other error to 404.
 func (api *Router) addToPlaylist(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	id, ok := itemIDParam(w, r, "playlistId")
@@ -276,6 +276,10 @@ func (api *Router) addToPlaylist(w http.ResponseWriter, r *http.Request) {
 	}
 	ids := api.expandContainerIDs(ctx, decoded)
 	if _, err := api.playlists.AddTracks(ctx, id, ids); err != nil {
+		if errors.Is(err, model.ErrPlaylistNotEditable) {
+			http.Error(w, "Forbidden", http.StatusForbidden)
+			return
+		}
 		http.Error(w, "Not Found", http.StatusNotFound)
 		return
 	}
@@ -284,7 +288,7 @@ func (api *Router) addToPlaylist(w http.ResponseWriter, r *http.Request) {
 
 // removeFromPlaylist removes entries by entryIds — playlist-entry ids (PlaylistItemId), not media
 // file ids, since RemoveTracks deletes playlist_tracks rows by that id. RemoveTracks enforces
-// ownership; any error maps to 404.
+// ownership; a locked playlist maps to 403, any other error to 404.
 func (api *Router) removeFromPlaylist(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	id, ok := itemIDParam(w, r, "playlistId")
@@ -302,21 +306,44 @@ func (api *Router) removeFromPlaylist(w http.ResponseWriter, r *http.Request) {
 		ids = append(ids, entry)
 	}
 	if err := api.playlists.RemoveTracks(ctx, id, ids); err != nil {
+		if errors.Is(err, model.ErrPlaylistNotEditable) {
+			http.Error(w, "Forbidden", http.StatusForbidden)
+			return
+		}
 		http.Error(w, "Not Found", http.StatusNotFound)
 		return
 	}
 	w.WriteHeader(http.StatusNoContent)
 }
 
-// getPlaylistUsers and getPlaylistUser answer client probes (e.g. Finamp) made before allowing
-// edits. Navidrome has no per-playlist ACL, so every user is reported CanEdit; ownership is still
-// enforced by AddTracks/RemoveTracks.
+// Clients probe these before offering edits. Navidrome has no per-playlist ACL, so CanEdit carries
+// only editability; ownership is enforced on write, and a lookup error 404s to prevent probing.
 func (api *Router) getPlaylistUsers(w http.ResponseWriter, r *http.Request) {
-	u, _ := request.UserFrom(r.Context())
-	api.ok(w, r, []dto.PlaylistUserPermissions{{UserId: dto.EncodeID(u.ID), CanEdit: true}})
+	ctx := r.Context()
+	id, ok := itemIDParam(w, r, "playlistId")
+	if !ok {
+		return
+	}
+	pls, err := api.playlists.Get(ctx, id)
+	if err != nil {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
+	u, _ := request.UserFrom(ctx)
+	api.ok(w, r, []dto.PlaylistUserPermissions{{UserId: dto.EncodeID(u.ID), CanEdit: pls.TracksEditable()}})
 }
 
 func (api *Router) getPlaylistUser(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	id, ok := itemIDParam(w, r, "playlistId")
+	if !ok {
+		return
+	}
+	pls, err := api.playlists.Get(ctx, id)
+	if err != nil {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
 	userId := chi.URLParam(r, "userId")
-	api.ok(w, r, dto.PlaylistUserPermissions{UserId: userId, CanEdit: true})
+	api.ok(w, r, dto.PlaylistUserPermissions{UserId: userId, CanEdit: pls.TracksEditable()})
 }
diff --git a/server/jellyfin/playlists_test.go b/server/jellyfin/playlists_test.go
index 3599cc784..270f5fe08 100644
--- a/server/jellyfin/playlists_test.go
+++ b/server/jellyfin/playlists_test.go
@@ -381,6 +381,15 @@ var _ = Describe("Playlists", func() {
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
+		It("returns 403 when the playlist is not editable (synced/smart), like Jellyfin", func() {
+			fp.addErr = model.ErrPlaylistNotEditable
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("POST", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?ids="+dto.EncodeID(testID("s1")), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
+			invoke(api.addToPlaylist, w, r)
+			Expect(w.Code).To(Equal(http.StatusForbidden))
+		})
+
 		It("passes no ids (not a spurious empty string) when the ids param is absent", func() {
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items", nil).WithContext(context.Background())
@@ -430,6 +439,15 @@ var _ = Describe("Playlists", func() {
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 
+		It("returns 403 when the playlist is not editable (synced/smart), like Jellyfin", func() {
+			fp.removeErr = model.ErrPlaylistNotEditable
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("DELETE", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items?entryIds="+dto.EncodePlaylistEntryID("1"), nil).WithContext(context.Background())
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
+			invoke(api.removeFromPlaylist, w, r)
+			Expect(w.Code).To(Equal(http.StatusForbidden))
+		})
+
 		It("passes no ids (not a spurious empty string) when the entryIds param is absent", func() {
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("DELETE", "/Playlists/"+dto.EncodeID(testID("pl1"))+"/Items", nil).WithContext(context.Background())
@@ -442,7 +460,8 @@ var _ = Describe("Playlists", func() {
 	})
 
 	Describe("getPlaylistUsers", func() {
-		It("returns the current user with CanEdit true", func() {
+		It("returns the current user with CanEdit true for an editable playlist", func() {
+			fp.getByIDPls = &model.Playlist{ID: testID("pl1")}
 			w := httptest.NewRecorder()
 			ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice"})
 			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1")+"/Users", nil).WithContext(ctx)
@@ -453,21 +472,59 @@ var _ = Describe("Playlists", func() {
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res).To(Equal([]dto.PlaylistUserPermissions{{UserId: dto.EncodeID(testID("u1")), CanEdit: true}}))
 		})
+
+		It("reports CanEdit false for a synced playlist", func() {
+			fp.getByIDPls = &model.Playlist{ID: testID("pl1"), Sync: true}
+			w := httptest.NewRecorder()
+			ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice"})
+			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1")+"/Users", nil).WithContext(ctx)
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
+			api.getPlaylistUsers(w, r)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			var res []dto.PlaylistUserPermissions
+			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+			Expect(res[0].CanEdit).To(BeFalse())
+		})
+
+		It("returns 404 when the playlist is not visible", func() {
+			fp.getByIDErr = model.ErrNotFound
+			w := httptest.NewRecorder()
+			ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice"})
+			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1")+"/Users", nil).WithContext(ctx)
+			r = withChiURLParam(r, "playlistId", dto.EncodeID(testID("pl1")))
+			api.getPlaylistUsers(w, r)
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
 	})
 
 	Describe("getPlaylistUser", func() {
-		It("returns CanEdit true for the requested user", func() {
+		requestUser := func() *httptest.ResponseRecorder {
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Playlists/"+testID("pl1")+"/Users/"+testID("u1"), nil).WithContext(context.Background())
 			rctx := chi.NewRouteContext()
-			rctx.URLParams.Add("playlistId", testID("pl1"))
+			rctx.URLParams.Add("playlistId", dto.EncodeID(testID("pl1")))
 			rctx.URLParams.Add("userId", testID("u1"))
 			r = r.WithContext(context.WithValue(r.Context(), chi.RouteCtxKey, rctx))
 			api.getPlaylistUser(w, r)
+			return w
+		}
+
+		It("returns CanEdit true for an editable playlist", func() {
+			fp.getByIDPls = &model.Playlist{ID: testID("pl1")}
+			w := requestUser()
 			Expect(w.Code).To(Equal(http.StatusOK))
 			var res dto.PlaylistUserPermissions
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res).To(Equal(dto.PlaylistUserPermissions{UserId: testID("u1"), CanEdit: true}))
 		})
+
+		It("reports CanEdit false for a synced playlist", func() {
+			fp.getByIDPls = &model.Playlist{ID: testID("pl1"), Sync: true}
+			w := requestUser()
+			Expect(w.Code).To(Equal(http.StatusOK))
+			var res dto.PlaylistUserPermissions
+			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+			Expect(res.CanEdit).To(BeFalse())
+		})
 	})
 })
diff --git a/server/nativeapi/playlists.go b/server/nativeapi/playlists.go
index 90b2f9e94..d215eb9dd 100644
--- a/server/nativeapi/playlists.go
+++ b/server/nativeapi/playlists.go
@@ -20,6 +20,20 @@ import (
 
 type restHandler = func(rest.RepositoryConstructor, ...rest.Logger) http.HandlerFunc
 
+// writePlaylistError maps a playlist service error to an HTTP status, or defaultStatus if unknown.
+func writePlaylistError(w http.ResponseWriter, err error, defaultStatus int) {
+	switch {
+	case errors.Is(err, model.ErrNotFound):
+		http.Error(w, err.Error(), http.StatusNotFound)
+	case errors.Is(err, model.ErrNotAuthorized):
+		http.Error(w, err.Error(), http.StatusForbidden)
+	case errors.Is(err, model.ErrPlaylistNotEditable):
+		http.Error(w, err.Error(), http.StatusConflict)
+	default:
+		http.Error(w, err.Error(), defaultStatus)
+	}
+}
+
 func playlistTracksHandler(pls playlists.Playlists, handler restHandler, refreshSmartPlaylist func(*http.Request) bool) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		plsId := chi.URLParam(r, "playlistId")
@@ -111,7 +125,7 @@ func deleteFromPlaylist(pls playlists.Playlists) http.HandlerFunc {
 		}
 		if err != nil {
 			log.Error(r.Context(), "Error deleting tracks from playlist", "playlistId", playlistId, "ids", ids, err)
-			http.Error(w, err.Error(), http.StatusInternalServerError)
+			writePlaylistError(w, err, http.StatusInternalServerError)
 			return
 		}
 		writeDeleteManyResponse(w, r, ids)
@@ -138,22 +152,22 @@ func addToPlaylist(pls playlists.Playlists) http.HandlerFunc {
 		}
 		count, c := 0, 0
 		if c, err = pls.AddTracks(ctx, playlistId, payload.Ids); err != nil {
-			http.Error(w, err.Error(), http.StatusBadRequest)
+			writePlaylistError(w, err, http.StatusBadRequest)
 			return
 		}
 		count += c
 		if c, err = pls.AddAlbums(ctx, playlistId, payload.AlbumIds); err != nil {
-			http.Error(w, err.Error(), http.StatusBadRequest)
+			writePlaylistError(w, err, http.StatusBadRequest)
 			return
 		}
 		count += c
 		if c, err = pls.AddArtists(ctx, playlistId, payload.ArtistIds); err != nil {
-			http.Error(w, err.Error(), http.StatusBadRequest)
+			writePlaylistError(w, err, http.StatusBadRequest)
 			return
 		}
 		count += c
 		if c, err = pls.AddDiscs(ctx, playlistId, payload.Discs); err != nil {
-			http.Error(w, err.Error(), http.StatusBadRequest)
+			writePlaylistError(w, err, http.StatusBadRequest)
 			return
 		}
 		count += c
@@ -192,12 +206,8 @@ func reorderItem(pls playlists.Playlists) http.HandlerFunc {
 			return
 		}
 		err = pls.ReorderTrack(ctx, playlistId, id, newPos)
-		if errors.Is(err, model.ErrNotAuthorized) {
-			http.Error(w, err.Error(), http.StatusForbidden)
-			return
-		}
 		if err != nil {
-			http.Error(w, err.Error(), http.StatusBadRequest)
+			writePlaylistError(w, err, http.StatusBadRequest)
 			return
 		}
 
diff --git a/server/nativeapi/playlists_test.go b/server/nativeapi/playlists_test.go
index 9bf502687..74ef58cab 100644
--- a/server/nativeapi/playlists_test.go
+++ b/server/nativeapi/playlists_test.go
@@ -183,6 +183,20 @@ var _ = Describe("Playlist Tracks Endpoint", func() {
 	})
 })
 
+var _ = Describe("writePlaylistError", func() {
+	DescribeTable("maps a service error to an HTTP status",
+		func(err error, expected int) {
+			w := httptest.NewRecorder()
+			writePlaylistError(w, err, http.StatusBadRequest)
+			Expect(w.Code).To(Equal(expected))
+		},
+		Entry("not found -> 404", model.ErrNotFound, http.StatusNotFound),
+		Entry("not authorized -> 403", model.ErrNotAuthorized, http.StatusForbidden),
+		Entry("not editable -> 409", model.ErrPlaylistNotEditable, http.StatusConflict),
+		Entry("unrecognized -> default", model.ErrValidation, http.StatusBadRequest),
+	)
+})
+
 type mockPlaylistTrackRepo struct {
 	model.PlaylistTrackRepository
 	tracks model.PlaylistTracks
diff --git a/server/subsonic/api.go b/server/subsonic/api.go
index 82e404228..029046c39 100644
--- a/server/subsonic/api.go
+++ b/server/subsonic/api.go
@@ -304,7 +304,8 @@ func mapToSubsonicError(err error) subError {
 		err = newError(responses.ErrorGeneric, err.Error())
 	case errors.Is(err, model.ErrNotFound), errors.Is(err, rest.ErrNotFound):
 		err = newError(responses.ErrorDataNotFound, "data not found")
-	case errors.Is(err, model.ErrNotAuthorized), errors.Is(err, rest.ErrPermissionDenied):
+	case errors.Is(err, model.ErrNotAuthorized), errors.Is(err, rest.ErrPermissionDenied),
+		errors.Is(err, model.ErrPlaylistNotEditable): // Subsonic has no code for "read-only resource"
 		err = newError(responses.ErrorAuthorizationFail)
 	case errors.Is(err, stream.ErrTooManyTranscodes):
 		err = newError(responses.ErrorGeneric, "too many concurrent transcodes, please retry shortly")
diff --git a/server/subsonic/playlists.go b/server/subsonic/playlists.go
index bd53528d9..774a9c430 100644
--- a/server/subsonic/playlists.go
+++ b/server/subsonic/playlists.go
@@ -172,7 +172,7 @@ func buildOSPlaylist(ctx context.Context, p model.Playlist) *responses.OpenSubso
 		}
 	} else {
 		user, ok := request.UserFrom(ctx)
-		pls.Readonly = !ok || p.OwnerID != user.ID
+		pls.Readonly = !ok || p.OwnerID != user.ID || !p.TracksEditable()
 	}
 
 	return &pls
diff --git a/server/subsonic/playlists_test.go b/server/subsonic/playlists_test.go
index a7c9e2ec7..f18f33b47 100644
--- a/server/subsonic/playlists_test.go
+++ b/server/subsonic/playlists_test.go
@@ -111,6 +111,15 @@ var _ = Describe("buildPlaylist", func() {
 				Expect(result.Public).To(BeTrue())
 				Expect(result.Readonly).To(BeFalse())
 			})
+
+			It("is read-only for a synced playlist even as owner", func() {
+				ctx = request.WithUser(ctx, model.User{ID: "1234", UserName: "admin"})
+				playlist.Sync = true
+
+				result := router.buildPlaylist(ctx, playlist)
+
+				Expect(result.Readonly).To(BeTrue())
+			})
 		})
 
 		Context("when minimal clients list is empty", func() {
diff --git a/ui/src/common/playlistUtils.js b/ui/src/common/playlistUtils.js
index 74a01d47a..2d0c745ff 100644
--- a/ui/src/common/playlistUtils.js
+++ b/ui/src/common/playlistUtils.js
@@ -12,4 +12,4 @@ export const isReadOnly = (ownerId) => {
 export const isSmartPlaylist = (pls) => !!pls.rules
 
 export const canChangeTracks = (pls) =>
-  isWritable(pls.ownerId) && !isSmartPlaylist(pls)
+  isWritable(pls.ownerId) && !isSmartPlaylist(pls) && !pls.sync
diff --git a/ui/src/common/playlistUtils.test.js b/ui/src/common/playlistUtils.test.js
index 2c671ecf5..345b6045d 100644
--- a/ui/src/common/playlistUtils.test.js
+++ b/ui/src/common/playlistUtils.test.js
@@ -74,5 +74,11 @@ describe('playlistUtils', () => {
       const playlist = { ownerId: 'user1', rules: [] }
       expect(canChangeTracks(playlist)).toBe(false)
     })
+
+    it('returns false if playlist is synced', () => {
+      localStorage.setItem('userId', 'user1')
+      const playlist = { ownerId: 'user1', sync: true }
+      expect(canChangeTracks(playlist)).toBe(false)
+    })
   })
 })
diff --git a/ui/src/dialogs/SelectPlaylistInput.jsx b/ui/src/dialogs/SelectPlaylistInput.jsx
index 847107523..2f040a7f7 100644
--- a/ui/src/dialogs/SelectPlaylistInput.jsx
+++ b/ui/src/dialogs/SelectPlaylistInput.jsx
@@ -16,7 +16,7 @@ import {
 import AddIcon from '@material-ui/icons/Add'
 import { useGetList, useTranslate } from 'react-admin'
 import PropTypes from 'prop-types'
-import { isWritable } from '../common'
+import { canChangeTracks } from '../common'
 import { makeStyles } from '@material-ui/core'
 
 const useStyles = makeStyles((theme) => ({
@@ -268,8 +268,7 @@ export const SelectPlaylistInput = ({ onChange }) => {
   )
 
   const options =
-    ids &&
-    ids.map((id) => data[id]).filter((option) => isWritable(option.ownerId))
+    ids && ids.map((id) => data[id]).filter((option) => canChangeTracks(option))
 
   // Filter playlists based on search text
   const filteredOptions =
diff --git a/ui/src/dialogs/SelectPlaylistInput.test.jsx b/ui/src/dialogs/SelectPlaylistInput.test.jsx
index 4ffcdf0b6..753d12c03 100644
--- a/ui/src/dialogs/SelectPlaylistInput.test.jsx
+++ b/ui/src/dialogs/SelectPlaylistInput.test.jsx
@@ -16,6 +16,7 @@ const mockPlaylists = [
   { id: 'playlist-2', name: 'Jazz Collection', ownerId: 'admin' },
   { id: 'playlist-3', name: 'Electronic Beats', ownerId: 'admin' },
   { id: 'playlist-4', name: 'Chill Vibes', ownerId: 'user2' }, // Not writable by admin
+  { id: 'playlist-5', name: 'Synced List', ownerId: 'admin', sync: true },
 ]
 
 const mockIndexedData = {
@@ -27,6 +28,12 @@ const mockIndexedData = {
     ownerId: 'admin',
   },
   'playlist-4': { id: 'playlist-4', name: 'Chill Vibes', ownerId: 'user2' },
+  'playlist-5': {
+    id: 'playlist-5',
+    name: 'Synced List',
+    ownerId: 'admin',
+    sync: true,
+  },
 }
 
 const createTestComponent = (
@@ -89,6 +96,8 @@ describe('SelectPlaylistInput', () => {
 
       // Should not show playlists not owned by admin (not writable)
       expect(screen.queryByText('Chill Vibes')).not.toBeInTheDocument()
+      // Should not show synced playlists (their tracks are not editable)
+      expect(screen.queryByText('Synced List')).not.toBeInTheDocument()
     })
 
     it('should filter playlists based on search input', async () => {

From 2dab4b40483a6feb3be2007afa4a1ac83c2d0504 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 19 Aug 2026 08:49:15 -0400
Subject: [PATCH 053/200] chore: remove redundant comment

Signed-off-by: Deluan <deluan@navidrome.org>
---
 model/errors.go | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/model/errors.go b/model/errors.go
index 0e2543378..9e56f9501 100644
--- a/model/errors.go
+++ b/model/errors.go
@@ -3,13 +3,11 @@ package model
 import "errors"
 
 var (
-	ErrNotFound      = errors.New("data not found")
-	ErrInvalidAuth   = errors.New("invalid authentication")
-	ErrNotAuthorized = errors.New("not authorized")
-	ErrExpired       = errors.New("access expired")
-	ErrNotAvailable  = errors.New("functionality not available")
-	ErrValidation    = errors.New("validation error")
-
-	// ErrPlaylistNotEditable: tracks are server-managed, so nobody can edit them (not an ACL failure).
+	ErrNotFound            = errors.New("data not found")
+	ErrInvalidAuth         = errors.New("invalid authentication")
+	ErrNotAuthorized       = errors.New("not authorized")
+	ErrExpired             = errors.New("access expired")
+	ErrNotAvailable        = errors.New("functionality not available")
+	ErrValidation          = errors.New("validation error")
 	ErrPlaylistNotEditable = errors.New("playlist tracks are not editable")
 )

From 6d8a3e48eeacf4dda8edd6841f714f3ee064a371 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 19 Aug 2026 09:19:47 -0400
Subject: [PATCH 054/200] refactor: replace `md5` with `xxh3` for faster and
 more efficient hashing

Signed-off-by: Deluan <deluan@navidrome.org>
---
 .golangci.yml                      |  3 +++
 core/artwork/housekeeping.go       |  6 ++----
 core/artwork/housekeeping_test.go  |  2 +-
 model/mediafile.go                 |  4 ++--
 model/mediafile_test.go            | 12 ++++--------
 model/participants.go              |  4 ++--
 model/tag.go                       |  4 ++--
 persistence/sql_base_repository.go |  6 +++---
 8 files changed, 19 insertions(+), 22 deletions(-)

diff --git a/.golangci.yml b/.golangci.yml
index 0804138dc..7df4f8ec3 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -27,6 +27,9 @@ linters:
   disable:
     - staticcheck
   settings:
+    errcheck:
+      exclude-functions:
+        - (*github.com/zeebo/xxh3.Hasher).Write
     gocritic:
       disable-all: true
       enabled-checks:
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
index ae1fc0a0d..f2996d044 100644
--- a/core/artwork/housekeeping.go
+++ b/core/artwork/housekeeping.go
@@ -2,8 +2,6 @@ package artwork
 
 import (
 	"context"
-	"crypto/md5"
-	"encoding/hex"
 	"fmt"
 	"slices"
 	"strconv"
@@ -16,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/zeebo/xxh3"
 )
 
 // StaleAbsentAge is how long an absent state is trusted before a recheck retries it.
@@ -66,8 +65,7 @@ func FingerprintInputs() []FingerprintInput {
 func ConfigFingerprint() string {
 	values := slice.Map(FingerprintInputs(), func(i FingerprintInput) string { return i.Value })
 	raw := fmt.Sprintf("%s|%d", strings.Join(values, "|"), artworkEpoch)
-	sum := md5.Sum([]byte(raw)) //nolint:gosec // fingerprint, not security-sensitive
-	return hex.EncodeToString(sum[:])
+	return fmt.Sprintf("%016x", xxh3.Hash([]byte(raw)))
 }
 
 // backfill enqueues artwork resolution for every entity when the config fingerprint changed.
diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.go
index 32a7688b4..4ea15ab04 100644
--- a/core/artwork/housekeeping_test.go
+++ b/core/artwork/housekeeping_test.go
@@ -135,7 +135,7 @@ var _ = Describe("Housekeeping", func() {
 			conf.Server.EnableExternalServices = true
 			conf.Server.EnableM3UExternalAlbumArt = false
 
-			Expect(ConfigFingerprint()).To(Equal("7e537a22febc07d3d5ca40546e88da54"))
+			Expect(ConfigFingerprint()).To(Equal("7b538a83a870c16d"))
 		})
 
 		It("reports the config inputs it hashes, so a change can be traced to a setting", func() {
diff --git a/model/mediafile.go b/model/mediafile.go
index f4e767272..99aee591e 100644
--- a/model/mediafile.go
+++ b/model/mediafile.go
@@ -2,7 +2,6 @@ package model
 
 import (
 	"cmp"
-	"crypto/md5"
 	"encoding/json"
 	"fmt"
 	"iter"
@@ -20,6 +19,7 @@ import (
 	"github.com/navidrome/navidrome/utils/gg"
 	"github.com/navidrome/navidrome/utils/number"
 	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/zeebo/xxh3"
 )
 
 type MediaFile struct {
@@ -232,7 +232,7 @@ func (mf MediaFile) Hash() string {
 		ZeroNil:         true,
 	}
 	hash, _ := hashstructure.Hash(mf, opts)
-	sum := md5.New()
+	sum := xxh3.New()
 	sum.Write(fmt.Appendf(nil, "%d", hash))
 	sum.Write(mf.Tags.Hash())
 	sum.Write(mf.Participants.Hash())
diff --git a/model/mediafile_test.go b/model/mediafile_test.go
index 3f306f1a7..097e3ca54 100644
--- a/model/mediafile_test.go
+++ b/model/mediafile_test.go
@@ -715,14 +715,10 @@ var _ = Describe("MediaFile.Movements", func() {
 })
 
 var _ = Describe("MediaFile.Hash", func() {
-	// Guards the upgrade guarantee: converting BPM/BitDepth from int to *int must not change hashes,
-	// or every file would be spuriously re-imported on the next scan.
-	// Golden hashes were captured at 46221d516 when those fields were plain ints.
-	It("keeps hashes identical to the pre-pointer-conversion values", func() {
-		// Golden hashes computed at 46221d516, when BPM/BitDepth were plain ints — pinning
-		// them guarantees the pointer conversion cannot trigger a full-library re-import.
-		Expect(MediaFile{Title: "Song"}.Hash()).To(Equal("1d856ced42cb96db39e354a4bac9a622"))
-		Expect(MediaFile{Title: "Song", BPM: new(120), BitDepth: new(16)}.Hash()).To(Equal("b2b0b1d1dd7fd767093588e4af3a0689"))
+	// Pins the hash formula: an accidental change spuriously re-imports every file on the next scan.
+	It("hashes to a stable value", func() {
+		Expect(MediaFile{Title: "Song"}.Hash()).To(Equal("05fdf70bb0cbe090"))
+		Expect(MediaFile{Title: "Song", BPM: new(120), BitDepth: new(16)}.Hash()).To(Equal("b5daf6ac1009a538"))
 	})
 	It("changes the hash when a pointer field has a value", func() {
 		base := MediaFile{Title: "Song"}
diff --git a/model/participants.go b/model/participants.go
index afbda10de..b5390d22c 100644
--- a/model/participants.go
+++ b/model/participants.go
@@ -2,12 +2,12 @@ package model
 
 import (
 	"cmp"
-	"crypto/md5"
 	"fmt"
 	"slices"
 	"strings"
 
 	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/zeebo/xxh3"
 )
 
 var (
@@ -193,7 +193,7 @@ func (p Participants) Hash() []byte {
 		flattened = append(flattened, role.String()+":"+strings.Join(ids, "/"))
 	}
 	slices.Sort(flattened)
-	sum := md5.New()
+	sum := xxh3.New()
 	sum.Write([]byte(strings.Join(flattened, "|")))
 	return sum.Sum(nil)
 }
diff --git a/model/tag.go b/model/tag.go
index 1bc011495..bb4fce181 100644
--- a/model/tag.go
+++ b/model/tag.go
@@ -2,13 +2,13 @@ package model
 
 import (
 	"cmp"
-	"crypto/md5"
 	"fmt"
 	"slices"
 	"strings"
 
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/zeebo/xxh3"
 )
 
 type Tag struct {
@@ -117,7 +117,7 @@ func (t Tags) Hash() []byte {
 	}
 	ids := t.IDs()
 	slices.Sort(ids)
-	sum := md5.New()
+	sum := xxh3.New()
 	sum.Write([]byte(strings.Join(ids, "|")))
 	return sum.Sum(nil)
 }
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index c61bca1a6..d4cf9b456 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -2,7 +2,6 @@ package persistence
 
 import (
 	"context"
-	"crypto/md5"
 	"database/sql"
 	"errors"
 	"fmt"
@@ -23,6 +22,7 @@ import (
 	"github.com/navidrome/navidrome/utils/hasher"
 	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/pocketbase/dbx"
+	"github.com/zeebo/xxh3"
 )
 
 // sqlRepository is the base repository for all SQL repositories. It provides common functions to interact with the DB.
@@ -298,8 +298,8 @@ func (r sqlRepository) visibleLibraryIDs() ([]int, error) {
 func (r sqlRepository) seedKey() string {
 	// Seed keys must be all lowercase, or else SQLite3 will encode it, making it not match the seed
 	// used in the query. Hashing the user ID and converting it to a hex string will do the trick
-	userIDHash := md5.Sum([]byte(loggedUser(r.ctx).ID))
-	return fmt.Sprintf("%s|%x", r.tableName, userIDHash)
+	userIDHash := xxh3.Hash([]byte(loggedUser(r.ctx).ID))
+	return fmt.Sprintf("%s|%016x", r.tableName, userIDHash)
 }
 
 func (r sqlRepository) resetSeededRandom(options []model.QueryOptions) {

From bd6b7a66863ce4771cd8e3450e355cf512b31363 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 19 Aug 2026 10:35:15 -0400
Subject: [PATCH 055/200] test: increase timeout for cache availability checks
 to 10 seconds

---
 core/artwork/e2e/acquire_serve_test.go       | 2 +-
 core/artwork/e2e/resolution_harness_test.go  | 2 +-
 core/stream/media_streamer_test.go           | 9 +++++----
 server/subsonic/e2e/subsonic_artwork_test.go | 2 +-
 4 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/core/artwork/e2e/acquire_serve_test.go b/core/artwork/e2e/acquire_serve_test.go
index 0a9363b5d..34dfb2cac 100644
--- a/core/artwork/e2e/acquire_serve_test.go
+++ b/core/artwork/e2e/acquire_serve_test.go
@@ -106,7 +106,7 @@ var _ = Describe("Acquisition → serve loop", func() {
 			func(context.Context, cache.Item) (io.Reader, error) {
 				return nil, errors.New("resize not exercised in e2e")
 			})
-		Eventually(func() bool { return imgCache.Available(ctx) }).Should(BeTrue())
+		Eventually(func() bool { return imgCache.Available(ctx) }, 10*time.Second).Should(BeTrue())
 
 		svc = artwork.NewArtwork(ds, imgCache, store, ffm)
 		worker = artwork.NewWorker(ds, store, agents.GetAgents(ds, nil), ffm, events.NoopBroker(), imgCache)
diff --git a/core/artwork/e2e/resolution_harness_test.go b/core/artwork/e2e/resolution_harness_test.go
index 1168393df..fff62ce69 100644
--- a/core/artwork/e2e/resolution_harness_test.go
+++ b/core/artwork/e2e/resolution_harness_test.go
@@ -117,7 +117,7 @@ func setupResolutionHarness() {
 		func(context.Context, cache.Item) (io.Reader, error) {
 			return nil, fmt.Errorf("resize not exercised in e2e")
 		})
-	Eventually(func() bool { return imgCache.Available(rctx) }).Should(BeTrue())
+	Eventually(func() bool { return imgCache.Available(rctx) }, 10*time.Second).Should(BeTrue())
 
 	rsvc = artwork.NewArtwork(rds, imgCache, rstore, ffm)
 	rworker = artwork.NewWorker(rds, rstore, agents.GetAgents(rds, nil), ffm, events.NoopBroker(), imgCache)
diff --git a/core/stream/media_streamer_test.go b/core/stream/media_streamer_test.go
index f5ca16d3f..fb1c59a60 100644
--- a/core/stream/media_streamer_test.go
+++ b/core/stream/media_streamer_test.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"io"
 	"os"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -33,7 +34,7 @@ var _ = Describe("MediaStreamer", func() {
 			{ID: "123", Path: "tests/fixtures/test.mp3", Suffix: "mp3", BitRate: 128, Duration: 257.0},
 		})
 		testCache := stream.NewTranscodingCache()
-		Eventually(func() bool { return testCache.Available(context.TODO()) }).Should(BeTrue())
+		Eventually(func() bool { return testCache.Available(context.TODO()) }, 10*time.Second).Should(BeTrue())
 		streamer = stream.NewMediaStreamer(ds, ffmpeg, testCache)
 	})
 	AfterEach(func() {
@@ -75,7 +76,7 @@ var _ = Describe("MediaStreamer", func() {
 			conf.Server.Transcoding.MaxConcurrent = 1
 			conf.Server.Transcoding.MaxConcurrentPerUser = 0
 			tightCache := stream.NewTranscodingCache()
-			Eventually(func() bool { return tightCache.Available(context.TODO()) }).Should(BeTrue())
+			Eventually(func() bool { return tightCache.Available(context.TODO()) }, 10*time.Second).Should(BeTrue())
 			tightStreamer := stream.NewMediaStreamer(ds, blockingFFmpeg, tightCache)
 
 			userCtx := request.WithUsername(ctx, "alice")
@@ -92,7 +93,7 @@ var _ = Describe("MediaStreamer", func() {
 			conf.Server.Transcoding.MaxConcurrent = 1
 			conf.Server.Transcoding.MaxConcurrentPerUser = 0
 			tightCache := stream.NewTranscodingCache()
-			Eventually(func() bool { return tightCache.Available(context.TODO()) }).Should(BeTrue())
+			Eventually(func() bool { return tightCache.Available(context.TODO()) }, 10*time.Second).Should(BeTrue())
 			tightStreamer := stream.NewMediaStreamer(ds, ffmpeg, tightCache)
 
 			userCtx := request.WithUsername(ctx, "alice")
@@ -112,7 +113,7 @@ var _ = Describe("MediaStreamer", func() {
 			conf.Server.Transcoding.MaxConcurrent = 1
 			conf.Server.Transcoding.MaxConcurrentPerUser = 0
 			tightCache := stream.NewTranscodingCache()
-			Eventually(func() bool { return tightCache.Available(context.TODO()) }).Should(BeTrue())
+			Eventually(func() bool { return tightCache.Available(context.TODO()) }, 10*time.Second).Should(BeTrue())
 			tightStreamer := stream.NewMediaStreamer(ds, ffmpeg, tightCache)
 
 			userCtx := request.WithUsername(ctx, "alice")
diff --git a/server/subsonic/e2e/subsonic_artwork_test.go b/server/subsonic/e2e/subsonic_artwork_test.go
index 619619810..9324ea9e3 100644
--- a/server/subsonic/e2e/subsonic_artwork_test.go
+++ b/server/subsonic/e2e/subsonic_artwork_test.go
@@ -313,7 +313,7 @@ func newDummyImageCache(ctx context.Context) cache.FileCache {
 		func(context.Context, cache.Item) (io.Reader, error) {
 			return nil, errors.New("resize not exercised in subsonic artwork e2e")
 		})
-	Eventually(func() bool { return c.Available(ctx) }).Should(BeTrue())
+	Eventually(func() bool { return c.Available(ctx) }, 10*time.Second).Should(BeTrue())
 	return c
 }
 

From c362519f76d1922a6c3e1345e5ec91dada6275ed Mon Sep 17 00:00:00 2001
From: Junker der Provinz <133605895+junkerderprovinz@users.noreply.github.com>
Date: Wed, 19 Aug 2026 17:50:32 +0200
Subject: [PATCH 056/200] test: unskip path-separator tests on Windows (#5381)
 (#5916)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* test: unskip AbsolutePath and i18n path-separator tests on Windows (#5381)

Signed-off-by: junkerderprovinz <jdp@braethoria.com>

* test: unskip metadata folder-PID test on Windows via path.Dir (#5381)

Signed-off-by: junkerderprovinz <jdp@braethoria.com>

* test(storage): make relative-folder assertion cross-platform and unskip on Windows (#5381)

Signed-off-by: junkerderprovinz <jdp@braethoria.com>

* fix(persistence): normalize folder-update-info paths with forward slashes on Windows (#5381)

Signed-off-by: junkerderprovinz <jdp@braethoria.com>

* review: drop folder-PID change, trim storage_test comment (#5381)

Revert model/metadata/persistent_ids.go to master: switching the `folder`
PID attribute from filepath.Dir to path.Dir would change the persistent IDs
of existing Windows libraries and needs a migration path, so it is out of
scope for this PR. The matching test unskip is reverted with it, leaving
#TBD-path-sep-metadata open in #5381.

Trim the core/storage/storage_test.go comment to two lines.

Signed-off-by: junkerderprovinz <jdp@braethoria.com>

---------

Signed-off-by: junkerderprovinz <jdp@braethoria.com>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 core/common_test.go                   |  4 ++--
 core/storage/storage_test.go          | 10 ++++++----
 persistence/folder_repository_test.go |  5 -----
 server/nativeapi/translations_test.go |  5 ++---
 4 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/core/common_test.go b/core/common_test.go
index 0d6e3a299..f57ea8d38 100644
--- a/core/common_test.go
+++ b/core/common_test.go
@@ -2,6 +2,7 @@ package core
 
 import (
 	"context"
+	"path/filepath"
 
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -41,10 +42,9 @@ 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"))
+			Expect(abs).To(Equal(filepath.FromSlash("/library/root/music/file.mp3")))
 		})
 
 		It("returns the original path if library not found", func() {
diff --git a/core/storage/storage_test.go b/core/storage/storage_test.go
index 336b5a7a9..03904d086 100644
--- a/core/storage/storage_test.go
+++ b/core/storage/storage_test.go
@@ -7,7 +7,6 @@ import (
 	"runtime"
 	"testing"
 
-	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -56,13 +55,16 @@ var _ = Describe("Storage", func() {
 			Expect(s.(*fakeLocalStorage).u.Path).To(Equal("/tmp"))
 		})
 		It("should return a file implementation for a relative folder", func() {
-			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage)")
 			s, err := For("tmp")
 			Expect(err).ToNot(HaveOccurred())
 			cwd, _ := os.Getwd()
 			Expect(s).To(BeAssignableToTypeOf(&fakeLocalStorage{}))
-			Expect(s.(*fakeLocalStorage).u.Scheme).To(Equal("file"))
-			Expect(s.(*fakeLocalStorage).u.Path).To(Equal(filepath.Join(cwd, "tmp")))
+			u := s.(*fakeLocalStorage).u
+			Expect(u.Scheme).To(Equal("file"))
+			// On Windows the drive letter lands in u.Host, so re-join it with
+			// u.Path (as newLocalStorage does) to keep the assertion OS-independent.
+			got := filepath.Join(u.Host, filepath.FromSlash(u.Path))
+			Expect(got).To(Equal(filepath.Join(cwd, "tmp")))
 		})
 		It("should return error if schema is unregistered", func() {
 			_, err := For("webdav:///tmp")
diff --git a/persistence/folder_repository_test.go b/persistence/folder_repository_test.go
index b429cecb9..545d8ad49 100644
--- a/persistence/folder_repository_test.go
+++ b/persistence/folder_repository_test.go
@@ -8,7 +8,6 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
-	"github.com/navidrome/navidrome/tests"
 	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -137,7 +136,6 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("includes all child folders when querying parent", func() {
-				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create a parent folder with multiple children
 				parent := model.NewFolder(testLib, "TestParent/Music")
 				child1 := model.NewFolder(testLib, "TestParent/Music/Rock/Queen")
@@ -159,7 +157,6 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("excludes children from other libraries", func() {
-				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create parent in testLib
 				parent := model.NewFolder(testLib, "TestIsolation/Parent")
 				child := model.NewFolder(testLib, "TestIsolation/Parent/Child")
@@ -185,7 +182,6 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("excludes missing children when querying parent", func() {
-				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create parent and children, mark one as missing
 				parent := model.NewFolder(testLib, "TestMissingChild/Parent")
 				child1 := model.NewFolder(testLib, "TestMissingChild/Parent/Child1")
@@ -206,7 +202,6 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("handles mix of existing and non-existing target paths", func() {
-				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create folders for one path but not the other
 				existingParent := model.NewFolder(testLib, "TestMixed/Exists")
 				existingChild := model.NewFolder(testLib, "TestMixed/Exists/Child")
diff --git a/server/nativeapi/translations_test.go b/server/nativeapi/translations_test.go
index 77c088f6f..1c641da77 100644
--- a/server/nativeapi/translations_test.go
+++ b/server/nativeapi/translations_test.go
@@ -5,12 +5,12 @@ import (
 	"io"
 	"io/fs"
 	"os"
+	"path"
 	"path/filepath"
 	"testing/fstest"
 
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/resources"
-	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -18,13 +18,12 @@ import (
 var _ = Describe("Translations", func() {
 	Describe("I18n files", func() {
 		It("contains only valid json language files", func() {
-			tests.SkipOnWindows("path separator bug (#TBD-path-sep-nativeapi)")
 			fsys := resources.FS()
 			dir, _ := fsys.Open(consts.I18nFolder)
 			files, _ := dir.(fs.ReadDirFile).ReadDir(-1)
 			for _, f := range files {
 				name := filepath.Base(f.Name())
-				filePath := filepath.Join(consts.I18nFolder, name)
+				filePath := path.Join(consts.I18nFolder, name)
 				file, _ := fsys.Open(filePath)
 				data, _ := io.ReadAll(file)
 				var out map[string]any

From dff9e47c2ea53e040ddac2fcc36f4563e53053be Mon Sep 17 00:00:00 2001
From: Junker der Provinz <133605895+junkerderprovinz@users.noreply.github.com>
Date: Wed, 19 Aug 2026 19:11:00 +0200
Subject: [PATCH 057/200] fix(scanner): detect in-place playlist edits via the
 folder content hash (#5914)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(scanner): detect in-place playlist edits via the folder content hash

Signed-off-by: junkerderprovinz <jdp@braethoria.com>

* docs(scanner): clarify the playlist entries in the folder hash

Shorten the comment on the playlist loop, and record why the playlist count
stays in the hash header: it is redundant with the loop for change detection,
but removing it changes the hashed byte stream for every folder, including
folders without playlists, which would mark every folder outdated on the first
scan after upgrade.

Signed-off-by: junkerderprovinz <jdp@braethoria.com>

* test(scanner): pin filename and size into the playlist hash assertions

The playlist size test called time.Now() twice, so the modtime differed too
and carried the assertion — dropping info.Size() from the hash left the suite
green. It now shares one baseTime. A new rename test swaps the map key with
count, size and modtime held constant, so dropping the filename from the hash
fails. Both mutations were verified to fail before this change and pass after.

---------

Signed-off-by: junkerderprovinz <jdp@braethoria.com>
Co-authored-by: Deluan <deluan@navidrome.org>
---
 scanner/folder_entry.go      | 22 +++++++---
 scanner/folder_entry_test.go | 80 ++++++++++++++++++++++++++++++++----
 scanner/phase_1_folders.go   |  4 +-
 scanner/walk_dir_tree.go     |  4 +-
 4 files changed, 93 insertions(+), 17 deletions(-)

diff --git a/scanner/folder_entry.go b/scanner/folder_entry.go
index 0e893d6e6..e7eef223c 100644
--- a/scanner/folder_entry.go
+++ b/scanner/folder_entry.go
@@ -23,6 +23,7 @@ func newFolderEntry(job *scanJob, id, path string, info model.FolderUpdateInfo)
 		path:                path,
 		audioFiles:          make(map[string]fs.DirEntry),
 		imageFiles:          make(map[string]fs.DirEntry),
+		playlistFiles:       make(map[string]fs.DirEntry),
 		albumIDMap:          make(map[string]string),
 		updTime:             info.UpdatedAt,
 		prevHash:            info.Hash,
@@ -41,7 +42,7 @@ type folderEntry struct {
 	updTime         time.Time // from DB
 	audioFiles      map[string]fs.DirEntry
 	imageFiles      map[string]fs.DirEntry
-	numPlaylists    int
+	playlistFiles   map[string]fs.DirEntry
 	numSubFolders   int
 	imagesUpdatedAt time.Time
 	prevHash        string // Previous hash from DB
@@ -57,7 +58,7 @@ type folderEntry struct {
 }
 
 func (f *folderEntry) hasNoFiles() bool {
-	return len(f.audioFiles) == 0 && len(f.imageFiles) == 0 && f.numPlaylists == 0
+	return len(f.audioFiles) == 0 && len(f.imageFiles) == 0 && len(f.playlistFiles) == 0
 }
 
 func (f *folderEntry) isEmpty() bool {
@@ -94,7 +95,7 @@ func (f *folderEntry) toFolder() *model.Folder {
 	folder := model.NewFolder(f.job.lib, f.path)
 	folder.NumAudioFiles = len(f.audioFiles)
 	if playlists.InPath(*folder) {
-		folder.NumPlaylists = f.numPlaylists
+		folder.NumPlaylists = len(f.playlistFiles)
 	}
 	folder.ImageFiles = slices.Collect(maps.Keys(f.imageFiles))
 	folder.ImagesUpdatedAt = f.imagesUpdatedAt
@@ -108,16 +109,18 @@ func (f *folderEntry) hash() string {
 		h,
 		"%s:%d:%d:%s",
 		f.modTime.UTC(),
-		f.numPlaylists,
+		len(f.playlistFiles), // redundant with the loop below, but dropping it re-hashes every folder
 		f.numSubFolders,
 		f.imagesUpdatedAt.UTC(),
 	)
 
-	// Sort the keys of audio and image files to ensure consistent hashing
+	// Sort the keys of audio, image and playlist files to ensure consistent hashing
 	audioKeys := slices.Collect(maps.Keys(f.audioFiles))
 	slices.Sort(audioKeys)
 	imageKeys := slices.Collect(maps.Keys(f.imageFiles))
 	slices.Sort(imageKeys)
+	playlistKeys := slices.Collect(maps.Keys(f.playlistFiles))
+	slices.Sort(playlistKeys)
 
 	// Include audio files with their size and modtime
 	for _, key := range audioKeys {
@@ -135,5 +138,14 @@ func (f *folderEntry) hash() string {
 		}
 	}
 
+	// Include playlist files, so a content edit is detected even when the folder's
+	// mtime is preserved (rsync -a) or the playlist is not the newest file.
+	for _, key := range playlistKeys {
+		_, _ = io.WriteString(h, key)
+		if info, err := f.playlistFiles[key].Info(); err == nil {
+			_, _ = fmt.Fprintf(h, ":%d:%s", info.Size(), info.ModTime().UTC().String())
+		}
+	}
+
 	return hex.EncodeToString(h.Sum(nil))
 }
diff --git a/scanner/folder_entry_test.go b/scanner/folder_entry_test.go
index e8e354b38..4493f9309 100644
--- a/scanner/folder_entry_test.go
+++ b/scanner/folder_entry_test.go
@@ -48,6 +48,7 @@ var _ = Describe("folder_entry", func() {
 			Expect(entry.path).To(Equal(path))
 			Expect(entry.audioFiles).To(BeEmpty())
 			Expect(entry.imageFiles).To(BeEmpty())
+			Expect(entry.playlistFiles).To(BeEmpty())
 			Expect(entry.albumIDMap).To(BeEmpty())
 			Expect(entry.updTime).To(Equal(updateInfo.UpdatedAt))
 			Expect(entry.prevHash).To(Equal(updateInfo.Hash))
@@ -95,7 +96,7 @@ var _ = Describe("folder_entry", func() {
 			})
 
 			It("returns false when folder has playlists", func() {
-				entry.numPlaylists = 1
+				entry.playlistFiles["list.m3u"] = &fakeDirEntry{name: "list.m3u"}
 				Expect(entry.hasNoFiles()).To(BeFalse())
 			})
 
@@ -107,7 +108,7 @@ var _ = Describe("folder_entry", func() {
 			It("returns false when folder has multiple types of content", func() {
 				entry.audioFiles["test.mp3"] = &fakeDirEntry{name: "test.mp3"}
 				entry.imageFiles["cover.jpg"] = &fakeDirEntry{name: "cover.jpg"}
-				entry.numPlaylists = 2
+				entry.playlistFiles["list.m3u"] = &fakeDirEntry{name: "list.m3u"}
 				entry.numSubFolders = 3
 				Expect(entry.hasNoFiles()).To(BeFalse())
 			})
@@ -149,7 +150,11 @@ var _ = Describe("folder_entry", func() {
 					"cover.jpg":  &fakeDirEntry{name: "cover.jpg"},
 					"folder.png": &fakeDirEntry{name: "folder.png"},
 				}
-				entry.numPlaylists = 3
+				entry.playlistFiles = map[string]fs.DirEntry{
+					"list1.m3u": &fakeDirEntry{name: "list1.m3u"},
+					"list2.m3u": &fakeDirEntry{name: "list2.m3u"},
+					"list3.m3u": &fakeDirEntry{name: "list3.m3u"},
+				}
 				entry.imagesUpdatedAt = time.Now()
 			})
 
@@ -200,7 +205,10 @@ var _ = Describe("folder_entry", func() {
 					"z.jpg": &fakeDirEntry{name: "z.jpg"},
 					"x.png": &fakeDirEntry{name: "x.png"},
 				}
-				entry.numPlaylists = 2
+				entry.playlistFiles = map[string]fs.DirEntry{
+					"q.m3u": &fakeDirEntry{name: "q.m3u"},
+					"p.m3u": &fakeDirEntry{name: "p.m3u"},
+				}
 				entry.numSubFolders = 3
 
 				hash1 := entry.hash()
@@ -214,6 +222,10 @@ var _ = Describe("folder_entry", func() {
 					"x.png": &fakeDirEntry{name: "x.png"},
 					"z.jpg": &fakeDirEntry{name: "z.jpg"},
 				}
+				entry.playlistFiles = map[string]fs.DirEntry{
+					"p.m3u": &fakeDirEntry{name: "p.m3u"},
+					"q.m3u": &fakeDirEntry{name: "q.m3u"},
+				}
 
 				hash2 := entry.hash()
 				Expect(hash1).To(Equal(hash2))
@@ -252,10 +264,10 @@ var _ = Describe("folder_entry", func() {
 				Expect(hash1).ToNot(Equal(hash2))
 			})
 
-			It("produces different hash when playlist count changes", func() {
+			It("produces different hash when playlist files change", func() {
 				hash1 := entry.hash()
 
-				entry.numPlaylists = 5
+				entry.playlistFiles["new.m3u"] = &fakeDirEntry{name: "new.m3u"}
 				hash2 := entry.hash()
 
 				Expect(hash1).ToNot(Equal(hash2))
@@ -377,6 +389,58 @@ var _ = Describe("folder_entry", func() {
 				Expect(hash1).ToNot(Equal(hash2))
 			})
 
+			It("produces different hash when playlist file size changes", func() {
+				baseTime := time.Now()
+				entry.playlistFiles["list.m3u"] = &fakeDirEntry{
+					name:     "list.m3u",
+					fileInfo: &fakeFileInfo{name: "list.m3u", size: 1000, modTime: baseTime},
+				}
+				hash1 := entry.hash()
+
+				entry.playlistFiles["list.m3u"] = &fakeDirEntry{
+					name:     "list.m3u",
+					fileInfo: &fakeFileInfo{name: "list.m3u", size: 2000, modTime: baseTime},
+				}
+				hash2 := entry.hash()
+
+				Expect(hash1).ToNot(Equal(hash2))
+			})
+
+			It("produces different hash when playlist file modification time changes", func() {
+				baseTime := time.Now()
+				entry.playlistFiles["list.m3u"] = &fakeDirEntry{
+					name:     "list.m3u",
+					fileInfo: &fakeFileInfo{name: "list.m3u", size: 1000, modTime: baseTime},
+				}
+				hash1 := entry.hash()
+
+				entry.playlistFiles["list.m3u"] = &fakeDirEntry{
+					name:     "list.m3u",
+					fileInfo: &fakeFileInfo{name: "list.m3u", size: 1000, modTime: baseTime.Add(1 * time.Hour)},
+				}
+				hash2 := entry.hash()
+
+				Expect(hash1).ToNot(Equal(hash2))
+			})
+
+			It("produces different hash when a playlist is renamed", func() {
+				baseTime := time.Now()
+				entry.playlistFiles["old.m3u"] = &fakeDirEntry{
+					name:     "old.m3u",
+					fileInfo: &fakeFileInfo{name: "old.m3u", size: 1000, modTime: baseTime},
+				}
+				hash1 := entry.hash()
+
+				delete(entry.playlistFiles, "old.m3u")
+				entry.playlistFiles["new.m3u"] = &fakeDirEntry{
+					name:     "new.m3u",
+					fileInfo: &fakeFileInfo{name: "new.m3u", size: 1000, modTime: baseTime},
+				}
+				hash2 := entry.hash()
+
+				Expect(hash1).ToNot(Equal(hash2))
+			})
+
 			It("produces valid hex-encoded hash", func() {
 				hash := entry.hash()
 				Expect(hash).To(HaveLen(32)) // MD5 hash should be 32 hex characters
@@ -421,7 +485,7 @@ var _ = Describe("folder_entry", func() {
 				})
 
 				It("returns true when hash has changed", func() {
-					entry.numPlaylists = 10 // Change something to change the hash
+					entry.playlistFiles["list.m3u"] = &fakeDirEntry{name: "list.m3u"} // Change something to change the hash
 					Expect(entry.isOutdated()).To(BeTrue())
 				})
 
@@ -445,7 +509,7 @@ var _ = Describe("folder_entry", func() {
 
 				It("returns true when full scan condition is not met but hash changed", func() {
 					entry.updTime = entry.job.lib.LastScanStartedAt.Add(1 * time.Hour)
-					entry.numPlaylists = 10 // Change hash
+					entry.playlistFiles["list.m3u"] = &fakeDirEntry{name: "list.m3u"} // Change hash
 					Expect(entry.isOutdated()).To(BeTrue())
 				})
 			})
diff --git a/scanner/phase_1_folders.go b/scanner/phase_1_folders.go
index 82e91d5ad..6107b3316 100644
--- a/scanner/phase_1_folders.go
+++ b/scanner/phase_1_folders.go
@@ -165,7 +165,7 @@ func (p *phaseFolders) producer() ppl.Producer[*folderEntry] {
 				log.Trace(p.ctx, "Scanner: Checking folder state", " folder", folder.path, "_updTime", folder.updTime,
 					"_modTime", folder.modTime, "_lastScanStartedAt", folder.job.lib.LastScanStartedAt,
 					"numAudioFiles", len(folder.audioFiles), "numImageFiles", len(folder.imageFiles),
-					"numPlaylists", folder.numPlaylists, "numSubfolders", folder.numSubFolders)
+					"numPlaylists", len(folder.playlistFiles), "numSubfolders", folder.numSubFolders)
 
 				// Check if folder is outdated
 				if folder.isOutdated() {
@@ -492,7 +492,7 @@ func (p *phaseFolders) logFolder(entry *folderEntry) (*folderEntry, error) {
 		logCall = log.Trace
 	}
 	logCall(p.ctx, "Scanner: Completed processing folder",
-		"audioCount", len(entry.audioFiles), "imageCount", len(entry.imageFiles), "plsCount", entry.numPlaylists,
+		"audioCount", len(entry.audioFiles), "imageCount", len(entry.imageFiles), "plsCount", len(entry.playlistFiles),
 		"elapsed", entry.elapsed.Elapsed(), "tracksMissing", len(entry.missingTracks),
 		"tracksImported", len(entry.tracks), "library", entry.job.lib.Name, consts.Zwsp+"folder", entry.path)
 	return entry, nil
diff --git a/scanner/walk_dir_tree.go b/scanner/walk_dir_tree.go
index 887344b1b..20f6d4213 100644
--- a/scanner/walk_dir_tree.go
+++ b/scanner/walk_dir_tree.go
@@ -82,7 +82,7 @@ func walkFolder(ctx context.Context, job *scanJob, currentFolder string, checker
 
 	dir := path.Clean(currentFolder)
 	log.Trace(ctx, "Scanner: Found directory", " path", dir, "audioFiles", maps.Keys(folder.audioFiles),
-		"images", maps.Keys(folder.imageFiles), "playlists", folder.numPlaylists, "imagesUpdatedAt", folder.imagesUpdatedAt,
+		"images", maps.Keys(folder.imageFiles), "playlists", len(folder.playlistFiles), "imagesUpdatedAt", folder.imagesUpdatedAt,
 		"updTime", folder.updTime, "modTime", folder.modTime, "numChildren", len(children))
 	folder.path = dir
 	folder.elapsed.Start()
@@ -157,7 +157,7 @@ func loadDir(ctx context.Context, job *scanJob, dirPath string, checker *IgnoreC
 			case model.IsAudioFile(name):
 				folder.audioFiles[entry.Name()] = entry
 			case model.IsValidPlaylist(name):
-				folder.numPlaylists++
+				folder.playlistFiles[entry.Name()] = entry
 			case model.IsImageFile(name):
 				folder.imageFiles[entry.Name()] = entry
 				folder.imagesUpdatedAt = utils.TimeNewest(folder.imagesUpdatedAt, fileInfo.ModTime(), folder.modTime)

From fd4b3256e4c3e2c6eeeb90c2e3034149b536f873 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 19 Aug 2026 16:20:38 -0400
Subject: [PATCH 058/200] perf(artwork): compute the blurhash DCT separably
 (#5989)

The cosine basis factors into cosX[i][x] * cosY[j][y], so the pixel loop
does not need to visit every (i,j) pair. Each row now collapses to xComp
dot products, folded over yComp once per row: w*h*xComp + h*xComp*yComp
multiply-accumulates instead of w*h*xComp*yComp.

Encoding is ~60% faster at every input size, and ~80% faster at the 128px
size the artwork pipeline actually feeds it (263us -> 53us). Hashes are
byte-identical, so the existing golden-value specs cover the rewrite.
---
 core/artwork/blurhash/blurhash.go | 35 +++++++++++++++++++++++--------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/core/artwork/blurhash/blurhash.go b/core/artwork/blurhash/blurhash.go
index ca5bf7026..29e1ccfda 100644
--- a/core/artwork/blurhash/blurhash.go
+++ b/core/artwork/blurhash/blurhash.go
@@ -52,6 +52,12 @@ func Encode(img image.Image) (string, error) {
 
 	lin := srgbToLinearTable()
 	factors := make([][3]float64, xComp*yComp)
+	linR := make([]float64, w)
+	linG := make([]float64, w)
+	linB := make([]float64, w)
+	rowR := make([]float64, xComp)
+	rowG := make([]float64, xComp)
+	rowB := make([]float64, xComp)
 	for y := range h {
 		row := src.pix[y*src.stride:]
 		for x := range w {
@@ -60,15 +66,26 @@ func Encode(img image.Image) (string, error) {
 			if src.straight {
 				r, g, b = premultiply(r, g, b, row[p+3])
 			}
-			lr, lg, lb := lin[r], lin[g], lin[b]
-			for j := range yComp {
-				for i := range xComp {
-					basis := cosX[i][x] * cosY[j][y]
-					f := &factors[j*xComp+i]
-					f[0] += basis * lr
-					f[1] += basis * lg
-					f[2] += basis * lb
-				}
+			linR[x], linG[x], linB[x] = lin[r], lin[g], lin[b]
+		}
+		// The basis is separable, so a row costs xComp dot products plus one fold over yComp,
+		// rather than xComp*yComp multiply-accumulates per pixel.
+		for i := range xComp {
+			var sr, sg, sb float64
+			for x, c := range cosX[i] {
+				sr += c * linR[x]
+				sg += c * linG[x]
+				sb += c * linB[x]
+			}
+			rowR[i], rowG[i], rowB[i] = sr, sg, sb
+		}
+		for j := range yComp {
+			cy := cosY[j][y]
+			for i := range xComp {
+				f := &factors[j*xComp+i]
+				f[0] += cy * rowR[i]
+				f[1] += cy * rowG[i]
+				f[2] += cy * rowB[i]
 			}
 		}
 	}

From 881073c1833e66c47839927dc3c1577e39471c25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 19 Aug 2026 16:25:12 -0400
Subject: [PATCH 059/200] feat(cli): let artwork explain/refresh accept an id
 without its kind (#5988)

* feat(cmd): make artwork explain/refresh accept an id without its kind

The kind can now come from the id itself: a full artwork id (al-<id>)
carries it in the prefix, and a bare id is resolved across tables via
GetEntityByID. The explicit <kind> <id> leader still works.

* fix(cmd): keep refreshing resolvable ids when others fail to resolve

resolveArtworkTargets now collects a self-describing id it cannot resolve
as a failure instead of aborting, so refresh reports and skips the bad ones
and still queues the rest, matching refreshItems per-item behavior. explain
stays strict and rejects any unresolved input.
---
 cmd/artwork.go           | 110 +++++++++++++++++++++++++++++++--------
 cmd/artwork_test.go      |  83 ++++++++++++++++++++++++++---
 model/get_entity.go      |  37 +++++++++----
 model/get_entity_test.go |  22 ++++++++
 4 files changed, 212 insertions(+), 40 deletions(-)

diff --git a/cmd/artwork.go b/cmd/artwork.go
index e9c910f11..aeaec0e43 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -59,31 +59,27 @@ var artworkCmd = &cobra.Command{
 }
 
 var artworkExplainCmd = &cobra.Command{
-	Use:   "explain <kind> <id>",
+	Use:   "explain [<kind>] <id>",
 	Short: "Explain why an item's artwork resolved the way it did",
 	Long: "Explain why an item's artwork resolved the way it did.\n\n" +
+		"The item can be given as a bare id, a full artwork id (e.g. al-<id>), or a <kind> <id> pair.\n" +
 		"<kind> is one of: " + kindPrefixes(explainKinds) + ".\n" +
 		"A disc artwork id is the album id and the disc number, joined by a colon: <albumID>:2",
-	Args: cobra.ExactArgs(2),
+	Args: cobra.RangeArgs(1, 2),
 	Run: func(cmd *cobra.Command, args []string) {
-		kind, err := parseArtworkKind(args[0], explainKinds)
-		if err != nil {
-			log.Fatal(cmd.Context(), err)
-		}
-		runExplain(cmd.Context(), kind, args[1])
+		runExplain(cmd.Context(), args)
 	},
 }
 
 var artworkRefreshCmd = &cobra.Command{
-	Use:   "refresh <kind> <id>...",
+	Use:   "refresh [<kind>] <id>...",
 	Short: "Clear an item's artwork state and re-resolve it",
-	Args:  cobra.MinimumNArgs(2),
+	Long: "Clear an item's artwork state and re-resolve it.\n\n" +
+		"Each item can be given as a bare id, a full artwork id (e.g. al-<id>), or a shared\n" +
+		"<kind> <id>... leader. <kind> is one of: " + kindPrefixes(artwork.RefreshableKinds) + ".",
+	Args: cobra.MinimumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
-		kind, err := parseArtworkKind(args[0], artwork.RefreshableKinds)
-		if err != nil {
-			log.Fatal(cmd.Context(), err)
-		}
-		runRefresh(cmd.Context(), kind, args[1:])
+		runRefresh(cmd.Context(), args)
 	},
 }
 
@@ -499,19 +495,28 @@ func printReprocessPreview(out io.Writer, kinds []model.Kind, matched []int64, t
 	}
 }
 
-func runRefresh(ctx context.Context, kind model.Kind, ids []string) {
+func runRefresh(ctx context.Context, args []string) {
 	defer db.Init(ctx)()
 	ds, ctx := getAdminContext(ctx)
 
-	if failed := refreshItems(ctx, ds, kind, ids, os.Stdout); failed > 0 {
-		log.Fatal(ctx, "Failed to refresh artwork", "kind", kind, "failed", failed, "total", len(ids))
+	targets, failures, err := resolveArtworkTargets(ctx, ds, args, artwork.RefreshableKinds)
+	if err != nil {
+		log.Fatal(ctx, err)
+	}
+	for _, f := range failures {
+		log.Error(ctx, "Skipping unresolved item", f)
+	}
+	failed := refreshItems(ctx, ds, targets, os.Stdout) + len(failures)
+	if failed > 0 {
+		log.Fatal(ctx, "Failed to refresh artwork", "failed", failed, "total", len(targets)+len(failures))
 	}
 }
 
-// refreshItems keeps going after a failure — the ids are independent — and returns how many failed.
-func refreshItems(ctx context.Context, ds model.DataStore, kind model.Kind, ids []string, out io.Writer) int {
+// refreshItems keeps going after a failure — the items are independent — and returns how many failed.
+func refreshItems(ctx context.Context, ds model.DataStore, targets []model.ArtworkID, out io.Writer) int {
 	var failed int
-	for _, id := range ids {
+	for _, t := range targets {
+		kind, id := t.Kind, t.ID
 		// artwork.Refresh would happily queue an id that does not exist, orphaning a queue row.
 		if _, err := artworkItemName(ctx, ds, kind, id); err != nil {
 			log.Error(ctx, "Item not found", "kind", kind, "id", id, err)
@@ -544,7 +549,56 @@ func parseArtworkKind(s string, valid []model.Kind) (model.Kind, error) {
 	if ok && slices.Contains(valid, kind) {
 		return kind, nil
 	}
-	return kind, fmt.Errorf("invalid kind %q, expected one of: %s", s, kindPrefixes(valid))
+	return kind, invalidKindErr(s, valid)
+}
+
+func invalidKindErr(s string, valid []model.Kind) error {
+	return fmt.Errorf("invalid kind %q, expected one of: %s", s, kindPrefixes(valid))
+}
+
+// resolveArtworkTargets resolves explain/refresh positional args into artwork ids, accepting a
+// shared "<kind> <id>..." leader or self-describing args (a bare id, or a full artwork id). A
+// self-describing arg that cannot be resolved is returned as a failure rather than aborting the
+// batch, so refresh can process the resolvable ids; a malformed <kind> leader is a usage error.
+func resolveArtworkTargets(ctx context.Context, ds model.DataStore, args []string, valid []model.Kind) ([]model.ArtworkID, []error, error) {
+	if kind, ok := model.ParseKind(args[0]); ok && len(args) > 1 {
+		if !slices.Contains(valid, kind) {
+			return nil, nil, invalidKindErr(args[0], valid)
+		}
+		return slice.Map(args[1:], func(id string) model.ArtworkID {
+			return model.ArtworkID{Kind: kind, ID: id}
+		}), nil, nil
+	}
+	var targets []model.ArtworkID
+	var failures []error
+	for _, arg := range args {
+		target, err := artworkKindAndID(ctx, ds, arg)
+		if err == nil && !slices.Contains(valid, target.Kind) {
+			err = invalidKindErr(target.Kind.Prefix(), valid)
+		}
+		if err != nil {
+			failures = append(failures, err)
+			continue
+		}
+		targets = append(targets, target)
+	}
+	return targets, failures, nil
+}
+
+// artworkKindAndID resolves one self-describing argument: a full artwork id (al-<id>) takes its kind
+// from the prefix, a bare id is looked up. Entity ids never start with "<kind>-", so no collision.
+func artworkKindAndID(ctx context.Context, ds model.DataStore, arg string) (model.ArtworkID, error) {
+	if artID, err := model.ParseArtworkID(arg); err == nil && artID.ID != "" {
+		return model.ArtworkID{Kind: artID.Kind, ID: artID.ID}, nil
+	}
+	kind, err := model.GetEntityKindByID(ctx, ds, arg)
+	if errors.Is(err, model.ErrNotFound) {
+		return model.ArtworkID{}, fmt.Errorf("could not determine kind for %q; pass an explicit <kind>", arg)
+	}
+	if err != nil {
+		return model.ArtworkID{}, err
+	}
+	return model.ArtworkID{Kind: kind, ID: arg}, nil
 }
 
 // explainAgents accounts for every configured agent: one the CLI cannot construct (a plugin, or a
@@ -721,10 +775,22 @@ func formatTime(t time.Time) string {
 	return t.Format(time.RFC3339)
 }
 
-func runExplain(ctx context.Context, kind model.Kind, id string) {
+func runExplain(ctx context.Context, args []string) {
 	defer db.Init(ctx)()
 	ds, ctx := getAdminContext(ctx)
 
+	targets, failures, err := resolveArtworkTargets(ctx, ds, args, explainKinds)
+	if err != nil {
+		log.Fatal(ctx, err)
+	}
+	if len(failures) > 0 {
+		log.Fatal(ctx, failures[0])
+	}
+	if len(targets) != 1 {
+		log.Fatal(ctx, "explain takes a single item; pass one id or a <kind> <id> pair")
+	}
+	kind, id := targets[0].Kind, targets[0].ID
+
 	name, err := artworkItemName(ctx, ds, kind, id)
 	if err != nil {
 		log.Fatal(ctx, "Item not found", "kind", kind, "id", id, err)
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index b28d8dac5..8b50ba775 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -54,6 +54,74 @@ var _ = Describe("parseArtworkKind", func() {
 	})
 })
 
+var _ = Describe("resolveArtworkTargets", func() {
+	var ds *tests.MockDataStore
+	ctx := context.Background()
+
+	BeforeEach(func() {
+		artists := tests.CreateMockArtistRepo()
+		artists.SetData(model.Artists{{ID: "artist1"}})
+		ds = &tests.MockDataStore{MockedArtist: artists}
+	})
+
+	It("accepts the explicit <kind> <id> leader shared by every id", func() {
+		targets, failures, err := resolveArtworkTargets(ctx, ds, []string{"al", "x", "y"}, explainKinds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(failures).To(BeEmpty())
+		Expect(targets).To(Equal([]model.ArtworkID{
+			{Kind: model.KindAlbumArtwork, ID: "x"}, {Kind: model.KindAlbumArtwork, ID: "y"}}))
+	})
+
+	It("rejects an explicit kind the command does not accept as a usage error", func() {
+		_, _, err := resolveArtworkTargets(ctx, ds, []string{"dc", "x"}, artwork.RefreshableKinds)
+		Expect(err).To(MatchError(ContainSubstring("invalid kind")))
+	})
+
+	It("resolves a bare id by looking it up across tables", func() {
+		targets, failures, err := resolveArtworkTargets(ctx, ds, []string{"artist1"}, explainKinds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(failures).To(BeEmpty())
+		Expect(targets).To(Equal([]model.ArtworkID{{Kind: model.KindArtistArtwork, ID: "artist1"}}))
+	})
+
+	It("reads the kind from a full artwork id prefix without a database lookup", func() {
+		targets, _, err := resolveArtworkTargets(ctx, ds, []string{"al-realalbum"}, explainKinds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(targets).To(Equal([]model.ArtworkID{{Kind: model.KindAlbumArtwork, ID: "realalbum"}}))
+	})
+
+	It("strips the hash suffix from a full artwork id", func() {
+		targets, _, err := resolveArtworkTargets(ctx, ds, []string{"al-realalbum_0123456789abcdef"}, explainKinds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(targets).To(Equal([]model.ArtworkID{{Kind: model.KindAlbumArtwork, ID: "realalbum"}}))
+	})
+
+	It("collects a self-describing arg whose kind the command does not accept", func() {
+		targets, failures, err := resolveArtworkTargets(ctx, ds, []string{"dc-realalbum:2"}, artwork.RefreshableKinds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(targets).To(BeEmpty())
+		Expect(failures).To(HaveLen(1))
+		Expect(failures[0]).To(MatchError(ContainSubstring("invalid kind")))
+	})
+
+	It("collects an id that matches nothing and has no kind prefix", func() {
+		targets, failures, err := resolveArtworkTargets(ctx, ds, []string{"nope"}, explainKinds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(targets).To(BeEmpty())
+		Expect(failures).To(HaveLen(1))
+		Expect(failures[0]).To(MatchError(ContainSubstring("could not determine kind")))
+	})
+
+	It("resolves the valid ids and collects the unresolvable ones", func() {
+		targets, failures, err := resolveArtworkTargets(ctx, ds, []string{"artist1", "nope", "al-realalbum"}, explainKinds)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(targets).To(Equal([]model.ArtworkID{
+			{Kind: model.KindArtistArtwork, ID: "artist1"}, {Kind: model.KindAlbumArtwork, ID: "realalbum"}}))
+		Expect(failures).To(HaveLen(1))
+		Expect(failures[0]).To(MatchError(ContainSubstring("could not determine kind")))
+	})
+})
+
 var _ = Describe("explainResult", func() {
 	It("reports the winning source", func() {
 		steps := []artwork.TraceStep{{Candidate: "folder", Outcome: "hit", Detail: "/music/a.jpg"}}
@@ -337,10 +405,10 @@ var _ = Describe("discArtworkName", func() {
 })
 
 var _ = Describe("artwork refresh command", func() {
-	It("requires at least a kind and one id", func() {
-		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar"})).To(HaveOccurred())
+	It("requires at least one argument", func() {
+		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{})).To(HaveOccurred())
+		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"id1"})).ToNot(HaveOccurred())
 		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar", "id1"})).ToNot(HaveOccurred())
-		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar", "id1", "id2"})).ToNot(HaveOccurred())
 	})
 })
 
@@ -873,7 +941,8 @@ var _ = Describe("refreshItems", func() {
 		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: model.KindAlbumArtwork.Prefix(),
 			ItemID: "al-1", ImageType: model.ImageTypePrimary, Hash: "abc123"})).To(Succeed())
 
-		Expect(refreshItems(ctx, ds, model.KindAlbumArtwork, []string{"al-1", "al-3"}, &out)).To(BeZero())
+		Expect(refreshItems(ctx, ds, []model.ArtworkID{
+			{Kind: model.KindAlbumArtwork, ID: "al-1"}, {Kind: model.KindAlbumArtwork, ID: "al-3"}}, &out)).To(BeZero())
 
 		_, err := art.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
@@ -884,7 +953,7 @@ var _ = Describe("refreshItems", func() {
 	})
 
 	It("skips an id that does not exist instead of queuing it", func() {
-		Expect(refreshItems(ctx, ds, model.KindAlbumArtwork, []string{"al-2"}, &out)).To(Equal(1))
+		Expect(refreshItems(ctx, ds, []model.ArtworkID{{Kind: model.KindAlbumArtwork, ID: "al-2"}}, &out)).To(Equal(1))
 
 		_, err := queue.Get(model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound), "a typo must not leave an orphan queue row")
@@ -892,8 +961,8 @@ var _ = Describe("refreshItems", func() {
 	})
 
 	It("continues past a failing id and counts the failures", func() {
-		Expect(refreshItems(ctx, ds, model.KindAlbumArtwork,
-			[]string{"al-1", "al-2", "al-3"}, &out)).To(Equal(1))
+		Expect(refreshItems(ctx, ds, []model.ArtworkID{{Kind: model.KindAlbumArtwork, ID: "al-1"},
+			{Kind: model.KindAlbumArtwork, ID: "al-2"}, {Kind: model.KindAlbumArtwork, ID: "al-3"}}, &out)).To(Equal(1))
 
 		Expect(out.String()).To(Equal("al/al-1: queued\nal/al-3: queued\n"),
 			"the ids after a failure are still refreshed")
diff --git a/model/get_entity.go b/model/get_entity.go
index 3e1a78d1d..e5d41f1be 100644
--- a/model/get_entity.go
+++ b/model/get_entity.go
@@ -7,21 +7,36 @@ import (
 
 // TODO: Should the type be encoded in the ID?
 func GetEntityByID(ctx context.Context, ds DataStore, id string) (any, error) {
-	getters := []func() (any, error){
-		func() (any, error) { return ds.Artist(ctx).Get(id) },
-		func() (any, error) { return ds.Album(ctx).Get(id) },
-		func() (any, error) { return ds.Playlist(ctx).Get(id) },
-		func() (any, error) { return ds.MediaFile(ctx).Get(id) },
-		func() (any, error) { return ds.Radio(ctx).Get(id) },
+	entity, _, err := getEntity(ctx, ds, id)
+	return entity, err
+}
+
+// GetEntityKindByID resolves a bare entity id to its artwork Kind, searching the same tables as
+// GetEntityByID. It reports ErrNotFound when no entity owns the id.
+func GetEntityKindByID(ctx context.Context, ds DataStore, id string) (Kind, error) {
+	_, kind, err := getEntity(ctx, ds, id)
+	return kind, err
+}
+
+func getEntity(ctx context.Context, ds DataStore, id string) (any, Kind, error) {
+	getters := []struct {
+		kind Kind
+		get  func() (any, error)
+	}{
+		{KindArtistArtwork, func() (any, error) { return ds.Artist(ctx).Get(id) }},
+		{KindAlbumArtwork, func() (any, error) { return ds.Album(ctx).Get(id) }},
+		{KindPlaylistArtwork, func() (any, error) { return ds.Playlist(ctx).Get(id) }},
+		{KindMediaFileArtwork, func() (any, error) { return ds.MediaFile(ctx).Get(id) }},
+		{KindRadioArtwork, func() (any, error) { return ds.Radio(ctx).Get(id) }},
 	}
-	for _, get := range getters {
-		entity, err := get()
+	for _, g := range getters {
+		entity, err := g.get()
 		if err == nil {
-			return entity, nil
+			return entity, g.kind, nil
 		}
 		if !errors.Is(err, ErrNotFound) {
-			return nil, err
+			return nil, Kind{}, err
 		}
 	}
-	return nil, ErrNotFound
+	return nil, Kind{}, ErrNotFound
 }
diff --git a/model/get_entity_test.go b/model/get_entity_test.go
index f8a4c9e8e..4e589406a 100644
--- a/model/get_entity_test.go
+++ b/model/get_entity_test.go
@@ -38,3 +38,25 @@ var _ = Describe("GetEntityByID", func() {
 		Expect(err).ToNot(MatchError(model.ErrNotFound))
 	})
 })
+
+var _ = Describe("GetEntityKindByID", func() {
+	var ds *tests.MockDataStore
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ds = &tests.MockDataStore{}
+		ctx = GinkgoT().Context()
+	})
+
+	It("returns the artwork kind for the matching id", func() {
+		ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1"}})
+		kind, err := model.GetEntityKindByID(ctx, ds, "a1")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(kind).To(Equal(model.KindAlbumArtwork))
+	})
+
+	It("returns ErrNotFound when no entity matches", func() {
+		_, err := model.GetEntityKindByID(ctx, ds, "missing")
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+})

From 3d3c3ed60186deb95461cd80b052e564fb9d2055 Mon Sep 17 00:00:00 2001
From: Daniel Barrientos Anariba
 <69573860+danielbanariba@users.noreply.github.com>
Date: Thu, 20 Aug 2026 06:53:11 -0600
Subject: [PATCH 060/200] ci: lint with the golangci-lint version the Makefile
 declares (#5994)

* ci: lint with the golangci-lint version the Makefile declares

The workflow asked for `version: latest` while the Makefile pins
`GOLANGCI_LINT_VERSION ?= v2.12.0`, so `make lint` and CI ran different
linters. golangci-lint v2.13.0 started reporting G404 on three existing
`rand.Shuffle` calls, which turned every PR red without a line of Go
changing.

Read the version from the Makefile instead of resolving `latest`, so the
two stay in step and a new release cannot break unchanged code.

* chore: re-run CI
---
 .github/workflows/pipeline.yml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index 8e6e8126a..b91c19505 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -68,10 +68,16 @@ jobs:
         with:
           go-version-file: go.mod
 
+      # Keep CI on the same version `make lint` installs, so a clean local run
+      # cannot turn red in CI just because a new golangci-lint was released.
+      - name: Resolve golangci-lint version
+        id: golangci-version
+        run: echo "version=$(grep '^GOLANGCI_LINT_VERSION' Makefile | cut -d ' ' -f 3)" >> "$GITHUB_OUTPUT"
+
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v9
         with:
-          version: latest
+          version: ${{ steps.golangci-version.outputs.version }}
           problem-matchers: true
           args: --timeout 2m
 

From fc1c1366dcfb18c6ac885fe271d04ec6fede8c2e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 20 Aug 2026 09:04:09 -0400
Subject: [PATCH 061/200] fix(cli): write `pls -p` playlist output to stdout
 (#5996)

The export path used the `println` builtin, which writes to stderr, so
`navidrome pls -p X > playlist.m3u8` produced an empty file while the M3U
body was interleaved with the startup logs on stderr.

`println` also appended a newline that `ToM3U8` already provides, so the
piped output had a stray trailing blank line that `-o file` did not. Both
destinations are now byte-identical.

The stdout/file choice moved into a `writePlaylist` helper shared by
`pls -p` and `pls export -p`, which both had the same bug. It takes the
destination as an `io.Writer`, matching the existing convention in
cmd/artwork.go.
---
 cmd/pls.go      | 17 ++++++++++-------
 cmd/pls_test.go | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 7 deletions(-)
 create mode 100644 cmd/pls_test.go

diff --git a/cmd/pls.go b/cmd/pls.go
index 184ca6fe7..93b411483 100644
--- a/cmd/pls.go
+++ b/cmd/pls.go
@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"strconv"
@@ -141,14 +142,16 @@ func findPlaylist(ctx context.Context, ds model.DataStore, nameOrID string) *mod
 func runExporter(ctx context.Context) {
 	ds, ctx := getAdminContext(ctx)
 	playlist := findPlaylist(ctx, ds, playlistID)
-	pls := playlist.ToM3U8()
-	if outputFile == "-" || outputFile == "" {
-		println(pls)
+	writePlaylist(playlist.ToM3U8(), os.Stdout, outputFile)
+}
+
+func writePlaylist(m3u string, out io.Writer, file string) {
+	if file == "" || file == "-" {
+		fmt.Fprint(out, m3u)
 		return
 	}
-	err := os.WriteFile(outputFile, []byte(pls), 0600)
-	if err != nil {
-		log.Fatal("Error writing to the output file", "file", outputFile, err)
+	if err := os.WriteFile(file, []byte(m3u), 0600); err != nil {
+		log.Fatal("Error writing to the output file", "file", file, err)
 	}
 }
 
@@ -157,7 +160,7 @@ func runExport(ctx context.Context) {
 
 	if playlistID != "" && outputFile == "" {
 		playlist := findPlaylist(ctx, ds, playlistID)
-		println(playlist.ToM3U8())
+		writePlaylist(playlist.ToM3U8(), os.Stdout, outputFile)
 		return
 	}
 
diff --git a/cmd/pls_test.go b/cmd/pls_test.go
new file mode 100644
index 000000000..f3e8c7edd
--- /dev/null
+++ b/cmd/pls_test.go
@@ -0,0 +1,35 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("writePlaylist", func() {
+	const m3u = "#EXTM3U\n#PLAYLIST:DJ Wave\n#EXTINF:364,Bel Canto - Dreaming Girl\n"
+	plsFile := filepath.Join(os.TempDir(), fmt.Sprintf("navidrome-pls-%d.m3u8", os.Getpid()))
+
+	BeforeEach(func() {
+		DeferCleanup(func() { _ = os.Remove(plsFile) })
+	})
+
+	DescribeTable("writes the playlist to exactly one destination",
+		func(file, wantStream, wantFile string) {
+			var out strings.Builder
+
+			writePlaylist(m3u, &out, file)
+
+			written, _ := os.ReadFile(plsFile)
+			Expect(out.String()).To(Equal(wantStream))
+			Expect(string(written)).To(Equal(wantFile))
+		},
+		Entry("no file name writes to the stream", "", m3u, ""),
+		Entry("a dash writes to the stream", "-", m3u, ""),
+		Entry("a path writes to the file", plsFile, "", m3u),
+	)
+})

From 17db7d40770bb30edffc675323e4329a9303288a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 20 Aug 2026 10:02:04 -0400
Subject: [PATCH 062/200] ci: pull base images through mirror.gcr.io instead of
 ECR Public (#5997)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI builds were failing at random with:

    buildx failed with: toomanyrequests: Rate exceeded

The 429 comes from public.ecr.aws, not Docker Hub. AWS caps unauthenticated
ECR Public pulls at 1 per second per source IP (authenticated: 10/s). The
build matrix starts 11 jobs at once and each resolves 4 base images, so
roughly 44 anonymous pulls land in a couple of seconds — from GitHub runner
IPs that are shared with every other GitHub customer.

Measured against public.ecr.aws with an anonymous token, 60 requests at
concurrency 30 returned 31x 429 in 0.48s.

The same probe against mirror.gcr.io (Google's Docker Hub pull-through
cache) returned zero errors: 750 manifest requests up to ~141 req/s, plus
120 layer blob requests at concurrency 60. Google publishes no rate limit
for it, so this is measured headroom, not a contract — but it is roughly
10x the pipeline's peak rate, and cached pulls do not count against Docker
Hub's limits either.

Authenticating to ECR Public was the alternative. It was rejected because
10 pulls/s is still under the ~44-pull burst, it needs an AWS account plus
a secret, and secrets never reach fork pull requests — so forks would keep
failing. The mirror fixes forks too.

Verified buildkit honours the mirror block by routing a build through a
local logging registry: all 6 requests (manifests and blobs) hit the mirror,
none went to Docker Hub directly. Confirmed mirror.gcr.io answers 200 for
buildkit's "?ns=docker.io" query form on all four images, for both GET and
HEAD. Confirmed buildkit falls back to Docker Hub when the mirror is
unreachable — the build still succeeds, but the resolve takes ~30s instead
of ~0.3s, so a mirror outage means slow builds, not broken ones. The
existing Docker Hub login covers that fallback on main-repo runs.

msitools.dockerfile is only used by the local `make docker-msi` target, but
is switched over too so no ECR Public reference is left behind.
---
 .github/actions/prepare-docker/action.yml |  5 +++++
 Dockerfile                                | 10 +++++-----
 release/wix/msitools.dockerfile           |  2 +-
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/.github/actions/prepare-docker/action.yml b/.github/actions/prepare-docker/action.yml
index b8cde4aaf..6cb54dbdb 100644
--- a/.github/actions/prepare-docker/action.yml
+++ b/.github/actions/prepare-docker/action.yml
@@ -68,6 +68,11 @@ runs:
     - name: Set up Docker Buildx
       id: buildx
       uses: docker/setup-buildx-action@v4
+      with:
+        # Runner IPs are shared, so anonymous base image pulls get rate-limited.
+        buildkitd-config-inline: |
+          [registry."docker.io"]
+            mirrors = ["mirror.gcr.io"]
 
     - name: Extract metadata for Docker image
       id: meta
diff --git a/Dockerfile b/Dockerfile
index df5df52ab..847c19bf7 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -2,7 +2,7 @@ FROM --platform=$BUILDPLATFORM ghcr.io/crazy-max/osxcross:14.5-debian AS osxcros
 
 ########################################################################################################################
 ### Build xx (original image: tonistiigi/xx)
-FROM --platform=$BUILDPLATFORM public.ecr.aws/docker/library/alpine:3.20 AS xx-build
+FROM --platform=$BUILDPLATFORM alpine:3.20 AS xx-build
 
 # v1.9.0
 ENV XX_VERSION=a5592eab7a57895e8d385394ff12241bc65ecd50
@@ -26,7 +26,7 @@ COPY --from=xx-build /out/ /usr/bin/
 
 ########################################################################################################################
 ### Build Navidrome UI
-FROM --platform=$BUILDPLATFORM public.ecr.aws/docker/library/node:lts-alpine AS ui
+FROM --platform=$BUILDPLATFORM node:lts-alpine AS ui
 WORKDIR /app
 
 # Install node dependencies
@@ -43,7 +43,7 @@ COPY --from=ui /build /build
 
 ########################################################################################################################
 ### 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
+FROM --platform=$BUILDPLATFORM golang:1.26-alpine AS build-alpine
 COPY --from=xx / /
 
 ARG TARGETPLATFORM
@@ -85,7 +85,7 @@ 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
+FROM --platform=$BUILDPLATFORM golang:1.26-trixie AS base
 RUN apt-get update && apt-get install -y clang lld
 COPY --from=xx / /
 WORKDIR /workspace
@@ -154,7 +154,7 @@ COPY --from=build /out /
 
 ########################################################################################################################
 ### Build Final Image
-FROM public.ecr.aws/docker/library/alpine:3.20 AS final
+FROM alpine:3.20 AS final
 LABEL maintainer="deluan@navidrome.org"
 LABEL org.opencontainers.image.source="https://github.com/navidrome/navidrome"
 
diff --git a/release/wix/msitools.dockerfile b/release/wix/msitools.dockerfile
index 38364eb47..90249c1ce 100644
--- a/release/wix/msitools.dockerfile
+++ b/release/wix/msitools.dockerfile
@@ -1,3 +1,3 @@
-FROM public.ecr.aws/docker/library/alpine
+FROM alpine
 RUN apk update && apk add jq msitools
 WORKDIR /workspace
\ No newline at end of file

From 0a55cc8cafdde9ab92aa0a207507dc2165ff1caf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 20 Aug 2026 22:48:26 -0400
Subject: [PATCH 063/200] docs(plugins): document how a metadata agent signals
 "not found" (#6001)

A MetadataAgent plugin reports "I have no data for this item" by returning an empty response
with a nil error. Any error it returns instead is treated as a plugin fault and retried with
backoff. That rule was not documented anywhere, so an author naturally returns an error for a
missing item, and Navidrome then retries every item the plugin's source does not cover.

This is not hypothetical: the artist-nfo-metadata plugin returned an error for every artist
without an artist.nfo, which kept those artists in the artwork retry queue for hours and
tripped the artwork circuit breaker for the plugin as a whole.

Document the rule on the capability interface, which ndpgen copies into the Go PDK, and in the
MetadataAgent section of the plugin README.
---
 plugins/README.md                        | 8 ++++++++
 plugins/capabilities/metadata_agent.go   | 3 +++
 plugins/pdk/go/metadata/metadata.go      | 3 +++
 plugins/pdk/go/metadata/metadata_stub.go | 3 +++
 4 files changed, 17 insertions(+)

diff --git a/plugins/README.md b/plugins/README.md
index b04e12bd9..7042b8c45 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -174,6 +174,14 @@ Capabilities define what your plugin can do. They're automatically detected base
 
 Provides artist and album metadata. All methods are **optional** — implement only the ones your data source supports.
 
+> **Returning "not found".** When you have no data for an item, return an empty response and no
+> error. In the Go PDK that is `return nil, nil`. Navidrome reads it as a definitive "not found"
+> and stops asking.
+>
+> Return an error only when the plugin itself failed, such as an unreachable API or a broken host
+> call. Navidrome retries failed calls with backoff. A plugin that errors on "no data" makes
+> Navidrome retry every item it has no data for.
+
 | Function                          | Input                      | Output                           | Description              |
 |-----------------------------------|----------------------------|----------------------------------|--------------------------|
 | `nd_get_artist_mbid`              | `{id, name}`               | `{mbid}`                         | Get MusicBrainz ID       |
diff --git a/plugins/capabilities/metadata_agent.go b/plugins/capabilities/metadata_agent.go
index f856562c6..72cb1622f 100644
--- a/plugins/capabilities/metadata_agent.go
+++ b/plugins/capabilities/metadata_agent.go
@@ -9,6 +9,9 @@ import "github.com/navidrome/navidrome/plugins/types"
 // Plugins implementing this capability can choose which methods to implement.
 // Each method is optional - plugins only need to provide the functionality they support.
 //
+// To say "no data for this item", return a nil response and a nil error. Return an error only when
+// the plugin itself failed, because Navidrome retries failed calls with backoff.
+//
 //nd:capability name=metadata
 type MetadataAgent interface {
 	// GetArtistMBID retrieves the MusicBrainz ID for an artist.
diff --git a/plugins/pdk/go/metadata/metadata.go b/plugins/pdk/go/metadata/metadata.go
index c561c2893..bb0ae9620 100644
--- a/plugins/pdk/go/metadata/metadata.go
+++ b/plugins/pdk/go/metadata/metadata.go
@@ -186,6 +186,9 @@ type TopSongsResponse struct {
 //
 // Plugins implementing this capability can choose which methods to implement.
 // Each method is optional - plugins only need to provide the functionality they support.
+//
+// To say "no data for this item", return a nil response and a nil error. Return an error only when
+// the plugin itself failed, because Navidrome retries failed calls with backoff.
 type Metadata interface{}
 
 // ArtistMBIDProvider provides the GetArtistMBID function.
diff --git a/plugins/pdk/go/metadata/metadata_stub.go b/plugins/pdk/go/metadata/metadata_stub.go
index e72cca103..572eba4da 100644
--- a/plugins/pdk/go/metadata/metadata_stub.go
+++ b/plugins/pdk/go/metadata/metadata_stub.go
@@ -184,6 +184,9 @@ type TopSongsResponse struct {
 //
 // Plugins implementing this capability can choose which methods to implement.
 // Each method is optional - plugins only need to provide the functionality they support.
+//
+// To say "no data for this item", return a nil response and a nil error. Return an error only when
+// the plugin itself failed, because Navidrome retries failed calls with backoff.
 type Metadata interface{}
 
 // ArtistMBIDProvider provides the GetArtistMBID function.

From c26f6f9e981dcdbf14a86120bcda5e3d0a3e74a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 21 Aug 2026 10:24:01 -0400
Subject: [PATCH 064/200] feat(artwork): store the resolution trace so `artwork
 explain` works offline (#5980)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(artwork): record the resolution trace so explain works without --live

The worker never attached a ChainTrace, so `artwork explain` had to re-walk the
priority chain at CLI time. That reconstruction could disagree with what actually
happened, and without --live it could not report the external tier at all.

The worker now traces every acquisition and stores it. `explain` reads the stored
trace by default and reports when it was recorded; --live re-walks and calls the
agents. Disc artwork keeps no row, so it always walks live.

A chain trace alone would have explained almost nothing about failures: six of the
seven ways an item can fail happen after the chain has already picked a winner. The
trace now covers those stages too, and has somewhere to live when they fail: the
retrying queue row carries the last failure, and the state row keeps it in
last_failure once the retry budget is spent and the queue row is deleted.

Measured on a copy of a 682MB / 43.6k-item library: +9.7MB (+1.4%). No row crosses
the WITHOUT ROWID overflow threshold, so list hydration is unchanged; only full
scans of item_artwork, which no request performs, read more pages.

* test(artwork): pin the give-up ordering that keeps a failure for unresolved items

recordGiveUp updates an existing row, and for a kind with a recheck path that row is
only created moments earlier by the absent settle. Recording before the settle would
lose the failure for every item that never resolved, with nothing to catch it.

* refactor(artwork): tighten the trace code after review

Four fixes worth taking:

The doc comments on ChainTrace and chainState.trace still said the worker never
attaches a trace and resolution stays allocation-free — the exact invariant this
branch reverses.

explain's report field meant both "the chain shown was walked just now" and "go out
for real", and was being passed to loadPluginAgents, which --live documents as the
only thing that may open external connections. Renamed to `walked` and restored
explainLive as the sole input to that decision.

A stored Detail is an error string on the failure paths, with no bound. The measured
"no row reaches the WITHOUT ROWID overflow limit" only holds while it is bounded, so
cap it at 200 runes.

offlineGate was a factory returning a constant closure; make it a plain gateFunc like
its sibling passthroughGate. Collapse five copies of the age-a-queue-row loop in the
worker tests into one helper.

* refactor(artwork): drop the offline explain walk, now that traces are stored

`artwork explain` reported the external tier without calling it, so a diagnostic
could not add load to a provider already rate-limiting us. Reading the stored trace
answers that better: it reports what the agents actually returned, not what would
be tried.

Nothing could reach the offline gate any more. It was installed only for a walk
with --live unset, which now happens for disc artwork alone, and disc rejects the
external candidate before any gate call. That made the gate, its sentinel error,
the would-try outcome and two of explain's verdicts unreachable.

Removes offlineGate, errOfflineSkipped, OutcomeWouldTry, the NewTracingResolver
live parameter and the CreateArtworkResolver argument threaded through wire.

Verified against a copy of a real library: disc artwork with "external" first in
DiscArtPriority and external services enabled still records the skip and issues no
agent call.

* fix(artwork): make explain's no-network guarantee structural, not incidental

Serving falls back disc -> album and track -> disc -> album. The resolver layer
explain uses has no such fallback today, so dropping the offline gate did not leak.
But the guarantee rested on which chains happen to lack an external tier, and the
serving layer already shows the fallback shape someone could mirror.

Without --live the tracing resolver is now built with no agents at all, so no chain
and no fallback added later can reach a provider. That is stronger than the gate it
replaces, which only intercepted the call.

The test pins it against exactly that regression: with the guard removed and the
serving fallback mirrored into resolveDisc, it fails.

* refactor(artwork): trim the trace plumbing

EncodeTrace was exported for nobody: only this package writes traces, and cmd reads
them. It becomes a ChainTrace method, which also drops the copy Steps made for a
caller that only wanted to serialize.

explain's report carried queuedSteps and failureSteps, both pure functions of the
queue and state rows already in the struct, which let a test set the two out of step
with each other. formatExplain derives them, as it already does for every other
display value.

The trace row format and its tabwriter empty-cell rule lived in two places, and the
"nothing was ever recorded" predicate in three.

* fix(artwork): clear the queue trace on a fresh re-enqueue

Enqueue's conflict clause reset attempts to 0 but left the new trace
column, so after a scan or refresh re-enqueued a previously-failed item
artwork explain showed "Attempts: 0" next to the prior lifecycle's
"Last attempt failed" trace. Clear trace in Enqueue (a fresh lifecycle
has no last attempt); EnqueuePreservingBackoff still keeps it.

* fix(artwork): treat a processing-stage error as indeterminate in explain

A read/hash/decode/store failure records an OutcomeError step and writes an
absent row, but explainResult only mapped external errors and unreadable
candidates to indeterminate, so the default verdict read "not resolved" —
presenting a processing failure as a definitive miss. The worker retries
these exactly as it retries an unreadable candidate, so classify any
OutcomeError as indeterminate too.

* fix(artwork): record a trace step when a chainless resolver faults

Playlist and radio resolvers walk no priority chain, so a fault (unreadable
upload/sidecar, or an m3u fetch error with no grid) returned localError/extError
without recording any trace step. The attempt then encoded [], leaving artwork
explain with an empty "Last attempt failed" and "Gave up after". Record a
fallback step in the faulted-no-image branch when nothing else did, and carry
the source label through resolveLocalFile so the step can name it.

* fix(artwork): trace the m3u failure at its source, not via the empty guard

A playlist's grid sampling records album-chain steps into the shared trace, so
the processor's empty-trace fallback no longer fires when the m3u remote image
fetch failed — the error that forced the retry was omitted from explain. Record
it where it happens, in resolvePlaylist's external step, as external:m3u.

* test(artwork): skip the chainless-fault spec on Windows

The spec provokes an open fault with a non-directory parent, but Windows maps
that to a not-exist error, so localError is never set and the item resolves
absent instead of failed. The sibling failed-on-unreadable-upload spec skips
Windows for the same class of reason.

* fix(artwork): don't label an absent empty-chain row as pre-tracing

explain reported "resolved before traces were recorded" for any stored row
with an empty chain, but an empty CoverArtPriority records a real, empty [] chain
and resolves absent. A recorded resolution that finds an image always records its
winning candidate, so only a row with a hash and no chain predates tracing; split
on the hash and report an absent empty chain plainly instead.

* fix(db): retimestamp the artwork trace migration after rebase

master merged a 2026-08-18 migration, so the original 2026-08-16 timestamp is now
older than the newest on the base branch and Goose would silently skip it on an
already-upgraded database. Bumped past it; the SQL is unchanged.

* fix(artwork): keep the m3u error detail in the trace

The m3u trace step recorded OutcomeError with no detail because resolveExternalStep
collapsed the gate's error to a bool, so explain showed only "external:m3u error -"
and could not tell a timeout from an HTTP error or an open breaker. Return the error
(normalizing not-found to nil so it stays a definitive miss, not a failure) and store
its message as the step detail; encodeSteps already bounds it.

* docs(artwork): note the give-up write relies on serial draining

recordGiveUp writes last_failure unconditionally; that is only correct because
the drain resolves each item serially, so no concurrent success can store artwork
between the write and the queue delete. Record the invariant at the call site.
---
 cmd/artwork.go                                | 108 ++++++++---
 cmd/artwork_test.go                           | 108 +++++++----
 core/artwork/agent_images.go                  |   6 +-
 core/artwork/artwork.go                       |  13 +-
 core/artwork/processor.go                     |  21 ++-
 core/artwork/processor_test.go                |  29 +++
 core/artwork/resolve.go                       |  26 ++-
 core/artwork/resolve_test.go                  |  31 ++++
 core/artwork/trace.go                         | 107 ++++++++---
 core/artwork/trace_test.go                    | 170 +++++++++++-------
 core/artwork/worker.go                        |  20 ++-
 core/artwork/worker_test.go                   |  95 ++++++++--
 ...260819204637_add_artwork_trace_columns.sql |   9 +
 model/artwork.go                              |  10 +-
 persistence/artwork_queue_repository.go       |  11 +-
 persistence/artwork_queue_repository_test.go  |  27 ++-
 persistence/artwork_repository.go             |  10 ++
 persistence/artwork_repository_test.go        |  45 +++++
 tests/mock_artwork_queue_repo.go              |   3 +-
 tests/mock_artwork_repo.go                    |  14 ++
 20 files changed, 662 insertions(+), 201 deletions(-)
 create mode 100644 db/migrations/20260819204637_add_artwork_trace_columns.sql

diff --git a/cmd/artwork.go b/cmd/artwork.go
index aeaec0e43..63f0d0917 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -36,8 +36,9 @@ var (
 
 func init() {
 	artworkExplainCmd.Flags().BoolVar(&explainLive, "live", false,
-		"perform real external lookups instead of reporting what would be tried; "+
-			"also initializes plugin agents, which may open external connections")
+		"walk the chain again now, performing real external lookups, instead of reporting the "+
+			"stored trace of the last resolution; also initializes plugin agents, which may open "+
+			"external connections")
 	artworkReprocessCmd.Flags().StringSliceVar(&reprocessKinds, "kind", nil,
 		"kinds to reprocess ("+kindPrefixes(artwork.RecheckKinds)+"); repeatable")
 	artworkReprocessCmd.Flags().StringSliceVar(&reprocessSources, "source", nil,
@@ -640,10 +641,6 @@ func explainResult(source string, steps []artwork.TraceStep) string {
 			if s.Outcome == artwork.OutcomeHit {
 				break
 			}
-			if s.Outcome == artwork.OutcomeWouldTry {
-				return "resolved from " + source +
-					" (offline: a higher-priority external candidate was not tried; re-run with --live)"
-			}
 			// An external winner discards the earlier error, so the resolver settles it with no retry.
 			if s.Outcome == artwork.OutcomeError && strings.HasPrefix(s.Candidate, artwork.ExternalPrefix) &&
 				!strings.HasPrefix(source, artwork.ExternalPrefix) {
@@ -655,14 +652,12 @@ func explainResult(source string, steps []artwork.TraceStep) string {
 	}
 	for _, s := range steps {
 		switch {
-		case s.Outcome == artwork.OutcomeWouldTry:
-			return "indeterminate (external agents not called; re-run with --live)"
 		case s.Outcome == artwork.OutcomeError && strings.HasPrefix(s.Candidate, artwork.ExternalPrefix):
 			return "indeterminate (an external lookup failed; the item may resolve on a later attempt)"
-		// The worker treats an unreadable local candidate exactly as it treats a failed external one:
-		// it retries instead of settling absent, so the verdict must not read as a clean miss.
-		case s.Outcome == artwork.OutcomeUnreadable:
-			return "indeterminate (a candidate exists but could not be read; the worker retries rather than settling absent)"
+		// A stage error or an unreadable candidate means a source was found but not processed; the
+		// worker retries rather than settling absent, so neither reads as a clean miss.
+		case s.Outcome == artwork.OutcomeError, s.Outcome == artwork.OutcomeUnreadable:
+			return "indeterminate (a candidate was found but could not be processed; the worker retries rather than settling absent)"
 		}
 	}
 	return "not resolved"
@@ -684,22 +679,55 @@ func explainConfig(kind model.Kind) (name, value string) {
 }
 
 type explainReport struct {
-	kind       model.Kind
-	id         string
-	name       string
-	stored     *model.ItemArtwork
-	queued     *model.ArtworkQueueItem
-	agents     string
+	kind   model.Kind
+	id     string
+	name   string
+	stored *model.ItemArtwork
+	queued *model.ArtworkQueueItem
+	agents string
+	// steps is the chain walk: recorded when the item was resolved, or performed just now when walked.
 	steps      []artwork.TraceStep
 	source     string
+	walked     bool
 	resolveErr error
 }
 
+// explainChainOrigin says whether the operator is reading history or a walk performed just now,
+// since the two can disagree after a config change.
+func explainChainOrigin(rep explainReport) string {
+	if rep.walked {
+		return "walked now"
+	}
+	if rep.stored != nil {
+		return "recorded " + formatTime(rep.stored.AttemptedAt)
+	}
+	return "not recorded"
+}
+
+// writeSteps prints the trace rows. An empty last cell would end tabwriter's column block and
+// break the alignment, so a missing detail is rendered as a dash.
+func writeSteps(w io.Writer, indent string, steps []artwork.TraceStep) {
+	for _, s := range steps {
+		fmt.Fprintf(w, "%s%s\t%s\t%s\n", indent, s.Candidate, s.Outcome, cmp.Or(s.Detail, "-"))
+	}
+}
+
+// writeStepTable prints a secondary trace, and nothing at all when there is none to show.
+func writeStepTable(w io.Writer, title string, steps []artwork.TraceStep) {
+	if len(steps) == 0 {
+		return
+	}
+	// No tab on the title: it closes the preceding column block, so these rows align among themselves.
+	fmt.Fprintf(w, "  %s:\n", title)
+	writeSteps(w, "    ", steps)
+}
+
 func formatExplain(rep explainReport) string {
 	var sb strings.Builder
 	w := newTabWriter(&sb)
 	explainable := artwork.Explainable(rep.kind)
 	stateful := artwork.KeepsState(rep.kind)
+	unrecorded := !rep.walked && rep.stored == nil
 
 	fmt.Fprintln(w, "Item")
 	fmt.Fprintf(w, "  Kind:\t%s (%s)\n", rep.kind, rep.kind.Prefix())
@@ -732,6 +760,12 @@ func formatExplain(rep explainReport) string {
 		fmt.Fprintf(w, "  Attempts:\t%d\n", rep.queued.Attempts)
 		fmt.Fprintf(w, "  Retry at:\t%s\n", formatTime(rep.queued.RetryAt))
 	}
+	if rep.queued != nil {
+		writeStepTable(w, "Last attempt failed", artwork.DecodeTrace(rep.queued.Trace, ""))
+	}
+	if rep.stored != nil {
+		writeStepTable(w, "Gave up after", artwork.DecodeTrace(rep.stored.LastFailure, ""))
+	}
 
 	fmt.Fprintln(w, "\nConfig")
 	if setting, value := explainConfig(rep.kind); setting == "" {
@@ -743,15 +777,22 @@ func formatExplain(rep explainReport) string {
 		}
 	}
 
-	fmt.Fprintln(w, "\nChain")
-	if !explainable {
+	fmt.Fprintf(w, "\nChain (%s)\n", explainChainOrigin(rep))
+	switch {
+	case !explainable:
 		fmt.Fprintf(w, "  (%s artwork does not walk a priority chain)\n", rep.kind)
-	} else {
+	case unrecorded:
+		fmt.Fprintln(w, "  (no resolution recorded yet; re-run with --live to walk the chain now)")
+	case !rep.walked && len(rep.steps) == 0 && rep.stored.Hash != "":
+		// A stored image with no chain can only predate trace recording: a recorded resolution that
+		// found an image always records its winning candidate.
+		fmt.Fprintln(w, "  (this item was resolved before traces were recorded; re-run with --live)")
+	case !rep.walked && len(rep.steps) == 0:
+		// Absent with no chain: an empty priority list walked nothing, or a pre-tracing absent row.
+		fmt.Fprintln(w, "  (no candidates were recorded; re-run with --live to walk the chain now)")
+	default:
 		fmt.Fprintln(w, "  CANDIDATE\tOUTCOME\tDETAIL")
-		for _, s := range rep.steps {
-			// A row with an empty last cell would end tabwriter's column block, breaking alignment.
-			fmt.Fprintf(w, "  %s\t%s\t%s\n", s.Candidate, s.Outcome, cmp.Or(s.Detail, "-"))
-		}
+		writeSteps(w, "  ", rep.steps)
 	}
 
 	fmt.Fprintln(w, "\nResult")
@@ -760,6 +801,8 @@ func formatExplain(rep explainReport) string {
 		fmt.Fprintf(w, "  resolution failed: %s\n", rep.resolveErr)
 	case !explainable:
 		fmt.Fprintln(w, "  not evaluated (no chain was walked; see Stored above)")
+	case unrecorded:
+		fmt.Fprintln(w, "  not evaluated (nothing recorded; re-run with --live to walk the chain now)")
 	default:
 		fmt.Fprintf(w, "  %s\n", explainResult(rep.source, rep.steps))
 	}
@@ -807,6 +850,8 @@ func runExplain(ctx context.Context, args []string) {
 		}
 	}
 
+	// Disc artwork keeps no row, so it has no stored trace and can only be explained by walking now.
+	rep.walked = explainLive || !artwork.KeepsState(kind)
 	if artwork.Explainable(kind) {
 		// Only artist and album reach an agent, and the load must precede the resolver, which reads
 		// the same manager.
@@ -815,11 +860,16 @@ func runExplain(ctx context.Context, args []string) {
 			defer func() { _ = mgr.Stop() }()
 			rep.agents = explainAgents(conf.Server.Agents, availableImageAgents(ds, mgr, kind))
 		}
-		trace := &artwork.ChainTrace{}
-		rep.source, rep.resolveErr = CreateArtworkResolver(trace, explainLive).Resolve(ctx, kind, id)
-		rep.steps = trace.Steps()
+		switch {
+		case rep.walked:
+			trace := &artwork.ChainTrace{}
+			rep.source, rep.resolveErr = CreateArtworkResolver(trace, explainLive).Resolve(ctx, kind, id)
+			rep.steps = trace.Steps()
+		case rep.stored != nil:
+			rep.steps = artwork.DecodeTrace(rep.stored.Trace, rep.stored.SourcePath)
+			rep.source = rep.stored.Source
+		}
 	}
-
 	fmt.Print(formatExplain(rep))
 	// The steps taken before a failed walk are the diagnosis, so report them before exiting.
 	if rep.resolveErr != nil {
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index 8b50ba775..38a1b79cb 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -145,6 +145,15 @@ var _ = Describe("explainResult", func() {
 			"the worker retries an unreadable candidate instead of settling absent, so this is not a clean miss")
 	})
 
+	It("reports indeterminate when a processing stage errored after a candidate was found", func() {
+		steps := []artwork.TraceStep{
+			{Candidate: "cover.*", Outcome: "hit", Detail: "/music/cover.jpg"},
+			{Candidate: "store", Outcome: "error", Detail: "disk full"},
+		}
+		Expect(explainResult("", steps)).To(ContainSubstring("indeterminate"),
+			"a stage error is a processing failure the worker retries, not a definitive miss")
+	})
+
 	It("does not qualify a hit that an earlier unreadable candidate preceded", func() {
 		// chainState.try stamps only the external error onto a hit and drops the local one, so the
 		// worker settles this as found; warning about it would be a false alarm.
@@ -164,34 +173,6 @@ var _ = Describe("explainResult", func() {
 			"a failed network call is not evidence that the item has no artwork")
 	})
 
-	It("qualifies a win a skipped higher-priority external candidate could have taken", func() {
-		steps := []artwork.TraceStep{
-			{Candidate: "external:deezer", Outcome: "would-try"},
-			{Candidate: "artist.*", Outcome: "hit", Detail: "/music/artist.jpg"},
-		}
-		res := explainResult("artist.*", steps)
-		Expect(res).To(ContainSubstring("resolved from artist.*"))
-		Expect(res).To(ContainSubstring("--live"),
-			"offline, the winner is only the winner because the external tier was skipped")
-	})
-
-	It("does not qualify a win that no skipped candidate outranked", func() {
-		steps := []artwork.TraceStep{
-			{Candidate: "artist.*", Outcome: "hit"},
-			{Candidate: "external:deezer", Outcome: "would-try"},
-		}
-		Expect(explainResult("artist.*", steps)).To(Equal("resolved from artist.*"))
-	})
-
-	It("reports indeterminate when external agents were never called", func() {
-		steps := []artwork.TraceStep{
-			{Candidate: "artist.*", Outcome: "miss"},
-			{Candidate: "external:deezer", Outcome: "would-try"},
-		}
-		Expect(explainResult("", steps)).To(ContainSubstring("indeterminate"),
-			"an offline run must not claim an item is unresolvable when external agents were skipped")
-	})
-
 	It("qualifies a win a failed higher-priority external lookup could have taken", func() {
 		steps := []artwork.TraceStep{
 			{Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},
@@ -252,9 +233,10 @@ var _ = Describe("formatExplain", func() {
 			id:     "ar-1",
 			name:   "Radiohead",
 			agents: "lastfm,spotify",
+			walked: true,
 			steps: []artwork.TraceStep{
 				{Candidate: "upload", Outcome: "skipped", Detail: "no uploaded image"},
-				{Candidate: "external:deezer", Outcome: "would-try"},
+				{Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},
 			},
 			source: "",
 		}
@@ -267,7 +249,6 @@ var _ = Describe("formatExplain", func() {
 		Expect(out).To(ContainSubstring("ArtistArtPriority"))
 		Expect(out).To(ContainSubstring("lastfm,spotify"))
 		Expect(out).To(ContainSubstring("external:deezer"))
-		Expect(out).To(ContainSubstring("would-try"))
 		Expect(out).To(ContainSubstring("indeterminate"))
 	})
 
@@ -304,7 +285,7 @@ var _ = Describe("formatExplain", func() {
 		out := formatExplain(rep)
 		Expect(out).To(ContainSubstring("resolution failed: no such directory"))
 		Expect(out).ToNot(ContainSubstring("indeterminate"))
-		Expect(out).To(ContainSubstring("would-try"), "the steps taken before the failure still print")
+		Expect(out).To(ContainSubstring("external:deezer"), "the steps taken before the failure still print")
 	})
 
 	It("says a kind that does not walk a chain has no chain, without an empty table", func() {
@@ -329,6 +310,7 @@ var _ = Describe("formatExplain", func() {
 			kind: model.KindDiscArtwork, id: "al-1:2", name: "OK Computer (disc 2)",
 			steps:  []artwork.TraceStep{{Candidate: "cover.jpg", Outcome: "hit", Detail: "/music/cover.jpg"}},
 			source: "folder",
+			walked: true,
 		}
 
 		out := formatExplain(rep)
@@ -341,10 +323,74 @@ var _ = Describe("formatExplain", func() {
 		Expect(out).To(ContainSubstring("resolved from folder"))
 	})
 
+	Context("stored traces", func() {
+		BeforeEach(func() {
+			rep.walked = false
+			rep.steps = nil
+		})
+
+		It("labels a recorded chain with when it was recorded, not as a walk done now", func() {
+			attempted := time.Date(2026, 8, 13, 10, 0, 0, 0, time.UTC)
+			rep.stored = &model.ItemArtwork{Source: "folder", Hash: "abc", AttemptedAt: attempted}
+			rep.steps = []artwork.TraceStep{{Candidate: "artist.*", Outcome: "hit", Detail: "/music/artist.jpg"}}
+			rep.source = "folder"
+
+			out := formatExplain(rep)
+			Expect(out).To(ContainSubstring("Chain (recorded 2026-08-13T10:00:00Z)"))
+			Expect(out).To(ContainSubstring("/music/artist.jpg"))
+			Expect(out).To(ContainSubstring("resolved from folder"))
+		})
+
+		It("says so when the item has never been resolved", func() {
+			out := formatExplain(rep)
+			Expect(out).To(ContainSubstring("no resolution recorded yet"))
+			Expect(out).To(ContainSubstring("--live"))
+			Expect(out).ToNot(ContainSubstring("not resolved"),
+				"nothing was recorded, which is not the same as resolving to nothing")
+		})
+
+		It("distinguishes a row written before traces existed from one with an empty chain", func() {
+			rep.stored = &model.ItemArtwork{Source: "folder", Hash: "abc", AttemptedAt: time.Now()}
+
+			Expect(formatExplain(rep)).To(ContainSubstring("resolved before traces were recorded"))
+		})
+
+		It("does not call an absent row with an empty recorded chain a pre-tracing row", func() {
+			// An empty priority list records a real but empty chain and resolves absent; that is not a
+			// legacy row, so it must not be reported as resolved before tracing existed.
+			rep.stored = &model.ItemArtwork{Source: "", Hash: "", AttemptedAt: time.Now()}
+
+			out := formatExplain(rep)
+			Expect(out).ToNot(ContainSubstring("resolved before traces were recorded"))
+			Expect(out).To(ContainSubstring("no candidates were recorded"))
+			Expect(out).To(ContainSubstring("not resolved"), "the Result still reports the absence plainly")
+		})
+
+		It("prints why the last attempt failed and why it gave up", func() {
+			rep.queued = &model.ArtworkQueueItem{Priority: model.ArtworkPriorityScan, Attempts: 3,
+				Trace: `[{"c":"decode","o":"error","d":"bad header"}]`}
+			rep.stored = &model.ItemArtwork{Source: "folder", Hash: "abc", AttemptedAt: time.Now(),
+				LastFailure: `[{"c":"read","o":"error","d":"i/o timeout"}]`}
+
+			out := formatExplain(rep)
+			Expect(out).To(ContainSubstring("Last attempt failed"))
+			Expect(out).To(ContainSubstring("bad header"))
+			Expect(out).To(ContainSubstring("Gave up after"))
+			Expect(out).To(ContainSubstring("i/o timeout"))
+		})
+
+		It("omits the failure tables when there is no failure to report", func() {
+			out := formatExplain(rep)
+			Expect(out).ToNot(ContainSubstring("Last attempt failed"))
+			Expect(out).ToNot(ContainSubstring("Gave up after"))
+		})
+	})
+
 	It("reports the setting that governs media file artwork", func() {
 		conf.Server.EnableMediaFileCoverArt = false
 		rep = explainReport{
 			kind: model.KindMediaFileArtwork, id: "mf-1", name: "Airbag",
+			walked: true,
 			steps: []artwork.TraceStep{
 				{Candidate: "embedded", Outcome: "skipped", Detail: "EnableMediaFileCoverArt is off"},
 			},
diff --git a/core/artwork/agent_images.go b/core/artwork/agent_images.go
index a6f746959..95596dabc 100644
--- a/core/artwork/agent_images.go
+++ b/core/artwork/agent_images.go
@@ -58,7 +58,7 @@ func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar
 		return nil, "", false
 	}
 	for _, a := range imageAgents {
-		reader, _, err := gate(a.Name, func() (io.ReadCloser, string, error) {
+		reader, path, err := gate(a.Name, func() (io.ReadCloser, string, error) {
 			imgs, err := a.Retriever.GetArtistImages(ctx, ar.ID, name, ar.MbzArtistID)
 			if err != nil {
 				return nil, "", err
@@ -69,6 +69,7 @@ func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar
 			}
 			return fromURL(ctx, u)
 		})
+		recordAgent(ctx, a.Name, reader, path, err)
 		if reader != nil {
 			return reader, a.Name, false
 		}
@@ -90,7 +91,7 @@ func fetchAlbumImage(ctx context.Context, ag *agents.Agents, gate gateFunc, al m
 		return nil, "", false
 	}
 	for _, a := range imageAgents {
-		reader, _, err := gate(a.Name, func() (io.ReadCloser, string, error) {
+		reader, path, err := gate(a.Name, func() (io.ReadCloser, string, error) {
 			imgs, err := a.Retriever.GetAlbumImages(ctx, name, artist, al.MbzAlbumID)
 			if err != nil {
 				return nil, "", err
@@ -101,6 +102,7 @@ func fetchAlbumImage(ctx context.Context, ag *agents.Agents, gate gateFunc, al m
 			}
 			return fromURL(ctx, u)
 		})
+		recordAgent(ctx, a.Name, reader, path, err)
 		if reader != nil {
 			return reader, a.Name, false
 		}
diff --git a/core/artwork/artwork.go b/core/artwork/artwork.go
index 7edc80e99..e8458a0f9 100644
--- a/core/artwork/artwork.go
+++ b/core/artwork/artwork.go
@@ -393,16 +393,15 @@ type TracingResolver struct {
 	trace *ChainTrace
 }
 
-// NewTracingResolver builds a TracingResolver that records its priority-chain walk. With live
-// false the external tier is reported but never called.
+// NewTracingResolver builds a TracingResolver that records its priority-chain walk. Without live
+// it gets no agents at all, so neither a chain nor any fallback added later can reach a provider;
+// with it, one item is at most one call per agent, so the rate limiter and breaker are bypassed.
 func NewTracingResolver(ds model.DataStore, ag *agents.Agents, ffm ffmpeg.FFmpeg, t *ChainTrace, live bool) *TracingResolver {
-	gate := offlineGate(t)
+	inner := newLocalResolver(ds, ffm)
 	if live {
-		// A diagnostic must show the provider's real answer, and one item is at most one call
-		// per agent, so --live deliberately bypasses the rate limiter and circuit breaker.
-		gate = tracingGate(t, passthroughGate)
+		inner = newResolver(ds, ag, ffm, passthroughGate)
 	}
-	return &TracingResolver{inner: newResolver(ds, ag, ffm, gate), trace: t}
+	return &TracingResolver{inner: inner, trace: t}
 }
 
 // Resolve walks kind's sources for id, recording the walk, and reports the winning source
diff --git a/core/artwork/processor.go b/core/artwork/processor.go
index 4d38ced95..fdb28189a 100644
--- a/core/artwork/processor.go
+++ b/core/artwork/processor.go
@@ -2,6 +2,7 @@ package artwork
 
 import (
 	"bytes"
+	"cmp"
 	"context"
 	"encoding/base64"
 	"errors"
@@ -89,12 +90,21 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 
 	res, err := p.resolver.resolve(ctx, item)
 	if err != nil {
+		traceStage(ctx, "resolve", err)
 		log.Warn(ctx, "Artwork: Could not resolve item", "kind", item.ItemKind, "id", item.ItemID, err)
 		return outcomeFailed, nil
 	}
 	if res.reader == nil {
 		if res.extError || res.localError {
 			// A fault is not a definitive "no image": never settle absent, keep serving old state.
+			// A chainless resolver (playlist/radio) records no step, so leave a fallback or explain is blank.
+			if t := traceFrom(ctx); len(t.Steps()) == 0 {
+				outcome := OutcomeError
+				if res.localError {
+					outcome = OutcomeUnreadable
+				}
+				t.add(TraceStep{Candidate: cmp.Or(res.source, "source"), Outcome: outcome})
+			}
 			log.Debug(ctx, "Artwork: No image, but a source faulted; keeping previous state",
 				"kind", item.ItemKind, "id", item.ItemID, "extError", res.extError, "localError", res.localError)
 			return outcomeFailed, nil
@@ -106,6 +116,7 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 	readStart := time.Now()
 	data, err := readCapped(res.reader)
 	if err != nil {
+		traceStage(ctx, "read", err)
 		log.Warn(ctx, "Artwork: Failed to read resolved image", "kind", item.ItemKind, "id", item.ItemID, "source", res.source, err)
 		return outcomeFailed, nil
 	}
@@ -115,6 +126,7 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 	hashStart := time.Now()
 	hash, err := hashImage(bytes.NewReader(data))
 	if err != nil {
+		traceStage(ctx, "hash", err)
 		log.Warn(ctx, "Artwork: Failed to hash image", "kind", item.ItemKind, "id", item.ItemID, err)
 		return outcomeFailed, nil
 	}
@@ -138,19 +150,22 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 			art, err = undecodedArtwork(hash), nil
 		}
 		if err != nil {
+			traceStage(ctx, "decode", err)
 			log.Warn(ctx, "Artwork: Failed to decode resolved image", "kind", item.ItemKind, "id", item.ItemID, err)
 			return outcomeFailed, nil
 		}
 		log.Debug(ctx, "Artwork: Decoded new image", "kind", item.ItemKind, "id", item.ItemID, "hash", hash,
 			"width", art.Width, "height", art.Height, "mime", art.Mime, "elapsed", time.Since(decodeStart))
 	default:
+		traceStage(ctx, "lookup", err)
 		log.Warn(ctx, "Artwork: Failed to look up image hash", "kind", item.ItemKind, "id", item.ItemID, err)
 		return outcomeFailed, nil
 	}
 	art.SizeBytes = int64(len(data))
 
-	ia, err := p.persist(repo, item, art, res, data)
+	ia, err := p.persist(ctx, repo, item, art, res, data)
 	if err != nil {
+		traceStage(ctx, "store", err)
 		log.Warn(ctx, "Artwork: Failed to persist resolved image", "kind", item.ItemKind, "id", item.ItemID, err)
 		return outcomeFailed, nil
 	}
@@ -165,7 +180,7 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 
 // persist places the bytes and commits the rows referencing them, excluding Prune for that
 // window only so a slow resolution can never hold it off.
-func (p *processor) persist(repo model.ArtworkRepository, item model.ArtworkQueueItem,
+func (p *processor) persist(ctx context.Context, repo model.ArtworkRepository, item model.ArtworkQueueItem,
 	art *model.Artwork, res resolution, data []byte,
 ) (*model.ItemArtwork, error) {
 	if p.pruneLock != nil {
@@ -188,6 +203,7 @@ func (p *processor) persist(repo model.ArtworkRepository, item model.ArtworkQueu
 		SourcePath:  sourcePath,
 		RefMtime:    refMtime,
 		AttemptedAt: time.Now(),
+		Trace:       traceFrom(ctx).encode(sourcePath),
 	}
 	// PutItemArtwork stamps UpdatedAt on ia, so the returned struct matches the persisted row.
 	if err := repo.PutItemArtwork(ia); err != nil {
@@ -203,6 +219,7 @@ func writeAbsent(ctx context.Context, repo model.ArtworkRepository, item model.A
 		ItemID:      item.ItemID,
 		ImageType:   item.ImageType,
 		AttemptedAt: time.Now(),
+		Trace:       traceFrom(ctx).encode(""),
 	})
 	if err != nil {
 		log.Warn(ctx, "Artwork: Failed to persist absent state", "kind", item.ItemKind, "id", item.ItemID, err)
diff --git a/core/artwork/processor_test.go b/core/artwork/processor_test.go
index 1ada8415d..0ca5a308e 100644
--- a/core/artwork/processor_test.go
+++ b/core/artwork/processor_test.go
@@ -229,6 +229,35 @@ var _ = Describe("processor.acquire", func() {
 		Expect(err).To(MatchError(model.ErrNotFound), "an unreadable upload must not be recorded as absent")
 	})
 
+	// Playlist/radio resolvers walk no chain, so a fault records no step; without a fallback,
+	// explain would show a give-up with an empty "Gave up after" table.
+	It("chainless fault: records a fallback trace step naming the faulted source", func() {
+		if runtime.GOOS == "windows" {
+			// os.Open under a non-directory maps to a not-exist error on Windows, so no localError.
+			Skip("cannot provoke an open fault via a non-directory parent on Windows")
+		}
+		radioRepo := tests.CreateMockedRadioRepo()
+		radioRepo.Data = map[string]*model.Radio{}
+		ds.MockedRadio = radioRepo
+		dir := GinkgoT().TempDir()
+		conf.Server.DataFolder = conf.NewDir(dir)
+		upload := model.UploadedImagePath(consts.EntityRadio, "ra-tr.jpg")
+		// A plain file where the upload's parent should be makes os.Open fault with ENOTDIR,
+		// deterministically and regardless of the test user's privileges.
+		Expect(os.MkdirAll(filepath.Dir(filepath.Dir(upload)), 0o755)).To(Succeed())
+		Expect(os.WriteFile(filepath.Dir(upload), []byte("x"), 0o600)).To(Succeed())
+		radioRepo.Data["ra-tr"] = &model.Radio{ID: "ra-tr", Name: "Station", UploadedImage: "ra-tr.jpg"}
+
+		trace := &ChainTrace{}
+		out, _ := proc.acquire(withTrace(ctx, trace), model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra-tr"})
+		Expect(out).To(Equal(outcomeFailed))
+
+		steps := trace.Steps()
+		Expect(steps).To(HaveLen(1), "a radio fault must leave one step so explain is not blank")
+		Expect(steps[0].Candidate).To(Equal("upload"))
+		Expect(steps[0].Outcome).To(Equal(OutcomeUnreadable))
+	})
+
 	It("failed-on-extError: leaves the item's state untouched", func() {
 		conf.Server.CoverArtPriority = "external"
 		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
index d25f76460..f42beb9f1 100644
--- a/core/artwork/resolve.go
+++ b/core/artwork/resolve.go
@@ -37,7 +37,7 @@ type resolution struct {
 // transient external failure still retries; localErr is dropped, as the scanner re-lists changes.
 type chainState struct {
 	extErr, localErr bool
-	trace            *ChainTrace // nil unless the CLI asked for a trace
+	trace            *ChainTrace // nil only where no caller attached one
 }
 
 // try stamps the accumulated external failure onto a hit, and records the miss otherwise.
@@ -354,10 +354,13 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 	}
 	if remoteImg != nil && conf.Server.EnableM3UExternalAlbumArt {
 		sf := func() (io.ReadCloser, string, error) { return fromURL(ctx, remoteImg) }
-		if res, ok, isErr := resolveExternalStep(r.ext.gate, "m3u", sf); ok {
+		if res, ok, err := resolveExternalStep(r.ext.gate, "m3u", sf); ok {
 			return res, nil
-		} else if isErr {
+		} else if err != nil {
 			extErr = true
+			// Record it here with its detail: once album sampling adds its own steps, the processor's
+			// empty-trace fallback no longer fires, and the error that forced the retry would be lost.
+			traceFrom(ctx).add(TraceStep{Candidate: ExternalPrefix + "m3u", Outcome: OutcomeError, Detail: err.Error()})
 		}
 	}
 
@@ -461,14 +464,17 @@ func (r *resolver) resolveDisc(ctx context.Context, id string) (resolution, erro
 	return dr.selectImage(ctx, r.ffmpeg, conf.Server.DiscArtPriority, &chain)
 }
 
-// resolveExternalStep runs a single external sourceFunc through the named gate. extErr excludes
-// a not-found, which is a definitive "no" rather than a failure.
-func resolveExternalStep(gate gateFunc, name string, sf sourceFunc) (res resolution, ok bool, extErr bool) {
+// resolveExternalStep runs a single external sourceFunc through the named gate. A not-found is a
+// definitive "no", returned as (_, false, nil); any other error is a failure the caller records.
+func resolveExternalStep(gate gateFunc, name string, sf sourceFunc) (resolution, bool, error) {
 	r, path, err := gate(name, sf)
 	if r != nil {
-		return resolution{reader: r, source: externalCandidate, sourcePath: path}, true, false
+		return resolution{reader: r, source: externalCandidate, sourcePath: path}, true, nil
 	}
-	return resolution{}, false, err != nil && !errors.Is(err, model.ErrNotFound)
+	if errors.Is(err, model.ErrNotFound) {
+		return resolution{}, false, nil
+	}
+	return resolution{}, false, err
 }
 
 // classifyPlaylistImage splits a playlist ExternalImageURL into a local filesystem path or a
@@ -561,7 +567,9 @@ func resolveLocalFile(path, source string) (resolution, bool) {
 	}
 	f, err := os.Open(path)
 	if err != nil {
-		return resolution{localError: !errors.Is(err, fs.ErrNotExist)}, false
+		// Carry the source label even on a fault, so a resolver with no chain (playlist/radio) can
+		// still name what faulted in the trace.
+		return resolution{source: source, localError: !errors.Is(err, fs.ErrNotExist)}, false
 	}
 	return resolution{reader: f, source: source, sourcePath: path, refMtime: mtimeOf(path)}, true
 }
diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.go
index 8b4c11c8c..236e76b9b 100644
--- a/core/artwork/resolve_test.go
+++ b/core/artwork/resolve_test.go
@@ -520,6 +520,37 @@ var _ = Describe("resolveItem", func() {
 			Expect(gatedNames).To(Equal([]string{"m3u"}), "the playlist URL fetch is gated under \"m3u\"")
 		})
 
+		It("records the m3u failure in the trace even when album sampling adds its own steps", func() {
+			conf.Server.EnableM3UExternalAlbumArt = true
+			folderRepo.result = nil // the sampled album yields no tile, so the m3u failure is what forced the retry
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "plm3u", Name: "Playlist", ExternalImageURL: "http://example.com/cover.jpg"}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+
+			gate := func(string, func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
+				return nil, "", errors.New("network down")
+			}
+
+			trace := &ChainTrace{}
+			res, err := newResolver(ds, ag, ffm, gate).resolve(withTrace(ctx, trace),
+				model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plm3u"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.extError).To(BeTrue())
+
+			steps := trace.Steps()
+			var m3u *TraceStep
+			for i := range steps {
+				if steps[i].Candidate == ExternalPrefix+"m3u" && steps[i].Outcome == OutcomeError {
+					m3u = &steps[i]
+				}
+			}
+			Expect(m3u).ToNot(BeNil(), "the m3u fetch error must be traced at its source, not left to the empty-trace fallback")
+			Expect(m3u.Detail).To(Equal("network down"),
+				"the trace must carry the underlying error so explain can tell a timeout from an HTTP error")
+		})
+
 		It("treats a missing local ExternalImageURL as a definitive miss, not extError", func() {
 			folderRepo.result = nil // no grid tiles, so the local-file miss is what surfaces
 
diff --git a/core/artwork/trace.go b/core/artwork/trace.go
index 5d02fa4ff..bca2f2c7d 100644
--- a/core/artwork/trace.go
+++ b/core/artwork/trace.go
@@ -2,10 +2,12 @@ package artwork
 
 import (
 	"context"
-	"errors"
+	"encoding/json"
 	"io"
 	"slices"
 	"sync"
+
+	"github.com/navidrome/navidrome/utils/str"
 )
 
 // Outcome is what the priority chain observed for one candidate; the CLI renders and branches on these.
@@ -16,7 +18,6 @@ const (
 	OutcomeMiss       Outcome = "miss"
 	OutcomeUnreadable Outcome = "unreadable"
 	OutcomeSkipped    Outcome = "skipped"
-	OutcomeWouldTry   Outcome = "would-try"
 	OutcomeError      Outcome = "error"
 )
 
@@ -34,8 +35,8 @@ type TraceStep struct {
 	Detail    string
 }
 
-// ChainTrace collects the walk of a single resolution. The artwork worker never attaches
-// one; only the CLI does, so resolution stays allocation-free in the hot path.
+// ChainTrace collects the walk of a single resolution: the worker attaches one per queue
+// item so it can be stored, and the CLI attaches one per explain.
 type ChainTrace struct {
 	mu    sync.Mutex
 	steps []TraceStep
@@ -59,6 +60,65 @@ func (t *ChainTrace) Steps() []TraceStep {
 	return slices.Clone(t.steps)
 }
 
+// maxTraceDetail bounds a stored Detail, which on the failure paths is an error string of
+// unknown length. Past ~1kB a row spills to an overflow page, slowing every scan of the table.
+const maxTraceDetail = 200
+
+// storedStep is the persisted shape of a TraceStep. The keys are single letters because a trace
+// is written for every item, and the encoded length is repeated across the whole library.
+type storedStep struct {
+	C string  `json:"c"`
+	O Outcome `json:"o"`
+	D string  `json:"d,omitempty"`
+}
+
+// encode serializes the trace for storage, without the copy Steps would make for a caller
+// that only wants to write it.
+func (t *ChainTrace) encode(sourcePath string) string {
+	if t == nil {
+		return encodeSteps(nil, sourcePath)
+	}
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return encodeSteps(t.steps, sourcePath)
+}
+
+// encodeSteps writes the stored form. A hit's Detail is the winning source's path, which the
+// same row already stores as source_path, so it is dropped and DecodeTrace puts it back.
+func encodeSteps(steps []TraceStep, sourcePath string) string {
+	out := make([]storedStep, 0, len(steps))
+	for _, s := range steps {
+		d := s.Detail
+		if s.Outcome == OutcomeHit && d == sourcePath {
+			d = ""
+		}
+		out = append(out, storedStep{C: s.Candidate, O: s.Outcome, D: str.TruncateRunes(d, maxTraceDetail, "...")})
+	}
+	b, _ := json.Marshal(out) // []storedStep is all strings, so this cannot fail
+	return string(b)
+}
+
+// DecodeTrace reverses the stored form. A trace that will not parse is reported as no trace at all,
+// since a diagnostic command must not fail on a bad row.
+func DecodeTrace(encoded, sourcePath string) []TraceStep {
+	if encoded == "" {
+		return nil
+	}
+	var stored []storedStep
+	if err := json.Unmarshal([]byte(encoded), &stored); err != nil {
+		return nil
+	}
+	steps := make([]TraceStep, 0, len(stored))
+	for _, s := range stored {
+		d := s.D
+		if d == "" && s.O == OutcomeHit {
+			d = sourcePath
+		}
+		steps = append(steps, TraceStep{Candidate: s.C, Outcome: s.O, Detail: d})
+	}
+	return steps
+}
+
 type traceCtxKey struct{}
 
 func withTrace(ctx context.Context, t *ChainTrace) context.Context {
@@ -70,30 +130,23 @@ func traceFrom(ctx context.Context) *ChainTrace {
 	return t
 }
 
-var errOfflineSkipped = errors.New("artwork: external lookup skipped (offline)")
-
-// tracingGate records each external agent's outcome without changing what the gate returns.
-func tracingGate(t *ChainTrace, inner gateFunc) gateFunc {
-	return func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
-		r, path, err := inner(name, f)
-		candidate := ExternalPrefix + name
-		switch {
-		case r != nil:
-			t.add(TraceStep{Candidate: candidate, Outcome: OutcomeHit, Detail: path})
-		case isTransientExternal(err):
-			t.add(TraceStep{Candidate: candidate, Outcome: OutcomeError, Detail: err.Error()})
-		default:
-			t.add(TraceStep{Candidate: candidate, Outcome: OutcomeMiss})
-		}
-		return r, path, err
+// recordAgent files what one external agent answered. The agent loops call this rather than a
+// gate wrapper, because only they hold the context that carries the trace.
+func recordAgent(ctx context.Context, name string, r io.ReadCloser, path string, err error) {
+	t := traceFrom(ctx)
+	candidate := ExternalPrefix + name
+	switch {
+	case r != nil:
+		t.add(TraceStep{Candidate: candidate, Outcome: OutcomeHit, Detail: path})
+	case isTransientExternal(err):
+		t.add(TraceStep{Candidate: candidate, Outcome: OutcomeError, Detail: err.Error()})
+	default:
+		t.add(TraceStep{Candidate: candidate, Outcome: OutcomeMiss})
 	}
 }
 
-// offlineGate reports which agents would be asked without asking them, so a diagnostic
-// command cannot add load to a provider that is already rate-limiting us.
-func offlineGate(t *ChainTrace) gateFunc {
-	return func(name string, _ func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {
-		t.add(TraceStep{Candidate: ExternalPrefix + name, Outcome: OutcomeWouldTry})
-		return nil, "", errOfflineSkipped
-	}
+// traceStage records a failure from the stages that run after the priority chain has already
+// picked a winner: most ways an item can fail are here, not in the chain walk.
+func traceStage(ctx context.Context, stage string, err error) {
+	traceFrom(ctx).add(TraceStep{Candidate: stage, Outcome: OutcomeError, Detail: err.Error()})
 }
diff --git a/core/artwork/trace_test.go b/core/artwork/trace_test.go
index 5a54c9e91..a16347457 100644
--- a/core/artwork/trace_test.go
+++ b/core/artwork/trace_test.go
@@ -24,13 +24,63 @@ var _ = Describe("trace vocabulary", func() {
 	// what `artwork explain` tells an operator, so it must be made deliberately.
 	It("pins the wire values the CLI reads", func() {
 		Expect([]Outcome{
-			OutcomeHit, OutcomeMiss, OutcomeUnreadable, OutcomeSkipped, OutcomeWouldTry, OutcomeError,
-		}).To(Equal([]Outcome{"hit", "miss", "unreadable", "skipped", "would-try", "error"}))
+			OutcomeHit, OutcomeMiss, OutcomeUnreadable, OutcomeSkipped, OutcomeError,
+		}).To(Equal([]Outcome{"hit", "miss", "unreadable", "skipped", "error"}))
 		Expect(externalCandidate).To(Equal("external"))
 		Expect(ExternalPrefix).To(Equal("external:"))
 	})
 })
 
+var _ = Describe("encodeSteps/DecodeTrace", func() {
+	It("round-trips a trace", func() {
+		steps := []TraceStep{
+			{Candidate: "cover.png", Outcome: OutcomeMiss},
+			{Candidate: "cover.*", Outcome: OutcomeHit, Detail: "/music/a/cover.jpg"},
+		}
+		Expect(DecodeTrace(encodeSteps(steps, ""), "")).To(Equal(steps))
+	})
+
+	It("encodes an empty trace as an empty JSON array", func() {
+		Expect(encodeSteps(nil, "")).To(Equal("[]"))
+		Expect(DecodeTrace("[]", "")).To(BeEmpty())
+	})
+
+	It("tolerates a row written before the column existed", func() {
+		Expect(DecodeTrace("", "")).To(BeEmpty())
+	})
+
+	// The hit detail repeats source_path byte for byte, and that column is on the same row.
+	It("drops a hit detail that repeats sourcePath, and restores it on read", func() {
+		path := "/music/artist/album/cover.jpg"
+		steps := []TraceStep{{Candidate: "cover.*", Outcome: OutcomeHit, Detail: path}}
+		encoded := encodeSteps(steps, path)
+		Expect(encoded).NotTo(ContainSubstring(path))
+		Expect(DecodeTrace(encoded, path)).To(Equal(steps))
+	})
+
+	It("keeps a detail that differs from sourcePath", func() {
+		steps := []TraceStep{{Candidate: "external:deezer", Outcome: OutcomeHit, Detail: "https://cdn/x.jpg"}}
+		Expect(DecodeTrace(encodeSteps(steps, "/music/a/cover.jpg"), "/music/a/cover.jpg")).To(Equal(steps))
+	})
+
+	// A row past ~1kB spills to an overflow page on these WITHOUT ROWID tables, which would
+	// slow every scan; Detail is an error string on the failure paths, so it needs a bound.
+	It("bounds a detail so one long error cannot inflate the row", func() {
+		steps := []TraceStep{{Candidate: "decode", Outcome: OutcomeError, Detail: strings.Repeat("x", 5000)}}
+
+		got := DecodeTrace(encodeSteps(steps, ""), "")
+
+		Expect(len(got[0].Detail)).To(BeNumerically("<=", 210))
+		Expect(got[0].Detail).To(HaveSuffix("..."))
+		Expect(got[0].Candidate).To(Equal("decode"), "truncating the detail must not disturb the step")
+	})
+
+	It("only restores sourcePath onto a detail-less hit", func() {
+		steps := []TraceStep{{Candidate: "cover.*", Outcome: OutcomeMiss}}
+		Expect(DecodeTrace(encodeSteps(steps, "/music/a/cover.jpg"), "/music/a/cover.jpg")).To(Equal(steps))
+	})
+})
+
 var _ = Describe("chainTrace", func() {
 	It("returns nil when no trace is attached", func() {
 		Expect(traceFrom(context.Background())).To(BeNil())
@@ -113,63 +163,41 @@ var _ = Describe("chainState tracing", func() {
 	})
 })
 
-var _ = Describe("external gate tracing", func() {
-	hit := func() (io.ReadCloser, string, error) {
-		return io.NopCloser(strings.NewReader("x")), "http://img", nil
-	}
-	miss := func() (io.ReadCloser, string, error) { return nil, "", agents.ErrNotFound }
-	boom := func() (io.ReadCloser, string, error) { return nil, "", errors.New("returned status 429") }
+var _ = Describe("external agent tracing", func() {
+	var (
+		t    *ChainTrace
+		ctx  context.Context
+		body io.ReadCloser
+	)
+	BeforeEach(func() {
+		t = &ChainTrace{}
+		ctx = withTrace(context.Background(), t)
+		body = io.NopCloser(strings.NewReader("x"))
+	})
 
 	It("records a hit with the image path", func() {
-		t := &ChainTrace{}
-		g := tracingGate(t, passthroughGate)
-
-		r, _, err := g("deezer", hit)
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(r).ToNot(BeNil())
+		recordAgent(ctx, "deezer", body, "http://img", nil)
 		Expect(t.Steps()).To(Equal([]TraceStep{
 			{Candidate: "external:deezer", Outcome: OutcomeHit, Detail: "http://img"},
 		}))
 	})
 
 	It("records a miss for a not-found", func() {
-		t := &ChainTrace{}
-		_, _, _ = tracingGate(t, passthroughGate)("deezer", miss)
+		recordAgent(ctx, "deezer", nil, "", agents.ErrNotFound)
 		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeMiss))
 	})
 
 	It("records a miss for a model not-found", func() {
-		t := &ChainTrace{}
-		notFound := func() (io.ReadCloser, string, error) { return nil, "", model.ErrNotFound }
-		_, _, _ = tracingGate(t, passthroughGate)("deezer", notFound)
+		recordAgent(ctx, "deezer", nil, "", model.ErrNotFound)
 		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeMiss),
 			"both not-found flavours are definitive answers, not faults")
 	})
 
 	It("records an error with its reason", func() {
-		t := &ChainTrace{}
-		_, _, _ = tracingGate(t, passthroughGate)("apple-music", boom)
+		recordAgent(ctx, "apple-music", nil, "", errors.New("returned status 429"))
 		Expect(t.Steps()[0].Outcome).To(Equal(OutcomeError))
 		Expect(t.Steps()[0].Detail).To(ContainSubstring("429"))
 	})
-
-	It("never calls the agent in offline mode", func() {
-		t := &ChainTrace{}
-		called := false
-		counting := func() (io.ReadCloser, string, error) {
-			called = true
-			return hit()
-		}
-
-		_, _, err := offlineGate(t)("deezer", counting)
-
-		Expect(called).To(BeFalse(), "offline mode must not perform external requests")
-		Expect(err).To(MatchError(errOfflineSkipped))
-		Expect(t.Steps()).To(Equal([]TraceStep{
-			{Candidate: "external:deezer", Outcome: OutcomeWouldTry},
-		}))
-	})
 })
 
 var _ = Describe("resolveAlbum tracing", func() {
@@ -409,51 +437,51 @@ var _ = Describe("NewTracingResolver", func() {
 		t = &ChainTrace{}
 	})
 
-	Context("offline", func() {
+	Context("resolving", func() {
 		var fake *fakeImageAgent
 
 		BeforeEach(func() {
-			fake = &fakeImageAgent{name: "offline-probe"}
+			// Misses, so the chain falls through to the local tier and both are traced.
+			fake = &fakeImageAgent{name: "probe", err: agents.ErrNotFound}
 			albumRepo.SetData(model.Albums{{
 				ID: "al1", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"},
 			}})
 			artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})
 		})
 
-		It("reports the external tier without asking any agent", func() {
-			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
+		It("asks the agents and records what each answered", func() {
+			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(source).To(Equal("embedded"))
-			Expect(fake.albumCalls).To(BeZero(), "offline mode must not add load to an external provider")
-			Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:offline-probe", Outcome: OutcomeWouldTry}))
+			Expect(fake.albumCalls).To(Equal(1))
+			Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:probe", Outcome: OutcomeMiss}))
 		})
 
 		It("records the local chain steps too", func() {
-			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
+			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
 
 			Expect(err).ToNot(HaveOccurred())
 			last := t.Steps()[len(t.Steps())-1]
-			Expect(last.Candidate).To(Equal("embedded"), "the local chain must be traced, not just the external gate")
+			Expect(last.Candidate).To(Equal("embedded"), "the local chain must be traced, not just the external tier")
 			Expect(last.Outcome).To(Equal(OutcomeHit))
 		})
 
 		It("never persists artwork state", func() {
-			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
+			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(artworkRepo.ItemData).To(BeEmpty(),
-				"an offline resolution carries extError, which must never be recorded as a real provider failure")
+				"explain is read-only; a diagnostic walk must never become the stored answer")
 			Expect(queueRepo.Data).To(BeEmpty())
 		})
 
 		It("resolves an artist without persisting anything", func() {
-			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindArtistArtwork, "ar1")
+			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindArtistArtwork, "ar1")
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(source).To(BeEmpty())
-			Expect(fake.artistCalls).To(BeZero())
-			Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:offline-probe", Outcome: OutcomeWouldTry}))
+			Expect(fake.artistCalls).To(Equal(1))
 			Expect(artworkRepo.ItemData).To(BeEmpty())
 			Expect(queueRepo.Data).To(BeEmpty())
 		})
@@ -465,31 +493,39 @@ var _ = Describe("NewTracingResolver", func() {
 				ID: "al2", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/no-such-file.mp3", FolderIDs: []string{"f1"},
 			}})
 
-			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al2")
+			source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindAlbumArtwork, "al2")
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(source).To(Equal("embedded"))
 			Expect(ffm.IsClosed()).To(BeTrue(), "nothing downstream closes it, so a leak is one file handle per invocation")
 		})
 
+		// Serving falls back disc -> album and track -> disc -> album. The resolver does not, but
+		// if it ever did, an explain without --live would start calling providers uninvited.
+		It("cannot reach a provider without live, whatever the chain does", func() {
+			conf.Server.DiscArtPriority = "external, cover.*"
+			conf.Server.CoverArtPriority = "external, cover.*"
+			conf.Server.EnableMediaFileCoverArt = true
+			mfRepo := tests.CreateMockMediaFileRepo()
+			mfRepo.SetData(model.MediaFiles{{ID: "mf1", LibraryID: 0, HasCoverArt: true,
+				Path: "tests/fixtures/artist/an-album/test.mp3"}})
+			ds.MockedMediaFile = mfRepo
+			offline := NewTracingResolver(ds, imageAgents(fake), ffm, t, false)
+
+			_, err := offline.Resolve(context.Background(), model.KindDiscArtwork, "al1:1")
+			Expect(err).ToNot(HaveOccurred())
+			_, err = offline.Resolve(context.Background(), model.KindMediaFileArtwork, "mf1")
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(fake.albumCalls).To(BeZero())
+			Expect(fake.artistCalls).To(BeZero())
+		})
+
 		It("propagates a lookup error", func() {
-			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "nope")
+			_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindAlbumArtwork, "nope")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 	})
-
-	It("asks the agents when live is true", func() {
-		fake := &fakeImageAgent{name: "live-probe", err: agents.ErrNotFound}
-		albumRepo.SetData(model.Albums{{
-			ID: "al1", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"},
-		}})
-
-		_, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindAlbumArtwork, "al1")
-
-		Expect(err).ToNot(HaveOccurred())
-		Expect(fake.albumCalls).To(Equal(1))
-		Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:live-probe", Outcome: OutcomeMiss}))
-	})
 })
 
 var _ = Describe("resolveDisc tracing", func() {
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index be8495305..6271e54bf 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -235,6 +235,8 @@ func (w *Worker) broadcastRefresh(ctx context.Context, found []model.ArtworkQueu
 
 func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outcome, *acquired) {
 	item.ImageType = cmp.Or(item.ImageType, model.ImageTypePrimary)
+	trace := &ChainTrace{}
+	ctx = withTrace(ctx, trace)
 	out, got := w.proc.acquire(ctx, item)
 
 	queue := w.proc.ds.ArtworkQueue(ctx)
@@ -247,10 +249,11 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 		}
 	case outcomeFoundStale, outcomeFailed:
 		retryAt := time.Now().Add(backoff(item.Attempts))
+		encoded := trace.encode("")
 		if retryAt.Before(item.EnqueuedAt.Add(giveUpAfter)) {
 			// A mid-flight re-enqueue reset retry_at; stale backoff must not stomp its
 			// fresh, immediate eligibility.
-			if err := queue.MarkFailedIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt, retryAt); err != nil {
+			if err := queue.MarkFailedIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt, retryAt, encoded); err != nil {
 				log.Warn(ctx, "Artwork: Could not reschedule failed queue item", "kind", item.ItemKind, "id", item.ItemID, err)
 			}
 			log.Debug(ctx, "Artwork: Rescheduled item", "kind", item.ItemKind, "id", item.ItemID,
@@ -265,6 +268,9 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 			writeAbsent(ctx, w.proc.ds.Artwork(ctx), item)
 			settled = "recorded absent"
 		}
+		// The queue row is about to go, taking the only record of the failure with it. This write is
+		// unconditional (not CAS-guarded) — safe only because the drain resolves each item serially.
+		w.recordGiveUp(ctx, item, encoded)
 		log.Info(ctx, "Artwork: Retry budget exhausted, giving up", "kind", item.ItemKind, "id", item.ItemID,
 			"outcome", out, "attempts", item.Attempts+1, "budget", giveUpAfter, "settled", settled)
 		if err := queue.DeleteIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt); err != nil {
@@ -274,6 +280,18 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 	return out, got
 }
 
+// recordGiveUp keeps the last failure on the state row after the queue row is deleted. An item
+// that never resolved has no row to update, and creating one would settle it absent.
+func (w *Worker) recordGiveUp(ctx context.Context, item model.ArtworkQueueItem, trace string) {
+	kind, ok := model.ParseKind(item.ItemKind)
+	if !ok {
+		return
+	}
+	if err := w.proc.ds.Artwork(ctx).PutLastFailure(kind, item.ItemID, item.ImageType, trace); err != nil {
+		log.Warn(ctx, "Artwork: Could not record the last failure", "kind", item.ItemKind, "id", item.ItemID, err)
+	}
+}
+
 func (w *Worker) hasResolvedArtwork(ctx context.Context, item model.ArtworkQueueItem) bool {
 	kind, ok := model.ParseKind(item.ItemKind)
 	if !ok {
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index 53b6a43b2..248e400e1 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -95,6 +95,17 @@ func (f *fakeEventBroker) getEvents() []events.Event {
 
 var _ events.Broker = (*fakeEventBroker)(nil)
 
+// expireQueued ages a row past the retry budget, so the next drain settles it instead of retrying.
+func expireQueued(q *tests.MockArtworkQueueRepo, id string) {
+	GinkgoHelper()
+	for k, v := range q.Data {
+		if v.ItemID == id {
+			v.EnqueuedAt = time.Now().Add(-(giveUpAfter + time.Hour))
+			q.Data[k] = v
+		}
+	}
+}
+
 func findQueued(q *tests.MockArtworkQueueRepo, kind, id string) *model.ArtworkQueueItem {
 	for _, it := range q.Data {
 		if it.ItemKind == kind && it.ItemID == id {
@@ -318,12 +329,7 @@ var _ = Describe("Worker", func() {
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
 			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al9"})).To(Succeed())
 			// Age the row past the retry budget.
-			for k, v := range queueRepo.Data {
-				if v.ItemID == "al9" {
-					v.EnqueuedAt = time.Now().Add(-(giveUpAfter + time.Hour))
-					queueRepo.Data[k] = v
-				}
-			}
+			expireQueued(queueRepo, "al9")
 
 			n, err := w.drain(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
@@ -345,12 +351,7 @@ var _ = Describe("Worker", func() {
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
 			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al10"})).To(Succeed())
-			for k, v := range queueRepo.Data {
-				if v.ItemID == "al10" {
-					v.EnqueuedAt = time.Now().Add(-(giveUpAfter + time.Hour))
-					queueRepo.Data[k] = v
-				}
-			}
+			expireQueued(queueRepo, "al10")
 
 			n, err := w.drain(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
@@ -362,6 +363,67 @@ var _ = Describe("Worker", func() {
 			Expect(ia.Hash).To(Equal("cafebabe"), "a persistent outage must not discard served art")
 		})
 
+		It("records on the queue row why the last attempt failed", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al11", Name: "Album"}})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al11"})).To(Succeed())
+
+			_, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+
+			it := findQueued(queueRepo, "al", "al11")
+			Expect(it).ToNot(BeNil())
+			Expect(DecodeTrace(it.Trace, "")).To(ContainElement(SatisfyAll(
+				HaveField("Candidate", "external:failAgent"),
+				HaveField("Outcome", OutcomeError),
+				HaveField("Detail", ContainSubstring("agent timed out")),
+			)), "a retrying row must say why it is retrying")
+		})
+
+		// The give-up path settles absent before recording, so the row exists by the time the
+		// failure is written. Recording first would silently lose it for every unresolved item.
+		It("keeps the failure for an item that never resolved at all", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al13", Name: "Album"}})
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al13"})).To(Succeed())
+			expireQueued(queueRepo, "al13")
+
+			_, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al13", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred(), "settling absent must create the row the failure is written to")
+			Expect(ia.Hash).To(BeEmpty())
+			Expect(DecodeTrace(ia.LastFailure, "")).ToNot(BeEmpty())
+		})
+
+		It("keeps the failure on the state row after the queue row is deleted", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al12", Name: "Album"}})
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al12", ImageType: model.ImageTypePrimary,
+				Hash: "cafebabe", Source: "external:lastfm",
+			})).To(Succeed())
+			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
+			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al12"})).To(Succeed())
+			expireQueued(queueRepo, "al12")
+
+			_, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(findQueued(queueRepo, "al", "al12")).To(BeNil())
+			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al12", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(DecodeTrace(ia.LastFailure, "")).ToNot(BeEmpty(),
+				"the queue row is gone, so this is the only remaining record of the failure")
+			Expect(ia.Hash).To(Equal("cafebabe"), "recording the failure must not disturb the served art")
+		})
+
 		// Media files are excluded from RecheckKinds, so an absent row here would never be
 		// revisited: a transient read error would look permanent.
 		It("does not settle absent on exhaustion for a kind with no recheck path", func() {
@@ -371,12 +433,7 @@ var _ = Describe("Worker", func() {
 				{ID: "mfX", LibraryID: 0, Path: "tests/fixtures/artist/an-album/gone.mp3", HasCoverArt: true},
 			})
 			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mfX"})).To(Succeed())
-			for k, v := range queueRepo.Data {
-				if v.ItemID == "mfX" {
-					v.EnqueuedAt = time.Now().Add(-(giveUpAfter + time.Hour))
-					queueRepo.Data[k] = v
-				}
-			}
+			expireQueued(queueRepo, "mfX")
 
 			n, err := w.drain(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
@@ -386,6 +443,8 @@ var _ = Describe("Worker", func() {
 			_, err = artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mfX", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound),
 				"no row leaves the track unresolved, so a later view can still recover it")
+			// Known gap: with no row and no absent settle, there is nowhere to keep the failure.
+			// Creating one here would write an empty hash, which every reader treats as absent.
 		})
 
 		It("resolves a private playlist under an admin context instead of failing forever", func() {
diff --git a/db/migrations/20260819204637_add_artwork_trace_columns.sql b/db/migrations/20260819204637_add_artwork_trace_columns.sql
new file mode 100644
index 000000000..90fbf9725
--- /dev/null
+++ b/db/migrations/20260819204637_add_artwork_trace_columns.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE item_artwork ADD COLUMN trace jsonb NOT NULL DEFAULT '[]';
+ALTER TABLE item_artwork ADD COLUMN last_failure jsonb NOT NULL DEFAULT '[]';
+ALTER TABLE artwork_queue ADD COLUMN trace jsonb NOT NULL DEFAULT '[]';
+
+-- +goose Down
+ALTER TABLE artwork_queue DROP COLUMN trace;
+ALTER TABLE item_artwork DROP COLUMN last_failure;
+ALTER TABLE item_artwork DROP COLUMN trace;
diff --git a/model/artwork.go b/model/artwork.go
index ea724265a..6107e9ffa 100644
--- a/model/artwork.go
+++ b/model/artwork.go
@@ -51,6 +51,10 @@ type ItemArtwork struct {
 	SourcePath string `structs:"source_path"`
 	// RefMtime is SourcePath's mtime (unix-nanoseconds) at resolution; 0 when there is no SourcePath.
 	RefMtime int64 `structs:"ref_mtime"`
+	// Trace is the encoded walk that produced this state; LastFailure is the walk of the attempt
+	// that exhausted the retry budget. Both are JSON, read back with artwork.DecodeTrace.
+	Trace       string `structs:"trace"`
+	LastFailure string `structs:"last_failure"`
 	// Nullable in the schema, but every insert must set them: these non-pointer fields cannot scan NULL.
 	AttemptedAt time.Time `structs:"attempted_at"`
 	UpdatedAt   time.Time `structs:"updated_at"`
@@ -91,6 +95,8 @@ type ArtworkQueueItem struct {
 	Attempts   int       `structs:"attempts"`
 	RetryAt    time.Time `structs:"retry_at"`
 	EnqueuedAt time.Time `structs:"enqueued_at"`
+	// Trace is why the last attempt failed. Only Get reads it; the drain projects it away.
+	Trace string `structs:"trace"`
 }
 
 // Queue priorities: higher drains first.
@@ -109,6 +115,8 @@ type ArtworkRepository interface {
 	PurgeOrphans(createdBefore time.Time) (int64, error)
 	GetItemArtwork(kind Kind, id, imageType string) (*ItemArtwork, error)
 	PutItemArtwork(ia *ItemArtwork) error
+	// PutLastFailure records the trace of the attempt that exhausted the retry budget.
+	PutLastFailure(kind Kind, id, imageType, trace string) error
 	DeleteForItems(kind Kind, ids []string) error
 	// GetInfoForItems hydrates a page in one batched query.
 	GetInfoForItems(kind Kind, ids []string) (map[string]ItemArtworkInfo, error)
@@ -145,7 +153,7 @@ type ArtworkQueueRepository interface {
 	DequeueBatch(n int, kinds ...string) ([]ArtworkQueueItem, error)
 	// MarkFailedIfUnchanged applies the failure backoff only while retry_at still matches
 	// seenRetryAt, so a concurrent re-enqueue keeps its fresh eligibility.
-	MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time) error
+	MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error
 	// DeleteIfUnchanged deletes only while retry_at still matches, sparing a concurrent re-enqueue.
 	DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error
 	Count() (int64, error)
diff --git a/persistence/artwork_queue_repository.go b/persistence/artwork_queue_repository.go
index 1ff754dc3..ba9fb6f1a 100644
--- a/persistence/artwork_queue_repository.go
+++ b/persistence/artwork_queue_repository.go
@@ -18,6 +18,7 @@ import (
 const enqueueChunkSize = 100
 
 // Every insert writes these, in this order; the INSERT..SELECT forms must project them to match.
+// DequeueBatch also selects exactly these, to leave the drain's rows free of the trace it never reads.
 var enqueueColumns = []string{"item_kind", "item_id", "image_type", "priority", "attempts", "retry_at", "enqueued_at"}
 
 type artworkQueueRepository struct {
@@ -42,11 +43,12 @@ func (r *artworkQueueRepository) Get(kind model.Kind, id, imageType string) (*mo
 	return &res, nil
 }
 
-// Enqueue also resets enqueued_at, so a fresh request does not inherit an old row's spent retry budget.
+// Enqueue starts a fresh lifecycle: it resets enqueued_at (so a fresh request does not inherit an old
+// row's spent retry budget) and clears trace (so explain does not show a prior failure at attempts 0).
 func (r *artworkQueueRepository) Enqueue(items ...model.ArtworkQueueItem) error {
 	return r.enqueue(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
 		priority = MAX(priority, excluded.priority), retry_at = excluded.retry_at,
-		attempts = 0, enqueued_at = excluded.enqueued_at`, items)
+		attempts = 0, enqueued_at = excluded.enqueued_at, trace = '[]'`, items)
 }
 
 func (r *artworkQueueRepository) EnqueuePreservingBackoff(items ...model.ArtworkQueueItem) error {
@@ -159,7 +161,7 @@ func (r *artworkQueueRepository) enqueue(conflict string, items []model.ArtworkQ
 }
 
 func (r *artworkQueueRepository) DequeueBatch(n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
-	sel := Select("*").From(r.tableName).
+	sel := Select(enqueueColumns...).From(r.tableName).
 		Where(LtOrEq{"retry_at": time.Now()}).
 		OrderBy("priority DESC", "enqueued_at ASC").
 		Limit(uint64(n))
@@ -171,10 +173,11 @@ func (r *artworkQueueRepository) DequeueBatch(n int, kinds ...string) ([]model.A
 	return res, err
 }
 
-func (r *artworkQueueRepository) MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time) error {
+func (r *artworkQueueRepository) MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error {
 	upd := Update(r.tableName).
 		Set("attempts", Expr("attempts + 1")).
 		Set("retry_at", retryAt).
+		Set("trace", trace).
 		Where(Eq{"item_kind": kind, "item_id": id, "image_type": imageType, "retry_at": seenRetryAt})
 	_, err := r.executeSQL(upd)
 	return err
diff --git a/persistence/artwork_queue_repository_test.go b/persistence/artwork_queue_repository_test.go
index d11d89a1f..84f3e2986 100644
--- a/persistence/artwork_queue_repository_test.go
+++ b/persistence/artwork_queue_repository_test.go
@@ -127,19 +127,42 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		Expect(repo.Enqueue(item("al", "m1", model.ArtworkPriorityScan))).To(Succeed())
 
 		future := time.Now().Add(48 * time.Hour)
-		Expect(repo.MarkFailedIfUnchanged("al", "m1", model.ImageTypePrimary, original, future)).To(Succeed())
+		Expect(repo.MarkFailedIfUnchanged("al", "m1", model.ImageTypePrimary, original, future, "[]")).To(Succeed())
 		got, _ = repo.DequeueBatch(10)
 		Expect(got).To(HaveLen(1), "the fresh re-enqueue stays immediately eligible")
 		Expect(got[0].Attempts).To(BeZero(), "re-enqueue clears attempts, and the stale failure must not bump them")
 		current := got[0].RetryAt
 
-		Expect(repo.MarkFailedIfUnchanged("al", "m1", model.ImageTypePrimary, current, future)).To(Succeed())
+		Expect(repo.MarkFailedIfUnchanged("al", "m1", model.ImageTypePrimary, current, future, `[{"c":"read","o":"error"}]`)).To(Succeed())
 		got, _ = repo.DequeueBatch(10)
 		Expect(got).To(BeEmpty(), "backed-off row is hidden until the future retry_at")
 		all, _ := repo.Count()
 		Expect(all).To(Equal(int64(1)))
 	})
 
+	It("Enqueue clears a prior lifecycle's failure trace; EnqueuePreservingBackoff keeps it", func() {
+		// Fail an attempt so the queue row carries a failure trace.
+		Expect(repo.Enqueue(item("al", "t1", model.ArtworkPriorityScan))).To(Succeed())
+		backOff("al", "t1", time.Now().Add(-time.Hour))
+		got, _ := repo.DequeueBatch(10)
+		Expect(got).To(HaveLen(1))
+		future := time.Now().Add(48 * time.Hour)
+		Expect(repo.MarkFailedIfUnchanged("al", "t1", model.ImageTypePrimary, got[0].RetryAt, future, `[{"c":"read","o":"error"}]`)).To(Succeed())
+
+		// A continuation of the same lifecycle must retain the trace.
+		Expect(repo.EnqueuePreservingBackoff(item("al", "t1", model.ArtworkPriorityBump))).To(Succeed())
+		kept, err := repo.Get(model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(kept.Trace).To(Equal(`[{"c":"read","o":"error"}]`))
+
+		// A fresh Enqueue resets attempts to 0, so the stale failure trace must be cleared with it.
+		Expect(repo.Enqueue(item("al", "t1", model.ArtworkPriorityScan))).To(Succeed())
+		fresh, err := repo.Get(model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(fresh.Attempts).To(BeZero())
+		Expect(fresh.Trace).To(Equal("[]"), "a fresh lifecycle has no last-attempt trace")
+	})
+
 	It("Enqueue restarts the retry budget an existing row had spent", func() {
 		Expect(repo.Enqueue(item("al", "e1", model.ArtworkPriorityScan))).To(Succeed())
 		backOff("al", "e1", time.Now().Add(-time.Hour))
diff --git a/persistence/artwork_repository.go b/persistence/artwork_repository.go
index 22662b575..89eb1d415 100644
--- a/persistence/artwork_repository.go
+++ b/persistence/artwork_repository.go
@@ -134,11 +134,21 @@ func (r *artworkRepository) PutItemArtwork(ia *model.ItemArtwork) error {
 	}
 	ins := Insert(itemArtworkTable).SetMap(values).Suffix(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
 		hash=excluded.hash, source=excluded.source, source_path=excluded.source_path, ref_mtime=excluded.ref_mtime,
+		trace=excluded.trace, last_failure=excluded.last_failure,
 		attempted_at=excluded.attempted_at, updated_at=excluded.updated_at`)
 	_, err = r.items.executeSQL(ins)
 	return err
 }
 
+// PutLastFailure records why an item exhausted its retry budget. It only updates an existing row:
+// inserting one would write an empty hash, which the rest of the system reads as a settled absent.
+func (r *artworkRepository) PutLastFailure(kind model.Kind, id, imageType, trace string) error {
+	upd := Update(itemArtworkTable).Set("last_failure", trace).
+		Where(Eq{"item_kind": kind.Prefix(), "item_id": id, "image_type": imageType})
+	_, err := r.items.executeSQL(upd)
+	return err
+}
+
 func (r *artworkRepository) DeleteForItems(kind model.Kind, ids []string) error {
 	for chunk := range slices.Chunk(ids, artworkBatchSize) {
 		if err := r.items.delete(Eq{"item_kind": kind.Prefix(), "item_id": chunk}); err != nil {
diff --git a/persistence/artwork_repository_test.go b/persistence/artwork_repository_test.go
index 683dc2d0f..a9687f76b 100644
--- a/persistence/artwork_repository_test.go
+++ b/persistence/artwork_repository_test.go
@@ -28,6 +28,51 @@ var _ = Describe("ArtworkRepository", func() {
 		repo = NewArtworkRepository(context.Background(), GetDBXBuilder())
 	})
 
+	Context("resolution traces", func() {
+		const traceJSON = `[{"c":"cover.*","o":"hit"}]`
+
+		It("round-trips the trace with the state row", func() {
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "t1",
+				ImageType: model.ImageTypePrimary, Hash: "h1", Trace: traceJSON})).To(Succeed())
+
+			got, err := repo.GetItemArtwork(model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Trace).To(Equal(traceJSON))
+			Expect(got.LastFailure).To(BeEmpty())
+		})
+
+		It("replaces the trace when the item is resolved again", func() {
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "t2",
+				ImageType: model.ImageTypePrimary, Trace: traceJSON})).To(Succeed())
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "t2",
+				ImageType: model.ImageTypePrimary, Trace: `[{"c":"embedded","o":"hit"}]`})).To(Succeed())
+
+			got, _ := repo.GetItemArtwork(model.KindAlbumArtwork, "t2", model.ImageTypePrimary)
+			Expect(got.Trace).To(Equal(`[{"c":"embedded","o":"hit"}]`))
+		})
+
+		It("records a last failure on an existing row", func() {
+			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "t3",
+				ImageType: model.ImageTypePrimary, Hash: "h3"})).To(Succeed())
+
+			Expect(repo.PutLastFailure(model.KindAlbumArtwork, "t3", model.ImageTypePrimary,
+				`[{"c":"decode","o":"error"}]`)).To(Succeed())
+
+			got, _ := repo.GetItemArtwork(model.KindAlbumArtwork, "t3", model.ImageTypePrimary)
+			Expect(got.LastFailure).To(Equal(`[{"c":"decode","o":"error"}]`))
+			Expect(got.Hash).To(Equal("h3"), "recording a failure must not disturb the served artwork")
+		})
+
+		// Inserting here would write hash='', which every reader treats as a settled absent.
+		It("never creates a row for an item that has no state", func() {
+			Expect(repo.PutLastFailure(model.KindAlbumArtwork, "ghost", model.ImageTypePrimary,
+				`[{"c":"decode","o":"error"}]`)).To(Succeed())
+
+			_, err := repo.GetItemArtwork(model.KindAlbumArtwork, "ghost", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+	})
+
 	Context("image identity", func() {
 		It("stores and retrieves an artwork by hash", func() {
 			a := &model.Artwork{Hash: "abc123", Mime: "image/jpeg", Width: 500, Height: 500, SizeBytes: 1234, BlurHash: "LKO2?U%2Tw=w"}
diff --git a/tests/mock_artwork_queue_repo.go b/tests/mock_artwork_queue_repo.go
index c8e915daa..f8f57e8d9 100644
--- a/tests/mock_artwork_queue_repo.go
+++ b/tests/mock_artwork_queue_repo.go
@@ -118,7 +118,7 @@ func (m *MockArtworkQueueRepo) DequeueBatch(n int, kinds ...string) ([]model.Art
 	return res, nil
 }
 
-func (m *MockArtworkQueueRepo) MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time) error {
+func (m *MockArtworkQueueRepo) MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -128,6 +128,7 @@ func (m *MockArtworkQueueRepo) MarkFailedIfUnchanged(kind, id, imageType string,
 	if it, ok := m.Data[k]; ok && it.RetryAt.Equal(seenRetryAt) {
 		it.Attempts++
 		it.RetryAt = retryAt
+		it.Trace = trace
 		m.Data[k] = it
 	}
 	return nil
diff --git a/tests/mock_artwork_repo.go b/tests/mock_artwork_repo.go
index 2ace0daba..5d76a0169 100644
--- a/tests/mock_artwork_repo.go
+++ b/tests/mock_artwork_repo.go
@@ -122,6 +122,20 @@ func (m *MockArtworkRepo) GetItemArtwork(kind model.Kind, id, imageType string)
 	return nil, model.ErrNotFound
 }
 
+func (m *MockArtworkRepo) PutLastFailure(kind model.Kind, id, imageType, trace string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return m.Err
+	}
+	key := iaKey(kind.Prefix(), id, imageType)
+	if ia, ok := m.ItemData[key]; ok {
+		ia.LastFailure = trace
+		m.ItemData[key] = ia
+	}
+	return nil
+}
+
 func (m *MockArtworkRepo) PutItemArtwork(ia *model.ItemArtwork) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()

From ffc68e29dbf53baf11ea6ae06d225a2ddea64e78 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 21 Aug 2026 14:03:59 -0400
Subject: [PATCH 065/200] feat(cli): add `artwork cancel` to call off queued
 artwork work (#6006)

* feat(cli): add `artwork cancel` to call off queued artwork work

A bulk backfill had no off switch. Changing an artwork setting bumps the config
fingerprint, which enqueues every entity in the library, and the only way to stop
it was to turn agents off -- which changes the fingerprint again and enqueues a
second full backfill. The escape hatch was the trap.

`artwork cancel` deletes pending queue rows selected by --kind and/or --priority,
with the --dry-run/confirm/-y flow `reprocess` already uses. Cancelling by
priority is the point: it drops a runaway backfill while leaving the bump-priority
rows an operator queued by hand.

It only touches the queue. Resolved artwork and the item_artwork state behind
`artwork explain` are left alone, and the trace of why a cancelled item last
failed goes with its row. Preserving that trace would mean writing it to
last_failure, which `explain` prints under "Gave up after" -- reporting a
cancellation as an exhausted retry budget. The help text says the trace is
discarded instead.

Two limits the help text states, because neither is guessable: work already
dequeued is not interrupted, and an item with no artwork state yet can be queued
again by the hourly missing-artwork recheck. Cancel calls off queued work; it
does not stop the worker.

--kind validates against RefreshableKinds, not the RecheckKinds `reprocess` uses:
the queue holds media file rows, so --all has to reach them. PurgeQueued follows
the repository's naming rule -- it finds its own rows and reports how many went --
and ignores retry_at, since a row still backing off is pending work. The preview
reuses CountByKindAndPriority rather than adding a counter. reprocessConfirm
became confirmUnlessYes(yes, in, verb) now that two commands prompt.

* refactor(cli): share the artwork queue filter between the preview and the delete

Follow-up cleanup on the previous commit; no change to what the command does,
apart from --all, noted below.

The "which rows does cancel touch" predicate was written three times: once as SQL
in PurgeQueued, once in Go in cmd's matchingQueueStats, and once more in the mock.
The preview and the delete could therefore drift, and the mock would keep the
tests green while they did. persistence now has one artworkQueueFilter, shared by
PurgeQueued and a new CountQueued, and cmd does no filtering at all.

That also makes the preview cheaper. It counted the whole queue and filtered in
Go, so `artwork cancel --kind al` scanned every row of every kind to print a
handful. CountQueued pushes the filter into SQL, which the drain index serves as a
range seek. CountByKindAndPriority is gone: it is CountQueued(nil, nil).

--all now selects with an empty filter instead of enumerating RefreshableKinds.
It is what the flag help already claimed, and the enumeration was narrower than
its own documentation -- a queue row whose item_kind this build does not know
survived `--all` with no flag combination able to remove it. It also restores
SQLite's truncate path: measured with EXPLAIN QUERY PLAN, a bare DELETE plans to
nothing, while `WHERE (1=1)` -- which an empty squirrel And renders -- plans to a
full index scan. A test pins the filter's emptiness so that cannot regress
silently.

Also folded together three copies of the parse-and-dedup loop (parseAll), two
copies of the queue-stats table (printQueueStats, now shared with `artwork
status`), two copies of the stat sum (queueTotal), and four copies of the
kind-to-prefix mapping (model.KindPrefixes). The PurgeQueued specs became one
DescribeTable that asserts count and delete agree on every selection.

* docs(cli): say when `artwork cancel` evaluates its selection

The help text covered the two limits that surprise an operator after the fact, but
not the one that bites during the prompt: the count is a preview, and the filters
run again on confirm. A scan or a manual refresh landing in between is cancelled
without ever appearing in the table the operator agreed to.

Deleting only the previewed rows was considered and rejected. The exposure is one
item re-resolving on next view instead of immediately: clearing an item's artwork
state is what every recovery path selects on, so a lost Bump row from
artwork.Refresh comes back at the same priority via provisional() on the next
request, and otherwise within the hour via EnqueueAllMissing. Buying a guarantee
against that costs the truncate path on --all, the flag that exists for a
29k-item backfill.

* refactor(cli): share one set of flag targets across the artwork subcommands

reprocess and cancel each declared their own kinds/all/dry-run/yes variables, but
cobra only ever parses the one subcommand being run, so the two sets could never
hold values at the same time. backup.go already binds one backupDir across two
subcommands and one force across two more; this follows that.

Ten package-level variables become six. Each command keeps its own help string
and its own valid-kind list, so --kind still reports RecheckKinds for reprocess
and RefreshableKinds for cancel, and --source and --priority stay registered only
on the command that has them.

The priority lookup table is now knownPriorities, freeing the artworkPriorities
name for the flag. The new name also reads better against priorityName's fallback
for a value it does not know.
---
 cmd/artwork.go                               | 223 +++++++++++++++----
 cmd/artwork_test.go                          | 168 +++++++++++++-
 model/artwork.go                             |   7 +-
 model/artwork_id.go                          |   7 +
 persistence/artwork_queue_repository.go      |  40 +++-
 persistence/artwork_queue_repository_test.go |  71 +++++-
 tests/mock_artwork_queue_repo.go             |  29 ++-
 7 files changed, 479 insertions(+), 66 deletions(-)

diff --git a/cmd/artwork.go b/cmd/artwork.go
index 63f0d0917..b193abeaf 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -26,12 +26,14 @@ import (
 
 var explainLive bool
 
+// Only one subcommand runs per invocation, so reprocess and cancel bind the same flag targets.
 var (
-	reprocessKinds   []string
-	reprocessSources []string
-	reprocessAll     bool
-	reprocessDryRun  bool
-	reprocessYes     bool
+	artworkKinds      []string
+	artworkSources    []string
+	artworkPriorities []string
+	artworkAll        bool
+	artworkDryRun     bool
+	artworkYes        bool
 )
 
 func init() {
@@ -39,17 +41,26 @@ func init() {
 		"walk the chain again now, performing real external lookups, instead of reporting the "+
 			"stored trace of the last resolution; also initializes plugin agents, which may open "+
 			"external connections")
-	artworkReprocessCmd.Flags().StringSliceVar(&reprocessKinds, "kind", nil,
+	artworkReprocessCmd.Flags().StringSliceVar(&artworkKinds, "kind", nil,
 		"kinds to reprocess ("+kindPrefixes(artwork.RecheckKinds)+"); repeatable")
-	artworkReprocessCmd.Flags().StringSliceVar(&reprocessSources, "source", nil,
+	artworkReprocessCmd.Flags().StringSliceVar(&artworkSources, "source", nil,
 		"only items currently resolved from these sources (e.g. folder, external:deezer, absent)")
-	artworkReprocessCmd.Flags().BoolVar(&reprocessAll, "all", false, "reprocess every kind")
-	artworkReprocessCmd.Flags().BoolVar(&reprocessDryRun, "dry-run", false,
+	artworkReprocessCmd.Flags().BoolVar(&artworkAll, "all", false, "reprocess every kind")
+	artworkReprocessCmd.Flags().BoolVar(&artworkDryRun, "dry-run", false,
 		"report what would be queued and exit without queueing")
-	artworkReprocessCmd.Flags().BoolVarP(&reprocessYes, "yes", "y", false, "skip the confirmation prompt")
+	artworkReprocessCmd.Flags().BoolVarP(&artworkYes, "yes", "y", false, "skip the confirmation prompt")
+	artworkCancelCmd.Flags().StringSliceVar(&artworkKinds, "kind", nil,
+		"kinds to cancel ("+kindPrefixes(artwork.RefreshableKinds)+"); repeatable")
+	artworkCancelCmd.Flags().StringSliceVar(&artworkPriorities, "priority", nil,
+		"only rows queued at these priorities ("+priorityNames()+"); repeatable")
+	artworkCancelCmd.Flags().BoolVar(&artworkAll, "all", false, "cancel every kind at every priority")
+	artworkCancelCmd.Flags().BoolVar(&artworkDryRun, "dry-run", false,
+		"report what would be cancelled and exit without cancelling")
+	artworkCancelCmd.Flags().BoolVarP(&artworkYes, "yes", "y", false, "skip the confirmation prompt")
 	artworkCmd.AddCommand(artworkExplainCmd)
 	artworkCmd.AddCommand(artworkRefreshCmd)
 	artworkCmd.AddCommand(artworkReprocessCmd)
+	artworkCmd.AddCommand(artworkCancelCmd)
 	artworkCmd.AddCommand(artworkStatusCmd)
 	rootCmd.AddCommand(artworkCmd)
 }
@@ -93,6 +104,22 @@ var artworkReprocessCmd = &cobra.Command{
 	},
 }
 
+var artworkCancelCmd = &cobra.Command{
+	Use:   "cancel",
+	Short: "Cancel pending artwork work in bulk, by kind and/or queue priority",
+	Long: "Cancel pending artwork work in bulk, by kind and/or queue priority.\n\n" +
+		"Only the queue is touched: resolved artwork and the state behind `artwork explain` are\n" +
+		"left alone, and the trace of why a cancelled item last failed goes with its queue row.\n\n" +
+		"Work already picked up is not interrupted, and an item with no artwork yet can be\n" +
+		"queued again by the hourly re-check. The selection is applied again when you confirm,\n" +
+		"so anything queued after the preview is cancelled too. Use it to call off a bulk\n" +
+		"backfill, not to stop the worker.",
+	Args: cobra.NoArgs,
+	Run: func(cmd *cobra.Command, args []string) {
+		runCancel(cmd.Context())
+	},
+}
+
 var artworkStatusCmd = &cobra.Command{
 	Use:   "status",
 	Short: "Report the artwork queue, where artwork resolves from, and the backfill state",
@@ -133,9 +160,11 @@ type statusReport struct {
 	current string
 }
 
-func (r statusReport) queueTotal() int64 {
+func (r statusReport) queueTotal() int64 { return queueTotal(r.queue) }
+
+func queueTotal(stats []model.ArtworkQueueStat) int64 {
 	var n int64
-	for _, s := range r.queue {
+	for _, s := range stats {
 		n += s.Count
 	}
 	return n
@@ -155,7 +184,7 @@ func collectStatus(ctx context.Context, ds model.DataStore) (statusReport, error
 	q := ds.ArtworkQueue(ctx)
 	var rep statusReport
 	var err error
-	if rep.queue, err = q.CountByKindAndPriority(); err != nil {
+	if rep.queue, err = q.CountQueued(nil, nil); err != nil {
 		return rep, fmt.Errorf("breaking the artwork queue down by kind: %w", err)
 	}
 
@@ -195,11 +224,7 @@ func formatStatus(rep statusReport) string {
 	if len(rep.queue) == 0 {
 		fmt.Fprintln(w, "  (empty)")
 	} else {
-		fmt.Fprintln(w, "  KIND\tPRIORITY\tITEMS")
-		for _, s := range rep.queue {
-			fmt.Fprintf(w, "  %s\t%s\t%d\n", kindName(s.ItemKind), priorityName(s.Priority), s.Count)
-		}
-		fmt.Fprintf(w, "  TOTAL\t\t%d\n", rep.queueTotal())
+		printQueueStats(w, rep.queue, rep.queueTotal(), "ITEMS", "  ")
 	}
 
 	fmt.Fprintln(w, "\nSources")
@@ -246,6 +271,15 @@ func backfillState(rep statusReport) string {
 	return "up to date"
 }
 
+// printQueueStats writes the shared queue breakdown; the caller owns the tab writer and flushes it.
+func printQueueStats(w io.Writer, stats []model.ArtworkQueueStat, total int64, countHeader, indent string) {
+	fmt.Fprintf(w, "%sKIND\tPRIORITY\t%s\n", indent, countHeader)
+	for _, s := range stats {
+		fmt.Fprintf(w, "%s%s\t%s\t%d\n", indent, kindName(s.ItemKind), priorityName(s.Priority), s.Count)
+	}
+	fmt.Fprintf(w, "%sTOTAL\t\t%d\n", indent, total)
+}
+
 func kindName(prefix string) string {
 	if k, ok := model.ParseKind(prefix); ok {
 		return k.String()
@@ -253,22 +287,44 @@ func kindName(prefix string) string {
 	return prefix
 }
 
+type artworkPriority struct {
+	name  string
+	value int
+}
+
+// knownPriorities is the one listing behind both the name and the parse, so they cannot drift.
+var knownPriorities = []artworkPriority{
+	{"bump", model.ArtworkPriorityBump},
+	{"scan", model.ArtworkPriorityScan},
+	{"backfill", model.ArtworkPriorityBackfill},
+	{"recheck", model.ArtworkPriorityRecheck},
+}
+
+// priorityName falls back to the number: a row written by a newer version still has to print.
 func priorityName(p int) string {
-	switch p {
-	case model.ArtworkPriorityRecheck:
-		return "recheck"
-	case model.ArtworkPriorityBackfill:
-		return "backfill"
-	case model.ArtworkPriorityScan:
-		return "scan"
-	case model.ArtworkPriorityBump:
-		return "bump"
+	for _, ap := range knownPriorities {
+		if ap.value == p {
+			return ap.name
+		}
 	}
 	return strconv.Itoa(p)
 }
 
+func priorityNames() string {
+	return strings.Join(slice.Map(knownPriorities, func(ap artworkPriority) string { return ap.name }), ", ")
+}
+
+func parseArtworkPriority(s string) (int, error) {
+	for _, ap := range knownPriorities {
+		if ap.name == s {
+			return ap.value, nil
+		}
+	}
+	return 0, fmt.Errorf("invalid priority %q, expected one of: %s", s, priorityNames())
+}
+
 func runReprocess(ctx context.Context) {
-	kinds, err := selectedKinds(reprocessKinds, reprocessSources, reprocessAll)
+	kinds, err := selectedKinds(artworkKinds, artworkSources, artworkAll)
 	if err != nil {
 		log.Fatal(ctx, err)
 	}
@@ -285,8 +341,8 @@ func runReprocess(ctx context.Context) {
 		imageAgents = imageAgentCount(ds, mgr)
 	}
 
-	if err := reprocessArtwork(ctx, ds, kinds, repositorySources(reprocessSources), imageAgents,
-		reprocessDryRun, reprocessConfirm(reprocessYes, os.Stdin), os.Stdout); err != nil {
+	if err := reprocessArtwork(ctx, ds, kinds, repositorySources(artworkSources), imageAgents,
+		artworkDryRun, confirmUnlessYes(artworkYes, os.Stdin, "re-resolve"), os.Stdout); err != nil {
 		log.Fatal(ctx, err)
 	}
 }
@@ -299,16 +355,9 @@ func selectedKinds(kinds, sources []string, all bool) ([]model.Kind, error) {
 	if len(kinds) == 0 {
 		return nil, fmt.Errorf("no selector given: pass --kind, --source or --all")
 	}
-	out := make([]model.Kind, 0, len(kinds))
-	for _, k := range kinds {
-		kind, err := parseArtworkKind(k, artwork.RecheckKinds)
-		if err != nil {
-			return nil, err
-		}
-		out = append(out, kind)
-	}
-	// A repeated kind would be counted twice, overstating the cost the operator confirms.
-	return slice.Unique(out), nil
+	return parseAll(kinds, func(s string) (model.Kind, error) {
+		return parseArtworkKind(s, artwork.RecheckKinds)
+	})
 }
 
 // absentSource is how the stored empty source — resolved, no image — is spelled on the CLI.
@@ -327,11 +376,11 @@ func displaySource(s string) string { return cmp.Or(s, absentSource) }
 
 type confirmFunc func(out io.Writer, total, external int64) bool
 
-func reprocessConfirm(yes bool, in io.Reader) confirmFunc {
+func confirmUnlessYes(yes bool, in io.Reader, verb string) confirmFunc {
 	if yes {
 		return func(io.Writer, int64, int64) bool { return true }
 	}
-	return promptConfirm(in)
+	return promptConfirm(in, verb)
 }
 
 // externalEstimate claims no bound: a local hit ends the walk before any agent is asked, and the
@@ -379,13 +428,13 @@ func configuredAgents() []string {
 	return names
 }
 
-func promptConfirm(in io.Reader) confirmFunc {
+func promptConfirm(in io.Reader, verb string) confirmFunc {
 	return func(out io.Writer, total, external int64) bool {
 		var cost string
 		if external > 0 {
 			cost = fmt.Sprintf(" %s", externalLookupLine(external))
 		}
-		fmt.Fprintf(out, "\nThis will re-resolve %d items.%s Continue? [y/N] ", total, cost)
+		fmt.Fprintf(out, "\nThis will %s %d items.%s Continue? [y/N] ", verb, total, cost)
 		var answer string
 		if _, err := fmt.Fscanln(in, &answer); err != nil {
 			return false
@@ -477,6 +526,90 @@ func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kin
 	return nil
 }
 
+func runCancel(ctx context.Context) {
+	kinds, priorities, err := cancelSelection(artworkKinds, artworkPriorities, artworkAll)
+	if err != nil {
+		log.Fatal(ctx, err)
+	}
+
+	defer db.Init(ctx)()
+	ds, ctx := getAdminContext(ctx)
+
+	if err := cancelArtwork(ctx, ds, kinds, priorities, artworkDryRun,
+		confirmUnlessYes(artworkYes, os.Stdin, "cancel"), os.Stdout); err != nil {
+		log.Fatal(ctx, err)
+	}
+}
+
+// cancelSelection leaves --all as the empty filter the repository reads as "every one", so a row
+// whose kind this build does not know still gets cancelled.
+func cancelSelection(kinds, priorities []string, all bool) ([]model.Kind, []int, error) {
+	if all {
+		return nil, nil, nil
+	}
+	if len(kinds) == 0 && len(priorities) == 0 {
+		return nil, nil, fmt.Errorf("no selector given: pass --kind, --priority or --all")
+	}
+	// RefreshableKinds, not RecheckKinds: media files are queued, so --kind must reach them.
+	outKinds, err := parseAll(kinds, func(s string) (model.Kind, error) {
+		return parseArtworkKind(s, artwork.RefreshableKinds)
+	})
+	if err != nil {
+		return nil, nil, err
+	}
+	outPriorities, err := parseAll(priorities, parseArtworkPriority)
+	if err != nil {
+		return nil, nil, err
+	}
+	return outKinds, outPriorities, nil
+}
+
+// parseAll drops repeats: a doubled selector would overstate the total the operator confirms.
+func parseAll[T comparable](values []string, parse func(string) (T, error)) ([]T, error) {
+	out := make([]T, 0, len(values))
+	for _, v := range values {
+		parsed, err := parse(v)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, parsed)
+	}
+	return slice.Unique(out), nil
+}
+
+func cancelArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kind, priorities []int,
+	dryRun bool, confirm confirmFunc, out io.Writer) error {
+	q := ds.ArtworkQueue(ctx)
+	matched, err := q.CountQueued(kinds, priorities)
+	if err != nil {
+		return fmt.Errorf("counting queued artwork: %w", err)
+	}
+	total := queueTotal(matched)
+	w := newTabWriter(out)
+	printQueueStats(w, matched, total, "MATCHED", "")
+	w.Flush()
+
+	switch {
+	case total == 0:
+		fmt.Fprintln(out, "\nNothing matches this selection.")
+		return nil
+	case dryRun:
+		fmt.Fprintln(out, "\nDry run: nothing was cancelled.")
+		return nil
+	case !confirm(out, total, 0):
+		fmt.Fprintln(out, "Aborted: nothing was cancelled.")
+		return nil
+	}
+
+	cancelled, err := q.PurgeQueued(kinds, priorities)
+	if err != nil {
+		return fmt.Errorf("cancelling queued artwork: %w", err)
+	}
+	// Count and delete are separate statements, so a drain in between makes these two differ.
+	fmt.Fprintf(out, "Cancelled %d of %d matched items.\n", cancelled, total)
+	return nil
+}
+
 // printReprocessPreview also states the external estimate, which --dry-run must show because it
 // skips the prompt that would otherwise carry it.
 func printReprocessPreview(out io.Writer, kinds []model.Kind, matched []int64, total, external int64, sources []string) {
@@ -542,7 +675,7 @@ var explainKinds = []model.Kind{
 }
 
 func kindPrefixes(kinds []model.Kind) string {
-	return strings.Join(slice.Map(kinds, func(k model.Kind) string { return k.Prefix() }), ", ")
+	return strings.Join(model.KindPrefixes(kinds), ", ")
 }
 
 func parseArtworkKind(s string, valid []model.Kind) (model.Kind, error) {
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index 38a1b79cb..1d2bdae73 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -549,36 +549,36 @@ var _ = Describe("promptConfirm", func() {
 	BeforeEach(func() { out.Reset() })
 
 	It("states the external cost and accepts an explicit yes", func() {
-		Expect(promptConfirm(strings.NewReader("y\n"))(&out, 42, 7)).To(BeTrue())
+		Expect(promptConfirm(strings.NewReader("y\n"), "re-resolve")(&out, 42, 7)).To(BeTrue())
 		Expect(out.String()).To(ContainSubstring("re-resolve 42 items"))
 		Expect(out.String()).To(ContainSubstring("External lookups: ~7 estimated"))
 	})
 
 	It("defaults to no on anything else", func() {
-		Expect(promptConfirm(strings.NewReader("\n"))(&out, 1, 1)).To(BeFalse())
-		Expect(promptConfirm(strings.NewReader("nope\n"))(&out, 1, 1)).To(BeFalse())
-		Expect(promptConfirm(strings.NewReader(""))(&out, 1, 1)).To(BeFalse())
+		Expect(promptConfirm(strings.NewReader("\n"), "re-resolve")(&out, 1, 1)).To(BeFalse())
+		Expect(promptConfirm(strings.NewReader("nope\n"), "re-resolve")(&out, 1, 1)).To(BeFalse())
+		Expect(promptConfirm(strings.NewReader(""), "re-resolve")(&out, 1, 1)).To(BeFalse())
 	})
 
 	It("drops the external clause when no lookup will be made", func() {
-		Expect(promptConfirm(strings.NewReader("y\n"))(&out, 3, 0)).To(BeTrue())
-		Expect(out.String()).To(ContainSubstring("re-resolve 3 items."))
+		Expect(promptConfirm(strings.NewReader("y\n"), "cancel")(&out, 3, 0)).To(BeTrue())
+		Expect(out.String()).To(ContainSubstring("cancel 3 items."))
 		Expect(out.String()).ToNot(ContainSubstring("External lookups"))
 	})
 })
 
-var _ = Describe("reprocessConfirm", func() {
+var _ = Describe("confirmUnlessYes", func() {
 	var out strings.Builder
 
 	BeforeEach(func() { out.Reset() })
 
 	It("prompts when --yes was not given", func() {
-		Expect(reprocessConfirm(false, strings.NewReader("n\n"))(&out, 5, 5)).To(BeFalse())
+		Expect(confirmUnlessYes(false, strings.NewReader("n\n"), "re-resolve")(&out, 5, 5)).To(BeFalse())
 		Expect(out.String()).To(ContainSubstring("Continue?"))
 	})
 
 	It("bypasses the prompt only for --yes", func() {
-		Expect(reprocessConfirm(true, strings.NewReader(""))(&out, 5, 5)).To(BeTrue())
+		Expect(confirmUnlessYes(true, strings.NewReader(""), "re-resolve")(&out, 5, 5)).To(BeTrue())
 		Expect(out.String()).To(BeEmpty(), "--yes must not print a prompt it never reads")
 	})
 })
@@ -1059,3 +1059,153 @@ var _ = Describe("configuredAgents", func() {
 		Expect(configuredAgents()).To(BeEmpty())
 	})
 })
+
+var _ = Describe("parseArtworkPriority", func() {
+	It("accepts every name status prints", func() {
+		for _, p := range []int{model.ArtworkPriorityRecheck, model.ArtworkPriorityBackfill,
+			model.ArtworkPriorityScan, model.ArtworkPriorityBump} {
+			Expect(parseArtworkPriority(priorityName(p))).To(Equal(p))
+		}
+	})
+
+	It("rejects an unknown name and lists the valid ones", func() {
+		_, err := parseArtworkPriority("urgent")
+		Expect(err).To(MatchError(ContainSubstring(`invalid priority "urgent"`)))
+		Expect(err).To(MatchError(ContainSubstring("backfill")))
+	})
+
+	// Accepting the raw numbers would make the help text a lie and let a typo like 11 select nothing.
+	It("rejects the numeric form", func() {
+		_, err := parseArtworkPriority("10")
+		Expect(err).To(HaveOccurred())
+	})
+})
+
+var _ = Describe("artwork cancel selection", func() {
+	It("errors when no selector is given", func() {
+		_, _, err := cancelSelection(nil, nil, false)
+		Expect(err).To(MatchError(ContainSubstring("no selector given")))
+	})
+
+	// Empty, not an enumeration of the known kinds: --all must also take a queue row whose kind
+	// this build does not recognise.
+	It("selects with no filter at all for --all", func() {
+		kinds, priorities, err := cancelSelection(nil, nil, true)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(kinds).To(BeEmpty())
+		Expect(priorities).To(BeEmpty())
+	})
+
+	// The queue holds media file rows, so --all must reach them.
+	It("accepts media file artwork, which reprocess does not", func() {
+		kinds, _, err := cancelSelection([]string{"mf"}, nil, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(kinds).To(Equal([]model.Kind{model.KindMediaFileArtwork}))
+	})
+
+	It("treats a priority filter on its own as a complete selection", func() {
+		kinds, priorities, err := cancelSelection(nil, []string{"backfill"}, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(kinds).To(BeEmpty(), "no kind filter means every kind")
+		Expect(priorities).To(Equal([]int{model.ArtworkPriorityBackfill}))
+	})
+
+	It("returns only the named kinds and priorities", func() {
+		kinds, priorities, err := cancelSelection([]string{"ar", "al"}, []string{"backfill", "scan"}, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(kinds).To(Equal([]model.Kind{model.KindArtistArtwork, model.KindAlbumArtwork}))
+		Expect(priorities).To(Equal([]int{model.ArtworkPriorityBackfill, model.ArtworkPriorityScan}))
+	})
+
+	It("counts a repeated kind and a repeated priority once", func() {
+		kinds, priorities, err := cancelSelection([]string{"ar", "ar"}, []string{"bump", "bump"}, false)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(kinds).To(HaveLen(1))
+		Expect(priorities).To(HaveLen(1))
+	})
+
+	It("rejects an unknown kind", func() {
+		_, _, err := cancelSelection([]string{"zz"}, nil, false)
+		Expect(err).To(MatchError(ContainSubstring(`invalid kind "zz"`)))
+	})
+
+	It("rejects a kind that is never queued", func() {
+		_, _, err := cancelSelection([]string{"dc"}, nil, false)
+		Expect(err).To(MatchError(ContainSubstring("invalid kind")))
+	})
+
+	It("rejects an unknown priority", func() {
+		_, _, err := cancelSelection(nil, []string{"urgent"}, false)
+		Expect(err).To(MatchError(ContainSubstring("invalid priority")))
+	})
+})
+
+var _ = Describe("cancelArtwork", func() {
+	var ds *tests.MockDataStore
+	var queue *tests.MockArtworkQueueRepo
+	var out strings.Builder
+	ctx := context.Background()
+	accept := func(io.Writer, int64, int64) bool { return true }
+	decline := func(io.Writer, int64, int64) bool { return false }
+
+	BeforeEach(func() {
+		ds = &tests.MockDataStore{}
+		queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)
+		out.Reset()
+		Expect(queue.Enqueue(
+			model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-1", ImageType: model.ImageTypePrimary,
+				Priority: model.ArtworkPriorityBackfill},
+			model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-2", ImageType: model.ImageTypePrimary,
+				Priority: model.ArtworkPriorityBump},
+			model.ArtworkQueueItem{ItemKind: "al", ItemID: "al-1", ImageType: model.ImageTypePrimary,
+				Priority: model.ArtworkPriorityBackfill},
+		)).To(Succeed())
+	})
+
+	It("previews the per-kind breakdown and cancels nothing on a dry run", func() {
+		Expect(cancelArtwork(ctx, ds, []model.Kind{model.KindArtistArtwork}, nil, true, accept, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("artist"))
+		Expect(out.String()).To(ContainSubstring("backfill"))
+		Expect(out.String()).To(ContainSubstring("TOTAL"))
+		Expect(out.String()).To(ContainSubstring("Dry run"))
+		Expect(queue.Count()).To(BeNumerically("==", 3))
+	})
+
+	It("cancels nothing when the operator declines", func() {
+		Expect(cancelArtwork(ctx, ds, nil, nil, false, decline, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("Aborted"))
+		Expect(queue.Count()).To(BeNumerically("==", 3))
+	})
+
+	It("deletes the selected rows and leaves the rest queued", func() {
+		Expect(cancelArtwork(ctx, ds, nil, []int{model.ArtworkPriorityBackfill}, false, accept, &out)).To(Succeed())
+
+		Expect(queue.Count()).To(BeNumerically("==", 1))
+		_, err := queue.Get(model.KindArtistArtwork, "ar-2", model.ImageTypePrimary)
+		Expect(err).ToNot(HaveOccurred(), "a non-matching priority must stay queued")
+		Expect(out.String()).To(ContainSubstring("Cancelled 2 of 2 matched items."))
+	})
+
+	It("cancels every kind and priority when neither filter is given", func() {
+		Expect(cancelArtwork(ctx, ds, nil, nil, false, accept, &out)).To(Succeed())
+		Expect(queue.Count()).To(BeZero())
+	})
+
+	It("stops at a selection that matches nothing instead of prompting", func() {
+		refuse := func(io.Writer, int64, int64) bool {
+			Fail("must not prompt when nothing matches")
+			return false
+		}
+		Expect(cancelArtwork(ctx, ds, []model.Kind{model.KindPlaylistArtwork}, nil, false, refuse, &out)).To(Succeed())
+
+		Expect(out.String()).To(ContainSubstring("Nothing matches this selection."))
+		Expect(queue.Count()).To(BeNumerically("==", 3))
+	})
+
+	It("reports a queue read failure instead of reporting nothing to cancel", func() {
+		queue.Err = errors.New("read failed")
+		Expect(cancelArtwork(ctx, ds, nil, nil, false, accept, &out)).To(MatchError(ContainSubstring("read failed")))
+	})
+})
diff --git a/model/artwork.go b/model/artwork.go
index 6107e9ffa..b484b0500 100644
--- a/model/artwork.go
+++ b/model/artwork.go
@@ -157,13 +157,16 @@ type ArtworkQueueRepository interface {
 	// DeleteIfUnchanged deletes only while retry_at still matches, sparing a concurrent re-enqueue.
 	DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error
 	Count() (int64, error)
-	// CountByKindAndPriority reports the pending queue rows grouped by kind and priority.
-	CountByKindAndPriority() ([]ArtworkQueueStat, error)
+	// CountQueued reports the pending rows matching the kinds and priorities, grouped by both;
+	// an empty filter means every one.
+	CountQueued(kinds []Kind, priorities []int) ([]ArtworkQueueStat, error)
 	// CountAbsent reports the absent states of a kind, and how many of those EnqueueStaleAbsent
 	// would pick up at the given cutoff.
 	CountAbsent(kind Kind, attemptedBefore time.Time) (ArtworkAbsentStat, error)
 	// PurgeDangling removes queue rows whose entity no longer exists.
 	PurgeDangling() (int64, error)
+	// PurgeQueued removes pending rows matching the kinds and priorities; an empty filter means every one.
+	PurgeQueued(kinds []Kind, priorities []int) (int64, error)
 }
 
 type ArtworkQueueStat struct {
diff --git a/model/artwork_id.go b/model/artwork_id.go
index 634a6442f..e827e935a 100644
--- a/model/artwork_id.go
+++ b/model/artwork_id.go
@@ -6,6 +6,8 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 type Kind struct {
@@ -40,6 +42,11 @@ var artworkKindMap = map[string]Kind{
 	KindRadioArtwork.prefix:     KindRadioArtwork,
 }
 
+// KindPrefixes leaves the typed Kind domain for the item_kind column, or for a help string.
+func KindPrefixes(kinds []Kind) []string {
+	return slice.Map(kinds, func(k Kind) string { return k.prefix })
+}
+
 // ParseKind resolves an item_kind prefix (e.g. "al") to its Kind, reporting whether it was known.
 // Use it at string boundaries — URL params, the item_kind column — to enter the typed Kind domain.
 func ParseKind(prefix string) (Kind, bool) {
diff --git a/persistence/artwork_queue_repository.go b/persistence/artwork_queue_repository.go
index ba9fb6f1a..5db122a8b 100644
--- a/persistence/artwork_queue_repository.go
+++ b/persistence/artwork_queue_repository.go
@@ -191,19 +191,45 @@ func (r *artworkQueueRepository) PurgeDangling() (int64, error) {
 	return purgeDangling(r.sqlRepository)
 }
 
+// artworkQueueFilter returns no conditions for an empty filter, so an unfiltered DELETE keeps
+// SQLite's truncate path. It ignores retry_at: a backing-off row is pending work too.
+func artworkQueueFilter(kinds []model.Kind, priorities []int) And {
+	var f And
+	if len(kinds) > 0 {
+		f = append(f, Eq{"item_kind": model.KindPrefixes(kinds)})
+	}
+	if len(priorities) > 0 {
+		f = append(f, Eq{"priority": priorities})
+	}
+	return f
+}
+
+// CountQueued shares its filter with PurgeQueued, so a preview cannot count rows the delete misses.
+func (r *artworkQueueRepository) CountQueued(kinds []model.Kind, priorities []int) ([]model.ArtworkQueueStat, error) {
+	sel := Select("item_kind", "priority", "count(*) as count").From(r.tableName).
+		GroupBy("item_kind", "priority").OrderBy("item_kind", "priority desc")
+	if f := artworkQueueFilter(kinds, priorities); len(f) > 0 {
+		sel = sel.Where(f)
+	}
+	var res []model.ArtworkQueueStat
+	err := r.queryAll(sel, &res)
+	return res, err
+}
+
+func (r *artworkQueueRepository) PurgeQueued(kinds []model.Kind, priorities []int) (int64, error) {
+	del := Delete(r.tableName)
+	if f := artworkQueueFilter(kinds, priorities); len(f) > 0 {
+		del = del.Where(f)
+	}
+	return r.executeSQL(del)
+}
+
 func (r *artworkQueueRepository) Count() (int64, error) {
 	var res struct{ Count int64 }
 	err := r.queryOne(Select("count(*) as count").From(r.tableName), &res)
 	return res.Count, err
 }
 
-func (r *artworkQueueRepository) CountByKindAndPriority() ([]model.ArtworkQueueStat, error) {
-	var res []model.ArtworkQueueStat
-	err := r.queryAll(Select("item_kind", "priority", "count(*) as count").From(r.tableName).
-		GroupBy("item_kind", "priority").OrderBy("item_kind", "priority desc"), &res)
-	return res, err
-}
-
 // CountAbsent matches EnqueueStaleAbsent on hash, so the stale count is what a recheck would queue.
 func (r *artworkQueueRepository) CountAbsent(kind model.Kind, attemptedBefore time.Time) (model.ArtworkAbsentStat, error) {
 	var res model.ArtworkAbsentStat
diff --git a/persistence/artwork_queue_repository_test.go b/persistence/artwork_queue_repository_test.go
index 84f3e2986..35eebdd6d 100644
--- a/persistence/artwork_queue_repository_test.go
+++ b/persistence/artwork_queue_repository_test.go
@@ -411,7 +411,7 @@ var _ = Describe("ArtworkQueueRepository", func() {
 			Expect(repo.Enqueue(item("ar", "a3", model.ArtworkPriorityBump))).To(Succeed())
 			Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
 
-			Expect(repo.CountByKindAndPriority()).To(ConsistOf(
+			Expect(repo.CountQueued(nil, nil)).To(ConsistOf(
 				model.ArtworkQueueStat{ItemKind: "ar", Priority: model.ArtworkPriorityBackfill, Count: 2},
 				model.ArtworkQueueStat{ItemKind: "ar", Priority: model.ArtworkPriorityBump, Count: 1},
 				model.ArtworkQueueStat{ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1},
@@ -419,7 +419,7 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		})
 
 		It("reports an empty queue as no rows", func() {
-			Expect(repo.CountByKindAndPriority()).To(BeEmpty())
+			Expect(repo.CountQueued(nil, nil)).To(BeEmpty())
 		})
 
 		It("counts absent states and how many are due for recheck", func() {
@@ -442,4 +442,71 @@ var _ = Describe("ArtworkQueueRepository", func() {
 			Expect(repo.CountAbsent(model.KindRadioArtwork, time.Now())).To(Equal(model.ArtworkAbsentStat{}))
 		})
 	})
+
+	Describe("PurgeQueued", func() {
+		queuedIDs := func() []string {
+			GinkgoHelper()
+			got, err := repo.DequeueBatch(100)
+			Expect(err).ToNot(HaveOccurred())
+			return slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })
+		}
+
+		BeforeEach(func() {
+			Expect(repo.Enqueue(
+				item("ar", "ar-backfill", model.ArtworkPriorityBackfill),
+				item("ar", "ar-bump", model.ArtworkPriorityBump),
+				item("al", "al-backfill", model.ArtworkPriorityBackfill),
+				item("mf", "mf-scan", model.ArtworkPriorityScan),
+			)).To(Succeed())
+		})
+
+		// CountQueued feeds the preview and PurgeQueued does the delete; they share one filter, so
+		// every selection must count exactly what it deletes.
+		DescribeTable("selects the same rows to count and to delete",
+			func(kinds []model.Kind, priorities []int, deleted int, remaining []string) {
+				counted, err := repo.CountQueued(kinds, priorities)
+				Expect(err).ToNot(HaveOccurred())
+				var total int64
+				for _, s := range counted {
+					total += s.Count
+				}
+				Expect(total).To(BeNumerically("==", deleted), "the preview must match the delete")
+
+				Expect(repo.PurgeQueued(kinds, priorities)).To(BeNumerically("==", deleted))
+				Expect(queuedIDs()).To(ConsistOf(remaining))
+			},
+			Entry("only the given kinds", []model.Kind{model.KindArtistArtwork}, nil,
+				2, []string{"al-backfill", "mf-scan"}),
+			Entry("only the given priorities", nil, []int{model.ArtworkPriorityBackfill},
+				2, []string{"ar-bump", "mf-scan"}),
+			Entry("the intersection of both", []model.Kind{model.KindArtistArtwork}, []int{model.ArtworkPriorityBackfill},
+				1, []string{"ar-bump", "al-backfill", "mf-scan"}),
+			Entry("everything, when neither filter is given", nil, nil,
+				4, []string{}),
+			Entry("several kinds and priorities at once",
+				[]model.Kind{model.KindArtistArtwork, model.KindMediaFileArtwork},
+				[]int{model.ArtworkPriorityBackfill, model.ArtworkPriorityScan},
+				2, []string{"ar-bump", "al-backfill"}),
+			Entry("nothing, leaving the queue alone", []model.Kind{model.KindPlaylistArtwork}, nil,
+				0, []string{"ar-backfill", "ar-bump", "al-backfill", "mf-scan"}),
+		)
+
+		It("deletes a row that is still backing off", func() {
+			backOff("ar", "ar-bump", time.Now().Add(time.Hour))
+
+			Expect(repo.PurgeQueued([]model.Kind{model.KindArtistArtwork}, nil)).To(BeNumerically("==", 2))
+			Expect(repo.Get(model.KindArtistArtwork, "ar-bump", model.ImageTypePrimary)).
+				Error().To(MatchError(model.ErrNotFound))
+		})
+
+		// A WHERE clause, even one that matches everything, costs SQLite its truncate optimization
+		// and turns `artwork cancel --all` into a full scan of the queue.
+		It("adds no conditions at all for an empty filter", func() {
+			Expect(artworkQueueFilter(nil, nil)).To(BeEmpty())
+			Expect(artworkQueueFilter([]model.Kind{model.KindArtistArtwork}, nil)).To(HaveLen(1))
+			Expect(artworkQueueFilter(nil, []int{model.ArtworkPriorityBump})).To(HaveLen(1))
+			Expect(artworkQueueFilter([]model.Kind{model.KindArtistArtwork}, []int{model.ArtworkPriorityBump})).
+				To(HaveLen(2))
+		})
+	})
 })
diff --git a/tests/mock_artwork_queue_repo.go b/tests/mock_artwork_queue_repo.go
index f8f57e8d9..70f7084ff 100644
--- a/tests/mock_artwork_queue_repo.go
+++ b/tests/mock_artwork_queue_repo.go
@@ -167,6 +167,30 @@ func (m *MockArtworkQueueRepo) PurgeDangling() (int64, error) {
 	return purged, nil
 }
 
+// queueFilterMatches mirrors artworkQueueFilter, so the mock cannot let a preview and a delete disagree.
+func queueFilterMatches(it model.ArtworkQueueItem, kinds []model.Kind, priorities []int) bool {
+	prefixes := model.KindPrefixes(kinds)
+	return (len(prefixes) == 0 || slices.Contains(prefixes, it.ItemKind)) &&
+		(len(priorities) == 0 || slices.Contains(priorities, it.Priority))
+}
+
+func (m *MockArtworkQueueRepo) PurgeQueued(kinds []model.Kind, priorities []int) (int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.Err != nil {
+		return 0, m.Err
+	}
+	var purged int64
+	for k, it := range m.Data {
+		if !queueFilterMatches(it, kinds, priorities) {
+			continue
+		}
+		delete(m.Data, k)
+		purged++
+	}
+	return purged, nil
+}
+
 func (m *MockArtworkQueueRepo) Count() (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -176,7 +200,7 @@ func (m *MockArtworkQueueRepo) Count() (int64, error) {
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockArtworkQueueRepo) CountByKindAndPriority() ([]model.ArtworkQueueStat, error) {
+func (m *MockArtworkQueueRepo) CountQueued(kinds []model.Kind, priorities []int) ([]model.ArtworkQueueStat, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -184,6 +208,9 @@ func (m *MockArtworkQueueRepo) CountByKindAndPriority() ([]model.ArtworkQueueSta
 	}
 	var res []model.ArtworkQueueStat
 	for _, it := range m.Data {
+		if !queueFilterMatches(it, kinds, priorities) {
+			continue
+		}
 		i := slices.IndexFunc(res, func(s model.ArtworkQueueStat) bool {
 			return s.ItemKind == it.ItemKind && s.Priority == it.Priority
 		})

From 07b6411c0bc3ff0c2aafe8c8cfac4d00f2a6ddcd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 21 Aug 2026 15:23:07 -0400
Subject: [PATCH 066/200] perf(artwork): cap the stale-absent recheck at 100
 items per kind per hour (#6007)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(artwork): drip the stale-absent recheck instead of bursting it daily

Each hourly housekeeping tick now re-queues at most 100 absent states
per kind, oldest attempts first, instead of everything older than 24h
at once. External agents see a flat ~100 requests/hour per agent
instead of hourly bursts of ~2,000, and the effective recheck interval
self-scales with the size of the absent pool (~4 days at 10k absent
artists) while small libraries keep the 24h floor.

* feat(artwork): trust an absent artwork state for a week before rechecking

With the recheck now dripped at 100 items per kind per hour, the 24h
floor only governed small libraries, where the drip cap never binds;
they still re-asked every agent daily. A 7-day floor cuts that cost 7x
and, for large libraries, becomes the binding limit over the drip
cycle (~5.7k calls/day instead of ~9.6k at 10k absent artists).

Among comparable servers, this is still the second-most-eager recheck:
gonic retries misses every 30 days, Jellyfin and Funkwhale never do.

* refactor(artwork): state the drip's backpressure contract where it bites

Review follow-ups: the recheck limit deliberately caps the *selection*,
not the insertions — already-queued rows use up budget, so a stalled
drain admits no new work instead of building a recovery burst. Say so
in the interface doc, mirror it in the mock by truncating the sorted
candidates (matching the SQL's LIMIT-before-ON CONFLICT), and teach
`artwork status` and the worker doc the post-drip wording. Also pin
the one cmd fixture that still assumed a 24h recheck window.
---
 cmd/artwork.go                               |  3 ++-
 cmd/artwork_test.go                          |  7 ++++---
 core/artwork/housekeeping.go                 |  8 ++++++--
 core/artwork/housekeeping_test.go            | 19 +++++++++++++++++--
 core/artwork/worker.go                       |  3 ++-
 model/artwork.go                             |  9 +++++----
 persistence/artwork_queue_repository.go      |  9 +++++----
 persistence/artwork_queue_repository_test.go | 19 ++++++++++++++++++-
 tests/mock_artwork_queue_repo.go             | 16 +++++++++++-----
 9 files changed, 70 insertions(+), 23 deletions(-)

diff --git a/cmd/artwork.go b/cmd/artwork.go
index b193abeaf..01de071bb 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -238,7 +238,8 @@ func formatStatus(rep statusReport) string {
 	for _, a := range rep.absent {
 		fmt.Fprintf(w, "  %s\t%d\t%d\n", a.kind, a.Total, a.Stale)
 	}
-	fmt.Fprintf(w, "  (rechecked once the last attempt is older than %gh)\n", artwork.StaleAbsentAge.Hours())
+	fmt.Fprintf(w, "  (eligible once the last attempt is older than %gh; re-queued %d per kind per hour, oldest first)\n",
+		artwork.StaleAbsentAge.Hours(), artwork.StaleAbsentRecheckBatch)
 
 	fmt.Fprintln(w, "\nBackfill")
 	fmt.Fprintf(w, "  State:\t%s\n", backfillState(rep))
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index 1d2bdae73..cc63ed86f 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -818,7 +818,7 @@ var _ = Describe("collectStatus", func() {
 				ImageType: model.ImageTypePrimary, Source: source, Hash: hash, AttemptedAt: attempted})).To(Succeed())
 		}
 		put(model.KindArtistArtwork, "ar-1", "external:deezer", "h1", time.Now())
-		put(model.KindArtistArtwork, "ar-2", "", "", time.Now().Add(-48*time.Hour))
+		put(model.KindArtistArtwork, "ar-2", "", "", time.Now().Add(-artwork.StaleAbsentAge-time.Hour))
 		put(model.KindArtistArtwork, "ar-3", "", "", time.Now())
 		put(model.KindAlbumArtwork, "al-1", "folder", "h2", time.Now())
 		Expect(queue.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-9",
@@ -909,8 +909,9 @@ var _ = Describe("formatStatus", func() {
 		Expect(absent).To(MatchRegexp(`artist\s+2\s+1`))
 	})
 
-	It("states the recheck window the absent counts are bucketed against", func() {
-		Expect(formatStatus(rep)).To(ContainSubstring("24h"))
+	It("states the recheck window and the drip rate the absent counts are bucketed against", func() {
+		Expect(formatStatus(rep)).To(ContainSubstring("168h"))
+		Expect(formatStatus(rep)).To(ContainSubstring("100 per kind per hour"))
 	})
 
 	It("leads with the queued backlog, which is the finding, not with the fingerprint verdict", func() {
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
index f2996d044..fed5757c8 100644
--- a/core/artwork/housekeeping.go
+++ b/core/artwork/housekeeping.go
@@ -18,7 +18,11 @@ import (
 )
 
 // StaleAbsentAge is how long an absent state is trusted before a recheck retries it.
-const StaleAbsentAge = 24 * time.Hour
+const StaleAbsentAge = 7 * 24 * time.Hour
+
+// StaleAbsentRecheckBatch caps how many absent states each hourly tick re-queues per kind,
+// oldest first, so external agents see a flat drip instead of a daily burst.
+const StaleAbsentRecheckBatch = 100
 
 // RecheckKinds omits media files: they resolve embedded-only, at scan or on view.
 var RecheckKinds = []model.Kind{
@@ -125,7 +129,7 @@ func enqueueStaleAbsentAll(ctx context.Context, ds model.DataStore) error {
 	cutoff := time.Now().Add(-StaleAbsentAge)
 	queue := ds.ArtworkQueue(ctx)
 	for _, kind := range RecheckKinds {
-		if _, err := queue.EnqueueStaleAbsent(kind, cutoff); err != nil {
+		if _, err := queue.EnqueueStaleAbsent(kind, cutoff, StaleAbsentRecheckBatch); err != nil {
 			return err
 		}
 	}
diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.go
index 4ea15ab04..4f229bff8 100644
--- a/core/artwork/housekeeping_test.go
+++ b/core/artwork/housekeeping_test.go
@@ -2,6 +2,7 @@ package artwork
 
 import (
 	"context"
+	"fmt"
 	"slices"
 	"time"
 
@@ -235,8 +236,8 @@ var _ = Describe("Housekeeping", func() {
 		})
 
 		It("enqueues only absent entries older than the recheck window, across all kinds", func() {
-			old := time.Now().Add(-48 * time.Hour)
-			recent := time.Now().Add(-time.Hour)
+			old := time.Now().Add(-StaleAbsentAge - time.Hour)
+			recent := time.Now().Add(-StaleAbsentAge + time.Hour)
 
 			artRepo.ItemData["ar-stale"] = model.ItemArtwork{ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
 			artRepo.ItemData["al-stale"] = model.ItemArtwork{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
@@ -259,6 +260,20 @@ var _ = Describe("Housekeeping", func() {
 			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar2")).To(BeNil())
 			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al2")).To(BeNil())
 		})
+
+		It("caps each tick at the recheck batch, oldest attempts first", func() {
+			for i := range StaleAbsentRecheckBatch + 1 {
+				id := fmt.Sprintf("ar%d", i)
+				artRepo.ItemData[id] = model.ItemArtwork{ItemKind: "ar", ItemID: id, ImageType: model.ImageTypePrimary,
+					Hash: "", AttemptedAt: time.Now().Add(-StaleAbsentAge - time.Duration(i+1)*time.Minute)}
+			}
+
+			Expect(enqueueStaleAbsentAll(ctx, ds)).To(Succeed())
+
+			Expect(queueRepo.Data).To(HaveLen(StaleAbsentRecheckBatch))
+			// ar0 has the newest attempted_at of the cohort, so it is the one left out.
+			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar0")).To(BeNil())
+		})
 	})
 
 	Describe("EnqueueMissingAll", func() {
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index 6271e54bf..0f947f6d7 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -137,7 +137,8 @@ func (w *Worker) Backfill(ctx context.Context) (bool, error) {
 	return backfill(ctx, w.proc.ds)
 }
 
-// EnqueueStaleAbsentAll requeues known-absent entries older than StaleAbsentAge.
+// EnqueueStaleAbsentAll requeues known-absent entries older than StaleAbsentAge, at most
+// StaleAbsentRecheckBatch per kind, oldest first.
 func (w *Worker) EnqueueStaleAbsentAll(ctx context.Context) error {
 	return enqueueStaleAbsentAll(ctx, w.proc.ds)
 }
diff --git a/model/artwork.go b/model/artwork.go
index b484b0500..3c0df209b 100644
--- a/model/artwork.go
+++ b/model/artwork.go
@@ -134,8 +134,9 @@ type ArtworkQueueRepository interface {
 	// EnqueuePreservingBackoff upserts like Enqueue but preserves an existing row's retry_at, so a
 	// request-triggered read-through never resets a failed resolution's backoff.
 	EnqueuePreservingBackoff(items ...ArtworkQueueItem) error
-	// EnqueueStaleAbsent inserts queue rows (priority Recheck) for absent states older than cutoff.
-	EnqueueStaleAbsent(kind Kind, attemptedBefore time.Time) (int64, error)
+	// EnqueueStaleAbsent inserts queue rows (priority Recheck) for absent states older than cutoff, oldest
+	// first; limit caps the selection, so already-queued rows use up budget (backpressure when the drain stalls).
+	EnqueueStaleAbsent(kind Kind, attemptedBefore time.Time, limit int) (int64, error)
 	// EnqueueAllMissing inserts queue rows for all entities with no item_artwork row, at the given priority.
 	EnqueueAllMissing(kind Kind, priority int) (int64, error)
 	// EnqueueIfMissing inserts only for items with no item_artwork row yet.
@@ -160,8 +161,8 @@ type ArtworkQueueRepository interface {
 	// CountQueued reports the pending rows matching the kinds and priorities, grouped by both;
 	// an empty filter means every one.
 	CountQueued(kinds []Kind, priorities []int) ([]ArtworkQueueStat, error)
-	// CountAbsent reports the absent states of a kind, and how many of those EnqueueStaleAbsent
-	// would pick up at the given cutoff.
+	// CountAbsent reports the absent states of a kind, and how many are past the given cutoff,
+	// eligible for EnqueueStaleAbsent (which drains them limit rows per call).
 	CountAbsent(kind Kind, attemptedBefore time.Time) (ArtworkAbsentStat, error)
 	// PurgeDangling removes queue rows whose entity no longer exists.
 	PurgeDangling() (int64, error)
diff --git a/persistence/artwork_queue_repository.go b/persistence/artwork_queue_repository.go
index 5db122a8b..1c0077fc7 100644
--- a/persistence/artwork_queue_repository.go
+++ b/persistence/artwork_queue_repository.go
@@ -56,11 +56,12 @@ func (r *artworkQueueRepository) EnqueuePreservingBackoff(items ...model.Artwork
 		priority = MAX(priority, excluded.priority)`, items)
 }
 
-func (r *artworkQueueRepository) EnqueueStaleAbsent(kind model.Kind, attemptedBefore time.Time) (int64, error) {
+func (r *artworkQueueRepository) EnqueueStaleAbsent(kind model.Kind, attemptedBefore time.Time, limit int) (int64, error) {
 	now := time.Now()
 	return r.insertIfNotQueued("", `SELECT item_kind, item_id, image_type, ?, 0, ?, ?
-		FROM `+itemArtworkTable+` WHERE item_kind = ? AND hash = '' AND attempted_at < ?`,
-		model.ArtworkPriorityRecheck, now, now, kind.Prefix(), attemptedBefore)
+		FROM `+itemArtworkTable+` WHERE item_kind = ? AND hash = '' AND attempted_at < ?
+		ORDER BY attempted_at LIMIT ?`,
+		model.ArtworkPriorityRecheck, now, now, kind.Prefix(), attemptedBefore, limit)
 }
 
 func (r *artworkQueueRepository) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {
@@ -230,7 +231,7 @@ func (r *artworkQueueRepository) Count() (int64, error) {
 	return res.Count, err
 }
 
-// CountAbsent matches EnqueueStaleAbsent on hash, so the stale count is what a recheck would queue.
+// CountAbsent matches EnqueueStaleAbsent on hash, so the stale count is the pool a recheck drains from.
 func (r *artworkQueueRepository) CountAbsent(kind model.Kind, attemptedBefore time.Time) (model.ArtworkAbsentStat, error) {
 	var res model.ArtworkAbsentStat
 	err := r.queryOne(Select("count(*) as total").
diff --git a/persistence/artwork_queue_repository_test.go b/persistence/artwork_queue_repository_test.go
index 35eebdd6d..1673a5b0e 100644
--- a/persistence/artwork_queue_repository_test.go
+++ b/persistence/artwork_queue_repository_test.go
@@ -244,7 +244,7 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "fresh1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
 		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "found1", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: old})).To(Succeed())
 
-		n, err := repo.EnqueueStaleAbsent(model.KindArtistArtwork, time.Now().Add(-24*time.Hour))
+		n, err := repo.EnqueueStaleAbsent(model.KindArtistArtwork, time.Now().Add(-24*time.Hour), 100)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(n).To(Equal(int64(1)))
 
@@ -255,6 +255,23 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		Expect(items[0].Priority).To(Equal(model.ArtworkPriorityRecheck))
 	})
 
+	It("enqueues only the oldest stale absent states up to the limit", func() {
+		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+		now := time.Now()
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "oldest", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: now.Add(-72 * time.Hour)})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "older", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: now.Add(-60 * time.Hour)})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "old", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: now.Add(-48 * time.Hour)})).To(Succeed())
+
+		n, err := repo.EnqueueStaleAbsent(model.KindArtistArtwork, now.Add(-24*time.Hour), 2)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(n).To(Equal(int64(2)))
+
+		items, err := repo.DequeueBatch(10)
+		Expect(err).ToNot(HaveOccurred())
+		ids := slice.Map(items, func(it model.ArtworkQueueItem) string { return it.ItemID })
+		Expect(ids).To(ConsistOf("oldest", "older"))
+	})
+
 	It("enqueues entities that have no item_artwork row at all", func() {
 		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
 		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: albumSgtPeppers.ID, ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: time.Now()})).To(Succeed())
diff --git a/tests/mock_artwork_queue_repo.go b/tests/mock_artwork_queue_repo.go
index 70f7084ff..51ddf4b61 100644
--- a/tests/mock_artwork_queue_repo.go
+++ b/tests/mock_artwork_queue_repo.go
@@ -272,18 +272,24 @@ func (m *MockArtworkQueueRepo) EnqueuePreservingBackoff(items ...model.ArtworkQu
 	return nil
 }
 
-func (m *MockArtworkQueueRepo) EnqueueStaleAbsent(kind model.Kind, attemptedBefore time.Time) (int64, error) {
+func (m *MockArtworkQueueRepo) EnqueueStaleAbsent(kind model.Kind, attemptedBefore time.Time, limit int) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil || m.ItemArtworkSource == nil {
 		return 0, m.Err
 	}
+	var stale []model.ItemArtwork
+	for _, ia := range m.ItemArtworkSource.ItemData {
+		if ia.ItemKind == kind.Prefix() && ia.Hash == "" && ia.AttemptedAt.Before(attemptedBefore) {
+			stale = append(stale, ia)
+		}
+	}
+	slices.SortFunc(stale, func(a, b model.ItemArtwork) int { return a.AttemptedAt.Compare(b.AttemptedAt) })
+	// The limit caps the selection, like the SQL's LIMIT before ON CONFLICT: queued rows use up budget.
+	stale = stale[:min(limit, len(stale))]
 	now := time.Now()
 	var inserted int64
-	for _, ia := range m.ItemArtworkSource.ItemData {
-		if ia.ItemKind != kind.Prefix() || ia.Hash != "" || !ia.AttemptedAt.Before(attemptedBefore) {
-			continue
-		}
+	for _, ia := range stale {
 		k := iaKey(ia.ItemKind, ia.ItemID, ia.ImageType)
 		if _, ok := m.Data[k]; ok { // DO NOTHING: never touch existing queue rows
 			continue

From 295886cb9a432d375afa796ed8a32db0775464af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 21 Aug 2026 20:27:42 -0400
Subject: [PATCH 067/200] feat(artwork): report what a config-fingerprint
 backfill enqueued (#6010)

* feat(artwork): report what a config-fingerprint backfill enqueued

A backfill re-resolves every entity, and on a large library that is tens of thousands of
external agent calls. It announced itself with a single line carrying nothing but an elapsed
time, so the size of the job was invisible until the request volume showed up hours later.

Log the item count, the per-kind breakdown, and a ceiling on the external lookups the queued
work can cost. The ceiling reuses ExternalLookupsPerItem, the same estimator behind the
`artwork reprocess` preview, so the two agree on what an item can cost.

backfill now returns a summary instead of a bare bool, which keeps the counts assertable
without capturing log output. Worker.Backfill keeps its (bool, error) signature, so its caller
is unchanged, and it reads the agent count off its own resolver.

* refactor(artwork): share the image-agent count and take it lazily

Counting image agents was written twice, once in the CLI for the `artwork reprocess` preview and
again as a resolver method for the backfill log. Two copies of "which agents count as image
agents" can drift, and the CLI estimate and the server log would then disagree silently.

Move the derivation next to the type it builds, as NewImageAgentCount, and call it from both.
The resolver method goes away with it: hanging the census on the resolver forced two nil guards
that its only caller could never trigger, because Worker always builds a resolver with agents.
The Worker keeps the *agents.Agents it is already handed instead of reaching through the
processor and resolver to find it.

Pass the count as a func. Building the agent list constructs every enabled agent (each one an
HTTP client and a cache goroutine) only to take its length, and a backfill returns early on an
unchanged fingerprint, which is what happens on nearly every restart.

* docs(artwork): say what the backfill lookup estimate does not bound

The comment called the number a ceiling, which the CLI comment on the same estimate already
contradicts: externalEstimate "claims no bound". Both are right about the local-source case and
only one of them mentions that a retried item asks its agents again.
---
 cmd/artwork.go                    |  7 +-----
 core/artwork/housekeeping.go      | 35 ++++++++++++++++++++-------
 core/artwork/housekeeping_test.go | 39 ++++++++++++++++++++++++-------
 core/artwork/resolve.go           |  9 +++++++
 core/artwork/worker.go            |  7 ++++--
 5 files changed, 73 insertions(+), 24 deletions(-)

diff --git a/cmd/artwork.go b/cmd/artwork.go
index 01de071bb..8b9e28f0e 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -339,7 +339,7 @@ func runReprocess(ctx context.Context) {
 	if needsImageAgents(kinds) {
 		mgr := loadPluginAgents(ctx, false)
 		defer func() { _ = mgr.Stop() }()
-		imageAgents = imageAgentCount(ds, mgr)
+		imageAgents = artwork.NewImageAgentCount(agents.GetAgents(ds, mgr))
 	}
 
 	if err := reprocessArtwork(ctx, ds, kinds, repositorySources(artworkSources), imageAgents,
@@ -397,11 +397,6 @@ func externalLookupLine(n int64) string {
 	return fmt.Sprintf("External lookups: %s.", externalEstimate(n))
 }
 
-func imageAgentCount(ds model.DataStore, mgr *plugins.Manager) artwork.ImageAgentCount {
-	ag := agents.GetAgents(ds, mgr)
-	return artwork.ImageAgentCount{Artist: len(ag.ArtistImageAgents()), Album: len(ag.AlbumImageAgents())}
-}
-
 // loadPluginAgents loads the plugins named in Agents, so the CLI resolves through the same agents a
 // running server would. A load failure is reported, not fatal: the built-in agents still answer.
 func loadPluginAgents(ctx context.Context, runInit bool) *plugins.Manager {
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
index fed5757c8..9456a5584 100644
--- a/core/artwork/housekeeping.go
+++ b/core/artwork/housekeeping.go
@@ -72,18 +72,27 @@ func ConfigFingerprint() string {
 	return fmt.Sprintf("%016x", xxh3.Hash([]byte(raw)))
 }
 
+// backfillSummary is what a backfill enqueued. MaxExternalLookups is an upper estimate for one
+// attempt per item, not a bound: a local hit ends the walk, and a retry asks the agents again.
+type backfillSummary struct {
+	Ran                bool
+	PerKind            map[string]int64
+	Items              int64
+	MaxExternalLookups int64
+}
+
 // backfill enqueues artwork resolution for every entity when the config fingerprint changed.
-func backfill(ctx context.Context, ds model.DataStore) (bool, error) {
+func backfill(ctx context.Context, ds model.DataStore, agentCount func() ImageAgentCount) (backfillSummary, error) {
 	start := time.Now()
 	ctx = auth.WithAdminUser(ctx, ds)
 	current := ConfigFingerprint()
 	props := ds.Property(ctx)
 	stored, err := props.DefaultGet(consts.ArtConfFingerprintPropertyKey, "")
 	if err != nil {
-		return false, err
+		return backfillSummary{}, err
 	}
 	if stored == current {
-		return false, nil
+		return backfillSummary{}, nil
 	}
 
 	// Artists first: few entities, most external-dependent, so they get a queue headstart.
@@ -96,21 +105,31 @@ func backfill(ctx context.Context, ds model.DataStore) (bool, error) {
 		{model.KindPlaylistArtwork, func() ([]string, error) { return ds.Playlist(ctx).GetAllIDs() }},
 		{model.KindRadioArtwork, func() ([]string, error) { return ds.Radio(ctx).GetAllIDs() }},
 	}
+	// Counted here, not by the caller: building the agent list constructs every enabled agent, and
+	// an unchanged fingerprint returns above without ever needing the number.
+	agents := agentCount()
+	summary := backfillSummary{Ran: true, PerKind: map[string]int64{}}
 	for _, k := range kinds {
 		ids, err := k.fetch()
 		if err != nil {
-			return false, err
+			return backfillSummary{}, err
 		}
 		if err := enqueueBackfillKind(ctx, ds, k.kind, ids); err != nil {
-			return false, err
+			return backfillSummary{}, err
 		}
+		n := int64(len(ids))
+		summary.PerKind[k.kind.Prefix()] = n
+		summary.Items += n
+		summary.MaxExternalLookups += n * ExternalLookupsPerItem(k.kind, agents)
 	}
 
 	if err := props.Put(consts.ArtConfFingerprintPropertyKey, current); err != nil {
-		return false, err
+		return backfillSummary{}, err
 	}
-	log.Info(ctx, "Artwork: Config fingerprint changed, backfill enqueued", "elapsed", time.Since(start))
-	return true, nil
+	log.Info(ctx, "Artwork: Config fingerprint changed, backfill enqueued", "items", summary.Items,
+		"byKind", summary.PerKind, "maxExternalLookups", summary.MaxExternalLookups,
+		"elapsed", time.Since(start))
+	return summary, nil
 }
 
 func enqueueBackfillKind(ctx context.Context, ds model.DataStore, kind model.Kind, ids []string) error {
diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.go
index 4f229bff8..7aecd2760 100644
--- a/core/artwork/housekeeping_test.go
+++ b/core/artwork/housekeeping_test.go
@@ -39,6 +39,8 @@ func adminUserRepo() *tests.MockedUserRepo {
 	return repo
 }
 
+func noAgents() ImageAgentCount { return ImageAgentCount{} }
+
 // orderTrackingQueueRepo records the item kind of each Enqueue call, so tests can
 // assert phase ordering (artists-first) that same-priority timestamps can't guarantee.
 type orderTrackingQueueRepo struct {
@@ -164,9 +166,14 @@ var _ = Describe("Housekeeping", func() {
 			seedEntities()
 			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, ConfigFingerprint())).To(Succeed())
 
-			did, err := backfill(ctx, ds)
+			counted := false
+			s, err := backfill(ctx, ds, func() ImageAgentCount {
+				counted = true
+				return ImageAgentCount{Artist: 3, Album: 2}
+			})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(did).To(BeFalse())
+			Expect(s).To(Equal(backfillSummary{}))
+			Expect(counted).To(BeFalse(), "building the agent list constructs every agent; an unchanged fingerprint must not pay for it")
 
 			count, err := queueRepo.Count()
 			Expect(err).ToNot(HaveOccurred())
@@ -176,9 +183,9 @@ var _ = Describe("Housekeeping", func() {
 		It("runs the backfill when no fingerprint was ever stored", func() {
 			seedEntities()
 
-			did, err := backfill(ctx, ds)
+			s, err := backfill(ctx, ds, noAgents)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(did).To(BeTrue())
+			Expect(s.Ran).To(BeTrue())
 
 			count, err := queueRepo.Count()
 			Expect(err).ToNot(HaveOccurred())
@@ -197,9 +204,9 @@ var _ = Describe("Housekeeping", func() {
 				tracks:        &tests.MockPlaylistTrackRepo{},
 			}
 
-			did, err := backfill(ctx, vds)
+			s, err := backfill(ctx, vds, noAgents)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(did).To(BeTrue())
+			Expect(s.Ran).To(BeTrue())
 			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "pl", "plPrivate")).ToNot(BeNil())
 		})
 
@@ -207,9 +214,9 @@ var _ = Describe("Housekeeping", func() {
 			seedEntities()
 			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, "stale-fingerprint")).To(Succeed())
 
-			did, err := backfill(ctx, ds)
+			s, err := backfill(ctx, ds, noAgents)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(did).To(BeTrue())
+			Expect(s.Ran).To(BeTrue())
 
 			Expect(queueRepo.callKinds).ToNot(BeEmpty())
 			firstOther := slices.IndexFunc(queueRepo.callKinds, func(k string) bool { return k != "ar" })
@@ -224,6 +231,22 @@ var _ = Describe("Housekeeping", func() {
 				Expect(it.ItemKind).To(BeElementOf("ar", "al", "pl", "ra"))
 			}
 		})
+
+		It("reports what it enqueued, per kind and as an external-lookup ceiling", func() {
+			conf.Server.ArtistArtPriority = "artist.*, external"
+			conf.Server.CoverArtPriority = "cover.*, external"
+			conf.Server.EnableM3UExternalAlbumArt = false
+			seedEntities()
+
+			s, err := backfill(ctx, ds, func() ImageAgentCount { return ImageAgentCount{Artist: 3, Album: 2} })
+			Expect(err).ToNot(HaveOccurred())
+			Expect(s.Ran).To(BeTrue())
+
+			Expect(s.PerKind).To(Equal(map[string]int64{"ar": 2, "al": 1, "pl": 1, "ra": 1}))
+			Expect(s.Items).To(Equal(int64(5)))
+			// 2 artists x 3 agents, 1 album x 2, 1 playlist grid x 2, and radios never fetch.
+			Expect(s.MaxExternalLookups).To(Equal(int64(6 + 2 + PlaylistGridSamples*2)))
+		})
 	})
 
 	Describe("EnqueueStaleAbsentAll", func() {
diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
index f42beb9f1..6663679fa 100644
--- a/core/artwork/resolve.go
+++ b/core/artwork/resolve.go
@@ -137,6 +137,15 @@ func MayFetchExternal(kind model.Kind) bool {
 // ImageAgentCount is how many enabled agents provide artist and album images.
 type ImageAgentCount struct{ Artist, Album int }
 
+// NewImageAgentCount counts what an external step would consult, so an estimate and the gate that
+// guards it cannot disagree about which agents exist.
+func NewImageAgentCount(ag *agents.Agents) ImageAgentCount {
+	if ag == nil {
+		return ImageAgentCount{}
+	}
+	return ImageAgentCount{Artist: len(ag.ArtistImageAgents()), Album: len(ag.AlbumImageAgents())}
+}
+
 // ExternalLookupsPerItem reports what resolving one item of this kind can cost: every image agent is
 // tried, and a zero count still bills one, so agents the caller cannot see never read as free.
 func ExternalLookupsPerItem(kind model.Kind, agents ImageAgentCount) int64 {
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index 0f947f6d7..0358708c0 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -40,6 +40,7 @@ type drainPool struct {
 // independently, and pruneMu serializes prune against the store-write window.
 type Worker struct {
 	proc    *processor
+	agents  *agents.Agents
 	cache   cache.FileCache
 	ffmpeg  ffmpeg.FFmpeg
 	broker  events.Broker
@@ -54,6 +55,7 @@ type Worker struct {
 func NewWorker(ds model.DataStore, store *ImageStore, ag *agents.Agents, ffmpeg ffmpeg.FFmpeg, broker events.Broker, imgCache cache.FileCache) *Worker {
 	w := &Worker{
 		proc:   &processor{ds: ds, store: store},
+		agents: ag,
 		cache:  imgCache,
 		ffmpeg: ffmpeg,
 		broker: broker,
@@ -132,9 +134,10 @@ func (w *Worker) RunPrune(ctx context.Context) error {
 }
 
 // Backfill enqueues every entity for re-resolution when the artwork config fingerprint changed,
-// artists first. It reports whether anything was enqueued.
+// artists first. It reports whether the backfill ran.
 func (w *Worker) Backfill(ctx context.Context) (bool, error) {
-	return backfill(ctx, w.proc.ds)
+	s, err := backfill(ctx, w.proc.ds, func() ImageAgentCount { return NewImageAgentCount(w.agents) })
+	return s.Ran, err
 }
 
 // EnqueueStaleAbsentAll requeues known-absent entries older than StaleAbsentAge, at most

From 59810c3d59af724f46c73fd8add72ec5cde1776e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 22 Aug 2026 20:36:24 -0400
Subject: [PATCH 068/200] feat(jellyfin): non-expiring, audience-scoped tokens
 revocable by password change (#6013)

* feat(auth): add per-user token_epoch column and bump method

* feat(auth): add aud and ep claims, omitted when zero

* feat(auth): add CreateAPIToken for non-expiring, audience-scoped tokens

* feat(auth): add CheckClaims for epoch and audience validation

* feat(jellyfin): issue non-expiring, jellyfin-scoped access tokens

* fix(subsonic): reject API-scoped and revoked tokens on the jwt path

* fix(server): reject API-scoped and revoked tokens on the native API

* fix(server): pin the token-subject guard and stop leaking test config

Adds a regression spec for the DevAutoLogin/ExtAuth guard in
tokenAllowed, switches its comparison to case-insensitive to match
the user lookup's own COLLATE NOCASE semantics, and restores Subsonic
JWT test config after each spec instead of leaking SessionTimeout.

* feat(request): add a token epoch holder for handler-to-middleware signalling

* refactor(server): write the refreshed JWT header after the handler runs

* feat(auth): revoke all tokens for a user when their password changes

* fix(server): restore Unwrap on the JWT refresh writer so SSE write deadlines apply

* test(auth): pin that non-session tokens reject API access tokens

* test(jellyfin): pin token scoping and epoch revocation end to end

Exercises auth.CreateAPIToken and CheckClaims against the real Jellyfin
router and SQLite DB: the minted token has no exp and is aud-scoped to
jellyfin, and bumping token_epoch through the real UserRepository revokes
an already-issued token on the next protected request.

* test(nativeapi): pin the token-epoch handoff through a real password-change request

Drive a self password change through the real Authenticator/JWTRefresher
chain and a real SQLite-backed userRepository, so the epoch handoff between
Put and the refreshed-token writer is verified end to end, not as two
separately-tested halves. Also fix tokenAllowed to read the enriched ctx it
was given instead of r.Context(), so its warning log carries the username.

* refactor(server): drop tokenAllowed's now-unused request parameter

Finding-2 already moved every use to ctx; r was dead weight. Also note
in the new nativeapi test why it must stay the package's only real-DB
spec: db.Db() is a process-wide singleton its cleanup closes for good.

* refactor(auth): remove duplication in claim decoding and token minting

* refactor(auth): group aud with the standard JWT claims

* refactor(auth): read aud with the standard-claim accessor pattern

* fix(log): redact every api_key spelling the Jellyfin API accepts

* fix(auth): bind session tokens to the user id, not just the username

* fix(auth): return the token epoch from the same atomic increment

* fix(auth): bump the token epoch in the same statement as the password write

* chore(auth): trim comments to the why-only budget
---
 adapters/lastfm/auth_router_test.go           |   9 +
 core/auth/auth.go                             |  59 ++++++-
 core/auth/auth_test.go                        | 109 ++++++++++++
 core/auth/claims.go                           |  32 +++-
 core/auth/claims_test.go                      |  40 +++++
 core/stream/token_test.go                     |  10 ++
 .../20260822062750_add_user_token_epoch.sql   |   7 +
 log/log.go                                    |   5 +-
 log/log_test.go                               |  11 ++
 model/request/request.go                      |  49 +++++-
 model/request/request_suite_test.go           |  17 ++
 model/request/request_test.go                 |  40 +++++
 model/user.go                                 |   2 +
 persistence/user_repository.go                |  35 +++-
 persistence/user_repository_test.go           | 157 ++++++++++++++++++
 server/auth.go                                |  94 +++++++++--
 server/auth_test.go                           | 135 +++++++++++++++
 server/jellyfin/README.md                     |   2 +
 server/jellyfin/auth.go                       |   2 +-
 server/jellyfin/e2e/auth_test.go              |  37 +++++
 server/jellyfin/middlewares.go                |   4 +
 server/jellyfin/middlewares_test.go           |  46 +++++
 .../user_password_token_refresh_test.go       |  80 +++++++++
 server/subsonic/middlewares.go                |   4 +-
 server/subsonic/middlewares_test.go           |  31 ++++
 25 files changed, 971 insertions(+), 46 deletions(-)
 create mode 100644 db/migrations/20260822062750_add_user_token_epoch.sql
 create mode 100644 model/request/request_suite_test.go
 create mode 100644 model/request/request_test.go
 create mode 100644 server/nativeapi/user_password_token_refresh_test.go

diff --git a/adapters/lastfm/auth_router_test.go b/adapters/lastfm/auth_router_test.go
index 4cbbd4298..1f65c059e 100644
--- a/adapters/lastfm/auth_router_test.go
+++ b/adapters/lastfm/auth_router_test.go
@@ -214,5 +214,14 @@ var _ = Describe("auth_router", func() {
 			_, err = verifyLinkToken(nonExpiringToken)
 			Expect(err).To(MatchError("link token missing expiration"))
 		})
+
+		It("rejects a Jellyfin access token", func() {
+			usr := &model.User{ID: "u1", UserName: "johndoe"}
+			tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
+			Expect(err).ToNot(HaveOccurred())
+
+			_, err = verifyLinkToken(tokenStr)
+			Expect(err).To(HaveOccurred())
+		})
 	})
 })
diff --git a/core/auth/auth.go b/core/auth/auth.go
index b1e2667bd..b36bb2696 100644
--- a/core/auth/auth.go
+++ b/core/auth/auth.go
@@ -4,6 +4,8 @@ import (
 	"cmp"
 	"context"
 	"crypto/sha256"
+	"errors"
+	"slices"
 	"sync"
 	"time"
 
@@ -26,6 +28,13 @@ var (
 	PublicTokenAuth *jwtauth.JWTAuth
 )
 
+// Audiences a session token can be scoped to. A token with no audience is accepted anywhere.
+const (
+	AudienceJellyfin = "jellyfin"
+	AudienceSubsonic = "subsonic"
+	AudienceNative   = "native"
+)
+
 // Init creates the JWTAuth objects from the secrets stored in the DB.
 // Missing or undecryptable secrets are regenerated and stored.
 func Init(ds model.DataStore) {
@@ -66,15 +75,20 @@ func CreateExpiringPublicToken(exp time.Time, claims Claims) (string, error) {
 	return token, err
 }
 
-func CreateToken(u *model.User) (string, error) {
-	claims := Claims{
+func userClaims(u *model.User, audience []string) Claims {
+	return Claims{
 		Issuer:   consts.JWTIssuer,
 		Subject:  u.UserName,
 		IssuedAt: time.Now(),
 		UserID:   u.ID,
 		IsAdmin:  u.IsAdmin,
+		Epoch:    u.TokenEpoch,
+		Audience: audience,
 	}
-	token, _, err := TokenAuth.Encode(claims.ToMap())
+}
+
+func CreateToken(u *model.User) (string, error) {
+	token, _, err := TokenAuth.Encode(userClaims(u, nil).ToMap())
 	if err != nil {
 		return "", err
 	}
@@ -82,10 +96,20 @@ func CreateToken(u *model.User) (string, error) {
 	return TouchToken(token)
 }
 
+// CreateAPIToken mints a non-expiring token scoped to one API, matching how Jellyfin
+// clients expect tokens to behave. Revocation is by token epoch, not expiry.
+func CreateAPIToken(u *model.User, audience string) (string, error) {
+	_, token, err := TokenAuth.Encode(userClaims(u, []string{audience}).ToMap())
+	return token, err
+}
+
 func TouchToken(token jwt.Token) (string, error) {
-	claims := ClaimsFromToken(token).
-		WithExpiresAt(time.Now().UTC().Add(conf.Server.SessionTimeout))
-	_, newToken, err := TokenAuth.Encode(claims.ToMap())
+	return TouchClaims(ClaimsFromToken(token))
+}
+
+func TouchClaims(c Claims) (string, error) {
+	c = c.WithExpiresAt(time.Now().UTC().Add(conf.Server.SessionTimeout))
+	_, newToken, err := TokenAuth.Encode(c.ToMap())
 	return newToken, err
 }
 
@@ -106,6 +130,29 @@ func ValidatePublic(tokenStr string) (Claims, error) {
 	return ClaimsFromToken(token), nil
 }
 
+var (
+	ErrTokenRevoked  = errors.New("token revoked")
+	ErrWrongAudience = errors.New("token not valid for this API")
+	ErrWrongUser     = errors.New("token issued for a different user")
+)
+
+// CheckClaims gates a session token against the user it names. Callers must have already
+// verified the signature; this adds revocation and API scoping on top.
+func CheckClaims(c Claims, usr model.User, audience string) error {
+	// Usernames can be reused: deleting a user and recreating the name yields a new random id
+	// at epoch 0, which an old token would otherwise match.
+	if c.UserID != "" && c.UserID != usr.ID {
+		return ErrWrongUser
+	}
+	if c.Epoch != usr.TokenEpoch {
+		return ErrTokenRevoked
+	}
+	if len(c.Audience) > 0 && !slices.Contains(c.Audience, audience) {
+		return ErrWrongAudience
+	}
+	return nil
+}
+
 func WithAdminUser(ctx context.Context, ds model.DataStore) context.Context {
 	u, err := ds.User(ctx).FindFirstAdmin()
 	if err != nil {
diff --git a/core/auth/auth_test.go b/core/auth/auth_test.go
index e5cbb2352..c86dcd08c 100644
--- a/core/auth/auth_test.go
+++ b/core/auth/auth_test.go
@@ -151,4 +151,113 @@ var _ = Describe("Auth", func() {
 			Expect(decodedClaims.ExpiresAt.Sub(yesterday)).To(BeNumerically(">=", oneDay))
 		})
 	})
+
+	Describe("CreateAPIToken", func() {
+		var usr *model.User
+
+		BeforeEach(func() {
+			usr = &model.User{ID: "123", UserName: "johndoe", TokenEpoch: 4}
+		})
+
+		It("does not expire", func() {
+			tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
+			Expect(err).ToNot(HaveOccurred())
+
+			claims, err := auth.Validate(tokenStr)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(claims.ExpiresAt.IsZero()).To(BeTrue())
+		})
+
+		It("carries the audience and the user's epoch", func() {
+			tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
+			Expect(err).ToNot(HaveOccurred())
+
+			claims, err := auth.Validate(tokenStr)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(claims.Audience).To(Equal([]string{"jellyfin"}))
+			Expect(claims.Epoch).To(Equal(4))
+			Expect(claims.Subject).To(Equal("johndoe"))
+			Expect(claims.UserID).To(Equal("123"))
+		})
+	})
+
+	Describe("CreateToken with an epoch", func() {
+		It("carries the epoch and still expires", func() {
+			usr := &model.User{ID: "123", UserName: "johndoe", TokenEpoch: 9}
+			tokenStr, err := auth.CreateToken(usr)
+			Expect(err).ToNot(HaveOccurred())
+
+			claims, err := auth.Validate(tokenStr)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(claims.Epoch).To(Equal(9))
+			Expect(claims.Audience).To(BeEmpty())
+			Expect(claims.ExpiresAt).To(BeTemporally(">", time.Now()))
+		})
+	})
+
+	Describe("TouchClaims", func() {
+		It("preserves custom claims and refreshes the expiry", func() {
+			tokenStr, err := auth.TouchClaims(auth.Claims{Subject: "johndoe", UserID: "123", Epoch: 5})
+			Expect(err).ToNot(HaveOccurred())
+
+			claims, err := auth.Validate(tokenStr)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(claims.Epoch).To(Equal(5))
+			Expect(claims.Subject).To(Equal("johndoe"))
+			Expect(claims.ExpiresAt).To(BeTemporally(">", time.Now()))
+		})
+	})
+
+	Describe("CheckClaims", func() {
+		usr := model.User{ID: "123", UserName: "johndoe", TokenEpoch: 2}
+
+		It("accepts a matching epoch and audience", func() {
+			c := auth.Claims{Epoch: 2, Audience: []string{auth.AudienceJellyfin}}
+			Expect(auth.CheckClaims(c, usr, auth.AudienceJellyfin)).To(Succeed())
+		})
+
+		It("accepts a token with no audience on any API", func() {
+			c := auth.Claims{Epoch: 2}
+			Expect(auth.CheckClaims(c, usr, auth.AudienceNative)).To(Succeed())
+			Expect(auth.CheckClaims(c, usr, auth.AudienceJellyfin)).To(Succeed())
+			Expect(auth.CheckClaims(c, usr, auth.AudienceSubsonic)).To(Succeed())
+		})
+
+		It("rejects a stale epoch", func() {
+			c := auth.Claims{Epoch: 1, Audience: []string{auth.AudienceJellyfin}}
+			Expect(auth.CheckClaims(c, usr, auth.AudienceJellyfin)).To(MatchError(auth.ErrTokenRevoked))
+		})
+
+		It("rejects a token minted for another API", func() {
+			c := auth.Claims{Epoch: 2, Audience: []string{auth.AudienceJellyfin}}
+			Expect(auth.CheckClaims(c, usr, auth.AudienceNative)).To(MatchError(auth.ErrWrongAudience))
+			Expect(auth.CheckClaims(c, usr, auth.AudienceSubsonic)).To(MatchError(auth.ErrWrongAudience))
+		})
+
+		It("accepts a multi-audience token that includes this API", func() {
+			c := auth.Claims{Epoch: 2, Audience: []string{"other", auth.AudienceNative}}
+			Expect(auth.CheckClaims(c, usr, auth.AudienceNative)).To(Succeed())
+		})
+
+		It("accepts a pre-upgrade token against a never-bumped user", func() {
+			fresh := model.User{ID: "456", UserName: "newbie"}
+			Expect(auth.CheckClaims(auth.Claims{}, fresh, auth.AudienceNative)).To(Succeed())
+		})
+
+		It("accepts a token whose user id matches", func() {
+			c := auth.Claims{UserID: "123", Epoch: 2}
+			Expect(auth.CheckClaims(c, usr, auth.AudienceNative)).To(Succeed())
+		})
+
+		It("rejects a token for a deleted user recreated under the same name", func() {
+			recreated := model.User{ID: "new-random-id", UserName: "johndoe"}
+			c := auth.Claims{UserID: "123", Audience: []string{auth.AudienceJellyfin}}
+			Expect(auth.CheckClaims(c, recreated, auth.AudienceJellyfin)).To(MatchError(auth.ErrWrongUser))
+		})
+
+		It("accepts a token that carries no user id", func() {
+			fresh := model.User{ID: "456", UserName: "newbie"}
+			Expect(auth.CheckClaims(auth.Claims{}, fresh, auth.AudienceNative)).To(Succeed())
+		})
+	})
 })
diff --git a/core/auth/claims.go b/core/auth/claims.go
index c7e6f02fe..42f7e4f2f 100644
--- a/core/auth/claims.go
+++ b/core/auth/claims.go
@@ -11,7 +11,8 @@ import (
 type Claims struct {
 	// Standard JWT claims
 	Issuer    string
-	Subject   string // username for session tokens
+	Subject   string   // username for session tokens
+	Audience  []string // which API may accept this token; empty means any
 	IssuedAt  time.Time
 	ExpiresAt time.Time
 
@@ -22,6 +23,7 @@ type Claims struct {
 	Format  string // "f" - audio format
 	BitRate int    // "b" - audio bitrate
 	ShareID string // "sid" - share ID for share stream tokens
+	Epoch   int    // "ep" - the user's token_epoch at mint time
 }
 
 // ToMap converts Claims to a map[string]any for use with TokenAuth.Encode().
@@ -34,6 +36,9 @@ func (c Claims) ToMap() map[string]any {
 	if c.Subject != "" {
 		m[jwt.SubjectKey] = c.Subject
 	}
+	if len(c.Audience) > 0 {
+		m[jwt.AudienceKey] = c.Audience
+	}
 	if !c.IssuedAt.IsZero() {
 		m[jwt.IssuedAtKey] = c.IssuedAt.UTC().Unix()
 	}
@@ -58,6 +63,9 @@ func (c Claims) ToMap() map[string]any {
 	if c.ShareID != "" {
 		m["sid"] = c.ShareID
 	}
+	if c.Epoch != 0 {
+		m["ep"] = c.Epoch
+	}
 	return m
 }
 
@@ -73,6 +81,7 @@ func ClaimsFromToken(token jwt.Token) Claims {
 	c.Subject, _ = token.Subject()
 	c.IssuedAt, _ = token.IssuedAt()
 	c.ExpiresAt, _ = token.Expiration()
+	c.Audience, _ = token.Audience()
 
 	var uid string
 	if err := token.Get("uid", &uid); err == nil {
@@ -90,15 +99,24 @@ func ClaimsFromToken(token jwt.Token) Claims {
 	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)
-		}
-	}
+	c.BitRate = intClaim(token, "b")
 	var sid string
 	if err := token.Get("sid", &sid); err == nil {
 		c.ShareID = sid
 	}
+	c.Epoch = intClaim(token, "ep")
 	return c
 }
+
+// intClaim reads a numeric claim, which a parsed token may decode as either int or float64.
+func intClaim(token jwt.Token, key string) int {
+	var i int
+	if err := token.Get(key, &i); err == nil {
+		return i
+	}
+	var f float64
+	if err := token.Get(key, &f); err == nil {
+		return int(f)
+	}
+	return 0
+}
diff --git a/core/auth/claims_test.go b/core/auth/claims_test.go
index 8820fd295..69d054031 100644
--- a/core/auth/claims_test.go
+++ b/core/auth/claims_test.go
@@ -105,4 +105,44 @@ var _ = Describe("Claims", func() {
 		})
 	})
 
+	Describe("Audience and Epoch claims", func() {
+		It("omits both when zero", func() {
+			m := auth.Claims{ID: "artwork-id"}.ToMap()
+			Expect(m).ToNot(HaveKey("aud"))
+			Expect(m).ToNot(HaveKey("ep"))
+		})
+
+		It("includes them when set", func() {
+			m := auth.Claims{Subject: "u", Epoch: 3, Audience: []string{"jellyfin"}}.ToMap()
+			Expect(m).To(HaveKeyWithValue("ep", 3))
+			Expect(m).To(HaveKeyWithValue("aud", []string{"jellyfin"}))
+		})
+
+		It("round-trips through a signed token", func() {
+			tokenAuth := jwtauth.New("HS256", []byte("test-secret"), nil)
+			_, tokenStr, err := tokenAuth.Encode(auth.Claims{
+				Subject: "u", Epoch: 7, Audience: []string{"jellyfin"},
+			}.ToMap())
+			Expect(err).ToNot(HaveOccurred())
+
+			token, err := jwtauth.VerifyToken(tokenAuth, tokenStr)
+			Expect(err).ToNot(HaveOccurred())
+			claims := auth.ClaimsFromToken(token)
+			Expect(claims.Epoch).To(Equal(7))
+			Expect(claims.Audience).To(Equal([]string{"jellyfin"}))
+		})
+
+		It("reads a token that has neither claim", func() {
+			tokenAuth := jwtauth.New("HS256", []byte("test-secret"), nil)
+			_, tokenStr, err := tokenAuth.Encode(auth.Claims{Subject: "u"}.ToMap())
+			Expect(err).ToNot(HaveOccurred())
+
+			token, err := jwtauth.VerifyToken(tokenAuth, tokenStr)
+			Expect(err).ToNot(HaveOccurred())
+			claims := auth.ClaimsFromToken(token)
+			Expect(claims.Epoch).To(BeZero())
+			Expect(claims.Audience).To(BeEmpty())
+		})
+	})
+
 })
diff --git a/core/stream/token_test.go b/core/stream/token_test.go
index 7409a7532..4f0d8066c 100644
--- a/core/stream/token_test.go
+++ b/core/stream/token_test.go
@@ -232,6 +232,16 @@ var _ = Describe("Token", func() {
 			_, err := svc.ResolveRequestFromToken(ctx, token, mf, 0)
 			Expect(err).To(MatchError(ErrTokenStale))
 		})
+
+		It("rejects a Jellyfin access token", func() {
+			mf := &model.MediaFile{ID: "song-1", UpdatedAt: sourceTime}
+			usr := &model.User{ID: "u1", UserName: "johndoe"}
+			tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
+			Expect(err).ToNot(HaveOccurred())
+
+			_, err = svc.ResolveRequestFromToken(ctx, tokenStr, mf, 0)
+			Expect(err).To(MatchError(ErrTokenInvalid))
+		})
 	})
 
 	Describe("paramsFromToken", func() {
diff --git a/db/migrations/20260822062750_add_user_token_epoch.sql b/db/migrations/20260822062750_add_user_token_epoch.sql
new file mode 100644
index 000000000..bd37ddeb4
--- /dev/null
+++ b/db/migrations/20260822062750_add_user_token_epoch.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+
+ALTER TABLE user ADD COLUMN token_epoch INTEGER NOT NULL DEFAULT 0;
+
+-- +goose Down
+
+ALTER TABLE user DROP COLUMN token_epoch;
diff --git a/log/log.go b/log/log.go
index 1c4ee3b4b..f7977c0fa 100644
--- a/log/log.go
+++ b/log/log.go
@@ -47,8 +47,9 @@ var redacted = &Hook{
 
 		// External services query params. Values can be JWTs (dots, dashes), so match everything up
 		// to the next query separator or whitespace, not just word chars. A [\w]+ class would stop
-		// at a JWT's first '.' and leak its payload and signature.
-		"([^\\w]api_key=)[^&\\s]+",
+		// at a JWT's first '.' and leak its payload and signature. Case-insensitive with an
+		// optional underscore: the API accepts api_key, apikey and ApiKey alike.
+		"(?i)([^\\w]api_?key=)[^&\\s]+",
 	},
 }
 
diff --git a/log/log_test.go b/log/log_test.go
index 7b6ecfc32..f0e2e0eae 100644
--- a/log/log_test.go
+++ b/log/log_test.go
@@ -264,5 +264,16 @@ var _ = Describe("Logger", func() {
 			msg := "/jellyfin/Audio/abc/universal?static=true&api_key=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiJ9.c2ln-X_1&other=1"
 			Expect(Redact(msg)).To(Equal("/jellyfin/Audio/abc/universal?static=true&api_key=[REDACTED]&other=1"))
 		})
+
+		DescribeTable("redacts every api_key spelling the Jellyfin API accepts",
+			func(param string) {
+				msg := "/jellyfin/Audio/abc/File?" + param + "=SECRET&other=1"
+				Expect(Redact(msg)).To(Equal("/jellyfin/Audio/abc/File?" + param + "=[REDACTED]&other=1"))
+			},
+			Entry("api_key", "api_key"),
+			Entry("apikey", "apikey"),
+			Entry("ApiKey", "ApiKey"),
+			Entry("APIKEY", "APIKEY"),
+		)
 	})
 })
diff --git a/model/request/request.go b/model/request/request.go
index 8d7919298..2b1cfb9ef 100644
--- a/model/request/request.go
+++ b/model/request/request.go
@@ -2,6 +2,7 @@ package request
 
 import (
 	"context"
+	"sync/atomic"
 
 	"github.com/navidrome/navidrome/model"
 )
@@ -9,15 +10,16 @@ import (
 type contextKey string
 
 const (
-	User           = contextKey("user")
-	Username       = contextKey("username")
-	Client         = contextKey("client")
-	Version        = contextKey("version")
-	Player         = contextKey("player")
-	Transcoding    = contextKey("transcoding")
-	ClientUniqueId = contextKey("clientUniqueId")
-	ReverseProxyIp = contextKey("reverseProxyIp")
-	InternalAuth   = contextKey("internalAuth") // Used for internal API calls, e.g., from the plugins
+	User             = contextKey("user")
+	Username         = contextKey("username")
+	Client           = contextKey("client")
+	Version          = contextKey("version")
+	Player           = contextKey("player")
+	Transcoding      = contextKey("transcoding")
+	ClientUniqueId   = contextKey("clientUniqueId")
+	ReverseProxyIp   = contextKey("reverseProxyIp")
+	InternalAuth     = contextKey("internalAuth") // Used for internal API calls, e.g., from the plugins
+	TokenEpochHolder = contextKey("tokenEpochHolder")
 )
 
 var allKeys = []contextKey{
@@ -125,3 +127,32 @@ func AddValues(ctx, requestCtx context.Context) context.Context {
 	}
 	return ctx
 }
+
+type tokenEpochHolder struct {
+	value atomic.Int64
+}
+
+// WithTokenEpochHolder installs a slot a handler can use to report a bumped token epoch
+// back to middleware that has already returned from the handler's perspective.
+func WithTokenEpochHolder(ctx context.Context) context.Context {
+	h := &tokenEpochHolder{}
+	h.value.Store(-1)
+	return context.WithValue(ctx, TokenEpochHolder, h)
+}
+
+func SetTokenEpoch(ctx context.Context, epoch int) {
+	if h, ok := ctx.Value(TokenEpochHolder).(*tokenEpochHolder); ok {
+		h.value.Store(int64(epoch))
+	}
+}
+
+func TokenEpochFrom(ctx context.Context) (int, bool) {
+	h, ok := ctx.Value(TokenEpochHolder).(*tokenEpochHolder)
+	if !ok {
+		return 0, false
+	}
+	if v := h.value.Load(); v >= 0 {
+		return int(v), true
+	}
+	return 0, false
+}
diff --git a/model/request/request_suite_test.go b/model/request/request_suite_test.go
new file mode 100644
index 000000000..643ca76d7
--- /dev/null
+++ b/model/request/request_suite_test.go
@@ -0,0 +1,17 @@
+package request
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// tests.Init is not used here: the tests package imports model/request, so importing it
+// back would create an import cycle.
+func TestRequest(t *testing.T) {
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Request Suite")
+}
diff --git a/model/request/request_test.go b/model/request/request_test.go
new file mode 100644
index 000000000..ef9af8231
--- /dev/null
+++ b/model/request/request_test.go
@@ -0,0 +1,40 @@
+package request
+
+import (
+	"context"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Token epoch holder", func() {
+	It("reports nothing when unset", func() {
+		ctx := WithTokenEpochHolder(context.TODO())
+		_, ok := TokenEpochFrom(ctx)
+		Expect(ok).To(BeFalse())
+	})
+
+	It("round-trips a value set by the handler", func() {
+		ctx := WithTokenEpochHolder(context.TODO())
+		SetTokenEpoch(ctx, 7)
+
+		epoch, ok := TokenEpochFrom(ctx)
+		Expect(ok).To(BeTrue())
+		Expect(epoch).To(Equal(7))
+	})
+
+	It("survives being wrapped in a derived context", func() {
+		ctx := WithTokenEpochHolder(context.TODO())
+		SetTokenEpoch(context.WithValue(ctx, contextKey("unrelated"), 1), 3)
+
+		epoch, ok := TokenEpochFrom(ctx)
+		Expect(ok).To(BeTrue())
+		Expect(epoch).To(Equal(3))
+	})
+
+	It("is a no-op with no holder installed", func() {
+		Expect(func() { SetTokenEpoch(context.TODO(), 5) }).ToNot(Panic())
+		_, ok := TokenEpochFrom(context.TODO())
+		Expect(ok).To(BeFalse())
+	})
+})
diff --git a/model/user.go b/model/user.go
index b6f792c9a..37bdca33d 100644
--- a/model/user.go
+++ b/model/user.go
@@ -22,6 +22,8 @@ type User struct {
 
 	// This is only available on the backend, and it is never sent over the wire
 	Password string `structs:"-" json:"-"`
+	// Bumped on password change to invalidate every issued token for this user.
+	TokenEpoch int `structs:"-" json:"-"`
 	// This is used to set or change a password when calling Put. If it is empty, the password is not changed.
 	// It is received from the UI with the name "password"
 	NewPassword string `structs:"password,omitempty" json:"password,omitempty"` //nolint:gosec
diff --git a/persistence/user_repository.go b/persistence/user_repository.go
index 3c030a640..9de37876b 100644
--- a/persistence/user_repository.go
+++ b/persistence/user_repository.go
@@ -18,6 +18,7 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/utils"
 	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/pocketbase/dbx"
@@ -126,14 +127,30 @@ func (r *userRepository) Put(u *model.User) error {
 	}
 	delete(values, "current_password")
 
-	// Save/update the user
+	// The epoch bump rides the password UPDATE: as two statements they can interleave with a
+	// concurrent change and leave a session valid that the other change should have revoked.
 	update := Update(r.tableName).Where(Eq{"id": u.ID}).SetMap(values)
-	count, err := r.executeSQL(update)
-	if err != nil {
-		return err
+	var isNewUser bool
+	var epoch int
+	if u.NewPassword != "" {
+		var res struct{ TokenEpoch int }
+		err = r.queryOne(update.Set("token_epoch", Expr("token_epoch + 1")).
+			Suffix("RETURNING token_epoch"), &res)
+		switch {
+		case errors.Is(err, model.ErrNotFound):
+			isNewUser = true
+		case err != nil:
+			return err
+		default:
+			epoch = res.TokenEpoch
+		}
+	} else {
+		count, err := r.executeSQL(update)
+		if err != nil {
+			return err
+		}
+		isNewUser = count == 0
 	}
-
-	isNewUser := count == 0
 	if isNewUser {
 		values["created_at"] = time.Now()
 		insert := Insert(r.tableName).SetMap(values)
@@ -163,6 +180,12 @@ func (r *userRepository) Put(u *model.User) error {
 		}
 	}
 
+	// Only the caller's own token can be refreshed in-flight; an admin resetting another
+	// user must keep their own epoch.
+	if u.NewPassword != "" && !isNewUser && loggedUser(r.ctx).ID == u.ID {
+		request.SetTokenEpoch(r.ctx, epoch)
+	}
+
 	return nil
 }
 
diff --git a/persistence/user_repository_test.go b/persistence/user_repository_test.go
index ec417c193..dc519d0a1 100644
--- a/persistence/user_repository_test.go
+++ b/persistence/user_repository_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"slices"
+	"sync"
 
 	"github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
@@ -13,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -683,4 +685,159 @@ var _ = Describe("UserRepository", func() {
 			Expect(query).To(ContainSubstring("user.id = {:p0}"))
 		})
 	})
+
+	Describe("token epoch", func() {
+		var repo model.UserRepository
+		var usr model.User
+
+		newUser := func() model.User {
+			uid := id.NewRandom()
+			// user_name is unique; suffix it so each It gets its own row in the shared suite DB.
+			return model.User{ID: uid, UserName: "epoch-user-" + uid, Name: "Epoch", NewPassword: "hunter2"}
+		}
+
+		BeforeEach(func() {
+			ctx := log.NewContext(context.TODO())
+			ctx = request.WithUser(ctx, model.User{ID: "userid", IsAdmin: true})
+			repo = NewUserRepository(ctx, GetDBXBuilder())
+			usr = newUser()
+			Expect(repo.Put(&usr)).To(Succeed())
+		})
+
+		It("starts at zero for a new user", func() {
+			got, err := repo.Get(usr.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.TokenEpoch).To(Equal(0))
+		})
+
+		It("increments once per password change", func() {
+			usr.NewPassword = "second"
+			Expect(repo.Put(&usr)).To(Succeed())
+			got, err := repo.Get(usr.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.TokenEpoch).To(Equal(1))
+
+			usr.NewPassword = "third"
+			Expect(repo.Put(&usr)).To(Succeed())
+			got, err = repo.Get(usr.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.TokenEpoch).To(Equal(2))
+		})
+
+		It("leaves the epoch alone when the password is untouched", func() {
+			usr.NewPassword = ""
+			usr.Name = "Renamed"
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			got, err := repo.Get(usr.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.TokenEpoch).To(Equal(0))
+			Expect(got.Name).To(Equal("Renamed"))
+		})
+
+		It("never signals the same epoch to two concurrent password changes", func() {
+			// Each writer's epoch must be the one its own UPDATE produced.
+			const callers = 4
+			var mu sync.Mutex
+			var signalled []int
+			var wg sync.WaitGroup
+			for range callers {
+				wg.Go(func() {
+					ctx := log.NewContext(context.TODO())
+					ctx = request.WithUser(ctx, model.User{ID: usr.ID})
+					ctx = request.WithTokenEpochHolder(ctx)
+					own := NewUserRepository(ctx, GetDBXBuilder())
+
+					u := usr
+					u.NewPassword = "concurrent"
+					if err := own.Put(&u); err != nil {
+						return // the shared in-memory test DB can raise SQLITE_LOCKED
+					}
+					epoch, ok := request.TokenEpochFrom(ctx)
+					if !ok {
+						return
+					}
+					mu.Lock()
+					defer mu.Unlock()
+					signalled = append(signalled, epoch)
+				})
+			}
+			wg.Wait()
+
+			Expect(signalled).To(HaveLen(len(slice.Unique(signalled))),
+				"an epoch was signalled to more than one writer: %v", signalled)
+		})
+	})
+
+	Describe("Put and the token epoch", func() {
+		newRepo := func(actingUserID string) model.UserRepository {
+			ctx := log.NewContext(context.TODO())
+			ctx = request.WithUser(ctx, model.User{ID: actingUserID, IsAdmin: true})
+			ctx = request.WithTokenEpochHolder(ctx)
+			return NewUserRepository(ctx, GetDBXBuilder())
+		}
+
+		It("does not bump when creating a user", func() {
+			repo := newRepo("admin")
+			usr := model.User{ID: id.NewRandom(), UserName: "fresh", NewPassword: "pw1"}
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			got, err := repo.Get(usr.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.TokenEpoch).To(Equal(0))
+		})
+
+		It("bumps when the password changes", func() {
+			repo := newRepo("admin")
+			usr := model.User{ID: id.NewRandom(), UserName: "changer", NewPassword: "pw1"}
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			usr.NewPassword = "pw2"
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			got, err := repo.Get(usr.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.TokenEpoch).To(Equal(1))
+		})
+
+		It("does not bump on an edit that leaves the password alone", func() {
+			repo := newRepo("admin")
+			usr := model.User{ID: id.NewRandom(), UserName: "renamer", NewPassword: "pw1"}
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			usr.NewPassword = ""
+			usr.Name = "New Display Name"
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			got, err := repo.Get(usr.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.TokenEpoch).To(Equal(0))
+		})
+
+		It("signals the new epoch when a user changes their own password", func() {
+			userID := id.NewRandom()
+			repo := newRepo(userID)
+			usr := model.User{ID: userID, UserName: "self", NewPassword: "pw1"}
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			usr.NewPassword = "pw2"
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			epoch, ok := request.TokenEpochFrom(repo.(*userRepository).ctx)
+			Expect(ok).To(BeTrue())
+			Expect(epoch).To(Equal(1))
+		})
+
+		It("does not signal when an admin changes someone else's password", func() {
+			repo := newRepo("some-admin")
+			usr := model.User{ID: id.NewRandom(), UserName: "other", NewPassword: "pw1"}
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			usr.NewPassword = "pw2"
+			Expect(repo.Put(&usr)).To(Succeed())
+
+			_, ok := request.TokenEpochFrom(repo.(*userRepository).ctx)
+			Expect(ok).To(BeFalse())
+		})
+	})
 })
diff --git a/server/auth.go b/server/auth.go
index 6a25f1406..37a318a83 100644
--- a/server/auth.go
+++ b/server/auth.go
@@ -12,10 +12,12 @@ import (
 	"net/http"
 	"slices"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/deluan/rest"
 	"github.com/go-chi/jwtauth/v5"
+	"github.com/lestrrat-go/jwx/v3/jwt"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/auth"
@@ -260,7 +262,7 @@ func Authenticator(ds model.DataStore) func(next http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			ctx, err := authenticateRequest(ds, r, UsernameFromConfig, UsernameFromToken, UsernameFromExtAuthHeader)
-			if err != nil {
+			if err != nil || !tokenAllowed(ctx) {
 				_ = rest.RespondWithError(w, http.StatusUnauthorized, "Not authenticated")
 				return
 			}
@@ -270,24 +272,88 @@ func Authenticator(ds model.DataStore) func(next http.Handler) http.Handler {
 	}
 }
 
-// JWTRefresher updates the expiry date of the received JWT token, and add the new one to the Authorization Header
+// tokenAllowed re-checks a JWT that actually identifies the resolved user. Header and
+// config auth carry no token, so they short-circuit to true.
+func tokenAllowed(ctx context.Context) bool {
+	token, _, err := jwtauth.FromContext(ctx)
+	if err != nil || token == nil {
+		return true
+	}
+	usr, ok := request.UserFrom(ctx)
+	if !ok {
+		return true
+	}
+	claims := auth.ClaimsFromToken(token)
+	if !strings.EqualFold(claims.Subject, usr.UserName) {
+		return true
+	}
+	if err := auth.CheckClaims(claims, usr, auth.AudienceNative); err != nil {
+		log.Warn(ctx, "Native API: rejected token", "user", claims.Subject, err)
+		return false
+	}
+	return true
+}
+
+// refreshingWriter defers the refreshed-token header until the handler's first write, so an
+// epoch the handler bumped reaches the token the client stores.
+type refreshingWriter struct {
+	http.ResponseWriter
+	ctx   context.Context
+	token jwt.Token
+	once  sync.Once
+}
+
+func (w *refreshingWriter) setToken() {
+	w.once.Do(func() {
+		claims := auth.ClaimsFromToken(w.token)
+		if epoch, ok := request.TokenEpochFrom(w.ctx); ok {
+			claims.Epoch = epoch
+		}
+		newToken, err := auth.TouchClaims(claims)
+		if err != nil {
+			log.Error(w.ctx, "Could not sign new token", err)
+			return
+		}
+		w.Header().Set(consts.UIAuthorizationHeader, newToken)
+	})
+}
+
+func (w *refreshingWriter) WriteHeader(code int) {
+	w.setToken()
+	w.ResponseWriter.WriteHeader(code)
+}
+
+func (w *refreshingWriter) Write(b []byte) (int, error) {
+	w.setToken()
+	return w.ResponseWriter.Write(b)
+}
+
+// Flush keeps the SSE events route working through the wrap.
+func (w *refreshingWriter) Flush() {
+	w.setToken()
+	if f, ok := w.ResponseWriter.(http.Flusher); ok {
+		f.Flush()
+	}
+}
+
+// Unwrap lets capability lookups, such as SSE's write deadline, see past this wrap.
+func (w *refreshingWriter) Unwrap() http.ResponseWriter {
+	return w.ResponseWriter
+}
+
+// JWTRefresher updates the expiry date of the received JWT token, and adds the new one to
+// the Authorization Header.
 func JWTRefresher(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		ctx := r.Context()
-		token, _, err := jwtauth.FromContext(ctx)
-		if err != nil {
+		token, _, err := jwtauth.FromContext(r.Context())
+		if err != nil || token == nil {
 			next.ServeHTTP(w, r)
 			return
 		}
-		newTokenString, err := auth.TouchToken(token)
-		if err != nil {
-			log.Error(r, "Could not sign new token", err)
-			_ = rest.RespondWithError(w, http.StatusUnauthorized, "Not authenticated")
-			return
-		}
-
-		w.Header().Set(consts.UIAuthorizationHeader, newTokenString)
-		next.ServeHTTP(w, r)
+		ctx := request.WithTokenEpochHolder(r.Context())
+		rw := &refreshingWriter{ResponseWriter: w, ctx: ctx, token: token}
+		next.ServeHTTP(rw, r.WithContext(ctx))
+		rw.setToken()
 	})
 }
 
diff --git a/server/auth_test.go b/server/auth_test.go
index f6af6f0d6..e021c82a8 100644
--- a/server/auth_test.go
+++ b/server/auth_test.go
@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/model"
@@ -342,4 +343,138 @@ var _ = Describe("Auth", func() {
 			Expect(u.IsAdmin).To(BeFalse())
 		})
 	})
+
+	Describe("Authenticator token gating", func() {
+		var ds *tests.MockDataStore
+		var usr *model.User
+
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.SessionTimeout = time.Hour
+			ds = &tests.MockDataStore{}
+			auth.Init(ds)
+			ur := ds.User(context.TODO()).(*tests.MockedUserRepo)
+			usr = &model.User{ID: "u1", UserName: "johndoe", NewPassword: "pw", TokenEpoch: 2}
+			Expect(ur.Put(usr)).To(Succeed())
+		})
+
+		serve := func(token string) *httptest.ResponseRecorder {
+			r := httptest.NewRequest("GET", "/api/song", nil)
+			r.Header.Set(consts.UIAuthorizationHeader, "Bearer "+token)
+			w := httptest.NewRecorder()
+			handler := JWTVerifier(Authenticator(ds)(http.HandlerFunc(
+				func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusOK) },
+			)))
+			handler.ServeHTTP(w, r)
+			return w
+		}
+
+		It("accepts a current session token", func() {
+			tokenStr, err := auth.CreateToken(usr)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusOK))
+		})
+
+		It("rejects a jellyfin-scoped token", func() {
+			tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusUnauthorized))
+		})
+
+		It("rejects a token with a stale epoch", func() {
+			tokenStr, err := auth.CreateToken(usr)
+			Expect(err).ToNot(HaveOccurred())
+			usr.TokenEpoch = 3
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusUnauthorized))
+		})
+
+		It("ignores a stray token for someone else when config auto-login resolves the user", func() {
+			conf.Server.DevAutoLoginUsername = usr.UserName
+			tokenStr, err := auth.CreateToken(&model.User{UserName: "someone-else"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusOK))
+		})
+
+		It("rejects a stale-epoch token whose subject differs only in case from the resolved user", func() {
+			tokenStr, err := auth.CreateToken(&model.User{UserName: strings.ToUpper(usr.UserName), TokenEpoch: usr.TokenEpoch})
+			Expect(err).ToNot(HaveOccurred())
+			usr.TokenEpoch = 5
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusUnauthorized))
+		})
+	})
+
+	Describe("JWTRefresher", func() {
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			// TouchClaims reads this; left at zero every refreshed token is born expired.
+			conf.Server.SessionTimeout = time.Hour
+			auth.Init(&tests.MockDataStore{})
+		})
+
+		serveWith := func(handler http.HandlerFunc) *httptest.ResponseRecorder {
+			usr := model.User{ID: "u1", UserName: "johndoe", TokenEpoch: 1}
+			tokenStr, err := auth.CreateToken(&usr)
+			Expect(err).ToNot(HaveOccurred())
+
+			r := httptest.NewRequest("GET", "/api/song", nil)
+			r.Header.Set(consts.UIAuthorizationHeader, "Bearer "+tokenStr)
+			w := httptest.NewRecorder()
+			JWTVerifier(JWTRefresher(handler)).ServeHTTP(w, r)
+			return w
+		}
+
+		It("writes a refreshed token when the handler writes a body", func() {
+			w := serveWith(func(w http.ResponseWriter, _ *http.Request) {
+				_, _ = w.Write([]byte("ok"))
+			})
+			Expect(w.Header().Get(consts.UIAuthorizationHeader)).ToNot(BeEmpty())
+		})
+
+		It("writes a refreshed token when the handler writes no body", func() {
+			w := serveWith(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusNoContent)
+			})
+			Expect(w.Header().Get(consts.UIAuthorizationHeader)).ToNot(BeEmpty())
+		})
+
+		It("picks up an epoch the handler reported", func() {
+			w := serveWith(func(w http.ResponseWriter, r *http.Request) {
+				request.SetTokenEpoch(r.Context(), 42)
+				w.WriteHeader(http.StatusOK)
+			})
+
+			claims, err := auth.Validate(w.Header().Get(consts.UIAuthorizationHeader))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(claims.Epoch).To(Equal(42))
+		})
+
+		It("keeps the original epoch when the handler reports nothing", func() {
+			w := serveWith(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+			})
+
+			claims, err := auth.Validate(w.Header().Get(consts.UIAuthorizationHeader))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(claims.Epoch).To(Equal(1))
+		})
+
+		It("propagates Flush to the underlying ResponseWriter", func() {
+			w := serveWith(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				w.(http.Flusher).Flush()
+			})
+			Expect(w.Flushed).To(BeTrue())
+		})
+
+		It("exposes the underlying ResponseWriter via Unwrap, for http.ResponseController lookups", func() {
+			var unwrapped http.ResponseWriter
+			w := serveWith(func(w http.ResponseWriter, _ *http.Request) {
+				u, ok := w.(interface{ Unwrap() http.ResponseWriter })
+				Expect(ok).To(BeTrue())
+				unwrapped = u.Unwrap()
+				w.WriteHeader(http.StatusOK)
+			})
+			Expect(unwrapped).To(BeIdenticalTo(w))
+		})
+	})
 })
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index dc3219dfa..15b56a499 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -58,6 +58,8 @@ query param — all forms are accepted, matching what different clients do).
 `/auth/login` (`AuthRequestLimit`/`AuthWindowLength`), since it's an unauthenticated brute-force
 surface.
 
+Access tokens do not expire, matching real Jellyfin. They are revoked by a password change, which bumps the user's token epoch.
+
 ### Public user list (login picker)
 
 `GET /Users/Public` lets a client render a login user-picker (tap a user, then just type the
diff --git a/server/jellyfin/auth.go b/server/jellyfin/auth.go
index 062ac6458..e7070d341 100644
--- a/server/jellyfin/auth.go
+++ b/server/jellyfin/auth.go
@@ -36,7 +36,7 @@ func (api *Router) authenticateByName(w http.ResponseWriter, r *http.Request) {
 		log.Error(ctx, "Jellyfin API: could not update last login date", "username", body.Username, err)
 	}
 
-	token, err := auth.CreateToken(usr)
+	token, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
 	if err != nil {
 		api.internalError(w, r, err)
 		return
diff --git a/server/jellyfin/e2e/auth_test.go b/server/jellyfin/e2e/auth_test.go
index 806b0e5e7..156e79ce9 100644
--- a/server/jellyfin/e2e/auth_test.go
+++ b/server/jellyfin/e2e/auth_test.go
@@ -6,6 +6,7 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -61,6 +62,42 @@ var _ = Describe("Authentication", func() {
 		It("rejects a malformed body", func() {
 			Expect(rawReq("POST", "/Users/AuthenticateByName", "not json").Code).To(Equal(http.StatusBadRequest))
 		})
+
+		It("mints a non-expiring token scoped to the Jellyfin audience", func() {
+			w := authenticate("admin", "password")
+			var res dto.AuthenticationResult
+			parseInto(w, &res)
+
+			claims, err := auth.Validate(res.AccessToken)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(claims.ExpiresAt.IsZero()).To(BeTrue())
+			Expect(claims.Audience).To(Equal([]string{"jellyfin"}))
+			Expect(claims.Subject).To(Equal("admin"))
+		})
+
+		It("revokes an already-issued token when the user's epoch is bumped", func() {
+			w := authenticate("admin", "password")
+			var res dto.AuthenticationResult
+			parseInto(w, &res)
+
+			r := httptest.NewRequest("GET", "/Users/Me", nil)
+			r.Header.Set("X-Emby-Token", res.AccessToken)
+			pw := httptest.NewRecorder()
+			router.ServeHTTP(pw, r)
+			Expect(pw.Code).To(Equal(http.StatusOK))
+
+			// A real password change through the repository, which is what revokes in production.
+			admin, err := ds.User(ctx).Get(testID("admin-1"))
+			Expect(err).ToNot(HaveOccurred())
+			admin.NewPassword = "rotated"
+			Expect(ds.User(ctx).Put(admin)).To(Succeed())
+
+			r = httptest.NewRequest("GET", "/Users/Me", nil)
+			r.Header.Set("X-Emby-Token", res.AccessToken)
+			pw = httptest.NewRecorder()
+			router.ServeHTTP(pw, r)
+			Expect(pw.Code).To(Equal(http.StatusUnauthorized))
+		})
 	})
 
 	Describe("GET /Users/Public", func() {
diff --git a/server/jellyfin/middlewares.go b/server/jellyfin/middlewares.go
index c90f9c088..0ae4f6071 100644
--- a/server/jellyfin/middlewares.go
+++ b/server/jellyfin/middlewares.go
@@ -167,6 +167,10 @@ func (api *Router) userFromToken(r *http.Request) (model.User, bool) {
 		log.Warn(r.Context(), "Jellyfin API: token subject not found", "user", claims.Subject, err)
 		return model.User{}, false
 	}
+	if err := auth.CheckClaims(claims, *usr, auth.AudienceJellyfin); err != nil {
+		log.Warn(r.Context(), "Jellyfin API: rejected token", "user", claims.Subject, err)
+		return model.User{}, false
+	}
 	return *usr, true
 }
 
diff --git a/server/jellyfin/middlewares_test.go b/server/jellyfin/middlewares_test.go
index b17b9a4ec..a3b88799b 100644
--- a/server/jellyfin/middlewares_test.go
+++ b/server/jellyfin/middlewares_test.go
@@ -95,6 +95,52 @@ var _ = Describe("authenticate middleware", func() {
 		api.authenticate(next).ServeHTTP(w, r)
 		Expect(w.Code).To(Equal(http.StatusUnauthorized))
 	})
+
+	Context("token scoping and revocation", func() {
+		var usr *model.User
+
+		BeforeEach(func() {
+			ur := ds.User(context.Background()).(*tests.MockedUserRepo)
+			usr = &model.User{ID: testID("u2"), UserName: "bob", NewPassword: "secret", TokenEpoch: 3}
+			Expect(ur.Put(usr)).To(Succeed())
+		})
+
+		serve := func(token string) *httptest.ResponseRecorder {
+			next := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+			})
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/Items", nil)
+			r.Header.Set("X-Emby-Token", token)
+			api.authenticate(next).ServeHTTP(w, r)
+			return w
+		}
+
+		It("accepts a jellyfin-scoped token with the current epoch", func() {
+			tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusOK))
+		})
+
+		It("rejects a token whose epoch is stale", func() {
+			tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
+			Expect(err).ToNot(HaveOccurred())
+			usr.TokenEpoch = 4
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusUnauthorized))
+		})
+
+		It("rejects a token minted for another API", func() {
+			tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceNative)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusUnauthorized))
+		})
+
+		It("still accepts an unscoped session token", func() {
+			tokenStr, err := auth.CreateToken(usr)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(serve(tokenStr).Code).To(Equal(http.StatusOK))
+		})
+	})
 })
 
 var _ = Describe("withPlayer middleware", func() {
diff --git a/server/nativeapi/user_password_token_refresh_test.go b/server/nativeapi/user_password_token_refresh_test.go
new file mode 100644
index 000000000..32f4b13cb
--- /dev/null
+++ b/server/nativeapi/user_password_token_refresh_test.go
@@ -0,0 +1,80 @@
+package nativeapi
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/db"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
+	"github.com/navidrome/navidrome/server"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type noopPluginUnloader struct{}
+
+func (noopPluginUnloader) UnloadDisabledPlugins(context.Context) {}
+
+// Pins that the token-epoch handoff survives a real request through the real middleware chain.
+var _ = Describe("PUT /user/{id}: token refresh on self password change", func() {
+	var ds model.DataStore
+	var router http.Handler
+
+	BeforeEach(func() {
+		// db.Db() is a process-wide singleton that this DeferCleanup closes for the whole binary; keep this the only real-DB spec in this package.
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.EnableUserEditing = true
+		conf.Server.EnableSharing = false
+		conf.Server.SessionTimeout = time.Hour
+		conf.Server.DbPath = filepath.Join(GinkgoT().TempDir(), "nativeapi-user-refresh.db") + "?_journal_mode=WAL"
+		DeferCleanup(db.Init(GinkgoT().Context()))
+
+		ds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
+		auth.Init(ds)
+
+		userService := core.NewUser(ds, noopPluginUnloader{})
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), userService, nil, nil, nil)
+		router = server.JWTVerifier(nativeRouter)
+	})
+
+	It("carries the bumped epoch in the refreshed token, not the epoch the token was minted with", func() {
+		usr := model.User{UserName: "selfchanger", Name: "Self Changer", NewPassword: "old-password"}
+		Expect(ds.User(GinkgoT().Context()).Put(&usr)).To(Succeed())
+
+		token, err := auth.CreateToken(&usr)
+		Expect(err).ToNot(HaveOccurred())
+
+		body, _ := json.Marshal(map[string]any{
+			"userName":        usr.UserName,
+			"name":            usr.Name,
+			"currentPassword": "old-password",
+			"password":        "new-password",
+		})
+		req := createAuthenticatedRequest(http.MethodPut, "/user/"+usr.ID, bytes.NewBuffer(body), token)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+		Expect(w.Code).To(Equal(http.StatusOK), w.Body.String())
+
+		refreshed := w.Header().Get(consts.UIAuthorizationHeader)
+		Expect(refreshed).ToNot(BeEmpty())
+		claims, err := auth.Validate(refreshed)
+		Expect(err).ToNot(HaveOccurred())
+
+		reloaded, err := ds.User(GinkgoT().Context()).Get(usr.ID)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(reloaded.TokenEpoch).To(Equal(1))
+		Expect(claims.Epoch).To(Equal(reloaded.TokenEpoch))
+	})
+})
diff --git a/server/subsonic/middlewares.go b/server/subsonic/middlewares.go
index 837852d18..6dfa2263f 100644
--- a/server/subsonic/middlewares.go
+++ b/server/subsonic/middlewares.go
@@ -178,7 +178,9 @@ func validateCredentials(user *model.User, pass, token, salt, jwt string) error
 	switch {
 	case jwt != "":
 		claims, err := auth.Validate(jwt)
-		valid = err == nil && claims.Subject == user.UserName
+		valid = err == nil &&
+			claims.Subject == user.UserName &&
+			auth.CheckClaims(claims, *user, auth.AudienceSubsonic) == nil
 	case pass != "":
 		if strings.HasPrefix(pass, "enc:") {
 			if dec, err := hex.DecodeString(pass[4:]); err == nil {
diff --git a/server/subsonic/middlewares_test.go b/server/subsonic/middlewares_test.go
index 3f8c07a56..cb34b92e7 100644
--- a/server/subsonic/middlewares_test.go
+++ b/server/subsonic/middlewares_test.go
@@ -470,6 +470,7 @@ var _ = Describe("Middlewares", func() {
 			var validToken string
 
 			BeforeEach(func() {
+				DeferCleanup(configtest.SetupConfig())
 				conf.Server.SessionTimeout = time.Minute
 				auth.Init(ds)
 
@@ -499,6 +500,36 @@ var _ = Describe("Middlewares", func() {
 				Expect(err).To(MatchError(model.ErrInvalidAuth))
 			})
 		})
+
+		Context("JWT credentials", func() {
+			var usr *model.User
+
+			BeforeEach(func() {
+				DeferCleanup(configtest.SetupConfig())
+				conf.Server.SessionTimeout = time.Minute
+				auth.Init(ds)
+				usr = &model.User{ID: "u1", UserName: "johndoe", TokenEpoch: 1}
+			})
+
+			It("accepts an unscoped session token", func() {
+				tokenStr, err := auth.CreateToken(usr)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(validateCredentials(usr, "", "", "", tokenStr)).To(Succeed())
+			})
+
+			It("rejects a jellyfin-scoped token", func() {
+				tokenStr, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(validateCredentials(usr, "", "", "", tokenStr)).To(MatchError(model.ErrInvalidAuth))
+			})
+
+			It("rejects a token with a stale epoch", func() {
+				tokenStr, err := auth.CreateToken(usr)
+				Expect(err).ToNot(HaveOccurred())
+				usr.TokenEpoch = 2
+				Expect(validateCredentials(usr, "", "", "", tokenStr)).To(MatchError(model.ErrInvalidAuth))
+			})
+		})
 	})
 })
 

From 3cb9850872f45a2cee0ca540b7c8d141c631f222 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sat, 22 Aug 2026 21:38:54 -0400
Subject: [PATCH 069/200] feat(artwork): extend stale absent age to 30 days and
 update test formatting

Signed-off-by: Deluan <deluan@navidrome.org>
---
 cmd/artwork_test.go          | 3 ++-
 core/artwork/housekeeping.go | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index cc63ed86f..f17206aaa 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -3,6 +3,7 @@ package cmd
 import (
 	"context"
 	"errors"
+	"fmt"
 	"io"
 	"strings"
 	"time"
@@ -910,7 +911,7 @@ var _ = Describe("formatStatus", func() {
 	})
 
 	It("states the recheck window and the drip rate the absent counts are bucketed against", func() {
-		Expect(formatStatus(rep)).To(ContainSubstring("168h"))
+		Expect(formatStatus(rep)).To(ContainSubstring(fmt.Sprintf("%gh", artwork.StaleAbsentAge.Hours())))
 		Expect(formatStatus(rep)).To(ContainSubstring("100 per kind per hour"))
 	})
 
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
index 9456a5584..ce98e2a03 100644
--- a/core/artwork/housekeeping.go
+++ b/core/artwork/housekeeping.go
@@ -18,7 +18,7 @@ import (
 )
 
 // StaleAbsentAge is how long an absent state is trusted before a recheck retries it.
-const StaleAbsentAge = 7 * 24 * time.Hour
+const StaleAbsentAge = 30 * 24 * time.Hour
 
 // StaleAbsentRecheckBatch caps how many absent states each hourly tick re-queues per kind,
 // oldest first, so external agents see a flat drip instead of a daily burst.

From fc9d93d22ac7e175223a48e0a84a6e5fe7c24c42 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 22 Aug 2026 22:02:25 -0400
Subject: [PATCH 070/200] fix(plugins): read the loaded plugin from a local,
 not the shared map (#6014)

Plugins load concurrently through an errgroup. loadPluginWithConfig wrote
m.plugins under m.mu but read it back unlocked to pass to callPluginInit,
so one goroutine's write raced another's read. Caught by -race on master
(run 32608293134): all 640 specs passed, the job failed only on the race.

Capture the pointer while holding the lock and use the local. Holding m.mu
across callPluginInit would be wrong, since that runs arbitrary plugin code.
---
 plugins/manager_loader.go | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/plugins/manager_loader.go b/plugins/manager_loader.go
index e5e3dbfc0..46da56396 100644
--- a/plugins/manager_loader.go
+++ b/plugins/manager_loader.go
@@ -434,8 +434,7 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 		return fmt.Errorf("manifest validation: %w", err)
 	}
 
-	m.mu.Lock()
-	m.plugins[p.ID] = &plugin{
+	loadedPlugin := &plugin{
 		name:           p.ID,
 		path:           p.Path,
 		manifest:       pkg.Manifest,
@@ -449,13 +448,16 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 		fsConfig:       fsConfig,
 		lyricsSem:      make(chan struct{}, maxConcurrentLyricsCalls),
 	}
+	m.mu.Lock()
+	m.plugins[p.ID] = loadedPlugin
 	m.mu.Unlock()
 	loaded = true
 
 	// Init is the plugin's first chance to run arbitrary code: open sockets, create task queues,
 	// schedule work. Only a caller that already intends to reach the network asks for it.
+	// Use the local: loads run concurrently, so reading the map back here would race the writes.
 	if m.transient == nil || m.transient.runInit {
-		callPluginInit(ctx, m.plugins[p.ID])
+		callPluginInit(ctx, loadedPlugin)
 	}
 
 	return nil

From 3e55886195bb125f5c1fda1a1ded39f319e96662 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 23 Aug 2026 14:31:37 -0400
Subject: [PATCH 071/200] feat: add optional natural sort order for names and
 titles (#6015)

* feat: add optional natural sort order for names and titles

Album, artist, song and playlist lists sort with a plain text comparison, so
names containing numbers come out as "Foo 1, Foo 10, Foo 2" instead of
"Foo 1, Foo 2, Foo 10" (issue #4554).

Adds an EnableNaturalSorting option, default off, that switches those sorts to
a NATSORT collation registered on every connection and backed by
natural.CompareFold. natural.Compare gained an ASCII case-folding variant
because it replaces 'collate nocase': sort_* columns hold raw tag values, so
without folding they would order uppercase before lowercase.

Applying the collation only inside mapSortOrder would have missed the default
configuration entirely, since that mapper runs only when PreferSortTags is on.
setSortMappings now also rewrites the order_* columns when natural sorting is
enabled on its own. Sorts over plain text columns that are not order_* columns
(playlist.name, album.name, media_file.title, playlist_tracks title) are
wrapped explicitly, and qualified with their table because 'user' is joined and
also has a 'name' column.

The option defaults to off because the collation cannot use the existing
indexes: measured on a synthetic 110k album library, the first page of an
album-by-name listing goes from 0.03ms to 14ms. Indexing the expression was
rejected outright - an index declared with a custom collation makes the whole
database unreadable to any tool that does not register it, including the
sqlite3 CLI, which fails even on 'select count(*)' and 'pragma integrity_check'.

* refactor: fold the two sort-order mappers into one

mapSortOrder and mapNaturalOrder shared the same regex and loop, differing only
in the expression they substituted, and setSortMappings picked between them with
a two-case switch. mapSortOrder now selects the column shape itself and defers to
collatedSort for the collation, so the 'collate' clause is emitted in one place
and the caller only has to decide whether any mapping is needed at all.

The mapper tests were three near-identical cases that each hard-coded one flag
combination; they are now a DescribeTable covering all four combinations of
PreferSortTags and EnableNaturalSorting, which the previous set did not. The
album sorting specs collapse the same way. Behavior is unchanged.

* fix: leave plain sort columns alone when natural sorting is off

collatedSort wrapped its column unconditionally, so the tiebreakers added for
plain text columns picked up 'collate nocase' even with EnableNaturalSorting
off. media_file.title, the playlist_tracks alias of it, and user.user_name are
all declared without a collation, so a default install would have silently
switched those tiebreaks from binary to case-insensitive ordering. Only
playlist.name was already NOCASE and genuinely unaffected.

The helper is now naturalSort and returns the column untouched unless the option
is on, so the default path keeps the collation each column was declared with.
sortCollation had a single remaining caller and folded into mapSortOrder.

Tests: the CompareFold table body was a verbatim copy of the Compare one, so
both now go through one expectOrder helper, and the album sorting specs inline
two single-use closures.

* fix(natural): defer the leading-zero tie-break to keep ordering transitive

Compare applied the padding difference between numerically equal digit runs only
when one side ended at the digit boundary, and ignored it mid-string. That made
the relation intransitive: CompareFold("1","1a") < 0 and CompareFold("1a","01a")
== 0, yet CompareFold("1","01a") > 0.

SQLite requires a collating function to be transitive and leaves ORDER BY
undefined otherwise, so registering this as NATSORT was not safe. Reproduced with
the real driver on three artist names that occur in practice - "3", "3 doors
down" and "03 greedo" - where paging one row at a time returned "03 greedo"
twice and dropped "3" entirely.

The padding difference is now carried as a tie-break that is applied only when
the strings are otherwise equal, which restores transitivity while keeping the
documented intent (a01 < a1, a0 < a00). Three existing entries changed: each
asserted that two distinct strings compare equal, which was the same defect seen
from the other side.

Found by the Codex review on #6015.
---
 conf/configuration.go                    |   2 +
 db/db.go                                 |  10 ++-
 persistence/album_repository.go          |   2 +-
 persistence/album_repository_test.go     |  39 +++++++++
 persistence/helpers.go                   |  29 +++++--
 persistence/helpers_test.go              |  55 ++++++++++---
 persistence/mediafile_repository.go      |   2 +-
 persistence/playlist_repository.go       |   3 +-
 persistence/playlist_repository_test.go  |  35 ++++++++
 persistence/playlist_track_repository.go |   2 +-
 persistence/sql_base_repository.go       |   5 +-
 utils/natural/natural.go                 |  51 ++++++++----
 utils/natural/natural_test.go            | 100 ++++++++++++++++++++---
 13 files changed, 284 insertions(+), 51 deletions(-)

diff --git a/conf/configuration.go b/conf/configuration.go
index fbbaaf252..df22e4ae2 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -73,6 +73,7 @@ type configOptions struct {
 	Matcher                         matcherOptions `json:",omitzero"`
 	RecentlyAddedByModTime          bool
 	PreferSortTags                  bool
+	EnableNaturalSorting            bool
 	IgnoredArticles                 string
 	IndexGroups                     string
 	FFmpegPath                      string
@@ -973,6 +974,7 @@ func setViperDefaults() {
 	viper.SetDefault("matcher.fuzzythreshold", 85)
 	viper.SetDefault("recentlyaddedbymodtime", false)
 	viper.SetDefault("prefersorttags", false)
+	viper.SetDefault("enablenaturalsorting", 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", "")
diff --git a/db/db.go b/db/db.go
index 11a05b456..a325dd3f5 100644
--- a/db/db.go
+++ b/db/db.go
@@ -13,10 +13,15 @@ import (
 	_ "github.com/navidrome/navidrome/db/migrations"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/utils/hasher"
+	"github.com/navidrome/navidrome/utils/natural"
 	"github.com/navidrome/navidrome/utils/singleton"
 	"github.com/pressly/goose/v3"
 )
 
+// NaturalCollation sorts embedded numbers by value. It is registered on every
+// connection, but only referenced when conf.Server.EnableNaturalSorting is on.
+const NaturalCollation = "NATSORT"
+
 var (
 	Dialect = "sqlite3"
 	Driver  = Dialect + "_custom"
@@ -32,7 +37,10 @@ func Db() *sql.DB {
 	return singleton.GetInstance(func() *sql.DB {
 		sql.Register(Driver, &sqlite3.SQLiteDriver{
 			ConnectHook: func(conn *sqlite3.SQLiteConn) error {
-				return conn.RegisterFunc("SEEDEDRAND", hasher.HashFunc(), false)
+				if err := conn.RegisterFunc("SEEDEDRAND", hasher.HashFunc(), false); err != nil {
+					return err
+				}
+				return conn.RegisterCollation(NaturalCollation, natural.CompareFold)
 			},
 		})
 		Path = conf.Server.DbPath
diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 5d7aad22e..7ac875a51 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -113,7 +113,7 @@ func NewAlbumRepository(ctx context.Context, db dbx.Builder) model.AlbumReposito
 		"artist":       "compilation, order_album_artist_name, order_album_name",
 		"album_artist": "compilation, order_album_artist_name, order_album_name",
 		// TODO Rename this to just year (or date)
-		"max_year":       "coalesce(nullif(original_date,''), cast(max_year as text)), release_date, name",
+		"max_year":       "coalesce(nullif(original_date,''), cast(max_year as text)), release_date, " + naturalSort("album.name"),
 		"random":         "random",
 		"recently_added": recentlyAddedSort(),
 		"starred_at":     "starred, starred_at",
diff --git a/persistence/album_repository_test.go b/persistence/album_repository_test.go
index f6768768d..0fb680cff 100644
--- a/persistence/album_repository_test.go
+++ b/persistence/album_repository_test.go
@@ -10,6 +10,7 @@ import (
 	"github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
@@ -38,6 +39,44 @@ var _ = Describe("AlbumRepository", func() {
 		albumRepo = NewAlbumRepository(ctx, GetDBXBuilder()).(*albumRepository)
 	})
 
+	Describe("natural sorting", func() {
+		var ids []string
+
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			ids = nil
+			for _, n := range []string{"foo 1", "foo 10", "foo 2", "foo 20", "foo 3"} {
+				aid := "nat-" + n
+				ids = append(ids, aid)
+				Expect(albumRepo.Put(&model.Album{
+					ID: aid, LibraryID: 1, Name: n, OrderAlbumName: n,
+				})).To(Succeed())
+			}
+			DeferCleanup(func() {
+				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": ids}))
+			})
+		})
+
+		DescribeTable("sorts albums by name",
+			func(naturalSorting, preferSortTags bool, expected []string) {
+				conf.Server.EnableNaturalSorting = naturalSorting
+				conf.Server.PreferSortTags = preferSortTags
+				albumRepo = NewAlbumRepository(ctx, GetDBXBuilder()).(*albumRepository)
+				albums, err := albumRepo.GetAll(model.QueryOptions{
+					Sort: "name", Filters: squirrel.Eq{"album.id": ids},
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(slice.Map(albums, func(a model.Album) string { return a.Name })).To(Equal(expected))
+			},
+			Entry("lexicographically by default", false, false,
+				[]string{"foo 1", "foo 10", "foo 2", "foo 20", "foo 3"}),
+			Entry("by number value when natural sorting is enabled", true, false,
+				[]string{"foo 1", "foo 2", "foo 3", "foo 10", "foo 20"}),
+			Entry("by number value with sort tags preferred too", true, true,
+				[]string{"foo 1", "foo 2", "foo 3", "foo 10", "foo 20"}),
+		)
+	})
+
 	Describe("Get", func() {
 		var Get = func(id string) (*model.Album, error) {
 			album, err := albumRepo.Get(id)
diff --git a/persistence/helpers.go b/persistence/helpers.go
index fd6a9a4cd..1da31cf02 100644
--- a/persistence/helpers.go
+++ b/persistence/helpers.go
@@ -9,6 +9,8 @@ import (
 
 	"github.com/Masterminds/squirrel"
 	"github.com/fatih/structs"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/db"
 )
 
 type PostMapper interface {
@@ -82,11 +84,28 @@ func (e existsCond) ToSql() (string, []any, error) {
 
 var sortOrderRegex = regexp.MustCompile(`order_([a-z_]+)`)
 
-// Convert the order_* columns to an expression using sort_* columns. Example:
-// sort_album_name -> (coalesce(nullif(sort_album_name,”),order_album_name) collate nocase)
+// naturalSort makes a plain text column sort numbers by value, leaving it alone
+// otherwise so it keeps its declared collation. Parens guard buildSortOrder's space split.
+func naturalSort(col string) string {
+	if !conf.Server.EnableNaturalSorting {
+		return col
+	}
+	return fmt.Sprintf("(%s collate %s)", col, db.NaturalCollation)
+}
+
+// Convert the order_* columns to a collated sort expression, falling back to the
+// sort_* column when those are preferred. Example:
+// order_album_name -> (coalesce(nullif(sort_album_name,”),order_album_name) collate nocase)
 // It finds order column names anywhere in the substring
 func mapSortOrder(tableName, order string) string {
-	order = strings.ToLower(order)
-	repl := fmt.Sprintf("(coalesce(nullif(%[1]s.sort_$1,''),%[1]s.order_$1) collate nocase)", tableName)
-	return sortOrderRegex.ReplaceAllString(order, repl)
+	col := tableName + ".order_$1"
+	if conf.Server.PreferSortTags {
+		col = fmt.Sprintf("coalesce(nullif(%[1]s.sort_$1,''),%[1]s.order_$1)", tableName)
+	}
+	collation := "nocase"
+	if conf.Server.EnableNaturalSorting {
+		collation = db.NaturalCollation
+	}
+	repl := fmt.Sprintf("(%s collate %s)", col, collation)
+	return sortOrderRegex.ReplaceAllString(strings.ToLower(order), repl)
 }
diff --git a/persistence/helpers_test.go b/persistence/helpers_test.go
index 85893ef55..3019609f3 100644
--- a/persistence/helpers_test.go
+++ b/persistence/helpers_test.go
@@ -4,6 +4,8 @@ import (
 	"time"
 
 	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -85,22 +87,51 @@ var _ = Describe("Helpers", func() {
 	})
 
 	Describe("mapSortOrder", func() {
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+		})
+
 		It("does not change the sort string if there are no order columns", func() {
-			sort := "album_name asc"
-			mapped := mapSortOrder("album", sort)
-			Expect(mapped).To(Equal(sort))
-		})
-		It("changes order columns to sort expression", func() {
-			sort := "ORDER_ALBUM_NAME asc"
-			mapped := mapSortOrder("album", sort)
-			Expect(mapped).To(Equal(`(coalesce(nullif(album.sort_album_name,''),album.order_album_name)` +
-				` collate nocase) asc`))
+			Expect(mapSortOrder("album", "album_name asc")).To(Equal("album_name asc"))
 		})
+
+		DescribeTable("maps order columns to a collated expression",
+			func(preferSortTags, naturalSorting bool, expected string) {
+				conf.Server.PreferSortTags = preferSortTags
+				conf.Server.EnableNaturalSorting = naturalSorting
+				Expect(mapSortOrder("album", "ORDER_ALBUM_NAME asc")).To(Equal(expected))
+			},
+			Entry("qualified column", false, false,
+				"(album.order_album_name collate nocase) asc"),
+			Entry("natural collation", false, true,
+				"(album.order_album_name collate NATSORT) asc"),
+			Entry("sort tags preferred", true, false,
+				`(coalesce(nullif(album.sort_album_name,''),album.order_album_name) collate nocase) asc`),
+			Entry("sort tags preferred, natural collation", true, true,
+				`(coalesce(nullif(album.sort_album_name,''),album.order_album_name) collate NATSORT) asc`),
+		)
+
 		It("changes multiple order columns to sort expressions", func() {
+			conf.Server.PreferSortTags = true
 			sort := "compilation, order_title asc, order_album_artist_name desc, year desc"
-			mapped := mapSortOrder("album", sort)
-			Expect(mapped).To(Equal(`compilation, (coalesce(nullif(album.sort_title,''),album.order_title) collate nocase) asc,` +
-				` (coalesce(nullif(album.sort_album_artist_name,''),album.order_album_artist_name) collate nocase) desc, year desc`))
+			Expect(mapSortOrder("album", sort)).To(Equal(
+				`compilation, (coalesce(nullif(album.sort_title,''),album.order_title) collate nocase) asc,` +
+					` (coalesce(nullif(album.sort_album_artist_name,''),album.order_album_artist_name) collate nocase) desc, year desc`))
+		})
+	})
+
+	Describe("naturalSort", func() {
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+		})
+
+		It("leaves the column alone by default, keeping its declared collation", func() {
+			Expect(naturalSort("media_file.title")).To(Equal("media_file.title"))
+		})
+
+		It("applies the natural collation when enabled", func() {
+			conf.Server.EnableNaturalSorting = true
+			Expect(naturalSort("media_file.title")).To(Equal("(media_file.title collate NATSORT)"))
 		})
 	})
 })
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index 8146cba2f..320b95ef2 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -86,7 +86,7 @@ func NewMediaFileRepository(ctx context.Context, db dbx.Builder) model.MediaFile
 		"title":          "order_title",
 		"artist":         "order_artist_name, order_album_name, release_date, disc_number, track_number",
 		"album_artist":   "order_album_artist_name, order_album_name, release_date, disc_number, track_number",
-		"album":          "order_album_name, album_id, disc_number, track_number, order_artist_name, title",
+		"album":          "order_album_name, album_id, disc_number, track_number, order_artist_name, " + naturalSort("media_file.title"),
 		"random":         "random",
 		"created_at":     "media_file.created_at",
 		"recently_added": mediaFileRecentlyAddedSort(),
diff --git a/persistence/playlist_repository.go b/persistence/playlist_repository.go
index cf54c6d5a..505f23440 100644
--- a/persistence/playlist_repository.go
+++ b/persistence/playlist_repository.go
@@ -60,7 +60,8 @@ func NewPlaylistRepository(ctx context.Context, db dbx.Builder) model.PlaylistRe
 		"starred": annotationBoolFilter("starred"),
 	})
 	r.setSortMappings(map[string]string{
-		"owner_name": "owner_name",
+		"name":       naturalSort("playlist.name"),
+		"owner_name": naturalSort("owner_name"),
 	})
 	return r
 }
diff --git a/persistence/playlist_repository_test.go b/persistence/playlist_repository_test.go
index 9697e6fff..f60b4e7ca 100644
--- a/persistence/playlist_repository_test.go
+++ b/persistence/playlist_repository_test.go
@@ -5,6 +5,8 @@ import (
 
 	"github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/criteria"
@@ -24,6 +26,39 @@ var _ = Describe("PlaylistRepository", func() {
 		repo = NewPlaylistRepository(ctx, GetDBXBuilder())
 	})
 
+	Describe("natural sorting", func() {
+		var ids []string
+
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.EnableNaturalSorting = true
+			ctx := log.NewContext(GinkgoT().Context())
+			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+			repo = NewPlaylistRepository(ctx, GetDBXBuilder())
+
+			ids = nil
+			for _, n := range []string{"mix 1", "mix 10", "mix 2"} {
+				pls := model.Playlist{Name: n, OwnerID: "userid"}
+				Expect(repo.Put(&pls)).To(Succeed())
+				ids = append(ids, pls.ID)
+			}
+			DeferCleanup(func() {
+				for _, id := range ids {
+					_ = repo.Delete(id)
+				}
+			})
+		})
+
+		It("sorts playlist names by number value", func() {
+			all, err := repo.GetAll(model.QueryOptions{
+				Sort: "name", Filters: squirrel.Eq{"playlist.id": ids},
+			})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(slice.Map(all, func(p model.Playlist) string { return p.Name })).To(
+				Equal([]string{"mix 1", "mix 2", "mix 10"}))
+		})
+	})
+
 	Describe("Count", func() {
 		It("returns the number of playlists in the DB", func() {
 			Expect(repo.CountAll()).To(Equal(int64(2)))
diff --git a/persistence/playlist_track_repository.go b/persistence/playlist_track_repository.go
index a5e1975fd..cf1b8f3fa 100644
--- a/persistence/playlist_track_repository.go
+++ b/persistence/playlist_track_repository.go
@@ -56,7 +56,7 @@ func (r *playlistRepository) Tracks(playlistId string, refreshSmartPlaylist bool
 			"id":           "playlist_tracks.id",
 			"artist":       "order_artist_name",
 			"album_artist": "order_album_artist_name",
-			"album":        "order_album_name, album_id, disc_number, track_number, order_artist_name, title",
+			"album":        "order_album_name, album_id, disc_number, track_number, order_artist_name, " + naturalSort("f.title"),
 			"title":        "order_title",
 			"random":       "random()",
 			// To make sure these fields will be whitelisted
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index d4cf9b456..f49e1bc4f 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -113,10 +113,9 @@ func (r *sqlRepository) setSortMappings(mappings map[string]string, tableName ..
 	if len(tableName) > 0 {
 		tn = tableName[0]
 	}
-	if conf.Server.PreferSortTags {
+	if conf.Server.PreferSortTags || conf.Server.EnableNaturalSorting {
 		for k, v := range mappings {
-			v = mapSortOrder(tn, v)
-			mappings[k] = v
+			mappings[k] = mapSortOrder(tn, v)
 		}
 	}
 	r.sortMappings = mappings
diff --git a/utils/natural/natural.go b/utils/natural/natural.go
index fa0800e1d..d8ddcc405 100644
--- a/utils/natural/natural.go
+++ b/utils/natural/natural.go
@@ -10,15 +10,32 @@ import "strings"
 // or a positive value if a > b using natural sort ordering.
 //
 // When two numeric segments are numerically equal (e.g. "01" vs "1"),
-// comparison continues with the remaining suffixes. If one or both
-// strings end at the digit boundary, the raw strings are compared
-// lexically, which makes leading zeros significant as a tie-breaker
-// (e.g. "a01" < "a1", "a0" < "a00").
+// comparison continues with the remaining suffixes, and the padding
+// difference is kept as a final tie-breaker that only decides strings
+// that are otherwise equal (e.g. "a01" < "a1", "a0" < "a00"). Deferring
+// it that way is what keeps the ordering transitive, which SQLite
+// requires of a collating function.
 func Compare(a, b string) int {
+	return compare(a, b, false)
+}
+
+// CompareFold is Compare with ASCII case folding, matching SQLite's NOCASE
+// collation: only A-Z fold, bytes >= 0x80 are compared as-is.
+func CompareFold(a, b string) int {
+	return compare(a, b, true)
+}
+
+func compare(a, b string, fold bool) int {
 	ia, ib := 0, 0
+	// Set when two runs are numerically equal but differently padded. Applying it
+	// immediately would break transitivity, so it only decides otherwise-equal strings.
+	padTie := 0
 	for ia < len(a) && ib < len(b) {
 		ca, cb := a[ia], b[ib]
 		da, db := isDigit(ca), isDigit(cb)
+		if fold {
+			ca, cb = lower(ca), lower(cb)
+		}
 
 		switch {
 		case da && db:
@@ -35,17 +52,11 @@ func Compare(a, b string) int {
 			if c := compareNumbers(a[ia:endA], b[ib:endB]); c != 0 {
 				return c
 			}
-
-			// Numerically equal. If both sides have trailing data, continue
-			// comparing after the digit runs. Otherwise fall through to
-			// lexical comparison of the full remaining strings (which makes
-			// leading-zero differences significant as a tie-breaker).
-			if endA < len(a) && endB < len(b) {
-				ia = endA
-				ib = endB
-				continue
+			if t := strings.Compare(a[ia:endA], b[ib:endB]); t != 0 {
+				padTie = t
 			}
-			return strings.Compare(a[ia:], b[ib:])
+			ia = endA
+			ib = endB
 		case da != db:
 			return int(ca) - int(cb)
 		default:
@@ -56,7 +67,10 @@ func Compare(a, b string) int {
 			ib++
 		}
 	}
-	return (len(a) - ia) - (len(b) - ib)
+	if c := (len(a) - ia) - (len(b) - ib); c != 0 {
+		return c
+	}
+	return padTie
 }
 
 // compareNumbers compares two digit strings numerically.
@@ -96,3 +110,10 @@ func stripZeros(s string) string {
 func isDigit(c byte) bool {
 	return c >= '0' && c <= '9'
 }
+
+func lower(c byte) byte {
+	if c >= 'A' && c <= 'Z' {
+		return c + 'a' - 'A'
+	}
+	return c
+}
diff --git a/utils/natural/natural_test.go b/utils/natural/natural_test.go
index 825a944c0..534885d40 100644
--- a/utils/natural/natural_test.go
+++ b/utils/natural/natural_test.go
@@ -13,17 +13,23 @@ func TestNatural(t *testing.T) {
 	RunSpecs(t, "Natural Suite")
 }
 
+// expectOrder asserts the sign of cmp(a, b) matches expected.
+func expectOrder(cmp func(string, string) int, a, b string, expected int) {
+	result := cmp(a, b)
+	switch {
+	case expected < 0:
+		ExpectWithOffset(1, result).To(BeNumerically("<", 0), "expected %q < %q", a, b)
+	case expected > 0:
+		ExpectWithOffset(1, result).To(BeNumerically(">", 0), "expected %q > %q", a, b)
+	default:
+		ExpectWithOffset(1, result).To(Equal(0), "expected %q == %q", a, b)
+	}
+}
+
 var _ = Describe("Compare", func() {
 	DescribeTable("returns correct ordering",
 		func(a, b string, expected int) {
-			result := natural.Compare(a, b)
-			if expected < 0 {
-				Expect(result).To(BeNumerically("<", 0), "expected %q < %q", a, b)
-			} else if expected > 0 {
-				Expect(result).To(BeNumerically(">", 0), "expected %q > %q", a, b)
-			} else {
-				Expect(result).To(Equal(0), "expected %q == %q", a, b)
-			}
+			expectOrder(natural.Compare, a, b, expected)
 		},
 		// Basic string ordering
 		Entry("a < b", "a", "b", -1),
@@ -67,7 +73,9 @@ var _ = Describe("Compare", func() {
 		Entry("a00b00 < a0b1", "a00b00", "a0b1", -1),
 		Entry("a00b00 > a0b0", "a00b00", "a0b0", 1),
 		Entry("a00b01 > a0b00", "a00b01", "a0b00", 1),
-		Entry("a00b00 == a0b00", "a00b00", "a0b00", 0),
+		// Distinct strings must not compare equal: the padding difference in the first
+		// run decides once everything else matches.
+		Entry("a00b00 > a0b00", "a00b00", "a0b00", 1),
 
 		// Leading zeros at end of string — lexical tie-break
 		Entry("file01 < file1", "file01", "file1", -1),
@@ -109,8 +117,78 @@ var _ = Describe("Compare", func() {
 		Entry("large: equal",
 			"a100000000000000000000", "a100000000000000000000", 0),
 		Entry("large: leading zeros with trailing data",
-			"a00000000000000000000001x", "a1x", 0),
+			"a00000000000000000000001x", "a1x", -1),
 		Entry("large: leading zeros with trailing data (2)",
-			"a099999999999999999999x", "a99999999999999999999x", 0),
+			"a099999999999999999999x", "a99999999999999999999x", -1),
 	)
 })
+
+var _ = Describe("CompareFold", func() {
+	DescribeTable("orders case-insensitively",
+		func(a, b string, expected int) {
+			expectOrder(natural.CompareFold, a, b, expected)
+		},
+		Entry("numbers compare numerically", "foo 2", "foo 10", -1),
+		Entry("numbers compare numerically, reversed", "foo 10", "foo 2", 1),
+		Entry("case is ignored", "apple 2", "Banana 10", -1),
+		Entry("case is ignored, reversed", "Banana 10", "apple 2", 1),
+		Entry("same word, different case, is equal", "ABC", "abc", 0),
+		Entry("case ignored while comparing numbers", "Vol 2", "vol 10", -1),
+		Entry("uppercase digits boundary", "Track9", "track10", -1),
+		Entry("empty vs empty", "", "", 0),
+		Entry("empty sorts first", "", "a", -1),
+		Entry("non-ASCII is left untouched", "café 2", "café 10", -1),
+	)
+
+	// SQLite requires a collating function to be transitive; if it is not, the behavior of
+	// ORDER BY is undefined and paginated queries can drop or duplicate rows.
+	It("is transitive, as a SQLite collation requires", func() {
+		var corpus []string
+		var build func(prefix string, depth int)
+		build = func(prefix string, depth int) {
+			if prefix != "" {
+				corpus = append(corpus, prefix)
+			}
+			if depth == 0 {
+				return
+			}
+			for _, c := range []string{"0", "1", "a"} {
+				build(prefix+c, depth-1)
+			}
+		}
+		build("", 3)
+
+		sign := func(n int) int {
+			switch {
+			case n < 0:
+				return -1
+			case n > 0:
+				return 1
+			}
+			return 0
+		}
+		for _, a := range corpus {
+			for _, b := range corpus {
+				ab := sign(natural.CompareFold(a, b))
+				for _, c := range corpus {
+					bc := sign(natural.CompareFold(b, c))
+					ac := sign(natural.CompareFold(a, c))
+					if ab == 0 && bc == 0 {
+						Expect(ac).To(Equal(0), "%q==%q and %q==%q but %q vs %q is %d", a, b, b, c, a, c, ac)
+					}
+					if ab < 0 && bc < 0 {
+						Expect(ac).To(BeNumerically("<", 0), "%q<%q<%q but %q vs %q is %d", a, b, c, a, c, ac)
+					}
+				}
+			}
+		}
+	})
+
+	It("matches Compare when both sides are already lowercase", func() {
+		pairs := [][2]string{{"foo 2", "foo 10"}, {"a01", "a1"}, {"a", "aa"}, {"vol 3", "vol 3"}}
+		for _, p := range pairs {
+			Expect(natural.CompareFold(p[0], p[1])).To(Equal(natural.Compare(p[0], p[1])),
+				"CompareFold(%q,%q) should match Compare", p[0], p[1])
+		}
+	})
+})

From 82b9a44a1f0ee94682f759086579df3a9ec4330e Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sun, 23 Aug 2026 15:24:44 -0400
Subject: [PATCH 072/200] fix(log): redact sensitive auth headers from request
 logs

The trace-level request log dumps all headers as a JSON blob, but the
redaction hook only had query-param patterns, so Authorization, X-Emby-Token,
X-MediaBrowser-Token and X-Nd-Authorization leaked their tokens in plaintext.
Add one pattern that blanks those header value arrays at the log sink.
---
 log/log.go      |  4 ++++
 log/log_test.go | 18 +++++++++++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/log/log.go b/log/log.go
index f7977c0fa..10cfb17b5 100644
--- a/log/log.go
+++ b/log/log.go
@@ -50,6 +50,10 @@ var redacted = &Hook{
 		// at a JWT's first '.' and leak its payload and signature. Case-insensitive with an
 		// optional underscore: the API accepts api_key, apikey and ApiKey alike.
 		"(?i)([^\\w]api_?key=)[^&\\s]+",
+
+		// Sensitive request headers, logged as a JSON blob at trace level and never matched by the
+		// query-param patterns above. Blank the whole value array; values may hold escaped quotes.
+		`(?i)("(?:Authorization|X-Emby-Token|X-MediaBrowser-Token|X-Nd-Authorization)":\[")[^\]]*("\])`,
 	},
 }
 
diff --git a/log/log_test.go b/log/log_test.go
index f0e2e0eae..82207c672 100644
--- a/log/log_test.go
+++ b/log/log_test.go
@@ -2,7 +2,9 @@ package log
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
+	"net/http"
 	"net/http/httptest"
 	"testing"
 	"time"
@@ -92,7 +94,7 @@ var _ = Describe("Logger", func() {
 			SetLogSourceLine(true)
 			Error("A crash happened")
 			// NOTE: This assertion breaks if the line number above changes
-			Expect(hook.LastEntry().Data[" source"]).To(ContainSubstring("/log/log_test.go:93"))
+			Expect(hook.LastEntry().Data[" source"]).To(ContainSubstring("/log/log_test.go:95"))
 			Expect(hook.LastEntry().Message).To(Equal("A crash happened"))
 		})
 
@@ -275,5 +277,19 @@ var _ = Describe("Logger", func() {
 			Entry("ApiKey", "ApiKey"),
 			Entry("APIKEY", "APIKEY"),
 		)
+
+		It("redacts sensitive request headers in a logged header blob", func() {
+			h := http.Header{
+				"Authorization":        {`MediaBrowser Client="Finamp", Token="jwt-secret"`},
+				"X-Emby-Token":         {"emby-secret"},
+				"X-Mediabrowser-Token": {"mb-secret"},
+				"X-Nd-Authorization":   {"Bearer nd-secret"},
+				"User-Agent":           {"Finamp/1.0"},
+			}
+			blob, _ := json.Marshal(h)
+			got := Redact(string(blob))
+			Expect(got).ToNot(ContainSubstring("secret"))
+			Expect(got).To(ContainSubstring(`"User-Agent":["Finamp/1.0"]`))
+		})
 	})
 })

From 3da2b590e780722df6c2a35e10fd38dfaf83098a Mon Sep 17 00:00:00 2001
From: Rob Emery <mintsoft@users.noreply.github.com>
Date: Mon, 24 Aug 2026 16:22:32 +0100
Subject: [PATCH 073/200] fix: add Navidrome UserAgent in all outgoing requests
 (#6020)

* There has been a report about navidrome hitting listenbrainz hard
and the listenbrainz guys wanting to be able to distinguish navidrome

* feat: apply Navidrome User-Agent to all outgoing HTTP requests

Add utils/httpclient, a shared http.Client factory whose transport sets
the User-Agent header (Navidrome/{version} - https://github.com/navidrome)
on any request that does not already have one, and use it at every place
the server builds an HTTP client: Last.fm, ListenBrainz and Deezer agents
and auth routers, insights collector, backgrounds handler, and the plugin
host HTTP service. Plugin-set User-Agent values are preserved. The
per-request header lines from the previous commit are superseded by the
transport.

---------

Co-authored-by: Deluan <deluan@navidrome.org>
---
 adapters/deezer/deezer.go                 |  6 +-
 adapters/lastfm/agent.go                  |  5 +-
 adapters/lastfm/auth_router.go            |  5 +-
 adapters/listenbrainz/agent.go            |  6 +-
 adapters/listenbrainz/auth_router.go      |  5 +-
 consts/consts.go                          |  2 +-
 core/metrics/insights.go                  |  5 +-
 plugins/host_httpclient.go                |  3 +-
 server/backgrounds/handler.go             |  5 +-
 utils/httpclient/httpclient.go            | 35 +++++++++++
 utils/httpclient/httpclient_suite_test.go | 17 +++++
 utils/httpclient/httpclient_test.go       | 76 +++++++++++++++++++++++
 12 files changed, 146 insertions(+), 24 deletions(-)
 create mode 100644 utils/httpclient/httpclient.go
 create mode 100644 utils/httpclient/httpclient_suite_test.go
 create mode 100644 utils/httpclient/httpclient_test.go

diff --git a/adapters/deezer/deezer.go b/adapters/deezer/deezer.go
index 742b8b1a5..1fa10e25c 100644
--- a/adapters/deezer/deezer.go
+++ b/adapters/deezer/deezer.go
@@ -5,7 +5,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"net/http"
 	"slices"
 	"strings"
 
@@ -15,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/cache"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
@@ -36,9 +36,7 @@ func deezerConstructor(dataStore model.DataStore) agents.Interface {
 		dataStore: dataStore,
 		languages: conf.Server.Deezer.Languages,
 	}
-	httpClient := &http.Client{
-		Timeout: consts.DefaultHttpClientTimeOut,
-	}
+	httpClient := httpclient.New(consts.DefaultHttpClientTimeOut)
 	cachedHttpClient := cache.NewHTTPClient(httpClient, consts.DefaultHttpClientTimeOut)
 	agent.client = newClient(cachedHttpClient)
 	return agent
diff --git a/adapters/lastfm/agent.go b/adapters/lastfm/agent.go
index f967595e3..863868b5a 100644
--- a/adapters/lastfm/agent.go
+++ b/adapters/lastfm/agent.go
@@ -18,6 +18,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/cache"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	"golang.org/x/net/html"
 )
 
@@ -59,9 +60,7 @@ func lastFMConstructor(ds model.DataStore) *lastfmAgent {
 		secret:      conf.Server.LastFM.Secret,
 		sessionKeys: &agents.SessionKeys{DataStore: ds, KeyName: sessionKeyProperty},
 	}
-	hc := &http.Client{
-		Timeout: consts.DefaultHttpClientTimeOut,
-	}
+	hc := httpclient.New(consts.DefaultHttpClientTimeOut)
 	chc := cache.NewHTTPClient(hc, consts.DefaultHttpClientTimeOut)
 	l.httpClient = chc
 	l.client = newClient(l.apiKey, l.secret, chc)
diff --git a/adapters/lastfm/auth_router.go b/adapters/lastfm/auth_router.go
index 499863e28..411bf069a 100644
--- a/adapters/lastfm/auth_router.go
+++ b/adapters/lastfm/auth_router.go
@@ -18,6 +18,7 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	"github.com/navidrome/navidrome/utils/req"
 )
 
@@ -41,9 +42,7 @@ func NewRouter(ds model.DataStore) *Router {
 		sessionKeys: &agents.SessionKeys{DataStore: ds, KeyName: sessionKeyProperty},
 	}
 	r.Handler = r.routes()
-	hc := &http.Client{
-		Timeout: consts.DefaultHttpClientTimeOut,
-	}
+	hc := httpclient.New(consts.DefaultHttpClientTimeOut)
 	r.client = newClient(r.apiKey, r.secret, hc)
 	return r
 }
diff --git a/adapters/listenbrainz/agent.go b/adapters/listenbrainz/agent.go
index 76beed921..a59a5393f 100644
--- a/adapters/listenbrainz/agent.go
+++ b/adapters/listenbrainz/agent.go
@@ -3,7 +3,6 @@ package listenbrainz
 import (
 	"context"
 	"errors"
-	"net/http"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
@@ -12,6 +11,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/cache"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
@@ -33,9 +33,7 @@ func listenBrainzConstructor(ds model.DataStore) *listenBrainzAgent {
 		sessionKeys: &agents.SessionKeys{DataStore: ds, KeyName: sessionKeyProperty},
 		baseURL:     conf.Server.ListenBrainz.BaseURL,
 	}
-	hc := &http.Client{
-		Timeout: consts.DefaultHttpClientTimeOut,
-	}
+	hc := httpclient.New(consts.DefaultHttpClientTimeOut)
 	chc := cache.NewHTTPClient(hc, consts.DefaultHttpClientTimeOut)
 	l.client = newClient(l.baseURL, chc)
 	return l
diff --git a/adapters/listenbrainz/auth_router.go b/adapters/listenbrainz/auth_router.go
index 7cb9eb16a..1ff1a1495 100644
--- a/adapters/listenbrainz/auth_router.go
+++ b/adapters/listenbrainz/auth_router.go
@@ -16,6 +16,7 @@ import (
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server"
+	"github.com/navidrome/navidrome/utils/httpclient"
 )
 
 type sessionKeysRepo interface {
@@ -37,9 +38,7 @@ func NewRouter(ds model.DataStore) *Router {
 		sessionKeys: &agents.SessionKeys{DataStore: ds, KeyName: sessionKeyProperty},
 	}
 	r.Handler = r.routes()
-	hc := &http.Client{
-		Timeout: consts.DefaultHttpClientTimeOut,
-	}
+	hc := httpclient.New(consts.DefaultHttpClientTimeOut)
 	r.client = newClient(conf.Server.ListenBrainz.BaseURL, hc)
 	return r
 }
diff --git a/consts/consts.go b/consts/consts.go
index aed8ecf66..2934cd968 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -201,7 +201,7 @@ var (
 	}
 )
 
-var HTTPUserAgent = "Navidrome" + "/" + Version
+var HTTPUserAgent = "Navidrome/" + Version + " - https://github.com/navidrome"
 
 var (
 	VariousArtists = "Various Artists"
diff --git a/core/metrics/insights.go b/core/metrics/insights.go
index 66d0b89bd..706df6559 100644
--- a/core/metrics/insights.go
+++ b/core/metrics/insights.go
@@ -26,6 +26,7 @@ import (
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/plugins"
 	"github.com/navidrome/navidrome/server/events"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	"github.com/navidrome/navidrome/utils/singleton"
 )
 
@@ -95,9 +96,7 @@ func (c *insightsCollector) sendInsights(ctx context.Context) {
 		log.Trace(ctx, "No users found, skipping Insights data collection")
 		return
 	}
-	hc := &http.Client{
-		Timeout: consts.DefaultHttpClientTimeOut,
-	}
+	hc := httpclient.New(consts.DefaultHttpClientTimeOut)
 	data := c.collect(ctx)
 	if data == nil {
 		return
diff --git a/plugins/host_httpclient.go b/plugins/host_httpclient.go
index f1d64deb7..4c8f85acd 100644
--- a/plugins/host_httpclient.go
+++ b/plugins/host_httpclient.go
@@ -14,6 +14,7 @@ import (
 
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/plugins/host"
+	"github.com/navidrome/navidrome/utils/httpclient"
 )
 
 const (
@@ -46,7 +47,7 @@ func newHTTPService(pluginName string, permission *HTTPPermission) *httpServiceI
 		requiredHosts: requiredHosts,
 	}
 	svc.client = &http.Client{
-		Transport: http.DefaultTransport,
+		Transport: httpclient.NewTransport(nil),
 		// Timeout is set per-request via context deadline, not here.
 		// CheckRedirect validates hosts and enforces redirect limits.
 		CheckRedirect: func(req *http.Request, via []*http.Request) error {
diff --git a/server/backgrounds/handler.go b/server/backgrounds/handler.go
index b00a51696..f6e159b4b 100644
--- a/server/backgrounds/handler.go
+++ b/server/backgrounds/handler.go
@@ -13,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/utils/cache"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	"github.com/navidrome/navidrome/utils/random"
 	"gopkg.in/yaml.v3"
 )
@@ -35,7 +36,7 @@ type Handler struct {
 
 func NewHandler() *Handler {
 	h := &Handler{}
-	h.httpClient = cache.NewHTTPClient(&http.Client{Timeout: 5 * time.Second}, imageListTTL)
+	h.httpClient = cache.NewHTTPClient(httpclient.New(5*time.Second), imageListTTL)
 	h.cache = cache.NewFileCache(imageCacheDir, imageCacheSize, imageCacheDir, imageCacheMaxItems, h.serveImage)
 	go func() {
 		_, _ = h.getImageList(log.NewContext(context.Background()))
@@ -78,7 +79,7 @@ func (h *Handler) serveImage(ctx context.Context, item cache.Item) (io.Reader, e
 	if image == "" {
 		return nil, errors.New("empty image name")
 	}
-	c := http.Client{Timeout: imageRequestTimeout}
+	c := httpclient.New(imageRequestTimeout)
 	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, imageURL(image), nil)
 	resp, err := c.Do(req) //nolint:bodyclose,gosec // No need to close resp.Body, it will be closed via the CachedStream wrapper
 	if errors.Is(err, context.DeadlineExceeded) {
diff --git a/utils/httpclient/httpclient.go b/utils/httpclient/httpclient.go
new file mode 100644
index 000000000..7fb48f36d
--- /dev/null
+++ b/utils/httpclient/httpclient.go
@@ -0,0 +1,35 @@
+// Package httpclient provides a shared http.Client factory that identifies
+// Navidrome via the User-Agent header on all outgoing requests.
+package httpclient
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/navidrome/navidrome/consts"
+)
+
+type uaTransport struct {
+	base http.RoundTripper
+}
+
+func (t *uaTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if _, ok := req.Header["User-Agent"]; !ok {
+		req = req.Clone(req.Context())
+		req.Header.Set("User-Agent", consts.HTTPUserAgent)
+	}
+	return t.base.RoundTrip(req)
+}
+
+// NewTransport wraps base (or http.DefaultTransport if nil) to set the
+// Navidrome User-Agent on requests that don't have one.
+func NewTransport(base http.RoundTripper) http.RoundTripper {
+	if base == nil {
+		base = http.DefaultTransport
+	}
+	return &uaTransport{base: base}
+}
+
+func New(timeout time.Duration) *http.Client {
+	return &http.Client{Timeout: timeout, Transport: NewTransport(nil)}
+}
diff --git a/utils/httpclient/httpclient_suite_test.go b/utils/httpclient/httpclient_suite_test.go
new file mode 100644
index 000000000..e18a9d0ad
--- /dev/null
+++ b/utils/httpclient/httpclient_suite_test.go
@@ -0,0 +1,17 @@
+package httpclient_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestHTTPClient(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "HTTPClient Suite")
+}
diff --git a/utils/httpclient/httpclient_test.go b/utils/httpclient/httpclient_test.go
new file mode 100644
index 000000000..c86b51165
--- /dev/null
+++ b/utils/httpclient/httpclient_test.go
@@ -0,0 +1,76 @@
+package httpclient_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"time"
+
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/utils/httpclient"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("httpclient", func() {
+	var server *httptest.Server
+	var receivedUA string
+
+	BeforeEach(func() {
+		server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			receivedUA = r.Header.Get("User-Agent")
+		}))
+		DeferCleanup(server.Close)
+	})
+
+	Describe("New", func() {
+		It("sets the Navidrome User-Agent when the request has none", func() {
+			c := httpclient.New(time.Second)
+			resp, err := c.Get(server.URL)
+			Expect(err).ToNot(HaveOccurred())
+			resp.Body.Close()
+			Expect(receivedUA).To(Equal(consts.HTTPUserAgent))
+		})
+
+		It("keeps a User-Agent already set by the caller", func() {
+			c := httpclient.New(time.Second)
+			req, err := http.NewRequest(http.MethodGet, server.URL, nil)
+			Expect(err).ToNot(HaveOccurred())
+			req.Header.Set("User-Agent", "CustomAgent/1.0")
+			resp, err := c.Do(req)
+			Expect(err).ToNot(HaveOccurred())
+			resp.Body.Close()
+			Expect(receivedUA).To(Equal("CustomAgent/1.0"))
+		})
+
+		It("applies the given timeout", func() {
+			c := httpclient.New(5 * time.Second)
+			Expect(c.Timeout).To(Equal(5 * time.Second))
+		})
+	})
+
+	Describe("NewTransport", func() {
+		It("uses the default transport when base is nil", func() {
+			c := &http.Client{Transport: httpclient.NewTransport(nil)}
+			resp, err := c.Get(server.URL)
+			Expect(err).ToNot(HaveOccurred())
+			resp.Body.Close()
+			Expect(receivedUA).To(Equal(consts.HTTPUserAgent))
+		})
+
+		It("does not modify the original request", func() {
+			c := &http.Client{Transport: httpclient.NewTransport(nil)}
+			req, err := http.NewRequest(http.MethodGet, server.URL, nil)
+			Expect(err).ToNot(HaveOccurred())
+			resp, err := c.Do(req)
+			Expect(err).ToNot(HaveOccurred())
+			resp.Body.Close()
+			Expect(req.Header).ToNot(HaveKey("User-Agent"))
+		})
+	})
+
+	Describe("HTTPUserAgent", func() {
+		It("identifies Navidrome with version and project URL", func() {
+			Expect(consts.HTTPUserAgent).To(Equal("Navidrome/" + consts.Version + " - https://github.com/navidrome"))
+		})
+	})
+})

From cb0a6cedd6c445d8040df3ac01fe69d06ca27b75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 25 Aug 2026 10:58:58 -0400
Subject: [PATCH 074/200] fix(scanner): keep album tag order from the files
 instead of alphabetical (#5872)

Album-level tags were ordered by frequency and then alphabetically by value.
Album.Genre is just the first genre in that list, so any album whose genres tie
on frequency, which is the normal case, displayed the alphabetically first genre
rather than the first one in the file. A file tagged
"Native American New Age; Indigenous American Traditional Music; Ambient"
showed up as "Ambient".

Break frequency ties on order of appearance instead. This affects all
album-level tags, so mood tagged "Happy; Chill" now keeps that order too.
MediaFiles.ToAlbum already sorts the files by path before flattening their tags,
so the aggregated order stays deterministic across scans.

Only album genre was affected; media_file tags already preserved file order.
---
 model/mediafile_test.go | 6 +++---
 model/tag.go            | 8 ++++++--
 model/tag_test.go       | 4 ++--
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/model/mediafile_test.go b/model/mediafile_test.go
index 097e3ca54..9ca3489bb 100644
--- a/model/mediafile_test.go
+++ b/model/mediafile_test.go
@@ -218,11 +218,11 @@ var _ = Describe("MediaFiles", func() {
 							{Tags: Tags{"genre": []string{"Alternative", "Rock"}}},
 						}
 					})
-					It("sets the correct Genre, sorted by frequency, then alphabetically", func() {
+					It("sets the correct Genre, sorted by frequency, then by order of appearance", func() {
 						album := mfs.ToAlbum()
 						Expect(album.Tags).To(HaveLen(2))
-						Expect(album.Tags).To(HaveKeyWithValue(TagGenre, []string{"Rock", "Alternative", "Punk"}))
-						Expect(album.Tags).To(HaveKeyWithValue(TagMood, []string{"Chill", "Happy"}))
+						Expect(album.Tags).To(HaveKeyWithValue(TagGenre, []string{"Rock", "Punk", "Alternative"}))
+						Expect(album.Tags).To(HaveKeyWithValue(TagMood, []string{"Happy", "Chill"}))
 					})
 				})
 				When("we have tags with mismatching case", func() {
diff --git a/model/tag.go b/model/tag.go
index bb4fce181..234cfb359 100644
--- a/model/tag.go
+++ b/model/tag.go
@@ -24,13 +24,17 @@ type TagList []Tag
 func (l TagList) GroupByFrequency() Tags {
 	grouped := map[string]map[string]int{}
 	values := map[string]string{}
-	for _, t := range l {
+	firstSeen := map[string]int{}
+	for i, t := range l {
 		if m, ok := grouped[string(t.TagName)]; !ok {
 			grouped[string(t.TagName)] = map[string]int{t.ID: 1}
 		} else {
 			m[t.ID]++
 		}
 		values[t.ID] = t.TagValue
+		if _, ok := firstSeen[t.ID]; !ok {
+			firstSeen[t.ID] = i
+		}
 	}
 
 	tags := Tags{}
@@ -42,7 +46,7 @@ func (l TagList) GroupByFrequency() Tags {
 		slices.SortFunc(idList, func(a, b string) int {
 			return cmp.Or(
 				cmp.Compare(counts[b], counts[a]),
-				cmp.Compare(values[a], values[b]),
+				cmp.Compare(firstSeen[a], firstSeen[b]),
 			)
 		})
 		tags[TagName(name)] = slice.Map(idList, func(id string) string { return values[id] })
diff --git a/model/tag_test.go b/model/tag_test.go
index c01aa0b4c..4dc99019b 100644
--- a/model/tag_test.go
+++ b/model/tag_test.go
@@ -93,7 +93,7 @@ var _ = Describe("Tag", func() {
 				Expect(groupedTags).To(HaveKeyWithValue(TagName("artist"), []string{"The Beatles", "The Rolling Stones"}))
 			})
 
-			It("should sort tags by name when frequency is the same", func() {
+			It("should keep the order the values appeared in when frequency is the same", func() {
 				tagList := TagList{
 					NewTag("genre", "Jazz"),
 					NewTag("genre", "Rock"),
@@ -103,7 +103,7 @@ var _ = Describe("Tag", func() {
 
 				groupedTags := tagList.GroupByFrequency()
 
-				Expect(groupedTags).To(HaveKeyWithValue(TagName("genre"), []string{"Alternative", "Jazz", "Pop", "Rock"}))
+				Expect(groupedTags).To(HaveKeyWithValue(TagName("genre"), []string{"Jazz", "Rock", "Alternative", "Pop"}))
 			})
 			It("should normalize casing", func() {
 				tagList := TagList{

From 97da9993d76126cadc45f54159ed6e5ce0932230 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 25 Aug 2026 18:48:43 -0400
Subject: [PATCH 075/200] fix(stream): abort the response when a transcoded
 stream is truncated (#6035)

* fix(stream): abort the response when a transcoded stream is truncated

When a transcode failed after some audio had already been sent, Serve logged
the error and returned nil, so Go finished the chunked body normally and the
client received an apparently complete, silently short file. Symfonium users
hit this on large offline syncs, and the worst path, ffmpeg dying mid-write
behind the transcoding cache, produced no error and nothing in the log above
Debug: the cache writer was closed plainly, so readers drained the truncated
entry to a clean EOF.

The root cause of that silence is an fscache limitation: Close is the only way
to end a cache write, and Close always means "complete". This adopts the
deluan/fscache fork, which adds CloseWithError: on failure copyAndClose now
cancels the entry with the cause, so every attached reader fails mid-read with
the real error instead of EOF, a late Get for the entry is refused, and the
entry never reports a final size. The error travels inside the entry each
reader holds, which makes per-generation delivery automatic and needs no
bookkeeping on our side.

With the failure arriving in-band, one change in Serve covers every mode: an
io.Copy error after bytes are on the wire panics with http.ErrAbortHandler.
Go aborts the response without the terminating chunk (RST_STREAM on HTTP/2),
chi's Recoverer re-panics that value, and the deferred stream.Close() still
runs, so the transcode limiter slot is released as before.

Two behaviors improve as side effects. A transcoder that dies before its first
byte now yields a Subsonic error response instead of a 200 with an empty body,
since the failure reaches Serve as an error while the status is still
unsent; genuinely empty output (clean EOF, exit 0) keeps the 200. And a failed
entry's invalidation no longer defers its unlink past a replacement entry
re-creating the same file, because canceling already closed its readers.

* fix(cache): warn when the cache writer cannot report failures to readers

The CloseWithError capability comes from the fscache fork via a go.mod
replace directive, and a type assertion picks it up. If that directive is
ever lost, the assertion fails silently, readers of a dead writer go back to
draining a truncated entry to a clean EOF, and nothing says so.

Two layers against that: a warning on the failure path when the writer lacks
the capability, and a test that asserts the writer fscache returns carries
it, so losing the fork fails CI instead of a listener's download.

* build: point the fscache replace at the fork's master

deluan/fscache#1 is merged; pin the merge commit instead of the review
branch. Pinned by sha because the module proxy still resolves the fork's
master ref to its pre-merge commit.

* build: reference the upstream fscache PR in the replace comment

The replace itself must keep pointing at the fork: the commit only exists in
djherbis/fscache under refs/pull/22/head, which the Go module fetcher cannot
resolve (verified: unknown revision for both short and full sha). The same
commit is advertised on the fork's master, so that is the fetchable source.
---
 core/stream/media_streamer.go      |  6 ++-
 core/stream/media_streamer_test.go | 51 ++++++++++++++++++++++++
 go.mod                             |  3 ++
 go.sum                             |  4 +-
 utils/cache/file_caches.go         | 11 ++++++
 utils/cache/file_caches_test.go    | 62 ++++++++++++++++++++++++++----
 6 files changed, 126 insertions(+), 11 deletions(-)

diff --git a/core/stream/media_streamer.go b/core/stream/media_streamer.go
index b09d9bab8..aaa3126b4 100644
--- a/core/stream/media_streamer.go
+++ b/core/stream/media_streamer.go
@@ -152,8 +152,9 @@ func (s *Stream) EstimatedContentLength() int {
 
 // Serve writes the stream to the HTTP response. For seekable streams it uses http.ServeContent
 // (supporting range requests). For non-seekable streams it writes directly and logs any errors.
-// Returns the number of bytes written and an error only when io.Copy fails with 0 bytes written
+// Returns the number of bytes written and an error only when it fails with 0 bytes written
 // (meaning the HTTP 200 status has not been flushed yet and the caller can still send an error response).
+// Once bytes are on the wire it panics with http.ErrAbortHandler instead, aborting the response.
 // Empty output (0 bytes, no error) is logged but not treated as an error.
 func (s *Stream) Serve(ctx context.Context, w http.ResponseWriter, r *http.Request) (int64, error) {
 	if s.Seekable() {
@@ -183,7 +184,8 @@ func (s *Stream) Serve(ctx context.Context, w http.ResponseWriter, r *http.Reque
 			w.Header().Del("Content-Length")
 			return 0, fmt.Errorf("sending transcoded file: %w", err)
 		}
-		return c, nil
+		// The 200 is already sent, so dropping the connection is the only way to say "truncated".
+		panic(http.ErrAbortHandler)
 	}
 	if c == 0 {
 		log.Error(ctx, "Transcoding returned empty output, ffmpeg may have failed. "+
diff --git a/core/stream/media_streamer_test.go b/core/stream/media_streamer_test.go
index fb1c59a60..e06599208 100644
--- a/core/stream/media_streamer_test.go
+++ b/core/stream/media_streamer_test.go
@@ -1,12 +1,18 @@
 package stream_test
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"io"
+	"net/http"
+	"net/http/httptest"
 	"os"
+	"testing/iotest"
 	"time"
 
+	"github.com/go-chi/chi/v5/middleware"
+
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/stream"
@@ -140,4 +146,49 @@ var _ = Describe("MediaStreamer", func() {
 			Expect(s.Seekable()).To(BeTrue())
 		})
 	})
+
+	Context("Serve", func() {
+		var mf *model.MediaFile
+		BeforeEach(func() {
+			var err error
+			mf, err = ds.MediaFile(ctx).Get("123")
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("keeps empty output a non-error, so callers still reply 200 with an empty body", func() {
+			s := stream.NewStream(mf, "mp3", 128, io.NopCloser(bytes.NewReader(nil)))
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest(http.MethodGet, "/", nil)
+
+			n, err := s.Serve(ctx, w, r)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(BeZero())
+			Expect(w.Code).To(Equal(http.StatusOK))
+		})
+
+		It("aborts the response when the source fails after sending data", func() {
+			src := io.NopCloser(io.MultiReader(
+				bytes.NewReader(bytes.Repeat([]byte("a"), 64*1024)),
+				iotest.ErrReader(errors.New("transcoder died")),
+			))
+			server := httptest.NewServer(serveHandler(stream.NewStream(mf, "mp3", 128, src)))
+			DeferCleanup(server.Close)
+
+			resp, err := http.Get(server.URL)
+			Expect(err).ToNot(HaveOccurred())
+			defer resp.Body.Close()
+
+			// A client-side read failure is the only observable proof the response was aborted.
+			_, err = io.ReadAll(resp.Body)
+			Expect(err).To(HaveOccurred())
+		})
+	})
 })
+
+// Serve runs behind the real server's Recoverer, which must let ErrAbortHandler through.
+func serveHandler(s *stream.Stream) http.Handler {
+	return middleware.Recoverer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = s.Serve(r.Context(), w, r)
+	}))
+}
diff --git a/go.mod b/go.mod
index 65a01a9b5..c0809f7b5 100644
--- a/go.mod
+++ b/go.mod
@@ -5,6 +5,9 @@ go 1.26
 // Fork to implement raw tags support
 replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3
 
+// Fork to implement CloseWithError, proposed upstream in https://github.com/djherbis/fscache/pull/22
+replace github.com/djherbis/fscache => github.com/deluan/fscache v0.9.1-0.20260825221051-a07d597526e2
+
 require (
 	github.com/Masterminds/squirrel v1.5.4
 	github.com/andybalholm/cascadia v1.3.4
diff --git a/go.sum b/go.sum
index c11f4bb20..8be5a910c 100644
--- a/go.sum
+++ b/go.sum
@@ -29,6 +29,8 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
+github.com/deluan/fscache v0.9.1-0.20260825221051-a07d597526e2 h1:s254V2hsrrCJXYtAn9WPG/5p4QHenfL9E+j6Tiq5MW4=
+github.com/deluan/fscache v0.9.1-0.20260825221051-a07d597526e2/go.mod h1:eNFa48vJrse+8ysT4IJnnUeXwLZNcR0JQumU/W/QoUI=
 github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3 h1:j7eSXqgtjhlNfwnMEzRdXnJGZTEw4I7J9TeQAll83bU=
 github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcHCKTtwzrd0HGfEmoODFA/qnk4=
@@ -39,8 +41,6 @@ github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36 h1:KtPfdSST6e0vJbM
 github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36/go.mod h1:RkQWLNITKkXHLP7LXxZSgEq+uFWU25M5qW7qfEhL9Wc=
 github.com/djherbis/atime v1.1.0 h1:rgwVbP/5by8BvvjBNrbh64Qz33idKT3pSnMSJsxhi0g=
 github.com/djherbis/atime v1.1.0/go.mod h1:28OF6Y8s3NQWwacXc5eZTsEsiMzp7LF8MbXE+XJPdBE=
-github.com/djherbis/fscache v0.10.2-0.20231127215153-442a07e326c4 h1:wdZllsLrDJtYfHiAKogB4PNHSDeO+v+5S3eqSWHGDlc=
-github.com/djherbis/fscache v0.10.2-0.20231127215153-442a07e326c4/go.mod h1:dHWjlanKIxaHVH1xJOTb4kzP800XdcXlgJ6JYlR2DPU=
 github.com/djherbis/stream v1.4.0 h1:aVD46WZUiq5kJk55yxJAyw6Kuera6kmC3i2vEQyW/AE=
 github.com/djherbis/stream v1.4.0/go.mod h1:cqjC1ZRq3FFwkGmUtHwcldbnW8f0Q4YuVsGW1eAFtOk=
 github.com/djherbis/times v1.6.0 h1:w2ctJ92J8fBvWPxugmXIv7Nz7Q3iDMKNx9v5ocVH20c=
diff --git a/utils/cache/file_caches.go b/utils/cache/file_caches.go
index dff9e4e7a..48cd135cb 100644
--- a/utils/cache/file_caches.go
+++ b/utils/cache/file_caches.go
@@ -255,6 +255,17 @@ func (fc *fileCache) copyAndClose(ctx context.Context, key string, w io.WriteClo
 	}
 	if err == nil {
 		fc.markComplete(ctx, key)
+	} else if cw, ok := w.(interface{ CloseWithError(error) error }); ok {
+		// Cancel instead of close, so readers fail with the cause rather than
+		// draining a truncated entry to a clean EOF.
+		if cErr := cw.CloseWithError(err); cErr != nil {
+			// Join, not Append: err is now shared with readers and must not be mutated.
+			return errors.Join(err, fmt.Errorf("closing cache writer: %w", cErr))
+		}
+		return err
+	} else {
+		log.Warn(ctx, "Cache writer cannot report failures; readers will see a truncated entry as a clean EOF",
+			"cache", fc.name, "key", key, err)
 	}
 	if cErr := w.Close(); cErr != nil {
 		err = multierror.Append(err, fmt.Errorf("closing cache writer: %w", cErr))
diff --git a/utils/cache/file_caches_test.go b/utils/cache/file_caches_test.go
index 974200656..3189de6b2 100644
--- a/utils/cache/file_caches_test.go
+++ b/utils/cache/file_caches_test.go
@@ -259,6 +259,54 @@ var _ = Describe("File Caches", func() {
 				}).Should(BeTrue())
 			})
 
+			It("gets a writer that can report failures to readers", func() {
+				// Guards the fork adoption: if the fscache replace directive is ever lost,
+				// this fails in CI instead of silently reviving the truncation bug.
+				fc := callNewFileCache("test", "10MB", "test", 0, nil)
+				_, w, err := fc.cache.Get("capability")
+				Expect(err).To(BeNil())
+				DeferCleanup(func() { _ = w.Close() })
+
+				_, ok := w.(interface{ CloseWithError(error) error })
+				Expect(ok).To(BeTrue(), "fscache writer lost CloseWithError; check the go.mod replace directive")
+			})
+
+			It("fails the reader with the cause instead of a clean EOF", func() {
+				fc := callNewFileCache("test", "10MB", "test", 0, func(ctx context.Context, arg Item) (io.Reader, error) {
+					return &partialThenErrReader{data: []byte("PARTIAL"), err: errors.New("transcoder died")}, nil
+				})
+				s, err := fc.Get(context.Background(), &testArg{"inband"})
+				Expect(err).To(BeNil())
+				DeferCleanup(func() { _ = s.Close() })
+
+				_, err = io.ReadAll(s)
+				Expect(err).To(MatchError(ContainSubstring("transcoder died")))
+			})
+
+			It("fails a reader that joined mid-write with the same cause", func() {
+				pr, pw := io.Pipe()
+				fc := callNewFileCache("test", "10MB", "test", 0, func(ctx context.Context, arg Item) (io.Reader, error) {
+					return pr, nil
+				})
+				s1, err := fc.Get(context.Background(), &testArg{"joined"})
+				Expect(err).To(BeNil())
+				DeferCleanup(func() { _ = s1.Close() })
+
+				// The blocking pipe write gives a happens-before: the entry is in flight.
+				_, err = pw.Write([]byte("PARTIAL"))
+				Expect(err).To(BeNil())
+
+				s2, err := fc.Get(context.Background(), &testArg{"joined"})
+				Expect(err).To(BeNil())
+				DeferCleanup(func() { _ = s2.Close() })
+				Expect(s2.Cached).To(BeTrue())
+
+				Expect(pw.CloseWithError(errors.New("transcoder died"))).To(Succeed())
+
+				_, err = io.ReadAll(s2)
+				Expect(err).To(MatchError(ContainSubstring("transcoder died")))
+			})
+
 			It("does not write a completion marker when the write fails after partial bytes", func() {
 				// Mimics a transcode that produces real output and then dies:
 				// the bytes land on disk, but the entry must NOT be marked complete.
@@ -304,9 +352,9 @@ var _ = Describe("File Caches", func() {
 				Expect(calls.Load()).To(BeNumerically("==", 2))
 			})
 
-			It("survives an invalidated entry's deferred file removal", func() {
-				// invalidate() drops the map entry but defers the unlink until readers close;
-				// a Get in that window re-creates the file, which the deferred unlink then eats.
+			It("removes a failed entry promptly, without eating its replacement", func() {
+				// Cancel closes the failed entry's readers, so its removal no longer defers
+				// past the point where a new entry re-creates the same file.
 				var n atomic.Int32
 				fc := callNewFileCache("test", "10MB", "test", 0, func(ctx context.Context, arg Item) (io.Reader, error) {
 					if n.Add(1) == 1 {
@@ -319,7 +367,6 @@ var _ = Describe("File Caches", func() {
 				s1, err := fc.Get(context.Background(), &testArg{"deferred"})
 				Expect(err).To(BeNil())
 
-				// The failed write invalidates the entry; the removal now waits on s1.
 				Eventually(func() bool { return fc.cache.Exists(key) }).Should(BeFalse())
 
 				s2, err := fc.Get(context.Background(), &testArg{"deferred"})
@@ -330,15 +377,16 @@ var _ = Describe("File Caches", func() {
 				Expect(s1.Close()).To(Succeed())
 
 				dataPath := fcSpreadFS(fc).KeyMapper(key)
-				Eventually(func() bool {
+				Consistently(func() error {
 					_, e := os.Stat(dataPath)
-					return os.IsNotExist(e)
-				}).Should(BeTrue(), "expected the deferred removal to take the re-created file")
+					return e
+				}).Should(Succeed(), "the replacement entry's file must survive the failed entry's cleanup")
 
 				s3, err := fc.Get(context.Background(), &testArg{"deferred"})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(io.ReadAll(s3)).To(Equal([]byte("GOOD")))
 				_ = s3.Close()
+				Expect(n.Load()).To(Equal(int32(2)), "the third Get must be served from cache")
 			})
 
 			It("re-fetches when an adopted entry's data file vanished", func() {

From f08b5297ee01e1c1195344f32204a8ffcd107750 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 25 Aug 2026 23:59:40 -0400
Subject: [PATCH 076/200] feat(ui): add Refresh Metadata to the album and
 artist context menus (#6036)

* refactor(artwork): move artworkItemName into core/artwork as ItemName

* feat(external): add RefreshInfo to force an external info refresh

RefreshInfo re-fetches and re-saves external info for one artist or
album, bypassing the TTL check that UpdateArtistInfo/UpdateAlbumInfo
use. It is synchronous; callers that must not block detach it themselves.

Also makes MockArtistRepo/MockAlbumRepo.UpdateExternalInfo persist to
Data (previously a no-op) and adds the new method to the e2e noopProvider,
both required so the interface addition compiles and is observable in tests.

* feat(external): broadcast RefreshResource after external info is saved

populateArtistInfo and populateAlbumInfo now emit the same RefreshResource
event the artwork worker uses, so the UI learns about both foreground and
background metadata refreshes.

* feat(nativeapi): replace artwork refresh endpoint with metadata refresh

* feat(ui): add refreshMetadata to the data provider

* feat(ui): add a Refresh Metadata item to the album and artist context menus

* fix(ui): re-fetch artist info when the record is refreshed

* test: fix mislabeled spec, add kind-gate negative case, guard nil mock maps

- Rename the RefreshInfo spec that claimed to cover the save-failure/broadcast
  path: SetError(true) fails Get too, so it only proves RefreshInfo bails out
  early at getArtist.
- Add a spec proving playlist refreshes skip the external-info step, since
  that asymmetry (al/ar only) was documented but unasserted.
- Add lazy nil-map init to MockAlbumRepo/MockArtistRepo.UpdateExternalInfo so
  a composite-literal-constructed mock doesn't panic on first save.

* test: relocate discArtworkName specs from cmd to core/artwork

artworkItemName moved into core/artwork as ItemName in an earlier commit, but
its disc-name specs stayed behind in cmd/artwork_test.go, reaching across
packages. Move them to core/artwork/item_name_test.go where the code now lives.

* fix(ui): shape refreshMetadata like a react-admin response

react-admin validates custom dataProvider methods and rejects any response
without a `data` key, so the raw httpClient promise made every click surface
an error toast instead of the success message. The unit test mocked
useDataProvider, which skips that validation.

Also folds "which kinds have external info" into external.HasInfo so the
handler stops restating it, drops the nil-broker guard that only existed for
tests, and delegates the mocks' UpdateExternalInfo to Put.

* refactor(external): unexport infoKinds

Only HasInfo is used outside the package, so the slice itself does not need
to be exported.

* refactor(artwork): fold ItemName into housekeeping.go next to Refresh

ItemName exists to guard Refresh from ids that would orphan a queue row, and
both callers invoke them back to back. A separate file hid that pairing; it was
only split out to keep the move out of cmd/ legible in review.

* fix(nativeapi): return 500 when the refresh lookup fails for a non-ErrNotFound reason

A transient repository error told the admin the id did not exist, and the error
was dropped without a log line, so nothing pointed at the real cause.

Also drops the inherited claim that clearing artwork state shows a placeholder.
Reads fall back to local resolution, so that only holds when there is no local art.

* fix(ui): move Refresh Metadata above Get Info in the context menu

Menu order follows key insertion order in the options object, so the new spec
pins the position rather than leaving it to be shuffled by the next addition.
---
 cmd/artwork.go                                |  61 +-----
 cmd/artwork_test.go                           |  27 ---
 cmd/wire_gen.go                               |   9 +-
 core/artwork/housekeeping.go                  |  57 ++++++
 core/artwork/housekeeping_test.go             |  53 ++++++
 core/external/provider.go                     |  47 ++++-
 core/external/provider_refreshinfo_test.go    | 156 +++++++++++++++
 core/external/provider_similarsongs_test.go   |   2 +-
 core/external/provider_topsongs_test.go       |   2 +-
 .../external/provider_updatealbuminfo_test.go |   2 +-
 .../provider_updateartistinfo_test.go         |   2 +-
 resources/i18n/pt-br.json                     |   4 +-
 server/nativeapi/artwork.go                   |  34 ----
 server/nativeapi/artwork_test.go              |  95 ----------
 server/nativeapi/config_test.go               |   2 +-
 server/nativeapi/library_test.go              |   2 +-
 server/nativeapi/metadata.go                  |  56 ++++++
 server/nativeapi/metadata_test.go             | 177 ++++++++++++++++++
 server/nativeapi/native_api.go                |   8 +-
 server/nativeapi/native_api_song_test.go      |   2 +-
 server/nativeapi/playlists_test.go            |   2 +-
 server/nativeapi/plugin_test.go               |   2 +-
 .../user_password_token_refresh_test.go       |   2 +-
 server/subsonic/e2e/e2e_suite_test.go         |   4 +
 tests/mock_album_repo.go                      |   8 +-
 tests/mock_artist_repo.go                     |   8 +-
 ui/src/artist/ArtistShow.jsx                  |   6 +-
 ui/src/artist/ArtistShow.test.jsx             |  63 +++++++
 ui/src/common/ContextMenus.jsx                |  18 +-
 ui/src/common/ContextMenus.test.jsx           |  57 +++++-
 ui/src/dataProvider/wrapperDataProvider.js    |   8 +
 .../dataProvider/wrapperDataProvider.test.js  |  33 ++++
 ui/src/i18n/en.json                           |   4 +-
 33 files changed, 766 insertions(+), 247 deletions(-)
 create mode 100644 core/external/provider_refreshinfo_test.go
 delete mode 100644 server/nativeapi/artwork.go
 delete mode 100644 server/nativeapi/artwork_test.go
 create mode 100644 server/nativeapi/metadata.go
 create mode 100644 server/nativeapi/metadata_test.go
 create mode 100644 ui/src/artist/ArtistShow.test.jsx

diff --git a/cmd/artwork.go b/cmd/artwork.go
index 8b9e28f0e..5cd4fc146 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -648,7 +648,7 @@ func refreshItems(ctx context.Context, ds model.DataStore, targets []model.Artwo
 	for _, t := range targets {
 		kind, id := t.Kind, t.ID
 		// artwork.Refresh would happily queue an id that does not exist, orphaning a queue row.
-		if _, err := artworkItemName(ctx, ds, kind, id); err != nil {
+		if _, err := artwork.ItemName(ctx, ds, kind, id); err != nil {
 			log.Error(ctx, "Item not found", "kind", kind, "id", id, err)
 			failed++
 			continue
@@ -963,7 +963,7 @@ func runExplain(ctx context.Context, args []string) {
 	}
 	kind, id := targets[0].Kind, targets[0].ID
 
-	name, err := artworkItemName(ctx, ds, kind, id)
+	name, err := artwork.ItemName(ctx, ds, kind, id)
 	if err != nil {
 		log.Fatal(ctx, "Item not found", "kind", kind, "id", id, err)
 	}
@@ -1005,60 +1005,3 @@ func runExplain(ctx context.Context, args []string) {
 		log.Fatal(ctx, "Failed to resolve artwork", "kind", kind, "id", id, rep.resolveErr)
 	}
 }
-
-// artworkItemName looks the entity up under its own kind, so a mismatched kind/id pair is
-// reported as not found instead of silently explaining another entity's artwork.
-func artworkItemName(ctx context.Context, ds model.DataStore, kind model.Kind, id string) (string, error) {
-	switch kind {
-	case model.KindArtistArtwork:
-		ar, err := ds.Artist(ctx).Get(id)
-		if err != nil {
-			return "", err
-		}
-		return ar.Name, nil
-	case model.KindAlbumArtwork:
-		al, err := ds.Album(ctx).Get(id)
-		if err != nil {
-			return "", err
-		}
-		return al.Name, nil
-	case model.KindPlaylistArtwork:
-		pls, err := ds.Playlist(ctx).Get(id)
-		if err != nil {
-			return "", err
-		}
-		return pls.Name, nil
-	case model.KindRadioArtwork:
-		rd, err := ds.Radio(ctx).Get(id)
-		if err != nil {
-			return "", err
-		}
-		return rd.Name, nil
-	case model.KindMediaFileArtwork:
-		mf, err := ds.MediaFile(ctx).Get(id)
-		if err != nil {
-			return "", err
-		}
-		return mf.Title, nil
-	case model.KindDiscArtwork:
-		return discArtworkName(ctx, ds, id)
-	}
-	return "", fmt.Errorf("unsupported kind %q", kind.Prefix())
-}
-
-func discArtworkName(ctx context.Context, ds model.DataStore, id string) (string, error) {
-	albumID, discNumber, err := model.ParseDiscArtworkID(id)
-	if err != nil {
-		return "", err
-	}
-	al, err := ds.Album(ctx).Get(albumID)
-	if err != nil {
-		return "", err
-	}
-	name := fmt.Sprintf("%s (disc %d)", al.Name, discNumber)
-	// The subtitle is itself a DiscArtPriority candidate, so name it where the chain can be read against it.
-	if subtitle := strings.TrimSpace(al.Discs[discNumber]); subtitle != "" {
-		name += ": " + subtitle
-	}
-	return name, nil
-}
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index f17206aaa..a7220d2d5 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -424,33 +424,6 @@ var _ = Describe("explainConfig", func() {
 	)
 })
 
-var _ = Describe("discArtworkName", func() {
-	var ds *tests.MockDataStore
-
-	BeforeEach(func() {
-		albumRepo := tests.CreateMockAlbumRepo()
-		albumRepo.SetData(model.Albums{{ID: "al-1", Name: "Sandinista!", Discs: model.Discs{2: "Side Three"}}})
-		ds = &tests.MockDataStore{MockedAlbum: albumRepo}
-	})
-
-	It("names the album, the disc and its subtitle", func() {
-		name, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1:2")
-		Expect(err).ToNot(HaveOccurred())
-		Expect(name).To(Equal("Sandinista! (disc 2): Side Three"))
-	})
-
-	It("omits the subtitle when the disc has none", func() {
-		name, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1:1")
-		Expect(err).ToNot(HaveOccurred())
-		Expect(name).To(Equal("Sandinista! (disc 1)"))
-	})
-
-	It("rejects an id that is not <albumID>:<disc>", func() {
-		_, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1")
-		Expect(err).To(HaveOccurred())
-	})
-})
-
 var _ = Describe("artwork refresh command", func() {
 	It("requires at least one argument", func() {
 		Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{})).To(HaveOccurred())
diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index 49a99f8ca..de4c55a1e 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -76,7 +76,10 @@ func CreateNativeAPIRouter(ctx context.Context) *nativeapi.Router {
 	library := core.NewLibrary(dataStore, modelScanner, watcher, broker, manager)
 	user := core.NewUser(dataStore, manager)
 	maintenance := core.NewMaintenance(dataStore)
-	router := nativeapi.New(dataStore, share, playlistsPlaylists, insights, library, user, maintenance, manager, uploader)
+	agentsAgents := agents.GetAgents(dataStore, manager)
+	matcherMatcher := matcher.New(dataStore)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher, broker)
+	router := nativeapi.New(dataStore, share, playlistsPlaylists, insights, library, user, maintenance, manager, uploader, provider)
 	return router
 }
 
@@ -97,7 +100,7 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	agentsAgents := agents.GetAgents(dataStore, manager)
 	matcherMatcher := matcher.New(dataStore)
-	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher, broker)
 	uploader := artwork.NewUploader(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
 	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
@@ -129,7 +132,7 @@ func CreateJellyfinAPIRouter(ctx context.Context) *jellyfin.Router {
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
 	agentsAgents := agents.GetAgents(dataStore, manager)
 	matcherMatcher := matcher.New(dataStore)
-	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher)
+	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher, broker)
 	sonicSonic := sonic.New(dataStore, manager, matcherMatcher)
 	lyricsLyrics := lyrics.NewLyrics(dataStore, manager)
 	router := jellyfin.New(dataStore, artworkArtwork, mediaStreamer, transcodeDecider, players, playTracker, playlistsPlaylists, provider, sonicSonic, lyricsLyrics, broker)
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
index ce98e2a03..a3330d7cf 100644
--- a/core/artwork/housekeeping.go
+++ b/core/artwork/housekeeping.go
@@ -166,6 +166,63 @@ func enqueueMissingAll(ctx context.Context, ds model.DataStore) error {
 	return nil
 }
 
+// ItemName resolves a kind+id to the entity's display name, and errors when the item
+// does not exist. Callers use it to reject ids that would otherwise orphan a queue row.
+func ItemName(ctx context.Context, ds model.DataStore, kind model.Kind, id string) (string, error) {
+	switch kind {
+	case model.KindArtistArtwork:
+		ar, err := ds.Artist(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return ar.Name, nil
+	case model.KindAlbumArtwork:
+		al, err := ds.Album(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return al.Name, nil
+	case model.KindPlaylistArtwork:
+		pls, err := ds.Playlist(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return pls.Name, nil
+	case model.KindRadioArtwork:
+		rd, err := ds.Radio(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return rd.Name, nil
+	case model.KindMediaFileArtwork:
+		mf, err := ds.MediaFile(ctx).Get(id)
+		if err != nil {
+			return "", err
+		}
+		return mf.Title, nil
+	case model.KindDiscArtwork:
+		return discArtworkName(ctx, ds, id)
+	}
+	return "", fmt.Errorf("unsupported kind %q", kind.Prefix())
+}
+
+func discArtworkName(ctx context.Context, ds model.DataStore, id string) (string, error) {
+	albumID, discNumber, err := model.ParseDiscArtworkID(id)
+	if err != nil {
+		return "", err
+	}
+	al, err := ds.Album(ctx).Get(albumID)
+	if err != nil {
+		return "", err
+	}
+	name := fmt.Sprintf("%s (disc %d)", al.Name, discNumber)
+	// The subtitle is itself a DiscArtPriority candidate, so name it where the chain can be read against it.
+	if subtitle := strings.TrimSpace(al.Discs[discNumber]); subtitle != "" {
+		name += ": " + subtitle
+	}
+	return name, nil
+}
+
 // Refresh drops an item's resolved artwork state and re-queues it at Bump priority.
 func Refresh(ctx context.Context, ds model.DataStore, kind model.Kind, id string) error {
 	if err := ds.Artwork(ctx).DeleteForItems(kind, []string{id}); err != nil {
diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.go
index 7aecd2760..c9809203a 100644
--- a/core/artwork/housekeeping_test.go
+++ b/core/artwork/housekeeping_test.go
@@ -332,3 +332,56 @@ var _ = Describe("Housekeeping", func() {
 		})
 	})
 })
+
+var _ = Describe("ItemName", func() {
+	var ds *tests.MockDataStore
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		albumRepo := tests.CreateMockAlbumRepo()
+		albumRepo.SetData(model.Albums{
+			{ID: "al-1", Name: "Kid A"},
+			{ID: "al-2", Name: "Sandinista!", Discs: model.Discs{2: "Side Three"}},
+		})
+		ds = &tests.MockDataStore{MockedAlbum: albumRepo}
+		Expect(ds.Artist(ctx).(*tests.MockArtistRepo).Put(&model.Artist{ID: "ar-1", Name: "Radiohead"})).To(Succeed())
+	})
+
+	It("returns the album name", func() {
+		Expect(ItemName(ctx, ds, model.KindAlbumArtwork, "al-1")).To(Equal("Kid A"))
+	})
+
+	It("returns the artist name", func() {
+		Expect(ItemName(ctx, ds, model.KindArtistArtwork, "ar-1")).To(Equal("Radiohead"))
+	})
+
+	It("errors for an unknown album", func() {
+		_, err := ItemName(ctx, ds, model.KindAlbumArtwork, "nope")
+		Expect(err).To(MatchError(model.ErrNotFound))
+	})
+
+	It("errors for an unsupported kind", func() {
+		// model.Kind is a struct with unexported fields, so the zero value is the only
+		// unsupported Kind constructible from outside package model.
+		_, err := ItemName(ctx, ds, model.Kind{}, "al-1")
+		Expect(err).To(HaveOccurred())
+	})
+
+	Context("disc artwork", func() {
+		It("names the album, the disc and its subtitle", func() {
+			Expect(ItemName(ctx, ds, model.KindDiscArtwork, "al-2:2")).
+				To(Equal("Sandinista! (disc 2): Side Three"))
+		})
+
+		It("omits the subtitle when the disc has none", func() {
+			Expect(ItemName(ctx, ds, model.KindDiscArtwork, "al-2:1")).
+				To(Equal("Sandinista! (disc 1)"))
+		})
+
+		It("rejects an id that is not <albumID>:<disc>", func() {
+			_, err := ItemName(ctx, ds, model.KindDiscArtwork, "al-2")
+			Expect(err).To(HaveOccurred())
+		})
+	})
+})
diff --git a/core/external/provider.go b/core/external/provider.go
index 782c7c3aa..5c46dc644 100644
--- a/core/external/provider.go
+++ b/core/external/provider.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"slices"
 	"sort"
 	"strings"
 	"time"
@@ -14,6 +15,7 @@ import (
 	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/utils"
 	. "github.com/navidrome/navidrome/utils/gg"
 	"github.com/navidrome/navidrome/utils/slice"
@@ -33,12 +35,14 @@ type Provider interface {
 	UpdateArtistInfo(ctx context.Context, id string, count int, includeNotPresent bool) (*model.Artist, error)
 	SimilarSongs(ctx context.Context, id string, count int) (model.MediaFiles, error)
 	TopSongs(ctx context.Context, artist, artistId string, count int) (model.MediaFiles, error)
+	RefreshInfo(ctx context.Context, kind model.Kind, id string) error
 }
 
 type provider struct {
 	ds          model.DataStore
 	ag          Agents
 	matcher     *matcher.Matcher
+	broker      events.Broker
 	artistQueue refreshQueue[auxArtist]
 	albumQueue  refreshQueue[auxAlbum]
 }
@@ -83,13 +87,17 @@ type Agents interface {
 	agents.SimilarSongsByArtistRetriever
 }
 
-func NewProvider(ds model.DataStore, agents Agents, m *matcher.Matcher) Provider {
-	e := &provider{ds: ds, ag: agents, matcher: m}
+func NewProvider(ds model.DataStore, agents Agents, m *matcher.Matcher, broker events.Broker) Provider {
+	e := &provider{ds: ds, ag: agents, matcher: m, broker: broker}
 	e.artistQueue = newRefreshQueue(context.TODO(), e.populateArtistInfo)
 	e.albumQueue = newRefreshQueue(context.TODO(), e.populateAlbumInfo)
 	return e
 }
 
+func (e *provider) broadcastRefresh(ctx context.Context, resource, id string) {
+	e.broker.SendBroadcastMessage(ctx, (&events.RefreshResource{}).With(resource, id))
+}
+
 func (e *provider) getAlbum(ctx context.Context, id string) (auxAlbum, error) {
 	var entity any
 	entity, err := model.GetEntityByID(ctx, e.ds, id)
@@ -179,6 +187,7 @@ func (e *provider) populateAlbumInfo(ctx context.Context, album auxAlbum) (auxAl
 			"elapsed", time.Since(start), err)
 	} else {
 		log.Trace(ctx, "AlbumInfo collected", "album", album, "elapsed", time.Since(start))
+		e.broadcastRefresh(ctx, "album", album.ID)
 	}
 
 	return album, nil
@@ -272,10 +281,44 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 			"elapsed", time.Since(start), err)
 	} else {
 		log.Trace(ctx, "ArtistInfo collected", "artist", artist, "elapsed", time.Since(start))
+		e.broadcastRefresh(ctx, "artist", artist.ID)
 	}
 	return artist, nil
 }
 
+// infoKinds are the kinds RefreshInfo can act on. Callers check this instead of restating
+// the set, so the switch below stays the only place that has to know how each kind loads.
+var infoKinds = []model.Kind{model.KindArtistArtwork, model.KindAlbumArtwork}
+
+// HasInfo reports whether a kind has external info to refresh.
+func HasInfo(kind model.Kind) bool { return slices.Contains(infoKinds, kind) }
+
+// RefreshInfo re-fetches external info for one item, ignoring the TTL. It is synchronous:
+// callers that must not block are responsible for detaching it.
+func (e *provider) RefreshInfo(ctx context.Context, kind model.Kind, id string) error {
+	ctx, cancel := context.WithTimeout(ctx, refreshTimeout)
+	defer cancel()
+
+	switch kind {
+	case model.KindArtistArtwork:
+		artist, err := e.getArtist(ctx, id)
+		if err != nil {
+			return err
+		}
+		_, err = e.populateArtistInfo(ctx, artist)
+		return err
+	case model.KindAlbumArtwork:
+		album, err := e.getAlbum(ctx, id)
+		if err != nil {
+			return err
+		}
+		_, err = e.populateAlbumInfo(ctx, album)
+		return err
+	default:
+		return model.ErrNotFound
+	}
+}
+
 func (e *provider) TopSongs(ctx context.Context, artistName, id string, count int) (model.MediaFiles, error) {
 	artist, err := e.findArtist(ctx, artistName, id)
 	if err != nil {
diff --git a/core/external/provider_refreshinfo_test.go b/core/external/provider_refreshinfo_test.go
new file mode 100644
index 000000000..e7910a734
--- /dev/null
+++ b/core/external/provider_refreshinfo_test.go
@@ -0,0 +1,156 @@
+package external_test
+
+import (
+	"context"
+	"slices"
+	"sync"
+	"time"
+
+	"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/server/events"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"github.com/stretchr/testify/mock"
+)
+
+type fakeBroker struct {
+	events.Broker
+	mu     sync.Mutex
+	events []events.Event
+}
+
+func (f *fakeBroker) SendBroadcastMessage(_ context.Context, e events.Event) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.events = append(f.events, e)
+}
+
+func (f *fakeBroker) sent() []events.Event {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return slices.Clone(f.events)
+}
+
+var _ = Describe("Provider - RefreshInfo", func() {
+	var (
+		ctx            context.Context
+		p              external.Provider
+		ds             *tests.MockDataStore
+		ag             *mockAgents
+		broker         *fakeBroker
+		mockArtistRepo *tests.MockArtistRepo
+		mockAlbumRepo  *tests.MockAlbumRepo
+	)
+
+	expectArtistAgents := func() {
+		ag.On("GetArtistMBID", mock.Anything, mock.Anything, mock.Anything).Return("mbid-1", nil)
+		ag.On("GetArtistImages", mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+			Return([]agents.ExternalImage{}, nil)
+		ag.On("GetArtistBiography", mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+			Return("Fresh Bio", nil)
+		ag.On("GetArtistURL", mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+			Return("http://artist.url", nil)
+		ag.On("GetSimilarArtists", mock.Anything, mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+			Return([]agents.Artist{}, nil)
+	}
+
+	expectAlbumAgents := func() {
+		ag.On("GetAlbumInfo", mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+			Return(&agents.AlbumInfo{URL: "http://album.url", Description: "Fresh Notes"}, nil)
+		ag.On("GetAlbumImages", mock.Anything, mock.Anything, mock.Anything, mock.Anything).
+			Return([]agents.ExternalImage{}, nil)
+	}
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+		ds = new(tests.MockDataStore)
+		ag = new(mockAgents)
+		broker = &fakeBroker{}
+		p = external.NewProvider(ds, ag, matcher.New(ds), broker)
+		mockArtistRepo = ds.Artist(ctx).(*tests.MockArtistRepo)
+		mockAlbumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
+	})
+
+	It("repopulates an artist even when its info is fresh", func() {
+		fresh := time.Now()
+		mockArtistRepo.SetData(model.Artists{{
+			ID: "ar-1", Name: "Test Artist", Biography: "stale", ExternalInfoUpdatedAt: &fresh,
+		}})
+		expectArtistAgents()
+
+		Expect(p.RefreshInfo(ctx, model.KindArtistArtwork, "ar-1")).To(Succeed())
+
+		saved, err := mockArtistRepo.Get("ar-1")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(saved.Biography).To(Equal("Fresh Bio"))
+	})
+
+	It("repopulates an album even when its info is fresh", func() {
+		fresh := time.Now()
+		mockAlbumRepo.SetData(model.Albums{{
+			ID: "al-1", Name: "Test Album", AlbumArtist: "Test Artist",
+			Description: "stale", ExternalInfoUpdatedAt: &fresh,
+		}})
+		expectAlbumAgents()
+
+		Expect(p.RefreshInfo(ctx, model.KindAlbumArtwork, "al-1")).To(Succeed())
+
+		saved, err := mockAlbumRepo.Get("al-1")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(saved.Description).To(Equal("Fresh Notes"))
+	})
+
+	It("returns ErrNotFound for an unknown id", func() {
+		Expect(p.RefreshInfo(ctx, model.KindArtistArtwork, "nope")).To(MatchError(model.ErrNotFound))
+	})
+
+	It("returns ErrNotFound for a kind with no external info", func() {
+		Expect(p.RefreshInfo(ctx, model.KindPlaylistArtwork, "pl-1")).To(MatchError(model.ErrNotFound))
+	})
+
+	It("broadcasts a RefreshResource naming the artist", func() {
+		mockArtistRepo.SetData(model.Artists{{ID: "ar-1", Name: "Test Artist"}})
+		expectArtistAgents()
+
+		Expect(p.RefreshInfo(ctx, model.KindArtistArtwork, "ar-1")).To(Succeed())
+
+		sent := broker.sent()
+		Expect(sent).To(HaveLen(1))
+		rr, ok := sent[0].(*events.RefreshResource)
+		Expect(ok).To(BeTrue())
+		Expect(rr.Data(rr)).To(ContainSubstring("ar-1"))
+		Expect(rr.Data(rr)).To(ContainSubstring("artist"))
+	})
+
+	It("broadcasts a RefreshResource naming the album", func() {
+		mockAlbumRepo.SetData(model.Albums{{ID: "al-1", Name: "Test Album", AlbumArtist: "Test Artist"}})
+		expectAlbumAgents()
+
+		Expect(p.RefreshInfo(ctx, model.KindAlbumArtwork, "al-1")).To(Succeed())
+
+		sent := broker.sent()
+		Expect(sent).To(HaveLen(1))
+		Expect(sent[0].Data(sent[0])).To(ContainSubstring("album"))
+		Expect(sent[0].Data(sent[0])).To(ContainSubstring("al-1"))
+	})
+
+	It("does not broadcast when the artist cannot be loaded", func() {
+		mockArtistRepo.SetData(model.Artists{{ID: "ar-1", Name: "Test Artist"}})
+		expectArtistAgents()
+		mockArtistRepo.SetError(true)
+
+		_ = p.RefreshInfo(ctx, model.KindArtistArtwork, "ar-1")
+
+		Expect(broker.sent()).To(BeEmpty())
+	})
+
+	It("reports which kinds have external info", func() {
+		Expect(external.HasInfo(model.KindArtistArtwork)).To(BeTrue())
+		Expect(external.HasInfo(model.KindAlbumArtwork)).To(BeTrue())
+		Expect(external.HasInfo(model.KindPlaylistArtwork)).To(BeFalse())
+	})
+})
diff --git a/core/external/provider_similarsongs_test.go b/core/external/provider_similarsongs_test.go
index ac54495f4..3944edb68 100644
--- a/core/external/provider_similarsongs_test.go
+++ b/core/external/provider_similarsongs_test.go
@@ -61,7 +61,7 @@ var _ = Describe("Provider - SimilarSongs", func() {
 			similarAgent:  mockSimilarAgent,
 		}
 
-		provider = NewProvider(ds, agentsCombined, matcher.New(ds))
+		provider = NewProvider(ds, agentsCombined, matcher.New(ds), &fakeBroker{})
 	})
 
 	// Resolves track-1 through the GetEntityByID probe order and on to its artist. Left permissive:
diff --git a/core/external/provider_topsongs_test.go b/core/external/provider_topsongs_test.go
index 795a7ff74..16e8ad840 100644
--- a/core/external/provider_topsongs_test.go
+++ b/core/external/provider_topsongs_test.go
@@ -45,7 +45,7 @@ var _ = Describe("Provider - TopSongs", func() {
 
 		ag = new(mockAgents)
 
-		p = NewProvider(ds, ag, matcher.New(ds))
+		p = NewProvider(ds, ag, matcher.New(ds), &fakeBroker{})
 	})
 
 	It("returns top songs for a known artist", func() {
diff --git a/core/external/provider_updatealbuminfo_test.go b/core/external/provider_updatealbuminfo_test.go
index 21824c93f..a54ef922c 100644
--- a/core/external/provider_updatealbuminfo_test.go
+++ b/core/external/provider_updatealbuminfo_test.go
@@ -34,7 +34,7 @@ var _ = Describe("Provider - UpdateAlbumInfo", func() {
 		ctx = GinkgoT().Context()
 		ds = new(tests.MockDataStore)
 		ag = new(mockAgents)
-		p = external.NewProvider(ds, ag, matcher.New(ds))
+		p = external.NewProvider(ds, ag, matcher.New(ds), &fakeBroker{})
 		mockAlbumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
 		conf.Server.DevAlbumInfoTimeToLive = 1 * time.Hour
 	})
diff --git a/core/external/provider_updateartistinfo_test.go b/core/external/provider_updateartistinfo_test.go
index d783128fb..853d56bbc 100644
--- a/core/external/provider_updateartistinfo_test.go
+++ b/core/external/provider_updateartistinfo_test.go
@@ -37,7 +37,7 @@ var _ = Describe("Provider - UpdateArtistInfo", func() {
 		ctx = GinkgoT().Context()
 		ds = new(tests.MockDataStore)
 		ag = new(mockAgents)
-		p = external.NewProvider(ds, ag, matcher.New(ds))
+		p = external.NewProvider(ds, ag, matcher.New(ds), &fakeBroker{})
 		mockArtistRepo = ds.Artist(ctx).(*tests.MockArtistRepo)
 	})
 
diff --git a/resources/i18n/pt-br.json b/resources/i18n/pt-br.json
index 9a6338ae1..a4ad6bc8c 100644
--- a/resources/i18n/pt-br.json
+++ b/resources/i18n/pt-br.json
@@ -93,6 +93,7 @@
         "addToPlaylist": "Adicionar à playlist",
         "download": "Baixar",
         "info": "Detalhes",
+        "refresh": "Atualizar Metadados",
         "share": "Compartilhar"
       },
       "lists": {
@@ -602,7 +603,8 @@
     "coverUploaded": "Capa atualizada",
     "coverRemoved": "Capa removida",
     "coverUploadError": "Erro ao enviar capa",
-    "coverRemoveError": "Erro ao remover capa"
+    "coverRemoveError": "Erro ao remover capa",
+    "metadataRefreshStarted": "Atualizando metadados em segundo plano"
   },
   "menu": {
     "library": "Biblioteca",
diff --git a/server/nativeapi/artwork.go b/server/nativeapi/artwork.go
deleted file mode 100644
index cfd943b1f..000000000
--- a/server/nativeapi/artwork.go
+++ /dev/null
@@ -1,34 +0,0 @@
-package nativeapi
-
-import (
-	"net/http"
-	"slices"
-
-	"github.com/go-chi/chi/v5"
-	"github.com/navidrome/navidrome/core/artwork"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/model"
-)
-
-func (api *Router) addArtworkRoute(r chi.Router) {
-	r.Post("/artwork/{kind}/{id}/refresh", api.refreshArtwork())
-}
-
-// State is deliberately cleared so a wrong pick disappears immediately (placeholder until re-resolved).
-func (api *Router) refreshArtwork() http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		ctx := r.Context()
-		kind, _ := model.ParseKind(chi.URLParam(r, "kind"))
-		id := chi.URLParam(r, "id")
-		if !slices.Contains(artwork.RefreshableKinds, kind) {
-			http.Error(w, "invalid artwork kind", http.StatusBadRequest)
-			return
-		}
-		if err := artwork.Refresh(ctx, api.ds, kind, id); err != nil {
-			log.Error(ctx, "Error refreshing artwork", "kind", kind, "id", id, err)
-			http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
-			return
-		}
-		w.WriteHeader(http.StatusNoContent)
-	}
-}
diff --git a/server/nativeapi/artwork_test.go b/server/nativeapi/artwork_test.go
deleted file mode 100644
index b26a94e6a..000000000
--- a/server/nativeapi/artwork_test.go
+++ /dev/null
@@ -1,95 +0,0 @@
-package nativeapi
-
-import (
-	"context"
-	"net/http"
-	"net/http/httptest"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/conf/configtest"
-	"github.com/navidrome/navidrome/core/auth"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/server"
-	"github.com/navidrome/navidrome/tests"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Artwork API", func() {
-	var ds *tests.MockDataStore
-	var artRepo *tests.MockArtworkRepo
-	var queueRepo *tests.MockArtworkQueueRepo
-	var router http.Handler
-	var adminToken, userToken string
-
-	BeforeEach(func() {
-		DeferCleanup(configtest.SetupConfig())
-		conf.Server.EnableSharing = false
-		artRepo = tests.CreateMockArtworkRepo()
-		queueRepo = tests.CreateMockArtworkQueueRepo()
-		ds = &tests.MockDataStore{MockedArtwork: artRepo, MockedArtworkQueue: queueRepo}
-		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil)
-		router = server.JWTVerifier(nativeRouter)
-
-		adminUser := model.User{ID: "admin-1", UserName: "admin", IsAdmin: true, NewPassword: "adminpass"}
-		regularUser := model.User{ID: "user-1", UserName: "regular", IsAdmin: false, NewPassword: "userpass"}
-		Expect(ds.User(context.TODO()).Put(&adminUser)).To(Succeed())
-		Expect(ds.User(context.TODO()).Put(&regularUser)).To(Succeed())
-
-		var err error
-		adminToken, err = auth.CreateToken(&adminUser)
-		Expect(err).ToNot(HaveOccurred())
-		userToken, err = auth.CreateToken(&regularUser)
-		Expect(err).ToNot(HaveOccurred())
-	})
-
-	Describe("POST /api/artwork/{kind}/{id}/refresh", func() {
-		It("clears state and enqueues a Bump for admins", func() {
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
-				ItemKind: "al", ItemID: "al-1", Hash: "oldhash", Source: "external",
-			})).To(Succeed())
-
-			req := createAuthenticatedRequest("POST", "/artwork/al/al-1/refresh", nil, adminToken)
-			w := httptest.NewRecorder()
-			router.ServeHTTP(w, req)
-
-			Expect(w.Code).To(Equal(http.StatusNoContent))
-
-			_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
-			Expect(err).To(MatchError(model.ErrNotFound))
-
-			queued, err := queueRepo.DequeueBatch(1000)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(queued).To(ContainElement(SatisfyAll(
-				HaveField("ItemKind", "al"),
-				HaveField("ItemID", "al-1"),
-				HaveField("Priority", model.ArtworkPriorityBump),
-			)))
-		})
-
-		It("returns 400 for an invalid kind", func() {
-			req := createAuthenticatedRequest("POST", "/artwork/xx/id-1/refresh", nil, adminToken)
-			w := httptest.NewRecorder()
-			router.ServeHTTP(w, req)
-
-			Expect(w.Code).To(Equal(http.StatusBadRequest))
-		})
-
-		It("denies access to regular users", func() {
-			req := createAuthenticatedRequest("POST", "/artwork/al/al-1/refresh", nil, userToken)
-			w := httptest.NewRecorder()
-			router.ServeHTTP(w, req)
-
-			Expect(w.Code).To(Equal(http.StatusForbidden))
-		})
-
-		It("denies access without authentication", func() {
-			req := createUnauthenticatedRequest("POST", "/artwork/al/al-1/refresh", nil)
-			w := httptest.NewRecorder()
-			router.ServeHTTP(w, req)
-
-			Expect(w.Code).To(Equal(http.StatusUnauthorized))
-		})
-	})
-})
diff --git a/server/nativeapi/config_test.go b/server/nativeapi/config_test.go
index 107b01e01..d1007f457 100644
--- a/server/nativeapi/config_test.go
+++ b/server/nativeapi/config_test.go
@@ -29,7 +29,7 @@ var _ = Describe("Config API", func() {
 		conf.Server.DevUIShowConfig = true // Enable config endpoint for tests
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
diff --git a/server/nativeapi/library_test.go b/server/nativeapi/library_test.go
index 9b7061845..13b33c238 100644
--- a/server/nativeapi/library_test.go
+++ b/server/nativeapi/library_test.go
@@ -31,7 +31,7 @@ var _ = Describe("Library API", func() {
 		conf.Server.EnableSharing = false
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
diff --git a/server/nativeapi/metadata.go b/server/nativeapi/metadata.go
new file mode 100644
index 000000000..913ab0471
--- /dev/null
+++ b/server/nativeapi/metadata.go
@@ -0,0 +1,56 @@
+package nativeapi
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"slices"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+func (api *Router) addMetadataRoute(r chi.Router) {
+	r.Post("/metadata/{kind}/{id}/refresh", api.refreshMetadata())
+}
+
+// refreshMetadata clears the artwork state deliberately, so a wrong pick cannot be served from
+// cache again; reads fall back to local resolution while the worker re-runs the chain at Bump.
+func (api *Router) refreshMetadata() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		ctx := r.Context()
+		kind, _ := model.ParseKind(chi.URLParam(r, "kind"))
+		id := chi.URLParam(r, "id")
+		if !slices.Contains(artwork.RefreshableKinds, kind) {
+			http.Error(w, "invalid artwork kind", http.StatusBadRequest)
+			return
+		}
+		if _, err := artwork.ItemName(ctx, api.ds, kind, id); err != nil {
+			if errors.Is(err, model.ErrNotFound) {
+				http.Error(w, http.StatusText(http.StatusNotFound), http.StatusNotFound)
+				return
+			}
+			log.Error(ctx, "Error looking up item to refresh", "kind", kind, "id", id, err)
+			http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
+			return
+		}
+		if err := artwork.Refresh(ctx, api.ds, kind, id); err != nil {
+			log.Error(ctx, "Error refreshing artwork", "kind", kind, "id", id, err)
+			http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
+			return
+		}
+		if external.HasInfo(kind) {
+			// Detached: the request context is cancelled the moment this handler returns 204.
+			bg := context.WithoutCancel(ctx)
+			go func() {
+				if err := api.provider.RefreshInfo(bg, kind, id); err != nil {
+					log.Error(bg, "Error refreshing external info", "kind", kind, "id", id, err)
+				}
+			}()
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}
+}
diff --git a/server/nativeapi/metadata_test.go b/server/nativeapi/metadata_test.go
new file mode 100644
index 000000000..ebc9aeb28
--- /dev/null
+++ b/server/nativeapi/metadata_test.go
@@ -0,0 +1,177 @@
+package nativeapi
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"sync"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type fakeProvider struct {
+	external.Provider
+	mu     sync.Mutex
+	called []string
+}
+
+func (f *fakeProvider) RefreshInfo(_ context.Context, kind model.Kind, id string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.called = append(f.called, kind.Prefix()+"/"+id)
+	return nil
+}
+
+func (f *fakeProvider) calls() []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return slices.Clone(f.called)
+}
+
+var _ = Describe("Metadata API", func() {
+	var ds *tests.MockDataStore
+	var artRepo *tests.MockArtworkRepo
+	var queueRepo *tests.MockArtworkQueueRepo
+	var albumRepo *tests.MockAlbumRepo
+	var provider *fakeProvider
+	var router http.Handler
+	var adminToken, userToken string
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.EnableSharing = false
+		artRepo = tests.CreateMockArtworkRepo()
+		queueRepo = tests.CreateMockArtworkQueueRepo()
+		albumRepo = tests.CreateMockAlbumRepo()
+		artistRepo := tests.CreateMockArtistRepo()
+		playlistRepo := tests.CreateMockPlaylistRepo()
+		Expect(albumRepo.Put(&model.Album{ID: "al-1", Name: "Kid A"})).To(Succeed())
+		Expect(artistRepo.Put(&model.Artist{ID: "ar-1", Name: "Radiohead"})).To(Succeed())
+		Expect(playlistRepo.Put(&model.Playlist{ID: "pl-1", Name: "My Playlist"})).To(Succeed())
+		ds = &tests.MockDataStore{
+			MockedArtwork:      artRepo,
+			MockedArtworkQueue: queueRepo,
+			MockedAlbum:        albumRepo,
+			MockedArtist:       artistRepo,
+			MockedPlaylist:     playlistRepo,
+		}
+		auth.Init(ds)
+		provider = &fakeProvider{}
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, provider)
+		router = server.JWTVerifier(nativeRouter)
+
+		adminUser := model.User{ID: "admin-1", UserName: "admin", IsAdmin: true, NewPassword: "adminpass"}
+		regularUser := model.User{ID: "user-1", UserName: "regular", IsAdmin: false, NewPassword: "userpass"}
+		Expect(ds.User(context.TODO()).Put(&adminUser)).To(Succeed())
+		Expect(ds.User(context.TODO()).Put(&regularUser)).To(Succeed())
+
+		var err error
+		adminToken, err = auth.CreateToken(&adminUser)
+		Expect(err).ToNot(HaveOccurred())
+		userToken, err = auth.CreateToken(&regularUser)
+		Expect(err).ToNot(HaveOccurred())
+	})
+
+	Describe("POST /api/metadata/{kind}/{id}/refresh", func() {
+		It("clears state and enqueues a Bump for admins", func() {
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "al-1", Hash: "oldhash", Source: "external",
+			})).To(Succeed())
+
+			req := createAuthenticatedRequest("POST", "/metadata/al/al-1/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusNoContent))
+
+			_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+			Expect(err).To(MatchError(model.ErrNotFound))
+
+			queued, err := queueRepo.DequeueBatch(1000)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(queued).To(ContainElement(SatisfyAll(
+				HaveField("ItemKind", "al"),
+				HaveField("ItemID", "al-1"),
+				HaveField("Priority", model.ArtworkPriorityBump),
+			)))
+		})
+
+		It("returns 400 for an invalid kind", func() {
+			req := createAuthenticatedRequest("POST", "/metadata/xx/id-1/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusBadRequest))
+		})
+
+		It("denies access to regular users", func() {
+			req := createAuthenticatedRequest("POST", "/metadata/al/al-1/refresh", nil, userToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusForbidden))
+		})
+
+		It("denies access without authentication", func() {
+			req := createUnauthenticatedRequest("POST", "/metadata/al/al-1/refresh", nil)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusUnauthorized))
+		})
+
+		It("triggers an external info refresh for albums", func() {
+			req := createAuthenticatedRequest("POST", "/metadata/al/al-1/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusNoContent))
+			Eventually(provider.calls).Should(ContainElement("al/al-1"))
+		})
+
+		It("triggers an external info refresh for artists", func() {
+			req := createAuthenticatedRequest("POST", "/metadata/ar/ar-1/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusNoContent))
+			Eventually(provider.calls).Should(ContainElement("ar/ar-1"))
+		})
+
+		It("skips the external info refresh for kinds without external info", func() {
+			req := createAuthenticatedRequest("POST", "/metadata/pl/pl-1/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusNoContent))
+			Consistently(provider.calls).ShouldNot(ContainElement("pl/pl-1"))
+		})
+
+		It("returns 404 for an unknown id", func() {
+			req := createAuthenticatedRequest("POST", "/metadata/al/nope/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns 500 when the lookup fails for a reason other than not-found", func() {
+			albumRepo.SetError(true)
+
+			req := createAuthenticatedRequest("POST", "/metadata/al/al-1/refresh", nil, adminToken)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			Expect(w.Code).To(Equal(http.StatusInternalServerError))
+		})
+	})
+})
diff --git a/server/nativeapi/native_api.go b/server/nativeapi/native_api.go
index f97bd26b2..57a712a20 100644
--- a/server/nativeapi/native_api.go
+++ b/server/nativeapi/native_api.go
@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/core/metrics"
 	playlistsvc "github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/log"
@@ -46,10 +47,11 @@ type Router struct {
 	maintenance   core.Maintenance
 	pluginManager PluginManager
 	imgUpload     artwork.Uploader
+	provider      external.Provider
 }
 
-func New(ds model.DataStore, share core.Share, playlists playlistsvc.Playlists, insights metrics.Insights, libraryService core.Library, userService core.User, maintenance core.Maintenance, pluginManager PluginManager, imgUpload artwork.Uploader) *Router {
-	r := &Router{ds: ds, share: share, playlists: playlists, insights: insights, libs: libraryService, users: userService, maintenance: maintenance, pluginManager: pluginManager, imgUpload: imgUpload}
+func New(ds model.DataStore, share core.Share, playlists playlistsvc.Playlists, insights metrics.Insights, libraryService core.Library, userService core.User, maintenance core.Maintenance, pluginManager PluginManager, imgUpload artwork.Uploader, provider external.Provider) *Router {
+	r := &Router{ds: ds, share: share, playlists: playlists, insights: insights, libs: libraryService, users: userService, maintenance: maintenance, pluginManager: pluginManager, imgUpload: imgUpload, provider: provider}
 	r.Handler = r.routes()
 	return r
 }
@@ -92,7 +94,7 @@ func (api *Router) routes() http.Handler {
 			api.addConfigRoute(r)
 			api.addUserLibraryRoute(r)
 			api.addPluginRoute(r)
-			api.addArtworkRoute(r)
+			api.addMetadataRoute(r)
 			api.RX(r, "/library", api.libs.NewRepository, true)
 		})
 	})
diff --git a/server/nativeapi/native_api_song_test.go b/server/nativeapi/native_api_song_test.go
index b1ed09d65..203fcd4cf 100644
--- a/server/nativeapi/native_api_song_test.go
+++ b/server/nativeapi/native_api_song_test.go
@@ -95,7 +95,7 @@ var _ = Describe("Song Endpoints", func() {
 		mfRepo.SetData(testSongs)
 
 		// Create the native API router and wrap it with the JWTVerifier middleware
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 		w = httptest.NewRecorder()
 	})
diff --git a/server/nativeapi/playlists_test.go b/server/nativeapi/playlists_test.go
index 74ef58cab..9abcc477f 100644
--- a/server/nativeapi/playlists_test.go
+++ b/server/nativeapi/playlists_test.go
@@ -99,7 +99,7 @@ var _ = Describe("Playlist Tracks Endpoint", func() {
 		err := userRepo.Put(&testUser)
 		Expect(err).ToNot(HaveOccurred())
 
-		nativeRouter := New(ds, nil, plsSvc, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil)
+		nativeRouter := New(ds, nil, plsSvc, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 		w = httptest.NewRecorder()
 	})
diff --git a/server/nativeapi/plugin_test.go b/server/nativeapi/plugin_test.go
index aa91a7951..1683885e7 100644
--- a/server/nativeapi/plugin_test.go
+++ b/server/nativeapi/plugin_test.go
@@ -34,7 +34,7 @@ var _ = Describe("Plugin API", func() {
 		ds = &tests.MockDataStore{}
 		mockManager = &tests.MockPluginManager{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, mockManager, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, mockManager, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
diff --git a/server/nativeapi/user_password_token_refresh_test.go b/server/nativeapi/user_password_token_refresh_test.go
index 32f4b13cb..2a363980f 100644
--- a/server/nativeapi/user_password_token_refresh_test.go
+++ b/server/nativeapi/user_password_token_refresh_test.go
@@ -45,7 +45,7 @@ var _ = Describe("PUT /user/{id}: token refresh on self password change", func()
 		auth.Init(ds)
 
 		userService := core.NewUser(ds, noopPluginUnloader{})
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), userService, nil, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), userService, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 	})
 
diff --git a/server/subsonic/e2e/e2e_suite_test.go b/server/subsonic/e2e/e2e_suite_test.go
index 8998731a4..58e877b0d 100644
--- a/server/subsonic/e2e/e2e_suite_test.go
+++ b/server/subsonic/e2e/e2e_suite_test.go
@@ -357,6 +357,10 @@ func (n noopProvider) TopSongs(context.Context, string, string, int) (model.Medi
 	return nil, nil
 }
 
+func (n noopProvider) RefreshInfo(context.Context, model.Kind, string) error {
+	return nil
+}
+
 // Compile-time interface checks
 var (
 	_ artwork.Artwork   = noopArtwork{}
diff --git a/tests/mock_album_repo.go b/tests/mock_album_repo.go
index ff6f9cff6..c63f7c425 100644
--- a/tests/mock_album_repo.go
+++ b/tests/mock_album_repo.go
@@ -65,6 +65,9 @@ func (m *MockAlbumRepo) Put(al *model.Album) error {
 	if al.ID == "" {
 		al.ID = id.NewRandom()
 	}
+	if m.Data == nil {
+		m.Data = make(map[string]*model.Album)
+	}
 	m.Data[al.ID] = al
 	return nil
 }
@@ -142,10 +145,7 @@ func (m *MockAlbumRepo) GetTouchedAlbums(libID int) (model.AlbumCursor, error) {
 }
 
 func (m *MockAlbumRepo) UpdateExternalInfo(album *model.Album) error {
-	if m.Err {
-		return errors.New("unexpected error")
-	}
-	return nil
+	return m.Put(album)
 }
 
 func (m *MockAlbumRepo) Search(q string, options ...model.QueryOptions) (model.Albums, error) {
diff --git a/tests/mock_artist_repo.go b/tests/mock_artist_repo.go
index 9691a6584..b71942208 100644
--- a/tests/mock_artist_repo.go
+++ b/tests/mock_artist_repo.go
@@ -58,6 +58,9 @@ func (m *MockArtistRepo) Put(ar *model.Artist, columsToUpdate ...string) error {
 	if ar.ID == "" {
 		ar.ID = id.NewRandom()
 	}
+	if m.Data == nil {
+		m.Data = make(map[string]*model.Artist)
+	}
 	m.Data[ar.ID] = ar
 	return nil
 }
@@ -137,10 +140,7 @@ func (m *MockArtistRepo) GetCursor(options ...model.QueryOptions) (model.ArtistC
 }
 
 func (m *MockArtistRepo) UpdateExternalInfo(artist *model.Artist) error {
-	if m.Err {
-		return errors.New("mock repo error")
-	}
-	return nil
+	return m.Put(artist)
 }
 
 func (m *MockArtistRepo) RefreshStats(allArtists bool) (int64, error) {
diff --git a/ui/src/artist/ArtistShow.jsx b/ui/src/artist/ArtistShow.jsx
index eef2989d5..515c1ab08 100644
--- a/ui/src/artist/ArtistShow.jsx
+++ b/ui/src/artist/ArtistShow.jsx
@@ -53,7 +53,7 @@ const useStyles = makeStyles(
   },
 )
 
-const ArtistDetails = (props) => {
+export const ArtistDetails = (props) => {
   const record = useRecordContext(props)
   const isDesktop = useMediaQuery((theme) => theme.breakpoints.up('sm'), {
     noSsr: true,
@@ -75,7 +75,9 @@ const ArtistDetails = (props) => {
         // eslint-disable-next-line no-console
         console.error('error on artist page', e)
       })
-  }, [record.id])
+    // Keyed on the record, not its id: a refreshed record must re-fetch, or the stale
+    // artistInfo state keeps winning the `||` above.
+  }, [record])
 
   const Component = isDesktop ? DesktopArtistDetails : MobileArtistDetails
   return (
diff --git a/ui/src/artist/ArtistShow.test.jsx b/ui/src/artist/ArtistShow.test.jsx
new file mode 100644
index 000000000..f51cde5ed
--- /dev/null
+++ b/ui/src/artist/ArtistShow.test.jsx
@@ -0,0 +1,63 @@
+import React from 'react'
+import { render, waitFor } from '@testing-library/react'
+import { RecordContextProvider } from 'react-admin'
+import { ThemeProvider, createTheme } from '@material-ui/core/styles'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { ArtistDetails } from './ArtistShow'
+import subsonic from '../subsonic'
+
+vi.mock('../subsonic', () => ({
+  default: { getArtistInfo: vi.fn(), getCoverArtUrl: vi.fn() },
+}))
+
+// Not under test here: isolate ArtistDetails from the leaf presentational views.
+vi.mock('./DesktopArtistDetails', () => ({ default: () => null }))
+vi.mock('./MobileArtistDetails', () => ({ default: () => null }))
+
+const mockGetArtistInfo = subsonic.getArtistInfo
+
+describe('ArtistDetails', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetArtistInfo.mockResolvedValue({
+      json: {
+        'subsonic-response': {
+          status: 'ok',
+          artistInfo: { biography: 'fetched' },
+        },
+      },
+    })
+  })
+
+  const theme = createTheme()
+
+  const wrap = (record) => (
+    <ThemeProvider theme={theme}>
+      <RecordContextProvider value={record}>
+        <ArtistDetails />
+      </RecordContextProvider>
+    </ThemeProvider>
+  )
+
+  const renderDetails = (record) => render(wrap(record))
+
+  it('re-fetches the artist info when the record object changes', async () => {
+    const record = { id: 'ar1', name: 'Artist', biography: 'old' }
+    const { rerender } = renderDetails(record)
+    await waitFor(() => expect(mockGetArtistInfo).toHaveBeenCalledTimes(1))
+
+    rerender(wrap({ ...record, biography: 'new' }))
+
+    await waitFor(() => expect(mockGetArtistInfo).toHaveBeenCalledTimes(2))
+  })
+
+  it('does not re-fetch when the same record object is passed again', async () => {
+    const record = { id: 'ar1', name: 'Artist', biography: 'old' }
+    const { rerender } = renderDetails(record)
+    await waitFor(() => expect(mockGetArtistInfo).toHaveBeenCalledTimes(1))
+
+    rerender(wrap(record))
+
+    expect(mockGetArtistInfo).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/ui/src/common/ContextMenus.jsx b/ui/src/common/ContextMenus.jsx
index 7ad8c735c..606506459 100644
--- a/ui/src/common/ContextMenus.jsx
+++ b/ui/src/common/ContextMenus.jsx
@@ -7,7 +7,12 @@ import MenuItem from '@material-ui/core/MenuItem'
 import MoreVertIcon from '@material-ui/icons/MoreVert'
 import { MdQuestionMark } from 'react-icons/md'
 import { makeStyles } from '@material-ui/core/styles'
-import { useDataProvider, useNotify, useTranslate } from 'react-admin'
+import {
+  useDataProvider,
+  useNotify,
+  usePermissions,
+  useTranslate,
+} from 'react-admin'
 import clsx from 'clsx'
 import {
   playNext,
@@ -69,6 +74,7 @@ const ContextMenu = ({
   const dispatch = useDispatch()
   const translate = useTranslate()
   const notify = useNotify()
+  const { permissions } = usePermissions()
   const [anchorEl, setAnchorEl] = useState(null)
 
   const isArtist = resource === 'artist'
@@ -129,6 +135,16 @@ const ContextMenu = ({
         )
       },
     },
+    refresh: {
+      enabled: permissions === 'admin',
+      needData: false,
+      label: translate('resources.album.actions.refresh'),
+      action: (record) =>
+        dataProvider
+          .refreshMetadata(resource, record.id)
+          .then(() => notify('message.metadataRefreshStarted'))
+          .catch(() => notify('ra.page.error', 'warning')),
+    },
     ...(!hideInfo && {
       info: {
         enabled: true,
diff --git a/ui/src/common/ContextMenus.test.jsx b/ui/src/common/ContextMenus.test.jsx
index 72a98b64b..59a7de966 100644
--- a/ui/src/common/ContextMenus.test.jsx
+++ b/ui/src/common/ContextMenus.test.jsx
@@ -17,12 +17,21 @@ const { mockConfig } = vi.hoisted(() => ({
 }))
 vi.mock('../config', () => ({ default: mockConfig }))
 
+const { mockPermissions, mockRefreshMetadata } = vi.hoisted(() => ({
+  mockPermissions: { value: 'admin' },
+  mockRefreshMetadata: vi.fn(),
+}))
+
 vi.mock('react-admin', async (importOriginal) => {
   const actual = await importOriginal()
   return {
     ...actual,
     useNotify: () => vi.fn(),
-    useDataProvider: () => ({ getList: vi.fn() }),
+    usePermissions: () => ({ permissions: mockPermissions.value }),
+    useDataProvider: () => ({
+      getList: vi.fn(),
+      refreshMetadata: mockRefreshMetadata,
+    }),
     useTranslate: () => (x) => x,
   }
 })
@@ -43,6 +52,7 @@ describe('ContextMenus', () => {
     vi.clearAllMocks()
     mockConfig.enableSharing = true
     mockConfig.enableDownloads = true
+    mockPermissions.value = 'admin'
   })
 
   describe('ArtistContextMenu', () => {
@@ -75,4 +85,49 @@ describe('ContextMenus', () => {
       expect(screen.getByText('ra.action.download (1 MB)')).toBeInTheDocument()
     })
   })
+
+  describe('refresh metadata', () => {
+    it('shows the item for admins on the album menu', () => {
+      renderMenu(AlbumContextMenu, { id: 'al1', name: 'Album', songCount: 1 })
+      expect(
+        screen.getByText('resources.album.actions.refresh'),
+      ).toBeInTheDocument()
+    })
+
+    // Menu order comes from key insertion order in the options object, so it is easy to
+    // change by accident when adding an entry.
+    it('places the item directly above Get Info', () => {
+      renderMenu(AlbumContextMenu, { id: 'al1', name: 'Album', songCount: 1 })
+      const labels = screen
+        .getAllByRole('menuitem')
+        .map((item) => item.textContent)
+      const refreshAt = labels.indexOf('resources.album.actions.refresh')
+      const infoAt = labels.indexOf('resources.album.actions.info')
+
+      expect(refreshAt).toBeGreaterThanOrEqual(0)
+      expect(infoAt).toEqual(refreshAt + 1)
+    })
+
+    it('shows the item for admins on the artist menu', () => {
+      renderMenu(ArtistContextMenu, { id: 'ar1', name: 'Artist', stats: {} })
+      expect(
+        screen.getByText('resources.album.actions.refresh'),
+      ).toBeInTheDocument()
+    })
+
+    it('hides the item for regular users', () => {
+      mockPermissions.value = 'regular'
+      renderMenu(AlbumContextMenu, { id: 'al1', name: 'Album', songCount: 1 })
+      expect(
+        screen.queryByText('resources.album.actions.refresh'),
+      ).not.toBeInTheDocument()
+    })
+
+    it('calls refreshMetadata with the resource and id', () => {
+      mockRefreshMetadata.mockResolvedValue({})
+      renderMenu(AlbumContextMenu, { id: 'al1', name: 'Album', songCount: 1 })
+      fireEvent.click(screen.getByText('resources.album.actions.refresh'))
+      expect(mockRefreshMetadata).toHaveBeenCalledWith('album', 'al1')
+    })
+  })
 })
diff --git a/ui/src/dataProvider/wrapperDataProvider.js b/ui/src/dataProvider/wrapperDataProvider.js
index f5004308b..e79beb787 100644
--- a/ui/src/dataProvider/wrapperDataProvider.js
+++ b/ui/src/dataProvider/wrapperDataProvider.js
@@ -4,6 +4,8 @@ import { REST_URL } from '../consts'
 
 const dataProvider = jsonServerProvider(REST_URL, httpClient)
 
+const REFRESH_KIND = { album: 'al', artist: 'ar' }
+
 const isAdmin = () => {
   const role = localStorage.getItem('role')
   return role === 'admin'
@@ -221,6 +223,12 @@ const wrapperDataProvider = {
       data: json,
     }))
   },
+  // The endpoint answers 204 with no body, but react-admin rejects any response without a
+  // `data` key, so the id stands in for one.
+  refreshMetadata: (resource, id) =>
+    httpClient(`${REST_URL}/metadata/${REFRESH_KIND[resource]}/${id}/refresh`, {
+      method: 'POST',
+    }).then(() => ({ data: { id } })),
 }
 
 export default wrapperDataProvider
diff --git a/ui/src/dataProvider/wrapperDataProvider.test.js b/ui/src/dataProvider/wrapperDataProvider.test.js
index fbc82f969..4225a5a54 100644
--- a/ui/src/dataProvider/wrapperDataProvider.test.js
+++ b/ui/src/dataProvider/wrapperDataProvider.test.js
@@ -87,4 +87,37 @@ describe('wrapperDataProvider', () => {
       )
     })
   })
+
+  describe('refreshMetadata', () => {
+    it('posts to the album metadata refresh endpoint', () => {
+      mockHttpClient.mockResolvedValue({ json: {} })
+      wrapperDataProvider.refreshMetadata('album', 'al-1')
+      expect(mockHttpClient).toHaveBeenCalledWith(
+        expect.stringContaining('/metadata/al/al-1/refresh'),
+        { method: 'POST' },
+      )
+    })
+
+    it('posts to the artist metadata refresh endpoint', () => {
+      mockHttpClient.mockResolvedValue({ json: {} })
+      wrapperDataProvider.refreshMetadata('artist', 'ar-1')
+      expect(mockHttpClient).toHaveBeenCalledWith(
+        expect.stringContaining('/metadata/ar/ar-1/refresh'),
+        { method: 'POST' },
+      )
+    })
+
+    // react-admin rejects a custom method whose response has no `data` key, and the
+    // endpoint answers 204 with no body.
+    it('resolves to a react-admin shaped response', async () => {
+      mockHttpClient.mockResolvedValue({
+        status: 204,
+        body: '',
+        json: undefined,
+      })
+      await expect(
+        wrapperDataProvider.refreshMetadata('album', 'al-1'),
+      ).resolves.toEqual({ data: { id: 'al-1' } })
+    })
+  })
 })
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index 12968afbd..8823a6749 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -93,7 +93,8 @@
         "shuffle": "Shuffle",
         "addToPlaylist": "Add to Playlist",
         "download": "Download",
-        "info": "Get Info"
+        "info": "Get Info",
+        "refresh": "Refresh Metadata"
       },
       "lists": {
         "all": "All",
@@ -569,6 +570,7 @@
     "coverRemoved": "Cover art removed",
     "coverUploadError": "Error uploading cover art",
     "coverRemoveError": "Error removing cover art",
+    "metadataRefreshStarted": "Refreshing metadata in the background",
     "note": "NOTE",
     "transcodingDisabled": "Changing the transcoding configuration through the web interface is disabled for security reasons. If you would like to change (edit or add) transcoding options, restart the server with the %{config} configuration option.",
     "transcodingEnabled": "Navidrome is currently running with %{config}, making it possible to run system commands from the transcoding settings using the web interface. We recommend to disable it for security reasons and only enable it when configuring Transcoding options.",

From a9962ebe5de7d1b077eb57852a096897eb3ae8e1 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 26 Aug 2026 10:53:07 -0400
Subject: [PATCH 077/200] refactor(artwork): use the shared httpclient for
 image downloads

Same behavior: httpclient.New sets the Navidrome User-Agent via its
transport, so the manual header is no longer needed.
---
 core/artwork/sources.go | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/core/artwork/sources.go b/core/artwork/sources.go
index 78b7dd68d..069b7bf5a 100644
--- a/core/artwork/sources.go
+++ b/core/artwork/sources.go
@@ -16,10 +16,10 @@ import (
 	"strings"
 	"time"
 
-	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/ffmpeg"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	"go.senan.xyz/taglib"
 )
 
@@ -163,9 +163,8 @@ type readCloser struct {
 }
 
 func fromURL(ctx context.Context, imageUrl *url.URL) (io.ReadCloser, string, error) {
-	hc := http.Client{Timeout: 5 * time.Second}
+	hc := httpclient.New(5 * time.Second)
 	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, imageUrl.String(), nil)
-	req.Header.Set("User-Agent", consts.HTTPUserAgent)
 	resp, err := hc.Do(req) //nolint:gosec
 	if err != nil {
 		return nil, "", err

From 23e4c8f580365e642d1e0f24c30484057423f4a1 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 26 Aug 2026 10:57:01 -0400
Subject: [PATCH 078/200] refactor(plugins): build the host HTTP client with
 httpclient.New

CheckRedirect is set on the returned client, so the plugin service no
longer hand-builds an http.Client just to attach the shared transport.
---
 plugins/host_httpclient.go | 33 +++++++++++++++------------------
 1 file changed, 15 insertions(+), 18 deletions(-)

diff --git a/plugins/host_httpclient.go b/plugins/host_httpclient.go
index 4c8f85acd..d52898bdd 100644
--- a/plugins/host_httpclient.go
+++ b/plugins/host_httpclient.go
@@ -46,24 +46,21 @@ func newHTTPService(pluginName string, permission *HTTPPermission) *httpServiceI
 		pluginName:    pluginName,
 		requiredHosts: requiredHosts,
 	}
-	svc.client = &http.Client{
-		Transport: httpclient.NewTransport(nil),
-		// Timeout is set per-request via context deadline, not here.
-		// CheckRedirect validates hosts and enforces redirect limits.
-		CheckRedirect: func(req *http.Request, via []*http.Request) error {
-			if req.Context().Value(noFollowRedirectsKey) != nil {
-				return http.ErrUseLastResponse
-			}
-			if len(via) >= httpClientMaxRedirects {
-				log.Warn(req.Context(), "HTTP redirect limit exceeded", "plugin", svc.pluginName, "url", req.URL.String(), "redirectCount", len(via))
-				return http.ErrUseLastResponse
-			}
-			if err := svc.validateHost(req.Context(), req.URL.Host); err != nil {
-				log.Warn(req.Context(), "HTTP redirect blocked", "plugin", svc.pluginName, "url", req.URL.String(), "err", err)
-				return err
-			}
-			return nil
-		},
+	// No client timeout: it is set per-request via context deadline.
+	svc.client = httpclient.New(0)
+	svc.client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+		if req.Context().Value(noFollowRedirectsKey) != nil {
+			return http.ErrUseLastResponse
+		}
+		if len(via) >= httpClientMaxRedirects {
+			log.Warn(req.Context(), "HTTP redirect limit exceeded", "plugin", svc.pluginName, "url", req.URL.String(), "redirectCount", len(via))
+			return http.ErrUseLastResponse
+		}
+		if err := svc.validateHost(req.Context(), req.URL.Host); err != nil {
+			log.Warn(req.Context(), "HTTP redirect blocked", "plugin", svc.pluginName, "url", req.URL.String(), "err", err)
+			return err
+		}
+		return nil
 	}
 	return svc
 }

From b0e1943d8ba8ba8f7abd92d0666e332c096a9b3c Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 26 Aug 2026 18:03:59 -0400
Subject: [PATCH 079/200] fix(ui): always show the Last.fm link on the artist
 details page

The button only rendered when an agent supplied a real last.fm URL, either
embedded in the biography or as artistInfo.lastFmUrl. Neither source is
reliable anymore: cleanContent strips the "Read more on Last.fm" anchor out of
the biography, and the Last.fm agent does not register at all unless
LastFM.ApiKey and LastFM.Secret are set, in which case GetArtistURL falls
through to ListenBrainz, which returns the artist's official homepage. The
isLastFmURL guard then correctly rejects it and the button disappears.

Build the URL from the artist name when no canonical one is available, the same
way AlbumExternalLinks already does for albums. A real last.fm URL is still
preferred when one is present, and the button stays hidden when Last.fm is
disabled or the artist has no name.
---
 ui/src/artist/ArtistExternalLink.jsx      | 16 +++---
 ui/src/artist/ArtistExternalLink.test.jsx | 60 +++++++++++++++++++++++
 2 files changed, 68 insertions(+), 8 deletions(-)
 create mode 100644 ui/src/artist/ArtistExternalLink.test.jsx

diff --git a/ui/src/artist/ArtistExternalLink.jsx b/ui/src/artist/ArtistExternalLink.jsx
index a83972f17..6595d1fbc 100644
--- a/ui/src/artist/ArtistExternalLink.jsx
+++ b/ui/src/artist/ArtistExternalLink.jsx
@@ -38,15 +38,15 @@ const ArtistExternalLinks = ({ artistInfo, record }) => {
   }
 
   if (config.lastFMEnabled) {
-    if (lastFMlink && isLastFmURL(lastFMlink[2])) {
+    // No agent may be enabled to supply a canonical URL, so fall back to a name-based one.
+    const lastFMUrl =
+      (lastFMlink && isLastFmURL(lastFMlink[2]) && lastFMlink[2]) ||
+      (isLastFmURL(artistInfo?.lastFmUrl) && artistInfo.lastFmUrl) ||
+      (record.name &&
+        `https://last.fm/music/${encodeURIComponent(record.name)}`)
+    if (lastFMUrl) {
       addLink(
-        lastFMlink[2],
-        'message.openIn.lastfm',
-        <ImLastfm2 className="lastfm-icon" />,
-      )
-    } else if (isLastFmURL(artistInfo?.lastFmUrl)) {
-      addLink(
-        artistInfo?.lastFmUrl,
+        lastFMUrl,
         'message.openIn.lastfm',
         <ImLastfm2 className="lastfm-icon" />,
       )
diff --git a/ui/src/artist/ArtistExternalLink.test.jsx b/ui/src/artist/ArtistExternalLink.test.jsx
new file mode 100644
index 000000000..4214c21ea
--- /dev/null
+++ b/ui/src/artist/ArtistExternalLink.test.jsx
@@ -0,0 +1,60 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { TestContext } from 'ra-test'
+import ArtistExternalLinks from './ArtistExternalLink'
+
+const { mockConfig } = vi.hoisted(() => ({
+  mockConfig: { lastFMEnabled: true },
+}))
+vi.mock('../config', () => ({ default: mockConfig }))
+
+describe('ArtistExternalLinks', () => {
+  beforeEach(() => {
+    mockConfig.lastFMEnabled = true
+  })
+
+  const renderLinks = (artistInfo, record = { id: 'ar-1', name: 'Björk' }) =>
+    render(
+      <TestContext>
+        <ArtistExternalLinks artistInfo={artistInfo} record={record} />
+      </TestContext>,
+    )
+
+  const lastFmHref = () =>
+    screen.getByLabelText('message.openIn.lastfm').closest('a').href
+
+  it('uses the URL returned by the server', () => {
+    renderLinks({ lastFmUrl: 'https://www.last.fm/music/Bjork' })
+    expect(lastFmHref()).toBe('https://www.last.fm/music/Bjork')
+  })
+
+  it('uses the URL found in the biography', () => {
+    renderLinks({
+      biography: 'Read more on <a href="https://www.last.fm/music/Bjork">',
+      lastFmUrl: 'https://bjork.com',
+    })
+    expect(lastFmHref()).toBe('https://www.last.fm/music/Bjork')
+  })
+
+  it('builds the URL from the artist name when the server has none', () => {
+    renderLinks({ lastFmUrl: 'https://bjork.com' })
+    expect(lastFmHref()).toBe('https://last.fm/music/Bj%C3%B6rk')
+  })
+
+  it('builds the URL when there is no artist info at all', () => {
+    renderLinks(undefined)
+    expect(lastFmHref()).toBe('https://last.fm/music/Bj%C3%B6rk')
+  })
+
+  it('shows no Last.fm link when Last.fm is disabled', () => {
+    mockConfig.lastFMEnabled = false
+    renderLinks({ lastFmUrl: 'https://www.last.fm/music/Bjork' })
+    expect(screen.queryByLabelText('message.openIn.lastfm')).toBeNull()
+  })
+
+  it('shows no Last.fm link when the artist has no name', () => {
+    renderLinks({}, { id: 'ar-1', name: '' })
+    expect(screen.queryByLabelText('message.openIn.lastfm')).toBeNull()
+  })
+})

From b5f530e90cc57c798e3b8277f96dbcda557a4df3 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Thu, 27 Aug 2026 20:19:16 -0400
Subject: [PATCH 080/200] chore(deps): update Go dependencies to latest
 versions

Signed-off-by: Deluan <deluan@navidrome.org>
---
 go.mod | 12 ++++++------
 go.sum | 24 ++++++++++++------------
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/go.mod b/go.mod
index c0809f7b5..624cf9a01 100644
--- a/go.mod
+++ b/go.mod
@@ -23,7 +23,7 @@ require (
 	github.com/extism/go-sdk v1.7.1
 	github.com/fatih/structs v1.1.0
 	github.com/gen2brain/webp v0.6.4
-	github.com/go-chi/chi/v5 v5.3.1
+	github.com/go-chi/chi/v5 v5.3.2
 	github.com/go-chi/cors v1.2.2
 	github.com/go-chi/httprate v0.16.0
 	github.com/go-chi/jwtauth/v5 v5.4.0
@@ -43,7 +43,7 @@ require (
 	github.com/microcosm-cc/bluemonday v1.0.27
 	github.com/mileusna/useragent v1.3.5
 	github.com/onsi/ginkgo/v2 v2.32.1
-	github.com/onsi/gomega v1.42.1
+	github.com/onsi/gomega v1.43.0
 	github.com/pelletier/go-toml/v2 v2.4.3
 	github.com/pmezard/go-difflib v1.0.0
 	github.com/pocketbase/dbx v1.12.0
@@ -53,10 +53,10 @@ require (
 	github.com/robfig/cron/v3 v3.0.1
 	github.com/sabhiram/go-gitignore v0.0.0-20210923224102-525f6e181f06
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.3
-	github.com/sirupsen/logrus v1.10.0
+	github.com/sirupsen/logrus v1.10.2
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
-	github.com/stretchr/testify v1.12.0
+	github.com/stretchr/testify v1.12.1
 	github.com/tetratelabs/wazero v1.12.0
 	github.com/unrolled/secure v1.17.0
 	github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342
@@ -92,7 +92,7 @@ require (
 	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
-	github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 // indirect
+	github.com/google/pprof v0.0.0-20260825171938-4d453200e7d9 // indirect
 	github.com/google/subcommands v1.2.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
@@ -104,7 +104,7 @@ require (
 	github.com/lann/builder v0.0.0-20180802200727-47ae307949d0 // indirect
 	github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0 // indirect
 	github.com/lestrrat-go/blackmagic v1.0.4 // indirect
-	github.com/lestrrat-go/dsig v1.3.0 // indirect
+	github.com/lestrrat-go/dsig v1.4.0 // indirect
 	github.com/lestrrat-go/dsig-secp256k1 v1.0.0 // indirect
 	github.com/lestrrat-go/httpcc v1.0.1 // indirect
 	github.com/lestrrat-go/httprc/v3 v3.0.6 // indirect
diff --git a/go.sum b/go.sum
index 8be5a910c..0fcd0a4c7 100644
--- a/go.sum
+++ b/go.sum
@@ -69,8 +69,8 @@ github.com/gkampitakis/go-diff v1.3.2 h1:Qyn0J9XJSDTgnsgHRdz9Zp24RaJeKMUHg2+PDZZ
 github.com/gkampitakis/go-diff v1.3.2/go.mod h1:LLgOrpqleQe26cte8s36HTWcTmMEur6OPYerdAAS9tk=
 github.com/gkampitakis/go-snaps v0.5.15 h1:amyJrvM1D33cPHwVrjo9jQxX8g/7E2wYdZ+01KS3zGE=
 github.com/gkampitakis/go-snaps v0.5.15/go.mod h1:HNpx/9GoKisdhw9AFOBT1N7DBs9DiHo/hGheFGBZ+mc=
-github.com/go-chi/chi/v5 v5.3.1 h1:3j4HZLGZQ3JpMCrPJF/Jl3mYJfWLKBfNJ6quurUGCf8=
-github.com/go-chi/chi/v5 v5.3.1/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
+github.com/go-chi/chi/v5 v5.3.2 h1:5YQkICvTCSZ25hoRsyJazN0scjzKGiu4VAUc7H1o1nY=
+github.com/go-chi/chi/v5 v5.3.2/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
 github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE=
 github.com/go-chi/cors v1.2.2/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
 github.com/go-chi/httprate v0.16.0 h1:8V5DH9j6pSK6UQoBsTpvMyFxycqaKEIToyPKzHJjUa8=
@@ -101,8 +101,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc h1:hd+uUVsB1vdxohPneMrhGH2YfQuH5hRIK9u4/XCeUtw=
 github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc/go.mod h1:SL66SJVysrh7YbDCP9tH30b8a9o/N2HeiQNUm85EKhc=
-github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
-github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
+github.com/google/pprof v0.0.0-20260825171938-4d453200e7d9 h1:dl4UZiszMU+NKHirOiCKTC+hRuNAQ0moHPxSg6WcU1o=
+github.com/google/pprof v0.0.0-20260825171938-4d453200e7d9/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
 github.com/google/subcommands v1.2.0 h1:vWQspBTo2nEqTUFita5/KeEWlUL8kQObDFbub/EN9oE=
 github.com/google/subcommands v1.2.0/go.mod h1:ZjhPrFU+Olkh9WazFPsl27BQ4UPiG37m3yTrtFlrHVk=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -151,8 +151,8 @@ github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0 h1:P6pPBnrTSX3DEVR4fDembhR
 github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0/go.mod h1:vmVJ0l/dxyfGW6FmdpVm2joNMFikkuWg0EoCKLGUMNw=
 github.com/lestrrat-go/blackmagic v1.0.4 h1:IwQibdnf8l2KoO+qC3uT4OaTWsW7tuRQXy9TRN9QanA=
 github.com/lestrrat-go/blackmagic v1.0.4/go.mod h1:6AWFyKNNj0zEXQYfTMPfZrAXUWUfTIZ5ECEUEJaijtw=
-github.com/lestrrat-go/dsig v1.3.0 h1:phjMOCXvYzhuIgn7Voe2rex8z166vGfxRxmqM25P9/Q=
-github.com/lestrrat-go/dsig v1.3.0/go.mod h1:RD2eOaidyPvpc7IJQoO3Qq52RWdy8ZcJs8lrOnoa1Kc=
+github.com/lestrrat-go/dsig v1.4.0 h1:g7LUjK8cT74A5DzBXJI5HzsJuLhoYN0Wzj4nuOMIrH8=
+github.com/lestrrat-go/dsig v1.4.0/go.mod h1:I8Nddg/vN2cUl/h8N7SRRApLnNNeyZPIqLYpvpOtGGo=
 github.com/lestrrat-go/dsig-secp256k1 v1.0.0 h1:JpDe4Aybfl0soBvoVwjqDbp+9S1Y2OM7gcrVVMFPOzY=
 github.com/lestrrat-go/dsig-secp256k1 v1.0.0/go.mod h1:CxUgAhssb8FToqbL8NjSPoGQlnO4w3LG1P0qPWQm/NU=
 github.com/lestrrat-go/httpcc v1.0.1 h1:ydWCStUeJLkpYyjLDHihupbn2tYmZ7m22BGkcvZZrIE=
@@ -187,8 +187,8 @@ github.com/ogier/pflag v0.0.1 h1:RW6JSWSu/RkSatfcLtogGfFgpim5p7ARQ10ECk5O750=
 github.com/ogier/pflag v0.0.1/go.mod h1:zkFki7tvTa0tafRvTBIZTvzYyAu6kQhPZFnshFFPE+g=
 github.com/onsi/ginkgo/v2 v2.32.1 h1:6tlvcDm/3sE8lGJbZ4+d4mO3RLy24/tQWOFzVSQNIfw=
 github.com/onsi/ginkgo/v2 v2.32.1/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
-github.com/onsi/gomega v1.42.1 h1:iN1rCUX+44NZ1Dc97MPoeFYbFR0vh8zxoxMFwKdyZ6I=
-github.com/onsi/gomega v1.42.1/go.mod h1:REff/hsDsodHoKlWsP2mAPhu1+5/6hVYNf9rIEBpeSg=
+github.com/onsi/gomega v1.43.0 h1:VlG/1FxqNxhSO+lq/OHBNaaqwiBK/mO8JbVkX9Y+FeU=
+github.com/onsi/gomega v1.43.0/go.mod h1:REff/hsDsodHoKlWsP2mAPhu1+5/6hVYNf9rIEBpeSg=
 github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
 github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
@@ -232,8 +232,8 @@ github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr
 github.com/sethvargo/go-retry v0.4.0 h1:9qy1OoIAxBL+gBYnkTnTnWle5wlfsXQlwRzIbbpdqPw=
 github.com/sethvargo/go-retry v0.4.0/go.mod h1:tvsjdKG6xfiCx4LSiUZ06kcv38xvdVQwv8R6/VnnVWg=
 github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=
-github.com/sirupsen/logrus v1.10.0 h1:T8MxJJXVZkfcC5zSRMRAg2F8+lxjmUCGGWPzFxO+Msc=
-github.com/sirupsen/logrus v1.10.0/go.mod h1:FXZFonkDAnFozmO+5hGAFvB0Yg9/j2SIhA/QuIkP180=
+github.com/sirupsen/logrus v1.10.2 h1:G2SED73/qrAu6YwbdxOD6peLkCBI3z7L+ykJFTXJBBo=
+github.com/sirupsen/logrus v1.10.2/go.mod h1:SLEg8TqYulVKKfIGHldVp2K2aYz2DKSVBq4g/H5bR7Q=
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d h1:zE9ykElWQ6/NYmHa3jpm/yHnI4xSofP+UP6SpjHcSeM=
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
 github.com/smartystreets/goconvey v1.6.4 h1:fv0U8FUIMPNf1L9lnHLvLhgicrIVChEkdzIKYqbNC9s=
@@ -266,8 +266,8 @@ github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/stretchr/testify v1.12.0 h1:K6Mr6jO9JICuend/5xzTM03ydSV3vdNRYAdPSukj8uI=
-github.com/stretchr/testify v1.12.0/go.mod h1:bOYBZb5qJ00vPzWfIqBUZPaxK8jWiXc6d3ErP4Ca9Gw=
+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
 github.com/tetratelabs/wabin v0.0.0-20230304001439-f6f874872834 h1:ZF+QBjOI+tILZjBaFj3HgFonKXUcwgJ4djLb6i42S3Q=

From 4b60b21316f9e8467479c1f389e2a12a112bcbf1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 29 Aug 2026 16:36:08 -0400
Subject: [PATCH 081/200] fix(scanner): read file birth time via statx on Linux
 (#6046)

* fix(scanner): read file birth time via statx on Linux

On Linux the file birth time is only reachable through statx(2). We were
reading it with times.Get(), which looks only at the plain stat() result,
where the field does not exist: djherbis/times declares HasBirthTime=false
for Linux, so the check was always false and every file fell back to
time.Now(). This has been the case since #2553 introduced the feature, which
means that PR was a no-op on Linux from day one. macOS and Windows were
never affected, as there the birth time does come back from plain stat.

BirthTime() now tries times.Get() first, which costs no syscall and is
already correct on macOS, Windows and BSD, and only falls back to
times.Stat() on the path when that comes back empty. Ordering matters: on
Windows times.Stat() opens the file asking for FILE_WRITE_ATTRIBUTES, which
fails on a read-only share before falling back.

Not every filesystem stores a birth time. Measured with a probe over real
mounts: ext4, SMB/CIFS and mergerfs report one, while NFS and rclone/FUSE
never do. Asking those on every file is pure overhead, so a miss is
remembered per device on the localFS and skipped from then on. The memo is
keyed by device rather than by library, so a library spanning two mounts
does not lose birth times on the mount that does support them.

Cost of the extra call is ~2us per file against ~52us just to open a file
for tag reading, so 0.23s across a 97k-file library, and only for files
whose tags are actually read.

Existing rows keep their current birth_time: the repository drops that
column on update, so only newly added files get the real value.

* fix(scanner): return the device id opaquely to satisfy unconvert

st.Dev is uint64 on Linux and int32 on darwin, so a uint64() cast is
redundant on one and required on the other. Returning it as an opaque value
drops the cast entirely, which also removes the gosec suppression that came
with it. The value is only ever used as a sync.Map key.
---
 core/storage/local/deviceid_unix.go    | 18 ++++++++++++
 core/storage/local/deviceid_windows.go |  8 ++++++
 core/storage/local/local.go            | 40 +++++++++++++++++++++++++-
 core/storage/local/local_test.go       | 33 +++++++++++++++++++++
 4 files changed, 98 insertions(+), 1 deletion(-)
 create mode 100644 core/storage/local/deviceid_unix.go
 create mode 100644 core/storage/local/deviceid_windows.go

diff --git a/core/storage/local/deviceid_unix.go b/core/storage/local/deviceid_unix.go
new file mode 100644
index 000000000..42e7dac70
--- /dev/null
+++ b/core/storage/local/deviceid_unix.go
@@ -0,0 +1,18 @@
+//go:build !windows
+
+package local
+
+import (
+	"io/fs"
+	"syscall"
+)
+
+// deviceID identifies the filesystem a file lives on, used to key birth time support per mount.
+// It is returned opaquely because its width varies by platform, and it is only used as a map key.
+func deviceID(fi fs.FileInfo) (any, bool) {
+	st, ok := fi.Sys().(*syscall.Stat_t)
+	if !ok {
+		return nil, false
+	}
+	return st.Dev, true
+}
diff --git a/core/storage/local/deviceid_windows.go b/core/storage/local/deviceid_windows.go
new file mode 100644
index 000000000..f1b44be4d
--- /dev/null
+++ b/core/storage/local/deviceid_windows.go
@@ -0,0 +1,8 @@
+//go:build windows
+
+package local
+
+import "io/fs"
+
+// deviceID has no Windows equivalent, and none is needed: birth time comes straight from FileInfo.
+func deviceID(fs.FileInfo) (any, bool) { return nil, false }
diff --git a/core/storage/local/local.go b/core/storage/local/local.go
index 32aff0955..686838565 100644
--- a/core/storage/local/local.go
+++ b/core/storage/local/local.go
@@ -6,6 +6,7 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
+	"sync"
 	"sync/atomic"
 	"time"
 
@@ -61,6 +62,8 @@ type localFS struct {
 	fs.FS
 	extractor Extractor
 	root      string
+	// devices whose statx never reports a birth time (NFS, rclone/FUSE), so we ask each only once
+	noBirthTime sync.Map
 }
 
 // ResolveSymlink implements storage.SymlinkResolverFS. It resolves the whole chain at the
@@ -84,7 +87,11 @@ func (lfs *localFS) ReadTags(path ...string) (map[string]metadata.Info, error) {
 			if err != nil {
 				return nil, err
 			}
-			v.FileInfo = localFileInfo{info}
+			v.FileInfo = localFileInfo{
+				FileInfo:    info,
+				path:        filepath.Join(lfs.root, filepath.FromSlash(path)),
+				noBirthTime: &lfs.noBirthTime,
+			}
 			res[path] = v
 		}
 	}
@@ -95,15 +102,46 @@ func (lfs *localFS) ReadTags(path ...string) (map[string]metadata.Info, error) {
 // with metadata.FileInfo
 type localFileInfo struct {
 	fs.FileInfo
+	path        string
+	noBirthTime *sync.Map
 }
 
 func (lfi localFileInfo) BirthTime() time.Time {
 	if ts := times.Get(lfi.FileInfo); ts.HasBirthTime() {
 		return ts.BirthTime()
 	}
+	if bt, ok := lfi.statxBirthTime(); ok {
+		return bt
+	}
 	return time.Now()
 }
 
+// statxBirthTime reads the birth time from the path, which on Linux is the only way to get it.
+// Filesystems that never report one are remembered per device, so a scan asks each only once.
+func (lfi localFileInfo) statxBirthTime() (time.Time, bool) {
+	if lfi.path == "" {
+		return time.Time{}, false
+	}
+	dev, hasDev := deviceID(lfi.FileInfo)
+	memo := lfi.noBirthTime
+	if hasDev && memo != nil {
+		if _, skip := memo.Load(dev); skip {
+			return time.Time{}, false
+		}
+	}
+	ts, err := times.Stat(lfi.path)
+	if err != nil {
+		return time.Time{}, false
+	}
+	if ts.HasBirthTime() {
+		return ts.BirthTime(), true
+	}
+	if hasDev && memo != nil {
+		memo.Store(dev, struct{}{})
+	}
+	return time.Time{}, false
+}
+
 func init() {
 	storage.Register(storage.LocalSchemaID, newLocalStorage)
 }
diff --git a/core/storage/local/local_test.go b/core/storage/local/local_test.go
index 90bdd4b5b..3ed6d6fd9 100644
--- a/core/storage/local/local_test.go
+++ b/core/storage/local/local_test.go
@@ -6,8 +6,10 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"sync"
 	"time"
 
+	"github.com/djherbis/times"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
@@ -440,6 +442,37 @@ var _ = Describe("LocalStorage", func() {
 				// Should be around the current time (within last few minutes)
 				Expect(birthTime).To(BeTemporally("~", time.Now(), 5*time.Minute))
 			})
+
+			It("reads the birth time from the path, not the time of the call", func() {
+				// On Linux, birth time is only available via statx(2) on the path.
+				lfi := localFileInfo{FileInfo: fileInfo, path: testFile}
+				time.Sleep(300 * time.Millisecond)
+				Expect(lfi.BirthTime()).To(BeTemporally("<", time.Now().Add(-200*time.Millisecond)))
+			})
+
+			It("does not remember filesystems that do report a birth time", func() {
+				memo := &sync.Map{}
+				lfi := localFileInfo{FileInfo: fileInfo, path: testFile, noBirthTime: memo}
+				lfi.BirthTime()
+
+				count := 0
+				memo.Range(func(_, _ any) bool { count++; return true })
+				Expect(count).To(BeZero())
+			})
+
+			It("skips statx on filesystems already known to have none", func() {
+				if times.Get(fileInfo).HasBirthTime() {
+					Skip("this platform reports birth time from FileInfo, so statx is never called")
+				}
+				dev, ok := deviceID(fileInfo)
+				Expect(ok).To(BeTrue())
+
+				memo := &sync.Map{}
+				memo.Store(dev, struct{}{})
+				lfi := localFileInfo{FileInfo: fileInfo, path: testFile, noBirthTime: memo}
+				time.Sleep(300 * time.Millisecond)
+				Expect(lfi.BirthTime()).To(BeTemporally("~", time.Now(), 100*time.Millisecond))
+			})
 		})
 
 		It("should delegate all other FileInfo methods", func() {

From d7ca00d0189210f5f00c110d7a35b74a98b5a71a Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sat, 29 Aug 2026 17:07:17 -0400
Subject: [PATCH 082/200] chore(deps): update fscache fork to the CancelWithErr
 simplification

stream v1.5.0 added CancelWithErr, which delivers a cancellation cause to
blocked reads, future reads, and NextReader. The fscache fork now delegates
CloseWithError to it, dropping its own cause recording and reader wrappers.
Behavior is unchanged on the Navidrome side.
---
 go.mod | 4 ++--
 go.sum | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/go.mod b/go.mod
index 624cf9a01..93e84b052 100644
--- a/go.mod
+++ b/go.mod
@@ -6,7 +6,7 @@ go 1.26
 replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3
 
 // Fork to implement CloseWithError, proposed upstream in https://github.com/djherbis/fscache/pull/22
-replace github.com/djherbis/fscache => github.com/deluan/fscache v0.9.1-0.20260825221051-a07d597526e2
+replace github.com/djherbis/fscache => github.com/deluan/fscache v0.9.1-0.20260829205053-654a9d517048
 
 require (
 	github.com/Masterminds/squirrel v1.5.4
@@ -17,7 +17,7 @@ require (
 	github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36
 	github.com/djherbis/atime v1.1.0
 	github.com/djherbis/fscache v0.10.2-0.20231127215153-442a07e326c4
-	github.com/djherbis/stream v1.4.0
+	github.com/djherbis/stream v1.5.0
 	github.com/djherbis/times v1.6.0
 	github.com/dustin/go-humanize v1.0.1
 	github.com/extism/go-sdk v1.7.1
diff --git a/go.sum b/go.sum
index 0fcd0a4c7..c75b72dd0 100644
--- a/go.sum
+++ b/go.sum
@@ -29,8 +29,8 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
-github.com/deluan/fscache v0.9.1-0.20260825221051-a07d597526e2 h1:s254V2hsrrCJXYtAn9WPG/5p4QHenfL9E+j6Tiq5MW4=
-github.com/deluan/fscache v0.9.1-0.20260825221051-a07d597526e2/go.mod h1:eNFa48vJrse+8ysT4IJnnUeXwLZNcR0JQumU/W/QoUI=
+github.com/deluan/fscache v0.9.1-0.20260829205053-654a9d517048 h1:u3oDvM7pOIouwDGeIoMu9SYgSzVMtiSkOc+xywtKiJk=
+github.com/deluan/fscache v0.9.1-0.20260829205053-654a9d517048/go.mod h1:Bbk9SqpJcg/saiPfG6byM1G4G/LQndknrsLVOQ+VJqY=
 github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3 h1:j7eSXqgtjhlNfwnMEzRdXnJGZTEw4I7J9TeQAll83bU=
 github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcHCKTtwzrd0HGfEmoODFA/qnk4=
@@ -41,8 +41,8 @@ github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36 h1:KtPfdSST6e0vJbM
 github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36/go.mod h1:RkQWLNITKkXHLP7LXxZSgEq+uFWU25M5qW7qfEhL9Wc=
 github.com/djherbis/atime v1.1.0 h1:rgwVbP/5by8BvvjBNrbh64Qz33idKT3pSnMSJsxhi0g=
 github.com/djherbis/atime v1.1.0/go.mod h1:28OF6Y8s3NQWwacXc5eZTsEsiMzp7LF8MbXE+XJPdBE=
-github.com/djherbis/stream v1.4.0 h1:aVD46WZUiq5kJk55yxJAyw6Kuera6kmC3i2vEQyW/AE=
-github.com/djherbis/stream v1.4.0/go.mod h1:cqjC1ZRq3FFwkGmUtHwcldbnW8f0Q4YuVsGW1eAFtOk=
+github.com/djherbis/stream v1.5.0 h1:+ewqpS/ndTmEiJRH142JyOpmmjnkTxdbJtqoAG5sg0Y=
+github.com/djherbis/stream v1.5.0/go.mod h1:cqjC1ZRq3FFwkGmUtHwcldbnW8f0Q4YuVsGW1eAFtOk=
 github.com/djherbis/times v1.6.0 h1:w2ctJ92J8fBvWPxugmXIv7Nz7Q3iDMKNx9v5ocVH20c=
 github.com/djherbis/times v1.6.0/go.mod h1:gOHeRAz2h+VJNZ5Gmc/o7iD9k4wW7NMVqieYCY99oc0=
 github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=

From 59448e928351f5afd08ee3ce86fa46b081128c0f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 29 Aug 2026 17:28:29 -0400
Subject: [PATCH 083/200] fix(scrobbler): back off when a provider asks us to,
 instead of retrying per play (#6028)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(agents): retry-later error type with optional server delay

Add agents.ErrRetryLater and agents.RetryLaterError, which carries the
delay requested by an external service (e.g. ListenBrainz's
X-RateLimit-Reset-In). scrobbler.ErrRetryLater becomes an alias of the new
sentinel, so existing errors.Is checks and the plugin error-string protocol
keep working unchanged. Groundwork for honoring server-requested retry
delays across scrobbling, metadata agents and artwork.

Song.Equals tests moved to song_test.go to enable external test package.

* fix(scrobbler): honor backoff window and server-requested retry delay

ListenBrainz 429s were decoded into a typed error that classified as
unrecoverable, silently discarding the scrobble (a JSON-bodied 429 was
measured live). The client now maps any 429 to agents.RetryLaterError,
carrying X-RateLimit-Reset-In when present (capped at 1h). Last.fm error 29
(rate limit) is now retryable like 11/16. The buffer's drain loop no longer
lets wake signals bypass an active backoff window - new plays enqueue but
drain only when the window closes - and the wait honors the server delay
via max(backoff, retryIn).

* feat(agents): skip cooling-down agents in aggregate calls

When an agent reports retry-later, remember a per-agent cooldown deadline
(the server-requested delay, or 1 minute when unspecified) and skip that
agent in all aggregate metadata calls until it passes. A round that found
no data but skipped or saw a throttled agent returns ErrRetryLater instead
of ErrNotFound, so callers cannot mistake rate limiting for a definitive
'no data' answer.

* feat(artwork): honor server-requested retry delay when rescheduling

When an external image lookup fails with a retry-later error carrying a
delay (e.g. a 429 with X-RateLimit-Reset-In), the chain trace carries the
largest such hint back to the worker, which reschedules the item at
max(exponential backoff, server delay) instead of backoff alone.

* feat(plugins): retry-later with optional delay for scrobbler and agent plugins

Scrobbler plugins can now return scrobbler(retry_later:N) to request a
retry in N seconds (capped at 1h); the bare token keeps its old meaning.
Metadata-agent plugins, which had no error vocabulary at all, gain the
parallel agent(retry_later[:N]) token, mapped to agents.RetryLaterError so
the aggregate's cooldown and the artwork worker honor plugin throttling
the same way as built-in agents.

* fix: address whole-branch review findings for retry-later handling

Narrow the aggregate's throttled rule to the spec sentence: core.Agents returns
ErrRetryLater only when no agent answered at all (all skipped-cooling or
retry-later). An agent that does not implement the called method now returns an
internal errUnsupported instead of ErrNotFound, so it counts as "did not run" —
without that, the always-appended local agent would answer for biography, URL
and images and make ErrRetryLater unreachable.

Wire the consequence in core/external: a throttled round no longer stamps
ExternalInfoUpdatedAt (artist and album), so the empty result is not cached for
the TTL, and TopSongs maps ErrRetryLater to the same empty-200 the not-found
path already produced instead of a new client-facing error.

Move the Last.fm code-29 mapping into the client's central error construction so
every metadata path produces RetryLaterError, and map ListenBrainz's body-level
code 429 (sent with a non-429 HTTP status) the same way.

Clamp server- and plugin-requested delays in seconds before scaling to a
Duration, in all three parse sites: a header of 18446744074 wrapped past 2^64 and
came out as a 0.29s delay.

Also: extract the artwork worker's reschedule computation into retryDelay() and
cover both it and the trace RetryIn wiring with tests; collapse the double regex
call in mapScrobblerError; drop capabilities.ScrobblerErrorRetryLaterIn (ndpgen
never emits funcs, so plugin authors could not reach it); regenerate the PDKs so
MetadataAgentError reaches the Go and Rust SDKs; de-flake the cooldown tests
(long RetryIn for the skip case, separate expiry spec); and cover the max()
retry-delay aggregation across users in the scrobble buffer.

* refactor: dedupe retry-later parsing and simplify error collection

- Add agents.NewRetryLater and agents.RetryLaterFromSeconds, with a single
  1h cap, replacing the parse+clamp+multiply logic and the maxRetryInSeconds
  constant duplicated across listenbrainz, plugins and the agent adapter.
- Move HTTP header parsing to httpclient.RetryAfter, so the transport layer
  owns it and stays domain-agnostic; drop retryInFromHeaders from the
  ListenBrainz client. Covered by a new Ginkgo table in that package.
- Collapse the two near-identical plugin retry_later regexes into one
  parseRetryLater(prefix, msg) shared by the agent and scrobbler adapters.
- Fold the duplicated noteRetryIn snippet from fetchArtistImage and
  fetchAlbumImage into recordAgent, which already branched on the same
  isTransientExternal condition.
- Replace the atomic.Bool + note() closure in populateArtistInfo with
  errgroup's own error collection; the group carries no context, so a
  returned error does not cancel its siblings.
- Reuse recoveringScrobbler for the per-user delay test instead of a third
  double, and switch fakeScrobbler's mutex-guarded error to the
  atomic.Pointer idiom already used in the same package.

* refactor(listenbrainz): keep rate-limit header parsing in the adapter

The X-RateLimit-Reset-In header is ListenBrainz's own convention, not a
shared one: Last.fm sends no rate-limit headers at all and reports its
limit as a body code, and no other integration in tree sends Retry-After.
A parser in utils/httpclient implied a uniformity across services that
does not exist, so it moves back next to the only client that can know
which header its service sends.

* refactor(agents): collapse the retry-later sentinel and error into one type

ErrRetryLater is now the zero-delay RetryLaterError rather than a separate
errors.New value, so errors.Is and errors.AsType both match the sentinel and
every delay-carrying variant. That removes the trap where a bare sentinel
silently skipped the AsType path, and lets every consumer read the delay off
the error directly: the RetryIn accessor and the two constructors are gone,
with the policy cap applied where untrusted input is parsed.

* refactor(agents): split the cooldown store from the per-dispatch tally

The cooldown map and mutex become a cooldowns value with active/park, holding
no knowledge of errors; agentAttempts records one dispatch's outcomes and owns
the classification that noteAgentError used to hide behind a bool. The three
dispatch loops now touch a single object: skip folds the cooldown check and the
throttled flag into one call, so the store never appears in the loops.

* refactor(agents): share one dispatch loop between the agent call helpers

callAgentMethod and callAgentSliceMethod ran identical loops, differing only in
how they test a result for emptiness: a slice cannot be compared against its
zero value, so the two could not share a constraint. Both now delegate to
callAgent, which takes that test as a parameter. Keeping the loop in one place
matters more than the lines saved: it holds the cooldown skip, the attempt
recording and the empty-dispatch verdict, and a fix applied to one copy but not
the other would be silent.

* test: cover the two retry-later paths a mutation could break silently

Both gaps were proven, not guessed: making the artwork worker pass 0 instead
of the collected hint left all 386 specs green, and replacing the default
agent cooldown with 0 left the agents suite green. The worker test drives a
throttled image agent through drain and asserts the persisted retry_at, and
the cooldown test parks an agent that asked to be retried without naming a
delay, which is what Last.fm does on every rate limit.

* refactor(artwork): carry the external failure as an error, not a flag plus a trace field

The retry delay was riding on ChainTrace, a diagnostic that gets persisted, while
the very same signal — an external source faulted — already travelled by value as
resolution.extError. That was two mechanisms for one idea, and it put control-flow
state inside a serializable trace.

resolution.extError and chainState.extErr become the error itself, so a caller
checks err != nil for the fault and errors.AsType for the delay the provider asked
for. The agent loops return that error last, per convention, and longerRetry keeps
whichever failure wants the longer wait. ChainTrace goes back to holding only steps
and no longer imports core/agents.

* fix(artwork): check the resolve error before reading its resolution

Reading res.extError before the err check was safe only because every error path
in resolve returns a bare resolution{}; a future path returning a partly-filled
one would have been read silently. The failure path now returns no delay
explicitly.

* test(artwork): assert the delay acquire reports, not just its downstream effect

acquire's retry delay was only covered through the worker's persisted retry_at,
one layer away from where the value is computed. Both outcomes are now pinned at
the processor: a plain failure asks for nothing, a throttled provider's delay is
passed through.

* refactor: share the retry-seconds parse and drop the backoff deadline arithmetic

The clamp-before-scaling invariant lived in two parsers and was independently
re-tested in three files with the same magic number; a fix applied to one copy
would have left the others wrapping a huge value down to a fraction of a second.
It moves to agents.ParseRetryIn.

The buffer tracked an absolute retryDeadline only to re-arm a timer that was
already armed for the same instant; a backingOff flag says the same thing without
the arithmetic. The plugin token regex now carries its capability in the pattern
instead of capturing and comparing, so another capability's token in the same
message cannot mask it. resolution.extError becomes extErr, matching its
chainState counterpart.

* fix(agents): keep the longer cooldown when parks overlap

Calls to one agent overlap, so a short cooldown could land after a long one
started and cut it short. park now keeps whichever deadline is later, matching
the rule longerRetry already applies on the artwork side. No in-tree provider
can currently produce two different delays for the same agent, so this is
hardening rather than a fix for observed behaviour.

* fix(agents): parse the retry delay at a fixed width

strconv.Atoi parses into the native int, so on the 32-bit targets we ship
(linux/386, windows/386, three ARM variants) a delay above MaxInt32 seconds
overflowed and became unspecified instead of being capped. No provider sends a
68-year delay, so this is not user-visible, but the overflow tests asserted the
cap and would have failed on those architectures, where tests never run.

* fix(plugins): anchor the retry_later regex to a word boundary

Prevents a superstring like useragent(retry_later) from matching the
agent capability token.
---
 adapters/lastfm/agent.go                      |   3 +-
 adapters/lastfm/agent_test.go                 |  19 +++
 adapters/lastfm/client.go                     |  11 +-
 adapters/listenbrainz/agent_test.go           |  13 ++
 adapters/listenbrainz/client.go               |  17 +++
 adapters/listenbrainz/client_test.go          |  73 +++++++++
 core/agents/agents.go                         | 144 +++++++++++++-----
 core/agents/agents_test.go                    | 126 ++++++++++++++-
 core/agents/interfaces.go                     |  51 ++++++-
 core/agents/interfaces_test.go                |  47 ++++--
 core/agents/song_test.go                      |  27 ++++
 core/artwork/agent_images.go                  |  36 +++--
 core/artwork/agent_images_test.go             |  65 +++++---
 core/artwork/processor.go                     |  32 ++--
 core/artwork/processor_test.go                |  57 ++++---
 core/artwork/resolve.go                       |  49 +++---
 core/artwork/resolve_test.go                  |  46 +++---
 core/artwork/worker.go                        |   9 +-
 core/artwork/worker_soak_test.go              |   2 +-
 core/artwork/worker_test.go                   |  33 ++++
 core/external/provider.go                     |  63 +++++---
 core/external/provider_similarsongs.go        |   2 +-
 core/external/provider_topsongs_test.go       |  15 ++
 .../external/provider_updatealbuminfo_test.go |  22 +++
 .../provider_updateartistinfo_test.go         |  19 +++
 core/scrobbler/buffered_scrobbler.go          |  47 +++---
 core/scrobbler/buffered_scrobbler_test.go     | 122 ++++++++++++++-
 core/scrobbler/interfaces.go                  |   4 +-
 core/scrobbler/play_tracker_test.go           |  37 +++--
 plugins/capabilities.go                       |  29 +++-
 plugins/capabilities/metadata_agent.go        |  12 ++
 plugins/metadata_agent.go                     |   3 +
 plugins/metadata_agent_test.go                |  26 ++++
 plugins/pdk/go/metadata/metadata.go           |  12 ++
 plugins/pdk/go/metadata/metadata_stub.go      |  12 ++
 .../rust/nd-pdk-capabilities/src/metadata.rs  |   5 +
 plugins/scrobbler_adapter.go                  |   5 +-
 plugins/scrobbler_adapter_test.go             |  22 +++
 38 files changed, 1085 insertions(+), 232 deletions(-)
 create mode 100644 core/agents/song_test.go

diff --git a/adapters/lastfm/agent.go b/adapters/lastfm/agent.go
index 863868b5a..7f005db1a 100644
--- a/adapters/lastfm/agent.go
+++ b/adapters/lastfm/agent.go
@@ -405,7 +405,8 @@ func (l *lastfmAgent) Scrobble(ctx context.Context, userId string, s scrobbler.S
 		log.Warn(ctx, "Last.fm client.scrobble returned error", "track", s.Title, err)
 		return errors.Join(err, scrobbler.ErrRetryLater)
 	}
-	if lfErr.Code == 11 || lfErr.Code == 16 {
+	// 11: service offline; 16: temporarily unavailable. Rate limiting is mapped by the client.
+	if lfErr.Code == 11 || lfErr.Code == 16 || errors.Is(err, scrobbler.ErrRetryLater) {
 		return errors.Join(err, scrobbler.ErrRetryLater)
 	}
 	return errors.Join(err, scrobbler.ErrUnrecoverable)
diff --git a/adapters/lastfm/agent_test.go b/adapters/lastfm/agent_test.go
index 94024b9ab..ce81e0916 100644
--- a/adapters/lastfm/agent_test.go
+++ b/adapters/lastfm/agent_test.go
@@ -100,6 +100,15 @@ var _ = Describe("lastfmAgent", func() {
 			Expect(httpClient.RequestCount).To(Equal(1))
 			Expect(httpClient.SavedRequest.URL.Query().Get("artist")).To(Equal("U2"))
 		})
+
+		It("returns ErrRetryLater on error 29 (rate limit exceeded)", func() {
+			httpClient.Res = http.Response{
+				Body:       io.NopCloser(bytes.NewBufferString(`{"error":29,"message":"Rate limit exceeded"}`)),
+				StatusCode: 200,
+			}
+			_, err := agent.GetArtistBiography(ctx, "123", "U2", "")
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
+		})
 	})
 
 	Describe("Language Fallback", func() {
@@ -497,6 +506,16 @@ var _ = Describe("lastfmAgent", func() {
 				Expect(err).To(MatchError(scrobbler.ErrRetryLater))
 			})
 
+			It("returns ErrRetryLater on error 29 (rate limit exceeded)", func() {
+				httpClient.Res = http.Response{
+					Body:       io.NopCloser(bytes.NewBufferString(`{"error":29,"message":"Rate limit exceeded"}`)),
+					StatusCode: 200,
+				}
+
+				err := agent.Scrobble(ctx, "user-1", scrobbler.Scrobble{MediaFile: *track, TimeStamp: time.Now()})
+				Expect(errors.Is(err, scrobbler.ErrRetryLater)).To(BeTrue())
+			})
+
 			It("returns ErrRetryLater on http errors", func() {
 				httpClient.Res = http.Response{
 					Body:       io.NopCloser(bytes.NewBufferString(`internal server error`)),
diff --git a/adapters/lastfm/client.go b/adapters/lastfm/client.go
index 726df1360..e468aa638 100644
--- a/adapters/lastfm/client.go
+++ b/adapters/lastfm/client.go
@@ -5,6 +5,7 @@ import (
 	"crypto/md5"
 	"encoding/hex"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/url"
@@ -14,11 +15,15 @@ import (
 	"strings"
 	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/log"
 )
 
 const (
 	apiBaseUrl = "https://ws.audioscrobbler.com/2.0/"
+	// errCodeRateLimit is Last.fm's "rate limit exceeded"; it arrives in the body, with HTTP 200
+	// and no rate-limit headers, so the body code is the only signal.
+	errCodeRateLimit = 29
 )
 
 type lastFMError struct {
@@ -225,7 +230,11 @@ func (c *client) makeRequest(ctx context.Context, method string, params url.Valu
 		return nil, jsonErr
 	}
 	if response.Error != 0 {
-		return &response, &lastFMError{Code: response.Error, Message: response.Message}
+		var err error = &lastFMError{Code: response.Error, Message: response.Message}
+		if response.Error == errCodeRateLimit {
+			err = errors.Join(err, &agents.RetryLaterError{})
+		}
+		return &response, err
 	}
 
 	return &response, nil
diff --git a/adapters/listenbrainz/agent_test.go b/adapters/listenbrainz/agent_test.go
index 2c4668296..a201b7c3a 100644
--- a/adapters/listenbrainz/agent_test.go
+++ b/adapters/listenbrainz/agent_test.go
@@ -164,6 +164,19 @@ var _ = Describe("listenBrainzAgent", func() {
 			err := agent.Scrobble(ctx, "user-1", sc)
 			Expect(err).To(MatchError(scrobbler.ErrUnrecoverable))
 		})
+
+		It("keeps a 429 scrobble for retry and carries the delay", func() {
+			httpClient.Res = http.Response{
+				StatusCode: 429,
+				Header:     http.Header{"X-Ratelimit-Reset-In": []string{"7"}},
+				Body:       io.NopCloser(bytes.NewBufferString(`{"code":429,"error":"rate limited"}`)),
+			}
+			err := agent.Scrobble(ctx, "user-1", scrobbler.Scrobble{MediaFile: *track, TimeStamp: time.Now()})
+			Expect(errors.Is(err, scrobbler.ErrRetryLater)).To(BeTrue())
+			retry, ok := errors.AsType[*agents.RetryLaterError](err)
+			Expect(ok).To(BeTrue())
+			Expect(retry.RetryIn).To(Equal(7 * time.Second))
+		})
 	})
 
 	Describe("GetArtistUrl", func() {
diff --git a/adapters/listenbrainz/client.go b/adapters/listenbrainz/client.go
index 708f02f28..aae4fb51d 100644
--- a/adapters/listenbrainz/client.go
+++ b/adapters/listenbrainz/client.go
@@ -13,6 +13,7 @@ import (
 	"slices"
 
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/log"
 )
 
@@ -21,6 +22,12 @@ const (
 	labsBase  = "https://labs.api.listenbrainz.org/"
 )
 
+// retryLaterErr reads the wait ListenBrainz asked for. It sends X-RateLimit-Reset-In
+// (delta-seconds) on every response, including the 429, and never Retry-After.
+func retryLaterErr(h http.Header) *agents.RetryLaterError {
+	return &agents.RetryLaterError{RetryIn: agents.ParseRetryIn(h.Get("X-RateLimit-Reset-In"))}
+}
+
 var (
 	ErrorNotFound = errors.New("listenbrainz: not found")
 )
@@ -174,6 +181,9 @@ func (c *client) makeAuthenticatedRequest(ctx context.Context, method string, en
 	}
 
 	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusTooManyRequests {
+		return nil, retryLaterErr(resp.Header)
+	}
 	decoder := json.NewDecoder(resp.Body)
 
 	var response listenBrainzResponse
@@ -185,6 +195,10 @@ func (c *client) makeAuthenticatedRequest(ctx context.Context, method string, en
 		return nil, jsonErr
 	}
 	if response.Code != 0 && response.Code != 200 {
+		// LB also reports rate limiting as a body code, not only as an HTTP status.
+		if response.Code == http.StatusTooManyRequests {
+			return &response, retryLaterErr(resp.Header)
+		}
 		return &response, &listenBrainzError{Code: response.Code, Message: response.Error}
 	}
 
@@ -211,6 +225,9 @@ func (c *client) makeGenericRequest(ctx context.Context, method string, endpoint
 	// On a 200 code, there is no code. Decode using using error message if it exists
 	if resp.StatusCode != 200 {
 		defer resp.Body.Close()
+		if resp.StatusCode == http.StatusTooManyRequests {
+			return nil, retryLaterErr(resp.Header)
+		}
 		decoder := json.NewDecoder(resp.Body)
 
 		var lbzError lbzHttpError
diff --git a/adapters/listenbrainz/client_test.go b/adapters/listenbrainz/client_test.go
index 319cf01ab..ec0b0ac11 100644
--- a/adapters/listenbrainz/client_test.go
+++ b/adapters/listenbrainz/client_test.go
@@ -4,13 +4,17 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
 	"os"
+	"strings"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -461,4 +465,73 @@ var _ = Describe("client", func() {
 			}))
 		})
 	})
+
+	Describe("rate limiting", func() {
+		It("returns RetryLaterError with the header delay on 429", func() {
+			httpClient.Res = http.Response{
+				StatusCode: 429,
+				Header:     http.Header{"X-Ratelimit-Reset-In": []string{"3"}},
+				Body:       io.NopCloser(strings.NewReader(`{"code":429,"error":"You have exceeded your rate limit."}`)),
+			}
+			_, err := client.validateToken(context.Background(), "token")
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
+			retry, ok := errors.AsType[*agents.RetryLaterError](err)
+			Expect(ok).To(BeTrue())
+			Expect(retry.RetryIn).To(Equal(3 * time.Second))
+		})
+
+		It("returns RetryLaterError with zero delay when no header is present", func() {
+			httpClient.Res = http.Response{
+				StatusCode: 429,
+				Body:       io.NopCloser(strings.NewReader(`{"code":429,"error":"rate limited"}`)),
+			}
+			_, err := client.validateToken(context.Background(), "token")
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
+			retry, _ := errors.AsType[*agents.RetryLaterError](err)
+			Expect(retry.RetryIn).To(BeZero())
+		})
+
+		DescribeTable("caps absurd header values at one hour",
+			func(header string) {
+				httpClient.Res = http.Response{
+					StatusCode: 429,
+					Header:     http.Header{"X-Ratelimit-Reset-In": []string{header}},
+					Body:       io.NopCloser(strings.NewReader(`{"code":429,"error":"rate limited"}`)),
+				}
+				_, err := client.validateToken(context.Background(), "token")
+				retry, _ := errors.AsType[*agents.RetryLaterError](err)
+				Expect(retry.RetryIn).To(Equal(time.Hour))
+			},
+			Entry("a large value", "999999"),
+			Entry("a huge value", "99999999999"),
+			// Scaling this to nanoseconds before capping wraps past 2^64, landing on ~0.29s.
+			Entry("a value that overflows int64 nanoseconds", "18446744074"),
+		)
+
+		It("maps a body-level 429 sent with a non-429 status", func() {
+			httpClient.Res = http.Response{
+				StatusCode: 200,
+				Header:     http.Header{"X-Ratelimit-Reset-In": []string{"7"}},
+				Body:       io.NopCloser(strings.NewReader(`{"code":429,"error":"You have exceeded your rate limit."}`)),
+			}
+			_, err := client.validateToken(context.Background(), "token")
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
+			retry, ok := errors.AsType[*agents.RetryLaterError](err)
+			Expect(ok).To(BeTrue())
+			Expect(retry.RetryIn).To(Equal(7 * time.Second))
+		})
+
+		It("returns RetryLaterError on a 429 from makeGenericRequest", func() {
+			httpClient.Res = http.Response{
+				StatusCode: 429,
+				Header:     http.Header{"X-Ratelimit-Reset-In": []string{"5"}},
+				Body:       io.NopCloser(strings.NewReader(`{"code":429,"error":"rate limited"}`)),
+			}
+			_, err := client.getArtistUrl(context.Background(), "1")
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
+			retry, ok := errors.AsType[*agents.RetryLaterError](err)
+			Expect(ok).To(BeTrue())
+			Expect(retry.RetryIn).To(Equal(5 * time.Second))
+		})
+	})
 })
diff --git a/core/agents/agents.go b/core/agents/agents.go
index 348f7d4e7..ac623951c 100644
--- a/core/agents/agents.go
+++ b/core/agents/agents.go
@@ -1,9 +1,12 @@
 package agents
 
 import (
+	"cmp"
 	"context"
+	"errors"
 	"slices"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -22,11 +25,43 @@ type PluginLoader interface {
 	LoadMediaAgent(name string) (Interface, bool)
 }
 
+// agentCooldown is the default cooldown duration for an agent that returns a RetryLaterError without a specific
+// RetryIn duration.
+const agentCooldown = time.Minute
+
+// errUnsupported marks an agent that does not implement the requested method: it never ran,
+// so it neither answered nor throttled.
+var errUnsupported = errors.New("agent does not support this method")
+
 // Agents is a meta-agent that aggregates multiple built-in and plugin agents. It tries each enabled agent in order
 // until one returns valid data.
 type Agents struct {
 	ds           model.DataStore
 	pluginLoader PluginLoader
+	cooldowns    cooldowns
+}
+
+// cooldowns remembers, across dispatches, which agents asked to be left alone and until when.
+type cooldowns struct {
+	mu    sync.RWMutex
+	until map[string]time.Time
+}
+
+func (c *cooldowns) active(name string) bool {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return time.Now().Before(c.until[name])
+}
+
+// park keeps whichever deadline is later, so a call still in flight when a longer cooldown
+// starts cannot cut it short when it finally answers.
+func (c *cooldowns) park(name string, d time.Duration) {
+	until := time.Now().Add(d)
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if until.After(c.until[name]) {
+		c.until[name] = until
+	}
 }
 
 // GetAgents returns the singleton instance of Agents
@@ -41,6 +76,7 @@ func createAgents(ds model.DataStore, pluginLoader PluginLoader) *Agents {
 	return &Agents{
 		ds:           ds,
 		pluginLoader: pluginLoader,
+		cooldowns:    cooldowns{until: map[string]time.Time{}},
 	}
 }
 
@@ -171,7 +207,7 @@ func (a *Agents) GetArtistMBID(ctx context.Context, id string, name string) (str
 	return callAgentMethod(ctx, a, "GetArtistMBID", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistMBIDRetriever)
 		if !ok {
-			return "", ErrNotFound
+			return "", errUnsupported
 		}
 		return retriever.GetArtistMBID(ctx, id, name)
 	})
@@ -188,7 +224,7 @@ func (a *Agents) GetArtistURL(ctx context.Context, id, name, mbid string) (strin
 	return callAgentMethod(ctx, a, "GetArtistURL", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistURLRetriever)
 		if !ok {
-			return "", ErrNotFound
+			return "", errUnsupported
 		}
 		return retriever.GetArtistURL(ctx, id, name, mbid)
 	})
@@ -205,7 +241,7 @@ func (a *Agents) GetArtistBiography(ctx context.Context, id, name, mbid string)
 	return callAgentMethod(ctx, a, "GetArtistBiography", func(ag Interface) (string, error) {
 		retriever, ok := ag.(ArtistBiographyRetriever)
 		if !ok {
-			return "", ErrNotFound
+			return "", errUnsupported
 		}
 		return retriever.GetArtistBiography(ctx, id, name, mbid)
 	})
@@ -224,7 +260,11 @@ func (a *Agents) GetSimilarArtists(ctx context.Context, id, name, mbid string, l
 	overLimit := int(float64(limit) * conf.Server.DevExternalArtistFetchMultiplier)
 
 	start := time.Now()
+	attempts := newAttempts(&a.cooldowns)
 	for _, enabledAgent := range a.getEnabledAgentNames() {
+		if attempts.skip(enabledAgent.name) {
+			continue
+		}
 		ag := a.getAgent(enabledAgent)
 		if ag == nil {
 			continue
@@ -237,6 +277,7 @@ func (a *Agents) GetSimilarArtists(ctx context.Context, id, name, mbid string, l
 			continue
 		}
 		similar, err := retriever.GetSimilarArtists(ctx, id, name, mbid, overLimit)
+		attempts.record(enabledAgent.name, err)
 		if len(similar) > 0 && err == nil {
 			if log.IsGreaterOrEqualTo(log.LevelTrace) {
 				log.Debug(ctx, "Got Similar Artists", "agent", ag.AgentName(), "artist", name, "similar", similar, "elapsed", time.Since(start))
@@ -246,7 +287,7 @@ func (a *Agents) GetSimilarArtists(ctx context.Context, id, name, mbid string, l
 			return similar, err
 		}
 	}
-	return nil, ErrNotFound
+	return nil, attempts.noResultErr()
 }
 
 func (a *Agents) GetArtistImages(ctx context.Context, id, name, mbid string) ([]ExternalImage, error) {
@@ -260,7 +301,7 @@ func (a *Agents) GetArtistImages(ctx context.Context, id, name, mbid string) ([]
 	return callAgentSliceMethod(ctx, a, "GetArtistImages", func(ag Interface) ([]ExternalImage, error) {
 		retriever, ok := ag.(ArtistImageRetriever)
 		if !ok {
-			return nil, ErrNotFound
+			return nil, errUnsupported
 		}
 		return retriever.GetArtistImages(ctx, id, name, mbid)
 	})
@@ -281,7 +322,7 @@ func (a *Agents) GetArtistTopSongs(ctx context.Context, id, artistName, mbid str
 	return callAgentSliceMethod(ctx, a, "GetArtistTopSongs", func(ag Interface) ([]Song, error) {
 		retriever, ok := ag.(ArtistTopSongsRetriever)
 		if !ok {
-			return nil, ErrNotFound
+			return nil, errUnsupported
 		}
 		return retriever.GetArtistTopSongs(ctx, id, artistName, mbid, overLimit)
 	})
@@ -295,7 +336,7 @@ func (a *Agents) GetAlbumInfo(ctx context.Context, name, artist, mbid string) (*
 	return callAgentMethod(ctx, a, "GetAlbumInfo", func(ag Interface) (*AlbumInfo, error) {
 		retriever, ok := ag.(AlbumInfoRetriever)
 		if !ok {
-			return nil, ErrNotFound
+			return nil, errUnsupported
 		}
 		return retriever.GetAlbumInfo(ctx, name, artist, mbid)
 	})
@@ -309,7 +350,7 @@ func (a *Agents) GetAlbumImages(ctx context.Context, name, artist, mbid string)
 	return callAgentSliceMethod(ctx, a, "GetAlbumImages", func(ag Interface) ([]ExternalImage, error) {
 		retriever, ok := ag.(AlbumImageRetriever)
 		if !ok {
-			return nil, ErrNotFound
+			return nil, errUnsupported
 		}
 		return retriever.GetAlbumImages(ctx, name, artist, mbid)
 	})
@@ -320,7 +361,7 @@ func (a *Agents) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, m
 	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByTrack", func(ag Interface) ([]Song, error) {
 		retriever, ok := ag.(SimilarSongsByTrackRetriever)
 		if !ok {
-			return nil, ErrNotFound
+			return nil, errUnsupported
 		}
 		return retriever.GetSimilarSongsByTrack(ctx, id, name, artist, mbid, count)
 	})
@@ -331,7 +372,7 @@ func (a *Agents) GetSimilarSongsByAlbum(ctx context.Context, id, name, artist, m
 	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByAlbum", func(ag Interface) ([]Song, error) {
 		retriever, ok := ag.(SimilarSongsByAlbumRetriever)
 		if !ok {
-			return nil, ErrNotFound
+			return nil, errUnsupported
 		}
 		return retriever.GetSimilarSongsByAlbum(ctx, id, name, artist, mbid, count)
 	})
@@ -349,16 +390,61 @@ func (a *Agents) GetSimilarSongsByArtist(ctx context.Context, id, name, mbid str
 	return callAgentSliceMethod(ctx, a, "GetSimilarSongsByArtist", func(ag Interface) ([]Song, error) {
 		retriever, ok := ag.(SimilarSongsByArtistRetriever)
 		if !ok {
-			return nil, ErrNotFound
+			return nil, errUnsupported
 		}
 		return retriever.GetSimilarSongsByArtist(ctx, id, name, mbid, count)
 	})
 }
 
-func callAgentMethod[T comparable](ctx context.Context, agents *Agents, methodName string, fn func(Interface) (T, error)) (T, error) {
+// agentAttempts tallies what the enabled agents did in one dispatch.
+type agentAttempts struct {
+	cooldowns *cooldowns
+	throttled bool
+	answered  bool
+}
+
+func newAttempts(c *cooldowns) agentAttempts {
+	return agentAttempts{cooldowns: c}
+}
+
+// skip reports whether name is still cooling down, counting it as throttled for this dispatch.
+func (t *agentAttempts) skip(name string) bool {
+	if !t.cooldowns.active(name) {
+		return false
+	}
+	t.throttled = true
+	return true
+}
+
+// record files one agent's outcome, parking it when it asked to be retried later.
+func (t *agentAttempts) record(name string, err error) {
+	switch retry, isRetryLater := errors.AsType[*RetryLaterError](err); {
+	case errors.Is(err, errUnsupported):
+	case isRetryLater:
+		t.cooldowns.park(name, cmp.Or(retry.RetryIn, agentCooldown))
+		t.throttled = true
+	default:
+		t.answered = true
+	}
+}
+
+// noResultErr tells a retryable empty dispatch (nobody answered) from a definitive miss.
+func (t *agentAttempts) noResultErr() error {
+	if t.throttled && !t.answered {
+		return ErrRetryLater
+	}
+	return ErrNotFound
+}
+
+// callAgent tries each enabled agent in order until found reports a usable result.
+func callAgent[T any](ctx context.Context, agents *Agents, methodName string, fn func(Interface) (T, error), found func(T) bool) (T, error) {
 	var zero T
 	start := time.Now()
+	attempts := newAttempts(&agents.cooldowns)
 	for _, enabledAgent := range agents.getEnabledAgentNames() {
+		if attempts.skip(enabledAgent.name) {
+			continue
+		}
 		ag := agents.getAgent(enabledAgent)
 		if ag == nil {
 			continue
@@ -367,41 +453,29 @@ func callAgentMethod[T comparable](ctx context.Context, agents *Agents, methodNa
 			break
 		}
 		result, err := fn(ag)
+		attempts.record(enabledAgent.name, err)
 		if err != nil {
 			log.Trace(ctx, "Agent method call error", "method", methodName, "agent", ag.AgentName(), "error", err)
 			continue
 		}
 
-		if result != zero {
+		if found(result) {
 			log.Debug(ctx, "Got result", "method", methodName, "agent", ag.AgentName(), "elapsed", time.Since(start))
 			return result, nil
 		}
 	}
-	return zero, ErrNotFound
+	return zero, attempts.noResultErr()
+}
+
+func callAgentMethod[T comparable](ctx context.Context, agents *Agents, methodName string, fn func(Interface) (T, error)) (T, error) {
+	return callAgent(ctx, agents, methodName, fn, func(result T) bool {
+		var zero T
+		return result != zero
+	})
 }
 
 func callAgentSliceMethod[T any](ctx context.Context, agents *Agents, methodName string, fn func(Interface) ([]T, error)) ([]T, error) {
-	start := time.Now()
-	for _, enabledAgent := range agents.getEnabledAgentNames() {
-		ag := agents.getAgent(enabledAgent)
-		if ag == nil {
-			continue
-		}
-		if utils.IsCtxDone(ctx) {
-			break
-		}
-		results, err := fn(ag)
-		if err != nil {
-			log.Trace(ctx, "Agent method call error", "method", methodName, "agent", ag.AgentName(), "error", err)
-			continue
-		}
-
-		if len(results) > 0 {
-			log.Debug(ctx, "Got results", "method", methodName, "agent", ag.AgentName(), "count", len(results), "elapsed", time.Since(start))
-			return results, nil
-		}
-	}
-	return nil, ErrNotFound
+	return callAgent(ctx, agents, methodName, fn, func(results []T) bool { return len(results) > 0 })
 }
 
 var _ Interface = (*Agents)(nil)
diff --git a/core/agents/agents_test.go b/core/agents/agents_test.go
index e79b2b3c8..35ebf18d8 100644
--- a/core/agents/agents_test.go
+++ b/core/agents/agents_test.go
@@ -3,6 +3,7 @@ package agents
 import (
 	"context"
 	"errors"
+	"time"
 
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
@@ -14,6 +15,29 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+var _ = Describe("cooldowns", func() {
+	// Calls to one agent overlap, so a short cooldown can land after a long one started.
+	It("keeps the longer deadline when a shorter park lands after it", func() {
+		c := cooldowns{until: map[string]time.Time{}}
+
+		c.park("fake", time.Hour)
+		c.park("fake", time.Millisecond)
+
+		time.Sleep(10 * time.Millisecond)
+		Expect(c.active("fake")).To(BeTrue())
+	})
+
+	It("extends the deadline when the later park is longer", func() {
+		c := cooldowns{until: map[string]time.Time{}}
+
+		c.park("fake", time.Millisecond)
+		c.park("fake", time.Hour)
+
+		time.Sleep(10 * time.Millisecond)
+		Expect(c.active("fake")).To(BeTrue())
+	})
+})
+
 var _ = Describe("Agents", func() {
 	var ctx context.Context
 	var cancel context.CancelFunc
@@ -160,6 +184,102 @@ var _ = Describe("Agents", func() {
 			})
 		})
 
+		Describe("cooldown", func() {
+			It("skips an agent that returned RetryLaterError until the deadline", func() {
+				mock.Err = &RetryLaterError{RetryIn: time.Hour}
+				_, err := ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				Expect(errors.Is(err, ErrRetryLater)).To(BeTrue())
+
+				// Immediately after: agent is skipped, not called
+				mock.Err = nil
+				calls := mock.Calls
+				_, err = ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				Expect(mock.Calls).To(Equal(calls))
+				Expect(errors.Is(err, ErrRetryLater)).To(BeTrue())
+			})
+
+			// Providers that throttle without saying for how long (Last.fm sends no delay at all)
+			// must still be parked, or the aggregate keeps calling them on every request.
+			It("parks an agent that asked to be retried without a delay", func() {
+				mock.Err = ErrRetryLater
+				_, err := ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				Expect(errors.Is(err, ErrRetryLater)).To(BeTrue())
+
+				mock.Err = nil
+				calls := mock.Calls
+				_, err = ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				Expect(mock.Calls).To(Equal(calls), "the default cooldown must outlast the request")
+				Expect(errors.Is(err, ErrRetryLater)).To(BeTrue())
+			})
+
+			It("calls the agent again once the cooldown expires", func() {
+				mock.Err = &RetryLaterError{RetryIn: 10 * time.Millisecond}
+				_, err := ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				Expect(errors.Is(err, ErrRetryLater)).To(BeTrue())
+
+				mock.Err = nil
+				Eventually(func() (string, error) {
+					return ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				}, 5*time.Second, 10*time.Millisecond).Should(Equal("bio"))
+			})
+
+			It("returns ErrNotFound, not ErrRetryLater, when agents failed for other reasons", func() {
+				mock.Err = errors.New("boom")
+				_, err := ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				Expect(errors.Is(err, ErrNotFound)).To(BeTrue())
+				Expect(errors.Is(err, ErrRetryLater)).To(BeFalse())
+			})
+
+			// ErrRetryLater tells the caller "nobody answered, do not cache this". A definitive
+			// answer from any other agent is an answer, throttled peer or not.
+			It("returns ErrNotFound when another agent answered with a definitive miss", func() {
+				other := &mockAgent{Err: ErrNotFound}
+				Register("fake2", func(model.DataStore) Interface { return other })
+				conf.Server.Agents = "fake,fake2"
+				ag = createAgents(ds, nil)
+				mock.Err = &RetryLaterError{RetryIn: time.Hour}
+
+				_, err := ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				Expect(errors.Is(err, ErrNotFound)).To(BeTrue())
+				Expect(errors.Is(err, ErrRetryLater)).To(BeFalse())
+
+				// The cooldown was still recorded for the throttled agent
+				calls := mock.Calls
+				_, _ = ag.GetArtistBiography(ctx, "id", "name", "mbid")
+				Expect(mock.Calls).To(Equal(calls))
+			})
+
+			It("returns ErrNotFound when another agent answered with an empty slice", func() {
+				empty := &testImageAgent{Name: "emptyImages"}
+				Register("emptyImages", func(model.DataStore) Interface { return empty })
+				conf.Server.Agents = "fake,emptyImages"
+				ag = createAgents(ds, nil)
+				mock.Err = &RetryLaterError{RetryIn: time.Hour}
+
+				_, err := ag.GetArtistImages(ctx, "123", "test", "mb123")
+				Expect(errors.Is(err, ErrNotFound)).To(BeTrue())
+				Expect(errors.Is(err, ErrRetryLater)).To(BeFalse())
+			})
+
+			It("returns ErrRetryLater from GetSimilarArtists when only cooling agents remain", func() {
+				mock.Err = &RetryLaterError{RetryIn: time.Hour}
+				_, err := ag.GetSimilarArtists(ctx, "123", "test", "mb123", 2)
+				Expect(errors.Is(err, ErrRetryLater)).To(BeTrue())
+			})
+
+			It("returns ErrNotFound from GetSimilarArtists when another agent answered", func() {
+				other := &mockAgent{Err: ErrNotFound}
+				Register("fake2", func(model.DataStore) Interface { return other })
+				conf.Server.Agents = "fake,fake2"
+				ag = createAgents(ds, nil)
+				mock.Err = &RetryLaterError{RetryIn: time.Hour}
+
+				_, err := ag.GetSimilarArtists(ctx, "123", "test", "mb123", 2)
+				Expect(errors.Is(err, ErrNotFound)).To(BeTrue())
+				Expect(errors.Is(err, ErrRetryLater)).To(BeFalse())
+			})
+		})
+
 		Describe("GetArtistImages", func() {
 			It("returns on first match", func() {
 				Expect(ag.GetArtistImages(ctx, "123", "test", "mb123")).To(Equal([]ExternalImage{{
@@ -423,8 +543,9 @@ var _ = Describe("Agents", func() {
 })
 
 type mockAgent struct {
-	Args []any
-	Err  error
+	Args  []any
+	Err   error
+	Calls int
 }
 
 func (a *mockAgent) AgentName() string {
@@ -449,6 +570,7 @@ func (a *mockAgent) GetArtistURL(_ context.Context, id, name, mbid string) (stri
 
 func (a *mockAgent) GetArtistBiography(_ context.Context, id, name, mbid string) (string, error) {
 	a.Args = []any{id, name, mbid}
+	a.Calls++
 	if a.Err != nil {
 		return "", a.Err
 	}
diff --git a/core/agents/interfaces.go b/core/agents/interfaces.go
index 7fc5de361..9225a0442 100644
--- a/core/agents/interfaces.go
+++ b/core/agents/interfaces.go
@@ -3,6 +3,9 @@ package agents
 import (
 	"context"
 	"errors"
+	"fmt"
+	"strconv"
+	"time"
 
 	"github.com/gohugoio/hashstructure"
 	"github.com/navidrome/navidrome/model"
@@ -52,11 +55,49 @@ func (s Song) Equals(other Song) bool {
 	return h1 == h2
 }
 
-var (
-	// ErrNotFound means the provider answered and had nothing. Return the underlying error
-	// for a fault instead, or callers that back off on faults will treat it as definitive.
-	ErrNotFound = errors.New("not found")
-)
+// ErrNotFound means the provider answered and had nothing. Return the underlying error
+// for a fault instead, or callers that back off on faults will treat it as definitive.
+var ErrNotFound = errors.New("not found")
+
+// ErrRetryLater is the zero-delay RetryLaterError: the provider is temporarily unavailable
+// or throttling us, but did not say for how long. Both errors.Is(err, ErrRetryLater) and
+// errors.AsType[*RetryLaterError] match it and every delay-carrying variant.
+// Treat it as immutable; build a new RetryLaterError to name a delay.
+var ErrRetryLater = &RetryLaterError{}
+
+// RetryLaterError asks callers to back off, optionally for the delay the provider requested.
+type RetryLaterError struct {
+	RetryIn time.Duration
+}
+
+func (e *RetryLaterError) Error() string {
+	if e.RetryIn > 0 {
+		return fmt.Sprintf("retry later (in %s)", e.RetryIn)
+	}
+	return "retry later"
+}
+
+func (e *RetryLaterError) Is(target error) bool {
+	_, ok := target.(*RetryLaterError)
+	return ok
+}
+
+// MaxRetryIn caps a delay parsed from a provider, so a bogus value cannot park it indefinitely.
+const MaxRetryIn = time.Hour
+const maxRetryInSeconds = int(MaxRetryIn / time.Second)
+
+// ParseRetryIn reads a provider's delay given in seconds, from a header or a plugin token.
+// Anything unparseable or non-positive means unspecified.
+func ParseRetryIn(seconds string) time.Duration {
+	// Clamp in seconds: scaling first would wrap a huge value past int64 nanoseconds,
+	// turning "wait an age" into a fraction of a second. Parse at a fixed width so the
+	// cap holds on the 32-bit targets we ship, where a plain Atoi would overflow first.
+	secs, err := strconv.ParseInt(seconds, 10, 64)
+	if err != nil || secs <= 0 {
+		return 0
+	}
+	return time.Duration(min(secs, int64(maxRetryInSeconds))) * time.Second
+}
 
 // AlbumInfoRetriever provides album info (no images)
 type AlbumInfoRetriever interface {
diff --git a/core/agents/interfaces_test.go b/core/agents/interfaces_test.go
index c13710a38..6acbc545d 100644
--- a/core/agents/interfaces_test.go
+++ b/core/agents/interfaces_test.go
@@ -1,27 +1,42 @@
-package agents
+package agents_test
 
 import (
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/navidrome/navidrome/core/agents"
+	"github.com/navidrome/navidrome/core/scrobbler"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
-var _ = Describe("Song.Equals", func() {
-	base := Song{ID: "1", Name: "S", Artists: []Artist{{ID: "x", Name: "A"}}}
-	It("true for identical songs incl Artists", func() {
-		Expect(base.Equals(base)).To(BeTrue())
+var _ = Describe("RetryLaterError", func() {
+	It("matches the ErrRetryLater sentinel via errors.Is", func() {
+		err := &agents.RetryLaterError{RetryIn: 30 * time.Second}
+		Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
 	})
-	It("false when Artists differ", func() {
-		other := base
-		other.Artists = []Artist{{ID: "y", Name: "B"}}
-		Expect(base.Equals(other)).To(BeFalse())
+
+	It("matches through errors.Join and wrapping", func() {
+		err := fmt.Errorf("calling LB: %w", errors.Join(errors.New("http 429"), &agents.RetryLaterError{}))
+		Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
 	})
-	It("false when a scalar differs", func() {
-		other := base
-		other.Name = "T"
-		Expect(base.Equals(other)).To(BeFalse())
+
+	It("exposes the delay through the wrapped error", func() {
+		err := errors.Join(errors.New("http 429"), &agents.RetryLaterError{RetryIn: 42 * time.Second})
+		retry, ok := errors.AsType[*agents.RetryLaterError](err)
+		Expect(ok).To(BeTrue())
+		Expect(retry.RetryIn).To(Equal(42 * time.Second))
 	})
-	It("true when both have empty Artists and equal scalars", func() {
-		a := Song{ID: "1", Name: "S"}
-		Expect(a.Equals(a)).To(BeTrue())
+
+	It("matches the sentinel too, reporting no delay", func() {
+		retry, ok := errors.AsType[*agents.RetryLaterError](agents.ErrRetryLater)
+		Expect(ok).To(BeTrue())
+		Expect(retry.RetryIn).To(BeZero())
+	})
+
+	It("is the same sentinel as scrobbler.ErrRetryLater", func() {
+		Expect(errors.Is(scrobbler.ErrRetryLater, agents.ErrRetryLater)).To(BeTrue())
+		Expect(errors.Is(&agents.RetryLaterError{}, scrobbler.ErrRetryLater)).To(BeTrue())
 	})
 })
diff --git a/core/agents/song_test.go b/core/agents/song_test.go
new file mode 100644
index 000000000..c13710a38
--- /dev/null
+++ b/core/agents/song_test.go
@@ -0,0 +1,27 @@
+package agents
+
+import (
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Song.Equals", func() {
+	base := Song{ID: "1", Name: "S", Artists: []Artist{{ID: "x", Name: "A"}}}
+	It("true for identical songs incl Artists", func() {
+		Expect(base.Equals(base)).To(BeTrue())
+	})
+	It("false when Artists differ", func() {
+		other := base
+		other.Artists = []Artist{{ID: "y", Name: "B"}}
+		Expect(base.Equals(other)).To(BeFalse())
+	})
+	It("false when a scalar differs", func() {
+		other := base
+		other.Name = "T"
+		Expect(base.Equals(other)).To(BeFalse())
+	})
+	It("true when both have empty Artists and equal scalars", func() {
+		a := Song{ID: "1", Name: "S"}
+		Expect(a.Equals(a)).To(BeTrue())
+	})
+})
diff --git a/core/artwork/agent_images.go b/core/artwork/agent_images.go
index 95596dabc..985abacd7 100644
--- a/core/artwork/agent_images.go
+++ b/core/artwork/agent_images.go
@@ -2,6 +2,7 @@ package artwork
 
 import (
 	"context"
+	"errors"
 	"io"
 	"net/url"
 
@@ -41,22 +42,36 @@ func bestImageURL(imgs []agents.ExternalImage) *url.URL {
 	return best
 }
 
-// fetchArtistImage tries each enabled artist-image agent in order. extErr is true only when no
+// longerRetry keeps whichever external failure asks for the longer wait, so one provider's
+// short delay cannot shorten another's.
+func longerRetry(a, b error) error {
+	if a == nil {
+		return b
+	}
+	var ra, rb *agents.RetryLaterError
+	if errors.As(b, &rb) && (!errors.As(a, &ra) || rb.RetryIn > ra.RetryIn) {
+		return b
+	}
+	return a
+}
+
+// fetchArtistImage tries each enabled artist-image agent in order. The error is non-nil only when no
 // agent succeeded and at least one failed transiently.
-func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar model.Artist) (r io.ReadCloser, agentName string, extErr bool) {
+func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar model.Artist) (io.ReadCloser, string, error) {
 	// Synthetic artists would otherwise get an unrelated agent result assigned to them.
 	switch ar.ID {
 	case consts.UnknownArtistID, consts.VariousArtistsID:
 		traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped, Detail: "synthetic artist"})
-		return nil, "", false
+		return nil, "", nil
 	}
 	name := externalName(ar.Name)
 	imageAgents := ag.ArtistImageAgents()
 	if len(imageAgents) == 0 {
 		traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped,
 			Detail: "no enabled agent provides artist images"})
-		return nil, "", false
+		return nil, "", nil
 	}
+	var extErr error
 	for _, a := range imageAgents {
 		reader, path, err := gate(a.Name, func() (io.ReadCloser, string, error) {
 			imgs, err := a.Retriever.GetArtistImages(ctx, ar.ID, name, ar.MbzArtistID)
@@ -71,10 +86,10 @@ func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar
 		})
 		recordAgent(ctx, a.Name, reader, path, err)
 		if reader != nil {
-			return reader, a.Name, false
+			return reader, a.Name, nil
 		}
 		if isTransientExternal(err) {
-			extErr = true
+			extErr = longerRetry(extErr, err)
 			log.Debug(ctx, "Artwork: External artist-image lookup failed", "agent", a.Name, "artist", ar.Name, err)
 		}
 	}
@@ -82,14 +97,15 @@ func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar
 }
 
 // fetchAlbumImage is the album counterpart of fetchArtistImage.
-func fetchAlbumImage(ctx context.Context, ag *agents.Agents, gate gateFunc, al model.Album) (r io.ReadCloser, agentName string, extErr bool) {
+func fetchAlbumImage(ctx context.Context, ag *agents.Agents, gate gateFunc, al model.Album) (io.ReadCloser, string, error) {
 	name, artist := externalName(al.Name), externalName(al.AlbumArtist)
 	imageAgents := ag.AlbumImageAgents()
 	if len(imageAgents) == 0 {
 		traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped,
 			Detail: "no enabled agent provides album images"})
-		return nil, "", false
+		return nil, "", nil
 	}
+	var extErr error
 	for _, a := range imageAgents {
 		reader, path, err := gate(a.Name, func() (io.ReadCloser, string, error) {
 			imgs, err := a.Retriever.GetAlbumImages(ctx, name, artist, al.MbzAlbumID)
@@ -104,10 +120,10 @@ func fetchAlbumImage(ctx context.Context, ag *agents.Agents, gate gateFunc, al m
 		})
 		recordAgent(ctx, a.Name, reader, path, err)
 		if reader != nil {
-			return reader, a.Name, false
+			return reader, a.Name, nil
 		}
 		if isTransientExternal(err) {
-			extErr = true
+			extErr = longerRetry(extErr, err)
 			log.Debug(ctx, "Artwork: External album-image lookup failed", "agent", a.Name, "album", al.Name, err)
 		}
 	}
diff --git a/core/artwork/agent_images_test.go b/core/artwork/agent_images_test.go
index 60a34352d..d0c2429b0 100644
--- a/core/artwork/agent_images_test.go
+++ b/core/artwork/agent_images_test.go
@@ -2,11 +2,13 @@ package artwork
 
 import (
 	"context"
+	"errors"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"sync"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -153,11 +155,11 @@ var _ = Describe("agent images", func() {
 			a := &fakeImageAgent{name: "agentA", imgs: []agents.ExternalImage{img("/a", 100)}}
 			ag := imageAgents(a)
 
-			r, name, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1", Name: "Artist"})
+			r, name, err := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1", Name: "Artist"})
 			Expect(r).ToNot(BeNil())
 			defer r.Close()
 			Expect(name).To(Equal("agentA"))
-			Expect(extErr).To(BeFalse())
+			Expect(err).ToNot(HaveOccurred())
 		})
 
 		It("skips the external lookup for synthetic artists", func() {
@@ -165,10 +167,10 @@ var _ = Describe("agent images", func() {
 			ag := imageAgents(a)
 
 			for _, id := range []string{consts.UnknownArtistID, consts.VariousArtistsID} {
-				r, name, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: id, Name: "Various Artists"})
+				r, name, err := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: id, Name: "Various Artists"})
 				Expect(r).To(BeNil())
 				Expect(name).To(BeEmpty())
-				Expect(extErr).To(BeFalse())
+				Expect(err).ToNot(HaveOccurred())
 			}
 			Expect(a.artistCalls).To(Equal(0), "synthetic artists never reach the agents")
 		})
@@ -177,9 +179,9 @@ var _ = Describe("agent images", func() {
 			ag := imageAgents()
 			t := &ChainTrace{}
 
-			r, _, extErr := fetchArtistImage(withTrace(ctx, t), ag, passthroughGate, model.Artist{ID: "ar1"})
+			r, _, err := fetchArtistImage(withTrace(ctx, t), ag, passthroughGate, model.Artist{ID: "ar1"})
 			Expect(r).To(BeNil())
-			Expect(extErr).To(BeFalse())
+			Expect(err).ToNot(HaveOccurred())
 			Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "external", Outcome: OutcomeSkipped,
 				Detail: "no enabled agent provides artist images"}}),
 				"a configured external token must never be silently absent from the chain")
@@ -211,11 +213,11 @@ var _ = Describe("agent images", func() {
 			b := &fakeImageAgent{name: "agentB", imgs: []agents.ExternalImage{img("/b", 50)}}
 			ag := imageAgents(a, b)
 
-			r, name, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
+			r, name, err := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
 			Expect(r).ToNot(BeNil())
 			defer r.Close()
 			Expect(name).To(Equal("agentB"))
-			Expect(extErr).To(BeFalse(), "a later hit clears an earlier agent's error")
+			Expect(err).ToNot(HaveOccurred(), "a later hit clears an earlier agent's error")
 			Expect(a.artistCalls).To(Equal(1))
 			Expect(b.artistCalls).To(Equal(1))
 		})
@@ -225,20 +227,43 @@ var _ = Describe("agent images", func() {
 			b := &fakeImageAgent{name: "agentB", err: agents.ErrNotFound}
 			ag := imageAgents(a, b)
 
-			r, name, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
+			r, name, err := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
 			Expect(r).To(BeNil())
 			Expect(name).To(BeEmpty())
-			Expect(extErr).To(BeFalse(), "not-found is definitive, never a transient failure")
+			Expect(err).ToNot(HaveOccurred(), "not-found is definitive, never a transient failure")
 		})
 
-		It("reports extErr when one agent fails transiently and the rest find nothing", func() {
+		It("reports an error when one agent fails transiently and the rest find nothing", func() {
 			a := &fakeImageAgent{name: "agentA", err: agents.ErrNotFound}
 			b := &fakeImageAgent{name: "agentB", err: context.DeadlineExceeded}
 			ag := imageAgents(a, b)
 
-			r, _, extErr := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
+			r, _, err := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
 			Expect(r).To(BeNil())
-			Expect(extErr).To(BeTrue())
+			Expect(err).To(HaveOccurred())
+		})
+
+		// The worker reschedules on this delay, so it is only honored if the agent loop
+		// returns it. Two throttled agents: the longest wait is the one that must survive.
+		It("returns the longest retry delay the providers asked for", func() {
+			a := &fakeImageAgent{name: "agentA", err: &agents.RetryLaterError{RetryIn: 10 * time.Second}}
+			b := &fakeImageAgent{name: "agentB", err: &agents.RetryLaterError{RetryIn: 5 * time.Second}}
+			ag := imageAgents(a, b)
+
+			r, _, err := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
+			Expect(r).To(BeNil())
+			retry, ok := errors.AsType[*agents.RetryLaterError](err)
+			Expect(ok).To(BeTrue())
+			Expect(retry.RetryIn).To(Equal(10 * time.Second))
+		})
+
+		It("returns no delay when the provider did not ask for one", func() {
+			ag := imageAgents(&fakeImageAgent{name: "agentA", err: errors.New("boom")})
+
+			_, _, err := fetchArtistImage(ctx, ag, passthroughGate, model.Artist{ID: "ar1"})
+			Expect(err).To(HaveOccurred())
+			_, ok := errors.AsType[*agents.RetryLaterError](err)
+			Expect(ok).To(BeFalse(), "a plain failure must not look like a throttle")
 		})
 	})
 
@@ -247,11 +272,11 @@ var _ = Describe("agent images", func() {
 			a := &fakeImageAgent{name: "agentA", imgs: []agents.ExternalImage{img("/a", 100)}}
 			ag := imageAgents(a)
 
-			r, name, extErr := fetchAlbumImage(ctx, ag, passthroughGate, model.Album{Name: "Album", AlbumArtist: "Artist"})
+			r, name, err := fetchAlbumImage(ctx, ag, passthroughGate, model.Album{Name: "Album", AlbumArtist: "Artist"})
 			Expect(r).ToNot(BeNil())
 			defer r.Close()
 			Expect(name).To(Equal("agentA"))
-			Expect(extErr).To(BeFalse())
+			Expect(err).ToNot(HaveOccurred())
 			Expect(a.albumCalls).To(Equal(1))
 		})
 
@@ -259,21 +284,21 @@ var _ = Describe("agent images", func() {
 			ag := imageAgents()
 			t := &ChainTrace{}
 
-			r, _, extErr := fetchAlbumImage(withTrace(ctx, t), ag, passthroughGate, model.Album{Name: "Album"})
+			r, _, err := fetchAlbumImage(withTrace(ctx, t), ag, passthroughGate, model.Album{Name: "Album"})
 			Expect(r).To(BeNil())
-			Expect(extErr).To(BeFalse())
+			Expect(err).ToNot(HaveOccurred())
 			Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "external", Outcome: OutcomeSkipped,
 				Detail: "no enabled agent provides album images"}}),
 				"a configured external token must never be silently absent from the chain")
 		})
 
-		It("reports extErr when the only agent fails transiently", func() {
+		It("reports an error when the only agent fails transiently", func() {
 			a := &fakeImageAgent{name: "agentA", err: context.DeadlineExceeded}
 			ag := imageAgents(a)
 
-			r, _, extErr := fetchAlbumImage(ctx, ag, passthroughGate, model.Album{Name: "Album"})
+			r, _, err := fetchAlbumImage(ctx, ag, passthroughGate, model.Album{Name: "Album"})
 			Expect(r).To(BeNil())
-			Expect(extErr).To(BeTrue())
+			Expect(err).To(HaveOccurred())
 		})
 	})
 
diff --git a/core/artwork/processor.go b/core/artwork/processor.go
index fdb28189a..cf2176775 100644
--- a/core/artwork/processor.go
+++ b/core/artwork/processor.go
@@ -16,6 +16,7 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/artwork/blurhash"
 	"github.com/navidrome/navidrome/core/artwork/dominant"
 	"github.com/navidrome/navidrome/core/artwork/thumbhash"
@@ -80,7 +81,7 @@ type processor struct {
 
 // acquire resolves one queue item end to end: find an image, hash/decode/
 // blurhash it, place its bytes, and persist the resulting state.
-func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (out outcome, got *acquired) {
+func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (out outcome, got *acquired, retryIn time.Duration) {
 	repo := p.ds.Artwork(ctx)
 	start := time.Now()
 	defer func() {
@@ -92,10 +93,13 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 	if err != nil {
 		traceStage(ctx, "resolve", err)
 		log.Warn(ctx, "Artwork: Could not resolve item", "kind", item.ItemKind, "id", item.ItemID, err)
-		return outcomeFailed, nil
+		return outcomeFailed, nil, 0
+	}
+	if retry, ok := errors.AsType[*agents.RetryLaterError](res.extErr); ok {
+		retryIn = retry.RetryIn
 	}
 	if res.reader == nil {
-		if res.extError || res.localError {
+		if res.extErr != nil || res.localError {
 			// A fault is not a definitive "no image": never settle absent, keep serving old state.
 			// A chainless resolver (playlist/radio) records no step, so leave a fallback or explain is blank.
 			if t := traceFrom(ctx); len(t.Steps()) == 0 {
@@ -106,10 +110,10 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 				t.add(TraceStep{Candidate: cmp.Or(res.source, "source"), Outcome: outcome})
 			}
 			log.Debug(ctx, "Artwork: No image, but a source faulted; keeping previous state",
-				"kind", item.ItemKind, "id", item.ItemID, "extError", res.extError, "localError", res.localError)
-			return outcomeFailed, nil
+				"kind", item.ItemKind, "id", item.ItemID, "extErr", res.extErr, "localError", res.localError)
+			return outcomeFailed, nil, retryIn
 		}
-		return writeAbsent(ctx, repo, item), nil
+		return writeAbsent(ctx, repo, item), nil, 0
 	}
 	defer res.reader.Close()
 
@@ -118,7 +122,7 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 	if err != nil {
 		traceStage(ctx, "read", err)
 		log.Warn(ctx, "Artwork: Failed to read resolved image", "kind", item.ItemKind, "id", item.ItemID, "source", res.source, err)
-		return outcomeFailed, nil
+		return outcomeFailed, nil, retryIn
 	}
 	log.Debug(ctx, "Artwork: Read resolved image", "kind", item.ItemKind, "id", item.ItemID,
 		"source", res.source, "bytes", len(data), "elapsed", time.Since(readStart))
@@ -128,7 +132,7 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 	if err != nil {
 		traceStage(ctx, "hash", err)
 		log.Warn(ctx, "Artwork: Failed to hash image", "kind", item.ItemKind, "id", item.ItemID, err)
-		return outcomeFailed, nil
+		return outcomeFailed, nil, retryIn
 	}
 	log.Trace(ctx, "Artwork: Hashed image", "kind", item.ItemKind, "id", item.ItemID,
 		"hash", hash, "bytes", len(data), "elapsed", time.Since(hashStart))
@@ -152,14 +156,14 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 		if err != nil {
 			traceStage(ctx, "decode", err)
 			log.Warn(ctx, "Artwork: Failed to decode resolved image", "kind", item.ItemKind, "id", item.ItemID, err)
-			return outcomeFailed, nil
+			return outcomeFailed, nil, retryIn
 		}
 		log.Debug(ctx, "Artwork: Decoded new image", "kind", item.ItemKind, "id", item.ItemID, "hash", hash,
 			"width", art.Width, "height", art.Height, "mime", art.Mime, "elapsed", time.Since(decodeStart))
 	default:
 		traceStage(ctx, "lookup", err)
 		log.Warn(ctx, "Artwork: Failed to look up image hash", "kind", item.ItemKind, "id", item.ItemID, err)
-		return outcomeFailed, nil
+		return outcomeFailed, nil, retryIn
 	}
 	art.SizeBytes = int64(len(data))
 
@@ -167,15 +171,15 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 	if err != nil {
 		traceStage(ctx, "store", err)
 		log.Warn(ctx, "Artwork: Failed to persist resolved image", "kind", item.ItemKind, "id", item.ItemID, err)
-		return outcomeFailed, nil
+		return outcomeFailed, nil, retryIn
 	}
 	got = &acquired{ia: ia, mime: art.Mime, data: data}
-	if res.extError {
+	if res.extErr != nil {
 		log.Debug(ctx, "Artwork: Serving a lower-priority source after an external failure",
 			"kind", item.ItemKind, "id", item.ItemID, "source", res.source)
-		return outcomeFoundStale, got
+		return outcomeFoundStale, got, retryIn
 	}
-	return outcomeFound, got
+	return outcomeFound, got, retryIn
 }
 
 // persist places the bytes and commits the rows referencing them, excluding Prune for that
diff --git a/core/artwork/processor_test.go b/core/artwork/processor_test.go
index 0ca5a308e..554ca08dc 100644
--- a/core/artwork/processor_test.go
+++ b/core/artwork/processor_test.go
@@ -90,7 +90,7 @@ var _ = Describe("processor.acquire", func() {
 			{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}},
 		})
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"})
 		Expect(out).To(Equal(outcomeFound))
 
 		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
@@ -127,7 +127,7 @@ var _ = Describe("processor.acquire", func() {
 				{ID: "alL1", Name: "Album", FolderIDs: []string{"f1"}},
 			})
 
-			out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alL1"})
+			out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alL1"})
 			Expect(out).To(Equal(outcomeFound))
 			Expect(lock.locks).To(BeNumerically(">", 0), "the write window must exclude prune")
 			Expect(lock.held()).To(BeFalse(), "the window must close before acquire returns")
@@ -141,7 +141,7 @@ var _ = Describe("processor.acquire", func() {
 				{ID: "alL2", Name: "Album", FolderIDs: []string{"f1"}},
 			})
 
-			out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alL2"})
+			out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alL2"})
 			Expect(out).To(Equal(outcomeAbsent))
 			Expect(lock.locks).To(BeZero())
 		})
@@ -153,7 +153,7 @@ var _ = Describe("processor.acquire", func() {
 		})
 		folderRepo.result = nil
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"})
 		Expect(out).To(Equal(outcomeFound))
 
 		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al2", model.ImageTypePrimary)
@@ -176,7 +176,7 @@ var _ = Describe("processor.acquire", func() {
 			{ID: "al3", Name: "Album"},
 		})
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"})
 		Expect(out).To(Equal(outcomeAbsent))
 
 		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
@@ -197,7 +197,7 @@ var _ = Describe("processor.acquire", func() {
 			{ID: "al-io", Name: "Album", FolderIDs: []string{"f1"}},
 		})
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al-io"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al-io"})
 		Expect(out).To(Equal(outcomeFailed))
 
 		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al-io", model.ImageTypePrimary)
@@ -222,7 +222,7 @@ var _ = Describe("processor.acquire", func() {
 		DeferCleanup(func() { _ = os.Chmod(upload, 0o600) })
 		radioRepo.Data["ra-io"] = &model.Radio{ID: "ra-io", Name: "Station", UploadedImage: "ra-io.jpg"}
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra-io"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra-io"})
 		Expect(out).To(Equal(outcomeFailed))
 
 		_, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra-io", model.ImageTypePrimary)
@@ -249,7 +249,7 @@ var _ = Describe("processor.acquire", func() {
 		radioRepo.Data["ra-tr"] = &model.Radio{ID: "ra-tr", Name: "Station", UploadedImage: "ra-tr.jpg"}
 
 		trace := &ChainTrace{}
-		out, _ := proc.acquire(withTrace(ctx, trace), model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra-tr"})
+		out, _, _ := proc.acquire(withTrace(ctx, trace), model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra-tr"})
 		Expect(out).To(Equal(outcomeFailed))
 
 		steps := trace.Steps()
@@ -265,13 +265,26 @@ var _ = Describe("processor.acquire", func() {
 		})
 		imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})
+		out, _, retryIn := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})
 		Expect(out).To(Equal(outcomeFailed))
+		Expect(retryIn).To(BeZero(), "a plain failure asks for no particular delay")
 
 		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al4", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
+	It("failed-on-extError: reports the delay a throttled provider asked for", func() {
+		conf.Server.CoverArtPriority = "external"
+		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+			{ID: "al4r", Name: "Album"},
+		})
+		imageAgents(&fakeImageAgent{name: "throttled", err: &agents.RetryLaterError{RetryIn: 42 * time.Second}})
+
+		out, _, retryIn := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4r"})
+		Expect(out).To(Equal(outcomeFailed))
+		Expect(retryIn).To(Equal(42 * time.Second))
+	})
+
 	It("found-stale: a fallback hit after a transient external failure persists state and returns outcomeFoundStale", func() {
 		conf.Server.CoverArtPriority = "external, cover.jpg"
 		folderRepo.result = []model.Folder{{
@@ -283,7 +296,7 @@ var _ = Describe("processor.acquire", func() {
 		})
 		imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alstale"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alstale"})
 		Expect(out).To(Equal(outcomeFoundStale))
 
 		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alstale", model.ImageTypePrimary)
@@ -300,7 +313,7 @@ var _ = Describe("processor.acquire", func() {
 		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alU", Name: "Album", FolderIDs: []string{"f1"}}})
 		folderRepo.result = []model.Folder{{Path: "album", ImageFiles: []string{"cover.jpg"}}}
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alU"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alU"})
 		Expect(out).To(Equal(outcomeFound))
 
 		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alU", model.ImageTypePrimary)
@@ -320,7 +333,7 @@ var _ = Describe("processor.acquire", func() {
 		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alE", Name: "Album", FolderIDs: []string{"f1"}}})
 		folderRepo.result = []model.Folder{{Path: "album", ImageFiles: []string{"cover.jpg"}}}
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alE"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alE"})
 		Expect(out).To(Equal(outcomeFailed))
 
 		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alE", model.ImageTypePrimary)
@@ -338,7 +351,7 @@ var _ = Describe("processor.acquire", func() {
 		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alX", Name: "Album"}})
 		imageAgents(&fakeImageAgent{name: "deezerFake", imgs: []agents.ExternalImage{{URL: srv.URL, Size: 500}}})
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alX"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alX"})
 		Expect(out).To(Equal(outcomeFailed))
 
 		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alX", model.ImageTypePrimary)
@@ -357,7 +370,7 @@ var _ = Describe("processor.acquire", func() {
 		ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alext", Name: "Album"}})
 		imageAgents(&fakeImageAgent{name: "deezerFake", imgs: []agents.ExternalImage{{URL: srv.URL, Size: 500}}})
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alext"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alext"})
 		Expect(out).To(Equal(outcomeFound))
 
 		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alext", model.ImageTypePrimary)
@@ -382,7 +395,7 @@ var _ = Describe("processor.acquire", func() {
 			{ID: "al6", Name: "Album B", FolderIDs: []string{"f1"}},
 		})
 
-		out1, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al5"})
+		out1, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al5"})
 		Expect(out1).To(Equal(outcomeFound))
 		ia1, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al5", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
@@ -392,7 +405,7 @@ var _ = Describe("processor.acquire", func() {
 		poisoned.BlurHash = "SENTINEL"
 		artRepo.Data[ia1.Hash] = poisoned
 
-		out2, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al6"})
+		out2, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al6"})
 		Expect(out2).To(Equal(outcomeFound))
 		ia2, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al6", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
@@ -422,7 +435,7 @@ var _ = Describe("processor.acquire", func() {
 		})
 
 		folderRepo.result = []model.Folder{{Path: "album-a", ImageFiles: []string{"cover.jpg"}}}
-		outN, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alA"})
+		outN, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alA"})
 		Expect(outN).To(Equal(outcomeFound))
 		iaA, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alA", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
@@ -436,7 +449,7 @@ var _ = Describe("processor.acquire", func() {
 		artRepo.Data[iaA.Hash] = poisoned
 
 		folderRepo.result = []model.Folder{{Path: "album-b", ImageFiles: []string{"cover.jpg"}}}
-		outN, _ = proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alB"})
+		outN, _, _ = proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alB"})
 		Expect(outN).To(Equal(outcomeFound))
 		iaB, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alB", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
@@ -467,7 +480,7 @@ var _ = Describe("processor.acquire", func() {
 		radioRepo.Data = map[string]*model.Radio{"ra1": {ID: "ra1", Name: "Radio", UploadedImage: "ra1_test.jpg"}}
 		ds.MockedRadio = radioRepo
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra1"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra1"})
 		Expect(out).To(Equal(outcomeFailed))
 
 		_, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
@@ -488,7 +501,7 @@ var _ = Describe("processor.acquire", func() {
 		radioRepo.Data = map[string]*model.Radio{"big": {ID: "big", Name: "Radio", UploadedImage: "big_test.jpg"}}
 		ds.MockedRadio = radioRepo
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "big"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "big"})
 		Expect(out).To(Equal(outcomeFailed))
 
 		_, err = artRepo.GetItemArtwork(model.KindRadioArtwork, "big", model.ImageTypePrimary)
@@ -554,7 +567,7 @@ var _ = Describe("processor.acquire", func() {
 		Expect(err).ToNot(HaveOccurred())
 		Expect(artRepo.PutImage(&model.Artwork{Hash: hash, Mime: "application/octet-stream"})).To(Succeed())
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alM"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alM"})
 		Expect(out).To(Equal(outcomeFound))
 
 		upgraded, err := artRepo.GetImage(hash)
@@ -574,7 +587,7 @@ var _ = Describe("processor.acquire", func() {
 		Expect(os.WriteFile(blockedRoot, []byte("x"), 0600)).To(Succeed())
 		proc.store = NewImageStore(blockedRoot)
 
-		out, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al7"})
+		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al7"})
 		Expect(out).To(Equal(outcomeFailed))
 
 		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al7", model.ImageTypePrimary)
diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
index 6663679fa..e7a2d3765 100644
--- a/core/artwork/resolve.go
+++ b/core/artwork/resolve.go
@@ -25,9 +25,9 @@ type resolution struct {
 	source     string        // model.ItemArtwork.Source value: "folder", "embedded", "external", "upload", "generated"
 	sourcePath string        // backing library/upload file (folder/upload: the image; embedded: the audio file); "" otherwise
 	refMtime   int64         // sourcePath mtime (unix-nanoseconds) at resolution; 0 when no sourcePath
-	// external source errored/timed out. With no reader it forces failed (never absent);
-	// on a hit a higher-priority external step failed—serve this, but retry later.
-	extError bool
+	// a faulted external source, carrying the provider's requested delay when it named one.
+	// With no reader it forces failed (never absent); on a hit, serve this but retry later.
+	extErr error
 	// a local source that should have been readable wasn't. With no reader it forces failed,
 	// so a transient I/O fault never records absent.
 	localError bool
@@ -36,14 +36,15 @@ type resolution struct {
 // chainState carries what a priority walk has seen so far. A hit takes extErr with it so a
 // transient external failure still retries; localErr is dropped, as the scanner re-lists changes.
 type chainState struct {
-	extErr, localErr bool
-	trace            *ChainTrace // nil only where no caller attached one
+	extErr   error
+	localErr bool
+	trace    *ChainTrace // nil only where no caller attached one
 }
 
 // try stamps the accumulated external failure onto a hit, and records the miss otherwise.
 func (c *chainState) try(candidate string, res resolution, ok bool) (resolution, bool) {
 	if ok {
-		res.extError = c.extErr
+		res.extErr = c.extErr
 		c.record(candidate, OutcomeHit, res.sourcePath)
 		return res, true
 	}
@@ -62,7 +63,7 @@ func (c *chainState) record(candidate string, out Outcome, detail string) {
 
 // exhausted is the outcome when no source in the chain yielded an image.
 func (c *chainState) exhausted() resolution {
-	return resolution{extError: c.extErr, localError: c.localErr}
+	return resolution{extErr: c.extErr, localError: c.localErr}
 }
 
 // externalSource holds the agents to ask and the rate limiter/circuit breaker to ask them through.
@@ -181,16 +182,16 @@ func chainFetchesExternal(priority string) bool {
 
 // Album and artist fetches stop here when the resolver is local-only, rather than at each point in
 // the chain walk; resolvePlaylist gates the third network path, the m3u image URL, itself.
-func (r *resolver) fetchExternalAlbum(ctx context.Context, al model.Album) (io.ReadCloser, string, bool) {
+func (r *resolver) fetchExternalAlbum(ctx context.Context, al model.Album) (io.ReadCloser, string, error) {
 	if r.ext == nil {
-		return nil, "", false
+		return nil, "", nil
 	}
 	return fetchAlbumImage(ctx, r.ext.agents, r.ext.gate, al)
 }
 
-func (r *resolver) fetchExternalArtist(ctx context.Context, ar model.Artist) (io.ReadCloser, string, bool) {
+func (r *resolver) fetchExternalArtist(ctx context.Context, ar model.Artist) (io.ReadCloser, string, error) {
 	if r.ext == nil {
-		return nil, "", false
+		return nil, "", nil
 	}
 	return fetchArtistImage(ctx, r.ext.agents, r.ext.gate, ar)
 }
@@ -223,10 +224,10 @@ func (r *resolver) resolveAlbum(ctx context.Context, albumID string) (resolution
 				return res, nil
 			}
 		case pattern == externalCandidate:
-			if rd, name, isErr := r.fetchExternalAlbum(ctx, *al); rd != nil {
+			if rd, name, err := r.fetchExternalAlbum(ctx, *al); rd != nil {
 				return resolution{reader: rd, source: ExternalPrefix + name}, nil
-			} else if isErr {
-				chain.extErr = true
+			} else if err != nil {
+				chain.extErr = longerRetry(chain.extErr, err)
 			}
 		case len(imgFiles) > 0:
 			res, ok := resolveFolderFile(ctx, lib, imgFiles, pattern)
@@ -285,10 +286,10 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resoluti
 		}
 		switch {
 		case pattern == externalCandidate:
-			if rd, name, isErr := r.fetchExternalArtist(ctx, *ar); rd != nil {
+			if rd, name, err := r.fetchExternalArtist(ctx, *ar); rd != nil {
 				return resolution{reader: rd, source: ExternalPrefix + name}, nil
-			} else if isErr {
-				chain.extErr = true
+			} else if err != nil {
+				chain.extErr = longerRetry(chain.extErr, err)
 			}
 		case pattern == "image-folder":
 			res, ok := resolveArtistImageFolder(ar)
@@ -332,7 +333,7 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 		return resolution{}, err
 	}
 
-	var extErr bool
+	var extErr error
 	for _, src := range []struct{ path, source string }{
 		{pl.UploadedImagePath(), "upload"},
 		{findPlaylistSidecarPath(ctx, pl.Path), "folder"},
@@ -366,7 +367,7 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 		if res, ok, err := resolveExternalStep(r.ext.gate, "m3u", sf); ok {
 			return res, nil
 		} else if err != nil {
-			extErr = true
+			extErr = longerRetry(extErr, err)
 			// Record it here with its detail: once album sampling adds its own steps, the processor's
 			// empty-trace fallback no longer fires, and the error that forced the retry would be lost.
 			traceFrom(ctx).add(TraceStep{Candidate: ExternalPrefix + "m3u", Outcome: OutcomeError, Detail: err.Error()})
@@ -389,8 +390,8 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 			}
 			continue
 		}
-		if res.extError {
-			extErr = true
+		if res.extErr != nil {
+			extErr = longerRetry(extErr, res.extErr)
 		}
 		if res.reader == nil {
 			continue
@@ -409,7 +410,7 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 		if tileErr != nil {
 			return resolution{}, fmt.Errorf("resolvePlaylist: sampled album art failed: %w", tileErr)
 		}
-		return resolution{extError: extErr}, nil
+		return resolution{extErr: extErr}, nil
 	}
 	// Grow to 4 tiles by repeating what we have.
 	switch len(tiles) {
@@ -420,9 +421,9 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 	}
 	grid, err := assembleTiles(tiles)
 	if err != nil {
-		return resolution{extError: extErr}, nil //nolint:nilerr // encode failure is a soft "no image", not a resolution error
+		return resolution{extErr: extErr}, nil //nolint:nilerr // encode failure is a soft "no image", not a resolution error
 	}
-	return resolution{reader: grid, source: "generated", extError: extErr}, nil
+	return resolution{reader: grid, source: "generated", extErr: extErr}, nil
 }
 
 // resolveRadio serves only an uploaded image; there is no fallback.
diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.go
index 236e76b9b..402a11363 100644
--- a/core/artwork/resolve_test.go
+++ b/core/artwork/resolve_test.go
@@ -100,7 +100,7 @@ var _ = Describe("resolveItem", func() {
 			Expect(res.source).To(Equal("embedded"))
 			Expect(filepath.ToSlash(res.sourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/test.mp3"))
 			Expect(res.refMtime).To(BeNumerically(">", 0))
-			Expect(res.extError).To(BeFalse())
+			Expect(res.extErr).ToNot(HaveOccurred())
 		})
 
 		It("resolves absent when the track has no cover art", func() {
@@ -111,7 +111,7 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mf2"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeFalse())
+			Expect(res.extErr).ToNot(HaveOccurred())
 		})
 
 		It("resolves absent when media file cover art is disabled", func() {
@@ -154,7 +154,7 @@ var _ = Describe("resolveItem", func() {
 			Expect(res.source).To(Equal("folder"))
 			Expect(filepath.ToSlash(res.sourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/cover.jpg"))
 			Expect(res.refMtime).To(BeNumerically(">", 0))
-			Expect(res.extError).To(BeFalse())
+			Expect(res.extErr).ToNot(HaveOccurred())
 		})
 
 		It("falls back to embedded art when no folder image matches", func() {
@@ -172,7 +172,7 @@ var _ = Describe("resolveItem", func() {
 			Expect(res.refMtime).To(BeNumerically(">", 0))
 		})
 
-		It("sets extError when the external source errors without being not-found", func() {
+		It("sets extErr when the external source errors without being not-found", func() {
 			conf.Server.CoverArtPriority = "external"
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "al3", Name: "Album"},
@@ -182,10 +182,10 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeTrue())
+			Expect(res.extErr).To(HaveOccurred())
 		})
 
-		It("does not set extError when the external source reports not-found", func() {
+		It("does not set extErr when the external source reports not-found", func() {
 			conf.Server.CoverArtPriority = "external"
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "al4", Name: "Album"},
@@ -195,10 +195,10 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeFalse())
+			Expect(res.extErr).ToNot(HaveOccurred())
 		})
 
-		It("carries extError onto a fallback folder hit after a transient external failure", func() {
+		It("carries extErr onto a fallback folder hit after a transient external failure", func() {
 			conf.Server.CoverArtPriority = "external, cover.jpg"
 			folderRepo.result = []model.Folder{{
 				Path:       "tests/fixtures/artist/an-album",
@@ -214,10 +214,10 @@ var _ = Describe("resolveItem", func() {
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
 			Expect(res.source).To(Equal("folder"))
-			Expect(res.extError).To(BeTrue())
+			Expect(res.extErr).To(HaveOccurred())
 		})
 
-		It("does not carry extError onto a fallback folder hit after a definitive external not-found", func() {
+		It("does not carry extErr onto a fallback folder hit after a definitive external not-found", func() {
 			conf.Server.CoverArtPriority = "external, cover.jpg"
 			folderRepo.result = []model.Folder{{
 				Path:       "tests/fixtures/artist/an-album",
@@ -233,7 +233,7 @@ var _ = Describe("resolveItem", func() {
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
 			Expect(res.source).To(Equal("folder"))
-			Expect(res.extError).To(BeFalse())
+			Expect(res.extErr).ToNot(HaveOccurred())
 		})
 
 		It("routes the external step through the injected gate, keyed by agent name", func() {
@@ -250,7 +250,7 @@ var _ = Describe("resolveItem", func() {
 
 			res, err := newResolver(ds, ag, ffm, gate).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al5"})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.extError).To(BeTrue())
+			Expect(res.extErr).To(HaveOccurred())
 			Expect(gatedNames).To(Equal([]string{"failAgent"}))
 		})
 	})
@@ -298,7 +298,7 @@ var _ = Describe("resolveItem", func() {
 			Expect(filepath.ToSlash(res.sourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/artist.png"))
 		})
 
-		It("sets extError when the external source errors without being not-found", func() {
+		It("sets extErr when the external source errors without being not-found", func() {
 			conf.Server.ArtistArtPriority = "external"
 			artistRepo := tests.CreateMockArtistRepo()
 			artistRepo.SetData(model.Artists{{ID: "ar3", Name: "Artist"}})
@@ -308,10 +308,10 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeTrue())
+			Expect(res.extErr).To(HaveOccurred())
 		})
 
-		It("does not set extError when the external source reports not-found", func() {
+		It("does not set extErr when the external source reports not-found", func() {
 			conf.Server.ArtistArtPriority = "external"
 			artistRepo := tests.CreateMockArtistRepo()
 			artistRepo.SetData(model.Artists{{ID: "ar4", Name: "Artist"}})
@@ -321,7 +321,7 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar4"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeFalse())
+			Expect(res.extErr).ToNot(HaveOccurred())
 		})
 
 		It("routes the external step through the injected gate, keyed by agent name", func() {
@@ -338,7 +338,7 @@ var _ = Describe("resolveItem", func() {
 
 			res, err := newResolver(ds, ag, ffm, gate).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar5"})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.extError).To(BeTrue())
+			Expect(res.extErr).To(HaveOccurred())
 			Expect(gatedNames).To(Equal([]string{"failAgent"}))
 		})
 	})
@@ -516,7 +516,7 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, gate).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "ple"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeTrue())
+			Expect(res.extErr).To(HaveOccurred())
 			Expect(gatedNames).To(Equal([]string{"m3u"}), "the playlist URL fetch is gated under \"m3u\"")
 		})
 
@@ -537,7 +537,7 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, gate).resolve(withTrace(ctx, trace),
 				model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plm3u"})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.extError).To(BeTrue())
+			Expect(res.extErr).To(HaveOccurred())
 
 			steps := trace.Steps()
 			var m3u *TraceStep
@@ -562,7 +562,7 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plm"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeFalse())
+			Expect(res.extErr).ToNot(HaveOccurred())
 		})
 
 		It("treats an ExternalImageURL 404 as a definitive miss and falls through to the grid", func() {
@@ -582,7 +582,7 @@ var _ = Describe("resolveItem", func() {
 			Expect(res.reader).ToNot(BeNil())
 			defer res.reader.Close()
 			Expect(res.source).To(Equal("generated"))
-			Expect(res.extError).To(BeFalse())
+			Expect(res.extErr).ToNot(HaveOccurred())
 		})
 
 		// A local resolver holds no agents: reaching the external branch would panic, not degrade.
@@ -594,7 +594,7 @@ var _ = Describe("resolveItem", func() {
 			res, err := newLocalResolver(ds, ffm).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alx"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeFalse(), "a skipped step is not a failed one")
+			Expect(res.extErr).ToNot(HaveOccurred(), "a skipped step is not a failed one")
 		})
 
 		// The worker resolving the same playlist is asserted alongside, so this cannot pass vacuously.
@@ -642,7 +642,7 @@ var _ = Describe("resolveItem", func() {
 			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl500"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.reader).To(BeNil())
-			Expect(res.extError).To(BeTrue())
+			Expect(res.extErr).To(HaveOccurred())
 		})
 
 		It("yields an empty resolution when no album has art", func() {
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index 0358708c0..bea478aa5 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -241,7 +241,7 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 	item.ImageType = cmp.Or(item.ImageType, model.ImageTypePrimary)
 	trace := &ChainTrace{}
 	ctx = withTrace(ctx, trace)
-	out, got := w.proc.acquire(ctx, item)
+	out, got, retryIn := w.proc.acquire(ctx, item)
 
 	queue := w.proc.ds.ArtworkQueue(ctx)
 	switch out {
@@ -252,7 +252,7 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 			log.Warn(ctx, "Artwork: Could not delete processed queue item", "kind", item.ItemKind, "id", item.ItemID, err)
 		}
 	case outcomeFoundStale, outcomeFailed:
-		retryAt := time.Now().Add(backoff(item.Attempts))
+		retryAt := time.Now().Add(retryDelay(item.Attempts, retryIn))
 		encoded := trace.encode("")
 		if retryAt.Before(item.EnqueuedAt.Add(giveUpAfter)) {
 			// A mid-flight re-enqueue reset retry_at; stale backoff must not stomp its
@@ -341,3 +341,8 @@ func backoffFor(attempts int, jitter float64) time.Duration {
 func backoff(attempts int) time.Duration {
 	return backoffFor(attempts, rand.Float64()*0.8-0.4) //nolint:gosec // retry jitter, not security-sensitive
 }
+
+// retryDelay is how long a failed item waits: our backoff, unless the provider asked for longer.
+func retryDelay(attempts int, hint time.Duration) time.Duration {
+	return max(backoff(attempts), hint)
+}
diff --git a/core/artwork/worker_soak_test.go b/core/artwork/worker_soak_test.go
index eb7346102..803cc2dfe 100644
--- a/core/artwork/worker_soak_test.go
+++ b/core/artwork/worker_soak_test.go
@@ -95,7 +95,7 @@ var _ = Describe("Worker soak", func() {
 		start := time.Now()
 		for i := range soakCycles {
 			it := items[i%len(items)]
-			out, _ := proc.acquire(context.Background(), it)
+			out, _, _ := proc.acquire(context.Background(), it)
 
 			// Read-back exercises the surfaces a caller would use after acquisition.
 			if out == outcomeFound {
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index 248e400e1..b0ef665fc 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -245,6 +245,23 @@ var _ = Describe("Worker", func() {
 			Expect(err).To(MatchError(model.ErrNotFound), "a timeout must never settle on absent")
 		})
 
+		It("reschedules past the provider's requested delay when it exceeds the backoff", func() {
+			conf.Server.CoverArtPriority = "external"
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al9", Name: "Album"}})
+			// Well above backoff(0)'s jittered ceiling, so only the hint can produce this retry_at.
+			const askedFor = 90 * time.Minute
+			imageAgents(&fakeImageAgent{name: "throttledAgent", err: &agents.RetryLaterError{RetryIn: askedFor}})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al9"})).To(Succeed())
+
+			n, err := w.drain(ctx, 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(1))
+
+			it := findQueued(queueRepo, "al", "al9")
+			Expect(it).ToNot(BeNil())
+			Expect(it.RetryAt).To(BeTemporally("~", time.Now().Add(askedFor), time.Minute))
+		})
+
 		It("reschedules a found-stale item via MarkFailed while keeping its served state", func() {
 			conf.Server.CoverArtPriority = "external, cover.jpg"
 			folderRepo.result = []model.Folder{{
@@ -911,3 +928,19 @@ var _ = Describe("backoff", func() {
 		}
 	})
 })
+
+var _ = Describe("retryDelay", func() {
+	It("uses the backoff schedule when the provider asked for nothing", func() {
+		d := retryDelay(0, 0)
+		Expect(d).To(BeNumerically(">=", 3*time.Second))
+		Expect(d).To(BeNumerically("<=", 7*time.Second))
+	})
+
+	It("waits the provider's delay when it is longer than the backoff", func() {
+		Expect(retryDelay(0, time.Hour)).To(Equal(time.Hour))
+	})
+
+	It("keeps the backoff when it is longer than the provider's delay", func() {
+		Expect(retryDelay(4, time.Second)).To(BeNumerically(">=", 3*time.Second))
+	})
+})
diff --git a/core/external/provider.go b/core/external/provider.go
index 5c46dc644..3a3f4bd46 100644
--- a/core/external/provider.go
+++ b/core/external/provider.go
@@ -148,7 +148,8 @@ func (e *provider) populateAlbumInfo(ctx context.Context, album auxAlbum) (auxAl
 	start := time.Now()
 	albumName := album.Name()
 	info, err := e.ag.GetAlbumInfo(ctx, albumName, album.AlbumArtist, album.MbzAlbumID)
-	if errors.Is(err, agents.ErrNotFound) {
+	// Throttled joins not-found: no answer to store, and an unstamped timestamp retries next call.
+	if errors.Is(err, agents.ErrNotFound) || errors.Is(err, agents.ErrRetryLater) {
 		return album, nil
 	}
 	if err != nil {
@@ -253,28 +254,37 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 	start := time.Now()
 	// Get MBID first, if it is not yet available
 	artistName := artist.Name()
+	var mbidErr error
 	if artist.MbzArtistID == "" {
 		mbid, err := e.ag.GetArtistMBID(ctx, artist.ID, artistName)
+		mbidErr = err
 		if mbid != "" && err == nil {
 			artist.MbzArtistID = mbid
 		}
 	}
 
-	// Call all registered agents and collect information
+	// Call all registered agents and collect information. The group carries no context, so a
+	// returned error does not cancel the siblings; only throttling is reported back.
 	g := errgroup.Group{}
 	g.SetLimit(2)
-	g.Go(func() error { _ = e.callGetImage(ctx, e.ag, &artist); return nil })
-	g.Go(func() error { e.callGetBiography(ctx, e.ag, &artist); return nil })
-	g.Go(func() error { e.callGetURL(ctx, e.ag, &artist); return nil })
-	g.Go(func() error { e.callGetSimilarArtists(ctx, e.ag, &artist, maxSimilarArtists, true); return nil })
-	_ = g.Wait()
+	g.Go(func() error { return retryLaterOnly(e.callGetImage(ctx, e.ag, &artist)) })
+	g.Go(func() error { return retryLaterOnly(e.callGetBiography(ctx, e.ag, &artist)) })
+	g.Go(func() error { return retryLaterOnly(e.callGetURL(ctx, e.ag, &artist)) })
+	g.Go(func() error {
+		return retryLaterOnly(e.callGetSimilarArtists(ctx, e.ag, &artist, maxSimilarArtists, true))
+	})
+	throttled := errors.Is(g.Wait(), agents.ErrRetryLater) || errors.Is(mbidErr, agents.ErrRetryLater)
 
 	if utils.IsCtxDone(ctx) {
 		log.Warn(ctx, "ArtistInfo update canceled", "id", artist.ID, "name", artistName, "elapsed", time.Since(start), ctx.Err())
 		return artist, ctx.Err()
 	}
 
-	artist.ExternalInfoUpdatedAt = new(time.Now())
+	// A throttled round keeps the previous timestamp, so the next call retries instead of
+	// serving an empty cache entry for the whole TTL.
+	if !throttled {
+		artist.ExternalInfoUpdatedAt = new(time.Now())
+	}
 	err := e.ds.Artist(ctx).UpdateExternalInfo(&artist.Artist)
 	if err != nil {
 		log.Error(ctx, "Error trying to update artist external information", "id", artist.ID, "name", artistName,
@@ -334,8 +344,9 @@ func (e *provider) TopSongs(ctx context.Context, artistName, id string, count in
 	songs, err := e.getMatchingTopSongs(ctx, e.ag, artist, count)
 	if err != nil {
 		switch {
-		case errors.Is(err, agents.ErrNotFound):
-			log.Trace(ctx, "TopSongs not found", "name", artistName)
+		// Throttled is not an answer, but the caller keeps the empty 200 it got before.
+		case errors.Is(err, agents.ErrNotFound), errors.Is(err, agents.ErrRetryLater):
+			log.Trace(ctx, "TopSongs not found", "name", artistName, err)
 			return nil, model.ErrNotFound
 		case errors.Is(err, context.Canceled):
 			log.Debug(ctx, "TopSongs call canceled", err)
@@ -385,22 +396,33 @@ func (e *provider) getMatchingTopSongs(ctx context.Context, agent agents.ArtistT
 	return mfs, nil
 }
 
-func (e *provider) callGetURL(ctx context.Context, agent agents.ArtistURLRetriever, artist *auxArtist) {
-	artisURL, err := agent.GetArtistURL(ctx, artist.ID, artist.Name(), artist.MbzArtistID)
-	if err != nil {
-		return
+// retryLaterOnly discards every failure the caller does not act on, so errgroup's
+// first-error slot is reserved for the throttling signal.
+func retryLaterOnly(err error) error {
+	if errors.Is(err, agents.ErrRetryLater) {
+		return err
 	}
-	artist.ExternalUrl = artisURL
+	return nil
 }
 
-func (e *provider) callGetBiography(ctx context.Context, agent agents.ArtistBiographyRetriever, artist *auxArtist) {
+func (e *provider) callGetURL(ctx context.Context, agent agents.ArtistURLRetriever, artist *auxArtist) error {
+	artisURL, err := agent.GetArtistURL(ctx, artist.ID, artist.Name(), artist.MbzArtistID)
+	if err != nil {
+		return err
+	}
+	artist.ExternalUrl = artisURL
+	return nil
+}
+
+func (e *provider) callGetBiography(ctx context.Context, agent agents.ArtistBiographyRetriever, artist *auxArtist) error {
 	bio, err := agent.GetArtistBiography(ctx, artist.ID, artist.Name(), artist.MbzArtistID)
 	if err != nil {
-		return
+		return err
 	}
 	bio = str.SanitizeText(bio)
 	bio = strings.ReplaceAll(bio, "\n", " ")
 	artist.Biography = strings.ReplaceAll(bio, "<a ", "<a target='_blank' ")
+	return nil
 }
 
 // callGetImage populates artist's image URLs. A transient agent failure is
@@ -428,19 +450,20 @@ func (e *provider) callGetImage(ctx context.Context, agent agents.ArtistImageRet
 }
 
 func (e *provider) callGetSimilarArtists(ctx context.Context, agent agents.ArtistSimilarRetriever, artist *auxArtist,
-	limit int, includeNotPresent bool) {
+	limit int, includeNotPresent bool) error {
 	artistName := artist.Name()
 	similar, err := agent.GetSimilarArtists(ctx, artist.ID, artistName, artist.MbzArtistID, limit)
 	if len(similar) == 0 || err != nil {
-		return
+		return err
 	}
 	start := time.Now()
 	sa, err := e.mapSimilarArtists(ctx, similar, limit, includeNotPresent)
 	log.Debug(ctx, "Mapped Similar Artists", "artist", artistName, "numSimilar", len(sa), "elapsed", time.Since(start))
 	if err != nil {
-		return
+		return err
 	}
 	artist.SimilarArtists = sa
+	return nil
 }
 
 func (e *provider) mapSimilarArtists(ctx context.Context, similar []agents.Artist, limit int, includeNotPresent bool) (model.Artists, error) {
diff --git a/core/external/provider_similarsongs.go b/core/external/provider_similarsongs.go
index 22b20565b..7720c9349 100644
--- a/core/external/provider_similarsongs.go
+++ b/core/external/provider_similarsongs.go
@@ -239,7 +239,7 @@ func (e *provider) similarSongsFallback(ctx context.Context, id string, count in
 		return nil, err
 	}
 
-	e.callGetSimilarArtists(ctx, e.ag, &artist, 15, false)
+	_ = e.callGetSimilarArtists(ctx, e.ag, &artist, 15, false)
 	if utils.IsCtxDone(ctx) {
 		log.Warn(ctx, "SimilarSongs call canceled", ctx.Err())
 		return nil, ctx.Err()
diff --git a/core/external/provider_topsongs_test.go b/core/external/provider_topsongs_test.go
index 16e8ad840..5d35ba914 100644
--- a/core/external/provider_topsongs_test.go
+++ b/core/external/provider_topsongs_test.go
@@ -232,6 +232,21 @@ var _ = Describe("Provider - TopSongs", func() {
 		ag.AssertExpectations(GinkgoT())
 	})
 
+	// This endpoint answered with an empty list before retry-later existed; it must keep doing so.
+	It("returns an empty list, not a client error, when the agents are throttled", func() {
+		artist1 := model.Artist{ID: "artist-1", Name: "Artist One", MbzArtistID: "mbid-artist-1"}
+		artistRepo.On("GetAll", mock.AnythingOfType("model.QueryOptions")).Return(model.Artists{artist1}, nil).Once()
+		ag.On("GetArtistTopSongs", ctx, "artist-1", "Artist One", "mbid-artist-1", 5).
+			Return(nil, agents.ErrRetryLater).Once()
+
+		songs, err := p.TopSongs(ctx, "Artist One", "", 5)
+
+		Expect(songs).To(BeEmpty())
+		Expect(err).To(MatchError(model.ErrNotFound), "the handler renders this as an empty 200")
+		Expect(err).ToNot(MatchError(agents.ErrRetryLater))
+		ag.AssertExpectations(GinkgoT())
+	})
+
 	It("returns fewer songs if count is less than available top songs", func() {
 		// Mock finding the artist
 		artist1 := model.Artist{ID: "artist-1", Name: "Artist One", MbzArtistID: "mbid-artist-1"}
diff --git a/core/external/provider_updatealbuminfo_test.go b/core/external/provider_updatealbuminfo_test.go
index a54ef922c..e168aa026 100644
--- a/core/external/provider_updatealbuminfo_test.go
+++ b/core/external/provider_updatealbuminfo_test.go
@@ -164,4 +164,26 @@ var _ = Describe("Provider - UpdateAlbumInfo", func() {
 
 		ag.AssertExpectations(GinkgoT())
 	})
+
+	It("returns the original album, unstamped, when the agents are throttled", func() {
+		originalAlbum := &model.Album{
+			ID:          "al-throttled",
+			Name:        "Throttled Album",
+			AlbumArtist: "Throttled Artist",
+			MbzAlbumID:  "mbid-throttled",
+		}
+		mockAlbumRepo.SetData(model.Albums{*originalAlbum})
+
+		ag.On("GetAlbumInfo", ctx, "Throttled Album", "Throttled Artist", "mbid-throttled").
+			Return(nil, agents.ErrRetryLater)
+
+		updatedAlbum, err := p.UpdateAlbumInfo(ctx, "al-throttled")
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(updatedAlbum).NotTo(BeNil())
+		Expect(*updatedAlbum).To(Equal(*originalAlbum))
+		Expect(updatedAlbum.ExternalInfoUpdatedAt).To(BeNil())
+
+		ag.AssertExpectations(GinkgoT())
+	})
 })
diff --git a/core/external/provider_updateartistinfo_test.go b/core/external/provider_updateartistinfo_test.go
index 853d56bbc..c722aaee8 100644
--- a/core/external/provider_updateartistinfo_test.go
+++ b/core/external/provider_updateartistinfo_test.go
@@ -104,6 +104,25 @@ var _ = Describe("Provider - UpdateArtistInfo", func() {
 		ag.AssertExpectations(GinkgoT())
 	})
 
+	// Stamping a throttled round would cache the empty result for the whole TTL.
+	It("does not stamp ExternalInfoUpdatedAt when the agents are throttled", func() {
+		originalArtist := &model.Artist{ID: "ar-throttled", Name: "Throttled Artist"}
+		mockArtistRepo.SetData(model.Artists{*originalArtist})
+
+		ag.On("GetArtistMBID", ctx, "ar-throttled", "Throttled Artist").Return("", agents.ErrRetryLater).Once()
+		ag.On("GetArtistImages", ctx, "ar-throttled", "Throttled Artist", "").Return(nil, agents.ErrRetryLater).Once()
+		ag.On("GetArtistBiography", ctx, "ar-throttled", "Throttled Artist", "").Return("", agents.ErrRetryLater).Once()
+		ag.On("GetArtistURL", ctx, "ar-throttled", "Throttled Artist", "").Return("", agents.ErrRetryLater).Once()
+		ag.On("GetSimilarArtists", ctx, "ar-throttled", "Throttled Artist", "", 100).Return(nil, agents.ErrRetryLater).Once()
+
+		updatedArtist, err := p.UpdateArtistInfo(ctx, "ar-throttled", 10, false)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(updatedArtist).NotTo(BeNil())
+		Expect(updatedArtist.ExternalInfoUpdatedAt).To(BeNil())
+		ag.AssertExpectations(GinkgoT())
+	})
+
 	It("preserves decoded plain text in biography storage", func() {
 		originalArtist := &model.Artist{
 			ID:   "ar-encoded-bio",
diff --git a/core/scrobbler/buffered_scrobbler.go b/core/scrobbler/buffered_scrobbler.go
index 38ea83228..c5c096a0b 100644
--- a/core/scrobbler/buffered_scrobbler.go
+++ b/core/scrobbler/buffered_scrobbler.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -126,42 +127,52 @@ func (b *bufferedScrobbler) run(ctx context.Context) {
 	timer.Stop()
 	defer timer.Stop()
 	failures := 0
+	backingOff := false
 	for {
-		if b.processQueue(ctx) {
-			failures = 0
-			timer.Stop()
-		} else {
-			timer.Reset(backoffDelay(failures))
-			if failures < maxRetryShift {
-				failures++
+		// While a backoff window is open the timer is already armed for the rest of it, so a
+		// wake (a new play enqueued) must not drain: that is the hammering this avoids.
+		if !backingOff {
+			if ok, retryIn := b.processQueue(ctx); ok {
+				failures = 0
+				timer.Stop()
+			} else {
+				timer.Reset(max(backoffDelay(failures), retryIn))
+				backingOff = true
+				if failures < maxRetryShift {
+					failures++
+				}
 			}
 		}
 		select {
 		case <-b.wakeSignal:
 		case <-timer.C:
+			backingOff = false
 		case <-ctx.Done():
 			return
 		}
 	}
 }
 
-func (b *bufferedScrobbler) processQueue(ctx context.Context) bool {
+func (b *bufferedScrobbler) processQueue(ctx context.Context) (bool, time.Duration) {
 	buffer := b.ds.ScrobbleBuffer(ctx)
 	userIds, err := buffer.UserIDs(b.service)
 	if err != nil {
 		log.Error(ctx, "Error retrieving userIds from scrobble buffer", "scrobbler", b.service, err)
-		return false
+		return false, 0
 	}
 	result := true
+	var retryIn time.Duration
 	for _, userId := range userIds {
-		if !b.processUserQueue(ctx, userId) {
+		ok, d := b.processUserQueue(ctx, userId)
+		if !ok {
 			result = false
+			retryIn = max(retryIn, d)
 		}
 	}
-	return result
+	return result, retryIn
 }
 
-func (b *bufferedScrobbler) processUserQueue(ctx context.Context, userId string) bool {
+func (b *bufferedScrobbler) processUserQueue(ctx context.Context, userId string) (bool, time.Duration) {
 	// Scrobbles are drained on a background context that no longer carries the
 	// request's authenticated user. Restore it from the buffered userId so that
 	// scrobblers relying on the user in the context (e.g. plugins) still get it.
@@ -175,25 +186,25 @@ func (b *bufferedScrobbler) processUserQueue(ctx context.Context, userId string)
 		entry, err := buffer.Next(b.service, userId)
 		if err != nil {
 			log.Error(ctx, "Error reading from scrobble buffer", "scrobbler", b.service, err)
-			return false
+			return false, 0
 		}
 		if entry == nil {
-			return true
+			return true, 0
 		}
 		s, ok := b.loader()
 		if !ok {
 			log.Warn(ctx, "Scrobbler not available, will retry later", "scrobbler", b.service)
-			return false
+			return false, 0
 		}
 		log.Debug(ctx, "Sending scrobble", "scrobbler", b.service, "track", entry.Title, "artist", entry.Artist)
 		err = s.Scrobble(ctx, entry.UserID, Scrobble{
 			MediaFile: entry.MediaFile,
 			TimeStamp: entry.PlayTime,
 		})
-		if errors.Is(err, ErrRetryLater) {
+		if retry, ok := errors.AsType[*agents.RetryLaterError](err); ok {
 			log.Warn(ctx, "Could not send scrobble. Will be retried", "userId", entry.UserID,
 				"track", entry.Title, "artist", entry.Artist, "scrobbler", b.service, err)
-			return false
+			return false, retry.RetryIn
 		}
 		if err != nil {
 			log.Error(ctx, "Error sending scrobble to service. Discarding", "scrobbler", b.service,
@@ -203,7 +214,7 @@ func (b *bufferedScrobbler) processUserQueue(ctx context.Context, userId string)
 		if err != nil {
 			log.Error(ctx, "Error removing entry from scrobble buffer", "userId", entry.UserID,
 				"track", entry.Title, "artist", entry.Artist, "scrobbler", b.service, err)
-			return false
+			return false, 0
 		}
 	}
 }
diff --git a/core/scrobbler/buffered_scrobbler_test.go b/core/scrobbler/buffered_scrobbler_test.go
index c250085ef..fd972e87d 100644
--- a/core/scrobbler/buffered_scrobbler_test.go
+++ b/core/scrobbler/buffered_scrobbler_test.go
@@ -2,11 +2,13 @@ package scrobbler
 
 import (
 	"context"
+	"errors"
 	"sync/atomic"
 	"testing"
 	"testing/synctest"
 	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -158,19 +160,128 @@ func TestBufferedScrobblerBackoffSchedule(t *testing.T) {
 			g.Expect(flaky.count.Load()).To(Equal(want), "retry did not fire after the %s backoff", gap)
 		}
 
-		// Once the service recovers, waking the loop drains the buffered entry.
+		// Once the service recovers, the buffered entry drains when the open
+		// backoff window closes (a wake alone must not drain it early).
 		flaky.succeed()
 		bs.sendWakeSignal()
 		synctest.Wait()
+		g.Expect(buffer.Length()).To(Equal(int64(1)), "wake during backoff drained early")
+		time.Sleep(80 * time.Second)
+		synctest.Wait()
 		g.Expect(buffer.Length()).To(Equal(int64(0)))
 	})
 }
 
+func TestBufferedScrobblerBackoffWindow(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		buffer := tests.CreateMockedScrobbleBufferRepo()
+		userRepo := tests.CreateMockUserRepo()
+		_ = userRepo.Put(&model.User{ID: "user1", UserName: "alice"})
+		ds := &tests.MockDataStore{MockedScrobbleBuffer: buffer, MockedUser: userRepo}
+		scr := &fakeScrobbler{Authorized: true}
+		scr.SetError(errors.Join(errors.New("boom"), ErrRetryLater))
+		bs := newBufferedScrobbler(ds, scr, "test")
+		defer bs.Stop()
+
+		// First enqueue: one immediate attempt, then a 5s window opens.
+		_ = bs.Scrobble(context.Background(), "user1", Scrobble{MediaFile: model.MediaFile{ID: "1"}, TimeStamp: time.Now()})
+		synctest.Wait()
+		if got := scr.ScrobbleAttempts(); got != 1 {
+			t.Fatalf("expected 1 attempt after first enqueue, got %d", got)
+		}
+
+		// A wake inside the window must NOT trigger an early attempt.
+		time.Sleep(1 * time.Second)
+		_ = bs.Scrobble(context.Background(), "user1", Scrobble{MediaFile: model.MediaFile{ID: "2"}, TimeStamp: time.Now()})
+		synctest.Wait()
+		if got := scr.ScrobbleAttempts(); got != 1 {
+			t.Fatalf("wake during backoff drained early: %d attempts", got)
+		}
+
+		// When the 5s window closes, the retry happens.
+		time.Sleep(4100 * time.Millisecond)
+		synctest.Wait()
+		if got := scr.ScrobbleAttempts(); got != 2 {
+			t.Fatalf("expected retry after window, got %d attempts", got)
+		}
+	})
+}
+
+func TestBufferedScrobblerHonorsServerDelay(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		buffer := tests.CreateMockedScrobbleBufferRepo()
+		userRepo := tests.CreateMockUserRepo()
+		_ = userRepo.Put(&model.User{ID: "user1", UserName: "alice"})
+		ds := &tests.MockDataStore{MockedScrobbleBuffer: buffer, MockedUser: userRepo}
+		scr := &fakeScrobbler{Authorized: true}
+		scr.SetError(errors.Join(errors.New("429"), &agents.RetryLaterError{RetryIn: 30 * time.Second}))
+		bs := newBufferedScrobbler(ds, scr, "test")
+		defer bs.Stop()
+
+		_ = bs.Scrobble(context.Background(), "user1", Scrobble{MediaFile: model.MediaFile{ID: "1"}, TimeStamp: time.Now()})
+		synctest.Wait()
+		if got := scr.ScrobbleAttempts(); got != 1 {
+			t.Fatalf("expected 1 attempt, got %d", got)
+		}
+
+		// The 5s exponential floor is overridden by the 30s server delay.
+		time.Sleep(20 * time.Second)
+		synctest.Wait()
+		if got := scr.ScrobbleAttempts(); got != 1 {
+			t.Fatalf("retried before server delay elapsed: %d attempts", got)
+		}
+		time.Sleep(10100 * time.Millisecond)
+		synctest.Wait()
+		if got := scr.ScrobbleAttempts(); got != 2 {
+			t.Fatalf("expected retry after server delay, got %d attempts", got)
+		}
+	})
+}
+
+// The drain visits users in an arbitrary order, so the longest delay must win regardless
+// of which user was seen last.
+func TestBufferedScrobblerTakesTheLongestServerDelayAcrossUsers(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		buffer := tests.CreateMockedScrobbleBufferRepo()
+		userRepo := tests.CreateMockUserRepo()
+		_ = userRepo.Put(&model.User{ID: "user1", UserName: "alice"})
+		_ = userRepo.Put(&model.User{ID: "user2", UserName: "bob"})
+		ds := &tests.MockDataStore{MockedScrobbleBuffer: buffer, MockedUser: userRepo}
+		scr := &recoveringScrobbler{delays: map[string]time.Duration{
+			"user1": 10 * time.Second,
+			"user2": 45 * time.Second,
+		}}
+		bs := newBufferedScrobbler(ds, scr, "test")
+		defer bs.Stop()
+
+		// user2 is enqueued directly so both are buffered before the first drain wakes.
+		_ = buffer.Enqueue("test", "user2", "2", time.Now())
+		_ = bs.Scrobble(context.Background(), "user1", Scrobble{MediaFile: model.MediaFile{ID: "1"}, TimeStamp: time.Now()})
+		synctest.Wait()
+		if got := scr.count.Load(); got != 2 {
+			t.Fatalf("expected both users drained, got %d attempts", got)
+		}
+
+		time.Sleep(30 * time.Second)
+		synctest.Wait()
+		if got := scr.count.Load(); got != 2 {
+			t.Fatalf("retried on the shorter delay: %d attempts", got)
+		}
+		time.Sleep(15100 * time.Millisecond)
+		synctest.Wait()
+		if got := scr.count.Load(); got != 4 {
+			t.Fatalf("expected a retry after the longest delay, got %d attempts", got)
+		}
+	})
+}
+
 // recoveringScrobbler is a race-safe Scrobbler whose error can be toggled while
 // the buffered scrobbler's goroutine is draining, to exercise retry then recovery.
+// With delays set, it instead fails every scrobble asking for that user's delay.
 type recoveringScrobbler struct {
-	err   atomic.Pointer[error]
-	count atomic.Int32
+	err    atomic.Pointer[error]
+	count  atomic.Int32
+	delays map[string]time.Duration
 }
 
 func (f *recoveringScrobbler) fail(err error) { f.err.Store(&err) }
@@ -182,8 +293,11 @@ func (f *recoveringScrobbler) NowPlaying(context.Context, string, *model.MediaFi
 	return nil
 }
 
-func (f *recoveringScrobbler) Scrobble(_ context.Context, _ string, _ Scrobble) error {
+func (f *recoveringScrobbler) Scrobble(_ context.Context, userId string, _ Scrobble) error {
 	f.count.Add(1)
+	if f.delays != nil {
+		return errors.Join(errors.New("429"), &agents.RetryLaterError{RetryIn: f.delays[userId]})
+	}
 	if e := f.err.Load(); e != nil {
 		return *e
 	}
diff --git a/core/scrobbler/interfaces.go b/core/scrobbler/interfaces.go
index 8a18bb37e..218b7a919 100644
--- a/core/scrobbler/interfaces.go
+++ b/core/scrobbler/interfaces.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/model"
 )
 
@@ -15,7 +16,8 @@ type Scrobble struct {
 
 var (
 	ErrNotAuthorized = errors.New("not authorized")
-	ErrRetryLater    = errors.New("retry later")
+	// ErrRetryLater is an alias of agents.ErrRetryLater so adapters and plugins share one identity.
+	ErrRetryLater    = agents.ErrRetryLater
 	ErrUnrecoverable = errors.New("unrecoverable")
 )
 
diff --git a/core/scrobbler/play_tracker_test.go b/core/scrobbler/play_tracker_test.go
index 72f802c2e..0e768c3f4 100644
--- a/core/scrobbler/play_tracker_test.go
+++ b/core/scrobbler/play_tracker_test.go
@@ -293,7 +293,7 @@ var _ = Describe("PlayTracker", func() {
 		})
 
 		It("increments play counts even if it cannot scrobble", func() {
-			fake.Error = errors.New("error")
+			fake.SetError(errors.New("error"))
 
 			err := tracker.Submit(ctx, []Submission{{TrackID: "123", Timestamp: time.Now()}})
 
@@ -1414,7 +1414,25 @@ type fakeScrobbler struct {
 	position             atomic.Int32
 	LastScrobble         atomic.Pointer[Scrobble]
 	LastPlaybackReport   atomic.Pointer[PlaybackSession]
-	Error                error
+	err                  atomic.Pointer[error]
+	scrobbleAttempts     atomic.Int32
+}
+
+// SetError sets the error returned by IsAuthorized/NowPlaying/Scrobble/PlaybackReport.
+func (f *fakeScrobbler) SetError(err error) {
+	f.err.Store(&err)
+}
+
+func (f *fakeScrobbler) getError() error {
+	if e := f.err.Load(); e != nil {
+		return *e
+	}
+	return nil
+}
+
+// ScrobbleAttempts returns how many times Scrobble was called.
+func (f *fakeScrobbler) ScrobbleAttempts() int32 {
+	return f.scrobbleAttempts.Load()
 }
 
 func (f *fakeScrobbler) GetNowPlayingCalled() bool {
@@ -1440,13 +1458,13 @@ func (f *fakeScrobbler) GetTrack() *model.MediaFile {
 }
 
 func (f *fakeScrobbler) IsAuthorized(ctx context.Context, userId string) bool {
-	return f.Error == nil && f.Authorized
+	return f.getError() == nil && f.Authorized
 }
 
 func (f *fakeScrobbler) NowPlaying(ctx context.Context, userId string, track *model.MediaFile, position int) error {
 	f.nowPlayingCalled.Store(true)
-	if f.Error != nil {
-		return f.Error
+	if err := f.getError(); err != nil {
+		return err
 	}
 	f.userID.Store(&userId)
 	// Capture username from context (this is what plugin scrobblers do)
@@ -1478,16 +1496,17 @@ func (f *fakeScrobbler) Scrobble(ctx context.Context, userId string, s Scrobble)
 	}
 	f.LastScrobble.Store(&s)
 	f.ScrobbleCalled.Store(true)
-	if f.Error != nil {
-		return f.Error
+	f.scrobbleAttempts.Add(1)
+	if err := f.getError(); err != nil {
+		return err
 	}
 	return nil
 }
 
 func (f *fakeScrobbler) PlaybackReport(ctx context.Context, info PlaybackSession) error {
 	f.PlaybackReportCalled.Store(true)
-	if f.Error != nil {
-		return f.Error
+	if err := f.getError(); err != nil {
+		return err
 	}
 	f.userID.Store(new(info.UserId))
 	f.LastPlaybackReport.Store(&info)
diff --git a/plugins/capabilities.go b/plugins/capabilities.go
index 81e683b6b..b86475028 100644
--- a/plugins/capabilities.go
+++ b/plugins/capabilities.go
@@ -1,6 +1,11 @@
 package plugins
 
-import "slices"
+import (
+	"regexp"
+	"slices"
+
+	"github.com/navidrome/navidrome/core/agents"
+)
 
 // Capability represents a plugin capability type.
 // Capabilities are detected by checking which functions a plugin exports.
@@ -39,3 +44,25 @@ func detectCapabilities(plugin functionExistsChecker) []Capability {
 func hasCapability(capabilities []Capability, cap Capability) bool {
 	return slices.Contains(capabilities, cap)
 }
+
+// retryLaterRe matches one capability's `<capability>(retry_later[:seconds])` token, which is
+// all a plugin fault carries back across the WASM boundary. The capability is part of the
+// pattern, so another capability's token in the same message cannot mask this one. The leading
+// \b keeps a superstring like `useragent(retry_later)` from matching `agent`.
+var (
+	agentRetryLaterRe     = retryLaterRe("agent")
+	scrobblerRetryLaterRe = retryLaterRe("scrobbler")
+)
+
+func retryLaterRe(capability string) *regexp.Regexp {
+	return regexp.MustCompile(`\b` + capability + `\(retry_later(?::(\d+))?\)`)
+}
+
+// parseRetryLater reports whether msg carries the capability's retry_later token, with its delay.
+func parseRetryLater(re *regexp.Regexp, msg string) (*agents.RetryLaterError, bool) {
+	m := re.FindStringSubmatch(msg)
+	if m == nil {
+		return nil, false
+	}
+	return &agents.RetryLaterError{RetryIn: agents.ParseRetryIn(m[1])}, true
+}
diff --git a/plugins/capabilities/metadata_agent.go b/plugins/capabilities/metadata_agent.go
index 72cb1622f..8fec7f5a8 100644
--- a/plugins/capabilities/metadata_agent.go
+++ b/plugins/capabilities/metadata_agent.go
@@ -224,3 +224,15 @@ type SimilarSongsResponse struct {
 	// Songs is the list of similar songs.
 	Songs []types.SongRef `json:"songs"`
 }
+
+// MetadataAgentError represents an error type for metadata agent operations.
+type MetadataAgentError string
+
+const (
+	// MetadataAgentErrorRetryLater indicates the provider is throttling; retry later.
+	// Append ":<seconds>" inside the parentheses to request a specific delay.
+	MetadataAgentErrorRetryLater MetadataAgentError = "agent(retry_later)"
+)
+
+// Error implements the error interface for MetadataAgentError.
+func (e MetadataAgentError) Error() string { return string(e) }
diff --git a/plugins/metadata_agent.go b/plugins/metadata_agent.go
index 607926438..17062ba6b 100644
--- a/plugins/metadata_agent.go
+++ b/plugins/metadata_agent.go
@@ -56,6 +56,9 @@ func agentErr(err error) error {
 	if errors.Is(err, errNotImplemented) || errors.Is(err, errFunctionNotFound) {
 		return errors.Join(agents.ErrNotFound, err)
 	}
+	if retryLater, ok := parseRetryLater(agentRetryLaterRe, err.Error()); ok {
+		return errors.Join(retryLater, err)
+	}
 	return err
 }
 
diff --git a/plugins/metadata_agent_test.go b/plugins/metadata_agent_test.go
index 2dc67d41c..a7a0aa8b8 100644
--- a/plugins/metadata_agent_test.go
+++ b/plugins/metadata_agent_test.go
@@ -5,6 +5,7 @@ package plugins
 import (
 	"errors"
 	"fmt"
+	"time"
 
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/plugins/capabilities"
@@ -31,6 +32,31 @@ var _ = Describe("agentErr", func() {
 		Entry("a non-zero exit is a fault",
 			errors.New("plugin call exited with code 1"), false),
 	)
+
+	DescribeTable("agentErr retry-later",
+		func(msg string, wantDelay time.Duration) {
+			err := agentErr(errors.New(msg))
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
+			retry, _ := errors.AsType[*agents.RetryLaterError](err)
+			d := retry.RetryIn
+			Expect(d).To(Equal(wantDelay))
+		},
+		Entry("bare token", "agent(retry_later)", time.Duration(0)),
+		Entry("with seconds", "agent(retry_later:120)", 120*time.Second),
+		Entry("capped at 1h", "agent(retry_later:999999)", time.Hour),
+		// Scaling to nanoseconds before capping wraps past 2^64, landing on ~0.29s.
+		Entry("capped before it can overflow", "agent(retry_later:18446744074)", time.Hour),
+	)
+
+	It("leaves other plugin errors untouched", func() {
+		orig := errors.New("some plugin failure")
+		Expect(agentErr(orig)).To(Equal(orig))
+	})
+
+	It("does not treat a superstring token as a throttle", func() {
+		orig := errors.New("useragent(retry_later)")
+		Expect(agentErr(orig)).To(Equal(orig))
+	})
 })
 
 var _ = Describe("MetadataAgent", Ordered, func() {
diff --git a/plugins/pdk/go/metadata/metadata.go b/plugins/pdk/go/metadata/metadata.go
index bb0ae9620..57546352e 100644
--- a/plugins/pdk/go/metadata/metadata.go
+++ b/plugins/pdk/go/metadata/metadata.go
@@ -18,6 +18,18 @@ type ArtistRef = types.ArtistRef
 // Deprecated: use types.SongRef.
 type SongRef = types.SongRef
 
+// MetadataAgentError represents an error type for metadata agent operations.
+type MetadataAgentError string
+
+const (
+	// MetadataAgentErrorRetryLater indicates the provider is throttling; retry later.
+	// Append ":<seconds>" inside the parentheses to request a specific delay.
+	MetadataAgentErrorRetryLater MetadataAgentError = "agent(retry_later)"
+)
+
+// Error implements the error interface for MetadataAgentError.
+func (e MetadataAgentError) Error() string { return string(e) }
+
 // AlbumImagesResponse is the response for GetAlbumImages.
 type AlbumImagesResponse struct {
 	// Images is the list of album images.
diff --git a/plugins/pdk/go/metadata/metadata_stub.go b/plugins/pdk/go/metadata/metadata_stub.go
index 572eba4da..f979419a9 100644
--- a/plugins/pdk/go/metadata/metadata_stub.go
+++ b/plugins/pdk/go/metadata/metadata_stub.go
@@ -16,6 +16,18 @@ type ArtistRef = types.ArtistRef
 // Deprecated: use types.SongRef.
 type SongRef = types.SongRef
 
+// MetadataAgentError represents an error type for metadata agent operations.
+type MetadataAgentError string
+
+const (
+	// MetadataAgentErrorRetryLater indicates the provider is throttling; retry later.
+	// Append ":<seconds>" inside the parentheses to request a specific delay.
+	MetadataAgentErrorRetryLater MetadataAgentError = "agent(retry_later)"
+)
+
+// Error implements the error interface for MetadataAgentError.
+func (e MetadataAgentError) Error() string { return string(e) }
+
 // AlbumImagesResponse is the response for GetAlbumImages.
 type AlbumImagesResponse struct {
 	// Images is the list of album images.
diff --git a/plugins/pdk/rust/nd-pdk-capabilities/src/metadata.rs b/plugins/pdk/rust/nd-pdk-capabilities/src/metadata.rs
index 38fcae9da..890e16954 100644
--- a/plugins/pdk/rust/nd-pdk-capabilities/src/metadata.rs
+++ b/plugins/pdk/rust/nd-pdk-capabilities/src/metadata.rs
@@ -24,6 +24,11 @@ pub type ArtistRef = nd_pdk_types::ArtistRef;
 
 #[deprecated(note = "use nd_pdk::types::SongRef")]
 pub type SongRef = nd_pdk_types::SongRef;
+/// MetadataAgentError represents an error type for metadata agent operations.
+pub type MetadataAgentError = &'static str;
+/// MetadataAgentErrorRetryLater indicates the provider is throttling; retry later.
+/// Append ":<seconds>" inside the parentheses to request a specific delay.
+pub const METADATA_AGENT_ERROR_RETRY_LATER: MetadataAgentError = "agent(retry_later)";
 /// AlbumImagesResponse is the response for GetAlbumImages.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
diff --git a/plugins/scrobbler_adapter.go b/plugins/scrobbler_adapter.go
index b3203a352..721f0d3fa 100644
--- a/plugins/scrobbler_adapter.go
+++ b/plugins/scrobbler_adapter.go
@@ -174,11 +174,12 @@ func mapScrobblerError(err error) error {
 		return nil
 	}
 	errMsg := err.Error()
+	retryLater, isRetryLater := parseRetryLater(scrobblerRetryLaterRe, errMsg)
 	switch {
 	case strings.Contains(errMsg, capabilities.ScrobblerErrorNotAuthorized.Error()):
 		return scrobbler.ErrNotAuthorized
-	case strings.Contains(errMsg, capabilities.ScrobblerErrorRetryLater.Error()):
-		return scrobbler.ErrRetryLater
+	case isRetryLater:
+		return retryLater
 	case strings.Contains(errMsg, capabilities.ScrobblerErrorUnrecoverable.Error()):
 		return scrobbler.ErrUnrecoverable
 	default:
diff --git a/plugins/scrobbler_adapter_test.go b/plugins/scrobbler_adapter_test.go
index 56a452742..3efd5d1b1 100644
--- a/plugins/scrobbler_adapter_test.go
+++ b/plugins/scrobbler_adapter_test.go
@@ -7,6 +7,7 @@ import (
 	"errors"
 	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/core/scrobbler"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -362,4 +363,25 @@ var _ = Describe("mapScrobblerError", func() {
 		err := mapScrobblerError(errors.New("some unknown error"))
 		Expect(err).To(MatchError(scrobbler.ErrUnrecoverable))
 	})
+
+	DescribeTable("mapScrobblerError retry-later",
+		func(msg string, wantDelay time.Duration) {
+			err := mapScrobblerError(errors.New(msg))
+			Expect(errors.Is(err, scrobbler.ErrRetryLater)).To(BeTrue())
+			retry, _ := errors.AsType[*agents.RetryLaterError](err)
+			d := retry.RetryIn
+			Expect(d).To(Equal(wantDelay))
+		},
+		Entry("bare token", "scrobbler(retry_later)", time.Duration(0)),
+		Entry("with seconds", "scrobbler(retry_later:30)", 30*time.Second),
+		Entry("capped at 1h", "scrobbler(retry_later:999999)", time.Hour),
+		// Scaling to nanoseconds before capping wraps past 2^64, landing on ~0.29s.
+		Entry("capped before it can overflow", "scrobbler(retry_later:18446744074)", time.Hour),
+		Entry("wrapped in context", "plugin xyz: scrobbler(retry_later:5)", 5*time.Second),
+	)
+
+	It("still maps unknown errors to unrecoverable", func() {
+		err := mapScrobblerError(errors.New("scrobbler(retry_later_garbage"))
+		Expect(errors.Is(err, scrobbler.ErrUnrecoverable)).To(BeTrue())
+	})
 })

From b134f16fd5f95308700b1e66940fc4f495f80ff2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 11:11:35 -0400
Subject: [PATCH 084/200] feat(plugins): surface the valid agent names in logs
 and the Plugins UI (#5910)

The agent name used in the `Agents` config option comes from the .ndp file
name, not from the manifest. The Plugins UI showed the ID but never said what
it was for, so renaming a plugin file silently breaks the config with only a
Debug-level "Unknown agent ignored" line to go on.

Add a caption under the ID in the Plugins UI, and list the accepted names
alongside the rejected one in that log line.

Related to navidrome/apple-music-plugin#14
---
 core/agents/agents.go           | 10 +++++++-
 core/agents/agents_test.go      | 17 ++++++++++++++
 resources/i18n/pt-br.json       |  1 +
 ui/src/i18n/en.json             |  1 +
 ui/src/plugin/InfoCard.jsx      |  9 +++++++-
 ui/src/plugin/InfoCard.test.jsx | 41 +++++++++++++++++++++++++++++++++
 ui/src/plugin/styles.js         |  4 ++++
 7 files changed, 81 insertions(+), 2 deletions(-)
 create mode 100644 ui/src/plugin/InfoCard.test.jsx

diff --git a/core/agents/agents.go b/core/agents/agents.go
index ac623951c..8ae3124ef 100644
--- a/core/agents/agents.go
+++ b/core/agents/agents.go
@@ -4,6 +4,7 @@ import (
 	"cmp"
 	"context"
 	"errors"
+	"maps"
 	"slices"
 	"strings"
 	"sync"
@@ -126,12 +127,19 @@ func (a *Agents) getEnabledAgentNames() []enabledAgent {
 		} else if isPlugin {
 			validAgents = append(validAgents, enabledAgent{name: name, isPlugin: true})
 		} else {
-			log.Debug("Unknown agent ignored", "name", name)
+			log.Debug("Unknown agent ignored", "name", name, "available", availableAgentNames(availablePlugins))
 		}
 	}
 	return validAgents
 }
 
+// availableAgentNames returns every name accepted by the Agents config option.
+func availableAgentNames(plugins []string) []string {
+	names := append(slices.Collect(maps.Keys(Map)), plugins...)
+	slices.Sort(names)
+	return names
+}
+
 func (a *Agents) getAgent(ea enabledAgent) Interface {
 	if ea.isPlugin {
 		// Try to load WASM plugin agent (if plugin loader is available)
diff --git a/core/agents/agents_test.go b/core/agents/agents_test.go
index 35ebf18d8..6163c7f3c 100644
--- a/core/agents/agents_test.go
+++ b/core/agents/agents_test.go
@@ -3,6 +3,7 @@ package agents
 import (
 	"context"
 	"errors"
+	"slices"
 	"time"
 
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -91,6 +92,22 @@ var _ = Describe("Agents", func() {
 			Expect(ags).ToNot(ContainElement("disabled"))
 		})
 
+		Describe("availableAgentNames", func() {
+			It("combines built-in agents with the given plugins", func() {
+				names := availableAgentNames([]string{"apple-music"})
+				Expect(names).To(ContainElements("apple-music", LocalAgentName, "fake", "empty"))
+			})
+
+			It("returns the names sorted", func() {
+				names := availableAgentNames([]string{"zz-plugin", "aa-plugin"})
+				Expect(slices.IsSorted(names)).To(BeTrue())
+			})
+
+			It("works when there are no plugins", func() {
+				Expect(availableAgentNames(nil)).To(ContainElement(LocalAgentName))
+			})
+		})
+
 		Describe("GetArtistMBID", func() {
 			It("returns on first match", func() {
 				Expect(ag.GetArtistMBID(ctx, "123", "test")).To(Equal("mbid"))
diff --git a/resources/i18n/pt-br.json b/resources/i18n/pt-br.json
index a4ad6bc8c..ccc5f872b 100644
--- a/resources/i18n/pt-br.json
+++ b/resources/i18n/pt-br.json
@@ -394,6 +394,7 @@
         "invalidJson": "A configuração deve ser um JSON válido"
       },
       "messages": {
+        "idHelp": "O ID do plugin, derivado do nome do arquivo. Use-o ao referenciar este plugin em opções de configuração, como Agents.",
         "configHelp": "Configure o plugin usando pares chave-valor. Deixe vazio se o plugin não precisa de configuração.",
         "clickPermissions": "Clique em uma permissão para ver detalhes",
         "noConfig": "Nenhuma configuração definida",
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index 8823a6749..de96d47c0 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -397,6 +397,7 @@
         "invalidJson": "Configuration must be valid JSON"
       },
       "messages": {
+        "idHelp": "The plugin ID, derived from its file name. Use it when referencing this plugin in configuration options, such as Agents.",
         "configHelp": "Configure the plugin using key-value pairs. Leave empty if the plugin requires no configuration.",
         "configValidationError": "Configuration validation failed:",
         "schemaRenderError": "Unable to render configuration form. The plugin's schema may be invalid.",
diff --git a/ui/src/plugin/InfoCard.jsx b/ui/src/plugin/InfoCard.jsx
index 8fb6853fe..3a7bb24c7 100644
--- a/ui/src/plugin/InfoCard.jsx
+++ b/ui/src/plugin/InfoCard.jsx
@@ -123,6 +123,13 @@ export const InfoCard = ({ record, manifest, classes, translate, isSmall }) => (
           isSmall={isSmall}
         >
           {record.id}
+          <Typography
+            variant="caption"
+            color="textSecondary"
+            className={classes.fieldHelp}
+          >
+            {translate('resources.plugin.messages.idHelp')}
+          </Typography>
         </InfoRow>
 
         {manifest?.name && (
@@ -201,7 +208,7 @@ export const InfoCard = ({ record, manifest, classes, translate, isSmall }) => (
               <Typography
                 variant="caption"
                 color="textSecondary"
-                style={{ marginTop: 4, display: 'block' }}
+                className={classes.fieldHelp}
               >
                 {translate('resources.plugin.messages.clickPermissions')}
               </Typography>
diff --git a/ui/src/plugin/InfoCard.test.jsx b/ui/src/plugin/InfoCard.test.jsx
new file mode 100644
index 000000000..24fa48caa
--- /dev/null
+++ b/ui/src/plugin/InfoCard.test.jsx
@@ -0,0 +1,41 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+
+vi.mock('../common', () => ({
+  DateField: ({ source }) => <span data-testid={`date-${source}`} />,
+}))
+
+const { InfoCard } = await import('./InfoCard')
+
+const record = {
+  id: 'apple-music',
+  path: '/data/plugins/apple-music.ndp',
+  updatedAt: '2026-01-01T00:00:00Z',
+  createdAt: '2026-01-01T00:00:00Z',
+}
+
+const renderCard = () =>
+  render(
+    <InfoCard
+      record={record}
+      manifest={{ name: 'Apple Music Metadata Agent' }}
+      classes={{}}
+      translate={(key) => key}
+      isSmall={false}
+    />,
+  )
+
+describe('InfoCard', () => {
+  it('shows the plugin ID', () => {
+    renderCard()
+    expect(screen.getByText('apple-music')).toBeInTheDocument()
+  })
+
+  it('explains that the ID is the name used in config options', () => {
+    renderCard()
+    expect(
+      screen.getByText('resources.plugin.messages.idHelp'),
+    ).toBeInTheDocument()
+  })
+})
diff --git a/ui/src/plugin/styles.js b/ui/src/plugin/styles.js
index 104d8bc0f..68c0be929 100644
--- a/ui/src/plugin/styles.js
+++ b/ui/src/plugin/styles.js
@@ -45,6 +45,10 @@ export const usePluginShowStyles = makeStyles(
       fontSize: '0.85rem',
       wordBreak: 'break-all',
     },
+    fieldHelp: {
+      marginTop: theme.spacing(0.5),
+      display: 'block',
+    },
     permissionsContainer: {
       display: 'flex',
       flexWrap: 'wrap',

From 3867fab4da6ea7142bfc6374c94b34a708e03b4e Mon Sep 17 00:00:00 2001
From: Aditya Raj Singh <github@adityaraj.com>
Date: Sun, 30 Aug 2026 20:51:14 +0530
Subject: [PATCH 085/200] fix(transcoding): report AAC streams as audio/aac
 instead of audio/mp4 (#5998)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The default AAC transcode emits raw ADTS (`ffmpeg ... -f adts -`), but
the MIME table mapped `.aac` to `audio/mp4`. Clients that dispatch
strictly on Content-Type could reject the stream because the declared
container did not match the payload.

`.m4a` and `.alac` stay on `audio/mp4`, since those really are MP4.

Fixes #5958

Signed-off-by: Aditya Raj Singh <aditya@bncw.in>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 resources/mime_types.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/mime_types.yaml b/resources/mime_types.yaml
index 83abf2e5c..18a2c22b5 100644
--- a/resources/mime_types.yaml
+++ b/resources/mime_types.yaml
@@ -10,7 +10,7 @@ types:
   .ogg: audio/ogg 
   .oga: audio/ogg 
   .opus: audio/ogg 
-  .aac: audio/mp4 
+  .aac: audio/aac
   .alac: audio/mp4 
   .m4a: audio/mp4 
   .m4b: audio/mp4 

From ff033d8db62c9b045ae3dea54fc794a8114dd5e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 12:43:15 -0400
Subject: [PATCH 086/200] chore(deps): upgrade to Go 1.27 (#5990)

* build: upgrade to Go 1.27

Bumps the toolchain in go.mod, both golang base images in the Dockerfile, and
the devcontainer VARIANT. CI needs no change, as the workflows resolve the
version through go-version-file: go.mod.

Tests, race tests, build and vet all pass on go1.27.0.

* build: upgrade golangci-lint to v2.13.0

v2.13.0 is the first release built with Go 1.27, so it can lint a module whose go
directive is 1.27. It also enables gosec's G404 on math/rand/v2, which flags the
three rand.Shuffle call sites. Shuffle order is not a security decision, and the
crypto-backed alternative in utils/random costs 25x and allocates per swap, so the
call sites are annotated rather than the rule excluded, keeping G404 active for the
cases where it would matter.

* chore(deps): update Go dependencies to latest versions

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

* build: bump golangci-lint to v2.13.2

---------

Signed-off-by: Deluan <deluan@navidrome.org>
---
 .devcontainer/devcontainer.json        | 2 +-
 Dockerfile                             | 4 ++--
 Makefile                               | 2 +-
 core/external/provider_similarsongs.go | 1 +
 core/playback/queue.go                 | 1 +
 db/backup_test.go                      | 1 +
 go.mod                                 | 2 +-
 7 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index c9e4ba2bf..efe965428 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -4,7 +4,7 @@
 		"dockerfile": "Dockerfile",
 		"args": {
 			// Update the VARIANT arg to pick a version of Go: 1, 1.15, 1.14
-			"VARIANT": "1.26",
+			"VARIANT": "1.27",
 			// Options
 			"INSTALL_NODE": "true",
 			"NODE_VERSION": "v24"
diff --git a/Dockerfile b/Dockerfile
index 847c19bf7..3d7a03f5d 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -43,7 +43,7 @@ COPY --from=ui /build /build
 
 ########################################################################################################################
 ### Build Navidrome binary for Docker image (dynamic musl, enables native libwebp via dlopen)
-FROM --platform=$BUILDPLATFORM golang:1.26-alpine AS build-alpine
+FROM --platform=$BUILDPLATFORM golang:1.27-alpine AS build-alpine
 COPY --from=xx / /
 
 ARG TARGETPLATFORM
@@ -85,7 +85,7 @@ EOT
 
 ########################################################################################################################
 ### Build Navidrome binary for standalone distribution (static glibc, cross-compiled)
-FROM --platform=$BUILDPLATFORM golang:1.26-trixie AS base
+FROM --platform=$BUILDPLATFORM golang:1.27-trixie AS base
 RUN apt-get update && apt-get install -y clang lld
 COPY --from=xx / /
 WORKDIR /workspace
diff --git a/Makefile b/Makefile
index fa0d10475..81a609422 100644
--- a/Makefile
+++ b/Makefile
@@ -20,7 +20,7 @@ IMAGE_PLATFORMS ?= $(shell echo $(SUPPORTED_PLATFORMS) | tr ',' '\n' | grep "lin
 PLATFORMS ?= $(SUPPORTED_PLATFORMS)
 DOCKER_TAG ?= deluan/navidrome:develop
 
-GOLANGCI_LINT_VERSION ?= v2.12.0
+GOLANGCI_LINT_VERSION ?= v2.13.2
 
 UI_SRC_FILES := $(shell find ui -type f -not -path "ui/build/*" -not -path "ui/node_modules/*")
 
diff --git a/core/external/provider_similarsongs.go b/core/external/provider_similarsongs.go
index 7720c9349..4ab465b03 100644
--- a/core/external/provider_similarsongs.go
+++ b/core/external/provider_similarsongs.go
@@ -167,6 +167,7 @@ func (e *provider) seedMix(ctx context.Context, count int, sample func() (model.
 	if len(matched) == 0 {
 		matched = seeds
 	}
+	//nolint:gosec // shuffle order is not a security decision
 	rand.Shuffle(len(matched), func(i, j int) { matched[i], matched[j] = matched[j], matched[i] })
 	if len(matched) > count {
 		matched = matched[:count]
diff --git a/core/playback/queue.go b/core/playback/queue.go
index d15eaad96..116db5fe6 100644
--- a/core/playback/queue.go
+++ b/core/playback/queue.go
@@ -100,6 +100,7 @@ func (pd *Queue) Shuffle() {
 		backupID = current.ID
 	}
 
+	//nolint:gosec // shuffle order is not a security decision
 	rand.Shuffle(len(pd.Items), func(i, j int) { pd.Items[i], pd.Items[j] = pd.Items[j], pd.Items[i] })
 
 	var err error
diff --git a/db/backup_test.go b/db/backup_test.go
index 5e8f877e6..5d1bfc6e3 100644
--- a/db/backup_test.go
+++ b/db/backup_test.go
@@ -68,6 +68,7 @@ var _ = Describe("database backups", func() {
 
 			timesShuffled = make([]time.Time, len(timesDecreasingChronologically))
 			copy(timesShuffled, timesDecreasingChronologically)
+			//nolint:gosec // shuffle order is not a security decision
 			rand.Shuffle(len(timesShuffled), func(i, j int) {
 				timesShuffled[i], timesShuffled[j] = timesShuffled[j], timesShuffled[i]
 			})
diff --git a/go.mod b/go.mod
index 93e84b052..a7b005c25 100644
--- a/go.mod
+++ b/go.mod
@@ -1,6 +1,6 @@
 module github.com/navidrome/navidrome
 
-go 1.26
+go 1.27
 
 // Fork to implement raw tags support
 replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3

From b3ecaddd9c49534f6612a12715a83bd457fe0a67 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 11:28:32 -0400
Subject: [PATCH 087/200] chore(deps): update fscache and stream dependencies
 to latest versions

Signed-off-by: Deluan <deluan@navidrome.org>
---
 go.mod | 7 ++-----
 go.sum | 8 ++++----
 2 files changed, 6 insertions(+), 9 deletions(-)

diff --git a/go.mod b/go.mod
index a7b005c25..cdf8fc699 100644
--- a/go.mod
+++ b/go.mod
@@ -5,9 +5,6 @@ go 1.27
 // Fork to implement raw tags support
 replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3
 
-// Fork to implement CloseWithError, proposed upstream in https://github.com/djherbis/fscache/pull/22
-replace github.com/djherbis/fscache => github.com/deluan/fscache v0.9.1-0.20260829205053-654a9d517048
-
 require (
 	github.com/Masterminds/squirrel v1.5.4
 	github.com/andybalholm/cascadia v1.3.4
@@ -16,8 +13,8 @@ require (
 	github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55
 	github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36
 	github.com/djherbis/atime v1.1.0
-	github.com/djherbis/fscache v0.10.2-0.20231127215153-442a07e326c4
-	github.com/djherbis/stream v1.5.0
+	github.com/djherbis/fscache v0.10.2-0.20260829235704-6d85d5878c22
+	github.com/djherbis/stream v1.5.1
 	github.com/djherbis/times v1.6.0
 	github.com/dustin/go-humanize v1.0.1
 	github.com/extism/go-sdk v1.7.1
diff --git a/go.sum b/go.sum
index c75b72dd0..d852285f1 100644
--- a/go.sum
+++ b/go.sum
@@ -29,8 +29,6 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
-github.com/deluan/fscache v0.9.1-0.20260829205053-654a9d517048 h1:u3oDvM7pOIouwDGeIoMu9SYgSzVMtiSkOc+xywtKiJk=
-github.com/deluan/fscache v0.9.1-0.20260829205053-654a9d517048/go.mod h1:Bbk9SqpJcg/saiPfG6byM1G4G/LQndknrsLVOQ+VJqY=
 github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3 h1:j7eSXqgtjhlNfwnMEzRdXnJGZTEw4I7J9TeQAll83bU=
 github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcHCKTtwzrd0HGfEmoODFA/qnk4=
@@ -41,8 +39,10 @@ github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36 h1:KtPfdSST6e0vJbM
 github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36/go.mod h1:RkQWLNITKkXHLP7LXxZSgEq+uFWU25M5qW7qfEhL9Wc=
 github.com/djherbis/atime v1.1.0 h1:rgwVbP/5by8BvvjBNrbh64Qz33idKT3pSnMSJsxhi0g=
 github.com/djherbis/atime v1.1.0/go.mod h1:28OF6Y8s3NQWwacXc5eZTsEsiMzp7LF8MbXE+XJPdBE=
-github.com/djherbis/stream v1.5.0 h1:+ewqpS/ndTmEiJRH142JyOpmmjnkTxdbJtqoAG5sg0Y=
-github.com/djherbis/stream v1.5.0/go.mod h1:cqjC1ZRq3FFwkGmUtHwcldbnW8f0Q4YuVsGW1eAFtOk=
+github.com/djherbis/fscache v0.10.2-0.20260829235704-6d85d5878c22 h1:GNKxzBirvK9arfVRGVebhFYBp3tnOZG3nlIog6N5/6I=
+github.com/djherbis/fscache v0.10.2-0.20260829235704-6d85d5878c22/go.mod h1:Bbk9SqpJcg/saiPfG6byM1G4G/LQndknrsLVOQ+VJqY=
+github.com/djherbis/stream v1.5.1 h1:9AoCl0bnm7imWT2uUORqT8aLuTh+YllyynYpolpjIqY=
+github.com/djherbis/stream v1.5.1/go.mod h1:cqjC1ZRq3FFwkGmUtHwcldbnW8f0Q4YuVsGW1eAFtOk=
 github.com/djherbis/times v1.6.0 h1:w2ctJ92J8fBvWPxugmXIv7Nz7Q3iDMKNx9v5ocVH20c=
 github.com/djherbis/times v1.6.0/go.mod h1:gOHeRAz2h+VJNZ5Gmc/o7iD9k4wW7NMVqieYCY99oc0=
 github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=

From b7ea48057682f564e6e8955de95a5115e99f959b Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 12:44:04 -0400
Subject: [PATCH 088/200] refactor: simplify return statements

Signed-off-by: Deluan <deluan@navidrome.org>
---
 core/share.go                | 3 +--
 tests/mock_artist_repo.go    | 3 +--
 tests/mock_mediafile_repo.go | 3 +--
 3 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/core/share.go b/core/share.go
index 5a611c7f0..b2f32ba39 100644
--- a/core/share.go
+++ b/core/share.go
@@ -123,8 +123,7 @@ func (r *shareRepositoryWrapper) Save(entity any) (string, error) {
 
 	s.Contents = str.TruncateRunes(s.Contents, 30, "...")
 
-	id, err = r.Persistable.Save(s)
-	return id, err
+	return r.Persistable.Save(s)
 }
 
 func (r *shareRepositoryWrapper) Update(id string, entity any, _ ...string) error {
diff --git a/tests/mock_artist_repo.go b/tests/mock_artist_repo.go
index b71942208..af393129e 100644
--- a/tests/mock_artist_repo.go
+++ b/tests/mock_artist_repo.go
@@ -205,8 +205,7 @@ func (m *MockArtistRepo) Search(q string, options ...model.QueryOptions) (model.
 		return nil, errors.New("unexpected error")
 	}
 	// Simple mock implementation - just return all artists for testing
-	allArtists, err := m.GetAll()
-	return allArtists, err
+	return m.GetAll()
 }
 
 var _ model.ArtistRepository = (*MockArtistRepo)(nil)
diff --git a/tests/mock_mediafile_repo.go b/tests/mock_mediafile_repo.go
index 58e84785b..f18280fd5 100644
--- a/tests/mock_mediafile_repo.go
+++ b/tests/mock_mediafile_repo.go
@@ -319,8 +319,7 @@ func (m *MockMediaFileRepo) Search(q string, options ...model.QueryOptions) (mod
 		return nil, errors.New("unexpected error")
 	}
 	// Simple mock implementation - just return all media files for testing
-	allFiles, err := m.GetAll()
-	return allFiles, err
+	return m.GetAll()
 }
 
 // Cross-library move detection mock methods

From aee8a705b1a579e328b88672826ee0d68da80a27 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 14:25:36 -0400
Subject: [PATCH 089/200] build(docker): upgrade Alpine base image to 3.22
 (#6048)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Moves both the xx-build toolchain stage and the final runtime image from
Alpine 3.20 (past end of active support) to 3.22.

3.22 is the last release where ffmpeg is still 6.1.x — it jumps to 8.0 in
3.23 — so transcoding behavior is unchanged by this bump.

Alpine 3.21 repackaged mesa, and from that release on `mpv` requires
so:libEGL.so.1 and so:libgbm.so.1. Those pull mesa -> llvm20-libs (156MB)
plus the gallium drivers (62MB), which took the image from 231MB/62MB
compressed to 578MB/147MB. mesa-egl is the only provider of libEGL.so.1,
and newer Alpine releases do not improve on this.

Navidrome runs mpv headless for jukebox audio and never enters a video
path, so this replaces libEGL/libgbm with generated no-op stubs and drops
the mesa/LLVM stack. The stub symbol list is read from real mesa at build
time and cross-compiled with the existing xx toolchain, so it adapts per
architecture rather than being hardcoded.

Verified with logging stubs across mp3/flac/ogg/opus/m4a/wav driving the
default MPVCmdTemplate (pause, volume, time-pos seek, quit): zero calls
into the stubbed libraries. The final stage now also runs mpv once at
build time, so a broken stub fails the build instead of shipping.

Image size: 323MB -> 325MB (84MB -> 86MB compressed).
---
 Dockerfile | 39 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 3d7a03f5d..3427d6806 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -2,7 +2,7 @@ FROM --platform=$BUILDPLATFORM ghcr.io/crazy-max/osxcross:14.5-debian AS osxcros
 
 ########################################################################################################################
 ### Build xx (original image: tonistiigi/xx)
-FROM --platform=$BUILDPLATFORM alpine:3.20 AS xx-build
+FROM --platform=$BUILDPLATFORM alpine:3.22 AS xx-build
 
 # v1.9.0
 ENV XX_VERSION=a5592eab7a57895e8d385394ff12241bc65ecd50
@@ -152,19 +152,52 @@ RUN xx-verify --static /out/navidrome*
 FROM scratch AS binary
 COPY --from=build /out /
 
+########################################################################################################################
+### Build no-op stubs for mpv's video-output libraries
+# mpv links libEGL/libgbm for video output only; Navidrome drives it headless, for audio.
+# Real mesa pulls in LLVM + gallium (+218MB uncompressed), so ship stubs it never calls.
+FROM --platform=$BUILDPLATFORM alpine:3.22 AS mpv-stubs
+COPY --from=xx / /
+RUN apk add --no-cache clang lld binutils mesa-egl mesa-gbm
+ARG TARGETPLATFORM
+RUN xx-apk add --no-cache musl-dev
+RUN <<EOT
+    set -e
+    mkdir -p /out
+    for so in libEGL.so.1 libgbm.so.1; do
+        readelf -sW /usr/lib/$so \
+            | awk '$5 == "GLOBAL" && $7 != "UND" { print $8 }' \
+            | sed 's/@.*//' \
+            | grep -vE '^(_init|_fini|_edata|_end|__bss_start|_GLOBAL_OFFSET_TABLE_)$' \
+            | sort -u \
+            | awk '{ print "void " $1 "(void) {}" }' > /tmp/stub.c
+        test -s /tmp/stub.c
+        xx-clang -shared -nostdlib -fPIC -Wl,-soname,$so -o /out/$so /tmp/stub.c
+        xx-verify /out/$so
+    done
+EOT
+
 ########################################################################################################################
 ### Build Final Image
-FROM alpine:3.20 AS final
+FROM alpine:3.22 AS final
 LABEL maintainer="deluan@navidrome.org"
 LABEL org.opencontainers.image.source="https://github.com/navidrome/navidrome"
 
 # Install runtime dependencies
 # - libwebp + symlinks: enables native WebP encoding via purego/dlopen
+# The mesa/LLVM stack mpv pulls in for video output is dropped in this same layer,
+# otherwise the deleted bytes still ship in the image.
 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
+    done && \
+    rm -rf /usr/lib/gallium-pipe /usr/lib/dri \
+        /usr/lib/libEGL.so* /usr/lib/libgbm.so* /usr/lib/libgallium*.so /usr/lib/libLLVM.so* \
+        /usr/lib/libGL.so* /usr/lib/libGLESv2.so* /usr/lib/libglapi.so*
+
+COPY --from=mpv-stubs /out/ /usr/lib/
+RUN mpv --no-video --ao=null --version > /dev/null
 
 # Copy navidrome binary (musl build for Docker, enables native libwebp)
 COPY --from=build-alpine /out/navidrome /app/

From 46041bb90884b818c8dbcaf851855cb1ee1aeccd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 16:06:08 -0400
Subject: [PATCH 090/200] ci: cache the plugins test suite WASM compilation
 across runs (#6049)

* ci: cache the plugins test suite WASM compilation across runs

The 'Test Go code' job was dominated by a single package: 'plugins' took
541s of the 699s test step. The suite builds 25 test plugins as full-Go
wasip1 modules of ~4.5MB each, and wazero must compile every one to machine
code. Under -race that compiler work is instrumented, so each module costs
around 11 seconds.

The suite already shared a wazero compilation cache, but three things kept it
from paying off. It lived in a fresh temp dir, so nothing survived the run.
The default plugins.cachesize of 200MB was smaller than the 334MB the cache
actually needs, so the purge evicted entries mid-run. And the wasm binaries
embedded VCS stamps, so every commit produced different bytes and missed the
content-addressed cache anyway.

Point CacheFolder at plugins/testdata/.wazero-cache, raise the test cache
limit past what the suite needs, build the test plugins with -buildvcs=false,
and restore the directory in CI. Locally the package goes from 256s to 74s
with the cache warm and the wasm rebuilt from scratch.

* ci: key the WASM cache on what actually changes the modules

The test plugins are separate Go modules with their own go.mod and go.sum;
they reach the PDK through a replace directive and never read the root
module. So the root go.sum has no bearing on the wasm bytes, and the wazero
version it pins is already namespaced by wazero itself, which stores entries
under wazero-<version>-<goarch>-<goos>. Keying on it only rotated the cache
on every unrelated dependency bump.

Drop it, and add the go.mod files that were missing: the test plugins' own
and the PDK's. The root go.mod stays, since it selects the toolchain that
builds the modules.

* ci: key the WASM cache on the toolchain version, not go.mod

Only the Go toolchain in the root go.mod affects the built wasm, but the file
also changes on every direct dependency bump, which would rotate the cache for
no reason. Take setup-go's go-version output instead: it is the version that
actually built the modules.
---
 .github/workflows/pipeline.yml | 10 ++++++++++
 .gitignore                     |  5 ++++-
 plugins/plugins_suite_test.go  | 21 ++++++++-------------
 plugins/testdata/Makefile      |  6 ++++--
 4 files changed, 26 insertions(+), 16 deletions(-)

diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index b91c19505..012e3a9c3 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -131,12 +131,22 @@ jobs:
         uses: actions/checkout@v7
 
       - uses: actions/setup-go@v6
+        id: setup-go
         with:
           go-version-file: go.mod
 
       - name: Download dependencies
         run: go mod download
 
+      # Without this, the plugins suite recompiles every test plugin WASM module,
+      # which dominates the job runtime under -race.
+      - name: Cache the plugins test suite WASM compilation cache
+        uses: actions/cache@v6
+        with:
+          path: plugins/testdata/.wazero-cache
+          key: wazero-${{ runner.os }}-go${{ steps.setup-go.outputs.go-version }}-${{ hashFiles('plugins/testdata/*/*.go', 'plugins/testdata/*/go.*', 'plugins/pdk/go/**/*.go', 'plugins/pdk/go/go.*') }}
+          restore-keys: wazero-${{ runner.os }}-
+
       - name: Test
         run: go test -shuffle=on -tags netgo,sqlite_fts5 -race ./... -v
 
diff --git a/.gitignore b/.gitignore
index 6459ded9b..810074e72 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,4 +43,7 @@ go.work*
 .playwright-mcp/
 
 # Temp benchmark files
-zz_*_test.go
\ No newline at end of file
+zz_*_test.go
+
+# wazero compilation cache for the plugins test suite
+/plugins/testdata/.wazero-cache/
diff --git a/plugins/plugins_suite_test.go b/plugins/plugins_suite_test.go
index 77956e2f9..c8585f2c1 100644
--- a/plugins/plugins_suite_test.go
+++ b/plugins/plugins_suite_test.go
@@ -25,7 +25,10 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-const testDataDir = "plugins/testdata"
+const (
+	testDataDir    = "plugins/testdata"
+	wazeroCacheDir = ".wazero-cache"
+)
 
 // Shared test state initialized in BeforeSuite
 var (
@@ -38,18 +41,10 @@ func TestPlugins(t *testing.T) {
 	tests.Init(t, false)
 	buildTestPlugins(t, testDataDir)
 
-	// Create a shared wazero compilation cache directory.
-	// All test managers will point CacheFolder here so that WASM compilation
-	// is done once per binary and then reused from disk cache.
-	sharedCacheDir, err := os.MkdirTemp("", "plugins-shared-cache-*")
-	if err != nil {
-		t.Fatalf("Failed to create shared cache dir: %v", err)
-	}
-	t.Cleanup(func() { os.RemoveAll(sharedCacheDir) })
-
-	// Set CacheFolder globally so all tests (including those using
-	// configtest.SetupConfig) inherit it without needing to set it manually.
-	conf.Server.CacheFolder = conf.NewDir(sharedCacheDir)
+	// Set globally so tests using configtest.SetupConfig inherit it. The cache
+	// persists between runs; entries are content-addressed, so a stale one only misses.
+	conf.Server.CacheFolder = conf.NewDir(filepath.Join(testDataDir, wazeroCacheDir))
+	conf.Server.Plugins.CacheSize = "1GB" // the default evicts the cache mid-run
 
 	log.SetLevel(log.LevelFatal)
 	RegisterFailHandler(Fail)
diff --git a/plugins/testdata/Makefile b/plugins/testdata/Makefile
index d53f2aaee..758497095 100644
--- a/plugins/testdata/Makefile
+++ b/plugins/testdata/Makefile
@@ -10,6 +10,7 @@ all: $(PLUGINS:%=%.ndp)
 
 clean:
 	rm -f $(PLUGINS:%=%.ndp) $(PLUGINS:%=%.wasm)
+	rm -rf .wazero-cache
 
 # PDK source files that trigger rebuild when changed (recursive)
 PDK_SOURCES := $(shell find ../pdk/go -name '*.go' 2>/dev/null)
@@ -22,10 +23,11 @@ PDK_SOURCES := $(shell find ../pdk/go -name '*.go' 2>/dev/null)
 	@rm -f plugin.wasm
 	@mv $< $<.tmp && mv $<.tmp $<  # Touch wasm to ensure it's older than ndp
 
-# Build the wasm binary
+# Build the wasm binary. -buildvcs=false keeps the bytes stable across commits, so
+# the test suite's wazero compilation cache still hits after a rebuild.
 %.wasm: %/*.go %/go.mod $(PDK_SOURCES)
 ifdef TINYGO
 	cd $* && tinygo build -target wasip1 -buildmode=c-shared -o ../$@ .
 else
-	cd $* && GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o ../$@ .
+	cd $* && GOOS=wasip1 GOARCH=wasm go build -buildvcs=false -buildmode=c-shared -o ../$@ .
 endif
\ No newline at end of file

From a2de8e61efe82ec1d81d67d985026c083ad541fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 16:57:40 -0400
Subject: [PATCH 091/200] ci: run the plugins test suite in parallel processes
 (#6051)

* test(plugins): make the suite safe to run in parallel processes

Two things broke when the suite ran across several Ginkgo processes.

buildTestPlugins ran in every process, so N copies of make raced in the same
directory. The packaging rule made that worse by staging every plugin through
one shared plugin.wasm, so concurrent targets clobbered each other and left
orphaned temp files behind. That also ruled out make -j.

Stage each package under its own per-target directory, and move the build into
SynchronizedBeforeSuite so process 1 does it once while the others wait.

* ci: run the plugins suite in parallel processes

With the compilation cache warm the suite is bound by spec execution, which
splits cleanly across processes. Run it as its own step with the ginkgo CLI,
already declared as a tool in go.mod, and drop the package from the main go
test invocation so it is not run twice.

Locally, with -race: 69s to 19s warm, and 256s to 96s cold.

* ci: give the plugins suite its own job so it runs concurrently

Running it as a second step in the go job serialised it against the other 90
packages, which cancelled out the parallel win: the job went from 5m41s to
only 5m29s even though the suite itself dropped from ~175s to 82s.

Move it to its own job so the two run at the same time. The WASM compilation
cache moves with it, since the go job no longer runs the suite.
---
 .github/workflows/pipeline.yml | 38 +++++++++++++++++++++++-----------
 .gitignore                     |  1 +
 plugins/plugins_suite_test.go  | 20 ++++++++----------
 plugins/testdata/Makefile      | 10 +++++----
 4 files changed, 42 insertions(+), 27 deletions(-)

diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index 012e3a9c3..9da99e864 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -131,24 +131,14 @@ jobs:
         uses: actions/checkout@v7
 
       - uses: actions/setup-go@v6
-        id: setup-go
         with:
           go-version-file: go.mod
 
       - name: Download dependencies
         run: go mod download
 
-      # Without this, the plugins suite recompiles every test plugin WASM module,
-      # which dominates the job runtime under -race.
-      - name: Cache the plugins test suite WASM compilation cache
-        uses: actions/cache@v6
-        with:
-          path: plugins/testdata/.wazero-cache
-          key: wazero-${{ runner.os }}-go${{ steps.setup-go.outputs.go-version }}-${{ hashFiles('plugins/testdata/*/*.go', 'plugins/testdata/*/go.*', 'plugins/pdk/go/**/*.go', 'plugins/pdk/go/go.*') }}
-          restore-keys: wazero-${{ runner.os }}-
-
       - name: Test
-        run: go test -shuffle=on -tags netgo,sqlite_fts5 -race ./... -v
+        run: go test -shuffle=on -tags netgo,sqlite_fts5 -race -v $(go list ./... | grep -v '/plugins$')
 
       - name: Test ndpgen
         run: |
@@ -157,6 +147,30 @@ jobs:
           go build -o ndpgen .
           ./ndpgen --help
 
+  go-plugins:
+    name: Test Go plugins
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        id: setup-go
+        with:
+          go-version-file: go.mod
+
+      # Without this, the suite recompiles every test plugin WASM module,
+      # which dominates its runtime under -race.
+      - name: Cache the WASM compilation cache
+        uses: actions/cache@v6
+        with:
+          path: plugins/testdata/.wazero-cache
+          key: wazero-${{ runner.os }}-go${{ steps.setup-go.outputs.go-version }}-${{ hashFiles('plugins/testdata/*/*.go', 'plugins/testdata/*/go.*', 'plugins/pdk/go/**/*.go', 'plugins/pdk/go/go.*') }}
+          restore-keys: wazero-${{ runner.os }}-
+
+      - name: Test plugins
+        run: go tool ginkgo -p -race -tags netgo,sqlite_fts5 ./plugins/
+
   go-windows:
     name: Test Go code (Windows)
     runs-on: windows-2022
@@ -294,7 +308,7 @@ jobs:
 
   build:
     name: Build
-    needs: [js, go, go-windows, go-lint, i18n-lint, git-version, check-push-enabled, validate-migrations]
+    needs: [js, go, go-plugins, go-windows, go-lint, i18n-lint, git-version, check-push-enabled, validate-migrations]
     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 ]
diff --git a/.gitignore b/.gitignore
index 810074e72..4ed971491 100644
--- a/.gitignore
+++ b/.gitignore
@@ -47,3 +47,4 @@ zz_*_test.go
 
 # wazero compilation cache for the plugins test suite
 /plugins/testdata/.wazero-cache/
+/plugins/testdata/*.stage/
diff --git a/plugins/plugins_suite_test.go b/plugins/plugins_suite_test.go
index c8585f2c1..2dae65d00 100644
--- a/plugins/plugins_suite_test.go
+++ b/plugins/plugins_suite_test.go
@@ -7,6 +7,7 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"os"
 	"os/exec"
@@ -39,7 +40,6 @@ var (
 
 func TestPlugins(t *testing.T) {
 	tests.Init(t, false)
-	buildTestPlugins(t, testDataDir)
 
 	// Set globally so tests using configtest.SetupConfig inherit it. The cache
 	// persists between runs; entries are content-addressed, so a stale one only misses.
@@ -51,16 +51,11 @@ func TestPlugins(t *testing.T) {
 	RunSpecs(t, "Plugins Suite")
 }
 
-func buildTestPlugins(t *testing.T, path string) {
-	t.Helper()
+func buildTestPlugins(path string) {
 	start := time.Now()
-	t.Logf("[BeforeSuite] Current working directory: %s", path)
-	cmd := exec.Command("make", "-C", path)
-	out, err := cmd.CombinedOutput()
-	t.Logf("[BeforeSuite] Make output: %s elapsed: %s", string(out), time.Since(start))
-	if err != nil {
-		t.Fatalf("Failed to build test plugins: %v", err)
-	}
+	out, err := exec.Command("make", "-C", path).CombinedOutput()
+	fmt.Fprintf(GinkgoWriter, "[BeforeSuite] built test plugins in %s:\n%s", time.Since(start), out)
+	Expect(err).ToNot(HaveOccurred(), "failed to build test plugins")
 }
 
 // createTestManager creates a new plugin Manager with the given plugin config.
@@ -146,7 +141,10 @@ func createTestManagerWithPluginsAndMetrics(pluginConfig map[string]map[string]s
 	return manager, tmpDir
 }
 
-var _ = BeforeSuite(func() {
+var _ = SynchronizedBeforeSuite(func() {
+	// Build once: the testdata Makefile is not safe to run concurrently.
+	buildTestPlugins(testDataDir)
+}, func() {
 	// Get testdata directory (where test plugin .ndp packages live)
 	_, currentFile, _, ok := runtime.Caller(0)
 	Expect(ok).To(BeTrue())
diff --git a/plugins/testdata/Makefile b/plugins/testdata/Makefile
index 758497095..de948a2bb 100644
--- a/plugins/testdata/Makefile
+++ b/plugins/testdata/Makefile
@@ -10,17 +10,19 @@ all: $(PLUGINS:%=%.ndp)
 
 clean:
 	rm -f $(PLUGINS:%=%.ndp) $(PLUGINS:%=%.wasm)
-	rm -rf .wazero-cache
+	rm -rf .wazero-cache $(PLUGINS:%=%.stage)
 
 # PDK source files that trigger rebuild when changed (recursive)
 PDK_SOURCES := $(shell find ../pdk/go -name '*.go' 2>/dev/null)
 
 # Build the .ndp package (zip containing manifest.json + plugin.wasm)
+# Stage under a per-target name: a shared plugin.wasm breaks concurrent builds.
 %.ndp: %.wasm %/manifest.json
 	@rm -f $@
-	@cp $< plugin.wasm
-	zip -j $@ $*/manifest.json plugin.wasm
-	@rm -f plugin.wasm
+	@rm -rf $*.stage && mkdir -p $*.stage
+	@cp $< $*.stage/plugin.wasm
+	zip -j $@ $*/manifest.json $*.stage/plugin.wasm
+	@rm -rf $*.stage
 	@mv $< $<.tmp && mv $<.tmp $<  # Touch wasm to ensure it's older than ndp
 
 # Build the wasm binary. -buildvcs=false keeps the bytes stable across commits, so

From 9ff005862071ee16f60f1ca103397b993821201d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 21:24:50 -0400
Subject: [PATCH 092/200] fix: assorted scanner, plugin, and server fixes from
 the Go 1.27 work (#6050)

* fix(plugins): stop the cache janitor when a plugin cache is dropped

newCacheService started a ttlcache janitor goroutine that only stopped via the
explicit Close() path, so a cache service that was discarded without being closed
leaked its janitor for the process lifetime. It now registers the same
runtime.AddCleanup safety net that utils/cache.simpleCache already uses.

* fix(scanner): stop splitting multi-byte characters when truncating tags

sanitize() capped tag values with a byte slice, so a value whose limit falls in
the middle of a multi-byte character was stored as invalid UTF-8. defaultMaxTagLength
is 1024, which is not a multiple of 3, so any sufficiently long CJK title hit this.
Only trailing invalid bytes are trimmed, leaving bad bytes elsewhere in the value
untouched.

* fix(scanner): store MusicBrainz ids in their canonical form

uuid.Parse accepts a UUID wrapped in any two bytes, as well as braced and urn:
forms, but sanitize() returned the raw string. A tag like {<mbid>} or a quoted
value was therefore persisted with its wrapper into the mbz_* columns, where the
exact-match MBID search can never find it. The parsed value is now stored, which
also lowercases uppercase ids and adds the dashes to unhyphenated ones.

* fix(plugins): parse IPv6 hosts correctly in the websocket allowlist

isHostAllowed cut the host at the last colon, which mangles an IPv6 literal:
"[::1]:8080" became "[::1]" and "[::1]" became "[:". A plugin manifest could
therefore never allow an IPv6 host. It now uses net.SplitHostPort, falling back to
unwrapping the brackets when there is no port.

* fix(server): serve pprof profiles when a BaseURL is configured

net/http/pprof's Index resolves the profile name by trimming "/debug/pprof/" from
the raw request path, which never matches once MountRouter prepends the BasePath.
Requests for any profile without an explicit chi route fell through to the index
page, returning HTML with a 200 instead of the profile. The handler now strips the
BasePath first.

* test(scanner): run the goroutine leak check unconditionally

The scanner suite's goleak check only ran when the GOLEAK env var was set, so it
never ran in CI and could not catch a regression. It passes with the existing
ignore list, verified over repeated runs, so the gate is removed.

* fix(server): close the background image body on a non-200 response

serveImage returned early on an unexpected status code without closing the response
body, pinning the connection until the 5s client timeout. The nolint:bodyclose
above the request suppressed the linter that would have caught it, and its
justification only holds on the success path, where the body is handed to the
CachedStream wrapper.

* test(scanner): repair BenchmarkScan so it can actually run

The benchmark failed three ways before reaching its first iteration: it reused a
shared temp DB and tried to repoint the default library, it never loaded the config
defaults so the scanner got a concurrency of 0, and it lacked the notify ignore that
the suite already carries. tests.Init now takes a testing.TB so a benchmark can load
the test config the same way the suites do.

* refactor(artwork): drop the unused sourceFunc Stringer

sourceFunc.String derived a label from the closure's symbol name via reflection, but
nothing called it: the trace output builds its candidate labels from explicit strings.
Whole-program analysis confirms it is unreachable, and dropping it removes a
reflection-based dependency on compiler closure-naming details.

* refactor(plugins): reuse extractHostname in the websocket allowlist

The IPv6 host parsing added for isHostAllowed duplicated extractHostname, which
already lives in the same package and backs the HTTP client's identical allowlist
check. Two copies of a security-relevant parser can drift, so the websocket service
now calls the existing helper. The port-stripping specs move into the URL Validation
block that already covered them.

* perf(scanner): bound the tag truncation trim to a partial rune

The trim loop dropped every trailing byte that failed to decode, so a value ending
in a long run of invalid bytes was walked one byte at a time: a 1 MiB lyrics tag
measured 2.58ms against 45ns for a normal cut. A partial rune is at most 3 trailing
bytes, so the loop is capped there, which also stops it consuming a pre-existing
invalid run.

* test: tighten the tests added with the Go 1.27 bugfixes

Drop the testItem stub in favour of the package's own cacheKey, register the pprof
test profile once at package scope, and replace the hand-rolled goroutine settle
loop with Eventually. Also corrects a comment that credited a TestMain the scanner
suite does not have.

* test(scanner): ignore notify's nonrecursive-tree goroutines on Linux

The goroutine leak check only ignored the recursive tree (macOS/FSEvents).
Linux CI uses inotify, whose nonrecursive tree leaks dispatch and internal
goroutines after Stop(), failing the check.

* fix(scanner): avoid a truncation panic when MaxLength is 1 or 2

A value of only UTF-8 continuation bytes drained the partial-rune loop to
empty, then sliced value[:-1] and panicked. Break when DecodeLastRune returns
size 0 (empty string) by testing size != 1 instead of size > 1.

* fix: address Codex review on the pprof base path and scan benchmark

- profilerHandler: treat a root BasePath ("/") as no prefix, so http.StripPrefix
  keeps the leading slash chi needs; without this the profiler 404s when BaseURL
  is "/". Cover the root case in the test.
- BenchmarkScan: make it run regardless of test/benchmark ordering. Add
  singleton.DeleteInstance so a fresh DB is opened after TestScanner closes the
  shared one, guard driver registration with sync.Once so the rebuild does not
  re-Register, and ignore the Ginkgo interrupt-handler and Linux notify
  goroutines the preceding suite leaves behind.

* fix: address Codex round 2 on BasePath trailing slash and benchmark DB cleanup

- profilerHandler: trim all trailing slashes (TrimRight), not just a bare "/", so
  a BaseURL like "/music/" strips correctly instead of 404ing. Cover it in the test.
- BenchmarkScan: keep and defer db.Init's closer so the DB is closed before
  b.TempDir cleanup, which otherwise cannot delete the open SQLite/WAL files on Windows.
---
 cmd/root.go                                  | 11 +++-
 cmd/root_test.go                             | 46 +++++++++++++
 core/artwork/sources.go                      | 12 ----
 db/db.go                                     | 21 ++++--
 model/metadata/metadata.go                   | 14 +++-
 model/metadata/metadata_internal_test.go     | 20 ++++++
 model/metadata/metadata_test.go              | 38 +++++++++++
 plugins/host_cache.go                        | 10 ++-
 plugins/host_cache_test.go                   | 34 ++++++++++
 plugins/host_websocket.go                    |  6 +-
 plugins/host_websocket_test.go               | 26 ++++----
 scanner/scanner_benchmark_test.go            | 22 ++++++-
 scanner/scanner_suite_test.go                | 20 +++---
 server/backgrounds/backgrounds_suite_test.go | 17 +++++
 server/backgrounds/handler.go                |  3 +-
 server/backgrounds/handler_test.go           | 68 ++++++++++++++++++++
 tests/init_tests.go                          |  2 +-
 utils/singleton/singleton.go                 | 10 +++
 18 files changed, 323 insertions(+), 57 deletions(-)
 create mode 100644 cmd/root_test.go
 create mode 100644 model/metadata/metadata_internal_test.go
 create mode 100644 server/backgrounds/backgrounds_suite_test.go
 create mode 100644 server/backgrounds/handler_test.go

diff --git a/cmd/root.go b/cmd/root.go
index ff1641bd3..94f861f40 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"context"
+	"net/http"
 	"os"
 	"os/signal"
 	"strings"
@@ -138,7 +139,7 @@ func startServer(ctx context.Context) func() error {
 			a.MountRouter("Prometheus metrics", conf.Server.Prometheus.MetricsPath, p.GetHandler())
 		}
 		if conf.Server.DevEnableProfiler {
-			a.MountRouter("Profiling", "/debug", middleware.Profiler())
+			a.MountRouter("Profiling", "/debug", profilerHandler())
 		}
 		if strings.HasPrefix(conf.Server.UILoginBackgroundURL, "/") {
 			a.MountRouter("Background images", conf.Server.UILoginBackgroundURL, backgrounds.NewHandler())
@@ -147,6 +148,14 @@ func startServer(ctx context.Context) func() error {
 	}
 }
 
+// profilerHandler returns the pprof handler. net/http/pprof resolves the profile
+// name from the raw request path, so the BasePath has to come off first.
+func profilerHandler() http.Handler {
+	// A trailing or root slash would make StripPrefix drop the leading slash chi needs.
+	basePath := strings.TrimRight(conf.Server.BasePath, "/")
+	return http.StripPrefix(basePath, middleware.Profiler())
+}
+
 // schedulePeriodicScan schedules a periodic scan of the music library, if configured.
 func schedulePeriodicScan(ctx context.Context) func() error {
 	return func() error {
diff --git a/cmd/root_test.go b/cmd/root_test.go
new file mode 100644
index 000000000..af8d44e7e
--- /dev/null
+++ b/cmd/root_test.go
@@ -0,0 +1,46 @@
+package cmd
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"path"
+	"runtime/pprof"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = pprof.NewProfile("nd-profiler-test")
+
+var _ = Describe("profilerHandler", func() {
+	// Mirrors how server.MountRouter mounts the handler.
+	mount := func() http.Handler {
+		router := chi.NewRouter()
+		router.Mount(path.Join(conf.Server.BasePath, "/debug"), profilerHandler())
+		return router
+	}
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+	})
+
+	DescribeTable("serves a named profile",
+		func(basePath string) {
+			conf.Server.BasePath = basePath
+
+			w := httptest.NewRecorder()
+			target := path.Join(basePath, "/debug/pprof/nd-profiler-test") + "?debug=1"
+			mount().ServeHTTP(w, httptest.NewRequest(http.MethodGet, target, nil))
+
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(w.Body.String()).To(HavePrefix("nd-profiler-test profile: total 0"))
+		},
+		Entry("without a BasePath", ""),
+		Entry("with a BasePath", "/music"),
+		Entry("with a root BasePath", "/"),
+		Entry("with a trailing-slash BasePath", "/music/"),
+	)
+})
diff --git a/core/artwork/sources.go b/core/artwork/sources.go
index 069b7bf5a..f2abf9da5 100644
--- a/core/artwork/sources.go
+++ b/core/artwork/sources.go
@@ -10,9 +10,7 @@ import (
 	"net/http"
 	"net/url"
 	"path/filepath"
-	"reflect"
 	"regexp"
-	"runtime"
 	"strings"
 	"time"
 
@@ -29,16 +27,6 @@ var errSourceUnreadable = errors.New("artwork source unreadable")
 
 type sourceFunc func() (r io.ReadCloser, path string, err error)
 
-func (f sourceFunc) String() string {
-	name := runtime.FuncForPC(reflect.ValueOf(f).Pointer()).Name()
-	name = strings.TrimPrefix(name, "github.com/navidrome/navidrome/core/artwork.")
-	if _, after, found := strings.Cut(name, ")."); found {
-		name = after
-	}
-	name = strings.TrimSuffix(name, ".func1")
-	return name
-}
-
 func fromExternalFile(ctx context.Context, libFS fs.FS, files []string, pattern string) sourceFunc {
 	return func() (io.ReadCloser, string, error) {
 		var openErr error
diff --git a/db/db.go b/db/db.go
index a325dd3f5..c53aa364a 100644
--- a/db/db.go
+++ b/db/db.go
@@ -6,6 +6,7 @@ import (
 	"embed"
 	"errors"
 	"fmt"
+	"sync"
 	"time"
 
 	"github.com/mattn/go-sqlite3"
@@ -33,15 +34,21 @@ var embedMigrations embed.FS
 
 const migrationsFolder = "migrations"
 
+// sql.Register panics if called twice, so guard it: the singleton instance can be reset
+// (tests/benchmarks) and rebuilt, but the driver is process-global and registers only once.
+var registerDriverOnce sync.Once
+
 func Db() *sql.DB {
 	return singleton.GetInstance(func() *sql.DB {
-		sql.Register(Driver, &sqlite3.SQLiteDriver{
-			ConnectHook: func(conn *sqlite3.SQLiteConn) error {
-				if err := conn.RegisterFunc("SEEDEDRAND", hasher.HashFunc(), false); err != nil {
-					return err
-				}
-				return conn.RegisterCollation(NaturalCollation, natural.CompareFold)
-			},
+		registerDriverOnce.Do(func() {
+			sql.Register(Driver, &sqlite3.SQLiteDriver{
+				ConnectHook: func(conn *sqlite3.SQLiteConn) error {
+					if err := conn.RegisterFunc("SEEDEDRAND", hasher.HashFunc(), false); err != nil {
+						return err
+					}
+					return conn.RegisterCollation(NaturalCollation, natural.CompareFold)
+				},
+			})
 		})
 		Path = conf.Server.DbPath
 		if Path == ":memory:" {
diff --git a/model/metadata/metadata.go b/model/metadata/metadata.go
index 729e83564..0efbe94ec 100644
--- a/model/metadata/metadata.go
+++ b/model/metadata/metadata.go
@@ -9,6 +9,7 @@ import (
 	"strconv"
 	"strings"
 	"time"
+	"unicode/utf8"
 
 	"github.com/google/uuid"
 	"github.com/navidrome/navidrome/consts"
@@ -366,6 +367,14 @@ func sanitize(filePath string, tagName model.TagName, tag model.TagConf, value s
 	if len(value) > maxLength {
 		log.Trace("Truncated tag value", "tag", tagName, "value", value, "length", len(value), "maxLength", maxLength)
 		value = value[:maxLength]
+		// Drop the partial rune the cut may have left: at most 3 trailing bytes,
+		// so a pre-existing invalid run elsewhere is never consumed.
+		for range 3 {
+			if r, size := utf8.DecodeLastRuneInString(value); r != utf8.RuneError || size != 1 {
+				break
+			}
+			value = value[:len(value)-1]
+		}
 	}
 
 	switch tag.Type {
@@ -387,11 +396,14 @@ func sanitize(filePath string, tagName model.TagName, tag model.TagConf, value s
 			return ""
 		}
 	case model.TagTypeUUID:
-		_, err := uuid.Parse(value)
+		u, err := uuid.Parse(value)
 		if err != nil {
 			log.Trace("Invalid UUID tag value", "tag", tagName, "value", value)
 			return ""
 		}
+		// Store the canonical form: uuid.Parse accepts braces, urn: prefixes and any
+		// two-byte wrapper, and a wrapped value would never match an exact-match query
+		value = u.String()
 	}
 	return value
 }
diff --git a/model/metadata/metadata_internal_test.go b/model/metadata/metadata_internal_test.go
new file mode 100644
index 000000000..99fbba328
--- /dev/null
+++ b/model/metadata/metadata_internal_test.go
@@ -0,0 +1,20 @@
+package metadata
+
+import (
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = DescribeTable("sanitize truncation with a tiny MaxLength",
+	// A value of only continuation bytes drains the partial-rune loop to empty; the loop
+	// must stop there instead of slicing value[:-1] and panicking.
+	func(maxLength int, value string) {
+		Expect(func() {
+			Expect(sanitize("file.mp3", "title", model.TagConf{MaxLength: maxLength}, value)).To(Equal(""))
+		}).NotTo(Panic())
+	},
+	Entry("maxLength 1", 1, "\x80\x80"),
+	Entry("maxLength 2", 2, "\x80\x80\x80"),
+	Entry("maxLength 3", 3, "\x80\x80\x80\x80"),
+)
diff --git a/model/metadata/metadata_test.go b/model/metadata/metadata_test.go
index 7ebe9fa4a..09a2dfde0 100644
--- a/model/metadata/metadata_test.go
+++ b/model/metadata/metadata_test.go
@@ -4,6 +4,7 @@ import (
 	"os"
 	"strings"
 	"time"
+	"unicode/utf8"
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/metadata"
@@ -122,6 +123,43 @@ var _ = Describe("Metadata", func() {
 				Expect(pair[0].Value()).To(HaveLen(1048570))
 			})
 
+			It("should not split a multi-byte character when truncating", func() {
+				// 1024 is not a multiple of 3, so a byte-wise cut lands mid-rune.
+				props.Tags = model.RawTags{
+					"Title": {strings.Repeat("日", 2048)},
+				}
+				md = metadata.New(filePath, props)
+
+				title := md.String(model.TagTitle)
+				Expect(utf8.ValidString(title)).To(BeTrue(), "truncation produced invalid UTF-8")
+				Expect(len(title)).To(BeNumerically("<=", 1024))
+			})
+
+			It("should keep invalid bytes that are not at the truncation point", func() {
+				props.Tags = model.RawTags{
+					"Title": {"a\xffb" + strings.Repeat("c", 2048)},
+				}
+				md = metadata.New(filePath, props)
+
+				Expect(md.String(model.TagTitle)).To(HaveLen(1024))
+			})
+
+			DescribeTable("should normalize UUID tags to their canonical form",
+				func(raw, expected string) {
+					props.Tags = model.RawTags{"musicbrainz_artistid": {raw}}
+					md = metadata.New(filePath, props)
+
+					Expect(md.String(model.TagMusicBrainzArtistID)).To(Equal(expected))
+				},
+				Entry("canonical", "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"),
+				Entry("uppercase", "F81D4FAE-7DEC-11D0-A765-00A0C91E6BF6", "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"),
+				Entry("braced", "{f81d4fae-7dec-11d0-a765-00a0c91e6bf6}", "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"),
+				Entry("urn prefix", "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"),
+				Entry("quoted", `"f81d4fae-7dec-11d0-a765-00a0c91e6bf6"`, "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"),
+				Entry("no dashes", "f81d4fae7dec11d0a76500a0c91e6bf6", "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"),
+				Entry("not a uuid", "the beatles", ""),
+			)
+
 			It("should split multiple values", func() {
 				props.Tags = model.RawTags{
 					"Genre": {"Rock/Pop;;Punk"},
diff --git a/plugins/host_cache.go b/plugins/host_cache.go
index b90d790cf..f410dfd3d 100644
--- a/plugins/host_cache.go
+++ b/plugins/host_cache.go
@@ -2,6 +2,7 @@ package plugins
 
 import (
 	"context"
+	"runtime"
 	"time"
 
 	"github.com/jellydator/ttlcache/v3"
@@ -29,11 +30,18 @@ func newCacheService(pluginName string) *cacheServiceImpl {
 	// Start the janitor goroutine to clean up expired entries
 	go cache.Start()
 
-	return &cacheServiceImpl{
+	svc := &cacheServiceImpl{
 		pluginName: pluginName,
 		cache:      cache,
 		defaultTTL: defaultCacheTTL,
 	}
+
+	// Automatic cleanup to prevent goroutine leak when the service is garbage collected
+	runtime.AddCleanup(svc, func(ttlCache *ttlcache.Cache[string, any]) {
+		ttlCache.Stop()
+	}, cache)
+
+	return svc
 }
 
 // getTTL converts seconds to a duration, using default if 0 or negative
diff --git a/plugins/host_cache_test.go b/plugins/host_cache_test.go
index cf3973fc4..5e91b04ec 100644
--- a/plugins/host_cache_test.go
+++ b/plugins/host_cache_test.go
@@ -8,9 +8,11 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"net/http"
 	"os"
 	"path/filepath"
+	"runtime"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -599,3 +601,35 @@ var _ = Describe("CacheService Integration", Ordered, func() {
 		})
 	})
 })
+
+var _ = Describe("newCacheService", func() {
+	// The suite above leaves goroutines winding down, so settle before sampling.
+	settledBaseline := func() int {
+		var n int
+		Eventually(func() int {
+			runtime.GC()
+			prev := n
+			n = runtime.NumGoroutine()
+			return n - prev
+		}).WithTimeout(10 * time.Second).WithPolling(20 * time.Millisecond).Should(BeZero())
+		return n
+	}
+
+	It("stops the janitor goroutine once the service is unreachable", func() {
+		const numServices = 5
+		baseline := settledBaseline()
+
+		func() {
+			services := make([]*cacheServiceImpl, 0, numServices)
+			for i := range numServices {
+				services = append(services, newCacheService(fmt.Sprintf("plugin_%d", i)))
+			}
+			Expect(runtime.NumGoroutine()).To(BeNumerically(">=", baseline+numServices),
+				"expected one janitor goroutine per cache service")
+		}()
+
+		Eventually(func() int { runtime.GC(); return runtime.NumGoroutine() }).
+			WithTimeout(10*time.Second).WithPolling(20*time.Millisecond).
+			Should(BeNumerically("<=", baseline), "janitor goroutines leaked")
+	})
+})
diff --git a/plugins/host_websocket.go b/plugins/host_websocket.go
index 90403f4c0..82aded0cb 100644
--- a/plugins/host_websocket.go
+++ b/plugins/host_websocket.go
@@ -243,11 +243,7 @@ func (s *webSocketServiceImpl) getConnection(connectionID string) (*wsConnection
 }
 
 func (s *webSocketServiceImpl) isHostAllowed(host string) bool {
-	// Strip port from host if present
-	hostWithoutPort := host
-	if idx := strings.LastIndex(host, ":"); idx != -1 {
-		hostWithoutPort = host[:idx]
-	}
+	hostWithoutPort := extractHostname(host)
 
 	for _, pattern := range s.requiredHosts {
 		if matchHostPattern(pattern, hostWithoutPort) {
diff --git a/plugins/host_websocket_test.go b/plugins/host_websocket_test.go
index e41cfbb82..2aa85cd21 100644
--- a/plugins/host_websocket_test.go
+++ b/plugins/host_websocket_test.go
@@ -144,20 +144,18 @@ var _ = Describe("WebSocketService", Ordered, func() {
 			Expect(allowed).To(BeFalse())
 		})
 
-		It("should strip port before checking host", func() {
-			// Implementation strips port before matching against patterns
-			// test-websocket manifest has "localhost:*" which matches "localhost"
-			// after port stripping
-			// Note: The port wildcard pattern isn't actually implemented, but
-			// since port is stripped, "localhost:*" is compared against "localhost"
-			// which won't match. To make localhost work, we'd need exact "localhost"
-			// in the allowed hosts list.
-
-			// Testing that port is properly stripped
-			// The pattern "localhost:*" won't match "localhost" due to exact match
-			allowed := testService.isHostAllowed("localhost:8080")
-			Expect(allowed).To(BeFalse())
-		})
+		DescribeTable("should match against the host with its port stripped",
+			func(allowed []string, host string, expected bool) {
+				svc := &webSocketServiceImpl{requiredHosts: allowed}
+				Expect(svc.isHostAllowed(host)).To(Equal(expected))
+			},
+			Entry("hostname with port", []string{"example.com"}, "example.com:8080", true),
+			Entry("IPv6 with port", []string{"::1"}, "[::1]:8080", true),
+			Entry("IPv6 without port", []string{"::1"}, "[::1]", true),
+			Entry("host not in the list", []string{"::2"}, "[::1]:8080", false),
+			// "localhost:*" is matched against the stripped "localhost", so it never hits
+			Entry("port wildcards are not supported", []string{"localhost:*"}, "localhost:8080", false),
+		)
 	})
 
 	Describe("Connection Management", func() {
diff --git a/scanner/scanner_benchmark_test.go b/scanner/scanner_benchmark_test.go
index ca1064631..65410d500 100644
--- a/scanner/scanner_benchmark_test.go
+++ b/scanner/scanner_benchmark_test.go
@@ -2,8 +2,8 @@ package scanner_test
 
 import (
 	"context"
+	"database/sql"
 	"fmt"
-	"os"
 	"path/filepath"
 	"runtime"
 	"testing"
@@ -21,6 +21,8 @@ import (
 	"github.com/navidrome/navidrome/persistence"
 	"github.com/navidrome/navidrome/scanner"
 	"github.com/navidrome/navidrome/server/events"
+	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/singleton"
 	"go.uber.org/goleak"
 )
 
@@ -31,11 +33,25 @@ func BenchmarkScan(b *testing.B) {
 		goleak.IgnoreAnyFunction("testing.(*B).doBench"),
 		// Ignore database/sql.(*DB).connectionOpener, as we are not closing the database connection
 		goleak.IgnoreAnyFunction("database/sql.(*DB).connectionOpener"),
+		// A preceding TestScanner leaves Ginkgo's interrupt handler running.
+		goleak.IgnoreTopFunction("github.com/onsi/ginkgo/v2/internal/interrupt_handler.(*InterruptHandler).registerForInterrupts.func2"),
+		// The notify library keeps watcher goroutines alive after Stop(); recursive on macOS, nonrecursive on Linux.
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*recursiveTree).dispatch"),
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*nonrecursiveTree).dispatch"),
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*nonrecursiveTree).internal"),
 	)
 
-	tmpDir := os.TempDir()
+	tests.Init(b, false)
+
+	tmpDir := b.TempDir()
 	conf.Server.DbPath = filepath.Join(tmpDir, "test-scanner.db?_journal_mode=WAL")
-	db.Init(context.Background())
+	// The default library is seeded from MusicFolder, and its path cannot be changed afterwards
+	conf.Server.MusicFolder = "fake:///music"
+	// TestScanner may run first and close the shared DB singleton; drop it so db.Init
+	// opens a fresh one whether or not the test suite ran before this benchmark.
+	singleton.DeleteInstance[*sql.DB]()
+	// Close before b.TempDir cleanup runs, or Windows cannot delete the open DB/WAL files.
+	defer db.Init(context.Background())()
 
 	ds := persistence.New(db.Db())
 	conf.Server.DevExternalScanner = false
diff --git a/scanner/scanner_suite_test.go b/scanner/scanner_suite_test.go
index 10be0401f..07ffd6e3a 100644
--- a/scanner/scanner_suite_test.go
+++ b/scanner/scanner_suite_test.go
@@ -3,7 +3,6 @@ package scanner_test
 import (
 	"context"
 	"io/fs"
-	"os"
 	"testing"
 
 	"github.com/navidrome/navidrome/consts"
@@ -31,16 +30,15 @@ func init() {
 }
 
 func TestScanner(t *testing.T) {
-	// Only run goleak checks when the GOLEAK env var is set
-	if os.Getenv("GOLEAK") != "" {
-		// Detect any goroutine leaks in the scanner code under test
-		defer goleak.VerifyNone(t,
-			goleak.IgnoreTopFunction("github.com/onsi/ginkgo/v2/internal/interrupt_handler.(*InterruptHandler).registerForInterrupts.func2"),
-			// The notify library creates internal goroutines for file watching that persist after Stop() is called.
-			// These are created by the plugins package tests and are expected behavior.
-			goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*recursiveTree).dispatch"),
-		)
-	}
+	// Detect any goroutine leaks in the scanner code under test
+	defer goleak.VerifyNone(t,
+		goleak.IgnoreTopFunction("github.com/onsi/ginkgo/v2/internal/interrupt_handler.(*InterruptHandler).registerForInterrupts.func2"),
+		// The notify library keeps internal goroutines alive after Stop(). The backend picks the tree per
+		// platform: recursive on macOS (FSEvents), nonrecursive on Linux (inotify), so ignore both.
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*recursiveTree).dispatch"),
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*nonrecursiveTree).dispatch"),
+		goleak.IgnoreTopFunction("github.com/rjeczalik/notify.(*nonrecursiveTree).internal"),
+	)
 
 	tests.Init(t, true)
 	defer db.Close(context.Background())
diff --git a/server/backgrounds/backgrounds_suite_test.go b/server/backgrounds/backgrounds_suite_test.go
new file mode 100644
index 000000000..5ad81907b
--- /dev/null
+++ b/server/backgrounds/backgrounds_suite_test.go
@@ -0,0 +1,17 @@
+package backgrounds
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestBackgrounds(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Backgrounds Suite")
+}
diff --git a/server/backgrounds/handler.go b/server/backgrounds/handler.go
index f6e159b4b..dcaaa9c66 100644
--- a/server/backgrounds/handler.go
+++ b/server/backgrounds/handler.go
@@ -81,7 +81,7 @@ func (h *Handler) serveImage(ctx context.Context, item cache.Item) (io.Reader, e
 	}
 	c := httpclient.New(imageRequestTimeout)
 	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, imageURL(image), nil)
-	resp, err := c.Do(req) //nolint:bodyclose,gosec // No need to close resp.Body, it will be closed via the CachedStream wrapper
+	resp, err := c.Do(req) //nolint:bodyclose,gosec // On success the body is closed via the CachedStream wrapper
 	if errors.Is(err, context.DeadlineExceeded) {
 		defaultImage, _ := base64.StdEncoding.DecodeString(consts.DefaultUILoginBackgroundOffline)
 		return strings.NewReader(string(defaultImage)), nil
@@ -90,6 +90,7 @@ func (h *Handler) serveImage(ctx context.Context, item cache.Item) (io.Reader, e
 		return nil, fmt.Errorf("could not get background image from hosting service: %w", err)
 	}
 	if resp.StatusCode != http.StatusOK {
+		_ = resp.Body.Close()
 		return nil, fmt.Errorf("unexpected status code getting background image from hosting service: %d", resp.StatusCode)
 	}
 	log.Debug(ctx, "Got background image from hosting service", "image", image, "elapsed", time.Since(start))
diff --git a/server/backgrounds/handler_test.go b/server/backgrounds/handler_test.go
new file mode 100644
index 000000000..e8c77380f
--- /dev/null
+++ b/server/backgrounds/handler_test.go
@@ -0,0 +1,68 @@
+package backgrounds
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type recordingBody struct {
+	io.Reader
+	closed *bool
+}
+
+func (b recordingBody) Close() error {
+	*b.closed = true
+	return nil
+}
+
+type stubTransport struct {
+	statusCode int
+	closed     *bool
+}
+
+func (t stubTransport) RoundTrip(*http.Request) (*http.Response, error) {
+	return &http.Response{
+		StatusCode: t.statusCode,
+		Header:     make(http.Header),
+		Body:       recordingBody{Reader: strings.NewReader("image-bytes"), closed: t.closed},
+	}, nil
+}
+
+var _ = Describe("serveImage", func() {
+	var closed bool
+
+	BeforeEach(func() {
+		closed = false
+	})
+
+	stubStatus := func(statusCode int) {
+		original := http.DefaultTransport
+		http.DefaultTransport = stubTransport{statusCode: statusCode, closed: &closed}
+		DeferCleanup(func() { http.DefaultTransport = original })
+	}
+
+	It("closes the response body when the hosting service returns an error", func() {
+		stubStatus(http.StatusNotFound)
+
+		_, err := (&Handler{}).serveImage(context.Background(), cacheKey("some-image.webp"))
+
+		Expect(err).To(MatchError(ContainSubstring("unexpected status code")))
+		Expect(closed).To(BeTrue(), "response body was left open")
+	})
+
+	It("hands the still-open body to the caller on success", func() {
+		stubStatus(http.StatusOK)
+
+		reader, err := (&Handler{}).serveImage(context.Background(), cacheKey("some-image.webp"))
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(closed).To(BeFalse(), "response body must stay open for the CachedStream wrapper")
+		body, _ := io.ReadAll(reader)
+		Expect(string(body)).To(Equal("image-bytes"))
+	})
+})
diff --git a/tests/init_tests.go b/tests/init_tests.go
index 582ad95fc..902cf196d 100644
--- a/tests/init_tests.go
+++ b/tests/init_tests.go
@@ -13,7 +13,7 @@ import (
 
 var once sync.Once
 
-func Init(t *testing.T, skipOnShort bool) {
+func Init(t testing.TB, skipOnShort bool) {
 	if skipOnShort && testing.Short() {
 		t.Skip("skipping test in short mode.")
 	}
diff --git a/utils/singleton/singleton.go b/utils/singleton/singleton.go
index 83f8c53ab..8271034ad 100644
--- a/utils/singleton/singleton.go
+++ b/utils/singleton/singleton.go
@@ -67,3 +67,13 @@ func GetInstance[T any](constructor func() T) T {
 
 	return newInstance
 }
+
+// DeleteInstance drops the cached instance of type T so the next GetInstance rebuilds it.
+// Intended for tests and benchmarks that need a fresh instance regardless of run order.
+func DeleteInstance[T any]() {
+	var v T
+	name := reflect.TypeOf(v).String()
+	lock.Lock()
+	delete(instances, name)
+	lock.Unlock()
+}

From dbd26ba2e71d0a5b79dba873a2beeff59f1cd8dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 30 Aug 2026 22:17:25 -0400
Subject: [PATCH 093/200] perf(scanner): improve playlist importing on large
 libraries (#6055)

* perf(persistence): avoid a full media_file scan when resolving playlist paths

FindByPaths built one OR-ed equality term per path. On the real media_file
schema SQLite abandons the path index at just two OR-ed terms and falls back to
SCAN media_file, re-testing every term against every row, so the cost grows with
(rows x terms).

Group the candidates by library and emit one IN list per library instead, which
plans as SEARCH media_file USING INDEX media_file_path_nocase. The NOCASE
collation is kept so ASCII case-insensitive matching still works.

This is the dominant cost of M3U playlist import, which resolves every track on
every scan. Measured with a 1000-track playlist against a migrated DB:

  100k media_file rows:   397 -> 51,414 tracks/sec
  500k media_file rows:  78.5 -> 47,174 tracks/sec

The rate no longer degrades as the table grows, which is the expected shape for
an index lookup. Reported in #6043, where an 8 hour scan of a 2M-song library
spent 7h52m in the playlist phase.

* docs(playlists): correct the stale reason for the M3U lookup chunk size

The expression-tree depth ceiling applied to the old OR-per-path query, which
capped a batch at roughly 500 terms. The IN form is bound by SQLite's 32766
variable limit instead, which the 400 candidates per chunk sit far below.
---
 core/playlists/parse_m3u.go              |  4 ++--
 persistence/mediafile_repository.go      | 25 +++++++++++++++++-------
 persistence/mediafile_repository_test.go | 22 +++++++++++++++++++++
 3 files changed, 42 insertions(+), 9 deletions(-)

diff --git a/core/playlists/parse_m3u.go b/core/playlists/parse_m3u.go
index a64c337c9..286f2e420 100644
--- a/core/playlists/parse_m3u.go
+++ b/core/playlists/parse_m3u.go
@@ -25,8 +25,8 @@ func (s *playlists) parseM3U(ctx context.Context, pls *model.Playlist, folder *m
 		return err
 	}
 	var mfs model.MediaFiles
-	// Chunk size of 100 lines, as each line can generate up to 4 lookup candidates
-	// (NFC/NFD × raw/lowercase), and SQLite has a max expression tree depth of 1000.
+	// Chunked so a huge playlist is not held in memory at once. Each line yields up to
+	// 4 lookup candidates (NFC/NFD × raw/lowercase), far below SQLite's 32766 variables.
 	for lines := range slice.CollectChunks(slice.LinesFrom(reader), 100) {
 		filteredLines := make([]string, 0, len(lines))
 		for _, line := range lines {
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index 320b95ef2..ed18333de 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"iter"
+	"maps"
 	"slices"
 	"strconv"
 	"strings"
@@ -355,7 +356,10 @@ func (r *mediaFileRepository) GetCursorWithArtwork(options ...model.QueryOptions
 // Library-qualified paths search within the specified library, while unqualified paths
 // search across all libraries for backward compatibility.
 func (r *mediaFileRepository) FindByPaths(paths []string) (model.MediaFiles, error) {
-	query := Or{}
+	// One IN list per library instead of one OR term per path: SQLite abandons the
+	// path index at just two OR-ed equality terms and scans the whole table.
+	byLibrary := map[int][]string{}
+	var unqualified []string
 
 	for _, path := range paths {
 		parts := strings.SplitN(path, ":", 2)
@@ -366,17 +370,24 @@ func (r *mediaFileRepository) FindByPaths(paths []string) (model.MediaFiles, err
 				// Invalid format, skip
 				continue
 			}
-			relativePath := parts[1]
-			query = append(query, And{
-				Eq{"path collate nocase": relativePath},
-				Eq{"library_id": libraryID},
-			})
+			byLibrary[libraryID] = append(byLibrary[libraryID], parts[1])
 		} else {
 			// Unqualified path: search across all libraries
-			query = append(query, Eq{"path collate nocase": path})
+			unqualified = append(unqualified, path)
 		}
 	}
 
+	query := Or{}
+	for _, libraryID := range slices.Sorted(maps.Keys(byLibrary)) {
+		query = append(query, And{
+			Eq{"path collate nocase": byLibrary[libraryID]},
+			Eq{"library_id": libraryID},
+		})
+	}
+	if len(unqualified) > 0 {
+		query = append(query, Eq{"path collate nocase": unqualified})
+	}
+
 	if len(query) == 0 {
 		return model.MediaFiles{}, nil
 	}
diff --git a/persistence/mediafile_repository_test.go b/persistence/mediafile_repository_test.go
index c1a91c5a5..8a492a813 100644
--- a/persistence/mediafile_repository_test.go
+++ b/persistence/mediafile_repository_test.go
@@ -1055,6 +1055,28 @@ var _ = Describe("MediaRepository", func() {
 				Expect(results).To(HaveLen(1))
 				Expect(results[0].ID).To(Equal("otherlib-track"))
 			})
+
+			It("resolves paths from multiple libraries in a single call", func() {
+				adminMr := NewMediaFileRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
+				results, err := adminMr.FindByPaths([]string{
+					"1:artist/Album/track.mp3",
+					fmt.Sprintf("%d:hidden/test.mp3", otherLib.ID),
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(results).To(HaveLen(2))
+				Expect([]string{results[0].ID, results[1].ID}).To(ConsistOf("findpath-1", "otherlib-track"))
+			})
+
+			It("keeps each path scoped to its own library when several are queried", func() {
+				adminMr := NewMediaFileRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
+				// Each path exists, but under the other library's ID, so neither must match.
+				results, err := adminMr.FindByPaths([]string{
+					fmt.Sprintf("%d:artist/Album/track.mp3", otherLib.ID),
+					"1:hidden/test.mp3",
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(results).To(BeEmpty())
+			})
 		})
 	})
 

From 96b051ffa774eab2e0d877f5fbabe3215bc4d4a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 31 Aug 2026 11:21:32 -0400
Subject: [PATCH 094/200] fix(nativeapi): stop partial PUTs from clearing
 untouched columns (#6058)

* fix(nativeapi): stop partial PUTs from clearing untouched columns

The REST layer parses the request body's top-level JSON keys and passes them
to Repository.Update as colsToUpdate. The radio and library repositories
discarded that list and issued a full-row UPDATE, so any field absent from
the body was written as its zero value.

For radio this wiped uploaded_image, deleting the station's cover on every
partial update (the Web UI is unaffected because its form submits the whole
record). For library it silently cleared remote_path and default_new_users.

Thread the column list through to Put in both repositories, and extract the
column-selection half of filterUpdateValues into selectUpdateColumns so
library, which hand-builds its update map, shares the same rule instead of
copying it.

Fixes #6057

* refactor(persistence): drop pluginRepository's dead rest.Persistable methods

Save and Update had no callers: PUT /api/plugin/{id} is served by the
hand-written updatePlugin handler over a typed request struct, and the
route only wires rest.GetAll and rest.Get. Both methods delegated to Put,
which upserts all twelve columns, so wiring rest.Put to this repository
would have reintroduced the partial-update clobbering fixed in the previous
commit. Removing them, along with the rest.Persistable assertion, makes
that a compile error instead of a silent data loss.

Put itself is unchanged and still backs plugin discovery.
---
 core/library.go                        |  4 ++--
 core/library_test.go                   |  9 +++++++++
 model/library.go                       |  2 +-
 persistence/library_repository.go      | 10 +++++-----
 persistence/library_repository_test.go | 20 ++++++++++++++++++++
 persistence/plugin_repository.go       | 26 --------------------------
 persistence/radio_repository.go        |  2 +-
 persistence/radio_repository_test.go   | 18 ++++++++++++++++++
 persistence/sql_base_repository.go     | 15 +++++++++------
 tests/mock_library_repo.go             | 10 ++++++----
 10 files changed, 71 insertions(+), 45 deletions(-)

diff --git a/core/library.go b/core/library.go
index 365dcbd4c..d905e00cb 100644
--- a/core/library.go
+++ b/core/library.go
@@ -191,7 +191,7 @@ func (r *libraryRepositoryWrapper) Save(entity any) (string, error) {
 	return strconv.Itoa(lib.ID), nil
 }
 
-func (r *libraryRepositoryWrapper) Update(id string, entity any, _ ...string) error {
+func (r *libraryRepositoryWrapper) Update(id string, entity any, cols ...string) error {
 	lib := entity.(*model.Library)
 	libID, err := strconv.Atoi(id)
 	if err != nil {
@@ -211,7 +211,7 @@ func (r *libraryRepositoryWrapper) Update(id string, entity any, _ ...string) er
 
 	pathChanged := originalLib.Path != lib.Path
 
-	err = r.LibraryRepository.Put(lib)
+	err = r.LibraryRepository.Put(lib, cols...)
 	if err != nil {
 		return r.mapError(err)
 	}
diff --git a/core/library_test.go b/core/library_test.go
index 175d9c37d..43097414d 100644
--- a/core/library_test.go
+++ b/core/library_test.go
@@ -188,6 +188,15 @@ var _ = Describe("Library Service", func() {
 				Expect(libraryRepo.Data[1].Path).To(Equal(newTempDir))
 			})
 
+			It("forwards the columns sent by the client to the repository", func() {
+				library := &model.Library{ID: 1, Name: "Updated Library", Path: tempDir}
+
+				err := repo.Update("1", library, "name", "path")
+
+				Expect(err).NotTo(HaveOccurred())
+				Expect(libraryRepo.PutCols).To(Equal([]string{"name", "path"}))
+			})
+
 			It("fails when library doesn't exist", func() {
 				// Create a unique temporary directory to avoid path conflicts
 				uniqueTempDir, err := os.MkdirTemp("", "navidrome-nonexistent-")
diff --git a/model/library.go b/model/library.go
index bcb2864c8..aceab533a 100644
--- a/model/library.go
+++ b/model/library.go
@@ -45,7 +45,7 @@ type LibraryRepository interface {
 	GetPath(id int) (string, error)
 	GetAll(...QueryOptions) (Libraries, error)
 	CountAll(...QueryOptions) (int64, error)
-	Put(*Library) error
+	Put(l *Library, colsToUpdate ...string) error
 	Delete(id int) error
 	StoreMusicFolder() error
 	AddArtist(id int, artistID string) error
diff --git a/persistence/library_repository.go b/persistence/library_repository.go
index 5a0142423..df5c9a066 100644
--- a/persistence/library_repository.go
+++ b/persistence/library_repository.go
@@ -70,7 +70,7 @@ func (r *libraryRepository) GetPath(id int) (string, error) {
 	}
 }
 
-func (r *libraryRepository) Put(l *model.Library) error {
+func (r *libraryRepository) Put(l *model.Library, colsToUpdate ...string) error {
 	if l.ID == model.DefaultLibraryID {
 		currentLib, err := r.Get(1)
 		// if we are creating it, it's ok.
@@ -89,13 +89,13 @@ func (r *libraryRepository) Put(l *model.Library) error {
 		err = r.db.Model(l).Insert()
 	} else {
 		// Try to update first
-		cols := map[string]any{
+		cols := selectUpdateColumns(map[string]any{
 			"name":              l.Name,
 			"path":              l.Path,
 			"remote_path":       l.RemotePath,
 			"default_new_users": l.DefaultNewUsers,
-			"updated_at":        l.UpdatedAt,
-		}
+		}, colsToUpdate...)
+		cols["updated_at"] = l.UpdatedAt
 		sq := Update(r.tableName).SetMap(cols).Where(Eq{"id": l.ID})
 		rowsAffected, updateErr := r.executeSQL(sq)
 		if updateErr != nil {
@@ -340,7 +340,7 @@ func (r *libraryRepository) Update(id string, entity any, cols ...string) error
 	}
 
 	lib.ID = idInt
-	return r.Put(lib)
+	return r.Put(lib, cols...)
 }
 
 var _ model.LibraryRepository = (*libraryRepository)(nil)
diff --git a/persistence/library_repository_test.go b/persistence/library_repository_test.go
index 1743df209..949dd93c5 100644
--- a/persistence/library_repository_test.go
+++ b/persistence/library_repository_test.go
@@ -52,6 +52,26 @@ var _ = Describe("LibraryRepository", func() {
 			})
 		})
 
+		Context("when colsToUpdate is specified", func() {
+			It("only writes the requested columns", func() {
+				lib := &model.Library{
+					Name:            "Original Library",
+					Path:            "/music/original",
+					RemotePath:      "/remote/original",
+					DefaultNewUsers: true,
+				}
+				Expect(repo.Put(lib)).To(Succeed())
+
+				Expect(repo.Put(&model.Library{ID: lib.ID, Name: "Renamed", Path: lib.Path}, "name", "path")).To(Succeed())
+
+				saved, err := repo.Get(lib.ID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(saved.Name).To(Equal("Renamed"))
+				Expect(saved.RemotePath).To(Equal("/remote/original"))
+				Expect(saved.DefaultNewUsers).To(BeTrue())
+			})
+		})
+
 		Context("when ID is non-zero and record exists", func() {
 			It("updates the existing record", func() {
 				// First create a library
diff --git a/persistence/plugin_repository.go b/persistence/plugin_repository.go
index 35c32de91..c1e36f0b1 100644
--- a/persistence/plugin_repository.go
+++ b/persistence/plugin_repository.go
@@ -141,31 +141,5 @@ func (r *pluginRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
 	return r.GetAll(r.parseRestOptions(r.ctx, options...))
 }
 
-func (r *pluginRepository) Save(entity any) (string, error) {
-	p := entity.(*model.Plugin)
-	if !r.isPermitted() {
-		return "", rest.ErrPermissionDenied
-	}
-	err := r.Put(p)
-	if errors.Is(err, model.ErrNotFound) {
-		return "", rest.ErrNotFound
-	}
-	return p.ID, err
-}
-
-func (r *pluginRepository) Update(id string, entity any, cols ...string) error {
-	p := entity.(*model.Plugin)
-	p.ID = id
-	if !r.isPermitted() {
-		return rest.ErrPermissionDenied
-	}
-	err := r.Put(p)
-	if errors.Is(err, model.ErrNotFound) {
-		return rest.ErrNotFound
-	}
-	return err
-}
-
 var _ model.PluginRepository = (*pluginRepository)(nil)
 var _ rest.Repository = (*pluginRepository)(nil)
-var _ rest.Persistable = (*pluginRepository)(nil)
diff --git a/persistence/radio_repository.go b/persistence/radio_repository.go
index b73487e40..915859559 100644
--- a/persistence/radio_repository.go
+++ b/persistence/radio_repository.go
@@ -152,7 +152,7 @@ func (r *radioRepository) Update(id string, entity any, cols ...string) error {
 	if !r.isPermitted() {
 		return rest.ErrPermissionDenied
 	}
-	err := r.Put(t)
+	err := r.Put(t, cols...)
 	if errors.Is(err, model.ErrNotFound) {
 		return rest.ErrNotFound
 	}
diff --git a/persistence/radio_repository_test.go b/persistence/radio_repository_test.go
index e2564455d..c35c85ad7 100644
--- a/persistence/radio_repository_test.go
+++ b/persistence/radio_repository_test.go
@@ -141,6 +141,24 @@ var _ = Describe("RadioRepository", func() {
 				)))
 			})
 		})
+
+		Describe("Update", func() {
+			It("only writes the columns sent by the client", func() {
+				radio := radioWithHomePage
+				radio.UploadedImage = "cover.png"
+				Expect(repo.Put(&radio)).To(Succeed())
+
+				persistable := repo.(rest.Persistable)
+				Expect(persistable.Update(radio.ID, &model.Radio{Name: "Renamed"}, "name")).To(Succeed())
+
+				item, err := repo.Get(radio.ID)
+				Expect(err).To(BeNil())
+				Expect(item.Name).To(Equal("Renamed"))
+				Expect(item.UploadedImage).To(Equal("cover.png"))
+				Expect(item.StreamUrl).To(Equal(radio.StreamUrl))
+				Expect(item.HomePageUrl).To(Equal(radio.HomePageUrl))
+			})
+		})
 	})
 
 	Describe("Regular User", func() {
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index f49e1bc4f..5530d2568 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -560,13 +560,11 @@ func (r sqlRepository) putByMatch(filter Sqlizer, id string, m any, colsToUpdate
 	return r.put(res.ID, m, colsToUpdate...)
 }
 
-// filterUpdateValues selects, from a marshaled column map, the values to write in an UPDATE on the
-// row identified by id: only the requested colsToUpdate (or all columns when none are specified),
-// dropping columns that must never be overwritten on update (created_at, birth_time).
-func filterUpdateValues(values map[string]any, id string, colsToUpdate ...string) map[string]any {
+// selectUpdateColumns keeps only the requested colsToUpdate (or all columns when none are
+// specified), dropping columns that must never be overwritten on update (created_at, birth_time).
+func selectUpdateColumns(values map[string]any, colsToUpdate ...string) map[string]any {
 	updateValues := map[string]any{}
 
-	// This is a map of the columns that need to be updated, if specified
 	c2upd := slice.ToMap(colsToUpdate, func(s string) (string, struct{}) {
 		return toSnakeCase(s), struct{}{}
 	})
@@ -576,7 +574,6 @@ func filterUpdateValues(values map[string]any, id string, colsToUpdate ...string
 		}
 	}
 
-	updateValues["id"] = id
 	delete(updateValues, "created_at")
 	// To avoid updating the media_file birth_time on each scan. Not the best solution, but it works for now
 	// TODO move to mediafile_repository when each repo has its own upsert method
@@ -584,6 +581,12 @@ func filterUpdateValues(values map[string]any, id string, colsToUpdate ...string
 	return updateValues
 }
 
+func filterUpdateValues(values map[string]any, id string, colsToUpdate ...string) map[string]any {
+	updateValues := selectUpdateColumns(values, colsToUpdate...)
+	updateValues["id"] = id
+	return updateValues
+}
+
 func (r sqlRepository) put(id string, m any, colsToUpdate ...string) (newId string, err error) {
 	values, err := toSQLArgs(m)
 	if err != nil {
diff --git a/tests/mock_library_repo.go b/tests/mock_library_repo.go
index 3f0e576e9..1a16a7e0b 100644
--- a/tests/mock_library_repo.go
+++ b/tests/mock_library_repo.go
@@ -14,9 +14,10 @@ import (
 
 type MockLibraryRepo struct {
 	model.LibraryRepository
-	Data  map[int]model.Library
-	Err   error
-	PutFn func(*model.Library) error // Allow custom Put behavior for testing
+	Data    map[int]model.Library
+	Err     error
+	PutFn   func(*model.Library) error // Allow custom Put behavior for testing
+	PutCols []string
 }
 
 func (m *MockLibraryRepo) SetData(data model.Libraries) {
@@ -90,7 +91,8 @@ func (m *MockLibraryRepo) GetPath(id int) (string, error) {
 	return "", model.ErrNotFound
 }
 
-func (m *MockLibraryRepo) Put(library *model.Library) error {
+func (m *MockLibraryRepo) Put(library *model.Library, colsToUpdate ...string) error {
+	m.PutCols = colsToUpdate
 	if m.PutFn != nil {
 		return m.PutFn(library)
 	}

From 1f861d27efd97fa7df2b7a6c3e83e665e43270a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 31 Aug 2026 21:27:43 -0400
Subject: [PATCH 095/200] fix(plugins): build public URLs on the caller's
 address instead of localhost (#6059)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(plugins): build public URLs on the caller's address instead of localhost

The artwork host service had no `*http.Request`, so it passed `nil` to
`publicurl.ImageURL`. With neither `ShareURL` nor `BaseURL` configured, that
produced `http://localhost/share/img/...`, which is useless to anything outside
the server. The Discord Rich Presence plugin explicitly drops localhost URLs, so
it fell back to the Navidrome logo instead of the real cover art.

`serverAddressMiddleware` already works out the client-facing scheme and host
from the `X-Forwarded-*` headers. It now also records them in the request
context, and `publicurl` takes a `context.Context` instead of an `*http.Request`
so any caller can reach them. Extism passes the caller's context through to host
functions, so plugins invoked during a request now get a reachable URL with no
configuration.

Switching the parameter also removes the need for a second, parallel entry
point: the package previously wanted only a scheme, a host, and a context, and
took a whole request to get them. `AbsoluteURL` no longer dereferences a
possibly-nil request on its parse-error path.

Plugin calls that start from `context.Background()` (scheduler and websocket
callbacks, the buffered scrobble drain) still fall back to localhost, since they
have no request to learn from. A debug log now points at `ShareURL` when that
happens.

* fix(publicurl): include the configured port in the localhost fallback

The last-resort fallback built `http://localhost/...`, which points at port 80
and so is unreachable for a server listening anywhere else — the default 4533
included. Use `conf.Server.Port` so a consumer on the same machine can actually
fetch the URL.

* fix(publicurl): use https in the localhost fallback when TLS is configured

The fallback hardcoded the http scheme, so a TLS-only server with no BaseURL
advertised a URL it does not answer on. Mirror the server's own switch, which
requires both a certificate and a key.

* refactor(publicurl): tidy the localhost fallback and its tests

Use gg.If for the fallback scheme so it reads as an expression, like the
BaseScheme branch above it, instead of assigning http and overwriting it.

Drop two tests the ctx refactor left redundant: one asserted PublicURL "works
without a request" but became a byte-identical copy of the ShareURL spec once
the *http.Request parameter went away, and the two port specs differed only in
the integer, where the non-default port is the stronger assertion.

* refactor(conf): add TLSEnabled and use it instead of repeating the predicate

Whether the server speaks HTTPS was decided inline in three unconnected
places. This PR added the third, in a URL-building package that has no
business inferring the transport config.

Move the rule to conf, next to the fields it derives from, and call it from
publicurl and the insights collector. server.Run keeps its own expression: it
takes the certificate and key as parameters, and its test passes values that
do not come from the config.
---
 conf/configuration.go            |   6 ++
 conf/configuration_test.go       |  27 ++++++++
 core/metrics/insights.go         |   2 +-
 core/publicurl/publicurl.go      |  41 +++++------
 core/publicurl/publicurl_test.go | 113 ++++++++++++++++++++-----------
 model/request/request.go         |  21 ++++++
 model/request/request_test.go    |  31 +++++++++
 plugins/host_artwork.go          |  16 ++---
 plugins/host_artwork_test.go     |  11 ++-
 server/middlewares.go            |   2 +
 server/middlewares_test.go       |  29 ++++++++
 server/public/handle_shares.go   |   6 +-
 server/public/public.go          |   5 +-
 server/subsonic/browsing.go      |  12 ++--
 server/subsonic/helpers.go       |   4 +-
 server/subsonic/searching.go     |   2 +-
 server/subsonic/sharing.go       |   2 +-
 17 files changed, 245 insertions(+), 85 deletions(-)

diff --git a/conf/configuration.go b/conf/configuration.go
index df22e4ae2..b9c9f027e 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -315,6 +315,12 @@ var currentGOOS = func() string {
 	return runtime.GOOS
 }
 
+// TLSEnabled reports whether the server serves HTTPS. Both halves are required,
+// so callers cannot infer it from the certificate alone.
+func (c *configOptions) TLSEnabled() bool {
+	return c.TLSCert != "" && c.TLSKey != ""
+}
+
 var (
 	Server = &configOptions{}
 	hooks  []func()
diff --git a/conf/configuration_test.go b/conf/configuration_test.go
index ac6477572..344ab3595 100644
--- a/conf/configuration_test.go
+++ b/conf/configuration_test.go
@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/log"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -453,3 +454,29 @@ var _ = Describe("Configuration", func() {
 		Entry("JSON format", "json"),
 	)
 })
+
+var _ = Describe("TLSEnabled", func() {
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+	})
+
+	It("is false when neither the certificate nor the key is set", func() {
+		Expect(conf.Server.TLSEnabled()).To(BeFalse())
+	})
+
+	It("is true when both the certificate and the key are set", func() {
+		conf.Server.TLSCert = "cert.pem"
+		conf.Server.TLSKey = "key.pem"
+		Expect(conf.Server.TLSEnabled()).To(BeTrue())
+	})
+
+	It("is false when only the certificate is set", func() {
+		conf.Server.TLSCert = "cert.pem"
+		Expect(conf.Server.TLSEnabled()).To(BeFalse())
+	})
+
+	It("is false when only the key is set", func() {
+		conf.Server.TLSKey = "key.pem"
+		Expect(conf.Server.TLSEnabled()).To(BeFalse())
+	})
+})
diff --git a/core/metrics/insights.go b/core/metrics/insights.go
index 706df6559..d952f517a 100644
--- a/core/metrics/insights.go
+++ b/core/metrics/insights.go
@@ -198,7 +198,7 @@ var staticData = sync.OnceValue(func() insights.Data {
 	// Config info
 	data.Config.LogLevel = conf.Server.LogLevel
 	data.Config.LogFileConfigured = conf.Server.LogFile != ""
-	data.Config.TLSConfigured = conf.Server.TLSCert != "" && conf.Server.TLSKey != ""
+	data.Config.TLSConfigured = conf.Server.TLSEnabled()
 	data.Config.DefaultBackgroundURLSet = conf.Server.UILoginBackgroundURL == consts.DefaultUILoginBackgroundURL
 	data.Config.EnableArtworkPrecache = conf.Server.EnableArtworkPrecache
 	data.Config.EnableArtworkUpload = conf.Server.EnableArtworkUpload
diff --git a/core/publicurl/publicurl.go b/core/publicurl/publicurl.go
index b0865e78b..345606324 100644
--- a/core/publicurl/publicurl.go
+++ b/core/publicurl/publicurl.go
@@ -2,7 +2,7 @@ package publicurl
 
 import (
 	"cmp"
-	"net/http"
+	"context"
 	"net/url"
 	"path"
 	"strconv"
@@ -13,35 +13,36 @@ import (
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/gg"
 )
 
 // ImageURL generates a public URL for artwork images.
 // It creates a signed token for the artwork ID and builds a complete public URL.
-func ImageURL(req *http.Request, artID model.ArtworkID, size int) string {
+func ImageURL(ctx context.Context, artID model.ArtworkID, size int) string {
 	token, _ := auth.CreatePublicToken(auth.Claims{ID: artID.String()})
 	uri := path.Join(consts.URLPathPublicImages, token)
 	params := url.Values{}
 	if size > 0 {
 		params.Add("size", strconv.Itoa(size))
 	}
-	return PublicURL(req, uri, params)
+	return PublicURL(ctx, uri, params)
 }
 
 // PublicURL builds a full URL for public-facing resources.
-// It uses ShareURL from config if available, otherwise falls back to extracting
-// the scheme and host from the provided http.Request.
-// If req is nil and ShareURL is not set, it defaults to http://localhost.
-func PublicURL(req *http.Request, u string, params url.Values) string {
+// It uses ShareURL from config if available, otherwise falls back to the address the
+// client used to reach the server, recorded in the context.
+func PublicURL(ctx context.Context, u string, params url.Values) string {
 	if conf.Server.ShareURL == "" {
-		return AbsoluteURL(req, u, params)
+		return AbsoluteURL(ctx, u, params)
 	}
 	shareUrl, err := url.Parse(conf.Server.ShareURL)
 	if err != nil {
-		return AbsoluteURL(req, u, params)
+		return AbsoluteURL(ctx, u, params)
 	}
 	buildUrl, err := url.Parse(u)
 	if err != nil {
-		return AbsoluteURL(req, u, params)
+		return AbsoluteURL(ctx, u, params)
 	}
 	buildUrl.Scheme = shareUrl.Scheme
 	buildUrl.Host = shareUrl.Host
@@ -55,13 +56,12 @@ func PublicURL(req *http.Request, u string, params url.Values) string {
 }
 
 // AbsoluteURL builds an absolute URL from a relative path.
-// It uses BaseHost/BaseScheme from config if available, otherwise extracts
-// the scheme and host from the http.Request.
-// If req is nil and BaseHost is not set, it defaults to http://localhost.
-func AbsoluteURL(req *http.Request, u string, params url.Values) string {
+// It uses BaseHost/BaseScheme from config if available, otherwise the address the client
+// used to reach the server, recorded in the context by the server's address middleware.
+func AbsoluteURL(ctx context.Context, u string, params url.Values) string {
 	buildUrl, err := url.Parse(u)
 	if err != nil {
-		log.Error(req.Context(), "Failed to parse URL path", "url", u, err)
+		log.Error(ctx, "Failed to parse URL path", "url", u, err)
 		return ""
 	}
 	if strings.HasPrefix(u, "/") {
@@ -69,12 +69,13 @@ func AbsoluteURL(req *http.Request, u string, params url.Values) string {
 		if conf.Server.BaseHost != "" {
 			buildUrl.Scheme = cmp.Or(conf.Server.BaseScheme, "http")
 			buildUrl.Host = conf.Server.BaseHost
-		} else if req != nil {
-			buildUrl.Scheme = req.URL.Scheme
-			buildUrl.Host = req.Host
+		} else if scheme, host, ok := request.ServerAddressFrom(ctx); ok {
+			buildUrl.Scheme = scheme
+			buildUrl.Host = host
 		} else {
-			buildUrl.Scheme = "http"
-			buildUrl.Host = "localhost"
+			log.Debug(ctx, "Building a public URL with no public address available; set ShareURL to make it reachable", "url", u)
+			buildUrl.Scheme = gg.If(conf.Server.TLSEnabled(), "https", "http")
+			buildUrl.Host = "localhost:" + strconv.Itoa(conf.Server.Port)
 		}
 	}
 	if len(params) > 0 {
diff --git a/core/publicurl/publicurl_test.go b/core/publicurl/publicurl_test.go
index 7e9ee8b8e..0f8ea806c 100644
--- a/core/publicurl/publicurl_test.go
+++ b/core/publicurl/publicurl_test.go
@@ -1,7 +1,7 @@
 package publicurl_test
 
 import (
-	"net/http"
+	"context"
 	"net/url"
 	"testing"
 
@@ -12,6 +12,7 @@ import (
 	"github.com/navidrome/navidrome/core/publicurl"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -36,24 +37,17 @@ var _ = Describe("Public URL Utilities", func() {
 			})
 
 			It("uses ShareURL as the base", func() {
-				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
-				result := publicurl.PublicURL(r, "/path/to/resource", nil)
+				result := publicurl.PublicURL(context.Background(), "/path/to/resource", nil)
 				Expect(result).To(Equal("https://share.example.com/path/to/resource"))
 			})
 
 			It("includes query parameters", func() {
-				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
 				params := url.Values{"size": []string{"300"}, "format": []string{"png"}}
-				result := publicurl.PublicURL(r, "/image/123", params)
+				result := publicurl.PublicURL(context.Background(), "/image/123", params)
 				Expect(result).To(ContainSubstring("https://share.example.com/image/123"))
 				Expect(result).To(ContainSubstring("size=300"))
 				Expect(result).To(ContainSubstring("format=png"))
 			})
-
-			It("works without a request", func() {
-				result := publicurl.PublicURL(nil, "/path/to/resource", nil)
-				Expect(result).To(Equal("https://share.example.com/path/to/resource"))
-			})
 		})
 
 		When("ShareURL includes a path", func() {
@@ -62,21 +56,19 @@ var _ = Describe("Public URL Utilities", func() {
 			})
 
 			It("prepends the ShareURL path to the resource", func() {
-				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
-				result := publicurl.PublicURL(r, "/share/img/hash", nil)
+				result := publicurl.PublicURL(context.Background(), "/share/img/hash", nil)
 				Expect(result).To(Equal("https://example.com/navi/share/img/hash"))
 			})
 
 			It("prepends the ShareURL path and includes query parameters", func() {
-				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
 				params := url.Values{"size": []string{"600"}}
-				result := publicurl.PublicURL(r, "/share/img/hash", params)
+				result := publicurl.PublicURL(context.Background(), "/share/img/hash", params)
 				Expect(result).To(Equal("https://example.com/navi/share/img/hash?size=600"))
 			})
 
 			It("handles trailing slash in ShareURL path", func() {
 				conf.Server.ShareURL = "https://example.com/navi/"
-				result := publicurl.PublicURL(nil, "/share/img/hash", nil)
+				result := publicurl.PublicURL(context.Background(), "/share/img/hash", nil)
 				Expect(result).To(Equal("https://example.com/navi/share/img/hash"))
 			})
 		})
@@ -87,15 +79,15 @@ var _ = Describe("Public URL Utilities", func() {
 			})
 
 			It("falls back to AbsoluteURL with request", func() {
-				r, _ := http.NewRequest("GET", "https://myserver.com/test", nil)
-				r.Host = "myserver.com"
-				result := publicurl.PublicURL(r, "/path/to/resource", nil)
+				ctx := request.WithServerAddress(context.Background(), "https", "myserver.com")
+				result := publicurl.PublicURL(ctx, "/path/to/resource", nil)
 				Expect(result).To(Equal("https://myserver.com/path/to/resource"))
 			})
 
-			It("falls back to localhost without request", func() {
-				result := publicurl.PublicURL(nil, "/path/to/resource", nil)
-				Expect(result).To(Equal("http://localhost/path/to/resource"))
+			It("falls back to localhost on the configured port without request", func() {
+				conf.Server.Port = 4533
+				result := publicurl.PublicURL(context.Background(), "/path/to/resource", nil)
+				Expect(result).To(Equal("http://localhost:4533/path/to/resource"))
 			})
 		})
 	})
@@ -109,15 +101,13 @@ var _ = Describe("Public URL Utilities", func() {
 			})
 
 			It("uses BaseHost and BaseScheme", func() {
-				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
-				result := publicurl.AbsoluteURL(r, "/path/to/resource", nil)
+				result := publicurl.AbsoluteURL(context.Background(), "/path/to/resource", nil)
 				Expect(result).To(Equal("https://configured.example.com/path/to/resource"))
 			})
 
 			It("defaults to http scheme if BaseScheme is empty", func() {
 				conf.Server.BaseScheme = ""
-				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
-				result := publicurl.AbsoluteURL(r, "/path/to/resource", nil)
+				result := publicurl.AbsoluteURL(context.Background(), "/path/to/resource", nil)
 				Expect(result).To(Equal("http://configured.example.com/path/to/resource"))
 			})
 		})
@@ -129,15 +119,30 @@ var _ = Describe("Public URL Utilities", func() {
 			})
 
 			It("extracts host from request", func() {
-				r, _ := http.NewRequest("GET", "https://request.example.com/test", nil)
-				r.Host = "request.example.com"
-				result := publicurl.AbsoluteURL(r, "/path/to/resource", nil)
+				ctx := request.WithServerAddress(context.Background(), "https", "request.example.com")
+				result := publicurl.AbsoluteURL(ctx, "/path/to/resource", nil)
 				Expect(result).To(Equal("https://request.example.com/path/to/resource"))
 			})
 
-			It("falls back to localhost without request", func() {
-				result := publicurl.AbsoluteURL(nil, "/path/to/resource", nil)
-				Expect(result).To(Equal("http://localhost/path/to/resource"))
+			It("falls back to localhost on the configured port without request", func() {
+				conf.Server.Port = 8080
+				result := publicurl.AbsoluteURL(context.Background(), "/path/to/resource", nil)
+				Expect(result).To(Equal("http://localhost:8080/path/to/resource"))
+			})
+
+			It("uses https in the fallback when TLS is configured", func() {
+				conf.Server.Port = 4533
+				conf.Server.TLSCert = "cert.pem"
+				conf.Server.TLSKey = "key.pem"
+				result := publicurl.AbsoluteURL(context.Background(), "/path/to/resource", nil)
+				Expect(result).To(Equal("https://localhost:4533/path/to/resource"))
+			})
+
+			It("stays on http when only the certificate is configured", func() {
+				conf.Server.Port = 4533
+				conf.Server.TLSCert = "cert.pem"
+				result := publicurl.AbsoluteURL(context.Background(), "/path/to/resource", nil)
+				Expect(result).To(Equal("http://localhost:4533/path/to/resource"))
 			})
 		})
 
@@ -149,24 +154,21 @@ var _ = Describe("Public URL Utilities", func() {
 			})
 
 			It("prepends BasePath to the URL", func() {
-				r, _ := http.NewRequest("GET", "http://localhost/test", nil)
-				result := publicurl.AbsoluteURL(r, "/path/to/resource", nil)
+				result := publicurl.AbsoluteURL(context.Background(), "/path/to/resource", nil)
 				Expect(result).To(Equal("https://example.com/navidrome/path/to/resource"))
 			})
 		})
 
 		It("passes through absolute URLs unchanged", func() {
-			r, _ := http.NewRequest("GET", "http://localhost/test", nil)
-			result := publicurl.AbsoluteURL(r, "https://other.example.com/path", nil)
+			result := publicurl.AbsoluteURL(context.Background(), "https://other.example.com/path", nil)
 			Expect(result).To(Equal("https://other.example.com/path"))
 		})
 
 		It("includes query parameters", func() {
 			conf.Server.BaseHost = "example.com"
 			conf.Server.BaseScheme = "https"
-			r, _ := http.NewRequest("GET", "http://localhost/test", nil)
 			params := url.Values{"key": []string{"value"}}
-			result := publicurl.AbsoluteURL(r, "/path", params)
+			result := publicurl.AbsoluteURL(context.Background(), "/path", params)
 			Expect(result).To(Equal("https://example.com/path?key=value"))
 		})
 	})
@@ -180,20 +182,51 @@ var _ = Describe("Public URL Utilities", func() {
 
 		It("generates a URL with the artwork token", func() {
 			artID := model.NewArtworkID(model.KindAlbumArtwork, "album-123", nil)
-			result := publicurl.ImageURL(nil, artID, 0)
+			result := publicurl.ImageURL(context.Background(), artID, 0)
 			Expect(result).To(HavePrefix("https://share.example.com/share/img/"))
 		})
 
 		It("includes size parameter when provided", func() {
 			artID := model.NewArtworkID(model.KindArtistArtwork, "artist-1", nil)
-			result := publicurl.ImageURL(nil, artID, 300)
+			result := publicurl.ImageURL(context.Background(), artID, 300)
 			Expect(result).To(ContainSubstring("size=300"))
 		})
 
 		It("omits size parameter when zero", func() {
 			artID := model.NewArtworkID(model.KindMediaFileArtwork, "track-1", nil)
-			result := publicurl.ImageURL(nil, artID, 0)
+			result := publicurl.ImageURL(context.Background(), artID, 0)
 			Expect(result).ToNot(ContainSubstring("size="))
 		})
 	})
+
+	Describe("ImageURL address precedence", func() {
+		var artID model.ArtworkID
+
+		BeforeEach(func() {
+			auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test secret"), nil)
+			artID = model.NewArtworkID(model.KindMediaFileArtwork, "track-1", nil)
+		})
+
+		It("uses the address of the request that triggered the call", func() {
+			ctx := request.WithServerAddress(context.Background(), "https", "music.example.com")
+
+			result := publicurl.ImageURL(ctx, artID, 300)
+			Expect(result).To(HavePrefix("https://music.example.com/share/img/"))
+			Expect(result).To(ContainSubstring("size=300"))
+		})
+
+		It("prefers ShareURL over the address in the context", func() {
+			conf.Server.ShareURL = "https://share.example.com"
+			ctx := request.WithServerAddress(context.Background(), "https", "music.example.com")
+
+			result := publicurl.ImageURL(ctx, artID, 0)
+			Expect(result).To(HavePrefix("https://share.example.com/share/img/"))
+		})
+
+		It("falls back to localhost on the configured port when no address is available", func() {
+			conf.Server.Port = 4533
+			result := publicurl.ImageURL(context.Background(), artID, 0)
+			Expect(result).To(HavePrefix("http://localhost:4533/share/img/"))
+		})
+	})
 })
diff --git a/model/request/request.go b/model/request/request.go
index 2b1cfb9ef..33c49f797 100644
--- a/model/request/request.go
+++ b/model/request/request.go
@@ -20,6 +20,7 @@ const (
 	ReverseProxyIp   = contextKey("reverseProxyIp")
 	InternalAuth     = contextKey("internalAuth") // Used for internal API calls, e.g., from the plugins
 	TokenEpochHolder = contextKey("tokenEpochHolder")
+	ServerAddress    = contextKey("serverAddress")
 )
 
 var allKeys = []contextKey{
@@ -32,6 +33,7 @@ var allKeys = []contextKey{
 	ClientUniqueId,
 	ReverseProxyIp,
 	InternalAuth,
+	ServerAddress,
 }
 
 func WithUser(ctx context.Context, u model.User) context.Context {
@@ -70,6 +72,25 @@ func WithInternalAuth(ctx context.Context, username string) context.Context {
 	return context.WithValue(ctx, InternalAuth, username)
 }
 
+// serverAddress is the public scheme and host the client used to reach this server,
+// so code running without an http.Request can still build absolute URLs.
+type serverAddress struct {
+	scheme string
+	host   string
+}
+
+func WithServerAddress(ctx context.Context, scheme, host string) context.Context {
+	return context.WithValue(ctx, ServerAddress, serverAddress{scheme: scheme, host: host})
+}
+
+func ServerAddressFrom(ctx context.Context) (scheme, host string, ok bool) {
+	a, ok := ctx.Value(ServerAddress).(serverAddress)
+	if !ok || a.host == "" {
+		return "", "", false
+	}
+	return a.scheme, a.host, true
+}
+
 func UserFrom(ctx context.Context) (model.User, bool) {
 	v, ok := ctx.Value(User).(model.User)
 	return v, ok
diff --git a/model/request/request_test.go b/model/request/request_test.go
index ef9af8231..da819f9c0 100644
--- a/model/request/request_test.go
+++ b/model/request/request_test.go
@@ -38,3 +38,34 @@ var _ = Describe("Token epoch holder", func() {
 		Expect(ok).To(BeFalse())
 	})
 })
+
+var _ = Describe("Server address", func() {
+	It("reports nothing when unset", func() {
+		_, _, ok := ServerAddressFrom(context.TODO())
+		Expect(ok).To(BeFalse())
+	})
+
+	It("round-trips the scheme and host", func() {
+		ctx := WithServerAddress(context.TODO(), "https", "music.example.com")
+
+		scheme, host, ok := ServerAddressFrom(ctx)
+		Expect(ok).To(BeTrue())
+		Expect(scheme).To(Equal("https"))
+		Expect(host).To(Equal("music.example.com"))
+	})
+
+	It("reports nothing when the host is empty", func() {
+		ctx := WithServerAddress(context.TODO(), "https", "")
+
+		_, _, ok := ServerAddressFrom(ctx)
+		Expect(ok).To(BeFalse())
+	})
+
+	It("is carried over to a background context by AddValues", func() {
+		reqCtx := WithServerAddress(context.TODO(), "https", "music.example.com")
+
+		_, host, ok := ServerAddressFrom(AddValues(context.Background(), reqCtx))
+		Expect(ok).To(BeTrue())
+		Expect(host).To(Equal("music.example.com"))
+	})
+})
diff --git a/plugins/host_artwork.go b/plugins/host_artwork.go
index 49b9a285d..7a19eddb9 100644
--- a/plugins/host_artwork.go
+++ b/plugins/host_artwork.go
@@ -14,24 +14,24 @@ func newArtworkService() host.ArtworkService {
 	return &artworkServiceImpl{}
 }
 
-func (a *artworkServiceImpl) GetArtistUrl(_ context.Context, id string, size int32) (string, error) {
+func (a *artworkServiceImpl) GetArtistUrl(ctx context.Context, id string, size int32) (string, error) {
 	artID := model.ArtworkID{Kind: model.KindArtistArtwork, ID: id}
-	return publicurl.ImageURL(nil, artID, int(size)), nil
+	return publicurl.ImageURL(ctx, artID, int(size)), nil
 }
 
-func (a *artworkServiceImpl) GetAlbumUrl(_ context.Context, id string, size int32) (string, error) {
+func (a *artworkServiceImpl) GetAlbumUrl(ctx context.Context, id string, size int32) (string, error) {
 	artID := model.ArtworkID{Kind: model.KindAlbumArtwork, ID: id}
-	return publicurl.ImageURL(nil, artID, int(size)), nil
+	return publicurl.ImageURL(ctx, artID, int(size)), nil
 }
 
-func (a *artworkServiceImpl) GetTrackUrl(_ context.Context, id string, size int32) (string, error) {
+func (a *artworkServiceImpl) GetTrackUrl(ctx context.Context, id string, size int32) (string, error) {
 	artID := model.ArtworkID{Kind: model.KindMediaFileArtwork, ID: id}
-	return publicurl.ImageURL(nil, artID, int(size)), nil
+	return publicurl.ImageURL(ctx, artID, int(size)), nil
 }
 
-func (a *artworkServiceImpl) GetPlaylistUrl(_ context.Context, id string, size int32) (string, error) {
+func (a *artworkServiceImpl) GetPlaylistUrl(ctx context.Context, id string, size int32) (string, error) {
 	artID := model.ArtworkID{Kind: model.KindPlaylistArtwork, ID: id}
-	return publicurl.ImageURL(nil, artID, int(size)), nil
+	return publicurl.ImageURL(ctx, artID, int(size)), nil
 }
 
 var _ host.ArtworkService = (*artworkServiceImpl)(nil)
diff --git a/plugins/host_artwork_test.go b/plugins/host_artwork_test.go
index 218d3d892..50a1a0335 100644
--- a/plugins/host_artwork_test.go
+++ b/plugins/host_artwork_test.go
@@ -16,6 +16,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -122,7 +123,7 @@ var _ = Describe("ArtworkService", Ordered, func() {
 				Size:        size,
 			}
 			inputBytes, _ := json.Marshal(input)
-			_, outputBytes, err := instance.Call("nd_test_artwork", inputBytes)
+			_, outputBytes, err := instance.CallWithContext(ctx, "nd_test_artwork", inputBytes)
 			if err != nil {
 				return "", err
 			}
@@ -189,6 +190,14 @@ var _ = Describe("ArtworkService", Ordered, func() {
 			Expect(artID.ID).To(Equal("al-456"))
 		})
 
+		It("uses the address of the request that triggered the plugin", func() {
+			ctx := request.WithServerAddress(GinkgoT().Context(), "https", "music.example.com")
+
+			url, err := callTestArtwork(ctx, "track", "mf-789", 300)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(url).To(HavePrefix("https://music.example.com/share/img/"))
+		})
+
 		It("should handle unknown artwork type", func() {
 			_, err := callTestArtwork(GinkgoT().Context(), "unknown", "id-123", 0)
 			Expect(err).To(HaveOccurred())
diff --git a/server/middlewares.go b/server/middlewares.go
index 23e11eaa6..b710b4068 100644
--- a/server/middlewares.go
+++ b/server/middlewares.go
@@ -208,6 +208,8 @@ func serverAddressMiddleware(h http.Handler) http.Handler {
 		if rScheme, rHost := ServerAddress(r); rHost != "" {
 			r.Host = rHost
 			r.URL.Scheme = rScheme
+			// Recorded so code running without the request (e.g. plugins) can build public URLs.
+			r = r.WithContext(request.WithServerAddress(r.Context(), rScheme, rHost))
 		}
 
 		// Call the next handler in the chain with the modified request and response.
diff --git a/server/middlewares_test.go b/server/middlewares_test.go
index 5cecba7d5..4ba9a853b 100644
--- a/server/middlewares_test.go
+++ b/server/middlewares_test.go
@@ -13,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/publicurl"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
@@ -69,10 +70,15 @@ var _ = Describe("middlewares", func() {
 			middleware  http.Handler
 			recorder    *httptest.ResponseRecorder
 			req         *http.Request
+			gotScheme   string
+			gotHost     string
+			gotOK       bool
 		)
 
 		BeforeEach(func() {
+			gotScheme, gotHost, gotOK = "", "", false
 			nextHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				gotScheme, gotHost, gotOK = request.ServerAddressFrom(r.Context())
 				w.WriteHeader(http.StatusOK)
 			})
 			middleware = serverAddressMiddleware(nextHandler)
@@ -89,6 +95,13 @@ var _ = Describe("middlewares", func() {
 				Expect(req.Host).To(Equal("example.com"))
 				Expect(req.URL.Scheme).To(Equal("http"))
 			})
+
+			It("should record the address in the context", func() {
+				middleware.ServeHTTP(recorder, req)
+				Expect(gotOK).To(BeTrue())
+				Expect(gotScheme).To(Equal("http"))
+				Expect(gotHost).To(Equal("example.com"))
+			})
 		})
 
 		Context("with X-Forwarded-Host header", func() {
@@ -143,6 +156,22 @@ var _ = Describe("middlewares", func() {
 				Expect(req.Host).To(Equal("forwarded.example.com"))
 				Expect(req.URL.Scheme).To(Equal("https"))
 			})
+
+			It("should record the forwarded address in the context", func() {
+				middleware.ServeHTTP(recorder, req)
+				Expect(gotOK).To(BeTrue())
+				Expect(gotScheme).To(Equal("https"))
+				Expect(gotHost).To(Equal("forwarded.example.com"))
+			})
+
+			It("lets a handler build a public URL on the forwarded address", func() {
+				var got string
+				serverAddressMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					got = publicurl.AbsoluteURL(r.Context(), "/share/img/token", nil)
+				})).ServeHTTP(recorder, req)
+
+				Expect(got).To(Equal("https://forwarded.example.com/share/img/token"))
+			})
 		})
 
 		Context("with multiple values in X-Forwarded-Host header", func() {
diff --git a/server/public/handle_shares.go b/server/public/handle_shares.go
index 13a7e4c32..d67cfe456 100644
--- a/server/public/handle_shares.go
+++ b/server/public/handle_shares.go
@@ -81,8 +81,8 @@ func checkShareError(ctx context.Context, w http.ResponseWriter, err error, id s
 }
 
 func (pub *Router) mapShareInfo(r *http.Request, s model.Share) *model.Share {
-	s.URL = ShareURL(r, s.ID)
-	s.ImageURL = publicurl.ImageURL(r, s.CoverArtID(), conf.Server.UICoverArtSize)
+	s.URL = ShareURL(r.Context(), s.ID)
+	s.ImageURL = publicurl.ImageURL(r.Context(), s.CoverArtID(), conf.Server.UICoverArtSize)
 	for i := range s.Tracks {
 		s.Tracks[i].ID = encodeMediafileShare(s, s.Tracks[i].ID)
 	}
@@ -92,7 +92,7 @@ func (pub *Router) mapShareInfo(r *http.Request, s model.Share) *model.Share {
 func (pub *Router) mapShareToM3U(r *http.Request, s model.Share) *model.Share {
 	for i := range s.Tracks {
 		id := encodeMediafileShare(s, s.Tracks[i].ID)
-		s.Tracks[i].Path = publicurl.PublicURL(r, path.Join(consts.URLPathPublic, "s", id), nil)
+		s.Tracks[i].Path = publicurl.PublicURL(r.Context(), path.Join(consts.URLPathPublic, "s", id), nil)
 	}
 	return &s
 }
diff --git a/server/public/public.go b/server/public/public.go
index 18867e1c4..142c474bd 100644
--- a/server/public/public.go
+++ b/server/public/public.go
@@ -1,6 +1,7 @@
 package public
 
 import (
+	"context"
 	"net/http"
 	"path"
 
@@ -59,7 +60,7 @@ func (pub *Router) routes() http.Handler {
 	return r
 }
 
-func ShareURL(r *http.Request, id string) string {
+func ShareURL(ctx context.Context, id string) string {
 	uri := path.Join(consts.URLPathPublic, id)
-	return publicurl.PublicURL(r, uri, nil)
+	return publicurl.PublicURL(ctx, uri, nil)
 }
diff --git a/server/subsonic/browsing.go b/server/subsonic/browsing.go
index d32a5c857..ac0edb69f 100644
--- a/server/subsonic/browsing.go
+++ b/server/subsonic/browsing.go
@@ -231,9 +231,9 @@ func (api *Router) GetAlbumInfo(r *http.Request) (*responses.Subsonic, error) {
 	response.AlbumInfo = &responses.AlbumInfo{}
 	response.AlbumInfo.Notes = album.Description
 	if !album.ImageAbsent {
-		response.AlbumInfo.SmallImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 300)
-		response.AlbumInfo.MediumImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 600)
-		response.AlbumInfo.LargeImageUrl = publicurl.ImageURL(r, album.CoverArtID(), 1200)
+		response.AlbumInfo.SmallImageUrl = publicurl.ImageURL(r.Context(), album.CoverArtID(), 300)
+		response.AlbumInfo.MediumImageUrl = publicurl.ImageURL(r.Context(), album.CoverArtID(), 600)
+		response.AlbumInfo.LargeImageUrl = publicurl.ImageURL(r.Context(), album.CoverArtID(), 1200)
 	}
 
 	response.AlbumInfo.LastFmUrl = album.ExternalUrl
@@ -298,9 +298,9 @@ func (api *Router) getArtistInfo(r *http.Request) (*responses.ArtistInfoBase, *m
 	base := responses.ArtistInfoBase{}
 	base.Biography = artist.Biography
 	if !artist.ImageAbsent {
-		base.SmallImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 300)
-		base.MediumImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 600)
-		base.LargeImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 1200)
+		base.SmallImageUrl = publicurl.ImageURL(r.Context(), artist.CoverArtID(), 300)
+		base.MediumImageUrl = publicurl.ImageURL(r.Context(), artist.CoverArtID(), 600)
+		base.LargeImageUrl = publicurl.ImageURL(r.Context(), artist.CoverArtID(), 1200)
 	}
 	base.LastFmUrl = artist.ExternalUrl
 	base.MusicBrainzID = artist.MbzArtistID
diff --git a/server/subsonic/helpers.go b/server/subsonic/helpers.go
index e367cdee5..2d9d53b18 100644
--- a/server/subsonic/helpers.go
+++ b/server/subsonic/helpers.go
@@ -112,7 +112,7 @@ func toArtist(r *http.Request, a model.Artist) responses.Artist {
 		CoverArt:   coverArtOrEmpty(a.CoverArtID(), a.ImageAbsent),
 	}
 	if !a.ImageAbsent {
-		artist.ArtistImageUrl = publicurl.ImageURL(r, a.CoverArtID(), 600)
+		artist.ArtistImageUrl = publicurl.ImageURL(r.Context(), a.CoverArtID(), 600)
 	}
 	if conf.Server.Subsonic.EnableAverageRating {
 		artist.AverageRating = a.AverageRating
@@ -132,7 +132,7 @@ func toArtistID3(r *http.Request, a model.Artist) responses.ArtistID3 {
 		UserRating: int32(a.Rating),
 	}
 	if !a.ImageAbsent {
-		artist.ArtistImageUrl = publicurl.ImageURL(r, a.CoverArtID(), 600)
+		artist.ArtistImageUrl = publicurl.ImageURL(r.Context(), a.CoverArtID(), 600)
 	}
 	if conf.Server.Subsonic.EnableAverageRating {
 		artist.AverageRating = a.AverageRating
diff --git a/server/subsonic/searching.go b/server/subsonic/searching.go
index cc787f041..35233a98f 100644
--- a/server/subsonic/searching.go
+++ b/server/subsonic/searching.go
@@ -116,7 +116,7 @@ func (api *Router) Search2(r *http.Request) (*responses.Subsonic, error) {
 			CoverArt:   coverArtOrEmpty(artist.CoverArtID(), artist.ImageAbsent),
 		}
 		if !artist.ImageAbsent {
-			a.ArtistImageUrl = publicurl.ImageURL(r, artist.CoverArtID(), 600)
+			a.ArtistImageUrl = publicurl.ImageURL(r.Context(), artist.CoverArtID(), 600)
 		}
 		if artist.Starred {
 			a.Starred = artist.StarredAt
diff --git a/server/subsonic/sharing.go b/server/subsonic/sharing.go
index 540ae79d7..36124c40b 100644
--- a/server/subsonic/sharing.go
+++ b/server/subsonic/sharing.go
@@ -31,7 +31,7 @@ func (api *Router) GetShares(r *http.Request) (*responses.Subsonic, error) {
 func (api *Router) buildShare(r *http.Request, share model.Share) responses.Share {
 	resp := responses.Share{
 		ID:          share.ID,
-		Url:         public.ShareURL(r, share.ID),
+		Url:         public.ShareURL(r.Context(), share.ID),
 		Description: share.Description,
 		Username:    share.Username,
 		Created:     share.CreatedAt,

From c9385fbb6b2e985d6c03034cf44eb05237c7e417 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 31 Aug 2026 21:42:10 -0400
Subject: [PATCH 096/200] test(plugins): build test plugins in Go instead of
 shelling out to make (#6060)

* test(plugins): build test plugins in Go instead of shelling out to make

The plugins suite built its .ndp test packages by running `make -C
plugins/testdata`, which needs make and zip on the PATH. That is the reason
the 26 WASM-dependent spec files are tagged //go:build !windows.

buildTestPlugins now does the same work in Go: the same mtime check make
performed, `GOOS=wasip1 GOARCH=wasm go build` per plugin, and archive/zip
for the package. TinyGo was already optional and unused in CI, so nothing is
lost there. The first plugin builds on its own so the shared wasip1 stdlib
and PDK objects land in the build cache before the rest fan out: on a cold
cache that is 2.2s against 3.4s for the sequential make and 7.3s for an
unrestrained fan-out.

Packaging moved into a writeNdp helper shared with createTestPackage, which
was already writing the same two-entry archive. Entries are written in a
fixed order, so the .ndp bytes are now reproducible; the loader hashes those
bytes, and `zip` also stored file mtimes, so the previous packages differed
on every rebuild.

The Makefile is unchanged and still works for building the plugins by hand.
Removing the !windows tags is a separate step, once CI is green here.

* test(plugins): run the WASM plugin specs on Windows

With the test plugins now built in Go, nothing in the suite needs a Unix
toolchain, so the //go:build !windows tags come off all 25 spec files. The
Windows CI job runs `go test ./...`, so it picks the suite up with no
workflow change.

plugins_suite_windows_test.go existed only to bootstrap the handful of specs
that compiled on Windows; plugins_suite_test.go now serves both.

* test(plugins): skip the planted-symlink spec where symlinks need privileges

os.Symlink needs an elevated token or Developer Mode on Windows, so the
unconditional Expect(...).To(Succeed()) would fail for contributors running
the suite on an ordinary Windows box. The elevated GitHub runner hides this.

The equivalent spec in sandbox_fs_internal_test.go already attempts the
symlink and skips on error; this does the same, keeping the pin live
everywhere it can run, including Windows CI.

* fix(ci): stop the Windows ndpgen test failing silently

The ndpgen suite builds its helper binary to %TEMP%\ndpgen-test, and Windows
will not exec a file without an executable extension, so the "supports
verbose mode" spec has been failing there. Nobody noticed because the
Test ndpgen step ran under pwsh, which carries on after a non-zero exit and
takes the step's status from the last command, so the job stayed green with
a FAIL line in its log.

Add the .exe suffix, and run the step under bash like the Linux job does, so
a failure in any of its three commands fails the job.
---
 .github/workflows/pipeline.yml           |   6 +-
 plugins/cmd/ndpgen/integration_test.go   |   4 +
 plugins/host_artwork_test.go             |   2 -
 plugins/host_cache_test.go               |   2 -
 plugins/host_config_test.go              |   2 -
 plugins/host_httpclient_test.go          |   2 -
 plugins/host_kvstore_test.go             |   2 -
 plugins/host_library_test.go             |   2 -
 plugins/host_matcher_test.go             |   2 -
 plugins/host_scheduler_test.go           |   2 -
 plugins/host_scrobbleretriever_test.go   |   2 -
 plugins/host_storage_test.go             |   2 -
 plugins/host_subsonicapi_test.go         |   2 -
 plugins/host_taskqueue_test.go           |   2 -
 plugins/host_users_test.go               |   2 -
 plugins/host_websocket_test.go           |   2 -
 plugins/lyrics_adapter_test.go           |   2 -
 plugins/manager_call_test.go             |   2 -
 plugins/manager_loader_load_test.go      |   2 -
 plugins/manager_readonly_test.go         |   2 -
 plugins/manager_test.go                  |   2 -
 plugins/manager_watcher_test.go          |   2 -
 plugins/metadata_agent_test.go           |   2 -
 plugins/package_test.go                  |  50 +++++-----
 plugins/plugins_suite_test.go            |  12 ---
 plugins/plugins_suite_windows_test.go    |  23 -----
 plugins/sandbox_fs_test.go               |   6 +-
 plugins/scrobbler_adapter_test.go        |   2 -
 plugins/sonic_similarity_adapter_test.go |   2 -
 plugins/testdata_builder_test.go         | 119 +++++++++++++++++++++++
 30 files changed, 156 insertions(+), 110 deletions(-)
 delete mode 100644 plugins/plugins_suite_windows_test.go
 create mode 100644 plugins/testdata_builder_test.go

diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index 9da99e864..37b532eb0 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -237,12 +237,12 @@ jobs:
         run: go test -shuffle=on -tags netgo,sqlite_fts5 ./... -v
 
       - name: Test ndpgen
-        shell: pwsh
+        shell: bash
         run: |
-          cd plugins\cmd\ndpgen
+          cd plugins/cmd/ndpgen
           go test -shuffle=on -v
           go build -o ndpgen.exe .
-          .\ndpgen.exe --help
+          ./ndpgen.exe --help
 
   js:
     name: Test JS code
diff --git a/plugins/cmd/ndpgen/integration_test.go b/plugins/cmd/ndpgen/integration_test.go
index d8bc5859d..bbe886f8d 100644
--- a/plugins/cmd/ndpgen/integration_test.go
+++ b/plugins/cmd/ndpgen/integration_test.go
@@ -6,6 +6,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"strings"
 
 	. "github.com/onsi/ginkgo/v2"
@@ -32,6 +33,9 @@ var _ = Describe("ndpgen CLI", Ordered, func() {
 
 		// Build the ndpgen binary
 		ndpgenBin = filepath.Join(os.TempDir(), "ndpgen-test")
+		if runtime.GOOS == "windows" {
+			ndpgenBin += ".exe" // Windows refuses to exec a file without it
+		}
 		cmd := exec.Command("go", "build", "-o", ndpgenBin, ".")
 		cmd.Dir = mustGetWd(GinkgoT())
 		output, err := cmd.CombinedOutput()
diff --git a/plugins/host_artwork_test.go b/plugins/host_artwork_test.go
index 50a1a0335..311bf21d5 100644
--- a/plugins/host_artwork_test.go
+++ b/plugins/host_artwork_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_cache_test.go b/plugins/host_cache_test.go
index 5e91b04ec..925856701 100644
--- a/plugins/host_cache_test.go
+++ b/plugins/host_cache_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_config_test.go b/plugins/host_config_test.go
index b296d29fb..80b06efe1 100644
--- a/plugins/host_config_test.go
+++ b/plugins/host_config_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_httpclient_test.go b/plugins/host_httpclient_test.go
index 27e92d59d..4eb34a247 100644
--- a/plugins/host_httpclient_test.go
+++ b/plugins/host_httpclient_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_kvstore_test.go b/plugins/host_kvstore_test.go
index 997409146..9af3fcbcd 100644
--- a/plugins/host_kvstore_test.go
+++ b/plugins/host_kvstore_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_library_test.go b/plugins/host_library_test.go
index eb5b17a02..00a953b24 100644
--- a/plugins/host_library_test.go
+++ b/plugins/host_library_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_matcher_test.go b/plugins/host_matcher_test.go
index 9d44ee581..f0967628c 100644
--- a/plugins/host_matcher_test.go
+++ b/plugins/host_matcher_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_scheduler_test.go b/plugins/host_scheduler_test.go
index ca53aed56..6940d8820 100644
--- a/plugins/host_scheduler_test.go
+++ b/plugins/host_scheduler_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_scrobbleretriever_test.go b/plugins/host_scrobbleretriever_test.go
index ab817c282..aa92c9eb5 100644
--- a/plugins/host_scrobbleretriever_test.go
+++ b/plugins/host_scrobbleretriever_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_storage_test.go b/plugins/host_storage_test.go
index d6f895bff..9fc58c396 100644
--- a/plugins/host_storage_test.go
+++ b/plugins/host_storage_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_subsonicapi_test.go b/plugins/host_subsonicapi_test.go
index c3d9ffe8a..4b941bc43 100644
--- a/plugins/host_subsonicapi_test.go
+++ b/plugins/host_subsonicapi_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_taskqueue_test.go b/plugins/host_taskqueue_test.go
index d459fd69b..72fb4cccd 100644
--- a/plugins/host_taskqueue_test.go
+++ b/plugins/host_taskqueue_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_users_test.go b/plugins/host_users_test.go
index 42f6a3032..1721d3ee2 100644
--- a/plugins/host_users_test.go
+++ b/plugins/host_users_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/host_websocket_test.go b/plugins/host_websocket_test.go
index 2aa85cd21..9f2d20bef 100644
--- a/plugins/host_websocket_test.go
+++ b/plugins/host_websocket_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/lyrics_adapter_test.go b/plugins/lyrics_adapter_test.go
index d110665f5..fe15e40b2 100644
--- a/plugins/lyrics_adapter_test.go
+++ b/plugins/lyrics_adapter_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/manager_call_test.go b/plugins/manager_call_test.go
index 3e64f1cee..5e2c6385e 100644
--- a/plugins/manager_call_test.go
+++ b/plugins/manager_call_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/manager_loader_load_test.go b/plugins/manager_loader_load_test.go
index 8f35548af..eb004276e 100644
--- a/plugins/manager_loader_load_test.go
+++ b/plugins/manager_loader_load_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/manager_readonly_test.go b/plugins/manager_readonly_test.go
index 9d16b76e9..019b14fbf 100644
--- a/plugins/manager_readonly_test.go
+++ b/plugins/manager_readonly_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/manager_test.go b/plugins/manager_test.go
index 9b6f7ea39..6cf90994a 100644
--- a/plugins/manager_test.go
+++ b/plugins/manager_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/manager_watcher_test.go b/plugins/manager_watcher_test.go
index 5b5ffca02..99326bde1 100644
--- a/plugins/manager_watcher_test.go
+++ b/plugins/manager_watcher_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/metadata_agent_test.go b/plugins/metadata_agent_test.go
index a7a0aa8b8..0a7b6c1e2 100644
--- a/plugins/metadata_agent_test.go
+++ b/plugins/metadata_agent_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/package_test.go b/plugins/package_test.go
index 953797750..1539d8df7 100644
--- a/plugins/package_test.go
+++ b/plugins/package_test.go
@@ -2,8 +2,11 @@ package plugins
 
 import (
 	"archive/zip"
+	"bytes"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 
@@ -266,6 +269,14 @@ func (h *testZipHelper) close() error {
 // createTestPackage creates an .ndp package file from a manifest and wasm bytes.
 // This is primarily used for testing.
 func createTestPackage(ndpPath string, manifest *Manifest, wasmBytes []byte) error {
+	manifestBytes, err := json.Marshal(manifest)
+	if err != nil {
+		return fmt.Errorf("marshaling manifest: %w", err)
+	}
+	return writeNdp(ndpPath, bytes.NewReader(manifestBytes), bytes.NewReader(wasmBytes))
+}
+
+func writeNdp(ndpPath string, manifest, wasm io.Reader) error {
 	f, err := os.Create(ndpPath)
 	if err != nil {
 		return fmt.Errorf("creating package file: %w", err)
@@ -273,30 +284,23 @@ func createTestPackage(ndpPath string, manifest *Manifest, wasmBytes []byte) err
 	defer f.Close()
 
 	zw := zip.NewWriter(f)
-	defer zw.Close()
-
-	// Write manifest.json
-	manifestBytes, err := json.Marshal(manifest)
-	if err != nil {
-		return fmt.Errorf("marshaling manifest: %w", err)
+	add := func(name string, r io.Reader) error {
+		w, err := zw.Create(name)
+		if err != nil {
+			return fmt.Errorf("creating %s in package: %w", name, err)
+		}
+		if _, err := io.Copy(w, r); err != nil {
+			return fmt.Errorf("writing %s: %w", name, err)
+		}
+		return nil
 	}
-
-	mw, err := zw.Create(manifestFileName)
-	if err != nil {
-		return fmt.Errorf("creating manifest in zip: %w", err)
+	// Entry order is fixed: the loader hashes the package bytes, so they must
+	// be reproducible across rebuilds.
+	if err := add(manifestFileName, manifest); err != nil {
+		return err
 	}
-	if _, err := mw.Write(manifestBytes); err != nil {
-		return fmt.Errorf("writing manifest: %w", err)
+	if err := add(wasmFileName, wasm); err != nil {
+		return err
 	}
-
-	// Write plugin.wasm
-	ww, err := zw.Create(wasmFileName)
-	if err != nil {
-		return fmt.Errorf("creating wasm in zip: %w", err)
-	}
-	if _, err := ww.Write(wasmBytes); err != nil {
-		return fmt.Errorf("writing wasm: %w", err)
-	}
-
-	return nil
+	return errors.Join(zw.Close(), f.Close())
 }
diff --git a/plugins/plugins_suite_test.go b/plugins/plugins_suite_test.go
index 2dae65d00..cc1b45f97 100644
--- a/plugins/plugins_suite_test.go
+++ b/plugins/plugins_suite_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
@@ -7,15 +5,12 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
-	"fmt"
 	"net/http"
 	"os"
-	"os/exec"
 	"path/filepath"
 	"runtime"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -51,13 +46,6 @@ func TestPlugins(t *testing.T) {
 	RunSpecs(t, "Plugins Suite")
 }
 
-func buildTestPlugins(path string) {
-	start := time.Now()
-	out, err := exec.Command("make", "-C", path).CombinedOutput()
-	fmt.Fprintf(GinkgoWriter, "[BeforeSuite] built test plugins in %s:\n%s", time.Since(start), out)
-	Expect(err).ToNot(HaveOccurred(), "failed to build test plugins")
-}
-
 // createTestManager creates a new plugin Manager with the given plugin config.
 // It creates a temp directory, copies the test-metadata-agent plugin, and starts the manager.
 // Returns the manager, temp directory path, and a cleanup function.
diff --git a/plugins/plugins_suite_windows_test.go b/plugins/plugins_suite_windows_test.go
deleted file mode 100644
index ed43bdcc3..000000000
--- a/plugins/plugins_suite_windows_test.go
+++ /dev/null
@@ -1,23 +0,0 @@
-//go:build windows
-
-package plugins
-
-import (
-	"testing"
-
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/tests"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-// Runs the subset of plugin specs compiled on Windows (files without the
-// //go:build !windows tag): capabilities, manager_cache, manager_plugin,
-// manifest, package. WASM-runtime-dependent specs live in !windows-tagged
-// files and aren't reached here.
-func TestPlugins(t *testing.T) {
-	tests.Init(t, false)
-	log.SetLevel(log.LevelFatal)
-	RegisterFailHandler(Fail)
-	RunSpecs(t, "Plugins Suite")
-}
diff --git a/plugins/sandbox_fs_test.go b/plugins/sandbox_fs_test.go
index ea033283f..0dd9d15ab 100644
--- a/plugins/sandbox_fs_test.go
+++ b/plugins/sandbox_fs_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
@@ -134,7 +132,9 @@ var _ = Describe("Plugin filesystem sandbox", Ordered, ContinueOnFailure, func()
 
 	// Accepted residual, pinned so a future tightening can't happen silently
 	It("still follows a symlink planted in the mount by something else", func() {
-		Expect(os.Symlink(outsideDir, filepath.Join(libraryDir, "planted"))).To(Succeed())
+		if err := os.Symlink(outsideDir, filepath.Join(libraryDir, "planted")); err != nil {
+			Skip("cannot create symlinks here: " + err.Error()) // Windows without privileges
+		}
 
 		out := call(sandboxInput{Operation: "write_file", FilePath: "planted/via-symlink.txt", Content: "escaped"})
 
diff --git a/plugins/scrobbler_adapter_test.go b/plugins/scrobbler_adapter_test.go
index 3efd5d1b1..00c9045a4 100644
--- a/plugins/scrobbler_adapter_test.go
+++ b/plugins/scrobbler_adapter_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/sonic_similarity_adapter_test.go b/plugins/sonic_similarity_adapter_test.go
index cb08b9acd..e08fc124f 100644
--- a/plugins/sonic_similarity_adapter_test.go
+++ b/plugins/sonic_similarity_adapter_test.go
@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (
diff --git a/plugins/testdata_builder_test.go b/plugins/testdata_builder_test.go
new file mode 100644
index 000000000..746a8af22
--- /dev/null
+++ b/plugins/testdata_builder_test.go
@@ -0,0 +1,119 @@
+package plugins
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/utils"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// buildTestPlugins packages every test plugin under dir, replicating
+// `make -C plugins/testdata` without needing make or zip on the PATH.
+func buildTestPlugins(dir string) {
+	start := time.Now()
+	built, err := buildPackages(dir)
+	fmt.Fprintf(GinkgoWriter, "[BeforeSuite] built test plugins in %s: %v\n", time.Since(start), built)
+	Expect(err).ToNot(HaveOccurred(), "failed to build test plugins")
+}
+
+func buildPackages(dir string) ([]string, error) {
+	mods, err := filepath.Glob(filepath.Join(dir, "*", "go.mod"))
+	if err != nil || len(mods) == 0 {
+		return nil, err
+	}
+	pdkTime, err := newestModTime(filepath.Join(dir, "..", "pdk", "go"))
+	if err != nil {
+		return nil, err
+	}
+
+	built := make([]string, len(mods))
+	errs := make([]error, len(mods))
+	build := func(i int) {
+		pluginDir := filepath.Dir(mods[i])
+		var rebuilt bool
+		if rebuilt, errs[i] = buildPackage(pluginDir, pdkTime); rebuilt {
+			built[i] = filepath.Base(pluginDir)
+		}
+	}
+
+	// The first build populates the wasip1 stdlib and PDK objects every plugin
+	// shares; fanning out before it lands makes each one compile them again.
+	build(0)
+	var wg sync.WaitGroup
+	for i := range mods[1:] {
+		wg.Go(func() { build(i + 1) })
+	}
+	wg.Wait()
+	return slices.DeleteFunc(built, func(name string) bool { return name == "" }), errors.Join(errs...)
+}
+
+func buildPackage(dir string, pdkTime time.Time) (bool, error) {
+	sourceTime, err := newestModTime(dir)
+	if err != nil {
+		return false, err
+	}
+	pkg := dir + PackageExtension
+	if info, err := os.Stat(pkg); err == nil && info.ModTime().After(utils.TimeNewest(sourceTime, pdkTime)) {
+		return false, nil
+	}
+
+	wasm, err := filepath.Abs(pkg + ".build.wasm")
+	if err != nil {
+		return false, err
+	}
+	defer os.Remove(wasm)
+	// -buildvcs=false keeps the bytes stable across commits, so the suite's
+	// wazero compilation cache still hits after a rebuild.
+	cmd := exec.Command("go", "build", "-buildvcs=false", "-buildmode=c-shared", "-o", wasm, ".")
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "GOOS=wasip1", "GOARCH=wasm")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		return false, fmt.Errorf("building %s: %w\n%s", dir, err, out)
+	}
+
+	tmp := pkg + ".build.ndp"
+	defer os.Remove(tmp)
+	if err := packageFiles(tmp, filepath.Join(dir, manifestFileName), wasm); err != nil {
+		return false, fmt.Errorf("packaging %s: %w", dir, err)
+	}
+	return true, os.Rename(tmp, pkg)
+}
+
+func packageFiles(pkg, manifest, wasm string) error {
+	m, err := os.Open(manifest)
+	if err != nil {
+		return err
+	}
+	defer m.Close()
+	w, err := os.Open(wasm)
+	if err != nil {
+		return err
+	}
+	defer w.Close()
+	return writeNdp(pkg, m, w)
+}
+
+func newestModTime(root string) (time.Time, error) {
+	var newest time.Time
+	err := filepath.WalkDir(root, func(_ string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return err
+		}
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		newest = utils.TimeNewest(newest, info.ModTime())
+		return nil
+	})
+	return newest, err
+}

From 4ed7494a3293a9e9e647897ebfb9be327efd981b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 31 Aug 2026 23:03:09 -0400
Subject: [PATCH 097/200] ci: report Go test coverage on pull requests (#6061)

* ci: report Go test coverage on pull requests

Adds octocov to the existing 'Test Go code' job. It reads the coverage
profile, posts a PR comment with the coverage percentage and the delta
against master, and writes the same report to the job summary.

The master-branch report is stored as a GitHub Actions artifact, so no
external service or secret is needed.

* ci: merge the plugins job coverage into the same report

The plugins suite runs in its own job, so its coverage was missing from
the report. Both jobs now upload their profile as an artifact and a new
'Report coverage' job merges them into a single PR comment.

* ci: update the coverage comment in place instead of reposting

octocov's default is to collapse the previous comment and create a new
one. updatePrevious edits the existing comment instead, so a PR keeps a
single coverage comment across pushes.

* ci: fix octocov timeout and step-time lookup

Storing the report hit the 30s default timeout: scanning this repo's
artifacts for the baseline consumed it first. Raise it to 5m.

The step-time lookup also matched the Windows job's 'Test' step and
waited for a job that was still running, so execution time was dropped
from the report. Rename the step to make it unique.

* ci: only store the coverage baseline from the default branch

* ci: report statement coverage instead of line coverage

octocov reports statement coverage for a single profile but switches to
line counting when it merges several itself, which made the number
disagree with 'go tool cover -func'. Merge the two job profiles into one
file first, so the reported number matches what developers see locally.

* ci: stop the download-link comment from clobbering the coverage report

Both comments are posted by github-actions[bot], and the download-link
job updated the first bot comment it found. On a new PR the coverage
comment is created first, so it would be overwritten. Match on the body
as well, and keep the coverage profiles out of the download list.
---
 .github/workflows/download-link-on-pr.yml | 11 ++++--
 .github/workflows/pipeline.yml            | 47 +++++++++++++++++++++--
 .octocov.yml                              | 33 ++++++++++++++++
 3 files changed, 84 insertions(+), 7 deletions(-)
 create mode 100644 .octocov.yml

diff --git a/.github/workflows/download-link-on-pr.yml b/.github/workflows/download-link-on-pr.yml
index 5b421331b..80ec18e90 100644
--- a/.github/workflows/download-link-on-pr.yml
+++ b/.github/workflows/download-link-on-pr.yml
@@ -34,16 +34,19 @@ jobs:
             }
 
             const {data: {artifacts}} = await github.rest.actions.listWorkflowRunArtifacts({owner, repo, run_id});
-            if (!artifacts.length) {
+            const downloadable = artifacts.filter((art) => !art.name.startsWith('octocov-'));
+            if (!downloadable.length) {
               return core.error(`No artifacts found`);
             }
-            let body = `Download the artifacts for this pull request:\n`;
-            for (const art of artifacts) {
+            const header = `Download the artifacts for this pull request:`;
+            let body = `${header}\n`;
+            for (const art of downloadable) {
               body += `\n* [${art.name}.zip](https://nightly.link/${owner}/${repo}/actions/artifacts/${art.id}.zip)`;
             }
 
             const {data: comments} = await github.rest.issues.listComments({repo, owner, issue_number});
-            const existing_comment = comments.find((c) => c.user.login === 'github-actions[bot]');
+            // Match on the body too: octocov also comments as github-actions[bot].
+            const existing_comment = comments.find((c) => c.user.login === 'github-actions[bot]' && c.body.startsWith(header));
             if (existing_comment) {
               core.info(`Updating comment ${existing_comment.id}`);
               await github.rest.issues.updateComment({repo, owner, comment_id: existing_comment.id, body});
diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index 37b532eb0..7625cf410 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -137,8 +137,10 @@ jobs:
       - name: Download dependencies
         run: go mod download
 
-      - name: Test
-        run: go test -shuffle=on -tags netgo,sqlite_fts5 -race -v $(go list ./... | grep -v '/plugins$')
+      # Name must stay unique across the workflow: octocov matches step names
+      # by name across every job, and waits for each match to finish.
+      - name: Test with coverage
+        run: go test -shuffle=on -tags netgo,sqlite_fts5 -race -v -covermode=atomic -coverprofile=coverage.out $(go list ./... | grep -v '/plugins$')
 
       - name: Test ndpgen
         run: |
@@ -147,6 +149,13 @@ jobs:
           go build -o ndpgen .
           ./ndpgen --help
 
+      - name: Upload coverage profile
+        uses: actions/upload-artifact@v7
+        with:
+          name: octocov-go
+          path: coverage.out
+          if-no-files-found: error
+
   go-plugins:
     name: Test Go plugins
     runs-on: ubuntu-latest
@@ -169,7 +178,39 @@ jobs:
           restore-keys: wazero-${{ runner.os }}-
 
       - name: Test plugins
-        run: go tool ginkgo -p -race -tags netgo,sqlite_fts5 ./plugins/
+        run: go tool ginkgo -p -race -tags netgo,sqlite_fts5 --cover --covermode=atomic --coverprofile=coverage.out --output-dir=. ./plugins/
+
+      - name: Upload coverage profile
+        uses: actions/upload-artifact@v7
+        with:
+          name: octocov-plugins
+          path: coverage.out
+          if-no-files-found: error
+
+  coverage:
+    name: Report coverage
+    runs-on: ubuntu-latest
+    needs: [go, go-plugins]
+    permissions:
+      contents: read
+      pull-requests: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: octocov-*
+
+      # Merge here rather than letting octocov do it: octocov reports statement
+      # coverage for a single profile, but switches to line counting for several.
+      - name: Merge coverage profiles
+        run: |
+          echo "mode: atomic" > coverage.out
+          awk 'FNR==1 && /^mode:/ {next} {k=$1" "$2; c[k]+=$3} END {for (k in c) print k, c[k]}' \
+            octocov-*/coverage.out | sort >> coverage.out
+
+      - uses: k1LoW/octocov-action@v1
 
   go-windows:
     name: Test Go code (Windows)
diff --git a/.octocov.yml b/.octocov.yml
new file mode 100644
index 000000000..397b5b364
--- /dev/null
+++ b/.octocov.yml
@@ -0,0 +1,33 @@
+# Code coverage reporting for pull requests. See https://github.com/k1LoW/octocov
+# The 30s default is not enough: scanning this repo's artifacts for the baseline
+# eats most of it, leaving none for the report upload.
+timeout: 5m
+coverage:
+  # A single pre-merged profile: octocov reports statements for one path, but
+  # switches to line counting when it merges several itself.
+  paths:
+    - coverage.out
+codeToTestRatio:
+  code:
+    - '**/*.go'
+    - '!**/*_test.go'
+    - '!**/*_gen.go'
+  test:
+    - '**/*_test.go'
+testExecutionTime:
+  if: true
+  steps:
+    - Test with coverage
+    - Test plugins
+diff:
+  datastores:
+    - artifact://${GITHUB_REPOSITORY}
+comment:
+  if: is_pull_request
+  updatePrevious: true
+summary:
+  if: true
+report:
+  if: is_default_branch
+  datastores:
+    - artifact://${GITHUB_REPOSITORY}

From 09867e5cc18678cb9ae9579c912dc54a597bf651 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 1 Sep 2026 07:32:28 -0400
Subject: [PATCH 098/200] ci: comment coverage on pull requests from forks
 (#6065)

* ci: comment coverage on pull requests from forks

A pull_request run from a fork gets a read-only GITHUB_TOKEN, so octocov could not post its comment: it logged a 403 and exited 0, leaving the job green and the PR silent. The 'permissions:' block cannot grant what the token does not have.

The comment now comes from a workflow_run workflow, which runs on the base repository and does get a write token. The pipeline job keeps the job summary and the default-branch baseline, and hands the merged profile and the PR number to it as an artifact.

A workflow_run job otherwise looks like a push to the default branch, so octocov is pointed back at the pull request and at the run that produced the profile via its OCTOCOV_ environment overrides. Without the run id override the test execution time would be read from the wrong run; without the ref override a fork's coverage would be stored as the master baseline.

The job holds a write token, so it reads .octocov.yml from the base branch rather than from the fork.

* ci: stop checking out the fork in the coverage comment workflow

CodeQL flagged the pull request checkout as untrusted code in a privileged context (actions/untrusted-checkout/high): the job holds a write token. The checkout existed only so the code-to-test ratio would reflect the pull request, which does not justify the alert.

The workflow now checks out just .octocov.yml from the base branch, and the ratio is skipped when reporting from there. Coverage and its delta against master, the metrics that motivated the report, are unaffected: they come from the profile the pipeline uploads.

* ci: treat the coverage artifact as untrusted input

A pull_request run executes the fork's own copy of pipeline.yml, so every file in the octocov-pr artifact is attacker-controlled. The artifact was extracted into the workspace root, on top of the base-branch checkout, and download-artifact truncates existing files. A fork could therefore replace .octocov.yml before octocov loaded it.

That is not only a config swap. config.Load expands ${VAR} from the job environment and the action sets OCTOCOV_GITHUB_TOKEN, so a crafted comment.message posts the privileged job's token into a public comment; a body: section rewrites a pull request description, which pull-requests: write allows.

The artifact now lands in a subdirectory and only coverage.out is copied out, after pr_number is checked to be digits and the named pull request's head is confirmed to be the sha that triggered this run. Without that check the artifact could aim the comment at any open pull request, and unvalidated content reached GITHUB_OUTPUT.
---
 .github/workflows/coverage-on-pr.yml | 60 ++++++++++++++++++++++++++++
 .github/workflows/pipeline.yml       | 17 +++++++-
 .octocov.yml                         |  7 +++-
 3 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/coverage-on-pr.yml

diff --git a/.github/workflows/coverage-on-pr.yml b/.github/workflows/coverage-on-pr.yml
new file mode 100644
index 000000000..03260cacc
--- /dev/null
+++ b/.github/workflows/coverage-on-pr.yml
@@ -0,0 +1,60 @@
+name: Report coverage on PR
+on:
+  workflow_run:
+    workflows: ['Pipeline: Test, Lint, Build']
+    types: [completed]
+jobs:
+  comment:
+    name: Comment coverage report
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+      pull-requests: write
+    env:
+      COVERAGE_COMMENT: 'true'
+    steps:
+      # Only the config, from the base branch: this job holds a write token, so
+      # it must never check out the fork.
+      - name: Check out the octocov config
+        uses: actions/checkout@v7
+        with:
+          sparse-checkout: .octocov.yml
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
+
+      # Into a subdirectory. A pull_request run executes the fork's own copy of
+      # pipeline.yml, so every file in here is attacker-controlled.
+      - uses: actions/download-artifact@v8
+        with:
+          name: octocov-pr
+          path: untrusted
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      - name: Verify the artifact and take the coverage profile
+        id: pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          number=$(head -c 20 untrusted/pr_number | tr -d '[:space:]')
+          case "$number" in ''|*[!0-9]*)
+            echo "::error::artifact pr_number is not a number"; exit 1;;
+          esac
+          sha=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$number" --jq .head.sha)
+          if [ "$sha" != "$HEAD_SHA" ]; then
+            echo "::error::artifact claims PR #$number, but its head $sha is not $HEAD_SHA"; exit 1
+          fi
+          cp untrusted/coverage.out coverage.out
+          echo "number=$number" >> "$GITHUB_OUTPUT"
+
+      - uses: k1LoW/octocov-action@v1
+        env:
+          # A workflow_run job looks like a push to the default branch. Point
+          # octocov back at the pull request and at the run that produced it.
+          GITHUB_PULL_REQUEST_NUMBER: ${{ steps.pr.outputs.number }}
+          OCTOCOV_GITHUB_REF: refs/pull/${{ steps.pr.outputs.number }}/merge
+          OCTOCOV_GITHUB_SHA: ${{ github.event.workflow_run.head_sha }}
+          OCTOCOV_GITHUB_RUN_ID: ${{ github.event.workflow_run.id }}
diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index 7625cf410..aa8e29e49 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -193,8 +193,9 @@ jobs:
     needs: [go, go-plugins]
     permissions:
       contents: read
-      pull-requests: write
       actions: write
+    env:
+      COVERAGE_COMMENT: 'false'
     steps:
       - uses: actions/checkout@v7
 
@@ -212,6 +213,20 @@ jobs:
 
       - uses: k1LoW/octocov-action@v1
 
+      - name: Save the PR number for the comment workflow
+        if: github.event_name == 'pull_request'
+        run: echo "${{ github.event.pull_request.number }}" > pr_number
+
+      - name: Upload the merged profile for the comment workflow
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v7
+        with:
+          name: octocov-pr
+          path: |
+            coverage.out
+            pr_number
+          if-no-files-found: error
+
   go-windows:
     name: Test Go code (Windows)
     runs-on: windows-2022
diff --git a/.octocov.yml b/.octocov.yml
index 397b5b364..52d4ff9bf 100644
--- a/.octocov.yml
+++ b/.octocov.yml
@@ -8,6 +8,9 @@ coverage:
   paths:
     - coverage.out
 codeToTestRatio:
+  # Needs the pull request's own source, which the comment workflow must not
+  # check out: it holds a write token.
+  if: env.COVERAGE_COMMENT != 'true'
   code:
     - '**/*.go'
     - '!**/*_test.go'
@@ -23,7 +26,9 @@ diff:
   datastores:
     - artifact://${GITHUB_REPOSITORY}
 comment:
-  if: is_pull_request
+  # Only the 'Report coverage on PR' workflow sets this: a pull_request run from
+  # a fork gets a read-only token, so commenting from here 403s.
+  if: env.COVERAGE_COMMENT == 'true'
   updatePrevious: true
 summary:
   if: true

From 3784fd0ea7c0d902a513777bef9f2c8f015ad42e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 1 Sep 2026 11:07:58 -0400
Subject: [PATCH 099/200] fix(artwork): honor a provider's explicit retry-later
 delay in the circuit breaker (#6056)

An explicit RetryLaterError now opens the agent's breaker immediately for the
provider's own delay, instead of counting it as one generic failure that needs
five to open and then always probes after a fixed minute.
---
 core/artwork/gate.go      | 19 ++++++++++++++++++-
 core/artwork/gate_test.go | 13 +++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/core/artwork/gate.go b/core/artwork/gate.go
index ebb65bcbe..aa2ad8f2f 100644
--- a/core/artwork/gate.go
+++ b/core/artwork/gate.go
@@ -1,6 +1,7 @@
 package artwork
 
 import (
+	"cmp"
 	"context"
 	"errors"
 	"io"
@@ -95,6 +96,9 @@ type breaker struct {
 	// generation identifies the current open episode, so an answer from a call admitted before
 	// the breaker opened cannot be mistaken for evidence that it has recovered.
 	generation int
+	// probeAfter overrides the probe delay for the current episode when a provider named its own
+	// back-off; zero falls back to breakerProbeAfter.
+	probeAfter time.Duration
 }
 
 func newBreaker() *breaker { return &breaker{} }
@@ -107,7 +111,7 @@ func (b *breaker) allow() (bool, int) {
 	if b.failures < breakerThreshold {
 		return true, 0
 	}
-	if time.Since(b.openedAt) >= breakerProbeAfter {
+	if time.Since(b.openedAt) >= cmp.Or(b.probeAfter, breakerProbeAfter) {
 		b.openedAt = time.Now() // start a fresh probe window so only one caller passes
 		return true, b.generation
 	}
@@ -121,11 +125,24 @@ func (b *breaker) record(name string, gen int, err error) {
 	}
 	b.mu.Lock()
 	defer b.mu.Unlock()
+	// An explicit back-off is a definitive "stop for this long", so it opens the breaker at once
+	// with the provider's own delay instead of waiting for the failure threshold.
+	if retry, ok := errors.AsType[*agents.RetryLaterError](err); ok && retry.RetryIn > 0 {
+		b.recoveries = 0
+		b.failures = breakerThreshold
+		b.openedAt = time.Now()
+		b.probeAfter = retry.RetryIn
+		b.generation++
+		log.Warn("Artwork: Circuit breaker opened for agent, provider asked to back off", "agent", name,
+			"probeAfter", retry.RetryIn)
+		return
+	}
 	if isTransientExternal(err) {
 		b.recoveries = 0
 		b.failures++
 		if b.failures == breakerThreshold {
 			b.openedAt = time.Now()
+			b.probeAfter = 0
 			b.generation++
 			log.Warn("Artwork: Circuit breaker opened for agent", "agent", name,
 				"consecutiveFailures", b.failures, "probeAfter", breakerProbeAfter, err)
diff --git a/core/artwork/gate_test.go b/core/artwork/gate_test.go
index abe723508..a954d4cac 100644
--- a/core/artwork/gate_test.go
+++ b/core/artwork/gate_test.go
@@ -2,7 +2,9 @@ package artwork
 
 import (
 	"errors"
+	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -40,4 +42,15 @@ var _ = Describe("breaker", func() {
 		Expect(allowed(b)).To(BeFalse(),
 			"answers from calls admitted before the breaker opened must not close it")
 	})
+
+	It("opens at once when a provider asks to retry later, honoring its delay", func() {
+		b := newBreaker()
+		Expect(allowed(b)).To(BeTrue(), "starts closed")
+
+		// A single explicit back-off opens the breaker without reaching the failure threshold.
+		b.record("agentA", 0, &agents.RetryLaterError{RetryIn: 5 * time.Second})
+
+		Expect(allowed(b)).To(BeFalse(), "an explicit back-off opens the breaker immediately")
+		Expect(b.probeAfter).To(Equal(5*time.Second), "the provider's delay drives the probe interval")
+	})
 })

From 88cd1c39374783e30ac7b5bcd9401789243a6cd7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 1 Sep 2026 17:17:52 -0400
Subject: [PATCH 100/200] fix(deezer): treat an exhausted quota as a throttle,
 not as a missing artist (#6068)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(deezer): treat an exhausted quota as a throttle, not as a missing artist

Deezer reports quota exhaustion in the response body, with HTTP 200 and no
rate-limit headers. The client only looked for errors when the status was
not 200, so a throttled reply was decoded into an empty result type, and an
empty search became ErrNotFound. The agent then compounded it: it tested
`errors.Is(err, ErrNotFound) || len(artists) == 0` before testing err, so
any failed search — which also returns no artists — reported not-found too.

The artwork worker settles an entity as "no image" on agents.ErrNotFound.
So being throttled did not make Navidrome back off; it made it record the
artist as having no artwork, and move on to do the same to the next one.

Errors are now parsed out of the body regardless of status, and the quota
code is joined with agents.RetryLaterError so the circuit breaker and the
artwork retry budget see a throttle for what it is. The agent checks err
before the empty-result case.

Last.fm already handles this exact shape (client.go errCodeRateLimit, with
a comment noting the 200-with-body-error pattern); this brings Deezer in
line with it, including the zero-delay RetryLaterError so both providers
share the default cooldown rather than a per-provider number.

Measured against the live API to pin the shape: a 120-request burst
returned 54 results and 66 quota replies, every one of them HTTP 200 with
{"error":{"type":"Exception","message":"Quota limit exceeded","code":4}}
and no Retry-After or rate-limit headers. A single request 5s later
succeeded, so the window is short and a cooldown fully clears it.

* refactor(deezer): fold the error envelope into one type

The envelope declared the code and message inline, parseBodyError copied
them field by field into a second struct with the same shape, and a zero
Code stood in for "no error reported". Making the envelope hold a pointer
to the error type removes all three: absent is nil, present is the error
itself, and the value returned needs no conversion.

searchArtist loses its empty-result branch. searchArtists converts an
empty result to errNotFound and returns early on any error, so it never
answers with no artists and no error, and the branch could not run. What
it left behind was a comment explaining an ordering that only mattered
while the branch existed.

ErrNotFound is unexported: nothing outside this package referenced it,
and it sat three lines from agents.ErrNotFound, which is a different
error with the opposite meaning for callers.

Throttling now joins agents.ErrRetryLater, the sentinel documented as the
zero-delay RetryLaterError, rather than allocating an equivalent value.

* refactor(deezer): return agents.ErrNotFound from the client

The client raised a package-local sentinel that the agent then translated
into agents.ErrNotFound, one call site each. Deezer was the only adapter
carrying its own: last.fm and listenbrainz have none.

The client already reports throttling with agents.ErrRetryLater, so it
already speaks the agent vocabulary; saying "not found" in the same words
costs nothing and lets searchArtist drop to plain error propagation.

* test(scrobbler): remove a race in the longest-server-delay test

newBufferedScrobbler starts its drain goroutine, and run() drains once
before it ever waits on the wake signal. The test enqueued user2, then
enqueued user1 via Scrobble, so that startup drain could land between
the two: it saw only user2, took its 45s delay, and set backingOff. The
wake from the second enqueue is then deliberately ignored — a wake
during a backoff window must not drain, which is the hammering the
window exists to prevent — so user1 was never attempted and the first
assertion read 1 instead of 2.

Buffering both users before the goroutine exists removes the window.
The test no longer goes through Scrobble, which the sibling tests
already cover; what this one is about is which delay wins.

Reproduced deterministically by forcing the interleaving with a
synctest.Wait between the two enqueues, which fails with the same
"expected both users drained, got 1 attempts" seen in CI. With both
enqueued first, that same forced drain passes.
---
 adapters/deezer/client.go                 | 44 +++++++++++++++++------
 adapters/deezer/client_test.go            | 34 +++++++++++++++++-
 adapters/deezer/deezer.go                 |  3 --
 adapters/deezer/deezer_test.go            | 17 +++++++++
 adapters/deezer/responses.go              |  8 ++---
 adapters/deezer/responses_test.go         |  2 +-
 core/scrobbler/buffered_scrobbler_test.go |  7 ++--
 7 files changed, 90 insertions(+), 25 deletions(-)

diff --git a/adapters/deezer/client.go b/adapters/deezer/client.go
index d51f65dd9..03f37af19 100644
--- a/adapters/deezer/client.go
+++ b/adapters/deezer/client.go
@@ -13,15 +13,26 @@ import (
 	"strings"
 
 	"github.com/microcosm-cc/bluemonday"
+	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/log"
 )
 
 const apiBaseURL = "https://api.deezer.com"
 const authBaseURL = "https://auth.deezer.com"
 
-var (
-	ErrNotFound = errors.New("deezer: not found")
-)
+// errCodeQuota is Deezer's "Quota limit exceeded"; it arrives in the body, with HTTP 200
+// and no rate-limit headers, so the body code is the only signal.
+const errCodeQuota = 4
+
+type deezerError struct {
+	Type    string `json:"type"`
+	Message string `json:"message"`
+	Code    int    `json:"code"`
+}
+
+func (e *deezerError) Error() string {
+	return fmt.Sprintf("deezer error(%d): %s", e.Code, e.Message)
+}
 
 type httpDoer interface {
 	Do(req *http.Request) (*http.Response, error)
@@ -56,7 +67,7 @@ func (c *client) searchArtists(ctx context.Context, name string, limit int) ([]A
 	}
 
 	if len(results.Data) == 0 {
-		return nil, ErrNotFound
+		return nil, agents.ErrNotFound
 	}
 	return results.Data, nil
 }
@@ -74,20 +85,31 @@ func (c *client) makeRequest(req *http.Request, response any) error {
 		return err
 	}
 
+	// Checked before the status: a throttled request still answers 200, and decoding its body
+	// into a result type yields an empty one, which reads as "nothing found".
+	if err := parseBodyError(data); err != nil {
+		return err
+	}
 	if resp.StatusCode != 200 {
-		return c.parseError(data)
+		return fmt.Errorf("deezer http status: (%d)", resp.StatusCode)
 	}
 
 	return json.Unmarshal(data, response)
 }
 
-func (c *client) parseError(data []byte) error {
-	var deezerError Error
-	err := json.Unmarshal(data, &deezerError)
-	if err != nil {
-		return err
+// parseBodyError returns the error Deezer reported in the body, or nil when it reported none.
+func parseBodyError(data []byte) error {
+	var body errorResponse
+	// Discarded: a payload that is not an error object leaves Error nil, which is the "none" answer.
+	_ = json.Unmarshal(data, &body)
+	switch {
+	case body.Error == nil:
+		return nil
+	case body.Error.Code == errCodeQuota:
+		return errors.Join(body.Error, agents.ErrRetryLater)
+	default:
+		return body.Error
 	}
-	return fmt.Errorf("deezer error(%d): %s", deezerError.Error.Code, deezerError.Error.Message)
 }
 
 func (c *client) getRelatedArtists(ctx context.Context, artistID int) ([]Artist, error) {
diff --git a/adapters/deezer/client_test.go b/adapters/deezer/client_test.go
index 9fa7afdd9..84d981a76 100644
--- a/adapters/deezer/client_test.go
+++ b/adapters/deezer/client_test.go
@@ -2,12 +2,14 @@ package deezer
 
 import (
 	"bytes"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
 	"os"
 	"time"
 
+	"github.com/navidrome/navidrome/core/agents"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -41,7 +43,37 @@ var _ = Describe("client", func() {
 			})
 
 			_, err := client.searchArtists(GinkgoT().Context(), "Michael Jackson", 20)
-			Expect(err).To(MatchError(ErrNotFound))
+			Expect(err).To(MatchError(agents.ErrNotFound))
+		})
+
+		// Deezer answers 200 with no rate-limit headers when throttling, so this body is the only signal.
+		It("reports an exhausted quota as a retryable error, not as a missing artist", func() {
+			httpClient.mock("https://api.deezer.com/search/artist", http.Response{
+				StatusCode: 200,
+				Body: io.NopCloser(bytes.NewBufferString(
+					`{"error":{"type":"Exception","message":"Quota limit exceeded","code":4}}`)),
+			})
+
+			_, err := client.searchArtists(GinkgoT().Context(), "Michael Jackson", 20)
+			Expect(err).To(HaveOccurred())
+			Expect(err).ToNot(MatchError(agents.ErrNotFound),
+				"a throttled lookup would otherwise settle the artist as having no image")
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
+			Expect(err.Error()).To(ContainSubstring("Quota limit exceeded"))
+		})
+
+		It("reports a non-quota body error as a plain error", func() {
+			httpClient.mock("https://api.deezer.com/search/artist", http.Response{
+				StatusCode: 200,
+				Body: io.NopCloser(bytes.NewBufferString(
+					`{"error":{"type":"Exception","message":"Invalid query","code":100}}`)),
+			})
+
+			_, err := client.searchArtists(GinkgoT().Context(), "Michael Jackson", 20)
+			Expect(err).To(HaveOccurred())
+			Expect(err).ToNot(MatchError(agents.ErrNotFound))
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeFalse(),
+				"only a throttle asks the caller to come back later")
 		})
 	})
 
diff --git a/adapters/deezer/deezer.go b/adapters/deezer/deezer.go
index 1fa10e25c..d3570a29f 100644
--- a/adapters/deezer/deezer.go
+++ b/adapters/deezer/deezer.go
@@ -91,9 +91,6 @@ func isPlaceholderPicture(url string) bool {
 
 func (s *deezerAgent) searchArtist(ctx context.Context, name string) (*Artist, error) {
 	artists, err := s.client.searchArtists(ctx, name, deezerArtistSearchLimit)
-	if errors.Is(err, ErrNotFound) || len(artists) == 0 {
-		return nil, agents.ErrNotFound
-	}
 	if err != nil {
 		return nil, err
 	}
diff --git a/adapters/deezer/deezer_test.go b/adapters/deezer/deezer_test.go
index 360db1f13..82d02c244 100644
--- a/adapters/deezer/deezer_test.go
+++ b/adapters/deezer/deezer_test.go
@@ -3,6 +3,7 @@ package deezer
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -80,6 +81,22 @@ var _ = Describe("deezerAgent", func() {
 			Expect(artist.ID).To(Equal(2))
 		})
 
+		// The artwork worker settles an artist as "no image" on agents.ErrNotFound, so a throttled
+		// lookup reaching that here would record a permanent absence.
+		It("surfaces an exhausted quota instead of reporting the artist as not found", func() {
+			httpClient.mock("https://api.deezer.com/search/artist", http.Response{
+				StatusCode: 200,
+				Body: io.NopCloser(bytes.NewBufferString(
+					`{"error":{"type":"Exception","message":"Quota limit exceeded","code":4}}`)),
+			})
+
+			_, err := agent.searchArtist(ctx, "Queen")
+
+			Expect(err).To(HaveOccurred())
+			Expect(err).ToNot(MatchError(agents.ErrNotFound))
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeTrue())
+		})
+
 		It("returns ErrNotFound when no result matches the name exactly", func() {
 			httpClient.mock("https://api.deezer.com/search/artist", http.Response{
 				StatusCode: 200,
diff --git a/adapters/deezer/responses.go b/adapters/deezer/responses.go
index 266c44c62..6cc95dd4b 100644
--- a/adapters/deezer/responses.go
+++ b/adapters/deezer/responses.go
@@ -22,12 +22,8 @@ type Artist struct {
 	Type          string `json:"type"`
 }
 
-type Error struct {
-	Error struct {
-		Type    string `json:"type"`
-		Message string `json:"message"`
-		Code    int    `json:"code"`
-	} `json:"error"`
+type errorResponse struct {
+	Error *deezerError `json:"error"`
 }
 
 type RelatedArtists struct {
diff --git a/adapters/deezer/responses_test.go b/adapters/deezer/responses_test.go
index a9de5c5fb..5a3fc7798 100644
--- a/adapters/deezer/responses_test.go
+++ b/adapters/deezer/responses_test.go
@@ -26,7 +26,7 @@ var _ = Describe("Responses", func() {
 
 	Describe("Error", func() {
 		It("parses the error response correctly", func() {
-			var errorResp Error
+			var errorResp errorResponse
 			body := []byte(`{"error":{"type":"MissingParameterException","message":"Missing parameters: q","code":501}}`)
 			err := json.Unmarshal(body, &errorResp)
 			Expect(err).To(BeNil())
diff --git a/core/scrobbler/buffered_scrobbler_test.go b/core/scrobbler/buffered_scrobbler_test.go
index fd972e87d..16172194b 100644
--- a/core/scrobbler/buffered_scrobbler_test.go
+++ b/core/scrobbler/buffered_scrobbler_test.go
@@ -251,12 +251,13 @@ func TestBufferedScrobblerTakesTheLongestServerDelayAcrossUsers(t *testing.T) {
 			"user1": 10 * time.Second,
 			"user2": 45 * time.Second,
 		}}
+		// Both are buffered before the drain goroutine exists: it drains once on startup, and
+		// seeing only one user there would park it on that user's delay, ignoring the other.
+		_ = buffer.Enqueue("test", "user1", "1", time.Now())
+		_ = buffer.Enqueue("test", "user2", "2", time.Now())
 		bs := newBufferedScrobbler(ds, scr, "test")
 		defer bs.Stop()
 
-		// user2 is enqueued directly so both are buffered before the first drain wakes.
-		_ = buffer.Enqueue("test", "user2", "2", time.Now())
-		_ = bs.Scrobble(context.Background(), "user1", Scrobble{MediaFile: model.MediaFile{ID: "1"}, TimeStamp: time.Now()})
 		synctest.Wait()
 		if got := scr.count.Load(); got != 2 {
 			t.Fatalf("expected both users drained, got %d attempts", got)

From b77fb45088e90c9530a17acfc34d30f1670c0314 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Tue, 1 Sep 2026 20:32:25 -0400
Subject: [PATCH 101/200] ci: exclude test helpers and generated code from the
 coverage report

The coverage profile counted the tests/ package and the *_gen.go files, none of
which are code under test: tests/ is the mock and helper package, and generated
code is never hand-tested. Together they added 2926 uncounted statements at 0%,
pulling the reported number down by almost 6 points (70.13% -> 75.98% on the
current master profile).

octocov's coverage.exclude takes doublestar globs matched against git-root-relative
paths. All 26 mock_*.go files live under tests/, so the single 'tests/**' pattern
covers them.
---
 .octocov.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.octocov.yml b/.octocov.yml
index 52d4ff9bf..467998b51 100644
--- a/.octocov.yml
+++ b/.octocov.yml
@@ -7,6 +7,10 @@ coverage:
   # switches to line counting when it merges several itself.
   paths:
     - coverage.out
+  # Not code under test: tests/ holds the mocks and helpers, *_gen.go is generated.
+  exclude:
+    - 'tests/**'
+    - '**/*_gen.go'
 codeToTestRatio:
   # Needs the pull request's own source, which the comment workflow must not
   # check out: it holds a write token.

From 47bc3c00f3a526ba4879307a6026004c241c83d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 1 Sep 2026 20:48:41 -0400
Subject: [PATCH 102/200] fix(artwork): never retry absent artwork on its own
 (#6054)

An absent artwork state was revisited by an hourly job, by viewing the entity, and
by the startup backfill on any artwork config change. On a large library the last
one queued tens of thousands of external lookups at once and got the provider to
rate-limit us for hours.

Nothing revisits an absent state now. Retrying is explicit: `artwork reprocess` on
the CLI, or the refresh button in the UI. The config fingerprint survives only as an
advisory, warning at startup and naming the command that clears it.

Since absent is terminal, `artwork status` splits it into two disjoint columns, and
`--source failed` targets only the ones that gave up rather than being answered.
Both read through the filter CountBySource and EnqueueBySource already share, so the
reported number is the set the command acts on.

Also fixes the last_failure default left by 20260819204637, which marked every
pre-existing absent row as failed, and removes the code the deleted retry paths
orphaned.
---
 cmd/artwork.go                                | 123 +++++----
 cmd/artwork_test.go                           | 102 ++++---
 cmd/root.go                                   |  30 +--
 consts/consts.go                              |   9 +-
 core/artwork/artwork.go                       |   9 +-
 core/artwork/artwork_test.go                  |  17 +-
 core/artwork/housekeeping.go                  | 125 +++------
 core/artwork/housekeeping_test.go             | 248 ++----------------
 core/artwork/worker.go                        |  25 +-
 core/artwork/worker_test.go                   |  30 ++-
 ...1225726_normalize_artwork_last_failure.sql |   9 +
 model/album.go                                |   1 -
 model/artist.go                               |   1 -
 model/artwork.go                              |  33 ++-
 model/mediafile.go                            |   2 -
 model/playlist.go                             |   1 -
 model/radio.go                                |   1 -
 persistence/album_repository.go               |   6 +-
 persistence/album_repository_test.go          |   4 +-
 persistence/artist_repository.go              |   6 +-
 persistence/artist_repository_test.go         |   4 +-
 persistence/artwork_hydration_test.go         |   2 +-
 persistence/artwork_queue_repository.go       |  35 +--
 persistence/artwork_queue_repository_test.go  |  83 +++---
 persistence/mediafile_repository.go           |   6 +-
 persistence/playlist_repository.go            |   6 +-
 persistence/playlist_repository_test.go       |   4 +-
 persistence/radio_repository.go               |   8 -
 persistence/radio_repository_test.go          |  12 -
 tests/mock_album_repo.go                      |   9 -
 tests/mock_artist_repo.go                     |   9 -
 tests/mock_artwork_queue_repo.go              |  73 +-----
 tests/mock_mediafile_repo.go                  |   8 -
 tests/mock_playlist_repo.go                   |   9 -
 tests/mock_radio_repository.go                |   9 -
 35 files changed, 341 insertions(+), 718 deletions(-)
 create mode 100644 db/migrations/20260901225726_normalize_artwork_last_failure.sql

diff --git a/cmd/artwork.go b/cmd/artwork.go
index 5cd4fc146..9a64cd8c3 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -42,9 +42,10 @@ func init() {
 			"stored trace of the last resolution; also initializes plugin agents, which may open "+
 			"external connections")
 	artworkReprocessCmd.Flags().StringSliceVar(&artworkKinds, "kind", nil,
-		"kinds to reprocess ("+kindPrefixes(artwork.RecheckKinds)+"); repeatable")
+		"kinds to reprocess ("+kindPrefixes(artwork.ReprocessKinds)+"); repeatable")
 	artworkReprocessCmd.Flags().StringSliceVar(&artworkSources, "source", nil,
-		"only items currently resolved from these sources (e.g. folder, external:deezer, absent)")
+		"only items currently resolved from these sources (e.g. folder, external:deezer, absent, "+
+			"or failed for the absent ones that gave up)")
 	artworkReprocessCmd.Flags().BoolVar(&artworkAll, "all", false, "reprocess every kind")
 	artworkReprocessCmd.Flags().BoolVar(&artworkDryRun, "dry-run", false,
 		"report what would be queued and exit without queueing")
@@ -113,7 +114,7 @@ var artworkCancelCmd = &cobra.Command{
 		"Work already picked up is not interrupted, and an item with no artwork yet can be\n" +
 		"queued again by the hourly re-check. The selection is applied again when you confirm,\n" +
 		"so anything queued after the preview is cancelled too. Use it to call off a bulk\n" +
-		"backfill, not to stop the worker.",
+		"reprocess, not to stop the worker.",
 	Args: cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		runCancel(cmd.Context())
@@ -122,7 +123,7 @@ var artworkCancelCmd = &cobra.Command{
 
 var artworkStatusCmd = &cobra.Command{
 	Use:   "status",
-	Short: "Report the artwork queue, where artwork resolves from, and the backfill state",
+	Short: "Report the artwork queue, where artwork resolves from, and the config state",
 	Args:  cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		runStatus(cmd.Context())
@@ -146,9 +147,11 @@ type sourceCount struct {
 	count  int64
 }
 
+// absentCount partitions a kind's absent states: noImage was answered, failed gave up.
 type absentCount struct {
-	kind model.Kind
-	model.ArtworkAbsentStat
+	kind    model.Kind
+	noImage int64
+	failed  int64
 }
 
 type statusReport struct {
@@ -170,16 +173,6 @@ func queueTotal(stats []model.ArtworkQueueStat) int64 {
 	return n
 }
 
-func (r statusReport) backfillQueued() int64 {
-	var n int64
-	for _, s := range r.queue {
-		if s.Priority == model.ArtworkPriorityBackfill {
-			n += s.Count
-		}
-	}
-	return n
-}
-
 func collectStatus(ctx context.Context, ds model.DataStore) (statusReport, error) {
 	q := ds.ArtworkQueue(ctx)
 	var rep statusReport
@@ -188,8 +181,7 @@ func collectStatus(ctx context.Context, ds model.DataStore) (statusReport, error
 		return rep, fmt.Errorf("breaking the artwork queue down by kind: %w", err)
 	}
 
-	cutoff := time.Now().Add(-artwork.StaleAbsentAge)
-	for _, k := range artwork.RecheckKinds {
+	for _, k := range artwork.ReprocessKinds {
 		sources, err := q.SourcesInUse(k)
 		if err != nil {
 			return rep, fmt.Errorf("listing the sources in use by %s artwork: %w", k, err)
@@ -201,12 +193,15 @@ func collectStatus(ctx context.Context, ds model.DataStore) (statusReport, error
 				return rep, fmt.Errorf("counting %s artwork resolved from %s: %w", k, displaySource(s), err)
 			}
 			rep.sources = append(rep.sources, sourceCount{kind: k, source: s, count: n})
+			// An absent state is exactly a row with no source, so it needs no second query.
+			if s == "" {
+				failed, err := q.CountBySource(k, []string{model.ArtworkSourceFailed})
+				if err != nil {
+					return rep, fmt.Errorf("counting failed %s artwork: %w", k, err)
+				}
+				rep.absent = append(rep.absent, absentCount{kind: k, noImage: n - failed, failed: failed})
+			}
 		}
-		stat, err := q.CountAbsent(k, cutoff)
-		if err != nil {
-			return rep, fmt.Errorf("counting absent %s artwork: %w", k, err)
-		}
-		rep.absent = append(rep.absent, absentCount{kind: k, ArtworkAbsentStat: stat})
 	}
 
 	rep.current, rep.inputs = artwork.ConfigFingerprint(), artwork.FingerprintInputs()
@@ -234,19 +229,20 @@ func formatStatus(rep statusReport) string {
 	}
 
 	fmt.Fprintln(w, "\nAbsent (resolved, no image found)")
-	fmt.Fprintln(w, "  KIND\tABSENT\tDUE FOR RECHECK")
+	fmt.Fprintln(w, "  KIND\tNO IMAGE\tFAILED")
 	for _, a := range rep.absent {
-		fmt.Fprintf(w, "  %s\t%d\t%d\n", a.kind, a.Total, a.Stale)
+		fmt.Fprintf(w, "  %s\t%d\t%d\n", a.kind, a.noImage, a.failed)
 	}
-	fmt.Fprintf(w, "  (eligible once the last attempt is older than %gh; re-queued %d per kind per hour, oldest first)\n",
-		artwork.StaleAbsentAge.Hours(), artwork.StaleAbsentRecheckBatch)
+	fmt.Fprintln(w, "  (nothing retries these; 'artwork reprocess --source absent' retries both columns)")
+	fmt.Fprintln(w, "  (failed = gave up rather than being answered, so the ones most likely to resolve;\n"+
+		"   'artwork reprocess --source failed' retries just those)")
 
-	fmt.Fprintln(w, "\nBackfill")
-	fmt.Fprintf(w, "  State:\t%s\n", backfillState(rep))
+	fmt.Fprintln(w, "\nConfig")
+	fmt.Fprintf(w, "  State:\t%s\n", configState(rep))
 	fmt.Fprintf(w, "  Stored fingerprint:\t%s\n", cmp.Or(rep.stored, "(none)"))
 	fmt.Fprintf(w, "  Current fingerprint:\t%s\n", rep.current)
 	if len(rep.inputs) > 0 {
-		fmt.Fprintln(w, "  Fingerprint inputs (changing any of these re-resolves the whole library):")
+		fmt.Fprintln(w, "  Fingerprint inputs (changing any of these makes the stored artwork stale):")
 		for _, in := range rep.inputs {
 			fmt.Fprintf(w, "    %s:\t%s\n", in.Name, in.Value)
 		}
@@ -256,18 +252,10 @@ func formatStatus(rep statusReport) string {
 	return sb.String()
 }
 
-// backfillState leads with the queued backlog: by the time anyone runs this, backfill has usually
-// already stored the new fingerprint, and "up to date" would bury the flood it is still working through.
-func backfillState(rep statusReport) string {
-	pending := "fingerprint changed — every artist, album, playlist and radio will be re-enqueued on the next startup"
-	if n := rep.backfillQueued(); n > 0 {
-		if rep.stored != rep.current {
-			return fmt.Sprintf("backfill running: %d items queued, and %s", n, pending)
-		}
-		return fmt.Sprintf("backfill running: %d items queued (fingerprint up to date)", n)
-	}
+func configState(rep statusReport) string {
 	if rep.stored != rep.current {
-		return pending
+		return "fingerprint changed — stored artwork keeps the old resolution; " +
+			"run 'artwork reprocess --all' to apply it"
 	}
 	return "up to date"
 }
@@ -297,8 +285,8 @@ type artworkPriority struct {
 var knownPriorities = []artworkPriority{
 	{"bump", model.ArtworkPriorityBump},
 	{"scan", model.ArtworkPriorityScan},
-	{"backfill", model.ArtworkPriorityBackfill},
 	{"recheck", model.ArtworkPriorityRecheck},
+	{"backfill", model.ArtworkPriorityBackfill},
 }
 
 // priorityName falls back to the number: a row written by a newer version still has to print.
@@ -351,29 +339,41 @@ func runReprocess(ctx context.Context) {
 func selectedKinds(kinds, sources []string, all bool) ([]model.Kind, error) {
 	// A source filter on its own is already a complete selection, so it does not also need a kind.
 	if all || (len(kinds) == 0 && len(sources) > 0) {
-		return artwork.RecheckKinds, nil
+		return artwork.ReprocessKinds, nil
 	}
 	if len(kinds) == 0 {
 		return nil, fmt.Errorf("no selector given: pass --kind, --source or --all")
 	}
 	return parseAll(kinds, func(s string) (model.Kind, error) {
-		return parseArtworkKind(s, artwork.RecheckKinds)
+		return parseArtworkKind(s, artwork.ReprocessKinds)
 	})
 }
 
-// absentSource is how the stored empty source — resolved, no image — is spelled on the CLI.
-const absentSource = "absent"
+// absentSource is how the stored empty source — resolved, no image — is spelled on the CLI, and
+// failedSource the subset of it that gave up rather than being answered.
+const (
+	absentSource = "absent"
+	failedSource = "failed"
+)
 
 func repositorySources(sources []string) []string {
 	return slice.Map(sources, func(s string) string {
-		if s == absentSource {
+		switch s {
+		case absentSource:
 			return ""
+		case failedSource:
+			return model.ArtworkSourceFailed
 		}
 		return s
 	})
 }
 
-func displaySource(s string) string { return cmp.Or(s, absentSource) }
+func displaySource(s string) string {
+	if s == model.ArtworkSourceFailed {
+		return failedSource
+	}
+	return cmp.Or(s, absentSource)
+}
 
 type confirmFunc func(out io.Writer, total, external int64) bool
 
@@ -447,7 +447,7 @@ func validateSources(q model.ArtworkQueueRepository, sources []string) error {
 		return nil
 	}
 	var inUse []string
-	for _, k := range artwork.RecheckKinds {
+	for _, k := range artwork.ReprocessKinds {
 		found, err := q.SourcesInUse(k)
 		if err != nil {
 			return fmt.Errorf("listing the sources in use by %s artwork: %w", k, err)
@@ -456,14 +456,16 @@ func validateSources(q model.ArtworkQueueRepository, sources []string) error {
 	}
 	var unknown []string
 	for _, s := range sources {
-		if s != "" && !slices.Contains(inUse, s) { // the reserved absent source is valid even when nothing is absent
+		// The reserved absent and failed sources are valid even when nothing currently matches them.
+		if s != "" && s != model.ArtworkSourceFailed && !slices.Contains(inUse, s) {
 			unknown = append(unknown, displaySource(s))
 		}
 	}
 	if len(unknown) == 0 {
 		return nil
 	}
-	valid := slice.Map(inUse, displaySource)
+	// failed is accepted but never stored, so listing only what is in use would hide it.
+	valid := append(slice.Map(inUse, displaySource), failedSource)
 	slices.Sort(valid)
 	return fmt.Errorf("no artwork resolves from %s; sources in use: %s",
 		strings.Join(unknown, ", "), cmp.Or(strings.Join(valid, ", "), "(none)"))
@@ -478,6 +480,18 @@ func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kin
 		return err
 	}
 
+	// Derived from what actually drives the queries, so a filter added to this signature cannot
+	// silently keep stamping the fingerprint for a partial run.
+	markApplied := func() error {
+		if len(sources) > 0 || len(kinds) < len(artwork.ReprocessKinds) {
+			return nil
+		}
+		if err := artwork.MarkConfigApplied(ctx, ds); err != nil {
+			return fmt.Errorf("recording the applied artwork config: %w", err)
+		}
+		return nil
+	}
+
 	matched := make([]int64, len(kinds))
 	var total, external int64
 	for i, k := range kinds {
@@ -496,8 +510,9 @@ func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kin
 		fmt.Fprintln(out, "\nDry run: nothing was queued.")
 		return nil
 	case total == 0:
+		// An empty match set still leaves nothing resolved under the old config.
 		fmt.Fprintln(out, "Nothing was queued.")
-		return nil
+		return markApplied()
 	case !confirm(out, total, external):
 		fmt.Fprintln(out, "Aborted: nothing was queued.")
 		return nil
@@ -519,7 +534,7 @@ func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kin
 	if skipped := total - queued; skipped > 0 {
 		fmt.Fprintf(out, "Already queued, left unchanged: %d (priority and retry backoff untouched).\n", skipped)
 	}
-	return nil
+	return markApplied()
 }
 
 func runCancel(ctx context.Context) {
@@ -546,7 +561,7 @@ func cancelSelection(kinds, priorities []string, all bool) ([]model.Kind, []int,
 	if len(kinds) == 0 && len(priorities) == 0 {
 		return nil, nil, fmt.Errorf("no selector given: pass --kind, --priority or --all")
 	}
-	// RefreshableKinds, not RecheckKinds: media files are queued, so --kind must reach them.
+	// RefreshableKinds, not ReprocessKinds: media files are queued, so --kind must reach them.
 	outKinds, err := parseAll(kinds, func(s string) (model.Kind, error) {
 		return parseArtworkKind(s, artwork.RefreshableKinds)
 	})
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index a7220d2d5..71b450914 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -3,7 +3,6 @@ package cmd
 import (
 	"context"
 	"errors"
-	"fmt"
 	"io"
 	"strings"
 	"time"
@@ -20,20 +19,20 @@ import (
 
 var _ = Describe("parseArtworkKind", func() {
 	It("accepts a supported kind", func() {
-		k, err := parseArtworkKind("ar", artwork.RecheckKinds)
+		k, err := parseArtworkKind("ar", artwork.ReprocessKinds)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(k).To(Equal(model.KindArtistArtwork))
 	})
 
 	It("rejects an unknown kind and lists the valid ones", func() {
-		_, err := parseArtworkKind("zz", artwork.RecheckKinds)
+		_, err := parseArtworkKind("zz", artwork.ReprocessKinds)
 		Expect(err).To(HaveOccurred())
 		Expect(err.Error()).To(ContainSubstring("ar"))
 		Expect(err.Error()).To(ContainSubstring("al"))
 	})
 
 	It("rejects a known kind the command does not accept", func() {
-		_, err := parseArtworkKind("mf", artwork.RecheckKinds)
+		_, err := parseArtworkKind("mf", artwork.ReprocessKinds)
 		Expect(err).To(HaveOccurred())
 	})
 
@@ -442,13 +441,13 @@ var _ = Describe("artwork reprocess selection", func() {
 	It("returns every kind for --all", func() {
 		ks, err := selectedKinds(nil, nil, true)
 		Expect(err).ToNot(HaveOccurred())
-		Expect(ks).To(ConsistOf(artwork.RecheckKinds))
+		Expect(ks).To(ConsistOf(artwork.ReprocessKinds))
 	})
 
 	It("returns every kind for a source filter given without a kind", func() {
 		ks, err := selectedKinds(nil, []string{"folder"}, false)
 		Expect(err).ToNot(HaveOccurred())
-		Expect(ks).To(ConsistOf(artwork.RecheckKinds), "--source alone is already a complete selection")
+		Expect(ks).To(ConsistOf(artwork.ReprocessKinds), "--source alone is already a complete selection")
 	})
 
 	It("returns only the named kinds", func() {
@@ -512,6 +511,11 @@ var _ = Describe("repositorySources", func() {
 		Expect(repositorySources([]string{"absent", "folder"})).To(Equal([]string{"", "folder"}))
 	})
 
+	It("maps the failed name onto the pseudo-source, and back for display", func() {
+		Expect(repositorySources([]string{failedSource})).To(Equal([]string{model.ArtworkSourceFailed}))
+		Expect(displaySource(model.ArtworkSourceFailed)).To(Equal(failedSource))
+	})
+
 	It("keeps an empty selection empty, meaning every source", func() {
 		Expect(repositorySources(nil)).To(BeEmpty())
 	})
@@ -607,6 +611,25 @@ var _ = Describe("reprocessArtwork", func() {
 		Expect(queue.Count()).To(BeZero())
 	})
 
+	DescribeTable("records the applied config only for a run that leaves nothing on the old one",
+		func(selected []model.Kind, sources []string, dryRun, applied bool) {
+			Expect(ds.Property(ctx).Put(consts.ArtConfFingerprintPropertyKey, "stale-fingerprint")).To(Succeed())
+
+			Expect(reprocessArtwork(ctx, ds, selected, sources, imageAgents, dryRun, accept, &out)).To(Succeed())
+
+			want := "stale-fingerprint"
+			if applied {
+				want = artwork.ConfigFingerprint()
+			}
+			Expect(ds.Property(ctx).Get(consts.ArtConfFingerprintPropertyKey)).To(Equal(want))
+		},
+		Entry("every kind, unfiltered", artwork.ReprocessKinds, nil, false, true),
+		Entry("every kind, but nothing matched", artwork.ReprocessKinds, []string{}, false, true),
+		Entry("filtered by source", artwork.ReprocessKinds, []string{"external:deezer"}, false, false),
+		Entry("a subset of kinds", []model.Kind{model.KindAlbumArtwork}, nil, false, false),
+		Entry("a dry run applies nothing", artwork.ReprocessKinds, nil, true, false),
+	)
+
 	It("queues the matching items at recheck priority, leaving their artwork state alone", func() {
 		Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, false, accept, &out)).To(Succeed())
 
@@ -760,6 +783,14 @@ var _ = Describe("reprocessArtwork", func() {
 			imageAgents, true, accept, &out)).ToNot(Succeed(), "a typo must still be rejected")
 	})
 
+	It("names failed among the valid sources when rejecting a typo", func() {
+		err := reprocessArtwork(ctx, ds, kinds, []string{"faild"}, imageAgents, true, accept, &out)
+
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("failed"),
+			"failed is accepted but never stored, so it has to be named explicitly")
+	})
+
 	It("accepts a source another kind uses, letting the empty selection report itself", func() {
 		Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindArtistArtwork}, []string{"folder"},
 			imageAgents, false, decline, &out)).To(Succeed())
@@ -792,14 +823,16 @@ var _ = Describe("collectStatus", func() {
 				ImageType: model.ImageTypePrimary, Source: source, Hash: hash, AttemptedAt: attempted})).To(Succeed())
 		}
 		put(model.KindArtistArtwork, "ar-1", "external:deezer", "h1", time.Now())
-		put(model.KindArtistArtwork, "ar-2", "", "", time.Now().Add(-artwork.StaleAbsentAge-time.Hour))
-		put(model.KindArtistArtwork, "ar-3", "", "", time.Now())
+		put(model.KindArtistArtwork, "ar-2", "", "", time.Now().Add(-24*time.Hour))
+		// ar-3 is absent because it gave up, so the two absent artists split across the columns.
+		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "ar-3",
+			ImageType: model.ImageTypePrimary, LastFailure: "[]", AttemptedAt: time.Now()})).To(Succeed())
 		put(model.KindAlbumArtwork, "al-1", "folder", "h2", time.Now())
 		Expect(queue.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-9",
 			ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBackfill})).To(Succeed())
 	})
 
-	It("reports the queue, the source distribution and the absent ages", func() {
+	It("reports the queue, the source distribution and the absent totals", func() {
 		rep, err := collectStatus(ctx, ds)
 		Expect(err).ToNot(HaveOccurred())
 
@@ -810,8 +843,8 @@ var _ = Describe("collectStatus", func() {
 			sourceCount{kind: model.KindArtistArtwork, source: "", count: 2},
 			sourceCount{kind: model.KindAlbumArtwork, source: "folder", count: 1},
 		))
-		Expect(rep.absent).To(ContainElement(absentCount{kind: model.KindArtistArtwork,
-			ArtworkAbsentStat: model.ArtworkAbsentStat{Total: 2, Stale: 1}}))
+		Expect(rep.absent).To(ContainElement(absentCount{kind: model.KindArtistArtwork, noImage: 1, failed: 1}),
+			"two absent artists, one answered and one that gave up")
 	})
 
 	It("compares the stored fingerprint against the current one", func() {
@@ -845,7 +878,7 @@ var _ = Describe("formatStatus", func() {
 				{kind: model.KindArtistArtwork, source: "", count: 2},
 			},
 			absent: []absentCount{
-				{kind: model.KindArtistArtwork, ArtworkAbsentStat: model.ArtworkAbsentStat{Total: 2, Stale: 1}},
+				{kind: model.KindArtistArtwork, noImage: 1, failed: 1},
 			},
 			inputs:  []artwork.FingerprintInput{{Name: "Agents", Value: "deezer,lastfm"}},
 			stored:  "abc123",
@@ -878,50 +911,37 @@ var _ = Describe("formatStatus", func() {
 		Expect(sources).To(MatchRegexp(`artist\s+absent\s+2`))
 	})
 
-	It("prints the absent total and how many are due for recheck", func() {
-		absent := block(formatStatus(rep), "Absent (resolved, no image found)")
-		Expect(absent).To(MatchRegexp(`artist\s+2\s+1`))
+	It("partitions the absent states into answered and gave up", func() {
+		out := block(formatStatus(rep), "Absent (resolved, no image found)")
+		Expect(out).To(ContainSubstring("NO IMAGE"))
+		Expect(out).To(MatchRegexp(`artist\s+1\s+1`), "1 answered plus 1 failed, summing to 2 absent")
+		Expect(formatStatus(rep)).To(ContainSubstring("artwork reprocess --source failed"))
 	})
 
-	It("states the recheck window and the drip rate the absent counts are bucketed against", func() {
-		Expect(formatStatus(rep)).To(ContainSubstring(fmt.Sprintf("%gh", artwork.StaleAbsentAge.Hours())))
-		Expect(formatStatus(rep)).To(ContainSubstring("100 per kind per hour"))
+	It("says absent states are never retried on their own, and names both commands that do", func() {
+		out := formatStatus(rep)
+		Expect(out).To(ContainSubstring("nothing retries these"))
+		Expect(out).To(ContainSubstring("artwork reprocess --source absent"))
+		Expect(out).To(ContainSubstring("artwork reprocess --source failed"))
 	})
 
-	It("leads with the queued backlog, which is the finding, not with the fingerprint verdict", func() {
-		out := block(formatStatus(rep), "Backfill")
-		Expect(out).To(MatchRegexp(`State:\s+backfill running: 2 items queued`),
-			"an operator scanning for trouble must not read 'up to date' while 2 items churn")
-		Expect(out).To(ContainSubstring("fingerprint up to date"))
-	})
-
-	It("keeps the re-enqueue warning while a backfill is already running", func() {
-		rep.stored = "older"
-
-		out := block(formatStatus(rep), "Backfill")
-		Expect(out).To(MatchRegexp(`State:\s+backfill running: 2 items queued`))
-		Expect(out).To(ContainSubstring("re-enqueued"),
-			"the stored fingerprint is still stale, so a second full re-enqueue is pending on top of this one")
-	})
-
-	It("reports up to date only once the backfill has drained", func() {
-		rep.queue = []model.ArtworkQueueStat{{ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1}}
-
-		Expect(block(formatStatus(rep), "Backfill")).To(MatchRegexp(`State:\s+up to date`))
+	It("reports a matching fingerprint as up to date, whatever else is queued", func() {
+		Expect(block(formatStatus(rep), "Config")).To(MatchRegexp(`State:\s+up to date`))
 	})
 
 	It("echoes the config inputs a fingerprint change would have come from", func() {
-		out := block(formatStatus(rep), "Backfill")
+		out := block(formatStatus(rep), "Config")
 		Expect(out).To(MatchRegexp(`Agents:\s+deezer,lastfm`))
 		Expect(out).To(ContainSubstring("abc123"), "the fingerprint values themselves must be printed")
 	})
 
-	It("reports a changed fingerprint as a pending re-resolve of everything", func() {
+	It("reports a changed fingerprint as stale artwork, and names the command that applies it", func() {
 		rep.stored = "older"
 		rep.queue = nil
 
 		out := formatStatus(rep)
 		Expect(out).To(ContainSubstring("fingerprint changed"))
+		Expect(out).To(ContainSubstring("artwork reprocess --all"))
 		Expect(out).ToNot(ContainSubstring("up to date"))
 	})
 
@@ -1015,7 +1035,7 @@ var _ = Describe("needsImageAgents", func() {
 	It("is false once the chains no longer reach an agent", func() {
 		conf.Server.CoverArtPriority = "cover.*"
 		conf.Server.ArtistArtPriority = "artist.*"
-		Expect(needsImageAgents(artwork.RecheckKinds)).To(BeFalse())
+		Expect(needsImageAgents(artwork.ReprocessKinds)).To(BeFalse())
 	})
 })
 
diff --git a/cmd/root.go b/cmd/root.go
index 94f861f40..c4e360010 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -366,21 +366,18 @@ func startArtworkWorker(ctx context.Context, worker *artwork.Worker) func() erro
 	}
 }
 
-// scheduleArtworkHousekeeping runs the startup fingerprint backfill and registers the
-// recurring stale-absent recheck and prune jobs.
+// scheduleArtworkHousekeeping registers the recurring missing-state and prune jobs, and
+// reports an artwork config change without acting on it.
 func scheduleArtworkHousekeeping(ctx context.Context, worker *artwork.Worker) func() error {
 	return func() error {
 		schedulerInstance := scheduler.GetInstance()
 
-		if _, err := schedulerInstance.Add(consts.ArtworkStaleAbsentRecheckSchedule, func() {
-			if err := worker.EnqueueStaleAbsentAll(ctx); err != nil {
-				log.Error(ctx, "Error enqueueing stale artwork rechecks", err)
-			}
+		if _, err := schedulerInstance.Add(consts.ArtworkEnqueueMissingSchedule, func() {
 			if err := worker.EnqueueMissingAll(ctx); err != nil {
 				log.Error(ctx, "Error enqueueing missing artwork rechecks", err)
 			}
 		}); err != nil {
-			log.Error(ctx, "Error scheduling artwork stale-absent recheck", err)
+			log.Error(ctx, "Error scheduling artwork missing-state recheck", err)
 		}
 
 		if _, err := schedulerInstance.Add(consts.ArtworkPruneSchedule, func() {
@@ -397,23 +394,8 @@ func scheduleArtworkHousekeeping(ctx context.Context, worker *artwork.Worker) fu
 			log.Error(ctx, "Error enqueueing missing artwork rechecks", err)
 		}
 
-		backfilled, err := worker.Backfill(ctx)
-		if err != nil {
-			log.Error(ctx, "Error running artwork backfill", err)
-			return nil
-		}
-		if !backfilled {
-			return nil
-		}
-		log.Info(ctx, "Artwork backfill enqueued, scheduling a follow-up prune")
-		timer := time.NewTimer(consts.ArtworkPostBackfillPruneDelay)
-		defer timer.Stop()
-		select {
-		case <-timer.C:
-			if err := worker.RunPrune(ctx); err != nil {
-				log.Error(ctx, "Error running post-backfill artwork prune", err)
-			}
-		case <-ctx.Done():
+		if err := worker.ReconcileConfig(ctx); err != nil {
+			log.Error(ctx, "Error checking the artwork config fingerprint", err)
 		}
 		return nil
 	}
diff --git a/consts/consts.go b/consts/consts.go
index 2934cd968..0f950ef10 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -24,8 +24,8 @@ const (
 	LastDBAnalyzeAttemptAtKey     = "LastDBAnalyzeAttemptAt"
 	DBAnalyzePendingKey           = "DBAnalyzePending"
 	DBAnalyzeFailureCountKey      = "DBAnalyzeFailureCount"
-	// ArtConfFingerprintPropertyKey is the model.PropertyRepository key Backfill compares against
-	// to detect artwork-affecting config changes across restarts.
+	// ArtConfFingerprintPropertyKey is the model.PropertyRepository key the artwork config check
+	// compares against to detect artwork-affecting config changes across restarts.
 	ArtConfFingerprintPropertyKey = "ArtConfFingerprint"
 
 	UIAuthorizationHeader  = "X-ND-Authorization"
@@ -39,9 +39,8 @@ const (
 	DBAnalyzeCheckSchedule = "@every 30m"
 	DBAnalyzeMaxAge        = 24 * time.Hour
 
-	ArtworkStaleAbsentRecheckSchedule = "@every 1h"
-	ArtworkPruneSchedule              = "@daily"
-	ArtworkPostBackfillPruneDelay     = 10 * time.Minute
+	ArtworkEnqueueMissingSchedule = "@every 1h"
+	ArtworkPruneSchedule          = "@daily"
 
 	// DefaultEncryptionKey This is the encryption key used if none is specified in the `PasswordEncryptionKey` option
 	// Never ever change this! Or it will break all Navidrome installations that don't set the config option
diff --git a/core/artwork/artwork.go b/core/artwork/artwork.go
index e8458a0f9..663d06d25 100644
--- a/core/artwork/artwork.go
+++ b/core/artwork/artwork.go
@@ -118,10 +118,6 @@ func (s *service) Get(ctx context.Context, artID model.ArtworkID, size int, squa
 	}
 }
 
-// requestRecheckAge throttles view-triggered rechecks so reopening a genuinely-absent page can't
-// hammer external services; below StaleAbsentAge to catch younger absences.
-const requestRecheckAge = time.Hour
-
 func (s *service) serveEntity(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
 	ia, err := s.ds.Artwork(ctx).GetItemArtwork(artID.Kind, artID.ID, model.ImageTypePrimary)
 	switch {
@@ -130,10 +126,7 @@ func (s *service) serveEntity(ctx context.Context, artID model.ArtworkID, size i
 	case err != nil:
 		return nil, err
 	case ia.Hash == "":
-		// Inserts an immediately-eligible recheck for a settled absent row.
-		if time.Since(ia.AttemptedAt) > requestRecheckAge {
-			s.enqueue(ctx, artID, model.ArtworkPriorityBump)
-		}
+		// Settled absent: only an explicit reprocess or refresh retries it.
 		return nil, ErrUnavailable
 	default:
 		return s.serveHash(ctx, artID, ia, size, square)
diff --git a/core/artwork/artwork_test.go b/core/artwork/artwork_test.go
index 7de5475d6..907b300de 100644
--- a/core/artwork/artwork_test.go
+++ b/core/artwork/artwork_test.go
@@ -204,28 +204,15 @@ var _ = Describe("Artwork", func() {
 			Expect(err).To(MatchError(ErrUnavailable))
 		})
 
-		It("does not re-enqueue a recently-attempted absent state", func() {
+		It("never re-enqueues an absent state on view, however old", func() {
 			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
-				ItemKind: "al", ItemID: "al4", AttemptedAt: time.Now(),
+				ItemKind: "al", ItemID: "al4", AttemptedAt: time.Now().Add(-365 * 24 * time.Hour),
 			})).To(Succeed())
 
 			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al4"), 0, false)
 			Expect(err).To(MatchError(ErrUnavailable))
 			Expect(queueRepo.Data).To(BeEmpty())
 		})
-
-		It("promotes a stale absent state at Bump priority on view", func() {
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
-				ItemKind: "al", ItemID: "al4b", AttemptedAt: time.Now().Add(-2 * requestRecheckAge),
-			})).To(Succeed())
-
-			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al4b"), 0, false)
-			Expect(err).To(MatchError(ErrUnavailable))
-			Expect(queueRepo.Data[primaryKey("al", "al4b")].Priority).To(Equal(model.ArtworkPriorityBump))
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al4b", model.ImageTypePrimary)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(ia.Hash).To(BeEmpty())
-		})
 	})
 
 	Describe("provisional read-through", func() {
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
index a3330d7cf..3ca452bdc 100644
--- a/core/artwork/housekeeping.go
+++ b/core/artwork/housekeeping.go
@@ -6,26 +6,18 @@ import (
 	"slices"
 	"strconv"
 	"strings"
-	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/zeebo/xxh3"
 )
 
-// StaleAbsentAge is how long an absent state is trusted before a recheck retries it.
-const StaleAbsentAge = 30 * 24 * time.Hour
-
-// StaleAbsentRecheckBatch caps how many absent states each hourly tick re-queues per kind,
-// oldest first, so external agents see a flat drip instead of a daily burst.
-const StaleAbsentRecheckBatch = 100
-
-// RecheckKinds omits media files: they resolve embedded-only, at scan or on view.
-var RecheckKinds = []model.Kind{
+// ReprocessKinds omits media files: they resolve embedded-only, at scan or on view. Artists lead
+// so bulk enqueues give the most external-dependent kind a queue headstart.
+var ReprocessKinds = []model.Kind{
 	model.KindArtistArtwork, model.KindAlbumArtwork, model.KindPlaylistArtwork, model.KindRadioArtwork,
 }
 
@@ -34,14 +26,16 @@ var RecheckKinds = []model.Kind{
 func KeepsState(kind model.Kind) bool { return kind != model.KindDiscArtwork }
 
 // RefreshableKinds is every kind Refresh can clear and re-queue, so it holds exactly the kinds
-// KeepsState admits. Media files are absent from RecheckKinds but belong here: the worker
-// resolves them, it just never revisits them on its own.
-var RefreshableKinds = append(slices.Clone(RecheckKinds), model.KindMediaFileArtwork)
+// KeepsState admits. Media files are absent from ReprocessKinds but belong here: the worker
+// resolves them, it just never enumerates them in bulk.
+var RefreshableKinds = append(slices.Clone(ReprocessKinds), model.KindMediaFileArtwork)
 
-// hasRecheckPath reports whether a periodic job will revisit this kind, making an absent settle recoverable.
-func hasRecheckPath(prefix string) bool {
+// settlesAbsentOnGiveUp reports whether an exhausted retry budget records an absent state. Media
+// files are excluded because retrying one costs nothing: they resolve embedded-only, from a local
+// read, and only a view ever enqueues them.
+func settlesAbsentOnGiveUp(prefix string) bool {
 	kind, ok := model.ParseKind(prefix)
-	return ok && slices.Contains(RecheckKinds, kind)
+	return ok && KeepsState(kind) && kind != model.KindMediaFileArtwork
 }
 
 // artworkEpoch invalidates all resolution state when bumped; bump it whenever resolution semantics change.
@@ -72,93 +66,36 @@ func ConfigFingerprint() string {
 	return fmt.Sprintf("%016x", xxh3.Hash([]byte(raw)))
 }
 
-// backfillSummary is what a backfill enqueued. MaxExternalLookups is an upper estimate for one
-// attempt per item, not a bound: a local hit ends the walk, and a retry asks the agents again.
-type backfillSummary struct {
-	Ran                bool
-	PerKind            map[string]int64
-	Items              int64
-	MaxExternalLookups int64
-}
-
-// backfill enqueues artwork resolution for every entity when the config fingerprint changed.
-func backfill(ctx context.Context, ds model.DataStore, agentCount func() ImageAgentCount) (backfillSummary, error) {
-	start := time.Now()
-	ctx = auth.WithAdminUser(ctx, ds)
+// ReconcileConfigFingerprint warns when the artwork config changed since the library was last
+// resolved under it. Nothing re-resolves on its own; applying a change is an explicit reprocess.
+func ReconcileConfigFingerprint(ctx context.Context, ds model.DataStore) error {
 	current := ConfigFingerprint()
-	props := ds.Property(ctx)
-	stored, err := props.DefaultGet(consts.ArtConfFingerprintPropertyKey, "")
+	stored, err := ds.Property(ctx).DefaultGet(consts.ArtConfFingerprintPropertyKey, "")
 	if err != nil {
-		return backfillSummary{}, err
+		return err
 	}
-	if stored == current {
-		return backfillSummary{}, nil
-	}
-
-	// Artists first: few entities, most external-dependent, so they get a queue headstart.
-	kinds := []struct {
-		kind  model.Kind
-		fetch func() ([]string, error)
-	}{
-		{model.KindArtistArtwork, func() ([]string, error) { return ds.Artist(ctx).GetAllIDs() }},
-		{model.KindAlbumArtwork, func() ([]string, error) { return ds.Album(ctx).GetAllIDs() }},
-		{model.KindPlaylistArtwork, func() ([]string, error) { return ds.Playlist(ctx).GetAllIDs() }},
-		{model.KindRadioArtwork, func() ([]string, error) { return ds.Radio(ctx).GetAllIDs() }},
-	}
-	// Counted here, not by the caller: building the agent list constructs every enabled agent, and
-	// an unchanged fingerprint returns above without ever needing the number.
-	agents := agentCount()
-	summary := backfillSummary{Ran: true, PerKind: map[string]int64{}}
-	for _, k := range kinds {
-		ids, err := k.fetch()
-		if err != nil {
-			return backfillSummary{}, err
-		}
-		if err := enqueueBackfillKind(ctx, ds, k.kind, ids); err != nil {
-			return backfillSummary{}, err
-		}
-		n := int64(len(ids))
-		summary.PerKind[k.kind.Prefix()] = n
-		summary.Items += n
-		summary.MaxExternalLookups += n * ExternalLookupsPerItem(k.kind, agents)
-	}
-
-	if err := props.Put(consts.ArtConfFingerprintPropertyKey, current); err != nil {
-		return backfillSummary{}, err
-	}
-	log.Info(ctx, "Artwork: Config fingerprint changed, backfill enqueued", "items", summary.Items,
-		"byKind", summary.PerKind, "maxExternalLookups", summary.MaxExternalLookups,
-		"elapsed", time.Since(start))
-	return summary, nil
-}
-
-func enqueueBackfillKind(ctx context.Context, ds model.DataStore, kind model.Kind, ids []string) error {
-	if len(ids) == 0 {
-		return nil
-	}
-	items := slice.Map(ids, func(id string) model.ArtworkQueueItem {
-		return model.ArtworkQueueItem{
-			ItemKind: kind.Prefix(), ItemID: id, ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBackfill,
-		}
-	})
-	return ds.ArtworkQueue(ctx).Enqueue(items...)
-}
-
-func enqueueStaleAbsentAll(ctx context.Context, ds model.DataStore) error {
-	cutoff := time.Now().Add(-StaleAbsentAge)
-	queue := ds.ArtworkQueue(ctx)
-	for _, kind := range RecheckKinds {
-		if _, err := queue.EnqueueStaleAbsent(kind, cutoff, StaleAbsentRecheckBatch); err != nil {
-			return err
-		}
+	switch stored {
+	case current:
+	case "":
+		// An unset fingerprint counts as current; the alternative warns every upgrading install once.
+		return MarkConfigApplied(ctx, ds)
+	default:
+		log.Warn(ctx, "Artwork: Config changed since the last full reprocess. Stored artwork keeps "+
+			"the old resolution; run 'navidrome artwork reprocess --all' to apply the change",
+			"stored", stored, "current", current, "inputs", FingerprintInputs())
 	}
 	return nil
 }
 
+// MarkConfigApplied records the current fingerprint as the one the library is resolved under.
+func MarkConfigApplied(ctx context.Context, ds model.DataStore) error {
+	return ds.Property(ctx).Put(consts.ArtConfFingerprintPropertyKey, ConfigFingerprint())
+}
+
 // enqueueMissingAll is the safety net for entities a scan never enqueued (added between scans, or scanner off).
 func enqueueMissingAll(ctx context.Context, ds model.DataStore) error {
 	queue := ds.ArtworkQueue(ctx)
-	for _, kind := range RecheckKinds {
+	for _, kind := range ReprocessKinds {
 		if _, err := queue.EnqueueAllMissing(kind, model.ArtworkPriorityRecheck); err != nil {
 			return err
 		}
diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.go
index c9809203a..2027cba9a 100644
--- a/core/artwork/housekeeping_test.go
+++ b/core/artwork/housekeeping_test.go
@@ -2,59 +2,17 @@ package artwork
 
 import (
 	"context"
-	"fmt"
 	"slices"
-	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
-// visibilityPlaylistDS models playlist_repository's userFilter: a private playlist is only
-// visible when the ctx carries an admin, so headless work must wrap ctx with one first.
-type visibilityPlaylistDS struct {
-	*tests.MockDataStore
-	private model.Playlist
-	tracks  model.PlaylistTrackRepository
-}
-
-func (v *visibilityPlaylistDS) Playlist(ctx context.Context) model.PlaylistRepository {
-	repo := tests.CreateMockPlaylistRepo()
-	repo.TracksRepo = v.tracks
-	if u, ok := request.UserFrom(ctx); ok && u.IsAdmin {
-		repo.SetData(model.Playlists{v.private})
-	}
-	return repo
-}
-
-func adminUserRepo() *tests.MockedUserRepo {
-	repo := tests.CreateMockUserRepo()
-	Expect(repo.Put(&model.User{ID: "admin", UserName: "admin", IsAdmin: true})).To(Succeed())
-	return repo
-}
-
-func noAgents() ImageAgentCount { return ImageAgentCount{} }
-
-// orderTrackingQueueRepo records the item kind of each Enqueue call, so tests can
-// assert phase ordering (artists-first) that same-priority timestamps can't guarantee.
-type orderTrackingQueueRepo struct {
-	*tests.MockArtworkQueueRepo
-	callKinds []string
-}
-
-func (o *orderTrackingQueueRepo) Enqueue(items ...model.ArtworkQueueItem) error {
-	if len(items) > 0 {
-		o.callKinds = append(o.callKinds, items[0].ItemKind)
-	}
-	return o.MockArtworkQueueRepo.Enqueue(items...)
-}
-
 var _ = Describe("RefreshableKinds", func() {
 	// The two are meant to describe the same fact. Nothing but this test stops them from drifting,
 	// and a drift would have `artwork explain` report state for a kind that keeps none.
@@ -72,7 +30,7 @@ var _ = Describe("Housekeeping", func() {
 	var (
 		ctx       context.Context
 		ds        *tests.MockDataStore
-		queueRepo *orderTrackingQueueRepo
+		queueRepo *tests.MockArtworkQueueRepo
 		propRepo  *tests.MockedPropertyRepo
 	)
 
@@ -84,52 +42,24 @@ var _ = Describe("Housekeeping", func() {
 		conf.Server.Agents = "spotify"
 		conf.Server.EnableExternalServices = true
 
-		queueRepo = &orderTrackingQueueRepo{MockArtworkQueueRepo: tests.CreateMockArtworkQueueRepo()}
+		queueRepo = tests.CreateMockArtworkQueueRepo()
 		propRepo = &tests.MockedPropertyRepo{}
 		ds = &tests.MockDataStore{MockedArtworkQueue: queueRepo, MockedProperty: propRepo}
 	})
 
-	seedEntities := func() {
-		artistRepo := tests.CreateMockArtistRepo()
-		artistRepo.SetData(model.Artists{{ID: "ar1"}, {ID: "ar2"}})
-		ds.MockedArtist = artistRepo
-
-		albumRepo := tests.CreateMockAlbumRepo()
-		albumRepo.SetData(model.Albums{{ID: "al1"}})
-		ds.MockedAlbum = albumRepo
-
-		playlistRepo := tests.CreateMockPlaylistRepo()
-		playlistRepo.SetData(model.Playlists{{ID: "pl1"}})
-		ds.MockedPlaylist = playlistRepo
-
-		radioRepo := tests.CreateMockedRadioRepo()
-		radioRepo.All = model.Radios{{ID: "ra1"}}
-		ds.MockedRadio = radioRepo
-	}
-
 	Describe("Fingerprint", func() {
-		It("changes when a fingerprint-affecting config value changes", func() {
-			f1 := ConfigFingerprint()
-			conf.Server.CoverArtPriority = "folder, embedded"
-			f2 := ConfigFingerprint()
-			Expect(f1).NotTo(Equal(f2))
-		})
+		DescribeTable("changes when a fingerprint-affecting config value changes",
+			func(change func()) {
+				before := ConfigFingerprint()
+				change()
+				Expect(ConfigFingerprint()).NotTo(Equal(before))
+			},
+			Entry("CoverArtPriority", func() { conf.Server.CoverArtPriority = "folder, embedded" }),
+			Entry("ArtistImageFolder", func() { conf.Server.ArtistImageFolder = "/after" }),
+			Entry("EnableM3UExternalAlbumArt", func() { conf.Server.EnableM3UExternalAlbumArt = true }),
+		)
 
-		It("changes when ArtistImageFolder changes", func() {
-			conf.Server.ArtistImageFolder = "/before"
-			f1 := ConfigFingerprint()
-			conf.Server.ArtistImageFolder = "/after"
-			Expect(ConfigFingerprint()).NotTo(Equal(f1))
-		})
-
-		It("changes when EnableM3UExternalAlbumArt is toggled", func() {
-			conf.Server.EnableM3UExternalAlbumArt = false
-			f1 := ConfigFingerprint()
-			conf.Server.EnableM3UExternalAlbumArt = true
-			Expect(ConfigFingerprint()).NotTo(Equal(f1))
-		})
-
-		// Pinned: a changed formula re-resolves every library on upgrade, flooding external providers.
+		// Pinned: a changed formula tells every existing install its artwork config went stale.
 		It("hashes a given config to a stable value", func() {
 			conf.Server.CoverArtPriority = "cover.*, embedded"
 			conf.Server.ArtistArtPriority = "artist.*, external"
@@ -157,145 +87,23 @@ var _ = Describe("Housekeeping", func() {
 			f1 := ConfigFingerprint()
 			consts.Version = original + "-next"
 			Expect(ConfigFingerprint()).To(Equal(f1),
-				"the version must not invalidate artwork state: it would re-resolve every entity on every build")
+				"the version must not invalidate artwork state: every build would report a stale config")
 		})
 	})
 
-	Describe("Backfill", func() {
-		It("enqueues nothing and returns false when the stored fingerprint matches", func() {
-			seedEntities()
-			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, ConfigFingerprint())).To(Succeed())
+	Describe("ReconcileConfigFingerprint", func() {
+		It("records the current fingerprint when none was ever stored", func() {
+			Expect(ReconcileConfigFingerprint(ctx, ds)).To(Succeed())
 
-			counted := false
-			s, err := backfill(ctx, ds, func() ImageAgentCount {
-				counted = true
-				return ImageAgentCount{Artist: 3, Album: 2}
-			})
-			Expect(err).ToNot(HaveOccurred())
-			Expect(s).To(Equal(backfillSummary{}))
-			Expect(counted).To(BeFalse(), "building the agent list constructs every agent; an unchanged fingerprint must not pay for it")
-
-			count, err := queueRepo.Count()
-			Expect(err).ToNot(HaveOccurred())
-			Expect(count).To(BeZero())
+			Expect(propRepo.Get(consts.ArtConfFingerprintPropertyKey)).To(Equal(ConfigFingerprint()))
 		})
 
-		It("runs the backfill when no fingerprint was ever stored", func() {
-			seedEntities()
-
-			s, err := backfill(ctx, ds, noAgents)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(s.Ran).To(BeTrue())
-
-			count, err := queueRepo.Count()
-			Expect(err).ToNot(HaveOccurred())
-			Expect(count).To(Equal(int64(5))) // 2 artists + 1 album + 1 playlist + 1 radio
-
-			stored, err := propRepo.Get(consts.ArtConfFingerprintPropertyKey)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(stored).To(Equal(ConfigFingerprint()))
-		})
-
-		It("enqueues a private playlist by resolving it under an admin context", func() {
-			ds.MockedUser = adminUserRepo()
-			vds := &visibilityPlaylistDS{
-				MockDataStore: ds,
-				private:       model.Playlist{ID: "plPrivate", OwnerID: "admin"},
-				tracks:        &tests.MockPlaylistTrackRepo{},
-			}
-
-			s, err := backfill(ctx, vds, noAgents)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(s.Ran).To(BeTrue())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "pl", "plPrivate")).ToNot(BeNil())
-		})
-
-		It("enqueues artists before albums/playlists/radios, all at Backfill priority", func() {
-			seedEntities()
+		It("leaves a stale fingerprint stored, so the warning survives a restart", func() {
 			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, "stale-fingerprint")).To(Succeed())
 
-			s, err := backfill(ctx, ds, noAgents)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(s.Ran).To(BeTrue())
+			Expect(ReconcileConfigFingerprint(ctx, ds)).To(Succeed())
 
-			Expect(queueRepo.callKinds).ToNot(BeEmpty())
-			firstOther := slices.IndexFunc(queueRepo.callKinds, func(k string) bool { return k != "ar" })
-			Expect(firstOther).ToNot(Equal(0), "artists must be the first Enqueue call")
-			if firstOther >= 0 {
-				Expect(queueRepo.callKinds[firstOther:]).ToNot(ContainElement("ar"),
-					"no artist Enqueue may follow another kind")
-			}
-
-			for _, it := range queueRepo.Data {
-				Expect(it.Priority).To(Equal(model.ArtworkPriorityBackfill))
-				Expect(it.ItemKind).To(BeElementOf("ar", "al", "pl", "ra"))
-			}
-		})
-
-		It("reports what it enqueued, per kind and as an external-lookup ceiling", func() {
-			conf.Server.ArtistArtPriority = "artist.*, external"
-			conf.Server.CoverArtPriority = "cover.*, external"
-			conf.Server.EnableM3UExternalAlbumArt = false
-			seedEntities()
-
-			s, err := backfill(ctx, ds, func() ImageAgentCount { return ImageAgentCount{Artist: 3, Album: 2} })
-			Expect(err).ToNot(HaveOccurred())
-			Expect(s.Ran).To(BeTrue())
-
-			Expect(s.PerKind).To(Equal(map[string]int64{"ar": 2, "al": 1, "pl": 1, "ra": 1}))
-			Expect(s.Items).To(Equal(int64(5)))
-			// 2 artists x 3 agents, 1 album x 2, 1 playlist grid x 2, and radios never fetch.
-			Expect(s.MaxExternalLookups).To(Equal(int64(6 + 2 + PlaylistGridSamples*2)))
-		})
-	})
-
-	Describe("EnqueueStaleAbsentAll", func() {
-		var artRepo *tests.MockArtworkRepo
-
-		BeforeEach(func() {
-			artRepo = tests.CreateMockArtworkRepo()
-			ds.MockedArtwork = artRepo
-			queueRepo.ItemArtworkSource = artRepo
-		})
-
-		It("enqueues only absent entries older than the recheck window, across all kinds", func() {
-			old := time.Now().Add(-StaleAbsentAge - time.Hour)
-			recent := time.Now().Add(-StaleAbsentAge + time.Hour)
-
-			artRepo.ItemData["ar-stale"] = model.ItemArtwork{ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
-			artRepo.ItemData["al-stale"] = model.ItemArtwork{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
-			artRepo.ItemData["pl-stale"] = model.ItemArtwork{ItemKind: "pl", ItemID: "pl1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
-			artRepo.ItemData["ra-stale"] = model.ItemArtwork{ItemKind: "ra", ItemID: "ra1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old}
-			artRepo.ItemData["ar-recent"] = model.ItemArtwork{ItemKind: "ar", ItemID: "ar2", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: recent}
-			artRepo.ItemData["al-resolved"] = model.ItemArtwork{ItemKind: "al", ItemID: "al2", ImageType: model.ImageTypePrimary, Hash: "somehash", AttemptedAt: old}
-
-			err := enqueueStaleAbsentAll(ctx, ds)
-			Expect(err).ToNot(HaveOccurred())
-
-			Expect(queueRepo.Data).To(HaveLen(4))
-			for _, it := range queueRepo.Data {
-				Expect(it.Priority).To(Equal(model.ArtworkPriorityRecheck))
-			}
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar1")).ToNot(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al1")).ToNot(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "pl", "pl1")).ToNot(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ra", "ra1")).ToNot(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar2")).To(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al2")).To(BeNil())
-		})
-
-		It("caps each tick at the recheck batch, oldest attempts first", func() {
-			for i := range StaleAbsentRecheckBatch + 1 {
-				id := fmt.Sprintf("ar%d", i)
-				artRepo.ItemData[id] = model.ItemArtwork{ItemKind: "ar", ItemID: id, ImageType: model.ImageTypePrimary,
-					Hash: "", AttemptedAt: time.Now().Add(-StaleAbsentAge - time.Duration(i+1)*time.Minute)}
-			}
-
-			Expect(enqueueStaleAbsentAll(ctx, ds)).To(Succeed())
-
-			Expect(queueRepo.Data).To(HaveLen(StaleAbsentRecheckBatch))
-			// ar0 has the newest attempted_at of the cohort, so it is the one left out.
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar0")).To(BeNil())
+			Expect(propRepo.Get(consts.ArtConfFingerprintPropertyKey)).To(Equal("stale-fingerprint"))
 		})
 	})
 
@@ -315,8 +123,8 @@ var _ = Describe("Housekeeping", func() {
 		})
 
 		It("enqueues only entities that have no item_artwork row, across all kinds", func() {
-			artRepo.ItemData["al-resolved"] = model.ItemArtwork{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "somehash", AttemptedAt: time.Now()}
-			artRepo.ItemData["ar-absent"] = model.ItemArtwork{ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()}
+			artRepo.ItemData["al-resolved"] = model.ItemArtwork{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "somehash"}
+			artRepo.ItemData["ar-absent"] = model.ItemArtwork{ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: ""}
 
 			err := enqueueMissingAll(ctx, ds)
 			Expect(err).ToNot(HaveOccurred())
@@ -324,11 +132,11 @@ var _ = Describe("Housekeeping", func() {
 			for _, it := range queueRepo.Data {
 				Expect(it.Priority).To(Equal(model.ArtworkPriorityRecheck))
 			}
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al2")).ToNot(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "pl", "pl1")).ToNot(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ra", "ra1")).ToNot(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "al", "al1")).To(BeNil())
-			Expect(findQueued(queueRepo.MockArtworkQueueRepo, "ar", "ar1")).To(BeNil())
+			Expect(findQueued(queueRepo, "al", "al2")).ToNot(BeNil())
+			Expect(findQueued(queueRepo, "pl", "pl1")).ToNot(BeNil())
+			Expect(findQueued(queueRepo, "ra", "ra1")).ToNot(BeNil())
+			Expect(findQueued(queueRepo, "al", "al1")).To(BeNil())
+			Expect(findQueued(queueRepo, "ar", "ar1")).To(BeNil())
 		})
 	})
 })
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index bea478aa5..bb09be55e 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -23,8 +23,8 @@ import (
 const (
 	workerPollInterval = 5 * time.Second
 	backoffBase        = 5 * time.Second
-	// giveUpAfter bounds the retry budget from enqueue; past it the item falls to the
-	// periodic stale-absent recheck.
+	// giveUpAfter bounds the retry budget from enqueue; past it the item settles and only an
+	// explicit reprocess retries it.
 	giveUpAfter = 12 * time.Hour
 )
 
@@ -40,7 +40,6 @@ type drainPool struct {
 // independently, and pruneMu serializes prune against the store-write window.
 type Worker struct {
 	proc    *processor
-	agents  *agents.Agents
 	cache   cache.FileCache
 	ffmpeg  ffmpeg.FFmpeg
 	broker  events.Broker
@@ -55,7 +54,6 @@ type Worker struct {
 func NewWorker(ds model.DataStore, store *ImageStore, ag *agents.Agents, ffmpeg ffmpeg.FFmpeg, broker events.Broker, imgCache cache.FileCache) *Worker {
 	w := &Worker{
 		proc:   &processor{ds: ds, store: store},
-		agents: ag,
 		cache:  imgCache,
 		ffmpeg: ffmpeg,
 		broker: broker,
@@ -133,17 +131,9 @@ func (w *Worker) RunPrune(ctx context.Context) error {
 	return prune(ctx, w.proc.ds, w.proc.store)
 }
 
-// Backfill enqueues every entity for re-resolution when the artwork config fingerprint changed,
-// artists first. It reports whether the backfill ran.
-func (w *Worker) Backfill(ctx context.Context) (bool, error) {
-	s, err := backfill(ctx, w.proc.ds, func() ImageAgentCount { return NewImageAgentCount(w.agents) })
-	return s.Ran, err
-}
-
-// EnqueueStaleAbsentAll requeues known-absent entries older than StaleAbsentAge, at most
-// StaleAbsentRecheckBatch per kind, oldest first.
-func (w *Worker) EnqueueStaleAbsentAll(ctx context.Context) error {
-	return enqueueStaleAbsentAll(ctx, w.proc.ds)
+// ReconcileConfig records the artwork config fingerprint, or warns when it changed.
+func (w *Worker) ReconcileConfig(ctx context.Context) error {
+	return ReconcileConfigFingerprint(ctx, w.proc.ds)
 }
 
 // EnqueueMissingAll requeues entities with no artwork state row: the safety net for anything
@@ -265,10 +255,9 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 				"budgetLeft", time.Until(item.EnqueuedAt.Add(giveUpAfter)))
 			break
 		}
-		// Absent is only recoverable where a periodic recheck revisits it, so other kinds keep
-		// no row; art already being served is kept, as exhaustion means unreachable, not removed.
+		// Art already being served is kept: exhaustion means unreachable, not removed.
 		settled := "kept previous state"
-		if out == outcomeFailed && hasRecheckPath(item.ItemKind) && !w.hasResolvedArtwork(ctx, item) {
+		if out == outcomeFailed && settlesAbsentOnGiveUp(item.ItemKind) && !w.hasResolvedArtwork(ctx, item) {
 			writeAbsent(ctx, w.proc.ds.Artwork(ctx), item)
 			settled = "recorded absent"
 		}
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index b0ef665fc..ebb8de251 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -15,6 +15,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/agents"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/tests"
 	"github.com/navidrome/navidrome/utils/cache"
@@ -115,6 +116,29 @@ func findQueued(q *tests.MockArtworkQueueRepo, kind, id string) *model.ArtworkQu
 	return nil
 }
 
+// visibilityPlaylistDS models playlist_repository's userFilter: a private playlist is only
+// visible when the ctx carries an admin, so headless work must wrap ctx with one first.
+type visibilityPlaylistDS struct {
+	*tests.MockDataStore
+	private model.Playlist
+	tracks  model.PlaylistTrackRepository
+}
+
+func (v *visibilityPlaylistDS) Playlist(ctx context.Context) model.PlaylistRepository {
+	repo := tests.CreateMockPlaylistRepo()
+	repo.TracksRepo = v.tracks
+	if u, ok := request.UserFrom(ctx); ok && u.IsAdmin {
+		repo.SetData(model.Playlists{v.private})
+	}
+	return repo
+}
+
+func adminUserRepo() *tests.MockedUserRepo {
+	repo := tests.CreateMockUserRepo()
+	Expect(repo.Put(&model.User{ID: "admin", UserName: "admin", IsAdmin: true})).To(Succeed())
+	return repo
+}
+
 var _ = Describe("Worker", func() {
 	var (
 		ctx        context.Context
@@ -441,9 +465,9 @@ var _ = Describe("Worker", func() {
 			Expect(ia.Hash).To(Equal("cafebabe"), "recording the failure must not disturb the served art")
 		})
 
-		// Media files are excluded from RecheckKinds, so an absent row here would never be
-		// revisited: a transient read error would look permanent.
-		It("does not settle absent on exhaustion for a kind with no recheck path", func() {
+		// Only a view enqueues a media file, and an absent row is exactly what stops a view from
+		// doing so: a transient read error would look permanent.
+		It("does not settle absent on exhaustion for a media file", func() {
 			conf.Server.EnableMediaFileCoverArt = true
 			ds.MockedMediaFile = tests.CreateMockMediaFileRepo()
 			ds.MockedMediaFile.(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
diff --git a/db/migrations/20260901225726_normalize_artwork_last_failure.sql b/db/migrations/20260901225726_normalize_artwork_last_failure.sql
new file mode 100644
index 000000000..6de12e757
--- /dev/null
+++ b/db/migrations/20260901225726_normalize_artwork_last_failure.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+-- 20260819204637 added last_failure with DEFAULT '[]', so every row already in the table got a
+-- non-empty value. That is how a give-up is now told apart from a definitive "no image", which
+-- would report every pre-existing absent row as failed.
+UPDATE item_artwork SET last_failure = '' WHERE last_failure = '[]';
+
+-- +goose Down
+-- Irreversible: a genuine give-up and a backfilled default are indistinguishable once normalized.
+SELECT 1;
diff --git a/model/album.go b/model/album.go
index 5a436fec0..ee24bfa96 100644
--- a/model/album.go
+++ b/model/album.go
@@ -143,7 +143,6 @@ type AlbumRepository interface {
 	UpdateExternalInfo(*Album) error
 	Get(id string) (*Album, error)
 	GetAll(...QueryOptions) (Albums, error)
-	GetAllIDs(...QueryOptions) ([]string, error)
 	// GetSoleAlbumArtistIDsInSubtrees returns the sole album artists of the albums with folders in
 	// any of the given library-relative subtrees.
 	GetSoleAlbumArtistIDsInSubtrees(lib Library, paths ...string) ([]string, error)
diff --git a/model/artist.go b/model/artist.go
index f3704b669..f88b3a974 100644
--- a/model/artist.go
+++ b/model/artist.go
@@ -90,7 +90,6 @@ type ArtistRepository interface {
 	UpdateExternalInfo(a *Artist) error
 	Get(id string) (*Artist, error)
 	GetAll(options ...QueryOptions) (Artists, error)
-	GetAllIDs(options ...QueryOptions) ([]string, error)
 	GetCursor(options ...QueryOptions) (ArtistCursor, error)
 	GetIndex(includeMissing bool, libraryIds []int, roles ...Role) (ArtistIndexes, error)
 
diff --git a/model/artwork.go b/model/artwork.go
index 3c0df209b..8856a35fa 100644
--- a/model/artwork.go
+++ b/model/artwork.go
@@ -18,6 +18,10 @@ type Artwork struct {
 
 const ImageTypePrimary = "primary"
 
+// ArtworkSourceFailed is a pseudo-source selecting absent states that exhausted the retry budget
+// rather than being answered. The "!" keeps it from colliding with a stored source value.
+const ArtworkSourceFailed = "!failed"
+
 // ItemImage is per-entity artwork state hydrated at query time; never persisted.
 type ItemImage struct {
 	ImageHash   string `structs:"-" json:"imageHash,omitempty"`
@@ -88,11 +92,12 @@ func (i ItemArtworkInfo) Image() ItemImage {
 }
 
 type ArtworkQueueItem struct {
-	ItemKind   string    `structs:"item_kind"`
-	ItemID     string    `structs:"item_id"`
-	ImageType  string    `structs:"image_type"`
-	Priority   int       `structs:"priority"`
-	Attempts   int       `structs:"attempts"`
+	ItemKind  string `structs:"item_kind"`
+	ItemID    string `structs:"item_id"`
+	ImageType string `structs:"image_type"`
+	Priority  int    `structs:"priority"`
+	Attempts  int    `structs:"attempts"`
+	// RetryAt is the earliest time the drain may take this row, not when it will run.
 	RetryAt    time.Time `structs:"retry_at"`
 	EnqueuedAt time.Time `structs:"enqueued_at"`
 	// Trace is why the last attempt failed. Only Get reads it; the drain projects it away.
@@ -101,7 +106,9 @@ type ArtworkQueueItem struct {
 
 // Queue priorities: higher drains first.
 const (
-	ArtworkPriorityRecheck  = 0
+	ArtworkPriorityRecheck = 0
+	// ArtworkPriorityBackfill sits between the hourly sweep and scan-driven work. Nothing enqueues
+	// it today; it stays named so a row still carrying it can be reported and cancelled.
 	ArtworkPriorityBackfill = 10
 	ArtworkPriorityScan     = 50
 	ArtworkPriorityBump     = 100
@@ -134,15 +141,13 @@ type ArtworkQueueRepository interface {
 	// EnqueuePreservingBackoff upserts like Enqueue but preserves an existing row's retry_at, so a
 	// request-triggered read-through never resets a failed resolution's backoff.
 	EnqueuePreservingBackoff(items ...ArtworkQueueItem) error
-	// EnqueueStaleAbsent inserts queue rows (priority Recheck) for absent states older than cutoff, oldest
-	// first; limit caps the selection, so already-queued rows use up budget (backpressure when the drain stalls).
-	EnqueueStaleAbsent(kind Kind, attemptedBefore time.Time, limit int) (int64, error)
 	// EnqueueAllMissing inserts queue rows for all entities with no item_artwork row, at the given priority.
 	EnqueueAllMissing(kind Kind, priority int) (int64, error)
 	// EnqueueIfMissing inserts only for items with no item_artwork row yet.
 	EnqueueIfMissing(items ...ArtworkQueueItem) error
 	// CountBySource reports how many items of a kind currently resolve from the given sources.
-	// An empty sources slice means every source; "" matches absent state.
+	// An empty sources slice means every source; "" matches absent state, and the pseudo-source
+	// ArtworkSourceFailed matches the absent states that gave up.
 	CountBySource(kind Kind, sources []string) (int64, error)
 	// SourcesInUse lists the distinct sources items of a kind currently resolve from, "" included.
 	SourcesInUse(kind Kind) ([]string, error)
@@ -161,9 +166,6 @@ type ArtworkQueueRepository interface {
 	// CountQueued reports the pending rows matching the kinds and priorities, grouped by both;
 	// an empty filter means every one.
 	CountQueued(kinds []Kind, priorities []int) ([]ArtworkQueueStat, error)
-	// CountAbsent reports the absent states of a kind, and how many are past the given cutoff,
-	// eligible for EnqueueStaleAbsent (which drains them limit rows per call).
-	CountAbsent(kind Kind, attemptedBefore time.Time) (ArtworkAbsentStat, error)
 	// PurgeDangling removes queue rows whose entity no longer exists.
 	PurgeDangling() (int64, error)
 	// PurgeQueued removes pending rows matching the kinds and priorities; an empty filter means every one.
@@ -175,8 +177,3 @@ type ArtworkQueueStat struct {
 	Priority int
 	Count    int64
 }
-
-type ArtworkAbsentStat struct {
-	Total int64
-	Stale int64
-}
diff --git a/model/mediafile.go b/model/mediafile.go
index 99aee591e..2669018f3 100644
--- a/model/mediafile.go
+++ b/model/mediafile.go
@@ -553,8 +553,6 @@ type MediaFileRepository interface {
 	// expression, using the logged user's annotations. Limit and offset are ignored.
 	MatchesCriteria(id string, c criteria.Criteria) (bool, error)
 	GetCursor(options ...QueryOptions) (MediaFileCursor, error)
-	// GetAllIDs returns just the media_file IDs for the same row set as GetAll.
-	GetAllIDs(options ...QueryOptions) ([]string, error)
 	// GetAlbumIDsByFolder returns the distinct IDs of albums with non-missing tracks in the given
 	// folders or their direct children.
 	GetAlbumIDsByFolder(lib Library, folderIDs ...string) ([]string, error)
diff --git a/model/playlist.go b/model/playlist.go
index 306401271..abd11b8c4 100644
--- a/model/playlist.go
+++ b/model/playlist.go
@@ -150,7 +150,6 @@ type PlaylistRepository interface {
 	Get(id string) (*Playlist, error)
 	GetWithTracks(id string, refreshSmartPlaylist, includeMissing bool) (*Playlist, error)
 	GetAll(options ...QueryOptions) (Playlists, error)
-	GetAllIDs(options ...QueryOptions) ([]string, error)
 	GetCursor(options ...QueryOptions) (PlaylistCursor, error)
 	FindByPath(path string) (*Playlist, error)
 	Delete(id string) error
diff --git a/model/radio.go b/model/radio.go
index 466ff48b0..013a24beb 100644
--- a/model/radio.go
+++ b/model/radio.go
@@ -35,6 +35,5 @@ type RadioRepository interface {
 	Exists(id string) (bool, error)
 	Get(id string) (*Radio, error)
 	GetAll(options ...QueryOptions) (Radios, error)
-	GetAllIDs(options ...QueryOptions) ([]string, error)
 	Put(u *Radio, colsToUpdate ...string) error
 }
diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 7ac875a51..808c880fb 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -259,8 +259,8 @@ func (r *albumRepository) hydrateArtwork(albums model.Albums) {
 		func(a *model.Album) (string, *model.ItemImage) { return a.ID, &a.ItemImage })
 }
 
-// GetAllIDs returns the IDs of GetAll's row set, skipping its column projection and JSON decoding.
-func (r *albumRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+// getAllIDs returns the IDs of GetAll's row set, skipping its column projection and JSON decoding.
+func (r *albumRepository) getAllIDs(options ...model.QueryOptions) ([]string, error) {
 	sq := r.applyLibraryFilter(r.newSelect(options...).Columns("album.id"))
 	if filtersNeedAnnotation(sq) {
 		sq = r.withAnnotation(sq, "album.id")
@@ -304,7 +304,7 @@ func (r *albumRepository) GetSoleAlbumArtistIDsInSubtrees(lib model.Library, pat
 }
 
 func (r *albumRepository) GetCursor(options ...model.QueryOptions) (model.AlbumCursor, error) {
-	ids, err := r.GetAllIDs(options...)
+	ids, err := r.getAllIDs(options...)
 	if err != nil {
 		return nil, err
 	}
diff --git a/persistence/album_repository_test.go b/persistence/album_repository_test.go
index 0fb680cff..c3d7f018f 100644
--- a/persistence/album_repository_test.go
+++ b/persistence/album_repository_test.go
@@ -152,12 +152,12 @@ var _ = Describe("AlbumRepository", func() {
 		})
 	})
 
-	Describe("GetAllIDs", func() {
+	Describe("getAllIDs", func() {
 		It("returns the same id set as GetAll", func() {
 			want, err := albumRepo.GetAll()
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).ToNot(BeEmpty())
-			ids, err := albumRepo.GetAllIDs()
+			ids, err := albumRepo.getAllIDs()
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(ConsistOf(slice.Map(want, func(a model.Album) string { return a.ID })))
 		})
diff --git a/persistence/artist_repository.go b/persistence/artist_repository.go
index 67d0df448..1ff291a0f 100644
--- a/persistence/artist_repository.go
+++ b/persistence/artist_repository.go
@@ -265,9 +265,9 @@ func (r *artistRepository) GetAll(options ...model.QueryOptions) (model.Artists,
 	return res, err
 }
 
-// GetAllIDs returns just the artist IDs for the same row set as GetAll, skipping the
+// getAllIDs returns just the artist IDs for the same row set as GetAll, skipping the
 // heavy stats columns and JSON post-processing.
-func (r *artistRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+func (r *artistRepository) getAllIDs(options ...model.QueryOptions) ([]string, error) {
 	sq := r.applyLibraryFilterToArtistQuery(r.newSelect(options...).Columns("artist.id")).GroupBy("artist.id")
 	if filtersNeedAnnotation(sq) {
 		sq = r.withAnnotation(sq, "artist.id")
@@ -284,7 +284,7 @@ func (r *artistRepository) hydrateArtwork(artists model.Artists) {
 }
 
 func (r *artistRepository) GetCursor(options ...model.QueryOptions) (model.ArtistCursor, error) {
-	ids, err := r.GetAllIDs(options...)
+	ids, err := r.getAllIDs(options...)
 	if err != nil {
 		return nil, err
 	}
diff --git a/persistence/artist_repository_test.go b/persistence/artist_repository_test.go
index 25472ffe1..d337b4c22 100644
--- a/persistence/artist_repository_test.go
+++ b/persistence/artist_repository_test.go
@@ -285,12 +285,12 @@ var _ = Describe("ArtistRepository", func() {
 			})
 		})
 
-		Describe("GetAllIDs", func() {
+		Describe("getAllIDs", func() {
 			It("returns the same id set as GetAll", func() {
 				want, err := repo.GetAll()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(want).ToNot(BeEmpty())
-				ids, err := repo.GetAllIDs()
+				ids, err := repo.(*artistRepository).getAllIDs()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(ids).To(ConsistOf(slice.Map(want, func(a model.Artist) string { return a.ID })))
 			})
diff --git a/persistence/artwork_hydration_test.go b/persistence/artwork_hydration_test.go
index 2b52d7d82..bb9cda04d 100644
--- a/persistence/artwork_hydration_test.go
+++ b/persistence/artwork_hydration_test.go
@@ -578,7 +578,7 @@ var _ = Describe("Artwork hydration", func() {
 			opts := model.QueryOptions{Sort: "name", Filters: onlyPlaylists}
 
 			// Both phases must filter on their own: the id pre-pass and the chunk fetch.
-			Expect(repo.GetAllIDs(opts)).To(ConsistOf(plsBest.ID))
+			Expect(repo.(*playlistRepository).getAllIDs(opts)).To(ConsistOf(plsBest.ID))
 			all, err := repo.GetAll(model.QueryOptions{Filters: onlyPlaylists})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(slice.Map(all, func(p model.Playlist) string { return p.ID })).To(ConsistOf(plsBest.ID))
diff --git a/persistence/artwork_queue_repository.go b/persistence/artwork_queue_repository.go
index 1c0077fc7..88b6f6f80 100644
--- a/persistence/artwork_queue_repository.go
+++ b/persistence/artwork_queue_repository.go
@@ -56,14 +56,6 @@ func (r *artworkQueueRepository) EnqueuePreservingBackoff(items ...model.Artwork
 		priority = MAX(priority, excluded.priority)`, items)
 }
 
-func (r *artworkQueueRepository) EnqueueStaleAbsent(kind model.Kind, attemptedBefore time.Time, limit int) (int64, error) {
-	now := time.Now()
-	return r.insertIfNotQueued("", `SELECT item_kind, item_id, image_type, ?, 0, ?, ?
-		FROM `+itemArtworkTable+` WHERE item_kind = ? AND hash = '' AND attempted_at < ?
-		ORDER BY attempted_at LIMIT ?`,
-		model.ArtworkPriorityRecheck, now, now, kind.Prefix(), attemptedBefore, limit)
-}
-
 func (r *artworkQueueRepository) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {
 	entityTable, ok := artworkOwnerTables[kind]
 	if !ok {
@@ -110,13 +102,23 @@ func (r *artworkQueueRepository) insertIfNotQueued(with, sql string, args ...any
 		` (`+strings.Join(enqueueColumns, ", ")+`) `+sql+skipIfQueued, args...))
 }
 
-// artworkSourceFilter selects item_artwork rows of a kind; no sources means every source, "" the absent state.
+// artworkSourceFilter selects item_artwork rows of a kind; no sources means every source, "" the
+// absent state, and ArtworkSourceFailed the absent states that gave up. Several are a union, so
+// asking for both absent and failed is just absent.
 func artworkSourceFilter(kind model.Kind, sources []string) Sqlizer {
 	f := And{Eq{"item_kind": kind.Prefix()}}
-	if len(sources) > 0 {
-		f = append(f, Eq{"source": sources})
+	if len(sources) == 0 {
+		return f
 	}
-	return f
+	stored := slices.DeleteFunc(slices.Clone(sources), func(s string) bool { return s == model.ArtworkSourceFailed })
+	var match Or
+	if len(stored) > 0 {
+		match = append(match, Eq{"source": stored})
+	}
+	if len(stored) != len(sources) {
+		match = append(match, And{Eq{"hash": ""}, NotEq{"last_failure": ""}})
+	}
+	return append(f, match)
 }
 
 func (r *artworkQueueRepository) CountBySource(kind model.Kind, sources []string) (int64, error) {
@@ -231,13 +233,4 @@ func (r *artworkQueueRepository) Count() (int64, error) {
 	return res.Count, err
 }
 
-// CountAbsent matches EnqueueStaleAbsent on hash, so the stale count is the pool a recheck drains from.
-func (r *artworkQueueRepository) CountAbsent(kind model.Kind, attemptedBefore time.Time) (model.ArtworkAbsentStat, error) {
-	var res model.ArtworkAbsentStat
-	err := r.queryOne(Select("count(*) as total").
-		Column(Expr("coalesce(sum(attempted_at < ?), 0) as stale", attemptedBefore)).
-		From(itemArtworkTable).Where(Eq{"item_kind": kind.Prefix(), "hash": ""}), &res)
-	return res, err
-}
-
 var _ model.ArtworkQueueRepository = (*artworkQueueRepository)(nil)
diff --git a/persistence/artwork_queue_repository_test.go b/persistence/artwork_queue_repository_test.go
index 1673a5b0e..0481d4193 100644
--- a/persistence/artwork_queue_repository_test.go
+++ b/persistence/artwork_queue_repository_test.go
@@ -237,41 +237,6 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		Expect(ids).To(ConsistOf(albumSgtPeppers.ID, artistKraftwerk.ID, plsBest.ID, radioWithHomePage.ID, songDayInALife.ID))
 	})
 
-	It("enqueues stale absent states for recheck", func() {
-		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
-		old := time.Now().Add(-48 * time.Hour)
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "stale1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old})).To(Succeed())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "fresh1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "found1", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: old})).To(Succeed())
-
-		n, err := repo.EnqueueStaleAbsent(model.KindArtistArtwork, time.Now().Add(-24*time.Hour), 100)
-		Expect(err).ToNot(HaveOccurred())
-		Expect(n).To(Equal(int64(1)))
-
-		items, err := repo.DequeueBatch(10)
-		Expect(err).ToNot(HaveOccurred())
-		Expect(items).To(HaveLen(1))
-		Expect(items[0].ItemID).To(Equal("stale1"))
-		Expect(items[0].Priority).To(Equal(model.ArtworkPriorityRecheck))
-	})
-
-	It("enqueues only the oldest stale absent states up to the limit", func() {
-		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
-		now := time.Now()
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "oldest", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: now.Add(-72 * time.Hour)})).To(Succeed())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "older", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: now.Add(-60 * time.Hour)})).To(Succeed())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "old", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: now.Add(-48 * time.Hour)})).To(Succeed())
-
-		n, err := repo.EnqueueStaleAbsent(model.KindArtistArtwork, now.Add(-24*time.Hour), 2)
-		Expect(err).ToNot(HaveOccurred())
-		Expect(n).To(Equal(int64(2)))
-
-		items, err := repo.DequeueBatch(10)
-		Expect(err).ToNot(HaveOccurred())
-		ids := slice.Map(items, func(it model.ArtworkQueueItem) string { return it.ItemID })
-		Expect(ids).To(ConsistOf("oldest", "older"))
-	})
-
 	It("enqueues entities that have no item_artwork row at all", func() {
 		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
 		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: albumSgtPeppers.ID, ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: time.Now()})).To(Succeed())
@@ -435,29 +400,49 @@ var _ = Describe("ArtworkQueueRepository", func() {
 			))
 		})
 
-		It("reports an empty queue as no rows", func() {
-			Expect(repo.CountQueued(nil, nil)).To(BeEmpty())
-		})
-
-		It("counts absent states and how many are due for recheck", func() {
+		It("selects only the absent states that gave up, not those a source answered", func() {
 			awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
-			old := time.Now().Add(-48 * time.Hour)
 			for _, ia := range []model.ItemArtwork{
-				{ItemKind: "ar", ItemID: "stale1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old},
-				{ItemKind: "ar", ItemID: "fresh1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()},
-				{ItemKind: "ar", ItemID: "found1", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: old},
-				{ItemKind: "al", ItemID: "stale2", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old},
+				{ItemKind: "ar", ItemID: "gaveup", ImageType: model.ImageTypePrimary, LastFailure: "[]"},
+				{ItemKind: "ar", ItemID: "toldno", ImageType: model.ImageTypePrimary},
+				{ItemKind: "ar", ItemID: "hasart", ImageType: model.ImageTypePrimary, Hash: "hX", LastFailure: "[]"},
 			} {
 				Expect(awRepo.PutItemArtwork(&ia)).To(Succeed())
 			}
 
-			Expect(repo.CountAbsent(model.KindArtistArtwork, time.Now().Add(-24*time.Hour))).
-				To(Equal(model.ArtworkAbsentStat{Total: 2, Stale: 1}))
+			Expect(repo.CountBySource(model.KindArtistArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(1)),
+				"an item still serving art is not absent, however its last attempt went")
+
+			// A later success rewrites the row, clearing the record.
+			Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "gaveup",
+				ImageType: model.ImageTypePrimary, Hash: "hZ"})).To(Succeed())
+			Expect(repo.CountBySource(model.KindArtistArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(0)))
 		})
 
-		It("reports a kind with no absent state as zero, not as an error", func() {
-			Expect(repo.CountAbsent(model.KindRadioArtwork, time.Now())).To(Equal(model.ArtworkAbsentStat{}))
+		It("unions the failed pseudo-source with a real one, so absent plus failed is just absent", func() {
+			awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+			for _, ia := range []model.ItemArtwork{
+				{ItemKind: "ar", ItemID: "gaveup", ImageType: model.ImageTypePrimary, LastFailure: "[]"},
+				{ItemKind: "ar", ItemID: "toldno", ImageType: model.ImageTypePrimary},
+				{ItemKind: "ar", ItemID: "folder", ImageType: model.ImageTypePrimary, Hash: "hX", Source: "folder"},
+			} {
+				Expect(awRepo.PutItemArtwork(&ia)).To(Succeed())
+			}
+			failedAndAbsent := []string{model.ArtworkSourceFailed, ""}
+			Expect(repo.CountBySource(model.KindArtistArtwork, failedAndAbsent)).To(Equal(int64(2)),
+				"failed is a subset of absent, so asking for both is asking for absent")
+			Expect(repo.CountBySource(model.KindArtistArtwork, []string{model.ArtworkSourceFailed, "folder"})).
+				To(Equal(int64(2)), "a pseudo-source and a stored source combine as a union")
 		})
+
+		It("reports a kind with nothing failed as zero", func() {
+			Expect(repo.CountBySource(model.KindRadioArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(0)))
+		})
+
+		It("reports an empty queue as no rows", func() {
+			Expect(repo.CountQueued(nil, nil)).To(BeEmpty())
+		})
+
 	})
 
 	Describe("PurgeQueued", func() {
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index ed18333de..da167b1a8 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -308,8 +308,8 @@ func (r *mediaFileRepository) GetCursor(options ...model.QueryOptions) (model.Me
 	return wrapMediaFileCursor(cursor), nil
 }
 
-// GetAllIDs returns the IDs of GetAll's row set, skipping its wide column projection.
-func (r *mediaFileRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+// getAllIDs returns the IDs of GetAll's row set, skipping its wide column projection.
+func (r *mediaFileRepository) getAllIDs(options ...model.QueryOptions) ([]string, error) {
 	sq := r.applyLibraryFilter(r.newSelect(options...).Columns("media_file.id"))
 	if filtersNeedAnnotation(sq) {
 		sq = r.withAnnotation(sq, "media_file.id")
@@ -341,7 +341,7 @@ func (r *mediaFileRepository) GetAlbumIDsByFolder(lib model.Library, folderIDs .
 
 // GetCursorWithArtwork streams the same rows as GetCursor, hydrated, via an id pre-pass.
 func (r *mediaFileRepository) GetCursorWithArtwork(options ...model.QueryOptions) (model.MediaFileCursor, error) {
-	ids, err := r.GetAllIDs(options...)
+	ids, err := r.getAllIDs(options...)
 	if err != nil {
 		return nil, err
 	}
diff --git a/persistence/playlist_repository.go b/persistence/playlist_repository.go
index 505f23440..bf8d6d5a8 100644
--- a/persistence/playlist_repository.go
+++ b/persistence/playlist_repository.go
@@ -208,8 +208,8 @@ func (r *playlistRepository) GetAll(options ...model.QueryOptions) (model.Playli
 	return playlists, err
 }
 
-// GetAllIDs returns the IDs of GetAll's row set, skipping its per-row processing.
-func (r *playlistRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
+// getAllIDs returns the IDs of GetAll's row set, skipping its per-row processing.
+func (r *playlistRepository) getAllIDs(options ...model.QueryOptions) ([]string, error) {
 	// Joins a projection of user, not the table: its name/created_at columns would make an ORDER BY
 	// on the playlist's own ambiguous.
 	sq := r.newSelect(options...).Columns("playlist.id", "user.user_name as owner_name").
@@ -224,7 +224,7 @@ func (r *playlistRepository) GetAllIDs(options ...model.QueryOptions) ([]string,
 
 func (r *playlistRepository) GetCursor(options ...model.QueryOptions) (model.PlaylistCursor, error) {
 	// Both passes apply userFilter, so a visibility change between them cannot widen the cursor.
-	ids, err := r.GetAllIDs(options...)
+	ids, err := r.getAllIDs(options...)
 	if err != nil {
 		return nil, err
 	}
diff --git a/persistence/playlist_repository_test.go b/persistence/playlist_repository_test.go
index f60b4e7ca..60263807a 100644
--- a/persistence/playlist_repository_test.go
+++ b/persistence/playlist_repository_test.go
@@ -74,12 +74,12 @@ var _ = Describe("PlaylistRepository", func() {
 		})
 	})
 
-	Describe("GetAllIDs", func() {
+	Describe("getAllIDs", func() {
 		It("returns the same id set as GetAll", func() {
 			want, err := repo.GetAll()
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).ToNot(BeEmpty())
-			ids, err := repo.GetAllIDs()
+			ids, err := repo.(*playlistRepository).getAllIDs()
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(ConsistOf(slice.Map(want, func(p model.Playlist) string { return p.ID })))
 		})
diff --git a/persistence/radio_repository.go b/persistence/radio_repository.go
index 915859559..e042ee6bf 100644
--- a/persistence/radio_repository.go
+++ b/persistence/radio_repository.go
@@ -79,14 +79,6 @@ func (r *radioRepository) hydrateArtwork(radios model.Radios) {
 		func(rd *model.Radio) (string, *model.ItemImage) { return rd.ID, &rd.ItemImage })
 }
 
-// GetAllIDs returns just the radio IDs. Used by bulk enumeration (artwork backfill).
-func (r *radioRepository) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
-	sel := r.newSelect(options...).Columns("id")
-	ids := []string{}
-	err := r.queryAllSlice(sel, &ids)
-	return ids, err
-}
-
 func (r *radioRepository) Put(radio *model.Radio, colsToUpdate ...string) error {
 	if !r.isPermitted() {
 		return rest.ErrPermissionDenied
diff --git a/persistence/radio_repository_test.go b/persistence/radio_repository_test.go
index c35c85ad7..a958f715d 100644
--- a/persistence/radio_repository_test.go
+++ b/persistence/radio_repository_test.go
@@ -7,7 +7,6 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
-	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -79,17 +78,6 @@ var _ = Describe("RadioRepository", func() {
 			})
 		})
 
-		Describe("GetAllIDs", func() {
-			It("returns the same id set as GetAll", func() {
-				want, err := repo.GetAll()
-				Expect(err).To(BeNil())
-				Expect(want).ToNot(BeEmpty())
-				ids, err := repo.GetAllIDs()
-				Expect(err).To(BeNil())
-				Expect(ids).To(ConsistOf(slice.Map(want, func(r model.Radio) string { return r.ID })))
-			})
-		})
-
 		Describe("Put", func() {
 			It("successfully updates item", func() {
 				err := repo.Put(&model.Radio{
diff --git a/tests/mock_album_repo.go b/tests/mock_album_repo.go
index c63f7c425..1b14f225b 100644
--- a/tests/mock_album_repo.go
+++ b/tests/mock_album_repo.go
@@ -7,7 +7,6 @@ import (
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
-	"github.com/navidrome/navidrome/utils/slice"
 )
 
 func CreateMockAlbumRepo() *MockAlbumRepo {
@@ -85,14 +84,6 @@ func (m *MockAlbumRepo) GetAll(qo ...model.QueryOptions) (model.Albums, error) {
 	return m.All, nil
 }
 
-func (m *MockAlbumRepo) GetAllIDs(qo ...model.QueryOptions) ([]string, error) {
-	all, err := m.GetAll(qo...)
-	if err != nil {
-		return nil, err
-	}
-	return slice.Map(all, func(a model.Album) string { return a.ID }), nil
-}
-
 func (m *MockAlbumRepo) GetCursor(qo ...model.QueryOptions) (model.AlbumCursor, error) {
 	res, err := m.GetAll(qo...)
 	if err != nil {
diff --git a/tests/mock_artist_repo.go b/tests/mock_artist_repo.go
index af393129e..db7d54d5d 100644
--- a/tests/mock_artist_repo.go
+++ b/tests/mock_artist_repo.go
@@ -6,7 +6,6 @@ import (
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
-	"github.com/navidrome/navidrome/utils/slice"
 )
 
 func CreateMockArtistRepo() *MockArtistRepo {
@@ -117,14 +116,6 @@ func (m *MockArtistRepo) GetAll(options ...model.QueryOptions) (model.Artists, e
 	return allArtists, nil
 }
 
-func (m *MockArtistRepo) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
-	all, err := m.GetAll(options...)
-	if err != nil {
-		return nil, err
-	}
-	return slice.Map(all, func(a model.Artist) string { return a.ID }), nil
-}
-
 func (m *MockArtistRepo) GetCursor(options ...model.QueryOptions) (model.ArtistCursor, error) {
 	res, err := m.GetAll(options...)
 	if err != nil {
diff --git a/tests/mock_artwork_queue_repo.go b/tests/mock_artwork_queue_repo.go
index 51ddf4b61..c482e2150 100644
--- a/tests/mock_artwork_queue_repo.go
+++ b/tests/mock_artwork_queue_repo.go
@@ -16,7 +16,7 @@ type MockArtworkQueueRepo struct {
 	mu   sync.Mutex
 	Data map[string]model.ArtworkQueueItem // keyed by iaKey(kind, id, imageType)
 	Err  error
-	// ItemArtworkSource, when set, backs EnqueueStaleAbsent with real item_artwork state.
+	// ItemArtworkSource, when set, backs the set-difference insert with real item_artwork state.
 	ItemArtworkSource *MockArtworkRepo
 	// ExistingIDs is keyed by item_kind; a nil per-kind map means PurgeDangling keeps that kind.
 	ExistingIDs map[string]map[string]bool
@@ -226,26 +226,6 @@ func (m *MockArtworkQueueRepo) CountQueued(kinds []model.Kind, priorities []int)
 	return res, nil
 }
 
-// CountAbsent mirrors the SQL predicate: an absent state is one with no hash.
-func (m *MockArtworkQueueRepo) CountAbsent(kind model.Kind, attemptedBefore time.Time) (model.ArtworkAbsentStat, error) {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-	var res model.ArtworkAbsentStat
-	if m.Err != nil || m.ItemArtworkSource == nil {
-		return res, m.Err
-	}
-	for _, ia := range m.ItemArtworkSource.ItemData {
-		if ia.ItemKind != kind.Prefix() || ia.Hash != "" {
-			continue
-		}
-		res.Total++
-		if ia.AttemptedAt.Before(attemptedBefore) {
-			res.Stale++
-		}
-	}
-	return res, nil
-}
-
 func (m *MockArtworkQueueRepo) EnqueuePreservingBackoff(items ...model.ArtworkQueueItem) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -272,49 +252,24 @@ func (m *MockArtworkQueueRepo) EnqueuePreservingBackoff(items ...model.ArtworkQu
 	return nil
 }
 
-func (m *MockArtworkQueueRepo) EnqueueStaleAbsent(kind model.Kind, attemptedBefore time.Time, limit int) (int64, error) {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-	if m.Err != nil || m.ItemArtworkSource == nil {
-		return 0, m.Err
-	}
-	var stale []model.ItemArtwork
-	for _, ia := range m.ItemArtworkSource.ItemData {
-		if ia.ItemKind == kind.Prefix() && ia.Hash == "" && ia.AttemptedAt.Before(attemptedBefore) {
-			stale = append(stale, ia)
-		}
-	}
-	slices.SortFunc(stale, func(a, b model.ItemArtwork) int { return a.AttemptedAt.Compare(b.AttemptedAt) })
-	// The limit caps the selection, like the SQL's LIMIT before ON CONFLICT: queued rows use up budget.
-	stale = stale[:min(limit, len(stale))]
-	now := time.Now()
-	var inserted int64
-	for _, ia := range stale {
-		k := iaKey(ia.ItemKind, ia.ItemID, ia.ImageType)
-		if _, ok := m.Data[k]; ok { // DO NOTHING: never touch existing queue rows
-			continue
-		}
-		m.Data[k] = model.ArtworkQueueItem{
-			ItemKind:   ia.ItemKind,
-			ItemID:     ia.ItemID,
-			ImageType:  ia.ImageType,
-			Priority:   model.ArtworkPriorityRecheck,
-			RetryAt:    now,
-			EnqueuedAt: now,
-		}
-		inserted++
-	}
-	return inserted, nil
-}
-
-// matchingSource mirrors the SQL filter: no sources means every source, "" the absent state.
+// matchingSource mirrors the SQL filter: no sources means every source, "" the absent state, and
+// ArtworkSourceFailed the absent states that gave up.
 func (m *MockArtworkQueueRepo) matchingSource(kind model.Kind, sources []string) []model.ItemArtwork {
 	if m.ItemArtworkSource == nil {
 		return nil
 	}
+	matches := func(ia model.ItemArtwork) bool {
+		if len(sources) == 0 {
+			return true
+		}
+		if slices.Contains(sources, ia.Source) {
+			return true
+		}
+		return slices.Contains(sources, model.ArtworkSourceFailed) && ia.Hash == "" && ia.LastFailure != ""
+	}
 	var res []model.ItemArtwork
 	for _, ia := range m.ItemArtworkSource.ItemData {
-		if ia.ItemKind == kind.Prefix() && (len(sources) == 0 || slices.Contains(sources, ia.Source)) {
+		if ia.ItemKind == kind.Prefix() && matches(ia) {
 			res = append(res, ia)
 		}
 	}
@@ -366,7 +321,7 @@ func (m *MockArtworkQueueRepo) EnqueueBySource(kind model.Kind, sources []string
 	return inserted, nil
 }
 
-// EnqueueMissing mirrors the SQL set-difference insert: ExistingIDs[kind] minus ItemArtworkSource.
+// EnqueueAllMissing mirrors the SQL set-difference insert: ExistingIDs[kind] minus ItemArtworkSource.
 func (m *MockArtworkQueueRepo) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
diff --git a/tests/mock_mediafile_repo.go b/tests/mock_mediafile_repo.go
index f18280fd5..7a1a8f926 100644
--- a/tests/mock_mediafile_repo.go
+++ b/tests/mock_mediafile_repo.go
@@ -130,14 +130,6 @@ func (m *MockMediaFileRepo) GetCursorWithArtwork(qo ...model.QueryOptions) (mode
 	return m.GetCursor(qo...)
 }
 
-func (m *MockMediaFileRepo) GetAllIDs(qo ...model.QueryOptions) ([]string, error) {
-	all, err := m.GetAll(qo...)
-	if err != nil {
-		return nil, err
-	}
-	return slice.Map(all, func(mf model.MediaFile) string { return mf.ID }), nil
-}
-
 func (m *MockMediaFileRepo) Put(mf *model.MediaFile) error {
 	if m.Err {
 		return errors.New("error")
diff --git a/tests/mock_playlist_repo.go b/tests/mock_playlist_repo.go
index f04ed98c6..0fa9618ae 100644
--- a/tests/mock_playlist_repo.go
+++ b/tests/mock_playlist_repo.go
@@ -7,7 +7,6 @@ import (
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
-	"github.com/navidrome/navidrome/utils/slice"
 )
 
 func CreateMockPlaylistRepo() *MockPlaylistRepo {
@@ -54,14 +53,6 @@ func (m *MockPlaylistRepo) GetAll(options ...model.QueryOptions) (model.Playlist
 	return m.All, nil
 }
 
-func (m *MockPlaylistRepo) GetAllIDs(options ...model.QueryOptions) ([]string, error) {
-	all, err := m.GetAll(options...)
-	if err != nil {
-		return nil, err
-	}
-	return slice.Map(all, func(p model.Playlist) string { return p.ID }), nil
-}
-
 func (m *MockPlaylistRepo) GetCursor(options ...model.QueryOptions) (model.PlaylistCursor, error) {
 	res, err := m.GetAll(options...)
 	if err != nil {
diff --git a/tests/mock_radio_repository.go b/tests/mock_radio_repository.go
index 2baeadc5c..20f81ec45 100644
--- a/tests/mock_radio_repository.go
+++ b/tests/mock_radio_repository.go
@@ -5,7 +5,6 @@ import (
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
-	"github.com/navidrome/navidrome/utils/slice"
 )
 
 type MockedRadioRepo struct {
@@ -74,14 +73,6 @@ func (m *MockedRadioRepo) GetAll(qo ...model.QueryOptions) (model.Radios, error)
 	return m.All, nil
 }
 
-func (m *MockedRadioRepo) GetAllIDs(qo ...model.QueryOptions) ([]string, error) {
-	all, err := m.GetAll(qo...)
-	if err != nil {
-		return nil, err
-	}
-	return slice.Map(all, func(r model.Radio) string { return r.ID }), nil
-}
-
 func (m *MockedRadioRepo) Put(radio *model.Radio, _ ...string) error {
 	if m.Err {
 		return errors.New("error")

From bd46284087ad0ceed420e1aaf7f54e380637648b Mon Sep 17 00:00:00 2001
From: Kendall Garner <17521368+kgarner7@users.noreply.github.com>
Date: Tue, 1 Sep 2026 18:16:14 -0700
Subject: [PATCH 103/200] feat: validate all configuration durations (#6002)

* chore: ensure that all durations are nonnegative

* make sure you actually include the test file

* test(conf): use non-zero durations in the valid_duration fixture

Zero is the boundary between the accepted and rejected ranges, so it
passes even if the guard is off by one. 1s exercises an ordinary value.

---------

Co-authored-by: Deluan <deluan@navidrome.org>
---
 conf/configuration.go               | 27 +++++++++++++++--
 conf/configuration_test.go          | 45 +++++++++++++++++++++++++++++
 conf/testdata/invalid_duration.toml | 12 ++++++++
 conf/testdata/valid_duration.toml   | 12 ++++++++
 consts/consts.go                    |  6 ++++
 5 files changed, 99 insertions(+), 3 deletions(-)
 create mode 100644 conf/testdata/invalid_duration.toml
 create mode 100644 conf/testdata/valid_duration.toml

diff --git a/conf/configuration.go b/conf/configuration.go
index b9c9f027e..ff119417a 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -351,6 +351,13 @@ func LoadFromFile(confFile string) {
 	Load(true)
 }
 
+func durationNonNegativeOrDefault(val *time.Duration, original time.Duration) {
+	if val.Nanoseconds() < 0 {
+		log.Warn("Duration is a negative value. Using default value", "value", *val, "default", original)
+		*val = original
+	}
+}
+
 func Load(noConfigDump bool) {
 	parseIniFileConfiguration()
 	remapEnvVarKeysFromConfig()
@@ -418,6 +425,20 @@ func Load(noConfigDump bool) {
 	log.SetLogSourceLine(Server.DevLogSourceLine)
 	log.SetRedacting(Server.EnableLogRedacting)
 
+	durationNonNegativeOrDefault(&Server.SessionTimeout, consts.DefaultSessionTimeout)
+	durationNonNegativeOrDefault(&Server.SmartPlaylistRefreshDelay, consts.DefaultSmartRefresh)
+	durationNonNegativeOrDefault(&Server.DefaultShareExpiration, consts.DefaultShareExpiration)
+	durationNonNegativeOrDefault(&Server.UIPlaybackReportInterval, consts.DefaultUIPlaybackReportInterval)
+	durationNonNegativeOrDefault(&Server.AuthWindowLength, consts.DefaultAuthWindowLength)
+	durationNonNegativeOrDefault(&Server.Scanner.WatcherWait, consts.DefaultWatcherWait)
+
+	durationNonNegativeOrDefault(&Server.DevActivityPanelUpdateRate, consts.DefaultActivityPanelUpdateRate)
+	durationNonNegativeOrDefault(&Server.DevArtworkThrottleBacklogTimeout, consts.RequestThrottleBacklogTimeout)
+	durationNonNegativeOrDefault(&Server.DevArtistInfoTimeToLive, consts.ArtistInfoTimeToLive)
+	durationNonNegativeOrDefault(&Server.DevAlbumInfoTimeToLive, consts.AlbumInfoTimeToLive)
+	durationNonNegativeOrDefault(&Server.DevInsightsInitialDelay, consts.InsightsInitialDelay)
+	durationNonNegativeOrDefault(&Server.DevPluginCompilationTimeout, consts.DefaultPluginCompilationTimeout)
+
 	// Log deprecated, removed and unknown options
 	for _, o := range deprecatedOptions {
 		logDeprecatedOptions(o.name, o.replacement)
@@ -967,7 +988,7 @@ func setViperDefaults() {
 	viper.SetDefault("autoimportplaylists", true)
 	viper.SetDefault("defaultplaylistpublicvisibility", false)
 	viper.SetDefault("playlistspath", "")
-	viper.SetDefault("smartPlaylistRefreshDelay", 5*time.Second)
+	viper.SetDefault("smartPlaylistRefreshDelay", consts.DefaultSmartRefresh)
 	viper.SetDefault("enabledownloads", true)
 	viper.SetDefault("enableexternalservices", true)
 	viper.SetDefault("enablem3uexternalalbumart", false)
@@ -1011,14 +1032,14 @@ func setViperDefaults() {
 	viper.SetDefault("maximagesize", consts.DefaultMaxImageSize)
 	viper.SetDefault("enablesharing", true)
 	viper.SetDefault("shareurl", "")
-	viper.SetDefault("defaultshareexpiration", 8760*time.Hour)
+	viper.SetDefault("defaultshareexpiration", consts.DefaultShareExpiration)
 	viper.SetDefault("defaultdownloadableshare", false)
 	viper.SetDefault("gatrackingid", "")
 	viper.SetDefault("enableinsightscollector", true)
 	viper.SetDefault("enablescheduleddbanalyze", true)
 	viper.SetDefault("enablelogredacting", true)
 	viper.SetDefault("authrequestlimit", 5)
-	viper.SetDefault("authwindowlength", 20*time.Second)
+	viper.SetDefault("authwindowlength", consts.DefaultAuthWindowLength)
 	viper.SetDefault("passwordencryptionkey", "")
 	viper.SetDefault("extauth.userheader", "Remote-User")
 	viper.SetDefault("extauth.trustedsources", "")
diff --git a/conf/configuration_test.go b/conf/configuration_test.go
index 344ab3595..2c7f8edaa 100644
--- a/conf/configuration_test.go
+++ b/conf/configuration_test.go
@@ -6,9 +6,11 @@ import (
 	"os"
 	"path/filepath"
 	"testing"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -453,6 +455,49 @@ var _ = Describe("Configuration", func() {
 		Entry("INI format", "ini"),
 		Entry("JSON format", "json"),
 	)
+
+	It("should use default values for negative duration fields", func() {
+		filename := filepath.Join("testdata", "invalid_duration.toml")
+		conf.InitConfig(filename, false)
+		conf.Load(true)
+
+		server := conf.Server
+		Expect(server.SessionTimeout).To(Equal(consts.DefaultSessionTimeout))
+		Expect(server.SmartPlaylistRefreshDelay).To(Equal(consts.DefaultSmartRefresh))
+		Expect(server.DefaultShareExpiration).To(Equal(consts.DefaultShareExpiration))
+		Expect(server.UIPlaybackReportInterval).To(Equal(consts.DefaultUIPlaybackReportInterval))
+		Expect(server.AuthWindowLength).To(Equal(consts.DefaultAuthWindowLength))
+		Expect(server.Scanner.WatcherWait).To(Equal(consts.DefaultWatcherWait))
+
+		Expect(server.DevActivityPanelUpdateRate).To(Equal(consts.DefaultActivityPanelUpdateRate))
+		Expect(server.DevArtworkThrottleBacklogTimeout).To(Equal(consts.RequestThrottleBacklogTimeout))
+		Expect(server.DevArtistInfoTimeToLive).To(Equal(consts.ArtistInfoTimeToLive))
+		Expect(server.DevAlbumInfoTimeToLive).To(Equal(consts.AlbumInfoTimeToLive))
+		Expect(server.DevInsightsInitialDelay).To(Equal(consts.InsightsInitialDelay))
+		Expect(server.DevPluginCompilationTimeout).To(Equal(consts.DefaultPluginCompilationTimeout))
+	})
+
+	It("should use parsed values for duration fields", func() {
+		conf.InitConfig(filepath.Join("testdata", "valid_duration.toml"), false)
+		conf.Load(true)
+
+		configured := 1 * time.Second
+
+		server := conf.Server
+		Expect(server.SessionTimeout).To(Equal(configured))
+		Expect(server.SmartPlaylistRefreshDelay).To(Equal(configured))
+		Expect(server.DefaultShareExpiration).To(Equal(configured))
+		Expect(server.UIPlaybackReportInterval).To(Equal(configured))
+		Expect(server.AuthWindowLength).To(Equal(configured))
+		Expect(server.Scanner.WatcherWait).To(Equal(configured))
+
+		Expect(server.DevActivityPanelUpdateRate).To(Equal(configured))
+		Expect(server.DevArtworkThrottleBacklogTimeout).To(Equal(configured))
+		Expect(server.DevArtistInfoTimeToLive).To(Equal(configured))
+		Expect(server.DevAlbumInfoTimeToLive).To(Equal(configured))
+		Expect(server.DevInsightsInitialDelay).To(Equal(configured))
+		Expect(server.DevPluginCompilationTimeout).To(Equal(configured))
+	})
 })
 
 var _ = Describe("TLSEnabled", func() {
diff --git a/conf/testdata/invalid_duration.toml b/conf/testdata/invalid_duration.toml
new file mode 100644
index 000000000..6540fef60
--- /dev/null
+++ b/conf/testdata/invalid_duration.toml
@@ -0,0 +1,12 @@
+SessionTimeout = "-10s"
+SmartPlaylistRefreshDelay = "-10s"
+UIPlaybackReportInterval = "-10s"
+AuthWindowLength = "-10s"
+DefaultShareExpiration = "-10s"
+Scanner.WatcherWait = "-10s"
+DevActivityPanelUpdateRate = "-10s"
+DevArtworkThrottleBacklogTimeout = "-10s"
+DevArtistInfoTimeToLive = "-10s"
+DevAlbumInfoTimeToLive = "-10s"
+DevInsightsInitialDelay = "-10s"
+DevPluginCompilationTimeout = "-10s"
diff --git a/conf/testdata/valid_duration.toml b/conf/testdata/valid_duration.toml
new file mode 100644
index 000000000..6ec4af480
--- /dev/null
+++ b/conf/testdata/valid_duration.toml
@@ -0,0 +1,12 @@
+SessionTimeout = "1s"
+SmartPlaylistRefreshDelay = "1s"
+UIPlaybackReportInterval = "1s"
+AuthWindowLength = "1s"
+DefaultShareExpiration = "1s"
+Scanner.WatcherWait = "1s"
+DevActivityPanelUpdateRate = "1s"
+DevArtworkThrottleBacklogTimeout = "1s"
+DevArtistInfoTimeToLive = "1s"
+DevAlbumInfoTimeToLive = "1s"
+DevInsightsInitialDelay = "1s"
+DevPluginCompilationTimeout = "1s"
diff --git a/consts/consts.go b/consts/consts.go
index 0f950ef10..486ea66bc 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -34,6 +34,8 @@ const (
 	JWTPublicSecretKey     = "JWTPublicSecret"
 	JWTIssuer              = "ND"
 	DefaultSessionTimeout  = 48 * time.Hour
+	DefaultSmartRefresh    = 5 * time.Second
+	DefaultShareExpiration = 8760 * time.Hour
 	CookieExpiry           = 365 * 24 * 3600 // One year
 
 	DBAnalyzeCheckSchedule = "@every 30m"
@@ -71,6 +73,7 @@ const (
 	DefaultUILoginBackgroundURLOffline = "data:image/png;base64," + DefaultUILoginBackgroundOffline
 	DefaultMaxSidebarPlaylists         = 100
 
+	DefaultAuthWindowLength       = 20 * time.Second
 	RequestThrottleBacklogLimit   = 100
 	RequestThrottleBacklogTimeout = time.Minute
 
@@ -106,6 +109,9 @@ const (
 	DefaultScannerExtractor = "taglib"
 	DefaultWatcherWait      = 5 * time.Second
 	Zwsp                    = string('\u200b')
+
+	DefaultActivityPanelUpdateRate  = 300 * time.Millisecond
+	DefaultPluginCompilationTimeout = time.Minute
 )
 
 const (

From cb045b8ef3959f0ee225d65857b665dfc1508df4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 1 Sep 2026 23:02:15 -0400
Subject: [PATCH 104/200] ci: exclude tests/ from the coverage report on pull
 requests too (#6070)

The exclusion only worked on master. Coverage profiles name files by import
path; octocov shortens those to repo-relative paths using the checked-out
source, but coverage-on-pr.yml sparse-checks-out only .octocov.yml, so the
paths stay as github.com/navidrome/navidrome/tests/mock_*.go and 'tests/**'
never matched. '**/*_gen.go' matched either way, which is why only the 30
tests/ files leaked.

Every pull request since b77fb45 therefore reported ~-3.7% against master:
447 files on the base side, 477 on the pull request side (#6002, #6069).
---
 .octocov.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.octocov.yml b/.octocov.yml
index 467998b51..c4ad10712 100644
--- a/.octocov.yml
+++ b/.octocov.yml
@@ -8,8 +8,10 @@ coverage:
   paths:
     - coverage.out
   # Not code under test: tests/ holds the mocks and helpers, *_gen.go is generated.
+  # Both patterns need the '**/' prefix: the comment workflow has no source tree,
+  # so octocov cannot shorten the profile's import paths to repo-relative ones.
   exclude:
-    - 'tests/**'
+    - '**/tests/**'
     - '**/*_gen.go'
 codeToTestRatio:
   # Needs the pull request's own source, which the comment workflow must not

From 8407fe6dda7e2c24a618127fd5cade2608e9f1c0 Mon Sep 17 00:00:00 2001
From: polybjorn <service@polybjorn.com>
Date: Thu, 3 Sep 2026 00:49:50 +0000
Subject: [PATCH 105/200] fix(ui): reload the playlist after rating or loving a
 track (#6009)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A playlistTrack id is a position in the playlist, not a stable key, so refetching
a row by id after the annotation is saved can return a different song: in a smart
playlist filtered on that annotation the track is gone and every later row has
shifted up. The stale-keyed record then renders as a duplicate of its neighbour.

Signed-off-by: Bjørn A. Andersen <polybjorn@users.noreply.github.com>
Co-authored-by: Bjørn A. Andersen <polybjorn@users.noreply.github.com>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 ui/src/common/useRating.jsx         | 22 ++++++---------
 ui/src/common/useRating.test.js     | 43 +++++++++++++++--------------
 ui/src/common/useToggleLove.jsx     | 31 ++++++++++-----------
 ui/src/common/useToggleLove.test.js | 39 +++++++++++++-------------
 4 files changed, 65 insertions(+), 70 deletions(-)

diff --git a/ui/src/common/useRating.jsx b/ui/src/common/useRating.jsx
index 2eb5d9eca..82e9bfc06 100644
--- a/ui/src/common/useRating.jsx
+++ b/ui/src/common/useRating.jsx
@@ -1,11 +1,12 @@
 import { useState, useCallback, useEffect, useRef } from 'react'
-import { useDataProvider, useNotify } from 'react-admin'
+import { useDataProvider, useNotify, useRefresh } from 'react-admin'
 import subsonic from '../subsonic'
 
 export const useRating = (resource, record) => {
   const [loading, setLoading] = useState(false)
   const notify = useNotify()
   const dataProvider = useDataProvider()
+  const refresh = useRefresh()
   const mountedRef = useRef(false)
   const rating = record.rating
 
@@ -17,23 +18,18 @@ export const useRating = (resource, record) => {
   }, [])
 
   const refreshRating = useCallback(() => {
-    // For playlist tracks, refresh both resources to keep data in sync
     if (record.mediaFileId) {
-      // This is a playlist track - refresh both the playlist track and the song
-      const promises = [
-        dataProvider.getOne('song', { id: record.mediaFileId }),
-        dataProvider.getOne('playlistTrack', {
-          id: record.id,
-          filter: { playlist_id: record.playlistId },
-        }),
-      ]
-
-      Promise.all(promises)
+      // A playlistTrack id is a position, not a stable key: rating a song can drop it out
+      // of a smart playlist, and that position then holds a different track. Refetching
+      // the row by id would write the neighbour's data under this row, so reload the list.
+      dataProvider
+        .getOne('song', { id: record.mediaFileId })
         .catch((e) => {
           // eslint-disable-next-line no-console
           console.log('Error encountered: ' + e)
         })
         .finally(() => {
+          refresh()
           if (mountedRef.current) {
             setLoading(false)
           }
@@ -52,7 +48,7 @@ export const useRating = (resource, record) => {
           }
         })
     }
-  }, [dataProvider, record.id, record.mediaFileId, record.playlistId, resource])
+  }, [dataProvider, record.id, record.mediaFileId, refresh, resource])
 
   const rate = (val, id) => {
     setLoading(true)
diff --git a/ui/src/common/useRating.test.js b/ui/src/common/useRating.test.js
index b1353512e..ffe9abffd 100644
--- a/ui/src/common/useRating.test.js
+++ b/ui/src/common/useRating.test.js
@@ -4,6 +4,8 @@ import { useRating } from './useRating'
 import subsonic from '../subsonic'
 import { useDataProvider } from 'react-admin'
 
+const mockRefresh = vi.fn()
+
 vi.mock('../subsonic', () => ({
   default: {
     setRating: vi.fn(() => Promise.resolve()),
@@ -16,13 +18,16 @@ vi.mock('react-admin', async () => {
     ...actual,
     useDataProvider: vi.fn(),
     useNotify: vi.fn(() => vi.fn()),
+    useRefresh: vi.fn(() => mockRefresh),
   }
 })
 
 describe('useRating', () => {
   let getOne
   beforeEach(() => {
-    getOne = vi.fn(() => Promise.resolve())
+    getOne = vi.fn((resource, params) =>
+      Promise.resolve({ data: { id: params.id } }),
+    )
     useDataProvider.mockReturnValue({ getOne })
     vi.clearAllMocks()
   })
@@ -56,9 +61,9 @@ describe('useRating', () => {
   })
 
   describe('playlist track scenarios', () => {
-    it('refreshes both playlist track and song for playlist tracks', async () => {
+    it('refreshes the song and reloads the list for playlist tracks', async () => {
       const record = {
-        id: 'pt-1',
+        id: '1',
         mediaFileId: 'sg-1',
         playlistId: 'pl-1',
         rating: 2,
@@ -71,18 +76,21 @@ describe('useRating', () => {
       // Should rate using the media file ID
       expect(subsonic.setRating).toHaveBeenCalledWith('sg-1', 5)
 
-      // Should refresh both the playlist track and the song
-      expect(getOne).toHaveBeenCalledTimes(2)
-      expect(getOne).toHaveBeenCalledWith('playlistTrack', {
-        id: 'pt-1',
-        filter: { playlist_id: 'pl-1' },
-      })
+      // The row is a position in the playlist, so it cannot be refetched by id:
+      // rating can drop the track out of a smart playlist and shift every row up
+      expect(getOne).toHaveBeenCalledTimes(1)
       expect(getOne).toHaveBeenCalledWith('song', { id: 'sg-1' })
+      expect(getOne).not.toHaveBeenCalledWith(
+        'playlistTrack',
+        expect.anything(),
+      )
+      expect(mockRefresh).toHaveBeenCalled()
     })
 
-    it('includes playlist_id filter when refreshing playlist tracks', async () => {
+    it('reloads the list even when the song refresh fails', async () => {
+      getOne.mockImplementation(() => Promise.reject(new Error('boom')))
       const record = {
-        id: 'pt-5',
+        id: '5',
         mediaFileId: 'sg-10',
         playlistId: 'pl-123',
         rating: 1,
@@ -92,16 +100,8 @@ describe('useRating', () => {
         await result.current[0](3, 'sg-10')
       })
 
-      // Should rate using the media file ID
       expect(subsonic.setRating).toHaveBeenCalledWith('sg-10', 3)
-
-      // Should refresh playlist track with correct playlist_id filter
-      expect(getOne).toHaveBeenCalledWith('playlistTrack', {
-        id: 'pt-5',
-        filter: { playlist_id: 'pl-123' },
-      })
-      // Should also refresh the underlying song
-      expect(getOne).toHaveBeenCalledWith('song', { id: 'sg-10' })
+      expect(mockRefresh).toHaveBeenCalled()
     })
 
     it('only refreshes original resource when no mediaFileId present', async () => {
@@ -111,9 +111,10 @@ describe('useRating', () => {
         await result.current[0](2, 'sg-1')
       })
 
-      // Should only refresh the original resource (song)
+      // Should only refresh the original resource (song), without reloading the list
       expect(getOne).toHaveBeenCalledTimes(1)
       expect(getOne).toHaveBeenCalledWith('song', { id: 'sg-1' })
+      expect(mockRefresh).not.toHaveBeenCalled()
     })
 
     it('does not include playlist_id filter for non-playlist resources', async () => {
diff --git a/ui/src/common/useToggleLove.jsx b/ui/src/common/useToggleLove.jsx
index 3f98a2e21..22468cbe1 100644
--- a/ui/src/common/useToggleLove.jsx
+++ b/ui/src/common/useToggleLove.jsx
@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { useDataProvider, useNotify } from 'react-admin'
+import { useDataProvider, useNotify, useRefresh } from 'react-admin'
 import subsonic from '../subsonic'
 
 export const useToggleLove = (resource, record = {}) => {
@@ -15,33 +15,32 @@ export const useToggleLove = (resource, record = {}) => {
   }, [])
 
   const dataProvider = useDataProvider()
+  const refresh = useRefresh()
 
   const refreshRecord = useCallback(() => {
-    const promises = []
+    // A playlistTrack id is a position, not a stable key: loving a song can drop it out of
+    // a smart playlist, and that position then holds a different track. Refetching the row
+    // by id would write the neighbour's data under this row, so reload the list instead.
+    const isPlaylistTrack = !!record.mediaFileId
+    const target = isPlaylistTrack
+      ? { resource: 'song', params: { id: record.mediaFileId } }
+      : { resource, params: { id: record.id } }
 
-    // Always refresh the original resource
-    const params = { id: record.id }
-    if (record.playlistId) {
-      params.filter = { playlist_id: record.playlistId }
-    }
-    promises.push(dataProvider.getOne(resource, params))
-
-    // If we have a mediaFileId, also refresh the song
-    if (record.mediaFileId) {
-      promises.push(dataProvider.getOne('song', { id: record.mediaFileId }))
-    }
-
-    Promise.all(promises)
+    dataProvider
+      .getOne(target.resource, target.params)
       .catch((e) => {
         // eslint-disable-next-line no-console
         console.log('Error encountered: ' + e)
       })
       .finally(() => {
+        if (isPlaylistTrack) {
+          refresh()
+        }
         if (mountedRef.current) {
           setLoading(false)
         }
       })
-  }, [dataProvider, record.mediaFileId, record.id, record.playlistId, resource])
+  }, [dataProvider, record.mediaFileId, record.id, refresh, resource])
 
   const toggleLove = () => {
     const toggle = record.starred ? subsonic.unstar : subsonic.star
diff --git a/ui/src/common/useToggleLove.test.js b/ui/src/common/useToggleLove.test.js
index 640e9ff89..10db1b3c3 100644
--- a/ui/src/common/useToggleLove.test.js
+++ b/ui/src/common/useToggleLove.test.js
@@ -4,6 +4,8 @@ import { useToggleLove } from './useToggleLove'
 import subsonic from '../subsonic'
 import { useDataProvider } from 'react-admin'
 
+const mockRefresh = vi.fn()
+
 vi.mock('../subsonic', () => ({
   default: {
     star: vi.fn(() => Promise.resolve()),
@@ -17,6 +19,7 @@ vi.mock('react-admin', async () => {
     ...actual,
     useDataProvider: vi.fn(),
     useNotify: vi.fn(() => vi.fn()),
+    useRefresh: vi.fn(() => mockRefresh),
   }
 })
 
@@ -58,9 +61,9 @@ describe('useToggleLove', () => {
   })
 
   describe('playlist track scenarios', () => {
-    it('refreshes both playlist track and song for playlist tracks', async () => {
+    it('refreshes the song and reloads the list for playlist tracks', async () => {
       const record = {
-        id: 'pt-1',
+        id: '1',
         mediaFileId: 'sg-1',
         playlistId: 'pl-1',
         starred: false,
@@ -75,18 +78,21 @@ describe('useToggleLove', () => {
       // Should star using the media file ID
       expect(subsonic.star).toHaveBeenCalledWith('sg-1')
 
-      // Should refresh both the playlist track and the song
-      expect(getOne).toHaveBeenCalledTimes(2)
-      expect(getOne).toHaveBeenCalledWith('playlistTrack', {
-        id: 'pt-1',
-        filter: { playlist_id: 'pl-1' },
-      })
+      // The row is a position in the playlist, so it cannot be refetched by id:
+      // loving can drop the track out of a smart playlist and shift every row up
+      expect(getOne).toHaveBeenCalledTimes(1)
       expect(getOne).toHaveBeenCalledWith('song', { id: 'sg-1' })
+      expect(getOne).not.toHaveBeenCalledWith(
+        'playlistTrack',
+        expect.anything(),
+      )
+      expect(mockRefresh).toHaveBeenCalled()
     })
 
-    it('includes playlist_id filter when refreshing playlist tracks', async () => {
+    it('reloads the list even when the song refresh fails', async () => {
+      getOne.mockImplementation(() => Promise.reject(new Error('boom')))
       const record = {
-        id: 'pt-5',
+        id: '5',
         mediaFileId: 'sg-10',
         playlistId: 'pl-123',
         starred: true,
@@ -98,16 +104,8 @@ describe('useToggleLove', () => {
         await result.current[0]()
       })
 
-      // Should unstar using the media file ID
       expect(subsonic.unstar).toHaveBeenCalledWith('sg-10')
-
-      // Should refresh playlist track with correct playlist_id filter
-      expect(getOne).toHaveBeenCalledWith('playlistTrack', {
-        id: 'pt-5',
-        filter: { playlist_id: 'pl-123' },
-      })
-      // Should also refresh the underlying song
-      expect(getOne).toHaveBeenCalledWith('song', { id: 'sg-10' })
+      expect(mockRefresh).toHaveBeenCalled()
     })
 
     it('only refreshes original resource when no mediaFileId present', async () => {
@@ -117,9 +115,10 @@ describe('useToggleLove', () => {
         await result.current[0]()
       })
 
-      // Should only refresh the original resource (song)
+      // Should only refresh the original resource (song), without reloading the list
       expect(getOne).toHaveBeenCalledTimes(1)
       expect(getOne).toHaveBeenCalledWith('song', { id: 'sg-1' })
+      expect(mockRefresh).not.toHaveBeenCalled()
     })
 
     it('does not include playlist_id filter for non-playlist resources', async () => {

From afb3a2f881a245c28cc7b65888f51ea1a2cbbb3b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 2 Sep 2026 23:29:31 -0400
Subject: [PATCH 106/200] feat(ui): add Refresh Metadata action to the album
 and artist pages (#6078)

The Refresh Metadata action was only reachable from the Album and Artist context menus, so it could not be triggered from AlbumShow or ArtistShow. This adds an icon-only button, with a tooltip, to the action toolbar on both detail pages. Like the menu entry, it is only rendered for admins.

The button is built on react-admin's Button rather than a plain IconButton: the surrounding toolbars use the former, so the theme colour and the icon-only swap at the xs breakpoint are inherited instead of restated. The dataProvider call and its two notifications move into a new useRefreshMetadata hook, which ContextMenus now shares, keeping a single copy of that logic.
---
 ui/src/album/AlbumActions.jsx                |   7 +-
 ui/src/album/AlbumActions.test.jsx           |  68 ++++++++++++
 ui/src/artist/ArtistActions.jsx              |   7 ++
 ui/src/artist/ArtistActions.test.jsx         |  32 +++++-
 ui/src/common/ContextMenus.jsx               |   8 +-
 ui/src/common/RefreshMetadataButton.jsx      |  62 +++++++++++
 ui/src/common/RefreshMetadataButton.test.jsx | 104 +++++++++++++++++++
 ui/src/common/index.js                       |   2 +
 ui/src/common/useRefreshMetadata.js          |  16 +++
 9 files changed, 298 insertions(+), 8 deletions(-)
 create mode 100644 ui/src/album/AlbumActions.test.jsx
 create mode 100644 ui/src/common/RefreshMetadataButton.jsx
 create mode 100644 ui/src/common/RefreshMetadataButton.test.jsx
 create mode 100644 ui/src/common/useRefreshMetadata.js

diff --git a/ui/src/album/AlbumActions.jsx b/ui/src/album/AlbumActions.jsx
index 96cfab09a..c3b3a4bc2 100644
--- a/ui/src/album/AlbumActions.jsx
+++ b/ui/src/album/AlbumActions.jsx
@@ -27,7 +27,7 @@ import {
 } from '../actions'
 import { formatBytes } from '../utils'
 import config from '../config'
-import { ToggleFieldsMenu } from '../common'
+import { RefreshMetadataButton, ToggleFieldsMenu } from '../common'
 
 const useStyles = makeStyles({
   toolbar: { display: 'flex', justifyContent: 'space-between', width: '100%' },
@@ -138,6 +138,11 @@ const AlbumActions = ({
               <CloudDownloadOutlinedIcon />
             </AlbumButton>
           )}
+          <RefreshMetadataButton
+            resource="album"
+            record={record}
+            size="small"
+          />
         </div>
         <div>{isNotSmall && <ToggleFieldsMenu resource="albumSong" />}</div>
       </div>
diff --git a/ui/src/album/AlbumActions.test.jsx b/ui/src/album/AlbumActions.test.jsx
new file mode 100644
index 000000000..246a15558
--- /dev/null
+++ b/ui/src/album/AlbumActions.test.jsx
@@ -0,0 +1,68 @@
+import React from 'react'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { ThemeProvider, createTheme } from '@material-ui/core/styles'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import AlbumActions from './AlbumActions'
+
+const { mockConfig, mockPermissions } = vi.hoisted(() => ({
+  mockConfig: {
+    enableSharing: false,
+    enableDownloads: false,
+    losslessFormats: 'FLAC,WAV',
+  },
+  mockPermissions: { value: 'admin' },
+}))
+vi.mock('../config', () => ({ default: mockConfig }))
+
+vi.mock('react-redux', () => ({
+  useDispatch: () => vi.fn(),
+  useSelector: () => ({}),
+}))
+
+const mockRefreshMetadata = vi.fn()
+
+vi.mock('react-admin', async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    useNotify: () => vi.fn(),
+    useDataProvider: () => ({ refreshMetadata: mockRefreshMetadata }),
+    usePermissions: () => ({ permissions: mockPermissions.value }),
+    useTranslate: () => (x) => x,
+  }
+})
+
+describe('AlbumActions', () => {
+  const record = { id: 'al1', name: 'Album', size: 1024 }
+  const refreshLabel = 'resources.album.actions.refresh'
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockPermissions.value = 'admin'
+    mockRefreshMetadata.mockResolvedValue({ data: { id: 'al1' } })
+  })
+
+  const renderAlbumActions = () =>
+    render(
+      <ThemeProvider theme={createTheme()}>
+        <AlbumActions record={record} ids={[]} data={{}} />
+      </ThemeProvider>,
+    )
+
+  it('refreshes the album metadata for admins', async () => {
+    renderAlbumActions()
+    fireEvent.click(screen.getByRole('button', { name: refreshLabel }))
+
+    await waitFor(() =>
+      expect(mockRefreshMetadata).toHaveBeenCalledWith('album', 'al1'),
+    )
+  })
+
+  it('hides the action for non-admin users', () => {
+    mockPermissions.value = 'regular'
+    renderAlbumActions()
+    expect(
+      screen.queryByRole('button', { name: refreshLabel }),
+    ).not.toBeInTheDocument()
+  })
+})
diff --git a/ui/src/artist/ArtistActions.jsx b/ui/src/artist/ArtistActions.jsx
index 2f329a034..c2614c05a 100644
--- a/ui/src/artist/ArtistActions.jsx
+++ b/ui/src/artist/ArtistActions.jsx
@@ -26,6 +26,7 @@ import {
 import config from '../config'
 import { formatBytes } from '../utils'
 import { artistDownloadSize } from '../common/artist'
+import { RefreshMetadataButton } from '../common/RefreshMetadataButton'
 
 const useStyles = makeStyles((theme) => ({
   toolbar: {
@@ -33,6 +34,7 @@ const useStyles = makeStyles((theme) => ({
     padding: '0 !important',
     background: 'transparent',
     boxShadow: 'none',
+    alignItems: 'center',
     '& .MuiToolbar-root': {
       minHeight: 'auto',
       padding: '0 !important',
@@ -174,6 +176,11 @@ const ArtistActions = ({ className, record, ...rest }) => {
           icon={<CloudDownloadOutlinedIcon />}
         />
       )}
+      <RefreshMetadataButton
+        resource="artist"
+        record={record}
+        size={isMobile ? 'small' : 'medium'}
+      />
     </TopToolbar>
   )
 }
diff --git a/ui/src/artist/ArtistActions.test.jsx b/ui/src/artist/ArtistActions.test.jsx
index ad25177b3..05f53f835 100644
--- a/ui/src/artist/ArtistActions.test.jsx
+++ b/ui/src/artist/ArtistActions.test.jsx
@@ -18,20 +18,26 @@ vi.mock('../subsonic', () => ({
   default: { getSimilarSongs2: vi.fn(), getTopSongs: vi.fn() },
 }))
 
-const { mockConfig } = vi.hoisted(() => ({
+const { mockConfig, mockPermissions } = vi.hoisted(() => ({
   mockConfig: { enableSharing: true, enableDownloads: true },
+  mockPermissions: { value: 'admin' },
 }))
 vi.mock('../config', () => ({ default: mockConfig }))
 
 const mockNotify = vi.fn()
 const mockGetList = vi.fn().mockResolvedValue({ data: [{ id: 's1' }] })
+const mockRefreshMetadata = vi.fn().mockResolvedValue({ data: { id: 'ar1' } })
 
 vi.mock('react-admin', async (importOriginal) => {
   const actual = await importOriginal()
   return {
     ...actual,
     useNotify: () => mockNotify,
-    useDataProvider: () => ({ getList: mockGetList }),
+    useDataProvider: () => ({
+      getList: mockGetList,
+      refreshMetadata: mockRefreshMetadata,
+    }),
+    usePermissions: () => ({ permissions: mockPermissions.value }),
     useTranslate: () => (x) => x,
   }
 })
@@ -64,6 +70,7 @@ describe('ArtistActions', () => {
     vi.spyOn(console, 'error').mockImplementation(() => {})
     mockConfig.enableSharing = true
     mockConfig.enableDownloads = true
+    mockPermissions.value = 'admin'
 
     const songWithReplayGain = {
       id: 'rec1',
@@ -290,4 +297,25 @@ describe('ArtistActions', () => {
       expect(screen.queryByText(/ra\.action\.download/)).not.toBeInTheDocument()
     })
   })
+
+  describe('Refresh metadata action', () => {
+    const refreshLabel = 'resources.album.actions.refresh'
+
+    it('refreshes the artist metadata for admins', async () => {
+      renderArtistActions()
+      fireEvent.click(screen.getByRole('button', { name: refreshLabel }))
+
+      await waitFor(() =>
+        expect(mockRefreshMetadata).toHaveBeenCalledWith('artist', 'ar1'),
+      )
+    })
+
+    it('hides the action for non-admin users', () => {
+      mockPermissions.value = 'regular'
+      renderArtistActions()
+      expect(
+        screen.queryByRole('button', { name: refreshLabel }),
+      ).not.toBeInTheDocument()
+    })
+  })
 })
diff --git a/ui/src/common/ContextMenus.jsx b/ui/src/common/ContextMenus.jsx
index 606506459..4407392c1 100644
--- a/ui/src/common/ContextMenus.jsx
+++ b/ui/src/common/ContextMenus.jsx
@@ -30,6 +30,7 @@ import { LoveButton } from './LoveButton'
 import config from '../config'
 import { formatBytes } from '../utils'
 import { artistDownloadSize } from './artist'
+import { useRefreshMetadata } from './useRefreshMetadata'
 
 const useStyles = makeStyles({
   noWrap: {
@@ -75,6 +76,7 @@ const ContextMenu = ({
   const translate = useTranslate()
   const notify = useNotify()
   const { permissions } = usePermissions()
+  const refreshMetadata = useRefreshMetadata()
   const [anchorEl, setAnchorEl] = useState(null)
 
   const isArtist = resource === 'artist'
@@ -139,11 +141,7 @@ const ContextMenu = ({
       enabled: permissions === 'admin',
       needData: false,
       label: translate('resources.album.actions.refresh'),
-      action: (record) =>
-        dataProvider
-          .refreshMetadata(resource, record.id)
-          .then(() => notify('message.metadataRefreshStarted'))
-          .catch(() => notify('ra.page.error', 'warning')),
+      action: (record) => refreshMetadata(resource, record.id),
     },
     ...(!hideInfo && {
       info: {
diff --git a/ui/src/common/RefreshMetadataButton.jsx b/ui/src/common/RefreshMetadataButton.jsx
new file mode 100644
index 000000000..aa0533ade
--- /dev/null
+++ b/ui/src/common/RefreshMetadataButton.jsx
@@ -0,0 +1,62 @@
+import React, { useCallback } from 'react'
+import PropTypes from 'prop-types'
+import Tooltip from '@material-ui/core/Tooltip'
+import { makeStyles } from '@material-ui/core/styles'
+import { Button, usePermissions, useTranslate } from 'react-admin'
+import { MdRefresh } from 'react-icons/md'
+import { useRefreshMetadata } from './useRefreshMetadata'
+
+const useStyles = makeStyles({
+  // Tooltip needs a ref-holding child, and react-admin's Button does not forward one.
+  wrapper: { display: 'inline-flex', verticalAlign: 'middle' },
+  button: { minWidth: 'auto' },
+})
+
+// react-admin's Button, not an IconButton: the toolbars use it, so colour and the icon-only swap
+// at xs match without restating either rule.
+export const RefreshMetadataButton = ({
+  resource,
+  record,
+  className,
+  size,
+}) => {
+  const translate = useTranslate()
+  const { permissions } = usePermissions()
+  const refreshMetadata = useRefreshMetadata()
+  const classes = useStyles()
+
+  const handleClick = useCallback(
+    () => refreshMetadata(resource, record?.id),
+    [refreshMetadata, resource, record],
+  )
+
+  if (permissions !== 'admin' || !record?.id) return null
+
+  const label = translate('resources.album.actions.refresh')
+  return (
+    <Tooltip title={label}>
+      <span className={classes.wrapper}>
+        <Button
+          aria-label={label}
+          className={className}
+          classes={{ button: classes.button }}
+          size={size}
+          onClick={handleClick}
+        >
+          <MdRefresh />
+        </Button>
+      </span>
+    </Tooltip>
+  )
+}
+
+RefreshMetadataButton.propTypes = {
+  resource: PropTypes.oneOf(['album', 'artist']).isRequired,
+  record: PropTypes.object,
+  className: PropTypes.string,
+  size: PropTypes.oneOf(['small', 'medium']),
+}
+
+RefreshMetadataButton.defaultProps = {
+  size: 'small',
+}
diff --git a/ui/src/common/RefreshMetadataButton.test.jsx b/ui/src/common/RefreshMetadataButton.test.jsx
new file mode 100644
index 000000000..7bda0497c
--- /dev/null
+++ b/ui/src/common/RefreshMetadataButton.test.jsx
@@ -0,0 +1,104 @@
+import React from 'react'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { ThemeProvider, createTheme } from '@material-ui/core/styles'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { RefreshMetadataButton } from './RefreshMetadataButton'
+
+const mockNotify = vi.fn()
+const mockRefreshMetadata = vi.fn()
+const { mockPermissions } = vi.hoisted(() => ({
+  mockPermissions: { value: 'admin' },
+}))
+
+vi.mock('react-admin', async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    useNotify: () => mockNotify,
+    useDataProvider: () => ({ refreshMetadata: mockRefreshMetadata }),
+    usePermissions: () => ({ permissions: mockPermissions.value }),
+    useTranslate: () => (x) => x,
+  }
+})
+
+describe('RefreshMetadataButton', () => {
+  const record = { id: 'al-1', name: 'Album' }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockPermissions.value = 'admin'
+    mockRefreshMetadata.mockResolvedValue({ data: { id: 'al-1' } })
+  })
+
+  const renderButton = (props = {}) =>
+    render(
+      <ThemeProvider theme={createTheme()}>
+        <RefreshMetadataButton resource="album" record={record} {...props} />
+      </ThemeProvider>,
+    )
+
+  it('renders an icon-only button labelled by the refresh action', () => {
+    renderButton()
+    const button = screen.getByRole('button', {
+      name: 'resources.album.actions.refresh',
+    })
+    expect(button).toBeInTheDocument()
+    expect(button).toHaveTextContent('')
+  })
+
+  it('shows the label as a tooltip on hover', async () => {
+    renderButton()
+    fireEvent.mouseOver(
+      screen.getByRole('button', {
+        name: 'resources.album.actions.refresh',
+      }),
+    )
+    await waitFor(() =>
+      expect(screen.getByRole('tooltip')).toHaveTextContent(
+        'resources.album.actions.refresh',
+      ),
+    )
+  })
+
+  it('renders nothing for non-admin users', () => {
+    mockPermissions.value = 'regular'
+    const { container } = renderButton()
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders nothing without a record', () => {
+    const { container } = renderButton({ record: undefined })
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('requests a refresh for the record and notifies success', async () => {
+    renderButton()
+    fireEvent.click(screen.getByRole('button'))
+
+    await waitFor(() =>
+      expect(mockRefreshMetadata).toHaveBeenCalledWith('album', 'al-1'),
+    )
+    await waitFor(() =>
+      expect(mockNotify).toHaveBeenCalledWith('message.metadataRefreshStarted'),
+    )
+  })
+
+  it('passes the artist resource through', async () => {
+    renderButton({ resource: 'artist', record: { id: 'ar-1' } })
+    fireEvent.click(screen.getByRole('button'))
+
+    await waitFor(() =>
+      expect(mockRefreshMetadata).toHaveBeenCalledWith('artist', 'ar-1'),
+    )
+  })
+
+  it('notifies a warning when the request fails', async () => {
+    mockRefreshMetadata.mockRejectedValue(new Error('boom'))
+    renderButton()
+    fireEvent.click(screen.getByRole('button'))
+
+    await waitFor(() =>
+      expect(mockNotify).toHaveBeenCalledWith('ra.page.error', 'warning'),
+    )
+  })
+})
diff --git a/ui/src/common/index.js b/ui/src/common/index.js
index 047f5b3cf..0177df326 100644
--- a/ui/src/common/index.js
+++ b/ui/src/common/index.js
@@ -36,6 +36,8 @@ export * from './useTraceUpdate'
 export * from './Writable'
 export * from './SongSimpleList'
 export * from './RatingField'
+export * from './RefreshMetadataButton'
+export * from './useRefreshMetadata'
 export * from './useRating'
 export * from './useSelectedFields'
 export * from './ToggleFieldsMenu'
diff --git a/ui/src/common/useRefreshMetadata.js b/ui/src/common/useRefreshMetadata.js
new file mode 100644
index 000000000..d34042919
--- /dev/null
+++ b/ui/src/common/useRefreshMetadata.js
@@ -0,0 +1,16 @@
+import { useCallback } from 'react'
+import { useDataProvider, useNotify } from 'react-admin'
+
+export const useRefreshMetadata = () => {
+  const dataProvider = useDataProvider()
+  const notify = useNotify()
+
+  return useCallback(
+    (resource, id) =>
+      dataProvider
+        .refreshMetadata(resource, id)
+        .then(() => notify('message.metadataRefreshStarted'))
+        .catch(() => notify('ra.page.error', 'warning')),
+    [dataProvider, notify],
+  )
+}

From a7365e119b4b2fdc3debbff7d8d801c3417f2824 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 3 Sep 2026 16:07:53 -0400
Subject: [PATCH 107/200] fix(subsonic): update the playlist `changed`
 timestamp when renaming a smart playlist (#6082)

`buildPlaylist` reported `evaluated_at` as `changed` for smart playlists, so a
rename or comment edit was invisible to clients until the next evaluation. A
never-evaluated smart playlist also reported the current time on every call,
which never settled.

Report `updated_at` for every playlist. `refreshCounters` now syncs the stamp it
writes back onto the model, and `refreshSmartPlaylist` reuses it for
`evaluated_at`. `changed` therefore still equals the evaluation time for a
just-evaluated playlist, and `validUntil` stays anchored to it.

Original Subsonic always bumps `changed` on any playlist update, so this also
aligns the behavior with upstream.
---
 persistence/playlist_repository.go            |  4 +++-
 persistence/smart_playlist_repository.go      |  3 ++-
 persistence/smart_playlist_repository_test.go | 17 +++++++++++++++++
 server/subsonic/playlists.go                  | 11 +----------
 server/subsonic/playlists_test.go             | 19 +++++++++++++++++--
 5 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/persistence/playlist_repository.go b/persistence/playlist_repository.go
index bf8d6d5a8..bc6bffd25 100644
--- a/persistence/playlist_repository.go
+++ b/persistence/playlist_repository.go
@@ -316,11 +316,12 @@ func (r *playlistRepository) refreshCounters(pls *model.Playlist) error {
 	}
 
 	// Update playlist's total duration, size and count
+	now := time.Now()
 	upd := Update("playlist").
 		Set("duration", res.Duration).
 		Set("size", res.Size).
 		Set("song_count", res.Count).
-		Set("updated_at", time.Now()).
+		Set("updated_at", now).
 		Where(Eq{"id": pls.ID})
 	_, err = r.executeSQL(upd)
 	if err != nil {
@@ -329,6 +330,7 @@ func (r *playlistRepository) refreshCounters(pls *model.Playlist) error {
 	pls.SongCount = int(res.Count)
 	pls.Duration = res.Duration
 	pls.Size = int64(res.Size)
+	pls.UpdatedAt = now
 	return nil
 }
 
diff --git a/persistence/smart_playlist_repository.go b/persistence/smart_playlist_repository.go
index 65ae4656b..9d2ac9590 100644
--- a/persistence/smart_playlist_repository.go
+++ b/persistence/smart_playlist_repository.go
@@ -58,7 +58,8 @@ func (r *playlistRepository) refreshSmartPlaylist(pls *model.Playlist) bool {
 		return false
 	}
 
-	now := time.Now()
+	// Reuse the stamp refreshCounters just wrote, so evaluated_at and updated_at agree
+	now := pls.UpdatedAt
 	updSql := Update(r.tableName).Set("evaluated_at", now).Where(Eq{"id": pls.ID})
 	if _, err = r.executeSQL(updSql); err != nil {
 		log.Error(r.ctx, "Error updating smart playlist", "playlist", pls.Name, "id", pls.ID, err)
diff --git a/persistence/smart_playlist_repository_test.go b/persistence/smart_playlist_repository_test.go
index ddc155fab..6f8684d5c 100644
--- a/persistence/smart_playlist_repository_test.go
+++ b/persistence/smart_playlist_repository_test.go
@@ -45,6 +45,23 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 			})
 		})
 
+		Context("after an evaluation", func() {
+			It("stamps updated_at and evaluated_at with the same instant", func() {
+				newPls := model.Playlist{Name: "Evaluated", OwnerID: "userid", Rules: rules}
+				Expect(repo.Put(&newPls)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+
+				refreshed, err := repo.GetWithTracks(newPls.ID, true, false)
+				Expect(err).ToNot(HaveOccurred())
+
+				stored, err := repo.Get(newPls.ID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(stored.EvaluatedAt).ToNot(BeNil())
+				Expect(stored.UpdatedAt).To(BeTemporally("==", *stored.EvaluatedAt))
+				Expect(refreshed.UpdatedAt).To(BeTemporally("==", stored.UpdatedAt))
+			})
+		})
+
 		Context("invalid rules", func() {
 			It("fails to Put it in the DB", func() {
 				rules = &criteria.Criteria{
diff --git a/server/subsonic/playlists.go b/server/subsonic/playlists.go
index 774a9c430..e64fc9e82 100644
--- a/server/subsonic/playlists.go
+++ b/server/subsonic/playlists.go
@@ -5,7 +5,6 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
-	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
@@ -133,15 +132,7 @@ func (api *Router) buildPlaylist(ctx context.Context, p model.Playlist) response
 	pls.SongCount = int32(p.SongCount)
 	pls.Duration = int32(p.Duration)
 	pls.Created = p.CreatedAt
-	if p.IsSmartPlaylist() {
-		if p.EvaluatedAt != nil {
-			pls.Changed = *p.EvaluatedAt
-		} else {
-			pls.Changed = time.Now()
-		}
-	} else {
-		pls.Changed = p.UpdatedAt
-	}
+	pls.Changed = p.UpdatedAt
 
 	player, ok := request.PlayerFrom(ctx)
 	if ok && isClientInList(conf.Server.Subsonic.MinimalClients, player.Client) {
diff --git a/server/subsonic/playlists_test.go b/server/subsonic/playlists_test.go
index f18f33b47..c7775c0fa 100644
--- a/server/subsonic/playlists_test.go
+++ b/server/subsonic/playlists_test.go
@@ -220,7 +220,7 @@ var _ = Describe("buildPlaylist", func() {
 				Expect(result.SongCount).To(Equal(int32(10)))
 				Expect(result.Duration).To(Equal(int32(600)))
 				Expect(result.Created).To(Equal(playlist.CreatedAt))
-				Expect(result.Changed).To(Equal(evaluatedAt))
+				Expect(result.Changed).To(Equal(playlist.UpdatedAt))
 
 				// These should not be set
 				Expect(result.Comment).To(BeEmpty())
@@ -245,7 +245,7 @@ var _ = Describe("buildPlaylist", func() {
 				Expect(result.SongCount).To(Equal(int32(10)))
 				Expect(result.Duration).To(Equal(int32(600)))
 				Expect(result.Created).To(Equal(playlist.CreatedAt))
-				Expect(result.Changed).To(Equal(*playlist.EvaluatedAt))
+				Expect(result.Changed).To(Equal(playlist.UpdatedAt))
 				Expect(result.Comment).To(Equal("Test comment"))
 				Expect(result.Owner).To(Equal("admin"))
 				Expect(result.Public).To(BeTrue())
@@ -271,6 +271,21 @@ var _ = Describe("buildPlaylist", func() {
 			})
 		})
 
+		Context("when it was never evaluated", func() {
+			BeforeEach(func() {
+				playlist.EvaluatedAt = nil
+				player := model.Player{Client: "regular-client"}
+				ctx = request.WithPlayer(ctx, player)
+			})
+
+			It("omits validUntil but still reports changed", func() {
+				result := router.buildPlaylist(ctx, playlist)
+
+				Expect(result.ValidUntil).To(BeNil())
+				Expect(result.Changed).To(Equal(playlist.UpdatedAt))
+			})
+		})
+
 		Context("with a per-playlist refreshDelay", func() {
 			BeforeEach(func() {
 				playlist.Rules.RefreshDelay = 24 * time.Hour

From 330da83efff42e67d5f065ae052a31adcb6bb15e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 5 Sep 2026 13:52:07 -0400
Subject: [PATCH 108/200] chore(deps): bump TagLib to 2.3.2 (#6088)

See https://github.com/taglib/taglib/releases/tag/v2.3.2
---
 go.mod | 2 +-
 go.sum | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/go.mod b/go.mod
index cdf8fc699..4339b9c55 100644
--- a/go.mod
+++ b/go.mod
@@ -3,7 +3,7 @@ module github.com/navidrome/navidrome
 go 1.27
 
 // Fork to implement raw tags support
-replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3
+replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260905051825-df1d035571df
 
 require (
 	github.com/Masterminds/squirrel v1.5.4
diff --git a/go.sum b/go.sum
index d852285f1..71d9facfd 100644
--- a/go.sum
+++ b/go.sum
@@ -29,8 +29,8 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
-github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3 h1:j7eSXqgtjhlNfwnMEzRdXnJGZTEw4I7J9TeQAll83bU=
-github.com/deluan/go-taglib v0.0.0-20260720134629-a133b9719ea3/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
+github.com/deluan/go-taglib v0.0.0-20260905051825-df1d035571df h1:LdLQVAWVc6hCzqnrfVIEXOhP+r0iSit+EvsXwZDyL70=
+github.com/deluan/go-taglib v0.0.0-20260905051825-df1d035571df/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcHCKTtwzrd0HGfEmoODFA/qnk4=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf/go.mod h1:tSgDythFsl0QgS/PFWfIZqcJKnkADWneY80jaVRlqK8=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55 h1:wSCnggTs2f2ji6nFwQmfwgINcmSMj0xF0oHnoyRSPe4=

From 546302576ab7d19109bc651fd136f595d4e1e92f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 5 Sep 2026 21:44:03 -0400
Subject: [PATCH 109/200] fix(jellyfin): emit TranscodingUrl without the
 /jellyfin base path (#6089)

PlaybackInfo returned a TranscodingUrl prefixed with the /jellyfin mount path.
Clients concatenate that value onto a server base URL that already carries the
prefix, producing /jellyfin/jellyfin/Audio/{id}/universal and a 404, so playback
never started. Jellify, jellyfin-web, jellyfin-vue and Streamyfin all consume the
field this way; real Jellyfin emits it server-relative (StreamInfo.ToUrl is called
with a nil baseUrl).

Emit the path server-relative to match. Finamp is unaffected: it builds its own
stream URLs and never reads the field.
---
 server/jellyfin/e2e/streaming_test.go | 12 +++++-------
 server/jellyfin/stream.go             |  9 +++------
 2 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/server/jellyfin/e2e/streaming_test.go b/server/jellyfin/e2e/streaming_test.go
index 954981910..67208aed3 100644
--- a/server/jellyfin/e2e/streaming_test.go
+++ b/server/jellyfin/e2e/streaming_test.go
@@ -113,14 +113,12 @@ var _ = Describe("Streaming", func() {
 			var info dto.PlaybackInfoResponse
 			parseInto(get("/Items/"+enc(id)+"/PlaybackInfo"), &info)
 			streamURL := info.MediaSources[0].TranscodingUrl
-			// The URL includes the /jellyfin mount prefix so a client resolving it as an absolute
-			// host path hits the mounted router.
-			Expect(streamURL).To(HavePrefix(consts.URLPathJellyfinAPI + "/Audio/" + enc(id) + "/universal"))
+			// Server-relative: clients append it to a base URL already carrying /jellyfin.
+			Expect(streamURL).To(HavePrefix("/Audio/" + enc(id) + "/universal"))
+			Expect(streamURL).ToNot(HavePrefix(consts.URLPathJellyfinAPI))
 			Expect(streamURL).To(ContainSubstring("api_key="))
-			// The embedded api_key alone must authenticate the stream — no auth header sent. The e2e
-			// router is mounted at the root, so strip the /jellyfin prefix before replaying.
-			replayURL := strings.TrimPrefix(streamURL, consts.URLPathJellyfinAPI)
-			w := rawReq("GET", replayURL, "")
+			// The embedded api_key alone must authenticate the stream — no auth header sent.
+			w := rawReq("GET", streamURL, "")
 			Expect(w.Code).To(Equal(http.StatusOK))
 			Expect(streamerSpy.LastMediaFile.ID).To(Equal(id))
 		})
diff --git a/server/jellyfin/stream.go b/server/jellyfin/stream.go
index 86746f89a..87660056c 100644
--- a/server/jellyfin/stream.go
+++ b/server/jellyfin/stream.go
@@ -10,7 +10,6 @@ import (
 	"strings"
 
 	"github.com/go-chi/chi/v5"
-	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -57,13 +56,11 @@ func (api *Router) getPlaybackInfo(w http.ResponseWriter, r *http.Request) {
 			})
 		}
 	}
-	// Embed the caller's token in the stream URL: Jellify's native player fetches TranscodingUrl
-	// verbatim without an auth header, so a non-self-authenticating URL would 401. Direct-play clients
-	// (Finamp) build their own /File?ApiKey URL and ignore this. Include the /jellyfin mount prefix so
-	// a client resolving it as an absolute host path still hits the mounted router.
+	// Self-authenticating: native players fetch this without an auth header. Server-relative:
+	// clients append it to a base URL already carrying /jellyfin.
 	if token := tokenFromRequest(r); token != "" {
 		src.TranscodingSubProtocol = "http"
-		src.TranscodingUrl = consts.URLPathJellyfinAPI + "/Audio/" + src.Id + "/universal?static=true&api_key=" + url.QueryEscape(token)
+		src.TranscodingUrl = "/Audio/" + src.Id + "/universal?static=true&api_key=" + url.QueryEscape(token)
 	}
 	api.ok(w, r, dto.PlaybackInfoResponse{MediaSources: []dto.MediaSourceInfo{src}, PlaySessionId: dto.EncodeID(mf.ID)})
 }

From c534aedd0c3e00579fd90c7adabed4a5fb742935 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 5 Sep 2026 22:57:36 -0400
Subject: [PATCH 110/200] fix(jellyfin): add the /Items/Latest route, and scope
 it by ParentId (#6090)

Jellify's Discover tab calls GET /Items/Latest and got a 404: we only routed the
/Users/{userId}/Items/Latest form, which real Jellyfin marks [Obsolete] and hides
from its OpenAPI spec, so SDK-generated clients never see it. Add the current
route alongside the legacy one, both served by the same handler.

getLatest also ignored ParentId, so browsing a library or an artist returned the
newest albums across everything the user can see. It now scopes to the library
when ParentId names one, and filters to that artist's albums otherwise, which
also makes a stale id return nothing instead of silently widening back to the
full library set. A malformed ParentId 404s, matching /Items and the contract
decodeFilterParam documents.
---
 server/jellyfin/api.go               |  1 +
 server/jellyfin/e2e/browsing_test.go | 37 ++++++++++++++++++++++++++++
 server/jellyfin/items.go             | 13 +++++++++-
 3 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index d64366a63..6484a3bb4 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -118,6 +118,7 @@ func (api *Router) routes() http.Handler {
 			r.Use(throttleStreams(conf.Server.Jellyfin.MaxConcurrentStreams))
 			r.Get("/items", api.getItems)
 			r.Get("/users/{userId}/items", api.getItems)
+			r.Get("/items/latest", api.getLatest)
 			r.Get("/users/{userId}/items/latest", api.getLatest)
 			r.Get("/artists", api.getArtists)
 			r.Get("/artists/albumartists", api.getAlbumArtists)
diff --git a/server/jellyfin/e2e/browsing_test.go b/server/jellyfin/e2e/browsing_test.go
index 004090de6..832b69f25 100644
--- a/server/jellyfin/e2e/browsing_test.go
+++ b/server/jellyfin/e2e/browsing_test.go
@@ -563,6 +563,43 @@ var _ = Describe("Browsing", func() {
 		})
 	})
 
+	Describe("GET /Items/Latest", func() {
+		// Jellyfin marks the /Users/{userId} form obsolete and hides it from the OpenAPI spec, so
+		// SDK-generated clients (Jellify) only ever call this one.
+		It("serves the same response as the legacy /Users/{userId} route", func() {
+			Expect(get("/Items/Latest?Limit=3").Body.String()).
+				To(Equal(get("/Users/admin-1/Items/Latest?Limit=3").Body.String()))
+		})
+
+		It("scopes to ParentId when it names a library", func() {
+			var items []dto.BaseItemDto
+			parseInto(get("/Items/Latest?ParentId="+dto.EncodeLibraryID(1)), &items)
+			Expect(names(items)).To(ConsistOf("Abbey Road", "Help!", "IV", "Kind of Blue", "Singles"))
+		})
+
+		It("scopes to ParentId when it names an artist", func() {
+			var items []dto.BaseItemDto
+			parseInto(get("/Items/Latest?ParentId="+enc(artistID("The Beatles"))), &items)
+			Expect(names(items)).To(ConsistOf("Abbey Road", "Help!"))
+		})
+
+		It("returns nothing for a library the user cannot access", func() {
+			var items []dto.BaseItemDto
+			parseInto(get("/Items/Latest?ParentId="+dto.EncodeLibraryID(99)), &items)
+			Expect(items).To(BeEmpty())
+		})
+
+		It("returns nothing for an id that is neither a library nor an artist", func() {
+			var items []dto.BaseItemDto
+			parseInto(get("/Items/Latest?ParentId="+enc(testID("does-not-exist"))), &items)
+			Expect(items).To(BeEmpty())
+		})
+
+		It("404s a malformed ParentId, like every other filtered endpoint", func() {
+			Expect(get("/Items/Latest?ParentId=not-a-valid-id").Code).To(Equal(http.StatusNotFound))
+		})
+	})
+
 	Describe("GET /Artists and /Genres", func() {
 		It("lists album artists only on /Artists/AlbumArtists (excludes performer-only artists)", func() {
 			names := names(queryResult(get("/Artists/AlbumArtists")).Items)
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index eb5cd2a1a..d16c5e57e 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -938,7 +938,18 @@ func (api *Router) getLatest(w http.ResponseWriter, r *http.Request) {
 	fields := dto.ParseFields(p.Strings("fields")...)
 	opts := filter.AlbumsByNewest()
 	opts.Max = p.IntOr("limit", 20)
-	opts = filter.ApplyLibraryFilter(opts, accessibleLibraryIDs(ctx))
+	parentID, ok := decodeFilterParam(p.StringOr("parentid", ""))
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
+	// A ParentId naming neither a library nor an artist (a stale id, an album) narrows to nothing
+	// rather than widening back to every library.
+	scopeIDs, isLibrary := resolveLibraryScope(ctx, parentID)
+	if parentID != "" && !isLibrary {
+		opts.Filters = squirrel.And{opts.Filters, filter.AlbumsByArtistID(parentID).Filters}
+	}
+	opts = filter.ApplyLibraryFilter(opts, scopeIDs)
 	repo := api.ds.Album(ctx)
 	open := streamCursor(func() (func(func(model.Album, error) bool), error) {
 		return repo.GetCursor(opts)

From 072331078d7ac999b443ebd66eed2c61820b75d9 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sun, 6 Sep 2026 12:39:53 -0400
Subject: [PATCH 111/200] fix(server): update StoreMusicFolder to skip updates
 when path is unchanged

Signed-off-by: Deluan <deluan@navidrome.org>
---
 persistence/library_repository.go      |  7 +++--
 persistence/library_repository_test.go | 42 ++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/persistence/library_repository.go b/persistence/library_repository.go
index df5c9a066..2e8feea7a 100644
--- a/persistence/library_repository.go
+++ b/persistence/library_repository.go
@@ -137,9 +137,10 @@ ON CONFLICT (user_id, library_id) DO NOTHING;`,
 func (r *libraryRepository) StoreMusicFolder() error {
 	sq := Update(r.tableName).Set("path", conf.Server.MusicFolder).
 		Set("updated_at", time.Now()).
-		Where(Eq{"id": model.DefaultLibraryID})
-	_, err := r.executeSQL(sq)
-	if err != nil {
+		Where(Eq{"id": model.DefaultLibraryID}).
+		Where(NotEq{"path": conf.Server.MusicFolder})
+	rowsAffected, err := r.executeSQL(sq)
+	if err == nil && rowsAffected > 0 {
 		libLock.Lock()
 		defer libLock.Unlock()
 		libCache[model.DefaultLibraryID] = conf.Server.MusicFolder
diff --git a/persistence/library_repository_test.go b/persistence/library_repository_test.go
index 949dd93c5..6aede8c4e 100644
--- a/persistence/library_repository_test.go
+++ b/persistence/library_repository_test.go
@@ -5,6 +5,8 @@ import (
 	"time"
 
 	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -139,6 +141,46 @@ var _ = Describe("LibraryRepository", func() {
 		})
 	})
 
+	Describe("StoreMusicFolder", func() {
+		var libBefore *model.Library
+
+		BeforeEach(func() {
+			var err error
+			libBefore, err = repo.Get(model.DefaultLibraryID)
+			Expect(err).ToNot(HaveOccurred())
+
+			DeferCleanup(configtest.SetupConfig())
+			DeferCleanup(func() {
+				_, _ = conn.NewQuery("update library set path = {:path}, updated_at = {:updated_at} where id = {:id}").
+					Bind(dbx.Params{"path": libBefore.Path, "updated_at": libBefore.UpdatedAt, "id": model.DefaultLibraryID}).
+					Execute()
+				libLock.Lock()
+				defer libLock.Unlock()
+				delete(libCache, model.DefaultLibraryID)
+			})
+		})
+
+		It("skips updating the default library when the configured path is unchanged", func() {
+			conf.Server.MusicFolder = libBefore.Path
+			Expect(repo.StoreMusicFolder()).To(Succeed())
+
+			libAfter, err := repo.Get(model.DefaultLibraryID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(libAfter.Path).To(Equal(libBefore.Path))
+			Expect(libAfter.UpdatedAt).To(Equal(libBefore.UpdatedAt))
+		})
+
+		It("updates the default library only when the configured path changes", func() {
+			conf.Server.MusicFolder = libBefore.Path + "-updated"
+			Expect(repo.StoreMusicFolder()).To(Succeed())
+
+			libAfter, err := repo.Get(model.DefaultLibraryID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(libAfter.Path).To(Equal(conf.Server.MusicFolder))
+			Expect(libAfter.UpdatedAt).ToNot(Equal(libBefore.UpdatedAt))
+		})
+	})
+
 	It("refreshes stats", func() {
 		libBefore, err := repo.Get(1)
 		Expect(err).ToNot(HaveOccurred())

From 8568010524f4b44207d8c8c28f55fc079867641f Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sun, 6 Sep 2026 13:08:05 -0400
Subject: [PATCH 112/200] refactor(log): replace sort with slices.SortFunc and
 use atomic for currentLevel

Signed-off-by: Deluan <deluan@navidrome.org>
---
 log/log.go | 40 +++++++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/log/log.go b/log/log.go
index 10cfb17b5..de2f171b2 100644
--- a/log/log.go
+++ b/log/log.go
@@ -1,6 +1,7 @@
 package log
 
 import (
+	"cmp"
 	"context"
 	"errors"
 	"fmt"
@@ -9,9 +10,10 @@ import (
 	"net/http"
 	"os"
 	"runtime"
-	"sort"
+	"slices"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/sirupsen/logrus"
@@ -76,18 +78,19 @@ type levelPath struct {
 }
 
 var (
-	currentLevel  Level
-	loggerMu      sync.RWMutex
-	defaultLogger = logrus.New()
-	logSourceLine = false
-	rootPath      string
-	logLevels     []levelPath
+	currentLevel         atomic.Uint32
+	hasLogLevelOverrides atomic.Bool
+	loggerMu             sync.RWMutex
+	defaultLogger        = logrus.New()
+	logSourceLine        = false
+	rootPath             string
+	logLevels            []levelPath
 )
 
 // SetLevel sets the global log level used by the simple logger.
 func SetLevel(l Level) {
 	loggerMu.Lock()
-	currentLevel = l
+	currentLevel.Store(uint32(l))
 	defaultLogger.Level = logrus.TraceLevel
 	loggerMu.Unlock()
 	logrus.SetLevel(logrus.Level(l))
@@ -126,9 +129,10 @@ func SetLogLevels(levels map[string]string) {
 	for k, v := range levels {
 		logLevels = append(logLevels, levelPath{path: k, level: ParseLogLevel(v)})
 	}
-	sort.Slice(logLevels, func(i, j int) bool {
-		return logLevels[i].path > logLevels[j].path
+	slices.SortFunc(logLevels, func(a, b levelPath) int {
+		return cmp.Compare(b.path, a.path)
 	})
+	hasLogLevelOverrides.Store(len(logLevels) != 0)
 }
 
 func SetLogSourceLine(enabled bool) {
@@ -193,9 +197,7 @@ func SetDefaultLogger(l *logrus.Logger) *logrus.Logger {
 }
 
 func CurrentLevel() Level {
-	loggerMu.RLock()
-	defer loggerMu.RUnlock()
-	return currentLevel
+	return Level(currentLevel.Load())
 }
 
 // IsGreaterOrEqualTo returns true if the caller's current log level is equal or greater than the provided level.
@@ -248,18 +250,18 @@ func Writer() io.Writer {
 }
 
 func shouldLog(requiredLevel Level, skip int) bool {
-	loggerMu.RLock()
-	level := currentLevel
-	levels := logLevels
-	loggerMu.RUnlock()
-
+	level := Level(currentLevel.Load())
 	if level >= requiredLevel {
 		return true
 	}
-	if len(levels) == 0 {
+	if !hasLogLevelOverrides.Load() {
 		return false
 	}
 
+	loggerMu.RLock()
+	levels := logLevels
+	loggerMu.RUnlock()
+
 	_, file, _, ok := runtime.Caller(skip)
 	if !ok {
 		return false

From 8a2135f076dcabe1399147c6c8dfe64a5b383047 Mon Sep 17 00:00:00 2001
From: karigane <169052233+karigane-cha@users.noreply.github.com>
Date: Mon, 7 Sep 2026 02:30:25 +0900
Subject: [PATCH 113/200] fix(i18n): Update Japanese translation (#6080)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(i18n): Update Japanese translation

* fix(i18n): fix Japanese translation

* fix(i18n): fix Japanese translation

Update Japanese translations for `recentlyAdded`, `recentlyPlayed`, and `mostPlayed` in album lists

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 resources/i18n/ja.json | 681 +++++++++++++++++++++++------------------
 1 file changed, 390 insertions(+), 291 deletions(-)

diff --git a/resources/i18n/ja.json b/resources/i18n/ja.json
index 29975b92b..83cd7822b 100644
--- a/resources/i18n/ja.json
+++ b/resources/i18n/ja.json
@@ -5,48 +5,53 @@
       "name": "曲",
       "fields": {
         "albumArtist": "アルバムアーティスト",
-        "duration": "長さ",
+        "duration": "再生時間",
         "trackNumber": "#",
-        "playCount": "再生数",
+        "playCount": "再生回数",
         "title": "タイトル",
         "artist": "アーティスト",
+        "composer": "作曲",
         "album": "アルバム",
         "path": "ファイルパス",
+        "libraryName": "ライブラリ",
         "genre": "ジャンル",
-        "compilation": "Compilation",
+        "compilation": "コンピレーション",
         "year": "年",
         "size": "ファイルサイズ",
-        "updatedAt": "更新日",
+        "updatedAt": "更新日時",
         "bitRate": "ビットレート",
+        "bitDepth": "ビット深度",
+        "sampleRate": "サンプリングレート",
+        "albumGain": "アルバムゲイン",
+        "trackGain": "トラックゲイン",
+        "channels": "チャンネル",
+        "disc": "ディスク %{discNumber}",
         "discSubtitle": "ディスクサブタイトル",
         "starred": "お気に入り",
         "comment": "コメント",
-        "rating": "レート",
-        "quality": "品質",
+        "rating": "評価",
+        "quality": "形式",
         "bpm": "BPM",
-        "playDate": "最後の再生",
-        "channels": "チャンネル",
-        "createdAt": "追加日",
-        "grouping": "グループ分け",
+        "playDate": "最終再生日時",
+        "createdAt": "追加日時",
+        "grouping": "グループ化",
         "mood": "ムード",
-        "participants": "追加参加者",
+        "participants": "参加者",
         "tags": "追加タグ",
-        "mappedTags": "マッピング済みタグ",
-        "rawTags": "未処理タグ",
-        "bitDepth": "ビット深度",
-        "sampleRate": "サンプリングレート",
-        "missing": "不明",
-        "libraryName": "ライブラリ"
+        "mappedTags": "マッピングされたタグ",
+        "rawTags": "未加工タグ",
+        "missing": "不明"
       },
       "actions": {
         "addToQueue": "最後に再生",
-        "playNow": "すぐに再生",
+        "playNow": "今すぐ再生",
         "addToPlaylist": "プレイリストに追加",
-        "shuffleAll": "全曲シャッフル",
+        "showInPlaylist": "プレイリストで表示",
+        "shuffleAll": "すべてシャッフル",
         "download": "ダウンロード",
         "playNext": "次に再生",
         "info": "詳細",
-        "showInPlaylist": "含まれるプレイリスト"
+        "instantMix": "インスタントミックス"
       }
     },
     "album": {
@@ -54,48 +59,49 @@
       "fields": {
         "albumArtist": "アルバムアーティスト",
         "artist": "アーティスト",
-        "duration": "長さ",
-        "songCount": "曲",
-        "playCount": "再生数",
-        "name": "名前",
+        "duration": "再生時間",
+        "songCount": "曲数",
+        "playCount": "再生回数",
+        "size": "ファイルサイズ",
+        "name": "アルバム名",
+        "libraryName": "ライブラリ",
         "genre": "ジャンル",
-        "compilation": "Compilation",
+        "compilation": "コンピレーション",
         "year": "年",
-        "updatedAt": "更新日",
-        "comment": "コメント",
-        "rating": "レート",
-        "createdAt": "追加日",
-        "size": "サイズ",
-        "originalDate": "オリジナルの日付",
-        "releaseDate": "リリース日",
+        "date": "録音日",
+        "originalDate": "オリジナル発売日",
+        "releaseDate": "発売日",
         "releases": "リリース",
-        "released": "リリース",
-        "recordLabel": "ラベル",
+        "released": "リリース済み",
+        "updatedAt": "更新日時",
+        "comment": "コメント",
+        "rating": "評価",
+        "createdAt": "追加日時",
+        "recordLabel": "レーベル",
         "catalogNum": "カタログ番号",
-        "releaseType": "タイプ",
-        "grouping": "グループ分け",
+        "releaseType": "リリースタイプ",
+        "grouping": "グループ化",
         "media": "メディア",
         "mood": "ムード",
-        "date": "録音日",
-        "missing": "不明",
-        "libraryName": "ライブラリ"
+        "missing": "不明"
       },
       "actions": {
-        "playAll": "再生",
+        "playAll": "すべて再生",
         "playNext": "次に再生",
         "addToQueue": "最後に再生",
+        "share": "共有",
         "shuffle": "シャッフル",
-        "addToPlaylist": "プレイリストへ追加",
+        "addToPlaylist": "プレイリストに追加",
         "download": "ダウンロード",
         "info": "詳細",
-        "share": "共有"
+        "refresh": "メタデータを更新"
       },
       "lists": {
-        "all": "全て",
+        "all": "すべて",
         "random": "ランダム",
         "recentlyAdded": "最近の追加",
         "recentlyPlayed": "最近の再生",
-        "mostPlayed": "最も再生",
+        "mostPlayed": "最多再生",
         "starred": "お気に入り",
         "topRated": "高評価"
       }
@@ -106,33 +112,33 @@
         "name": "名前",
         "albumCount": "アルバム枚数",
         "songCount": "曲数",
-        "playCount": "再生数",
-        "rating": "レート",
-        "genre": "ジャンル",
         "size": "サイズ",
+        "playCount": "再生回数",
+        "rating": "評価",
+        "genre": "ジャンル",
         "role": "役割",
         "missing": "不明"
       },
       "roles": {
         "albumartist": "アルバムアーティスト",
         "artist": "アーティスト",
-        "composer": "作曲家",
-        "conductor": "指揮者",
-        "lyricist": "作詞家",
-        "arranger": "編曲者",
+        "composer": "作曲",
+        "conductor": "指揮",
+        "lyricist": "作詞",
+        "arranger": "編曲",
         "producer": "プロデューサー",
-        "director": "ディレクター",
+        "director": "監督",
         "engineer": "エンジニア",
         "mixer": "ミキサー",
         "remixer": "リミキサー",
         "djmixer": "DJ ミキサー",
-        "performer": "演奏者",
-        "maincredit": "アルバムアーティストもしくはアーティスト"
+        "performer": "演奏",
+        "maincredit": "アルバムアーティストまたはアーティスト"
       },
       "actions": {
+        "topSongs": "人気曲",
         "shuffle": "シャッフル",
-        "radio": "ラジオ",
-        "topSongs": "トップソング"
+        "radio": "ラジオ"
       }
     },
     "user": {
@@ -140,55 +146,58 @@
       "fields": {
         "userName": "ユーザー名",
         "isAdmin": "管理者",
-        "lastLoginAt": "最終ログイン",
-        "updatedAt": "更新日",
+        "lastLoginAt": "最終ログイン日時",
+        "lastAccessAt": "最終アクセス日時",
+        "updatedAt": "更新日時",
         "name": "名前",
         "password": "パスワード",
-        "createdAt": "作成日",
+        "createdAt": "作成日時",
         "changePassword": "パスワードを変更しますか？",
         "currentPassword": "現在のパスワード",
         "newPassword": "新しいパスワード",
         "token": "トークン",
-        "lastAccessAt": "最終アクセス",
-        "libraries": "ライブラリ"
+        "libraries": "ライブラリ",
+        "scrobbleFilter": "Scrobble フィルター"
       },
       "helperTexts": {
-        "name": "名前の変更は次回ログイン以降反映されます",
-        "libraries": "このユーザーに対して特定ライブラリを選択するか、デフォルトのライブラリを使用する場合は空欄のままにします"
+        "name": "ユーザー名の変更は、次回ログイン時に反映されます",
+        "libraries": "このユーザー用に特定のライブラリを選択するか、デフォルトのライブラリを使用する場合は空のままにしてください",
+        "scrobbleFilter": "これらのスマートプレイリストのルールに一致する曲は、Last.fm、ListenBrainz、または Scrobble プラグインに送信されません。スマートプレイリストと同じ JSON 構文と動作を使用します。例: {\"all\":[{\"lt\":{\"rating\":4}}]}。すべてを Scrobble する場合は空欄のままにしてください。ローカルでの再生回数には影響しません。"
       },
       "notifications": {
         "created": "ユーザーが作成されました",
         "updated": "ユーザーが更新されました",
         "deleted": "ユーザーが削除されました"
       },
-      "message": {
-        "listenBrainzToken": "ListenBrainzユーザートークンを入力",
-        "clickHereForToken": "ここをクリックしトークンを入手",
-        "selectAllLibraries": "全てのライブラリを選択",
-        "adminAutoLibraries": "管理者ユーザーは自動的にすべてのライブラリにアクセスできます"
-      },
       "validation": {
-        "librariesRequired": "管理者以外のユーザーには少なくとも1つのライブラリを選択する必要があります"
+        "librariesRequired": "管理者以外のユーザーについては、少なくとも 1 つのライブラリを選択する必要があります",
+        "invalidScrobbleFilter": "有効なスマートプレイリストのルールである必要があります。上限、オフセット、更新遅延はサポートされていません。"
+      },
+      "message": {
+        "listenBrainzToken": "ListenBrainz のユーザートークンを入力してください。",
+        "clickHereForToken": "トークンを取得するには、ここをクリックしてください",
+        "selectAllLibraries": "すべてのライブラリを選択",
+        "adminAutoLibraries": "管理者ユーザーは、すべてのライブラリに自動的にアクセスできます"
       }
     },
     "player": {
-      "name": "プレイヤー",
+      "name": "プレーヤー",
       "fields": {
         "name": "名前",
         "transcodingId": "トランスコード",
         "maxBitRate": "最大ビットレート",
         "client": "クライアント",
-        "userName": "ユーザ名",
-        "lastSeen": "最後の利用",
+        "userName": "ユーザー名",
+        "lastSeen": "最終アクセス日時",
         "reportRealPath": "実際のファイルパスを返す",
-        "scrobbleEnabled": "他のサービスへscrobbleする"
+        "scrobbleEnabled": "外部サービスに Scrobble する"
       }
     },
     "transcoding": {
       "name": "トランスコード",
       "fields": {
         "name": "名前",
-        "targetFormat": "対象フォーマット",
+        "targetFormat": "ターゲット形式",
         "defaultBitRate": "デフォルトビットレート",
         "command": "コマンド"
       }
@@ -197,45 +206,46 @@
       "name": "プレイリスト",
       "fields": {
         "name": "名前",
-        "duration": "時間",
+        "duration": "再生時間",
         "ownerName": "所有者",
         "public": "公開",
-        "updatedAt": "更新日",
-        "createdAt": "作成日",
-        "songCount": "曲",
+        "updatedAt": "更新日時",
+        "createdAt": "作成日時",
+        "songCount": "曲数",
         "comment": "コメント",
-        "sync": "自動インポート",
-        "path": "インポート元"
+        "sync": "同期",
+        "path": "インポートパス",
+        "starred": "お気に入り"
       },
       "actions": {
-        "selectPlaylist": "プレイリストを選択",
-        "addNewPlaylist": "'%{name}' を作成",
+        "selectPlaylist": "プレイリストを選択:",
+        "addNewPlaylist": "\"%{name}\" を作成",
         "export": "エクスポート",
-        "makePublic": "公開する",
-        "makePrivate": "非公開にする",
         "saveQueue": "キューをプレイリストに保存",
-        "searchOrCreate": "プレイリストを検索または入力して新規作成...",
-        "pressEnterToCreate": "Enterキーを押して新しいプレイリストを作成",
-        "removeFromSelection": "選択から削除"
+        "makePublic": "公開にする",
+        "makePrivate": "非公開にする",
+        "searchOrCreate": "プレイリストを検索するか、入力して新規作成します...",
+        "pressEnterToCreate": "Enter キーを押して新しいプレイリストを作成します",
+        "removeFromSelection": "選択から除外"
       },
       "message": {
-        "duplicate_song": "重複する曲を追加",
-        "song_exist": "既にプレイリストに存在する曲です。追加しますか？",
-        "noPlaylistsFound": "プレイリストが見つかりません",
-        "noPlaylists": "利用可能なプレイリストはありません"
+        "duplicate_song": "重複している曲を追加",
+        "song_exist": "プレイリストに重複する曲が追加されようとしています。重複する曲を追加しますか、それともスキップしますか？",
+        "noPlaylistsFound": "プレイリストが見つかりませんでした",
+        "noPlaylists": "利用可能なプレイリストがありません"
       }
     },
     "radio": {
       "name": "ラジオ",
       "fields": {
         "name": "名前",
-        "streamUrl": "配信URL",
-        "homePageUrl": "ホームページURL",
-        "updatedAt": "更新日",
-        "createdAt": "作成日"
+        "streamUrl": "ストリーム URL",
+        "homePageUrl": "ホームページ URL",
+        "updatedAt": "更新日時",
+        "createdAt": "作成日時"
       },
       "actions": {
-        "playNow": "すぐに再生"
+        "playNow": "今すぐ再生"
       }
     },
     "share": {
@@ -244,55 +254,57 @@
         "username": "共有者",
         "url": "URL",
         "description": "説明",
+        "downloadable": "ダウンロードを許可しますか？",
         "contents": "コンテンツ",
-        "expiresAt": "期限切れ",
-        "lastVisitedAt": "最後の訪問",
-        "visitCount": "訪問回数",
-        "format": "フォーマット",
+        "expiresAt": "有効期限",
+        "lastVisitedAt": "最終閲覧日時",
+        "visitCount": "閲覧回数",
+        "format": "形式",
         "maxBitRate": "最大ビットレート",
-        "updatedAt": "更新日",
-        "createdAt": "作成日",
-        "downloadable": "ダウンロードを許可しますか？"
-      }
+        "updatedAt": "更新日時",
+        "createdAt": "作成日時"
+      },
+      "notifications": {},
+      "actions": {}
     },
     "missing": {
-      "name": "欠落したファイル",
+      "name": "欠落ファイル",
+      "empty": "欠落しているファイルはありません",
       "fields": {
-        "path": "パス",
-        "size": "サイズ",
-        "updatedAt": "欠落日",
-        "libraryName": "ライブラリ"
+        "path": "ファイルパス",
+        "size": "ファイルサイズ",
+        "libraryName": "ライブラリ名",
+        "updatedAt": "更新日時"
       },
       "actions": {
         "remove": "削除",
-        "remove_all": "全て削除"
+        "remove_all": "すべて削除"
       },
       "notifications": {
         "removed": "欠落ファイルが削除されました"
-      },
-      "empty": "ファイルの欠落はありません"
+      }
     },
     "library": {
       "name": "ライブラリ",
       "fields": {
         "name": "名前",
         "path": "パス",
-        "remotePath": "リモートパス",
-        "lastScanAt": "最終スキャン",
+        "remotePath": "リモートスキャン",
+        "lastScanAt": "最終スキャン日時",
         "songCount": "曲数",
-        "albumCount": "アルバム数",
+        "albumCount": "アルバム枚数",
         "artistCount": "アーティスト数",
-        "totalSongs": "曲数",
-        "totalAlbums": "アルバム数",
-        "totalArtists": "アーティスト数",
-        "totalFolders": "フォルダー数",
-        "totalFiles": "ファイル数",
-        "totalMissingFiles": "欠落したファイル",
+        "totalSongs": "総曲数",
+        "totalAlbums": "総アルバム枚数",
+        "totalArtists": "総アーティスト数",
+        "totalFolders": "フォルダー総数",
+        "totalFiles": "ファイル総数",
+        "totalMissingFiles": "欠落ファイル数",
         "totalSize": "合計サイズ",
-        "totalDuration": "合計時間",
-        "defaultNewUsers": "新規ユーザーに対するデフォルト",
-        "createdAt": "作成日",
-        "updatedAt": "更新日"
+        "totalDuration": "総再生時間",
+        "defaultNewUsers": "新規ユーザーのデフォルト設定",
+        "createdAt": "作成日時",
+        "updatedAt": "更新日時"
       },
       "sections": {
         "basic": "基本情報",
@@ -300,95 +312,172 @@
       },
       "actions": {
         "scan": "ライブラリをスキャン",
-        "manageUsers": "ユーザーアクセス管理",
-        "viewDetails": "詳細を表示",
         "quickScan": "クイックスキャン",
-        "fullScan": "フルスキャン"
+        "fullScan": "フルスキャン",
+        "manageUsers": "ユーザーを管理",
+        "viewDetails": "詳細を表示"
       },
       "notifications": {
         "created": "ライブラリが正常に作成されました",
         "updated": "ライブラリが正常に更新されました",
         "deleted": "ライブラリが正常に削除されました",
-        "scanStarted": "スキャンを開始しました",
-        "scanCompleted": "スキャンが完了しました",
-        "quickScanStarted": "クイックスキャンを開始しました",
-        "fullScanStarted": "フルスキャンを開始しました",
-        "scanError": "スキャン開始中にエラーが発生。ログを確認してください"
+        "scanStarted": "ライブラリのスキャンが開始されました",
+        "quickScanStarted": "クイックスキャンが開始されました",
+        "fullScanStarted": "フルスキャンが開始されました",
+        "scanError": "スキャンを開始できませんでした。ログを確認してください",
+        "scanCompleted": "ライブラリのスキャンが完了しました"
       },
       "validation": {
-        "nameRequired": "ライブラリの名前が必要です",
-        "pathRequired": "ライブラリのパスが必要です",
+        "nameRequired": "ライブラリ名は必須です",
+        "pathRequired": "ライブラリパスは必須です",
         "pathNotDirectory": "ライブラリパスはディレクトリである必要があります",
-        "pathNotFound": "ライブラリのパスが見つかりません",
-        "pathNotAccessible": "ライブラリパスへアクセスできません",
+        "pathNotFound": "ライブラリパスが見つかりません",
+        "pathNotAccessible": "ライブラリパスにアクセスできません",
         "pathInvalid": "無効なライブラリパス"
       },
       "messages": {
-        "deleteConfirm": "このライブラリを削除しますか？関連する全てのデータとユーザーアクセスが削除されます。",
+        "deleteConfirm": "このライブラリを削除してもよろしいですか？これにより、関連するすべてのデータおよびユーザーのアクセス権が削除されます。",
         "scanInProgress": "スキャン中...",
-        "noLibrariesAssigned": "このユーザーに割り当てられているライブラリはありません"
+        "noLibrariesAssigned": "このユーザーに割り当てられたライブラリはありません"
+      }
+    },
+    "plugin": {
+      "name": "プラグイン",
+      "fields": {
+        "id": "ID",
+        "name": "名前",
+        "description": "説明",
+        "version": "バージョン",
+        "author": "作者",
+        "website": "ウェブサイト",
+        "permissions": "権限",
+        "enabled": "有効",
+        "status": "ステータス",
+        "path": "パス",
+        "lastError": "エラー",
+        "hasError": "エラー",
+        "updatedAt": "更新日時",
+        "createdAt": "インストール日時",
+        "configKey": "キー",
+        "configValue": "値",
+        "allUsers": "すべてのユーザーを許可",
+        "selectedUsers": "選択されたユーザー",
+        "allLibraries": "すべてのライブラリを許可",
+        "selectedLibraries": "選択されたライブラリ",
+        "allowWriteAccess": "書き込み権限を許可"
+      },
+      "sections": {
+        "status": "ステータス",
+        "info": "プラグイン情報",
+        "configuration": "設定",
+        "manifest": "マニフェスト",
+        "usersPermission": "ユーザー権限",
+        "libraryPermission": "ライブラリ権限"
+      },
+      "status": {
+        "enabled": "有効",
+        "disabled": "無効"
+      },
+      "actions": {
+        "enable": "有効化",
+        "disable": "無効化",
+        "disabledDueToError": "有効化する前にエラーを修正してください",
+        "disabledUsersRequired": "有効化する前にユーザーを選択してください",
+        "disabledLibrariesRequired": "有効化する前にライブラリを選択してください",
+        "addConfig": "設定を追加",
+        "rescan": "再スキャン"
+      },
+      "notifications": {
+        "enabled": "プラグインが有効化されました",
+        "disabled": "プラグインが無効化されました",
+        "updated": "プラグインが更新されました",
+        "error": "プラグインの更新中にエラーが発生しました"
+      },
+      "validation": {
+        "invalidJson": "設定は有効な JSON である必要があります"
+      },
+      "messages": {
+        "idHelp": "ファイル名から生成されるプラグイン ID です。エージェントなどの設定オプションでこのプラグインを参照する際に使用します。",
+        "configHelp": "キーと値のペアを使用してプラグインを設定します。設定が不要な場合は、空のままにしてください。",
+        "configValidationError": "設定の検証に失敗しました:",
+        "schemaRenderError": "設定フォームを表示できません。プラグインのスキーマが無効である可能性があります。",
+        "clickPermissions": "詳細を表示するには、「権限」をクリックしてください",
+        "noConfig": "設定がありません",
+        "allUsersHelp": "有効にすると、このプラグインは、今後作成されるユーザーも含め、すべてのユーザーにアクセスできるようになります。",
+        "noUsers": "ユーザーが選択されていません",
+        "permissionReason": "理由",
+        "usersRequired": "このプラグインは、ユーザー情報へのアクセスを必要とします。プラグインがアクセスできるユーザーを選択するか、「すべてのユーザーを許可」を有効にしてください。",
+        "allLibrariesHelp": "有効にすると、このプラグインは、今後作成されるライブラリも含め、すべてのライブラリにアクセスできるようになります。",
+        "noLibraries": "ライブラリが選択されていません",
+        "librariesRequired": "このプラグインは、ライブラリ情報へのアクセスを必要とします。プラグインがアクセスできるライブラリを選択するか、「すべてのライブラリを許可」を有効にしてください。",
+        "allowWriteAccessHelp": "有効にすると、プラグインはライブラリディレクトリ内のファイルを変更できるようになります。デフォルトでは、プラグインのアクセス権限は読み取り専用に設定されています。",
+        "requiredHosts": "必須ホスト"
+      },
+      "placeholders": {
+        "configKey": "キー",
+        "configValue": "値"
       }
     }
   },
   "ra": {
     "auth": {
-      "welcome1": "Navidromeをインストールいただきありがとうございます！",
-      "welcome2": "管理ユーザーを作成して始めましょう",
+      "welcome1": "Navidrome をインストールしていただき、ありがとうございます！",
+      "welcome2": "まずは、管理者ユーザーを作成してください",
       "confirmPassword": "パスワードの確認",
-      "buttonCreateAdmin": "管理者の作成",
-      "auth_check_error": "認証に失敗しました。再度ログインしてください",
-      "user_menu": "プロフィール",
+      "buttonCreateAdmin": "管理者を作成",
+      "auth_check_error": "続行するにはログインしてください",
+      "user_menu": "プロファイル",
       "username": "ユーザー名",
       "password": "パスワード",
       "sign_in": "ログイン",
-      "sign_in_error": "認証に失敗しました。入力を確認してください",
+      "sign_in_error": "認証に失敗しました。もう一度お試しください",
       "logout": "ログアウト",
-      "insightsCollectionNote": "Navidromeでは、プロジェクトの改善に役立てるため、匿名の利用データを収集しています。詳しくは [here] をクリックしてください。"
+      "insightsCollectionNote": "Navidrome では、プロジェクトの改善に役立てるため、匿名化された利用データを収集しています。詳細の確認やオプトアウト（収集の停止）を行うには、[こちら]をクリックしてください"
     },
     "validation": {
-      "invalidChars": "文字と数字のみを使用してください",
+      "invalidChars": "英数字のみを使用してください",
       "passwordDoesNotMatch": "パスワードが一致しません",
       "required": "必須",
-      "minLength": "%{min}文字以上である必要があります",
-      "maxLength": "%{max}文字以下である必要があります",
-      "minValue": "%{min}以上である必要があります",
-      "maxValue": "%{max}以下である必要があります",
+      "minLength": "%{min} 文字以上である必要があります",
+      "maxLength": "%{max} 文字以下である必要があります",
+      "minValue": "%{min} 桁以上である必要があります",
+      "maxValue": "%{max} 桁以下である必要があります",
       "number": "数字である必要があります",
-      "email": "メールアドレスである必要があります",
+      "email": "有効なメールアドレスである必要があります",
       "oneOf": "次のいずれかである必要があります: %{options}",
-      "regex": "次の正規表現形式にする必要があります: %{pattern}",
+      "regex": "特定の形式（正規表現）に一致する必要があります: %{pattern}",
       "unique": "一意である必要があります",
-      "url": "有効なURLを入力してください"
+      "url": "有効な URL である必要があります"
     },
     "action": {
-      "add_filter": "検索条件",
+      "add_filter": "フィルターを追加",
       "add": "追加",
       "back": "戻る",
-      "bulk_actions": "%{smart_count}件選択",
+      "bulk_actions": "1 件選択中 |||| %{smart_count} 件選択中",
+      "bulk_actions_mobile": "1 |||| %{smart_count}",
       "cancel": "キャンセル",
-      "clear_input_value": "空にする",
+      "clear_input_value": "値を消去",
       "clone": "複製",
       "confirm": "確認",
       "create": "作成",
       "delete": "削除",
       "edit": "編集",
       "export": "エクスポート",
-      "list": "一覧",
+      "list": "リスト",
       "refresh": "更新",
-      "remove_filter": "検索条件を削除",
+      "remove_filter": "このフィルターを削除",
       "remove": "削除",
       "save": "保存",
       "search": "検索",
-      "show": "詳細",
-      "sort": "並び替え",
+      "show": "表示",
+      "sort": "並べ替え",
       "undo": "元に戻す",
-      "expand": "開く",
+      "expand": "展開",
       "close": "閉じる",
-      "open_menu": "開く",
-      "close_menu": "閉じる",
+      "open_menu": "メニューを開く",
+      "close_menu": "メニューを閉じる",
       "unselect": "選択解除",
       "skip": "スキップ",
-      "bulk_actions_mobile": "1 |||| %{smart_count}",
       "share": "共有",
       "download": "ダウンロード"
     },
@@ -402,71 +491,71 @@
       "edit": "%{name} #%{id}",
       "error": "問題が発生しました",
       "list": "%{name}",
-      "loading": "読込中",
+      "loading": "読み込み中",
       "not_found": "見つかりませんでした",
       "show": "%{name} #%{id}",
-      "empty": "%{name}はありません",
-      "invite": "作成しますか？"
+      "empty": "%{name} はまだありません。",
+      "invite": "追加してもよろしいですか？"
     },
     "input": {
       "file": {
-        "upload_several": "アップロードするファイルをドロップ、または選択してください",
-        "upload_single": "アップロードするファイルをドロップ、または選択してください"
+        "upload_several": "ファイルをドロップしてアップロードするか、クリックしてファイルを選択してください。",
+        "upload_single": "ファイルをドロップしてアップロードするか、クリックして選択してください。"
       },
       "image": {
-        "upload_several": "アップロードする画像をドロップ、または選択してください",
-        "upload_single": "アップロードする画像をドロップ、または選択してください"
+        "upload_several": "画像をドロップしてアップロードするか、クリックして画像を選択してください。",
+        "upload_single": "画像をドロップしてアップロードするか、クリックして画像を選択してください。"
       },
       "references": {
-        "all_missing": "データが利用できなくなりました",
-        "many_missing": "選択したデータが利用できなくなりました",
-        "single_missing": "選択したデータが利用できなくなりました"
+        "all_missing": "参照データが見つかりませんでした。",
+        "many_missing": "参照データのうち、少なくとも 1 件が利用できなくなっています。",
+        "single_missing": "参照データは現在利用できません。"
       },
       "password": {
-        "toggle_visible": "非表示",
-        "toggle_hidden": "表示"
+        "toggle_visible": "パスワードを非表示",
+        "toggle_hidden": "パスワードを表示"
       }
     },
     "message": {
-      "about": "詳細",
-      "are_you_sure": "本当によろしいですか？",
-      "bulk_delete_content": "%{name} を削除してよろしいですか？ |||| 選択した %{smart_count}件のアイテムを削除してよろしいですか？",
-      "bulk_delete_title": "%{name} を削除 |||| %{name} %{smart_count}件を削除",
-      "delete_content": "削除してよろしいですか？",
+      "about": "概要",
+      "are_you_sure": "よろしいですか？",
+      "bulk_delete_content": "%{name} を削除してもよろしいですか？ |||| %{smart_count} 件の項目を削除してもよろしいですか？",
+      "bulk_delete_title": "%{name} を削除 |||| %{smart_count} 件の %{name} を削除",
+      "delete_content": "この項目を削除してもよろしいですか？",
       "delete_title": "%{name} #%{id} を削除",
       "details": "詳細",
-      "error": "クライアントエラーが発生し、処理を完了できませんでした",
-      "invalid_form": "入力値に誤りがあります。エラーメッセージを確認してください",
-      "loading": "読み込み中です。しばらくお待ちください",
+      "error": "クライアント側でエラーが発生したため、リクエストを完了できませんでした。",
+      "invalid_form": "フォームが無効です。エラーを確認してください",
+      "loading": "ページを読み込んでいます。しばらくお待ちください",
       "no": "いいえ",
-      "not_found": "間違ったURLを入力したか、間違ったリンクを辿りました",
+      "not_found": "URL を間違えて入力したか、無効なリンクをクリックした可能性があります。",
       "yes": "はい",
-      "unsaved_changes": "行った変更が保存されていません。このページから移動してよろしいですか？"
+      "unsaved_changes": "変更の一部が保存されませんでした。変更を破棄してもよろしいですか？"
     },
     "navigation": {
-      "no_results": "結果が見つかりませんでした",
-      "no_more_results": "ページ番号 %{page} は最大のページ数を超えています。前のページに戻ってください",
-      "page_out_of_boundaries": "ページ番号 %{page} は最大のページ数を超えています",
-      "page_out_from_end": "最大のページ数より後に移動できません",
-      "page_out_from_begin": "1 ページより前に移動できません",
+      "no_results": "検索結果はありません",
+      "no_more_results": "ページ番号 %{page} は範囲外です。前のページに戻ってください。",
+      "page_out_of_boundaries": "ページ番号 %{page} は範囲外です",
+      "page_out_from_end": "最後のページより先には進めません",
+      "page_out_from_begin": "ページ 1 より前には戻れません",
       "page_range_info": "%{offsetBegin}-%{offsetEnd} / %{total}",
-      "page_rows_per_page": "表示件数:",
+      "page_rows_per_page": "1 ページあたりの表示件数:",
       "next": "次",
       "prev": "前",
-      "skip_nav": "スキップ"
+      "skip_nav": "コンテンツへスキップ"
     },
     "notification": {
-      "updated": "更新しました |||| %{smart_count} 件更新しました",
-      "created": "作成しました",
-      "deleted": "削除しました |||| %{smart_count} 件削除しました",
-      "bad_item": "データが不正です",
-      "item_doesnt_exist": "データが存在しませんでした",
-      "http_error": "通信エラーが発生しました",
-      "data_provider_error": "dataProviderエラー。詳細はコンソールを確認してください",
-      "i18n_error": "翻訳ファイルが読み込めませんでした",
-      "canceled": "元に戻しました",
-      "logged_out": "認証に失敗しました。再度ログインしてください",
-      "new_version": "新しいバージョンが利用可能です！ページを更新してください。"
+      "updated": "更新されました |||| %{smart_count} 件の項目が更新されました",
+      "created": "作成されました",
+      "deleted": "削除されました |||| %{smart_count} 件の項目が削除されました",
+      "bad_item": "項目が無効です",
+      "item_doesnt_exist": "項目が存在しません",
+      "http_error": "サーバー通信エラーが発生しました",
+      "data_provider_error": "dataProvider のエラーが発生しました。詳細についてはコンソールを確認してください。",
+      "i18n_error": "指定された言語の翻訳を読み込めません",
+      "canceled": "操作がキャンセルされました",
+      "logged_out": "セッションが終了しました。再接続してください。",
+      "new_version": "新しいバージョンが利用可能になりました！このウィンドウを更新してください。"
     },
     "toggleFieldsMenu": {
       "columnsToDisplay": "表示列",
@@ -476,45 +565,59 @@
     }
   },
   "message": {
-    "note": "注意",
-    "transcodingDisabled": "セキュリティ上の理由から、Web インターフェイスからのトランスコード設定は無効になっています。\nこれを設定したい場合、環境変数 %{config} を設定しサーバーを再起動してください。",
-    "transcodingEnabled": "Navidromeは現在 %{config} の設定で実行されており、WebUIのトランスコード設定からコマンドを実行できます。\nセキュリティ上の問題から、この設定はトランスコード設定を変更する時のみ有効にすることを推奨します。",
-    "songsAddedToPlaylist": "プレイリストへ1曲追加しました |||| プレイリストへ%{smart_count}曲追加しました",
-    "noPlaylistsAvailable": "利用不可",
-    "delete_user_title": "'%{name}' を削除",
-    "delete_user_content": "このユーザーとその全てのデータ(プレイリストや設定)を削除してもよろしいですか？",
-    "notifications_blocked": "ブラウザの設定でこのサイトの通知がブロックされています",
-    "notifications_not_available": "このブラウザはデスクトップ通知をサポートしていません",
-    "lastfmLinkSuccess": "Last.fmとリンクしscrobbleが有効になりました",
-    "lastfmLinkFailure": "Last.fmとリンクできませんでした",
-    "lastfmUnlinkSuccess": "設定が解除され、Last.fmへのscrobbleは無効になっています",
-    "lastfmUnlinkFailure": "Last.fmとリンクできませんでした",
+    "uploadCover": "カバーをアップロード",
+    "removeCover": "カバーを削除",
+    "coverUploaded": "カバーアートが更新されました",
+    "coverRemoved": "カバーアートが削除されました",
+    "coverUploadError": "カバーアートのアップロード中にエラーが発生しました",
+    "coverRemoveError": "カバーアートの削除中にエラーが発生しました",
+    "metadataRefreshStarted": "メタデータの更新が開始されました",
+    "note": "注記",
+    "transcodingDisabled": "セキュリティ上の理由により、ウェブインターフェース経由でのトランスコード設定の変更は無効になっています。トランスコードのオプションを変更（編集または追加）する場合は、%{config} 設定オプションを指定してサーバーを再起動してください。",
+    "transcodingEnabled": "Navidrome は現在 %{config} で動作しており、ウェブインターフェースのトランスコード設定からシステムコマンドを実行できる状態になっています。セキュリティ上の理由から、この機能を無効にしておき、トランスコードのオプションを設定する際のみ有効にすることをお勧めします。",
+    "songsAddedToPlaylist": "1 曲をプレイリストに追加しました |||| %{smart_count} 曲をプレイリストに追加しました",
+    "noSimilarSongsFound": "類似の曲は見つかりませんでした",
+    "startingInstantMix": "インスタントミックスを読み込み中...",
+    "noTopSongsFound": "人気曲は見つかりませんでした",
+    "noPlaylistsAvailable": "利用可能なプレイリストがありません",
+    "delete_user_title": "ユーザー「%{name}」を削除",
+    "delete_user_content": "このユーザーと、そのすべてのデータ（プレイリストや設定を含む）を削除してもよろしいですか？",
+    "remove_missing_title": "欠落ファイルを削除",
+    "remove_missing_content": "選択した欠落ファイルをデータベースから削除してもよろしいですか？これにより、再生回数や評価を含む、これらのファイルに関するすべての情報が完全に削除されます。",
+    "remove_all_missing_title": "すべての欠落ファイルを削除",
+    "remove_all_missing_content": "すべての欠落ファイルをデータベースから削除してもよろしいですか？これにより、再生回数や評価を含む、これらのファイルに関するすべての情報が完全に削除されます。",
+    "notifications_blocked": "お使いのブラウザーの設定で、このサイトからの通知をブロックしています",
+    "notifications_not_available": "このブラウザーはデスクトップ通知に対応していないか、または Navidrome に HTTPS 経由でアクセスしていない可能性があります",
+    "lastfmLinkSuccess": "Last.fm との連携に成功し、Scrobbling 機能が有効になりました",
+    "lastfmLinkFailure": "Last.fm との連携に失敗しました",
+    "lastfmUnlinkSuccess": "Last.fm との連携が解除され、Scrobbling 機能が無効になりました",
+    "lastfmUnlinkFailure": "Last.fm との連携解除に失敗しました",
+    "listenBrainzLinkSuccess": "ListenBrainz との連携に成功し、ユーザー %{user} として Scrobbling 機能が有効になりました",
+    "listenBrainzLinkFailure": "ListenBrainz との連携に失敗しました: %{error}",
+    "listenBrainzUnlinkSuccess": "ListenBrainz との連携が解除され、Scrobbling 機能が無効になりました",
+    "listenBrainzUnlinkFailure": "ListenBrainz との連携解除に失敗しました",
     "openIn": {
-      "lastfm": "Last.fmで開く",
-      "musicbrainz": "MusicBrainzで開く"
+      "lastfm": "Last.fm で開く",
+      "musicbrainz": "MusicBrainz で開く"
     },
     "lastfmLink": "続きを読む",
-    "listenBrainzLinkSuccess": "%{user} へのscrobbling設定に成功しました",
-    "listenBrainzLinkFailure": "ListenBrainzとのリンクに失敗しました: %{error}",
-    "listenBrainzUnlinkSuccess": "ListenBrainzとのリンクとscrobblingを無効化しました。",
-    "listenBrainzUnlinkFailure": "ListenBrainzとのリンクを解除できませんでした",
-    "downloadOriginalFormat": "元のフォーマットでダウンロード",
-    "shareOriginalFormat": "元のフォーマットで共有",
-    "shareDialogTitle": "%{resource} '%{name}' を共有",
+    "shareOriginalFormat": "オリジナルの形式で共有",
+    "shareDialogTitle": "%{resource}「%{name}」を共有",
     "shareBatchDialogTitle": "1 %{resource} を共有 |||| %{smart_count} %{resource} を共有",
-    "shareSuccess": "コピーしました: %{url}",
-    "shareFailure": "コピーに失敗しました %{url}",
-    "downloadDialogTitle": "ダウンロード %{resource} '%{name}' (%{size})",
-    "shareCopyToClipboard": "クリップボードへコピー: Ctrl+C, Enter",
-    "remove_missing_title": "欠落ファイルを削除",
-    "remove_missing_content": "選択した欠落ファイルをデータベースから削除してもよろしいですか？これにより、再生数や評価を含むそれらのファイルへの参照が完全に削除されます。",
-    "remove_all_missing_title": "全ての欠落ファイルを削除",
-    "remove_all_missing_content": "データベースから欠落ファイルをすべて削除してもよろしいですか？これにより、再生数や評価を含むそれらのファイルへの参照が永久に削除されます。",
-    "noSimilarSongsFound": "類似の曲が見つかりませんでした",
-    "noTopSongsFound": "トップソングが見つかりません"
+    "shareCopyToClipboard": "クリップボードにコピー: Ctrl+C、Enter",
+    "shareSuccess": "URL をクリップボードにコピーしました: %{url}",
+    "shareFailure": "URL %{url} をクリップボードにコピーできませんでした",
+    "downloadDialogTitle": "%{resource}「%{name}」(%{size}) をダウンロード",
+    "downloadOriginalFormat": "オリジナルの形式でダウンロード"
   },
   "menu": {
     "library": "ライブラリ",
+    "librarySelector": {
+      "allLibraries": "すべてのライブラリ (%{count})",
+      "multipleLibraries": "%{total} 件のライブラリのうち %{selected} 件",
+      "selectLibraries": "ライブラリを選択",
+      "none": "無し"
+    },
     "settings": "設定",
     "version": "バージョン",
     "theme": "テーマ",
@@ -523,53 +626,48 @@
       "options": {
         "theme": "テーマ",
         "language": "言語",
-        "defaultView": "デフォルト画面",
+        "defaultView": "デフォルトの画面",
         "desktop_notifications": "デスクトップ通知",
-        "lastfmScrobbling": "Last.fmへscrobbleする",
-        "listenBrainzScrobbling": "ListenBrainzへscrobble",
-        "replaygain": "ReplayGainモード",
-        "preAmp": "プリアンプ",
+        "lastfmNotConfigured": "Last.fm API キーが設定されていません。",
+        "lastfmScrobbling": "Last.fm に Scrobble",
+        "listenBrainzScrobbling": "ListenBrainz に Scrobble",
+        "replaygain": "リプレイゲインモード",
+        "preAmp": "リプレイゲインプリアンプ (dB)",
         "gain": {
           "none": "無効",
-          "album": "アルバムゲインを使う",
-          "track": "トラックゲインを使う"
-        },
-        "lastfmNotConfigured": "Last.fmのAPIキーが設定されていません"
+          "album": "アルバムゲインを使用",
+          "track": "トラックゲインを使用"
+        }
       }
     },
     "albumList": "アルバム",
-    "about": "詳細",
     "playlists": "プレイリスト",
+    "onlyFavourites": "お気に入りのみ表示",
     "sharedPlaylists": "共有プレイリスト",
-    "librarySelector": {
-      "allLibraries": "全てのライブラリ( %{count} )",
-      "multipleLibraries": "%{selected}  個 / %{total} 個のライブラリ",
-      "selectLibraries": "ライブラリを選択",
-      "none": "無し"
-    }
+    "about": "概要"
   },
   "player": {
-    "playListsText": "再生リスト",
+    "playListsText": "再生キュー",
     "openText": "開く",
     "closeText": "閉じる",
     "notContentText": "音楽がありません",
     "clickToPlayText": "クリックして再生",
-    "clickToPauseText": "一時停止",
+    "clickToPauseText": "クリックして一時停止",
     "nextTrackText": "次の曲",
     "previousTrackText": "前の曲",
-    "reloadText": "更新",
+    "reloadText": "再読み込み",
     "volumeText": "音量",
-    "toggleLyricText": "歌詞を切り替え",
+    "toggleLyricText": "歌詞の表示 / 非表示",
     "toggleMiniModeText": "最小化",
-    "destroyText": "削除",
+    "destroyText": "破棄",
     "downloadText": "ダウンロード",
-    "removeAudioListsText": "リストを空にする",
-    "clickToDeleteText": "クリックして%{name}を削除",
+    "removeAudioListsText": "オーディオリストを削除",
+    "clickToDeleteText": "クリックして %{name} を削除",
     "emptyLyricText": "歌詞がありません",
     "playModeText": {
-      "order": "順番に",
-      "orderLoop": "リピート",
-      "singleLoop": "一曲リピート",
+      "order": "順番に再生",
+      "orderLoop": "繰り返し再生",
+      "singleLoop": "1 曲のみ繰り返し再生",
       "shufflePlay": "シャッフル"
     }
   },
@@ -578,14 +676,14 @@
       "homepage": "ホームページ",
       "source": "ソースコード",
       "featureRequests": "機能リクエスト",
-      "lastInsightsCollection": "最後のデータ収集",
+      "lastInsightsCollection": "最終データ収集日時",
       "insights": {
         "disabled": "無効",
         "waiting": "待機中"
       }
     },
     "tabs": {
-      "about": "詳細",
+      "about": "概要",
       "config": "設定"
     },
     "config": {
@@ -593,42 +691,43 @@
       "environmentVariable": "環境変数",
       "currentValue": "現在値",
       "configurationFile": "設定ファイル",
-      "exportToml": "設定をエクスポート(TOML)",
-      "exportSuccess": "設定をTOML形式でクリップボードへエクスポートしました",
+      "exportToml": "設定をエクスポート (TOML)",
+      "downloadToml": "設定をダウンロード (TOML)",
+      "exportSuccess": "設定が TOML 形式でクリップボードにエクスポートされました",
       "exportFailed": "設定のコピーに失敗しました",
-      "devFlagsHeader": "開発フラグ(変更・削除の可能性あり)",
+      "devFlagsHeader": "開発用フラグ（変更または削除される可能性があります）",
       "devFlagsComment": "これらは実験的な設定であり、将来のバージョンで削除される可能性があります"
     }
   },
   "activity": {
-    "title": "活動",
-    "totalScanned": "スキャン済みフォルダー",
+    "title": "アクティビティ",
+    "totalScanned": "スキャンされたフォルダーの総数",
     "quickScan": "クイック",
     "fullScan": "フル",
+    "selectiveScan": "選択的",
     "serverUptime": "サーバー稼働時間",
-    "serverDown": "サーバーオフライン",
+    "serverDown": "オフライン",
     "scanType": "最終スキャン",
     "status": "スキャンエラー",
-    "elapsedTime": "経過時間",
-    "selectiveScan": "選択的スキャン"
-  },
-  "help": {
-    "title": "ホットキー",
-    "hotkeys": {
-      "show_help": "このヘルプを表示",
-      "toggle_menu": "サイドバーの表示/非表示",
-      "toggle_play": "再生/停止",
-      "prev_song": "前の曲",
-      "next_song": "次の曲",
-      "vol_up": "音量を上げる",
-      "vol_down": "音量を下げる",
-      "toggle_love": "星の付け外し",
-      "current_song": "現在の曲へ移動"
-    }
+    "elapsedTime": "経過時間"
   },
   "nowPlaying": {
     "title": "再生中",
-    "empty": "何も再生されていません",
-    "minutesAgo": "%{smart_count} 分前 |||| %{smart_count} 分前"
+    "empty": "再生中の曲はありません",
+    "minutesAgo": "%{smart_count} 分前"
+  },
+  "help": {
+    "title": "Navidrome ホットキー",
+    "hotkeys": {
+      "show_help": "ヘルプを表示",
+      "toggle_menu": "サイドバーの表示 / 非表示",
+      "toggle_play": "再生 / 一時停止",
+      "prev_song": "前の曲",
+      "next_song": "次の曲",
+      "current_song": "再生中の曲へ移動",
+      "vol_up": "音量を上げる",
+      "vol_down": "音量を下げる",
+      "toggle_love": "この曲をお気に入り登録 / 登録解除"
+    }
   }
-}
\ No newline at end of file
+}

From 9198bde34ad1b75060773de32ff3bb111b9d6ab9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 6 Sep 2026 13:40:43 -0400
Subject: [PATCH 114/200] test(scanner): fix Windows flake in the quick-scan
 artist image spec (#6093)

The spec asserted on artistID("Kraftwerk") and intermittently found zero artists
on Windows. The scan did import the artist; it was then made invisible.

RefreshStats selects touched artists with a strict artist.updated_at >
library.last_scan_at (persistence/artist_repository.go:466). Windows' wall clock
has ~15ms granularity, so a new artist written by a quick scan can land in the
same tick as the previous scan's last_scan_at and be excluded. Its
library_artist.stats then stays at the '{}' default and the unscoped cleanup
DELETE removes the row, after which selectArtist's INNER JOIN on library_artist
hides the artist from GetAll.

Backdate last_scan_at before the scan so the comparison is unambiguous, matching
the fix already applied to the search_normalized spec below it.
---
 scanner/scanner_test.go | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/scanner/scanner_test.go b/scanner/scanner_test.go
index 00f91699d..8542b3ac6 100644
--- a/scanner/scanner_test.go
+++ b/scanner/scanner_test.go
@@ -387,6 +387,11 @@ var _ = Describe("Scanner", Ordered, func() {
 			files := fsys.MapFS
 			files["Kraftwerk/Autobahn/01 - Autobahn.mp3"] = kraftwerk(track(1, "Autobahn"))
 			fsys.SetFiles(files)
+			// Backdate the previous scan so this one's new artists are unambiguously newer:
+			// RefreshStats picks touched artists with a strict artist.updated_at >
+			// library.last_scan_at, and Windows' coarse clock can put both in one tick.
+			_, err := db.Db().ExecContext(ctx, "UPDATE library SET last_scan_at = ?", time.Now().Add(-time.Hour))
+			Expect(err).ToNot(HaveOccurred())
 			Expect(runScanner(ctx, false)).To(Succeed())
 			resolveQueuedArtwork()
 

From 97e1f73cc85bc35eb1d998e9e6a987b239552537 Mon Sep 17 00:00:00 2001
From: Shxiao <shxiao1115@163.com>
Date: Mon, 7 Sep 2026 12:08:49 +0900
Subject: [PATCH 115/200] docs: fix broken links in Jellyfin and plugin
 documentation (#6097)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: point jftui client link to canonical repository

* docs: fix relative path to webhook-rs example in nd-pdk-host README

* docs: fix capability schema paths in plugin examples README

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 plugins/examples/README.md             | 4 ++--
 plugins/pdk/rust/nd-pdk-host/README.md | 2 +-
 server/jellyfin/README.md              | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/plugins/examples/README.md b/plugins/examples/README.md
index bce2b6762..8e2dc5a85 100644
--- a/plugins/examples/README.md
+++ b/plugins/examples/README.md
@@ -108,7 +108,7 @@ Generate boilerplate from a schema:
 # Install XTP: https://docs.xtp.dylibso.com/docs/cli
 
 xtp plugin init \
-  --schema-file ../schemas/metadata_agent.yaml \
+  --schema-file ../capabilities/metadata_agent.yaml \
   --template go \
   --path ./my-plugin \
   --name my-plugin
@@ -119,7 +119,7 @@ xtp plugin build
 zip -j my-plugin.ndp manifest.json dist/plugin.wasm
 ```
 
-Available schemas in [../schemas/](../schemas/):
+Available schemas in [../capabilities/](../capabilities/):
 - `metadata_agent.yaml` – Artist/album metadata
 - `scrobbler.yaml` – Scrobbling integration
 - `lifecycle.yaml` – Init callbacks
diff --git a/plugins/pdk/rust/nd-pdk-host/README.md b/plugins/pdk/rust/nd-pdk-host/README.md
index f722b2e5a..00bcdfc2f 100644
--- a/plugins/pdk/rust/nd-pdk-host/README.md
+++ b/plugins/pdk/rust/nd-pdk-host/README.md
@@ -84,4 +84,4 @@ Rust plugins must be compiled to WebAssembly:
 cargo build --target wasm32-wasip1 --release
 ```
 
-See the [webhook-rs](../../examples/webhook-rs/) example for a complete plugin implementation.
+See the [webhook-rs](../../../examples/webhook-rs/) example for a complete plugin implementation.
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 15b56a499..5b9a2dba4 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -3,7 +3,7 @@
 This package implements a subset of the [Jellyfin](https://jellyfin.org/) REST API on top of
 Navidrome's existing library, users, playlists and scrobbling infrastructure. It lets
 Jellyfin-compatible clients (e.g. [Finamp](https://github.com/jmshrv/finamp),
-[jftui](https://github.com/dylanmtaylor/jftui)) browse and stream a Navidrome library without
+[jftui](https://github.com/Aanok/jftui)) browse and stream a Navidrome library without
 requiring a real Jellyfin server.
 
 It is **not** a full Jellyfin server implementation: only the endpoints needed to browse a music

From 1ceb25c6c1cc0698efcf164010cf8a25092d0024 Mon Sep 17 00:00:00 2001
From: jaxi <jaxi@cmyksoda.cc>
Date: Sun, 6 Sep 2026 23:28:25 -0400
Subject: [PATCH 116/200] =?UTF-8?q?feat(ui):=20added=20Catppuccin=20Mocha?=
 =?UTF-8?q?=20and=20Frapp=C3=A9=20themes,=20updated=20Macchiato=20theme=20?=
 =?UTF-8?q?to=20better=20reflect=20the=20official=20palette=20(#5835)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* added catppuccin mocha theme

* added catppuccin mocha theme to index.js

* fix syntax

* add catppuccin frappé theme

* made frappe and mocha themes more consistant with official color palette and added comments for easy verification

* same for macchiato, seperate commit in case original is preferred

* added comments to .js files

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 ui/src/themes/catppuccinFrappe.css.js    | 158 ++++++++++++++++++++
 ui/src/themes/catppuccinFrappe.js        | 106 +++++++++++++
 ui/src/themes/catppuccinLatte.css.js     |  54 +++----
 ui/src/themes/catppuccinMacchiato.css.js | 180 ++++++++++++-----------
 ui/src/themes/catppuccinMacchiato.js     |  50 +++----
 ui/src/themes/catppuccinMocha.css.js     | 158 ++++++++++++++++++++
 ui/src/themes/catppuccinMocha.js         | 106 +++++++++++++
 ui/src/themes/index.js                   |   6 +-
 8 files changed, 677 insertions(+), 141 deletions(-)
 create mode 100644 ui/src/themes/catppuccinFrappe.css.js
 create mode 100644 ui/src/themes/catppuccinFrappe.js
 create mode 100644 ui/src/themes/catppuccinMocha.css.js
 create mode 100644 ui/src/themes/catppuccinMocha.js

diff --git a/ui/src/themes/catppuccinFrappe.css.js b/ui/src/themes/catppuccinFrappe.css.js
new file mode 100644
index 000000000..f927d3ba1
--- /dev/null
+++ b/ui/src/themes/catppuccinFrappe.css.js
@@ -0,0 +1,158 @@
+const stylesheet = `
+  .react-jinke-music-player-main svg:active,
+  .react-jinke-music-player-main svg:hover {
+    color: #949cbb; /* overlay2 */
+  }
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle,
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-track {
+    background-color: #a5adce; /* subtext0 */
+  }
+
+  .react-jinke-music-player-main ::-webkit-scrollbar-thumb {
+    background-color: #a5adce; /* subtext0 */
+  }
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle:active {
+    box-shadow: 0 0 2px #a5adce; /* subtext0 */
+  }
+
+  .react-jinke-music-player-main .audio-item.playing svg {
+    color: #a5adce; /* subtext0 */
+  }
+
+  .react-jinke-music-player-main .audio-item.playing .player-singer {
+    color: #a5adce !important;
+  }
+
+  .react-jinke-music-player-main .loading svg {
+    color: #a5adce !important;
+  }
+
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle {
+    border: hidden;
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+  }
+
+
+  .rc-slider-rail, .rc-slider-track {
+    height: 6px;
+  }
+
+  .rc-slider {
+    padding: 3px 0;
+  }
+
+  .sound-operation > div:nth-child(4) {
+    transform: translateX(-50%) translateY(5%) !important;
+  }
+
+  .sound-operation {
+    padding: 4px 0;
+  }
+
+  .react-jinke-music-player-main .music-player-panel {
+    background-color: #292c3c; /* mantle */
+    color: #c6d0f5; /* text */
+    box-shadow: 0 0 8px rgba(0, 0, 0, 0.25);
+  }
+
+  .audio-lists-panel {
+    background-color: #292c3c; /* mantle */
+    bottom: 6.25rem;
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+  }
+
+  .audio-lists-panel-content .audio-item.playing {
+    background-color: rgba(0, 0, 0, 0);
+  }
+
+  .audio-lists-panel-content .audio-item:nth-child(2n+1) {
+    background-color: rgba(0, 0, 0, 0);
+  }
+
+  .audio-lists-panel-content .audio-item:active,
+  .audio-lists-panel-content .audio-item:hover {
+    background-color:rgba(255, 255, 255, 0.08);
+  }
+
+  .audio-lists-panel-header {
+    border-bottom:1px solid #414559; /* surface0 */
+  }
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .player-content .audio-lists-btn {
+    background-color:rgba(0,0,0,0);
+    box-shadow:0 0 0 0;
+  }
+
+  .audio-lists-panel-content .audio-item {
+    line-height: 32px;
+  }
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .img-content {
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+  }
+
+  .react-jinke-music-player-main .music-player-lyric {
+    color: #a5adce; /* subtext0 */
+    -webkit-text-stroke: 0.5px #303446; /* base */
+    font-weight: bolder;
+  }
+
+  .react-jinke-music-player-main .lyric-btn-active,
+  .react-jinke-music-player-main .lyric-btn-active svg {
+    color: #a5adce !important;
+  }
+
+  .audio-lists-panel-header {
+    border-bottom:1px solid rgba(0, 0, 0, 0.25);
+    box-shadow:none;
+  }
+
+  .audio-lists-panel-content .audio-item.playing,
+  .audio-lists-panel-content .audio-item.playing svg {
+    color: #a5adce; /* subtext0 */
+  }
+
+  .audio-lists-panel-content .audio-item:active .group:not([class=".player-delete"]) svg,
+  .audio-lists-panel-content .audio-item:hover .group:not([class=".player-delete"]) svg {
+    color: #a5adce; /* subtext0 */
+  }
+
+  .audio-lists-panel-content .audio-item .player-icons {
+    scale: 75%;
+  }
+
+  .audio-lists-panel-content .audio-item:active,
+  .audio-lists-panel-content .audio-item:hover {
+    background-color: #51576d; /* surface1 */
+  }
+
+/* Mobile */
+
+  .react-jinke-music-player-mobile-cover {
+    border: none;
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+  }
+
+  .react-jinke-music-player .music-player-controller {
+    border: none;
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+    color: #a5adce; /* subtext0 */
+  }
+
+  .react-jinke-music-player .music-player-controller .music-player-controller-setting {
+    color: rgba(122,160,236,.3);
+  }
+
+  .react-jinke-music-player-mobile-progress .rc-slider-handle, .react-jinke-music-player-mobile-progress .rc-slider-track {
+    background-color: #a5adce; /* subtext0 */
+  }
+
+  .react-jinke-music-player-mobile-progress .rc-slider-handle {
+    border: none;
+  }
+`
+
+export default stylesheet
diff --git a/ui/src/themes/catppuccinFrappe.js b/ui/src/themes/catppuccinFrappe.js
new file mode 100644
index 000000000..87ff6258f
--- /dev/null
+++ b/ui/src/themes/catppuccinFrappe.js
@@ -0,0 +1,106 @@
+import stylesheet from './catppuccinFrappe.css.js'
+
+export default {
+  themeName: 'Catppuccin Frappé',
+  palette: {
+    primary: {
+      main: '#ca9ee6', // Mauve
+    },
+    secondary: {
+      main: '#292c3c', //Mantle
+      contrastText: '#c6d0f5', // Text
+    },
+    type: 'dark',
+    background: {
+      default: '#303446', // Base
+    },
+  },
+  overrides: {
+    MuiPaper: {
+      root: {
+        color: '#c6d0f5', // Text
+        backgroundColor: '#292c3c', // Mantle
+        MuiSnackbarContent: {
+          root: {
+            color: '#c6d0f5', // Text
+            backgroundColor: '#e78284', // Red
+          },
+          message: {
+            color: '#c6d0f5', // Text
+            backgroundColor: '#e78284', // Red
+          },
+        },
+      },
+    },
+    MuiButton: {
+      textPrimary: {
+        color: '#8caaee', // Blue
+      },
+      textSecondary: {
+        color: '#c6d0f5', // Text
+      },
+    },
+    MuiChip: {
+      clickable: {
+        background: '#292c3c', //Mantle
+      },
+    },
+    MuiFormGroup: {
+      root: {
+        color: '#c6d0f5', // Text
+      },
+    },
+    MuiFormHelperText: {
+      root: {
+        Mui: {
+          error: {
+            color: '#e78284', // Red
+          },
+        },
+      },
+    },
+    MuiTableHead: {
+      root: {
+        color: '#c6d0f5', // Text
+        background: '#292c3c', //Mantle
+      },
+    },
+    MuiTableCell: {
+      root: {
+        color: '#c6d0f5', // Text
+        background: '#292c3c !important', //Mantle
+      },
+      head: {
+        color: '#c6d0f5', // Text
+        background: '#292c3c !important', //Mantle
+      },
+    },
+    NDLogin: {
+      systemNameLink: {
+        color: '#ca9ee6', // Mauve
+      },
+      icon: {},
+      welcome: {
+        color: '#c6d0f5', // Text
+      },
+      card: {
+        minWidth: 300,
+        background: '#303446', // Base
+      },
+      avatar: {},
+      button: {
+        boxShadow: '3px 3px 5px #303446', // Base
+      },
+    },
+    NDMobileArtistDetails: {
+      bgContainer: {
+        background:
+          'linear-gradient(to bottom, rgba(52 52 52 / 72%), rgb(48 48 48))!important',
+      },
+    },
+  },
+  player: {
+    theme: 'dark',
+    stylesheet,
+  },
+}
diff --git a/ui/src/themes/catppuccinLatte.css.js b/ui/src/themes/catppuccinLatte.css.js
index 84c8d2d7f..006601cd9 100644
--- a/ui/src/themes/catppuccinLatte.css.js
+++ b/ui/src/themes/catppuccinLatte.css.js
@@ -2,41 +2,41 @@ const stylesheet = `
   .react-jinke-music-player-main.light-theme svg,
   .react-jinke-music-player .music-player-controller,
   .react-jinke-music-player .audio-circle-process-bar circle[class='stroke'] {
-    color: #6c6f85;
-    stroke: #6c6f85;
+    color: #6c6f85; /* subtext0 */
+    stroke: #6c6f85; /* subtext0 */
   }
 
   .react-jinke-music-player-main svg:active,
   .react-jinke-music-player-main svg:hover {
-    color: #7c7f93;
+    color: #7c7f93; /* overlay2 */
   }
 
   .react-jinke-music-player-main.light-theme svg:active,
   .react-jinke-music-player-main.light-theme svg:hover {
-    color: #7c7f93;
+    color: #7c7f93; /* overlay2 */
   }
 
   .react-jinke-music-player-mobile-play-model-tip,
   .react-jinke-music-player-main.light-theme .play-mode-title {
-    background-color: #6c6f85;
-    color: #eff1f5;
+    background-color: #6c6f85; /* subtext0 */
+    color: #eff1f5; /* base */
   }
 
   .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle,
   .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-track {
-    background-color: #6c6f85;
+    background-color: #6c6f85; /* subtext0 */
   }
 
   .react-jinke-music-player-main ::-webkit-scrollbar-thumb {
-    background-color: #6c6f85;
+    background-color: #6c6f85; /* subtext0 */
   }
 
   .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle:active {
-    box-shadow: 0 0 2px #6c6f85;
+    box-shadow: 0 0 2px #6c6f85; /* subtext0 */
   }
 
   .react-jinke-music-player-main .audio-item.playing svg {
-    color: #6c6f85;
+    color: #6c6f85; /* subtext0 */
   }
 
   .react-jinke-music-player-main .audio-item.playing .player-singer {
@@ -65,7 +65,7 @@ const stylesheet = `
 
   .react-jinke-music-player-main.light-theme .rc-switch-checked {
     background-color: #6c6f85 !important;
-    border: 1px solid #6c6f85;
+    border: 1px solid #6c6f85; /* subtext0 */
   }
 
   .sound-operation > div:nth-child(4) {
@@ -77,17 +77,17 @@ const stylesheet = `
   }
 
   .react-jinke-music-player-main .music-player-panel {
-    background-color: #e6e9ef;
-    color: #4c4f69;
+    background-color: #e6e9ef; /* mantle */
+    color: #4c4f69; /* text */
     box-shadow: 0 0 8px rgba(76, 79, 105, 0.15);
   }
 
   .react-jinke-music-player-main.light-theme .music-player-panel {
-    color: #4c4f69;
+    color: #4c4f69; /* text */
   }
 
   .audio-lists-panel {
-    background-color: #e6e9ef;
+    background-color: #e6e9ef; /* mantle */
     bottom: 6.25rem;
     box-shadow:
       rgba(76, 79, 105, 0.12) 0px 4px 6px,
@@ -108,7 +108,7 @@ const stylesheet = `
   }
 
   .audio-lists-panel-header {
-    border-bottom: 1px solid #ccd0da;
+    border-bottom: 1px solid #ccd0da; /* surface0 */
     box-shadow: none;
   }
 
@@ -118,13 +118,13 @@ const stylesheet = `
   }
 
   .react-jinke-music-player-main.light-theme .audio-lists-panel-header {
-    background-color: #e6e9ef;
-    color: #4c4f69;
+    background-color: #e6e9ef; /* mantle */
+    color: #4c4f69; /* text */
   }
 
   .audio-lists-panel-content .audio-item {
     line-height: 32px;
-    color: #4c4f69;
+    color: #4c4f69; /* text */
   }
 
   .react-jinke-music-player-main .music-player-panel .panel-content .img-content {
@@ -135,7 +135,7 @@ const stylesheet = `
 
   .react-jinke-music-player-main .music-player-lyric {
     color: #6c6f85; /* subtext0 */
-    -webkit-text-stroke: 0.35px #eff1f5;
+    -webkit-text-stroke: 0.35px #eff1f5; /* base */
     font-weight: bolder;
   }
 
@@ -146,12 +146,12 @@ const stylesheet = `
 
   .audio-lists-panel-content .audio-item.playing,
   .audio-lists-panel-content .audio-item.playing svg {
-    color: #6c6f85;
+    color: #6c6f85; /* subtext0 */
   }
 
   .audio-lists-panel-content .audio-item:active .group:not([class=".player-delete"]) svg,
   .audio-lists-panel-content .audio-item:hover .group:not([class=".player-delete"]) svg {
-    color: #6c6f85;
+    color: #6c6f85; /* subtext0 */
   }
 
   .audio-lists-panel-content .audio-item .player-icons {
@@ -173,12 +173,12 @@ const stylesheet = `
 
   .react-jinke-music-player .music-player-controller {
     border: none;
-    background-color: #e6e9ef;
-    border-color: #e6e9ef;
+    background-color: #e6e9ef; /* mantle */
+    border-color: #e6e9ef; /* mantle */
     box-shadow:
       rgba(76, 79, 105, 0.12) 0px 4px 6px,
       rgba(76, 79, 105, 0.08) 0px 5px 7px;
-    color: #6c6f85;
+    color: #6c6f85; /* subtext0 */
   }
 
   .react-jinke-music-player .music-player-controller.music-player-playing:before {
@@ -187,12 +187,12 @@ const stylesheet = `
 
   .react-jinke-music-player .music-player-controller .music-player-controller-setting {
     background: rgba(108, 111, 133, 0.2);
-    color: #eff1f5;
+    color: #eff1f5; /* base */
   }
 
   .react-jinke-music-player-mobile-progress .rc-slider-handle,
   .react-jinke-music-player-mobile-progress .rc-slider-track {
-    background-color: #6c6f85;
+    background-color: #6c6f85; /* subtext0 */
   }
 
   .react-jinke-music-player-mobile-progress .rc-slider-handle {
diff --git a/ui/src/themes/catppuccinMacchiato.css.js b/ui/src/themes/catppuccinMacchiato.css.js
index d303a0364..e415a990b 100644
--- a/ui/src/themes/catppuccinMacchiato.css.js
+++ b/ui/src/themes/catppuccinMacchiato.css.js
@@ -1,154 +1,158 @@
 const stylesheet = `
+  .react-jinke-music-player-main svg:active,
+  .react-jinke-music-player-main svg:hover {
+    color: #939ab7; /* overlay2 */
+  }
 
-.react-jinke-music-player-main svg:active, .react-jinke-music-player-main svg:hover {
-    color: #00a4dc
-}
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle,
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-track {
+    background-color: #a5adcb; /* subtext0 */
+  }
 
-.react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle, .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-track {
-    background-color: #00a4dc
-}
+  .react-jinke-music-player-main ::-webkit-scrollbar-thumb {
+    background-color: #a5adcb; /* subtext0 */
+  }
 
-.react-jinke-music-player-main ::-webkit-scrollbar-thumb {
-    background-color: #00a4dc;
-}
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle:active {
+    box-shadow: 0 0 2px #a5adcb; /* subtext0 */
+  }
 
-.react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle:active {
-    box-shadow: 0 0 2px #00a4dc
-}
+  .react-jinke-music-player-main .audio-item.playing svg {
+    color: #a5adcb; /* subtext0 */
+  }
 
-.react-jinke-music-player-main .audio-item.playing svg {
-    color: #00a4dc
-}
+  .react-jinke-music-player-main .audio-item.playing .player-singer {
+    color: #a5adcb !important;
+  }
 
-.react-jinke-music-player-main .audio-item.playing .player-singer {
-    color: #00a4dc !important
-}
-
-.react-jinke-music-player-main .loading svg {
-    color: #00a4dc !important
-}
+  .react-jinke-music-player-main .loading svg {
+    color: #a5adcb !important;
+  }
 
 
-.react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle {
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle {
     border: hidden;
     box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
-}
+  }
 
 
-.rc-slider-rail, .rc-slider-track {
+  .rc-slider-rail, .rc-slider-track {
     height: 6px;
-}
+  }
 
-.rc-slider {
+  .rc-slider {
     padding: 3px 0;
-}
+  }
 
-.sound-operation > div:nth-child(4) {
+  .sound-operation > div:nth-child(4) {
     transform: translateX(-50%) translateY(5%) !important;
-}
+  }
 
-.sound-operation {
+  .sound-operation {
     padding: 4px 0;
-}
+  }
 
-.react-jinke-music-player-main .music-player-panel {
-    background-color: #1e2030;
-    color: #24273a
+  .react-jinke-music-player-main .music-player-panel {
+    background-color: #1e2030; /* mantle */
+    color: #cad3f5; /* text */
     box-shadow: 0 0 8px rgba(0, 0, 0, 0.25);
-}
+  }
 
-.audio-lists-panel {
-    background-color: #1e2030;
+  .audio-lists-panel {
+    background-color: #1e2030; /* mantle */
     bottom: 6.25rem;
     box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
-}
+  }
 
-.audio-lists-panel-content .audio-item.playing {
+  .audio-lists-panel-content .audio-item.playing {
     background-color: rgba(0, 0, 0, 0);
-}
+  }
 
-.audio-lists-panel-content .audio-item:nth-child(2n+1) {
+  .audio-lists-panel-content .audio-item:nth-child(2n+1) {
     background-color: rgba(0, 0, 0, 0);
-}
+  }
 
-.audio-lists-panel-content .audio-item:active,
-.audio-lists-panel-content .audio-item:hover {
+  .audio-lists-panel-content .audio-item:active,
+  .audio-lists-panel-content .audio-item:hover {
     background-color:rgba(255, 255, 255, 0.08);
-}
+  }
 
-.audio-lists-panel-header {
-    border-bottom:1px solid #242936;
-}
+  .audio-lists-panel-header {
+    border-bottom:1px solid #363a4f; /* surface0 */
+  }
 
-.react-jinke-music-player-main .music-player-panel .panel-content .player-content .audio-lists-btn {
+  .react-jinke-music-player-main .music-player-panel .panel-content .player-content .audio-lists-btn {
     background-color:rgba(0,0,0,0);
     box-shadow:0 0 0 0;
-}
+  }
 
-.audio-lists-panel-content .audio-item {
+  .audio-lists-panel-content .audio-item {
     line-height: 32px;
-}
+  }
 
-.react-jinke-music-player-main .music-player-panel .panel-content .img-content {
+  .react-jinke-music-player-main .music-player-panel .panel-content .img-content {
     box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
-}
+  }
 
-.react-jinke-music-player-main .music-player-lyric {
-    color: #acb3d2;
-    -webkit-text-stroke: 0.5px #2E3440;
+  .react-jinke-music-player-main .music-player-lyric {
+    color: #a5adcb; /* subtext0 */
+    -webkit-text-stroke: 0.5px #1e1e2e; /* base */
     font-weight: bolder;
-}
+  }
 
-.react-jinke-music-player-main .lyric-btn-active, .react-jinke-music-player-main .lyric-btn-active svg {
-    color: #acb3d2 !important;
-}
+  .react-jinke-music-player-main .lyric-btn-active,
+  .react-jinke-music-player-main .lyric-btn-active svg {
+    color: #a5adcb !important;
+  }
 
-.audio-lists-panel-header {
+  .audio-lists-panel-header {
     border-bottom:1px solid rgba(0, 0, 0, 0.25);
     box-shadow:none;
-}
+  }
 
-.audio-lists-panel-content .audio-item.playing, .audio-lists-panel-content .audio-item.playing svg {
-    color: #00a4dc
-}
+  .audio-lists-panel-content .audio-item.playing,
+  .audio-lists-panel-content .audio-item.playing svg {
+    color: #a5adcb; /* subtext0 */
+  }
 
-.audio-lists-panel-content .audio-item:active .group:not([class=".player-delete"]) svg, .audio-lists-panel-content .audio-item:hover .group:not([class=".player-delete"]) svg {
-    color: #00a4dc
-}
+  .audio-lists-panel-content .audio-item:active .group:not([class=".player-delete"]) svg,
+  .audio-lists-panel-content .audio-item:hover .group:not([class=".player-delete"]) svg {
+    color: #a5adcb; /* subtext0 */
+  }
 
-.audio-lists-panel-content .audio-item .player-icons {
+  .audio-lists-panel-content .audio-item .player-icons {
     scale: 75%;
-}
+  }
 
-.audio-lists-panel-content .audio-item:active,
-.audio-lists-panel-content .audio-item:hover {
-    background-color: #363a4f;
-}
+  .audio-lists-panel-content .audio-item:active,
+  .audio-lists-panel-content .audio-item:hover {
+    background-color: #494d64; /* surface1 */
+  }
 
 /* Mobile */
 
-.react-jinke-music-player-mobile-cover {
+  .react-jinke-music-player-mobile-cover {
     border: none;
     box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
-}
+  }
 
-.react-jinke-music-player .music-player-controller {
+  .react-jinke-music-player .music-player-controller {
     border: none;
     box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
-    color: #00a4dc;
-}
+    color: #a5adcb; /* subtext0 */
+  }
 
-.react-jinke-music-player .music-player-controller .music-player-controller-setting {
+  .react-jinke-music-player .music-player-controller .music-player-controller-setting {
     color: rgba(122,160,236,.3);
-}
+  }
 
-.react-jinke-music-player-mobile-progress .rc-slider-handle, .react-jinke-music-player-mobile-progress .rc-slider-track {
-    background-color: #00a4dc;
-}
+  .react-jinke-music-player-mobile-progress .rc-slider-handle, .react-jinke-music-player-mobile-progress .rc-slider-track {
+    background-color: #a5adcb; /* subtext0 */
+  }
 
-.react-jinke-music-player-mobile-progress .rc-slider-handle {
+  .react-jinke-music-player-mobile-progress .rc-slider-handle {
     border: none;
-}
+  }
 `
 
 export default stylesheet
diff --git a/ui/src/themes/catppuccinMacchiato.js b/ui/src/themes/catppuccinMacchiato.js
index 63c93ff66..b41a7b2ea 100644
--- a/ui/src/themes/catppuccinMacchiato.js
+++ b/ui/src/themes/catppuccinMacchiato.js
@@ -4,92 +4,92 @@ export default {
   themeName: 'Catppuccin Macchiato',
   palette: {
     primary: {
-      main: '#c6a0f6',
+      main: '#c6a0f6', // Mauve
     },
     secondary: {
-      main: '#1e2030',
-      contrastText: '#cad3f5',
+      main: '#1e2030', // Mantle
+      contrastText: '#cad3f5', // Text
     },
     type: 'dark',
     background: {
-      default: '#24273a',
+      default: '#24273a', // Base
     },
   },
   overrides: {
     MuiPaper: {
       root: {
-        color: '#cad3f5',
-        backgroundColor: '#1e2030',
+        color: '#cad3f5', // Text
+        backgroundColor: '#1e2030', // Mantle
         MuiSnackbarContent: {
           root: {
-            color: '#cad3f5',
-            backgroundColor: '#ed8796',
+            color: '#cad3f5', // Text
+            backgroundColor: '#ed8796', // Red
           },
           message: {
-            color: '#cad3f5',
-            backgroundColor: '#ed8796',
+            color: '#cad3f5', // Text
+            backgroundColor: '#ed8796', // Red
           },
         },
       },
     },
     MuiButton: {
       textPrimary: {
-        color: '#8aadf4',
+        color: '#8aadf4', // Blue
       },
       textSecondary: {
-        color: '#cad3f5',
+        color: '#cad3f5', // Text
       },
     },
     MuiChip: {
       clickable: {
-        background: '#1e2030',
+        background: '#1e2030', // Mantle
       },
     },
     MuiFormGroup: {
       root: {
-        color: '#cad3f5',
+        color: '#cad3f5', // Text
       },
     },
     MuiFormHelperText: {
       root: {
         Mui: {
           error: {
-            color: '#ed8796',
+            color: '#ed8796', // Red
           },
         },
       },
     },
     MuiTableHead: {
       root: {
-        color: '#cad3f5',
-        background: '#1e2030',
+        color: '#cad3f5', // Text
+        background: '#1e2030', // Mantle
       },
     },
     MuiTableCell: {
       root: {
-        color: '#cad3f5',
-        background: '#1e2030 !important',
+        color: '#cad3f5', // Text
+        background: '#1e2030 !important', // Mantle
       },
       head: {
-        color: '#cad3f5',
-        background: '#1e2030 !important',
+        color: '#cad3f5', // Text
+        background: '#1e2030 !important', // Mantle
       },
     },
     NDLogin: {
       systemNameLink: {
-        color: '#c6a0f6',
+        color: '#c6a0f6', // Mauve
       },
       icon: {},
       welcome: {
-        color: '#cad3f5',
+        color: '#cad3f5', // Text
       },
       card: {
         minWidth: 300,
-        background: '#24273a',
+        background: '#24273a', // Base
       },
       avatar: {},
       button: {
-        boxShadow: '3px 3px 5px #24273a',
+        boxShadow: '3px 3px 5px #24273a', // Base
       },
     },
     NDMobileArtistDetails: {
diff --git a/ui/src/themes/catppuccinMocha.css.js b/ui/src/themes/catppuccinMocha.css.js
new file mode 100644
index 000000000..7a238468a
--- /dev/null
+++ b/ui/src/themes/catppuccinMocha.css.js
@@ -0,0 +1,158 @@
+const stylesheet = `
+  .react-jinke-music-player-main svg:active,
+  .react-jinke-music-player-main svg:hover {
+    color: #9399b2; /* overlay2 */
+  }
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle,
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-track {
+    background-color: #a6adc8; /* subtext0 */
+  }
+
+  .react-jinke-music-player-main ::-webkit-scrollbar-thumb {
+    background-color: #a6adc8; /* subtext0 */
+  }
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle:active {
+    box-shadow: 0 0 2px #a6adc8; /* subtext0 */
+  }
+
+  .react-jinke-music-player-main .audio-item.playing svg {
+    color: #a6adc8; /* subtext0 */
+  }
+
+  .react-jinke-music-player-main .audio-item.playing .player-singer {
+    color: #a6adc8 !important;
+  }
+
+  .react-jinke-music-player-main .loading svg {
+    color: #a6adc8 !important;
+  }
+
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .rc-slider-handle {
+    border: hidden;
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+  }
+
+
+  .rc-slider-rail, .rc-slider-track {
+    height: 6px;
+  }
+
+  .rc-slider {
+    padding: 3px 0;
+  }
+
+  .sound-operation > div:nth-child(4) {
+    transform: translateX(-50%) translateY(5%) !important;
+  }
+
+  .sound-operation {
+    padding: 4px 0;
+  }
+
+  .react-jinke-music-player-main .music-player-panel {
+    background-color: #181825; /* mantle */
+    color: #cdd6f4; /* text */
+    box-shadow: 0 0 8px rgba(0, 0, 0, 0.25);
+  }
+
+  .audio-lists-panel {
+    background-color: #181825; /* mantle */
+    bottom: 6.25rem;
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+  }
+
+  .audio-lists-panel-content .audio-item.playing {
+    background-color: rgba(0, 0, 0, 0);
+  }
+
+  .audio-lists-panel-content .audio-item:nth-child(2n+1) {
+    background-color: rgba(0, 0, 0, 0);
+  }
+
+  .audio-lists-panel-content .audio-item:active,
+  .audio-lists-panel-content .audio-item:hover {
+    background-color:rgba(255, 255, 255, 0.08);
+  }
+
+  .audio-lists-panel-header {
+    border-bottom:1px solid #313244; /* surface0 */
+  }
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .player-content .audio-lists-btn {
+    background-color:rgba(0,0,0,0);
+    box-shadow:0 0 0 0;
+  }
+
+  .audio-lists-panel-content .audio-item {
+    line-height: 32px;
+  }
+
+  .react-jinke-music-player-main .music-player-panel .panel-content .img-content {
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+  }
+
+  .react-jinke-music-player-main .music-player-lyric {
+    color: #a6adc8; /* subtext0 */
+    -webkit-text-stroke: 0.5px #1e1e2e; /* base */
+    font-weight: bolder;
+  }
+
+  .react-jinke-music-player-main .lyric-btn-active,
+  .react-jinke-music-player-main .lyric-btn-active svg {
+    color: #a6adc8 !important;
+  }
+
+  .audio-lists-panel-header {
+    border-bottom:1px solid rgba(0, 0, 0, 0.25);
+    box-shadow:none;
+  }
+
+  .audio-lists-panel-content .audio-item.playing,
+  .audio-lists-panel-content .audio-item.playing svg {
+    color: #a6adc8; /* subtext0 */
+  }
+
+  .audio-lists-panel-content .audio-item:active .group:not([class=".player-delete"]) svg,
+  .audio-lists-panel-content .audio-item:hover .group:not([class=".player-delete"]) svg {
+    color: #a6adc8; /* subtext0 */
+  }
+
+  .audio-lists-panel-content .audio-item .player-icons {
+    scale: 75%;
+  }
+
+  .audio-lists-panel-content .audio-item:active,
+  .audio-lists-panel-content .audio-item:hover {
+    background-color: #45475a; /* surface1 */
+  }
+
+/* Mobile */
+
+  .react-jinke-music-player-mobile-cover {
+    border: none;
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+  }
+
+  .react-jinke-music-player .music-player-controller {
+    border: none;
+    box-shadow:rgba(15, 17, 21, 0.25) 0px 4px 6px, rgba(15, 17, 21, 0.1) 0px 5px 7px;
+    color: #a6adc8; /* subtext0 */
+  }
+
+  .react-jinke-music-player .music-player-controller .music-player-controller-setting {
+    color: rgba(122,160,236,.3);
+  }
+
+  .react-jinke-music-player-mobile-progress .rc-slider-handle, .react-jinke-music-player-mobile-progress .rc-slider-track {
+    background-color: #a6adc8; /* subtext0 */
+  }
+
+  .react-jinke-music-player-mobile-progress .rc-slider-handle {
+    border: none;
+  }
+`
+
+export default stylesheet
diff --git a/ui/src/themes/catppuccinMocha.js b/ui/src/themes/catppuccinMocha.js
new file mode 100644
index 000000000..bdfb33520
--- /dev/null
+++ b/ui/src/themes/catppuccinMocha.js
@@ -0,0 +1,106 @@
+import stylesheet from './catppuccinMocha.css.js'
+
+export default {
+  themeName: 'Catppuccin Mocha',
+  palette: {
+    primary: {
+      main: '#cba6f7', // Mauve
+    },
+    secondary: {
+      main: '#181825', // Mantle
+      contrastText: '#cdd6f4', // Text
+    },
+    type: 'dark',
+    background: {
+      default: '#1e1e2e', // Base
+    },
+  },
+  overrides: {
+    MuiPaper: {
+      root: {
+        color: '#cdd6f4', // Text
+        backgroundColor: '#181825', // Mantle
+        MuiSnackbarContent: {
+          root: {
+            color: '#cdd6f4', // Text
+            backgroundColor: '#f38ba8', // Red
+          },
+          message: {
+            color: '#cdd6f4', // Text
+            backgroundColor: '#f38ba8', // Red
+          },
+        },
+      },
+    },
+    MuiButton: {
+      textPrimary: {
+        color: '#89b4fa', // Blue
+      },
+      textSecondary: {
+        color: '#cdd6f4', // Text
+      },
+    },
+    MuiChip: {
+      clickable: {
+        background: '#181825', // Mantle
+      },
+    },
+    MuiFormGroup: {
+      root: {
+        color: '#cdd6f4', // Text
+      },
+    },
+    MuiFormHelperText: {
+      root: {
+        Mui: {
+          error: {
+            color: '#f38ba8', // Red
+          },
+        },
+      },
+    },
+    MuiTableHead: {
+      root: {
+        color: '#cdd6f4', // Text
+        background: '#181825', // Mantle
+      },
+    },
+    MuiTableCell: {
+      root: {
+        color: '#cdd6f4', // Text
+        background: '#181825 !important', // Mantle
+      },
+      head: {
+        color: '#cdd6f4', // Text
+        background: '#181825 !important', // Mantle
+      },
+    },
+    NDLogin: {
+      systemNameLink: {
+        color: '#cba6f7', // Mauve
+      },
+      icon: {},
+      welcome: {
+        color: '#cdd6f4', // Text
+      },
+      card: {
+        minWidth: 300,
+        background: '#1e1e2e', // Base
+      },
+      avatar: {},
+      button: {
+        boxShadow: '3px 3px 5px #1e1e2e', // Base
+      },
+    },
+    NDMobileArtistDetails: {
+      bgContainer: {
+        background:
+          'linear-gradient(to bottom, rgba(52 52 52 / 72%), rgb(48 48 48))!important',
+      },
+    },
+  },
+  player: {
+    theme: 'dark',
+    stylesheet,
+  },
+}
diff --git a/ui/src/themes/index.js b/ui/src/themes/index.js
index 98705da30..391a97f2c 100644
--- a/ui/src/themes/index.js
+++ b/ui/src/themes/index.js
@@ -8,7 +8,9 @@ import MonokaiTheme from './monokai'
 import ElectricPurpleTheme from './electricPurple'
 import NordTheme from './nord'
 import GruvboxDarkTheme from './gruvboxDark'
+import CatppuccinFrappeTheme from './catppuccinFrappe'
 import CatppuccinMacchiatoTheme from './catppuccinMacchiato'
+import CatppuccinMochaTheme from './catppuccinMocha'
 import CatppuccinLatteTheme from './catppuccinLatte'
 import DraculaTheme from './dracula'
 import NuclearTheme from './nuclear'
@@ -31,8 +33,10 @@ export default {
 
   // New themes should be added here, in alphabetic order
   AmusicTheme,
-  CatppuccinMacchiatoTheme,
+  CatppuccinFrappeTheme,
   CatppuccinLatteTheme,
+  CatppuccinMacchiatoTheme,
+  CatppuccinMochaTheme,
   DraculaTheme,
   ElectricPurpleTheme,
   ExtraDarkTheme,

From 48af781b82524fcb1dd9e4b1a0a3d35c7405428b Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Mon, 7 Sep 2026 13:47:45 -0400
Subject: [PATCH 117/200] fix(reflex): exclude .worktrees from the reflex
 configuration regex

---
 reflex.conf | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reflex.conf b/reflex.conf
index 47dd775ab..1cbaa7bb7 100644
--- a/reflex.conf
+++ b/reflex.conf
@@ -1 +1 @@
--s -r "(\.go$$|\.cpp$$|\.h$$|navidrome.toml|resources|token_received.html)" -R "(^ui|^data|^db/migrations)" -R "_test\.go$$" -- go run -race -tags netgo,sqlite_fts5 .
+-s -r "(\.go$$|\.cpp$$|\.h$$|navidrome.toml|resources|token_received.html)" -R "(^ui|^data|^db/migrations)" -R "_test\.go$$" -R "^\.worktrees" -- go run -race -tags netgo,sqlite_fts5 .

From 404837799b9e7fc378625a1e8e1834df5c3533a3 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Mon, 7 Sep 2026 13:43:26 -0400
Subject: [PATCH 118/200] fix(subsonic): don't re-encode a source already in
 the player's forced format

When a player has a forced transcoding format, ClientInfo.ForceFormat cleared
DirectPlayProfiles unconditionally. A FLAC source on a player configured to
transcode to FLAC was therefore re-encoded to FLAC, wasting CPU and bandwidth
for no gain. Worse, the transcoder pipes ffmpeg output to stdout, so the
resulting FLAC has total_samples=0 and no seek table -- an offline copy of it
can never be seeked. Reported against getTranscodeDecision by the Symfonium
author.

ForceFormat now rebuilds DirectPlayProfiles from the matching transcoding
profiles instead of dropping them: a client declaring a transcoding profile for
a format is proof it can consume that format, so a source already in it is
served as-is. Container and codec come from resolveTargetFormat, so a legacy
"oga" target_format yields an ogg/opus profile, and the profile's
MaxAudioChannels is carried across.

DirectPlayProfile has no bitrate field, so restoring direct play needs a
ceiling to keep an over-bitrate source out of it. GetTranscodeDecision now
seeds that ceiling from the transcoding row's DefaultBitRate when a format was
successfully forced, with the player's own MaxBitRate still taking precedence.
This also closes a gap where the new endpoint ignored DefaultBitRate entirely:
an mp3 320 source on a player forced to mp3@192 was served at 320, while the
legacy /rest/stream path correctly gave 192.

Applied via CapBitrate, which only ever lowers, so a client declaring a
stricter limit keeps it. The legacy path (applyServerOverride) is untouched --
ForceFormat has no other callers.
---
 core/stream/decider_test.go       | 76 +++++++++++++++++++++++++++++++
 core/stream/types.go              | 26 +++++++----
 core/stream/types_test.go         | 32 ++++++++++++-
 server/subsonic/transcode.go      | 25 ++++++----
 server/subsonic/transcode_test.go | 45 +++++++++++++++++-
 5 files changed, 183 insertions(+), 21 deletions(-)

diff --git a/core/stream/decider_test.go b/core/stream/decider_test.go
index 577207636..01fef1249 100644
--- a/core/stream/decider_test.go
+++ b/core/stream/decider_test.go
@@ -1144,6 +1144,82 @@ var _ = Describe("Decider", func() {
 			})
 		})
 
+		Context("Player-forced format", func() {
+			symfonium := func() *ClientInfo {
+				return &ClientInfo{
+					Name: "Symfonium",
+					DirectPlayProfiles: []DirectPlayProfile{
+						{Containers: []string{"mp3", "flac", "ogg"}, Protocols: []string{ProtocolHTTP}},
+					},
+					TranscodingProfiles: []Profile{
+						{Container: "flac", AudioCodec: "flac", Protocol: ProtocolHTTP},
+						{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP},
+					},
+				}
+			}
+
+			It("direct plays a flac source forced to flac", func() {
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1026, Channels: 2, SampleRate: 44100, BitDepth: new(16)})
+				ci := symfonium()
+				Expect(ci.ForceFormat("flac")).To(BeTrue())
+
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanDirectPlay).To(BeTrue())
+			})
+
+			It("still transcodes a 24-bit flac when the client caps bit depth", func() {
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 4600, Channels: 2, SampleRate: 96000, BitDepth: new(24)})
+				ci := symfonium()
+				ci.CodecProfiles = []CodecProfile{{
+					Type: CodecProfileTypeAudio, Name: "flac",
+					Limitations: []Limitation{{Name: LimitationAudioBitdepth, Comparison: ComparisonLessThanEqual, Values: []string{"16"}, Required: true}},
+				}}
+				Expect(ci.ForceFormat("flac")).To(BeTrue())
+
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanDirectPlay).To(BeFalse())
+				Expect(decision.CanTranscode).To(BeTrue())
+				Expect(decision.TranscodeStream.BitDepth).To(Equal(16))
+			})
+
+			It("still transcodes a 320 mp3 forced to mp3 at a lower bitrate", func() {
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "mp3", Codec: "MP3", BitRate: 320, Channels: 2, SampleRate: 44100})
+				ci := symfonium()
+				Expect(ci.ForceFormat("mp3")).To(BeTrue())
+				ci.CapBitrate(192)
+
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanDirectPlay).To(BeFalse())
+				Expect(decision.CanTranscode).To(BeTrue())
+				Expect(decision.TargetBitrate).To(Equal(192))
+			})
+
+			It("direct plays a 128 mp3 forced to mp3 at a higher bitrate", func() {
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "mp3", Codec: "MP3", BitRate: 128, Channels: 2, SampleRate: 44100})
+				ci := symfonium()
+				Expect(ci.ForceFormat("mp3")).To(BeTrue())
+				ci.CapBitrate(192)
+
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanDirectPlay).To(BeTrue())
+			})
+
+			It("transcodes a flac source forced to mp3", func() {
+				mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1026, Channels: 2, SampleRate: 44100, BitDepth: new(16)})
+				ci := symfonium()
+				Expect(ci.ForceFormat("mp3")).To(BeTrue())
+
+				decision, err := svc.MakeDecision(ctx, mf, ci, TranscodeOptions{})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(decision.CanDirectPlay).To(BeFalse())
+				Expect(decision.CanTranscode).To(BeTrue())
+				Expect(decision.TargetFormat).To(Equal("mp3"))
+			})
+		})
 	})
 
 	Describe("ensureProbed", func() {
diff --git a/core/stream/types.go b/core/stream/types.go
index 19474dd91..300017c01 100644
--- a/core/stream/types.go
+++ b/core/stream/types.go
@@ -59,28 +59,38 @@ func (ci *ClientInfo) CapBitrate(maxKbps int) bool {
 	return changed
 }
 
-// ForceFormat narrows the client to transcoding to targetFormat and suppresses
-// direct play, but only if the client already declares a profile for that
-// format. All matching profiles are kept so negotiation can still pick among
-// them (e.g. by protocol). Returns false (no-op) when targetFormat is empty or
-// unsupported.
+// ForceFormat narrows the client to transcoding to targetFormat, but only if the
+// client already declares a profile for it. All matching profiles are kept so
+// negotiation can still pick among them (e.g. by protocol). Direct play is rebuilt
+// from those profiles rather than dropped, since declaring a transcoding profile
+// for a format is proof the client can play it. Returns false when unsupported.
 func (ci *ClientInfo) ForceFormat(targetFormat string) bool {
 	if targetFormat == "" {
 		return false
 	}
 	var matched []Profile
+	var directPlay []DirectPlayProfile
 	for i := range ci.TranscodingProfiles {
+		p := &ci.TranscodingProfiles[i]
 		// matchesContainer is alias-aware, so a forced "oga" (legacy Opus
 		// target_format) still matches a resolved "opus" profile.
-		if _, format := resolveTargetFormat(&ci.TranscodingProfiles[i]); matchesContainer(format, []string{targetFormat}) {
-			matched = append(matched, ci.TranscodingProfiles[i])
+		container, format := resolveTargetFormat(p)
+		if !matchesContainer(format, []string{targetFormat}) {
+			continue
 		}
+		matched = append(matched, *p)
+		directPlay = append(directPlay, DirectPlayProfile{
+			Containers:       []string{container},
+			AudioCodecs:      []string{format},
+			Protocols:        []string{ProtocolHTTP},
+			MaxAudioChannels: p.MaxAudioChannels,
+		})
 	}
 	if len(matched) == 0 {
 		return false
 	}
 	ci.TranscodingProfiles = matched
-	ci.DirectPlayProfiles = nil
+	ci.DirectPlayProfiles = directPlay
 	return true
 }
 
diff --git a/core/stream/types_test.go b/core/stream/types_test.go
index eff408362..88ad904a7 100644
--- a/core/stream/types_test.go
+++ b/core/stream/types_test.go
@@ -58,7 +58,7 @@ var _ = Describe("ClientInfo", func() {
 	})
 
 	Describe("ForceFormat", func() {
-		It("restricts to the forced format and clears direct play when supported", func() {
+		It("restricts direct play to the forced format when supported", func() {
 			ci := &ClientInfo{
 				DirectPlayProfiles: []DirectPlayProfile{{Containers: []string{"flac"}, AudioCodecs: []string{"flac"}}},
 				TranscodingProfiles: []Profile{
@@ -71,7 +71,35 @@ var _ = Describe("ClientInfo", func() {
 			Expect(ok).To(BeTrue())
 			Expect(ci.TranscodingProfiles).To(HaveLen(1))
 			Expect(ci.TranscodingProfiles[0].AudioCodec).To(Equal("opus"))
-			Expect(ci.DirectPlayProfiles).To(BeEmpty())
+			Expect(ci.DirectPlayProfiles).To(ConsistOf(DirectPlayProfile{
+				Containers: []string{"ogg"}, AudioCodecs: []string{"opus"}, Protocols: []string{ProtocolHTTP},
+			}))
+		})
+
+		It("keeps direct play for a source already in the forced format", func() {
+			ci := &ClientInfo{
+				DirectPlayProfiles: []DirectPlayProfile{{Containers: []string{"flac"}, AudioCodecs: []string{"flac"}}},
+				TranscodingProfiles: []Profile{
+					{Container: "flac", AudioCodec: "flac", Protocol: ProtocolHTTP},
+					{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP},
+				},
+			}
+			ok := ci.ForceFormat("flac")
+			Expect(ok).To(BeTrue())
+			Expect(ci.DirectPlayProfiles).To(ConsistOf(DirectPlayProfile{
+				Containers: []string{"flac"}, AudioCodecs: []string{"flac"}, Protocols: []string{ProtocolHTTP},
+			}))
+		})
+
+		It("carries the channel limit of the forced profile into direct play", func() {
+			ci := &ClientInfo{
+				TranscodingProfiles: []Profile{
+					{Container: "flac", AudioCodec: "flac", Protocol: ProtocolHTTP, MaxAudioChannels: 2},
+				},
+			}
+			Expect(ci.ForceFormat("flac")).To(BeTrue())
+			Expect(ci.DirectPlayProfiles).To(HaveLen(1))
+			Expect(ci.DirectPlayProfiles[0].MaxAudioChannels).To(Equal(2))
 		})
 
 		It("matches a container-only forced format (mp3)", func() {
diff --git a/server/subsonic/transcode.go b/server/subsonic/transcode.go
index 9eb2af160..d64bce605 100644
--- a/server/subsonic/transcode.go
+++ b/server/subsonic/transcode.go
@@ -280,12 +280,19 @@ func (api *Router) GetTranscodeDecision(w http.ResponseWriter, r *http.Request)
 		return stream.IsAACCodec(p.Container)
 	})
 
+	player, hasPlayer := request.PlayerFrom(ctx)
+
 	// Honor the player's forced transcoding format, falling back to normal
 	// negotiation when the client can't play it (issue #5583).
+	maxBitRate := 0
 	if trc, ok := request.TranscodingFrom(ctx); ok && trc.TargetFormat != "" {
-		if !clientInfo.ForceFormat(trc.TargetFormat) {
+		if clientInfo.ForceFormat(trc.TargetFormat) {
+			// DirectPlayProfile carries no bitrate, so this ceiling is the only
+			// thing keeping an over-bitrate source out of direct play.
+			maxBitRate = trc.DefaultBitRate
+		} else {
 			clientName := clientInfo.Name
-			if player, ok := request.PlayerFrom(ctx); ok && player.Client != "" {
+			if hasPlayer && player.Client != "" {
 				clientName = player.Client
 			}
 			log.Debug(ctx, "Player forced format not supported by client; falling back to negotiation",
@@ -293,13 +300,13 @@ func (api *Router) GetTranscodeDecision(w http.ResponseWriter, r *http.Request)
 		}
 	}
 
-	// Apply the player's MaxBitRate as a ceiling on the client's declared
-	// limits (issue #5583). Both fields are capped because the client sends
-	// them independently here; capping only MaxAudioBitrate would let an
-	// independent MaxTranscodingAudioBitrate slip through computeBitrate.
-	if player, ok := request.PlayerFrom(ctx); ok && clientInfo.CapBitrate(player.MaxBitRate) {
-		log.Debug(ctx, "Applied player MaxBitRate cap to transcode decision",
-			"playerMaxBitRate", player.MaxBitRate, "client", clientInfo.Name)
+	// The player's own MaxBitRate outranks the forced-format default (issue #5583).
+	if hasPlayer && player.MaxBitRate > 0 {
+		maxBitRate = player.MaxBitRate
+	}
+	if clientInfo.CapBitrate(maxBitRate) {
+		log.Debug(ctx, "Applied bitrate ceiling to transcode decision",
+			"maxBitRate", maxBitRate, "client", clientInfo.Name)
 	}
 
 	// Get media file
diff --git a/server/subsonic/transcode_test.go b/server/subsonic/transcode_test.go
index 8d5cbb974..0f3c24832 100644
--- a/server/subsonic/transcode_test.go
+++ b/server/subsonic/transcode_test.go
@@ -369,7 +369,7 @@ var _ = Describe("Transcode endpoints", func() {
 				mockTD.token = "token"
 			})
 
-			It("forces a supported format and clears direct play", func() {
+			It("forces a supported format and narrows direct play to it", func() {
 				body := `{"directPlayProfiles":[{"containers":["flac"],"audioCodecs":["flac"],"protocols":["http"]}],
 					"transcodingProfiles":[{"container":"ogg","audioCodec":"opus","protocol":"http"},
 						{"container":"mp3","audioCodec":"mp3","protocol":"http"}]}`
@@ -380,7 +380,11 @@ var _ = Describe("Transcode endpoints", func() {
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockTD.capturedClient.TranscodingProfiles).To(HaveLen(1))
 				Expect(mockTD.capturedClient.TranscodingProfiles[0].AudioCodec).To(Equal("opus"))
-				Expect(mockTD.capturedClient.DirectPlayProfiles).To(BeEmpty())
+				Expect(mockTD.capturedClient.DirectPlayProfiles).To(ConsistOf(stream.DirectPlayProfile{
+					Containers:  []string{"ogg"},
+					AudioCodecs: []string{"opus"},
+					Protocols:   []string{"http"},
+				}))
 			})
 
 			It("falls back to negotiation when the forced format is unsupported", func() {
@@ -416,6 +420,43 @@ var _ = Describe("Transcode endpoints", func() {
 				Expect(mockTD.capturedClient.MaxAudioBitrate).To(Equal(128))
 				Expect(mockTD.capturedClient.MaxTranscodingAudioBitrate).To(Equal(128))
 			})
+
+			withForcedBitRate := func(r *http.Request, format string, defaultBitRate, playerMaxBitRate int) *http.Request {
+				ctx := request.WithTranscoding(r.Context(), model.Transcoding{TargetFormat: format, DefaultBitRate: defaultBitRate})
+				ctx = request.WithPlayer(ctx, model.Player{Client: "NavidromeUI", MaxBitRate: playerMaxBitRate})
+				return r.WithContext(ctx)
+			}
+
+			It("applies the transcoding default bitrate when the player sets no maxBitRate", func() {
+				body := `{"transcodingProfiles":[{"container":"mp3","audioCodec":"mp3","protocol":"http"}]}`
+				r := withForcedBitRate(newJSONPostRequest("mediaId=song-1&mediaType=song", body), "mp3", 192, 0)
+
+				_, err := router.GetTranscodeDecision(w, r)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockTD.capturedClient.MaxAudioBitrate).To(Equal(192))
+				Expect(mockTD.capturedClient.MaxTranscodingAudioBitrate).To(Equal(192))
+			})
+
+			It("prefers the player maxBitRate over the transcoding default bitrate", func() {
+				body := `{"transcodingProfiles":[{"container":"mp3","audioCodec":"mp3","protocol":"http"}]}`
+				r := withForcedBitRate(newJSONPostRequest("mediaId=song-1&mediaType=song", body), "mp3", 192, 320)
+
+				_, err := router.GetTranscodeDecision(w, r)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockTD.capturedClient.MaxAudioBitrate).To(Equal(320))
+			})
+
+			It("ignores the transcoding default bitrate when the forced format is unsupported", func() {
+				body := `{"transcodingProfiles":[{"container":"mp3","audioCodec":"mp3","protocol":"http"}]}`
+				r := withForcedBitRate(newJSONPostRequest("mediaId=song-1&mediaType=song", body), "opus", 192, 0)
+
+				_, err := router.GetTranscodeDecision(w, r)
+
+				Expect(err).ToNot(HaveOccurred())
+				Expect(mockTD.capturedClient.MaxAudioBitrate).To(BeZero())
+			})
 		})
 	})
 

From 89026012ab3d9aeddcd7bbdf965fa9d6e0806b62 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Mon, 7 Sep 2026 14:19:45 -0400
Subject: [PATCH 119/200] fix(transcoding): make piped FLAC transcodes seekable

The FLAC muxer writes STREAMINFO before it knows the stream length, then
rewinds at the end to fill total_samples in. Navidrome pipes ffmpeg's stdout
(-f flac -), which is not seekable, so ffmpeg logs "unable to rewrite FLAC
header" and the field stays 0. A decoder needs total_samples to turn a
timestamp into a byte offset, so it reports an unknown duration and refuses to
seek. Online playback hides this because the client re-requests with a new
offset each time, but an offline copy is permanently unseekable, the symptom
reported against Symfonium where seeking a downloaded track jumps back to the
start.

Transcode now wraps its own output and rewrites total_samples as the first
bytes flow past. This lives in core/ffmpeg because the unseekable pipe is that
package's doing: buildDynamicArgs is what appends the trailing '-'. core/stream
only learns a target format and hands back an io.ReadCloser, so compensating
there leaked a transcoder implementation detail one layer up. TranscodeOptions
grows a Duration field alongside the existing Offset, which also puts the
duration-minus-offset arithmetic in the same function that emits -ss.

The wrapper runs on every transcode rather than only FLAC targets: the format
on a transcoding row is a declared target that nothing validates against the
command's actual -f, so a custom command can emit FLAC under any target_format.
The magic-byte check inside the wrapper is the authoritative test and costs a
26-byte peek. The output sample rate is read back out of the header ffmpeg just
wrote rather than taken from the transcode options, so a resampled (-ar) output
still gets the right count. Anything that is not a FLAC stream with an unset
total_samples passes through byte for byte.

Measured on a 177s source: before, total_samples=0 and ffprobe reported
duration N/A; after, total_samples=7807023 and duration 177.03s, with the audio
payload byte-identical. This affects every piped FLAC regardless of the source
format; only FLAC stores an authoritative "unknown", which is why mp3, opus
and aac survive the same pipe.

No SEEKTABLE is synthesised and the MD5 is left zero: both are optional, and
decoders binary-search using total_samples alone.
---
 core/ffmpeg/ffmpeg.go               |  17 ++--
 core/ffmpeg/ffmpeg_test.go          |  35 +++++++
 core/ffmpeg/flac_streaminfo.go      |  66 +++++++++++++
 core/ffmpeg/flac_streaminfo_test.go | 142 ++++++++++++++++++++++++++++
 core/stream/media_streamer.go       |   1 +
 5 files changed, 255 insertions(+), 6 deletions(-)
 create mode 100644 core/ffmpeg/flac_streaminfo.go
 create mode 100644 core/ffmpeg/flac_streaminfo_test.go

diff --git a/core/ffmpeg/ffmpeg.go b/core/ffmpeg/ffmpeg.go
index af2dab647..cc38dd9de 100644
--- a/core/ffmpeg/ffmpeg.go
+++ b/core/ffmpeg/ffmpeg.go
@@ -27,11 +27,12 @@ type TranscodeOptions struct {
 	Command    string // DB command template (used to detect custom vs default)
 	Format     string // Target format (mp3, opus, aac, flac)
 	FilePath   string
-	BitRate    int // kbps, 0 = codec default
-	SampleRate int // 0 = no constraint
-	Channels   int // 0 = no constraint
-	BitDepth   int // 0 = no constraint; valid values: 16, 24, 32
-	Offset     int // seconds
+	BitRate    int     // kbps, 0 = codec default
+	SampleRate int     // 0 = no constraint
+	Channels   int     // 0 = no constraint
+	BitDepth   int     // 0 = no constraint; valid values: 16, 24, 32
+	Offset     int     // seconds
+	Duration   float32 // seconds; 0 = unknown. Only used to repair a piped FLAC header.
 }
 
 // AudioProbeResult contains authoritative audio stream properties from ffprobe.
@@ -86,7 +87,11 @@ func (e *ffmpeg) Transcode(ctx context.Context, opts TranscodeOptions) (io.ReadC
 	} else {
 		args = buildTemplateArgs(opts)
 	}
-	return e.start(ctx, args)
+	out, err := e.start(ctx, args)
+	if err != nil {
+		return nil, err
+	}
+	return patchFLACDuration(out, opts.Duration-float32(opts.Offset)), nil
 }
 
 func (e *ffmpeg) ConvertAnimatedImage(ctx context.Context, reader io.Reader, maxSize int, quality int) (io.ReadCloser, error) {
diff --git a/core/ffmpeg/ffmpeg_test.go b/core/ffmpeg/ffmpeg_test.go
index 0fa3de111..dbc8fa3c8 100644
--- a/core/ffmpeg/ffmpeg_test.go
+++ b/core/ffmpeg/ffmpeg_test.go
@@ -3,6 +3,7 @@ package ffmpeg
 import (
 	"context"
 	"errors"
+	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -684,6 +685,40 @@ var _ = Describe("ffmpeg", func() {
 				})
 				Expect(err).To(MatchError(context.Canceled))
 			})
+
+			It("fills in total_samples on a piped FLAC transcode", func() {
+				stream, err := ff.Transcode(GinkgoT().Context(), TranscodeOptions{
+					Command:  "ffmpeg -i %s -map 0:a:0 -v 0 -c:a flac -f flac -",
+					Format:   "flac",
+					FilePath: "tests/fixtures/test.flac",
+					Duration: 1, // the fixture is exactly 1s at 44100Hz
+				})
+				Expect(err).ToNot(HaveOccurred())
+				defer stream.Close()
+
+				out, err := io.ReadAll(stream)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(string(out[:4])).To(Equal("fLaC"))
+				Expect(readTotalSamples(out)).To(Equal(uint64(44100)))
+			})
+
+			It("patches the duration net of the requested offset", func() {
+				// The command has no %t, so ffmpeg still emits the whole fixture.
+				// What is under test is the header arithmetic, not the audio.
+				stream, err := ff.Transcode(GinkgoT().Context(), TranscodeOptions{
+					Command:  "ffmpeg -i %s -map 0:a:0 -v 0 -c:a flac -f flac -",
+					Format:   "flac",
+					FilePath: "tests/fixtures/test.flac",
+					Duration: 3,
+					Offset:   1,
+				})
+				Expect(err).ToNot(HaveOccurred())
+				defer stream.Close()
+
+				out, err := io.ReadAll(stream)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(readTotalSamples(out)).To(Equal(uint64(2 * 44100)))
+			})
 		})
 
 		Context("stderr capture", func() {
diff --git a/core/ffmpeg/flac_streaminfo.go b/core/ffmpeg/flac_streaminfo.go
new file mode 100644
index 000000000..878c28718
--- /dev/null
+++ b/core/ffmpeg/flac_streaminfo.go
@@ -0,0 +1,66 @@
+package ffmpeg
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"io"
+	"math"
+)
+
+const (
+	flacPrefixLen       = 26 // through the last total_samples byte
+	flacMaxTotalSamples = 1<<36 - 1
+)
+
+// patchFLACDuration fills in the STREAMINFO total_samples that ffmpeg leaves at 0
+// when writing to a pipe, since a decoder cannot seek a cached FLAC without it.
+func patchFLACDuration(r io.ReadCloser, duration float32) io.ReadCloser {
+	if duration <= 0 {
+		return r
+	}
+	return &flacPatcher{ReadCloser: r, duration: duration}
+}
+
+type flacPatcher struct {
+	io.ReadCloser
+	duration float32
+	// Peeking here rather than in the constructor keeps Transcode from blocking
+	// until ffmpeg has emitted its first bytes.
+	stream io.Reader
+}
+
+func (f *flacPatcher) Read(p []byte) (int, error) {
+	if f.stream == nil {
+		prefix := make([]byte, flacPrefixLen)
+		n, err := io.ReadFull(f.ReadCloser, prefix)
+		if err != nil && !errors.Is(err, io.EOF) && !errors.Is(err, io.ErrUnexpectedEOF) {
+			return 0, err
+		}
+		prefix = prefix[:n]
+		if err == nil {
+			setFLACTotalSamples(prefix, f.duration)
+		}
+		f.stream = io.MultiReader(bytes.NewReader(prefix), f.ReadCloser)
+	}
+	return f.stream.Read(p)
+}
+
+// setFLACTotalSamples takes the rate from the header rather than the transcode
+// options, so a resampled (-ar) output still gets the right count.
+func setFLACTotalSamples(prefix []byte, duration float32) {
+	if string(prefix[:4]) != "fLaC" || prefix[4]&0x7F != 0 {
+		return
+	}
+	// 20-bit rate | 3-bit channels | 5-bit depth | 36-bit total_samples
+	info := binary.BigEndian.Uint64(prefix[18:])
+	rate := info >> 44
+	if rate == 0 || info&flacMaxTotalSamples != 0 {
+		return
+	}
+	total := math.Round(float64(duration) * float64(rate))
+	if total > flacMaxTotalSamples {
+		return
+	}
+	binary.BigEndian.PutUint64(prefix[18:], info|uint64(total))
+}
diff --git a/core/ffmpeg/flac_streaminfo_test.go b/core/ffmpeg/flac_streaminfo_test.go
new file mode 100644
index 000000000..6bf3503d7
--- /dev/null
+++ b/core/ffmpeg/flac_streaminfo_test.go
@@ -0,0 +1,142 @@
+package ffmpeg
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"os"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Decoded independently so the specs do not mirror the production bit-twiddling.
+func readSampleRate(b []byte) int {
+	return int(b[18])<<12 | int(b[19])<<4 | int(b[20])>>4
+}
+
+func readTotalSamples(b []byte) uint64 {
+	return uint64(b[21]&0x0F)<<32 | uint64(b[22])<<24 | uint64(b[23])<<16 | uint64(b[24])<<8 | uint64(b[25])
+}
+
+var _ = Describe("patchFLACDuration", func() {
+	var fileFLAC []byte
+
+	// Zeroing total_samples reproduces what a piped transcode emits.
+	pipedFLAC := func() []byte {
+		b := bytes.Clone(fileFLAC)
+		b[21] &= 0xF0
+		clear(b[22:26])
+		return b
+	}
+
+	readAll := func(in []byte, duration float32) []byte {
+		out, err := io.ReadAll(patchFLACDuration(io.NopCloser(bytes.NewReader(in)), duration))
+		Expect(err).ToNot(HaveOccurred())
+		return out
+	}
+
+	BeforeEach(func() {
+		var err error
+		fileFLAC, err = os.ReadFile("tests/fixtures/test.flac")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(readSampleRate(fileFLAC)).To(Equal(44100)) // specs below hard-code this rate
+	})
+
+	It("fills in total_samples from the duration", func() {
+		out := readAll(pipedFLAC(), 1.0)
+		Expect(readTotalSamples(out)).To(Equal(uint64(44100)))
+	})
+
+	It("takes the sample rate from the header, not from the source file", func() {
+		in := pipedFLAC()
+		// Rewrite the header's rate to 48000, as -ar would.
+		in[18], in[19] = 0x0B, 0xB8
+		in[20] &= 0x0F
+
+		out := readAll(in, 2.0)
+
+		Expect(readSampleRate(out)).To(Equal(48000))
+		Expect(readTotalSamples(out)).To(Equal(uint64(96000)))
+	})
+
+	It("rounds to the nearest sample rather than truncating", func() {
+		// float32(0.7)*44100 is 30869.9995, so truncation would lose a sample.
+		out := readAll(pipedFLAC(), 0.7)
+		Expect(readTotalSamples(out)).To(Equal(uint64(30870)))
+	})
+
+	It("passes through when the duration overflows the 36-bit field", func() {
+		in := pipedFLAC()
+		Expect(readAll(in, 2e6)).To(Equal(in))
+	})
+
+	It("leaves everything after the header untouched", func() {
+		in := pipedFLAC()
+		out := readAll(in, 1.0)
+		Expect(out).To(HaveLen(len(in)))
+		Expect(out[26:]).To(Equal(in[26:]))
+		Expect(out[:18]).To(Equal(in[:18]))
+	})
+
+	It("leaves an already-populated total_samples alone", func() {
+		out := readAll(fileFLAC, 99.0)
+		Expect(out).To(Equal(fileFLAC))
+	})
+
+	It("passes through a stream that is not FLAC", func() {
+		in := []byte("ID3\x04\x00\x00\x00\x00\x00\x00 not a flac stream at all, just bytes")
+		Expect(readAll(in, 1.0)).To(Equal(in))
+	})
+
+	It("passes through when the first metadata block is not STREAMINFO", func() {
+		in := pipedFLAC()
+		in[4] = 0x04 // VORBIS_COMMENT
+		Expect(readAll(in, 1.0)).To(Equal(in))
+	})
+
+	It("passes through a stream shorter than the STREAMINFO fields it patches", func() {
+		in := pipedFLAC()[:20]
+		Expect(readAll(in, 1.0)).To(Equal(in))
+	})
+
+	It("passes through an empty stream", func() {
+		Expect(readAll(nil, 1.0)).To(BeEmpty())
+	})
+
+	It("passes through when the duration is zero or negative", func() {
+		in := pipedFLAC()
+		Expect(readAll(in, 0)).To(Equal(in))
+		Expect(readAll(in, -5)).To(Equal(in))
+	})
+
+	It("passes through when the header declares no sample rate", func() {
+		in := pipedFLAC()
+		in[18], in[19] = 0, 0
+		in[20] &= 0x0F
+		Expect(readAll(in, 1.0)).To(Equal(in))
+	})
+
+	It("propagates a read error from the underlying stream", func() {
+		_, err := io.ReadAll(patchFLACDuration(io.NopCloser(io.MultiReader(
+			bytes.NewReader(pipedFLAC()[:10]), &errReader{})), 1.0))
+		Expect(err).To(MatchError("boom"))
+	})
+
+	It("closes the underlying stream", func() {
+		c := &closeSpy{Reader: bytes.NewReader(pipedFLAC())}
+		Expect(patchFLACDuration(c, 1.0).Close()).To(Succeed())
+		Expect(c.closed).To(BeTrue())
+	})
+})
+
+type errReader struct{}
+
+func (e *errReader) Read([]byte) (int, error) { return 0, errors.New("boom") }
+
+type closeSpy struct {
+	io.Reader
+	closed bool
+}
+
+func (c *closeSpy) Close() error { c.closed = true; return nil }
diff --git a/core/stream/media_streamer.go b/core/stream/media_streamer.go
index aaa3126b4..6db2f6338 100644
--- a/core/stream/media_streamer.go
+++ b/core/stream/media_streamer.go
@@ -268,6 +268,7 @@ func NewTranscodingCache() TranscodingCache {
 				BitDepth:   job.bitDepth,
 				Channels:   job.channels,
 				Offset:     job.offset,
+				Duration:   job.mf.Duration,
 			})
 			if err != nil {
 				release()

From bea9715001abc956c712f76bf87cd93fd41bd6f1 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Tue, 8 Sep 2026 18:51:49 -0400
Subject: [PATCH 120/200] refactor(ui): replace icons in LibraryScanButton with
 react-icons

---
 ui/src/library/LibraryScanButton.jsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/ui/src/library/LibraryScanButton.jsx b/ui/src/library/LibraryScanButton.jsx
index 50d90e615..b793844fd 100644
--- a/ui/src/library/LibraryScanButton.jsx
+++ b/ui/src/library/LibraryScanButton.jsx
@@ -8,8 +8,8 @@ import {
   useUnselectAll,
 } from 'react-admin'
 import { useSelector } from 'react-redux'
-import SyncIcon from '@material-ui/icons/Sync'
-import CachedIcon from '@material-ui/icons/Cached'
+import { GiMagnifyingGlass } from 'react-icons/gi'
+import { VscSync } from 'react-icons/vsc'
 import subsonic from '../subsonic'
 
 const LibraryScanButton = ({ fullScan, selectedIds, className }) => {
@@ -54,7 +54,7 @@ const LibraryScanButton = ({ fullScan, selectedIds, className }) => {
     ? translate('resources.library.actions.fullScan')
     : translate('resources.library.actions.quickScan')
 
-  const icon = fullScan ? <CachedIcon /> : <SyncIcon />
+  const icon = fullScan ? <GiMagnifyingGlass /> : <VscSync />
 
   return (
     <Button

From 043de7a86c0afa0317a926c8a08c6038bb2c5e3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 9 Sep 2026 10:42:54 -0400
Subject: [PATCH 121/200] docs(jellyfin): correct the rationale for the public
 image endpoint (#6114)

The comment justified anonymous access with "item ids are unguessable".
That is not true: an artist id is a deterministic, unsalted hash of the
artist name, id.NewHash(id.NewHash(str.Clear(lower(name)))), so it is
computable offline by anyone who knows the name.

The real reason the route is public is that upstream Jellyfin's is too.
ImageController.GetItemImage carries no [Authorize] attribute (verified on
v12.0, master/13.0.0, v10.11.9 and v10.10.7), and an anonymous request
reaches LibraryManager.ItemIsVisible with a null user, which returns true
unconditionally. Clients build cover URLs with no credentials at all, so
requiring auth here would break them.

No behavior change.
---
 server/jellyfin/images.go | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/server/jellyfin/images.go b/server/jellyfin/images.go
index fcf69c039..9f1b9ce1a 100644
--- a/server/jellyfin/images.go
+++ b/server/jellyfin/images.go
@@ -34,8 +34,8 @@ func imageSize(maxWidth, maxHeight int) int {
 }
 
 func (api *Router) getItemImage(w http.ResponseWriter, r *http.Request) {
-	// Public endpoint, like real Jellyfin's image routes: clients fetch cover URLs without credentials
-	// and item ids are unguessable, so resolution runs elevated to bypass the visibility filter.
+	// Public, like Jellyfin's own image routes: clients build cover URLs without credentials, and
+	// upstream resolves them with no visibility check either (LibraryManager.ItemIsVisible, null user).
 	ctx := request.WithUser(r.Context(), model.User{IsAdmin: true})
 	itemId, ok := itemIDParam(w, r, "itemId")
 	if !ok {

From fe1c87c190eff85271b16525327599adb204d356 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 9 Sep 2026 10:52:15 -0400
Subject: [PATCH 122/200] fix(ui): round the album grid hover overlay in the
 Nautiline theme (#6115)

The theme rounded the cover image directly and set a border radius on
albumContainer, which has no background or clipping, so it rounded
nothing. The hover overlay is a sibling of the image inside the same
link, so it kept square corners that poked out over the rounded cover.

Move the radius to that link and clip it, so both the image and the
overlay follow the same rounded box. This also covers the mobile bar,
which is always visible.

Fixes #6110
---
 ui/src/themes/nautiline.js  |  6 ++----
 ui/src/themes/theme.test.js | 22 ++++++++++++++++++++++
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/ui/src/themes/nautiline.js b/ui/src/themes/nautiline.js
index 0c13dc0ec..9194ad7a0 100644
--- a/ui/src/themes/nautiline.js
+++ b/ui/src/themes/nautiline.js
@@ -598,11 +598,9 @@ const NautilineTheme = {
       },
     },
     NDAlbumGridView: {
-      albumContainer: {
+      link: {
         borderRadius: radii.md,
-        '& img': {
-          borderRadius: radii.md,
-        },
+        overflow: 'hidden',
       },
       albumTitle: {
         fontWeight: 600,
diff --git a/ui/src/themes/theme.test.js b/ui/src/themes/theme.test.js
index b65c3a5fe..a015ae696 100644
--- a/ui/src/themes/theme.test.js
+++ b/ui/src/themes/theme.test.js
@@ -12,3 +12,25 @@ describe('NDPlaylistDetails styles', () => {
     },
   )
 })
+
+describe('NDAlbumGridView styles', () => {
+  const themeEntries = Object.entries(themes)
+
+  // The hover overlay is a sibling of the image, so it keeps square corners.
+  it.each(themeEntries)(
+    '%s should not round the grid cover image on its own',
+    (themeName, theme) => {
+      const container = theme.overrides?.NDAlbumGridView?.albumContainer
+      expect(container?.['& img']?.borderRadius).toBeUndefined()
+    },
+  )
+
+  it.each(themeEntries)(
+    '%s should clip the grid cover link when it is rounded',
+    (themeName, theme) => {
+      const link = theme.overrides?.NDAlbumGridView?.link
+      if (!link?.borderRadius) return
+      expect(link.overflow).toBe('hidden')
+    },
+  )
+})

From 02c9816aec605a8403263a3cc1a0e4af69e22782 Mon Sep 17 00:00:00 2001
From: MIguel Lopes <miguel.lopes@miguelallopes.dev>
Date: Wed, 9 Sep 2026 16:38:59 +0100
Subject: [PATCH 123/200] build(docker): add curl to container image (#6111)
 (#6116)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Miguel Lopes <miguel.lopes@miguelallopes.dev>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 Dockerfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Dockerfile b/Dockerfile
index 3427d6806..5fc0529f0 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -187,7 +187,7 @@ LABEL org.opencontainers.image.source="https://github.com/navidrome/navidrome"
 # - libwebp + symlinks: enables native WebP encoding via purego/dlopen
 # The mesa/LLVM stack mpv pulls in for video output is dropped in this same layer,
 # otherwise the deleted bytes still ship in the image.
-RUN apk add -U --no-cache ffmpeg mpv sqlite libwebp libwebpdemux libwebpmux && \
+RUN apk add -U --no-cache curl 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; \

From 8d77a49b31d97e3c1554c8cc811b53a8a23e40a2 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 9 Sep 2026 16:09:58 -0400
Subject: [PATCH 124/200] fix(ui): allow setting a transcoding Default Bit Rate
 of 0

The Default Bit Rate dropdown on the Transcoding create/edit forms was fed
BITRATE_CHOICES, which starts at 32. There was no way to pick 0, and the
SelectInput was not resettable, so an admin could neither create nor restore a
transcoding with no default bit rate, such as the default FLAC one (seeded with
0 in consts.DefaultTranscodings). Editing that row also rendered a blank
dropdown, since its stored value matched no choice.

Adds TRANSCODING_BITRATE_CHOICES, which prepends a 0 entry labelled 'None' to
the shared list. The forms use it as SelectInput choices, and the list and
read-only show view render it through SelectField, so all four screens resolve
the label from the same array and cannot drift. The shared BITRATE_CHOICES is
left untouched, because 0 is not a meaningful option for the player Max. Bit
Rate or the share dialog.

Reported in discussion #6107, where a user had deleted the default
transcodings and could not recreate the FLAC one.
---
 ui/src/consts.js                         |  6 ++++++
 ui/src/i18n/en.json                      |  3 +++
 ui/src/transcoding/TranscodingCreate.jsx |  4 ++--
 ui/src/transcoding/TranscodingEdit.jsx   |  7 +++++--
 ui/src/transcoding/TranscodingList.jsx   | 16 +++++++++++++---
 ui/src/transcoding/TranscodingShow.jsx   |  8 ++++++--
 6 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/ui/src/consts.js b/ui/src/consts.js
index 472cd4940..46c76e194 100644
--- a/ui/src/consts.js
+++ b/ui/src/consts.js
@@ -31,3 +31,9 @@ export const DEFAULT_SHARE_BITRATE = 128
 export const BITRATE_CHOICES = [
   32, 48, 64, 80, 96, 112, 128, 160, 192, 256, 320,
 ].map((b) => ({ id: b, name: b.toString() }))
+
+// 0 is a valid stored value ("no default bit rate") that BITRATE_CHOICES cannot express.
+export const TRANSCODING_BITRATE_CHOICES = [
+  { id: 0, name: 'resources.transcoding.choices.noDefaultBitRate' },
+  ...BITRATE_CHOICES,
+]
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index de96d47c0..fd200fa60 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -200,6 +200,9 @@
         "targetFormat": "Target Format",
         "defaultBitRate": "Default Bit Rate",
         "command": "Command"
+      },
+      "choices": {
+        "noDefaultBitRate": "None"
       }
     },
     "playlist": {
diff --git a/ui/src/transcoding/TranscodingCreate.jsx b/ui/src/transcoding/TranscodingCreate.jsx
index aaf122665..014a94e48 100644
--- a/ui/src/transcoding/TranscodingCreate.jsx
+++ b/ui/src/transcoding/TranscodingCreate.jsx
@@ -8,7 +8,7 @@ import {
   useTranslate,
 } from 'react-admin'
 import { Title } from '../common'
-import { BITRATE_CHOICES } from '../consts'
+import { TRANSCODING_BITRATE_CHOICES } from '../consts'
 
 const TranscodingTitle = () => {
   const translate = useTranslate()
@@ -28,7 +28,7 @@ const TranscodingCreate = (props) => (
       <TextInput source="targetFormat" validate={[required()]} />
       <SelectInput
         source="defaultBitRate"
-        choices={BITRATE_CHOICES}
+        choices={TRANSCODING_BITRATE_CHOICES}
         defaultValue={192}
       />
       <TextInput
diff --git a/ui/src/transcoding/TranscodingEdit.jsx b/ui/src/transcoding/TranscodingEdit.jsx
index 5aba9a4e3..bf500920f 100644
--- a/ui/src/transcoding/TranscodingEdit.jsx
+++ b/ui/src/transcoding/TranscodingEdit.jsx
@@ -9,7 +9,7 @@ import {
 } from 'react-admin'
 import { Title } from '../common'
 import { TranscodingNote } from './TranscodingNote'
-import { BITRATE_CHOICES } from '../consts'
+import { TRANSCODING_BITRATE_CHOICES } from '../consts'
 
 const TranscodingTitle = ({ record }) => {
   const translate = useTranslate()
@@ -28,7 +28,10 @@ const TranscodingEdit = (props) => {
         <SimpleForm variant={'outlined'}>
           <TextInput source="name" validate={[required()]} />
           <TextInput source="targetFormat" validate={[required()]} />
-          <SelectInput source="defaultBitRate" choices={BITRATE_CHOICES} />
+          <SelectInput
+            source="defaultBitRate"
+            choices={TRANSCODING_BITRATE_CHOICES}
+          />
           <TextInput source="command" fullWidth validate={[required()]} />
         </SimpleForm>
       </Edit>
diff --git a/ui/src/transcoding/TranscodingList.jsx b/ui/src/transcoding/TranscodingList.jsx
index bca8b49df..d1371c04a 100644
--- a/ui/src/transcoding/TranscodingList.jsx
+++ b/ui/src/transcoding/TranscodingList.jsx
@@ -1,7 +1,8 @@
 import React from 'react'
-import { Datagrid, TextField } from 'react-admin'
+import { Datagrid, SelectField, TextField } from 'react-admin'
 import { useMediaQuery } from '@material-ui/core'
 import { SimpleList, List } from '../common'
+import { TRANSCODING_BITRATE_CHOICES } from '../consts'
 import config from '../config'
 
 const TranscodingList = (props) => {
@@ -16,13 +17,22 @@ const TranscodingList = (props) => {
         <SimpleList
           primaryText={(r) => r.name}
           secondaryText={(r) => `format: ${r.targetFormat}`}
-          tertiaryText={(r) => r.defaultBitRate}
+          tertiaryText={(r) => (
+            <SelectField
+              record={r}
+              source="defaultBitRate"
+              choices={TRANSCODING_BITRATE_CHOICES}
+            />
+          )}
         />
       ) : (
         <Datagrid rowClick={config.enableTranscodingConfig ? 'edit' : 'show'}>
           <TextField source="name" />
           <TextField source="targetFormat" />
-          <TextField source="defaultBitRate" />
+          <SelectField
+            source="defaultBitRate"
+            choices={TRANSCODING_BITRATE_CHOICES}
+          />
           <TextField source="command" />
         </Datagrid>
       )}
diff --git a/ui/src/transcoding/TranscodingShow.jsx b/ui/src/transcoding/TranscodingShow.jsx
index e132afee5..b7ec2f595 100644
--- a/ui/src/transcoding/TranscodingShow.jsx
+++ b/ui/src/transcoding/TranscodingShow.jsx
@@ -1,7 +1,8 @@
 import React from 'react'
-import { Show, SimpleShowLayout, TextField } from 'react-admin'
+import { SelectField, Show, SimpleShowLayout, TextField } from 'react-admin'
 import { Title } from '../common'
 import { TranscodingNote } from './TranscodingNote'
+import { TRANSCODING_BITRATE_CHOICES } from '../consts'
 
 const TranscodingTitle = ({ record }) => {
   return <Title subTitle={`Transcoding ${record ? record.name : ''}`} />
@@ -16,7 +17,10 @@ const TranscodingShow = (props) => {
         <SimpleShowLayout>
           <TextField source="name" />
           <TextField source="targetFormat" />
-          <TextField source="defaultBitRate" />
+          <SelectField
+            source="defaultBitRate"
+            choices={TRANSCODING_BITRATE_CHOICES}
+          />
           <TextField source="command" />
         </SimpleShowLayout>
       </Show>

From 72975a95fbe123a4684bdeb8361b58b0b245cc24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 9 Sep 2026 20:29:00 -0400
Subject: [PATCH 125/200] fix(subsonic): honor DefaultDownloadableShare in
 createShare (#6121)

* fix(subsonic): honor DefaultDownloadableShare in createShare

The DefaultDownloadableShare option was only sent to the web UI, which used
it to pre-tick the "Allow Downloads?" checkbox. The Subsonic createShare
handler built the model.Share without touching Downloadable, so it fell back
to the Go zero value and every share created through the API was stored as
non-downloadable, regardless of the configured default.

createShare now reads an optional downloadable parameter and falls back to
conf.Server.DefaultDownloadableShare when the client omits it, matching the
web UI. Fixes #6119.

updateShare had a related problem: core's share repository wrapper always
writes the downloadable column, but the handler never set the field, so any
updateShare call silently reset the share to non-downloadable. It now loads
the current share and uses its value as the fallback.

* refactor(subsonic): trim the share downloadable lookup and align with the UI

updateShare fetched the share with Get to recover the stored downloadable
flag, which also runs loadMedia and materializes every album and track the
share points at, just to read one boolean. It now uses Read, which skips
loadMedia, and only queries at all when the client omitted the parameter.

createShare now ANDs the default with EnableDownloads, matching what the web
UI already computes, so both paths apply the same rule.

The specs collapse the create-path matrix into a DescribeTable, reuse the
existing albumIDByName helper, and set the request-time config after
setupTestDB so it does not leak into the config snapshot.

* fix(subsonic): keep the share description on a downloadable-only update

updateShare read the description straight from the request, so a client that
sent only id and downloadable got an empty string written over the stored
description. shareRepositoryWrapper.Update always writes that column, so the
description was silently erased.

This predates the downloadable parameter added earlier in this branch: any
updateShare that omitted description already cleared it. Adding the parameter
just made it easy to hit, since toggling downloads is a natural reason to call
updateShare without touching the description.

Both fields now use the presence-aware accessors and fall back to the stored
share, which still costs at most one read and none when the client sends both.
An explicitly empty description still clears the field.
---
 server/subsonic/e2e/subsonic_sharing_test.go | 73 ++++++++++++++++++++
 server/subsonic/sharing.go                   | 32 +++++++--
 2 files changed, 98 insertions(+), 7 deletions(-)

diff --git a/server/subsonic/e2e/subsonic_sharing_test.go b/server/subsonic/e2e/subsonic_sharing_test.go
index 0421d96ea..1ae68dc1a 100644
--- a/server/subsonic/e2e/subsonic_sharing_test.go
+++ b/server/subsonic/e2e/subsonic_sharing_test.go
@@ -205,3 +205,76 @@ var _ = Describe("Sharing Cross-User Isolation", Ordered, func() {
 		Expect(check.Shares.Share[0].ID).To(Equal(shareID))
 	})
 })
+
+var _ = Describe("Sharing Downloadable Default", func() {
+	var albumID string
+
+	BeforeEach(func() {
+		conf.Server.EnableSharing = true
+		setupTestDB()
+		conf.Server.EnableDownloads = true
+		albumID = albumIDByName("Abbey Road")
+	})
+
+	createShare := func(params ...string) *model.Share {
+		GinkgoHelper()
+		resp := doReq("createShare", append([]string{"id", albumID}, params...)...)
+		Expect(resp.Status).To(Equal(responses.StatusOK))
+		Expect(resp.Shares.Share).To(HaveLen(1))
+		share, err := ds.Share(ctx).Get(resp.Shares.Share[0].ID)
+		Expect(err).ToNot(HaveOccurred())
+		return share
+	}
+
+	DescribeTable("createShare resolves downloadable",
+		func(defaultDownloadable, enableDownloads bool, params []string, expected bool) {
+			conf.Server.DefaultDownloadableShare = defaultDownloadable
+			conf.Server.EnableDownloads = enableDownloads
+
+			Expect(createShare(params...).Downloadable).To(Equal(expected))
+		},
+		Entry("applies the default when the param is absent", true, true, nil, true),
+		Entry("stays off when the default is off", false, true, nil, false),
+		Entry("ignores the default when downloads are disabled", true, false, nil, false),
+		Entry("honors an explicit false over the default", true, true, []string{"downloadable", "false"}, false),
+		Entry("honors an explicit true over the default", false, true, []string{"downloadable", "true"}, true),
+	)
+
+	It("updateShare keeps the current downloadable when the param is absent", func() {
+		conf.Server.DefaultDownloadableShare = true
+		share := createShare()
+		Expect(share.Downloadable).To(BeTrue())
+
+		resp := doReq("updateShare", "id", share.ID, "description", "Updated")
+		Expect(resp.Status).To(Equal(responses.StatusOK))
+
+		updated, err := ds.Share(ctx).Get(share.ID)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(updated.Description).To(Equal("Updated"))
+		Expect(updated.Downloadable).To(BeTrue())
+	})
+
+	It("updateShare applies an explicit downloadable and keeps the description", func() {
+		conf.Server.DefaultDownloadableShare = true
+		share := createShare("description", "Keep me")
+
+		resp := doReq("updateShare", "id", share.ID, "downloadable", "false")
+		Expect(resp.Status).To(Equal(responses.StatusOK))
+
+		updated, err := ds.Share(ctx).Get(share.ID)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(updated.Downloadable).To(BeFalse())
+		Expect(updated.Description).To(Equal("Keep me"))
+	})
+
+	It("updateShare clears the description when it is sent empty", func() {
+		share := createShare("description", "Clear me")
+
+		resp := doReq("updateShare", "id", share.ID, "description", "")
+		Expect(resp.Status).To(Equal(responses.StatusOK))
+
+		updated, err := ds.Share(ctx).Get(share.ID)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(updated.Description).To(BeEmpty())
+	})
+})
diff --git a/server/subsonic/sharing.go b/server/subsonic/sharing.go
index 36124c40b..c4b735832 100644
--- a/server/subsonic/sharing.go
+++ b/server/subsonic/sharing.go
@@ -1,11 +1,13 @@
 package subsonic
 
 import (
+	"cmp"
 	"net/http"
 	"strings"
 	"time"
 
 	"github.com/deluan/rest"
+	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server/public"
 	"github.com/navidrome/navidrome/server/subsonic/responses"
@@ -60,9 +62,10 @@ func (api *Router) CreateShare(r *http.Request) (*responses.Subsonic, error) {
 	description, _ := p.String("description")
 	repo := api.share.NewRepository(r.Context())
 	share := &model.Share{
-		Description: description,
-		ExpiresAt:   new(p.TimeOr("expires", time.Time{})),
-		ResourceIDs: strings.Join(ids, ","),
+		Description:  description,
+		Downloadable: p.BoolOr("downloadable", conf.Server.DefaultDownloadableShare && conf.Server.EnableDownloads),
+		ExpiresAt:    new(p.TimeOr("expires", time.Time{})),
+		ResourceIDs:  strings.Join(ids, ","),
 	}
 
 	id, err := repo.(rest.Persistable).Save(share)
@@ -87,12 +90,27 @@ func (api *Router) UpdateShare(r *http.Request) (*responses.Subsonic, error) {
 		return nil, err
 	}
 
-	description, _ := p.String("description")
 	repo := api.share.NewRepository(r.Context())
+
+	// The update always writes description and downloadable, so read back the
+	// stored value for whichever one the client omitted.
+	description := p.StringPtr("description")
+	downloadable := p.BoolPtr("downloadable")
+	if description == nil || downloadable == nil {
+		current, err := repo.Read(id)
+		if err != nil {
+			return nil, err
+		}
+		cur := current.(*model.Share)
+		description = cmp.Or(description, &cur.Description)
+		downloadable = cmp.Or(downloadable, &cur.Downloadable)
+	}
+
 	share := &model.Share{
-		ID:          id,
-		Description: description,
-		ExpiresAt:   new(p.TimeOr("expires", time.Time{})),
+		ID:           id,
+		Description:  *description,
+		Downloadable: *downloadable,
+		ExpiresAt:    new(p.TimeOr("expires", time.Time{})),
 	}
 
 	err = repo.(rest.Persistable).Update(id, share)

From 055fbde3cf042f48caf96ff38cdb1e6cef648dbf Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Wed, 9 Sep 2026 12:03:36 -0400
Subject: [PATCH 126/200] fix(server): key the login rate limit on a
 trust-aware client IP

The RealIP middleware rewrote RemoteAddr from the True-Client-IP, X-Real-IP
and X-Forwarded-For headers on every request, including when no trusted
reverse proxy was configured. The login rate limiters on /auth/login and the
Jellyfin /Users/AuthenticateByName derived their bucket from that value, so
an unauthenticated client could rotate a forwarding header and get a fresh
bucket for every password attempt, defeating the brute-force protection.

Resolve the client IP with chi's ClientIPFrom* middlewares instead. The
forwarding headers are only honoured when ExtAuth.TrustedSources is set and
the connecting peer is in that list, reusing the trust check that external
authentication already applies; otherwise the peer address is used. The
X-Forwarded-For chain is now walked against the trusted CIDRs rather than
taking its leftmost entry, so a spoofed value prepended by the client is
skipped.

Both limiters now key on the resolved address. The resolved address is still
mirrored into RemoteAddr, so request logging, player registration and the
Jellyfin local-network check keep reporting the client rather than the proxy.

Reported by gehan-psbc.
---
 server/jellyfin/api.go      |  5 +-
 server/jellyfin/api_test.go | 23 +++++++++
 server/jellyfin/system.go   |  2 +-
 server/middlewares.go       | 82 ++++++++++++++++++++++++++-----
 server/middlewares_test.go  | 97 +++++++++++++++++++++++++++++++++++++
 server/server.go            |  3 +-
 6 files changed, 195 insertions(+), 17 deletions(-)

diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index 6484a3bb4..b0a5350b3 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -7,7 +7,6 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
-	"github.com/go-chi/httprate"
 	"golang.org/x/sync/singleflight"
 
 	"github.com/navidrome/navidrome/conf"
@@ -78,9 +77,9 @@ func (api *Router) routes() http.Handler {
 	inner.Post("/system/ping", api.ping)
 	inner.Get("/quickconnect/enabled", api.quickConnectEnabled)
 	// Rate-limit the password login, mirroring the native /auth/login: it's an unauthenticated
-	// brute-force surface, so it must share the same per-IP throttle when one is configured.
+	// brute-force surface, so it must share the same per-client throttle when one is configured.
 	if conf.Server.AuthRequestLimit > 0 {
-		limiter := httprate.LimitByIP(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength)
+		limiter := server.ClientIPRateLimiter(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength)
 		inner.With(limiter).Post("/users/authenticatebyname", api.authenticateByName)
 	} else {
 		inner.Post("/users/authenticatebyname", api.authenticateByName)
diff --git a/server/jellyfin/api_test.go b/server/jellyfin/api_test.go
index fe69c8321..605303793 100644
--- a/server/jellyfin/api_test.go
+++ b/server/jellyfin/api_test.go
@@ -6,6 +6,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/go-chi/chi/v5/middleware"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/auth"
@@ -84,4 +85,26 @@ var _ = Describe("Router", func() {
 		Expect(login()).To(Equal(http.StatusUnauthorized))
 		Expect(login()).To(Equal(http.StatusTooManyRequests))
 	})
+
+	It("rate-limits AuthenticateByName by resolved client IP, not by the proxy connection", func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.AuthRequestLimit = 1
+		conf.Server.AuthWindowLength = time.Minute
+		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		// Every request arrives on the same proxy connection, so only the resolved client IP
+		// can separate the buckets.
+		handler := middleware.ClientIPFromHeader("X-Real-IP")(api)
+
+		login := func(clientIP string) int {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("POST", "/Users/AuthenticateByName", strings.NewReader(`{"Username":"x","Pw":"y"}`))
+			r.RemoteAddr = "10.0.0.1:1234"
+			r.Header.Set("X-Real-IP", clientIP)
+			handler.ServeHTTP(w, r)
+			return w.Code
+		}
+		Expect(login("203.0.113.1")).To(Equal(http.StatusUnauthorized))
+		Expect(login("203.0.113.1")).To(Equal(http.StatusTooManyRequests))
+		Expect(login("203.0.113.2")).To(Equal(http.StatusUnauthorized))
+	})
 })
diff --git a/server/jellyfin/system.go b/server/jellyfin/system.go
index 8b847987f..ccc1277df 100644
--- a/server/jellyfin/system.go
+++ b/server/jellyfin/system.go
@@ -136,7 +136,7 @@ func isSameMachine(r *http.Request, remote netip.Addr) bool {
 	return parseIP(local.String()) == remote
 }
 
-// remoteIP parses RemoteAddr, which the RealIP middleware may have rewritten to a bare IP.
+// remoteIP parses RemoteAddr, which realIPMiddleware may have rewritten to a bare client IP.
 func remoteIP(r *http.Request) netip.Addr {
 	return parseIP(r.RemoteAddr)
 }
diff --git a/server/middlewares.go b/server/middlewares.go
index b710b4068..c54e947f3 100644
--- a/server/middlewares.go
+++ b/server/middlewares.go
@@ -7,7 +7,9 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
+	"net"
 	"net/http"
+	"net/netip"
 	"net/url"
 	"strings"
 	"time"
@@ -15,6 +17,7 @@ import (
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/go-chi/cors"
+	"github.com/go-chi/httprate"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
@@ -165,20 +168,77 @@ func clientUniqueIDMiddleware(next http.Handler) http.Handler {
 	})
 }
 
-// realIPMiddleware applies middleware.RealIP, and additionally saves the request's original RemoteAddr to the request's
-// context if navidrome is behind a trusted reverse proxy.
+// realIPMiddleware resolves the request's client IP into the context, where it can be read with
+// middleware.GetClientIP, and mirrors it into RemoteAddr for logging and player registration.
+// Forwarding headers are only honoured when the peer is listed in ExtAuth.TrustedSources, so that
+// a client cannot pick its own identity and evade controls keyed on it. The peer address is kept
+// in the context as request.ReverseProxyIp.
 func realIPMiddleware(next http.Handler) http.Handler {
-	if conf.Server.ExtAuth.TrustedSources != "" {
-		return chi.Chain(
-			reqToCtx(request.ReverseProxyIp, func(r *http.Request) any { return r.RemoteAddr }),
-			middleware.RealIP,
-		).Handler(next)
+	trusted := conf.Server.ExtAuth.TrustedSources
+	fromPeer := middleware.ClientIPFromRemoteAddr(next)
+	if trusted == "" {
+		return fromPeer
 	}
 
-	// The middleware is applied without a trusted reverse proxy to support other use-cases such as multiple clients
-	// behind a caching proxy. In this case, navidrome only uses the request's RemoteAddr for logging, so the security
-	// impact of reading the headers from untrusted sources is limited.
-	return middleware.RealIP(next)
+	// Last match wins, so this order reproduces RealIP's precedence: True-Client-IP, X-Real-IP,
+	// X-Forwarded-For, peer. Only X-Forwarded-For is checked against the trusted list.
+	fromProxy := chi.Chain(
+		middleware.ClientIPFromRemoteAddr,
+		middleware.ClientIPFromXFF(trustedProxyPrefixes(trusted)...),
+		middleware.ClientIPFromHeader("X-Real-IP"),
+		middleware.ClientIPFromHeader("True-Client-IP"),
+	).Handler(mirrorClientIP(next))
+
+	dispatch := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if validateIPAgainstList(r.RemoteAddr, trusted) {
+			fromProxy.ServeHTTP(w, r)
+			return
+		}
+		log.Trace(r.Context(), "Ignoring forwarding headers from untrusted peer", "peer", r.RemoteAddr)
+		fromPeer.ServeHTTP(w, r)
+	})
+	return reqToCtx(request.ReverseProxyIp, func(r *http.Request) any { return r.RemoteAddr })(dispatch)
+}
+
+// mirrorClientIP copies the resolved client IP into RemoteAddr when it differs from the peer.
+func mirrorClientIP(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if ip := middleware.GetClientIP(r.Context()); ip != "" && ip != peerHost(r) {
+			r.RemoteAddr = ip
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// peerHost returns the host part of RemoteAddr, which may already be a bare IP.
+func peerHost(r *http.Request) string {
+	if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		return host
+	}
+	return r.RemoteAddr
+}
+
+// trustedProxyPrefixes returns the CIDR entries of a trusted sources list, skipping non-CIDR
+// entries such as the "@" unix socket marker. An empty result makes ClientIPFromXFF trust
+// exactly one hop.
+func trustedProxyPrefixes(list string) []string {
+	var prefixes []string
+	for _, entry := range strings.Split(list, ",") {
+		entry = strings.TrimSpace(entry)
+		if _, err := netip.ParsePrefix(entry); err == nil {
+			prefixes = append(prefixes, entry)
+		}
+	}
+	return prefixes
+}
+
+// ClientIPRateLimiter returns a rate limiter keyed by the client IP resolved by realIPMiddleware,
+// so spoofed forwarding headers cannot be rotated for a fresh bucket. It falls back to the peer
+// address, so that a missing middleware degrades to per-peer limiting rather than one shared bucket.
+func ClientIPRateLimiter(requestLimit int, windowLength time.Duration) func(http.Handler) http.Handler {
+	return httprate.LimitBy(requestLimit, windowLength, func(r *http.Request) (string, error) {
+		return httprate.CanonicalizeIP(cmp.Or(middleware.GetClientIP(r.Context()), peerHost(r))), nil
+	})
 }
 
 // reqToCtx creates a middleware that updates the request's context with a value computed from the request. A given key
diff --git a/server/middlewares_test.go b/server/middlewares_test.go
index 4ba9a853b..a9b0bc99e 100644
--- a/server/middlewares_test.go
+++ b/server/middlewares_test.go
@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
 	"github.com/google/uuid"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -435,4 +436,100 @@ var _ = Describe("middlewares", func() {
 			})
 		})
 	})
+	Describe("realIPMiddleware", func() {
+		var resolved, remoteAddr string
+		var proxyIP any
+		next := func(w http.ResponseWriter, r *http.Request) {
+			resolved = middleware.GetClientIP(r.Context())
+			remoteAddr = r.RemoteAddr
+			proxyIP = r.Context().Value(request.ReverseProxyIp)
+		}
+		call := func(peer string, headers map[string]string) {
+			resolved, remoteAddr, proxyIP = "", "", nil
+			r := httptest.NewRequest("POST", "/auth/login", nil)
+			r.RemoteAddr = peer
+			for k, v := range headers {
+				r.Header.Set(k, v)
+			}
+			realIPMiddleware(http.HandlerFunc(next)).ServeHTTP(httptest.NewRecorder(), r)
+		}
+
+		Context("without a trusted proxy", func() {
+			It("ignores client-supplied forwarding headers", func() {
+				call("10.0.0.1:1234", map[string]string{
+					"X-Forwarded-For": "203.0.113.5",
+					"X-Real-IP":       "203.0.113.6",
+					"True-Client-IP":  "203.0.113.7",
+				})
+				Expect(resolved).To(Equal("10.0.0.1"))
+			})
+			It("leaves RemoteAddr untouched", func() {
+				call("10.0.0.1:1234", map[string]string{"X-Forwarded-For": "203.0.113.5"})
+				Expect(remoteAddr).To(Equal("10.0.0.1:1234"))
+			})
+		})
+
+		Context("with a trusted proxy", func() {
+			BeforeEach(func() {
+				conf.Server.ExtAuth.TrustedSources = "10.0.0.0/8"
+			})
+			It("uses the forwarded client IP when the peer is a trusted proxy", func() {
+				call("10.0.0.1:1234", map[string]string{"X-Forwarded-For": "203.0.113.5, 10.0.0.1"})
+				Expect(resolved).To(Equal("203.0.113.5"))
+				Expect(remoteAddr).To(Equal("203.0.113.5"))
+			})
+			It("honours X-Real-IP from a trusted proxy", func() {
+				call("10.0.0.1:1234", map[string]string{"X-Real-IP": "203.0.113.6"})
+				Expect(resolved).To(Equal("203.0.113.6"))
+			})
+			It("ignores forwarding headers when the peer is not a trusted proxy", func() {
+				call("198.51.100.9:1234", map[string]string{"X-Forwarded-For": "203.0.113.5"})
+				Expect(resolved).To(Equal("198.51.100.9"))
+				Expect(remoteAddr).To(Equal("198.51.100.9:1234"))
+			})
+			It("keeps the peer address in the context for external auth", func() {
+				call("10.0.0.1:1234", map[string]string{"X-Forwarded-For": "203.0.113.5"})
+				Expect(proxyIP).To(Equal("10.0.0.1:1234"))
+			})
+		})
+	})
+
+	Describe("ClientIPRateLimiter", func() {
+		var handler http.Handler
+		JustBeforeEach(func() {
+			handler = realIPMiddleware(ClientIPRateLimiter(2, time.Minute)(
+				http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })))
+		})
+		attempt := func(peer string, header, value string) int {
+			r := httptest.NewRequest("POST", "/auth/login", nil)
+			r.RemoteAddr = peer
+			r.Header.Set(header, value)
+			w := httptest.NewRecorder()
+			handler.ServeHTTP(w, r)
+			return w.Code
+		}
+
+		DescribeTable("keeps one bucket per peer when the forwarding header is rotated",
+			func(header string) {
+				Expect(attempt("198.51.100.9:1", header, "203.0.113.1")).To(Equal(http.StatusOK))
+				Expect(attempt("198.51.100.9:2", header, "203.0.113.2")).To(Equal(http.StatusOK))
+				Expect(attempt("198.51.100.9:3", header, "203.0.113.3")).To(Equal(http.StatusTooManyRequests))
+			},
+			Entry("X-Forwarded-For", "X-Forwarded-For"),
+			Entry("X-Real-IP", "X-Real-IP"),
+			Entry("True-Client-IP", "True-Client-IP"),
+		)
+
+		Context("behind a trusted proxy", func() {
+			BeforeEach(func() {
+				conf.Server.ExtAuth.TrustedSources = "10.0.0.0/8"
+			})
+			It("gives each real client its own bucket", func() {
+				Expect(attempt("10.0.0.1:1", "X-Forwarded-For", "203.0.113.1")).To(Equal(http.StatusOK))
+				Expect(attempt("10.0.0.1:2", "X-Forwarded-For", "203.0.113.1")).To(Equal(http.StatusOK))
+				Expect(attempt("10.0.0.1:3", "X-Forwarded-For", "203.0.113.1")).To(Equal(http.StatusTooManyRequests))
+				Expect(attempt("10.0.0.1:4", "X-Forwarded-For", "203.0.113.2")).To(Equal(http.StatusOK))
+			})
+		})
+	})
 })
diff --git a/server/server.go b/server/server.go
index b05c20cc5..7e7cfa3ea 100644
--- a/server/server.go
+++ b/server/server.go
@@ -17,7 +17,6 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
-	"github.com/go-chi/httprate"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/auth"
@@ -209,7 +208,7 @@ func (s *Server) mountAuthenticationRoutes() chi.Router {
 			log.Info("Login rate limit set", "requestLimit", conf.Server.AuthRequestLimit,
 				"windowLength", conf.Server.AuthWindowLength)
 
-			rateLimiter := httprate.LimitByIP(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength)
+			rateLimiter := ClientIPRateLimiter(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength)
 			r.With(rateLimiter).Post("/login", login(s.ds))
 		} else {
 			log.Warn("Login rate limit is disabled! Consider enabling it to be protected against brute-force attacks")

From 964d3c778bdbddf781cfbea3e64dcf802d1856e8 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Thu, 10 Sep 2026 15:00:01 -0400
Subject: [PATCH 127/200] build(deps): update direct Go dependencies and taglib
 fork

Bumps all 13 direct dependencies that had newer releases, plus the
go-taglib fork pin. No source changes were needed.

The jwx bump to v3.3.0 carries a security fix (GHSA-4cf7-xm37-g63h):
custom claim, header and JWK names were written unescaped, so a name
containing a quote could inject extra members. Navidrome is not
affected - every claim name we emit is a hardcoded literal - but the
fix is worth taking. cascadia v1.3.5 similarly limits selector nesting
to avoid a stack overflow, and our only selector is a constant.

go-sqlite3 v1.14.52 is the only bump with real behavior change: it
flushes the statement cache on schema changes, steps cached statements
eagerly, and drops the per-row goroutine used for query cancellation.
goose v3.28.0 raises its minimum to Go 1.26 and otherwise only touches
MySQL, ClickHouse and Azure SQL, which we do not use. The golang.org/x
bumps are routine. govulncheck reports no reachable vulnerabilities.

The taglib fork pin picks up two fixes. Audio properties are now
clamped with std::max(0, ...) before the unsigned conversion, so a
malformed file no longer reports a duration of ~49 days; this ports
upstream sentriz/go-taglib 0524e91 and additionally covers
bitsPerSample, which is specific to this fork. Bit depth is also now
reported for DSDIFF, TrueAudio and Shorten, which previously returned
0. Both values reach media_file only on re-extraction, so existing
libraries need a full scan to pick them up.
---
 go.mod | 34 +++++++++++------------
 go.sum | 88 +++++++++++++++++++++++++++++-----------------------------
 2 files changed, 61 insertions(+), 61 deletions(-)

diff --git a/go.mod b/go.mod
index 4339b9c55..1a73328f3 100644
--- a/go.mod
+++ b/go.mod
@@ -3,11 +3,11 @@ module github.com/navidrome/navidrome
 go 1.27
 
 // Fork to implement raw tags support
-replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260905051825-df1d035571df
+replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260910183509-2ca9506dd7ec
 
 require (
 	github.com/Masterminds/squirrel v1.5.4
-	github.com/andybalholm/cascadia v1.3.4
+	github.com/andybalholm/cascadia v1.3.5
 	github.com/bmatcuk/doublestar/v4 v4.10.0
 	github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf
 	github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55
@@ -26,7 +26,7 @@ require (
 	github.com/go-chi/jwtauth/v5 v5.4.0
 	github.com/go-viper/encoding/ini v0.1.1
 	github.com/go-viper/mapstructure/v2 v2.5.0
-	github.com/gohugoio/hashstructure v1.0.0
+	github.com/gohugoio/hashstructure v1.1.0
 	github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc
 	github.com/google/uuid v1.6.0
 	github.com/google/wire v0.7.0
@@ -35,16 +35,16 @@ require (
 	github.com/jellydator/ttlcache/v3 v3.4.1
 	github.com/kardianos/service v1.3.0
 	github.com/kr/pretty v0.3.1
-	github.com/lestrrat-go/jwx/v3 v3.2.0
-	github.com/mattn/go-sqlite3 v1.14.50
+	github.com/lestrrat-go/jwx/v3 v3.3.0
+	github.com/mattn/go-sqlite3 v1.14.52
 	github.com/microcosm-cc/bluemonday v1.0.27
 	github.com/mileusna/useragent v1.3.5
-	github.com/onsi/ginkgo/v2 v2.32.1
+	github.com/onsi/ginkgo/v2 v2.32.2
 	github.com/onsi/gomega v1.43.0
 	github.com/pelletier/go-toml/v2 v2.4.3
 	github.com/pmezard/go-difflib v1.0.0
 	github.com/pocketbase/dbx v1.12.0
-	github.com/pressly/goose/v3 v3.27.3
+	github.com/pressly/goose/v3 v3.28.0
 	github.com/prometheus/client_golang v1.24.1
 	github.com/rjeczalik/notify v0.9.3
 	github.com/robfig/cron/v3 v3.0.1
@@ -60,13 +60,13 @@ require (
 	github.com/zeebo/xxh3 v1.1.0
 	go.senan.xyz/taglib v0.11.1
 	go.uber.org/goleak v1.3.0
-	golang.org/x/image v0.45.0
-	golang.org/x/net v0.58.0
-	golang.org/x/sync v0.22.0
-	golang.org/x/sys v0.47.0
-	golang.org/x/term v0.45.0
-	golang.org/x/text v0.41.0
-	golang.org/x/time v0.15.0
+	golang.org/x/image v0.46.0
+	golang.org/x/net v0.59.0
+	golang.org/x/sync v0.23.0
+	golang.org/x/sys v0.48.0
+	golang.org/x/term v0.46.0
+	golang.org/x/text v0.42.0
+	golang.org/x/time v0.16.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -114,7 +114,7 @@ require (
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/common v0.70.1 // indirect
-	github.com/prometheus/procfs v0.21.1 // indirect
+	github.com/prometheus/procfs v0.22.0 // indirect
 	github.com/rogpeppe/go-internal v1.16.0 // indirect
 	github.com/sagikazarmark/locafero v0.12.0 // indirect
 	github.com/sanity-io/litter v1.5.8 // indirect
@@ -131,8 +131,8 @@ require (
 	go.opentelemetry.io/proto/otlp v1.11.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.5 // indirect
-	golang.org/x/crypto v0.55.0 // indirect
-	golang.org/x/mod v0.40.0 // indirect
+	golang.org/x/crypto v0.57.0 // indirect
+	golang.org/x/mod v0.41.0 // indirect
 	golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5 // indirect
 	golang.org/x/tools v0.49.0 // indirect
 	google.golang.org/protobuf v1.36.12 // indirect
diff --git a/go.sum b/go.sum
index 71d9facfd..42e1505e9 100644
--- a/go.sum
+++ b/go.sum
@@ -6,8 +6,8 @@ github.com/Masterminds/semver/v3 v3.5.0 h1:kQceYJfbupGfZOKZQg0kou0DgAKhzDg2NZPAw
 github.com/Masterminds/semver/v3 v3.5.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
 github.com/Masterminds/squirrel v1.5.4 h1:uUcX/aBc8O7Fg9kaISIUsHXdKuqehiXAMQTYX8afzqM=
 github.com/Masterminds/squirrel v1.5.4/go.mod h1:NNaOrjSoIDfDA40n7sr2tPNZRfjzjA400rg+riTZj10=
-github.com/andybalholm/cascadia v1.3.4 h1:vM2lgh0Vru9Vwyfm4cQqWP2HHMW0u0+2PAW7Q38Qufg=
-github.com/andybalholm/cascadia v1.3.4/go.mod h1:BLRmbRjpEtNKieZOCCvYj4RqN+KRA41GBe/5O+G93kM=
+github.com/andybalholm/cascadia v1.3.5 h1:RLjq12WJy58dN6eCIQrz0bAGZkztHWsEPFxP53Y7Ms8=
+github.com/andybalholm/cascadia v1.3.5/go.mod h1:BLRmbRjpEtNKieZOCCvYj4RqN+KRA41GBe/5O+G93kM=
 github.com/atombender/go-jsonschema v0.20.0 h1:AHg0LeI0HcjQ686ALwUNqVJjNRcSXpIR6U+wC2J0aFY=
 github.com/atombender/go-jsonschema v0.20.0/go.mod h1:ZmbuR11v2+cMM0PdP6ySxtyZEGFBmhgF4xa4J6Hdls8=
 github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuPk=
@@ -29,8 +29,8 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
-github.com/deluan/go-taglib v0.0.0-20260905051825-df1d035571df h1:LdLQVAWVc6hCzqnrfVIEXOhP+r0iSit+EvsXwZDyL70=
-github.com/deluan/go-taglib v0.0.0-20260905051825-df1d035571df/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
+github.com/deluan/go-taglib v0.0.0-20260910183509-2ca9506dd7ec h1:3VyOFsbsRtCQqdq/+fcmD3D6zlRvKSG7RCixgrdWfEo=
+github.com/deluan/go-taglib v0.0.0-20260910183509-2ca9506dd7ec/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcHCKTtwzrd0HGfEmoODFA/qnk4=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf/go.mod h1:tSgDythFsl0QgS/PFWfIZqcJKnkADWneY80jaVRlqK8=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55 h1:wSCnggTs2f2ji6nFwQmfwgINcmSMj0xF0oHnoyRSPe4=
@@ -94,8 +94,8 @@ github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
 github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
 github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
-github.com/gohugoio/hashstructure v1.0.0 h1:vWYuyzs1n0LdI0F54TJQeYAiB44fHX7H9hCp9X6gHKg=
-github.com/gohugoio/hashstructure v1.0.0/go.mod h1:FSbTK4QwxucJ2bC4Lvrs9a6x0DbQDXNoyBO+h4nlCgE=
+github.com/gohugoio/hashstructure v1.1.0 h1:38yUfZBca6qXSbUpteLhjDGLNskclHaguFBYpjaRjf4=
+github.com/gohugoio/hashstructure v1.1.0/go.mod h1:Pz8dcwjZs6FBKWu9x/ZIChrTHIM175zfUJK0KLvC1z8=
 github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
@@ -134,8 +134,8 @@ github.com/kardianos/service v1.3.0 h1:/LGy+xPP2TM+GLTiCZ2di7cy0Jd/qrawlTUfqKYFd
 github.com/kardianos/service v1.3.0/go.mod h1:E4V9ufUuY82F7Ztlu1eN9VXWIQxg8NoLQlmFe0MtrXc=
 github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 h1:Z9n2FFNUXsshfwJMBgNA0RU6/i7WVaAegv3PtuIHPMs=
 github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51/go.mod h1:CzGEWj7cYgsdH8dAjBGEr58BoE7ScuLd+fwFZ44+/x8=
-github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk=
-github.com/klauspost/compress v1.19.1/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/compress v1.19.2 h1:hMRETovs/pu/dVWN7zIT1PGG8t509MwT6bO7XSi26R8=
+github.com/klauspost/compress v1.19.2/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/klauspost/cpuid/v2 v2.4.0 h1:S6Hrbc7+ywsr0r+RLapfGBHfyefhCTwEh3A0tV913Dw=
 github.com/klauspost/cpuid/v2 v2.4.0/go.mod h1:19jmZ9mjzoF//ddRSUsv0zfBTJWh3QJh9FNxZTMrGxU=
 github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
@@ -159,16 +159,16 @@ github.com/lestrrat-go/httpcc v1.0.1 h1:ydWCStUeJLkpYyjLDHihupbn2tYmZ7m22BGkcvZZ
 github.com/lestrrat-go/httpcc v1.0.1/go.mod h1:qiltp3Mt56+55GPVCbTdM9MlqhvzyuL6W/NMDA8vA5E=
 github.com/lestrrat-go/httprc/v3 v3.0.6 h1:4FpLQ18KK/ypPbVU3NLWJNRvH3kcYiqKqWfKGqNWxxI=
 github.com/lestrrat-go/httprc/v3 v3.0.6/go.mod h1:mSMtkZW92Z98M5YoNNztbRGxbXHql7tSitCvaxvo9l0=
-github.com/lestrrat-go/jwx/v3 v3.2.0 h1:Jb3zBASTSZXz7gzzSAfYqxXF8KejvKC4xWoePLQqXCA=
-github.com/lestrrat-go/jwx/v3 v3.2.0/go.mod h1:38vQ8iWKq3qRSbilbzvzdQPuywhowwuR03lhkYskyrw=
+github.com/lestrrat-go/jwx/v3 v3.3.0 h1:OXcYvQOQ7cxWzeZ/Q9sYk8ABe/kCSI371WmuACiCT+4=
+github.com/lestrrat-go/jwx/v3 v3.3.0/go.mod h1:eIJhDcKHBwcgxqv8RiIylV67TVl1wJp/265IAHY1Db8=
 github.com/lestrrat-go/option/v2 v2.0.0 h1:XxrcaJESE1fokHy3FpaQ/cXW8ZsIdWcdFzzLOcID3Ss=
 github.com/lestrrat-go/option/v2 v2.0.0/go.mod h1:oSySsmzMoR0iRzCDCaUfsCzxQHUEuhOViQObyy7S6Vg=
 github.com/maruel/natural v1.3.0 h1:VsmCsBmEyrR46RomtgHs5hbKADGRVtliHTyCOLFBpsg=
 github.com/maruel/natural v1.3.0/go.mod h1:v+Rfd79xlw1AgVBjbO0BEQmptqb5HvL/k9GRHB7ZKEg=
-github.com/mattn/go-isatty v0.0.23 h1:cYwCQTQf3HB6xUC+BtyCLZNr7IzbOmoZbmssVNzSyiQ=
-github.com/mattn/go-isatty v0.0.23/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
-github.com/mattn/go-sqlite3 v1.14.50 h1:dmdFvo1XG4MPzA4IkAmE9upVz/Nj31uRoM5+jC8hYbY=
-github.com/mattn/go-sqlite3 v1.14.50/go.mod h1:6JTjA44L93a0QCyJef5YvlPoKXntQPjzWv5gtm9sB6w=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/mattn/go-sqlite3 v1.14.52 h1:wVbm2Qnf4OXkqhBTSPuCRZDRnxfbVrrmiCEroVdog8U=
+github.com/mattn/go-sqlite3 v1.14.52/go.mod h1:6JTjA44L93a0QCyJef5YvlPoKXntQPjzWv5gtm9sB6w=
 github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
 github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg=
 github.com/mfridman/tparse v0.18.0 h1:wh6dzOKaIwkUGyKgOntDW4liXSo37qg5AXbIhkMV3vE=
@@ -185,8 +185,8 @@ github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOF
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/ogier/pflag v0.0.1 h1:RW6JSWSu/RkSatfcLtogGfFgpim5p7ARQ10ECk5O750=
 github.com/ogier/pflag v0.0.1/go.mod h1:zkFki7tvTa0tafRvTBIZTvzYyAu6kQhPZFnshFFPE+g=
-github.com/onsi/ginkgo/v2 v2.32.1 h1:6tlvcDm/3sE8lGJbZ4+d4mO3RLy24/tQWOFzVSQNIfw=
-github.com/onsi/ginkgo/v2 v2.32.1/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
+github.com/onsi/ginkgo/v2 v2.32.2 h1:2o6vyFvR6snrJWgRVztC+OwuqqPEMI1UzYl2s2iU7Cg=
+github.com/onsi/ginkgo/v2 v2.32.2/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
 github.com/onsi/gomega v1.43.0 h1:VlG/1FxqNxhSO+lq/OHBNaaqwiBK/mO8JbVkX9Y+FeU=
 github.com/onsi/gomega v1.43.0/go.mod h1:REff/hsDsodHoKlWsP2mAPhu1+5/6hVYNf9rIEBpeSg=
 github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
@@ -199,16 +199,16 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pocketbase/dbx v1.12.0 h1:/oLErM+A0b4xI0PWTGPqSDVjzix48PqI/bng2l0PzoA=
 github.com/pocketbase/dbx v1.12.0/go.mod h1:xXRCIAKTHMgUCyCKZm55pUOdvFziJjQfXaWKhu2vhMs=
-github.com/pressly/goose/v3 v3.27.3 h1:pIglVHjw99r4e/hDHHwbl9vfOsDMqUokfkXo6+n/RxA=
-github.com/pressly/goose/v3 v3.27.3/go.mod h1:Dag+xpV6o20HR2LFY1j0q6MDwc3f7vPUFDA77R+0yGY=
+github.com/pressly/goose/v3 v3.28.0 h1:D2M+iL31GmpZxSHOhX8mqyqAT3CXnokUmm0eKoSP+Vc=
+github.com/pressly/goose/v3 v3.28.0/go.mod h1:v26MOuB8bL3kzzrt3Vqhb3R0PRVsl8hFQKdrht/L6Rk=
 github.com/prometheus/client_golang v1.24.1 h1:JnJkREXzWxUdCuPFpIWZiPispT9xVV59uiuyR2bPlnU=
 github.com/prometheus/client_golang v1.24.1/go.mod h1:F+oSRECHg4sse5ucfYpYDeIv/hu68Zo0uoHKetWnzcE=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
 github.com/prometheus/common v0.70.1 h1:1HvjP4D5oL3t8RsPlwxA9onvvStjtIHYE5XuuwOi/PY=
 github.com/prometheus/common v0.70.1/go.mod h1:VdFUQDMZK3VLkurFUVhia6uys/0suUp86TJz5qbJRhc=
-github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
-github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
+github.com/prometheus/procfs v0.22.0 h1:6q9+/JL9IKAPbCmBrv9n5O5Ty3NKnciV5X7YGw0oics=
+github.com/prometheus/procfs v0.22.0/go.mod h1:CvmFr/GVhIjIvWJZW3tgkODBQMRIf0EyWMQLHCHab58=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 github.com/rjeczalik/notify v0.9.3 h1:6rJAzHTGKXGj76sbRgDiDcYj/HniypXmSJo1SWakZeY=
@@ -304,34 +304,34 @@ go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
 go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M=
-golang.org/x/crypto v0.55.0/go.mod h1:uq0V9dE/fzQuJtbnL+2EhWOE63vo164FY8xqEnV9xis=
-golang.org/x/image v0.45.0 h1:FMb1nTbH5H9vF55SriQHgFw5GnNL9Jg6L25BwXKzhB0=
-golang.org/x/image v0.45.0/go.mod h1:n62x/7RqlwXDvGsSU4u6IUTUf6KghUZ9Bt7cG/T9Fx4=
-golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
-golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=
+golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
+golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
+golang.org/x/image v0.46.0 h1:b1+oYj0Jbp6K5MDT4i4/eZpYlk3V8SJhhDKh6LBHAyQ=
+golang.org/x/image v0.46.0/go.mod h1:3B3W05VGVQyuXucLINLjXKrqISASfi4Xj+iCVkLMwew=
+golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
+golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o=
 golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
-golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
-golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
-golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
-golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues=
+golang.org/x/net v0.59.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg=
+golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
+golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
 golang.org/x/sys v0.0.0-20180926160741-c2ed4eda69e7/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190422165155-953cdadca894/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20220615213510-4f61da869c0c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
-golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
 golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5 h1:ZUSxONxc981v7AW7QUg+I9WwZzSTTJ019ENBYr5pV/Q=
 golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5/go.mod h1:LVehoXe41cL5SCVQilsV7Gg6BNG+Js6P9PhSbYTIUkQ=
-golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
-golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
+golang.org/x/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE=
+golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
-golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
-golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
-golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
-golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
+golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
+golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
+golang.org/x/time v0.16.0 h1:vMb6ptszcQMkcwiRTAuNNU50gom6++Q/6gY2hDM6VDE=
+golang.org/x/time v0.16.0/go.mod h1:rVKOqvZeKvrDKTQiAHJ7wmwP0RzleSphoEA9RcdLA0s=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
 golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
@@ -350,11 +350,11 @@ gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-modernc.org/libc v1.74.3 h1:a4J+Z8aVaxPyjyxRAdJzw246PqpcFGvVPnfT/AuM5Ws=
-modernc.org/libc v1.74.3/go.mod h1:4H7h/MJ8wnjL8RAbp9v3OXgnk22X7MouHIhDbvP3gj4=
+modernc.org/libc v1.75.6 h1:yKk8qo+Di4gkmvRboK8ocCqH22FiUCR6jRy2OwtCRus=
+modernc.org/libc v1.75.6/go.mod h1:bO5o2ztHxBb2rjz0PgdHN0sSMw57CgxGFLZ3Qd/QpVQ=
 modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
 modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
-modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
-modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
-modernc.org/sqlite v1.54.0 h1:JCxR4qwkJvOaqAoYcgDoO25Nc+ROg6EJ2LfBVzdrgog=
-modernc.org/sqlite v1.54.0/go.mod h1:4ntCLuNmnH8+GNqjka1wNg7KJd5/Hi5FYp8K+XQ7GZw=
+modernc.org/memory v1.12.1 h1:nFMiWrpStgZczNl6XI9GnIk/rWhYIyHGUaR04pGbp9g=
+modernc.org/memory v1.12.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/sqlite v1.57.0 h1:qNQP6xnx5M0ISNtlnxoOX0+cD5bJ0/gr9aMmndFczzg=
+modernc.org/sqlite v1.57.0/go.mod h1:yCJ2cmAaIkHQ25oXWrF8H4O1lIfPYPR26yCEDj2P3pQ=

From 2aa7a5c46696a8ba09d73915b203b309c38ee93d Mon Sep 17 00:00:00 2001
From: York <goog10216922@gmail.com>
Date: Fri, 11 Sep 2026 08:48:33 +0800
Subject: [PATCH 128/200] fix(ui): prevent Safari album grid resize when top
 menus open (#6125)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ui): prevent Safari album grid resize when top menus open

* fix(ui): disable scroll lock for all popovers

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 ui/src/themes/useCurrentTheme.js | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/ui/src/themes/useCurrentTheme.js b/ui/src/themes/useCurrentTheme.js
index 2b5d13d13..4ccefe820 100644
--- a/ui/src/themes/useCurrentTheme.js
+++ b/ui/src/themes/useCurrentTheme.js
@@ -59,7 +59,11 @@ const useCurrentTheme = () => {
   return useMemo(
     () => ({
       ...theme,
-      props: { ...theme.props, MuiUseMediaQuery: { noSsr: true } },
+      props: {
+        ...theme.props,
+        MuiUseMediaQuery: { noSsr: true },
+        MuiPopover: { disableScrollLock: true },
+      },
     }),
     [theme],
   )

From 2dc09836291a1eadaced27cbeb938d875635d9ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 11 Sep 2026 15:03:54 -0400
Subject: [PATCH 129/200] fix: miscellaneous fixes for shares, artwork resize,
 auth limits, and watcher start (#6098)

* fix(artwork): cap declared image dimensions before resizing

resizeStaticImage decoded the image with a raw image.Decode, so a small file declaring huge dimensions (e.g. a PNG header claiming 50k x 50k) forced a multi-gigabyte allocation on the serve-time resize path. The processor already guards its own decodes with decodeCapped; use it here too so the same 64M pixel cap applies to uploaded and sidecar images served through the cache.

* fix(share): validate every resource ID and reject mixed types when saving

Save only resolved the first ID in ResourceIDs to pick the resource type; the remaining IDs were never checked. A non-existent or hidden entity could ride along behind a valid first ID, and IDs of different kinds were accepted as one share. Resolve every ID as the current user and require all of them to be the same kind, returning ErrNotFound or ErrValidation otherwise.

* fix(share): scope album and media file shares to the owner's libraries

loadMedia already loaded artist and playlist shares as the share owner, but album and media_file shares used the repository context. Public share rendering carries no user, so the library filter was skipped and the share listed albums and tracks from libraries the owner cannot access. Streaming was already blocked, so only metadata leaked. Use ownerContext for all resource types.

* fix(server): limit login payload size and surface first-admin creation errors

The unauthenticated /login and /createAdmin handlers decoded the request body
with no size limit. Add a body-limit middleware to the /auth route group that
caps the payload at 8KiB, which is plenty for a username and password. Also
make createAdminUser return the datastore error instead of logging it and
returning nil, which previously let createAdmin proceed to a login attempt for
a user that was never saved.

* fix(conf): create the log file readable only by the owner

The log file was created with mode 0644, so other local users could read it. Logs can contain usernames, paths and, at trace level, request details, so create it with 0600 instead. Existing files keep their current mode.

* fix(lastfm): stop logging the auth token when fetching the session key fails

The Last.fm callback token was written to the log as a structured field on failure. The redaction hook only matches value patterns, so it was not masked. Drop the field; the request ID is enough to correlate the failure.

* fix(db): allow a music folder path containing a single quote on fresh databases

The library table migration interpolated conf.Server.MusicFolder into the SQL with fmt.Sprintf, so a path such as /music/Rock 'n' Roll produced invalid SQL and the migration failed on a brand new database. Bind the path as a parameter instead.

* fix(scanner): return an error when the folder watcher cannot start

When notify.Watch failed, the watcher goroutine logged the error and exited, but never signalled the started channel, so Start blocked until its context was cancelled and left the watching flag set. Call notify.Watch before spawning the event loop, so Start returns the error right away, the started/failed signalling goes away, and the storage can be watched again later.

* fix(jellyfin): limit the login request body size

The Jellyfin AuthenticateByName endpoint decoded its JSON body with no size limit, the same gap the native /auth routes had. Export the login body-limit middleware from the server package and apply it to the Jellyfin login route, before the optional per-IP rate limiter, so both unauthenticated login surfaces share the same 8KiB cap.

* fix(scanner): share one scanner instance across all injectors

Each wire injector built its own scanner controller, so the Subsonic and native API routers held a different instance from the ones used by the startup scan, the periodic scan, the folder watcher and the SIGUSR1 handler. Status reads the in-progress file and folder counters from its own instance, so getScanStatus reported scanning=true with count=0 for every scan not started through the API. Verified live with a startup scan: master reports count 0 while scanning, this branch reports the real counts. Expose the controller through a singleton, as the watcher, broker and play tracker already are, and wire everything to it. New stays available for tests that need isolated controllers.

* fix(share): do not panic when a media file share has no visible tracks

Share.CoverArtID picked a random track for media file shares without checking that any track was loaded. The tracks are empty when the files went missing, were deleted, or the owner lost access to their library, and the public share page then panicked inside the random pick and returned a 500. Return an empty artwork ID instead, so the page renders with the placeholder cover. The old guard on the split resource IDs was dead code, since SplitN always returns at least one element.
---
 adapters/lastfm/auth_router.go                |  2 +-
 cmd/wire_gen.go                               | 10 ++---
 cmd/wire_injectors.go                         |  2 +-
 conf/configuration.go                         |  2 +-
 conf/configuration_test.go                    | 16 +++++++
 core/artwork/resize.go                        |  2 +-
 core/artwork/resize_test.go                   | 13 ++++++
 core/share.go                                 | 45 +++++++++++++------
 core/share_test.go                            | 13 ++++++
 core/storage/local/watcher.go                 | 23 ++++------
 core/storage/local/watcher_test.go            | 15 +++++++
 .../20240511220020_add_library_table.go       |  9 ++--
 model/share.go                                |  7 +--
 model/share_test.go                           | 19 ++++++++
 persistence/share_repository.go               | 22 ++++-----
 persistence/share_repository_test.go          | 43 +++++++++++++-----
 scanner/controller.go                         | 10 +++++
 scanner/controller_test.go                    | 10 +++++
 server/auth.go                                | 11 +++++
 server/auth_test.go                           | 16 +++++++
 server/jellyfin/api.go                        |  7 ++-
 server/jellyfin/auth_test.go                  | 13 ++++++
 server/server.go                              |  1 +
 23 files changed, 237 insertions(+), 74 deletions(-)
 create mode 100644 core/artwork/resize_test.go
 create mode 100644 model/share_test.go

diff --git a/adapters/lastfm/auth_router.go b/adapters/lastfm/auth_router.go
index 411bf069a..ec1bb9290 100644
--- a/adapters/lastfm/auth_router.go
+++ b/adapters/lastfm/auth_router.go
@@ -132,7 +132,7 @@ func (s *Router) callback(w http.ResponseWriter, r *http.Request) {
 func (s *Router) fetchSessionKey(ctx context.Context, uid, token string) error {
 	sessionKey, err := s.client.getSession(ctx, token)
 	if err != nil {
-		log.Error(ctx, "Could not fetch LastFM session key", "userId", uid, "token", token,
+		log.Error(ctx, "Could not fetch LastFM session key", "userId", uid,
 			"requestId", middleware.GetReqID(ctx), err)
 		return err
 	}
diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index de4c55a1e..fd04c44c5 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -70,7 +70,7 @@ func CreateNativeAPIRouter(ctx context.Context) *nativeapi.Router {
 	insights := metrics.GetInstance(dataStore)
 	broker := events.GetBroker()
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
-	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
+	modelScanner := scanner.GetInstance(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	watcher := scanner.GetWatcher(dataStore, modelScanner)
 	manager := plugins.GetManager(dataStore, broker, metricsMetrics)
 	library := core.NewLibrary(dataStore, modelScanner, watcher, broker, manager)
@@ -103,7 +103,7 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher, broker)
 	uploader := artwork.NewUploader(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
-	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
+	modelScanner := scanner.GetInstance(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	playTracker := scrobbler.GetPlayTracker(dataStore, broker, manager)
 	playbackServer := playback.GetInstance(dataStore)
 	lyricsLyrics := lyrics.NewLyrics(dataStore, manager)
@@ -189,7 +189,7 @@ func CreateScanner(ctx context.Context) model.Scanner {
 	uploader := artwork.NewUploader(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
-	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
+	modelScanner := scanner.GetInstance(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	return modelScanner
 }
 
@@ -200,7 +200,7 @@ func CreateScanWatcher(ctx context.Context) scanner.Watcher {
 	uploader := artwork.NewUploader(dataStore)
 	playlistsPlaylists := playlists.NewPlaylists(dataStore, uploader)
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
-	modelScanner := scanner.New(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
+	modelScanner := scanner.GetInstance(ctx, dataStore, broker, playlistsPlaylists, metricsMetrics)
 	watcher := scanner.GetWatcher(dataStore, modelScanner)
 	return watcher
 }
@@ -249,7 +249,7 @@ func getPluginManager() *plugins.Manager {
 
 // wire_injectors.go:
 
-var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, jellyfin.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(sonic.Engine), new(*sonic.Sonic)), 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)), wire.Bind(new(playlists.ImageUploadService), new(artwork.Uploader)))
+var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, jellyfin.New, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.GetInstance, 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(sonic.Engine), new(*sonic.Sonic)), 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)), wire.Bind(new(playlists.ImageUploadService), new(artwork.Uploader)))
 
 func GetPluginManager(ctx context.Context) *plugins.Manager {
 	manager := getPluginManager()
diff --git a/cmd/wire_injectors.go b/cmd/wire_injectors.go
index 8bc404fb1..a54d4ae1b 100644
--- a/cmd/wire_injectors.go
+++ b/cmd/wire_injectors.go
@@ -42,7 +42,7 @@ var allProviders = wire.NewSet(
 	lastfm.NewRouter,
 	listenbrainz.NewRouter,
 	events.GetBroker,
-	scanner.New,
+	scanner.GetInstance,
 	scanner.GetWatcher,
 	metrics.GetPrometheusInstance,
 	db.Db,
diff --git a/conf/configuration.go b/conf/configuration.go
index ff119417a..e549e2a61 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -407,7 +407,7 @@ func Load(noConfigDump bool) {
 		if mkErr := os.MkdirAll(filepath.Dir(Server.LogFile), os.ModePerm); mkErr != nil {
 			logFatal(fmt.Sprintf("Error creating log file directory: %s", mkErr.Error()))
 		}
-		out, err = os.OpenFile(Server.LogFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+		out, err = os.OpenFile(Server.LogFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)
 		if err != nil {
 			logFatal(fmt.Sprintf("Error opening log file %s: %s", Server.LogFile, err.Error()))
 		}
diff --git a/conf/configuration_test.go b/conf/configuration_test.go
index 2c7f8edaa..9404f01bc 100644
--- a/conf/configuration_test.go
+++ b/conf/configuration_test.go
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"runtime"
 	"testing"
 	"time"
 
@@ -329,6 +330,21 @@ var _ = Describe("Configuration", func() {
 			}).To(PanicWith(ContainSubstring("Error creating log file directory")))
 		})
 
+		It("creates the log file readable only by the owner", func() {
+			if runtime.GOOS == "windows" {
+				Skip("file modes are not enforced on Windows")
+			}
+			logFile := filepath.Join(GinkgoT().TempDir(), "navidrome.log")
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("logfile", logFile)
+			DeferCleanup(log.SetOutput, os.Stderr)
+			conf.Load(true)
+
+			info, err := os.Stat(logFile)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(info.Mode().Perm()).To(Equal(os.FileMode(0600)))
+		})
+
 		It("is called when BaseURL is invalid", func() {
 			viper.SetDefault("datafolder", GinkgoT().TempDir())
 			viper.SetDefault("baseurl", "://invalid")
diff --git a/core/artwork/resize.go b/core/artwork/resize.go
index 9536c3bb1..9b3ff46e5 100644
--- a/core/artwork/resize.go
+++ b/core/artwork/resize.go
@@ -76,7 +76,7 @@ func toFastScaleType(img image.Image) image.Image {
 }
 
 func resizeStaticImage(data []byte, size int, square bool) (io.Reader, int, error) {
-	original, format, err := image.Decode(bytes.NewReader(data))
+	original, format, err := decodeCapped(data)
 	if err != nil {
 		return nil, 0, err
 	}
diff --git a/core/artwork/resize_test.go b/core/artwork/resize_test.go
new file mode 100644
index 000000000..76b95974d
--- /dev/null
+++ b/core/artwork/resize_test.go
@@ -0,0 +1,13 @@
+package artwork
+
+import (
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("resizeStaticImage", func() {
+	It("rejects images whose declared dimensions exceed the pixel cap before decoding", func() {
+		_, _, err := resizeStaticImage(pngHeaderWithDims(9000, 9000), 300, false)
+		Expect(err).To(MatchError(ContainSubstring("exceed pixel cap")))
+	})
+})
diff --git a/core/share.go b/core/share.go
index b2f32ba39..5ee1a5667 100644
--- a/core/share.go
+++ b/core/share.go
@@ -2,6 +2,8 @@ package core
 
 import (
 	"context"
+	"fmt"
+	"slices"
 	"strings"
 	"time"
 
@@ -98,27 +100,19 @@ func (r *shareRepositoryWrapper) Save(entity any) (string, error) {
 		s.ExpiresAt = new(time.Now().Add(conf.Server.DefaultShareExpiration))
 	}
 
-	firstId, _, _ := strings.Cut(s.ResourceIDs, ",")
-	v, err := model.GetEntityByID(r.ctx, r.ds, firstId)
+	s.ResourceType, err = r.resourceType(s.ResourceIDs)
 	if err != nil {
 		return "", err
 	}
-	switch v.(type) {
-	case *model.Artist:
-		s.ResourceType = "artist"
+	switch s.ResourceType {
+	case "artist":
 		s.Contents = r.contentsLabelFromArtist(s.ID, s.ResourceIDs)
-	case *model.Album:
-		s.ResourceType = "album"
+	case "album":
 		s.Contents = r.contentsLabelFromAlbums(s.ID, s.ResourceIDs)
-	case *model.Playlist:
-		s.ResourceType = "playlist"
+	case "playlist":
 		s.Contents = r.contentsLabelFromPlaylist(s.ID, s.ResourceIDs)
-	case *model.MediaFile:
-		s.ResourceType = "media_file"
+	case "media_file":
 		s.Contents = r.contentsLabelFromMediaFiles(s.ID, s.ResourceIDs)
-	default:
-		log.Error(r.ctx, "Invalid Resource ID", "id", firstId)
-		return "", model.ErrNotFound
 	}
 
 	s.Contents = str.TruncateRunes(s.Contents, 30, "...")
@@ -126,6 +120,29 @@ func (r *shareRepositoryWrapper) Save(entity any) (string, error) {
 	return r.Persistable.Save(s)
 }
 
+var shareableKinds = []model.Kind{model.KindArtistArtwork, model.KindAlbumArtwork, model.KindPlaylistArtwork, model.KindMediaFileArtwork}
+
+// resourceType resolves every ID as the current user, so an entity they cannot see cannot
+// ride along behind a valid first one, and requires all IDs to be of the same kind.
+func (r *shareRepositoryWrapper) resourceType(resourceIDs string) (string, error) {
+	resourceType := ""
+	for _, id := range strings.Split(resourceIDs, ",") {
+		kind, err := model.GetEntityKindByID(r.ctx, r.ds, id)
+		if err != nil {
+			return "", err
+		}
+		if !slices.Contains(shareableKinds, kind) {
+			log.Error(r.ctx, "Invalid Resource ID", "id", id)
+			return "", model.ErrNotFound
+		}
+		if resourceType != "" && kind.String() != resourceType {
+			return "", fmt.Errorf("%w: share mixes %s and %s resources", model.ErrValidation, resourceType, kind)
+		}
+		resourceType = kind.String()
+	}
+	return resourceType, nil
+}
+
 func (r *shareRepositoryWrapper) Update(id string, entity any, _ ...string) error {
 	cols := []string{"description", "downloadable"}
 
diff --git a/core/share_test.go b/core/share_test.go
index 475d40ec9..a5ee0428b 100644
--- a/core/share_test.go
+++ b/core/share_test.go
@@ -70,6 +70,19 @@ var _ = Describe("Share", func() {
 				Expect(err).ToNot(HaveOccurred())
 				Expect(entity.Contents).To(Equal("私の中の幻想的世界観及びその顕現を想起させたある現実で..."))
 			})
+
+			It("fails when any of the resource IDs does not exist", func() {
+				entity := &model.Share{Description: "test", ResourceIDs: "123,missing"}
+				_, err := repo.Save(entity)
+				Expect(err).To(MatchError(model.ErrNotFound))
+			})
+
+			It("fails when the resource IDs are of mixed types", func() {
+				_ = ds.MediaFile(ctx).Put(&model.MediaFile{ID: "456", Title: "Example Media File"})
+				entity := &model.Share{Description: "test", ResourceIDs: "123,456"}
+				_, err := repo.Save(entity)
+				Expect(err).To(HaveOccurred())
+			})
 		})
 
 		Describe("Update", func() {
diff --git a/core/storage/local/watcher.go b/core/storage/local/watcher.go
index 1b8a4e0c8..ef404d497 100644
--- a/core/storage/local/watcher.go
+++ b/core/storage/local/watcher.go
@@ -3,6 +3,7 @@ package local
 import (
 	"context"
 	"errors"
+	"fmt"
 	"path/filepath"
 	"strings"
 
@@ -18,22 +19,18 @@ func (s *localStorage) Start(ctx context.Context) (<-chan string, error) {
 		return nil, errors.New("watcher already started")
 	}
 	input := make(chan notify.EventInfo, 500)
-	output := make(chan string, 500)
+	libPath := filepath.Join(s.u.Path, "...")
+	log.Debug(ctx, "Starting watcher", "lib", libPath)
+	if err := notify.Watch(libPath, input, WatchEvents); err != nil {
+		s.watching.Store(false)
+		return nil, fmt.Errorf("starting watcher on %s: %w", libPath, err)
+	}
 
-	started := make(chan struct{})
+	output := make(chan string, 500)
 	go func() {
 		defer close(input)
 		defer close(output)
-
-		libPath := filepath.Join(s.u.Path, "...")
-		log.Debug(ctx, "Starting watcher", "lib", libPath)
-		err := notify.Watch(libPath, input, WatchEvents)
-		if err != nil {
-			log.Error("Error starting watcher", "lib", libPath, err)
-			return
-		}
 		defer notify.Stop(input)
-		close(started) // signals the main goroutine we have started
 
 		for {
 			select {
@@ -49,9 +46,5 @@ func (s *localStorage) Start(ctx context.Context) (<-chan string, error) {
 			}
 		}
 	}()
-	select {
-	case <-started:
-	case <-ctx.Done():
-	}
 	return output, nil
 }
diff --git a/core/storage/local/watcher_test.go b/core/storage/local/watcher_test.go
index 8d2d31367..37387c76a 100644
--- a/core/storage/local/watcher_test.go
+++ b/core/storage/local/watcher_test.go
@@ -137,3 +137,18 @@ type noopExtractor struct{}
 
 func (s noopExtractor) Parse(files ...string) (map[string]metadata.Info, error) { return nil, nil }
 func (s noopExtractor) Version() string                                         { return "0" }
+
+var _ = Describe("Watcher.Start", func() {
+	It("returns an error instead of hanging when the path cannot be watched", func() {
+		local.RegisterExtractor("noop", func(fs fs.FS, path string) local.Extractor { return noopExtractor{} })
+		conf.Server.Scanner.Extractor = "noop"
+		ls, err := storage.For(filepath.Join(GinkgoT().TempDir(), "does-not-exist"))
+		Expect(err).ToNot(HaveOccurred())
+		lsw := ls.(storage.Watcher)
+
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_, err = lsw.Start(ctx)
+		Expect(err).To(HaveOccurred())
+	})
+})
diff --git a/db/migrations/20240511220020_add_library_table.go b/db/migrations/20240511220020_add_library_table.go
index 55b521ca9..d7b4aa5c2 100644
--- a/db/migrations/20240511220020_add_library_table.go
+++ b/db/migrations/20240511220020_add_library_table.go
@@ -3,7 +3,6 @@ package migrations
 import (
 	"context"
 	"database/sql"
-	"fmt"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/pressly/goose/v3"
@@ -28,10 +27,10 @@ func upAddLibraryTable(ctx context.Context, tx *sql.Tx) error {
 		return err
 	}
 
-	_, err = tx.ExecContext(ctx, fmt.Sprintf(`
-		insert into library(id, name, path) values(1, 'Music Library', '%s');
-		delete from property where id like 'LastScan-%%';
-`, conf.Server.MusicFolder))
+	_, err = tx.ExecContext(ctx, `
+		insert into library(id, name, path) values(1, 'Music Library', ?);
+		delete from property where id like 'LastScan-%';
+`, conf.Server.MusicFolder)
 	if err != nil {
 		return err
 	}
diff --git a/model/share.go b/model/share.go
index ce0846d60..cf1f4cb34 100644
--- a/model/share.go
+++ b/model/share.go
@@ -32,9 +32,6 @@ type Share struct {
 
 func (s Share) CoverArtID() ArtworkID {
 	ids := strings.SplitN(s.ResourceIDs, ",", 2)
-	if len(ids) == 0 {
-		return ArtworkID{}
-	}
 	switch s.ResourceType {
 	case "album":
 		return Album{ID: ids[0]}.CoverArtID()
@@ -43,6 +40,10 @@ func (s Share) CoverArtID() ArtworkID {
 	case "artist":
 		return Artist{ID: ids[0]}.CoverArtID()
 	}
+	// Tracks can be empty when they went missing or the owner lost access to their library.
+	if len(s.Tracks) == 0 {
+		return ArtworkID{}
+	}
 	rnd := random.Int64N(len(s.Tracks))
 	return s.Tracks[rnd].CoverArtID()
 }
diff --git a/model/share_test.go b/model/share_test.go
new file mode 100644
index 000000000..b5e38af59
--- /dev/null
+++ b/model/share_test.go
@@ -0,0 +1,19 @@
+package model_test
+
+import (
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Share.CoverArtID", func() {
+	It("returns an empty artwork ID for a media file share with no visible tracks", func() {
+		s := model.Share{ResourceType: "media_file", ResourceIDs: "mf-1"}
+		Expect(s.CoverArtID()).To(Equal(model.ArtworkID{}))
+	})
+
+	It("picks a track's cover for a media file share", func() {
+		s := model.Share{ResourceType: "media_file", ResourceIDs: "mf-1", Tracks: model.MediaFiles{{ID: "mf-1"}}}
+		Expect(s.CoverArtID()).To(Equal(model.MediaFile{ID: "mf-1"}.CoverArtID()))
+	})
+})
diff --git a/persistence/share_repository.go b/persistence/share_repository.go
index 4b6dc9240..92c696688 100644
--- a/persistence/share_repository.go
+++ b/persistence/share_repository.go
@@ -72,7 +72,6 @@ func (r *shareRepository) GetAll(options ...model.QueryOptions) (model.Shares, e
 }
 
 func (r *shareRepository) loadMedia(share *model.Share) error {
-	var err error
 	ids := strings.Split(share.ResourceIDs, ",")
 	if len(ids) == 0 {
 		return nil
@@ -80,15 +79,15 @@ func (r *shareRepository) loadMedia(share *model.Share) error {
 	noMissing := func(cond Sqlizer) Sqlizer {
 		return And{cond, Eq{"missing": false}}
 	}
+	// Load as the share owner so their library access is applied, whoever renders the share.
+	ctx, err := r.ownerContext(share)
+	if err != nil {
+		return err
+	}
 	switch share.ResourceType {
 	case "artist":
 		// Match by album-artist participation, not the deprecated album_artist_id
 		// column (first album artist only), so co-album-artists are included too.
-		// Load as the share owner so their library access is applied.
-		ctx, err := r.ownerContext(share)
-		if err != nil {
-			return err
-		}
 		albumRepo := NewAlbumRepository(ctx, r.db)
 		share.Albums, err = albumRepo.GetAll(model.QueryOptions{Filters: noMissing(ParticipantIDFilter("album", ids, model.RoleAlbumArtist)), Sort: "artist"})
 		if err != nil {
@@ -98,20 +97,15 @@ func (r *shareRepository) loadMedia(share *model.Share) error {
 		share.Tracks, err = mfRepo.GetAll(model.QueryOptions{Filters: noMissing(ParticipantIDFilter("media_file", ids, model.RoleAlbumArtist)), Sort: "artist"})
 		return err
 	case "album":
-		albumRepo := NewAlbumRepository(r.ctx, r.db)
+		albumRepo := NewAlbumRepository(ctx, r.db)
 		share.Albums, err = albumRepo.GetAll(model.QueryOptions{Filters: noMissing(Eq{"album.id": ids})})
 		if err != nil {
 			return err
 		}
-		mfRepo := NewMediaFileRepository(r.ctx, r.db)
+		mfRepo := NewMediaFileRepository(ctx, r.db)
 		share.Tracks, err = mfRepo.GetAll(model.QueryOptions{Filters: noMissing(Eq{"album_id": ids}), Sort: "album"})
 		return err
 	case "playlist":
-		// Load tracks as the share owner so their library access is applied.
-		ctx, err := r.ownerContext(share)
-		if err != nil {
-			return err
-		}
 		plsRepo := NewPlaylistRepository(ctx, r.db)
 		// Tracks returns nil when the playlist is no longer visible to the owner
 		// (e.g. it was made private after the share was created); leave the share
@@ -127,7 +121,7 @@ func (r *shareRepository) loadMedia(share *model.Share) error {
 		share.Tracks = tracks.MediaFiles()
 		return nil
 	case "media_file":
-		mfRepo := NewMediaFileRepository(r.ctx, r.db)
+		mfRepo := NewMediaFileRepository(ctx, r.db)
 		tracks, err := mfRepo.GetAll(model.QueryOptions{Filters: noMissing(Eq{"media_file.id": ids})})
 		share.Tracks = sortByIdPosition(tracks, ids)
 		return err
diff --git a/persistence/share_repository_test.go b/persistence/share_repository_test.go
index 3af91b2af..02d8a7386 100644
--- a/persistence/share_repository_test.go
+++ b/persistence/share_repository_test.go
@@ -228,7 +228,7 @@ var _ = Describe("ShareRepository", func() {
 		})
 	})
 
-	Describe("Artist share library scoping", func() {
+	Describe("Artist, album and media file share library scoping", func() {
 		var otherLib model.Library
 		var owner model.User
 		const primaryID = "share-aa-primary"
@@ -267,20 +267,26 @@ var _ = Describe("ShareRepository", func() {
 			Expect(ur.Put(&owner)).To(Succeed())
 			Expect(ur.SetUserLibraries(owner.ID, []int{1})).To(Succeed())
 
-			_, err := b.NewQuery(`
-				INSERT INTO share (id, user_id, description, resource_type, resource_ids, created_at, updated_at)
-				VALUES ({:id}, {:user}, {:desc}, {:type}, {:ids}, {:created}, {:updated})
-			`).Bind(map[string]any{
-				"id": "art-share", "user": owner.ID, "desc": "Artist scope share",
-				"type": "artist", "ids": secondaryID, "created": time.Now(), "updated": time.Now(),
-			}).Execute()
-			Expect(err).ToNot(HaveOccurred())
+			for _, s := range []struct{ id, typ, ids string }{
+				{"art-share", "artist", secondaryID},
+				{"art-album-share", "album", "art-album-ok,art-album-other"},
+				{"art-mf-share", "media_file", "art-ok,art-other"},
+			} {
+				_, err := b.NewQuery(`
+					INSERT INTO share (id, user_id, description, resource_type, resource_ids, created_at, updated_at)
+					VALUES ({:id}, {:user}, {:desc}, {:type}, {:ids}, {:created}, {:updated})
+				`).Bind(map[string]any{
+					"id": s.id, "user": owner.ID, "desc": "Scope share",
+					"type": s.typ, "ids": s.ids, "created": time.Now(), "updated": time.Now(),
+				}).Execute()
+				Expect(err).ToNot(HaveOccurred())
+			}
 		})
 
 		AfterEach(func() {
 			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
 			b := GetDBXBuilder()
-			_, _ = b.NewQuery(`DELETE FROM share WHERE id = 'art-share'`).Execute()
+			_, _ = b.NewQuery(`DELETE FROM share WHERE id IN ('art-share', 'art-album-share', 'art-mf-share')`).Execute()
 			mr := NewMediaFileRepository(adminCtx, b).(*mediaFileRepository)
 			_, _ = mr.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": []string{"art-ok", "art-other"}}))
 			alr := NewAlbumRepository(adminCtx, b).(*albumRepository)
@@ -309,6 +315,23 @@ var _ = Describe("ShareRepository", func() {
 			Expect(share.Albums).ToNot(ContainElement(HaveField("ID", "art-album-other")),
 				"an album outside the owner's libraries must not appear in the share")
 		})
+
+		It("excludes albums and their tracks outside the owner's libraries from an album share", func() {
+			// Public share rendering has no user in the context.
+			share, err := NewShareRepository(log.NewContext(GinkgoT().Context()), GetDBXBuilder()).Get("art-album-share")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(share.Albums).To(ContainElement(HaveField("ID", "art-album-ok")))
+			Expect(share.Albums).ToNot(ContainElement(HaveField("ID", "art-album-other")))
+			Expect(share.Tracks).To(ContainElement(HaveField("ID", "art-ok")))
+			Expect(share.Tracks).ToNot(ContainElement(HaveField("ID", "art-other")))
+		})
+
+		It("excludes tracks outside the owner's libraries from a media file share", func() {
+			share, err := NewShareRepository(log.NewContext(GinkgoT().Context()), GetDBXBuilder()).Get("art-mf-share")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(share.Tracks).To(ContainElement(HaveField("ID", "art-ok")))
+			Expect(share.Tracks).ToNot(ContainElement(HaveField("ID", "art-other")))
+		})
 	})
 
 	Describe("Ownership Checks", func() {
diff --git a/scanner/controller.go b/scanner/controller.go
index df5aeb6f9..bfb396c6d 100644
--- a/scanner/controller.go
+++ b/scanner/controller.go
@@ -20,6 +20,7 @@ import (
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/utils/pl"
+	"github.com/navidrome/navidrome/utils/singleton"
 	"golang.org/x/time/rate"
 )
 
@@ -387,3 +388,12 @@ func (s *controller) trackProgress(ctx context.Context, progress <-chan *Progres
 func (s *controller) sendMessage(ctx context.Context, status *events.ScanStatus) {
 	s.broker.SendBroadcastMessage(ctx, status)
 }
+
+// GetInstance returns the scanner singleton: Status reads the progress counters of the controller
+// running the scan, and scheduler, watcher and signal scans do not start from the API's injector.
+func GetInstance(rootCtx context.Context, ds model.DataStore, broker events.Broker,
+	pls playlists.Playlists, m metrics.Metrics) model.Scanner {
+	return singleton.GetInstance(func() *controller {
+		return New(rootCtx, ds, broker, pls, m).(*controller)
+	})
+}
diff --git a/scanner/controller_test.go b/scanner/controller_test.go
index 7ffdd69d4..45d202904 100644
--- a/scanner/controller_test.go
+++ b/scanner/controller_test.go
@@ -92,3 +92,13 @@ var _ = Describe("EffectiveFullScan", func() {
 		Expect(scanner.EffectiveFullScan(context.Background(), ds, false, targets)).To(BeFalse())
 	})
 })
+
+var _ = Describe("GetInstance", func() {
+	It("returns the same controller to every caller", func() {
+		ds := &tests.MockDataStore{}
+		pls := playlists.NewPlaylists(ds, artwork.NewUploader(ds))
+		a := scanner.GetInstance(context.Background(), ds, events.NoopBroker(), pls, metrics.NewNoopInstance())
+		b := scanner.GetInstance(context.Background(), ds, events.NoopBroker(), pls, metrics.NewNoopInstance())
+		Expect(a).To(BeIdenticalTo(b))
+	})
+})
diff --git a/server/auth.go b/server/auth.go
index 37a318a83..fdeb8c455 100644
--- a/server/auth.go
+++ b/server/auth.go
@@ -96,6 +96,16 @@ func buildAuthPayload(user *model.User) map[string]any {
 	return payload
 }
 
+// MaxLoginBodySize bounds the payload of unauthenticated login routes across all APIs.
+const MaxLoginBodySize = 8 << 10
+
+func LimitLoginBody(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		r.Body = http.MaxBytesReader(w, r.Body, MaxLoginBodySize)
+		next.ServeHTTP(w, r)
+	})
+}
+
 func getCredentialsFromBody(r *http.Request) (username string, password string, err error) {
 	data := make(map[string]string)
 	decoder := json.NewDecoder(r.Body)
@@ -150,6 +160,7 @@ func createAdminUser(ctx context.Context, ds model.DataStore, username, password
 	err := ds.User(ctx).Put(&initialUser)
 	if err != nil {
 		log.Error(ctx, "Could not create initial user", "user", initialUser, err)
+		return fmt.Errorf("creating initial user: %w", err)
 	}
 	return nil
 }
diff --git a/server/auth_test.go b/server/auth_test.go
index e021c82a8..af9ffcaeb 100644
--- a/server/auth_test.go
+++ b/server/auth_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"crypto/md5"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
@@ -64,6 +65,14 @@ var _ = Describe("Auth", func() {
 			})
 		})
 
+		Describe("createAdminUser", func() {
+			It("returns the error when the user cannot be saved", func() {
+				ds = &tests.MockDataStore{MockedUser: &tests.MockedUserRepo{Error: errors.New("db is down")}}
+				err := createAdminUser(context.Background(), ds, "johndoe", "secret")
+				Expect(err).To(MatchError(ContainSubstring("db is down")))
+			})
+		})
+
 		Describe("Login from HTTP headers", func() {
 			const (
 				trustedIpv4   = "192.168.0.42"
@@ -200,6 +209,13 @@ var _ = Describe("Auth", func() {
 				Expect(resp.Code).To(Equal(http.StatusUnauthorized))
 			})
 
+			It("rejects a request body larger than the limit", func() {
+				body := `{"username":"janedoe", "password":"abc123", "padding":"` + strings.Repeat("x", MaxLoginBodySize) + `"}`
+				req = httptest.NewRequest("POST", "/login", strings.NewReader(body))
+				LimitLoginBody(http.HandlerFunc(login(ds))).ServeHTTP(resp, req)
+				Expect(resp.Code).To(Equal(http.StatusUnprocessableEntity))
+			})
+
 			It("logs in successfully if user exists", func() {
 				usr := ds.User(context.Background())
 				_ = usr.Put(&model.User{ID: "111", UserName: "janedoe", NewPassword: "abc123", Name: "Jane", IsAdmin: false})
diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index b0a5350b3..971f7794a 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -78,12 +78,11 @@ func (api *Router) routes() http.Handler {
 	inner.Get("/quickconnect/enabled", api.quickConnectEnabled)
 	// Rate-limit the password login, mirroring the native /auth/login: it's an unauthenticated
 	// brute-force surface, so it must share the same per-client throttle when one is configured.
+	login := inner.With(server.LimitLoginBody)
 	if conf.Server.AuthRequestLimit > 0 {
-		limiter := server.ClientIPRateLimiter(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength)
-		inner.With(limiter).Post("/users/authenticatebyname", api.authenticateByName)
-	} else {
-		inner.Post("/users/authenticatebyname", api.authenticateByName)
+		login = login.With(server.ClientIPRateLimiter(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength))
 	}
+	login.Post("/users/authenticatebyname", api.authenticateByName)
 	inner.Get("/users/public", api.getPublicUsers)
 
 	// Images are intentionally public: artwork isn't sensitive, matching Jellyfin's image handling.
diff --git a/server/jellyfin/auth_test.go b/server/jellyfin/auth_test.go
index 5a613f828..577677643 100644
--- a/server/jellyfin/auth_test.go
+++ b/server/jellyfin/auth_test.go
@@ -9,6 +9,7 @@ import (
 
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server"
 	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -101,3 +102,15 @@ var _ = Describe("AuthenticateByName", func() {
 		Expect(w.Code).To(Equal(http.StatusUnauthorized))
 	})
 })
+
+var _ = Describe("AuthenticateByName body limit", func() {
+	It("rejects a request body larger than the limit", func() {
+		ds := &tests.MockDataStore{}
+		api := &Router{ds: ds}
+		w := httptest.NewRecorder()
+		body := `{"Username":"alice","Pw":"secret","Padding":"` + strings.Repeat("x", server.MaxLoginBodySize) + `"}`
+		r := httptest.NewRequest("POST", "/Users/AuthenticateByName", strings.NewReader(body))
+		server.LimitLoginBody(http.HandlerFunc(api.authenticateByName)).ServeHTTP(w, r)
+		Expect(w.Code).To(Equal(http.StatusBadRequest))
+	})
+})
diff --git a/server/server.go b/server/server.go
index 7e7cfa3ea..7e7e2f6bd 100644
--- a/server/server.go
+++ b/server/server.go
@@ -204,6 +204,7 @@ func (s *Server) initRoutes() {
 func (s *Server) mountAuthenticationRoutes() chi.Router {
 	r := s.router
 	return r.Route(path.Join(conf.Server.BasePath, "/auth"), func(r chi.Router) {
+		r.Use(LimitLoginBody)
 		if conf.Server.AuthRequestLimit > 0 {
 			log.Info("Login rate limit set", "requestLimit", conf.Server.AuthRequestLimit,
 				"windowLength", conf.Server.AuthWindowLength)

From 9e950cb63d6bd965a7a71e3b03ede294b8bc83a0 Mon Sep 17 00:00:00 2001
From: Huang-404-Q <129407632+Huang-404-Q@users.noreply.github.com>
Date: Sat, 12 Sep 2026 08:50:45 +0800
Subject: [PATCH 130/200] fix(cli): fail restore when the backup file does not
 exist instead of wiping the database (#6085)

* fix(db): fail restore when the backup file does not exist instead of wiping the database

`navidrome backup restore -b <file>` passed the flag value straight to the
SQLite driver, which opens databases with SQLITE_OPEN_CREATE by default. If
the file was not found (for example a file name relative to the working
directory instead of the backup directory), the driver silently created an
empty database and the backup API copied that emptiness over the live
database, reporting 'Restore complete' with an empty instance afterwards.

Two changes:

- db.Restore now opens the backup file read-only, so a missing file is an
  error and nothing gets created or overwritten.
- A relative --backup-file is resolved against Backup.Path, the same folder
  'backup create' writes to; absolute paths keep working as before.

Fixes #6083

* fix(db): stat the backup file instead of opening it read-only

The read-only DSN added in the previous commit works for the reported case but
breaks on other paths: 'file:' + path is parsed as a URI, so a '#' truncates the
path and a '%' sequence is percent-decoded, and a read-only open of a WAL
database leaves '-shm'/'-wal' sidecars next to the backup. Those sidecars then
matched the unanchored prune regex, so 'backup prune -k 3' right after a restore
deleted real backups and kept one.

Stat the file before opening it and keep passing the plain path to the driver.
Paths containing '?' are rejected, since go-sqlite3 splits the DSN there and
would otherwise open (and create) a different file. The prune regex is anchored
so sidecars are never counted as backups.

Also fixes the restore/backup/prune error logs, which printed BasePath (the web
URL prefix) instead of the backup location.

---------

Co-authored-by: Deluan <deluan@navidrome.org>
---
 cmd/backup.go     | 21 ++++++++---
 db/backup.go      | 15 +++++++-
 db/backup_test.go | 89 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 120 insertions(+), 5 deletions(-)

diff --git a/cmd/backup.go b/cmd/backup.go
index c02f3a19f..eca78a272 100644
--- a/cmd/backup.go
+++ b/cmd/backup.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -31,7 +32,7 @@ func init() {
 	pruneCmd.Flags().BoolVarP(&force, "force", "f", false, "bypass warning when backup count is zero")
 	backupRoot.AddCommand(pruneCmd)
 
-	restoreCommand.Flags().StringVarP(&restorePath, "backup-file", "b", "", "path of backup database to restore")
+	restoreCommand.Flags().StringVarP(&restorePath, "backup-file", "b", "", "file name of the backup database to restore (resolved against the backup directory unless it is an absolute path)")
 	restoreCommand.Flags().BoolVarP(&force, "force", "f", false, "bypass restore warning")
 	_ = restoreCommand.MarkFlagRequired("backup-file")
 	backupRoot.AddCommand(restoreCommand)
@@ -95,7 +96,7 @@ func runBackup(ctx context.Context) {
 	start := time.Now()
 	path, err := db.Backup(ctx)
 	if err != nil {
-		log.Fatal("Error backing up database", "backup path", conf.Server.BasePath, err)
+		log.Fatal("Error backing up database", "backupPath", conf.Server.Backup.Path, err)
 	}
 
 	elapsed := time.Since(start)
@@ -140,7 +141,7 @@ func runPrune(ctx context.Context) {
 	start := time.Now()
 	count, err := db.Prune(ctx)
 	if err != nil {
-		log.Fatal("Error pruning up database", "backup path", conf.Server.BasePath, err)
+		log.Fatal("Error pruning database", "backupPath", conf.Server.Backup.Path, err)
 	}
 
 	elapsed := time.Since(start)
@@ -163,6 +164,18 @@ func runRestore(ctx context.Context) {
 		return
 	}
 
+	// A relative --backup-file is resolved against Backup.Path, the same folder
+	// `backup create` writes to. Without this, the value was treated as relative
+	// to the working directory, where the file does not exist.
+	if !filepath.IsAbs(restorePath) {
+		backupPath, err := conf.Server.Backup.Path.Path()
+		if err != nil {
+			log.Fatal("Backup directory not available", "backupPath", conf.Server.Backup.Path, err)
+			return
+		}
+		restorePath = filepath.Join(backupPath, restorePath)
+	}
+
 	if !force {
 		fmt.Println("Warning: restoring the Navidrome database should only be done offline, especially if your backup is very old.")
 		fmt.Printf("Please enter YES (all caps) to continue: ")
@@ -178,7 +191,7 @@ func runRestore(ctx context.Context) {
 	start := time.Now()
 	err := db.Restore(ctx, restorePath)
 	if err != nil {
-		log.Fatal("Error restoring database", "backup path", conf.Server.BasePath, err)
+		log.Fatal("Error restoring database", "backupFile", restorePath, err)
 	}
 
 	elapsed := time.Since(start)
diff --git a/db/backup.go b/db/backup.go
index 806bef8e2..74cae553e 100644
--- a/db/backup.go
+++ b/db/backup.go
@@ -9,6 +9,7 @@ import (
 	"path/filepath"
 	"regexp"
 	"slices"
+	"strings"
 	"time"
 
 	"github.com/mattn/go-sqlite3"
@@ -18,7 +19,7 @@ import (
 
 const (
 	backupPrefix      = "navidrome_backup"
-	backupRegexString = backupPrefix + "_(.+)\\.db"
+	backupRegexString = "^" + backupPrefix + "_(.+)\\.db$"
 )
 
 var backupRegex = regexp.MustCompile(backupRegexString)
@@ -40,6 +41,18 @@ func backupOrRestore(ctx context.Context, isBackup bool, path string) error {
 	}
 	defer existingConn.Close()
 
+	// The driver opens with SQLITE_OPEN_CREATE, so without this check a typo in the
+	// path would create an empty database and "restore" it over the live one.
+	if !isBackup {
+		// The driver splits the DSN at '?', so such a path would open a different file.
+		if strings.ContainsRune(path, '?') {
+			return fmt.Errorf("backup path cannot contain '?': %s", path)
+		}
+		if _, err := os.Stat(path); err != nil {
+			return fmt.Errorf("backup file not available: %w", err)
+		}
+	}
+
 	backupDb, err := sql.Open(Driver, path)
 	if err != nil {
 		return fmt.Errorf("opening backup database in '%s': %w", path, err)
diff --git a/db/backup_test.go b/db/backup_test.go
index 5d1bfc6e3..609cba3d6 100644
--- a/db/backup_test.go
+++ b/db/backup_test.go
@@ -5,12 +5,14 @@ import (
 	"database/sql"
 	"math/rand"
 	"os"
+	"path/filepath"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	. "github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/singleton"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -103,6 +105,19 @@ var _ = Describe("database backups", func() {
 			Entry("delete all files", 0, 0),
 			Entry("preserve all files when at length", len(timesDecreasingChronologically), len(timesDecreasingChronologically)),
 			Entry("preserve all files when less than count", 10000, len(timesDecreasingChronologically)))
+
+		It("ignores SQLite sidecar files when counting backups", func() {
+			for _, suffix := range []string{"-shm", "-wal"} {
+				file, err := os.Create(BackupPath(timesDecreasingChronologically[0]) + suffix)
+				Expect(err).ToNot(HaveOccurred())
+				_ = file.Close()
+			}
+
+			conf.Server.Backup.Count = len(timesDecreasingChronologically)
+			pruneCount, err := Prune(ctx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pruneCount).To(BeZero())
+		})
 	})
 
 	Describe("backup and restore", Ordered, func() {
@@ -148,4 +163,78 @@ var _ = Describe("database backups", func() {
 			Expect(IsSchemaEmpty(ctx, Db())).To(BeFalse())
 		})
 	})
+
+	Describe("backup and restore with a file-based database", Ordered, func() {
+		var ctx context.Context
+		var tempFolder string
+		var dbFilePath string
+
+		BeforeAll(func() {
+			ctx = context.Background()
+			DeferCleanup(configtest.SetupConfig())
+
+			var err error
+			tempFolder, err = os.MkdirTemp("", "navidrome_restore")
+			Expect(err).ToNot(HaveOccurred())
+			DeferCleanup(func() {
+				Close(ctx)
+				_ = os.RemoveAll(tempFolder)
+			})
+
+			// Mimic the production DSN (consts.DefaultDbPath): a file database in WAL mode.
+			dbFilePath = filepath.Join(tempFolder, "navidrome.db")
+			conf.Server.DbPath = dbFilePath + "?_busy_timeout=15000&_journal_mode=WAL&_foreign_keys=on&synchronous=normal"
+			// The previous container's cleanup closed the shared *sql.DB without
+			// dropping the singleton; force a fresh connection for this container.
+			singleton.DeleteInstance[*sql.DB]()
+			DeferCleanup(Init(ctx))
+		})
+
+		It("restores data into a database whose stale WAL sidecar files were left behind", func() {
+			By("seeding user data in the current database")
+			_, err := Db().ExecContext(ctx, `INSERT INTO user (id, user_name, name, email, password, is_admin, created_at, updated_at)
+				VALUES ('u-restore-1', 'drilladmin', 'drilladmin', 'drilladmin@example.com', 'x', 1, datetime('now'), datetime('now'))`)
+			Expect(err).ToNot(HaveOccurred())
+
+			By("creating a backup containing the user row")
+			path, err := Backup(ctx)
+			Expect(err).ToNot(HaveOccurred())
+
+			By("simulating the CLI exiting without closing the pool: sidecar files stay behind")
+			_, err = Db().ExecContext(ctx, "CREATE TABLE IF NOT EXISTS _restore_probe(x)")
+			Expect(err).ToNot(HaveOccurred())
+			singleton.DeleteInstance[*sql.DB]()
+
+			err = tests.ClearDB()
+			Expect(err).ToNot(HaveOccurred())
+
+			By("restoring the backup")
+			Expect(Restore(ctx, path)).To(Succeed())
+
+			By("verifying the restored data is readable through a fresh connection")
+			singleton.DeleteInstance[*sql.DB]()
+			var userName string
+			Expect(Db().QueryRowContext(ctx, "SELECT user_name FROM user WHERE id = 'u-restore-1'").Scan(&userName)).To(Succeed())
+			Expect(userName).To(Equal("drilladmin"))
+		})
+
+		It("fails to restore from a backup file that does not exist, leaving the database intact", func() {
+			By("seeding user data in the current database")
+			_, err := Db().ExecContext(ctx, `INSERT INTO user (id, user_name, name, email, password, is_admin, created_at, updated_at)
+				VALUES ('u-restore-2', 'keepme', 'keepme', 'keepme@example.com', 'x', 1, datetime('now'), datetime('now'))`)
+			Expect(err).ToNot(HaveOccurred())
+
+			By("attempting a restore from a nonexistent file")
+			missingPath := filepath.Join(tempFolder, "does_not_exist.db")
+			err = Restore(ctx, missingPath)
+			Expect(err).To(HaveOccurred())
+
+			By("verifying the database was not wiped")
+			var userName string
+			Expect(Db().QueryRowContext(ctx, "SELECT user_name FROM user WHERE id = 'u-restore-2'").Scan(&userName)).To(Succeed())
+			Expect(userName).To(Equal("keepme"))
+			_, statErr := os.Stat(missingPath)
+			Expect(statErr).To(MatchError(os.ErrNotExist))
+		})
+	})
 })

From d0d5403708c1232de53741856b1cfb035b807912 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 11 Sep 2026 22:26:28 -0400
Subject: [PATCH 131/200] feat(cli): add 'doctor' and 'search rebuild' commands
 to recover from FTS5 corruption (#6069)

* feat(db): add repair command to rebuild a corrupted FTS5 search index

A corrupted media_file_fts index made every scan fail with 'database disk
image is malformed', and sqlite3's built-in 'rebuild' command cannot repair
contentless FTS5 tables, leaving users to hand-drop tables and triggers.

Add 'navidrome db repair': it runs PRAGMA integrity_check, and when the
reported corruption is confined to the FTS5 search tables, drops and
recreates the three tables and their nine triggers and repopulates them
from the base tables (which hold all the data, so nothing is lost). The
result is verified with the FTS5-native 'integrity-check' command, which
reads only the rebuilt indexes instead of re-scanning the whole database
(on a 761MB production copy: ~9s full check, ~1s rebuild, sub-second
verify). A --rebuild flag forces the rebuild even when the check passes,
for silently desynced indexes. The rebuild refuses to run while migrations
are pending, and a schema-comparison test guards the duplicated DDL against
drifting from the migration.

The DbPath existence check and the YES confirmation prompt, previously
copy-pasted across the backup commands, are extracted into shared cmd
helpers used by both backup and repair.

Part of #6067

* fix(db): type the FTS migration version as int64 for 32-bit builds

The untyped constant defaults to int, which overflows on arm/v7 and 386.

* feat(db): split repair into 'db doctor' and 'search rebuild' commands

A single 'db repair' command promised more than it delivered: the only thing
it could actually repair was the search index, and its diagnosis and its fix
were welded together, so a forced rebuild paid the full integrity check twice.

Split it: 'navidrome db doctor' is strictly read-only, runs both PRAGMA
integrity_check and PRAGMA foreign_key_check, and routes the user (to
'search rebuild' when corruption is FTS-only, to backup/.recover otherwise).
'navidrome search rebuild' just rebuilds and verifies the FTS index, which
takes ~2s on a prod-size library instead of ~19s.

* refactor(cmd): extract a testable doctor function and bound foreign key output

Extract the doctor routing (check, classify, advise) into a function that
takes an io.Writer, so the advice paths are unit-tested and the process exit
happens in the cobra wrapper after the DB is closed (os.Exit was skipping the
deferred close, leaving WAL/SHM files behind on the unhealthy paths).

Aggregate foreign_key_check by (table, parent): the raw pragma emits one row
per orphan, which is unbounded output on a large corrupted library. Also
make confirmYES take an io.Reader, drop the unused return from the renamed
requireExistingDB, share the FTS table list with the tests, and stop the
schema-guard specs from paying for a seeded database they never use.

* docs(cmd): promise 'never alters your data' instead of 'never modifies the database'

Closing the doctor's connection can checkpoint a stale WAL into the main
file (as any SQLite tool does), so the byte-level claim was too strong. The
checks themselves are read-only and no logical content ever changes.

* fix(cmd): make 'db doctor' advice honest when checks are inconclusive

PRAGMA integrity_check stops at 100 errors and emits no marker row, so a
saturated result was being read as the whole picture. IntegrityCheck now sets
the limit itself and reports saturation as a truncated list, and doctor no
longer claims corruption is limited to the search index in that case.

Foreign key violations now print a next step instead of only flipping the
exit code: migrations run with foreign_keys off, so orphan rows are a
realistic leftover on a database that is not corrupt.

Also corrects the 'search rebuild' help, which promised that 'db doctor'
detects when a rebuild is needed -- integrity_check cannot see an index that
is merely out of sync; gives the never-migrated case its intended message
instead of a raw 'no such table: goose_db_version'; and extracts
rebuildSearchIndex so the database is closed before log.Fatal exits.

* refactor(cmd): promote 'db doctor' to a top-level 'doctor' command

The 'db' group held a single subcommand, and the checks planned for it reach
past the database: config, music folder permissions, external tools. None of
those belong under 'db'.

Promoting it also evens out the shape of the pair. The command that finds the
problem is now top-level alongside 'search rebuild', the command that fixes
it, matching the 'brew doctor' convention users already expect.

'db doctor' has never been released, so no alias or deprecation is needed.

* refactor(db): tighten the doctor and search rebuild internals

Follow-up cleanup with no behaviour change except where noted.

integrity_check now asks the pragma for one row beyond the reported limit and
treats that extra row as the proof it truncated, instead of inferring truncation
from a saturated count. That distinguishes a list of exactly 100 issues from one
that was cut short -- the old test could not, and 100 was SQLite's own default,
so passing it was a no-op.

ForeignKeyCheck returns []FKViolation instead of pre-formatted English, moving
the prose to the layer that already owns the CLI vocabulary. The goose table
probe shared with isSchemaEmpty becomes hasGooseTable, so 'has this database
ever been migrated' has one spelling. Also folds ftsMigrationApplied into
requireFTSMigration, lifts printFindings out of a closure that captured nothing,
names the FTS trigger suffixes once, and corrects the ftsSchemaDDL comment: the
drift test compares against the full migration chain, not the single frozen
migration it claimed.

* fix(db): verify the rebuilt search index before committing it

RebuildFTS committed its transaction and only then ran the FTS5 integrity
check, from the caller. A rebuild that produced a bad index was therefore
already persisted by the time anyone noticed, leaving the user worse off than
before they ran the command.

The check now runs inside the transaction, so a rebuild that does not verify
rolls back and leaves the original index in place. VerifyFTS keeps its *sql.DB
signature for callers outside a transaction; the shared body takes the small
execer interface that both *sql.DB and *sql.Tx satisfy.

Adds a spec for the rollback: it removes a column the repopulating SELECT
reads, so the transaction fails after the drops, and asserts the old index
still answers queries.

* refactor(cmd): drop the unused io.Reader parameter from confirmYES

The reader was added as a test seam that no test ever used: all three callers
pass os.Stdin. Back to fmt.Scanln, which drops the parameter and the now-unused
os import from backup.go and search.go.

* fix(cmd): stop promising a scan clears every foreign key violation

doctor told the user to run 'navidrome scan -f' for any foreign key
violation. SQLStore.GC only purges albums, artists, folders, annotations,
bookmarks, tags and playlist tracks, so orphans elsewhere survive it and the
next doctor run still reports them. player.user_id references user(id) and no
scan phase touches that table at all.

The advice now says a scan clears some of them and the rest have to be removed
by hand, which keeps the next step the earlier round asked for without claiming
a cleanup that does not happen.

* docs(db): trim over-long comments on the doctor and rebuild paths

Six comments ran past two lines or repeated something already stated nearby.
The RebuildFTS doc claimed the rebuild rolls back on a column mismatch, which
the new 'verifies before committing' sentence already implies, and a spec
comment restated that same rationale a second time.

* docs: drop em dashes from the comments added in this branch
---
 cmd/backup.go      |  71 ++-------
 cmd/doctor.go      |  99 ++++++++++++
 cmd/doctor_test.go | 124 +++++++++++++++
 cmd/search.go      |  55 +++++++
 cmd/utils.go       |  20 +++
 db/db.go           |  17 ++-
 db/export_test.go  |   4 +
 db/repair.go       | 367 +++++++++++++++++++++++++++++++++++++++++++++
 db/repair_test.go  | 309 ++++++++++++++++++++++++++++++++++++++
 9 files changed, 1001 insertions(+), 65 deletions(-)
 create mode 100644 cmd/doctor.go
 create mode 100644 cmd/doctor_test.go
 create mode 100644 cmd/search.go
 create mode 100644 db/repair.go
 create mode 100644 db/repair_test.go

diff --git a/cmd/backup.go b/cmd/backup.go
index eca78a272..932a833f2 100644
--- a/cmd/backup.go
+++ b/cmd/backup.go
@@ -2,10 +2,7 @@ package cmd
 
 import (
 	"context"
-	"fmt"
-	"os"
 	"path/filepath"
-	"strings"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -79,19 +76,7 @@ func runBackup(ctx context.Context) {
 		conf.Server.Backup.Path = conf.NewDir(backupDir)
 	}
 
-	idx := strings.LastIndex(conf.Server.DbPath, "?")
-	var path string
-
-	if idx == -1 {
-		path = conf.Server.DbPath
-	} else {
-		path = conf.Server.DbPath[:idx]
-	}
-
-	if _, err := os.Stat(path); os.IsNotExist(err) {
-		log.Fatal("No existing database", "path", path)
-		return
-	}
+	requireExistingDB()
 
 	start := time.Now()
 	path, err := db.Backup(ctx)
@@ -112,32 +97,13 @@ func runPrune(ctx context.Context) {
 		conf.Server.Backup.Count = backupCount
 	}
 
-	if conf.Server.Backup.Count == 0 && !force {
-		fmt.Println("Warning: pruning ALL backups")
-		fmt.Printf("Please enter YES (all caps) to continue: ")
-		var input string
-		_, err := fmt.Scanln(&input)
-
-		if input != "YES" || err != nil {
-			log.Warn("Prune cancelled")
-			return
-		}
-	}
-
-	idx := strings.LastIndex(conf.Server.DbPath, "?")
-	var path string
-
-	if idx == -1 {
-		path = conf.Server.DbPath
-	} else {
-		path = conf.Server.DbPath[:idx]
-	}
-
-	if _, err := os.Stat(path); os.IsNotExist(err) {
-		log.Fatal("No existing database", "path", path)
+	if conf.Server.Backup.Count == 0 && !force && !confirmYES("Warning: pruning ALL backups") {
+		log.Warn("Prune cancelled")
 		return
 	}
 
+	requireExistingDB()
+
 	start := time.Now()
 	count, err := db.Prune(ctx)
 	if err != nil {
@@ -150,19 +116,7 @@ func runPrune(ctx context.Context) {
 }
 
 func runRestore(ctx context.Context) {
-	idx := strings.LastIndex(conf.Server.DbPath, "?")
-	var path string
-
-	if idx == -1 {
-		path = conf.Server.DbPath
-	} else {
-		path = conf.Server.DbPath[:idx]
-	}
-
-	if _, err := os.Stat(path); os.IsNotExist(err) {
-		log.Fatal("No existing database", "path", path)
-		return
-	}
+	requireExistingDB()
 
 	// A relative --backup-file is resolved against Backup.Path, the same folder
 	// `backup create` writes to. Without this, the value was treated as relative
@@ -176,16 +130,9 @@ func runRestore(ctx context.Context) {
 		restorePath = filepath.Join(backupPath, restorePath)
 	}
 
-	if !force {
-		fmt.Println("Warning: restoring the Navidrome database should only be done offline, especially if your backup is very old.")
-		fmt.Printf("Please enter YES (all caps) to continue: ")
-		var input string
-		_, err := fmt.Scanln(&input)
-
-		if input != "YES" || err != nil {
-			log.Warn("Restore cancelled")
-			return
-		}
+	if !force && !confirmYES("Warning: restoring the Navidrome database should only be done offline, especially if your backup is very old.") {
+		log.Warn("Restore cancelled")
+		return
 	}
 
 	start := time.Now()
diff --git a/cmd/doctor.go b/cmd/doctor.go
new file mode 100644
index 000000000..fd0eb1cd7
--- /dev/null
+++ b/cmd/doctor.go
@@ -0,0 +1,99 @@
+package cmd
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/navidrome/navidrome/db"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(doctorCmd)
+}
+
+var doctorCmd = &cobra.Command{
+	Use:   "doctor",
+	Short: "Check your Navidrome installation for problems",
+	Long: "Run read-only health checks and report what was found. Checks the database for " +
+		"corruption and foreign key violations, and reports whether 'navidrome search rebuild' " +
+		"can fix what it finds. This command never alters your data",
+	Run: func(cmd *cobra.Command, _ []string) {
+		runDoctor(cmd.Context())
+	},
+}
+
+func runDoctor(ctx context.Context) {
+	requireExistingDB()
+
+	healthy := doctor(ctx, db.Db(), os.Stdout)
+	db.Close(ctx)
+	if !healthy {
+		os.Exit(1)
+	}
+}
+
+const recoveryAdvice = "Restore a backup (navidrome backup restore), or try SQLite's '.recover' command."
+
+func printFindings(out io.Writer, check, noun string, items []string) {
+	fmt.Fprintf(out, "%s reported %d %s:\n", check, len(items), noun)
+	for _, item := range items {
+		fmt.Fprintln(out, "  "+item)
+	}
+}
+
+func doctor(ctx context.Context, database *sql.DB, out io.Writer) bool {
+	healthy := true
+
+	fmt.Fprintln(out, "Checking database integrity...")
+	issues, truncated, err := db.IntegrityCheck(ctx, database)
+	switch {
+	case err != nil:
+		fmt.Fprintln(out, "The integrity check could not complete: "+err.Error())
+		fmt.Fprintln(out, recoveryAdvice)
+		return false
+	case len(issues) == 0:
+		fmt.Fprintln(out, "Integrity check passed.")
+	default:
+		healthy = false
+		printFindings(out, "Integrity check", "issue(s)", issues)
+		switch {
+		case truncated:
+			fmt.Fprintln(out, "The integrity check stopped at its limit, so the damage may reach further than listed.")
+			fmt.Fprintln(out, recoveryAdvice)
+		case db.IsFTSCorruptionOnly(issues):
+			fmt.Fprintln(out, "Corruption is limited to the search index. Run 'navidrome search rebuild' to fix it.")
+		default:
+			fmt.Fprintln(out, "Corruption is not limited to the search index, and cannot be repaired automatically.")
+			fmt.Fprintln(out, recoveryAdvice)
+		}
+	}
+
+	fmt.Fprintln(out, "Checking foreign keys...")
+	violations, err := db.ForeignKeyCheck(ctx, database)
+	switch {
+	case err != nil:
+		healthy = false
+		fmt.Fprintln(out, "The foreign key check could not complete: "+err.Error())
+	case len(violations) == 0:
+		fmt.Fprintln(out, "Foreign key check passed.")
+	default:
+		healthy = false
+		lines := make([]string, 0, len(violations))
+		for _, v := range violations {
+			lines = append(lines,
+				fmt.Sprintf("%s: %d row(s) reference missing rows in %s", v.Table, v.Count, v.Parent))
+		}
+		printFindings(out, "Foreign key check", "violation(s)", lines)
+		fmt.Fprintln(out, "These are orphaned rows, not corruption. 'navidrome scan -f' clears some of them "+
+			"in library data; the rest have to be removed by hand.")
+	}
+
+	if healthy {
+		fmt.Fprintln(out, "Database is healthy.")
+	}
+	return healthy
+}
diff --git a/cmd/doctor_test.go b/cmd/doctor_test.go
new file mode 100644
index 000000000..7f8cd9728
--- /dev/null
+++ b/cmd/doctor_test.go
@@ -0,0 +1,124 @@
+package cmd
+
+import (
+	"context"
+	"database/sql"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/navidrome/navidrome/db"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("doctor", func() {
+	var (
+		ctx      context.Context
+		dbPath   string
+		database *sql.DB
+		out      *strings.Builder
+		reopen   func()
+	)
+
+	// A file-backed DB so specs can corrupt raw pages; a table named like a real FTS
+	// search table so IsFTSCorruptionOnly matches, plus a parent/child pair for FK checks.
+	BeforeEach(func() {
+		ctx = context.Background()
+		dbPath = filepath.Join(GinkgoT().TempDir(), "doctor.db")
+		reopen = func() {
+			var err error
+			database, err = sql.Open(db.Dialect, dbPath)
+			Expect(err).ToNot(HaveOccurred())
+			database.SetMaxOpenConns(1)
+		}
+		reopen()
+		DeferCleanup(func() { _ = database.Close() })
+
+		for _, stmt := range []string{
+			`create virtual table media_file_fts using fts5(title, content='', content_rowid='rowid')`,
+			`insert into media_file_fts(rowid, title) values (1, 'teenage lobotomy'), (2, 'rockaway beach')`,
+			`create table library(id integer primary key)`,
+			`create table media_file(id integer primary key, library_id integer references library(id))`,
+		} {
+			_, err := database.ExecContext(ctx, stmt)
+			Expect(err).ToNot(HaveOccurred())
+		}
+		out = &strings.Builder{}
+	})
+
+	It("reports a healthy database", func() {
+		Expect(doctor(ctx, database, out)).To(BeTrue())
+		Expect(out.String()).To(ContainSubstring("Database is healthy."))
+	})
+
+	It("points to 'search rebuild' when corruption is limited to the search index", func() {
+		_, err := database.ExecContext(ctx,
+			`update media_file_fts_data set block = x'deadbeefdeadbeef' where id > 1`)
+		Expect(err).ToNot(HaveOccurred())
+
+		Expect(doctor(ctx, database, out)).To(BeFalse())
+		Expect(out.String()).To(ContainSubstring("navidrome search rebuild"))
+	})
+
+	It("points to a backup restore when corruption is not limited to the search index", func() {
+		_, err := database.ExecContext(ctx,
+			`insert into library(id)
+			 with recursive s(x) as (select 1 union all select x+1 from s where x < 200)
+			 select x from s`)
+		Expect(err).ToNot(HaveOccurred())
+		var rootPage, pageSize int64
+		Expect(database.QueryRowContext(ctx,
+			`select rootpage from sqlite_master where name = 'library'`).Scan(&rootPage)).To(Succeed())
+		Expect(database.QueryRowContext(ctx, `pragma page_size`).Scan(&pageSize)).To(Succeed())
+		Expect(database.Close()).To(Succeed())
+		f, err := os.OpenFile(dbPath, os.O_WRONLY, 0600)
+		Expect(err).ToNot(HaveOccurred())
+		_, err = f.WriteAt([]byte{0xde, 0xad, 0xbe, 0xef, 0xde, 0xad, 0xbe, 0xef}, (rootPage-1)*pageSize+40)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(f.Close()).To(Succeed())
+		reopen()
+
+		Expect(doctor(ctx, database, out)).To(BeFalse())
+		Expect(out.String()).To(ContainSubstring("backup restore"))
+		Expect(out.String()).ToNot(ContainSubstring("search rebuild"))
+	})
+
+	It("reports foreign key violations", func() {
+		_, err := database.ExecContext(ctx, `pragma foreign_keys = off`)
+		Expect(err).ToNot(HaveOccurred())
+		_, err = database.ExecContext(ctx, `insert into media_file(id, library_id) values (1, 999)`)
+		Expect(err).ToNot(HaveOccurred())
+
+		Expect(doctor(ctx, database, out)).To(BeFalse())
+		Expect(out.String()).To(ContainSubstring("Foreign key check reported"))
+		Expect(out.String()).To(ContainSubstring("media_file"))
+		Expect(out.String()).To(ContainSubstring("navidrome scan -f"))
+		// GC never touches player, share or playqueue, so don't promise a full cleanup.
+		Expect(out.String()).To(ContainSubstring("removed by hand"))
+	})
+
+	// Every issue names an FTS-like index, so IsFTSCorruptionOnly alone would send the
+	// user to 'search rebuild', but the pragma stopped at its limit without saying so.
+	It("does not blame the search index when the issue list is truncated", func() {
+		for _, stmt := range []string{
+			`create table t(a, b)`,
+			`with recursive s(x) as (select 1 union all select x+1 from s where x < 300)
+			 insert into t select x, x + 10000 from s`,
+			`create index media_file_fts_probe on t(a)`,
+			`pragma writable_schema=on`,
+			`update sqlite_master set sql = 'CREATE INDEX media_file_fts_probe ON t(b)'
+			 where name = 'media_file_fts_probe'`,
+		} {
+			_, err := database.ExecContext(ctx, stmt)
+			Expect(err).ToNot(HaveOccurred())
+		}
+		Expect(database.Close()).To(Succeed())
+		reopen()
+
+		Expect(doctor(ctx, database, out)).To(BeFalse())
+		Expect(out.String()).ToNot(ContainSubstring("search rebuild"))
+		Expect(out.String()).To(ContainSubstring("backup restore"))
+	})
+})
diff --git a/cmd/search.go b/cmd/search.go
new file mode 100644
index 000000000..46b7eebd5
--- /dev/null
+++ b/cmd/search.go
@@ -0,0 +1,55 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/navidrome/navidrome/db"
+	"github.com/navidrome/navidrome/log"
+	"github.com/spf13/cobra"
+)
+
+var searchRebuildForce bool
+
+func init() {
+	rootCmd.AddCommand(searchRoot)
+
+	searchRebuildCmd.Flags().BoolVarP(&searchRebuildForce, "force", "f", false, "bypass rebuild confirmation")
+	searchRoot.AddCommand(searchRebuildCmd)
+}
+
+var (
+	searchRoot = &cobra.Command{
+		Use:   "search",
+		Short: "Search index maintenance",
+	}
+
+	searchRebuildCmd = &cobra.Command{
+		Use:   "rebuild",
+		Short: "Rebuild the full-text search index",
+		Long: "Drop and rebuild the full-text search index from the library data. Fixes a corrupted " +
+			"or desynced search index without any data loss. Note that 'navidrome doctor' detects a " +
+			"corrupted index, but cannot tell when the index has merely drifted out of sync with the " +
+			"library. This must be done offline",
+		Run: func(cmd *cobra.Command, _ []string) {
+			runSearchRebuild(cmd.Context())
+		},
+	}
+)
+
+func runSearchRebuild(ctx context.Context) {
+	requireExistingDB()
+
+	if !searchRebuildForce && !confirmYES("This will rebuild the search index. Make sure Navidrome is not running.") {
+		log.Warn("Rebuild cancelled")
+		return
+	}
+
+	fmt.Println("Rebuilding the search index...")
+	err := db.RebuildFTS(ctx, db.Db())
+	db.Close(ctx)
+	if err != nil {
+		log.Fatal("Error rebuilding the search index", err)
+	}
+	fmt.Println("Search index rebuilt successfully.")
+}
diff --git a/cmd/utils.go b/cmd/utils.go
index 74da51828..a67f720ac 100644
--- a/cmd/utils.go
+++ b/cmd/utils.go
@@ -5,8 +5,11 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"os"
+	"strings"
 	"text/tabwriter"
 
+	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
@@ -15,6 +18,23 @@ import (
 	"github.com/navidrome/navidrome/persistence"
 )
 
+// requireExistingDB aborts the command when the database file (DbPath minus DSN
+// params) does not exist.
+func requireExistingDB() {
+	path, _, _ := strings.Cut(conf.Server.DbPath, "?")
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		log.Fatal("No existing database", "path", path)
+	}
+}
+
+func confirmYES(warning string) bool {
+	fmt.Println(warning)
+	fmt.Printf("Please enter YES (all caps) to continue: ")
+	var input string
+	_, err := fmt.Scanln(&input)
+	return input == "YES" && err == nil
+}
+
 // newTabWriter keeps every CLI table on the same column settings.
 func newTabWriter(out io.Writer) *tabwriter.Writer {
 	return tabwriter.NewWriter(out, 0, 4, 2, ' ', 0)
diff --git a/db/db.go b/db/db.go
index c53aa364a..685886edb 100644
--- a/db/db.go
+++ b/db/db.go
@@ -157,13 +157,24 @@ func hasPendingMigrations(ctx context.Context, db *sql.DB, folder string) bool {
 	return l.numPending > 0
 }
 
+// hasGooseTable reports whether goose's bookkeeping table exists, i.e. whether the
+// database has ever been migrated.
+func hasGooseTable(ctx context.Context, db *sql.DB) (bool, error) {
+	var name string
+	err := db.QueryRowContext(ctx,
+		"SELECT name FROM sqlite_master WHERE type='table' AND name='goose_db_version'").Scan(&name)
+	if errors.Is(err, sql.ErrNoRows) {
+		return false, nil
+	}
+	return err == nil, err
+}
+
 func isSchemaEmpty(ctx context.Context, db *sql.DB) bool {
-	rows, err := db.QueryContext(ctx, "SELECT name FROM sqlite_master WHERE type='table' AND name='goose_db_version';") // nolint:rowserrcheck
+	found, err := hasGooseTable(ctx, db)
 	if err != nil {
 		log.Fatal(ctx, "Database could not be opened!", err)
 	}
-	defer rows.Close()
-	return !rows.Next()
+	return !found
 }
 
 type logAdapter struct {
diff --git a/db/export_test.go b/db/export_test.go
index 02b88cd66..d2034bcdb 100644
--- a/db/export_test.go
+++ b/db/export_test.go
@@ -2,6 +2,10 @@ package db
 
 // Definitions for testing private methods
 var (
+	EmbedMigrations      = embedMigrations
+	FTSTables            = ftsTables
+	FTSTriggerSuffixes   = ftsTriggerSuffixes
+	FTSSearchMigration   = ftsSearchMigration
 	IsSchemaEmpty        = isSchemaEmpty
 	BackupPath           = backupPath
 	OptimizeDBAt         = optimizeAt
diff --git a/db/repair.go b/db/repair.go
new file mode 100644
index 000000000..7f8b8d044
--- /dev/null
+++ b/db/repair.go
@@ -0,0 +1,367 @@
+package db
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"slices"
+	"strings"
+)
+
+var ftsTables = []string{"media_file_fts", "album_fts", "artist_fts"}
+
+var ftsTriggerSuffixes = []string{"_ai", "_ad", "_au"}
+
+// integrityCheckMaxIssues bounds the problems reported; IntegrityCheck asks the
+// pragma for one extra row, because it truncates without emitting any marker.
+const integrityCheckMaxIssues = 100
+
+// IntegrityCheck runs PRAGMA integrity_check and returns the problems it reports, or
+// an empty slice when healthy. The second value marks a list that was cut short.
+func IntegrityCheck(ctx context.Context, database *sql.DB) ([]string, bool, error) {
+	rows, err := database.QueryContext(ctx,
+		fmt.Sprintf("PRAGMA integrity_check(%d)", integrityCheckMaxIssues+1))
+	if err != nil {
+		return nil, false, fmt.Errorf("running integrity_check: %w", err)
+	}
+	defer rows.Close()
+
+	var issues []string
+	for rows.Next() {
+		var line string
+		if err := rows.Scan(&line); err != nil {
+			return nil, false, fmt.Errorf("reading integrity_check results: %w", err)
+		}
+		issues = append(issues, line)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, false, fmt.Errorf("reading integrity_check results: %w", err)
+	}
+	if len(issues) == 1 && issues[0] == "ok" {
+		return nil, false, nil
+	}
+	if len(issues) > integrityCheckMaxIssues {
+		return issues[:integrityCheckMaxIssues], true, nil
+	}
+	return issues, false, nil
+}
+
+// FKViolation counts the rows in Table that reference missing rows in Parent.
+type FKViolation struct {
+	Table  string
+	Parent string
+	Count  int64
+}
+
+// ForeignKeyCheck runs PRAGMA foreign_key_check, aggregated per (table, parent) pair
+// because the raw pragma emits one row per orphan, unbounded on a large library.
+func ForeignKeyCheck(ctx context.Context, database *sql.DB) ([]FKViolation, error) {
+	rows, err := database.QueryContext(ctx,
+		`SELECT "table", "parent", count(*) FROM pragma_foreign_key_check GROUP BY "table", "parent"`)
+	if err != nil {
+		return nil, fmt.Errorf("running foreign_key_check: %w", err)
+	}
+	defer rows.Close()
+
+	var violations []FKViolation
+	for rows.Next() {
+		var v FKViolation
+		if err := rows.Scan(&v.Table, &v.Parent, &v.Count); err != nil {
+			return nil, fmt.Errorf("reading foreign_key_check results: %w", err)
+		}
+		violations = append(violations, v)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("reading foreign_key_check results: %w", err)
+	}
+	return violations, nil
+}
+
+// IsFTSCorruptionOnly reports whether every integrity issue refers to one of the
+// FTS5 search tables, meaning RebuildFTS can fully repair the database.
+func IsFTSCorruptionOnly(issues []string) bool {
+	if len(issues) == 0 {
+		return false
+	}
+	for _, line := range issues {
+		if !slices.ContainsFunc(ftsTables, func(table string) bool { return strings.Contains(line, table) }) {
+			return false
+		}
+	}
+	return true
+}
+
+// execer is the subset of *sql.DB and *sql.Tx that verifyFTS needs.
+type execer interface {
+	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
+}
+
+// VerifyFTS runs the FTS5 'integrity-check' command on each search table. Unlike a
+// full PRAGMA integrity_check, it reads only the FTS indexes, not the whole database.
+func VerifyFTS(ctx context.Context, database *sql.DB) error {
+	return verifyFTS(ctx, database)
+}
+
+func verifyFTS(ctx context.Context, database execer) error {
+	for _, table := range ftsTables {
+		stmt := fmt.Sprintf("INSERT INTO %[1]s(%[1]s) VALUES('integrity-check')", table) //nolint:gosec // fixed table list
+		if _, err := database.ExecContext(ctx, stmt); err != nil {
+			return fmt.Errorf("verifying %s: %w", table, err)
+		}
+	}
+	return nil
+}
+
+const ftsSearchMigration int64 = 20260220173400
+
+var errNotMigrated = errors.New("the FTS search migration has not been applied yet; start Navidrome once to migrate the database first")
+
+// requireFTSMigration fails unless the FTS search migration has run. The goose table
+// is probed separately because a query against a missing table fails at prepare time.
+func requireFTSMigration(ctx context.Context, database *sql.DB) error {
+	migrated, err := hasGooseTable(ctx, database)
+	if err != nil {
+		return fmt.Errorf("checking FTS migration status: %w", err)
+	}
+	if !migrated {
+		return errNotMigrated
+	}
+	var applied int
+	if err := database.QueryRowContext(ctx,
+		"SELECT count(*) FROM goose_db_version WHERE version_id = ?", ftsSearchMigration).Scan(&applied); err != nil {
+		return fmt.Errorf("checking FTS migration status: %w", err)
+	}
+	if applied == 0 {
+		return errNotMigrated
+	}
+	return nil
+}
+
+// RebuildFTS drops the FTS5 search tables and their triggers, recreates them from the
+// base tables, and verifies the result before committing. The tables are contentless,
+// so no user data is lost. It needs only the FTS migration, not a fully migrated
+// schema, because a corrupted DB often cannot run pending migrations.
+func RebuildFTS(ctx context.Context, database *sql.DB) error {
+	if err := requireFTSMigration(ctx, database); err != nil {
+		return err
+	}
+
+	tx, err := database.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("starting FTS rebuild transaction: %w", err)
+	}
+	defer func() { _ = tx.Rollback() }()
+
+	var stmts []string
+	for _, table := range ftsTables {
+		for _, suffix := range ftsTriggerSuffixes {
+			stmts = append(stmts, "DROP TRIGGER IF EXISTS "+table+suffix)
+		}
+		stmts = append(stmts, "DROP TABLE IF EXISTS "+table)
+	}
+	stmts = append(stmts, ftsSchemaDDL...)
+	for _, stmt := range stmts {
+		if _, err := tx.ExecContext(ctx, stmt); err != nil {
+			return fmt.Errorf("rebuilding FTS schema: %w", err)
+		}
+	}
+	if err := verifyFTS(ctx, tx); err != nil {
+		return fmt.Errorf("the rebuilt search index did not verify: %w", err)
+	}
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("committing FTS rebuild: %w", err)
+	}
+	return nil
+}
+
+// ftsSchemaDDL must reproduce what the full migration chain produces, not what any
+// single migration does; the schema comparison in repair_test.go guards the drift.
+var ftsSchemaDDL = []string{
+	`
+		CREATE VIRTUAL TABLE IF NOT EXISTS media_file_fts USING fts5(
+			title, album, artist, album_artist,
+			sort_title, sort_album_name, sort_artist_name, sort_album_artist_name,
+			disc_subtitle, search_participants, search_normalized,
+			content='', content_rowid='rowid',
+			tokenize='unicode61 remove_diacritics 2'
+		)
+	`,
+	`
+		CREATE VIRTUAL TABLE IF NOT EXISTS album_fts USING fts5(
+			name, sort_album_name, album_artist,
+			search_participants, discs, catalog_num, album_version, search_normalized,
+			content='', content_rowid='rowid',
+			tokenize='unicode61 remove_diacritics 2'
+		)
+	`,
+	`
+		CREATE VIRTUAL TABLE IF NOT EXISTS artist_fts USING fts5(
+			name, sort_artist_name, search_normalized,
+			content='', content_rowid='rowid',
+			tokenize='unicode61 remove_diacritics 2'
+		)
+	`,
+	`
+		INSERT INTO media_file_fts(rowid, title, album, artist, album_artist,
+			sort_title, sort_album_name, sort_artist_name, sort_album_artist_name,
+			disc_subtitle, search_participants, search_normalized)
+		SELECT rowid, title, album, artist, album_artist,
+			sort_title, sort_album_name, sort_artist_name, sort_album_artist_name,
+			COALESCE(disc_subtitle, ''), COALESCE(search_participants, ''),
+			COALESCE(search_normalized, '')
+		FROM media_file
+	`,
+	`
+		INSERT INTO album_fts(rowid, name, sort_album_name, album_artist,
+			search_participants, discs, catalog_num, album_version, search_normalized)
+		SELECT rowid, name, COALESCE(sort_album_name, ''), COALESCE(album_artist, ''),
+			COALESCE(search_participants, ''), COALESCE(discs, ''),
+			COALESCE(catalog_num, ''),
+			COALESCE((SELECT group_concat(json_extract(je.value, '$.value'), ' ')
+				FROM json_each(album.tags, '$.albumversion') AS je), ''),
+			COALESCE(search_normalized, '')
+		FROM album
+	`,
+	`
+		INSERT INTO artist_fts(rowid, name, sort_artist_name, search_normalized)
+		SELECT rowid, name, COALESCE(sort_artist_name, ''), COALESCE(search_normalized, '')
+		FROM artist
+	`,
+	`
+		CREATE TRIGGER media_file_fts_ai AFTER INSERT ON media_file BEGIN
+			INSERT INTO media_file_fts(rowid, title, album, artist, album_artist,
+				sort_title, sort_album_name, sort_artist_name, sort_album_artist_name,
+				disc_subtitle, search_participants, search_normalized)
+			VALUES (NEW.rowid, NEW.title, NEW.album, NEW.artist, NEW.album_artist,
+				NEW.sort_title, NEW.sort_album_name, NEW.sort_artist_name, NEW.sort_album_artist_name,
+				COALESCE(NEW.disc_subtitle, ''), COALESCE(NEW.search_participants, ''),
+				COALESCE(NEW.search_normalized, ''));
+		END
+	`,
+	`
+		CREATE TRIGGER media_file_fts_ad AFTER DELETE ON media_file BEGIN
+			INSERT INTO media_file_fts(media_file_fts, rowid, title, album, artist, album_artist,
+				sort_title, sort_album_name, sort_artist_name, sort_album_artist_name,
+				disc_subtitle, search_participants, search_normalized)
+			VALUES ('delete', OLD.rowid, OLD.title, OLD.album, OLD.artist, OLD.album_artist,
+				OLD.sort_title, OLD.sort_album_name, OLD.sort_artist_name, OLD.sort_album_artist_name,
+				COALESCE(OLD.disc_subtitle, ''), COALESCE(OLD.search_participants, ''),
+				COALESCE(OLD.search_normalized, ''));
+		END
+	`,
+	`
+		CREATE TRIGGER media_file_fts_au AFTER UPDATE ON media_file
+		WHEN
+			OLD.title IS NOT NEW.title OR
+			OLD.album IS NOT NEW.album OR
+			OLD.artist IS NOT NEW.artist OR
+			OLD.album_artist IS NOT NEW.album_artist OR
+			OLD.sort_title IS NOT NEW.sort_title OR
+			OLD.sort_album_name IS NOT NEW.sort_album_name OR
+			OLD.sort_artist_name IS NOT NEW.sort_artist_name OR
+			OLD.sort_album_artist_name IS NOT NEW.sort_album_artist_name OR
+			OLD.disc_subtitle IS NOT NEW.disc_subtitle OR
+			OLD.search_participants IS NOT NEW.search_participants OR
+			OLD.search_normalized IS NOT NEW.search_normalized
+		BEGIN
+			INSERT INTO media_file_fts(media_file_fts, rowid, title, album, artist, album_artist,
+				sort_title, sort_album_name, sort_artist_name, sort_album_artist_name,
+				disc_subtitle, search_participants, search_normalized)
+			VALUES ('delete', OLD.rowid, OLD.title, OLD.album, OLD.artist, OLD.album_artist,
+				OLD.sort_title, OLD.sort_album_name, OLD.sort_artist_name, OLD.sort_album_artist_name,
+				COALESCE(OLD.disc_subtitle, ''), COALESCE(OLD.search_participants, ''),
+				COALESCE(OLD.search_normalized, ''));
+			INSERT INTO media_file_fts(rowid, title, album, artist, album_artist,
+				sort_title, sort_album_name, sort_artist_name, sort_album_artist_name,
+				disc_subtitle, search_participants, search_normalized)
+			VALUES (NEW.rowid, NEW.title, NEW.album, NEW.artist, NEW.album_artist,
+				NEW.sort_title, NEW.sort_album_name, NEW.sort_artist_name, NEW.sort_album_artist_name,
+				COALESCE(NEW.disc_subtitle, ''), COALESCE(NEW.search_participants, ''),
+				COALESCE(NEW.search_normalized, ''));
+		END
+	`,
+	`
+		CREATE TRIGGER album_fts_ai AFTER INSERT ON album BEGIN
+			INSERT INTO album_fts(rowid, name, sort_album_name, album_artist,
+				search_participants, discs, catalog_num, album_version, search_normalized)
+			VALUES (NEW.rowid, NEW.name, COALESCE(NEW.sort_album_name, ''), COALESCE(NEW.album_artist, ''),
+				COALESCE(NEW.search_participants, ''), COALESCE(NEW.discs, ''),
+				COALESCE(NEW.catalog_num, ''),
+				COALESCE((SELECT group_concat(json_extract(je.value, '$.value'), ' ')
+					FROM json_each(NEW.tags, '$.albumversion') AS je), ''),
+				COALESCE(NEW.search_normalized, ''));
+		END
+	`,
+	`
+		CREATE TRIGGER album_fts_ad AFTER DELETE ON album BEGIN
+			INSERT INTO album_fts(album_fts, rowid, name, sort_album_name, album_artist,
+				search_participants, discs, catalog_num, album_version, search_normalized)
+			VALUES ('delete', OLD.rowid, OLD.name, COALESCE(OLD.sort_album_name, ''), COALESCE(OLD.album_artist, ''),
+				COALESCE(OLD.search_participants, ''), COALESCE(OLD.discs, ''),
+				COALESCE(OLD.catalog_num, ''),
+				COALESCE((SELECT group_concat(json_extract(je.value, '$.value'), ' ')
+					FROM json_each(OLD.tags, '$.albumversion') AS je), ''),
+				COALESCE(OLD.search_normalized, ''));
+		END
+	`,
+	`
+		CREATE TRIGGER album_fts_au AFTER UPDATE ON album
+		WHEN
+			OLD.name IS NOT NEW.name OR
+			OLD.sort_album_name IS NOT NEW.sort_album_name OR
+			OLD.album_artist IS NOT NEW.album_artist OR
+			OLD.search_participants IS NOT NEW.search_participants OR
+			OLD.discs IS NOT NEW.discs OR
+			OLD.catalog_num IS NOT NEW.catalog_num OR
+			OLD.tags IS NOT NEW.tags OR
+			OLD.search_normalized IS NOT NEW.search_normalized
+		BEGIN
+			INSERT INTO album_fts(album_fts, rowid, name, sort_album_name, album_artist,
+				search_participants, discs, catalog_num, album_version, search_normalized)
+			VALUES ('delete', OLD.rowid, OLD.name, COALESCE(OLD.sort_album_name, ''), COALESCE(OLD.album_artist, ''),
+				COALESCE(OLD.search_participants, ''), COALESCE(OLD.discs, ''),
+				COALESCE(OLD.catalog_num, ''),
+				COALESCE((SELECT group_concat(json_extract(je.value, '$.value'), ' ')
+					FROM json_each(OLD.tags, '$.albumversion') AS je), ''),
+				COALESCE(OLD.search_normalized, ''));
+			INSERT INTO album_fts(rowid, name, sort_album_name, album_artist,
+				search_participants, discs, catalog_num, album_version, search_normalized)
+			VALUES (NEW.rowid, NEW.name, COALESCE(NEW.sort_album_name, ''), COALESCE(NEW.album_artist, ''),
+				COALESCE(NEW.search_participants, ''), COALESCE(NEW.discs, ''),
+				COALESCE(NEW.catalog_num, ''),
+				COALESCE((SELECT group_concat(json_extract(je.value, '$.value'), ' ')
+					FROM json_each(NEW.tags, '$.albumversion') AS je), ''),
+				COALESCE(NEW.search_normalized, ''));
+		END
+	`,
+	`
+		CREATE TRIGGER artist_fts_ai AFTER INSERT ON artist BEGIN
+			INSERT INTO artist_fts(rowid, name, sort_artist_name, search_normalized)
+			VALUES (NEW.rowid, NEW.name, COALESCE(NEW.sort_artist_name, ''),
+				COALESCE(NEW.search_normalized, ''));
+		END
+	`,
+	`
+		CREATE TRIGGER artist_fts_ad AFTER DELETE ON artist BEGIN
+			INSERT INTO artist_fts(artist_fts, rowid, name, sort_artist_name, search_normalized)
+			VALUES ('delete', OLD.rowid, OLD.name, COALESCE(OLD.sort_artist_name, ''),
+				COALESCE(OLD.search_normalized, ''));
+		END
+	`,
+	`
+		CREATE TRIGGER artist_fts_au AFTER UPDATE ON artist
+		WHEN
+			OLD.name IS NOT NEW.name OR
+			OLD.sort_artist_name IS NOT NEW.sort_artist_name OR
+			OLD.search_normalized IS NOT NEW.search_normalized
+		BEGIN
+			INSERT INTO artist_fts(artist_fts, rowid, name, sort_artist_name, search_normalized)
+			VALUES ('delete', OLD.rowid, OLD.name, COALESCE(OLD.sort_artist_name, ''),
+				COALESCE(OLD.search_normalized, ''));
+			INSERT INTO artist_fts(rowid, name, sort_artist_name, search_normalized)
+			VALUES (NEW.rowid, NEW.name, COALESCE(NEW.sort_artist_name, ''),
+				COALESCE(NEW.search_normalized, ''));
+		END
+	`,
+}
diff --git a/db/repair_test.go b/db/repair_test.go
new file mode 100644
index 000000000..eb7321939
--- /dev/null
+++ b/db/repair_test.go
@@ -0,0 +1,309 @@
+package db_test
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/navidrome/navidrome/db"
+	"github.com/pressly/goose/v3"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// newDB returns an in-memory database migrated up to the given goose version
+// (0 = fully migrated).
+func newDB(ctx context.Context, upTo int64) *sql.DB {
+	GinkgoHelper()
+	d, err := sql.Open(db.Dialect, "file::memory:")
+	Expect(err).ToNot(HaveOccurred())
+	d.SetMaxOpenConns(1) // non-shared :memory:, a second conn would be an empty DB
+	DeferCleanup(func() { _ = d.Close() })
+
+	_, err = d.ExecContext(ctx, "PRAGMA foreign_keys=off")
+	Expect(err).ToNot(HaveOccurred())
+	goose.SetBaseFS(db.EmbedMigrations)
+	goose.SetLogger(goose.NopLogger())
+	DeferCleanup(func() { goose.SetBaseFS(nil) })
+	Expect(goose.SetDialect(db.Dialect)).To(Succeed())
+	if upTo == 0 {
+		Expect(goose.UpContext(ctx, d, "migrations")).To(Succeed())
+	} else {
+		Expect(goose.UpToContext(ctx, d, "migrations", upTo)).To(Succeed())
+	}
+	return d
+}
+
+// openMismatchedIndexDB builds a database whose index is declared over a different
+// column than the one it was populated from, so integrity_check reports one issue per row.
+func openMismatchedIndexDB(ctx context.Context, rows int) *sql.DB {
+	GinkgoHelper()
+	path := filepath.Join(GinkgoT().TempDir(), "mismatched.db")
+	open := func() *sql.DB {
+		d, err := sql.Open(db.Dialect, path)
+		Expect(err).ToNot(HaveOccurred())
+		d.SetMaxOpenConns(1)
+		return d
+	}
+	d := open()
+	for _, stmt := range []string{
+		`create table t(a, b)`,
+		fmt.Sprintf(`with recursive s(x) as (select 1 union all select x+1 from s where x < %d)
+		 insert into t select x, x + 10000 from s`, rows),
+		`create index i on t(a)`,
+		`pragma writable_schema=on`,
+		`update sqlite_master set sql = 'CREATE INDEX i ON t(b)' where name = 'i'`,
+	} {
+		_, err := d.ExecContext(ctx, stmt)
+		Expect(err).ToNot(HaveOccurred())
+	}
+	Expect(d.Close()).To(Succeed()) // reopen so SQLite reparses the doctored schema
+
+	d = open()
+	DeferCleanup(func() { _ = d.Close() })
+	return d
+}
+
+var _ = Describe("IsFTSCorruptionOnly", func() {
+	It("is true when every issue mentions an FTS search table", func() {
+		Expect(db.IsFTSCorruptionOnly([]string{
+			`fts5: corruption found reading blob 42 from table "media_file_fts"`,
+			`malformed inverted index for FTS5 table main.album_fts`,
+			`fts5: corruption in "artist_fts"`,
+		})).To(BeTrue())
+	})
+
+	It("is false when any issue is outside the FTS search tables", func() {
+		Expect(db.IsFTSCorruptionOnly([]string{
+			`fts5: corruption found reading blob 42 from table "media_file_fts"`,
+			`*** in database main ***`,
+		})).To(BeFalse())
+	})
+
+	It("is false when there are no issues", func() {
+		Expect(db.IsFTSCorruptionOnly(nil)).To(BeFalse())
+	})
+})
+
+var _ = Describe("RebuildFTS schema guard", func() {
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = context.Background()
+	})
+
+	It("refuses to run on a schema older than the FTS migration", func() {
+		old := newDB(ctx, db.FTSSearchMigration-1)
+
+		err := db.RebuildFTS(ctx, old)
+		Expect(err).To(MatchError(ContainSubstring("migration")))
+	})
+
+	It("refuses to run on a database that was never migrated", func() {
+		empty, err := sql.Open(db.Dialect, "file::memory:")
+		Expect(err).ToNot(HaveOccurred())
+		empty.SetMaxOpenConns(1)
+		DeferCleanup(func() { _ = empty.Close() })
+
+		Expect(db.RebuildFTS(ctx, empty)).To(MatchError(ContainSubstring("start Navidrome once")))
+	})
+
+	It("runs on a post-FTS schema even when newer migrations are pending", func() {
+		behind := newDB(ctx, 20260702152457)
+
+		Expect(db.RebuildFTS(ctx, behind)).To(Succeed())
+	})
+})
+
+var _ = Describe("Repair", func() {
+	var (
+		ctx      context.Context
+		database *sql.DB
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		database = newDB(ctx, 0)
+
+		for _, stmt := range []string{
+			`insert into artist(id, name, search_normalized) values ('ar-1', 'Ramones', 'ramones')`,
+			`insert into album(id, name, search_normalized) values ('al-1', 'Rocket to Russia', 'rocket to russia')`,
+			`insert into media_file(id, title, search_normalized) values ('mf-1', 'Teenage Lobotomy', 'teenage lobotomy')`,
+			`insert into media_file(id, title, search_normalized) values ('mf-2', 'Rockaway Beach', 'rockaway beach')`,
+		} {
+			_, err := database.ExecContext(ctx, stmt)
+			Expect(err).ToNot(HaveOccurred())
+		}
+	})
+
+	corruptFTS := func(table string) {
+		// 8+ bytes of garbage: a 4-byte blob still parses as a valid empty structure record
+		_, err := database.ExecContext(ctx, `update `+table+`_data set block = x'deadbeefdeadbeef' where id > 1`) //nolint:gosec
+		Expect(err).ToNot(HaveOccurred())
+	}
+
+	searchFTS := func(table, term string) int {
+		var count int
+		err := database.QueryRowContext(ctx, `select count(*) from `+table+` where `+table+` match ?`, term).Scan(&count)
+		Expect(err).ToNot(HaveOccurred())
+		return count
+	}
+
+	// ftsSchema returns name -> whitespace-normalized DDL for the FTS tables,
+	// their shadow tables, and their triggers.
+	ftsSchema := func() map[string]string {
+		rows, err := database.QueryContext(ctx,
+			`select name, sql from sqlite_master where name like '%_fts%' and sql is not null`)
+		Expect(err).ToNot(HaveOccurred())
+		defer rows.Close()
+		ws := regexp.MustCompile(`\s+`)
+		schema := map[string]string{}
+		for rows.Next() {
+			var name, ddl string
+			Expect(rows.Scan(&name, &ddl)).To(Succeed())
+			schema[name] = ws.ReplaceAllString(ddl, " ")
+		}
+		Expect(rows.Err()).ToNot(HaveOccurred())
+		return schema
+	}
+
+	Describe("IntegrityCheck", func() {
+		It("returns no issues for a healthy database", func() {
+			issues, truncated, err := db.IntegrityCheck(ctx, database)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(issues).To(BeEmpty())
+			Expect(truncated).To(BeFalse())
+		})
+
+		It("reports corruption in an FTS index", func() {
+			corruptFTS("media_file_fts")
+			issues, truncated, err := db.IntegrityCheck(ctx, database)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(issues).ToNot(BeEmpty())
+			Expect(strings.Join(issues, "\n")).To(ContainSubstring("media_file_fts"))
+			Expect(truncated).To(BeFalse())
+		})
+
+		It("flags the issue list as truncated when there are more issues than the limit", func() {
+			broken := openMismatchedIndexDB(ctx, 300)
+
+			issues, truncated, err := db.IntegrityCheck(ctx, broken)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(issues).To(HaveLen(100))
+			Expect(truncated).To(BeTrue())
+		})
+
+		It("does not flag truncation when the issues exactly fill the limit", func() {
+			broken := openMismatchedIndexDB(ctx, 100)
+
+			issues, truncated, err := db.IntegrityCheck(ctx, broken)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(issues).To(HaveLen(100))
+			Expect(truncated).To(BeFalse())
+		})
+	})
+
+	Describe("ForeignKeyCheck", func() {
+		It("returns no violations for a healthy database", func() {
+			violations, err := db.ForeignKeyCheck(ctx, database)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(violations).To(BeEmpty())
+		})
+
+		It("reports rows referencing missing parents", func() {
+			_, err := database.ExecContext(ctx,
+				`insert into media_file(id, title, library_id) values ('mf-bad', 'Orphan', 999)`)
+			Expect(err).ToNot(HaveOccurred())
+
+			violations, err := db.ForeignKeyCheck(ctx, database)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(violations).To(HaveLen(1))
+			Expect(violations[0].Table).To(Equal("media_file"))
+			Expect(violations[0].Parent).To(Equal("library"))
+			Expect(violations[0].Count).To(BeNumerically("==", 1))
+		})
+	})
+
+	Describe("VerifyFTS", func() {
+		It("passes on a healthy index", func() {
+			Expect(db.VerifyFTS(ctx, database)).To(Succeed())
+		})
+
+		It("fails on a corrupted index, naming the table", func() {
+			corruptFTS("album_fts")
+			Expect(db.VerifyFTS(ctx, database)).To(MatchError(ContainSubstring("album_fts")))
+		})
+	})
+
+	Describe("RebuildFTS", func() {
+		It("repairs a corrupted FTS index", func() {
+			corruptFTS("media_file_fts")
+
+			Expect(db.RebuildFTS(ctx, database)).To(Succeed())
+
+			issues, _, err := db.IntegrityCheck(ctx, database)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(issues).To(BeEmpty())
+			Expect(db.VerifyFTS(ctx, database)).To(Succeed())
+			Expect(searchFTS("media_file_fts", "lobotomy")).To(Equal(1))
+			Expect(searchFTS("album_fts", "russia")).To(Equal(1))
+			Expect(searchFTS("artist_fts", "ramones")).To(Equal(1))
+		})
+
+		It("recreates tables and triggers dropped by hand", func() {
+			for _, table := range db.FTSTables {
+				for _, suffix := range db.FTSTriggerSuffixes {
+					_, err := database.ExecContext(ctx, "drop trigger "+table+suffix)
+					Expect(err).ToNot(HaveOccurred())
+				}
+				_, err := database.ExecContext(ctx, "drop table "+table)
+				Expect(err).ToNot(HaveOccurred())
+			}
+
+			Expect(db.RebuildFTS(ctx, database)).To(Succeed())
+
+			Expect(searchFTS("media_file_fts", "rockaway")).To(Equal(1))
+		})
+
+		It("rolls back and keeps the old index when the rebuild fails", func() {
+			// Triggers go first: SQLite refuses to drop a column they reference.
+			for _, suffix := range db.FTSTriggerSuffixes {
+				_, err := database.ExecContext(ctx, "drop trigger media_file_fts"+suffix)
+				Expect(err).ToNot(HaveOccurred())
+			}
+			_, err := database.ExecContext(ctx, `alter table media_file drop column disc_subtitle`)
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(db.RebuildFTS(ctx, database)).ToNot(Succeed())
+
+			Expect(searchFTS("media_file_fts", "lobotomy")).To(Equal(1))
+			Expect(searchFTS("album_fts", "russia")).To(Equal(1))
+		})
+
+		It("produces the same schema as the migration", func() {
+			migrated := ftsSchema()
+			Expect(migrated).ToNot(BeEmpty())
+
+			Expect(db.RebuildFTS(ctx, database)).To(Succeed())
+
+			Expect(ftsSchema()).To(Equal(migrated))
+		})
+
+		It("leaves working triggers behind", func() {
+			Expect(db.RebuildFTS(ctx, database)).To(Succeed())
+
+			_, err := database.ExecContext(ctx,
+				`insert into artist(id, name, search_normalized) values ('ar-2', 'Blondie', 'blondie')`)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(searchFTS("artist_fts", "blondie")).To(Equal(1))
+
+			_, err = database.ExecContext(ctx, `delete from artist where id = 'ar-2'`)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(searchFTS("artist_fts", "blondie")).To(BeZero())
+		})
+	})
+})

From d9d38f842ae839f59356d0dbb0c33e6bf85a5a77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 12 Sep 2026 00:52:54 -0400
Subject: [PATCH 132/200] fix(ui): update German, Greek, Finnish, Galician,
 Polish, Portuguese (BR), Thai, Ukrainian, Chinese (traditional) translations
 from POEditor (#5833)

Co-authored-by: navidrome-bot <navidrome-bot@navidrome.org>
---
 resources/i18n/de.json      | 27 +++++++++++++++-------
 resources/i18n/el.json      | 31 +++++++++++++++++--------
 resources/i18n/fi.json      | 27 +++++++++++++++-------
 resources/i18n/gl.json      | 33 ++++++++++++++++++---------
 resources/i18n/pl.json      | 45 ++++++++++++++++++++++++++++---------
 resources/i18n/pt-br.json   | 23 +++++++++++--------
 resources/i18n/th.json      | 27 +++++++++++++++-------
 resources/i18n/uk.json      | 31 +++++++++++++++++--------
 resources/i18n/zh-Hant.json | 27 +++++++++++++++-------
 9 files changed, 190 insertions(+), 81 deletions(-)

diff --git a/resources/i18n/de.json b/resources/i18n/de.json
index 1a516d393..8f3df0b4d 100644
--- a/resources/i18n/de.json
+++ b/resources/i18n/de.json
@@ -93,7 +93,8 @@
         "addToPlaylist": "Zu einer Wiedergabeliste hinzufügen",
         "download": "Herunterladen",
         "info": "Mehr Informationen",
-        "share": "Freigabe erstellen"
+        "share": "Freigabe erstellen",
+        "refresh": ""
       },
       "lists": {
         "all": "Alle",
@@ -155,11 +156,13 @@
         "newPassword": "Neues Passwort",
         "token": "Token",
         "lastAccessAt": "Letzter Zugriff am",
-        "libraries": "Bibliotheken"
+        "libraries": "Bibliotheken",
+        "scrobbleFilter": ""
       },
       "helperTexts": {
         "name": "Die Änderung wird erst nach dem nächsten Login gültig",
-        "libraries": "Wähle spezifische Bibliotheken für diesen Benutzer, oder leer lassen für Standard Bibliotheken"
+        "libraries": "Wähle spezifische Bibliotheken für diesen Benutzer, oder leer lassen für Standard Bibliotheken",
+        "scrobbleFilter": ""
       },
       "notifications": {
         "created": "Benutzer erstellt",
@@ -173,7 +176,8 @@
         "adminAutoLibraries": "Administrator-Benutzer haben automatisch Zugriff auf alle Bibliotheken"
       },
       "validation": {
-        "librariesRequired": "Mindestens eine Bibliothek muss für nicht-administrator Benutzer ausgewählt sein"
+        "librariesRequired": "Mindestens eine Bibliothek muss für nicht-administrator Benutzer ausgewählt sein",
+        "invalidScrobbleFilter": ""
       }
     },
     "player": {
@@ -196,6 +200,9 @@
         "targetFormat": "Zielformat",
         "defaultBitRate": "Standardbitrate",
         "command": "Befehl"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -210,7 +217,8 @@
         "songCount": "Titelanzahl",
         "comment": "Kommentar",
         "sync": "Auto-Import",
-        "path": "Importieren aus"
+        "path": "Importieren aus",
+        "starred": "Favorit"
       },
       "actions": {
         "selectPlaylist": "Wiedergabeliste auswählen:",
@@ -403,7 +411,8 @@
         "requiredHosts": "Benötigte Hosts",
         "configValidationError": "Validierung der Konfiguration fehlgeschlagen:",
         "schemaRenderError": "Rendern der Konfiguration fehlgeschlagen. Das Schema das Plugins ist eventuell nicht korrekt.",
-        "allowWriteAccessHelp": "Wenn aktiviert, kann das Plugin Dateien in den Bibliotheken verändern. Als Standard haben Plugins nur Lesezugriff."
+        "allowWriteAccessHelp": "Wenn aktiviert, kann das Plugin Dateien in den Bibliotheken verändern. Als Standard haben Plugins nur Lesezugriff.",
+        "idHelp": ""
       },
       "placeholders": {
         "configKey": "Schlüssel",
@@ -599,7 +608,8 @@
     "coverUploaded": "Cover aktualisiert",
     "coverRemoved": "Cover entfernt",
     "coverUploadError": "Fehler beim Hochladen des Covers",
-    "coverRemoveError": "Fehler beim Entfernen des Covers"
+    "coverRemoveError": "Fehler beim Entfernen des Covers",
+    "metadataRefreshStarted": ""
   },
   "menu": {
     "library": "Bibliothek",
@@ -634,7 +644,8 @@
       "multipleLibraries": "%{selected} von %{total} Bibliotheken",
       "selectLibraries": "Bibliotheken auswählen",
       "none": "Keine"
-    }
+    },
+    "onlyFavourites": "Nur Favoriten anzeigen"
   },
   "player": {
     "playListsText": "Warteschlange abspielen",
diff --git a/resources/i18n/el.json b/resources/i18n/el.json
index 3876c2e33..37882ea99 100644
--- a/resources/i18n/el.json
+++ b/resources/i18n/el.json
@@ -38,7 +38,9 @@
         "missing": "Απών",
         "libraryName": "Βιβλιοθήκη",
         "composer": "Συνθέτης",
-        "disc": "Δίσκος %{discNumber}"
+        "disc": "Δίσκος %{discNumber}",
+        "albumGain": "Κέρδος άλμπουμ",
+        "trackGain": "Κέρδος παρακολούθησης"
       },
       "actions": {
         "addToQueue": "Αναπαραγωγη Μετα",
@@ -91,7 +93,8 @@
         "addToPlaylist": "Προσθηκη στη λιστα αναπαραγωγης",
         "download": "Ληψη",
         "info": "Εμφάνιση Πληροφοριών",
-        "share": "Μερίδιο"
+        "share": "Μερίδιο",
+        "refresh": "Ανανέωση μεταδεδομένων"
       },
       "lists": {
         "all": "Όλα",
@@ -153,11 +156,13 @@
         "newPassword": "Νέος Κωδικός Πρόσβασης",
         "token": "Token",
         "lastAccessAt": "Τελευταία Πρόσβαση",
-        "libraries": "Βιβλιοθήκες"
+        "libraries": "Βιβλιοθήκες",
+        "scrobbleFilter": "Φίλτρο Scrobble"
       },
       "helperTexts": {
         "name": "Αλλαγές στο όνομα σας θα εφαρμοστούν στην επόμενη σύνδεση",
-        "libraries": "Επιλέξτε συγκεκριμένες βιβλιοθήκες για αυτόν τον χρήστη, ή αφήστε την κενή για να χρησιμοποιήσετε την προεπιλεγμένη βιβλιοθήκη"
+        "libraries": "Επιλέξτε συγκεκριμένες βιβλιοθήκες για αυτόν τον χρήστη, ή αφήστε την κενή για να χρησιμοποιήσετε την προεπιλεγμένη βιβλιοθήκη",
+        "scrobbleFilter": "Τα τραγούδια που αντιστοιχούν σε αυτούς τους κανόνες έξυπνης λίστας αναπαραγωγής δεν αποστέλλονται στα πρόσθετα Last.fm, ListenBrainz ή scrobbler. Χρησιμοποιεί την ίδια σύνταξη και συμπεριφορά JSON με τις έξυπνες λίστες αναπαραγωγής. Παράδειγμα: {\"all\":[{\"lt\":{\"rating\":4}}]}."
       },
       "notifications": {
         "created": "Ο χρήστης δημιουργήθηκε",
@@ -171,7 +176,8 @@
         "adminAutoLibraries": "Οι χρήστες διαχειριστές έχουν αυτόματα πρόσβαση σε όλες τις βιβλιοθήκες"
       },
       "validation": {
-        "librariesRequired": "Πρέπει να επιλεγεί τουλάχιστον μία βιβλιοθήκη για χρήστες που δεν είναι διαχειριστές"
+        "librariesRequired": "Πρέπει να επιλεγεί τουλάχιστον μία βιβλιοθήκη για χρήστες που δεν είναι διαχειριστές",
+        "invalidScrobbleFilter": "Πρέπει να υπάρχουν έγκυροι κανόνες έξυπνης λίστας αναπαραγωγής. Δεν υποστηρίζονται το όριο, η μετατόπιση και η καθυστέρηση ανανέωσης."
       }
     },
     "player": {
@@ -194,6 +200,9 @@
         "targetFormat": "Μορφη Προορισμου",
         "defaultBitRate": "Προκαθορισμένος Ρυθμός Bit",
         "command": "Εντολή"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -208,7 +217,8 @@
         "songCount": "Τραγούδια",
         "comment": "Σχόλιο",
         "sync": "Αυτόματη εισαγωγή",
-        "path": "Εισαγωγή από"
+        "path": "Εισαγωγή από",
+        "starred": "Ευνοούμενος"
       },
       "actions": {
         "selectPlaylist": "Επιλέξτε μια λίστα αναπαραγωγής:",
@@ -401,7 +411,8 @@
         "requiredHosts": "Απαιτούμενοι hosts",
         "configValidationError": "Η επικύρωση διαμόρφωσης απέτυχε:",
         "schemaRenderError": "Δεν είναι δυνατή η απόδοση της φόρμας διαμόρφωσης. Το σχήμα της προσθήκης ενδέχεται να μην είναι έγκυρο.",
-        "allowWriteAccessHelp": "Όταν είναι ενεργοποιημένο, το πρόσθετο μπορεί να τροποποιήσει αρχεία στους καταλόγους της βιβλιοθήκης. Από προεπιλογή, τα πρόσθετα έχουν πρόσβαση μόνο για ανάγνωση."
+        "allowWriteAccessHelp": "Όταν είναι ενεργοποιημένο, το πρόσθετο μπορεί να τροποποιήσει αρχεία στους καταλόγους της βιβλιοθήκης. Από προεπιλογή, τα πρόσθετα έχουν πρόσβαση μόνο για ανάγνωση.",
+        "idHelp": ""
       },
       "placeholders": {
         "configKey": "κλειδί",
@@ -597,7 +608,8 @@
     "coverUploaded": "Το εξώφυλλο ενημερώθηκε",
     "coverRemoved": "Το εξώφυλλο αφαιρέθηκε",
     "coverUploadError": "Σφάλμα κατά τη μεταφόρτωση του εξωφύλλου",
-    "coverRemoveError": "Σφάλμα κατά την αφαίρεση του εξωφύλλου"
+    "coverRemoveError": "Σφάλμα κατά την αφαίρεση του εξωφύλλου",
+    "metadataRefreshStarted": "Ανανέωση μεταδεδομένων στο παρασκήνιο"
   },
   "menu": {
     "library": "Βιβλιοθήκη",
@@ -632,7 +644,8 @@
       "multipleLibraries": "%{selected} από %{total} Βιβλιοθήκες",
       "selectLibraries": "Επιλέξτε βιβλιοθήκες",
       "none": "Κανένα"
-    }
+    },
+    "onlyFavourites": "Εμφάνιση μόνο αγαπημένων"
   },
   "player": {
     "playListsText": "Ουρά Αναπαραγωγής",
diff --git a/resources/i18n/fi.json b/resources/i18n/fi.json
index 0e6149f87..3d1edbbd5 100644
--- a/resources/i18n/fi.json
+++ b/resources/i18n/fi.json
@@ -93,7 +93,8 @@
         "addToPlaylist": "Lisää soittolistaan",
         "download": "Lataa",
         "info": "Info",
-        "share": "Jaa"
+        "share": "Jaa",
+        "refresh": "Päivitä metatiedot"
       },
       "lists": {
         "all": "Kaikki",
@@ -155,11 +156,13 @@
         "newPassword": "Uusi salasana",
         "token": "Avain",
         "lastAccessAt": "Viimeisin käyttö",
-        "libraries": "Kirjastot"
+        "libraries": "Kirjastot",
+        "scrobbleFilter": "Scrobble-suodatin"
       },
       "helperTexts": {
         "name": "Nimen muutos tulee voimaan kun seuraavan kerran kirjaudut sisään",
-        "libraries": "Valitse tietyt kirjastot tälle käyttäjälle tai jätä tyhjäksi käyttääksesi oletuskirjastoja"
+        "libraries": "Valitse tietyt kirjastot tälle käyttäjälle tai jätä tyhjäksi käyttääksesi oletuskirjastoja",
+        "scrobbleFilter": "Älykkään soittolistan sääntöihin osumat kappaleet ohitetaan Last.fm-, ListenBrainz- ja skrobbausliitännäisissä. Käyttää samaa JSON-syntaksia ja toimintalogiikkaa kuin älykkäät soittolistat. Esimerkki: {\"all\":[{\"lt\":{\"rating\":4}}]}. Jätä tyhjäksi, jos haluat skrobata kaiken. Paikallisiin toistokertoihin tämä ei vaikuta."
       },
       "notifications": {
         "created": "Käyttäjä luotu",
@@ -173,7 +176,8 @@
         "adminAutoLibraries": "Admin-käyttäjillä on automaattisesti pääsy kaikkiin kirjastoihin"
       },
       "validation": {
-        "librariesRequired": "Vähintään yksi kirjasto on valittava ei-admin käyttäjille"
+        "librariesRequired": "Vähintään yksi kirjasto on valittava ei-admin käyttäjille",
+        "invalidScrobbleFilter": "Sääntöjen pitää olla kelvollisia älykkään soittolistan sääntöjä. Rajaus (limit), siirtymä (offset) ja päivitysviive eivät toimi tässä."
       }
     },
     "player": {
@@ -196,6 +200,9 @@
         "targetFormat": "Kohde formaatti",
         "defaultBitRate": "Oletus bittinopeus",
         "command": "Komento"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -210,7 +217,8 @@
         "songCount": "Kappaleita",
         "comment": "Kommentti",
         "sync": "Automaattinen tuonti",
-        "path": "Tuo"
+        "path": "Tuo",
+        "starred": "Suosikki"
       },
       "actions": {
         "selectPlaylist": "Valitse soittolista:",
@@ -403,7 +411,8 @@
         "requiredHosts": "Vaaditut palvelimet",
         "configValidationError": "Määrityksen validointi epäonnistui:",
         "schemaRenderError": "Konfiguraatiolomaketta ei voi näyttää. Lisäosan skeema saattaa olla virheellinen.",
-        "allowWriteAccessHelp": "Kun otettu käyttöön, liitännäinen voi muokata tiedostoja kirjastohakemistoissa. Oletuksena liitännäisillä on vain luku -oikeus."
+        "allowWriteAccessHelp": "Kun otettu käyttöön, liitännäinen voi muokata tiedostoja kirjastohakemistoissa. Oletuksena liitännäisillä on vain luku -oikeus.",
+        "idHelp": "Lisäosan ID, joka johdetaan sen tiedostonimestä. Käytä sitä viitatessasi tähän lisäosaan määritelmäasetuksissa, kuten agenteissa."
       },
       "placeholders": {
         "configKey": "avain",
@@ -599,7 +608,8 @@
     "coverUploaded": "Kansikuva päivitetty",
     "coverRemoved": "Kansikuva poistettu",
     "coverUploadError": "Virhe ladattaessa kansikuvaa",
-    "coverRemoveError": "Virhe poistettaessa kansikuvaa"
+    "coverRemoveError": "Virhe poistettaessa kansikuvaa",
+    "metadataRefreshStarted": "Metatietoja päivitetään taustalla"
   },
   "menu": {
     "library": "Kirjasto",
@@ -634,7 +644,8 @@
       "multipleLibraries": "%{selected} / %{total} kirjastoa",
       "selectLibraries": "Valitse kirjastot",
       "none": "Ei mitään"
-    }
+    },
+    "onlyFavourites": "Näytä vain suosikit"
   },
   "player": {
     "playListsText": "Jono",
diff --git a/resources/i18n/gl.json b/resources/i18n/gl.json
index 444998d03..47f2f4272 100644
--- a/resources/i18n/gl.json
+++ b/resources/i18n/gl.json
@@ -93,7 +93,8 @@
         "addToPlaylist": "Engadir a Lista",
         "download": "Descargar",
         "info": "Obter info",
-        "share": "Compartir"
+        "share": "Compartir",
+        "refresh": "Actualizar metadatos"
       },
       "lists": {
         "all": "Todo",
@@ -155,11 +156,13 @@
         "newPassword": "Novo contrasinal",
         "token": "Token",
         "lastAccessAt": "Último acceso",
-        "libraries": "Bibliotecas"
+        "libraries": "Bibliotecas",
+        "scrobbleFilter": "Filtro para scrobble"
       },
       "helperTexts": {
         "name": "Os cambios no nome aplicaranse a próxima vez que accedas",
-        "libraries": "Selecciona bibliotecas específicas para esta usuaria, ou deixa baleiro para usar as bibliotecas por defecto"
+        "libraries": "Selecciona bibliotecas específicas para esta usuaria, ou deixa baleiro para usar as bibliotecas por defecto",
+        "scrobbleFilter": "As cancións que concorden coas regras desta lista intelixente non se envían a Last.fm, ListenBrainz ou complementos similares. O filtro usa a mesma sintaxe JSON e comportamento que as listas de reprodución intelixentes. Exemplo: {\"all\":[{\"lt\":{\"rating\":4}}]}. Deixar baleiro para enviar todo. Non lle afecta ao número de reproducións locais."
       },
       "notifications": {
         "created": "Creouse a usuaria",
@@ -173,7 +176,8 @@
         "adminAutoLibraries": "As usuarias Admin teñen acceso por defecto a todas as bibliotecas"
       },
       "validation": {
-        "librariesRequired": "Debes seleccionar polo menos unha biblioteca para usuarias non admins"
+        "librariesRequired": "Debes seleccionar polo menos unha biblioteca para usuarias non admins",
+        "invalidScrobbleFilter": ""
       }
     },
     "player": {
@@ -196,6 +200,9 @@
         "targetFormat": "Formato de destino",
         "defaultBitRate": "Taxa de bit por defecto",
         "command": "Orde"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -210,7 +217,8 @@
         "songCount": "Cancións",
         "comment": "Comentario",
         "sync": "Autoimportación",
-        "path": "Importar desde"
+        "path": "Importar desde",
+        "starred": "Favorita"
       },
       "actions": {
         "selectPlaylist": "Elixe unha lista:",
@@ -403,7 +411,8 @@
         "requiredHosts": "Servidores requeridos",
         "configValidationError": "Fallou a comprobación da configuración:",
         "schemaRenderError": "Non se puido aplicar a configuración. O esquema do complemento podería non ser válido.",
-        "allowWriteAccessHelp": "A activalo, este complemento pode modificar ficheiros nos directorios da biblioteca. Por defecto os complementos teñen acceso de só-lectura."
+        "allowWriteAccessHelp": "A activalo, este complemento pode modificar ficheiros nos directorios da biblioteca. Por defecto os complementos teñen acceso de só-lectura.",
+        "idHelp": "O ID do complemento, derivado do seu nome de ficheiro. Utilízao cando te refiras ao complemento nas opcións de configuración, como en Agents."
       },
       "placeholders": {
         "configKey": "clave",
@@ -435,7 +444,7 @@
       "minValue": "Ten que ter polo menos %{min}",
       "maxValue": "Ten que ter %{max} ou menos",
       "number": "Ten que ser un número",
-      "email": "Ten que ser un email válido",
+      "email": "Ten que ser un correo válido",
       "oneOf": "Ten que ser un de: %{options}",
       "regex": "Ten que ter un formato específico (regexp): %{pattern}",
       "unique": "Ten que ser único",
@@ -509,7 +518,7 @@
       }
     },
     "message": {
-      "about": "Acerca de",
+      "about": "Sobre",
       "are_you_sure": "Tes certeza?",
       "bulk_delete_content": "Tes a certeza de querer borrar a %{name} |||| Tes a certeza de querer eleminar estes %{smart_count} elementos?",
       "bulk_delete_title": "Eliminar %{name} |||| Eliminar %{smart_count} %{name}",
@@ -599,7 +608,8 @@
     "coverUploaded": "Subiuse a capa",
     "coverRemoved": "Retirouse a capa",
     "coverUploadError": "Erro ao subir a capa",
-    "coverRemoveError": "Erro ao retirar a capa"
+    "coverRemoveError": "Erro ao retirar a capa",
+    "metadataRefreshStarted": "Actualizar en segundo plano os metadatos"
   },
   "menu": {
     "library": "Biblioteca",
@@ -626,7 +636,7 @@
       }
     },
     "albumList": "Álbums",
-    "about": "Acerca de",
+    "about": "Sobre",
     "playlists": "Listas de reprodución",
     "sharedPlaylists": "Listas compartidas",
     "librarySelector": {
@@ -634,7 +644,8 @@
       "multipleLibraries": "%{selected} de %{total} Bibliotecas",
       "selectLibraries": "Seleccionar Bibliotecas",
       "none": "Ningunha"
-    }
+    },
+    "onlyFavourites": "Mostrar só as favoritas"
   },
   "player": {
     "playListsText": "Reproducir cola",
diff --git a/resources/i18n/pl.json b/resources/i18n/pl.json
index 6229798e9..ff697d64c 100644
--- a/resources/i18n/pl.json
+++ b/resources/i18n/pl.json
@@ -37,7 +37,10 @@
         "sampleRate": "Częstotliwość próbkowania",
         "missing": "Brak",
         "libraryName": "Biblioteka",
-        "composer": "Kompozytor"
+        "composer": "Kompozytor",
+        "disc": "Dysk %{discNumber}",
+        "albumGain": "Wzmocnienie albumu",
+        "trackGain": "Wzmocnienie utworu"
       },
       "actions": {
         "addToQueue": "Odtwarzaj Później",
@@ -90,7 +93,8 @@
         "addToPlaylist": "Dodaj do Playlisty",
         "download": "Pobierz",
         "info": "Zdobądź Informacje",
-        "share": "Udostępnij"
+        "share": "Udostępnij",
+        "refresh": "Odśwież Metadane"
       },
       "lists": {
         "all": "Wszystkie",
@@ -152,11 +156,13 @@
         "newPassword": "Nowe hasło",
         "token": "Token",
         "lastAccessAt": "Ostatnia Aktywność",
-        "libraries": "Biblioteki"
+        "libraries": "Biblioteki",
+        "scrobbleFilter": "Filtr scrobblowania"
       },
       "helperTexts": {
         "name": "Zmiana nazwy będzie widoczna przy następnym logowaniu",
-        "libraries": "Wybierz biblioteki dla użytkownika lub pozostaw pustę, aby użyć domyślnej biblioteki"
+        "libraries": "Wybierz biblioteki dla użytkownika lub pozostaw pustę, aby użyć domyślnej biblioteki",
+        "scrobbleFilter": "Utwory spełniające kryteria tych inteligentnych list odtwarzania nie są wysyłane do serwisów Last.fm, ListenBrainz ani do wtyczek typu scrobbler. Wykorzystywana jest tu ta sama składnia JSON i zasada działania, co w przypadku inteligentnych list odtwarzania. Przykład: {\"all\":[{\"lt\":{\"rating\":4}}]}. Pozostawienie pola pustego spowoduje scrobblowanie wszystkich utworów. Nie wpływa to na lokalne liczniki odtworzeń."
       },
       "notifications": {
         "created": "Dodano użytkownika",
@@ -170,7 +176,8 @@
         "adminAutoLibraries": "Administratorzy automatycznie mają dostęp do wszystkich bibliotek"
       },
       "validation": {
-        "librariesRequired": "Przynajmniej jedna biblioteka musi być wybrana dla zwykłego użytkownika"
+        "librariesRequired": "Przynajmniej jedna biblioteka musi być wybrana dla zwykłego użytkownika",
+        "invalidScrobbleFilter": "Reguły inteligentnej listy odtwarzania muszą być poprawne. Parametry limitu, przesunięcia oraz opóźnienia odświeżania nie są obsługiwane."
       }
     },
     "player": {
@@ -193,6 +200,9 @@
         "targetFormat": "Format Docelowy",
         "defaultBitRate": "Domyślny Bit Rate",
         "command": "Komenda"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -207,7 +217,8 @@
         "songCount": "Liczba utworów",
         "comment": "Komentarz",
         "sync": "Import automatyczny",
-        "path": "Zaimportuj z"
+        "path": "Zaimportuj z",
+        "starred": "Ulubione"
       },
       "actions": {
         "selectPlaylist": "Wybierz playlistę:",
@@ -353,7 +364,8 @@
         "allUsers": "Zezwalaj wszystkim użytkownikom",
         "selectedUsers": "Wybrani użytkownicy",
         "allLibraries": "Zezwalaj dla wszystkich bibliotek",
-        "selectedLibraries": "Wybrane biblioteki"
+        "selectedLibraries": "Wybrane biblioteki",
+        "allowWriteAccess": "Zezwól na zapis"
       },
       "sections": {
         "status": "Status",
@@ -398,7 +410,9 @@
         "librariesRequired": "Wtyczka wymaga dostępu do informacji o bibliotece. Wybierz, dla której biblioteki zezwolić dostęp, lub włącz 'Zezwalaj dla wszystkich bibliotek'.",
         "requiredHosts": "Wymagane hosty",
         "configValidationError": "Weryfikacja konfiguracji nie powiodła się:",
-        "schemaRenderError": "Nie można wyrenderować formularza konfiguracji. Schemat wtyczki może być nieprawidłowy."
+        "schemaRenderError": "Nie można wyrenderować formularza konfiguracji. Schemat wtyczki może być nieprawidłowy.",
+        "allowWriteAccessHelp": "Po włączeniu wtyczka może modyfikować pliki w katalogach bibliotek. Domyślnie wtyczki mają dostęp tylko do odczytu.",
+        "idHelp": ""
       },
       "placeholders": {
         "configKey": "klucz",
@@ -588,7 +602,14 @@
     "remove_all_missing_content": "Czy chcesz usunąć wszystkie brakujące pliki z bazy danych? Spowoduje to trwałe usunięcie wszelkich odniesień do tych plików, takich jak liczba odtworzeń, czy oceny.",
     "noSimilarSongsFound": "Brak podobnych utworów",
     "noTopSongsFound": "Brak najlepszych utworów",
-    "startingInstantMix": "Ładowanie Natychmiastowego Miksu..."
+    "startingInstantMix": "Ładowanie Natychmiastowego Miksu...",
+    "uploadCover": "Prześlij Okładkę",
+    "removeCover": "Usuń Okładkę",
+    "coverUploaded": "Okładka zaktualizowana",
+    "coverRemoved": "Okładka usunięta",
+    "coverUploadError": "Błąd przesyłania okładki",
+    "coverRemoveError": "Błąd usuwania okładki",
+    "metadataRefreshStarted": "Odświeżanie metadanych w tle"
   },
   "menu": {
     "library": "Biblioteka",
@@ -623,7 +644,8 @@
       "multipleLibraries": "%{selected} z %{total} Bibliotek",
       "selectLibraries": "Wybierz Biblioteki",
       "none": "Żadna"
-    }
+    },
+    "onlyFavourites": "Pokaż tylko ulubione"
   },
   "player": {
     "playListsText": "Kolejka Odtwarzania",
@@ -674,7 +696,8 @@
       "exportSuccess": "Konfiguracja wyeksportowana do schowka w formacie TOML",
       "exportFailed": "Błąd kopiowania konfiguracji",
       "devFlagsHeader": "Flagi Rozwojowe (mogą ulec zmianie/usunięciu)",
-      "devFlagsComment": "To są ustawienia eksperymentalne i mogą zostać usunięte w przyszłych wydaniach"
+      "devFlagsComment": "To są ustawienia eksperymentalne i mogą zostać usunięte w przyszłych wydaniach",
+      "downloadToml": "Konfiguracja Pobierania (TOML)"
     }
   },
   "activity": {
diff --git a/resources/i18n/pt-br.json b/resources/i18n/pt-br.json
index ccc5f872b..2584da6cd 100644
--- a/resources/i18n/pt-br.json
+++ b/resources/i18n/pt-br.json
@@ -35,12 +35,12 @@
         "rawTags": "Tags originais",
         "bitDepth": "Profundidade de bits",
         "sampleRate": "Taxa de amostragem",
-        "albumGain": "Ganho do álbum",
-        "trackGain": "Ganho da faixa",
         "missing": "Ausente",
         "libraryName": "Biblioteca",
         "composer": "Compositor",
-        "disc": "Disco %{discNumber}"
+        "disc": "Disco %{discNumber}",
+        "albumGain": "Ganho do álbum",
+        "trackGain": "Ganho da faixa"
       },
       "actions": {
         "addToQueue": "Adicionar à fila",
@@ -93,8 +93,8 @@
         "addToPlaylist": "Adicionar à playlist",
         "download": "Baixar",
         "info": "Detalhes",
-        "refresh": "Atualizar Metadados",
-        "share": "Compartilhar"
+        "share": "Compartilhar",
+        "refresh": "Atualizar Metadados"
       },
       "lists": {
         "all": "Todos",
@@ -200,6 +200,9 @@
         "targetFormat": "Formato",
         "defaultBitRate": "Bitrate padrão",
         "command": "Comando"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -214,7 +217,8 @@
         "songCount": "Músicas",
         "comment": "Comentário",
         "sync": "Auto-importar",
-        "path": "Importar de"
+        "path": "Importar de",
+        "starred": "Favorita"
       },
       "actions": {
         "selectPlaylist": "Selecione a playlist:",
@@ -394,7 +398,6 @@
         "invalidJson": "A configuração deve ser um JSON válido"
       },
       "messages": {
-        "idHelp": "O ID do plugin, derivado do nome do arquivo. Use-o ao referenciar este plugin em opções de configuração, como Agents.",
         "configHelp": "Configure o plugin usando pares chave-valor. Deixe vazio se o plugin não precisa de configuração.",
         "clickPermissions": "Clique em uma permissão para ver detalhes",
         "noConfig": "Nenhuma configuração definida",
@@ -408,7 +411,8 @@
         "requiredHosts": "Hosts necessários",
         "configValidationError": "Falha na validação da configuração:",
         "schemaRenderError": "Não foi possível renderizar o formulário de configuração. O schema do plugin pode estar inválido.",
-        "allowWriteAccessHelp": "Quando habilitado, o plugin pode modificar arquivos nos diretórios das bibliotecas. Por padrão, plugins têm acesso somente leitura."
+        "allowWriteAccessHelp": "Quando habilitado, o plugin pode modificar arquivos nos diretórios das bibliotecas. Por padrão, plugins têm acesso somente leitura.",
+        "idHelp": "O ID do plugin, derivado do nome do arquivo. Use-o ao referenciar este plugin em opções de configuração, como Agents."
       },
       "placeholders": {
         "configKey": "chave",
@@ -640,7 +644,8 @@
       "multipleLibraries": "%{selected} de %{total} Bibliotecas",
       "selectLibraries": "Selecionar Bibliotecas",
       "none": "Nenhuma"
-    }
+    },
+    "onlyFavourites": "Somente favoritas"
   },
   "player": {
     "playListsText": "Fila de Execução",
diff --git a/resources/i18n/th.json b/resources/i18n/th.json
index fde89494e..3c5c9e07b 100644
--- a/resources/i18n/th.json
+++ b/resources/i18n/th.json
@@ -93,7 +93,8 @@
         "addToPlaylist": "เพิ่มลงในเพลย์ลิสต์",
         "download": "ดาวน์โหลด",
         "info": "ดูรายละเอียด",
-        "share": "แบ่งปัน"
+        "share": "แบ่งปัน",
+        "refresh": ""
       },
       "lists": {
         "all": "ทั้งหมด",
@@ -155,11 +156,13 @@
         "newPassword": "รหัสผ่านใหม่",
         "token": "โทเคน",
         "lastAccessAt": "เข้าใช้ล่าสุด",
-        "libraries": "ห้องสมุด"
+        "libraries": "ห้องสมุด",
+        "scrobbleFilter": ""
       },
       "helperTexts": {
         "name": "การเปลี่ยนชื่อจะมีผลในการล็อกอินครั้งถัดไป",
-        "libraries": "เลือกห้องสมุดสำหรับผู้ใช้นี้หรือปล่อยว่างเพื่อใช้ห้องสมุดเริ่มต้น"
+        "libraries": "เลือกห้องสมุดสำหรับผู้ใช้นี้หรือปล่อยว่างเพื่อใช้ห้องสมุดเริ่มต้น",
+        "scrobbleFilter": ""
       },
       "notifications": {
         "created": "สร้างชื่อผู้ใช้",
@@ -173,7 +176,8 @@
         "adminAutoLibraries": "ผู้ดูแลเข้าถึงห้องสมุดทั้งหมดโดยอัตโนมัติ"
       },
       "validation": {
-        "librariesRequired": "ต้องเลือกห้องสมุด 1 ห้อง สำหรับผู้ใช้ที่ไม่ใช่ผู้ดูแล"
+        "librariesRequired": "ต้องเลือกห้องสมุด 1 ห้อง สำหรับผู้ใช้ที่ไม่ใช่ผู้ดูแล",
+        "invalidScrobbleFilter": ""
       }
     },
     "player": {
@@ -196,6 +200,9 @@
         "targetFormat": "ชนิดไฟล์เสียง",
         "defaultBitRate": "บิตเรท",
         "command": "คำสั่ง"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -210,7 +217,8 @@
         "songCount": "เพลง",
         "comment": "ความคิดเห็น",
         "sync": "นำเข้าอัตโนมัติ",
-        "path": "นำเข้าจาก"
+        "path": "นำเข้าจาก",
+        "starred": "ชื่นชอบ"
       },
       "actions": {
         "selectPlaylist": "เลือกเพลย์ลิสต์",
@@ -403,7 +411,8 @@
         "requiredHosts": "ต้องการ Host",
         "configValidationError": "การตั้งค่าเกิดความผิดพลาด",
         "schemaRenderError": "ไม่สามารถแสดงหน้าจอการตั้งค่า อาจเกิดจากความผิดพลาดจากปลั๊กอิน",
-        "allowWriteAccessHelp": "เมื่อเปิดใช้งาน ปลั๊กอินสามารถแก้ไขไฟล์ในห้องสมุด ปลั๊กอินอยู่ในโหมดอ่านอย่างเดียวเป็นค่าเริ่มต้น"
+        "allowWriteAccessHelp": "เมื่อเปิดใช้งาน ปลั๊กอินสามารถแก้ไขไฟล์ในห้องสมุด ปลั๊กอินอยู่ในโหมดอ่านอย่างเดียวเป็นค่าเริ่มต้น",
+        "idHelp": ""
       },
       "placeholders": {
         "configKey": "คีย์",
@@ -599,7 +608,8 @@
     "coverUploaded": "ภาพหน้าปกถูกอัพเดทแล้ว",
     "coverRemoved": "ภาพหน้าปกถูกลบแล้ว",
     "coverUploadError": "อัพโหลดภาพหน้าปกผิดพลาด",
-    "coverRemoveError": "ลบภาพหน้าปกผิดพลาด"
+    "coverRemoveError": "ลบภาพหน้าปกผิดพลาด",
+    "metadataRefreshStarted": ""
   },
   "menu": {
     "library": "ห้องสมุดเพลง",
@@ -634,7 +644,8 @@
       "multipleLibraries": "%{selected} ของ %{total} ห้องสมุด",
       "selectLibraries": "เลือกห้องสมุด",
       "none": "ไม่มี"
-    }
+    },
+    "onlyFavourites": "แสดงเฉพาะที่ชื่นชอบ"
   },
   "player": {
     "playListsText": "คิวเล่น",
diff --git a/resources/i18n/uk.json b/resources/i18n/uk.json
index c5644fde7..3049f9840 100644
--- a/resources/i18n/uk.json
+++ b/resources/i18n/uk.json
@@ -38,7 +38,9 @@
         "missing": "Поле відсутнє",
         "libraryName": "Бібліотека",
         "composer": "Композитор",
-        "disc": "Диск %{discNumber}"
+        "disc": "Диск %{discNumber}",
+        "albumGain": "",
+        "trackGain": ""
       },
       "actions": {
         "addToQueue": "Прослухати пізніше",
@@ -91,7 +93,8 @@
         "addToPlaylist": "Додати у список відтворення",
         "download": "Завантажити",
         "info": "Отримати інформацію",
-        "share": "Поширити"
+        "share": "Поширити",
+        "refresh": ""
       },
       "lists": {
         "all": "Усі",
@@ -153,11 +156,13 @@
         "newPassword": "Новий пароль",
         "token": "Токен",
         "lastAccessAt": "Останній доступ",
-        "libraries": "Бібліотеки"
+        "libraries": "Бібліотеки",
+        "scrobbleFilter": ""
       },
       "helperTexts": {
         "name": "Змінене ім'я буде відображатися при наступній авторизації",
-        "libraries": "Виберіть конкретні бібліотеки для цього користувача, або залиште поле порожнім, щоб використовувати бібліотеки за замовчуванням"
+        "libraries": "Виберіть конкретні бібліотеки для цього користувача, або залиште поле порожнім, щоб використовувати бібліотеки за замовчуванням",
+        "scrobbleFilter": ""
       },
       "notifications": {
         "created": "Користувача створено",
@@ -171,7 +176,8 @@
         "adminAutoLibraries": "Користувачі-адміністратори автоматично отримують доступ до всіх бібліотек"
       },
       "validation": {
-        "librariesRequired": "Для користувачів, які не є адміністраторами, має бути обрана хоча б одна бібліотека"
+        "librariesRequired": "Для користувачів, які не є адміністраторами, має бути обрана хоча б одна бібліотека",
+        "invalidScrobbleFilter": ""
       }
     },
     "player": {
@@ -194,6 +200,9 @@
         "targetFormat": "Цільовий формат",
         "defaultBitRate": "Швидкість передачі бітів за замовчуванням",
         "command": "Команда"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -208,7 +217,8 @@
         "songCount": "Пісні",
         "comment": "Коментар",
         "sync": "Автоімпорт",
-        "path": "Імпортувати із"
+        "path": "Імпортувати із",
+        "starred": "Улюблене"
       },
       "actions": {
         "selectPlaylist": "Вибрати список відтворення:",
@@ -401,7 +411,8 @@
         "requiredHosts": "Обов'язкові хости",
         "configValidationError": "Перевірка конфігурації зазнала невдачі:",
         "schemaRenderError": "Неможливо відобразити форму конфігурації. Схема плагіна може бути недійсною.",
-        "allowWriteAccessHelp": "При включенні плагін може змінювати файли в каталогах бібліотеки. За замовчуванням плагіни мають доступ лише для читання."
+        "allowWriteAccessHelp": "При включенні плагін може змінювати файли в каталогах бібліотеки. За замовчуванням плагіни мають доступ лише для читання.",
+        "idHelp": ""
       },
       "placeholders": {
         "configKey": "ключ",
@@ -597,7 +608,8 @@
     "coverUploaded": "Обкладинку оновлено",
     "coverRemoved": "Обкладинка видалена",
     "coverUploadError": "Помилка завантаження обкладинки",
-    "coverRemoveError": "Помилка видалення обкладинки"
+    "coverRemoveError": "Помилка видалення обкладинки",
+    "metadataRefreshStarted": ""
   },
   "menu": {
     "library": "Бібліотека",
@@ -632,7 +644,8 @@
       "multipleLibraries": "%{selected} з %{total} Бібліотеки",
       "selectLibraries": "Вибір бібліотек",
       "none": "Відсутня"
-    }
+    },
+    "onlyFavourites": "Показати улюблене"
   },
   "player": {
     "playListsText": "Грати по черзі",
diff --git a/resources/i18n/zh-Hant.json b/resources/i18n/zh-Hant.json
index d00ae2ac3..5e48352ea 100644
--- a/resources/i18n/zh-Hant.json
+++ b/resources/i18n/zh-Hant.json
@@ -93,7 +93,8 @@
         "addToPlaylist": "加入至播放清單",
         "download": "下載",
         "info": "取得資訊",
-        "share": "分享"
+        "share": "分享",
+        "refresh": ""
       },
       "lists": {
         "all": "所有",
@@ -155,11 +156,13 @@
         "newPassword": "新密碼",
         "token": "權杖",
         "lastAccessAt": "上次存取",
-        "libraries": "媒體庫"
+        "libraries": "媒體庫",
+        "scrobbleFilter": ""
       },
       "helperTexts": {
         "name": "您的名稱會在下次登入時生效",
-        "libraries": "為該使用者選擇指定媒體庫，留空則使用預設媒體庫"
+        "libraries": "為該使用者選擇指定媒體庫，留空則使用預設媒體庫",
+        "scrobbleFilter": ""
       },
       "notifications": {
         "created": "使用者已建立",
@@ -173,7 +176,8 @@
         "adminAutoLibraries": "管理員預設可存取所有媒體庫"
       },
       "validation": {
-        "librariesRequired": "非管理員使用者必須至少選擇一個媒體庫"
+        "librariesRequired": "非管理員使用者必須至少選擇一個媒體庫",
+        "invalidScrobbleFilter": ""
       }
     },
     "player": {
@@ -196,6 +200,9 @@
         "targetFormat": "目標格式",
         "defaultBitRate": "預設位元率",
         "command": "指令"
+      },
+      "choices": {
+        "noDefaultBitRate": ""
       }
     },
     "playlist": {
@@ -210,7 +217,8 @@
         "songCount": "歌曲數",
         "comment": "註解",
         "sync": "自動匯入",
-        "path": "匯入來源"
+        "path": "匯入來源",
+        "starred": "收藏"
       },
       "actions": {
         "selectPlaylist": "選取播放清單：",
@@ -403,7 +411,8 @@
         "requiredHosts": "必要的 Hosts",
         "configValidationError": "設定驗證失敗：",
         "schemaRenderError": "無法顯示設定表單。外掛的 schema 可能無效。",
-        "allowWriteAccessHelp": "啟用後，外掛可以修改媒體庫目錄中的檔案。 預設情況下，外掛具有唯讀權限。"
+        "allowWriteAccessHelp": "啟用後，外掛可以修改媒體庫目錄中的檔案。 預設情況下，外掛具有唯讀權限。",
+        "idHelp": ""
       },
       "placeholders": {
         "configKey": "鍵",
@@ -599,7 +608,8 @@
     "coverUploaded": "已更新封面圖",
     "coverRemoved": "已移除封面圖",
     "coverUploadError": "上傳封面圖時發生錯誤",
-    "coverRemoveError": "移除封面圖時發生錯誤"
+    "coverRemoveError": "移除封面圖時發生錯誤",
+    "metadataRefreshStarted": ""
   },
   "menu": {
     "library": "媒體庫",
@@ -634,7 +644,8 @@
       "multipleLibraries": "已選 %{selected} 共 %{total} 媒體庫",
       "selectLibraries": "選取媒體庫",
       "none": "無"
-    }
+    },
+    "onlyFavourites": "僅顯示收藏"
   },
   "player": {
     "playListsText": "播放佇列",

From 2802c05a66e0d48ff9a58b087d534064b42a8c92 Mon Sep 17 00:00:00 2001
From: Rob Emery <mintsoft@users.noreply.github.com>
Date: Sat, 12 Sep 2026 14:40:59 +0100
Subject: [PATCH 133/200] feat(msi): keep install folder and settings across
 upgrades (#5333)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Implementing the RememberProperty pattern for the settings set
through the UI on install. Previously, these got reset on upgrade.

This is as simple as squirrelling them away in the registry for
all settings except for the INSTALLDIR, as the INSTALLDIR depends
on the environment that the msi is being installed into (i.e. the
actual location of ProgramFiles can be anywhere technically), that
needs to be dynamically set after the CostFinalize phase and in the
version of WiX schema supported by wixl needs to be implemented
through a customAction.

This will not fix the upgrade issue for existing installs, as the
information entered doesn't exist in the registry or anything so
the best option imo is to backup the navidrome database and config
uninstall the old version and install the new version with the
desired paths. It should then upgrade from there on correctly.

* Make it possible to build 386 and amd64 on the same machine

* When upgrading from the pre-fix installer, it would dump everything
into the C:\ root as the UI never executes to set the value for
the MSI_INSTALLATIONDIRECTORY, and the custom action doesn't run
on upgrade as we should be reading from the registry in that situation

This will force the customaction to run when the path is the confusingly
named TARGETDIR (which is C:\ in 99% of cases).

All other properties when upgrading from the pre-fix to the fix
will be reset to the default values as well; which was the same
as the previous behaviour anyway.

* build(msi): drop local ffmpeg download cache

The cache key did not include the ffmpeg version, and a partial download
would stick forever. CI runners start clean, so the cache only helped
local builds.

* fix(msi): set install directory during silent installs and upgrades

SetInstallDirProperty only ran in InstallUISequence, which Windows
Installer skips for /passive and /qn (the modes winget uses). With
MSI_INSTALLATIONDIRECTORY unset, the files and the service went to the
root of the drive with the most free space. Upgrades from releases that
did not store MSI_INSTALLATIONDIRECTORY in the registry hit the same
path, even with the full UI.

The action now runs before CostFinalize in both sequences, whenever the
registry search did not find a saved directory, and defaults to
[ProgramFiles64Folder]Navidrome\ (ProgramFilesFolder on x86) so it does
not depend on INSTALLDIR being resolved. The unused INSTALLDIR directory
is removed.

Verified on a GitHub Actions Windows runner: fresh installs with /passive,
/qn and /qr, upgrades from 0.63.1 with /passive and /qr, and an upgrade
between two fixed builds that keeps a custom directory and port.

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 release/wix/SettingsDlg.wxs |  2 +-
 release/wix/navidrome.wxs   | 96 +++++++++++++++++++++----------------
 2 files changed, 57 insertions(+), 41 deletions(-)

diff --git a/release/wix/SettingsDlg.wxs b/release/wix/SettingsDlg.wxs
index 4a83f91da..cdc625434 100644
--- a/release/wix/SettingsDlg.wxs
+++ b/release/wix/SettingsDlg.wxs
@@ -16,7 +16,7 @@
         
         <!-- Install directory -->
         <Control Id="NameLabel1" Type="Text" X="30" Y="60" Width="220" Height="15" TabSkip="no" Text="&amp;Installation Folder (executable and configuration file):" />
-        <Control Id="NameEdit1" Type="Edit" X="30" Y="75" Width="220" Height="18" Property="INSTALLDIR" Text="[INSTALLDIR]" />
+        <Control Id="NameEdit1" Type="Edit" X="30" Y="75" Width="220" Height="18" Property="MSI_INSTALLATIONDIRECTORY" Text="[MSI_INSTALLATIONDIRECTORY]" />
 
         <!-- NAVIDROME_PORT -->
         <Control Id="NameLabel2" Type="Text" X="30" Y="93" Width="100" Height="15" TabSkip="no" Text="&amp;Port:" />
diff --git a/release/wix/navidrome.wxs b/release/wix/navidrome.wxs
index 6d94bab9d..71a6de6b5 100644
--- a/release/wix/navidrome.wxs
+++ b/release/wix/navidrome.wxs
@@ -14,6 +14,7 @@
 	<?include SettingsDlg.wxs?>
 	<?include Navidrome_UI_Flow.wxs?>
 	<Product Name="$(var.ProductName)" Id="*" UpgradeCode="$(var.UpgradeCode)" Language='1033' Codepage='1252' Version='$(var.Version)' Manufacturer='Deluan'>
+		<UIRef Id="Navidrome_UI_Flow"/>
 
 		<Package Id='*' Keywords='Installer' Description="$(var.ProductName)" Comments='' Manufacturer='Deluan' InstallerVersion='200' Languages='1033' Compressed='yes' SummaryCodepage='1252' InstallScope='perMachine' />
 
@@ -23,55 +24,65 @@
 		<Property Id='DiskPrompt' Value="Navidrome Install [1]" />
 		<Property Id="REBOOT" Value="ReallySuppress" />
 
-		<Property Id="ND_PORT" Value="4533" />
-		<Property Id="ND_MUSICFOLDER" Value="C:\Music" />
-		<Property Id="ND_DATAFOLDER" Value="C:\ProgramData\Navidrome" />
+		<Property Id="ND_PORT" Value="4533">
+			<RegistrySearch Id="ND_PORT" Root='HKLM' Key='SOFTWARE\Deluan\$(var.ProductName)\Installer' Name='ND_PORT' Type='raw' />
+		</Property>
+		<Property Id="ND_MUSICFOLDER" Value="C:\Music">
+			<RegistrySearch Id="ND_MUSICFOLDER" Root='HKLM' Key='SOFTWARE\Deluan\$(var.ProductName)\Installer' Name='ND_MUSICFOLDER' Type='raw' />
+		</Property>
+		<Property Id="ND_DATAFOLDER" Value="C:\ProgramData\Navidrome">
+			<RegistrySearch Id="ND_DATAFOLDER" Root='HKLM' Key='SOFTWARE\Deluan\$(var.ProductName)\Installer' Name='ND_DATAFOLDER' Type='raw' />
+		</Property>
+		<Property Id="MSI_INSTALLATIONDIRECTORY">
+			<RegistrySearch Id="MSI_INSTALLATIONDIRECTORY" Root='HKLM' Key='SOFTWARE\Deluan\$(var.ProductName)\Installer' Name='MSI_INSTALLATIONDIRECTORY' Type='raw' />
+		</Property>
 
-		<UIRef Id="Navidrome_UI_Flow"/>
+		<CustomAction Id="SetInstallDirProperty" Property="MSI_INSTALLATIONDIRECTORY" Value="[$(var.PlatformProgramFilesFolder)]Navidrome\" />
 
 		<Directory Id='TARGETDIR' Name='SourceDir'>
-			<Directory Id="$(var.PlatformProgramFilesFolder)">
-				<Directory Id='INSTALLDIR' Name='Navidrome'>
+			<Directory Id="MSI_INSTALLATIONDIRECTORY">
+				<Component Id='LICENSEFile' Guid='eb5610a4-e3f3-4f36-ae2c-e96914e460c2' Win64="$(var.Win64)">
+					<File Id='LICENSE' Name='LICENSE' DiskId='1' Source='LICENSE' KeyPath='yes' />
+				</Component>
 
-					<Component Id='LICENSEFile' Guid='eb5610a4-e3f3-4f36-ae2c-e96914e460c2' Win64="$(var.Win64)">
-						<File Id='LICENSE' Name='LICENSE' DiskId='1' Source='LICENSE' KeyPath='yes' />
-					</Component>
+				<Component Id='README.mdFile' Guid='d1ee412b-2ebc-4b0b-9fa7-0228ab707686' Win64="$(var.Win64)">
+					<File Id='README.md' Name='README.md' DiskId='1' Source='README.md' KeyPath='yes' />
+				</Component>
 
-					<Component Id='README.mdFile' Guid='d1ee412b-2ebc-4b0b-9fa7-0228ab707686' Win64="$(var.Win64)">
-						<File Id='README.md' Name='README.md' DiskId='1' Source='README.md' KeyPath='yes' />
-					</Component>
+				<Component Id="Configuration" Guid="9e17ed4b-ef13-44bf-a605-ed4132cff7f6" Win64="$(var.Win64)">
+					<IniFile Id="ConfigurationPort" Name="navidrome.ini" Action="createLine" Directory="MSI_INSTALLATIONDIRECTORY" Key="Port" Section="default" Value="&apos;[ND_PORT]&apos;" />
+					<IniFile Id="ConfigurationMusicDir" Name="navidrome.ini" Action="createLine" Directory="MSI_INSTALLATIONDIRECTORY" Key="MusicFolder" Section="default" Value="&apos;[ND_MUSICFOLDER]&apos;" />
+					<IniFile Id="ConfigurationDataDir" Name="navidrome.ini" Action="createLine" Directory="MSI_INSTALLATIONDIRECTORY" Key="DataFolder" Section="default" Value="&apos;[ND_DATAFOLDER]&apos;" />
+					<IniFile Id="FFmpegPath" Name="navidrome.ini" Action="createLine" Directory="MSI_INSTALLATIONDIRECTORY" Key="FFmpegPath" Section="default" Value="&apos;[MSI_INSTALLATIONDIRECTORY]ffmpeg.exe&apos;" />
 
-					<Component Id="Configuration" Guid="9e17ed4b-ef13-44bf-a605-ed4132cff7f6" Win64="$(var.Win64)">
-						<IniFile Id="ConfigurationPort" Name="navidrome.ini" Action="createLine" Directory="INSTALLDIR" Key="Port" Section="default" Value="&apos;[ND_PORT]&apos;" />
-						<IniFile Id="ConfigurationMusicDir" Name="navidrome.ini" Action="createLine" Directory="INSTALLDIR" Key="MusicFolder" Section="default" Value="&apos;[ND_MUSICFOLDER]&apos;" />
-						<IniFile Id="ConfigurationDataDir" Name="navidrome.ini" Action="createLine" Directory="INSTALLDIR" Key="DataFolder" Section="default" Value="&apos;[ND_DATAFOLDER]&apos;" />
-						<IniFile Id="FFmpegPath" Name="navidrome.ini" Action="createLine" Directory="INSTALLDIR" Key="FFmpegPath" Section="default" Value="&apos;[INSTALLDIR]ffmpeg.exe&apos;" />
-					</Component>
+					<RegistryValue Root='HKLM' Key='SOFTWARE\Deluan\$(var.ProductName)\Installer' Name='MSI_INSTALLATIONDIRECTORY' Value='[MSI_INSTALLATIONDIRECTORY]' Type='string' />
+					<RegistryValue Root='HKLM' Key='SOFTWARE\Deluan\$(var.ProductName)\Installer' Name='ND_PORT' Value='[ND_PORT]' Type='string' />
+					<RegistryValue Root='HKLM' Key='SOFTWARE\Deluan\$(var.ProductName)\Installer' Name='ND_MUSICFOLDER' Value='[ND_MUSICFOLDER]' Type='string' />
+					<RegistryValue Root='HKLM' Key='SOFTWARE\Deluan\$(var.ProductName)\Installer' Name='ND_DATAFOLDER' Value='[ND_DATAFOLDER]' Type='string' />
+				</Component>
 
-					<Component Id='MainExecutable' Guid='e645aa06-8bbc-40d6-8d3c-73b4f5b76fd7' Win64="$(var.Win64)">
-						<File Id='NavidromeExe' Name='Navidrome.exe' DiskId='1' Source='navidrome.exe' KeyPath='yes' />
-						<ServiceInstall
-							Description='Navidrome is a self-hosted music server and streamer'
-							ErrorControl='ignore'
-							Name = '$(var.ProductName)'
-							Id='NavidromeService'
-							Start='auto'
-							Type='ownProcess'
-							Vital='yes'
-							Arguments='service execute --configfile &quot;[INSTALLDIR]navidrome.ini&quot; --logfile &quot;[ND_DATAFOLDER]\navidrome.log&quot;'
-						/>
-						<ServiceControl Id='StartNavidromeService' Start='install' Stop='both' Remove='uninstall' Name='$(var.ProductName)' Wait='yes' />
-					</Component>
+				<Component Id='MainExecutable' Guid='e645aa06-8bbc-40d6-8d3c-73b4f5b76fd7' Win64="$(var.Win64)">
+					<File Id='NavidromeExe' Name='Navidrome.exe' DiskId='1' Source='navidrome.exe' KeyPath='yes' />
+					<ServiceInstall
+						Description='Navidrome is a self-hosted music server and streamer'
+						ErrorControl='ignore'
+						Name = '$(var.ProductName)'
+						Id='NavidromeService'
+						Start='auto'
+						Type='ownProcess'
+						Vital='yes'
+						Arguments='service execute --configfile &quot;[MSI_INSTALLATIONDIRECTORY]navidrome.ini&quot; --logfile &quot;[ND_DATAFOLDER]\navidrome.log&quot;'
+					/>
+					<ServiceControl Id='StartNavidromeService' Start='install' Stop='both' Remove='uninstall' Name='$(var.ProductName)' Wait='yes' />
+				</Component>
 
-					<Component Id='FFMpegExecutable' Guid='d17358f7-abdc-4080-acd3-6427903a7dd8' Win64="$(var.Win64)">
-						<File Id='ffmpeg.exe' Name='ffmpeg.exe' DiskId='1' Source='ffmpeg.exe' KeyPath='yes' />
-					</Component>
+				<Component Id='FFMpegExecutable' Guid='d17358f7-abdc-4080-acd3-6427903a7dd8' Win64="$(var.Win64)">
+					<File Id='ffmpeg.exe' Name='ffmpeg.exe' DiskId='1' Source='ffmpeg.exe' KeyPath='yes' />
+				</Component>
 
-					<Component Id='FFProbeExecutable' Guid='f8a3b2c1-5d4e-4f6a-9b8c-7e2d1a0f3c5b' Win64="$(var.Win64)">
-						<File Id='ffprobe.exe' Name='ffprobe.exe' DiskId='1' Source='ffprobe.exe' KeyPath='yes' />
-					</Component>
-
-				</Directory>
+				<Component Id='FFProbeExecutable' Guid='f8a3b2c1-5d4e-4f6a-9b8c-7e2d1a0f3c5b' Win64="$(var.Win64)">
+					<File Id='ffprobe.exe' Name='ffprobe.exe' DiskId='1' Source='ffprobe.exe' KeyPath='yes' />
+				</Component>
 			</Directory>
 
 			<Directory Id="ND_DATAFOLDER" name="[ND_DATAFOLDER]">
@@ -81,7 +92,12 @@
 			</Directory>
 		</Directory>
 
+		<InstallExecuteSequence>
+			<Custom Action="SetInstallDirProperty" Before="CostFinalize">NOT MSI_INSTALLATIONDIRECTORY</Custom>
+		</InstallExecuteSequence>
+
 		<InstallUISequence>
+			<Custom Action="SetInstallDirProperty" Before="CostFinalize">NOT MSI_INSTALLATIONDIRECTORY</Custom>
 			<Show Dialog="MyCustomPropertiesDlg" After="WelcomeDlg">Not Installed AND NOT WIX_UPGRADE_DETECTED</Show>
 		</InstallUISequence>
 

From c6732e1fdf564bb2ed2df150b1d9809079407df1 Mon Sep 17 00:00:00 2001
From: ts <933064+zerovox@users.noreply.github.com>
Date: Sat, 12 Sep 2026 10:08:25 -0600
Subject: [PATCH 134/200] feat(cli): add missing file list and remap
 subcommands (#5928)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(cli): add missing file list and remap subcommands

Signed-off-by: zerovox <933064+zerovox@users.noreply.github.com>

* fix: prevent remapping from dropping participants on target track

* fix: after remapping, refresh stats synchronously

* fix: only move album annotations if moving a track would empty the old album

* fix(persistence): keep the new item's annotation when reassigning onto an item the user already annotated

ReassignAnnotation was a plain UPDATE; the annotation table is unique on
(user_id, item_id, item_type), so when a user had annotated both items the
statement aborted and none of the rows moved. In the scanner that surfaced as
a warning; in the missing-file remap it rolled back the whole operation.
UPDATE OR IGNORE moves what it can and leaves the conflicting rows for GC.

* fix(core): keep the target track's history when remapping a missing file onto it

The remap discards the target's row, and GC then dropped its play counts,
stars, ratings, bookmarks and every playlist entry pointing at it. That is
harmless in the scanner, whose target was imported seconds earlier, but the
CLI lets the user pick any existing track. Move those references onto the
surviving id first; where a user already has a row for both, theirs on the
missing file wins.

* fix(persistence): stop FindByPaths dropping plain paths that contain a colon

Any colon was taken as the libraryID separator, and a non-numeric prefix
made the whole path vanish from the lookup. 'missing fix' then rejected the
very paths 'missing list' printed, and M3U imports silently skipped such
tracks. Only a numeric prefix qualifies a path now.

* perf(cli): stream 'missing list' instead of loading every missing file into memory

GetAll materialised the whole result set before a single row was written;
on a library with 97k missing files that peaked at 1.28 GB of RSS. Iterate
the repository cursor and write rows as they arrive.

* refactor(core): tidy the missing-file remap

Drop the log lines copied from deleteMissing that still said 'after deleting
missing files', the debug-on-success branches, and the what-comments; build
the affected album list without slice helpers.

* fix(cli): move path to the last column of 'missing list'

Path is the only variable-width field, so leading with it misaligns every
row that follows. Applies to both csv and json.

* fix(persistence): also try a numeric colon prefix as a plain path

'1999: A Different Life/01.mp3' parsed as library 1999 plus a truncated path
and matched nothing. The prefix is ambiguous, so search both ways.

Also buffer the json branch of 'missing list', which wrote a syscall per row.

* fix(persistence): move scrobbles and buffered scrobbles off a discarded media file

Both tables carry ON DELETE CASCADE on media_file_id, so 'missing fix'
deleting the target erased its play history and dropped scrobbles still
waiting on an external service. scrobble_buffer needs OR IGNORE for its
unique (user_id, service, media_file_id, play_time).

* fix(persistence): recompute the cached average rating after merging annotations

Merging the discarded row's annotations grows the rating population of the
surviving track, so media_file.average_rating no longer matched what the
annotation rows say. Only reachable since the remap started merging those
rows instead of deleting them.

* fix(persistence): recompute the cached average rating inside ReassignAnnotation

Moving annotation rows always changes the new item's rating population, so
the recompute belongs with the move rather than at each call site. Covers
the album reassign in the remap and the two scanner sites, and replaces the
explicit call ReassignReferences was making.

Album was the worse case: rate an album, move its files, and 'missing fix'
handed the rating to an album still caching an average of 0.

* fix(cli): let libraryID:path win over a file literally named like one

FindByPaths searches a numeric-prefixed reference both ways, so a top-level
file named '1:foo.mp3' can tie with library 1's 'foo.mp3'. The CLI then
rejected the reference as ambiguous while advising the exact syntax the
caller had used. Also disambiguates the same path in two libraries, which
is what the qualified form is for.

---------

Signed-off-by: zerovox <933064+zerovox@users.noreply.github.com>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 cmd/missing.go                           | 171 +++++++++++++++++++++++
 cmd/missing_test.go                      |  81 +++++++++++
 core/maintenance.go                      |  97 ++++++++++++-
 core/maintenance_test.go                 | 162 +++++++++++++++++++++
 model/mediafile.go                       |   3 +
 persistence/mediafile_repository.go      |  40 ++++--
 persistence/mediafile_repository_test.go | 123 ++++++++++++++++
 persistence/sql_annotations.go           |  14 +-
 persistence/sql_annotations_test.go      |  47 +++++++
 persistence/sql_bookmarks.go             |   7 +
 scanner/phase_2_missing_tracks_test.go   |   6 +-
 tests/mock_mediafile_repo.go             |  34 +++--
 12 files changed, 756 insertions(+), 29 deletions(-)
 create mode 100644 cmd/missing.go
 create mode 100644 cmd/missing_test.go

diff --git a/cmd/missing.go b/cmd/missing.go
new file mode 100644
index 000000000..65f571661
--- /dev/null
+++ b/cmd/missing.go
@@ -0,0 +1,171 @@
+package cmd
+
+import (
+	"bufio"
+	"context"
+	"encoding/csv"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
+	"github.com/spf13/cobra"
+)
+
+var missingListFormat string
+
+func init() {
+	missingListCmd.Flags().StringVarP(&missingListFormat, "format", "f", "csv", "output format [supported values: csv, json]")
+	missingCmd.AddCommand(missingListCmd)
+	missingCmd.AddCommand(missingFixCmd)
+	rootCmd.AddCommand(missingCmd)
+}
+
+var (
+	missingCmd = &cobra.Command{
+		Use:   "missing",
+		Short: "Manage missing files",
+		Long:  "List files marked as missing and remap them onto existing files",
+	}
+
+	missingListCmd = &cobra.Command{
+		Use:   "list",
+		Short: "List missing files",
+		Run: func(cmd *cobra.Command, _ []string) {
+			runMissingList(cmd.Context())
+		},
+	}
+
+	missingFixCmd = &cobra.Command{
+		Use:   "fix <missing path|id> <target path|id>",
+		Short: "Remap a missing file onto an existing file",
+		Long: "Remap a file marked as missing onto an existing (non-missing) file, the same way\n" +
+			"the scanner reconciles moved or renamed files. Each argument may be a media file ID,\n" +
+			"a library-relative path, or a libraryID:path pair.",
+		Args: cobra.ExactArgs(2),
+		Run: func(cmd *cobra.Command, args []string) {
+			runMissingFix(cmd.Context(), args[0], args[1])
+		},
+	}
+)
+
+type displayMissingFile struct {
+	ID        string `json:"id"`
+	LibraryID int    `json:"libraryId"`
+	Title     string `json:"title"`
+	Album     string `json:"album"`
+	Artist    string `json:"artist"`
+	Path      string `json:"path"`
+}
+
+func runMissingList(ctx context.Context) {
+	if missingListFormat != "csv" && missingListFormat != "json" {
+		log.Fatal("Invalid output format. Must be one of csv, json", "format", missingListFormat)
+	}
+
+	ds, ctx := getAdminContext(ctx)
+	mfs, err := ds.MediaFile(ctx).GetCursor(model.QueryOptions{
+		Filters: squirrel.Eq{"missing": true},
+		Sort:    "path",
+	})
+	if err == nil {
+		err = writeMissingList(os.Stdout, missingListFormat, mfs)
+	}
+	if err != nil {
+		log.Fatal(ctx, "Failed to retrieve missing files", err)
+	}
+}
+
+// writeMissingList streams the cursor so a library with many missing files doesn't get loaded into memory
+func writeMissingList(w io.Writer, format string, mfs model.MediaFileCursor) error {
+	if format == "json" {
+		bw := bufio.NewWriter(w)
+		_, _ = io.WriteString(bw, "[")
+		sep := ""
+		for mf, err := range mfs {
+			if err != nil {
+				return err
+			}
+			j, _ := json.Marshal(displayMissingFile{ID: mf.ID, LibraryID: mf.LibraryID, Title: mf.Title, Album: mf.Album, Artist: mf.Artist, Path: mf.Path})
+			_, _ = fmt.Fprintf(bw, "%s%s", sep, j)
+			sep = ","
+		}
+		_, _ = io.WriteString(bw, "]\n")
+		return bw.Flush()
+	}
+
+	cw := csv.NewWriter(w)
+	_ = cw.Write([]string{"id", "library id", "title", "album", "artist", "path"})
+	for mf, err := range mfs {
+		if err != nil {
+			return err
+		}
+		_ = cw.Write([]string{mf.ID, strconv.Itoa(mf.LibraryID), mf.Title, mf.Album, mf.Artist, mf.Path})
+	}
+	cw.Flush()
+	return cw.Error()
+}
+
+func runMissingFix(ctx context.Context, missingRef, targetRef string) {
+	ds, ctx := getAdminContext(ctx)
+
+	missing := resolveMediaFile(ctx, ds, missingRef)
+	target := resolveMediaFile(ctx, ds, targetRef)
+
+	if err := core.NewMaintenance(ds).RemapMissingFile(ctx, missing.ID, target.ID); err != nil {
+		log.Fatal(ctx, "Failed to remap missing file", "missing", missing.Path, "target", target.Path, err)
+	}
+	fmt.Printf("Remapped %q onto %q\n", missing.Path, target.Path)
+}
+
+// resolveMediaFile looks up a media file by ID first, then by path (optionally libraryID:path).
+func resolveMediaFile(ctx context.Context, ds model.DataStore, ref string) *model.MediaFile {
+	mf, err := ds.MediaFile(ctx).Get(ref)
+	if err == nil {
+		return mf
+	}
+	if !errors.Is(err, model.ErrNotFound) {
+		log.Fatal(ctx, "Error looking up media file", "ref", ref, err)
+	}
+
+	mfs, err := ds.MediaFile(ctx).FindByPaths([]string{ref})
+	if err != nil {
+		log.Fatal(ctx, "Error looking up media file by path", "ref", ref, err)
+	}
+	if len(mfs) == 0 {
+		log.Fatal(ctx, "No media file found", "ref", ref)
+	}
+	mfs = preferQualified(ref, mfs)
+	if len(mfs) > 1 {
+		log.Fatal(ctx, "Path matches multiple files; disambiguate with an ID or libraryID:path", "ref", ref, "matches", len(mfs))
+	}
+	return &mfs[0]
+}
+
+// preferQualified resolves the ambiguity FindByPaths creates by searching a "libraryID:path"
+// reference both ways: an explicit library wins over a file literally named like one.
+func preferQualified(ref string, mfs model.MediaFiles) model.MediaFiles {
+	id, path, ok := strings.Cut(ref, ":")
+	if !ok {
+		return mfs
+	}
+	libraryID, err := strconv.Atoi(id)
+	if err != nil {
+		return mfs
+	}
+	qualified := slice.Filter(mfs, func(mf model.MediaFile) bool {
+		return mf.LibraryID == libraryID && strings.EqualFold(mf.Path, path)
+	})
+	if len(qualified) == 0 {
+		return mfs
+	}
+	return qualified
+}
diff --git a/cmd/missing_test.go b/cmd/missing_test.go
new file mode 100644
index 000000000..2e96cf3c7
--- /dev/null
+++ b/cmd/missing_test.go
@@ -0,0 +1,81 @@
+package cmd
+
+import (
+	"errors"
+	"strings"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("writeMissingList", func() {
+	cursor := func(err error, mfs ...model.MediaFile) model.MediaFileCursor {
+		return func(yield func(model.MediaFile, error) bool) {
+			for _, mf := range mfs {
+				if !yield(mf, nil) {
+					return
+				}
+			}
+			if err != nil {
+				yield(model.MediaFile{}, err)
+			}
+		}
+	}
+	song := model.MediaFile{ID: "1", LibraryID: 1, Path: "Bach: Goldberg/01.mp3", Title: "Aria", Album: "Goldberg", Artist: "Bach"}
+
+	It("writes csv with a header, quoting as needed", func() {
+		var out strings.Builder
+		Expect(writeMissingList(&out, "csv", cursor(nil, song))).To(Succeed())
+		Expect(out.String()).To(Equal("id,library id,title,album,artist,path\n1,1,Aria,Goldberg,Bach,Bach: Goldberg/01.mp3\n"))
+	})
+
+	It("writes a json array", func() {
+		var out strings.Builder
+		Expect(writeMissingList(&out, "json", cursor(nil, song, song))).To(Succeed())
+		Expect(out.String()).To(MatchJSON(`[
+			{"id":"1","libraryId":1,"path":"Bach: Goldberg/01.mp3","title":"Aria","album":"Goldberg","artist":"Bach"},
+			{"id":"1","libraryId":1,"path":"Bach: Goldberg/01.mp3","title":"Aria","album":"Goldberg","artist":"Bach"}
+		]`))
+	})
+
+	It("writes an empty json array when nothing is missing", func() {
+		var out strings.Builder
+		Expect(writeMissingList(&out, "json", cursor(nil))).To(Succeed())
+		Expect(out.String()).To(MatchJSON(`[]`))
+	})
+
+	It("returns the cursor's error", func() {
+		var out strings.Builder
+		Expect(writeMissingList(&out, "csv", cursor(errors.New("boom"), song))).To(MatchError("boom"))
+	})
+})
+
+var _ = Describe("preferQualified", func() {
+	target := model.MediaFile{ID: "want", LibraryID: 1, Path: "foo.mp3"}
+	decoy := model.MediaFile{ID: "decoy", LibraryID: 1, Path: "1:foo.mp3"}
+
+	It("picks the library-qualified match over a literal path that looks like one", func() {
+		Expect(preferQualified("1:foo.mp3", model.MediaFiles{target, decoy})).To(Equal(model.MediaFiles{target}))
+	})
+
+	It("picks the named library when the same path exists in two", func() {
+		other := model.MediaFile{ID: "other", LibraryID: 2, Path: "foo.mp3"}
+		Expect(preferQualified("1:foo.mp3", model.MediaFiles{target, other})).To(Equal(model.MediaFiles{target}))
+	})
+
+	It("leaves an unqualified reference ambiguous", func() {
+		both := model.MediaFiles{target, {ID: "other", LibraryID: 2, Path: "foo.mp3"}}
+		Expect(preferQualified("foo.mp3", both)).To(Equal(both))
+	})
+
+	It("leaves it alone when the prefix is not a library id", func() {
+		both := model.MediaFiles{decoy, {ID: "other", LibraryID: 2, Path: "1:foo.mp3"}}
+		Expect(preferQualified("x:foo.mp3", both)).To(Equal(both))
+	})
+
+	It("leaves it alone when no candidate matches the qualified form", func() {
+		both := model.MediaFiles{decoy, {ID: "other", LibraryID: 2, Path: "1:foo.mp3"}}
+		Expect(preferQualified("9:nope.mp3", both)).To(Equal(both))
+	})
+})
diff --git a/core/maintenance.go b/core/maintenance.go
index 13d1141d3..56c0ac18d 100644
--- a/core/maintenance.go
+++ b/core/maintenance.go
@@ -2,6 +2,7 @@ package core
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"slices"
 	"sync"
@@ -14,11 +15,23 @@ import (
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
+var (
+	// ErrNotMissing is returned when a remap is attempted from a file not marked as missing.
+	ErrNotMissing = errors.New("file is not marked as missing")
+	// ErrTargetMissing is returned when the remap target is itself a missing file.
+	ErrTargetMissing = errors.New("target file is missing")
+	// ErrSameFile is returned when the remap source and target are the same file.
+	ErrSameFile = errors.New("missing and target are the same file")
+)
+
 type Maintenance interface {
 	// DeleteMissingFiles deletes specific missing files by their IDs
 	DeleteMissingFiles(ctx context.Context, ids []string) error
 	// DeleteAllMissingFiles deletes all files marked as missing
 	DeleteAllMissingFiles(ctx context.Context) error
+	// RemapMissingFile moves a missing file's identity onto an existing file, the manual
+	// counterpart to the scanner's move detection (phaseMissingTracks.moveMatched).
+	RemapMissingFile(ctx context.Context, missingID, targetID string) error
 }
 
 type maintenanceService struct {
@@ -40,6 +53,87 @@ func (s *maintenanceService) DeleteAllMissingFiles(ctx context.Context) error {
 	return s.deleteMissing(ctx, nil)
 }
 
+func (s *maintenanceService) RemapMissingFile(ctx context.Context, missingID, targetID string) error {
+	if missingID == targetID {
+		return fmt.Errorf("%w: %q", ErrSameFile, missingID)
+	}
+
+	missing, err := s.ds.MediaFile(ctx).Get(missingID)
+	if err != nil {
+		return fmt.Errorf("loading missing file %q: %w", missingID, err)
+	}
+	if !missing.Missing {
+		return fmt.Errorf("%w: %q", ErrNotMissing, missingID)
+	}
+
+	target, err := s.ds.MediaFile(ctx).GetWithParticipants(targetID)
+	if err != nil {
+		return fmt.Errorf("loading target file %q: %w", targetID, err)
+	}
+	if target.Missing {
+		return fmt.Errorf("%w: %q", ErrTargetMissing, targetID)
+	}
+
+	oldAlbumID, newAlbumID := missing.AlbumID, target.AlbumID
+
+	err = s.ds.WithTx(func(tx model.DataStore) error {
+		discardedID := target.ID
+
+		// Preserve the original created_at so the remapped track doesn't resurface in "Recently Added"
+		target.CreatedAt = missing.CreatedAt
+		target.ID = missing.ID
+		if err := tx.MediaFile(ctx).Put(target); err != nil {
+			return fmt.Errorf("update matched track: %w", err)
+		}
+		// Unlike the scanner's freshly-imported target, this one may carry history of its own
+		if err := tx.MediaFile(ctx).ReassignReferences(discardedID, missing.ID); err != nil {
+			return fmt.Errorf("reassign target references: %w", err)
+		}
+		if err := tx.MediaFile(ctx).Delete(discardedID); err != nil {
+			return fmt.Errorf("delete discarded track: %w", err)
+		}
+
+		if oldAlbumID != newAlbumID {
+			oldAlbumTracks, err := tx.MediaFile(ctx).CountAll(model.QueryOptions{Filters: squirrel.Eq{"album_id": oldAlbumID}})
+			if err != nil {
+				return fmt.Errorf("get old album tracks: %w", err)
+			}
+			if oldAlbumTracks == 0 {
+				if err := tx.Album(ctx).ReassignAnnotation(oldAlbumID, newAlbumID); err != nil {
+					return fmt.Errorf("reassign album annotations: %w", err)
+				}
+				if err := tx.Album(ctx).CopyAttributes(oldAlbumID, newAlbumID, "created_at"); err != nil && !errors.Is(err, model.ErrNotFound) {
+					return fmt.Errorf("copy album attributes: %w", err)
+				}
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		log.Error(ctx, "Error remapping missing file", "missing", missing.Path, "target", target.Path, err)
+		return err
+	}
+
+	if err := s.ds.GC(ctx); err != nil {
+		log.Error(ctx, "Error running GC after remapping missing file", err)
+		return err
+	}
+
+	// Stats are refreshed synchronously, unlike deleteMissing, so the CLI sees them before it exits.
+	// album/artist play count aggregates are not recalculated here; they are refreshed by the next scan.
+	if _, err := s.ds.Artist(ctx).RefreshStats(true); err != nil {
+		log.Error(ctx, "Error refreshing artist stats after remapping missing file", err)
+	}
+	affectedAlbumIDs := []string{newAlbumID}
+	if oldAlbumID != newAlbumID {
+		affectedAlbumIDs = append(affectedAlbumIDs, oldAlbumID)
+	}
+	if err := s.refreshAlbums(ctx, affectedAlbumIDs); err != nil {
+		log.Error(ctx, "Error refreshing album stats after remapping missing file", err)
+	}
+	return nil
+}
+
 // deleteMissing handles the deletion of missing files and triggers necessary cleanup operations
 func (s *maintenanceService) deleteMissing(ctx context.Context, ids []string) error {
 	// Track affected album IDs before deletion for refresh
@@ -68,7 +162,8 @@ func (s *maintenanceService) deleteMissing(ctx context.Context, ids []string) er
 		return err
 	}
 
-	// Refresh statistics in background
+	// Refresh statistics in background. album/artist play count aggregates are not recalculated
+	// here; they are refreshed by the next scan.
 	s.refreshStatsAsync(ctx, affectedAlbumIDs)
 
 	return nil
diff --git a/core/maintenance_test.go b/core/maintenance_test.go
index 09b442438..56e6d13b5 100644
--- a/core/maintenance_test.go
+++ b/core/maintenance_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"sync"
+	"time"
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -250,6 +251,167 @@ var _ = Describe("Maintenance", func() {
 			})
 		})
 	})
+
+	Describe("RemapMissingFile", func() {
+		It("relocates the missing file's identity onto the target and runs GC", func() {
+			created := time.Now().Add(-30 * 24 * time.Hour)
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", Path: "old/song.mp3", AlbumID: "album1", CreatedAt: created, Missing: true},
+				{ID: "t1", Path: "new/song.mp3", AlbumID: "album1", Missing: false},
+			})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
+
+			got, err := mfRepo.Get("m1")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Path).To(Equal("new/song.mp3")) // moved to target's location
+			Expect(got.Missing).To(BeFalse())
+			Expect(got.CreatedAt).To(BeTemporally("==", created)) // created_at preserved
+			exists, _ := mfRepo.Exists("t1")
+			Expect(exists).To(BeFalse()) // discarded row removed
+			Expect(ds.GCCalled).To(BeTrue())
+		})
+
+		It("moves the target's annotations, bookmarks and playlist entries onto the surviving id", func() {
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", AlbumID: "album1", Missing: true},
+				{ID: "t1", AlbumID: "album1", Missing: false},
+			})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
+
+			Expect(mfRepo.ReassignReferencesCalls).To(HaveKeyWithValue("t1", "m1"))
+		})
+
+		It("reassigns album annotations when the old album is emptied", func() {
+			albumRepo := ds.MockedAlbum.(*extendedAlbumRepo)
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", AlbumID: "album1", Missing: true},
+				{ID: "t1", AlbumID: "album2", Missing: false},
+			})
+
+			mfRepo.SetCountAll(0)
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
+
+			Expect(albumRepo.ReassignAnnotationCalls).To(HaveKeyWithValue("album1", "album2"))
+		})
+
+		It("does not reassign album annotations when the old album is not emptied", func() {
+			albumRepo := ds.MockedAlbum.(*extendedAlbumRepo)
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", AlbumID: "album1", Missing: true},
+				{ID: "m2", AlbumID: "album1", Missing: false},
+				{ID: "t1", AlbumID: "album2", Missing: false},
+			})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
+
+			Expect(albumRepo.ReassignAnnotationCalls).To(BeEmpty())
+		})
+
+		It("does not reassign annotations when the album is unchanged", func() {
+			albumRepo := ds.MockedAlbum.(*extendedAlbumRepo)
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", AlbumID: "album1", Missing: true},
+				{ID: "t1", AlbumID: "album1", Missing: false},
+			})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
+
+			Expect(albumRepo.ReassignAnnotationCalls).To(BeEmpty())
+		})
+
+		It("returns ErrNotFound when the missing file does not exist", func() {
+			mfRepo.SetData(model.MediaFiles{{ID: "t1", Missing: false}})
+
+			Expect(service.RemapMissingFile(ctx, "nope", "t1")).To(MatchError(model.ErrNotFound))
+		})
+
+		It("refuses to remap from a file that is not missing", func() {
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", Missing: false},
+				{ID: "t1", Missing: false},
+			})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(MatchError(ErrNotMissing))
+		})
+
+		It("refuses to remap a file onto itself", func() {
+			mfRepo.SetData(model.MediaFiles{{ID: "m1", Missing: true}})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "m1")).To(MatchError(ErrSameFile))
+		})
+
+		It("refuses to remap onto a target that is itself missing", func() {
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", Missing: true},
+				{ID: "t1", Missing: true},
+			})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(MatchError(ErrTargetMissing))
+		})
+
+		It("refreshes artist and album stats right after the remap", func() {
+			artistRepo := ds.MockedArtist.(*extendedArtistRepo)
+			albumRepo := ds.MockedAlbum.(*extendedAlbumRepo)
+			albumRepo.SetData(model.Albums{
+				{ID: "album1", Name: "Old Album", SongCount: 2, Size: 1100, Duration: 110},
+				{ID: "album2", Name: "New Album", SongCount: 1, Size: 2000, Duration: 200},
+			})
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", Path: "old/1.mp3", Album: "Old Album", AlbumID: "album1", Missing: true, Size: 100, Duration: 10},
+				{ID: "k1", Path: "old/2.mp3", Album: "Old Album", AlbumID: "album1", Missing: false, Size: 1000, Duration: 100},
+				{ID: "t1", Path: "new/1.mp3", Album: "New Album", AlbumID: "album2", Missing: false, Size: 2000, Duration: 200},
+			})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
+
+			Expect(artistRepo.IsRefreshStatsCalled()).To(BeTrue(), "Artist stats should be refreshed")
+
+			// The old album lost the remapped track, so its stats are recalculated from the remaining one
+			oldAlbum, err := albumRepo.Get("album1")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(oldAlbum.SongCount).To(Equal(1))
+			Expect(oldAlbum.Size).To(Equal(int64(1000)))
+			Expect(oldAlbum.Duration).To(BeNumerically("==", 100))
+
+			// The target album keeps the track, now under the missing file's ID
+			newAlbum, err := albumRepo.Get("album2")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(newAlbum.SongCount).To(Equal(1))
+			Expect(newAlbum.Size).To(Equal(int64(2000)))
+			Expect(newAlbum.Duration).To(BeNumerically("==", 200))
+		})
+
+		It("returns an error if GC fails", func() {
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", AlbumID: "album1", Missing: true},
+				{ID: "t1", AlbumID: "album1", Missing: false},
+			})
+			ds.GCError = errors.New("gc failed")
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(MatchError(ContainSubstring("gc failed")))
+		})
+
+		It("preserves the target's participants on the remapped track", func() {
+			participant := model.Participant{
+				Artist: model.Artist{ID: "a1", Name: "Artist", OrderArtistName: "artist", MbzArtistID: "mbz-artist"},
+			}
+			mfRepo.SetData(model.MediaFiles{
+				{ID: "m1", AlbumID: "album1", Missing: true},
+				{ID: "t1", AlbumID: "album2", Missing: false, Participants: model.Participants{
+					model.RoleArtist: model.ParticipantList{participant},
+				}},
+			})
+
+			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
+
+			// The surviving row is the missing file's ID, holding the target's data
+			got, err := mfRepo.GetWithParticipants("m1")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Participants).To(HaveKeyWithValue(model.RoleArtist, model.ParticipantList{participant}))
+		})
+	})
 })
 
 // Test helper to create a mock DataStore with controllable behavior
diff --git a/model/mediafile.go b/model/mediafile.go
index 2669018f3..7cbdb583c 100644
--- a/model/mediafile.go
+++ b/model/mediafile.go
@@ -563,6 +563,9 @@ type MediaFileRepository interface {
 	DeleteMissing(ids []string) error
 	DeleteAllMissing() (int64, error)
 	FindByPaths(paths []string) (MediaFiles, error)
+	// ReassignReferences moves annotations, bookmarks and playlist entries from prevID to newID,
+	// keeping newID's own row wherever a user has both.
+	ReassignReferences(prevID, newID string) error
 
 	// The following methods are used exclusively by the scanner:
 	MarkMissing(bool, ...*MediaFile) error
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index da167b1a8..935a64bb9 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -362,19 +362,14 @@ func (r *mediaFileRepository) FindByPaths(paths []string) (model.MediaFiles, err
 	var unqualified []string
 
 	for _, path := range paths {
-		parts := strings.SplitN(path, ":", 2)
-		if len(parts) == 2 {
-			// Library-qualified path: "libraryID:path"
-			libraryID, err := strconv.Atoi(parts[0])
-			if err != nil {
-				// Invalid format, skip
-				continue
+		// A numeric prefix is ambiguous: "1:foo.mp3" qualifies a library, but "1999: A Life/01.mp3"
+		// is a plain path. Search both ways rather than guessing.
+		if id, rest, ok := strings.Cut(path, ":"); ok {
+			if libraryID, err := strconv.Atoi(id); err == nil {
+				byLibrary[libraryID] = append(byLibrary[libraryID], rest)
 			}
-			byLibrary[libraryID] = append(byLibrary[libraryID], parts[1])
-		} else {
-			// Unqualified path: search across all libraries
-			unqualified = append(unqualified, path)
 		}
+		unqualified = append(unqualified, path)
 	}
 
 	query := Or{}
@@ -405,6 +400,29 @@ func (r *mediaFileRepository) Delete(id string) error {
 	return r.delete(Eq{"id": id})
 }
 
+func (r *mediaFileRepository) ReassignReferences(prevID, newID string) error {
+	if err := r.ReassignAnnotation(prevID, newID); err != nil {
+		return fmt.Errorf("reassigning annotations: %w", err)
+	}
+	if err := r.reassignBookmark(prevID, newID); err != nil {
+		return fmt.Errorf("reassigning bookmarks: %w", err)
+	}
+	upd := Update("playlist_tracks").Set("media_file_id", newID).Where(Eq{"media_file_id": prevID})
+	if _, err := r.executeSQL(upd); err != nil {
+		return fmt.Errorf("reassigning playlist tracks: %w", err)
+	}
+	upd = Update("scrobbles").Set("media_file_id", newID).Where(Eq{"media_file_id": prevID})
+	if _, err := r.executeSQL(upd); err != nil {
+		return fmt.Errorf("reassigning scrobbles: %w", err)
+	}
+	// OR IGNORE: scrobble_buffer is unique on (user_id, service, media_file_id, play_time)
+	buf := Expr("update or ignore scrobble_buffer set media_file_id = ? where media_file_id = ?", newID, prevID)
+	if _, err := r.executeSQL(buf); err != nil {
+		return fmt.Errorf("reassigning buffered scrobbles: %w", err)
+	}
+	return nil
+}
+
 func (r *mediaFileRepository) DeleteAllMissing() (int64, error) {
 	user := loggedUser(r.ctx)
 	if !user.IsAdmin {
diff --git a/persistence/mediafile_repository_test.go b/persistence/mediafile_repository_test.go
index 8a492a813..1fb939415 100644
--- a/persistence/mediafile_repository_test.go
+++ b/persistence/mediafile_repository_test.go
@@ -16,6 +16,7 @@ import (
 	"github.com/navidrome/navidrome/model/criteria"
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/pocketbase/dbx"
@@ -918,6 +919,105 @@ var _ = Describe("MediaRepository", func() {
 		})
 	})
 
+	Describe("ReassignReferences", func() {
+		var prev, next model.MediaFile
+		var pr model.PlaylistRepository
+		var pls model.Playlist
+
+		BeforeEach(func() {
+			ctx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid"})
+			pr = NewPlaylistRepository(ctx, GetDBXBuilder())
+			prev = model.MediaFile{ID: "reassign-prev", LibraryID: 1, Path: "reassign/prev.mp3", Title: "Prev"}
+			next = model.MediaFile{ID: "reassign-next", LibraryID: 1, Path: "reassign/next.mp3", Title: "Next"}
+			Expect(mr.Put(&prev)).To(Succeed())
+			Expect(mr.Put(&next)).To(Succeed())
+			pls = model.Playlist{Name: "Reassign", OwnerID: "userid"}
+			pls.AddMediaFilesByID([]string{prev.ID})
+			Expect(pr.Put(&pls)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			_ = pr.Delete(pls.ID)
+			_ = mr.Delete(prev.ID)
+			_ = mr.Delete(next.ID)
+			_, _ = mr.(*mediaFileRepository).executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
+			_, _ = mr.(*mediaFileRepository).executeSQL(squirrel.Delete("bookmark").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
+			_, _ = mr.(*mediaFileRepository).executeSQL(squirrel.Delete("scrobbles").Where(squirrel.Eq{"media_file_id": []string{prev.ID, next.ID}}))
+			_, _ = mr.(*mediaFileRepository).executeSQL(squirrel.Delete("scrobble_buffer").Where(squirrel.Eq{"media_file_id": []string{prev.ID, next.ID}}))
+		})
+
+		It("moves annotations, bookmarks and playlist entries onto the new id", func() {
+			Expect(mr.SetRating(5, prev.ID)).To(Succeed())
+			Expect(mr.AddBookmark(prev.ID, "here", 42)).To(Succeed())
+
+			Expect(mr.ReassignReferences(prev.ID, next.ID)).To(Succeed())
+
+			got, err := mr.Get(next.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Rating).To(Equal(5))
+
+			bookmarks, err := mr.GetBookmarks()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(bookmarks).To(ContainElement(HaveField("Item.ID", next.ID)))
+
+			withTracks, err := pr.GetWithTracks(pls.ID, false, false)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(withTracks.Tracks).To(HaveLen(1))
+			Expect(withTracks.Tracks[0].MediaFileID).To(Equal(next.ID))
+		})
+
+		It("moves scrobbles and buffered scrobbles onto the new id", func() {
+			ctx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid"})
+			scrobbles := NewScrobbleRepository(ctx, GetDBXBuilder())
+			buffer := NewScrobbleBufferRepository(ctx, GetDBXBuilder())
+			Expect(scrobbles.RecordScrobble(prev.ID, time.Now())).To(Succeed())
+			Expect(buffer.Enqueue("lastfm", "userid", prev.ID, time.Now())).To(Succeed())
+
+			Expect(mr.ReassignReferences(prev.ID, next.ID)).To(Succeed())
+			Expect(mr.Delete(prev.ID)).To(Succeed())
+
+			all, err := scrobbles.GetAll()
+			Expect(err).ToNot(HaveOccurred())
+			mine := slice.Map(slice.Filter(all, func(sc model.Scrobble) bool {
+				return sc.MediaFileID == prev.ID || sc.MediaFileID == next.ID
+			}), func(sc model.Scrobble) string { return sc.MediaFileID })
+			Expect(mine).To(ConsistOf(next.ID))
+
+			entry, err := buffer.Next("lastfm", "userid")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(entry).ToNot(BeNil())
+			Expect(entry.MediaFile.ID).To(Equal(next.ID))
+		})
+
+		It("recomputes the average rating after merging another user's annotation", func() {
+			other := NewMediaFileRepository(request.WithUser(log.NewContext(context.TODO()), model.User{ID: "2222"}), GetDBXBuilder())
+			Expect(mr.SetRating(5, next.ID)).To(Succeed())
+			Expect(other.SetRating(3, prev.ID)).To(Succeed())
+
+			Expect(mr.ReassignReferences(prev.ID, next.ID)).To(Succeed())
+
+			got, err := mr.Get(next.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.AverageRating).To(Equal(4.0))
+		})
+
+		It("keeps the new id's own annotation and bookmark when both exist", func() {
+			Expect(mr.SetRating(5, prev.ID)).To(Succeed())
+			Expect(mr.SetRating(1, next.ID)).To(Succeed())
+			Expect(mr.AddBookmark(prev.ID, "prev", 42)).To(Succeed())
+			Expect(mr.AddBookmark(next.ID, "next", 7)).To(Succeed())
+
+			Expect(mr.ReassignReferences(prev.ID, next.ID)).To(Succeed())
+
+			got, err := mr.Get(next.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Rating).To(Equal(1))
+			bookmarks, err := mr.GetBookmarks()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(bookmarks).To(ContainElement(SatisfyAll(HaveField("Item.ID", next.ID), HaveField("Comment", "next"))))
+		})
+	})
+
 	Describe("FindByPaths", func() {
 		// Test fixtures for Unicode and case-sensitivity tests
 		var testFiles []model.MediaFile
@@ -930,6 +1030,8 @@ var _ = Describe("MediaRepository", func() {
 				{ID: "findpath-3", LibraryID: 1, Path: "plex/02 - ＡＣＲＯＳＳ.flac", Title: "Fullwidth"},
 				// French diacritic: è (U+00E8, can decompose to e + combining grave)
 				{ID: "findpath-4", LibraryID: 1, Path: "artist/Michèle/song.mp3", Title: "French"},
+				{ID: "findpath-5", LibraryID: 1, Path: "Bach: Goldberg Variations/01.mp3", Title: "Colon"},
+				{ID: "findpath-6", LibraryID: 1, Path: "1999: A Different Life/01.mp3", Title: "Numeric colon"},
 			}
 			for _, mf := range testFiles {
 				Expect(mr.Put(&mf)).To(Succeed())
@@ -942,6 +1044,27 @@ var _ = Describe("MediaRepository", func() {
 			}
 		})
 
+		It("treats a path whose prefix is not a library id as unqualified", func() {
+			results, err := mr.FindByPaths([]string{"Bach: Goldberg Variations/01.mp3"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(results).To(HaveLen(1))
+			Expect(results[0].ID).To(Equal("findpath-5"))
+		})
+
+		It("finds a plain path whose colon prefix looks like a library id", func() {
+			results, err := mr.FindByPaths([]string{"1999: A Different Life/01.mp3"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(results).To(HaveLen(1))
+			Expect(results[0].ID).To(Equal("findpath-6"))
+		})
+
+		It("splits only the first colon of a library-qualified path", func() {
+			results, err := mr.FindByPaths([]string{"1:Bach: Goldberg Variations/01.mp3"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(results).To(HaveLen(1))
+			Expect(results[0].ID).To(Equal("findpath-5"))
+		})
+
 		It("finds files by exact path", func() {
 			results, err := mr.FindByPaths([]string{"1:artist/Album/track.mp3"})
 			Expect(err).ToNot(HaveOccurred())
diff --git a/persistence/sql_annotations.go b/persistence/sql_annotations.go
index 46ad6a0de..27445b886 100644
--- a/persistence/sql_annotations.go
+++ b/persistence/sql_annotations.go
@@ -185,12 +185,14 @@ func (r sqlRepository) ReassignAnnotation(prevID string, newID string) error {
 	if prevID == newID || prevID == "" || newID == "" {
 		return nil
 	}
-	upd := Update(annotationTable).Where(And{
-		Eq{annotationTable + ".item_type": r.tableName},
-		Eq{annotationTable + ".item_id": prevID},
-	}).Set("item_id", newID)
-	_, err := r.executeSQL(upd)
-	return err
+	// OR IGNORE keeps newID's own row where a user annotated both, instead of aborting the whole statement
+	upd := Expr("update or ignore "+annotationTable+" set item_id = ? where item_type = ? and item_id = ?",
+		newID, r.tableName, prevID)
+	if _, err := r.executeSQL(upd); err != nil {
+		return err
+	}
+	// The moved rows change newID's rating population, so its cached average no longer matches
+	return r.updateAvgRating(newID)
 }
 
 func (r sqlRepository) cleanAnnotations() error {
diff --git a/persistence/sql_annotations_test.go b/persistence/sql_annotations_test.go
index 5766f687f..79ad3c152 100644
--- a/persistence/sql_annotations_test.go
+++ b/persistence/sql_annotations_test.go
@@ -30,6 +30,53 @@ var _ = Describe("Annotation Filters", func() {
 		_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": albumWithoutAnnotation.ID}))
 	})
 
+	Describe("ReassignAnnotation", func() {
+		var prev, next model.Album
+
+		BeforeEach(func() {
+			prev = model.Album{ID: "reassign-prev", Name: "Prev", LibraryID: 1}
+			next = model.Album{ID: "reassign-next", Name: "Next", LibraryID: 1}
+			Expect(albumRepo.Put(&prev)).To(Succeed())
+			Expect(albumRepo.Put(&next)).To(Succeed())
+		})
+
+		AfterEach(func() {
+			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
+			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": []string{prev.ID, next.ID}}))
+		})
+
+		It("moves the annotation when the new item has none", func() {
+			Expect(albumRepo.SetRating(4, prev.ID)).To(Succeed())
+
+			Expect(albumRepo.ReassignAnnotation(prev.ID, next.ID)).To(Succeed())
+
+			got, err := albumRepo.Get(next.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Rating).To(Equal(4))
+		})
+
+		It("recomputes the new item's cached average rating", func() {
+			Expect(albumRepo.SetRating(4, prev.ID)).To(Succeed())
+
+			Expect(albumRepo.ReassignAnnotation(prev.ID, next.ID)).To(Succeed())
+
+			got, err := albumRepo.Get(next.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.AverageRating).To(Equal(4.0))
+		})
+
+		It("keeps the new item's annotation when both exist", func() {
+			Expect(albumRepo.SetRating(4, prev.ID)).To(Succeed())
+			Expect(albumRepo.SetRating(2, next.ID)).To(Succeed())
+
+			Expect(albumRepo.ReassignAnnotation(prev.ID, next.ID)).To(Succeed())
+
+			got, err := albumRepo.Get(next.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Rating).To(Equal(2))
+		})
+	})
+
 	Describe("annotationBoolFilter", func() {
 		DescribeTable("creates correct SQL expressions",
 			func(field, value string, expectedSQL string, expectedArgs []any) {
diff --git a/persistence/sql_bookmarks.go b/persistence/sql_bookmarks.go
index 19f16b231..a9f53430d 100644
--- a/persistence/sql_bookmarks.go
+++ b/persistence/sql_bookmarks.go
@@ -144,6 +144,13 @@ func (r sqlRepository) GetBookmarks() (model.Bookmarks, error) {
 	return resp, nil
 }
 
+func (r sqlRepository) reassignBookmark(prevID, newID string) error {
+	upd := Expr("update or ignore "+bookmarkTable+" set item_id = ? where item_type = ? and item_id = ?",
+		newID, r.tableName, prevID)
+	_, err := r.executeSQL(upd)
+	return err
+}
+
 func (r sqlRepository) cleanBookmarks() error {
 	del := Delete(bookmarkTable).Where(Eq{"item_type": r.tableName}).Where("item_id not in (select id from " + r.tableName + ")")
 	c, err := r.executeSQL(del)
diff --git a/scanner/phase_2_missing_tracks_test.go b/scanner/phase_2_missing_tracks_test.go
index d54ceee40..f93b166c1 100644
--- a/scanner/phase_2_missing_tracks_test.go
+++ b/scanner/phase_2_missing_tracks_test.go
@@ -311,7 +311,7 @@ var _ = Describe("phaseMissingTracks", func() {
 		When("PurgeMissing is 'always'", func() {
 			BeforeEach(func() {
 				conf.Server.Scanner.PurgeMissing = consts.PurgeMissingAlways
-				mr.CountAllValue = 3
+				mr.SetCountAll(3)
 				mr.DeleteAllMissingValue = 3
 			})
 			It("should purge missing files", func() {
@@ -325,7 +325,7 @@ var _ = Describe("phaseMissingTracks", func() {
 		When("PurgeMissing is 'full'", func() {
 			BeforeEach(func() {
 				conf.Server.Scanner.PurgeMissing = consts.PurgeMissingFull
-				mr.CountAllValue = 2
+				mr.SetCountAll(2)
 				mr.DeleteAllMissingValue = 2
 			})
 			It("should not purge missing files if not a full scan", func() {
@@ -346,7 +346,7 @@ var _ = Describe("phaseMissingTracks", func() {
 		When("PurgeMissing is 'never'", func() {
 			BeforeEach(func() {
 				conf.Server.Scanner.PurgeMissing = consts.PurgeMissingNever
-				mr.CountAllValue = 1
+				mr.SetCountAll(1)
 				mr.DeleteAllMissingValue = 1
 			})
 			It("should not purge missing files", func() {
diff --git a/tests/mock_mediafile_repo.go b/tests/mock_mediafile_repo.go
index 7a1a8f926..74225cd9b 100644
--- a/tests/mock_mediafile_repo.go
+++ b/tests/mock_mediafile_repo.go
@@ -24,11 +24,14 @@ type MockMediaFileRepo struct {
 	model.MediaFileRepository
 	Data map[string]*model.MediaFile
 	Err  bool
-	// Add fields and methods for controlling CountAll and DeleteAllMissing in tests
-	CountAllValue         int64
+	// Add fields and methods for controlling CountAll and DeleteAllMissing in tests.
+	// A nil CountAllValue is unset, and CountAll falls back to counting rows in Data.
+	CountAllValue         *int64
 	CountAllOptions       model.QueryOptions
 	DeleteAllMissingValue int64
-	Options               model.QueryOptions
+	// ReassignReferencesCalls records prevID -> newID
+	ReassignReferencesCalls map[string]string
+	Options                 model.QueryOptions
 	// Add fields for cross-library move detection tests
 	FindRecentFilesByMBZTrackIDFunc func(missing model.MediaFile, since time.Time) (model.MediaFiles, error)
 	FindRecentFilesByPropertiesFunc func(missing model.MediaFile, since time.Time) (model.MediaFiles, error)
@@ -40,6 +43,10 @@ func (m *MockMediaFileRepo) SetError(err bool) {
 	m.Err = err
 }
 
+func (m *MockMediaFileRepo) SetCountAll(count int64) {
+	m.CountAllValue = &count
+}
+
 func (m *MockMediaFileRepo) SetData(mfs model.MediaFiles) {
 	m.Data = make(map[string]*model.MediaFile)
 	for i, mf := range mfs {
@@ -163,6 +170,17 @@ func (m *MockMediaFileRepo) Delete(id string) error {
 	return nil
 }
 
+func (m *MockMediaFileRepo) ReassignReferences(prevID, newID string) error {
+	if m.Err {
+		return errors.New("error")
+	}
+	if m.ReassignReferencesCalls == nil {
+		m.ReassignReferencesCalls = make(map[string]string)
+	}
+	m.ReassignReferencesCalls[prevID] = newID
+	return nil
+}
+
 func (m *MockMediaFileRepo) IncPlayCount(id string, timestamp time.Time) error {
 	if m.Err {
 		return errors.New("error")
@@ -251,11 +269,11 @@ func (m *MockMediaFileRepo) CountAll(opts ...model.QueryOptions) (int64, error)
 	if m.Err {
 		return 0, errors.New("error")
 	}
-	if m.CountAllValue != 0 {
-		if len(opts) > 0 {
-			m.CountAllOptions = opts[0]
-		}
-		return m.CountAllValue, nil
+	if len(opts) > 0 {
+		m.CountAllOptions = opts[0]
+	}
+	if m.CountAllValue != nil {
+		return *m.CountAllValue, nil
 	}
 	return int64(len(m.Data)), nil
 }

From 2d09ebc67661d9a31f02f673c4a5e94c8eeb98cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 12 Sep 2026 12:58:00 -0400
Subject: [PATCH 135/200] fix(ui): update Chinese (traditional) translations
 from POEditor (#6128)

Co-authored-by: navidrome-bot <navidrome-bot@navidrome.org>
---
 resources/i18n/zh-Hant.json | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/resources/i18n/zh-Hant.json b/resources/i18n/zh-Hant.json
index 5e48352ea..7b8819da3 100644
--- a/resources/i18n/zh-Hant.json
+++ b/resources/i18n/zh-Hant.json
@@ -94,7 +94,7 @@
         "download": "下載",
         "info": "取得資訊",
         "share": "分享",
-        "refresh": ""
+        "refresh": "重新整理中繼資料"
       },
       "lists": {
         "all": "所有",
@@ -157,12 +157,12 @@
         "token": "權杖",
         "lastAccessAt": "上次存取",
         "libraries": "媒體庫",
-        "scrobbleFilter": ""
+        "scrobbleFilter": "紀錄過濾條件"
       },
       "helperTexts": {
         "name": "您的名稱會在下次登入時生效",
         "libraries": "為該使用者選擇指定媒體庫，留空則使用預設媒體庫",
-        "scrobbleFilter": ""
+        "scrobbleFilter": "符合這些智慧播放清單規則的歌曲將不會傳送至 Last.fm、ListenBrainz 或 Scrobbler 插件。語法與行為皆與智慧播放清單的 JSON 格式相同。範例：{\"all\":[{\"lt\":{\"rating\":4}}]}。若留空則會記錄所有播放紀錄。本機播放次數不受影響。"
       },
       "notifications": {
         "created": "使用者已建立",
@@ -177,7 +177,7 @@
       },
       "validation": {
         "librariesRequired": "非管理員使用者必須至少選擇一個媒體庫",
-        "invalidScrobbleFilter": ""
+        "invalidScrobbleFilter": "必須是有效的智慧播放清單規則。不支援數量限制、位移及重新整理延遲。"
       }
     },
     "player": {
@@ -202,7 +202,7 @@
         "command": "指令"
       },
       "choices": {
-        "noDefaultBitRate": ""
+        "noDefaultBitRate": "無"
       }
     },
     "playlist": {
@@ -412,7 +412,7 @@
         "configValidationError": "設定驗證失敗：",
         "schemaRenderError": "無法顯示設定表單。外掛的 schema 可能無效。",
         "allowWriteAccessHelp": "啟用後，外掛可以修改媒體庫目錄中的檔案。 預設情況下，外掛具有唯讀權限。",
-        "idHelp": ""
+        "idHelp": "插件 ID，衍生自其檔案名稱。在 Agents 等設定選項中參照此插件時請使用此 ID。"
       },
       "placeholders": {
         "configKey": "鍵",
@@ -609,7 +609,7 @@
     "coverRemoved": "已移除封面圖",
     "coverUploadError": "上傳封面圖時發生錯誤",
     "coverRemoveError": "移除封面圖時發生錯誤",
-    "metadataRefreshStarted": ""
+    "metadataRefreshStarted": "正在背景重新整理中繼資料"
   },
   "menu": {
     "library": "媒體庫",

From 4168377b656f1237da4bcb503a08094cb885b115 Mon Sep 17 00:00:00 2001
From: Sudo-Ivan <ivan@quad4.io>
Date: Sat, 12 Sep 2026 12:37:33 -0500
Subject: [PATCH 136/200] Merge commit from fork

---
 persistence/artist_repository.go      | 21 ++++++++++--
 persistence/artist_repository_test.go | 46 +++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/persistence/artist_repository.go b/persistence/artist_repository.go
index 1ff291a0f..97c1452cb 100644
--- a/persistence/artist_repository.go
+++ b/persistence/artist_repository.go
@@ -162,13 +162,26 @@ func NewArtistRepository(ctx context.Context, db dbx.Builder) model.ArtistReposi
 
 func roleFilter(_ string, role any) Sqlizer {
 	if role, ok := role.(string); ok {
-		if _, ok := model.AllRoles[role]; ok {
-			return Expr("JSON_EXTRACT(library_artist.stats, '$." + role + ".m') IS NOT NULL")
+		if safe, ok := sanitizeArtistStatsRole(role); ok && safe != "total" {
+			return Expr("JSON_EXTRACT(library_artist.stats, '$." + safe + ".m') IS NOT NULL")
 		}
 	}
 	return Eq{"1": 2}
 }
 
+// sanitizeArtistStatsRole allowlists values interpolated into JSON paths for artist
+// stats (filter and sort). "total" is the aggregate key stored by the scanner.
+// Unknown values must not reach SQL string concatenation.
+func sanitizeArtistStatsRole(role string) (string, bool) {
+	if role == "" || role == "total" {
+		return "total", true
+	}
+	if _, ok := model.AllRoles[role]; ok {
+		return role, true
+	}
+	return "", false
+}
+
 // artistLibraryIdFilter filters artists based on library access through the library_artist table
 func artistLibraryIdFilter(_ string, value any) Sqlizer {
 	return Eq{"library_artist.library_id": value}
@@ -716,7 +729,9 @@ func (r *artistRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
 	role := "total"
 	if len(options) > 0 {
 		if v, ok := options[0].Filters["role"].(string); ok {
-			role = v
+			if safe, ok := sanitizeArtistStatsRole(v); ok {
+				role = safe
+			}
 		}
 	}
 	r.sortMappings["song_count"] = "sum(stats->>'" + role + "'->>'m')"
diff --git a/persistence/artist_repository_test.go b/persistence/artist_repository_test.go
index d337b4c22..f6612acc4 100644
--- a/persistence/artist_repository_test.go
+++ b/persistence/artist_repository_test.go
@@ -112,6 +112,52 @@ var _ = Describe("ArtistRepository", func() {
 			})
 		})
 
+		Describe("sanitizeArtistStatsRole", func() {
+			It("allowlists total and registered roles", func() {
+				role, ok := sanitizeArtistStatsRole("total")
+				Expect(ok).To(BeTrue())
+				Expect(role).To(Equal("total"))
+				role, ok = sanitizeArtistStatsRole("albumartist")
+				Expect(ok).To(BeTrue())
+				Expect(role).To(Equal("albumartist"))
+			})
+
+			It("rejects SQL injection payloads used in sort mappings", func() {
+				payload := "total'||(SELECT password FROM user LIMIT 1)||'"
+				role, ok := sanitizeArtistStatsRole(payload)
+				Expect(ok).To(BeFalse())
+				Expect(role).To(BeEmpty())
+			})
+		})
+
+		Describe("ReadAll role sort SQL injection", func() {
+			It("does not interpolate attacker-controlled role into ORDER BY", func() {
+				ctx := request.WithUser(GinkgoT().Context(), adminUser)
+				repo := NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)
+				payload := "total') OR 1=1--"
+				_, err := repo.ReadAll(rest.QueryOptions{
+					Sort:    "songCount",
+					Order:   "ASC",
+					Filters: map[string]any{"role": payload},
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(repo.sortMappings["song_count"]).To(Equal("sum(stats->>'total'->>'m')"))
+				Expect(repo.sortMappings["song_count"]).ToNot(ContainSubstring(payload))
+			})
+
+			It("keeps valid role sort paths", func() {
+				ctx := request.WithUser(GinkgoT().Context(), adminUser)
+				repo := NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)
+				_, err := repo.ReadAll(rest.QueryOptions{
+					Sort:    "songCount",
+					Order:   "DESC",
+					Filters: map[string]any{"role": "composer"},
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(repo.sortMappings["song_count"]).To(Equal("sum(stats->>'composer'->>'m')"))
+			})
+		})
+
 		Describe("searchScope", func() {
 			// Resolves the library IDs a search must be restricted to (nil = fast-path / no filter),
 			// the way Search() does, for a repo whose context carries the given user.

From 1a8463f7de3cfc3c71a3af7488492b890eea9bad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 12 Sep 2026 13:38:08 -0400
Subject: [PATCH 137/200] Merge commit from fork

* fix(share): always assign the authenticated user as share owner

A share's UserID was taken from the request body and only defaulted when
empty, so any authenticated user could create a share attributed to
another user. For playlist shares the contents are resolved in the
owner's library-access context, turning the spoofed owner into an
access-escalation vector in multi-library setups.

Force the owner from the request context at both the service boundary
and the persistence layer, ignoring any client-supplied UserID.

* fix(plugins): block SSRF to private IPs resolved from hostnames

The HTTP host client only checked the literal host string, so a symbolic
hostname (or a trailing-dot "localhost.") resolving to a private/loopback
address bypassed the SSRF guard when a plugin declared no requiredHosts.

Enforce the check at dial time via net.Dialer.Control on the resolved IP,
which also covers redirect hops and DNS rebinding. When an explicit
requiredHosts allowlist is set, defer to it as the operator's trust decision.

* fix(plugins): gate private IPs on explicit IP/CIDR allowlist entries

Following review feedback: an allowlisted hostname authorizes the external
service, not whatever private IP it may resolve or rebind to. Enforce the
resolved-IP guard even when requiredHosts is set, permitting a private
address only when a literal IP or CIDR entry explicitly covers it. This
keeps "reach this external API" and "reach my internal network" as two
separate, explicit operator decisions.

* fix(plugins): treat unspecified addresses as private in the SSRF guard

Dialing 0.0.0.0 or :: reaches the local host, so they bypassed the
private/loopback check.

* fix(plugins): let a bare "*" allowlist reach private addresses

Plugins such as AudioMuse-AI declare requiredHosts ["*"] to reach a
user-configured service on the LAN, whose address the manifest cannot
know. Requiring a literal IP/CIDR entry broke them. Named hosts and
subdomain wildcards still cannot resolve to private addresses.

* refactor(plugins): simplify the SSRF-guarded HTTP client and release its pool

Build the client directly around the guarded transport instead of
replacing a throwaway one, fail closed on an unparseable dial address,
and close the per-plugin transport's idle connections when the plugin
unloads. Trim stale comments.

* fix(plugins): stop enabling extism's unguarded http_request host function

Passing requiredHosts as the extism manifest's AllowedHosts enabled
extism's own http_request (pdk.NewHTTPRequest), which only glob-matches
the hostname and follows redirects without re-checking, bypassing the
resolved-IP SSRF guard. Plugins must use host.HTTPSend.

* fix(plugins): move bundled Rust examples to the host HTTP service

Extism's built-in http_request is now disabled, so the webhook and
Discord examples switch to nd_pdk::host::http::send. Update the README
to say host.HTTPSend is the only supported way to make HTTP requests.

* fix(plugins): move the Python example to the host HTTP service

coverartarchive-py used extism's built-in Http.request, which is now
disabled. Call Navidrome's http_send host function instead. The plugin
can no longer run under the standalone extism CLI, so drop the CLI test
targets and instructions.
---
 core/share.go                                 |  6 ++
 core/share_test.go                            | 10 +++
 persistence/share_repository.go               |  4 +-
 persistence/share_repository_test.go          | 22 ++++++
 plugins/README.md                             |  2 +-
 plugins/examples/coverartarchive-py/Makefile  | 17 +----
 plugins/examples/coverartarchive-py/README.md |  9 +--
 .../coverartarchive-py/plugin/__init__.py     | 31 ++++++---
 .../discord-rich-presence-rs/src/rpc.rs       | 47 ++++++++-----
 plugins/examples/webhook-rs/src/lib.rs        | 18 +++--
 plugins/host_httpclient.go                    | 68 +++++++++++++++++--
 plugins/host_httpclient_test.go               | 67 +++++++++++++++++-
 plugins/manager_loader.go                     | 14 ++--
 plugins/manager_loader_test.go                |  4 +-
 14 files changed, 238 insertions(+), 81 deletions(-)

diff --git a/core/share.go b/core/share.go
index 5ee1a5667..a291a060c 100644
--- a/core/share.go
+++ b/core/share.go
@@ -12,6 +12,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
 	. "github.com/navidrome/navidrome/utils/gg"
 	"github.com/navidrome/navidrome/utils/nanoid"
 	"github.com/navidrome/navidrome/utils/slice"
@@ -91,6 +92,11 @@ func (r *shareRepositoryWrapper) newId() (string, error) {
 
 func (r *shareRepositoryWrapper) Save(entity any) (string, error) {
 	s := entity.(*model.Share)
+	// Owner is always the caller; never trust a client-supplied UserID, as it
+	// determines the library-access context used to resolve the share contents.
+	if user, ok := request.UserFrom(r.ctx); ok {
+		s.UserID = user.ID
+	}
 	id, err := r.newId()
 	if err != nil {
 		return "", err
diff --git a/core/share_test.go b/core/share_test.go
index a5ee0428b..e6dec1b92 100644
--- a/core/share_test.go
+++ b/core/share_test.go
@@ -5,6 +5,7 @@ import (
 
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -39,6 +40,15 @@ var _ = Describe("Share", func() {
 				Expect(entity.ID).To(Equal(id))
 			})
 
+			It("assigns the logged-in user as owner, ignoring a client-supplied UserID", func() {
+				loggedInCtx := request.WithUser(context.Background(), model.User{ID: "logged-in-user"})
+				repo := share.NewRepository(loggedInCtx).(rest.Persistable)
+				entity := &model.Share{Description: "test", ResourceIDs: "123", UserID: "victim-user"}
+				_, err := repo.Save(entity)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(entity.UserID).To(Equal("logged-in-user"))
+			})
+
 			It("does not truncate ASCII labels shorter than 30 characters", func() {
 				_ = ds.MediaFile(ctx).Put(&model.MediaFile{ID: "456", Title: "Example Media File"})
 				entity := &model.Share{Description: "test", ResourceIDs: "456"}
diff --git a/persistence/share_repository.go b/persistence/share_repository.go
index 92c696688..bcf33790d 100644
--- a/persistence/share_repository.go
+++ b/persistence/share_repository.go
@@ -170,8 +170,10 @@ func (r *shareRepository) Update(id string, entity any, cols ...string) error {
 func (r *shareRepository) Save(entity any) (string, error) {
 	s := entity.(*model.Share)
 	// TODO Validate record
+	// Owner is server-managed: for an authenticated request, never trust a
+	// client-supplied UserID, as it drives the share's library-access context.
 	u := loggedUser(r.ctx)
-	if s.UserID == "" {
+	if u.ID != invalidUserId || s.UserID == "" {
 		s.UserID = u.ID
 	}
 	s.CreatedAt = time.Now()
diff --git a/persistence/share_repository_test.go b/persistence/share_repository_test.go
index 02d8a7386..af8cf2ae9 100644
--- a/persistence/share_repository_test.go
+++ b/persistence/share_repository_test.go
@@ -393,6 +393,28 @@ var _ = Describe("ShareRepository", func() {
 			})
 		})
 
+		Describe("Save", func() {
+			It("assigns the logged-in user as owner, ignoring a client-supplied UserID", func() {
+				ur := NewUserRepository(ctx, GetDBXBuilder())
+				Expect(ur.Put(&ownerUser)).To(Succeed())
+				Expect(ur.Put(&otherUser)).To(Succeed())
+
+				attackerCtx := request.WithUser(log.NewContext(GinkgoT().Context()), ownerUser)
+				attackerRepo := NewShareRepository(attackerCtx, GetDBXBuilder()).(rest.Persistable)
+
+				id, err := attackerRepo.Save(&model.Share{
+					ID: "spoof-save-share", UserID: otherUser.ID,
+					ResourceType: "media_file", ResourceIDs: "1001",
+				})
+				Expect(err).ToNot(HaveOccurred())
+
+				adminRepo := NewShareRepository(request.WithUser(log.NewContext(GinkgoT().Context()), adminUser), GetDBXBuilder())
+				got, err := adminRepo.Get(id)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(got.UserID).To(Equal(ownerUser.ID))
+			})
+		})
+
 		Describe("Update", func() {
 			It("allows a non-admin user to update their own share", func() {
 				insertShare("own-share-upd", ownerUser.ID)
diff --git a/plugins/README.md b/plugins/README.md
index 7042b8c45..10eb34fbc 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -401,7 +401,7 @@ import "github.com/navidrome/navidrome/plugins/pdk/go/host"
 
 ### HTTP
 
-Make HTTP requests to external services. This is a dedicated host service (separate from Extism's built-in HTTP support) with additional features like timeouts and redirect control.
+Make HTTP requests to external services, with timeouts, redirect control, and protection against reaching private network addresses. This is the only supported way to make HTTP requests: Extism's built-in HTTP (`pdk.NewHTTPRequest`) is disabled.
 
 **Manifest permission:**
 
diff --git a/plugins/examples/coverartarchive-py/Makefile b/plugins/examples/coverartarchive-py/Makefile
index e3cd60d1c..c47c242d7 100644
--- a/plugins/examples/coverartarchive-py/Makefile
+++ b/plugins/examples/coverartarchive-py/Makefile
@@ -1,5 +1,5 @@
 # Build the Cover Art Archive Python plugin
-.PHONY: build test clean
+.PHONY: build clean
 
 WASM_FILE = coverartarchive-py.wasm
 
@@ -8,20 +8,5 @@ build: $(WASM_FILE)
 $(WASM_FILE): plugin/__init__.py
 	extism-py plugin/__init__.py -o $(WASM_FILE)
 
-test: build
-	@echo "Testing nd_manifest..."
-	extism call $(WASM_FILE) nd_manifest --wasi
-	@echo ""
-	@echo "Testing nd_get_album_images with Portishead's Dummy MBID..."
-	extism call $(WASM_FILE) nd_get_album_images --wasi \
-		--input '{"name":"Dummy","artist":"Portishead","mbid":"76df3287-6cda-33eb-8e9a-044b5e15ffdd"}' \
-		--allow-host "coverartarchive.org" --allow-host "archive.org"
-
-test-error: build
-	@echo "Testing error case (missing MBID)..."
-	-extism call $(WASM_FILE) nd_get_album_images --wasi \
-		--input '{"name":"Test Album","artist":"Test Artist"}' \
-		--allow-host "coverartarchive.org"
-
 clean:
 	rm -f $(WASM_FILE)
diff --git a/plugins/examples/coverartarchive-py/README.md b/plugins/examples/coverartarchive-py/README.md
index 77957ac4f..c779f4a43 100644
--- a/plugins/examples/coverartarchive-py/README.md
+++ b/plugins/examples/coverartarchive-py/README.md
@@ -51,14 +51,7 @@ zip -j coverartarchive-py.ndp manifest.json plugin.wasm
 
 ## Testing
 
-Extract the wasm file and test:
-
-```bash
-unzip -p coverartarchive-py.ndp plugin.wasm > coverartarchive-py.wasm
-extism call coverartarchive-py.wasm nd_get_album_images --wasi \
-  --input '{"name":"Dummy","artist":"Portishead","mbid":"76df3287-6cda-33eb-8e9a-044b5e15ffdd"}' \
-  --allow-host "coverartarchive.org" --allow-host "archive.org"
-```
+The plugin makes HTTP requests through Navidrome's `http_send` host function, so it only runs inside Navidrome (the `extism` CLI can't provide that function). Install the `.ndp` as described above, then open an album that has a MusicBrainz ID and check the Navidrome logs.
 
 ## How It Works
 
diff --git a/plugins/examples/coverartarchive-py/plugin/__init__.py b/plugins/examples/coverartarchive-py/plugin/__init__.py
index 3c1d4149e..e6f4c6a07 100644
--- a/plugins/examples/coverartarchive-py/plugin/__init__.py
+++ b/plugins/examples/coverartarchive-py/plugin/__init__.py
@@ -5,16 +5,25 @@
 #
 # Build with:
 #   extism-py plugin/__init__.py -o coverartarchive-py.wasm
-#
-# Test with:
-#   extism call coverartarchive-py.wasm nd_get_album_images --wasi \
-#     --input '{"name":"Dummy","artist":"Portishead","mbid":"76df3287-6cda-33eb-8e9a-044b5e15ffdd"}' \
-#     --allow-host "coverartarchive.org" --allow-host "archive.org"
 
+import base64
 import extism
 import json
 
 
+@extism.import_fn("extism:host/user", "http_send")
+def http_send(req: dict) -> dict: ...
+
+
+def http_get(url):
+    """GET url via Navidrome's HTTP host service. Returns (status_code, body_bytes)."""
+    resp = http_send({"request": {"method": "GET", "url": url}})
+    if resp.get("error"):
+        raise Exception(f"HTTP request failed: {resp['error']}")
+    result = resp.get("result") or {}
+    return result.get("statusCode", 0), base64.b64decode(result.get("body") or "")
+
+
 @extism.plugin_fn
 def nd_get_album_images():
     """Retrieve album cover images from Cover Art Archive."""
@@ -26,13 +35,13 @@ def nd_get_album_images():
     
     # Query Cover Art Archive API
     url = f"https://coverartarchive.org/release/{mbid}"
-    response = extism.Http.request(url, meth="GET")
-    
-    if response.status_code != 200:
-        raise Exception(f"not found: CAA returned status {response.status_code}")
-    
+    status, body = http_get(url)
+
+    if status != 200:
+        raise Exception(f"not found: CAA returned status {status}")
+
     try:
-        data = json.loads(response.data_str())
+        data = json.loads(body)
     except json.JSONDecodeError:
         raise Exception("not found: invalid JSON response")
     
diff --git a/plugins/examples/discord-rich-presence-rs/src/rpc.rs b/plugins/examples/discord-rich-presence-rs/src/rpc.rs
index 3de9eff63..d90cb4341 100644
--- a/plugins/examples/discord-rich-presence-rs/src/rpc.rs
+++ b/plugins/examples/discord-rich-presence-rs/src/rpc.rs
@@ -4,7 +4,7 @@
 //! presence updates, and heartbeat management.
 
 use extism_pdk::*;
-use nd_pdk::host::{cache, scheduler, websocket};
+use nd_pdk::host::{cache, http, scheduler, websocket};
 use serde::{Deserialize, Serialize};
 
 // ============================================================================
@@ -359,19 +359,33 @@ fn find_username_for_connection(connection_id: &str) -> Result<Option<String>, E
     Ok(cache::get_string(&reverse_key)?.filter(|s| !s.is_empty()))
 }
 
-fn get_discord_gateway() -> Result<String, Error> {
-    let req = HttpRequest::new("https://discord.com/api/gateway")
-        .with_method("GET");
+fn send_http(
+    method: &str,
+    url: &str,
+    headers: std::collections::HashMap<String, String>,
+    body: Vec<u8>,
+) -> Result<http::HTTPResponse, Error> {
+    http::send(http::HTTPRequest {
+        method: method.into(),
+        url: url.into(),
+        headers,
+        no_follow_redirects: false,
+        body,
+        timeout_ms: 0,
+    })?
+    .ok_or_else(|| Error::msg("empty HTTP response"))
+}
 
-    let resp = http::request::<String>(&req, None::<String>)?;
-    if resp.status_code() >= 400 {
+fn get_discord_gateway() -> Result<String, Error> {
+    let resp = send_http("GET", "https://discord.com/api/gateway", Default::default(), Vec::new())?;
+    if resp.status_code >= 400 {
         return Err(Error::msg(format!(
             "Failed to get Discord gateway: HTTP {}",
-            resp.status_code()
+            resp.status_code
         )));
     }
 
-    let body = resp.body();
+    let body = resp.body;
     let data: std::collections::HashMap<String, String> = serde_json::from_slice(&body)
         .map_err(|e| Error::msg(format!("Failed to parse gateway response: {}", e)))?;
 
@@ -487,23 +501,22 @@ fn process_image_inner(
         client_id
     );
 
-    let req = HttpRequest::new(&api_url)
-        .with_method("POST")
-        .with_header("Authorization", token)
-        .with_header("Content-Type", "application/json");
-
-    let resp = http::request::<String>(&req, Some(body))?;
-    if resp.status_code() >= 400 {
+    let headers = std::collections::HashMap::from([
+        ("Authorization".to_string(), token.to_string()),
+        ("Content-Type".to_string(), "application/json".to_string()),
+    ]);
+    let resp = send_http("POST", &api_url, headers, body.into_bytes())?;
+    if resp.status_code >= 400 {
         if is_default {
             return Err(Error::msg(format!(
                 "failed to process default image: HTTP {}",
-                resp.status_code()
+                resp.status_code
             )));
         }
         return process_image_inner(DEFAULT_IMAGE, client_id, token, true);
     }
 
-    let body = resp.body();
+    let body = resp.body;
     let data: Vec<std::collections::HashMap<String, String>> = serde_json::from_slice(&body)
         .map_err(|e| Error::msg(format!("Failed to parse image response: {}", e)))?;
 
diff --git a/plugins/examples/webhook-rs/src/lib.rs b/plugins/examples/webhook-rs/src/lib.rs
index 743c03744..794cda59c 100644
--- a/plugins/examples/webhook-rs/src/lib.rs
+++ b/plugins/examples/webhook-rs/src/lib.rs
@@ -12,7 +12,8 @@
 //! urls = "https://example.com/webhook1,https://example.com/webhook2"
 //! ```
 
-use extism_pdk::{config, error, http, info, warn, HttpRequest};
+use extism_pdk::{config, error, info, warn};
+use nd_pdk::host::http::{self, HTTPRequest};
 use nd_pdk::scrobbler::{
     Error, IsAuthorizedRequest, NowPlayingRequest, PlaybackReportRequest, ScrobbleRequest,
     Scrobbler,
@@ -90,11 +91,18 @@ impl Scrobbler for WebhookPlugin {
             let full_url = format!("{}{}", url, query);
             info!("Sending webhook to: {}", full_url);
 
-            let http_req = HttpRequest::new(&full_url);
-            match http::request::<()>(&http_req, None) {
+            let http_req = HTTPRequest {
+                method: "GET".into(),
+                url: full_url,
+                headers: Default::default(),
+                no_follow_redirects: false,
+                body: Vec::new(),
+                timeout_ms: 0,
+            };
+            match http::send(http_req) {
                 Ok(res) => {
-                    let status = res.status_code();
-                    if status >= 200 && status < 300 {
+                    let status = res.map_or(0, |r| r.status_code);
+                    if (200..300).contains(&status) {
                         info!("Webhook succeeded: {} (status {})", url, status);
                     } else {
                         warn!("Webhook returned non-2xx status: {} (status {})", url, status);
diff --git a/plugins/host_httpclient.go b/plugins/host_httpclient.go
index d52898bdd..749ba096e 100644
--- a/plugins/host_httpclient.go
+++ b/plugins/host_httpclient.go
@@ -9,7 +9,9 @@ import (
 	"net"
 	"net/http"
 	"net/url"
+	"slices"
 	"strings"
+	"syscall"
 	"time"
 
 	"github.com/navidrome/navidrome/log"
@@ -34,6 +36,7 @@ type httpServiceImpl struct {
 	pluginName    string
 	requiredHosts []string
 	client        *http.Client
+	transport     *http.Transport
 }
 
 // newHTTPService creates a new HTTPService for a plugin.
@@ -46,8 +49,14 @@ func newHTTPService(pluginName string, permission *HTTPPermission) *httpServiceI
 		pluginName:    pluginName,
 		requiredHosts: requiredHosts,
 	}
+	svc.transport = http.DefaultTransport.(*http.Transport).Clone()
+	svc.transport.DialContext = (&net.Dialer{
+		Timeout:   30 * time.Second,
+		KeepAlive: 30 * time.Second,
+		Control:   svc.dialControl,
+	}).DialContext
 	// No client timeout: it is set per-request via context deadline.
-	svc.client = httpclient.New(0)
+	svc.client = &http.Client{Transport: httpclient.NewTransport(svc.transport)}
 	svc.client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
 		if req.Context().Value(noFollowRedirectsKey) != nil {
 			return http.ErrUseLastResponse
@@ -65,6 +74,12 @@ func newHTTPService(pluginName string, permission *HTTPPermission) *httpServiceI
 	return svc
 }
 
+// Close releases the plugin's pooled connections when the plugin is unloaded.
+func (s *httpServiceImpl) Close() error {
+	s.transport.CloseIdleConnections()
+	return nil
+}
+
 func (s *httpServiceImpl) Send(ctx context.Context, request host.HTTPRequest) (*host.HTTPResponse, error) {
 	// Parse and validate URL
 	parsedURL, err := url.Parse(request.URL)
@@ -159,11 +174,49 @@ func (s *httpServiceImpl) validateHost(ctx context.Context, hostStr string) erro
 	return nil
 }
 
+// dialControl checks the resolved IP, so hostnames can't reach private addresses unless a literal
+// IP/CIDR entry or a bare "*" (plugins targeting user-configured LAN services) allows it.
+func (s *httpServiceImpl) dialControl(_, address string, _ syscall.RawConn) error {
+	if slices.Contains(s.requiredHosts, "*") {
+		return nil
+	}
+	host, _, err := net.SplitHostPort(address)
+	if err != nil {
+		return err
+	}
+	ip := net.ParseIP(host)
+	if ip == nil || !isPrivateIP(ip) {
+		return nil
+	}
+	for _, entry := range s.requiredHosts {
+		if ipMatchesEntry(entry, ip) {
+			return nil
+		}
+	}
+	return fmt.Errorf("dial to private/loopback address %q blocked: requires an explicit IP or CIDR in requiredHosts", address)
+}
+
+// ipMatchesEntry reports whether a requiredHosts entry is a literal IP or CIDR
+// that covers ip. Hostname and wildcard entries never match.
+func ipMatchesEntry(entry string, ip net.IP) bool {
+	if _, cidr, err := net.ParseCIDR(entry); err == nil {
+		return cidr.Contains(ip)
+	}
+	if entryIP := net.ParseIP(entry); entryIP != nil {
+		return entryIP.Equal(ip)
+	}
+	return false
+}
+
 func (s *httpServiceImpl) isHostAllowed(hostname string) bool {
+	ip := net.ParseIP(hostname)
 	for _, pattern := range s.requiredHosts {
 		if matchHostPattern(pattern, hostname) {
 			return true
 		}
+		if ip != nil && ipMatchesEntry(pattern, ip) {
+			return true
+		}
 	}
 	return false
 }
@@ -182,11 +235,8 @@ func extractHostname(hostStr string) string {
 	return hostStr
 }
 
-// isPrivateOrLoopback returns true if the given hostname resolves to or is
-// a private, loopback, or link-local IP address. This includes:
-// IPv4: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16
-// IPv6: ::1, fc00::/7, fe80::/10
-// It also blocks "localhost" by name.
+// isPrivateOrLoopback is a pre-flight check on the literal host (IP or "localhost"); it does not
+// resolve names, so dialControl remains the real guard.
 func isPrivateOrLoopback(hostname string) bool {
 	if strings.EqualFold(hostname, "localhost") {
 		return true
@@ -195,7 +245,11 @@ func isPrivateOrLoopback(hostname string) bool {
 	if ip == nil {
 		return false
 	}
-	return ip.IsLoopback() || ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()
+	return isPrivateIP(ip)
+}
+
+func isPrivateIP(ip net.IP) bool {
+	return ip.IsLoopback() || ip.IsUnspecified() || ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()
 }
 
 // Verify interface implementation
diff --git a/plugins/host_httpclient_test.go b/plugins/host_httpclient_test.go
index 4eb34a247..6edf75a97 100644
--- a/plugins/host_httpclient_test.go
+++ b/plugins/host_httpclient_test.go
@@ -3,6 +3,7 @@ package plugins
 import (
 	"context"
 	"io"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -43,6 +44,21 @@ var _ = Describe("httpServiceImpl", func() {
 			Expect(err.Error()).To(ContainSubstring("private/loopback"))
 		})
 
+		It("should block a symbolic hostname that resolves to loopback (SSRF)", func() {
+			ts = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(200)
+			}))
+			// The trailing dot passes the pre-flight string check; only the dial-time guard catches it.
+			_, port, _ := net.SplitHostPort(strings.TrimPrefix(ts.URL, "http://"))
+			_, err := svc.Send(context.Background(), host.HTTPRequest{
+				Method:    "GET",
+				URL:       "http://localhost.:" + port + "/test",
+				TimeoutMs: 1000,
+			})
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("private/loopback"))
+		})
+
 		It("should block requests to localhost by name", func() {
 			_, err := svc.Send(context.Background(), host.HTTPRequest{
 				Method:    "GET",
@@ -419,13 +435,53 @@ var _ = Describe("httpServiceImpl", func() {
 			Expect(resp).To(BeNil())
 		})
 
+		It("blocks a private IP reached via a hostname allowlist entry (rebinding protection)", func() {
+			// Allowlisting a name authorizes the external service, not whatever private
+			// IP it may resolve or rebind to. Only literal IP/CIDR entries do that.
+			svc.requiredHosts = []string{"api.example.com"}
+			err := svc.dialControl("tcp", "10.0.0.1:80", nil)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("private/loopback"))
+		})
+
+		It("allows a private IP that an explicit CIDR allowlist entry authorizes", func() {
+			svc.requiredHosts = []string{"10.0.0.0/8"}
+			Expect(svc.dialControl("tcp", "10.0.0.1:80", nil)).To(Succeed())
+		})
+
+		It("allows private IPs when the allowlist is the bare '*' wildcard", func() {
+			svc.requiredHosts = []string{"*"}
+			Expect(svc.dialControl("tcp", "192.168.1.10:8000", nil)).To(Succeed())
+			Expect(svc.dialControl("tcp", "127.0.0.1:8000", nil)).To(Succeed())
+		})
+
+		It("still blocks private IPs for a subdomain wildcard entry", func() {
+			svc.requiredHosts = []string{"*.example.com"}
+			Expect(svc.dialControl("tcp", "10.0.0.1:80", nil)).To(MatchError(ContainSubstring("private/loopback")))
+		})
+
+		It("closes idle pooled connections on Close", func() {
+			closed := make(chan struct{})
+			ts = httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+			ts.Config.ConnState = func(_ net.Conn, state http.ConnState) {
+				if state == http.StateClosed {
+					close(closed)
+				}
+			}
+			ts.Start()
+			svc.requiredHosts = []string{"127.0.0.1"}
+			_, err := svc.Send(context.Background(), host.HTTPRequest{Method: "GET", URL: ts.URL, TimeoutMs: 1000})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(svc.Close()).To(Succeed())
+			Eventually(closed).Should(BeClosed())
+		})
+
 		It("should allow wildcard host patterns", func() {
 			ts = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 				_, _ = w.Write([]byte("wildcard"))
 			}))
-			// *.allowed.org is in the requiredHosts from BeforeEach, but test server is 127.0.0.1
-			// Override with a wildcard that matches the test server
-			svc.requiredHosts = []string{"*.0.0.1"}
+			// The literal IP is what authorizes the loopback dial under the private-IP guard.
+			svc.requiredHosts = []string{"*.0.0.1", "127.0.0.1"}
 			resp, err := svc.Send(context.Background(), host.HTTPRequest{
 				Method:    "GET",
 				URL:       ts.URL,
@@ -566,6 +622,11 @@ var _ = Describe("isPrivateOrLoopback", func() {
 		Expect(isPrivateOrLoopback("fe80::1")).To(BeTrue())
 	})
 
+	It("should detect unspecified addresses, which dial the local host", func() {
+		Expect(isPrivateOrLoopback("0.0.0.0")).To(BeTrue())
+		Expect(isPrivateOrLoopback("::")).To(BeTrue())
+	})
+
 	It("should allow public IPs", func() {
 		Expect(isPrivateOrLoopback("8.8.8.8")).To(BeFalse())
 		Expect(isPrivateOrLoopback("203.0.113.1")).To(BeFalse())
diff --git a/plugins/manager_loader.go b/plugins/manager_loader.go
index 46da56396..024b14b72 100644
--- a/plugins/manager_loader.go
+++ b/plugins/manager_loader.go
@@ -148,7 +148,7 @@ var hostServices = []hostServiceEntry{
 		create: func(ctx *serviceContext) ([]extism.HostFunction, io.Closer, error) {
 			perm := ctx.permissions.Http
 			service := newHTTPService(ctx.pluginName, perm)
-			return host.RegisterHTTPHostFunctions(service), nil, nil
+			return host.RegisterHTTPHostFunctions(service), service, nil
 		},
 	},
 	{
@@ -498,18 +498,12 @@ func parsePluginConfig(configJSON string) (map[string]string, error) {
 	return pluginConfig, nil
 }
 
-// buildExtismManifest describes the plugin to extism. It must never set
-// AllowedPaths: extism would replace our jailed FSConfig with plain dir mounts.
+// buildExtismManifest describes the plugin to extism. It must never set AllowedPaths (extism would replace our
+// jailed FSConfig) nor AllowedHosts (extism's http_request has no SSRF guard; plugins must use host.HTTPSend).
 func buildExtismManifest(pkg *ndpPackage, pluginConfig map[string]string) extism.Manifest {
-	manifest := extism.Manifest{
+	return extism.Manifest{
 		Wasm:    []extism.Wasm{extism.WasmData{Data: pkg.WasmBytes, Name: "main"}},
 		Config:  pluginConfig,
 		Timeout: uint64(defaultTimeout.Milliseconds()),
 	}
-	if pkg.Manifest.Permissions != nil && pkg.Manifest.Permissions.Http != nil {
-		if hosts := pkg.Manifest.Permissions.Http.RequiredHosts; len(hosts) > 0 {
-			manifest.AllowedHosts = hosts
-		}
-	}
-	return manifest
 }
diff --git a/plugins/manager_loader_test.go b/plugins/manager_loader_test.go
index 6326b2218..85a636202 100644
--- a/plugins/manager_loader_test.go
+++ b/plugins/manager_loader_test.go
@@ -23,8 +23,8 @@ var _ = Describe("buildExtismManifest", func() {
 		Expect(buildExtismManifest(pkg, nil).AllowedPaths).To(BeEmpty())
 	})
 
-	It("carries the hosts the plugin is allowed to reach", func() {
-		Expect(buildExtismManifest(pkg, nil).AllowedHosts).To(Equal([]string{"example.com"}))
+	It("never sets AllowedHosts, so plugin HTTP can't bypass the host service's SSRF guard", func() {
+		Expect(buildExtismManifest(pkg, nil).AllowedHosts).To(BeEmpty())
 	})
 })
 

From 276d767ce5baad29fe66d115a23a2d8b7fc4cab8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 12 Sep 2026 13:41:00 -0400
Subject: [PATCH 138/200] Merge commit from fork

* fix(plugins): apply the private-address dial guard to WebSocket connections

The WebSocket host service only matched the host string against
requiredHosts, so an allowlisted name resolving (or rebinding) to a
private address was dialed. Share the HTTP client's resolved-IP check
and allowlist matching, so WebSocket follows the same rules: named hosts
can't reach private addresses, literal IP/CIDR entries and a bare "*"
can.

* refactor(plugins): drop redundant WebSocket dial timeout and tidy guard tests
---
 plugins/host_httpclient.go     | 48 ++--------------------------
 plugins/host_netguard.go       | 58 ++++++++++++++++++++++++++++++++++
 plugins/host_websocket.go      | 14 ++++----
 plugins/host_websocket_test.go | 45 ++++++++++++++++++++++++++
 4 files changed, 112 insertions(+), 53 deletions(-)
 create mode 100644 plugins/host_netguard.go

diff --git a/plugins/host_httpclient.go b/plugins/host_httpclient.go
index 749ba096e..209f80eb0 100644
--- a/plugins/host_httpclient.go
+++ b/plugins/host_httpclient.go
@@ -9,7 +9,6 @@ import (
 	"net"
 	"net/http"
 	"net/url"
-	"slices"
 	"strings"
 	"syscall"
 	"time"
@@ -174,51 +173,12 @@ func (s *httpServiceImpl) validateHost(ctx context.Context, hostStr string) erro
 	return nil
 }
 
-// dialControl checks the resolved IP, so hostnames can't reach private addresses unless a literal
-// IP/CIDR entry or a bare "*" (plugins targeting user-configured LAN services) allows it.
 func (s *httpServiceImpl) dialControl(_, address string, _ syscall.RawConn) error {
-	if slices.Contains(s.requiredHosts, "*") {
-		return nil
-	}
-	host, _, err := net.SplitHostPort(address)
-	if err != nil {
-		return err
-	}
-	ip := net.ParseIP(host)
-	if ip == nil || !isPrivateIP(ip) {
-		return nil
-	}
-	for _, entry := range s.requiredHosts {
-		if ipMatchesEntry(entry, ip) {
-			return nil
-		}
-	}
-	return fmt.Errorf("dial to private/loopback address %q blocked: requires an explicit IP or CIDR in requiredHosts", address)
-}
-
-// ipMatchesEntry reports whether a requiredHosts entry is a literal IP or CIDR
-// that covers ip. Hostname and wildcard entries never match.
-func ipMatchesEntry(entry string, ip net.IP) bool {
-	if _, cidr, err := net.ParseCIDR(entry); err == nil {
-		return cidr.Contains(ip)
-	}
-	if entryIP := net.ParseIP(entry); entryIP != nil {
-		return entryIP.Equal(ip)
-	}
-	return false
+	return checkPrivateDial(s.requiredHosts, address)
 }
 
 func (s *httpServiceImpl) isHostAllowed(hostname string) bool {
-	ip := net.ParseIP(hostname)
-	for _, pattern := range s.requiredHosts {
-		if matchHostPattern(pattern, hostname) {
-			return true
-		}
-		if ip != nil && ipMatchesEntry(pattern, ip) {
-			return true
-		}
-	}
-	return false
+	return isHostInAllowlist(s.requiredHosts, hostname)
 }
 
 // extractHostname returns the hostname portion of a host string, stripping
@@ -248,9 +208,5 @@ func isPrivateOrLoopback(hostname string) bool {
 	return isPrivateIP(ip)
 }
 
-func isPrivateIP(ip net.IP) bool {
-	return ip.IsLoopback() || ip.IsUnspecified() || ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()
-}
-
 // Verify interface implementation
 var _ host.HTTPService = (*httpServiceImpl)(nil)
diff --git a/plugins/host_netguard.go b/plugins/host_netguard.go
new file mode 100644
index 000000000..8400446ed
--- /dev/null
+++ b/plugins/host_netguard.go
@@ -0,0 +1,58 @@
+package plugins
+
+import (
+	"fmt"
+	"net"
+	"slices"
+)
+
+// checkPrivateDial runs at dial time on the resolved IP, so hostnames can't reach private addresses unless a
+// literal IP/CIDR entry or a bare "*" (plugins targeting user-configured LAN services) allows it.
+func checkPrivateDial(requiredHosts []string, address string) error {
+	if slices.Contains(requiredHosts, "*") {
+		return nil
+	}
+	host, _, err := net.SplitHostPort(address)
+	if err != nil {
+		return err
+	}
+	ip := net.ParseIP(host)
+	if ip == nil || !isPrivateIP(ip) {
+		return nil
+	}
+	for _, entry := range requiredHosts {
+		if ipMatchesEntry(entry, ip) {
+			return nil
+		}
+	}
+	return fmt.Errorf("dial to private/loopback address %q blocked: requires an explicit IP or CIDR in requiredHosts", address)
+}
+
+func isHostInAllowlist(requiredHosts []string, hostname string) bool {
+	ip := net.ParseIP(hostname)
+	for _, pattern := range requiredHosts {
+		if matchHostPattern(pattern, hostname) {
+			return true
+		}
+		if ip != nil && ipMatchesEntry(pattern, ip) {
+			return true
+		}
+	}
+	return false
+}
+
+// ipMatchesEntry reports whether a requiredHosts entry is a literal IP or CIDR
+// that covers ip. Hostname and wildcard entries never match.
+func ipMatchesEntry(entry string, ip net.IP) bool {
+	if _, cidr, err := net.ParseCIDR(entry); err == nil {
+		return cidr.Contains(ip)
+	}
+	if entryIP := net.ParseIP(entry); entryIP != nil {
+		return entryIP.Equal(ip)
+	}
+	return false
+}
+
+func isPrivateIP(ip net.IP) bool {
+	return ip.IsLoopback() || ip.IsUnspecified() || ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()
+}
diff --git a/plugins/host_websocket.go b/plugins/host_websocket.go
index 82aded0cb..933e53144 100644
--- a/plugins/host_websocket.go
+++ b/plugins/host_websocket.go
@@ -5,10 +5,12 @@ import (
 	"errors"
 	"fmt"
 	"maps"
+	"net"
 	"net/http"
 	"net/url"
 	"strings"
 	"sync"
+	"syscall"
 	"time"
 
 	"github.com/gorilla/websocket"
@@ -112,6 +114,7 @@ func (s *webSocketServiceImpl) Connect(ctx context.Context, urlStr string, heade
 	// Establish WebSocket connection
 	dialer := websocket.Dialer{
 		HandshakeTimeout: 30 * time.Second,
+		NetDialContext:   (&net.Dialer{Control: s.dialControl}).DialContext,
 	}
 
 	conn, resp, err := dialer.DialContext(ctx, urlStr, httpHeaders)
@@ -243,14 +246,11 @@ func (s *webSocketServiceImpl) getConnection(connectionID string) (*wsConnection
 }
 
 func (s *webSocketServiceImpl) isHostAllowed(host string) bool {
-	hostWithoutPort := extractHostname(host)
+	return isHostInAllowlist(s.requiredHosts, extractHostname(host))
+}
 
-	for _, pattern := range s.requiredHosts {
-		if matchHostPattern(pattern, hostWithoutPort) {
-			return true
-		}
-	}
-	return false
+func (s *webSocketServiceImpl) dialControl(_, address string, _ syscall.RawConn) error {
+	return checkPrivateDial(s.requiredHosts, address)
 }
 
 // matchHostPattern matches a host against a pattern.
diff --git a/plugins/host_websocket_test.go b/plugins/host_websocket_test.go
index 9f2d20bef..772d83cc9 100644
--- a/plugins/host_websocket_test.go
+++ b/plugins/host_websocket_test.go
@@ -8,6 +8,7 @@ import (
 	"maps"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -499,6 +500,50 @@ var _ = Describe("WebSocketService", Ordered, func() {
 		})
 	})
 
+	Describe("Private address protection", func() {
+		var wsServer *httptest.Server
+		var savedHosts []string
+
+		BeforeEach(func() {
+			savedHosts = testService.requiredHosts
+			upgrader := websocket.Upgrader{CheckOrigin: func(r *http.Request) bool { return true }}
+			wsServer = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if conn, err := upgrader.Upgrade(w, r, nil); err == nil {
+					_, _, _ = conn.ReadMessage()
+				}
+			}))
+		})
+
+		AfterEach(func() {
+			testService.closeAllConnections()
+			testService.requiredHosts = savedHosts
+			wsServer.Close()
+		})
+
+		serverPort := func() string {
+			u, _ := url.Parse(wsServer.URL)
+			return u.Port()
+		}
+
+		It("blocks an allowlisted hostname that resolves to loopback", func() {
+			testService.requiredHosts = []string{"localhost."}
+			_, err := testService.Connect(GinkgoT().Context(), "ws://localhost.:"+serverPort(), nil, "")
+			Expect(err).To(MatchError(ContainSubstring("private/loopback")))
+		})
+
+		It("allows loopback when a CIDR entry covers it", func() {
+			testService.requiredHosts = []string{"127.0.0.0/8"}
+			_, err := testService.Connect(GinkgoT().Context(), "ws://127.0.0.1:"+serverPort(), nil, "")
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("allows loopback when the allowlist is the bare '*' wildcard", func() {
+			testService.requiredHosts = []string{"*"}
+			_, err := testService.Connect(GinkgoT().Context(), "ws://localhost.:"+serverPort(), nil, "")
+			Expect(err).ToNot(HaveOccurred())
+		})
+	})
+
 	Describe("Plugin Unload", func() {
 		It("should close all connections when plugin is unloaded", func() {
 			// Create a fresh server for this test

From 1072e9f7eb27faef740df5f0bd7fb18898aa650e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 12 Sep 2026 13:59:46 -0400
Subject: [PATCH 139/200] chore(plugins): document requiredHosts rules and
 deprecate pdk.NewHTTPRequest (#6129)

* fix(plugins): align the Python HTTP example with the repo's host-call pattern

Bind http_send with raw memory offsets like nowplaying-py does, drop
guards for fields the host always sends, and document how plugins
without a PDK call host services and which built-in HTTP APIs are
disabled.

* docs(plugins): document the private-address rules for HTTP requiredHosts

Explain in the README and manifest schema that named hosts can't reach
private addresses while IP/CIDR entries and a bare "*" can.

* docs(plugins): document the private-address rules for requiredHosts

Explain in the README and manifest schema that named hosts can't reach
private addresses while IP/CIDR entries and a bare "*" can, for both
HTTP and WebSocket. Inline the single-use HTTP isHostAllowed wrapper.

* feat(plugins): derive Default for Rust host service structs

The ndpgen client.rs template now adds Default to the derive list of host
service structs, as the capability and shared types templates already do.
Plugin authors can now set only the fields they need, for example
HTTPRequest { method, url, ..Default::default() }. The webhook-rs and
discord-rich-presence-rs examples use this form now. The golden files and
the generated nd-pdk-host crate are updated to match.

* feat(plugins): deprecate pdk.NewHTTPRequest in the Go PDK

Navidrome no longer enables extism's http_request host function, so a
request built with pdk.NewHTTPRequest always fails. ndpgen now reads a small
deprecation table and writes a Deprecated: paragraph for the listed extism
functions, in both the WASM wrapper and the native stub. Linters and IDEs
now point plugin authors to host.HTTPSend. The PDK example tests used to
teach NewHTTPRequest. They now use host.HTTPSend and host.HTTPMock.

* docs(plugins): correct requiredHosts rules for websocket and private addresses

Two statements in the plugin docs did not match the code.

The WebSocket section claimed requiredHosts behaves like HTTP. It does not:
host_httpclient.go only consults the allowlist when the list is non-empty and
otherwise falls back to allowing public addresses, while host_websocket.go
always calls isHostInAllowlist, so an absent list blocks every connection.

The HTTP section claimed a named host can never reach a private address.
checkPrivateDial scans the whole requiredHosts list, so a named host does
reach a private address when the same list also holds a covering IP or CIDR.

Reworded both, plus the matching requiredHosts descriptions in
manifest-schema.json, and regenerated manifest_gen.go.
---
 plugins/README.md                             |   8 +-
 plugins/cmd/ndpgen/internal/generator_test.go |  27 +++++
 plugins/cmd/ndpgen/internal/pdk_parser.go     |   7 ++
 .../ndpgen/internal/templates/client.rs.tmpl  |   2 +-
 .../cmd/ndpgen/internal/templates/pdk.go.tmpl |   4 +
 .../internal/templates/pdk_stub.go.tmpl       |   4 +
 .../testdata/comprehensive_client_expected.rs |   4 +-
 .../ndpgen/testdata/list_client_expected.rs   |   2 +-
 .../ndpgen/testdata/search_client_expected.rs |   2 +-
 .../ndpgen/testdata/store_client_expected.rs  |   2 +-
 .../ndpgen/testdata/users_client_expected.rs  |   2 +-
 .../coverartarchive-py/plugin/__init__.py     |  10 +-
 .../discord-rich-presence-rs/src/rpc.rs       |   3 +-
 plugins/examples/webhook-rs/src/lib.rs        |   5 +-
 plugins/host_httpclient.go                    |   6 +-
 plugins/host_netguard.go                      |   3 +-
 plugins/manifest-schema.json                  |   4 +-
 plugins/manifest_gen.go                       |   7 +-
 plugins/pdk/go/pdk/example_test.go            | 100 ++++++++----------
 plugins/pdk/go/pdk/pdk.go                     |   2 +
 plugins/pdk/go/pdk/pdk_stub.go                |   2 +
 .../pdk/rust/nd-pdk-host/src/nd_host_http.rs  |   4 +-
 .../rust/nd-pdk-host/src/nd_host_library.rs   |   2 +-
 .../rust/nd-pdk-host/src/nd_host_matcher.rs   |   2 +-
 .../src/nd_host_scrobbleretriever.rs          |   6 +-
 .../pdk/rust/nd-pdk-host/src/nd_host_task.rs  |   4 +-
 .../pdk/rust/nd-pdk-host/src/nd_host_users.rs |   2 +-
 27 files changed, 132 insertions(+), 94 deletions(-)

diff --git a/plugins/README.md b/plugins/README.md
index 10eb34fbc..7dca3a5f2 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -401,7 +401,7 @@ import "github.com/navidrome/navidrome/plugins/pdk/go/host"
 
 ### HTTP
 
-Make HTTP requests to external services, with timeouts, redirect control, and protection against reaching private network addresses. This is the only supported way to make HTTP requests: Extism's built-in HTTP (`pdk.NewHTTPRequest`) is disabled.
+Make HTTP requests to external services, with timeouts, redirect control, and protection against reaching private network addresses. This is the only supported way to make HTTP requests: Extism's built-in HTTP is disabled (`pdk.NewHTTPRequest` in Go, `http::request` in Rust, `extism.Http.request` in Python, `Http.request` in JS).
 
 **Manifest permission:**
 
@@ -416,6 +416,8 @@ Make HTTP requests to external services, with timeouts, redirect control, and pr
 }
 ```
 
+**Private addresses:** the check runs on the resolved IP when connecting. A named host entry (`api.example.com`, `*.example.com`) never authorizes a loopback, private or link-local address on its own, even if its DNS points there. To reach a service on the local network, also list its IP or a CIDR (`192.168.1.10`, `10.0.0.0/8`), or use `"*"` when the user configures the address. Without `requiredHosts`, only public addresses are allowed.
+
 **Host functions:**
 
 | Function    | Parameters                                               | Returns                          |
@@ -700,6 +702,8 @@ Establish persistent WebSocket connections to external services. Your plugin mus
 }
 ```
 
+`requiredHosts` is mandatory here: leave it out and every connection is blocked. Unlike HTTP, there is no fallback to public addresses. Entries follow the same [private address rules](#http).
+
 **Host functions:**
 
 | Function                   | Parameters                      | Description       |
@@ -1242,6 +1246,8 @@ extism-py plugin.wasm -o plugin.wasm *.py
 zip -j my-plugin.ndp manifest.json plugin.wasm
 ```
 
+There is no Python PDK, so call host services directly: import them from the `extism:host/user` namespace (e.g. `http_send`) with `@extism.import_fn`, and exchange JSON through Extism memory. Each function takes a JSON request and returns a JSON response with an `error` field on failure. For HTTP, send `{"request": {"method": "GET", "url": "..."}}` and read `result.statusCode` and `result.body` (base64). See [coverartarchive-py](examples/coverartarchive-py/) and [nowplaying-py](examples/nowplaying-py/).
+
 ### Using XTP CLI (Scaffolding)
 
 Bootstrap a new plugin from a schema:
diff --git a/plugins/cmd/ndpgen/internal/generator_test.go b/plugins/cmd/ndpgen/internal/generator_test.go
index ea94c7fc6..555906489 100644
--- a/plugins/cmd/ndpgen/internal/generator_test.go
+++ b/plugins/cmd/ndpgen/internal/generator_test.go
@@ -1790,6 +1790,33 @@ var _ = Describe("Rust Generation", func() {
 				Expect(codeStr).NotTo(ContainSubstring("return args.Get(0).(*HTTPRequest)"))
 			})
 		})
+
+		Describe("Deprecated PDK functions", func() {
+			symbols := &PDKSymbols{
+				Functions: []PDKFunc{
+					{
+						Name:       "NewHTTPRequest",
+						Doc:        "NewHTTPRequest returns a new `HTTPRequest`.",
+						Params:     []PDKParam{{Name: "method", Type: "HTTPMethod"}, {Name: "url", Type: "string"}},
+						Returns:    []PDKReturn{{Type: "*HTTPRequest"}},
+						Deprecated: "Use host.HTTPSend instead.",
+					},
+				},
+			}
+
+			DescribeTable("emits a Deprecated paragraph after the doc line",
+				func(generate func(*PDKSymbols) ([]byte, error)) {
+					code, err := generate(symbols)
+					Expect(err).NotTo(HaveOccurred())
+					_, err = format.Source(code)
+					Expect(err).NotTo(HaveOccurred())
+					Expect(string(code)).To(ContainSubstring(
+						"// NewHTTPRequest NewHTTPRequest returns a new `HTTPRequest`.\n//\n// Deprecated: Use host.HTTPSend instead.\nfunc NewHTTPRequest("))
+				},
+				Entry("WASM wrapper", GeneratePDKGo),
+				Entry("native stub", GeneratePDKGoStub),
+			)
+		})
 	})
 })
 
diff --git a/plugins/cmd/ndpgen/internal/pdk_parser.go b/plugins/cmd/ndpgen/internal/pdk_parser.go
index 4756334dd..7607fe881 100644
--- a/plugins/cmd/ndpgen/internal/pdk_parser.go
+++ b/plugins/cmd/ndpgen/internal/pdk_parser.go
@@ -50,6 +50,12 @@ type PDKFunc struct {
 	Params     []PDKParam
 	Returns    []PDKReturn
 	IsVariadic bool
+	Deprecated string // Rendered as a "Deprecated:" paragraph when set
+}
+
+// deprecatedPDKFuncs marks extism functions that do not work inside Navidrome, with what to use instead.
+var deprecatedPDKFuncs = map[string]string{
+	"NewHTTPRequest": "Navidrome does not enable extism's http_request host function, so every request sent this way fails. Use host.HTTPSend instead.",
 }
 
 // PDKParam represents a function parameter.
@@ -156,6 +162,7 @@ func ParseExtismPDK() (*PDKSymbols, error) {
 						t.Methods = append(t.Methods, fn)
 					}
 				} else {
+					fn.Deprecated = deprecatedPDKFuncs[fn.Name]
 					symbols.Functions = append(symbols.Functions, fn)
 				}
 			}
diff --git a/plugins/cmd/ndpgen/internal/templates/client.rs.tmpl b/plugins/cmd/ndpgen/internal/templates/client.rs.tmpl
index f8b786849..786a50db5 100644
--- a/plugins/cmd/ndpgen/internal/templates/client.rs.tmpl
+++ b/plugins/cmd/ndpgen/internal/templates/client.rs.tmpl
@@ -11,7 +11,7 @@ use serde::{Deserialize, Serialize};
 {{if .Doc}}
 {{rustDocComment .Doc}}
 {{else}}
-{{end}}#[derive(Debug, Clone, Serialize, Deserialize)]
+{{end}}#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct {{.Name}} {
 {{- range .Fields}}
diff --git a/plugins/cmd/ndpgen/internal/templates/pdk.go.tmpl b/plugins/cmd/ndpgen/internal/templates/pdk.go.tmpl
index ebaf88df0..117bd9232 100644
--- a/plugins/cmd/ndpgen/internal/templates/pdk.go.tmpl
+++ b/plugins/cmd/ndpgen/internal/templates/pdk.go.tmpl
@@ -40,6 +40,10 @@ const (
 {{- if .Doc}}
 // {{.Name}} {{firstSentence .Doc}}
 {{- end}}
+{{- if .Deprecated}}
+//
+// Deprecated: {{.Deprecated}}
+{{- end}}
 func {{.Name}}({{paramList .Params}}){{returnList .Returns}} {
 {{- if .Returns}}
 	return extism.{{.Name}}({{argList .Params}})
diff --git a/plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl b/plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl
index 2bd73f107..27d06faa0 100644
--- a/plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl
+++ b/plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl
@@ -31,6 +31,10 @@ func ResetMock() {
 {{- if .Doc}}
 // {{.Name}} {{firstSentence .Doc}}
 {{- end}}
+{{- if .Deprecated}}
+//
+// Deprecated: {{.Deprecated}}
+{{- end}}
 func {{.Name}}({{paramList .Params}}){{returnList .Returns}} {
 {{- if .Returns}}
 	args := PDKMock.Called({{argList .Params}})
diff --git a/plugins/cmd/ndpgen/testdata/comprehensive_client_expected.rs b/plugins/cmd/ndpgen/testdata/comprehensive_client_expected.rs
index 08dae2901..1bd953640 100644
--- a/plugins/cmd/ndpgen/testdata/comprehensive_client_expected.rs
+++ b/plugins/cmd/ndpgen/testdata/comprehensive_client_expected.rs
@@ -29,14 +29,14 @@ mod base64_bytes {
     }
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct User2 {
     pub id: String,
     pub name: String,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Filter2 {
     pub active: bool,
diff --git a/plugins/cmd/ndpgen/testdata/list_client_expected.rs b/plugins/cmd/ndpgen/testdata/list_client_expected.rs
index 9b54f7544..5227cadf4 100644
--- a/plugins/cmd/ndpgen/testdata/list_client_expected.rs
+++ b/plugins/cmd/ndpgen/testdata/list_client_expected.rs
@@ -6,7 +6,7 @@
 use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Filter {
     pub active: bool,
diff --git a/plugins/cmd/ndpgen/testdata/search_client_expected.rs b/plugins/cmd/ndpgen/testdata/search_client_expected.rs
index b0ab2505a..396a22b4e 100644
--- a/plugins/cmd/ndpgen/testdata/search_client_expected.rs
+++ b/plugins/cmd/ndpgen/testdata/search_client_expected.rs
@@ -6,7 +6,7 @@
 use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Result {
     pub id: String,
diff --git a/plugins/cmd/ndpgen/testdata/store_client_expected.rs b/plugins/cmd/ndpgen/testdata/store_client_expected.rs
index 25d2af2e0..3b9d5ac17 100644
--- a/plugins/cmd/ndpgen/testdata/store_client_expected.rs
+++ b/plugins/cmd/ndpgen/testdata/store_client_expected.rs
@@ -6,7 +6,7 @@
 use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Item {
     pub id: String,
diff --git a/plugins/cmd/ndpgen/testdata/users_client_expected.rs b/plugins/cmd/ndpgen/testdata/users_client_expected.rs
index 40daa9cfd..4bac43ce8 100644
--- a/plugins/cmd/ndpgen/testdata/users_client_expected.rs
+++ b/plugins/cmd/ndpgen/testdata/users_client_expected.rs
@@ -6,7 +6,7 @@
 use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct User {
     pub id: String,
diff --git a/plugins/examples/coverartarchive-py/plugin/__init__.py b/plugins/examples/coverartarchive-py/plugin/__init__.py
index e6f4c6a07..c4a0480b5 100644
--- a/plugins/examples/coverartarchive-py/plugin/__init__.py
+++ b/plugins/examples/coverartarchive-py/plugin/__init__.py
@@ -12,16 +12,18 @@ import json
 
 
 @extism.import_fn("extism:host/user", "http_send")
-def http_send(req: dict) -> dict: ...
+def _http_send(offset: int) -> int: ...
 
 
 def http_get(url):
     """GET url via Navidrome's HTTP host service. Returns (status_code, body_bytes)."""
-    resp = http_send({"request": {"method": "GET", "url": url}})
+    request = json.dumps({"request": {"method": "GET", "url": url}}).encode("utf-8")
+    response_offset = _http_send(extism.memory.alloc(request).offset)
+    resp = json.loads(extism.memory.string(extism.memory.find(response_offset)))
     if resp.get("error"):
         raise Exception(f"HTTP request failed: {resp['error']}")
-    result = resp.get("result") or {}
-    return result.get("statusCode", 0), base64.b64decode(result.get("body") or "")
+    result = resp["result"]
+    return result["statusCode"], base64.b64decode(result.get("body", ""))
 
 
 @extism.plugin_fn
diff --git a/plugins/examples/discord-rich-presence-rs/src/rpc.rs b/plugins/examples/discord-rich-presence-rs/src/rpc.rs
index d90cb4341..fa72f7466 100644
--- a/plugins/examples/discord-rich-presence-rs/src/rpc.rs
+++ b/plugins/examples/discord-rich-presence-rs/src/rpc.rs
@@ -369,9 +369,8 @@ fn send_http(
         method: method.into(),
         url: url.into(),
         headers,
-        no_follow_redirects: false,
         body,
-        timeout_ms: 0,
+        ..Default::default()
     })?
     .ok_or_else(|| Error::msg("empty HTTP response"))
 }
diff --git a/plugins/examples/webhook-rs/src/lib.rs b/plugins/examples/webhook-rs/src/lib.rs
index 794cda59c..5f5d972a0 100644
--- a/plugins/examples/webhook-rs/src/lib.rs
+++ b/plugins/examples/webhook-rs/src/lib.rs
@@ -94,10 +94,7 @@ impl Scrobbler for WebhookPlugin {
             let http_req = HTTPRequest {
                 method: "GET".into(),
                 url: full_url,
-                headers: Default::default(),
-                no_follow_redirects: false,
-                body: Vec::new(),
-                timeout_ms: 0,
+                ..Default::default()
             };
             match http::send(http_req) {
                 Ok(res) => {
diff --git a/plugins/host_httpclient.go b/plugins/host_httpclient.go
index 209f80eb0..54875ae8a 100644
--- a/plugins/host_httpclient.go
+++ b/plugins/host_httpclient.go
@@ -159,7 +159,7 @@ func (s *httpServiceImpl) validateHost(ctx context.Context, hostStr string) erro
 	hostname := extractHostname(hostStr)
 
 	if len(s.requiredHosts) > 0 {
-		if !s.isHostAllowed(hostname) {
+		if !isHostInAllowlist(s.requiredHosts, hostname) {
 			return fmt.Errorf("host %q is not allowed", hostStr)
 		}
 		return nil
@@ -177,10 +177,6 @@ func (s *httpServiceImpl) dialControl(_, address string, _ syscall.RawConn) erro
 	return checkPrivateDial(s.requiredHosts, address)
 }
 
-func (s *httpServiceImpl) isHostAllowed(hostname string) bool {
-	return isHostInAllowlist(s.requiredHosts, hostname)
-}
-
 // extractHostname returns the hostname portion of a host string, stripping
 // any port number and IPv6 brackets. It handles IPv6 addresses correctly
 // (e.g. "[::1]:8080" → "::1", "[::1]" → "::1").
diff --git a/plugins/host_netguard.go b/plugins/host_netguard.go
index 8400446ed..2244fed1f 100644
--- a/plugins/host_netguard.go
+++ b/plugins/host_netguard.go
@@ -41,8 +41,7 @@ func isHostInAllowlist(requiredHosts []string, hostname string) bool {
 	return false
 }
 
-// ipMatchesEntry reports whether a requiredHosts entry is a literal IP or CIDR
-// that covers ip. Hostname and wildcard entries never match.
+// ipMatchesEntry reports whether a requiredHosts entry is a literal IP or CIDR that covers ip.
 func ipMatchesEntry(entry string, ip net.IP) bool {
 	if _, cidr, err := net.ParseCIDR(entry); err == nil {
 		return cidr.Contains(ip)
diff --git a/plugins/manifest-schema.json b/plugins/manifest-schema.json
index dae0fd937..056a1caed 100644
--- a/plugins/manifest-schema.json
+++ b/plugins/manifest-schema.json
@@ -134,7 +134,7 @@
         },
         "requiredHosts": {
           "type": "array",
-          "description": "List of required host patterns for HTTP requests (e.g., 'api.example.com', '*.musicbrainz.org')",
+          "description": "List of required host patterns for HTTP requests (e.g., 'api.example.com', '*.musicbrainz.org'). A named host alone can't reach a private address; also list an IP, a CIDR (e.g., '10.0.0.0/8') or '*' for that",
           "items": {
             "type": "string"
           }
@@ -174,7 +174,7 @@
         },
         "requiredHosts": {
           "type": "array",
-          "description": "List of required host patterns for WebSocket connections (e.g., 'api.example.com', '*.musicbrainz.org')",
+          "description": "List of required host patterns for WebSocket connections (e.g., 'api.example.com', '*.musicbrainz.org'). Required: with no entries every connection is blocked. A named host alone can't reach a private address; also list an IP, a CIDR (e.g., '10.0.0.0/8') or '*' for that",
           "items": {
             "type": "string"
           }
diff --git a/plugins/manifest_gen.go b/plugins/manifest_gen.go
index 6f5c01596..b5e9afd96 100644
--- a/plugins/manifest_gen.go
+++ b/plugins/manifest_gen.go
@@ -51,7 +51,8 @@ type HTTPPermission struct {
 	Reason *string `json:"reason,omitempty" yaml:"reason,omitempty" mapstructure:"reason,omitempty"`
 
 	// List of required host patterns for HTTP requests (e.g., 'api.example.com',
-	// '*.musicbrainz.org')
+	// '*.musicbrainz.org'). A named host alone can't reach a private address; also
+	// list an IP, a CIDR (e.g., '10.0.0.0/8') or '*' for that
 	RequiredHosts []string `json:"requiredHosts,omitempty" yaml:"requiredHosts,omitempty" mapstructure:"requiredHosts,omitempty"`
 }
 
@@ -264,6 +265,8 @@ type WebSocketPermission struct {
 	Reason *string `json:"reason,omitempty" yaml:"reason,omitempty" mapstructure:"reason,omitempty"`
 
 	// List of required host patterns for WebSocket connections (e.g.,
-	// 'api.example.com', '*.musicbrainz.org')
+	// 'api.example.com', '*.musicbrainz.org'). Required: with no entries every
+	// connection is blocked. A named host alone can't reach a private address; also
+	// list an IP, a CIDR (e.g., '10.0.0.0/8') or '*' for that
 	RequiredHosts []string `json:"requiredHosts,omitempty" yaml:"requiredHosts,omitempty" mapstructure:"requiredHosts,omitempty"`
 }
diff --git a/plugins/pdk/go/pdk/example_test.go b/plugins/pdk/go/pdk/example_test.go
index 5678bddd4..bf98eba2f 100644
--- a/plugins/pdk/go/pdk/example_test.go
+++ b/plugins/pdk/go/pdk/example_test.go
@@ -8,6 +8,7 @@ package pdk_test
 import (
 	"testing"
 
+	"github.com/navidrome/navidrome/plugins/pdk/go/host"
 	"github.com/navidrome/navidrome/plugins/pdk/go/pdk"
 	"github.com/stretchr/testify/mock"
 )
@@ -136,48 +137,39 @@ func TestProcessJSONRequest(t *testing.T) {
 }
 
 // =============================================================================
-// Examples using stub types (Memory, HTTPRequest, HTTPResponse)
+// HTTP requests go through the host HTTP service (host.HTTPSend), not
+// pdk.NewHTTPRequest, which Navidrome does not enable.
 // =============================================================================
 
 // FetchData demonstrates a plugin function that makes an HTTP request.
 func FetchData(url string) ([]byte, error) {
-	// Create and configure the HTTP request
-	// Note: SetHeader and SetBody work directly on the stub - no mocking needed!
-	req := pdk.NewHTTPRequest(pdk.MethodGet, url)
-	req.SetHeader("Accept", "application/json")
-	req.SetHeader("User-Agent", "MyPlugin/1.0")
-
-	// Send the request - this is mocked because it requires host interaction
-	resp := req.Send()
-
-	// Check status - works directly on the stub
-	if resp.Status() != 200 {
-		return nil, nil
+	resp, err := host.HTTPSend(host.HTTPRequest{
+		Method: "GET",
+		URL:    url,
+		Headers: map[string]string{
+			"Accept":     "application/json",
+			"User-Agent": "MyPlugin/1.0",
+		},
+	})
+	if err != nil {
+		return nil, err
 	}
 
-	// Return body - works directly on the stub
-	return resp.Body(), nil
+	if resp.StatusCode != 200 {
+		return nil, nil
+	}
+	return resp.Body, nil
 }
 
 func TestFetchData(t *testing.T) {
-	pdk.ResetMock()
+	host.HTTPMock.ExpectedCalls = nil
 
-	// Create a stub response with test data
 	expectedBody := []byte(`{"result": "success"}`)
-	stubResponse := pdk.NewStubHTTPResponse(200, map[string]string{
-		"Content-Type": "application/json",
-	}, expectedBody)
+	host.HTTPMock.On("Send", mock.MatchedBy(func(req host.HTTPRequest) bool {
+		return req.Method == "GET" && req.URL == "https://api.example.com/data" &&
+			req.Headers["Accept"] == "application/json"
+	})).Return(&host.HTTPResponse{StatusCode: 200, Body: expectedBody}, nil)
 
-	// Mock NewHTTPRequest to return a real HTTPRequest struct
-	// The struct methods (SetHeader, SetBody) work without mocking
-	pdk.PDKMock.On("NewHTTPRequest", pdk.MethodGet, "https://api.example.com/data").
-		Return(&pdk.HTTPRequest{})
-
-	// Mock Send to return our stub response
-	pdk.PDKMock.On("Send", mock.AnythingOfType("*pdk.HTTPRequest")).
-		Return(stubResponse)
-
-	// Call the function
 	body, err := FetchData("https://api.example.com/data")
 
 	if err != nil {
@@ -188,21 +180,15 @@ func TestFetchData(t *testing.T) {
 		t.Errorf("expected body %q, got %q", expectedBody, body)
 	}
 
-	pdk.PDKMock.AssertExpectations(t)
+	host.HTTPMock.AssertExpectations(t)
 }
 
 func TestFetchData_NonOKStatus(t *testing.T) {
-	pdk.ResetMock()
+	host.HTTPMock.ExpectedCalls = nil
 
-	// Create a stub response with 404 status
-	stubResponse := pdk.NewStubHTTPResponse(404, nil, []byte("Not Found"))
+	host.HTTPMock.On("Send", mock.Anything).
+		Return(&host.HTTPResponse{StatusCode: 404, Body: []byte("Not Found")}, nil)
 
-	pdk.PDKMock.On("NewHTTPRequest", pdk.MethodGet, "https://api.example.com/missing").
-		Return(&pdk.HTTPRequest{})
-	pdk.PDKMock.On("Send", mock.AnythingOfType("*pdk.HTTPRequest")).
-		Return(stubResponse)
-
-	// Call the function
 	body, err := FetchData("https://api.example.com/missing")
 
 	if err != nil {
@@ -214,7 +200,7 @@ func TestFetchData_NonOKStatus(t *testing.T) {
 		t.Errorf("expected nil body for 404, got %q", body)
 	}
 
-	pdk.PDKMock.AssertExpectations(t)
+	host.HTTPMock.AssertExpectations(t)
 }
 
 // ProcessMemoryData demonstrates working with Memory type.
@@ -292,23 +278,27 @@ func TestHTTPMethodString(t *testing.T) {
 
 // PostJSON demonstrates a more complex HTTP request with body.
 func PostJSON(url string, data []byte) (int, error) {
-	req := pdk.NewHTTPRequest(pdk.MethodPost, url)
-	req.SetHeader("Content-Type", "application/json")
-	req.SetBody(data) // Works directly on stub
-
-	resp := req.Send() // This is mocked
-	return int(resp.Status()), nil
+	resp, err := host.HTTPSend(host.HTTPRequest{
+		Method:  "POST",
+		URL:     url,
+		Headers: map[string]string{"Content-Type": "application/json"},
+		Body:    data,
+	})
+	if err != nil {
+		return 0, err
+	}
+	return int(resp.StatusCode), nil
 }
 
 func TestPostJSON(t *testing.T) {
-	pdk.ResetMock()
+	host.HTTPMock.ExpectedCalls = nil
 
-	stubResponse := pdk.NewStubHTTPResponse(201, nil, nil)
-
-	pdk.PDKMock.On("NewHTTPRequest", pdk.MethodPost, "https://api.example.com/items").
-		Return(&pdk.HTTPRequest{})
-	pdk.PDKMock.On("Send", mock.AnythingOfType("*pdk.HTTPRequest")).
-		Return(stubResponse)
+	host.HTTPMock.On("Send", host.HTTPRequest{
+		Method:  "POST",
+		URL:     "https://api.example.com/items",
+		Headers: map[string]string{"Content-Type": "application/json"},
+		Body:    []byte(`{"name":"test"}`),
+	}).Return(&host.HTTPResponse{StatusCode: 201}, nil)
 
 	status, err := PostJSON("https://api.example.com/items", []byte(`{"name":"test"}`))
 
@@ -320,5 +310,5 @@ func TestPostJSON(t *testing.T) {
 		t.Errorf("expected status 201, got %d", status)
 	}
 
-	pdk.PDKMock.AssertExpectations(t)
+	host.HTTPMock.AssertExpectations(t)
 }
diff --git a/plugins/pdk/go/pdk/pdk.go b/plugins/pdk/go/pdk/pdk.go
index 35394d700..456a238f5 100644
--- a/plugins/pdk/go/pdk/pdk.go
+++ b/plugins/pdk/go/pdk/pdk.go
@@ -111,6 +111,8 @@ func LogMemory(level LogLevel, m Memory) {
 }
 
 // NewHTTPRequest NewHTTPRequest returns a new `HTTPRequest`.
+//
+// Deprecated: Navidrome does not enable extism's http_request host function, so every request sent this way fails. Use host.HTTPSend instead.
 func NewHTTPRequest(method HTTPMethod, url string) *HTTPRequest {
 	return extism.NewHTTPRequest(method, url)
 }
diff --git a/plugins/pdk/go/pdk/pdk_stub.go b/plugins/pdk/go/pdk/pdk_stub.go
index 8f2707d56..1a685eecc 100644
--- a/plugins/pdk/go/pdk/pdk_stub.go
+++ b/plugins/pdk/go/pdk/pdk_stub.go
@@ -114,6 +114,8 @@ func LogMemory(level LogLevel, m Memory) {
 }
 
 // NewHTTPRequest NewHTTPRequest returns a new `HTTPRequest`.
+//
+// Deprecated: Navidrome does not enable extism's http_request host function, so every request sent this way fails. Use host.HTTPSend instead.
 func NewHTTPRequest(method HTTPMethod, url string) *HTTPRequest {
 	args := PDKMock.Called(method, url)
 	var r0 *HTTPRequest
diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_http.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_http.rs
index 1c44cd2f3..f1607112c 100644
--- a/plugins/pdk/rust/nd-pdk-host/src/nd_host_http.rs
+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_http.rs
@@ -30,7 +30,7 @@ mod base64_bytes {
 }
 
 /// HTTPRequest represents an outbound HTTP request from a plugin.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct HTTPRequest {
     pub method: String,
@@ -47,7 +47,7 @@ pub struct HTTPRequest {
 }
 
 /// HTTPResponse represents the response from an outbound HTTP request.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct HTTPResponse {
     pub status_code: i32,
diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_library.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_library.rs
index b4b9b3fb0..966c1607f 100644
--- a/plugins/pdk/rust/nd-pdk-host/src/nd_host_library.rs
+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_library.rs
@@ -7,7 +7,7 @@ use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
 /// Library represents a music library with metadata.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Library {
     pub id: i32,
diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_matcher.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_matcher.rs
index be2819257..7fdf88b7f 100644
--- a/plugins/pdk/rust/nd-pdk-host/src/nd_host_matcher.rs
+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_matcher.rs
@@ -7,7 +7,7 @@ use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
 /// MatchOptions carries optional parameters for a match request.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MatchOptions {
     #[serde(default)]
diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs
index fe80d98f6..19010924a 100644
--- a/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs
+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_scrobbleretriever.rs
@@ -7,7 +7,7 @@ use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
 /// ScrobbleCountOptions carries optional parameters for counting user scrobbles
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ScrobbleCountOptions {
     #[serde(default)]
@@ -17,7 +17,7 @@ pub struct ScrobbleCountOptions {
 }
 
 /// ScrobbleOptions carries optional parameters for retrieving user scrobbles
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ScrobbleOptions {
     #[serde(default)]
@@ -31,7 +31,7 @@ pub struct ScrobbleOptions {
 }
 
 /// ScrobbleRef represents one instance of a scrobble (instance id, file id, submission time)
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ScrobbleRef {
     pub id: i64,
diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_task.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_task.rs
index 4f43e165c..ac82fdd08 100644
--- a/plugins/pdk/rust/nd-pdk-host/src/nd_host_task.rs
+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_task.rs
@@ -30,7 +30,7 @@ mod base64_bytes {
 }
 
 /// QueueConfig holds configuration for a task queue.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct QueueConfig {
     pub concurrency: i32,
@@ -41,7 +41,7 @@ pub struct QueueConfig {
 }
 
 /// TaskInfo holds the current state of a task.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TaskInfo {
     pub status: String,
diff --git a/plugins/pdk/rust/nd-pdk-host/src/nd_host_users.rs b/plugins/pdk/rust/nd-pdk-host/src/nd_host_users.rs
index faa795bb9..b31b39fb4 100644
--- a/plugins/pdk/rust/nd-pdk-host/src/nd_host_users.rs
+++ b/plugins/pdk/rust/nd-pdk-host/src/nd_host_users.rs
@@ -8,7 +8,7 @@ use serde::{Deserialize, Serialize};
 
 /// User represents a Navidrome user with minimal information exposed to plugins.
 /// Sensitive fields like password, email, and internal IDs are intentionally excluded.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct User {
     pub user_name: String,

From d00c84716bbc123b5cf0631879909480ea4dfbe7 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sun, 13 Sep 2026 11:03:56 -0400
Subject: [PATCH 140/200] fix(scanner): update go-taglib to fix permission
 denied on shared hosts

The go-taglib WASM compilation cache lived in a shared $TMPDIR/go-taglib-wasm
directory, created with 0700 by whichever user ran first. A second Navidrome
instance running as another user on the same machine failed to read every
file with "permission denied", so its scan found no files.

The updated fork uses a per-user cache directory (go-taglib-wasm-<uid>) and
falls back to running without the cache when it cannot be created or used.
---
 go.mod | 2 +-
 go.sum | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/go.mod b/go.mod
index 1a73328f3..32db6ab1f 100644
--- a/go.mod
+++ b/go.mod
@@ -3,7 +3,7 @@ module github.com/navidrome/navidrome
 go 1.27
 
 // Fork to implement raw tags support
-replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260910183509-2ca9506dd7ec
+replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260913142955-d55e0c9353cb
 
 require (
 	github.com/Masterminds/squirrel v1.5.4
diff --git a/go.sum b/go.sum
index 42e1505e9..5ed48d77a 100644
--- a/go.sum
+++ b/go.sum
@@ -29,8 +29,8 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
-github.com/deluan/go-taglib v0.0.0-20260910183509-2ca9506dd7ec h1:3VyOFsbsRtCQqdq/+fcmD3D6zlRvKSG7RCixgrdWfEo=
-github.com/deluan/go-taglib v0.0.0-20260910183509-2ca9506dd7ec/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
+github.com/deluan/go-taglib v0.0.0-20260913142955-d55e0c9353cb h1:CGVY6RtDsqaleUFogGP03m3a/9OKi3ZMDr5nhm51Emk=
+github.com/deluan/go-taglib v0.0.0-20260913142955-d55e0c9353cb/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcHCKTtwzrd0HGfEmoODFA/qnk4=
 github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf/go.mod h1:tSgDythFsl0QgS/PFWfIZqcJKnkADWneY80jaVRlqK8=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55 h1:wSCnggTs2f2ji6nFwQmfwgINcmSMj0xF0oHnoyRSPe4=

From dd71f1c57f772f750cf046d8ff5897ef804a31de Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sun, 13 Sep 2026 20:52:39 -0400
Subject: [PATCH 141/200] chore(release): fix PikaPods link and replace Danian
 with Zenith

The release notes footer pointed to an outdated PikaPods URL and still
listed Danian as a hosting option. Use the PikaPods run URL and Zenith,
matching the links already used in the published v0.64.0 release notes.
---
 release/goreleaser.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/release/goreleaser.yml b/release/goreleaser.yml
index 103f2beaf..e7610f25e 100644
--- a/release/goreleaser.yml
+++ b/release/goreleaser.yml
@@ -114,7 +114,7 @@ release:
     ## Where to go next?
 
     * Read installation instructions on our [website](https://www.navidrome.org/docs/installation/).
-    * Host Navidrome on [PikaPods](https://www.pikapods.com/pods/navidrome) or [Danian](https://danian.co/navidrome?nd) for a simple cloud solution.
+    * Host Navidrome on [PikaPods](https://www.pikapods.com/pods?run=navidrome) or [Zenith](https://zenith.hosting/host/navidrome?ref=navidrome) for a simple cloud solution.
     * Reach out on [Discord](https://discord.gg/xh7j7yF), [Reddit](https://www.reddit.com/r/navidrome/) and [Twitter](https://twitter.com/navidrome)!
 
   # Add the MSI installers to the release

From 3f4b6a642cf3f1c5628c900790d2a9fcd7997fad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 14 Sep 2026 22:46:21 -0400
Subject: [PATCH 142/200] fix(server): return 404 instead of 500 for missing
 native API resources (#6131)

* fix: return 404 instead of 500 for missing native API resources

The deluan/rest controller only maps rest.ErrNotFound to 404, comparing with ==.
Most repositories return model.ErrNotFound, which had the same message but was a
different value, so requesting a missing playlist, album, artist, song, radio,
player, transcoding or library returned 500. This also applied to other users'
private playlists.

Make model.ErrNotFound the same value as rest.ErrNotFound. This fixes every REST
route at once, with no per-route wrapping. errors.Is checks against either
error keep working, and nothing wraps model.ErrNotFound before it reaches the
controller.

Fixes #6130

* fix(radio): return not found when deleting a missing radio station

radioRepository.Delete used the shared delete helper, which never reports a
missing row because SQL DELETE on zero rows is not an error. Deleting an unknown
id silently succeeded: DELETE /api/radio/{id} returned 200, and the Subsonic
deleteInternetRadioStation endpoint returned ok.

Delete now checks the affected row count and returns model.ErrNotFound when
nothing was deleted. The native API returns 404, and deleteInternetRadioStation
returns error 70 (data not found). This matches Subsonic 6.1.6, gonic (both
verified live) and Ampache (verified in source). Airsonic-Advanced does not
implement this endpoint.

The shared delete helper is unchanged, as several callers rely on deletes of
absent rows succeeding.

* fix(ui): return 404 for missing files that are not missing or do not exist

missingRepository.Read filtered media files by bare "id" and "missing" columns.
The media file query joins the library table, so SQLite rejected the query as
ambiguous and GET /api/missing/{id} returned 500. Read now loads the file with
MediaFileRepository.Get, which qualifies the column, and returns not found
when the file does not exist or is not marked missing.

* fix: report missing rows on single-item deletes and adopt deluan/rest errors.Is

Bump github.com/deluan/rest to the version whose controller matches errors
with errors.Is and errors.As. model.ErrNotFound stays the same value as
rest.ErrNotFound, so the many hand-written conversions from model.ErrNotFound
to rest.ErrNotFound in repositories, core services and test mocks did nothing.
Remove them, along with the duplicate rest.ErrNotFound check in the Subsonic
error mapper. Mappings from model.ErrNotAuthorized stay, as those are
different errors.

User and transcoding deletes had the same silent success as radio: the shared
delete helper never reports a missing row, so their not-found checks never
fired and DELETE /api/user/{id} and /api/transcoding/{id} returned 200 for
unknown ids. Add deleteByID, which returns model.ErrNotFound when no row
matched, and use it for radio, user and transcoding. Also drop the dead
sql.ErrNoRows branch from delete, since a DELETE never returns it.

The Subsonic deleteUser endpoint is not implemented (501), so this does not
change the Subsonic API. Plugin deletes keep the silent helper: there is no
REST route for them, and the plugin manager only deletes rows it just read.

* chore: drop ErrNotFound comment and its identity test

The alias to rest.ErrNotFound is self-explanatory, and the identity test only
restated the declaration.

* refactor: alias model.ErrNotAuthorized to rest.ErrPermissionDenied

Like ErrNotFound, make model.ErrNotAuthorized the same value as the rest
library's error, so REST endpoints map it to 403 directly. This removes the
ErrNotAuthorized to rest.ErrPermissionDenied mappings in the library and
playlist REST adapters and the duplicate check in the Subsonic error mapper.

Handlers that check model.ErrNotAuthorized now also recognize
rest.ErrPermissionDenied returned by repositories, so writePlaylistError, the
image upload handlers and the public share handler return 403 for it instead
of their fallback status. The error message changes from "not authorized" to
"permission denied".
---
 core/library.go                            | 10 +---
 core/playlists/rest_adapter.go             | 20 +-------
 go.mod                                     |  2 +-
 go.sum                                     |  4 +-
 model/errors.go                            | 10 ++--
 persistence/player_repository.go           |  7 +--
 persistence/playlist_repository.go         |  3 --
 persistence/radio_repository.go            | 12 +----
 persistence/radio_repository_test.go       |  4 ++
 persistence/share_repository.go            |  7 +--
 persistence/sql_base_repository.go         | 16 +++++--
 persistence/transcoding_repository.go      | 16 +------
 persistence/transcoding_repository_test.go |  5 ++
 persistence/user_repository.go             | 18 ++-----
 persistence/user_repository_test.go        |  8 ++++
 server/nativeapi/missing.go                | 10 ++--
 server/nativeapi/missing_test.go           | 56 ++++++++++++++++++++++
 server/nativeapi/playlists_test.go         |  1 +
 server/subsonic/api.go                     |  6 +--
 server/subsonic/e2e/subsonic_radio_test.go |  8 ++++
 tests/mock_library_repo.go                 |  6 +--
 tests/mock_mediafile_repo.go               |  6 +--
 tests/mock_plugin_repo.go                  |  6 +--
 23 files changed, 124 insertions(+), 117 deletions(-)
 create mode 100644 server/nativeapi/missing_test.go

diff --git a/core/library.go b/core/library.go
index d905e00cb..6df0e95b5 100644
--- a/core/library.go
+++ b/core/library.go
@@ -2,7 +2,6 @@ package core
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"io/fs"
 	"os"
@@ -307,14 +306,7 @@ func (r *libraryRepositoryWrapper) mapError(err error) error {
 		}
 	}
 
-	switch {
-	case errors.Is(err, model.ErrNotFound):
-		return rest.ErrNotFound
-	case errors.Is(err, model.ErrNotAuthorized):
-		return rest.ErrPermissionDenied
-	default:
-		return err
-	}
+	return err
 }
 
 func (r *libraryRepositoryWrapper) validateLibrary(library *model.Library) error {
diff --git a/core/playlists/rest_adapter.go b/core/playlists/rest_adapter.go
index ca7cfb0cc..45642c819 100644
--- a/core/playlists/rest_adapter.go
+++ b/core/playlists/rest_adapter.go
@@ -2,7 +2,6 @@ package playlists
 
 import (
 	"context"
-	"errors"
 	"reflect"
 	"strings"
 
@@ -41,15 +40,7 @@ func (r *playlistRepositoryWrapper) Update(id string, entity any, cols ...string
 }
 
 func (r *playlistRepositoryWrapper) Delete(id string) error {
-	err := r.service.Delete(r.ctx, id)
-	switch {
-	case errors.Is(err, model.ErrNotFound):
-		return rest.ErrNotFound
-	case errors.Is(err, model.ErrNotAuthorized):
-		return rest.ErrPermissionDenied
-	default:
-		return err
-	}
+	return r.service.Delete(r.ctx, id)
 }
 
 func (s *playlists) TracksRepository(ctx context.Context, playlistId string, refreshSmartPlaylist bool) rest.Repository {
@@ -92,14 +83,7 @@ func (s *playlists) savePlaylist(ctx context.Context, pls *model.Playlist) (stri
 func (s *playlists) updatePlaylistEntity(ctx context.Context, id string, entity *model.Playlist, cols ...string) error {
 	current, err := s.checkWritable(ctx, id)
 	if err != nil {
-		switch {
-		case errors.Is(err, model.ErrNotFound):
-			return rest.ErrNotFound
-		case errors.Is(err, model.ErrNotAuthorized):
-			return rest.ErrPermissionDenied
-		default:
-			return err
-		}
+		return err
 	}
 
 	sent := sentFields(cols)
diff --git a/go.mod b/go.mod
index 32db6ab1f..9a693d651 100644
--- a/go.mod
+++ b/go.mod
@@ -9,7 +9,7 @@ require (
 	github.com/Masterminds/squirrel v1.5.4
 	github.com/andybalholm/cascadia v1.3.5
 	github.com/bmatcuk/doublestar/v4 v4.10.0
-	github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf
+	github.com/deluan/rest v0.0.0-20260913134927-47b21f30cc12
 	github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55
 	github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36
 	github.com/djherbis/atime v1.1.0
diff --git a/go.sum b/go.sum
index 5ed48d77a..4cda9a2f3 100644
--- a/go.sum
+++ b/go.sum
@@ -31,8 +31,8 @@ github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3h
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
 github.com/deluan/go-taglib v0.0.0-20260913142955-d55e0c9353cb h1:CGVY6RtDsqaleUFogGP03m3a/9OKi3ZMDr5nhm51Emk=
 github.com/deluan/go-taglib v0.0.0-20260913142955-d55e0c9353cb/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
-github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf h1:tb246l2Zmpt/GpF9EcHCKTtwzrd0HGfEmoODFA/qnk4=
-github.com/deluan/rest v0.0.0-20211102003136-6260bc399cbf/go.mod h1:tSgDythFsl0QgS/PFWfIZqcJKnkADWneY80jaVRlqK8=
+github.com/deluan/rest v0.0.0-20260913134927-47b21f30cc12 h1:x4N/tx0XC9zcnipk5rpdI4qaG9JmovHW5HL97XYnO1I=
+github.com/deluan/rest v0.0.0-20260913134927-47b21f30cc12/go.mod h1:tSgDythFsl0QgS/PFWfIZqcJKnkADWneY80jaVRlqK8=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55 h1:wSCnggTs2f2ji6nFwQmfwgINcmSMj0xF0oHnoyRSPe4=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55/go.mod h1:ZNCLJfehvEf34B7BbLKjgpsL9lyW7q938w/GY1XgV4E=
 github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36 h1:KtPfdSST6e0vJbMzMmVqPa5mO1u8vMBlybRCW2ieXpA=
diff --git a/model/errors.go b/model/errors.go
index 9e56f9501..b3f07565f 100644
--- a/model/errors.go
+++ b/model/errors.go
@@ -1,11 +1,15 @@
 package model
 
-import "errors"
+import (
+	"errors"
+
+	"github.com/deluan/rest"
+)
 
 var (
-	ErrNotFound            = errors.New("data not found")
+	ErrNotFound            = rest.ErrNotFound
 	ErrInvalidAuth         = errors.New("invalid authentication")
-	ErrNotAuthorized       = errors.New("not authorized")
+	ErrNotAuthorized       = rest.ErrPermissionDenied
 	ErrExpired             = errors.New("access expired")
 	ErrNotAvailable        = errors.New("functionality not available")
 	ErrValidation          = errors.New("validation error")
diff --git a/persistence/player_repository.go b/persistence/player_repository.go
index 353b0444f..a2b079d53 100644
--- a/persistence/player_repository.go
+++ b/persistence/player_repository.go
@@ -2,7 +2,6 @@ package persistence
 
 import (
 	"context"
-	"errors"
 
 	. "github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
@@ -127,11 +126,7 @@ func (r *playerRepository) Save(entity any) (string, error) {
 	if !r.isPermitted(t) {
 		return "", rest.ErrPermissionDenied
 	}
-	id, err := r.put(t.ID, t)
-	if errors.Is(err, model.ErrNotFound) {
-		return "", rest.ErrNotFound
-	}
-	return id, err
+	return r.put(t.ID, t)
 }
 
 func (r *playerRepository) Update(id string, entity any, cols ...string) error {
diff --git a/persistence/playlist_repository.go b/persistence/playlist_repository.go
index bc6bffd25..cd3e48d18 100644
--- a/persistence/playlist_repository.go
+++ b/persistence/playlist_repository.go
@@ -416,9 +416,6 @@ func (r *playlistRepository) Update(id string, entity any, cols ...string) error
 	pls.ID = id
 	pls.UpdatedAt = time.Now()
 	_, err := r.put(id, pls, append(cols, "updatedAt")...)
-	if errors.Is(err, model.ErrNotFound) {
-		return rest.ErrNotFound
-	}
 	return err
 }
 
diff --git a/persistence/radio_repository.go b/persistence/radio_repository.go
index e042ee6bf..4584ceaed 100644
--- a/persistence/radio_repository.go
+++ b/persistence/radio_repository.go
@@ -2,7 +2,6 @@ package persistence
 
 import (
 	"context"
-	"errors"
 	"time"
 
 	. "github.com/Masterminds/squirrel"
@@ -47,7 +46,7 @@ func (r *radioRepository) Delete(id string) error {
 		return rest.ErrPermissionDenied
 	}
 
-	return r.delete(Eq{"id": id})
+	return r.deleteByID(id)
 }
 
 func (r *radioRepository) Get(id string) (*model.Radio, error) {
@@ -132,9 +131,6 @@ func (r *radioRepository) Save(entity any) (string, error) {
 		return "", rest.ErrPermissionDenied
 	}
 	err := r.Put(t)
-	if errors.Is(err, model.ErrNotFound) {
-		return "", rest.ErrNotFound
-	}
 	return t.ID, err
 }
 
@@ -144,11 +140,7 @@ func (r *radioRepository) Update(id string, entity any, cols ...string) error {
 	if !r.isPermitted() {
 		return rest.ErrPermissionDenied
 	}
-	err := r.Put(t, cols...)
-	if errors.Is(err, model.ErrNotFound) {
-		return rest.ErrNotFound
-	}
-	return err
+	return r.Put(t, cols...)
 }
 
 var _ model.RadioRepository = (*radioRepository)(nil)
diff --git a/persistence/radio_repository_test.go b/persistence/radio_repository_test.go
index a958f715d..8d4b685d9 100644
--- a/persistence/radio_repository_test.go
+++ b/persistence/radio_repository_test.go
@@ -52,6 +52,10 @@ var _ = Describe("RadioRepository", func() {
 				_, err = repo.Get(radioWithHomePage.ID)
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
+
+			It("errors when missing", func() {
+				Expect(repo.Delete("notanid")).To(MatchError(model.ErrNotFound))
+			})
 		})
 
 		Describe("Get", func() {
diff --git a/persistence/share_repository.go b/persistence/share_repository.go
index bcf33790d..0cf23068a 100644
--- a/persistence/share_repository.go
+++ b/persistence/share_repository.go
@@ -2,7 +2,6 @@ package persistence
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"strings"
 	"time"
@@ -178,11 +177,7 @@ func (r *shareRepository) Save(entity any) (string, error) {
 	}
 	s.CreatedAt = time.Now()
 	s.UpdatedAt = time.Now()
-	id, err := r.put(s.ID, s)
-	if errors.Is(err, model.ErrNotFound) {
-		return "", rest.ErrNotFound
-	}
-	return id, err
+	return r.put(s.ID, s)
 }
 
 func (r *shareRepository) CountAll(options ...model.QueryOptions) (int64, error) {
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index 5530d2568..9248f2a26 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -614,12 +614,20 @@ func (r sqlRepository) put(id string, m any, colsToUpdate ...string) (newId stri
 }
 
 func (r sqlRepository) delete(cond Sqlizer) error {
-	del := Delete(r.tableName).Where(cond)
-	_, err := r.executeSQL(del)
-	if errors.Is(err, sql.ErrNoRows) {
+	_, err := r.executeSQL(Delete(r.tableName).Where(cond))
+	return err
+}
+
+// deleteByID is for single-item deletes that must report a missing row; delete succeeds silently.
+func (r sqlRepository) deleteByID(id string) error {
+	count, err := r.executeSQL(Delete(r.tableName).Where(Eq{"id": id}))
+	if err != nil {
+		return err
+	}
+	if count == 0 {
 		return model.ErrNotFound
 	}
-	return err
+	return nil
 }
 
 func (r sqlRepository) logSQL(sql string, args dbx.Params, err error, rowsAffected int64, start time.Time) {
diff --git a/persistence/transcoding_repository.go b/persistence/transcoding_repository.go
index 96fd3efdb..fdf67806d 100644
--- a/persistence/transcoding_repository.go
+++ b/persistence/transcoding_repository.go
@@ -2,7 +2,6 @@ package persistence
 
 import (
 	"context"
-	"errors"
 
 	. "github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
@@ -91,11 +90,7 @@ func (r *transcodingRepository) Save(entity any) (string, error) {
 		return "", rest.ErrPermissionDenied
 	}
 	t := entity.(*model.Transcoding)
-	id, err := r.put(t.ID, t)
-	if errors.Is(err, model.ErrNotFound) {
-		return "", rest.ErrNotFound
-	}
-	return id, err
+	return r.put(t.ID, t)
 }
 
 func (r *transcodingRepository) Update(id string, entity any, cols ...string) error {
@@ -105,9 +100,6 @@ func (r *transcodingRepository) Update(id string, entity any, cols ...string) er
 	t := entity.(*model.Transcoding)
 	t.ID = id
 	_, err := r.put(id, t)
-	if errors.Is(err, model.ErrNotFound) {
-		return rest.ErrNotFound
-	}
 	return err
 }
 
@@ -115,11 +107,7 @@ func (r *transcodingRepository) Delete(id string) error {
 	if !loggedUser(r.ctx).IsAdmin {
 		return rest.ErrPermissionDenied
 	}
-	err := r.delete(Eq{"id": id})
-	if errors.Is(err, model.ErrNotFound) {
-		return rest.ErrNotFound
-	}
-	return err
+	return r.deleteByID(id)
 }
 
 var _ model.TranscodingRepository = (*transcodingRepository)(nil)
diff --git a/persistence/transcoding_repository_test.go b/persistence/transcoding_repository_test.go
index 73250163c..3be46bae3 100644
--- a/persistence/transcoding_repository_test.go
+++ b/persistence/transcoding_repository_test.go
@@ -65,6 +65,11 @@ var _ = Describe("TranscodingRepository", func() {
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
+		It("returns not found when deleting a missing transcoding", func() {
+			err := adminRepo.(*transcodingRepository).Delete("does-not-exist")
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
 		It("reads the Command field via the REST Read method", func() {
 			tr := &model.Transcoding{ID: "adminread", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg -secret"}
 			Expect(adminRepo.Put(tr)).To(Succeed())
diff --git a/persistence/user_repository.go b/persistence/user_repository.go
index 9de37876b..9399bcb53 100644
--- a/persistence/user_repository.go
+++ b/persistence/user_repository.go
@@ -244,11 +244,7 @@ func (r *userRepository) Read(id string) (any, error) {
 	if !usr.IsAdmin && usr.ID != id {
 		return nil, rest.ErrPermissionDenied
 	}
-	usr, err := r.Get(id)
-	if errors.Is(err, model.ErrNotFound) {
-		return nil, rest.ErrNotFound
-	}
-	return usr, err
+	return r.Get(id)
 }
 
 func (r *userRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
@@ -314,11 +310,7 @@ func (r *userRepository) Update(id string, entity any, _ ...string) error {
 	if err := validateScrobbleFilter(u); err != nil {
 		return err
 	}
-	err := r.Put(u)
-	if errors.Is(err, model.ErrNotFound) {
-		return rest.ErrNotFound
-	}
-	return err
+	return r.Put(u)
 }
 
 func validatePasswordChange(newUser *model.User, logged *model.User) error {
@@ -393,11 +385,7 @@ func (r *userRepository) Delete(id string) error {
 	if !usr.IsAdmin {
 		return rest.ErrPermissionDenied
 	}
-	err := r.delete(Eq{"id": id})
-	if errors.Is(err, model.ErrNotFound) {
-		return rest.ErrNotFound
-	}
-	if err != nil {
+	if err := r.deleteByID(id); err != nil {
 		return err
 	}
 
diff --git a/persistence/user_repository_test.go b/persistence/user_repository_test.go
index dc519d0a1..9a51b17dd 100644
--- a/persistence/user_repository_test.go
+++ b/persistence/user_repository_test.go
@@ -230,6 +230,14 @@ var _ = Describe("UserRepository", func() {
 		})
 	})
 
+	Describe("Delete", func() {
+		It("returns not found for a missing user", func() {
+			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
+			adminRepo := NewUserRepository(adminCtx, GetDBXBuilder()).(*userRepository)
+			Expect(adminRepo.Delete("does-not-exist")).To(MatchError(model.ErrNotFound))
+		})
+	})
+
 	Describe("ReadAll name filter", func() {
 		var adminRepo model.ResourceRepository
 
diff --git a/server/nativeapi/missing.go b/server/nativeapi/missing.go
index 0ad9bb0cc..de6595e00 100644
--- a/server/nativeapi/missing.go
+++ b/server/nativeapi/missing.go
@@ -6,7 +6,6 @@ import (
 	"maps"
 	"net/http"
 
-	"github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/log"
@@ -46,17 +45,14 @@ func (r *missingRepository) parseOptions(options []rest.QueryOptions) rest.Query
 }
 
 func (r *missingRepository) Read(id string) (any, error) {
-	all, err := r.mfRepo.GetAll(model.QueryOptions{Filters: squirrel.And{
-		squirrel.Eq{"id": id},
-		squirrel.Eq{"missing": true},
-	}})
+	mf, err := r.mfRepo.Get(id)
 	if err != nil {
 		return nil, err
 	}
-	if len(all) == 0 {
+	if !mf.Missing {
 		return nil, model.ErrNotFound
 	}
-	return all[0], nil
+	return mf, nil
 }
 
 func (r *missingRepository) EntityName() string {
diff --git a/server/nativeapi/missing_test.go b/server/nativeapi/missing_test.go
new file mode 100644
index 000000000..4da550c0d
--- /dev/null
+++ b/server/nativeapi/missing_test.go
@@ -0,0 +1,56 @@
+package nativeapi
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Missing Files Endpoint", func() {
+	var router http.Handler
+	var token string
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.SessionTimeout = time.Minute
+		conf.Server.EnableSharing = false
+
+		mfRepo := tests.CreateMockMediaFileRepo()
+		mfRepo.SetData(model.MediaFiles{
+			{ID: "missing-1", Title: "Gone", Missing: true},
+			{ID: "present-1", Title: "Here"},
+		})
+		userRepo := tests.CreateMockUserRepo()
+		ds := &tests.MockDataStore{MockedMediaFile: mfRepo, MockedUser: userRepo, MockedProperty: &tests.MockedPropertyRepo{}}
+		auth.Init(ds)
+
+		user := model.User{ID: "user-1", UserName: "user", NewPassword: "pass"}
+		Expect(userRepo.Put(&user)).To(Succeed())
+		var err error
+		token, err = auth.CreateToken(&user)
+		Expect(err).ToNot(HaveOccurred())
+
+		router = server.JWTVerifier(New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil))
+	})
+
+	DescribeTable("GET /missing/{id}",
+		func(id string, status int) {
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, createAuthenticatedRequest(http.MethodGet, "/missing/"+id, &bytes.Buffer{}, token))
+			Expect(w.Code).To(Equal(status), w.Body.String())
+		},
+		Entry("returns a missing file", "missing-1", http.StatusOK),
+		Entry("returns 404 for a file that is not missing", "present-1", http.StatusNotFound),
+		Entry("returns 404 for an unknown id", "unknown", http.StatusNotFound),
+	)
+})
diff --git a/server/nativeapi/playlists_test.go b/server/nativeapi/playlists_test.go
index 9abcc477f..4a6f5d03d 100644
--- a/server/nativeapi/playlists_test.go
+++ b/server/nativeapi/playlists_test.go
@@ -192,6 +192,7 @@ var _ = Describe("writePlaylistError", func() {
 		},
 		Entry("not found -> 404", model.ErrNotFound, http.StatusNotFound),
 		Entry("not authorized -> 403", model.ErrNotAuthorized, http.StatusForbidden),
+		Entry("rest permission denied -> 403", rest.ErrPermissionDenied, http.StatusForbidden),
 		Entry("not editable -> 409", model.ErrPlaylistNotEditable, http.StatusConflict),
 		Entry("unrecognized -> default", model.ErrValidation, http.StatusBadRequest),
 	)
diff --git a/server/subsonic/api.go b/server/subsonic/api.go
index 029046c39..deedc46c7 100644
--- a/server/subsonic/api.go
+++ b/server/subsonic/api.go
@@ -9,7 +9,6 @@ import (
 	"regexp"
 	"strconv"
 
-	"github.com/deluan/rest"
 	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core"
@@ -302,10 +301,9 @@ func mapToSubsonicError(err error) subError {
 		err = newError(responses.ErrorMissingParameter, err.Error())
 	case errors.Is(err, req.ErrInvalidParam):
 		err = newError(responses.ErrorGeneric, err.Error())
-	case errors.Is(err, model.ErrNotFound), errors.Is(err, rest.ErrNotFound):
+	case errors.Is(err, model.ErrNotFound):
 		err = newError(responses.ErrorDataNotFound, "data not found")
-	case errors.Is(err, model.ErrNotAuthorized), errors.Is(err, rest.ErrPermissionDenied),
-		errors.Is(err, model.ErrPlaylistNotEditable): // Subsonic has no code for "read-only resource"
+	case errors.Is(err, model.ErrNotAuthorized), errors.Is(err, model.ErrPlaylistNotEditable): // Subsonic has no code for "read-only resource"
 		err = newError(responses.ErrorAuthorizationFail)
 	case errors.Is(err, stream.ErrTooManyTranscodes):
 		err = newError(responses.ErrorGeneric, "too many concurrent transcodes, please retry shortly")
diff --git a/server/subsonic/e2e/subsonic_radio_test.go b/server/subsonic/e2e/subsonic_radio_test.go
index cd778fa79..d51cf6b14 100644
--- a/server/subsonic/e2e/subsonic_radio_test.go
+++ b/server/subsonic/e2e/subsonic_radio_test.go
@@ -130,4 +130,12 @@ var _ = Describe("Internet Radio Endpoints", Ordered, func() {
 		Expect(resp.InternetRadioStations).ToNot(BeNil())
 		Expect(resp.InternetRadioStations.Radios).To(BeEmpty())
 	})
+
+	It("deleteInternetRadioStation returns not found for a missing station", func() {
+		resp := doReq("deleteInternetRadioStation", "id", radioID)
+
+		Expect(resp.Status).To(Equal(responses.StatusFailed))
+		Expect(resp.Error).ToNot(BeNil())
+		Expect(resp.Error.Code).To(Equal(responses.ErrorDataNotFound))
+	})
 })
diff --git a/tests/mock_library_repo.go b/tests/mock_library_repo.go
index 1a16a7e0b..0f7af2aab 100644
--- a/tests/mock_library_repo.go
+++ b/tests/mock_library_repo.go
@@ -172,11 +172,7 @@ func (m *MockLibraryRepo) Count(options ...rest.QueryOptions) (int64, error) {
 
 func (m *MockLibraryRepo) Read(id string) (any, error) {
 	idInt, _ := strconv.Atoi(id)
-	mf, err := m.Get(idInt)
-	if errors.Is(err, model.ErrNotFound) {
-		return nil, rest.ErrNotFound
-	}
-	return mf, err
+	return m.Get(idInt)
 }
 
 func (m *MockLibraryRepo) ReadAll(options ...rest.QueryOptions) (any, error) {
diff --git a/tests/mock_mediafile_repo.go b/tests/mock_mediafile_repo.go
index 74225cd9b..a365bd2bd 100644
--- a/tests/mock_mediafile_repo.go
+++ b/tests/mock_mediafile_repo.go
@@ -302,11 +302,7 @@ func (m *MockMediaFileRepo) Count(...rest.QueryOptions) (int64, error) {
 }
 
 func (m *MockMediaFileRepo) Read(id string) (any, error) {
-	mf, err := m.Get(id)
-	if errors.Is(err, model.ErrNotFound) {
-		return nil, rest.ErrNotFound
-	}
-	return mf, err
+	return m.Get(id)
 }
 
 func (m *MockMediaFileRepo) ReadAll(...rest.QueryOptions) (any, error) {
diff --git a/tests/mock_plugin_repo.go b/tests/mock_plugin_repo.go
index 5d22c26aa..e65d56def 100644
--- a/tests/mock_plugin_repo.go
+++ b/tests/mock_plugin_repo.go
@@ -69,11 +69,7 @@ func (m *MockPluginRepo) Get(id string) (*model.Plugin, error) {
 }
 
 func (m *MockPluginRepo) Read(id string) (any, error) {
-	p, err := m.Get(id)
-	if errors.Is(err, model.ErrNotFound) {
-		return nil, rest.ErrNotFound
-	}
-	return p, err
+	return m.Get(id)
 }
 
 func (m *MockPluginRepo) Put(p *model.Plugin) error {

From 97270d44e194ccd467611ebe4af4acaf1d8b8b32 Mon Sep 17 00:00:00 2001
From: fxj368 <62541194+fxj368@users.noreply.github.com>
Date: Wed, 16 Sep 2026 19:24:50 +0800
Subject: [PATCH 143/200] fix(ui): update Chinese Simplified translations
 (#6152)

---
 resources/i18n/zh-Hans.json | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/resources/i18n/zh-Hans.json b/resources/i18n/zh-Hans.json
index 24f55357a..cae42460b 100644
--- a/resources/i18n/zh-Hans.json
+++ b/resources/i18n/zh-Hans.json
@@ -93,7 +93,8 @@
         "shuffle": "随机播放",
         "addToPlaylist": "添加到歌单",
         "download": "下载",
-        "info": "查看信息"
+        "info": "查看信息",
+        "refresh": "刷新元数据"
       },
       "lists": {
         "all": "全部",
@@ -155,11 +156,13 @@
         "currentPassword": "当前密码",
         "newPassword": "新密码",
         "token": "令牌",
-        "libraries": "媒体库"
+        "libraries": "媒体库",
+        "scrobbleFilter": "个性化记录过滤器"
       },
       "helperTexts": {
         "name": "名称的更改将在下次登录时生效",
-        "libraries": "为此用户选择指定媒体库，留空则使用默认媒体库"
+        "libraries": "为此用户选择指定媒体库，留空则使用默认媒体库",
+        "scrobbleFilter": "符合这些智能歌单规则的歌曲不会发送到 Last.fm、ListenBrainz 或个性化记录插件。使用与智能歌单相同的 JSON 语法和行为。例如：{\"all\":[{\"lt\":{\"rating\":4}}]}。留空则记录所有播放。本地播放次数不受影响。"
       },
       "notifications": {
         "created": "用户已创建",
@@ -167,7 +170,8 @@
         "deleted": "用户已删除"
       },
       "validation": {
-        "librariesRequired": "至少为非管理员用户选择一个媒体库"
+        "librariesRequired": "至少为非管理员用户选择一个媒体库",
+        "invalidScrobbleFilter": "必须是有效的智能歌单规则。不支持数量限制（limit）、偏移量（offset）和刷新延迟（refresh delay）。"
       },
       "message": {
         "listenBrainzToken": "输入您的 ListenBrainz 用户令牌",
@@ -196,6 +200,9 @@
         "targetFormat": "目标格式",
         "defaultBitRate": "默认比特率",
         "command": "命令"
+      },
+      "choices": {
+        "noDefaultBitRate": "无"
       }
     },
     "playlist": {
@@ -393,6 +400,7 @@
         "invalidJson": "配置必须是有效的 JSON"
       },
       "messages": {
+        "idHelp": "由插件文件名派生的插件 ID。在 Agents 等配置选项中引用此插件时使用。",
         "configHelp": "使用键值对配置插件。如果插件无需配置则留空。",
         "configValidationError": "配置验证失败：",
         "schemaRenderError": "无法渲染配置表单。此插件的 schema 定义可能无效。",
@@ -401,10 +409,10 @@
         "allUsersHelp": "启用时，插件将可以访问所有用户，包括将来创建的。",
         "noUsers": "未选择用户",
         "permissionReason": "原因",
-        "usersRequired": "此插件需要访问用户信息。请选择允许此插件访问的用户, 或启用 '允许所有用户'。",
+        "usersRequired": "此插件需要访问用户信息。请选择允许此插件访问的用户，或启用 '允许所有用户'。",
         "allLibrariesHelp": "启用时，插件将可以访问所有媒体库，包括将来创建的。",
         "noLibraries": "未选择媒体库",
-        "librariesRequired": "此插件需要访问媒体库信息。请选择允许此插件访问的媒体库, 或启用 '允许所有媒体库'。",
+        "librariesRequired": "此插件需要访问媒体库信息。请选择允许此插件访问的媒体库，或启用 '允许所有媒体库'。",
         "allowWriteAccessHelp": "启用时，插件将可以修改媒体库目录中的文件。默认情况下，插件仅拥有只读权限。",
         "requiredHosts": "必需的主机"
       },
@@ -566,6 +574,7 @@
     "coverRemoved": "封面已移除",
     "coverUploadError": "上传封面时出错",
     "coverRemoveError": "移除封面时出错",
+    "metadataRefreshStarted": "正在后台刷新元数据",
     "note": "注意",
     "transcodingDisabled": "出于安全原因，从 Web 界面更改转码配置的功能已被禁用。要更改（编辑或新增）转码选项，请在启用 %{config} 选项的情况下重新启动服务器。",
     "transcodingEnabled": "Navidrome 当前与 %{config} 一起使用，可以通过从 Web 界面配置转码选项来执行任意命令。建议禁用此选项，并且仅在需要配置转码选项时启用此功能。",
@@ -598,7 +607,7 @@
     "shareOriginalFormat": "分享原始格式",
     "shareDialogTitle": "分享 %{resource} '%{name}'",
     "shareBatchDialogTitle": "分享 %{smart_count} 项 %{resource}",
-    "shareCopyToClipboard": "复制到剪切板: Ctrl+C, Enter",
+    "shareCopyToClipboard": "复制到剪切板: Ctrl+C，Enter",
     "shareSuccess": "URL 已复制: %{url}",
     "shareFailure": "URL 复制失败: %{url}",
     "downloadDialogTitle": "下载 %{resource} '%{name}' (%{size})",

From 18205366c8f1a7b91b209b770f5dc966e824d33e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 16 Sep 2026 07:28:32 -0400
Subject: [PATCH 144/200] fix(jellyfin): match Jellyfin's item payloads so
 strict clients can sync (#6151)

* fix(jellyfin): match Jellyfin's item payloads so strict clients can sync

Manet (iOS/macOS) aborted its whole library sync on the first item that was
missing a key its decoder requires, leaving the library empty (#6147). Every
gap was a field real Jellyfin always sends:

- dates now use .NET's round-trip layout with 7 fractional digits, which Manet
  requires and plain RFC3339 failed
- playlists carry SortName/DateCreated, and every item carries MediaType,
  ImageTags, ChannelId and, when Fields asks, Genres/GenreItems/Tags
- albums carry Artists and LocationType; songs always carry HasLyrics
- the library view is a full CollectionFolder (ChildCount, DateCreated,
  SortName, Path, LocationType, UserData), read from the library rows rather
  than the user projection, which has no counts
- IncludeItemTypes matches case-insensitively and returns nothing for Jellyfin
  kinds Navidrome has none of, instead of falling back to every album

Verified against a real Jellyfin 10.10.7 server and a live Manet client.

* refactor(jellyfin): fold the repeated empty-list defaults into one helper

The three mappers each initialised Genres/GenreItems/Tags the same way, and the
e2e suite grew three near-identical specs walking every item type. Both now go
through a single helper and one table.

* refactor(jellyfin): fill the always-present item fields at the serialization edge

The defaults real Jellyfin puts on every item were spread across three mappers,
so item types nobody had tested yet (playlists, genres, the library view) still
shipped payloads a strict client rejects. stampItem now takes the request's
Fields and fills them for every item, which is provably the only path to JSON.

Also drops the hand-copied BaseItemKind list: only an absent IncludeItemTypes
defaults to albums now, so any type Navidrome does not serve returns nothing,
as it would from Jellyfin. The synthetic playlists folder matches
case-insensitively like the rest, /Items/{libraryId} reads the full library row
instead of the count-less user projection, and PremiereDate and LastPlayedDate
go through jellyfinDate rather than spelling the layout out again.
---
 server/jellyfin/api.go               |  3 +-
 server/jellyfin/dto/dto.go           | 39 ++++++++-------
 server/jellyfin/dto/mappers.go       | 48 +++++++++++++++---
 server/jellyfin/dto/mappers_test.go  | 32 +++++++-----
 server/jellyfin/e2e/browsing_test.go | 43 ++++++++++++++--
 server/jellyfin/e2e/lyrics_test.go   |  6 +--
 server/jellyfin/items.go             | 73 +++++++++++++++++++---------
 server/jellyfin/items_test.go        | 15 ++++++
 server/jellyfin/library.go           | 14 ------
 server/jellyfin/users.go             | 18 +++++--
 server/jellyfin/users_test.go        | 28 ++++++++++-
 11 files changed, 233 insertions(+), 86 deletions(-)

diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index 971f7794a..a4a1ee367 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -213,8 +213,7 @@ func (api *Router) ok(w http.ResponseWriter, r *http.Request, payload any) {
 		api.writeItems(w, r, materialized(p))
 		return
 	case dto.BaseItemDto:
-		p.ServerId = api.serverID(r.Context())
-		payload = p
+		payload = stampItem(p, api.serverID(r.Context()), requestFields(r))
 	}
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	if err := json.NewEncoder(w).Encode(payload); err != nil {
diff --git a/server/jellyfin/dto/dto.go b/server/jellyfin/dto/dto.go
index 58a6b919e..6d867ed21 100644
--- a/server/jellyfin/dto/dto.go
+++ b/server/jellyfin/dto/dto.go
@@ -49,20 +49,23 @@ type BaseItemDto struct {
 	// PlaylistItemId identifies an entry within a playlist listing (GET /Playlists/{id}/Items),
 	// distinct from Id so a song appearing more than once can be removed by occurrence
 	// (DELETE .../Items?EntryIds=...) rather than by song id.
-	PlaylistItemId    string `json:"PlaylistItemId,omitempty"`
-	Type              string `json:"Type"`
-	IsFolder          bool   `json:"IsFolder"`
-	MediaType         string `json:"MediaType,omitempty"`
-	CollectionType    string `json:"CollectionType,omitempty"`
-	LocationType      string `json:"LocationType,omitempty"`
-	HasLyrics         bool   `json:"HasLyrics,omitempty"`
-	SortName          string `json:"SortName,omitempty"`
-	Path              string `json:"Path,omitempty"`
-	ParentId          string `json:"ParentId,omitempty"`
-	RunTimeTicks      int64  `json:"RunTimeTicks,omitempty"`
-	IndexNumber       *int   `json:"IndexNumber,omitempty"`
-	ParentIndexNumber *int   `json:"ParentIndexNumber,omitempty"`
-	ProductionYear    *int   `json:"ProductionYear,omitempty"`
+	PlaylistItemId string `json:"PlaylistItemId,omitempty"`
+	Type           string `json:"Type"`
+	IsFolder       bool   `json:"IsFolder"`
+	MediaType      string `json:"MediaType,omitempty"`
+	CollectionType string `json:"CollectionType,omitempty"`
+	LocationType   string `json:"LocationType,omitempty"`
+	HasLyrics      *bool  `json:"HasLyrics,omitempty"`
+	// ChannelId is always null for music, but Jellyfin emits it on every item and clients may require it.
+	ChannelId         *string  `json:"ChannelId"`
+	Tags              []string `json:"Tags,omitzero"`
+	SortName          string   `json:"SortName,omitempty"`
+	Path              string   `json:"Path,omitempty"`
+	ParentId          string   `json:"ParentId,omitempty"`
+	RunTimeTicks      int64    `json:"RunTimeTicks,omitempty"`
+	IndexNumber       *int     `json:"IndexNumber,omitempty"`
+	ParentIndexNumber *int     `json:"ParentIndexNumber,omitempty"`
+	ProductionYear    *int     `json:"ProductionYear,omitempty"`
 	// PremiereDate is the ISO 8601 release date; Finamp sorts "Latest Releases" by it client-side.
 	PremiereDate *string `json:"PremiereDate,omitempty"`
 	// DateCreated is the ISO 8601 date the item was added to the library; clients show it as
@@ -73,17 +76,17 @@ type BaseItemDto struct {
 	AlbumArtist            string            `json:"AlbumArtist,omitempty"`
 	AlbumArtists           []NameGuidPair    `json:"AlbumArtists,omitempty"`
 	AlbumPrimaryImageTag   string            `json:"AlbumPrimaryImageTag,omitempty"`
-	Artists                []string          `json:"Artists,omitempty"`
+	Artists                []string          `json:"Artists,omitzero"`
 	ArtistItems            []NameGuidPair    `json:"ArtistItems,omitempty"`
-	Genres                 []string          `json:"Genres,omitempty"`
-	GenreItems             []NameGuidPair    `json:"GenreItems,omitempty"`
+	Genres                 []string          `json:"Genres,omitzero"`
+	GenreItems             []NameGuidPair    `json:"GenreItems,omitzero"`
 	Studios                []NameGuidPair    `json:"Studios,omitempty"`
 	NormalizationGain      *float64          `json:"NormalizationGain,omitempty"`
 	AlbumNormalizationGain *float64          `json:"AlbumNormalizationGain,omitempty"`
 	ChildCount             *int              `json:"ChildCount,omitempty"`
 	SongCount              *int              `json:"SongCount,omitempty"`
 	AlbumCount             *int              `json:"AlbumCount,omitempty"`
-	ImageTags              map[string]string `json:"ImageTags,omitempty"`
+	ImageTags              map[string]string `json:"ImageTags"`
 	// ImageBlurHashes is keyed by image type (e.g. "Primary") then image tag. Finamp uses it as a
 	// de-dup key for image downloads (and a placeholder); absent, it warns the server isn't
 	// calculating blurhashes.
diff --git a/server/jellyfin/dto/mappers.go b/server/jellyfin/dto/mappers.go
index 1ebf66ca1..0c9199066 100644
--- a/server/jellyfin/dto/mappers.go
+++ b/server/jellyfin/dto/mappers.go
@@ -46,17 +46,24 @@ func premiereDate(date string, year int) *string {
 		}
 		d = fmt.Sprintf("%04d-01-01", year)
 	}
-	s := d + "T00:00:00Z"
+	parsed, err := time.Parse(time.DateOnly, d)
+	if err != nil {
+		return nil
+	}
+	s := jellyfinDate(&parsed)
 	return &s
 }
 
-// jellyfinDate formats t as the ISO 8601 string clients expect, or "" for the zero time so the
+// Dates use .NET's round-trip layout, 7 fractional digits and all: Manet rejects plain RFC3339.
+const jellyfinDateLayout = "2006-01-02T15:04:05.0000000Z07:00"
+
+// jellyfinDate formats t as the date string clients expect, or "" for the zero time so the
 // field is omitted rather than sent as a meaningless epoch.
 func jellyfinDate(t *time.Time) string {
 	if t == nil || t.IsZero() {
 		return ""
 	}
-	return t.UTC().Format(time.RFC3339)
+	return t.UTC().Format(jellyfinDateLayout)
 }
 
 // channelLayout maps a channel count to the label Jellyfin clients expect on a MediaStream.
@@ -127,8 +134,7 @@ func UserData(a model.Annotations, itemID string) *UserItemDataDto {
 		r := float64(a.Rating) * 2 // Navidrome 0-5 -> Jellyfin 0-10
 		d.Rating = &r
 	}
-	if a.PlayDate != nil {
-		s := a.PlayDate.UTC().Format(time.RFC3339)
+	if s := jellyfinDate(a.PlayDate); s != "" {
 		d.LastPlayedDate = &s
 	}
 	return d
@@ -146,7 +152,7 @@ func SongToBaseItem(mf model.MediaFile, fields Fields) BaseItemDto {
 		MediaType:         "Audio",
 		IsFolder:          false,
 		LocationType:      "FileSystem",
-		HasLyrics:         mf.HasEmbeddedLyrics(),
+		HasLyrics:         new(mf.HasEmbeddedLyrics()),
 		ParentId:          albumID,
 		Album:             mf.Album,
 		AlbumId:           albumID,
@@ -251,6 +257,7 @@ func AlbumToBaseItem(al model.Album, fields Fields) BaseItemDto {
 		Id:                      EncodeID(al.ID),
 		Type:                    "MusicAlbum",
 		IsFolder:                true,
+		LocationType:            "FileSystem",
 		ParentId:                EncodeID(al.AlbumArtistID),
 		AlbumArtist:             al.AlbumArtist,
 		Album:                   al.Name,
@@ -266,6 +273,10 @@ func AlbumToBaseItem(al model.Album, fields Fields) BaseItemDto {
 	if tag != "" {
 		item.ImageTags = map[string]string{"Primary": tag}
 	}
+	item.Artists = []string{}
+	if al.AlbumArtist != "" {
+		item.Artists = append(item.Artists, al.AlbumArtist)
+	}
 	if al.AlbumArtistID != "" {
 		item.AlbumArtists = []NameGuidPair{{Name: al.AlbumArtist, Id: EncodeID(al.AlbumArtistID)}}
 		item.ArtistItems = item.AlbumArtists
@@ -321,6 +332,26 @@ func ArtistToBaseItem(ar model.Artist, fields Fields) BaseItemDto {
 	return item
 }
 
+// LibraryToBaseItem maps a library to the CollectionFolder item clients browse as a top-level node.
+// Manet keeps no library, and so syncs nothing, unless it carries the fields Jellyfin sends here.
+func LibraryToBaseItem(lib model.Library) BaseItemDto {
+	id := EncodeLibraryID(lib.ID)
+	return BaseItemDto{
+		Id:                id,
+		Name:              lib.Name,
+		SortName:          lib.Name,
+		Type:              "CollectionFolder",
+		CollectionType:    "music",
+		IsFolder:          true,
+		Path:              lib.Path,
+		LocationType:      "FileSystem",
+		DateCreated:       jellyfinDate(&lib.CreatedAt),
+		ChildCount:        new(lib.TotalAlbums),
+		UserData:          &UserItemDataDto{Key: id, ItemId: id},
+		BackdropImageTags: []string{},
+	}
+}
+
 func GenreToBaseItem(g model.Genre) BaseItemDto {
 	return BaseItemDto{
 		Name:              g.Name,
@@ -354,6 +385,7 @@ func PlaylistToBaseItem(p model.Playlist, fields Fields) BaseItemDto {
 		MediaType:               "Audio",
 		ChildCount:              new(p.SongCount),
 		RunTimeTicks:            TicksFromSeconds(p.Duration),
+		DateCreated:             jellyfinDate(&p.CreatedAt),
 		ImageBlurHashes:         blurs,
 		PrimaryImageAspectRatio: ratio,
 		BackdropImageTags:       []string{},
@@ -362,6 +394,10 @@ func PlaylistToBaseItem(p model.Playlist, fields Fields) BaseItemDto {
 	if tag != "" {
 		item.ImageTags = map[string]string{"Primary": tag}
 	}
+	// Playlists have no sort tag; the repository orders them by name.
+	if fields.Has("SortName") {
+		item.SortName = p.Name
+	}
 	return item
 }
 
diff --git a/server/jellyfin/dto/mappers_test.go b/server/jellyfin/dto/mappers_test.go
index 576482e61..6dc177363 100644
--- a/server/jellyfin/dto/mappers_test.go
+++ b/server/jellyfin/dto/mappers_test.go
@@ -104,10 +104,10 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("sets HasLyrics from the media file's lyrics", func() {
-			Expect(SongToBaseItem(mf, nil).HasLyrics).To(BeTrue())
-			Expect(SongToBaseItem(model.MediaFile{ID: testID("s2"), Title: "No Lyrics"}, nil).HasLyrics).To(BeFalse())
+			Expect(*SongToBaseItem(mf, nil).HasLyrics).To(BeTrue())
+			Expect(*SongToBaseItem(model.MediaFile{ID: testID("s2"), Title: "No Lyrics"}, nil).HasLyrics).To(BeFalse())
 			// "[]" is the no-lyrics sentinel, not a truthy value.
-			Expect(SongToBaseItem(model.MediaFile{ID: testID("s3"), Title: "Empty Lyrics", Lyrics: "[]"}, nil).HasLyrics).To(BeFalse())
+			Expect(*SongToBaseItem(model.MediaFile{ID: testID("s3"), Title: "Empty Lyrics", Lyrics: "[]"}, nil).HasLyrics).To(BeFalse())
 		})
 	})
 
@@ -120,7 +120,7 @@ var _ = Describe("mappers", func() {
 
 	It("sets DateCreated from the media file's CreatedAt", func() {
 		mf := model.MediaFile{ID: testID("s1"), Title: "Song", CreatedAt: time.Date(2024, 1, 15, 10, 30, 0, 0, time.UTC)}
-		Expect(SongToBaseItem(mf, nil).DateCreated).To(Equal("2024-01-15T10:30:00Z"))
+		Expect(SongToBaseItem(mf, nil).DateCreated).To(Equal("2024-01-15T10:30:00.0000000Z"))
 	})
 
 	It("omits DateCreated when CreatedAt is the zero time", func() {
@@ -282,7 +282,7 @@ var _ = Describe("mappers", func() {
 		mf.PlayDate = &playDate
 		item := SongToBaseItem(mf, nil)
 		Expect(item.UserData.LastPlayedDate).NotTo(BeNil())
-		Expect(*item.UserData.LastPlayedDate).To(Equal(playDate.Format(time.RFC3339)))
+		Expect(*item.UserData.LastPlayedDate).To(Equal("2023-05-17T12:30:00.0000000Z"))
 	})
 
 	It("maps an album to a MusicAlbum folder item", func() {
@@ -299,6 +299,9 @@ var _ = Describe("mappers", func() {
 		Expect(*item.ChildCount).To(Equal(10))
 		Expect(item.ImageTags).To(HaveKeyWithValue("Primary", testID("alb-1")))
 		Expect(item.ImageBlurHashes).To(BeNil())
+		// Jellyfin sends both on every album; Manet stops its sync on an album without them.
+		Expect(item.Artists).To(Equal([]string{"AA"}))
+		Expect(item.LocationType).To(Equal("FileSystem"))
 		Expect(item.Genres).To(Equal([]string{"genre 1", "genre 2"}))
 		Expect(item.GenreItems).To(Equal([]NameGuidPair{{Id: EncodeID(testID("1")), Name: "genre 1"}, {Id: EncodeID(testID("2")), Name: "genre 2"}}))
 	})
@@ -426,22 +429,22 @@ var _ = Describe("mappers", func() {
 		It("serializes a full date", func() {
 			mf := model.MediaFile{ID: testID("s1"), Title: "Song", Date: "2007-02-01", Year: 2007}
 			item := SongToBaseItem(mf, nil)
-			Expect(*item.PremiereDate).To(Equal("2007-02-01T00:00:00Z"))
+			Expect(*item.PremiereDate).To(Equal("2007-02-01T00:00:00.0000000Z"))
 		})
 
 		It("pads a year-only date so clients can parse it", func() {
 			mf := model.MediaFile{ID: testID("s1"), Title: "Song", Date: "2007", Year: 2007}
-			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("2007-01-01T00:00:00Z"))
+			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("2007-01-01T00:00:00.0000000Z"))
 		})
 
 		It("pads a year-month date", func() {
 			mf := model.MediaFile{ID: testID("s1"), Title: "Song", Date: "2007-02"}
-			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("2007-02-01T00:00:00Z"))
+			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("2007-02-01T00:00:00.0000000Z"))
 		})
 
 		It("falls back to the year when no date tag exists", func() {
 			mf := model.MediaFile{ID: testID("s1"), Title: "Song", Year: 1999}
-			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("1999-01-01T00:00:00Z"))
+			Expect(*SongToBaseItem(mf, nil).PremiereDate).To(Equal("1999-01-01T00:00:00.0000000Z"))
 		})
 
 		It("is omitted when the track has no date at all", func() {
@@ -449,8 +452,8 @@ var _ = Describe("mappers", func() {
 		})
 
 		It("is set on albums from their date, falling back to MaxYear", func() {
-			Expect(*AlbumToBaseItem(model.Album{ID: testID("a1"), Date: "2013-09-06"}, nil).PremiereDate).To(Equal("2013-09-06T00:00:00Z"))
-			Expect(*AlbumToBaseItem(model.Album{ID: testID("a2"), MaxYear: 2013}, nil).PremiereDate).To(Equal("2013-01-01T00:00:00Z"))
+			Expect(*AlbumToBaseItem(model.Album{ID: testID("a1"), Date: "2013-09-06"}, nil).PremiereDate).To(Equal("2013-09-06T00:00:00.0000000Z"))
+			Expect(*AlbumToBaseItem(model.Album{ID: testID("a2"), MaxYear: 2013}, nil).PremiereDate).To(Equal("2013-01-01T00:00:00.0000000Z"))
 			Expect(AlbumToBaseItem(model.Album{ID: testID("a3")}, nil).PremiereDate).To(BeNil())
 		})
 	})
@@ -475,6 +478,13 @@ var _ = Describe("mappers", func() {
 		Expect(item.ImageBlurHashes).To(BeNil())
 	})
 
+	It("emits DateCreated and SortName on playlists, like albums and artists", func() {
+		p := model.Playlist{ID: testID("pl-1"), Name: "Chill", CreatedAt: time.Date(2026, 7, 1, 12, 0, 0, 0, time.UTC)}
+		Expect(PlaylistToBaseItem(p, nil).DateCreated).To(Equal("2026-07-01T12:00:00.0000000Z"))
+		Expect(PlaylistToBaseItem(p, nil).SortName).To(BeEmpty())
+		Expect(PlaylistToBaseItem(p, ParseFields("SortName")).SortName).To(Equal("Chill"))
+	})
+
 	It("changes the playlist image tag when the cover content changes", func() {
 		p := model.Playlist{ID: testID("pl-1"), Name: "Chill"}
 		p.ImageHash = "1111111111111111"
diff --git a/server/jellyfin/e2e/browsing_test.go b/server/jellyfin/e2e/browsing_test.go
index 832b69f25..111e246fd 100644
--- a/server/jellyfin/e2e/browsing_test.go
+++ b/server/jellyfin/e2e/browsing_test.go
@@ -1,6 +1,7 @@
 package e2e
 
 import (
+	"encoding/json"
 	"net/http"
 	"slices"
 	"sort"
@@ -110,10 +111,46 @@ var _ = Describe("Browsing", func() {
 			Expect(q.Items).To(BeEmpty())
 		})
 
-		It("defaults to albums when IncludeItemTypes is unrecognized", func() {
-			q := queryResult(get("/Items?IncludeItemTypes=Nonsense&Recursive=true"))
-			Expect(q.TotalRecordCount).To(Equal(5))
+		// Manet syncs collections as Boxset, and took albums coming back instead as a sync failure.
+		DescribeTable("returns nothing for a type it does not serve",
+			func(itemType string) {
+				q := queryResult(get("/Items?IncludeItemTypes=" + itemType + "&Recursive=true"))
+				Expect(q.TotalRecordCount).To(Equal(0))
+				Expect(q.Items).To(BeEmpty())
+			},
+			Entry("a Jellyfin kind Navidrome has none of", "Boxset"),
+			Entry("a name Jellyfin does not know either", "Nonsense"),
+		)
+
+		// A strict client (Manet) fails its whole sync on the first item missing any of these.
+		DescribeTable("sends the keys Jellyfin puts on every item",
+			func(itemType string, fields string, nonNull ...string) {
+				var body struct{ Items []map[string]json.RawMessage }
+				res := get("/Items?IncludeItemTypes=" + itemType + "&Fields=" + fields + "&Recursive=true")
+				Expect(json.Unmarshal(res.Body.Bytes(), &body)).To(Succeed())
+				Expect(body.Items).ToNot(BeEmpty())
+				for _, it := range body.Items {
+					Expect(it).To(HaveKey("ChannelId"), "ChannelId is null, but always present")
+					for _, k := range nonNull {
+						Expect(it).To(HaveKey(k))
+						Expect(string(it[k])).ToNot(Equal("null"), k)
+					}
+				}
+			},
+			Entry("songs", "Audio", "Genres,Tags", "ImageTags", "HasLyrics", "Genres", "GenreItems", "Tags"),
+			Entry("albums", "MusicAlbum", "Genres", "ImageTags", "Genres", "GenreItems"),
+			Entry("artists", "MusicArtist", "Genres", "ImageTags", "Genres", "GenreItems"),
+		)
+
+		It("sends MediaType Unknown on items without one, as Jellyfin always emits it", func() {
+			q := queryResult(get("/Items?IncludeItemTypes=MusicAlbum&Recursive=true"))
+			Expect(q.Items).ToNot(BeEmpty())
+			for _, it := range q.Items {
+				Expect(it.MediaType).To(Equal("Unknown"))
+			}
+			Expect(queryResult(get("/Items?IncludeItemTypes=Audio&Recursive=true")).Items[0].MediaType).To(Equal("Audio"))
 		})
+
 	})
 
 	Describe("ParentId browsing", func() {
diff --git a/server/jellyfin/e2e/lyrics_test.go b/server/jellyfin/e2e/lyrics_test.go
index a49019bbf..d52a3b00f 100644
--- a/server/jellyfin/e2e/lyrics_test.go
+++ b/server/jellyfin/e2e/lyrics_test.go
@@ -58,14 +58,14 @@ var _ = Describe("Lyrics", func() {
 	})
 
 	Describe("HasLyrics badge", func() {
-		It("is true for a track with embedded lyrics and omitted/false otherwise", func() {
+		It("is true for a track with embedded lyrics and false otherwise", func() {
 			var stairway dto.BaseItemDto
 			parseInto(get("/Items/"+enc(songID("Stairway To Heaven"))), &stairway)
-			Expect(stairway.HasLyrics).To(BeTrue())
+			Expect(*stairway.HasLyrics).To(BeTrue())
 
 			var soWhat dto.BaseItemDto
 			parseInto(get("/Items/"+enc(songID("So What"))), &soWhat)
-			Expect(soWhat.HasLyrics).To(BeFalse())
+			Expect(*soWhat.HasLyrics).To(BeFalse())
 		})
 	})
 })
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index d16c5e57e..9ed3d2c8d 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -219,11 +219,40 @@ func (api *Router) writeItemsArray(w http.ResponseWriter, r *http.Request, res i
 	api.streamResult(w, r, res, streamItemsArray)
 }
 
-// streamResult stamps every item's ServerId (constant per request, so it's set here rather than in
-// each mapper). The cursor opens before the first byte, so a failed open is still a clean 500.
+// stampItem fills in what real Jellyfin puts on every item it returns, so a client that requires a
+// key never meets an item without it: ServerId, MediaType, ImageTags, and the Fields-gated lists.
+func stampItem(it dto.BaseItemDto, serverID string, fields dto.Fields) dto.BaseItemDto {
+	it.ServerId = serverID
+	if it.MediaType == "" {
+		it.MediaType = "Unknown"
+	}
+	if it.ImageTags == nil {
+		it.ImageTags = map[string]string{}
+	}
+	if fields.Has("Genres") {
+		if it.Genres == nil {
+			it.Genres = []string{}
+		}
+		if it.GenreItems == nil {
+			it.GenreItems = []dto.NameGuidPair{}
+		}
+	}
+	if fields.Has("Tags") && it.Tags == nil {
+		it.Tags = []string{}
+	}
+	return it
+}
+
+// requestFields parses the Fields param, which gates what stampItem and the mappers attach.
+func requestFields(r *http.Request) dto.Fields {
+	return dto.ParseFields(req.Params(r).Strings("fields")...)
+}
+
+// streamResult stamps every item (see stampItem). The cursor opens before the first byte, so a
+// failed open is still a clean 500.
 func (api *Router) streamResult(w http.ResponseWriter, r *http.Request, res itemsResult,
 	write func(io.Writer, iter.Seq2[dto.BaseItemDto, error]) error) {
-	sid := api.serverID(r.Context())
+	sid, fields := api.serverID(r.Context()), requestFields(r)
 	seq, err := res.seq()
 	if err != nil {
 		api.internalError(w, r, err)
@@ -235,8 +264,7 @@ func (api *Router) streamResult(w http.ResponseWriter, r *http.Request, res item
 				yield(dto.BaseItemDto{}, err)
 				return
 			}
-			it.ServerId = sid
-			if !yield(it, nil) {
+			if !yield(stampItem(it, sid, fields), nil) {
 				return
 			}
 		}
@@ -380,7 +408,7 @@ func (api *Router) queryItems(ctx context.Context, r *http.Request) (itemsResult
 	case len(q.ids) > 0:
 		return materialized(api.itemsByIDs(ctx, q.ids, q.fields)), nil
 	// A ManualPlaylistsFolder query asks for the synthetic "playlists library" container, not real items.
-	case strings.Contains(q.rawTypes, "ManualPlaylistsFolder"):
+	case strings.Contains(strings.ToLower(q.rawTypes), "manualplaylistsfolder"):
 		return materialized(result([]dto.BaseItemDto{playlistsFolder()}, 1, 0)), nil
 	}
 	if repo, ok := api.playlistTracksRepo(ctx, q); ok {
@@ -559,23 +587,26 @@ func parseYears(r *http.Request) []int {
 	return years
 }
 
-// parseTypes returns the recognized entries in IncludeItemTypes in order, defaulting to
-// {"MusicAlbum"} when none are recognized (so ParentId=<artistId> browses that artist's albums).
+// supportedTypes maps lowercased IncludeItemTypes names (Jellyfin binds them case-insensitively)
+// to the item types Navidrome serves.
+var supportedTypes = map[string]string{
+	"audio": "Audio", "musicartist": "MusicArtist", "musicalbum": "MusicAlbum", "musicgenre": "MusicGenre", "playlist": "Playlist",
+}
+
+// parseTypes returns the supported entries in IncludeItemTypes in order. Only an absent param
+// defaults to albums, so ParentId=<artistId> still browses that artist's albums.
 func parseTypes(types string) []string {
+	if strings.TrimSpace(types) == "" {
+		return []string{"MusicAlbum"}
+	}
 	var recognized []string
 	for t := range strings.SplitSeq(types, ",") {
-		t = strings.TrimSpace(t)
-		switch t {
-		case "Audio", "MusicArtist", "MusicAlbum", "MusicGenre", "Playlist":
-			recognized = append(recognized, t)
+		if name, ok := supportedTypes[strings.ToLower(strings.TrimSpace(t))]; ok {
+			recognized = append(recognized, name)
 		}
 	}
 	// Dedupe: a repeated type would duplicate items in the merge and spawn a redundant query.
-	recognized = slice.Unique(recognized)
-	if len(recognized) == 0 {
-		return []string{"MusicAlbum"}
-	}
-	return recognized
+	return slice.Unique(recognized)
 }
 
 // paginate applies StartIndex/Limit to an in-memory item list, for the multi-type merge path only
@@ -828,14 +859,8 @@ func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fi
 	// Finamp resolves a /UserViews entry (Id=library id) by fetching it as a plain item; without this
 	// the home screen and library tabs 404.
 	if libID, err := strconv.Atoi(id); err == nil && u.HasLibraryAccess(libID) {
-		for _, lib := range u.Libraries {
-			if lib.ID == libID {
-				return libraryView(lib), true
-			}
-		}
-		// Admin bypass: Libraries is empty but all access is granted, so fetch the real library.
 		if lib, err := api.ds.Library(ctx).Get(libID); err == nil {
-			return libraryView(*lib), true
+			return dto.LibraryToBaseItem(*lib), true
 		}
 	}
 	if al, err := api.ds.Album(ctx).Get(id); err == nil {
diff --git a/server/jellyfin/items_test.go b/server/jellyfin/items_test.go
index 17180c36a..c92c011fe 100644
--- a/server/jellyfin/items_test.go
+++ b/server/jellyfin/items_test.go
@@ -981,6 +981,7 @@ var _ = Describe("Items", func() {
 		It("resolves a library-view id (from /UserViews) as a CollectionFolder item", func() {
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1, Name: "Music Library"}}
+			ds.Library(context.Background()).(*tests.MockLibraryRepo).SetData(libs)
 			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeLibraryID(1), nil).WithContext(ctxUserWithLibraries(libs))
 			r = withChiURLParam(r, "itemId", dto.EncodeLibraryID(1))
 			invoke(api.getItem, w, r)
@@ -1124,6 +1125,20 @@ var _ = Describe("Items", func() {
 		It("dedupes repeated types, preserving first-seen order", func() {
 			Expect(parseTypes("Audio,MusicAlbum,Audio")).To(Equal([]string{"Audio", "MusicAlbum"}))
 		})
+
+		It("matches type names case-insensitively, like Jellyfin's enum binding", func() {
+			Expect(parseTypes("musicalbum, AUDIO")).To(Equal([]string{"MusicAlbum", "Audio"}))
+		})
+
+		It("returns no types for real Jellyfin kinds Navidrome has none of", func() {
+			Expect(parseTypes("Boxset")).To(BeEmpty())
+			Expect(parseTypes("BoxSet,Movie")).To(BeEmpty())
+		})
+
+		It("defaults to albums only when IncludeItemTypes is absent", func() {
+			Expect(parseTypes("")).To(Equal([]string{"MusicAlbum"}))
+			Expect(parseTypes("Nonsense")).To(BeEmpty())
+		})
 	})
 
 	Describe("decodeFilterParam", func() {
diff --git a/server/jellyfin/library.go b/server/jellyfin/library.go
index b21603843..9f1f7ee73 100644
--- a/server/jellyfin/library.go
+++ b/server/jellyfin/library.go
@@ -7,7 +7,6 @@ import (
 
 	"github.com/Masterminds/squirrel"
 	"github.com/go-chi/chi/v5"
-	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/jellyfin/dto"
 	"github.com/navidrome/navidrome/utils/req"
@@ -74,16 +73,3 @@ func libraryScopeFilter(scope []int) squirrel.Sqlizer {
 	}
 	return squirrel.Eq{"library_tag.library_id": scope}
 }
-
-// libraryView builds the CollectionFolder BaseItemDto representing a library as a top-level node.
-// Shared by getUserViews and getItem, since Finamp fetches a UserView's id as a plain item.
-func libraryView(lib model.Library) dto.BaseItemDto {
-	return dto.BaseItemDto{
-		Id:                dto.EncodeLibraryID(lib.ID),
-		Name:              lib.Name,
-		Type:              "CollectionFolder",
-		CollectionType:    "music",
-		IsFolder:          true,
-		BackdropImageTags: []string{},
-	}
-}
diff --git a/server/jellyfin/users.go b/server/jellyfin/users.go
index bbc60c892..ee4ace48e 100644
--- a/server/jellyfin/users.go
+++ b/server/jellyfin/users.go
@@ -13,10 +13,20 @@ import (
 // getUserViews returns one CollectionFolder view per accessible library, so clients browse each
 // library as its own top-level view rather than one aggregate.
 func (api *Router) getUserViews(w http.ResponseWriter, r *http.Request) {
-	u, _ := request.UserFrom(r.Context())
-	views := make([]dto.BaseItemDto, 0, len(u.Libraries))
-	for _, lib := range u.Libraries {
-		views = append(views, libraryView(lib))
+	ctx := r.Context()
+	u, _ := request.UserFrom(ctx)
+	// u.Libraries comes from a projection without counts or stats, and clients hide a library that
+	// looks empty, so the rows are re-read in full here.
+	libs, err := api.ds.Library(ctx).GetAll()
+	if err != nil {
+		api.internalError(w, r, err)
+		return
+	}
+	views := make([]dto.BaseItemDto, 0, len(libs))
+	for _, lib := range libs {
+		if u.HasLibraryAccess(lib.ID) {
+			views = append(views, dto.LibraryToBaseItem(lib))
+		}
 	}
 	api.ok(w, r, dto.QueryResult{Items: views, TotalRecordCount: len(views), StartIndex: 0})
 }
diff --git a/server/jellyfin/users_test.go b/server/jellyfin/users_test.go
index 3e53d598f..c6bb99f71 100644
--- a/server/jellyfin/users_test.go
+++ b/server/jellyfin/users_test.go
@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -18,8 +19,14 @@ import (
 
 var _ = Describe("Users", func() {
 	var api *Router
+	// The repo holds the full rows; the user carries the id/name-only copy its projection returns.
 	authedWithLibraries := func(r *http.Request, libs model.Libraries) *http.Request {
-		ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: libs})
+		api.ds.Library(context.Background()).(*tests.MockLibraryRepo).SetData(libs)
+		stripped := make(model.Libraries, len(libs))
+		for i, lib := range libs {
+			stripped[i] = model.Library{ID: lib.ID, Name: lib.Name}
+		}
+		ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: stripped})
 		return r.WithContext(ctx)
 	}
 	BeforeEach(func() { api = &Router{ds: &tests.MockDataStore{}} })
@@ -45,6 +52,25 @@ var _ = Describe("Users", func() {
 			Expect(res.Items[1].Name).To(Equal("Podcasts"))
 		})
 
+		// Manet keeps no library, and so syncs no artists/albums/tracks, when these are missing.
+		It("describes the library like Jellyfin's CollectionFolder", func() {
+			created := time.Date(2026, 7, 1, 12, 0, 0, 0, time.UTC)
+			libs := model.Libraries{{ID: 1, Name: "Music", Path: "/music", TotalAlbums: 42, CreatedAt: created}}
+			w := httptest.NewRecorder()
+			api.getUserViews(w, authedWithLibraries(httptest.NewRequest("GET", "/UserViews", nil), libs))
+			var res dto.QueryResult
+			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+
+			item := res.Items[0]
+			Expect(*item.ChildCount).To(Equal(42))
+			Expect(item.DateCreated).To(Equal("2026-07-01T12:00:00.0000000Z"))
+			Expect(item.SortName).To(Equal("Music"))
+			Expect(item.Path).To(Equal("/music"))
+			Expect(item.LocationType).To(Equal("FileSystem"))
+			Expect(item.UserData).ToNot(BeNil())
+			Expect(item.UserData.ItemId).To(Equal(dto.EncodeLibraryID(1)))
+		})
+
 		It("returns a single view for a user with one library", func() {
 			libs := model.Libraries{{ID: 1, Name: "Music"}}
 			w := httptest.NewRecorder()

From decac50f60133326a54f3f53e6b7e00340966ba2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 17 Sep 2026 07:29:56 -0400
Subject: [PATCH 145/200] fix(lastfm): double-encode plus signs in artist and
 track names (#6158)

Last.fm decodes the artist and track params of artist.getInfo, artist.getSimilar, artist.getTopTracks and track.getSimilar twice, so a "+" in a name becomes a space. Names like "Florence + The Machine" resolved to a misspelled duplicate page whose bio is Last.fm's "incorrect tag" notice, and names like "+44" were not found at all. Encode "+" as %2B before the normal query encoding for those calls. album.getInfo decodes only once, so it keeps the plain encoding.
---
 adapters/lastfm/client.go      | 16 ++++++++----
 adapters/lastfm/client_test.go | 47 ++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 5 deletions(-)

diff --git a/adapters/lastfm/client.go b/adapters/lastfm/client.go
index e468aa638..7b2601cf9 100644
--- a/adapters/lastfm/client.go
+++ b/adapters/lastfm/client.go
@@ -49,6 +49,12 @@ type client struct {
 	hc     httpDoer
 }
 
+// escapePlus works around Last.fm decoding artist.* and track.* params twice, turning "+" into a space.
+// album.getInfo decodes only once, so it must not use this.
+func escapePlus(s string) string {
+	return strings.ReplaceAll(s, "+", "%2B")
+}
+
 func (c *client) albumGetInfo(ctx context.Context, name string, artist string, mbid string, lang string) (*Album, error) {
 	params := url.Values{}
 	params.Add("method", "album.getInfo")
@@ -66,7 +72,7 @@ func (c *client) albumGetInfo(ctx context.Context, name string, artist string, m
 func (c *client) artistGetInfo(ctx context.Context, name string, lang string) (*Artist, error) {
 	params := url.Values{}
 	params.Add("method", "artist.getInfo")
-	params.Add("artist", name)
+	params.Add("artist", escapePlus(name))
 	params.Add("lang", lang)
 	response, err := c.makeRequest(ctx, http.MethodGet, params, false)
 	if err != nil {
@@ -78,7 +84,7 @@ func (c *client) artistGetInfo(ctx context.Context, name string, lang string) (*
 func (c *client) artistGetSimilar(ctx context.Context, name string, limit int) (*SimilarArtists, error) {
 	params := url.Values{}
 	params.Add("method", "artist.getSimilar")
-	params.Add("artist", name)
+	params.Add("artist", escapePlus(name))
 	params.Add("limit", strconv.Itoa(limit))
 	response, err := c.makeRequest(ctx, http.MethodGet, params, false)
 	if err != nil {
@@ -90,7 +96,7 @@ func (c *client) artistGetSimilar(ctx context.Context, name string, limit int) (
 func (c *client) artistGetTopTracks(ctx context.Context, name string, limit int) (*TopTracks, error) {
 	params := url.Values{}
 	params.Add("method", "artist.getTopTracks")
-	params.Add("artist", name)
+	params.Add("artist", escapePlus(name))
 	params.Add("limit", strconv.Itoa(limit))
 	response, err := c.makeRequest(ctx, http.MethodGet, params, false)
 	if err != nil {
@@ -102,8 +108,8 @@ func (c *client) artistGetTopTracks(ctx context.Context, name string, limit int)
 func (c *client) trackGetSimilar(ctx context.Context, name, artist string, limit int) (*SimilarTracks, error) {
 	params := url.Values{}
 	params.Add("method", "track.getSimilar")
-	params.Add("track", name)
-	params.Add("artist", artist)
+	params.Add("track", escapePlus(name))
+	params.Add("artist", escapePlus(artist))
 	params.Add("limit", strconv.Itoa(limit))
 	response, err := c.makeRequest(ctx, http.MethodGet, params, false)
 	if err != nil {
diff --git a/adapters/lastfm/client_test.go b/adapters/lastfm/client_test.go
index 271ae1419..f72c84b91 100644
--- a/adapters/lastfm/client_test.go
+++ b/adapters/lastfm/client_test.go
@@ -35,6 +35,15 @@ var _ = Describe("client", func() {
 			Expect(album.Name).To(Equal("Believe"))
 			Expect(httpClient.SavedRequest.URL.String()).To(Equal(apiBaseUrl + "?album=Believe&api_key=API_KEY&artist=U2&format=json&lang=pt&mbid=mbid-1234&method=album.getInfo"))
 		})
+
+		It("does not double-encode plus signs", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.album.getinfo.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			_, err := client.albumGetInfo(context.Background(), "Lungs", "Florence + the Machine", "", "en")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(httpClient.SavedRequest.URL.Query().Get("artist")).To(Equal("Florence + the Machine"))
+		})
 	})
 
 	Describe("artistGetInfo", func() {
@@ -48,6 +57,15 @@ var _ = Describe("client", func() {
 			Expect(httpClient.SavedRequest.URL.String()).To(Equal(apiBaseUrl + "?api_key=API_KEY&artist=U2&format=json&lang=pt&method=artist.getInfo"))
 		})
 
+		It("double-encodes plus signs in the artist name", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.artist.getinfo.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			_, err := client.artistGetInfo(context.Background(), "Florence + the Machine", "en")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(httpClient.SavedRequest.URL.Query().Get("artist")).To(Equal("Florence %2B the Machine"))
+		})
+
 		It("fails if Last.fm returns an http status != 200", func() {
 			httpClient.Res = http.Response{
 				Body:       io.NopCloser(bytes.NewBufferString(`Internal Server Error`)),
@@ -107,6 +125,15 @@ var _ = Describe("client", func() {
 			Expect(len(similar.Artists)).To(Equal(2))
 			Expect(httpClient.SavedRequest.URL.String()).To(Equal(apiBaseUrl + "?api_key=API_KEY&artist=U2&format=json&limit=2&method=artist.getSimilar"))
 		})
+
+		It("double-encodes plus signs in the artist name", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.artist.getsimilar.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			_, err := client.artistGetSimilar(context.Background(), "+44", 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(httpClient.SavedRequest.URL.Query().Get("artist")).To(Equal("%2B44"))
+		})
 	})
 
 	Describe("artistGetTopTracks", func() {
@@ -119,6 +146,15 @@ var _ = Describe("client", func() {
 			Expect(len(top.Track)).To(Equal(2))
 			Expect(httpClient.SavedRequest.URL.String()).To(Equal(apiBaseUrl + "?api_key=API_KEY&artist=U2&format=json&limit=2&method=artist.getTopTracks"))
 		})
+
+		It("double-encodes plus signs in the artist name", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.artist.gettoptracks.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			_, err := client.artistGetTopTracks(context.Background(), "C+C Music Factory", 2)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(httpClient.SavedRequest.URL.Query().Get("artist")).To(Equal("C%2BC Music Factory"))
+		})
 	})
 
 	Describe("trackGetSimilar", func() {
@@ -135,6 +171,17 @@ var _ = Describe("client", func() {
 			Expect(httpClient.SavedRequest.URL.String()).To(Equal(apiBaseUrl + "?api_key=API_KEY&artist=Depeche+Mode&format=json&limit=5&method=track.getSimilar&track=Just+Can%27t+Get+Enough"))
 		})
 
+		It("double-encodes plus signs in the track and artist names", func() {
+			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.json")
+			httpClient.Res = http.Response{Body: f, StatusCode: 200}
+
+			_, err := client.trackGetSimilar(context.Background(), "1+1", "Queen + Paul Rodgers", 5)
+			Expect(err).ToNot(HaveOccurred())
+			query := httpClient.SavedRequest.URL.Query()
+			Expect(query.Get("track")).To(Equal("1%2B1"))
+			Expect(query.Get("artist")).To(Equal("Queen %2B Paul Rodgers"))
+		})
+
 		It("returns empty list when no similar tracks found", func() {
 			f, _ := os.Open("tests/fixtures/lastfm.track.getsimilar.unknown.json")
 			httpClient.Res = http.Response{Body: f, StatusCode: 200}

From 5bd14da65cd6ee1213aed4b5867ffdab17c6e1a3 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Thu, 17 Sep 2026 10:59:28 -0400
Subject: [PATCH 146/200] test(artwork): cover artist folder lookup for a
 single album without images

Add an e2e spec for an artist whose only album folder has no images of its
own, while the artist folder holds folder.jpg (plus unrelated images) and
ArtistArtPriority starts with folder.*. Before #5856, the album's parent was
promoted into the album paths, so the artist folder resolved to the library
root and the artist got no image. The spec fails if that promotion comes
back, and passes on current code.

Refs #5823
---
 core/artwork/e2e/artist_test.go | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/core/artwork/e2e/artist_test.go b/core/artwork/e2e/artist_test.go
index 5a9396cc3..4a6959d95 100644
--- a/core/artwork/e2e/artist_test.go
+++ b/core/artwork/e2e/artist_test.go
@@ -90,6 +90,28 @@ var _ = Describe("Artist artwork resolution", func() {
 		})
 	})
 
+	When("the artist's only album folder has no images of its own", func() {
+		// Artist/
+		// ├── backdrop1.jpg
+		// ├── folder.jpg               ← matched by folder.*
+		// ├── logo.png
+		// └── Album/
+		//     ├── 01 - Track.mp3
+		//     └── 02 - Track.mp3
+		It("resolves the artist folder, not the library root", func() {
+			conf.Server.ArtistArtPriority = "folder.*, artist.*, album/artist.*"
+			setLayout(fstest.MapFS{
+				"Artist/Album/01 - Track.mp3": trackFile(1, "Track 1", map[string]any{"albumartist": "Artist", "album": "Album"}),
+				"Artist/Album/02 - Track.mp3": trackFile(2, "Track 2", map[string]any{"albumartist": "Artist", "album": "Album"}),
+				"Artist/backdrop1.jpg":        smallPNG("backdrop"),
+				"Artist/folder.jpg":           smallPNG("artist-folder"),
+				"Artist/logo.png":             smallPNG("logo"),
+			})
+			scan()
+			expectArtistFolder(soleArtist(), "Artist/folder.jpg")
+		})
+	})
+
 	When("the artist's only album has its tracks in disc subfolders", func() {
 		// Artist/
 		// ├── artist.jpg               ← wins (artist.* before album/artist.*)

From ded4f47d93d6854f284056cbecfa33e5a35af003 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 17 Sep 2026 17:17:56 -0400
Subject: [PATCH 147/200] fix(release): repair root-owned artwork and plugins
 folders on upgrade (#6143)

* fix(release): repair root-owned artwork and plugins folders on upgrade

Navidrome 0.57.0, 0.60.x and 0.61.x created the plugins and artwork folders as soon as the configuration loaded. The deb/rpm postinstall script runs navidrome as root, so fresh installs and upgrades on those versions left these folders owned by root. The service runs as the navidrome user and cannot write to them. Since 0.64.0 new artwork is stored under artwork/hashed, so affected installs fail to persist artwork and cannot read the plugins folder.

The postinstall script now changes the owner of these two folders to navidrome, only when they exist and are owned by root. The change is not recursive: root created the folders empty and the service could never write inside them, so fixing the folder itself is enough and stays instant regardless of how much artwork exists. Folders an admin assigned to another user are left untouched.

Fixes #6140

* fix(release): handle root-owned cache folder without install noise

The postinstall script ran an unconditional chown on /var/lib/navidrome/cache during fresh installs. Since folders are created lazily, the cache folder does not exist at that point, so every fresh deb/rpm install printed "chown: cannot access '/var/lib/navidrome/cache': No such file or directory".

The cache folder is now part of the same root-owned folder check used for artwork and plugins: it is fixed when it exists and is owned by root, and skipped silently otherwise. This also covers installs from 0.54.1 and 0.54.2, which created the cache folder as root before the chown was added.

* fix(release): never follow symlinks when repairing folder ownership

The ownership check used find's default -P mode, so -user root tested a symlink itself, while chown dereferenced it. A root-owned symlink pointing to a folder owned by another account made the postinstall script reassign that folder to navidrome, bypassing the root-owner guard.

The check now only matches real directories (-type d without following links) and uses chown -h. Following the link with find -H was rejected: /var/lib/navidrome is owned by navidrome, so the service account could plant a symlink to any root-owned directory and have the next upgrade hand it over. As a trade-off, a symlink to a root-owned folder is no longer repaired; the folders affected by the original bug were always real directories.
---
 release/linux/postinstall.sh | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/release/linux/postinstall.sh b/release/linux/postinstall.sh
index ed39fb127..007114ef5 100644
--- a/release/linux/postinstall.sh
+++ b/release/linux/postinstall.sh
@@ -13,15 +13,16 @@ if [ ! -f /etc/navidrome/navidrome.toml ]; then
     printf "MusicFolder = \"/opt/navidrome/music\"\n" >> /etc/navidrome/navidrome.toml
 fi
 
+# Older versions created these folders as root when this script ran `navidrome`. They were created empty,
+# so no -R. Real dirs only, never following links: navidrome owns /var/lib/navidrome and could plant symlinks.
+find /var/lib/navidrome/cache /var/lib/navidrome/artwork /var/lib/navidrome/plugins -maxdepth 0 -type d -user root -exec chown -h navidrome:navidrome {} + 2>/dev/null
+
 postinstall_flag="/var/lib/navidrome/.installed"
 
 if [ ! -f "$postinstall_flag" ]; then
     # The primary reason why this would fail is if the service was already installed AND
     # someone manually removed the .installed flag. In this case, ignore the error
     navidrome service install --user navidrome --working-directory /var/lib/navidrome --configfile /etc/navidrome/navidrome.toml || :
-    # Any `navidrome` command will make a cache. Make sure that this is properly owned by the Navidrome user
-    # and not by root
-    chown navidrome:navidrome /var/lib/navidrome/cache
     touch "$postinstall_flag"
 else
     navidrome service stop --configfile /etc/navidrome/navidrome.toml && navidrome service start --configfile /etc/navidrome/navidrome.toml

From 16567f147b6a57f9cdfc4fe37c4577cf0a4b1d57 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 17 Sep 2026 23:48:39 -0400
Subject: [PATCH 148/200] fix(jellyfin): match Jellyfin on login SessionInfo,
 item types and universal streams (#6161)

* fix(jellyfin): send SessionInfo on login so JellyBox gets past sign-in

JellyBox parses AuthenticateByName's SessionInfo as a required object and
fails silently when it is missing, leaving the user on the login screen.
Real Jellyfin always sends it (SessionManager.AuthenticateNewSessionInternal,
10.10.7 and master), so the login response now carries a full SessionInfo
built from the user and the MediaBrowser auth header. It includes every field
JellyBox (Id, PlayState) and Finamp (UserId, LastActivityDate, the activity
and control bools, PlayState's CanSeek/IsPaused/IsMuted) require once the
object is present. The session Id is derived from client and device id, so
repeated logins from one install share it.

* fix(jellyfin): ignore IncludeItemTypes names that aren't Jellyfin kinds

JellyBox opens an album with ParentId=<album>&IncludeItemTypes=music. Music
is not a BaseItemKind, and Jellyfin's comma-delimited binder drops values it
cannot parse, so real Jellyfin treats the request as having no type filter and
lists the album's tracks. Navidrome returned an empty list, so every album
opened empty. Entries that aren't BaseItemKind names are now dropped before
type resolution, so an all-unknown list behaves like an absent one. Real kinds
Navidrome doesn't serve, such as Boxset, still return nothing.

* fix(jellyfin): treat universal Container as the direct-play list

On /Audio/{id}/universal, Container lists the "container|codec" entries the
client can direct play, and TranscodingContainer/AudioCodec name the target
when it can't (UniversalAudioController builds DirectPlayProfiles from it).
Navidrome passed the whole list to the decider as one target format, which
matched nothing and fell back to DefaultDownsamplingFormat, so JellyBox got
every MP3 transcoded to Opus. /universal now has its own handler: a source
matching an entry keeps its format (still downsampled under a bitrate cap),
anything else is transcoded to TranscodingContainer, then AudioCodec. The
/stream routes keep treating Container as the target format.

* refactor(jellyfin): let the stream decider resolve universal requests

streamUniversal matched the Container list itself with plain string equality
and then asked the legacy resolver for the source format. That skipped the
decider's container and codec aliases (mp4 vs m4a, ogg vs opus), and a
direct-playable source over the bitrate cap was transcoded to its own format
instead of the client's TranscodingContainer.

The shared part of ResolveRequest (server-side player override, player
MaxBitRate cap, decision to Request mapping) moves to a resolve helper, and a
new ResolveClientRequest exposes it for callers that build their own
ClientInfo. streamUniversal now turns Container into DirectPlayProfiles and
TranscodingContainer/AudioCodec into a transcoding profile, so the decision
uses the same rules as the Subsonic getTranscodeDecision path. streamFile and
the /stream routes share a serveStream helper, NewSessionInfo reads the clock
itself, and duplicate comments and tests are trimmed.
---
 core/stream/decider.go               |  1 +
 core/stream/legacy_client.go         | 77 ++++++++++++++++-----------
 core/stream/legacy_client_test.go    | 69 ++++++++++++++++++++++++
 server/jellyfin/api.go               |  2 +-
 server/jellyfin/auth.go              |  9 ++--
 server/jellyfin/auth_test.go         | 50 ++++++++++++++++--
 server/jellyfin/dto/dto.go           | 32 ++++++++++--
 server/jellyfin/dto/mappers.go       | 23 ++++++++
 server/jellyfin/e2e/browsing_test.go |  7 ++-
 server/jellyfin/items.go             | 25 ++++++++-
 server/jellyfin/items_test.go        | 17 ++++++
 server/jellyfin/stream.go            | 78 ++++++++++++++++++++--------
 server/jellyfin/stream_test.go       | 47 +++++++++++++++++
 server/subsonic/transcode_test.go    |  4 ++
 14 files changed, 375 insertions(+), 66 deletions(-)

diff --git a/core/stream/decider.go b/core/stream/decider.go
index 3c6b01e05..886898206 100644
--- a/core/stream/decider.go
+++ b/core/stream/decider.go
@@ -23,6 +23,7 @@ type TranscodeDecider interface {
 	CreateTranscodeParams(decision *TranscodeDecision) (string, error)
 	ResolveRequestFromToken(ctx context.Context, token string, mf *model.MediaFile, offset int) (Request, error)
 	ResolveRequest(ctx context.Context, mf *model.MediaFile, reqFormat string, reqBitRate int, offset int) Request
+	ResolveClientRequest(ctx context.Context, mf *model.MediaFile, clientInfo *ClientInfo, offset int) Request
 }
 
 func NewTranscodeDecider(ds model.DataStore, ff ffmpeg.FFmpeg) TranscodeDecider {
diff --git a/core/stream/legacy_client.go b/core/stream/legacy_client.go
index 652e42eba..5b732c3e2 100644
--- a/core/stream/legacy_client.go
+++ b/core/stream/legacy_client.go
@@ -73,37 +73,8 @@ func (s *deciderService) ResolveRequest(ctx context.Context, mf *model.MediaFile
 	}
 
 	clientInfo := buildLegacyClientInfo(mf, reqFormat, reqBitRate, playerMaxBitRate)
-
-	// Apply server-side player transcoding override before making the decision
-	if trc, ok := request.TranscodingFrom(ctx); ok && trc.TargetFormat != "" {
-		clientInfo = applyServerOverride(ctx, clientInfo, &trc)
-	} else if player, ok := request.PlayerFrom(ctx); ok {
-		modified := *clientInfo
-		if modified.CapBitrate(player.MaxBitRate) {
-			clientInfo = &modified
-			log.Debug(ctx, "Applied player MaxBitRate cap", "playerMaxBitRate", player.MaxBitRate, "client", clientInfo.Name)
-		}
-	}
-
-	decision, err := s.MakeDecision(ctx, mf, clientInfo, TranscodeOptions{SkipProbe: true})
-	if err != nil {
-		log.Error(ctx, "Error making transcode decision, falling back to raw", "id", mf.ID, err)
-		req.Format = "raw"
-		return req
-	}
-
-	if decision.CanDirectPlay {
-		req.Format = "raw"
-		return req
-	}
-
-	if decision.CanTranscode {
-		req.Format = decision.TargetFormat
-		req.BitRate = decision.TargetBitrate
-		req.SampleRate = decision.TargetSampleRate
-		req.BitDepth = decision.TargetBitDepth
-		req.Channels = decision.TargetChannels
-		return req
+	if resolved, ok := s.resolve(ctx, mf, clientInfo, offset); ok {
+		return resolved
 	}
 
 	// No compatible profile for the requested format — retry with DefaultDownsamplingFormat
@@ -119,3 +90,47 @@ func (s *deciderService) ResolveRequest(ctx context.Context, mf *model.MediaFile
 	req.Format = "raw"
 	return req
 }
+
+// ResolveClientRequest resolves a stream request for a client that declared its own direct play
+// and transcoding profiles, falling back to raw when none fits.
+func (s *deciderService) ResolveClientRequest(ctx context.Context, mf *model.MediaFile, clientInfo *ClientInfo, offset int) Request {
+	if req, ok := s.resolve(ctx, mf, clientInfo, offset); ok {
+		return req
+	}
+	return Request{Format: "raw", Offset: offset}
+}
+
+// resolve applies the server-side player overrides to clientInfo and maps the decision to a
+// Request. ok is false when no profile fits.
+func (s *deciderService) resolve(ctx context.Context, mf *model.MediaFile, clientInfo *ClientInfo, offset int) (Request, bool) {
+	req := Request{Offset: offset}
+	if trc, ok := request.TranscodingFrom(ctx); ok && trc.TargetFormat != "" {
+		clientInfo = applyServerOverride(ctx, clientInfo, &trc)
+	} else if player, ok := request.PlayerFrom(ctx); ok {
+		modified := *clientInfo
+		if modified.CapBitrate(player.MaxBitRate) {
+			clientInfo = &modified
+			log.Debug(ctx, "Applied player MaxBitRate cap", "playerMaxBitRate", player.MaxBitRate, "client", clientInfo.Name)
+		}
+	}
+
+	decision, err := s.MakeDecision(ctx, mf, clientInfo, TranscodeOptions{SkipProbe: true})
+	if err != nil {
+		log.Error(ctx, "Error making transcode decision, falling back to raw", "id", mf.ID, err)
+		req.Format = "raw"
+		return req, true
+	}
+	switch {
+	case decision.CanDirectPlay:
+		req.Format = "raw"
+	case decision.CanTranscode:
+		req.Format = decision.TargetFormat
+		req.BitRate = decision.TargetBitrate
+		req.SampleRate = decision.TargetSampleRate
+		req.BitDepth = decision.TargetBitDepth
+		req.Channels = decision.TargetChannels
+	default:
+		return req, false
+	}
+	return req, true
+}
diff --git a/core/stream/legacy_client_test.go b/core/stream/legacy_client_test.go
index bc8405976..ad3417faf 100644
--- a/core/stream/legacy_client_test.go
+++ b/core/stream/legacy_client_test.go
@@ -414,3 +414,72 @@ var _ = Describe("ResolveRequest", func() {
 		})
 	})
 })
+
+var _ = Describe("ResolveClientRequest", func() {
+	var (
+		svc TranscodeDecider
+		ctx context.Context
+	)
+	mp3Target := []Profile{{Container: "mp3", AudioCodec: "mp3", Protocol: ProtocolHTTP}}
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+		ds := &tests.MockDataStore{
+			MockedProperty:    &tests.MockedPropertyRepo{},
+			MockedTranscoding: &tests.MockTranscodingRepo{},
+		}
+		auth.Init(ds)
+		svc = NewTranscodeDecider(ds, tests.NewMockFFmpeg(""))
+	})
+
+	It("direct plays a source matching a profile through container aliases", func() {
+		mf := withProbe(&model.MediaFile{ID: "1", Suffix: "m4a", Codec: "AAC", BitRate: 256, Channels: 2, SampleRate: 44100})
+		ci := &ClientInfo{
+			DirectPlayProfiles:  []DirectPlayProfile{{Containers: []string{"mp4"}, AudioCodecs: []string{"aac"}}},
+			TranscodingProfiles: mp3Target,
+		}
+
+		req := svc.ResolveClientRequest(ctx, mf, ci, 5)
+
+		Expect(req.Format).To(Equal("raw"))
+		Expect(req.Offset).To(Equal(5))
+	})
+
+	It("transcodes to the client's transcoding profile when no direct play profile matches", func() {
+		mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 2, SampleRate: 44100, BitDepth: new(16)})
+		ci := &ClientInfo{
+			DirectPlayProfiles:  []DirectPlayProfile{{Containers: []string{"mp3"}}},
+			TranscodingProfiles: mp3Target,
+		}
+
+		Expect(svc.ResolveClientRequest(ctx, mf, ci, 0).Format).To(Equal("mp3"))
+	})
+
+	It("transcodes a direct-playable source over the bitrate cap to the client's target", func() {
+		mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 2, SampleRate: 44100, BitDepth: new(16)})
+		ci := &ClientInfo{
+			MaxAudioBitrate:     128,
+			DirectPlayProfiles:  []DirectPlayProfile{{Containers: []string{"flac"}}},
+			TranscodingProfiles: mp3Target,
+		}
+
+		req := svc.ResolveClientRequest(ctx, mf, ci, 0)
+
+		Expect(req.Format).To(Equal("mp3"))
+		Expect(req.BitRate).To(Equal(128))
+	})
+
+	It("applies the player's MaxBitRate cap", func() {
+		mf := withProbe(&model.MediaFile{ID: "1", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 2, SampleRate: 44100, BitDepth: new(16)})
+		ctx = request.WithPlayer(ctx, model.Player{MaxBitRate: 192})
+		ci := &ClientInfo{
+			DirectPlayProfiles:  []DirectPlayProfile{{Containers: []string{"flac"}}},
+			TranscodingProfiles: mp3Target,
+		}
+
+		req := svc.ResolveClientRequest(ctx, mf, ci, 0)
+
+		Expect(req.Format).To(Equal("mp3"))
+		Expect(req.BitRate).To(Equal(192))
+	})
+})
diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index a4a1ee367..839c43ea5 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -165,7 +165,7 @@ func (api *Router) routes() http.Handler {
 
 		r.Get("/audio/{itemId}/stream", api.streamAudio)
 		r.Get("/audio/{itemId}/stream.{container}", api.streamAudio)
-		r.Get("/audio/{itemId}/universal", api.streamAudio)
+		r.Get("/audio/{itemId}/universal", api.streamUniversal)
 		r.Get("/audio/{itemId}/main.m3u8", api.streamHls)
 		r.Get("/items/{itemId}/playbackinfo", api.getPlaybackInfo)
 		r.Post("/items/{itemId}/playbackinfo", api.getPlaybackInfo)
diff --git a/server/jellyfin/auth.go b/server/jellyfin/auth.go
index e7070d341..bfcfab319 100644
--- a/server/jellyfin/auth.go
+++ b/server/jellyfin/auth.go
@@ -42,12 +42,13 @@ func (api *Router) authenticateByName(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// SessionInfo is omitted, not partially filled: a stub {Id, UserId} could fail a strict client's
-	// parse, and Finamp's login doesn't need it (its AuthenticationResult.sessionInfo is nullable).
+	a := parseMediaBrowserAuth(r)
+	serverID := api.serverID(ctx)
 	api.ok(w, r, dto.AuthenticationResult{
-		User:        userToDto(usr, api.serverName(), api.serverID(ctx)),
+		User:        userToDto(usr, api.serverName(), serverID),
+		SessionInfo: dto.NewSessionInfo(usr, a.Client, a.DeviceId, a.Device, a.Version, serverID),
 		AccessToken: token,
-		ServerId:    api.serverID(ctx),
+		ServerId:    serverID,
 	})
 }
 
diff --git a/server/jellyfin/auth_test.go b/server/jellyfin/auth_test.go
index 577677643..0821614d6 100644
--- a/server/jellyfin/auth_test.go
+++ b/server/jellyfin/auth_test.go
@@ -48,10 +48,54 @@ var _ = Describe("AuthenticateByName", func() {
 		Expect(res.User.Policy.EnableAllFolders).To(BeTrue())
 		Expect(res.User.Policy.EnableMediaPlayback).To(BeTrue())
 		Expect(res.User.Configuration).ToNot(BeNil())
+	})
 
-		// Ours is a partial SessionInfo; a strict client may fail to parse it, and Finamp's
-		// login doesn't require it, so it should be omitted entirely rather than sent partial.
-		Expect(res.SessionInfo).To(BeNil())
+	Describe("SessionInfo", func() {
+		login := func(authHeader string) map[string]any {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("POST", "/Users/AuthenticateByName",
+				strings.NewReader(`{"Username":"alice","Pw":"secret"}`))
+			r.Header.Set("Authorization", authHeader)
+			api.authenticateByName(w, r)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			var raw map[string]any
+			Expect(json.Unmarshal(w.Body.Bytes(), &raw)).To(Succeed())
+			Expect(raw).To(HaveKey("SessionInfo"))
+			return raw["SessionInfo"].(map[string]any)
+		}
+		const jellybox = `MediaBrowser Client="JellyBox", Device="Mac", DeviceId="dev-1", Version="2.1"`
+
+		It("has the fields strict clients require", func() {
+			s := login(jellybox)
+			Expect(s["Id"]).To(And(BeAssignableToTypeOf(""), Not(BeEmpty())))
+			Expect(s["UserId"]).To(Equal(dto.EncodeID(testID("u1"))))
+			Expect(s["LastActivityDate"]).To(And(BeAssignableToTypeOf(""), Not(BeEmpty())))
+			for _, k := range []string{"SupportsRemoteControl", "SupportsMediaControl", "HasCustomDeviceName"} {
+				Expect(s[k]).To(BeAssignableToTypeOf(false), k)
+			}
+			ps, ok := s["PlayState"].(map[string]any)
+			Expect(ok).To(BeTrue())
+			for _, k := range []string{"CanSeek", "IsPaused", "IsMuted"} {
+				Expect(ps[k]).To(BeAssignableToTypeOf(false), k)
+			}
+		})
+
+		It("describes the calling client", func() {
+			s := login(jellybox)
+			Expect(s).To(HaveKeyWithValue("UserName", "alice"))
+			Expect(s).To(HaveKeyWithValue("Client", "JellyBox"))
+			Expect(s).To(HaveKeyWithValue("DeviceName", "Mac"))
+			Expect(s).To(HaveKeyWithValue("DeviceId", "dev-1"))
+			Expect(s).To(HaveKeyWithValue("ApplicationVersion", "2.1"))
+			Expect(s).To(HaveKeyWithValue("IsActive", true))
+		})
+
+		It("keeps the same Id for the same device, and a new one for another device", func() {
+			first := login(jellybox)["Id"]
+			Expect(login(jellybox)["Id"]).To(Equal(first))
+			other := login(`MediaBrowser Client="JellyBox", Device="Mac", DeviceId="dev-2", Version="2.1"`)
+			Expect(other["Id"]).ToNot(Equal(first))
+		})
 	})
 
 	It("records the login time, like the web UI login does", func() {
diff --git a/server/jellyfin/dto/dto.go b/server/jellyfin/dto/dto.go
index 6d867ed21..21e3903f2 100644
--- a/server/jellyfin/dto/dto.go
+++ b/server/jellyfin/dto/dto.go
@@ -202,14 +202,40 @@ type UserConfiguration struct {
 	CastReceiverId             string   `json:"CastReceiverId"`
 }
 
+// SessionInfo mirrors real Jellyfin's SessionInfoDto. JellyBox requires Id and PlayState, and Finamp
+// requires UserId, LastActivityDate and the bools, so none of those may be omitted.
 type SessionInfo struct {
-	Id     string `json:"Id"`
-	UserId string `json:"UserId"`
+	Id                    string          `json:"Id"`
+	UserId                string          `json:"UserId"`
+	UserName              string          `json:"UserName"`
+	Client                string          `json:"Client"`
+	DeviceId              string          `json:"DeviceId"`
+	DeviceName            string          `json:"DeviceName"`
+	ApplicationVersion    string          `json:"ApplicationVersion"`
+	ServerId              string          `json:"ServerId"`
+	LastActivityDate      string          `json:"LastActivityDate"`
+	IsActive              bool            `json:"IsActive"`
+	SupportsMediaControl  bool            `json:"SupportsMediaControl"`
+	SupportsRemoteControl bool            `json:"SupportsRemoteControl"`
+	HasCustomDeviceName   bool            `json:"HasCustomDeviceName"`
+	PlayableMediaTypes    []string        `json:"PlayableMediaTypes"`
+	SupportedCommands     []string        `json:"SupportedCommands"`
+	AdditionalUsers       []any           `json:"AdditionalUsers"`
+	NowPlayingQueue       []any           `json:"NowPlayingQueue"`
+	PlayState             PlayerStateInfo `json:"PlayState"`
+}
+
+type PlayerStateInfo struct {
+	CanSeek       bool   `json:"CanSeek"`
+	IsPaused      bool   `json:"IsPaused"`
+	IsMuted       bool   `json:"IsMuted"`
+	RepeatMode    string `json:"RepeatMode"`
+	PlaybackOrder string `json:"PlaybackOrder"`
 }
 
 type AuthenticationResult struct {
 	User        *UserDto     `json:"User"`
-	SessionInfo *SessionInfo `json:"SessionInfo,omitempty"`
+	SessionInfo *SessionInfo `json:"SessionInfo"`
 	AccessToken string       `json:"AccessToken"`
 	ServerId    string       `json:"ServerId"`
 }
diff --git a/server/jellyfin/dto/mappers.go b/server/jellyfin/dto/mappers.go
index 0c9199066..bb17b40c7 100644
--- a/server/jellyfin/dto/mappers.go
+++ b/server/jellyfin/dto/mappers.go
@@ -7,6 +7,7 @@ import (
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
@@ -446,3 +447,25 @@ func LyricDtoFromLyrics(mf model.MediaFile, lyrics model.Lyrics) LyricDto {
 	}
 	return d
 }
+
+// NewSessionInfo's Id is stable per client install, as Jellyfin reuses a device's session across logins.
+func NewSessionInfo(u *model.User, client, deviceID, deviceName, version, serverID string) *SessionInfo {
+	now := time.Now()
+	return &SessionInfo{
+		Id:                 EncodeID(id.NewHash(client, deviceID)),
+		UserId:             EncodeID(u.ID),
+		UserName:           u.UserName,
+		Client:             client,
+		DeviceId:           deviceID,
+		DeviceName:         deviceName,
+		ApplicationVersion: version,
+		ServerId:           serverID,
+		LastActivityDate:   jellyfinDate(&now),
+		IsActive:           true,
+		PlayableMediaTypes: []string{"Audio"},
+		SupportedCommands:  []string{},
+		AdditionalUsers:    []any{},
+		NowPlayingQueue:    []any{},
+		PlayState:          PlayerStateInfo{RepeatMode: "RepeatNone", PlaybackOrder: "Default"},
+	}
+}
diff --git a/server/jellyfin/e2e/browsing_test.go b/server/jellyfin/e2e/browsing_test.go
index 111e246fd..68d87cd25 100644
--- a/server/jellyfin/e2e/browsing_test.go
+++ b/server/jellyfin/e2e/browsing_test.go
@@ -119,9 +119,14 @@ var _ = Describe("Browsing", func() {
 				Expect(q.Items).To(BeEmpty())
 			},
 			Entry("a Jellyfin kind Navidrome has none of", "Boxset"),
-			Entry("a name Jellyfin does not know either", "Nonsense"),
 		)
 
+		It("treats a name Jellyfin does not know as an absent IncludeItemTypes", func() {
+			q := queryResult(get("/Items?IncludeItemTypes=Nonsense&Recursive=true"))
+			Expect(q.TotalRecordCount).To(Equal(queryResult(get("/Items?Recursive=true")).TotalRecordCount))
+			Expect(q.TotalRecordCount).To(BeNumerically(">", 0))
+		})
+
 		// A strict client (Manet) fails its whole sync on the first item missing any of these.
 		DescribeTable("sends the keys Jellyfin puts on every item",
 			func(itemType string, fields string, nonNull ...string) {
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index 9ed3d2c8d..124d17920 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -349,7 +349,7 @@ func (api *Router) parseItemsQuery(ctx context.Context, r *http.Request) (itemsQ
 	}
 	q := listParams(p)
 	q.ids = ids
-	q.rawTypes = p.StringOr("includeitemtypes", "")
+	q.rawTypes = knownItemKinds(p.StringOr("includeitemtypes", ""))
 	q.parentId = parentId
 	q.genreIds = genreIds
 	q.albumIds = albumIds
@@ -593,6 +593,29 @@ var supportedTypes = map[string]string{
 	"audio": "Audio", "musicartist": "MusicArtist", "musicalbum": "MusicAlbum", "musicgenre": "MusicGenre", "playlist": "Playlist",
 }
 
+// jellyfinItemKinds lists Jellyfin's BaseItemKind names, lowercased.
+var jellyfinItemKinds = map[string]bool{
+	"aggregatefolder": true, "audio": true, "audiobook": true, "basepluginfolder": true, "book": true,
+	"boxset": true, "channel": true, "channelfolderitem": true, "collectionfolder": true, "episode": true,
+	"folder": true, "genre": true, "manualplaylistsfolder": true, "movie": true, "livetvchannel": true,
+	"livetvprogram": true, "musicalbum": true, "musicartist": true, "musicgenre": true, "musicvideo": true,
+	"person": true, "photo": true, "photoalbum": true, "playlist": true, "playlistsfolder": true,
+	"program": true, "recording": true, "season": true, "series": true, "studio": true, "trailer": true,
+	"tvchannel": true, "tvprogram": true, "userrootfolder": true, "userview": true, "video": true, "year": true,
+}
+
+// knownItemKinds drops IncludeItemTypes entries that aren't BaseItemKind names, as Jellyfin's binder
+// does, so an all-unknown list (JellyBox sends "music") behaves like an absent one.
+func knownItemKinds(types string) string {
+	var known []string
+	for t := range strings.SplitSeq(types, ",") {
+		if t = strings.TrimSpace(t); jellyfinItemKinds[strings.ToLower(t)] {
+			known = append(known, t)
+		}
+	}
+	return strings.Join(known, ",")
+}
+
 // parseTypes returns the supported entries in IncludeItemTypes in order. Only an absent param
 // defaults to albums, so ParentId=<artistId> still browses that artist's albums.
 func parseTypes(types string) []string {
diff --git a/server/jellyfin/items_test.go b/server/jellyfin/items_test.go
index c92c011fe..a8dfb7bb2 100644
--- a/server/jellyfin/items_test.go
+++ b/server/jellyfin/items_test.go
@@ -74,6 +74,18 @@ var _ = Describe("Items", func() {
 			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
 		})
 
+		It("ignores IncludeItemTypes names that aren't Jellyfin item kinds", func() {
+			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", AlbumID: testID("a1")}})
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("a1"))+"&IncludeItemTypes=music", nil).WithContext(ctxUser())
+			invoke(api.getItems, w, r)
+			var res dto.QueryResult
+			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+			Expect(res.Items).To(HaveLen(1))
+			Expect(res.Items[0].Id).To(Equal(dto.EncodeID(testID("s1"))))
+		})
+
 		It("lists a playlist's tracks when ParentId is a playlist, whatever the type", func() {
 			fp.getPls = &model.Playlist{ID: testID("pl1"), Tracks: model.PlaylistTracks{
 				{ID: "1", MediaFileID: testID("s1"), PlaylistID: testID("pl1"), MediaFile: model.MediaFile{ID: testID("s1")}},
@@ -1135,6 +1147,11 @@ var _ = Describe("Items", func() {
 			Expect(parseTypes("BoxSet,Movie")).To(BeEmpty())
 		})
 
+		It("drops names that aren't Jellyfin item kinds, case-insensitively", func() {
+			Expect(knownItemKinds("music")).To(BeEmpty())
+			Expect(knownItemKinds("music, audio,MUSICVIDEO")).To(Equal("audio,MUSICVIDEO"))
+		})
+
 		It("defaults to albums only when IncludeItemTypes is absent", func() {
 			Expect(parseTypes("")).To(Equal([]string{"MusicAlbum"}))
 			Expect(parseTypes("Nonsense")).To(BeEmpty())
diff --git a/server/jellyfin/stream.go b/server/jellyfin/stream.go
index 87660056c..c6dc0c80e 100644
--- a/server/jellyfin/stream.go
+++ b/server/jellyfin/stream.go
@@ -1,6 +1,7 @@
 package jellyfin
 
 import (
+	"cmp"
 	"fmt"
 	"math"
 	"net/http"
@@ -10,6 +11,7 @@ import (
 	"strings"
 
 	"github.com/go-chi/chi/v5"
+	"github.com/navidrome/navidrome/core/stream"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -65,16 +67,14 @@ func (api *Router) getPlaybackInfo(w http.ResponseWriter, r *http.Request) {
 	api.ok(w, r, dto.PlaybackInfoResponse{MediaSources: []dto.MediaSourceInfo{src}, PlaySessionId: dto.EncodeID(mf.ID)})
 }
 
-// streamAudio serves /Audio/{itemId}/stream[.container] and /Audio/{itemId}/universal,
-// reusing the same transcode-decision + streaming pipeline as the Subsonic /stream endpoint.
+// streamAudio serves /Audio/{itemId}/stream[.container], reusing the same transcode-decision +
+// streaming pipeline as the Subsonic /stream endpoint.
 func (api *Router) streamAudio(w http.ResponseWriter, r *http.Request) {
 	mf, ok := api.mediaFileForRequest(w, r)
 	if !ok {
 		return
 	}
-	ctx := r.Context()
 	p := req.Params(r)
-
 	format := p.StringOr("container", "")
 	if format == "" {
 		// The /stream.{container} route form carries the format as a path segment, not a query param.
@@ -84,17 +84,61 @@ func (api *Router) streamAudio(w http.ResponseWriter, r *http.Request) {
 		// Jellyfin's audioCodec param names the target codec when no container is given.
 		format = p.StringOr("audiocodec", "")
 	}
+	api.serveAudio(w, r, mf, format)
+}
+
+// streamUniversal serves /Audio/{itemId}/universal, where Container lists the "container|codec"
+// entries the client direct-plays, and TranscodingContainer/AudioCodec name the fallback target.
+func (api *Router) streamUniversal(w http.ResponseWriter, r *http.Request) {
+	mf, ok := api.mediaFileForRequest(w, r)
+	if !ok {
+		return
+	}
+	p := req.Params(r)
+	var streamReq stream.Request
 	if p.BoolOr("static", false) {
+		streamReq = api.transcodeDecider.ResolveRequest(r.Context(), mf, "raw", 0, 0)
+	} else {
+		streamReq = api.transcodeDecider.ResolveClientRequest(r.Context(), mf, universalClientInfo(p), 0)
+	}
+	api.serveStream(w, r, mf, streamReq)
+}
+
+func universalClientInfo(p *req.Values) *stream.ClientInfo {
+	ci := &stream.ClientInfo{Name: "jellyfin-universal", MaxAudioBitrate: bitRateParam(p)}
+	for entry := range strings.SplitSeq(p.StringOr("container", ""), ",") {
+		container, codec, _ := strings.Cut(strings.TrimSpace(entry), "|")
+		if container == "" {
+			continue
+		}
+		profile := stream.DirectPlayProfile{Containers: []string{container}, Protocols: []string{stream.ProtocolHTTP}}
+		if codec != "" {
+			profile.AudioCodecs = []string{codec}
+		}
+		ci.DirectPlayProfiles = append(ci.DirectPlayProfiles, profile)
+	}
+	codec := p.StringOr("audiocodec", "")
+	if container := cmp.Or(p.StringOr("transcodingcontainer", ""), codec); container != "" {
+		ci.TranscodingProfiles = []stream.Profile{{Container: container, AudioCodec: cmp.Or(codec, container), Protocol: stream.ProtocolHTTP}}
+		ci.MaxTranscodingAudioBitrate = ci.MaxAudioBitrate
+	}
+	return ci
+}
+
+// bitRateParam reads Jellyfin's bits/sec bitrate params as the kbps the stream package expects.
+func bitRateParam(p *req.Values) int {
+	return cmp.Or(p.IntOr("audiobitrate", 0), p.IntOr("maxstreamingbitrate", 0)) / 1000
+}
+
+func (api *Router) serveAudio(w http.ResponseWriter, r *http.Request, mf *model.MediaFile, format string) {
+	if req.Params(r).BoolOr("static", false) {
 		format = "raw"
 	}
+	api.serveStream(w, r, mf, api.transcodeDecider.ResolveRequest(r.Context(), mf, format, bitRateParam(req.Params(r)), 0))
+}
 
-	// Bitrate params are bits/sec by Jellyfin convention; ResolveRequest expects kbps.
-	bitRate := p.IntOr("audiobitrate", 0) / 1000
-	if bitRate == 0 {
-		bitRate = p.IntOr("maxstreamingbitrate", 0) / 1000
-	}
-
-	streamReq := api.transcodeDecider.ResolveRequest(ctx, mf, format, bitRate, 0)
+func (api *Router) serveStream(w http.ResponseWriter, r *http.Request, mf *model.MediaFile, streamReq stream.Request) {
+	ctx := r.Context()
 	s, err := api.streamer.NewStream(ctx, mf, streamReq)
 	if err != nil {
 		api.internalError(w, r, err)
@@ -160,15 +204,5 @@ func (api *Router) streamFile(w http.ResponseWriter, r *http.Request) {
 	if !ok {
 		return
 	}
-	ctx := r.Context()
-	streamReq := api.transcodeDecider.ResolveRequest(ctx, mf, "raw", 0, 0)
-	s, err := api.streamer.NewStream(ctx, mf, streamReq)
-	if err != nil {
-		api.internalError(w, r, err)
-		return
-	}
-	defer s.Close()
-	if _, err := s.Serve(ctx, w, r); err != nil {
-		log.Error(ctx, "Jellyfin API: error streaming", "id", mf.ID, err)
-	}
+	api.serveStream(w, r, mf, api.transcodeDecider.ResolveRequest(r.Context(), mf, "raw", 0, 0))
 }
diff --git a/server/jellyfin/stream_test.go b/server/jellyfin/stream_test.go
index d6220d33f..3cd692c1b 100644
--- a/server/jellyfin/stream_test.go
+++ b/server/jellyfin/stream_test.go
@@ -244,6 +244,45 @@ var _ = Describe("Stream", func() {
 		})
 	})
 
+	Describe("streamUniversal", func() {
+		universal := func(query string) {
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+				{ID: testID("s1"), Suffix: "mp3", LibraryID: 1},
+			})
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("GET", "/Audio/"+dto.EncodeID(testID("s1"))+"/universal?"+query, nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
+			invoke(api.streamUniversal, w, r)
+			Expect(w.Code).To(Equal(http.StatusOK))
+		}
+
+		It("turns Container into direct play profiles and TranscodingContainer into the target", func() {
+			universal("Container=mp3,m4a|aac&TranscodingContainer=m4a&AudioCodec=aac&MaxStreamingBitrate=128000")
+			Expect(decider.client.DirectPlayProfiles).To(Equal([]stream.DirectPlayProfile{
+				{Containers: []string{"mp3"}, Protocols: []string{stream.ProtocolHTTP}},
+				{Containers: []string{"m4a"}, AudioCodecs: []string{"aac"}, Protocols: []string{stream.ProtocolHTTP}},
+			}))
+			Expect(decider.client.TranscodingProfiles).To(Equal([]stream.Profile{
+				{Container: "m4a", AudioCodec: "aac", Protocol: stream.ProtocolHTTP},
+			}))
+			Expect(decider.client.MaxAudioBitrate).To(Equal(128))
+			Expect(decider.client.MaxTranscodingAudioBitrate).To(Equal(128))
+		})
+
+		It("uses AudioCodec as the target when no TranscodingContainer is given", func() {
+			universal("Container=mp3&AudioCodec=aac")
+			Expect(decider.client.TranscodingProfiles).To(Equal([]stream.Profile{
+				{Container: "aac", AudioCodec: "aac", Protocol: stream.ProtocolHTTP},
+			}))
+		})
+
+		It("serves the file as is for static=true", func() {
+			universal("static=true&Container=ogg")
+			Expect(decider.req.Format).To(Equal("raw"))
+			Expect(decider.client).To(BeNil())
+		})
+	})
+
 	Describe("streamHls", func() {
 		BeforeEach(func() {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
@@ -364,6 +403,7 @@ var _ = Describe("Stream", func() {
 type fakeTranscodeDecider struct {
 	invoked bool
 	req     stream.Request
+	client  *stream.ClientInfo
 }
 
 func (f *fakeTranscodeDecider) MakeDecision(context.Context, *model.MediaFile, *stream.ClientInfo, stream.TranscodeOptions) (*stream.TranscodeDecision, error) {
@@ -384,6 +424,13 @@ func (f *fakeTranscodeDecider) ResolveRequest(_ context.Context, _ *model.MediaF
 	return f.req
 }
 
+func (f *fakeTranscodeDecider) ResolveClientRequest(_ context.Context, _ *model.MediaFile, ci *stream.ClientInfo, offset int) stream.Request {
+	f.invoked = true
+	f.client = ci
+	f.req = stream.Request{Offset: offset}
+	return f.req
+}
+
 // fakeMediaStreamer is a local test double for stream.MediaStreamer: it records whether
 // NewStream was invoked and, on success, returns a real (non-seekable) *stream.Stream backed
 // by an in-memory reader, so streamAudio's call to Stream.Serve exercises real code.
diff --git a/server/subsonic/transcode_test.go b/server/subsonic/transcode_test.go
index 0f3c24832..1f2fdfcef 100644
--- a/server/subsonic/transcode_test.go
+++ b/server/subsonic/transcode_test.go
@@ -625,6 +625,10 @@ func (m *mockTranscodeDecision) ResolveRequest(_ context.Context, _ *model.Media
 	return stream.Request{Format: "raw"}
 }
 
+func (m *mockTranscodeDecision) ResolveClientRequest(context.Context, *model.MediaFile, *stream.ClientInfo, int) stream.Request {
+	return stream.Request{Format: "raw"}
+}
+
 func (m *mockTranscodeDecision) CreateTranscodeParams(_ *stream.TranscodeDecision) (string, error) {
 	return m.token, m.tokenErr
 }

From 549dfa7f3027a325905791626820a46f2b0afb28 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 19 Sep 2026 13:19:48 -0400
Subject: [PATCH 149/200] feat(jellyfin): advertise Jellyfin 12.1.0 and add the
 missing 12.x quick wins (#6163)

* feat(jellyfin): advertise Jellyfin server version 12.1.0

Streamyfin, jellyfin-android and jellyfin-androidtv refuse servers older than
10.10, Swiftfin warns below 12.0, and @jellyfin/sdk flags anything below its
minimum as unsupported, so 10.9.11 locked those clients out. 12.1.0 is the
current Jellyfin release (after 10.11 Jellyfin renumbered to 12.0). No client
checked has an upper bound or assumes the major is 10, and the value keeps
three parts because the Kotlin SDK and Swiftfin reject two-part versions.

* feat(jellyfin): acknowledge POST /Sessions/Playing/Ping

Jellyfin clients ping this endpoint to keep a transcode job alive while
paused. Navidrome ties transcodes to the stream request, so there is nothing
to keep alive; answer 204 like Jellyfin instead of a 404. It shares one no-op
handler with Sessions/Capabilities, renamed to acknowledge.

* feat(jellyfin): reorder playlist entries via Items/{entryId}/Move

Adds POST /Playlists/{id}/Items/{entryId}/Move/{newIndex}, which clients use
to reorder playlists. It maps the entry's PlaylistItemId (its position) and
Jellyfin's zero-based newIndex onto the existing core ReorderTrack, which
enforces ownership. As in Jellyfin, an index past the end appends and an
unknown entry is a no-op; out-of-range positions never reach Reorder, which
would otherwise shift unrelated rows.

* feat(jellyfin): honor position when adding items to a playlist

POST /Playlists/{id}/Items takes an optional zero-based position (added to
the Jellyfin spec in 12.0). Match Jellyfin: zero or negative prepends, past
the end appends, otherwise the new items are inserted at that index in the
order they were added.

Adds PlaylistTrackRepository.Insert and core playlists.InsertTracks, which
shift the following entries and insert in one transaction, instead of
appending and moving each new track with its own ReorderTrack call.

* feat(jellyfin): add type-specific InstantMix routes

Jellyfin exposes InstantMix under Songs/, Albums/, Artists/ and Playlists/
as well as Items/, plus the legacy Artists/InstantMix and
MusicGenres/InstantMix forms that take the seed as ?id=. Clients generated
from the Jellyfin SDKs call the type-specific routes, which 404ed. All of them
now share the existing Items/{id}/InstantMix handler; the external provider
already builds mixes from song, album, artist, playlist and genre seeds.

* feat(jellyfin): honor Width, Height and Fill* image size params

The image endpoint only read MaxWidth/MaxHeight, so clients that size covers
with fillWidth/fillHeight (Manet, Finamp) or width/height got the full-size
original on a cold artwork cache: a 578 KB PNG instead of a 13 KB resize.
Jellyfin applies Width/Height, caps them with MaxWidth/MaxHeight, then
shrinks to the smallest size that still covers the Fill box. Navidrome
resizes on one dimension, so the tightest bound wins and a fill box counts
as its larger side.

* feat(jellyfin): answer HEAD on audio, file and image routes

Fintunes sends HEAD to /Audio/{id}/universal to read the content type and
detect direct play (a Content-Length means direct play), and to the audio and
image URLs before a download, aborting the download when it fails. Those routes
were GET-only, so HEAD got a 404. HEAD now reuses the GET handlers. Direct
play goes through Stream.Serve, which already answers HEAD; a transcode
answers with the target content type and no length without starting ffmpeg,
so a probe never costs a transcode.

* fix(jellyfin): clamp playlist move and insert positions before adding one

movePlaylistItem computed min(newIndex+1, SongCount): newIndex=MaxInt wrapped
to a negative position, and Reorder then left the playlist with a gap
(positions 2, 3, 999998), making the moved entry unmovable. Clamp against the
playlist length first. addToPlaylist's min(position, MaxInt32)+1 wrapped on
32-bit builds and req.Int truncated large values there, so a far-past-the-end
position prepended; parse as int64 and clamp before converting.

* fix(playlists): validate reorder positions inside the write transaction

Reorder never checked its positions, so a source outside the playlist or a
destination past its end shifted rows around a missing entry and left a gap
(e.g. ids 1 and 3), which made the moved entry unmovable afterwards. The
Jellyfin Move handler guarded this with a SongCount read before ReorderTrack,
but a concurrent removal between the two reopened it, and the native API
reorder endpoint passed client positions through unchecked.

Reorder now reads the last position in the same transaction, returns
ErrNotFound for a source outside the playlist and clamps the destination.
ReorderTrack uses an immediate transaction so that read and the updates are
atomic against other writers. The Jellyfin handler drops its pre-check and
maps ErrNotFound to Jellyfin's no-op 204; the native API now answers 404 for
an unknown track instead of corrupting the order.
---
 core/playlists/playlists.go                   | 19 +++-
 core/playlists/playlists_test.go              | 37 +++++++
 model/playlist.go                             |  1 +
 persistence/playlist_track_repository.go      | 35 ++++++-
 persistence/playlist_track_repository_test.go | 99 +++++++++++++++++++
 server/jellyfin/README.md                     | 10 +-
 server/jellyfin/api.go                        | 20 +++-
 server/jellyfin/e2e/images_test.go            |  4 +
 server/jellyfin/e2e/playlists_test.go         | 83 ++++++++++++++++
 server/jellyfin/e2e/sessions_test.go          |  4 +
 server/jellyfin/e2e/similar_test.go           | 29 ++++++
 server/jellyfin/e2e/streaming_test.go         | 14 +++
 server/jellyfin/images.go                     | 20 ++--
 server/jellyfin/images_test.go                | 11 ++-
 server/jellyfin/playlists.go                  | 52 +++++++++-
 server/jellyfin/playlists_test.go             | 12 +++
 server/jellyfin/sessions.go                   |  6 +-
 server/jellyfin/sessions_test.go              |  4 +-
 server/jellyfin/similar.go                    | 17 +++-
 server/jellyfin/stream.go                     |  9 ++
 server/jellyfin/stream_test.go                | 30 ++++++
 server/jellyfin/system.go                     |  7 +-
 tests/mock_playlist_track_repo.go             |  6 ++
 23 files changed, 497 insertions(+), 32 deletions(-)

diff --git a/core/playlists/playlists.go b/core/playlists/playlists.go
index 9ae8f09cb..1f8cc9581 100644
--- a/core/playlists/playlists.go
+++ b/core/playlists/playlists.go
@@ -32,6 +32,7 @@ type Playlists interface {
 
 	// Track management
 	AddTracks(ctx context.Context, playlistID string, ids []string) (int, error)
+	InsertTracks(ctx context.Context, playlistID string, ids []string, pos int) (int, error)
 	AddAlbums(ctx context.Context, playlistID string, albumIds []string) (int, error)
 	AddArtists(ctx context.Context, playlistID string, artistIds []string) (int, error)
 	AddDiscs(ctx context.Context, playlistID string, discs []model.DiscID) (int, error)
@@ -268,6 +269,22 @@ func (s *playlists) AddTracks(ctx context.Context, playlistID string, ids []stri
 	return s.ds.Playlist(ctx).Tracks(playlistID, false).Add(ids)
 }
 
+// InsertTracks adds tracks before the 1-based position pos; a position past the end appends.
+func (s *playlists) InsertTracks(ctx context.Context, playlistID string, ids []string, pos int) (int, error) {
+	if _, err := s.checkTracksEditable(ctx, playlistID); err != nil {
+		return 0, err
+	}
+	var count int
+	// Immediate: a deferred tx that reads before shifting fails at once with SQLITE_BUSY under
+	// concurrent writers instead of waiting for the lock.
+	err := s.ds.WithTxImmediate(func(tx model.DataStore) error {
+		var err error
+		count, err = tx.Playlist(ctx).Tracks(playlistID, false).Insert(ids, pos)
+		return err
+	})
+	return count, err
+}
+
 func (s *playlists) AddAlbums(ctx context.Context, playlistID string, albumIds []string) (int, error) {
 	if _, err := s.checkTracksEditable(ctx, playlistID); err != nil {
 		return 0, err
@@ -302,7 +319,7 @@ func (s *playlists) ReorderTrack(ctx context.Context, playlistID string, pos int
 	if _, err := s.checkTracksEditable(ctx, playlistID); err != nil {
 		return err
 	}
-	return s.ds.WithTx(func(tx model.DataStore) error {
+	return s.ds.WithTxImmediate(func(tx model.DataStore) error {
 		return tx.Playlist(ctx).Tracks(playlistID, false).Reorder(pos, newPos)
 	})
 }
diff --git a/core/playlists/playlists_test.go b/core/playlists/playlists_test.go
index dd182b3f1..dd6213555 100644
--- a/core/playlists/playlists_test.go
+++ b/core/playlists/playlists_test.go
@@ -324,6 +324,43 @@ var _ = Describe("Playlists", func() {
 		})
 	})
 
+	Describe("InsertTracks", func() {
+		var mockTracks *tests.MockPlaylistTrackRepo
+
+		BeforeEach(func() {
+			mockTracks = &tests.MockPlaylistTrackRepo{AddCount: 2}
+			mockPlsRepo.Data = map[string]*model.Playlist{
+				"pls-1": {ID: "pls-1", Name: "My Playlist", OwnerID: "user-1"},
+				"pls-smart": {ID: "pls-smart", Name: "Smart", OwnerID: "user-1",
+					Rules: &criteria.Criteria{Expression: criteria.Contains{"title": "test"}}},
+			}
+			mockPlsRepo.TracksRepo = mockTracks
+			ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
+		})
+
+		It("inserts the tracks at the given position for the owner", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+			count, err := ps.InsertTracks(ctx, "pls-1", []string{"song-1", "song-2"}, 3)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(count).To(Equal(2))
+			Expect(mockTracks.AddedIds).To(Equal([]string{"song-1", "song-2"}))
+			Expect(mockTracks.InsertPos).To(Equal(3))
+		})
+
+		It("denies non-owner, non-admin", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "other-user", IsAdmin: false})
+			_, err := ps.InsertTracks(ctx, "pls-1", []string{"song-1"}, 1)
+			Expect(err).To(MatchError(model.ErrNotAuthorized))
+			Expect(mockTracks.AddedIds).To(BeEmpty())
+		})
+
+		It("denies editing smart playlists", func() {
+			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
+			_, err := ps.InsertTracks(ctx, "pls-smart", []string{"song-1"}, 1)
+			Expect(err).To(MatchError(model.ErrPlaylistNotEditable))
+		})
+	})
+
 	Describe("ReorderTrack", func() {
 		var mockTracks *tests.MockPlaylistTrackRepo
 
diff --git a/model/playlist.go b/model/playlist.go
index abd11b8c4..f320d845b 100644
--- a/model/playlist.go
+++ b/model/playlist.go
@@ -184,6 +184,7 @@ type PlaylistTrackRepository interface {
 	GetAlbumIDs(options ...QueryOptions) ([]string, error)
 	GetMediaFileIDs(options ...QueryOptions) ([]string, error)
 	Add(mediaFileIds []string) (int, error)
+	Insert(mediaFileIds []string, pos int) (int, error)
 	AddAlbums(albumIds []string) (int, error)
 	AddArtists(artistIds []string) (int, error)
 	AddDiscs(discs []DiscID) (int, error)
diff --git a/persistence/playlist_track_repository.go b/persistence/playlist_track_repository.go
index cf1b8f3fa..847316868 100644
--- a/persistence/playlist_track_repository.go
+++ b/persistence/playlist_track_repository.go
@@ -195,6 +195,29 @@ func (r *playlistTrackRepository) Add(mediaFileIds []string) (int, error) {
 	return len(mediaFileIds), r.playlistRepo.addTracks(r.playlistId, int(res.Max.Int32+1), mediaFileIds)
 }
 
+// Insert adds tracks before the 1-based position pos, shifting the following entries down; a
+// position past the end appends. Callers must run it in a transaction.
+func (r *playlistTrackRepository) Insert(mediaFileIds []string, pos int) (int, error) {
+	if len(mediaFileIds) == 0 {
+		return 0, nil
+	}
+	pos = max(pos, 1)
+	n := len(mediaFileIds)
+	// Negate while shifting, so no intermediate row hits the unique (playlist_id, id) index.
+	_, err := r.executeSQL(Expr(`UPDATE playlist_tracks SET id = -(id + ?) WHERE playlist_id = ? AND id >= ?`, n, r.playlistId, pos))
+	if err != nil {
+		return 0, err
+	}
+	res, err := r.executeSQL(Expr(`UPDATE playlist_tracks SET id = -id WHERE playlist_id = ? AND id < 0`, r.playlistId))
+	if err != nil {
+		return 0, err
+	}
+	if res == 0 {
+		return r.Add(mediaFileIds)
+	}
+	return n, r.playlistRepo.addTracks(r.playlistId, pos, mediaFileIds)
+}
+
 func (r *playlistTrackRepository) addMediaFileIds(cond Sqlizer) (int, error) {
 	sq := Select("id").From("media_file").Where(cond).OrderBy("album_artist, album, release_date, disc_number, track_number")
 	var ids []string
@@ -247,8 +270,18 @@ func (r *playlistTrackRepository) DeleteAll() error {
 	return r.playlistRepo.renumber(r.playlistId)
 }
 
-// Reorder moves a track from pos to newPos, shifting other tracks accordingly.
+// Reorder moves a track from pos to newPos, shifting other tracks accordingly. newPos is clamped
+// to the playlist; a pos outside it is ErrNotFound, since shifting around it would leave a gap.
 func (r *playlistTrackRepository) Reorder(pos int, newPos int) error {
+	var res struct{ Max sql.NullInt32 }
+	if err := r.queryOne(r.newSelect().Columns("max(id) as max").Where(Eq{"playlist_id": r.playlistId}), &res); err != nil {
+		return err
+	}
+	last := int(res.Max.Int32)
+	if pos < 1 || pos > last {
+		return model.ErrNotFound
+	}
+	newPos = min(max(newPos, 1), last)
 	if pos == newPos {
 		return nil
 	}
diff --git a/persistence/playlist_track_repository_test.go b/persistence/playlist_track_repository_test.go
index 88ddbff48..e0360adb4 100644
--- a/persistence/playlist_track_repository_test.go
+++ b/persistence/playlist_track_repository_test.go
@@ -78,6 +78,105 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		})
 	})
 
+	Describe("Insert", func() {
+		var tracks model.PlaylistTrackRepository
+
+		BeforeEach(func() {
+			ctx := log.NewContext(GinkgoT().Context())
+			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+			plsRepo := NewPlaylistRepository(ctx, GetDBXBuilder())
+			pls := model.Playlist{Name: "Insert", OwnerID: "userid", OwnerName: "userid"}
+			Expect(plsRepo.Put(&pls)).To(Succeed())
+			DeferCleanup(func() { Expect(plsRepo.Delete(pls.ID)).To(Succeed()) })
+
+			tracks = plsRepo.Tracks(pls.ID, false)
+			Expect(tracks.Add([]string{songDayInALife.ID, songRadioactivity.ID})).To(Equal(2))
+		})
+
+		order := func() []string {
+			ids, err := tracks.GetMediaFileIDs(model.QueryOptions{Sort: "id"})
+			Expect(err).ToNot(HaveOccurred())
+			return ids
+		}
+
+		DescribeTable("inserts before a 1-based position, keeping the new tracks' order",
+			func(pos int, want func() []string) {
+				Expect(tracks.Insert([]string{songComeTogether.ID, songAntenna.ID}, pos)).To(Equal(2))
+				Expect(order()).To(Equal(want()))
+				Expect(tracks.CountAll()).To(Equal(int64(4)))
+			},
+			Entry("in the middle", 2, func() []string {
+				return []string{songDayInALife.ID, songComeTogether.ID, songAntenna.ID, songRadioactivity.ID}
+			}),
+			Entry("at the start, for zero or less", 0, func() []string {
+				return []string{songComeTogether.ID, songAntenna.ID, songDayInALife.ID, songRadioactivity.ID}
+			}),
+			Entry("at the end, past the last position", 9, func() []string {
+				return []string{songDayInALife.ID, songRadioactivity.ID, songComeTogether.ID, songAntenna.ID}
+			}),
+		)
+
+		It("renumbers positions contiguously", func() {
+			Expect(tracks.Insert([]string{songComeTogether.ID}, 1)).To(Equal(1))
+			all, err := tracks.GetAll(model.QueryOptions{Sort: "id"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect([]string{all[0].ID, all[1].ID, all[2].ID}).To(Equal([]string{"1", "2", "3"}))
+		})
+	})
+
+	Describe("Reorder", func() {
+		var tracks model.PlaylistTrackRepository
+
+		BeforeEach(func() {
+			ctx := log.NewContext(GinkgoT().Context())
+			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+			plsRepo := NewPlaylistRepository(ctx, GetDBXBuilder())
+			pls := model.Playlist{Name: "Reorder", OwnerID: "userid", OwnerName: "userid"}
+			Expect(plsRepo.Put(&pls)).To(Succeed())
+			DeferCleanup(func() { Expect(plsRepo.Delete(pls.ID)).To(Succeed()) })
+
+			tracks = plsRepo.Tracks(pls.ID, false)
+			Expect(tracks.Add([]string{songDayInALife.ID, songRadioactivity.ID, songComeTogether.ID})).To(Equal(3))
+		})
+
+		rows := func() ([]string, []string) {
+			all, err := tracks.GetAll(model.QueryOptions{Sort: "id"})
+			Expect(err).ToNot(HaveOccurred())
+			var ids, songs []string
+			for _, t := range all {
+				ids = append(ids, t.ID)
+				songs = append(songs, t.MediaFileID)
+			}
+			return ids, songs
+		}
+
+		DescribeTable("clamps the destination to the playlist",
+			func(newPos int, want func() []string) {
+				Expect(tracks.Reorder(1, newPos)).To(Succeed())
+				ids, songs := rows()
+				Expect(ids).To(Equal([]string{"1", "2", "3"}))
+				Expect(songs).To(Equal(want()))
+			},
+			Entry("past the end moves to the end", 9, func() []string {
+				return []string{songRadioactivity.ID, songComeTogether.ID, songDayInALife.ID}
+			}),
+			Entry("below 1 stays first", -4, func() []string {
+				return []string{songDayInALife.ID, songRadioactivity.ID, songComeTogether.ID}
+			}),
+		)
+
+		DescribeTable("rejects a source position outside the playlist, leaving rows untouched",
+			func(pos int) {
+				Expect(tracks.Reorder(pos, 1)).To(MatchError(model.ErrNotFound))
+				ids, songs := rows()
+				Expect(ids).To(Equal([]string{"1", "2", "3"}))
+				Expect(songs).To(Equal([]string{songDayInALife.ID, songRadioactivity.ID, songComeTogether.ID}))
+			},
+			Entry("past the end", 4),
+			Entry("zero", 0),
+		)
+	})
+
 	Describe("Delete", func() {
 		var tracks model.PlaylistTrackRepository
 		const numTracks = deleteChunkSize*2 + 1
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 5b9a2dba4..a20c9ce4e 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -123,13 +123,13 @@ returns direct children only (no tracks — no track is a library's direct child
 | Users | `GET UserViews`, `GET Users/{userId}/Views`, `GET Users/Me`, `GET Users/{userId}` |
 | Browsing | `GET Items`, `GET Users/{userId}/Items`, `GET Items/{itemId}`, `GET Users/{userId}/Items/{itemId}`, `GET Users/{userId}/Items/Latest`, `DELETE Items/{itemId}` (playlists only) |
 | Artists / genres | `GET Artists`, `GET Artists/AlbumArtists`, `GET Genres`, `GET MusicGenres` |
-| Similar / mixes | `GET Artists/{itemId}/Similar`, `GET Items/{itemId}/Similar`, `GET Items/{itemId}/InstantMix` |
+| Similar / mixes | `GET Artists/{itemId}/Similar`, `GET Items/{itemId}/Similar`, `GET {Items,Songs,Albums,Artists,Playlists}/{itemId}/InstantMix`, `GET Artists/InstantMix?id=`, `GET MusicGenres/InstantMix?id=` |
 | Images | `GET Items/{itemId}/Images/{type}[/{index}]` (public), `POST`/`DELETE Items/{itemId}/Images/{type}` (playlist cover, authenticated) |
 | Favorites / ratings for songs, albums, artists, and playlists | `POST`/`DELETE UserFavoriteItems/{itemId}`, `POST`/`DELETE Users/{userId}/FavoriteItems/{itemId}`, `POST`/`DELETE Users/{userId}/Items/{itemId}/Rating`, `GET UserItems/{itemId}/UserData`, `GET Users/{userId}/Items/{itemId}/UserData` |
-| Streaming | `GET Audio/{itemId}/stream[.{container}]`, `GET Audio/{itemId}/universal`, `GET Audio/{itemId}/main.m3u8`, `GET Items/{itemId}/File`, `GET Items/{itemId}/Download`, `GET`/`POST Items/{itemId}/PlaybackInfo` |
+| Streaming | `GET Audio/{itemId}/stream[.{container}]`, `GET Audio/{itemId}/universal`, `GET Audio/{itemId}/main.m3u8`, `GET Items/{itemId}/File`, `GET Items/{itemId}/Download`, `GET`/`POST Items/{itemId}/PlaybackInfo` (`HEAD` too on stream, universal, File, Download and images; a transcode HEAD answers without starting it) |
 | Lyrics | `GET Audio/{itemId}/Lyrics` |
-| Playback reporting | `POST Sessions/Playing`, `POST Sessions/Playing/Progress`, `POST Sessions/Playing/Stopped`, `POST Sessions/Capabilities[/Full]` |
-| Playlists | `POST Playlists`, `GET Playlists/{playlistId}`, `POST Playlists/{playlistId}` (rename / visibility / replace tracks), `GET Playlists/{playlistId}/Items`, `POST`/`DELETE Playlists/{playlistId}/Items`, `GET Playlists/{playlistId}/Users[/{userId}]` |
+| Playback reporting | `POST Sessions/Playing`, `POST Sessions/Playing/Progress`, `POST Sessions/Playing/Stopped`, `POST Sessions/Playing/Ping` (no-op), `POST Sessions/Capabilities[/Full]` |
+| Playlists | `POST Playlists`, `GET Playlists/{playlistId}`, `POST Playlists/{playlistId}` (rename / visibility / replace tracks), `GET Playlists/{playlistId}/Items`, `POST`/`DELETE Playlists/{playlistId}/Items` (`POST` honors `position`), `POST Playlists/{playlistId}/Items/{entryId}/Move/{newIndex}`, `GET Playlists/{playlistId}/Users[/{userId}]` |
 | Real-time | `GET socket` (WebSocket; keeps clients like Finamp from 404-loop-reconnecting) |
 | AudioMuse-AI (see below) | `GET AudioMuseAI/info`, `GET AudioMuseAI/health`, `GET AudioMuseAI/similar_tracks`, `GET AudioMuseAI/find_path` |
 
@@ -350,7 +350,7 @@ make test PKG=./server/jellyfin/...
   just a list badge): browse lists advertise it from embedded lyrics only (the `"[]"` sentinel
   check — the column is never `""` post-scan), while `PlaybackInfo` runs the full pipeline per
   track so sidecar/plugin lyrics also light up. Feishin additionally requires server version
-  ≥ 10.9 — the reason `jellyfinVersion` is 10.9.11.
+  ≥ 10.9 (`jellyfinVersion` advertises 12.1.0).
   Concurrent misses on the same track share one pipeline invocation (`SimpleCache.GetWithLoader`
   is singleflighted), and the load runs detached from the request context with a one-minute bound,
   so a cancelled request or hung plugin can't fail or pin the load for other waiters.
diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index 839c43ea5..955ebc3bb 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -93,6 +93,8 @@ func (api *Router) routes() http.Handler {
 			conf.Server.DevArtworkThrottleBacklogTimeout))
 		r.Get("/items/{itemId}/images/{type}", api.getItemImage)
 		r.Get("/items/{itemId}/images/{type}/{index}", api.getItemImage)
+		r.Head("/items/{itemId}/images/{type}", api.getItemImage)
+		r.Head("/items/{itemId}/images/{type}/{index}", api.getItemImage)
 	})
 
 	inner.Group(func(r chi.Router) {
@@ -145,6 +147,12 @@ func (api *Router) routes() http.Handler {
 		r.Get("/items/{itemId}/similar", api.getSimilarItems)
 		r.Get("/albums/{itemId}/similar", api.getSimilarAlbums)
 		r.Get("/items/{itemId}/instantmix", api.getInstantMix)
+		r.Get("/songs/{itemId}/instantmix", api.getInstantMix)
+		r.Get("/albums/{itemId}/instantmix", api.getInstantMix)
+		r.Get("/artists/{itemId}/instantmix", api.getInstantMix)
+		r.Get("/playlists/{itemId}/instantmix", api.getInstantMix)
+		r.Get("/artists/instantmix", api.getInstantMixByQuery)
+		r.Get("/musicgenres/instantmix", api.getInstantMixByQuery)
 		r.Get("/genres", api.getGenres)
 		r.Get("/musicgenres", api.getGenres)
 		r.Get("/studios", api.getStudios)
@@ -155,6 +163,7 @@ func (api *Router) routes() http.Handler {
 		r.Post("/playlists/{playlistId}", api.updatePlaylist)
 		r.Post("/playlists/{playlistId}/items", api.addToPlaylist)
 		r.Delete("/playlists/{playlistId}/items", api.removeFromPlaylist)
+		r.Post("/playlists/{playlistId}/items/{entryId}/move/{newIndex}", api.movePlaylistItem)
 		r.Get("/playlists/{playlistId}/users", api.getPlaylistUsers)
 		r.Get("/playlists/{playlistId}/users/{userId}", api.getPlaylistUser)
 
@@ -166,6 +175,10 @@ func (api *Router) routes() http.Handler {
 		r.Get("/audio/{itemId}/stream", api.streamAudio)
 		r.Get("/audio/{itemId}/stream.{container}", api.streamAudio)
 		r.Get("/audio/{itemId}/universal", api.streamUniversal)
+		// Fintunes probes these with HEAD for the content type before playing or downloading.
+		r.Head("/audio/{itemId}/stream", api.streamAudio)
+		r.Head("/audio/{itemId}/stream.{container}", api.streamAudio)
+		r.Head("/audio/{itemId}/universal", api.streamUniversal)
 		r.Get("/audio/{itemId}/main.m3u8", api.streamHls)
 		r.Get("/items/{itemId}/playbackinfo", api.getPlaybackInfo)
 		r.Post("/items/{itemId}/playbackinfo", api.getPlaybackInfo)
@@ -174,12 +187,15 @@ func (api *Router) routes() http.Handler {
 		// /Audio/{id}/stream; /Download reuses the direct-play handler as Jellyfin serves the same file.
 		r.Get("/items/{itemId}/file", api.streamFile)
 		r.Get("/items/{itemId}/download", api.streamFile)
+		r.Head("/items/{itemId}/file", api.streamFile)
+		r.Head("/items/{itemId}/download", api.streamFile)
 
 		r.Post("/sessions/playing", api.reportPlaybackStart)
 		r.Post("/sessions/playing/progress", api.reportPlaybackProgress)
 		r.Post("/sessions/playing/stopped", api.reportPlaybackStopped)
-		r.Post("/sessions/capabilities", api.postCapabilities)
-		r.Post("/sessions/capabilities/full", api.postCapabilities)
+		r.Post("/sessions/playing/ping", api.acknowledge)
+		r.Post("/sessions/capabilities", api.acknowledge)
+		r.Post("/sessions/capabilities/full", api.acknowledge)
 
 		// Real-time clients (e.g. Finamp) open this right after login; without it they 404-loop-reconnect.
 		r.Get("/socket", api.handleSocket)
diff --git a/server/jellyfin/e2e/images_test.go b/server/jellyfin/e2e/images_test.go
index 7fb85cba8..d1c3c132b 100644
--- a/server/jellyfin/e2e/images_test.go
+++ b/server/jellyfin/e2e/images_test.go
@@ -41,6 +41,10 @@ var _ = Describe("Item images", func() {
 		Expect(u.IsAdmin).To(BeTrue())
 	})
 
+	It("answers HEAD without authentication", func() {
+		Expect(rawReq("HEAD", "/Items/"+enc(albumID("Abbey Road"))+"/Images/Primary", "").Code).To(Equal(http.StatusOK))
+	})
+
 	It("serves images without authentication (public route)", func() {
 		id := albumID("IV")
 		w := rawReq("GET", "/Items/"+enc(id)+"/Images/Primary", "")
diff --git a/server/jellyfin/e2e/playlists_test.go b/server/jellyfin/e2e/playlists_test.go
index 50c2e17f2..174ba8660 100644
--- a/server/jellyfin/e2e/playlists_test.go
+++ b/server/jellyfin/e2e/playlists_test.go
@@ -19,6 +19,7 @@ var _ = Describe("Playlists", func() {
 	playlistItems := func(plID string) dto.QueryResult {
 		return queryResult(get("/Playlists/" + enc(plID) + "/Items"))
 	}
+	order := func(plID string) []string { return names(playlistItems(plID).Items) }
 
 	Describe("create", func() {
 		It("creates an empty playlist", func() {
@@ -102,6 +103,36 @@ var _ = Describe("Playlists", func() {
 			Expect(playlistItems(plID).TotalRecordCount).To(BeZero())
 		})
 
+		Describe("at a position", func() {
+			var plID string
+			addAt := func(position string, ids ...string) {
+				url := "/Playlists/" + enc(plID) + "/Items?position=" + position
+				for _, id := range ids {
+					url += "&ids=" + enc(id)
+				}
+				Expect(post(url, "").Code).To(Equal(http.StatusNoContent))
+			}
+			BeforeEach(func() {
+				plID = createPlaylist("Insert", []string{enc(songID("Come Together")), enc(songID("Something"))})
+			})
+
+			DescribeTable("inserts at Jellyfin's zero-based position",
+				func(position string, want []string) {
+					addAt(position, songID("So What"), songID("Help!"))
+					Expect(order(plID)).To(Equal(want))
+				},
+				Entry("in the middle", "1", []string{"Come Together", "So What", "Help!", "Something"}),
+				Entry("first, for zero or less", "-3", []string{"So What", "Help!", "Come Together", "Something"}),
+				Entry("last, past the end", "9", []string{"Come Together", "Something", "So What", "Help!"}),
+			)
+
+			It("keeps an expanded album's track order", func() {
+				albumOrder := order(createPlaylist("Album", []string{enc(albumID("Abbey Road"))}))
+				addAt("1", albumID("Abbey Road"))
+				Expect(order(plID)).To(Equal(append(append([]string{"Come Together"}, albumOrder...), "Something")))
+			})
+		})
+
 		It("removes an entry by its PlaylistItemId", func() {
 			plID := createPlaylist("Remove", []string{enc(songID("Come Together")), enc(songID("Something"))})
 			entryID := playlistItems(plID).Items[0].PlaylistItemId
@@ -118,6 +149,58 @@ var _ = Describe("Playlists", func() {
 		})
 	})
 
+	Describe("move", func() {
+		move := func(u model.User, plID, entryID string, newIndex string) int {
+			return jReq(u, "POST", "/Playlists/"+enc(plID)+"/Items/"+entryID+"/Move/"+newIndex, "").Code
+		}
+		var plID string
+		var entries []dto.BaseItemDto
+		BeforeEach(func() {
+			plID = createPlaylist("Move", []string{enc(songID("Come Together")), enc(songID("Something")), enc(songID("So What"))})
+			entries = playlistItems(plID).Items
+		})
+
+		DescribeTable("moves an entry to Jellyfin's zero-based index",
+			func(entry int, newIndex string, want []string) {
+				Expect(move(adminUser, plID, entries[entry].PlaylistItemId, newIndex)).To(Equal(http.StatusNoContent))
+				Expect(order(plID)).To(Equal(want))
+				var positions []string
+				for _, it := range playlistItems(plID).Items {
+					positions = append(positions, it.PlaylistItemId)
+				}
+				Expect(positions).To(Equal([]string{dto.EncodePlaylistEntryID("1"), dto.EncodePlaylistEntryID("2"), dto.EncodePlaylistEntryID("3")}))
+			},
+			Entry("towards the end", 0, "2", []string{"Something", "So What", "Come Together"}),
+			Entry("towards the start", 2, "0", []string{"So What", "Come Together", "Something"}),
+			Entry("to the end, past the last index", 0, "99", []string{"Something", "So What", "Come Together"}),
+			Entry("to the end, for the largest int", 0, "9223372036854775807", []string{"Something", "So What", "Come Together"}),
+		)
+
+		It("ignores an entry that is not in the playlist", func() {
+			Expect(move(adminUser, plID, dto.EncodePlaylistEntryID("42"), "0")).To(Equal(http.StatusNoContent))
+			Expect(order(plID)).To(Equal([]string{"Come Together", "Something", "So What"}))
+		})
+
+		It("404s on a malformed entry id", func() {
+			Expect(move(adminUser, plID, enc(songID("So What")), "0")).To(Equal(http.StatusNotFound))
+		})
+
+		It("hides another user's private playlist", func() {
+			Expect(move(regularUser, plID, entries[0].PlaylistItemId, "2")).To(Equal(http.StatusNotFound))
+			Expect(order(plID)).To(Equal([]string{"Come Together", "Something", "So What"}))
+		})
+
+		It("forbids a non-owner on a public playlist", func() {
+			Expect(post("/Playlists/"+enc(plID), `{"Name":"Move","IsPublic":true}`).Code).To(Equal(http.StatusNoContent))
+			Expect(move(regularUser, plID, entries[0].PlaylistItemId, "2")).To(Equal(http.StatusForbidden))
+			Expect(order(plID)).To(Equal([]string{"Come Together", "Something", "So What"}))
+		})
+
+		It("rejects a negative index", func() {
+			Expect(move(adminUser, plID, entries[0].PlaylistItemId, "-1")).To(Equal(http.StatusBadRequest))
+		})
+	})
+
 	Describe("users", func() {
 		It("reports the current user as an editor", func() {
 			plID := createPlaylist("Perms", nil)
diff --git a/server/jellyfin/e2e/sessions_test.go b/server/jellyfin/e2e/sessions_test.go
index 2057b43c6..c5c42cb2b 100644
--- a/server/jellyfin/e2e/sessions_test.go
+++ b/server/jellyfin/e2e/sessions_test.go
@@ -37,6 +37,10 @@ var _ = Describe("Sessions", func() {
 			Expect(mf.PlayCount).To(BeNumerically(">=", 1))
 		})
 
+		It("acknowledges a playback session ping", func() {
+			Expect(post("/Sessions/Playing/Ping?playSessionId=abc", "").Code).To(Equal(http.StatusNoContent))
+		})
+
 		It("does not count a brief play stopped before the threshold", func() {
 			// Regression: Finamp sends a Stopped report on every track switch, so an immediate skip
 			// (1 second in) must not mark the track played. Seeded tracks are >= 120s, so the 50%
diff --git a/server/jellyfin/e2e/similar_test.go b/server/jellyfin/e2e/similar_test.go
index 5f1a88a21..06054f8bf 100644
--- a/server/jellyfin/e2e/similar_test.go
+++ b/server/jellyfin/e2e/similar_test.go
@@ -150,4 +150,33 @@ var _ = Describe("Similar", func() {
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 		})
 	})
+
+	Describe("type-specific InstantMix routes", func() {
+		BeforeEach(func() {
+			providerFake.similarSongs = model.MediaFiles{{ID: testID("x1"), Title: "Mix Song", LibraryID: 1}}
+		})
+
+		It("leads a song mix with the seed on /Songs/{id}/InstantMix", func() {
+			q := queryResult(get("/Songs/" + enc(songID("So What")) + "/InstantMix"))
+			Expect(names(q.Items)).To(Equal([]string{"So What", "Mix Song"}))
+		})
+
+		DescribeTable("returns the provider's mix",
+			func(path func() string) {
+				q := queryResult(get(path()))
+				Expect(names(q.Items)).To(Equal([]string{"Mix Song"}))
+			},
+			Entry("Albums/{id}", func() string { return "/Albums/" + enc(albumID("Abbey Road")) + "/InstantMix" }),
+			Entry("Artists/{id}", func() string { return "/Artists/" + enc(artistID("Miles Davis")) + "/InstantMix" }),
+			Entry("Playlists/{id}", func() string {
+				return "/Playlists/" + enc(createPlaylist("Seed", []string{enc(songID("So What"))})) + "/InstantMix"
+			}),
+			Entry("Artists/InstantMix?id=", func() string { return "/Artists/InstantMix?id=" + enc(artistID("Miles Davis")) }),
+			Entry("MusicGenres/InstantMix?id=", func() string { return "/MusicGenres/InstantMix?id=" + enc(genreID("Jazz")) }),
+		)
+
+		It("404s a malformed id query param", func() {
+			Expect(get("/Artists/InstantMix?id=not-a-valid-id").Code).To(Equal(http.StatusNotFound))
+		})
+	})
 })
diff --git a/server/jellyfin/e2e/streaming_test.go b/server/jellyfin/e2e/streaming_test.go
index 67208aed3..9b7380185 100644
--- a/server/jellyfin/e2e/streaming_test.go
+++ b/server/jellyfin/e2e/streaming_test.go
@@ -1,6 +1,7 @@
 package e2e
 
 import (
+	"fmt"
 	"net/http"
 	"strings"
 
@@ -45,6 +46,19 @@ var _ = Describe("Streaming", func() {
 		It("returns 404 for an unknown track", func() {
 			Expect(get("/Audio/" + enc(testID("nope")) + "/stream").Code).To(Equal(http.StatusNotFound))
 		})
+
+		DescribeTable("answers HEAD (Fintunes probes the type before playing or downloading)",
+			func(path string) {
+				w := jReq(adminUser, "HEAD", fmt.Sprintf(path, enc(songID("Help!"))), "")
+				Expect(w.Code).To(Equal(http.StatusOK))
+				Expect(w.Header().Get("Content-Type")).ToNot(BeEmpty())
+			},
+			Entry("stream", "/Audio/%s/stream"),
+			Entry("stream.{container}", "/Audio/%s/stream.mp3"),
+			Entry("universal", "/Audio/%s/universal"),
+			Entry("File", "/Items/%s/File"),
+			Entry("Download", "/Items/%s/Download"),
+		)
 	})
 
 	Describe("GET /Audio/{id}/main.m3u8 (Finamp transcoding mode)", func() {
diff --git a/server/jellyfin/images.go b/server/jellyfin/images.go
index 9f1b9ce1a..0c9e0380c 100644
--- a/server/jellyfin/images.go
+++ b/server/jellyfin/images.go
@@ -23,14 +23,17 @@ import (
 	_ "golang.org/x/image/webp"
 )
 
-// imageSize picks the tighter of Jellyfin's two bounds, because Navidrome resizes on a single
-// dimension: reading only MaxWidth serves the full-size original to a client that sent MaxHeight.
-func imageSize(maxWidth, maxHeight int) int {
-	w, h := max(maxWidth, 0), max(maxHeight, 0)
-	if w == 0 || h == 0 {
-		return max(w, h)
+// imageSize reduces Jellyfin's size params to Navidrome's single bound. Width/Height/Max* are
+// bounds, so the tightest wins; Fill* must cover its box, so its larger side is the bound.
+func imageSize(p *req.Values) int {
+	fill := max(p.IntOr("fillwidth", 0), p.IntOr("fillheight", 0))
+	size := 0
+	for _, v := range []int{p.IntOr("width", 0), p.IntOr("height", 0), p.IntOr("maxwidth", 0), p.IntOr("maxheight", 0), fill} {
+		if v > 0 && (size == 0 || v < size) {
+			size = v
+		}
 	}
-	return min(w, h)
+	return size
 }
 
 func (api *Router) getItemImage(w http.ResponseWriter, r *http.Request) {
@@ -41,8 +44,7 @@ func (api *Router) getItemImage(w http.ResponseWriter, r *http.Request) {
 	if !ok {
 		return
 	}
-	p := req.Params(r)
-	size := imageSize(p.IntOr("maxwidth", 0), p.IntOr("maxheight", 0))
+	size := imageSize(req.Params(r))
 
 	artID := api.resolveArtworkID(ctx, itemId)
 	img, err := api.artwork.GetOrPlaceholder(ctx, artID, size, false)
diff --git a/server/jellyfin/images_test.go b/server/jellyfin/images_test.go
index 2f32e6ec9..b7b262895 100644
--- a/server/jellyfin/images_test.go
+++ b/server/jellyfin/images_test.go
@@ -65,7 +65,7 @@ func newImageRequest(itemId string) (*httptest.ResponseRecorder, *http.Request)
 var _ = Describe("Images", func() {
 	// Real Jellyfin fits the image inside either bound, so a client that sends only MaxHeight must
 	// still get a resized image rather than the full-size original.
-	DescribeTable("derives the requested size from MaxWidth or MaxHeight",
+	DescribeTable("derives the requested size from the Jellyfin size params",
 		func(query string, wantSize int) {
 			ds := &tests.MockDataStore{}
 			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
@@ -84,6 +84,15 @@ var _ = Describe("Images", func() {
 		Entry("both, smaller bound wins", "maxwidth=200&maxheight=300", 200),
 		Entry("both, smaller bound wins regardless of order", "maxwidth=300&maxheight=200", 200),
 		Entry("neither", "", 0),
+		Entry("Width only", "width=300", 300),
+		Entry("Height only", "height=300", 300),
+		Entry("Width capped by MaxWidth", "width=500&maxwidth=300", 300),
+		Entry("FillWidth only", "fillwidth=300", 300),
+		Entry("FillHeight only", "fillheight=300", 300),
+		Entry("both fill sides, larger one covers the box", "fillwidth=200&fillheight=300", 300),
+		Entry("fill smaller than MaxWidth wins", "maxwidth=500&fillwidth=300&fillheight=300", 300),
+		Entry("MaxWidth smaller than fill wins", "maxwidth=200&fillwidth=300&fillheight=300", 200),
+		Entry("non-positive values are ignored", "fillwidth=0&maxwidth=-5&height=250", 250),
 	)
 
 	It("streams album artwork", func() {
diff --git a/server/jellyfin/playlists.go b/server/jellyfin/playlists.go
index ac790a821..1052a398f 100644
--- a/server/jellyfin/playlists.go
+++ b/server/jellyfin/playlists.go
@@ -4,7 +4,9 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"math"
 	"net/http"
+	"strconv"
 	"strings"
 
 	"github.com/go-chi/chi/v5"
@@ -261,8 +263,8 @@ func (api *Router) songIDs(ctx context.Context, opts model.QueryOptions) []strin
 	return slice.Map(mfs, func(mf model.MediaFile) string { return mf.ID })
 }
 
-// addToPlaylist appends items by id, expanding containers into tracks (see expandContainerIDs).
-// AddTracks enforces ownership; a locked playlist maps to 403, any other error to 404.
+// addToPlaylist adds items by id (containers expand to tracks), inserting at the zero-based position
+// when given. Core enforces ownership: a locked playlist maps to 403, any other error to 404.
 func (api *Router) addToPlaylist(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	id, ok := itemIDParam(w, r, "playlistId")
@@ -275,7 +277,13 @@ func (api *Router) addToPlaylist(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	ids := api.expandContainerIDs(ctx, decoded)
-	if _, err := api.playlists.AddTracks(ctx, id, ids); err != nil {
+	var err error
+	if position, perr := req.Params(r).Int64("position"); perr == nil {
+		_, err = api.playlists.InsertTracks(ctx, id, ids, insertPosition(position))
+	} else {
+		_, err = api.playlists.AddTracks(ctx, id, ids)
+	}
+	if err != nil {
 		if errors.Is(err, model.ErrPlaylistNotEditable) {
 			http.Error(w, "Forbidden", http.StatusForbidden)
 			return
@@ -286,6 +294,12 @@ func (api *Router) addToPlaylist(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// insertPosition maps Jellyfin's zero-based position to a 1-based one, clamped in int64 first so
+// it can't wrap on 32-bit builds.
+func insertPosition(position int64) int {
+	return int(min(max(position, 0), math.MaxInt32-1) + 1)
+}
+
 // removeFromPlaylist removes entries by entryIds — playlist-entry ids (PlaylistItemId), not media
 // file ids, since RemoveTracks deletes playlist_tracks rows by that id. RemoveTracks enforces
 // ownership; a locked playlist maps to 403, any other error to 404.
@@ -316,6 +330,38 @@ func (api *Router) removeFromPlaylist(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// movePlaylistItem moves an entry to Jellyfin's zero-based newIndex. Reorder clamps past-the-end
+// indexes and rejects unknown entries, which Jellyfin treats as a no-op.
+func (api *Router) movePlaylistItem(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	id, ok := itemIDParam(w, r, "playlistId")
+	if !ok {
+		return
+	}
+	entry, ok := dto.DecodePlaylistEntryID(chi.URLParam(r, "entryId"))
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
+	newIndex, err := strconv.Atoi(chi.URLParam(r, "newIndex"))
+	if err != nil || newIndex < 0 {
+		http.Error(w, "Bad Request", http.StatusBadRequest)
+		return
+	}
+	// Resolve first, so a missing or hidden playlist is still a 404 below the unknown-entry no-op.
+	if _, err := api.playlists.Get(ctx, id); err != nil {
+		api.playlistError(w, r, err)
+		return
+	}
+	pos, _ := strconv.Atoi(entry)
+	err = api.playlists.ReorderTrack(ctx, id, pos, min(newIndex, math.MaxInt32-1)+1)
+	if err != nil && !errors.Is(err, model.ErrNotFound) {
+		api.playlistError(w, r, err)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
 // Clients probe these before offering edits. Navidrome has no per-playlist ACL, so CanEdit carries
 // only editability; ownership is enforced on write, and a lookup error 404s to prevent probing.
 func (api *Router) getPlaylistUsers(w http.ResponseWriter, r *http.Request) {
diff --git a/server/jellyfin/playlists_test.go b/server/jellyfin/playlists_test.go
index 270f5fe08..ae0a5da3c 100644
--- a/server/jellyfin/playlists_test.go
+++ b/server/jellyfin/playlists_test.go
@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"io"
+	"math"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -133,6 +134,17 @@ func (f *fakePlaylists) RemoveImage(_ context.Context, playlistID string) error
 	return f.removeImageErr
 }
 
+var _ = DescribeTable("insertPosition",
+	func(position int64, want int) {
+		Expect(insertPosition(position)).To(Equal(want))
+	},
+	Entry("zero-based index becomes a 1-based position", int64(2), 3),
+	Entry("negative prepends", int64(-5), 1),
+	Entry("beyond int32 stays past the end instead of wrapping", int64(1)<<32+1, math.MaxInt32),
+	Entry("largest int64 stays past the end", int64(math.MaxInt64), math.MaxInt32),
+	Entry("smallest int64 prepends", int64(math.MinInt64), 1),
+)
+
 var _ = Describe("Playlists", func() {
 	var api *Router
 	var fp *fakePlaylists
diff --git a/server/jellyfin/sessions.go b/server/jellyfin/sessions.go
index a145e7359..e60b1bf5b 100644
--- a/server/jellyfin/sessions.go
+++ b/server/jellyfin/sessions.go
@@ -113,8 +113,8 @@ func (api *Router) reportPlaybackStopped(w http.ResponseWriter, r *http.Request)
 	w.WriteHeader(http.StatusNoContent)
 }
 
-// postCapabilities acknowledges Jellyfin session-capability negotiation.
-// Navidrome doesn't track per-session client capabilities, so this is a no-op.
-func (api *Router) postCapabilities(w http.ResponseWriter, _ *http.Request) {
+// acknowledge answers requests Navidrome keeps no state for: session capabilities (not tracked per
+// session) and playback pings (transcodes live only as long as their stream request).
+func (api *Router) acknowledge(w http.ResponseWriter, _ *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
diff --git a/server/jellyfin/sessions_test.go b/server/jellyfin/sessions_test.go
index 05151c39a..f2f04497c 100644
--- a/server/jellyfin/sessions_test.go
+++ b/server/jellyfin/sessions_test.go
@@ -152,12 +152,12 @@ var _ = Describe("Sessions", func() {
 		})
 	})
 
-	Describe("postCapabilities", func() {
+	Describe("acknowledge", func() {
 		It("returns 204 No Content and does not touch the scrobbler", func() {
 			w := httptest.NewRecorder()
 			r := authed(httptest.NewRequest("POST", "/Sessions/Capabilities", strings.NewReader(`{"SupportsMediaControl":true}`)))
 
-			api.postCapabilities(w, r)
+			api.acknowledge(w, r)
 
 			Expect(w.Code).To(Equal(http.StatusNoContent))
 			Expect(pt.reported).To(BeEmpty())
diff --git a/server/jellyfin/similar.go b/server/jellyfin/similar.go
index 82d12f52b..1bd887f43 100644
--- a/server/jellyfin/similar.go
+++ b/server/jellyfin/similar.go
@@ -111,11 +111,26 @@ func (api *Router) getSimilarAlbums(w http.ResponseWriter, r *http.Request) {
 // a track seed leads its own mix; provider errors and unknown seeds degrade to seed-only/empty
 // results, never a 404 the client would surface as an error.
 func (api *Router) getInstantMix(w http.ResponseWriter, r *http.Request) {
-	ctx := r.Context()
 	id, ok := itemIDParam(w, r, "itemId")
 	if !ok {
 		return
 	}
+	api.instantMix(w, r, id)
+}
+
+// getInstantMixByQuery serves the legacy Artists/InstantMix and MusicGenres/InstantMix forms,
+// which take the seed as ?id= instead of a path segment.
+func (api *Router) getInstantMixByQuery(w http.ResponseWriter, r *http.Request) {
+	id, ok := dto.DecodeID(req.Params(r).StringOr("id", ""))
+	if !ok {
+		http.Error(w, "Not Found", http.StatusNotFound)
+		return
+	}
+	api.instantMix(w, r, id)
+}
+
+func (api *Router) instantMix(w http.ResponseWriter, r *http.Request, id string) {
+	ctx := r.Context()
 	limit := clampLimit(req.Params(r).IntOr("limit", 0), defaultSimilarLimit, maxInstantMixLimit)
 
 	// Genre ids don't resolve via GetEntityByID, so a not-found entity is fine: it is just "not a
diff --git a/server/jellyfin/stream.go b/server/jellyfin/stream.go
index c6dc0c80e..b9809bd29 100644
--- a/server/jellyfin/stream.go
+++ b/server/jellyfin/stream.go
@@ -4,6 +4,7 @@ import (
 	"cmp"
 	"fmt"
 	"math"
+	"mime"
 	"net/http"
 	"net/url"
 	"slices"
@@ -139,6 +140,14 @@ func (api *Router) serveAudio(w http.ResponseWriter, r *http.Request, mf *model.
 
 func (api *Router) serveStream(w http.ResponseWriter, r *http.Request, mf *model.MediaFile, streamReq stream.Request) {
 	ctx := r.Context()
+	// A probe must not start a transcode. Omitting Content-Length is what tells a client (Fintunes)
+	// this is not direct play; direct play falls through to Serve, which answers HEAD itself.
+	if r.Method == http.MethodHead && streamReq.Format != "" && streamReq.Format != "raw" {
+		w.Header().Set("Content-Type", mime.TypeByExtension("."+streamReq.Format))
+		w.Header().Set("Accept-Ranges", "none")
+		w.WriteHeader(http.StatusOK)
+		return
+	}
 	s, err := api.streamer.NewStream(ctx, mf, streamReq)
 	if err != nil {
 		api.internalError(w, r, err)
diff --git a/server/jellyfin/stream_test.go b/server/jellyfin/stream_test.go
index 3cd692c1b..1a6d1badc 100644
--- a/server/jellyfin/stream_test.go
+++ b/server/jellyfin/stream_test.go
@@ -244,6 +244,36 @@ var _ = Describe("Stream", func() {
 		})
 	})
 
+	Describe("HEAD requests", func() {
+		head := func(query string) *httptest.ResponseRecorder {
+			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+				{ID: testID("s1"), Title: "Song", Suffix: "flac", LibraryID: 1},
+			})
+			streamer.content = "audio-bytes"
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("HEAD", "/Audio/"+dto.EncodeID(testID("s1"))+"/stream?"+query, nil).WithContext(ctxUser())
+			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
+			invoke(api.streamAudio, w, r)
+			return w
+		}
+
+		It("answers a transcode with the target type and no length, without starting it", func() {
+			w := head("audioCodec=mp3")
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(w.Header().Get("Content-Type")).To(Equal("audio/mpeg"))
+			Expect(w.Header().Get("Content-Length")).To(BeEmpty())
+			Expect(w.Body.String()).To(BeEmpty())
+			Expect(streamer.invoked).To(BeFalse())
+		})
+
+		It("answers direct play through the streamer, without a body", func() {
+			w := head("static=true")
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(streamer.invoked).To(BeTrue())
+			Expect(w.Body.String()).To(BeEmpty())
+		})
+	})
+
 	Describe("streamUniversal", func() {
 		universal := func(query string) {
 			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
diff --git a/server/jellyfin/system.go b/server/jellyfin/system.go
index ccc1277df..0a85d4545 100644
--- a/server/jellyfin/system.go
+++ b/server/jellyfin/system.go
@@ -20,10 +20,9 @@ import (
 	"github.com/navidrome/navidrome/server/jellyfin/dto"
 )
 
-// jellyfinVersion is the Jellyfin API version advertised in the handshake. Clients feature-gate
-// on it, so it must stay a real Jellyfin release, not Navidrome's own version. 10.9+ is required
-// for Feishin to use the server lyrics endpoint.
-const jellyfinVersion = "10.9.11"
+// jellyfinVersion is the Jellyfin API version advertised in the handshake. Clients and SDKs gate on
+// it (Streamyfin and the Android apps refuse < 10.10), and some parsers need exactly three parts.
+const jellyfinVersion = "12.1.0"
 
 func (api *Router) serverName() string {
 	if conf.Server.Jellyfin.ServerName != "" {
diff --git a/tests/mock_playlist_track_repo.go b/tests/mock_playlist_track_repo.go
index 83751bb28..5666e7cc7 100644
--- a/tests/mock_playlist_track_repo.go
+++ b/tests/mock_playlist_track_repo.go
@@ -13,6 +13,7 @@ type MockPlaylistTrackRepo struct {
 	DeletedIds []string
 	Reordered  bool
 	AddCount   int
+	InsertPos  int
 	Err        error
 	AlbumIDs   []string // stubbed result for GetAlbumIDs, ignoring options
 }
@@ -89,6 +90,11 @@ func (m *MockPlaylistTrackRepo) Add(ids []string) (int, error) {
 	return m.AddCount, nil
 }
 
+func (m *MockPlaylistTrackRepo) Insert(ids []string, pos int) (int, error) {
+	m.InsertPos = pos
+	return m.Add(ids)
+}
+
 func (m *MockPlaylistTrackRepo) AddAlbums(_ []string) (int, error) {
 	if m.Err != nil {
 		return 0, m.Err

From fed35e08de2d784af8ad7d7f9533d56b59e6f42e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 19 Sep 2026 13:33:19 -0400
Subject: [PATCH 150/200] feat(jellyfin): add opt-in LAN auto-discovery (#6169)

* feat(jellyfin): compute the address advertised by auto-discovery

* fix(jellyfin): use TLSEnabled and path.Join for the auto-discovery address

* feat(jellyfin): answer LAN auto-discovery broadcasts

* test(jellyfin): e2e check that auto-discovery matches the public server identity

* feat(jellyfin): add opt-in AutoDiscovery option and start the listener

* fix(jellyfin): close the auto-discovery socket on read errors and quiet reply failures

* refactor(jellyfin): build the auto-discovery address with publicurl and log bind failures in place

discoveryAddress now hands only the discovery-specific part (the requester-facing host) to publicurl.AbsoluteURL, so the BaseURL, scheme and BasePath rules live in one place. ServeDiscovery logs its own bind failure and returns nothing, so the caller cannot route the error into the server errgroup. Tests use a DescribeTable and no longer wait on a fixed timeout to prove a packet was ignored.

* refactor(jellyfin): run auto-discovery as its own service in the main errgroup

Discovery is now a small type that needs only a DataStore, started by startJellyfinDiscovery like the other background services, so the errgroup waits for it on shutdown and startServer is back to a one-line mount. The server id resolution moved to resolveServerID with a package-level lock: the Router and Discovery are separate objects, and a per-Router lock would let them persist two different ids on first boot.

* refactor(jellyfin): build Discovery through wire and drop the serverName forwarder

startJellyfinDiscovery now follows its siblings: negative guard with a DISABLED debug log, and the service comes from a CreateJellyfinDiscovery wire injector instead of an inline constructor. The Router.serverName method only forwarded to the package function, so its four call sites call the function directly.

* fix(jellyfin): skip auto-discovery for unix socket servers without a BaseURL host

With Address set to a unix socket nothing listens on Port, so the route-facing IP plus Port pointed clients at a dead URL. Discovery now logs a warning and does not start in that mode unless BaseURL names the proxy host, which AbsoluteURL already advertises as-is.

* docs(jellyfin): note which address auto-discovery advertises on restricted binds

Also stop using a hostname Address in the fallback spec: a hostname like localhost binds a single interface, so it is not an example of the route-facing fallback being right. An empty Address is.
---
 cmd/root.go                           |  13 ++
 cmd/wire_gen.go                       |   9 +-
 cmd/wire_injectors.go                 |   7 ++
 conf/configuration.go                 |   2 +
 server/jellyfin/README.md             |  22 ++++
 server/jellyfin/api.go                |   2 -
 server/jellyfin/auth.go               |   2 +-
 server/jellyfin/discovery.go          | 110 ++++++++++++++++
 server/jellyfin/discovery_test.go     | 175 ++++++++++++++++++++++++++
 server/jellyfin/e2e/discovery_test.go |  50 ++++++++
 server/jellyfin/system.go             |  45 +++----
 server/jellyfin/system_test.go        |  12 ++
 server/jellyfin/users.go              |   2 +-
 13 files changed, 425 insertions(+), 26 deletions(-)
 create mode 100644 server/jellyfin/discovery.go
 create mode 100644 server/jellyfin/discovery_test.go
 create mode 100644 server/jellyfin/e2e/discovery_test.go

diff --git a/cmd/root.go b/cmd/root.go
index c4e360010..f632b0425 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -86,6 +86,7 @@ func runNavidrome(ctx context.Context) {
 	g.Go(startSignaller(ctx))
 	g.Go(startScheduler(ctx))
 	g.Go(startPlaybackServer(ctx))
+	g.Go(startJellyfinDiscovery(ctx))
 	g.Go(schedulePeriodicBackup(ctx))
 	g.Go(startInsightsCollector(ctx))
 	g.Go(scheduleDBAnalyzer(ctx))
@@ -343,6 +344,18 @@ func startInsightsCollector(ctx context.Context) func() error {
 	}
 }
 
+// startJellyfinDiscovery never returns an error: a discovery failure must not stop the server.
+func startJellyfinDiscovery(ctx context.Context) func() error {
+	return func() error {
+		if !conf.Server.Jellyfin.Enabled || !conf.Server.Jellyfin.AutoDiscovery {
+			log.Debug("Jellyfin auto-discovery is DISABLED")
+			return nil
+		}
+		CreateJellyfinDiscovery().Serve(ctx)
+		return nil
+	}
+}
+
 // startPlaybackServer starts the Navidrome playback server, if configured.
 // It is responsible for the Jukebox functionality
 func startPlaybackServer(ctx context.Context) func() error {
diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index fd04c44c5..d6bf4da07 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -168,6 +168,13 @@ func CreateListenBrainzRouter() *listenbrainz.Router {
 	return router
 }
 
+func CreateJellyfinDiscovery() *jellyfin.Discovery {
+	sqlDB := db.Db()
+	dataStore := persistence.New(sqlDB)
+	discovery := jellyfin.NewDiscovery(dataStore)
+	return discovery
+}
+
 func CreateInsights() metrics.Insights {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
@@ -249,7 +256,7 @@ func getPluginManager() *plugins.Manager {
 
 // wire_injectors.go:
 
-var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, jellyfin.New, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.GetInstance, 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(sonic.Engine), new(*sonic.Sonic)), 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)), wire.Bind(new(playlists.ImageUploadService), new(artwork.Uploader)))
+var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, jellyfin.New, jellyfin.NewDiscovery, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.GetInstance, 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(sonic.Engine), new(*sonic.Sonic)), 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)), wire.Bind(new(playlists.ImageUploadService), new(artwork.Uploader)))
 
 func GetPluginManager(ctx context.Context) *plugins.Manager {
 	manager := getPluginManager()
diff --git a/cmd/wire_injectors.go b/cmd/wire_injectors.go
index a54d4ae1b..527617959 100644
--- a/cmd/wire_injectors.go
+++ b/cmd/wire_injectors.go
@@ -36,6 +36,7 @@ var allProviders = wire.NewSet(
 	server.New,
 	subsonic.New,
 	jellyfin.New,
+	jellyfin.NewDiscovery,
 	nativeapi.New,
 	public.New,
 	persistence.New,
@@ -108,6 +109,12 @@ func CreateListenBrainzRouter() *listenbrainz.Router {
 	))
 }
 
+func CreateJellyfinDiscovery() *jellyfin.Discovery {
+	panic(wire.Build(
+		allProviders,
+	))
+}
+
 func CreateInsights() metrics.Insights {
 	panic(wire.Build(
 		allProviders,
diff --git a/conf/configuration.go b/conf/configuration.go
index e549e2a61..4812f2515 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -235,6 +235,7 @@ type jellyfinOptions struct {
 	// ExposedPublicUsers is a comma-separated list of usernames to advertise on the unauthenticated
 	// GET /Users/Public, so Jellyfin clients can show a login user-picker. Empty exposes no users.
 	ExposedPublicUsers string
+	AutoDiscovery      bool
 	// MaxConcurrentStreams bounds how many collection responses can stream at once. Each holds a DB
 	// cursor — and its pooled connection — for the whole client-paced response, so without a bound
 	// enough slow clients would take the entire pool and stall the scanner, scrobbles and the UI.
@@ -1087,6 +1088,7 @@ func setViperDefaults() {
 	viper.SetDefault("listenbrainz.trackalgorithm", consts.DefaultListenBrainzTrackAlgorithm)
 	viper.SetDefault("jellyfin.enabled", false)
 	viper.SetDefault("jellyfin.servername", "")
+	viper.SetDefault("jellyfin.autodiscovery", false)
 	viper.SetDefault("enablescrobblehistory", true)
 	viper.SetDefault("httpheaders.frameoptions", "DENY")
 	viper.SetDefault("backup.path", "")
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index a20c9ce4e..893642cdd 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -22,6 +22,8 @@ Enabled = true
 ServerName = "My Music Server"
 # Optional: usernames to show in the client login user-picker (default: none). See "Public user list".
 ExposedPublicUsers = "alice, bob"
+# Optional: answer LAN auto-discovery broadcasts on UDP 7359 (default: false). See "Auto discovery".
+AutoDiscovery = true
 # Optional: max collection responses streaming at once (default: half the DB connection pool,
 # min 2). Each streaming response holds a DB connection for its whole duration; excess requests
 # queue rather than fail.
@@ -34,6 +36,7 @@ or via environment variables:
 ND_JELLYFIN_ENABLED=true
 ND_JELLYFIN_SERVERNAME="My Music Server"
 ND_JELLYFIN_EXPOSEDPUBLICUSERS="alice,bob"
+ND_JELLYFIN_AUTODISCOVERY=true
 ```
 
 Once enabled, the API is mounted at:
@@ -46,6 +49,25 @@ All the paths below are relative to that base URL (e.g. `System/Info/Public` mea
 `http://localhost:4533/jellyfin/System/Info/Public`). Routes are matched **case-insensitively**,
 since real Jellyfin clients (and `jellyfin-apiclient-python`) send mixed-case paths.
 
+## Auto discovery
+
+With `AutoDiscovery = true`, Navidrome answers the Jellyfin LAN discovery broadcast
+(`who is JellyfinServer?` on UDP port 7359), so clients list the server without a typed URL.
+It is off by default because a real Jellyfin server on the same host owns that port. If the port
+is taken, Navidrome logs a warning and keeps running without discovery.
+
+The advertised address is `BaseURL` when it includes a host. Otherwise it is the bind `Address`
+when that is a specific IP, or else the local IP that faces the requesting client, plus `Port`. With a
+unix socket `Address` there is no port to advertise, so discovery only starts when `BaseURL` has a host.
+
+Discovery answers on all IPv4 interfaces, but the advertised address follows `BaseURL`, `Address` and
+`Port`. If `Address` is a loopback or a single interface IP and `BaseURL` has no host, clients on other
+networks get an address they cannot reach. Set `BaseURL` to the address clients should use.
+
+Docker: publish the port (`-p 7359:7359/udp`). In bridge mode the server only sees its container
+IP, so also set `ND_BASEURL` to the LAN address (for example `http://192.168.1.10:4533`), or use
+host networking. Keep UDP 7359 on the LAN: never forward it from the internet.
+
 ## Authentication
 
 Jellyfin clients authenticate with `POST /Users/AuthenticateByName` using the user's Navidrome
diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index 955ebc3bb..eddd14f66 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -3,7 +3,6 @@ package jellyfin
 import (
 	"encoding/json"
 	"net/http"
-	"sync"
 	"time"
 
 	"github.com/go-chi/chi/v5"
@@ -41,7 +40,6 @@ type Router struct {
 	broker           events.Broker
 	lyricsCache      cache.SimpleCache[string, model.LyricList]
 	similarFlight    singleflight.Group
-	serverIDMu       sync.Mutex
 	serverIDVal      string
 }
 
diff --git a/server/jellyfin/auth.go b/server/jellyfin/auth.go
index bfcfab319..ba4fe40f1 100644
--- a/server/jellyfin/auth.go
+++ b/server/jellyfin/auth.go
@@ -45,7 +45,7 @@ func (api *Router) authenticateByName(w http.ResponseWriter, r *http.Request) {
 	a := parseMediaBrowserAuth(r)
 	serverID := api.serverID(ctx)
 	api.ok(w, r, dto.AuthenticationResult{
-		User:        userToDto(usr, api.serverName(), serverID),
+		User:        userToDto(usr, serverName(), serverID),
 		SessionInfo: dto.NewSessionInfo(usr, a.Client, a.DeviceId, a.Device, a.Version, serverID),
 		AccessToken: token,
 		ServerId:    serverID,
diff --git a/server/jellyfin/discovery.go b/server/jellyfin/discovery.go
new file mode 100644
index 000000000..d111287a6
--- /dev/null
+++ b/server/jellyfin/discovery.go
@@ -0,0 +1,110 @@
+package jellyfin
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"strconv"
+	"strings"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/publicurl"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/gg"
+)
+
+// Jellyfin clients broadcast this query text to this UDP port.
+const (
+	discoveryPort  = 7359
+	discoveryQuery = "who is jellyfinserver?"
+)
+
+type discoveryInfo struct {
+	Address         string  `json:"Address"`
+	Id              string  `json:"Id"`
+	Name            string  `json:"Name"`
+	EndpointAddress *string `json:"EndpointAddress"`
+}
+
+// Discovery answers LAN auto-discovery broadcasts with the same identity the Router reports.
+type Discovery struct {
+	ds          model.DataStore
+	serverIDVal string
+}
+
+func NewDiscovery(ds model.DataStore) *Discovery {
+	return &Discovery{ds: ds}
+}
+
+func (d *Discovery) serverID(ctx context.Context) string {
+	return resolveServerID(ctx, d.ds, &d.serverIDVal)
+}
+
+// Serve runs until ctx is done. A failed bind is only logged: discovery is best-effort.
+func (d *Discovery) Serve(ctx context.Context) {
+	if !hasAdvertisableAddress() {
+		log.Warn(ctx, "Jellyfin API: auto-discovery is off, a unix socket server needs a BaseURL with a host to advertise")
+		return
+	}
+	// udp4 only: a dual-stack bind can share the port with another server and never get a packet.
+	conn, err := net.ListenPacket("udp4", net.JoinHostPort("0.0.0.0", strconv.Itoa(discoveryPort)))
+	if err != nil {
+		log.Warn(ctx, "Jellyfin API: auto-discovery is off, the UDP port is unavailable. Is another Jellyfin server running?", "port", discoveryPort, err)
+		return
+	}
+	log.Info(ctx, "Jellyfin API: listening for auto-discovery broadcasts", "port", discoveryPort)
+	d.ServeOn(ctx, conn)
+}
+
+// ServeOn answers discovery queries on conn until ctx is done, then closes conn.
+func (d *Discovery) ServeOn(ctx context.Context, conn net.PacketConn) {
+	defer conn.Close()
+	stop := context.AfterFunc(ctx, func() { _ = conn.Close() })
+	defer stop()
+	buf := make([]byte, 1024)
+	for {
+		n, remote, err := conn.ReadFrom(buf)
+		if err != nil {
+			if ctx.Err() == nil {
+				log.Error(ctx, "Jellyfin API: auto-discovery listener stopped", err)
+			}
+			return
+		}
+		if !strings.Contains(strings.ToLower(string(buf[:n])), discoveryQuery) {
+			continue
+		}
+		info := discoveryInfo{Address: discoveryAddress(ctx, remote), Id: d.serverID(ctx), Name: serverName()}
+		res, _ := json.Marshal(info)
+		log.Debug(ctx, "Jellyfin API: answering auto-discovery request", "from", remote.String(), "address", info.Address)
+		if _, err := conn.WriteTo(res, remote); err != nil {
+			log.Debug(ctx, "Jellyfin API: could not answer auto-discovery request", "to", remote.String(), err)
+		}
+	}
+}
+
+// Behind a unix socket nothing listens on Port, so only a BaseURL host gives clients an address.
+func hasAdvertisableAddress() bool {
+	return conf.Server.BaseHost != "" || !strings.HasPrefix(conf.Server.Address, "unix:")
+}
+
+func discoveryAddress(ctx context.Context, remote net.Addr) string {
+	scheme := gg.If(conf.Server.TLSEnabled(), "https", "http")
+	host := net.JoinHostPort(localIPFor(remote), strconv.Itoa(conf.Server.Port))
+	return publicurl.AbsoluteURL(request.WithServerAddress(ctx, scheme, host), consts.URLPathJellyfinAPI, nil)
+}
+
+// On a multi-homed host, only the interface that routes to the requester is reachable by it.
+func localIPFor(remote net.Addr) string {
+	if ip := parseIP(conf.Server.Address); ip.IsValid() && !ip.IsUnspecified() {
+		return ip.String()
+	}
+	c, err := net.Dial("udp", remote.String())
+	if err != nil {
+		return conf.Server.Address
+	}
+	defer c.Close()
+	return c.LocalAddr().(*net.UDPAddr).IP.String()
+}
diff --git a/server/jellyfin/discovery_test.go b/server/jellyfin/discovery_test.go
new file mode 100644
index 000000000..bcd11fe76
--- /dev/null
+++ b/server/jellyfin/discovery_test.go
@@ -0,0 +1,175 @@
+package jellyfin
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net"
+	"os"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type failingConn struct {
+	net.PacketConn
+	closed bool
+}
+
+func (c *failingConn) ReadFrom([]byte) (int, net.Addr, error) {
+	return 0, nil, errors.New("read failed")
+}
+
+func (c *failingConn) Close() error {
+	c.closed = true
+	return nil
+}
+
+var _ = Describe("Discovery", func() {
+	var d *Discovery
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.Jellyfin.ServerName = "Test Server"
+		conf.Server.Address = "0.0.0.0"
+		conf.Server.Port = 4533
+		conf.Server.BaseHost = ""
+		conf.Server.BaseScheme = ""
+		conf.Server.BasePath = ""
+		conf.Server.TLSCert = ""
+		conf.Server.TLSKey = ""
+		d = &Discovery{}
+	})
+
+	DescribeTable("discoveryAddress",
+		func(setup func(), expected string) {
+			setup()
+			remote := &net.UDPAddr{IP: net.ParseIP("127.0.0.1"), Port: 50000}
+			Expect(discoveryAddress(context.Background(), remote)).To(Equal(expected))
+		},
+		Entry("uses the BaseURL host and scheme when set", func() {
+			conf.Server.BaseScheme = "https"
+			conf.Server.BaseHost = "music.example.com"
+			conf.Server.BasePath = "/nd"
+		}, "https://music.example.com/nd/jellyfin"),
+		Entry("uses a specific bind Address with the Port", func() {
+			conf.Server.Address = "192.168.1.10"
+		}, "http://192.168.1.10:4533/jellyfin"),
+		Entry("falls back to the interface facing the requester when Address is unspecified", func() {},
+			"http://127.0.0.1:4533/jellyfin"),
+		Entry("falls back to the interface facing the requester when Address is empty", func() {
+			conf.Server.Address = ""
+		}, "http://127.0.0.1:4533/jellyfin"),
+		Entry("advertises https when TLS is configured", func() {
+			conf.Server.TLSCert = "/path/cert.pem"
+			conf.Server.TLSKey = "/path/key.pem"
+		}, "https://127.0.0.1:4533/jellyfin"),
+		Entry("advertises http when only the TLS cert is configured", func() {
+			conf.Server.TLSCert = "/path/cert.pem"
+		}, "http://127.0.0.1:4533/jellyfin"),
+		Entry("keeps a path-only BaseURL as the path prefix", func() {
+			conf.Server.BasePath = "/music"
+		}, "http://127.0.0.1:4533/music/jellyfin"),
+		Entry("does not double the slash when BasePath has a trailing slash", func() {
+			conf.Server.BasePath = "/music/"
+		}, "http://127.0.0.1:4533/music/jellyfin"),
+	)
+
+	DescribeTable("hasAdvertisableAddress",
+		func(address, baseHost string, expected bool) {
+			conf.Server.Address = address
+			conf.Server.BaseHost = baseHost
+			Expect(hasAdvertisableAddress()).To(Equal(expected))
+		},
+		Entry("TCP listener", "0.0.0.0", "", true),
+		Entry("unix socket without a BaseURL host", "unix:/tmp/navidrome.sock", "", false),
+		Entry("unix socket behind a proxy named by BaseURL", "unix:/tmp/navidrome.sock", "music.example.com", true),
+	)
+
+	It("closes the connection when the read loop fails", func() {
+		fake := &failingConn{}
+		d.ServeOn(context.Background(), fake)
+		Expect(fake.closed).To(BeTrue())
+	})
+
+	Describe("ServeOn", func() {
+		var (
+			server net.PacketConn
+			client net.PacketConn
+			cancel context.CancelFunc
+			done   chan struct{}
+		)
+
+		BeforeEach(func() {
+			var err error
+			server, err = net.ListenPacket("udp4", "127.0.0.1:0")
+			Expect(err).ToNot(HaveOccurred())
+			client, err = net.ListenPacket("udp4", "127.0.0.1:0")
+			Expect(err).ToNot(HaveOccurred())
+			DeferCleanup(client.Close)
+
+			var ctx context.Context
+			ctx, cancel = context.WithCancel(context.Background())
+			done = make(chan struct{})
+			go func() {
+				defer close(done)
+				d.ServeOn(ctx, server)
+			}()
+			DeferCleanup(func() {
+				cancel()
+				Eventually(done).Should(BeClosed())
+			})
+		})
+
+		send := func(msg string) {
+			_, err := client.WriteTo([]byte(msg), server.LocalAddr())
+			Expect(err).ToNot(HaveOccurred())
+		}
+		receive := func() ([]byte, error) {
+			Expect(client.SetReadDeadline(time.Now().Add(time.Second))).To(Succeed())
+			buf := make([]byte, 1024)
+			n, _, err := client.ReadFrom(buf)
+			return buf[:n], err
+		}
+
+		It("answers the discovery query with the server identity", func() {
+			send("who is JellyfinServer?")
+			res, err := receive()
+			Expect(err).ToNot(HaveOccurred())
+
+			var info discoveryInfo
+			Expect(json.Unmarshal(res, &info)).To(Succeed())
+			Expect(info.Address).To(Equal("http://127.0.0.1:4533/jellyfin"))
+			Expect(info.Id).To(Equal(d.serverID(context.Background())))
+			Expect(info.Name).To(Equal("Test Server"))
+			Expect(string(res)).To(ContainSubstring(`"EndpointAddress":null`))
+		})
+
+		It("matches the query case-insensitively", func() {
+			send("WHO IS JELLYFINSERVER?")
+			_, err := receive()
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		// The loop is serial, so a reply to the first packet would arrive before the second's.
+		It("ignores unrelated packets", func() {
+			send("who is PlexServer?")
+			send("who is JellyfinServer?")
+			_, err := receive()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(client.SetReadDeadline(time.Now().Add(50 * time.Millisecond))).To(Succeed())
+			_, _, err = client.ReadFrom(make([]byte, 1024))
+			Expect(errors.Is(err, os.ErrDeadlineExceeded)).To(BeTrue())
+		})
+
+		It("stops and closes the socket when the context is cancelled", func() {
+			cancel()
+			Eventually(done).Should(BeClosed())
+			_, _, err := server.ReadFrom(make([]byte, 1))
+			Expect(err).To(HaveOccurred())
+		})
+	})
+})
diff --git a/server/jellyfin/e2e/discovery_test.go b/server/jellyfin/e2e/discovery_test.go
new file mode 100644
index 000000000..0126ef3c6
--- /dev/null
+++ b/server/jellyfin/e2e/discovery_test.go
@@ -0,0 +1,50 @@
+package e2e
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"time"
+
+	"github.com/navidrome/navidrome/server/jellyfin"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Auto discovery", func() {
+	BeforeEach(func() { setupTestDB() })
+
+	It("advertises the same Id and Name as /System/Info/Public", func() {
+		server, err := net.ListenPacket("udp4", "127.0.0.1:0")
+		Expect(err).ToNot(HaveOccurred())
+		client, err := net.ListenPacket("udp4", "127.0.0.1:0")
+		Expect(err).ToNot(HaveOccurred())
+		DeferCleanup(client.Close)
+
+		ctx, cancel := context.WithCancel(context.Background())
+		done := make(chan struct{})
+		go func() {
+			defer close(done)
+			jellyfin.NewDiscovery(ds).ServeOn(ctx, server)
+		}()
+		DeferCleanup(func() {
+			cancel()
+			Eventually(done).Should(BeClosed())
+		})
+
+		_, err = client.WriteTo([]byte("who is JellyfinServer?"), server.LocalAddr())
+		Expect(err).ToNot(HaveOccurred())
+		Expect(client.SetReadDeadline(time.Now().Add(time.Second))).To(Succeed())
+		buf := make([]byte, 1024)
+		n, _, err := client.ReadFrom(buf)
+		Expect(err).ToNot(HaveOccurred())
+		var reply map[string]any
+		Expect(json.Unmarshal(buf[:n], &reply)).To(Succeed())
+
+		var pub map[string]any
+		parseInto(rawReq("GET", "/System/Info/Public", ""), &pub)
+		Expect(reply["Id"]).To(Equal(pub["Id"]))
+		Expect(reply["Name"]).To(Equal(pub["ServerName"]))
+		Expect(reply["Address"]).To(HaveSuffix("/jellyfin"))
+	})
+})
diff --git a/server/jellyfin/system.go b/server/jellyfin/system.go
index 0a85d4545..35ade5ff1 100644
--- a/server/jellyfin/system.go
+++ b/server/jellyfin/system.go
@@ -10,6 +10,7 @@ import (
 	"net/netip"
 	"path"
 	"strings"
+	"sync"
 
 	"github.com/google/uuid"
 	"github.com/navidrome/navidrome/conf"
@@ -24,35 +25,37 @@ import (
 // it (Streamyfin and the Android apps refuse < 10.10), and some parsers need exactly three parts.
 const jellyfinVersion = "12.1.0"
 
-func (api *Router) serverName() string {
+func serverName() string {
 	if conf.Server.Jellyfin.ServerName != "" {
 		return conf.Server.Jellyfin.ServerName
 	}
 	return fmt.Sprintf("Navidrome %s", consts.Version)
 }
 
-// serverID returns a stable Id that survives restarts, get-or-created in the Property table.
-// Jellyfin clients cache ServerId across sessions, so a per-process value would break
-// re-authentication. api.ds is nil only in unit tests; New() always sets it.
-//
-// The mutex serializes first-boot resolution so concurrent requests can't persist different
-// UUIDs. Only a successful read or persisted id is cached; a transient failure yields a
-// temporary id and retries on the next request rather than pinning a value.
 func (api *Router) serverID(ctx context.Context) string {
-	api.serverIDMu.Lock()
-	defer api.serverIDMu.Unlock()
-	if api.serverIDVal != "" {
-		return api.serverIDVal
+	return resolveServerID(ctx, api.ds, &api.serverIDVal)
+}
+
+// Package-level: the Router and Discovery are separate objects and must not persist different ids.
+var serverIDMu sync.Mutex
+
+// Clients cache ServerId across sessions, so it is persisted. Only a successful read or write is
+// cached: a transient failure yields a temporary id and retries on the next call.
+func resolveServerID(ctx context.Context, ds model.DataStore, cached *string) string {
+	serverIDMu.Lock()
+	defer serverIDMu.Unlock()
+	if *cached != "" {
+		return *cached
 	}
-	if api.ds == nil {
-		api.serverIDVal = newServerID()
-		return api.serverIDVal
+	if ds == nil {
+		*cached = newServerID()
+		return *cached
 	}
-	id, err := api.ds.Property(ctx).Get(consts.JellyfinServerIDKey)
+	id, err := ds.Property(ctx).Get(consts.JellyfinServerIDKey)
 	switch {
 	case errors.Is(err, model.ErrNotFound):
 		id = newServerID()
-		if err := api.ds.Property(ctx).Put(consts.JellyfinServerIDKey, id); err != nil {
+		if err := ds.Property(ctx).Put(consts.JellyfinServerIDKey, id); err != nil {
 			log.Error(ctx, "Jellyfin API: could not persist server id", err)
 			return id
 		}
@@ -61,8 +64,8 @@ func (api *Router) serverID(ctx context.Context) string {
 		return newServerID()
 	}
 	// Ids persisted before this change are dashed; normalize on read rather than rewriting the DB.
-	api.serverIDVal = strings.ReplaceAll(id, "-", "")
-	return api.serverIDVal
+	*cached = strings.ReplaceAll(id, "-", "")
+	return *cached
 }
 
 // newServerID returns a UUID in Jellyfin's no-dash GUID form (Guid.ToString("N")).
@@ -74,7 +77,7 @@ func newServerID() string {
 func (api *Router) publicInfo(r *http.Request) dto.PublicSystemInfo {
 	return dto.PublicSystemInfo{
 		LocalAddress:           localAddress(r),
-		ServerName:             api.serverName(),
+		ServerName:             serverName(),
 		Version:                jellyfinVersion,
 		ProductName:            "Jellyfin Server",
 		Id:                     api.serverID(r.Context()),
@@ -106,7 +109,7 @@ func (api *Router) getSystemInfo(w http.ResponseWriter, r *http.Request) {
 func (api *Router) ping(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
 	w.WriteHeader(http.StatusOK)
-	_, _ = w.Write([]byte(api.serverName()))
+	_, _ = w.Write([]byte(serverName()))
 }
 
 // getEndpointInfo answers /System/Endpoint, which Finamp's connection test uses to pick between a
diff --git a/server/jellyfin/system_test.go b/server/jellyfin/system_test.go
index 4b3ac240e..c9368f3b5 100644
--- a/server/jellyfin/system_test.go
+++ b/server/jellyfin/system_test.go
@@ -7,6 +7,7 @@ import (
 	"net"
 	"net/http"
 	"net/http/httptest"
+	"sync"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -173,6 +174,17 @@ var _ = Describe("System", func() {
 			Expect(second.serverID(ctx)).To(Equal(id))
 		})
 
+		It("resolves one id when a Router and a Discovery race on first boot", func() {
+			r, d := &Router{ds: ds}, NewDiscovery(ds)
+			ids := make([]string, 2)
+			var wg sync.WaitGroup
+			wg.Go(func() { ids[0] = r.serverID(ctx) })
+			wg.Go(func() { ids[1] = d.serverID(ctx) })
+			wg.Wait()
+			Expect(ids[0]).ToNot(BeEmpty())
+			Expect(ids[1]).To(Equal(ids[0]))
+		})
+
 		It("memoizes the id across repeated calls on the same Router", func() {
 			r := &Router{ds: ds}
 			id := r.serverID(ctx)
diff --git a/server/jellyfin/users.go b/server/jellyfin/users.go
index ee4ace48e..dddcd99da 100644
--- a/server/jellyfin/users.go
+++ b/server/jellyfin/users.go
@@ -34,7 +34,7 @@ func (api *Router) getUserViews(w http.ResponseWriter, r *http.Request) {
 func (api *Router) getCurrentUser(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	u, _ := request.UserFrom(ctx)
-	api.ok(w, r, userToDto(&u, api.serverName(), api.serverID(ctx)))
+	api.ok(w, r, userToDto(&u, serverName(), api.serverID(ctx)))
 }
 
 // getPublicUsers advertises the users named in Jellyfin.ExposedPublicUsers for a client login

From be8ec15168b78fda2b30db659f394df2d34e9a00 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 19 Sep 2026 14:07:42 -0400
Subject: [PATCH 151/200] feat(ui): format dates using the selected language
 (#6160)

Dates were rendered with the browser locale, ignoring the language chosen in
Personal settings, so a user browsing in German still saw US-style dates. All
date rendering now resolves its locale through a useDateLocale hook that returns
the selected language, augmented with the region from navigator.languages when
the language carries none (Intl reads a bare "en" as en-US). Applied to
DateField, the rated/loved tooltips, the mobile user list and album release
dates; the three inline timestamp tooltips now share a formatDateTime helper.

Closes #229
---
 ui/src/album/AlbumDetails.jsx     |  9 ++++---
 ui/src/common/DateField.jsx       |  4 ++-
 ui/src/common/DateField.test.jsx  | 32 ++++++++++++++++++++++
 ui/src/common/LoveButton.jsx      |  5 +++-
 ui/src/common/RatingField.jsx     |  5 +++-
 ui/src/i18n/useDateLocale.js      | 14 ++++++++++
 ui/src/i18n/useDateLocale.test.js | 45 +++++++++++++++++++++++++++++++
 ui/src/user/UserList.jsx          |  5 +++-
 ui/src/utils/formatters.js        |  3 +++
 9 files changed, 115 insertions(+), 7 deletions(-)
 create mode 100644 ui/src/common/DateField.test.jsx
 create mode 100644 ui/src/i18n/useDateLocale.js
 create mode 100644 ui/src/i18n/useDateLocale.test.js

diff --git a/ui/src/album/AlbumDetails.jsx b/ui/src/album/AlbumDetails.jsx
index f55d94ffc..7fbc479db 100644
--- a/ui/src/album/AlbumDetails.jsx
+++ b/ui/src/album/AlbumDetails.jsx
@@ -31,6 +31,7 @@ import {
   SizeField,
   useAlbumsPerPage,
 } from '../common'
+import { useDateLocale } from '../i18n/useDateLocale'
 import { formatFullDate, intersperse } from '../utils'
 import AlbumExternalLinks from './AlbumExternalLinks'
 import { SafeHTML } from '../common/SafeHTML'
@@ -151,6 +152,7 @@ export const Details = (props) => {
   const isXsmall = useMediaQuery((theme) => theme.breakpoints.down('xs'))
   const translate = useTranslate()
   const record = useRecordContext(props)
+  const locale = useDateLocale()
 
   // Create an array of detail elements
   let details = []
@@ -161,12 +163,13 @@ export const Details = (props) => {
 
   // Calculate date related fields
   const yearRange = formatRange(record, 'year')
-  const date = record.date ? formatFullDate(record.date) : yearRange
+  const date = record.date ? formatFullDate(record.date, locale) : yearRange
 
   const originalDate = record.originalDate
-    ? formatFullDate(record.originalDate)
+    ? formatFullDate(record.originalDate, locale)
     : formatRange(record, 'originalYear')
-  const releaseDate = record?.releaseDate && formatFullDate(record.releaseDate)
+  const releaseDate =
+    record?.releaseDate && formatFullDate(record.releaseDate, locale)
 
   const dateToUse = originalDate || date
   const isOriginalDate = originalDate && dateToUse !== date
diff --git a/ui/src/common/DateField.jsx b/ui/src/common/DateField.jsx
index dce24a2b9..dac9cff08 100644
--- a/ui/src/common/DateField.jsx
+++ b/ui/src/common/DateField.jsx
@@ -1,12 +1,14 @@
 import React from 'react'
 import { isDateSet } from '../utils/validations'
 import { DateField as RADateField } from 'react-admin'
+import { useDateLocale } from '../i18n/useDateLocale'
 
 export const DateField = (props) => {
   const { record, source } = props
+  const locale = useDateLocale()
   const value = record?.[source]
   if (!isDateSet(value)) return null
-  return <RADateField {...props} />
+  return <RADateField locales={locale} {...props} />
 }
 
 DateField.defaultProps = {
diff --git a/ui/src/common/DateField.test.jsx b/ui/src/common/DateField.test.jsx
new file mode 100644
index 000000000..47d56756b
--- /dev/null
+++ b/ui/src/common/DateField.test.jsx
@@ -0,0 +1,32 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { DateField } from './DateField'
+
+vi.mock('react-admin', async (importOriginal) => ({
+  ...(await importOriginal()),
+  useLocale: vi.fn(),
+}))
+
+describe('<DateField>', () => {
+  const record = { id: '1', updatedAt: '2026-09-17T14:30:00Z' }
+
+  beforeEach(async () => {
+    vi.clearAllMocks()
+    vi.spyOn(navigator, 'languages', 'get').mockReturnValue([])
+    const { useLocale } = await import('react-admin')
+    vi.mocked(useLocale).mockReturnValue('de')
+  })
+
+  it('formats the date using the selected language', () => {
+    render(<DateField record={record} source="updatedAt" />)
+    expect(screen.getByText('17.9.2026')).toBeInTheDocument()
+  })
+
+  it('renders nothing when the date is not set', () => {
+    const { container } = render(
+      <DateField record={{ id: '1' }} source="updatedAt" />,
+    )
+    expect(container).toBeEmptyDOMElement()
+  })
+})
diff --git a/ui/src/common/LoveButton.jsx b/ui/src/common/LoveButton.jsx
index 492ba95b3..128b375c2 100644
--- a/ui/src/common/LoveButton.jsx
+++ b/ui/src/common/LoveButton.jsx
@@ -6,6 +6,8 @@ import IconButton from '@material-ui/core/IconButton'
 import { makeStyles } from '@material-ui/core/styles'
 import clsx from 'clsx'
 import { useToggleLove } from './useToggleLove'
+import { useDateLocale } from '../i18n/useDateLocale'
+import { formatDateTime } from '../utils/formatters'
 import { useRecordContext } from 'react-admin'
 import config from '../config'
 import { isDateSet } from '../utils/validations'
@@ -40,6 +42,7 @@ export const LoveButton = ({
   const record = useRecordContext({ record: recordProp }) || {}
   const classes = useStyles({ color, visible, loved: record.starred })
   const [toggleLove, loading] = useToggleLove(resource, record)
+  const locale = useDateLocale()
 
   const handleToggleLove = useCallback(
     (e) => {
@@ -61,7 +64,7 @@ export const LoveButton = ({
       className={clsx(classes.love, className)}
       title={
         isDateSet(record.starredAt)
-          ? new Date(record.starredAt).toLocaleString()
+          ? formatDateTime(record.starredAt, locale)
           : undefined
       }
       {...rest}
diff --git a/ui/src/common/RatingField.jsx b/ui/src/common/RatingField.jsx
index f92b0d948..f892b475a 100644
--- a/ui/src/common/RatingField.jsx
+++ b/ui/src/common/RatingField.jsx
@@ -6,6 +6,8 @@ import { isDateSet } from '../utils/validations'
 import StarBorderIcon from '@material-ui/icons/StarBorder'
 import clsx from 'clsx'
 import { useRating } from './useRating'
+import { useDateLocale } from '../i18n/useDateLocale'
+import { formatDateTime } from '../utils/formatters'
 import { useRecordContext } from 'react-admin'
 
 const useStyles = makeStyles({
@@ -32,6 +34,7 @@ export const RatingField = ({
   const record = useRecordContext(rest) || {}
   const [rate, rating] = useRating(resource, record)
   const classes = useStyles({ color, visible })
+  const locale = useDateLocale()
 
   const stopPropagation = (e) => {
     e.stopPropagation()
@@ -50,7 +53,7 @@ export const RatingField = ({
       onClick={(e) => stopPropagation(e)}
       title={
         isDateSet(record.ratedAt)
-          ? new Date(record.ratedAt).toLocaleString()
+          ? formatDateTime(record.ratedAt, locale)
           : undefined
       }
     >
diff --git a/ui/src/i18n/useDateLocale.js b/ui/src/i18n/useDateLocale.js
new file mode 100644
index 000000000..c9298a473
--- /dev/null
+++ b/ui/src/i18n/useDateLocale.js
@@ -0,0 +1,14 @@
+import { useLocale } from 'react-admin'
+
+// Our language codes are mostly region-less ("en"), and Intl reads a bare "en"
+// as en-US. Borrow the region from the browser when it speaks the same language.
+const resolveDateLocale = (locale, browserLocales = []) => {
+  if (!locale || locale.includes('-')) return locale
+  const base = locale.toLowerCase()
+  return (
+    browserLocales.find((l) => l.toLowerCase().split('-')[0] === base) || locale
+  )
+}
+
+export const useDateLocale = () =>
+  resolveDateLocale(useLocale(), navigator.languages)
diff --git a/ui/src/i18n/useDateLocale.test.js b/ui/src/i18n/useDateLocale.test.js
new file mode 100644
index 000000000..c0ea5ab40
--- /dev/null
+++ b/ui/src/i18n/useDateLocale.test.js
@@ -0,0 +1,45 @@
+import { renderHook } from '@testing-library/react-hooks'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useDateLocale } from './useDateLocale'
+
+vi.mock('react-admin', () => ({
+  useLocale: vi.fn(),
+}))
+
+describe('useDateLocale', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const renderWith = async (locale, browserLocales) => {
+    const { useLocale } = await import('react-admin')
+    vi.mocked(useLocale).mockReturnValue(locale)
+    vi.spyOn(navigator, 'languages', 'get').mockReturnValue(browserLocales)
+    return renderHook(() => useDateLocale()).result
+  }
+
+  it('adds the region from the browser when the language has none', async () => {
+    const result = await renderWith('en', ['en-GB', 'fr-FR'])
+    expect(result.current).toEqual('en-GB')
+  })
+
+  it('falls back to the language when no browser entry matches', async () => {
+    const result = await renderWith('de', ['en-US', 'fr-FR'])
+    expect(result.current).toEqual('de')
+  })
+
+  it('keeps a language that already carries a region or script', async () => {
+    expect((await renderWith('pt-br', ['pt-PT'])).current).toEqual('pt-br')
+    expect((await renderWith('zh-Hans', ['zh-TW'])).current).toEqual('zh-Hans')
+  })
+
+  it('matches the browser language case-insensitively', async () => {
+    const result = await renderWith('pt', ['PT-PT'])
+    expect(result.current).toEqual('PT-PT')
+  })
+
+  it('returns undefined when there is no language', async () => {
+    const result = await renderWith(undefined, ['en-GB'])
+    expect(result.current).toBeUndefined()
+  })
+})
diff --git a/ui/src/user/UserList.jsx b/ui/src/user/UserList.jsx
index 4faf31785..7922ca08d 100644
--- a/ui/src/user/UserList.jsx
+++ b/ui/src/user/UserList.jsx
@@ -9,6 +9,8 @@ import {
 } from 'react-admin'
 import { useMediaQuery } from '@material-ui/core'
 import { List, DateField } from '../common'
+import { useDateLocale } from '../i18n/useDateLocale'
+import { formatDateTime } from '../utils/formatters'
 
 const UserFilter = (props) => (
   <Filter {...props} variant={'outlined'}>
@@ -18,6 +20,7 @@ const UserFilter = (props) => (
 
 const UserList = (props) => {
   const isXsmall = useMediaQuery((theme) => theme.breakpoints.down('xs'))
+  const locale = useDateLocale()
 
   return (
     <List
@@ -31,7 +34,7 @@ const UserList = (props) => {
         <SimpleList
           primaryText={(record) => record.userName}
           secondaryText={(record) =>
-            record.lastLoginAt && new Date(record.lastLoginAt).toLocaleString()
+            record.lastLoginAt && formatDateTime(record.lastLoginAt, locale)
           }
           tertiaryText={(record) => (record.isAdmin ? '[admin]️' : '')}
         />
diff --git a/ui/src/utils/formatters.js b/ui/src/utils/formatters.js
index cfcb84b05..f7c59c195 100644
--- a/ui/src/utils/formatters.js
+++ b/ui/src/utils/formatters.js
@@ -95,6 +95,9 @@ export const formatFullDate = (date, locale) => {
   return new Date(date).toLocaleDateString(locale, options)
 }
 
+export const formatDateTime = (value, locale) =>
+  new Date(value).toLocaleString(locale)
+
 export const formatNumber = (value, locale) => {
   if (value === null || value === undefined) return '0'
   return value.toLocaleString(locale)

From b76ae14286179b9dd69b2a958124ed4a7d032dff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 19 Sep 2026 14:57:01 -0400
Subject: [PATCH 152/200] feat(jellyfin): add Quick Connect sign-in (#6174)

* feat(jellyfin): add Quick Connect sign-in

Jellyfin clients can now sign in without a password: the client shows a
6-digit code, a signed-in user approves it, and the client redeems a secret
for its access token.

- core/quickconnect: in-memory store shared by both routers through wire.
  Codes expire after 10 minutes; a secret redeems only once (Jellyfin
  allows repeats for 10 minutes); at most 1000 pending requests.
- Jellyfin API: Initiate, Connect, Authorize and AuthenticateWithQuickConnect.
  Admins may approve for another user via UserId, like Swiftfin's admin page.
  Initiate and redeem share the login rate limiter; Connect does not, since
  Finamp and Streamyfin poll it every second.
- Web UI: a Quick Connect item in the user menu looks up the code and shows
  the app and device before approving, so a user can't be tricked into
  approving an unknown device blindly.
- Jellyfin.QuickConnect option, on by default like Jellyfin. It only matters
  when the Jellyfin API is enabled.

* refactor(jellyfin): tidy Quick Connect naming and route guards

Group the Quick Connect routes under one requireQuickConnect guard, make the
request's device a named field so req.Device.ID can't be mistaken for a
request id, and rename the web API response type to quickConnectDevice.

* refactor(jellyfin): remove duplicated Jellyfin date formatting function

* test(jellyfin): set play count and starred in the song fixture literal

* refactor(jellyfin): inline the Quick Connect redeem body and use the shared date helper

* fix(jellyfin): bound the client fields Quick Connect keeps in memory

Initiate is unauthenticated and keeps the Client, Device, DeviceId and Version
header fields for up to ten minutes. With no header size limit, each pending
request could hold about 1 MB, and even a short field kept the whole header
alive because the parsed values are substrings of it. Reject fields over 512
bytes and copy the stored values.

Also answer 500 instead of 401 when the redeem user lookup fails for a reason
other than the user being gone.

* fix(jellyfin): rate-limit Quick Connect code approval

Any signed-in user could try codes without limit on the Jellyfin Authorize
endpoint and the web UI lookup/authorize endpoints, and so could approve
another person's pending device for their own account. Apply the same per-IP
limiter as the login (AuthRequestLimit/AuthWindowLength) to both surfaces.
---
 cmd/wire_gen.go                               |   7 +-
 conf/configuration.go                         |   2 +
 core/quickconnect/quickconnect.go             | 203 ++++++++++++
 core/quickconnect/quickconnect_suite_test.go  |  17 +
 core/quickconnect/quickconnect_test.go        | 190 +++++++++++
 core/wire_providers.go                        |   2 +
 server/jellyfin/README.md                     |  27 +-
 server/jellyfin/api.go                        |  17 +-
 server/jellyfin/api_test.go                   |  40 ++-
 server/jellyfin/auth.go                       |   7 +-
 server/jellyfin/dto/dto.go                    |  11 +
 server/jellyfin/dto/mappers.go                |  20 +-
 server/jellyfin/dto/mappers_test.go           |   6 +-
 server/jellyfin/e2e/e2e_suite_test.go         |   2 +
 server/jellyfin/e2e/quickconnect_test.go      |  91 ++++++
 server/jellyfin/e2e/system_test.go            |   8 -
 server/jellyfin/quickconnect.go               | 145 +++++++++
 server/jellyfin/quickconnect_test.go          | 301 ++++++++++++++++++
 server/jellyfin/routing_test.go               |   2 +-
 server/jellyfin/socket_test.go                |   2 +-
 server/jellyfin/system.go                     |   4 -
 server/jellyfin/system_test.go                |  11 -
 server/nativeapi/config_test.go               |   2 +-
 server/nativeapi/library_test.go              |   2 +-
 server/nativeapi/metadata_test.go             |   2 +-
 server/nativeapi/missing_test.go              |   2 +-
 server/nativeapi/native_api.go                |   7 +-
 server/nativeapi/native_api_song_test.go      |   2 +-
 server/nativeapi/playlists_test.go            |   2 +-
 server/nativeapi/plugin_test.go               |   2 +-
 server/nativeapi/quickconnect.go              |  76 +++++
 server/nativeapi/quickconnect_test.go         | 148 +++++++++
 .../user_password_token_refresh_test.go       |   2 +-
 server/serve_index.go                         |   2 +
 server/serve_index_test.go                    |   2 +
 ui/src/config.js                              |   1 +
 ui/src/dataProvider/wrapperDataProvider.js    |   9 +
 ui/src/dialogs/QuickConnectDialog.jsx         | 128 ++++++++
 ui/src/dialogs/QuickConnectDialog.test.jsx    | 103 ++++++
 ui/src/dialogs/index.js                       |   1 +
 ui/src/i18n/en.json                           |  11 +
 ui/src/layout/AppBar.jsx                      |  73 +++--
 ui/src/layout/AppBar.test.jsx                 |  22 ++
 43 files changed, 1626 insertions(+), 88 deletions(-)
 create mode 100644 core/quickconnect/quickconnect.go
 create mode 100644 core/quickconnect/quickconnect_suite_test.go
 create mode 100644 core/quickconnect/quickconnect_test.go
 create mode 100644 server/jellyfin/e2e/quickconnect_test.go
 create mode 100644 server/jellyfin/quickconnect.go
 create mode 100644 server/jellyfin/quickconnect_test.go
 create mode 100644 server/nativeapi/quickconnect.go
 create mode 100644 server/nativeapi/quickconnect_test.go
 create mode 100644 ui/src/dialogs/QuickConnectDialog.jsx
 create mode 100644 ui/src/dialogs/QuickConnectDialog.test.jsx

diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index d6bf4da07..43ba808d0 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -21,6 +21,7 @@ import (
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playback"
 	"github.com/navidrome/navidrome/core/playlists"
+	"github.com/navidrome/navidrome/core/quickconnect"
 	"github.com/navidrome/navidrome/core/scrobbler"
 	"github.com/navidrome/navidrome/core/sonic"
 	"github.com/navidrome/navidrome/core/stream"
@@ -79,7 +80,8 @@ func CreateNativeAPIRouter(ctx context.Context) *nativeapi.Router {
 	agentsAgents := agents.GetAgents(dataStore, manager)
 	matcherMatcher := matcher.New(dataStore)
 	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher, broker)
-	router := nativeapi.New(dataStore, share, playlistsPlaylists, insights, library, user, maintenance, manager, uploader, provider)
+	quickConnect := quickconnect.GetInstance()
+	router := nativeapi.New(dataStore, share, playlistsPlaylists, insights, library, user, maintenance, manager, uploader, provider, quickConnect)
 	return router
 }
 
@@ -135,7 +137,8 @@ func CreateJellyfinAPIRouter(ctx context.Context) *jellyfin.Router {
 	provider := external.NewProvider(dataStore, agentsAgents, matcherMatcher, broker)
 	sonicSonic := sonic.New(dataStore, manager, matcherMatcher)
 	lyricsLyrics := lyrics.NewLyrics(dataStore, manager)
-	router := jellyfin.New(dataStore, artworkArtwork, mediaStreamer, transcodeDecider, players, playTracker, playlistsPlaylists, provider, sonicSonic, lyricsLyrics, broker)
+	quickConnect := quickconnect.GetInstance()
+	router := jellyfin.New(dataStore, artworkArtwork, mediaStreamer, transcodeDecider, players, playTracker, playlistsPlaylists, provider, sonicSonic, lyricsLyrics, broker, quickConnect)
 	return router
 }
 
diff --git a/conf/configuration.go b/conf/configuration.go
index 4812f2515..6f295ebeb 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -236,6 +236,7 @@ type jellyfinOptions struct {
 	// GET /Users/Public, so Jellyfin clients can show a login user-picker. Empty exposes no users.
 	ExposedPublicUsers string
 	AutoDiscovery      bool
+	QuickConnect       bool
 	// MaxConcurrentStreams bounds how many collection responses can stream at once. Each holds a DB
 	// cursor — and its pooled connection — for the whole client-paced response, so without a bound
 	// enough slow clients would take the entire pool and stall the scanner, scrobbles and the UI.
@@ -1089,6 +1090,7 @@ func setViperDefaults() {
 	viper.SetDefault("jellyfin.enabled", false)
 	viper.SetDefault("jellyfin.servername", "")
 	viper.SetDefault("jellyfin.autodiscovery", false)
+	viper.SetDefault("jellyfin.quickconnect", true)
 	viper.SetDefault("enablescrobblehistory", true)
 	viper.SetDefault("httpheaders.frameoptions", "DENY")
 	viper.SetDefault("backup.path", "")
diff --git a/core/quickconnect/quickconnect.go b/core/quickconnect/quickconnect.go
new file mode 100644
index 000000000..9b69bc904
--- /dev/null
+++ b/core/quickconnect/quickconnect.go
@@ -0,0 +1,203 @@
+// Package quickconnect implements Jellyfin-style Quick Connect: a new client shows a short code, and
+// an already signed-in user approves it, so the client can sign in without a password.
+package quickconnect
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/random"
+	"github.com/navidrome/navidrome/utils/singleton"
+)
+
+const timeout = 10 * time.Minute
+
+// Initiate is unauthenticated, so the number of live requests must be bounded.
+const maxPending = 1000
+
+var (
+	ErrAlreadyAuthorized = errors.New("quick connect request already authorized")
+	ErrTooManyRequests   = errors.New("too many pending quick connect requests")
+)
+
+type Device struct {
+	ID         string
+	Name       string
+	App        string
+	AppVersion string
+}
+
+type Request struct {
+	Device    Device
+	Secret    string
+	Code      string
+	DateAdded time.Time
+	UserID    string
+}
+
+func (r Request) Authorized() bool {
+	return r.UserID != ""
+}
+
+type QuickConnect interface {
+	Initiate(device Device) (Request, error)
+	Status(secret string) (Request, error)
+	// Lookup returns a request still waiting for approval.
+	Lookup(code string) (Request, error)
+	Authorize(code, userID string) (Request, error)
+	// Redeem returns the id of the user who approved the request. It succeeds only once per secret.
+	Redeem(secret string) (string, error)
+}
+
+type entry struct {
+	Request
+	expiresAt time.Time
+}
+
+type quickConnect struct {
+	mu       sync.Mutex
+	bySecret map[string]*entry
+	byCode   map[string]*entry
+}
+
+// GetInstance returns the shared store: the Jellyfin and native API routers must see the same requests.
+func GetInstance() QuickConnect {
+	return singleton.GetInstance(newStore)
+}
+
+func New() QuickConnect {
+	return newStore()
+}
+
+func newStore() *quickConnect {
+	return &quickConnect{
+		bySecret: map[string]*entry{},
+		byCode:   map[string]*entry{},
+	}
+}
+
+// Enabled reports whether users can approve codes from the web UI, which needs the Jellyfin API.
+func Enabled() bool {
+	return conf.Server.Jellyfin.Enabled && conf.Server.Jellyfin.QuickConnect
+}
+
+func (qc *quickConnect) Initiate(device Device) (Request, error) {
+	qc.mu.Lock()
+	defer qc.mu.Unlock()
+	qc.expire()
+	if len(qc.bySecret) >= maxPending {
+		return Request{}, ErrTooManyRequests
+	}
+	// The fields may be substrings of a much larger header; copy them so the header isn't retained.
+	device = Device{ID: strings.Clone(device.ID), Name: strings.Clone(device.Name),
+		App: strings.Clone(device.App), AppVersion: strings.Clone(device.AppVersion)}
+	now := time.Now()
+	e := &entry{
+		Request:   Request{Device: device, Secret: newSecret(), Code: qc.newCode(), DateAdded: now},
+		expiresAt: now.Add(timeout),
+	}
+	qc.bySecret[e.Secret] = e
+	qc.byCode[e.Code] = e
+	return e.Request, nil
+}
+
+func (qc *quickConnect) Status(secret string) (Request, error) {
+	qc.mu.Lock()
+	defer qc.mu.Unlock()
+	e, err := qc.find(qc.bySecret, secret)
+	if err != nil {
+		return Request{}, err
+	}
+	return e.Request, nil
+}
+
+func (qc *quickConnect) Lookup(code string) (Request, error) {
+	qc.mu.Lock()
+	defer qc.mu.Unlock()
+	e, err := qc.findPending(code)
+	if err != nil {
+		return Request{}, err
+	}
+	return e.Request, nil
+}
+
+func (qc *quickConnect) Authorize(code, userID string) (Request, error) {
+	qc.mu.Lock()
+	defer qc.mu.Unlock()
+	e, err := qc.findPending(code)
+	if err != nil {
+		return Request{}, err
+	}
+	e.UserID = userID
+	e.expiresAt = time.Now().Add(timeout)
+	return e.Request, nil
+}
+
+func (qc *quickConnect) Redeem(secret string) (string, error) {
+	qc.mu.Lock()
+	defer qc.mu.Unlock()
+	e, err := qc.find(qc.bySecret, secret)
+	if err != nil || !e.Authorized() {
+		return "", model.ErrNotFound
+	}
+	qc.remove(e)
+	return e.UserID, nil
+}
+
+func (qc *quickConnect) find(index map[string]*entry, key string) (*entry, error) {
+	qc.expire()
+	e, ok := index[key]
+	if !ok {
+		return nil, model.ErrNotFound
+	}
+	return e, nil
+}
+
+func (qc *quickConnect) findPending(code string) (*entry, error) {
+	e, err := qc.find(qc.byCode, normalizeCode(code))
+	if err == nil && e.Authorized() {
+		return nil, ErrAlreadyAuthorized
+	}
+	return e, err
+}
+
+func (qc *quickConnect) expire() {
+	now := time.Now()
+	for _, e := range qc.bySecret {
+		if !now.Before(e.expiresAt) {
+			qc.remove(e)
+		}
+	}
+}
+
+func (qc *quickConnect) remove(e *entry) {
+	delete(qc.bySecret, e.Secret)
+	delete(qc.byCode, e.Code)
+}
+
+func (qc *quickConnect) newCode() string {
+	for {
+		code := fmt.Sprintf("%06d", random.Int64N(900000)+100000)
+		if _, taken := qc.byCode[code]; !taken {
+			return code
+		}
+	}
+}
+
+func newSecret() string {
+	b := make([]byte, 32)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}
+
+// Users often type the code in groups ("123 456").
+func normalizeCode(code string) string {
+	return strings.Join(strings.Fields(code), "")
+}
diff --git a/core/quickconnect/quickconnect_suite_test.go b/core/quickconnect/quickconnect_suite_test.go
new file mode 100644
index 000000000..029f4e333
--- /dev/null
+++ b/core/quickconnect/quickconnect_suite_test.go
@@ -0,0 +1,17 @@
+package quickconnect
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestQuickConnect(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "QuickConnect Suite")
+}
diff --git a/core/quickconnect/quickconnect_test.go b/core/quickconnect/quickconnect_test.go
new file mode 100644
index 000000000..b03186807
--- /dev/null
+++ b/core/quickconnect/quickconnect_test.go
@@ -0,0 +1,190 @@
+package quickconnect
+
+import (
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var device = Device{ID: "dev-1", Name: "Pixel 7", App: "Finamp", AppVersion: "1.0.0"}
+
+var _ = Describe("QuickConnect", func() {
+	var qc QuickConnect
+
+	BeforeEach(func() {
+		qc = New()
+	})
+
+	Describe("Initiate", func() {
+		It("creates a pending request with a 6-digit code and a random secret", func() {
+			req, err := qc.Initiate(device)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(req.Code).To(MatchRegexp(`^[1-9]\d{5}$`))
+			Expect(req.Secret).To(MatchRegexp(`^[0-9a-f]{64}$`))
+			Expect(req.Device).To(Equal(device))
+			Expect(req.DateAdded).ToNot(BeZero())
+			Expect(req.Authorized()).To(BeFalse())
+		})
+
+		It("never gives two live requests the same code or secret", func() {
+			codes := map[string]bool{}
+			secrets := map[string]bool{}
+			for range 500 {
+				req, err := qc.Initiate(device)
+				Expect(err).ToNot(HaveOccurred())
+				codes[req.Code] = true
+				secrets[req.Secret] = true
+			}
+			Expect(codes).To(HaveLen(500))
+			Expect(secrets).To(HaveLen(500))
+		})
+
+		It("refuses new requests when too many are pending", func() {
+			for range maxPending {
+				_, err := qc.Initiate(device)
+				Expect(err).ToNot(HaveOccurred())
+			}
+			_, err := qc.Initiate(device)
+			Expect(err).To(MatchError(ErrTooManyRequests))
+		})
+	})
+
+	Describe("Status", func() {
+		It("returns the request for a known secret", func() {
+			req, _ := qc.Initiate(device)
+			got, err := qc.Status(req.Secret)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got).To(Equal(req))
+		})
+
+		It("returns ErrNotFound for an unknown secret", func() {
+			_, err := qc.Status("nope")
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+	})
+
+	Describe("Lookup", func() {
+		It("finds a request by code, ignoring spaces", func() {
+			req, _ := qc.Initiate(device)
+			got, err := qc.Lookup(req.Code[:3] + " " + req.Code[3:])
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got).To(Equal(req))
+		})
+
+		It("returns ErrNotFound for an unknown code", func() {
+			_, err := qc.Lookup("000000")
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
+		It("refuses a request that is already authorized", func() {
+			req, _ := qc.Initiate(device)
+			_, _ = qc.Authorize(req.Code, "user-1")
+			_, err := qc.Lookup(req.Code)
+			Expect(err).To(MatchError(ErrAlreadyAuthorized))
+		})
+	})
+
+	Describe("Authorize", func() {
+		It("marks the request as authorized by the user", func() {
+			req, _ := qc.Initiate(device)
+			got, err := qc.Authorize(" "+req.Code+" ", "user-1")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(got.Authorized()).To(BeTrue())
+			Expect(got.UserID).To(Equal("user-1"))
+
+			status, _ := qc.Status(req.Secret)
+			Expect(status.Authorized()).To(BeTrue())
+		})
+
+		It("refuses a request that is already authorized", func() {
+			req, _ := qc.Initiate(device)
+			_, _ = qc.Authorize(req.Code, "user-1")
+			_, err := qc.Authorize(req.Code, "user-2")
+			Expect(err).To(MatchError(ErrAlreadyAuthorized))
+		})
+
+		It("returns ErrNotFound for an unknown code", func() {
+			_, err := qc.Authorize("000000", "user-1")
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+	})
+
+	Describe("Redeem", func() {
+		It("returns the approving user once, then forgets the request", func() {
+			req, _ := qc.Initiate(device)
+			_, _ = qc.Authorize(req.Code, "user-1")
+
+			userID, err := qc.Redeem(req.Secret)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(userID).To(Equal("user-1"))
+
+			_, err = qc.Redeem(req.Secret)
+			Expect(err).To(MatchError(model.ErrNotFound))
+			_, err = qc.Status(req.Secret)
+			Expect(err).To(MatchError(model.ErrNotFound))
+			_, err = qc.Lookup(req.Code)
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+
+		It("refuses a request that is not authorized yet", func() {
+			req, _ := qc.Initiate(device)
+			_, err := qc.Redeem(req.Secret)
+			Expect(err).To(MatchError(model.ErrNotFound))
+			_, err = qc.Status(req.Secret)
+			Expect(err).ToNot(HaveOccurred())
+		})
+	})
+})
+
+// Plain tests: testing/synctest needs a *testing.T, which Ginkgo doesn't give.
+func TestPendingRequestExpires(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		g := NewWithT(t)
+		qc := New()
+		req, _ := qc.Initiate(device)
+
+		time.Sleep(timeout - time.Second)
+		_, err := qc.Status(req.Secret)
+		g.Expect(err).ToNot(HaveOccurred())
+
+		time.Sleep(2 * time.Second)
+		_, err = qc.Status(req.Secret)
+		g.Expect(err).To(MatchError(model.ErrNotFound))
+		_, err = qc.Authorize(req.Code, "user-1")
+		g.Expect(err).To(MatchError(model.ErrNotFound))
+	})
+}
+
+func TestAuthorizeExtendsExpiry(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		g := NewWithT(t)
+		qc := New()
+		req, _ := qc.Initiate(device)
+
+		time.Sleep(timeout - time.Second)
+		_, err := qc.Authorize(req.Code, "user-1")
+		g.Expect(err).ToNot(HaveOccurred())
+
+		time.Sleep(timeout - time.Second)
+		userID, err := qc.Redeem(req.Secret)
+		g.Expect(err).ToNot(HaveOccurred())
+		g.Expect(userID).To(Equal("user-1"))
+	})
+}
+
+func TestExpiredRequestsFreeCapacity(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		g := NewWithT(t)
+		qc := New()
+		for range maxPending {
+			_, _ = qc.Initiate(device)
+		}
+		time.Sleep(timeout + time.Second)
+		_, err := qc.Initiate(device)
+		g.Expect(err).ToNot(HaveOccurred())
+	})
+}
diff --git a/core/wire_providers.go b/core/wire_providers.go
index a09fcc108..b3df9b2dc 100644
--- a/core/wire_providers.go
+++ b/core/wire_providers.go
@@ -10,6 +10,7 @@ import (
 	"github.com/navidrome/navidrome/core/metrics"
 	"github.com/navidrome/navidrome/core/playback"
 	"github.com/navidrome/navidrome/core/playlists"
+	"github.com/navidrome/navidrome/core/quickconnect"
 	"github.com/navidrome/navidrome/core/scrobbler"
 	"github.com/navidrome/navidrome/core/stream"
 )
@@ -32,6 +33,7 @@ var Set = wire.NewSet(
 	ffmpeg.New,
 	scrobbler.GetPlayTracker,
 	playback.GetInstance,
+	quickconnect.GetInstance,
 	metrics.GetInstance,
 	lyrics.NewLyrics,
 )
diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index 893642cdd..c0c5e6ca1 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -24,6 +24,8 @@ ServerName = "My Music Server"
 ExposedPublicUsers = "alice, bob"
 # Optional: answer LAN auto-discovery broadcasts on UDP 7359 (default: false). See "Auto discovery".
 AutoDiscovery = true
+# Optional: let users sign in new devices with a 6-digit code (default: true). See "Quick Connect".
+QuickConnect = false
 # Optional: max collection responses streaming at once (default: half the DB connection pool,
 # min 2). Each streaming response holds a DB connection for its whole duration; excess requests
 # queue rather than fail.
@@ -37,6 +39,7 @@ ND_JELLYFIN_ENABLED=true
 ND_JELLYFIN_SERVERNAME="My Music Server"
 ND_JELLYFIN_EXPOSEDPUBLICUSERS="alice,bob"
 ND_JELLYFIN_AUTODISCOVERY=true
+ND_JELLYFIN_QUICKCONNECT=false
 ```
 
 Once enabled, the API is mounted at:
@@ -82,6 +85,27 @@ surface.
 
 Access tokens do not expire, matching real Jellyfin. They are revoked by a password change, which bumps the user's token epoch.
 
+### Quick Connect
+
+Quick Connect signs a new device in without typing a password. The client shows a 6-digit code,
+a signed-in user approves it, and the client gets its `AccessToken`. It is on by default
+(`Jellyfin.QuickConnect`); when off, `GET QuickConnect/Enabled` returns `false` and every other
+Quick Connect call returns 401.
+
+1. `POST QuickConnect/Initiate` (public; needs `Client`, `Device`, `DeviceId` and `Version` in the
+   auth header) returns the `Code` and a `Secret`.
+2. The user approves the code, either in the Navidrome web UI (user menu → **Quick Connect**, which
+   shows the app and device before approving) or from a signed-in Jellyfin client with
+   `POST QuickConnect/Authorize?Code=`. Admins may pass `UserId` to approve for another user.
+3. The client polls `GET QuickConnect/Connect?Secret=` until `Authenticated` is `true`.
+4. `POST Users/AuthenticateWithQuickConnect` with `{"Secret": "..."}` returns the same result as
+   `AuthenticateByName`.
+
+Pending codes live in memory and expire after 10 minutes (a server restart drops them). Unlike
+Jellyfin, a secret signs in only once. `Initiate`, `AuthenticateWithQuickConnect` and code approval
+(`Authorize` and the web UI) are rate-limited per IP like the login; `Connect` is not, since some
+clients poll it every second.
+
 ### Public user list (login picker)
 
 `GET /Users/Public` lets a client render a login user-picker (tap a user, then just type the
@@ -140,7 +164,8 @@ returns direct children only (no tracks — no track is a library's direct child
 
 | Area | Endpoints |
 |---|---|
-| Handshake / system | `GET System/Info/Public`, `GET System/Info` (authenticated), `GET`/`POST System/Ping`, `GET System/Endpoint` (authenticated), `GET QuickConnect/Enabled` |
+| Handshake / system | `GET System/Info/Public`, `GET System/Info` (authenticated), `GET`/`POST System/Ping`, `GET System/Endpoint` (authenticated) |
+| Quick Connect | `GET QuickConnect/Enabled`, `POST QuickConnect/Initiate`, `GET QuickConnect/Connect`, `POST QuickConnect/Authorize` (authenticated), `POST Users/AuthenticateWithQuickConnect` |
 | Auth | `POST Users/AuthenticateByName`, `GET Users/Public` |
 | Users | `GET UserViews`, `GET Users/{userId}/Views`, `GET Users/Me`, `GET Users/{userId}` |
 | Browsing | `GET Items`, `GET Users/{userId}/Items`, `GET Items/{itemId}`, `GET Users/{userId}/Items/{itemId}`, `GET Users/{userId}/Items/Latest`, `DELETE Items/{itemId}` (playlists only) |
diff --git a/server/jellyfin/api.go b/server/jellyfin/api.go
index eddd14f66..4a471d1f0 100644
--- a/server/jellyfin/api.go
+++ b/server/jellyfin/api.go
@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/core/lyrics"
 	"github.com/navidrome/navidrome/core/playlists"
+	"github.com/navidrome/navidrome/core/quickconnect"
 	"github.com/navidrome/navidrome/core/scrobbler"
 	"github.com/navidrome/navidrome/core/sonic"
 	"github.com/navidrome/navidrome/core/stream"
@@ -40,17 +41,18 @@ type Router struct {
 	broker           events.Broker
 	lyricsCache      cache.SimpleCache[string, model.LyricList]
 	similarFlight    singleflight.Group
+	quickConnect     quickconnect.QuickConnect
 	serverIDVal      string
 }
 
 func New(ds model.DataStore, artwork artwork.Artwork, streamer stream.MediaStreamer,
 	transcodeDecider stream.TranscodeDecider, players core.Players,
 	scrobbler scrobbler.PlayTracker, playlists playlists.Playlists, provider external.Provider,
-	sonicSvc sonic.Engine, lyricsSvc lyrics.Lyrics, broker events.Broker) *Router {
+	sonicSvc sonic.Engine, lyricsSvc lyrics.Lyrics, broker events.Broker, quickConnect quickconnect.QuickConnect) *Router {
 	r := &Router{
 		ds: ds, artwork: artwork, streamer: streamer, transcodeDecider: transcodeDecider,
 		players: players, scrobbler: scrobbler, playlists: playlists, provider: provider,
-		sonic: sonicSvc, lyrics: lyricsSvc, broker: broker,
+		sonic: sonicSvc, lyrics: lyricsSvc, broker: broker, quickConnect: quickConnect,
 		lyricsCache: cache.NewSimpleCache[string, model.LyricList](cache.Options{
 			SizeLimit:  1000,
 			DefaultTTL: 5 * time.Minute,
@@ -81,6 +83,11 @@ func (api *Router) routes() http.Handler {
 		login = login.With(server.ClientIPRateLimiter(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength))
 	}
 	login.Post("/users/authenticatebyname", api.authenticateByName)
+	quickConnectLogin := login.With(requireQuickConnect)
+	quickConnectLogin.Post("/quickconnect/initiate", api.quickConnectInitiate)
+	quickConnectLogin.Post("/users/authenticatewithquickconnect", api.authenticateWithQuickConnect)
+	// Not rate-limited: Finamp and Streamyfin poll it every second while the code is shown.
+	inner.With(requireQuickConnect).Get("/quickconnect/connect", api.quickConnectConnect)
 	inner.Get("/users/public", api.getPublicUsers)
 
 	// Images are intentionally public: artwork isn't sensitive, matching Jellyfin's image handling.
@@ -107,6 +114,12 @@ func (api *Router) routes() http.Handler {
 		r.Get("/users/{userId}/views", api.getUserViews)
 		r.Get("/users/me", api.getCurrentUser)
 		r.Get("/users/{userId}", api.getCurrentUser)
+		// Throttled like login so a signed-in user cannot enumerate other people's pending codes.
+		approve := r.With(requireQuickConnect)
+		if conf.Server.AuthRequestLimit > 0 {
+			approve = approve.With(server.ClientIPRateLimiter(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength))
+		}
+		approve.Post("/quickconnect/authorize", api.quickConnectAuthorize)
 
 		// Cursor-backed collections: each streams straight from the DB, holding a connection for the
 		// whole client-paced response, so enough slow clients would take the entire pool and stall the
diff --git a/server/jellyfin/api_test.go b/server/jellyfin/api_test.go
index 605303793..a64dcfe8f 100644
--- a/server/jellyfin/api_test.go
+++ b/server/jellyfin/api_test.go
@@ -10,6 +10,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/quickconnect"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -19,7 +20,7 @@ import (
 var _ = Describe("Router", func() {
 	It("serves the public handshake through the mounted handler", func() {
 		ds := &tests.MockDataStore{}
-		api := New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		api := New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("GET", "/System/Info/Public", nil)
 		api.ServeHTTP(w, r)
@@ -27,7 +28,7 @@ var _ = Describe("Router", func() {
 	})
 
 	It("returns 404 JSON for unknown routes", func() {
-		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("GET", "/Nonexistent/Route", nil)
 		api.ServeHTTP(w, r)
@@ -37,7 +38,7 @@ var _ = Describe("Router", func() {
 	})
 
 	It("returns 404 JSON for a known path with an unsupported method", func() {
-		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("PATCH", "/System/Info/Public", nil)
 		api.ServeHTTP(w, r)
@@ -54,7 +55,7 @@ var _ = Describe("Router", func() {
 		Expect(err).ToNot(HaveOccurred())
 
 		fp := &fakePlayers{}
-		api := New(ds, nil, nil, nil, fp, nil, nil, nil, nil, nil, nil)
+		api := New(ds, nil, nil, nil, fp, nil, nil, nil, nil, nil, nil, nil)
 
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("GET", "/Users/Me", nil)
@@ -71,7 +72,7 @@ var _ = Describe("Router", func() {
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.AuthRequestLimit = 2
 		conf.Server.AuthWindowLength = time.Minute
-		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 
 		login := func() int {
 			w := httptest.NewRecorder()
@@ -86,11 +87,38 @@ var _ = Describe("Router", func() {
 		Expect(login()).To(Equal(http.StatusTooManyRequests))
 	})
 
+	It("rate-limits Quick Connect approval by IP when a login limit is configured", func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.AuthRequestLimit = 2
+		conf.Server.AuthWindowLength = time.Minute
+		conf.Server.Jellyfin.QuickConnect = true
+		ds := &tests.MockDataStore{}
+		auth.Init(ds)
+		usr := model.User{ID: testID("alice"), UserName: "alice"}
+		Expect(ds.User(GinkgoT().Context()).Put(&usr)).To(Succeed())
+		token, err := auth.CreateAPIToken(&usr, auth.AudienceJellyfin)
+		Expect(err).ToNot(HaveOccurred())
+		api := New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, quickconnect.New())
+
+		authorize := func() int {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("POST", "/QuickConnect/Authorize?code=000000", nil)
+			r.RemoteAddr = "10.0.0.1:1234"
+			r.Header.Set("X-Emby-Token", token)
+			api.ServeHTTP(w, r)
+			return w.Code
+		}
+		// An unknown code is 404; the limiter cuts in on the 3rd attempt with 429.
+		Expect(authorize()).To(Equal(http.StatusNotFound))
+		Expect(authorize()).To(Equal(http.StatusNotFound))
+		Expect(authorize()).To(Equal(http.StatusTooManyRequests))
+	})
+
 	It("rate-limits AuthenticateByName by resolved client IP, not by the proxy connection", func() {
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.AuthRequestLimit = 1
 		conf.Server.AuthWindowLength = time.Minute
-		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		api := New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		// Every request arrives on the same proxy connection, so only the resolved client IP
 		// can separate the buckets.
 		handler := middleware.ClientIPFromHeader("X-Real-IP")(api)
diff --git a/server/jellyfin/auth.go b/server/jellyfin/auth.go
index ba4fe40f1..32b4a1432 100644
--- a/server/jellyfin/auth.go
+++ b/server/jellyfin/auth.go
@@ -30,10 +30,15 @@ func (api *Router) authenticateByName(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Unauthorized", http.StatusUnauthorized)
 		return
 	}
+	api.signIn(w, r, usr)
+}
+
+func (api *Router) signIn(w http.ResponseWriter, r *http.Request, usr *model.User) {
+	ctx := r.Context()
 	// Best-effort, like the web UI's validateLogin: without it, Jellyfin-only users show a
 	// never/stale "Last Login" in the admin UI.
 	if err := api.ds.User(ctx).UpdateLastLoginAt(usr.ID); err != nil {
-		log.Error(ctx, "Jellyfin API: could not update last login date", "username", body.Username, err)
+		log.Error(ctx, "Jellyfin API: could not update last login date", "username", usr.UserName, err)
 	}
 
 	token, err := auth.CreateAPIToken(usr, auth.AudienceJellyfin)
diff --git a/server/jellyfin/dto/dto.go b/server/jellyfin/dto/dto.go
index 21e3903f2..4a28eb313 100644
--- a/server/jellyfin/dto/dto.go
+++ b/server/jellyfin/dto/dto.go
@@ -233,6 +233,17 @@ type PlayerStateInfo struct {
 	PlaybackOrder string `json:"PlaybackOrder"`
 }
 
+type QuickConnectResult struct {
+	Authenticated bool   `json:"Authenticated"`
+	Secret        string `json:"Secret"`
+	Code          string `json:"Code"`
+	DeviceId      string `json:"DeviceId"`
+	DeviceName    string `json:"DeviceName"`
+	AppName       string `json:"AppName"`
+	AppVersion    string `json:"AppVersion"`
+	DateAdded     string `json:"DateAdded"`
+}
+
 type AuthenticationResult struct {
 	User        *UserDto     `json:"User"`
 	SessionInfo *SessionInfo `json:"SessionInfo"`
diff --git a/server/jellyfin/dto/mappers.go b/server/jellyfin/dto/mappers.go
index bb17b40c7..fc7e329de 100644
--- a/server/jellyfin/dto/mappers.go
+++ b/server/jellyfin/dto/mappers.go
@@ -51,16 +51,16 @@ func premiereDate(date string, year int) *string {
 	if err != nil {
 		return nil
 	}
-	s := jellyfinDate(&parsed)
+	s := JellyfinDate(&parsed)
 	return &s
 }
 
 // Dates use .NET's round-trip layout, 7 fractional digits and all: Manet rejects plain RFC3339.
 const jellyfinDateLayout = "2006-01-02T15:04:05.0000000Z07:00"
 
-// jellyfinDate formats t as the date string clients expect, or "" for the zero time so the
+// JellyfinDate formats t as the date string clients expect, or "" for the zero time so the
 // field is omitted rather than sent as a meaningless epoch.
-func jellyfinDate(t *time.Time) string {
+func JellyfinDate(t *time.Time) string {
 	if t == nil || t.IsZero() {
 		return ""
 	}
@@ -135,7 +135,7 @@ func UserData(a model.Annotations, itemID string) *UserItemDataDto {
 		r := float64(a.Rating) * 2 // Navidrome 0-5 -> Jellyfin 0-10
 		d.Rating = &r
 	}
-	if s := jellyfinDate(a.PlayDate); s != "" {
+	if s := JellyfinDate(a.PlayDate); s != "" {
 		d.LastPlayedDate = &s
 	}
 	return d
@@ -159,7 +159,7 @@ func SongToBaseItem(mf model.MediaFile, fields Fields) BaseItemDto {
 		AlbumId:           albumID,
 		AlbumArtist:       mf.AlbumArtist,
 		RunTimeTicks:      TicksFromSeconds(mf.Duration),
-		DateCreated:       jellyfinDate(&mf.CreatedAt),
+		DateCreated:       JellyfinDate(&mf.CreatedAt),
 		Container:         mf.Suffix,
 		CanDownload:       true,
 		BackdropImageTags: []string{},
@@ -265,7 +265,7 @@ func AlbumToBaseItem(al model.Album, fields Fields) BaseItemDto {
 		ChildCount:              new(al.SongCount),
 		SongCount:               new(al.SongCount),
 		RunTimeTicks:            TicksFromSeconds(al.Duration),
-		DateCreated:             jellyfinDate(&al.CreatedAt),
+		DateCreated:             JellyfinDate(&al.CreatedAt),
 		ImageBlurHashes:         blurs,
 		PrimaryImageAspectRatio: ratio,
 		BackdropImageTags:       []string{},
@@ -318,7 +318,7 @@ func ArtistToBaseItem(ar model.Artist, fields Fields) BaseItemDto {
 		IsFolder:                true,
 		AlbumCount:              new(ar.AlbumCount),
 		SongCount:               new(ar.SongCount),
-		DateCreated:             jellyfinDate(ar.CreatedAt),
+		DateCreated:             JellyfinDate(ar.CreatedAt),
 		ImageBlurHashes:         blurs,
 		PrimaryImageAspectRatio: ratio,
 		BackdropImageTags:       []string{},
@@ -346,7 +346,7 @@ func LibraryToBaseItem(lib model.Library) BaseItemDto {
 		IsFolder:          true,
 		Path:              lib.Path,
 		LocationType:      "FileSystem",
-		DateCreated:       jellyfinDate(&lib.CreatedAt),
+		DateCreated:       JellyfinDate(&lib.CreatedAt),
 		ChildCount:        new(lib.TotalAlbums),
 		UserData:          &UserItemDataDto{Key: id, ItemId: id},
 		BackdropImageTags: []string{},
@@ -386,7 +386,7 @@ func PlaylistToBaseItem(p model.Playlist, fields Fields) BaseItemDto {
 		MediaType:               "Audio",
 		ChildCount:              new(p.SongCount),
 		RunTimeTicks:            TicksFromSeconds(p.Duration),
-		DateCreated:             jellyfinDate(&p.CreatedAt),
+		DateCreated:             JellyfinDate(&p.CreatedAt),
 		ImageBlurHashes:         blurs,
 		PrimaryImageAspectRatio: ratio,
 		BackdropImageTags:       []string{},
@@ -460,7 +460,7 @@ func NewSessionInfo(u *model.User, client, deviceID, deviceName, version, server
 		DeviceName:         deviceName,
 		ApplicationVersion: version,
 		ServerId:           serverID,
-		LastActivityDate:   jellyfinDate(&now),
+		LastActivityDate:   JellyfinDate(&now),
 		IsActive:           true,
 		PlayableMediaTypes: []string{"Audio"},
 		SupportedCommands:  []string{},
diff --git a/server/jellyfin/dto/mappers_test.go b/server/jellyfin/dto/mappers_test.go
index 6dc177363..259904673 100644
--- a/server/jellyfin/dto/mappers_test.go
+++ b/server/jellyfin/dto/mappers_test.go
@@ -17,10 +17,10 @@ var _ = Describe("mappers", func() {
 			ID: testID("song-1"), Title: "Song", Album: "Alb", AlbumID: testID("alb-1"),
 			Artist: "Art", AlbumArtist: "AA", TrackNumber: 3, DiscNumber: 1,
 			Year: 1999, Duration: 60, Size: 2_500_000,
-			Genres: []model.Genre{{ID: testID("1"), Name: "genre 1"}, {ID: testID("2"), Name: "genre 2"}},
+			Genres:    []model.Genre{{ID: testID("1"), Name: "genre 1"}, {ID: testID("2"), Name: "genre 2"}},
+			PlayCount: 2,
+			Starred:   true,
 		}
-		mf.PlayCount = 2
-		mf.Starred = true
 		item := SongToBaseItem(mf, nil)
 		Expect(item.Type).To(Equal("Audio"))
 		Expect(item.MediaType).To(Equal("Audio"))
diff --git a/server/jellyfin/e2e/e2e_suite_test.go b/server/jellyfin/e2e/e2e_suite_test.go
index 1ee19ea01..aa93f7e38 100644
--- a/server/jellyfin/e2e/e2e_suite_test.go
+++ b/server/jellyfin/e2e/e2e_suite_test.go
@@ -44,6 +44,7 @@ import (
 	"github.com/navidrome/navidrome/core/lyrics"
 	"github.com/navidrome/navidrome/core/matcher"
 	"github.com/navidrome/navidrome/core/playlists"
+	"github.com/navidrome/navidrome/core/quickconnect"
 	"github.com/navidrome/navidrome/core/scrobbler"
 	"github.com/navidrome/navidrome/core/sonic"
 	"github.com/navidrome/navidrome/core/storage/storagetest"
@@ -338,6 +339,7 @@ func setupTestDB() {
 		sonicSvc,
 		lyrics.NewLyrics(ds, nil),
 		events.NoopBroker(),
+		quickconnect.New(),
 	)
 }
 
diff --git a/server/jellyfin/e2e/quickconnect_test.go b/server/jellyfin/e2e/quickconnect_test.go
new file mode 100644
index 000000000..1beffc56f
--- /dev/null
+++ b/server/jellyfin/e2e/quickconnect_test.go
@@ -0,0 +1,91 @@
+package e2e
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/server/jellyfin/dto"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("QuickConnect", func() {
+	BeforeEach(func() {
+		setupTestDB()
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.Jellyfin.QuickConnect = true
+	})
+
+	clientReq := func(deviceID, method, path, body string) *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(method, path, strings.NewReader(body))
+		r.Header.Set("Authorization", `MediaBrowser Client="Finamp", Device="Pixel 7", DeviceId="`+deviceID+`", Version="1.0"`)
+		r.Header.Set("Content-Type", "application/json")
+		router.ServeHTTP(w, r)
+		return w
+	}
+	initiate := func() dto.QuickConnectResult {
+		var pending dto.QuickConnectResult
+		parseInto(clientReq("new-device", "POST", "/QuickConnect/Initiate", ""), &pending)
+		Expect(pending.Authenticated).To(BeFalse())
+		return pending
+	}
+	redeem := func(deviceID, secret string) *httptest.ResponseRecorder {
+		return clientReq(deviceID, "POST", "/Users/AuthenticateWithQuickConnect", `{"Secret":"`+secret+`"}`)
+	}
+
+	It("signs a new client in with a code approved by a signed-in user", func() {
+		Expect(rawReq("GET", "/QuickConnect/Enabled", "").Body.String()).To(MatchJSON("true"))
+		pending := initiate()
+
+		Expect(postAs(regularUser, "/QuickConnect/Authorize?Code="+pending.Code, "").Code).To(Equal(http.StatusOK))
+
+		var status dto.QuickConnectResult
+		parseInto(rawReq("GET", "/QuickConnect/Connect?Secret="+pending.Secret, ""), &status)
+		Expect(status.Authenticated).To(BeTrue())
+
+		// Android TV redeems with a different DeviceId than it initiated with.
+		w := redeem("other-device", pending.Secret)
+		Expect(w.Code).To(Equal(http.StatusOK))
+		var res dto.AuthenticationResult
+		parseInto(w, &res)
+		Expect(res.User.Name).To(Equal(regularUser.UserName))
+		Expect(res.SessionInfo).ToNot(BeNil())
+		Expect(res.SessionInfo.DeviceId).To(Equal("other-device"))
+
+		r := httptest.NewRequest("GET", "/Users/Me", nil)
+		r.Header.Set("X-Emby-Token", res.AccessToken)
+		me := httptest.NewRecorder()
+		router.ServeHTTP(me, r)
+		Expect(me.Code).To(Equal(http.StatusOK))
+
+		Expect(redeem("new-device", pending.Secret).Code).To(Equal(http.StatusNotFound))
+	})
+
+	It("lets an admin approve a code for another user", func() {
+		pending := initiate()
+		Expect(post("/QuickConnect/Authorize?Code="+pending.Code+"&UserId="+enc(regularUser.ID), "").Code).
+			To(Equal(http.StatusOK))
+
+		var res dto.AuthenticationResult
+		parseInto(redeem("new-device", pending.Secret), &res)
+		Expect(res.User.Name).To(Equal(regularUser.UserName))
+	})
+
+	It("requires authentication to approve a code", func() {
+		pending := initiate()
+		Expect(rawReq("POST", "/QuickConnect/Authorize?Code="+pending.Code, "").Code).To(Equal(http.StatusUnauthorized))
+	})
+
+	It("answers 401 on every Quick Connect call when disabled", func() {
+		conf.Server.Jellyfin.QuickConnect = false
+		Expect(rawReq("GET", "/QuickConnect/Enabled", "").Body.String()).To(MatchJSON("false"))
+		Expect(clientReq("new-device", "POST", "/QuickConnect/Initiate", "").Code).To(Equal(http.StatusUnauthorized))
+		Expect(rawReq("GET", "/QuickConnect/Connect?Secret=x", "").Code).To(Equal(http.StatusUnauthorized))
+		Expect(post("/QuickConnect/Authorize?Code=123456", "").Code).To(Equal(http.StatusUnauthorized))
+		Expect(redeem("new-device", "x").Code).To(Equal(http.StatusUnauthorized))
+	})
+})
diff --git a/server/jellyfin/e2e/system_test.go b/server/jellyfin/e2e/system_test.go
index ac8c350c4..51443bdc9 100644
--- a/server/jellyfin/e2e/system_test.go
+++ b/server/jellyfin/e2e/system_test.go
@@ -81,12 +81,4 @@ var _ = Describe("System", func() {
 			Expect(strings.TrimSpace(w.Body.String())).To(HavePrefix("Navidrome"))
 		})
 	})
-
-	Describe("GET /QuickConnect/Enabled", func() {
-		It("reports QuickConnect disabled", func() {
-			w := rawReq("GET", "/QuickConnect/Enabled", "")
-			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(strings.TrimSpace(w.Body.String())).To(Equal("false"))
-		})
-	})
 })
diff --git a/server/jellyfin/quickconnect.go b/server/jellyfin/quickconnect.go
new file mode 100644
index 000000000..c478b1894
--- /dev/null
+++ b/server/jellyfin/quickconnect.go
@@ -0,0 +1,145 @@
+package jellyfin
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/quickconnect"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/server/jellyfin/dto"
+)
+
+func requireQuickConnect(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !conf.Server.Jellyfin.QuickConnect {
+			http.Error(w, "Quick connect is disabled", http.StatusUnauthorized)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func (api *Router) quickConnectEnabled(w http.ResponseWriter, r *http.Request) {
+	api.ok(w, r, conf.Server.Jellyfin.QuickConnect)
+}
+
+// Initiate is unauthenticated and its fields are kept for minutes, so their size must be bounded.
+const maxQuickConnectField = 512
+
+func (api *Router) quickConnectInitiate(w http.ResponseWriter, r *http.Request) {
+	a := parseMediaBrowserAuth(r)
+	if a.Client == "" || a.Device == "" || a.DeviceId == "" || a.Version == "" ||
+		max(len(a.Client), len(a.Device), len(a.DeviceId), len(a.Version)) > maxQuickConnectField {
+		http.Error(w, "Client, Device, DeviceId and Version are required", http.StatusBadRequest)
+		return
+	}
+	req, err := api.quickConnect.Initiate(quickconnect.Device{
+		ID: a.DeviceId, Name: a.Device, App: a.Client, AppVersion: a.Version,
+	})
+	if errors.Is(err, quickconnect.ErrTooManyRequests) {
+		http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
+		return
+	}
+	if err != nil {
+		api.internalError(w, r, err)
+		return
+	}
+	api.ok(w, r, quickConnectResult(req))
+}
+
+func (api *Router) quickConnectConnect(w http.ResponseWriter, r *http.Request) {
+	req, err := api.quickConnect.Status(r.URL.Query().Get("secret"))
+	if err != nil {
+		http.Error(w, "Unknown secret", http.StatusNotFound)
+		return
+	}
+	api.ok(w, r, quickConnectResult(req))
+}
+
+func (api *Router) quickConnectAuthorize(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	caller, _ := request.UserFrom(ctx)
+	userID := caller.ID
+	if encoded := r.URL.Query().Get("userid"); encoded != "" {
+		var ok bool
+		if userID, ok = dto.DecodeID(encoded); !ok {
+			http.Error(w, "Invalid userId", http.StatusBadRequest)
+			return
+		}
+	}
+	target := caller
+	if userID != caller.ID {
+		if !caller.IsAdmin {
+			http.Error(w, "Forbidden", http.StatusForbidden)
+			return
+		}
+		usr, err := api.ds.User(ctx).Get(userID)
+		if errors.Is(err, model.ErrNotFound) {
+			http.Error(w, "Unknown user", http.StatusNotFound)
+			return
+		}
+		if err != nil {
+			api.internalError(w, r, err)
+			return
+		}
+		target = *usr
+	}
+
+	req, err := api.quickConnect.Authorize(r.URL.Query().Get("code"), target.ID)
+	switch {
+	case errors.Is(err, model.ErrNotFound):
+		http.Error(w, "Unknown code", http.StatusNotFound)
+	case errors.Is(err, quickconnect.ErrAlreadyAuthorized):
+		http.Error(w, "Code already used", http.StatusConflict)
+	case err != nil:
+		api.internalError(w, r, err)
+	default:
+		log.Info(ctx, "Jellyfin API: Quick Connect sign-in approved", "username", target.UserName,
+			"approvedBy", caller.UserName, "client", req.Device.App, "device", req.Device.Name)
+		api.ok(w, r, true)
+	}
+}
+
+func (api *Router) authenticateWithQuickConnect(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	var body struct {
+		Secret string `json:"Secret"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body.Secret == "" {
+		http.Error(w, "Bad Request", http.StatusBadRequest)
+		return
+	}
+	userID, err := api.quickConnect.Redeem(body.Secret)
+	if err != nil {
+		http.Error(w, "Unknown secret", http.StatusNotFound)
+		return
+	}
+	usr, err := api.ds.User(ctx).Get(userID)
+	if errors.Is(err, model.ErrNotFound) {
+		log.Warn(ctx, "Jellyfin API: Quick Connect user not found", "userID", userID)
+		http.Error(w, "Unauthorized", http.StatusUnauthorized)
+		return
+	}
+	if err != nil {
+		api.internalError(w, r, err)
+		return
+	}
+	api.signIn(w, r, usr)
+}
+
+func quickConnectResult(req quickconnect.Request) dto.QuickConnectResult {
+	return dto.QuickConnectResult{
+		Authenticated: req.Authorized(),
+		Secret:        req.Secret,
+		Code:          req.Code,
+		DeviceId:      req.Device.ID,
+		DeviceName:    req.Device.Name,
+		AppName:       req.Device.App,
+		AppVersion:    req.Device.AppVersion,
+		DateAdded:     dto.JellyfinDate(&req.DateAdded),
+	}
+}
diff --git a/server/jellyfin/quickconnect_test.go b/server/jellyfin/quickconnect_test.go
new file mode 100644
index 000000000..0478a356a
--- /dev/null
+++ b/server/jellyfin/quickconnect_test.go
@@ -0,0 +1,301 @@
+package jellyfin
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/quickconnect"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/server/jellyfin/dto"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type fullQuickConnect struct{ quickconnect.QuickConnect }
+
+func (fullQuickConnect) Initiate(quickconnect.Device) (quickconnect.Request, error) {
+	return quickconnect.Request{}, quickconnect.ErrTooManyRequests
+}
+
+var _ = Describe("QuickConnect", func() {
+	const finamp = `MediaBrowser Client="Finamp", Device="Pixel 7", DeviceId="dev-1", Version="1.0.0"`
+	var (
+		api   *Router
+		ds    *tests.MockDataStore
+		qc    quickconnect.QuickConnect
+		alice = model.User{ID: testID("alice"), UserName: "alice"}
+		bob   = model.User{ID: testID("bob"), UserName: "bob"}
+		admin = model.User{ID: testID("admin"), UserName: "admin", IsAdmin: true}
+	)
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.Jellyfin.QuickConnect = true
+		ds = &tests.MockDataStore{}
+		auth.Init(ds)
+		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
+		for _, u := range []model.User{alice, bob, admin} {
+			Expect(ur.Put(&u)).To(Succeed())
+		}
+		qc = quickconnect.New()
+		api = &Router{ds: ds, quickConnect: qc}
+	})
+
+	as := func(r *http.Request, u model.User) *http.Request {
+		return r.WithContext(request.WithUser(r.Context(), u))
+	}
+	initiate := func() quickconnect.Request {
+		req, err := qc.Initiate(quickconnect.Device{ID: "dev-1", Name: "Pixel 7", App: "Finamp", AppVersion: "1.0.0"})
+		Expect(err).ToNot(HaveOccurred())
+		return req
+	}
+
+	Describe("GET /QuickConnect/Enabled", func() {
+		DescribeTable("reports the config value",
+			func(enabled bool, expected string) {
+				conf.Server.Jellyfin.QuickConnect = enabled
+				w := httptest.NewRecorder()
+				api.quickConnectEnabled(w, httptest.NewRequest("GET", "/QuickConnect/Enabled", nil))
+				Expect(w.Code).To(Equal(http.StatusOK))
+				Expect(w.Body.String()).To(MatchJSON(expected))
+			},
+			Entry("enabled", true, "true"),
+			Entry("disabled", false, "false"),
+		)
+	})
+
+	Describe("requireQuickConnect", func() {
+		next := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusTeapot) })
+
+		It("rejects requests with 401 when Quick Connect is disabled", func() {
+			conf.Server.Jellyfin.QuickConnect = false
+			w := httptest.NewRecorder()
+			requireQuickConnect(next).ServeHTTP(w, httptest.NewRequest("POST", "/QuickConnect/Initiate", nil))
+			Expect(w.Code).To(Equal(http.StatusUnauthorized))
+		})
+
+		It("passes requests through when Quick Connect is enabled", func() {
+			w := httptest.NewRecorder()
+			requireQuickConnect(next).ServeHTTP(w, httptest.NewRequest("POST", "/QuickConnect/Initiate", nil))
+			Expect(w.Code).To(Equal(http.StatusTeapot))
+		})
+	})
+
+	Describe("POST /QuickConnect/Initiate", func() {
+		initiateWith := func(authHeader string) *httptest.ResponseRecorder {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("POST", "/QuickConnect/Initiate", nil)
+			r.Header.Set("Authorization", authHeader)
+			api.quickConnectInitiate(w, r)
+			return w
+		}
+
+		It("returns all QuickConnectResult fields, with the device from the auth header", func() {
+			w := initiateWith(finamp)
+
+			Expect(w.Code).To(Equal(http.StatusOK))
+			var raw map[string]any
+			Expect(json.Unmarshal(w.Body.Bytes(), &raw)).To(Succeed())
+			// sdk-kotlin declares every field non-null.
+			Expect(raw).To(HaveKeyWithValue("Authenticated", false))
+			Expect(raw).To(HaveKeyWithValue("Secret", MatchRegexp(`^[0-9a-f]{64}$`)))
+			Expect(raw).To(HaveKeyWithValue("Code", MatchRegexp(`^\d{6}$`)))
+			Expect(raw).To(HaveKeyWithValue("DeviceId", "dev-1"))
+			Expect(raw).To(HaveKeyWithValue("DeviceName", "Pixel 7"))
+			Expect(raw).To(HaveKeyWithValue("AppName", "Finamp"))
+			Expect(raw).To(HaveKeyWithValue("AppVersion", "1.0.0"))
+			Expect(raw).To(HaveKeyWithValue("DateAdded", Not(BeEmpty())))
+
+			_, err := qc.Status(raw["Secret"].(string))
+			Expect(err).ToNot(HaveOccurred())
+		})
+
+		It("returns 400 when the auth header does not identify the client", func() {
+			w := initiateWith(`MediaBrowser Client="Finamp", Device="Pixel 7", Version="1.0.0"`)
+			Expect(w.Code).To(Equal(http.StatusBadRequest))
+		})
+
+		It("returns 400 when a client field is oversized", func() {
+			long := strings.Repeat("x", maxQuickConnectField+1)
+			api.quickConnect = fullQuickConnect{qc}
+			w := initiateWith(`MediaBrowser Client="Finamp", Device="` + long + `", DeviceId="dev-1", Version="1.0.0"`)
+			Expect(w.Code).To(Equal(http.StatusBadRequest))
+		})
+
+		It("returns 429 when too many requests are pending", func() {
+			api.quickConnect = fullQuickConnect{qc}
+			Expect(initiateWith(finamp).Code).To(Equal(http.StatusTooManyRequests))
+		})
+	})
+
+	Describe("GET /QuickConnect/Connect", func() {
+		connect := func(secret string) (int, dto.QuickConnectResult) {
+			w := httptest.NewRecorder()
+			invoke(api.quickConnectConnect, w, httptest.NewRequest("GET", "/QuickConnect/Connect?Secret="+secret, nil))
+			var res dto.QuickConnectResult
+			if w.Code == http.StatusOK {
+				Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+			}
+			return w.Code, res
+		}
+
+		It("reports whether the request has been authorized", func() {
+			req := initiate()
+			code, res := connect(req.Secret)
+			Expect(code).To(Equal(http.StatusOK))
+			Expect(res.Authenticated).To(BeFalse())
+			Expect(res.Code).To(Equal(req.Code))
+
+			_, err := qc.Authorize(req.Code, alice.ID)
+			Expect(err).ToNot(HaveOccurred())
+			code, res = connect(req.Secret)
+			Expect(code).To(Equal(http.StatusOK))
+			Expect(res.Authenticated).To(BeTrue())
+		})
+
+		It("returns 404 for an unknown secret", func() {
+			code, _ := connect("unknown")
+			Expect(code).To(Equal(http.StatusNotFound))
+		})
+	})
+
+	Describe("POST /QuickConnect/Authorize", func() {
+		authorize := func(query string, u model.User) *httptest.ResponseRecorder {
+			w := httptest.NewRecorder()
+			invoke(api.quickConnectAuthorize, w, as(httptest.NewRequest("POST", "/QuickConnect/Authorize?"+query, nil), u))
+			return w
+		}
+		approver := func(req quickconnect.Request) string {
+			got, err := qc.Status(req.Secret)
+			Expect(err).ToNot(HaveOccurred())
+			return got.UserID
+		}
+
+		It("approves the code for the caller when no userId is given", func() {
+			req := initiate()
+			w := authorize("code="+req.Code, alice)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(w.Body.String()).To(MatchJSON("true"))
+			Expect(approver(req)).To(Equal(alice.ID))
+		})
+
+		It("accepts the caller's own userId", func() {
+			req := initiate()
+			w := authorize("Code="+req.Code+"&UserId="+dto.EncodeID(alice.ID), alice)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(approver(req)).To(Equal(alice.ID))
+		})
+
+		It("forbids a non-admin from approving for another user", func() {
+			req := initiate()
+			w := authorize("code="+req.Code+"&userId="+dto.EncodeID(bob.ID), alice)
+			Expect(w.Code).To(Equal(http.StatusForbidden))
+			Expect(approver(req)).To(BeEmpty())
+		})
+
+		It("lets an admin approve for another user", func() {
+			req := initiate()
+			w := authorize("code="+req.Code+"&userId="+dto.EncodeID(bob.ID), admin)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(approver(req)).To(Equal(bob.ID))
+		})
+
+		It("returns 404 when an admin approves for an unknown user", func() {
+			req := initiate()
+			w := authorize("code="+req.Code+"&userId="+dto.EncodeID(testID("ghost")), admin)
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+			Expect(approver(req)).To(BeEmpty())
+		})
+
+		It("returns 400 for a malformed userId", func() {
+			req := initiate()
+			w := authorize("code="+req.Code+"&userId=not-a-guid", admin)
+			Expect(w.Code).To(Equal(http.StatusBadRequest))
+		})
+
+		It("returns 404 for an unknown code", func() {
+			w := authorize("code=000000", alice)
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns 409 for a code that is already approved", func() {
+			req := initiate()
+			Expect(authorize("code="+req.Code, alice).Code).To(Equal(http.StatusOK))
+			Expect(authorize("code="+req.Code, bob).Code).To(Equal(http.StatusConflict))
+			Expect(approver(req)).To(Equal(alice.ID))
+		})
+	})
+
+	Describe("POST /Users/AuthenticateWithQuickConnect", func() {
+		redeem := func(body string) *httptest.ResponseRecorder {
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest("POST", "/Users/AuthenticateWithQuickConnect", strings.NewReader(body))
+			r.Header.Set("Authorization", finamp)
+			api.authenticateWithQuickConnect(w, r)
+			return w
+		}
+		redeemSecret := func(secret string) *httptest.ResponseRecorder {
+			return redeem(`{"Secret":"` + secret + `"}`)
+		}
+
+		It("signs in the approving user once", func() {
+			req := initiate()
+			_, _ = qc.Authorize(req.Code, alice.ID)
+
+			w := redeemSecret(req.Secret)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			var res dto.AuthenticationResult
+			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+			Expect(res.User.Name).To(Equal("alice"))
+			Expect(res.ServerId).ToNot(BeEmpty())
+			Expect(res.SessionInfo).ToNot(BeNil())
+			Expect(res.SessionInfo.DeviceId).To(Equal("dev-1"))
+			claims, err := auth.Validate(res.AccessToken)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(claims.Subject).To(Equal("alice"))
+
+			Expect(redeemSecret(req.Secret).Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("accepts a camelCase body", func() {
+			req := initiate()
+			_, _ = qc.Authorize(req.Code, alice.ID)
+			Expect(redeem(`{"secret":"` + req.Secret + `"}`).Code).To(Equal(http.StatusOK))
+		})
+
+		It("returns 404 while the request is not approved", func() {
+			req := initiate()
+			Expect(redeemSecret(req.Secret).Code).To(Equal(http.StatusNotFound))
+		})
+
+		DescribeTable("returns 400 for a bad body",
+			func(body string) {
+				Expect(redeem(body).Code).To(Equal(http.StatusBadRequest))
+			},
+			Entry("not JSON", `nope`),
+			Entry("no secret", `{}`),
+		)
+
+		It("returns 401 when the approving user no longer exists", func() {
+			req := initiate()
+			_, _ = qc.Authorize(req.Code, testID("ghost"))
+			Expect(redeemSecret(req.Secret).Code).To(Equal(http.StatusUnauthorized))
+		})
+
+		It("returns 500 when the user lookup fails", func() {
+			req := initiate()
+			_, _ = qc.Authorize(req.Code, alice.ID)
+			ds.User(context.Background()).(*tests.MockedUserRepo).Error = errors.New("db down")
+			Expect(redeemSecret(req.Secret).Code).To(Equal(http.StatusInternalServerError))
+		})
+	})
+})
diff --git a/server/jellyfin/routing_test.go b/server/jellyfin/routing_test.go
index 62b52cfff..70da5b1eb 100644
--- a/server/jellyfin/routing_test.go
+++ b/server/jellyfin/routing_test.go
@@ -19,7 +19,7 @@ var _ = Describe("Case-insensitive routing", func() {
 	var api *Router
 
 	BeforeEach(func() {
-		api = New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		api = New(&tests.MockDataStore{}, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 	})
 
 	It("serves a fully lowercase path directly", func() {
diff --git a/server/jellyfin/socket_test.go b/server/jellyfin/socket_test.go
index 401c791fd..b4be0e244 100644
--- a/server/jellyfin/socket_test.go
+++ b/server/jellyfin/socket_test.go
@@ -94,7 +94,7 @@ var _ = Describe("handleSocket", func() {
 			Expect(err).ToNot(HaveOccurred())
 			token = t
 
-			api = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+			api = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		})
 
 		It("upgrades when authenticated via the api_key query parameter", func() {
diff --git a/server/jellyfin/system.go b/server/jellyfin/system.go
index 35ade5ff1..49e41470c 100644
--- a/server/jellyfin/system.go
+++ b/server/jellyfin/system.go
@@ -153,7 +153,3 @@ func parseIP(addr string) netip.Addr {
 	}
 	return ip.Unmap()
 }
-
-func (api *Router) quickConnectEnabled(w http.ResponseWriter, r *http.Request) {
-	api.ok(w, r, false)
-}
diff --git a/server/jellyfin/system_test.go b/server/jellyfin/system_test.go
index c9368f3b5..2350a7342 100644
--- a/server/jellyfin/system_test.go
+++ b/server/jellyfin/system_test.go
@@ -145,17 +145,6 @@ var _ = Describe("System", func() {
 		Expect(info.IsInNetwork).To(BeTrue())
 	})
 
-	It("reports quick connect as disabled", func() {
-		w := httptest.NewRecorder()
-		r := httptest.NewRequest("GET", "/QuickConnect/Enabled", nil)
-		api.quickConnectEnabled(w, r)
-
-		Expect(w.Code).To(Equal(http.StatusOK))
-		var enabled bool
-		Expect(json.Unmarshal(w.Body.Bytes(), &enabled)).To(Succeed())
-		Expect(enabled).To(BeFalse())
-	})
-
 	Context("serverID with a real DataStore", func() {
 		var ctx context.Context
 		var ds *tests.MockDataStore
diff --git a/server/nativeapi/config_test.go b/server/nativeapi/config_test.go
index d1007f457..7c4f00fdd 100644
--- a/server/nativeapi/config_test.go
+++ b/server/nativeapi/config_test.go
@@ -29,7 +29,7 @@ var _ = Describe("Config API", func() {
 		conf.Server.DevUIShowConfig = true // Enable config endpoint for tests
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
diff --git a/server/nativeapi/library_test.go b/server/nativeapi/library_test.go
index 13b33c238..cef2e06ad 100644
--- a/server/nativeapi/library_test.go
+++ b/server/nativeapi/library_test.go
@@ -31,7 +31,7 @@ var _ = Describe("Library API", func() {
 		conf.Server.EnableSharing = false
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
diff --git a/server/nativeapi/metadata_test.go b/server/nativeapi/metadata_test.go
index ebc9aeb28..ae6e301a8 100644
--- a/server/nativeapi/metadata_test.go
+++ b/server/nativeapi/metadata_test.go
@@ -66,7 +66,7 @@ var _ = Describe("Metadata API", func() {
 		}
 		auth.Init(ds)
 		provider = &fakeProvider{}
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, provider)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, provider, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		adminUser := model.User{ID: "admin-1", UserName: "admin", IsAdmin: true, NewPassword: "adminpass"}
diff --git a/server/nativeapi/missing_test.go b/server/nativeapi/missing_test.go
index 4da550c0d..9d7575a0c 100644
--- a/server/nativeapi/missing_test.go
+++ b/server/nativeapi/missing_test.go
@@ -40,7 +40,7 @@ var _ = Describe("Missing Files Endpoint", func() {
 		token, err = auth.CreateToken(&user)
 		Expect(err).ToNot(HaveOccurred())
 
-		router = server.JWTVerifier(New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil))
+		router = server.JWTVerifier(New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil))
 	})
 
 	DescribeTable("GET /missing/{id}",
diff --git a/server/nativeapi/native_api.go b/server/nativeapi/native_api.go
index 57a712a20..f931834c6 100644
--- a/server/nativeapi/native_api.go
+++ b/server/nativeapi/native_api.go
@@ -17,6 +17,7 @@ import (
 	"github.com/navidrome/navidrome/core/external"
 	"github.com/navidrome/navidrome/core/metrics"
 	playlistsvc "github.com/navidrome/navidrome/core/playlists"
+	"github.com/navidrome/navidrome/core/quickconnect"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -48,10 +49,11 @@ type Router struct {
 	pluginManager PluginManager
 	imgUpload     artwork.Uploader
 	provider      external.Provider
+	quickConnect  quickconnect.QuickConnect
 }
 
-func New(ds model.DataStore, share core.Share, playlists playlistsvc.Playlists, insights metrics.Insights, libraryService core.Library, userService core.User, maintenance core.Maintenance, pluginManager PluginManager, imgUpload artwork.Uploader, provider external.Provider) *Router {
-	r := &Router{ds: ds, share: share, playlists: playlists, insights: insights, libs: libraryService, users: userService, maintenance: maintenance, pluginManager: pluginManager, imgUpload: imgUpload, provider: provider}
+func New(ds model.DataStore, share core.Share, playlists playlistsvc.Playlists, insights metrics.Insights, libraryService core.Library, userService core.User, maintenance core.Maintenance, pluginManager PluginManager, imgUpload artwork.Uploader, provider external.Provider, quickConnect quickconnect.QuickConnect) *Router {
+	r := &Router{ds: ds, share: share, playlists: playlists, insights: insights, libs: libraryService, users: userService, maintenance: maintenance, pluginManager: pluginManager, imgUpload: imgUpload, provider: provider, quickConnect: quickConnect}
 	r.Handler = r.routes()
 	return r
 }
@@ -88,6 +90,7 @@ func (api *Router) routes() http.Handler {
 		api.addMissingFilesRoute(r)
 		api.addKeepAliveRoute(r)
 		api.addInsightsRoute(r)
+		api.addQuickConnectRoute(r)
 
 		r.With(adminOnlyMiddleware).Group(func(r chi.Router) {
 			api.addInspectRoute(r)
diff --git a/server/nativeapi/native_api_song_test.go b/server/nativeapi/native_api_song_test.go
index 203fcd4cf..954c872a7 100644
--- a/server/nativeapi/native_api_song_test.go
+++ b/server/nativeapi/native_api_song_test.go
@@ -95,7 +95,7 @@ var _ = Describe("Song Endpoints", func() {
 		mfRepo.SetData(testSongs)
 
 		// Create the native API router and wrap it with the JWTVerifier middleware
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 		w = httptest.NewRecorder()
 	})
diff --git a/server/nativeapi/playlists_test.go b/server/nativeapi/playlists_test.go
index 4a6f5d03d..2f6c578f9 100644
--- a/server/nativeapi/playlists_test.go
+++ b/server/nativeapi/playlists_test.go
@@ -99,7 +99,7 @@ var _ = Describe("Playlist Tracks Endpoint", func() {
 		err := userRepo.Put(&testUser)
 		Expect(err).ToNot(HaveOccurred())
 
-		nativeRouter := New(ds, nil, plsSvc, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, plsSvc, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 		w = httptest.NewRecorder()
 	})
diff --git a/server/nativeapi/plugin_test.go b/server/nativeapi/plugin_test.go
index 1683885e7..4e45ddb92 100644
--- a/server/nativeapi/plugin_test.go
+++ b/server/nativeapi/plugin_test.go
@@ -34,7 +34,7 @@ var _ = Describe("Plugin API", func() {
 		ds = &tests.MockDataStore{}
 		mockManager = &tests.MockPluginManager{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, mockManager, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, mockManager, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
diff --git a/server/nativeapi/quickconnect.go b/server/nativeapi/quickconnect.go
new file mode 100644
index 000000000..61d402cc5
--- /dev/null
+++ b/server/nativeapi/quickconnect.go
@@ -0,0 +1,76 @@
+package nativeapi
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/core/quickconnect"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/server"
+)
+
+type quickConnectDevice struct {
+	AppName    string `json:"appName"`
+	AppVersion string `json:"appVersion"`
+	DeviceName string `json:"deviceName"`
+}
+
+func (api *Router) addQuickConnectRoute(r chi.Router) {
+	if !quickconnect.Enabled() {
+		return
+	}
+	r.Route("/quickconnect", func(r chi.Router) {
+		// Throttled like login so a signed-in user cannot enumerate other people's pending codes.
+		if conf.Server.AuthRequestLimit > 0 {
+			r.Use(server.ClientIPRateLimiter(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength))
+		}
+		r.Get("/", lookupQuickConnect(api.quickConnect))
+		r.Post("/authorize", authorizeQuickConnect(api.quickConnect))
+	})
+}
+
+func lookupQuickConnect(qc quickconnect.QuickConnect) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		req, err := qc.Lookup(r.URL.Query().Get("code"))
+		writeQuickConnectResult(w, r, req, err)
+	}
+}
+
+func authorizeQuickConnect(qc quickconnect.QuickConnect) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		var body struct {
+			Code string `json:"code"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			http.Error(w, "Bad Request", http.StatusBadRequest)
+			return
+		}
+		ctx := r.Context()
+		user, _ := request.UserFrom(ctx)
+		req, err := qc.Authorize(body.Code, user.ID)
+		if err == nil {
+			log.Info(ctx, "Quick Connect sign-in approved", "username", user.UserName, "client", req.Device.App, "device", req.Device.Name)
+		}
+		writeQuickConnectResult(w, r, req, err)
+	}
+}
+
+func writeQuickConnectResult(w http.ResponseWriter, r *http.Request, req quickconnect.Request, err error) {
+	switch {
+	case errors.Is(err, model.ErrNotFound):
+		http.Error(w, "Unknown code", http.StatusNotFound)
+	case errors.Is(err, quickconnect.ErrAlreadyAuthorized):
+		http.Error(w, "Code already used", http.StatusConflict)
+	case err != nil:
+		log.Error(r.Context(), "Quick Connect failed", err)
+		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+	default:
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(quickConnectDevice{AppName: req.Device.App, AppVersion: req.Device.AppVersion, DeviceName: req.Device.Name})
+	}
+}
diff --git a/server/nativeapi/quickconnect_test.go b/server/nativeapi/quickconnect_test.go
new file mode 100644
index 000000000..f2f06f0f3
--- /dev/null
+++ b/server/nativeapi/quickconnect_test.go
@@ -0,0 +1,148 @@
+package nativeapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/core/quickconnect"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Quick Connect endpoints", func() {
+	var (
+		qc      quickconnect.QuickConnect
+		pending quickconnect.Request
+		user    = model.User{ID: "u1", UserName: "alice"}
+	)
+
+	BeforeEach(func() {
+		qc = quickconnect.New()
+		var err error
+		pending, err = qc.Initiate(quickconnect.Device{ID: "dev-1", Name: "Pixel 7", App: "Finamp", AppVersion: "1.0.0"})
+		Expect(err).ToNot(HaveOccurred())
+	})
+
+	asUser := func(r *http.Request) *http.Request {
+		return r.WithContext(request.WithUser(r.Context(), user))
+	}
+	decode := func(w *httptest.ResponseRecorder) quickConnectDevice {
+		var res quickConnectDevice
+		Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
+		return res
+	}
+	finamp := quickConnectDevice{AppName: "Finamp", AppVersion: "1.0.0", DeviceName: "Pixel 7"}
+
+	Describe("GET /quickconnect", func() {
+		lookup := func(code string) *httptest.ResponseRecorder {
+			w := httptest.NewRecorder()
+			lookupQuickConnect(qc)(w, asUser(httptest.NewRequest("GET", "/quickconnect?code="+code, nil)))
+			return w
+		}
+
+		It("describes the device waiting for the code", func() {
+			w := lookup(pending.Code)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(decode(w)).To(Equal(finamp))
+		})
+
+		It("does not approve the code", func() {
+			lookup(pending.Code)
+			got, _ := qc.Status(pending.Secret)
+			Expect(got.Authorized()).To(BeFalse())
+		})
+
+		It("returns 404 for an unknown code", func() {
+			Expect(lookup("000000").Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns 409 for a code that is already approved", func() {
+			_, _ = qc.Authorize(pending.Code, "someone")
+			Expect(lookup(pending.Code).Code).To(Equal(http.StatusConflict))
+		})
+	})
+
+	Describe("POST /quickconnect/authorize", func() {
+		authorize := func(body string) *httptest.ResponseRecorder {
+			w := httptest.NewRecorder()
+			authorizeQuickConnect(qc)(w, asUser(httptest.NewRequest("POST", "/quickconnect/authorize", strings.NewReader(body))))
+			return w
+		}
+
+		It("approves the code for the signed-in user", func() {
+			w := authorize(`{"code":"` + pending.Code + `"}`)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(decode(w)).To(Equal(finamp))
+			got, _ := qc.Status(pending.Secret)
+			Expect(got.UserID).To(Equal(user.ID))
+		})
+
+		It("returns 404 for an unknown code", func() {
+			Expect(authorize(`{"code":"000000"}`).Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns 409 for a code that is already approved", func() {
+			_, _ = qc.Authorize(pending.Code, "someone")
+			Expect(authorize(`{"code":"` + pending.Code + `"}`).Code).To(Equal(http.StatusConflict))
+		})
+
+		It("returns 400 for a bad body", func() {
+			Expect(authorize(`nope`).Code).To(Equal(http.StatusBadRequest))
+		})
+	})
+
+	Describe("route registration", func() {
+		serve := func() int {
+			r := chi.NewRouter()
+			(&Router{quickConnect: qc}).addQuickConnectRoute(r)
+			w := httptest.NewRecorder()
+			r.ServeHTTP(w, asUser(httptest.NewRequest("GET", "/quickconnect?code="+pending.Code, nil)))
+			return w.Code
+		}
+
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.Jellyfin.Enabled = true
+			conf.Server.Jellyfin.QuickConnect = true
+		})
+
+		It("mounts the routes when Jellyfin Quick Connect is on", func() {
+			Expect(serve()).To(Equal(http.StatusOK))
+		})
+
+		It("rate-limits code attempts when a login limit is configured", func() {
+			conf.Server.AuthRequestLimit = 2
+			conf.Server.AuthWindowLength = time.Minute
+			r := chi.NewRouter()
+			(&Router{quickConnect: qc}).addQuickConnectRoute(r)
+			attempt := func() int {
+				w := httptest.NewRecorder()
+				req := httptest.NewRequest("GET", "/quickconnect?code=000000", nil)
+				req.RemoteAddr = "10.0.0.1:1234"
+				r.ServeHTTP(w, asUser(req))
+				return w.Code
+			}
+			Expect(attempt()).To(Equal(http.StatusNotFound))
+			Expect(attempt()).To(Equal(http.StatusNotFound))
+			Expect(attempt()).To(Equal(http.StatusTooManyRequests))
+		})
+
+		It("skips the routes when the Jellyfin API is off", func() {
+			conf.Server.Jellyfin.Enabled = false
+			Expect(serve()).To(Equal(http.StatusNotFound))
+		})
+
+		It("skips the routes when Quick Connect is off", func() {
+			conf.Server.Jellyfin.QuickConnect = false
+			Expect(serve()).To(Equal(http.StatusNotFound))
+		})
+	})
+})
diff --git a/server/nativeapi/user_password_token_refresh_test.go b/server/nativeapi/user_password_token_refresh_test.go
index 2a363980f..27454fc7d 100644
--- a/server/nativeapi/user_password_token_refresh_test.go
+++ b/server/nativeapi/user_password_token_refresh_test.go
@@ -45,7 +45,7 @@ var _ = Describe("PUT /user/{id}: token refresh on self password change", func()
 		auth.Init(ds)
 
 		userService := core.NewUser(ds, noopPluginUnloader{})
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), userService, nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), userService, nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 	})
 
diff --git a/server/serve_index.go b/server/serve_index.go
index a538daf1a..651c8c907 100644
--- a/server/serve_index.go
+++ b/server/serve_index.go
@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/mime"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/core/quickconnect"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
@@ -75,6 +76,7 @@ func serveIndex(ds model.DataStore, fs fs.FS, shareInfo *model.Share) http.Handl
 			"listenBrainzEnabled":       conf.Server.ListenBrainz.Enabled,
 			"enableExternalServices":    conf.Server.EnableExternalServices,
 			"enableReplayGain":          conf.Server.EnableReplayGain,
+			"enableQuickConnect":        quickconnect.Enabled(),
 			"defaultDownsamplingFormat": conf.Server.DefaultDownsamplingFormat,
 			"separator":                 string(os.PathSeparator),
 			"enableInspect":             conf.Server.Inspect.Enabled,
diff --git a/server/serve_index_test.go b/server/serve_index_test.go
index 78f3873b8..23215a5ef 100644
--- a/server/serve_index_test.go
+++ b/server/serve_index_test.go
@@ -97,6 +97,8 @@ var _ = Describe("serveIndex", func() {
 		Entry("devUIShowConfig", func() { conf.Server.DevUIShowConfig = true }, "devUIShowConfig", true),
 		Entry("listenBrainzEnabled", func() { conf.Server.ListenBrainz.Enabled = true }, "listenBrainzEnabled", true),
 		Entry("enableReplayGain", func() { conf.Server.EnableReplayGain = true }, "enableReplayGain", true),
+		Entry("enableQuickConnect", func() { conf.Server.Jellyfin.Enabled = true; conf.Server.Jellyfin.QuickConnect = true }, "enableQuickConnect", true),
+		Entry("enableQuickConnect without the Jellyfin API", func() { conf.Server.Jellyfin.Enabled = false; conf.Server.Jellyfin.QuickConnect = true }, "enableQuickConnect", false),
 		Entry("enableExternalServices", func() { conf.Server.EnableExternalServices = true }, "enableExternalServices", true),
 		Entry("devActivityPanel", func() { conf.Server.DevActivityPanel = true }, "devActivityPanel", true),
 		Entry("shareURL", func() { conf.Server.ShareURL = "https://share.example.com" }, "shareURL", "https://share.example.com"),
diff --git a/ui/src/config.js b/ui/src/config.js
index 39f0cd467..e406e47cf 100644
--- a/ui/src/config.js
+++ b/ui/src/config.js
@@ -38,6 +38,7 @@ const defaultConfig = {
   devUIShowConfig: true,
   devNewEventStream: false,
   enableReplayGain: true,
+  enableQuickConnect: false,
   defaultDownsamplingFormat: 'opus',
   publicBaseUrl: '/share',
   separator: '/',
diff --git a/ui/src/dataProvider/wrapperDataProvider.js b/ui/src/dataProvider/wrapperDataProvider.js
index e79beb787..f0e44ce1d 100644
--- a/ui/src/dataProvider/wrapperDataProvider.js
+++ b/ui/src/dataProvider/wrapperDataProvider.js
@@ -218,6 +218,15 @@ const wrapperDataProvider = {
       ({ json }) => ({ data: json }),
     )
   },
+  lookupQuickConnect: (code) =>
+    httpClient(
+      `${REST_URL}/quickconnect?code=${encodeURIComponent(code)}`,
+    ).then(({ json }) => ({ data: json })),
+  authorizeQuickConnect: (code) =>
+    httpClient(`${REST_URL}/quickconnect/authorize`, {
+      method: 'POST',
+      body: JSON.stringify({ code }),
+    }).then(({ json }) => ({ data: json })),
   inspect: (songId) => {
     return httpClient(`${REST_URL}/inspect?id=${songId}`).then(({ json }) => ({
       data: json,
diff --git a/ui/src/dialogs/QuickConnectDialog.jsx b/ui/src/dialogs/QuickConnectDialog.jsx
new file mode 100644
index 000000000..cde7e9eaf
--- /dev/null
+++ b/ui/src/dialogs/QuickConnectDialog.jsx
@@ -0,0 +1,128 @@
+import { useState } from 'react'
+import PropTypes from 'prop-types'
+import { useDataProvider, useNotify, useTranslate } from 'react-admin'
+import {
+  Button,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogContentText,
+  DialogTitle,
+  TextField,
+} from '@material-ui/core'
+
+export const QuickConnectDialog = ({ open, onClose }) => {
+  const translate = useTranslate()
+  const notify = useNotify()
+  const dataProvider = useDataProvider()
+  const [code, setCode] = useState('')
+  const [pending, setPending] = useState(null)
+  const [loading, setLoading] = useState(false)
+
+  const handleClose = () => {
+    setCode('')
+    setPending(null)
+    onClose()
+  }
+
+  const handleError = (error) => {
+    setPending(null)
+    const invalid = error?.status === 404 || error?.status === 409
+    notify(
+      invalid ? 'message.quickConnectInvalidCode' : 'message.quickConnectError',
+      'warning',
+    )
+  }
+
+  const run = (request, onSuccess) => {
+    setLoading(true)
+    request
+      .then(({ data }) => onSuccess(data))
+      .catch(handleError)
+      .finally(() => setLoading(false))
+  }
+
+  const lookup = (event) => {
+    event.preventDefault()
+    run(dataProvider.lookupQuickConnect(code), setPending)
+  }
+
+  const approve = () =>
+    run(dataProvider.authorizeQuickConnect(code), (data) => {
+      notify('message.quickConnectApproved', 'success', {
+        app: data.appName,
+        device: data.deviceName,
+      })
+      handleClose()
+    })
+
+  return (
+    <Dialog
+      open={open}
+      onClose={handleClose}
+      aria-labelledby="quick-connect-dialog"
+      fullWidth
+      maxWidth="xs"
+    >
+      <DialogTitle id="quick-connect-dialog">
+        {translate('menu.quickConnect.name')}
+      </DialogTitle>
+      {pending ? (
+        <>
+          <DialogContent>
+            <DialogContentText>
+              {translate('menu.quickConnect.confirm', {
+                app: pending.appName,
+                version: pending.appVersion,
+                device: pending.deviceName,
+              })}
+            </DialogContentText>
+          </DialogContent>
+          <DialogActions>
+            <Button onClick={() => setPending(null)} color="primary">
+              {translate('ra.action.back')}
+            </Button>
+            <Button onClick={approve} color="primary" disabled={loading}>
+              {translate('menu.quickConnect.approve')}
+            </Button>
+          </DialogActions>
+        </>
+      ) : (
+        <form onSubmit={lookup}>
+          <DialogContent>
+            <DialogContentText>
+              {translate('menu.quickConnect.help')}
+            </DialogContentText>
+            <TextField
+              id="quickConnectCode"
+              variant="outlined"
+              fullWidth
+              autoFocus
+              label={translate('menu.quickConnect.code')}
+              value={code}
+              onChange={(event) => setCode(event.target.value)}
+              inputProps={{ inputMode: 'numeric', autoComplete: 'off' }}
+            />
+          </DialogContent>
+          <DialogActions>
+            <Button onClick={handleClose} color="primary">
+              {translate('ra.action.cancel')}
+            </Button>
+            <Button
+              type="submit"
+              color="primary"
+              disabled={!code.trim() || loading}
+            >
+              {translate('menu.quickConnect.continue')}
+            </Button>
+          </DialogActions>
+        </form>
+      )}
+    </Dialog>
+  )
+}
+
+QuickConnectDialog.propTypes = {
+  open: PropTypes.bool.isRequired,
+  onClose: PropTypes.func.isRequired,
+}
diff --git a/ui/src/dialogs/QuickConnectDialog.test.jsx b/ui/src/dialogs/QuickConnectDialog.test.jsx
new file mode 100644
index 000000000..5dda1cbdf
--- /dev/null
+++ b/ui/src/dialogs/QuickConnectDialog.test.jsx
@@ -0,0 +1,103 @@
+import * as React from 'react'
+import { TestContext } from 'ra-test'
+import { DataProviderContext } from 'react-admin'
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react'
+import { describe, afterEach, it, expect, vi } from 'vitest'
+import { QuickConnectDialog } from './QuickConnectDialog'
+
+const finamp = { appName: 'Finamp', appVersion: '1.0.0', deviceName: 'Pixel 7' }
+
+const renderDialog = (dataProvider, onClose = vi.fn()) => {
+  render(
+    <DataProviderContext.Provider value={dataProvider}>
+      <TestContext initialState={{ admin: { ui: { optimistic: false } } }}>
+        <QuickConnectDialog open={true} onClose={onClose} />
+      </TestContext>
+    </DataProviderContext.Provider>,
+  )
+  return onClose
+}
+
+const enterCode = (code) => {
+  fireEvent.change(screen.getByRole('textbox'), { target: { value: code } })
+  fireEvent.click(screen.getByText('menu.quickConnect.continue'))
+}
+
+describe('QuickConnectDialog', () => {
+  afterEach(cleanup)
+
+  it('shows the device before approving the code', async () => {
+    const dataProvider = {
+      lookupQuickConnect: vi.fn().mockResolvedValue({ data: finamp }),
+      authorizeQuickConnect: vi.fn().mockResolvedValue({ data: finamp }),
+    }
+    const onClose = renderDialog(dataProvider)
+
+    enterCode('123 456')
+    await screen.findByText('menu.quickConnect.approve')
+    expect(dataProvider.lookupQuickConnect.mock.calls[0][0]).toBe('123 456')
+    expect(dataProvider.authorizeQuickConnect).not.toHaveBeenCalled()
+
+    fireEvent.click(screen.getByText('menu.quickConnect.approve'))
+    await waitFor(() => expect(onClose).toHaveBeenCalled())
+    expect(dataProvider.authorizeQuickConnect.mock.calls[0][0]).toBe('123 456')
+  })
+
+  it('goes back to the code input', async () => {
+    const dataProvider = {
+      lookupQuickConnect: vi.fn().mockResolvedValue({ data: finamp }),
+      authorizeQuickConnect: vi.fn(),
+    }
+    renderDialog(dataProvider)
+
+    enterCode('123456')
+    await screen.findByText('menu.quickConnect.approve')
+    fireEvent.click(screen.getByText('ra.action.back'))
+
+    expect(screen.getByRole('textbox')).toHaveValue('123456')
+    expect(dataProvider.authorizeQuickConnect).not.toHaveBeenCalled()
+  })
+
+  it('stays on the code input when the code is unknown', async () => {
+    const dataProvider = {
+      lookupQuickConnect: vi.fn().mockRejectedValue({ status: 404 }),
+      authorizeQuickConnect: vi.fn(),
+    }
+    const onClose = renderDialog(dataProvider)
+
+    enterCode('000000')
+    await waitFor(() =>
+      expect(dataProvider.lookupQuickConnect).toHaveBeenCalled(),
+    )
+    expect(screen.getByRole('textbox')).toBeInTheDocument()
+    expect(screen.queryByText('menu.quickConnect.approve')).toBeNull()
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('returns to the code input when approval fails', async () => {
+    const dataProvider = {
+      lookupQuickConnect: vi.fn().mockResolvedValue({ data: finamp }),
+      authorizeQuickConnect: vi.fn().mockRejectedValue({ status: 409 }),
+    }
+    const onClose = renderDialog(dataProvider)
+
+    enterCode('123456')
+    fireEvent.click(await screen.findByText('menu.quickConnect.approve'))
+
+    await screen.findByRole('textbox')
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('disables Continue until a code is typed', () => {
+    renderDialog({ lookupQuickConnect: vi.fn() })
+    expect(
+      screen.getByText('menu.quickConnect.continue').closest('button'),
+    ).toBeDisabled()
+  })
+})
diff --git a/ui/src/dialogs/index.js b/ui/src/dialogs/index.js
index 86586aef0..3234e4685 100644
--- a/ui/src/dialogs/index.js
+++ b/ui/src/dialogs/index.js
@@ -2,4 +2,5 @@ export * from './AboutDialog'
 export * from './SelectPlaylistInput'
 export * from './ListenBrainzTokenDialog'
 export * from './SaveQueueDialog'
+export * from './QuickConnectDialog'
 export * from './Dialogs'
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index fd200fa60..f5af05b7b 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -591,6 +591,9 @@
     "remove_all_missing_content": "Are you sure you want to remove all missing files from the database? This will permanently remove any references to them, including their play counts and ratings.",
     "notifications_blocked": "You have blocked Notifications for this site in your browser's settings",
     "notifications_not_available": "This browser does not support desktop notifications or you are not accessing Navidrome over https",
+    "quickConnectApproved": "%{app} on %{device} is now signed in",
+    "quickConnectInvalidCode": "Invalid or expired code",
+    "quickConnectError": "Could not approve the code",
     "lastfmLinkSuccess": "Last.fm successfully linked and scrobbling enabled",
     "lastfmLinkFailure": "Last.fm could not be linked",
     "lastfmUnlinkSuccess": "Last.fm unlinked and scrobbling disabled",
@@ -622,6 +625,14 @@
       "none": "None"
     },
     "settings": "Settings",
+    "quickConnect": {
+      "name": "Quick Connect",
+      "code": "Code",
+      "help": "Enter the code shown by a Jellyfin app to sign it in to your account",
+      "confirm": "Sign in %{app} %{version} on %{device} to your account?",
+      "continue": "Continue",
+      "approve": "Approve"
+    },
     "version": "Version",
     "theme": "Theme",
     "personal": {
diff --git a/ui/src/layout/AppBar.jsx b/ui/src/layout/AppBar.jsx
index 561701dce..7de111e67 100644
--- a/ui/src/layout/AppBar.jsx
+++ b/ui/src/layout/AppBar.jsx
@@ -6,12 +6,17 @@ import {
   usePermissions,
   getResources,
 } from 'react-admin'
-import { MdInfo, MdPerson, MdSupervisorAccount } from 'react-icons/md'
+import {
+  MdInfo,
+  MdPerson,
+  MdPhonelink,
+  MdSupervisorAccount,
+} from 'react-icons/md'
 import { useSelector } from 'react-redux'
 import { makeStyles, MenuItem, ListItemIcon, Divider } from '@material-ui/core'
 import ViewListIcon from '@material-ui/icons/ViewList'
 import { Dialogs } from '../dialogs/Dialogs'
-import { AboutDialog } from '../dialogs'
+import { AboutDialog, QuickConnectDialog } from '../dialogs'
 import PersonalMenu from './PersonalMenu'
 import ActivityPanel from './ActivityPanel'
 import NowPlayingPanel from './NowPlayingPanel'
@@ -33,33 +38,34 @@ const useStyles = makeStyles(
   },
 )
 
-const AboutMenuItem = forwardRef(({ onClick, ...rest }, ref) => {
-  const classes = useStyles(rest)
-  const translate = useTranslate()
-  const [open, setOpen] = React.useState(false)
+const DialogMenuItem = forwardRef(
+  ({ onClick, label, icon, dialog, ...rest }, ref) => {
+    const classes = useStyles(rest)
+    const [open, setOpen] = React.useState(false)
 
-  const handleOpen = () => {
-    setOpen(true)
-  }
-  const handleClose = () => {
-    onClick && onClick()
-    setOpen(false)
-  }
-  const label = translate('menu.about')
-  return (
-    <>
-      <MenuItem ref={ref} onClick={handleOpen} className={classes.root}>
-        <ListItemIcon className={classes.icon}>
-          <MdInfo title={label} size={24} />
-        </ListItemIcon>
-        {label}
-      </MenuItem>
-      <AboutDialog onClose={handleClose} open={open} />
-    </>
-  )
-})
+    const handleClose = () => {
+      onClick && onClick()
+      setOpen(false)
+    }
+    return (
+      <>
+        <MenuItem
+          ref={ref}
+          onClick={() => setOpen(true)}
+          className={classes.root}
+        >
+          <ListItemIcon className={classes.icon}>
+            {createElement(icon, { title: label, size: 24 })}
+          </ListItemIcon>
+          {label}
+        </MenuItem>
+        {createElement(dialog, { onClose: handleClose, open })}
+      </>
+    )
+  },
+)
 
-AboutMenuItem.displayName = 'AboutMenuItem'
+DialogMenuItem.displayName = 'DialogMenuItem'
 
 const settingsResources = (resource) =>
   resource.name !== 'user' &&
@@ -126,13 +132,24 @@ const CustomUserMenu = ({ onClick, ...rest }) => {
       {config.devActivityPanel && permissions === 'admin' && <ActivityPanel />}
       <UserMenu {...rest}>
         <PersonalMenu sidebarIsOpen={true} onClick={onClick} />
+        {config.enableQuickConnect && (
+          <DialogMenuItem
+            label={translate('menu.quickConnect.name')}
+            icon={MdPhonelink}
+            dialog={QuickConnectDialog}
+          />
+        )}
         <Divider />
         {renderUserMenuItemLink()}
         {resources
           .filter(settingsResources)
           .map((r) => renderSettingsMenuItemLink(r))}
         <Divider />
-        <AboutMenuItem />
+        <DialogMenuItem
+          label={translate('menu.about')}
+          icon={MdInfo}
+          dialog={AboutDialog}
+        />
       </UserMenu>
       <Dialogs />
     </>
diff --git a/ui/src/layout/AppBar.test.jsx b/ui/src/layout/AppBar.test.jsx
index f39dd75cb..7c8cd3dcd 100644
--- a/ui/src/layout/AppBar.test.jsx
+++ b/ui/src/layout/AppBar.test.jsx
@@ -33,12 +33,14 @@ vi.mock('../dialogs/Dialogs', () => ({
 }))
 vi.mock('../dialogs', () => ({
   AboutDialog: () => <div />,
+  QuickConnectDialog: () => <div />,
 }))
 
 describe('<AppBar />', () => {
   beforeEach(() => {
     config.devActivityPanel = true
     config.enableNowPlaying = true
+    config.enableQuickConnect = false
     store = createStore(combineReducers({ activity: activityReducer }), {
       activity: { nowPlayingCount: 0 },
     })
@@ -62,4 +64,24 @@ describe('<AppBar />', () => {
     )
     expect(screen.queryByTestId('now-playing-panel')).toBeNull()
   })
+
+  it('shows the Quick Connect menu item when enabled', () => {
+    config.enableQuickConnect = true
+    render(
+      <Provider store={store}>
+        <AppBar />
+      </Provider>,
+    )
+    expect(screen.queryAllByText('menu.quickConnect.name')).not.toHaveLength(0)
+  })
+
+  it('hides the Quick Connect menu item when disabled', () => {
+    render(
+      <Provider store={store}>
+        <AppBar />
+      </Provider>,
+    )
+    expect(screen.queryAllByText('menu.quickConnect.name')).toHaveLength(0)
+    expect(screen.queryAllByText('menu.about')).not.toHaveLength(0)
+  })
 })

From fb45ad7b9c705c52b7a8df6051252e5a9010e16c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 19 Sep 2026 17:08:49 -0400
Subject: [PATCH 153/200] fix(auth): ExtAuth logout redirect on unauthenticated
 loads, and warning spam from untrusted sources (#6176)

* fix(ui): only redirect to ExtAuth logout URL for proxy-authenticated sessions

react-admin calls authProvider.logout() when the boot-time checkAuth fails
and after a 401, not only when the user clicks Logout. With
ExtAuth.LogoutURL set, every unauthenticated page load (e.g. direct LAN
access that bypasses the auth proxy) was sent to the IdP sign-out page and
the login form was never shown.

Redirect only when the page was authenticated by the reverse proxy
(config.auth is present). Other sessions fall back to the login form.

Fixes #6175

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

* fix(server): only warn about untrusted ExtAuth sources when the header is sent

UsernameFromExtAuthHeader checked the source IP before looking for the user
header, so every request from an IP outside ExtAuth.TrustedSources logged a
warning, even when it carried no header at all. With direct LAN access
alongside a forward-auth proxy, a single polling client produced a constant
stream of warnings (twice per Subsonic request, since the middleware chain
resolves the username in both checkRequiredParameters and authenticate).

Look for the header first and warn only when an untrusted source actually
sends it, which is the case worth seeing: a misconfigured proxy or a spoof
attempt.

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

---------

Signed-off-by: Deluan <deluan@navidrome.org>
---
 server/auth.go              |  8 +++---
 server/auth_test.go         | 53 +++++++++++++++++++++++++++++++++++++
 ui/src/authProvider.js      |  3 ++-
 ui/src/authProvider.test.js | 47 ++++++++++++++++++++++++++++++++
 ui/src/setupTests.js        |  3 +++
 5 files changed, 109 insertions(+), 5 deletions(-)
 create mode 100644 ui/src/authProvider.test.js

diff --git a/server/auth.go b/server/auth.go
index fdeb8c455..d9ade7b29 100644
--- a/server/auth.go
+++ b/server/auth.go
@@ -218,14 +218,14 @@ func UsernameFromExtAuthHeader(r *http.Request) string {
 		log.Error("ExtAuth enabled but no proxy IP found in request context. Please report this error.")
 		return ""
 	}
-	if !validateIPAgainstList(reverseProxyIp, conf.Server.ExtAuth.TrustedSources) {
-		log.Warn(r.Context(), "IP is not whitelisted for external authentication", "proxy-ip", reverseProxyIp, "client-ip", r.RemoteAddr)
-		return ""
-	}
 	username := r.Header.Get(conf.Server.ExtAuth.UserHeader)
 	if username == "" {
 		return ""
 	}
+	if !validateIPAgainstList(reverseProxyIp, conf.Server.ExtAuth.TrustedSources) {
+		log.Warn(r.Context(), "IP is not whitelisted for external authentication", "proxy-ip", reverseProxyIp, "client-ip", r.RemoteAddr)
+		return ""
+	}
 	log.Trace(r, "Found username in ExtAuth.UserHeader", "username", username)
 	return username
 }
diff --git a/server/auth_test.go b/server/auth_test.go
index af9ffcaeb..a4d592c51 100644
--- a/server/auth_test.go
+++ b/server/auth_test.go
@@ -16,12 +16,15 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
+	"github.com/sirupsen/logrus"
+	"github.com/sirupsen/logrus/hooks/test"
 )
 
 var _ = Describe("Auth", func() {
@@ -234,6 +237,56 @@ var _ = Describe("Auth", func() {
 		})
 	})
 
+	Describe("UsernameFromExtAuthHeader", func() {
+		var hook *test.Hook
+		var r *http.Request
+
+		BeforeEach(func() {
+			conf.Server.ExtAuth.TrustedSources = "192.168.0.0/16"
+			prevLevel := log.CurrentLevel()
+			l, h := test.NewNullLogger()
+			hook = h
+			prevLogger := log.SetDefaultLogger(l)
+			log.SetLevel(log.LevelWarn)
+			DeferCleanup(func() {
+				log.SetDefaultLogger(prevLogger)
+				log.SetLevel(prevLevel)
+			})
+			r = httptest.NewRequest("GET", "/", nil)
+		})
+
+		warnings := func() []*logrus.Entry {
+			var ws []*logrus.Entry
+			for _, e := range hook.AllEntries() {
+				if e.Level == logrus.WarnLevel {
+					ws = append(ws, e)
+				}
+			}
+			return ws
+		}
+
+		It("returns the username from a trusted source", func() {
+			r.Header.Set("Remote-User", "janedoe")
+			r = r.WithContext(request.WithReverseProxyIp(r.Context(), "192.168.0.42"))
+			Expect(UsernameFromExtAuthHeader(r)).To(Equal("janedoe"))
+			Expect(warnings()).To(BeEmpty())
+		})
+
+		It("does not warn when an untrusted source sends no user header", func() {
+			r = r.WithContext(request.WithReverseProxyIp(r.Context(), "8.8.8.8"))
+			Expect(UsernameFromExtAuthHeader(r)).To(BeEmpty())
+			Expect(warnings()).To(BeEmpty())
+		})
+
+		It("warns when an untrusted source sends the user header", func() {
+			r.Header.Set("Remote-User", "janedoe")
+			r = r.WithContext(request.WithReverseProxyIp(r.Context(), "8.8.8.8"))
+			Expect(UsernameFromExtAuthHeader(r)).To(BeEmpty())
+			Expect(warnings()).To(HaveLen(1))
+			Expect(warnings()[0].Message).To(Equal("IP is not whitelisted for external authentication"))
+		})
+	})
+
 	Describe("tokenFromHeader", func() {
 		It("returns the token when the Authorization header is set correctly", func() {
 			req := httptest.NewRequest("GET", "/", nil)
diff --git a/ui/src/authProvider.js b/ui/src/authProvider.js
index 18badbc9c..f93114ded 100644
--- a/ui/src/authProvider.js
+++ b/ui/src/authProvider.js
@@ -64,7 +64,8 @@ const authProvider = {
 
   logout: () => {
     removeItems()
-    if (config.extAuthLogoutURL) {
+    // Only proxy-authenticated sessions go to the IdP; others (e.g. direct LAN access) get the login form
+    if (config.extAuthLogoutURL && config.auth) {
       window.location.href = config.extAuthLogoutURL
       return Promise.resolve(false)
     }
diff --git a/ui/src/authProvider.test.js b/ui/src/authProvider.test.js
new file mode 100644
index 000000000..b16a39815
--- /dev/null
+++ b/ui/src/authProvider.test.js
@@ -0,0 +1,47 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import config from './config'
+import authProvider from './authProvider'
+
+vi.mock('./config', () => ({ default: {} }))
+
+describe('authProvider.logout', () => {
+  const logoutURL = 'https://auth.example.com/signout'
+
+  beforeEach(() => {
+    vi.stubGlobal('location', { href: '' })
+    localStorage.setItem('is-authenticated', 'true')
+    localStorage.setItem('token', 'abc')
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    localStorage.clear()
+    delete config.extAuthLogoutURL
+    delete config.auth
+  })
+
+  it('clears the stored session', async () => {
+    await authProvider.logout()
+    expect(localStorage.getItem('is-authenticated')).toBeNull()
+    expect(localStorage.getItem('token')).toBeNull()
+  })
+
+  it('does not redirect when no logout URL is configured', async () => {
+    config.auth = { id: '1' }
+    await expect(authProvider.logout()).resolves.toBeUndefined()
+    expect(window.location.href).toBe('')
+  })
+
+  it('redirects to the logout URL when the page was authenticated by the proxy', async () => {
+    config.extAuthLogoutURL = logoutURL
+    config.auth = { id: '1' }
+    await expect(authProvider.logout()).resolves.toBe(false)
+    expect(window.location.href).toBe(logoutURL)
+  })
+
+  it('does not redirect when the page was not authenticated by the proxy', async () => {
+    config.extAuthLogoutURL = logoutURL
+    await expect(authProvider.logout()).resolves.toBeUndefined()
+    expect(window.location.href).toBe('')
+  })
+})
diff --git a/ui/src/setupTests.js b/ui/src/setupTests.js
index ddb999f3c..7cb46e09c 100644
--- a/ui/src/setupTests.js
+++ b/ui/src/setupTests.js
@@ -14,6 +14,9 @@ const localStorageMock = (function () {
     setItem: function (key, value) {
       store[key] = value.toString()
     },
+    removeItem: function (key) {
+      delete store[key]
+    },
     clear: function () {
       store = {}
     },

From 672c0af580b182ffb219dc5f64c62b456163fd38 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sat, 19 Sep 2026 17:10:49 -0400
Subject: [PATCH 154/200] docs(README): update Docker networking instructions
 for UDP discovery

---
 server/jellyfin/README.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index c0c5e6ca1..e38997569 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -67,9 +67,10 @@ Discovery answers on all IPv4 interfaces, but the advertised address follows `Ba
 `Port`. If `Address` is a loopback or a single interface IP and `BaseURL` has no host, clients on other
 networks get an address they cannot reach. Set `BaseURL` to the address clients should use.
 
-Docker: publish the port (`-p 7359:7359/udp`). In bridge mode the server only sees its container
-IP, so also set `ND_BASEURL` to the LAN address (for example `http://192.168.1.10:4533`), or use
-host networking. Keep UDP 7359 on the LAN: never forward it from the internet.
+Docker: use host networking (`network_mode: host` / `--network host`). On Linux, bridge mode does not
+deliver broadcasts to the container, even with `-p 7359:7359/udp`, so clients never find the server.
+With host networking the server sees the host's IP, so `BaseURL` is not needed for discovery. If host
+networking is not an option, leave discovery off. Keep UDP 7359 on the LAN: never forward it from the internet.
 
 ## Authentication
 

From 49f626c00a0ef3449530cd37d3121734982d86f9 Mon Sep 17 00:00:00 2001
From: David Vedvick <dvedvick@gmail.com>
Date: Sat, 19 Sep 2026 20:05:58 -0500
Subject: [PATCH 155/200] feat(smartplaylists): add support for referencing
 playlists using paths (#5187)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat: Add support for referencing playlists using paths

Signed-off-by: David <dvedvick@gmail.com>

* feat: Support relative playlist paths in smartlists

Signed-off-by: David <dvedvick@gmail.com>

* fix(smartplaylists): protect against nil panic

Signed-off-by: David <dvedvick@gmail.com>

* fix(smartplaylists): refreshing child playlists

Signed-off-by: David <dvedvick@gmail.com>

* chore(smartplaylists): log field parsing error

Signed-off-by: David <dvedvick@gmail.com>

* fix(smartplaylists): handle empty playlist paths

Signed-off-by: David <dvedvick@gmail.com>

* refactor(smartplaylists): make NormalizeChildPaths non-mutating

Signed-off-by: David <dvedvick@gmail.com>

* fix(smartplaylists): stop warning on every inPlaylist rule without the looked-up field

Rules that reference a playlist by id have no path field, and the reverse, so
the warning fired on every refresh. The log call also had a bad argument count.

* fix(smartplaylists): ignore empty inPlaylist id and path references

An empty path matched every playlist without a file path, including the
referencing playlist itself, so the refresh recursed until the stack overflowed.
An empty id also shadowed a valid path in the same rule.

* fix(smartplaylists): match inPlaylist paths in both NFC and NFD forms

A playlist path is stored in the Unicode form the filesystem reports, which can
differ from the form typed in the .nsp file. The exact comparison then found no
playlist for names with accents.

* fix(smartplaylists): keep all criteria fields when normalizing child paths

The field-by-field copy dropped RefreshDelay.

* fix(smartplaylists): clean absolute inPlaylist path references

Only relative references were cleaned, so an absolute reference such as
/music/./child.nsp never matched the stored /music/child.nsp.

* fix(smartplaylists): stop infinite recursion on playlists that reference each other

Two smart playlists referencing each other, by id or by path, recursed until the
stack overflowed and the server died. The refresh now tracks visited playlists.

* fix(smartplaylists): resolve inPlaylist path references with OS-native separators

Playlist.Path is OS-native, but references in a .nsp file use forward slashes.
On Windows they never matched, and a leading slash was not seen as absolute.
The specs now build OS-native paths, so they also run on Windows.

* fix(smartplaylists): warn when a relative inPlaylist path cannot be resolved

A playlist created in the UI has no file path, so a relative reference silently
matched nothing.

* refactor(smartplaylists): simplify child playlist reference handling

Share one extractor for child ids and paths, return only the normalized rules
instead of a playlist copy, and resolve each path reference in a single switch.

* test(smartplaylists): store the Unicode child path in OS-native form

Playlist.Path is OS-native, so on Windows the forward-slash fixture never matched
the normalized reference.

---------

Signed-off-by: David <dvedvick@gmail.com>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 model/criteria/criteria.go                    | 17 ++--
 model/criteria/criteria_test.go               | 30 ++++--
 model/criteria/operators.go                   | 35 +++----
 model/playlist.go                             | 64 ++++++++++++
 model/playlist_test.go                        | 99 +++++++++++++++++++
 persistence/criteria_sql.go                   | 25 ++++-
 persistence/criteria_sql_test.go              | 12 ++-
 persistence/smart_playlist_repository.go      | 49 +++++++--
 persistence/smart_playlist_repository_test.go | 90 ++++++++++++++++-
 9 files changed, 370 insertions(+), 51 deletions(-)

diff --git a/model/criteria/criteria.go b/model/criteria/criteria.go
index 5d7dc3826..e6db3b481 100644
--- a/model/criteria/criteria.go
+++ b/model/criteria/criteria.go
@@ -64,18 +64,21 @@ func (c Criteria) IsPercentageLimit() bool {
 }
 
 func (c Criteria) ChildPlaylistIds() []string {
-	if c.Expression == nil {
-		return nil
-	}
+	return c.childPlaylistRefs(conjunction.ChildPlaylistIds)
+}
 
+func (c Criteria) ChildPlaylistPaths() []string {
+	return c.childPlaylistRefs(conjunction.ChildPlaylistPaths)
+}
+
+func (c Criteria) childPlaylistRefs(extract func(conjunction) []string) []string {
 	parent, ok := c.Expression.(conjunction)
 	if !ok {
 		return nil
 	}
-
-	ids := parent.ChildPlaylistIds()
-	slices.Sort(ids)
-	return slices.Compact(ids)
+	refs := extract(parent)
+	slices.Sort(refs)
+	return slices.Compact(refs)
 }
 
 func (c Criteria) MarshalJSON() ([]byte, error) {
diff --git a/model/criteria/criteria_test.go b/model/criteria/criteria_test.go
index 5e653150a..de5124568 100644
--- a/model/criteria/criteria_test.go
+++ b/model/criteria/criteria_test.go
@@ -323,19 +323,23 @@ var _ = Describe("Criteria", func() {
 
 	Context("with child playlists", func() {
 		var (
-			topLevelInPlaylistID     string
-			topLevelNotInPlaylistID  string
-			nestedAnyInPlaylistID    string
-			nestedAnyNotInPlaylistID string
-			nestedAllInPlaylistID    string
-			nestedAllNotInPlaylistID string
+			topLevelInPlaylistID       string
+			topLevelInPlaylistPath     string
+			topLevelNotInPlaylistID    string
+			nestedAnyInPlaylistID      string
+			nestedAnyNotInPlaylistID   string
+			nestedAllInPlaylistID      string
+			nestedAllNotInPlaylistID   string
+			nestedAnyNotInPlaylistPath string
 		)
 		BeforeEach(func() {
 			topLevelInPlaylistID = uuid.NewString()
+			topLevelInPlaylistPath = "./test.nsp"
 			topLevelNotInPlaylistID = uuid.NewString()
 
 			nestedAnyInPlaylistID = uuid.NewString()
 			nestedAnyNotInPlaylistID = uuid.NewString()
+			nestedAnyNotInPlaylistPath = "../not-in-playlist.m3u"
 
 			nestedAllInPlaylistID = uuid.NewString()
 			nestedAllNotInPlaylistID = uuid.NewString()
@@ -343,10 +347,12 @@ var _ = Describe("Criteria", func() {
 			goObj = Criteria{
 				Expression: All{
 					InPlaylist{"id": topLevelInPlaylistID},
+					InPlaylist{"path": topLevelInPlaylistPath},
 					NotInPlaylist{"id": topLevelNotInPlaylistID},
 					Any{
 						InPlaylist{"id": nestedAnyInPlaylistID},
 						NotInPlaylist{"id": nestedAnyNotInPlaylistID},
+						NotInPlaylist{"path": nestedAnyNotInPlaylistPath},
 					},
 					All{
 						InPlaylist{"id": nestedAllInPlaylistID},
@@ -359,6 +365,18 @@ var _ = Describe("Criteria", func() {
 			ids := goObj.ChildPlaylistIds()
 			gomega.Expect(ids).To(gomega.ConsistOf(topLevelInPlaylistID, topLevelNotInPlaylistID, nestedAnyInPlaylistID, nestedAnyNotInPlaylistID, nestedAllInPlaylistID, nestedAllNotInPlaylistID))
 		})
+		It("extracts all child smart playlist paths from expression criteria", func() {
+			paths := goObj.ChildPlaylistPaths()
+			gomega.Expect(paths).To(gomega.ConsistOf(topLevelInPlaylistPath, nestedAnyNotInPlaylistPath))
+		})
+		It("ignores empty child playlist paths", func() {
+			c := Criteria{Expression: All{InPlaylist{"path": ""}, NotInPlaylist{"path": ""}}}
+			gomega.Expect(c.ChildPlaylistPaths()).To(gomega.BeEmpty())
+		})
+		It("ignores empty child playlist ids", func() {
+			c := Criteria{Expression: All{InPlaylist{"id": ""}, NotInPlaylist{"id": ""}}}
+			gomega.Expect(c.ChildPlaylistIds()).To(gomega.BeEmpty())
+		})
 		It("extracts child smart playlist IDs from deeply nested expression", func() {
 			goObj = Criteria{
 				Expression: Any{
diff --git a/model/criteria/operators.go b/model/criteria/operators.go
index 14a02ff4b..ec32f2d16 100644
--- a/model/criteria/operators.go
+++ b/model/criteria/operators.go
@@ -1,8 +1,9 @@
 package criteria
 
-// Conjunctions need to implement this interface, to allow Criteria to extract child playlist IDs recursively
+// Conjunctions need to implement this interface, to allow Criteria to extract child playlist references recursively
 type conjunction interface {
 	ChildPlaylistIds() []string
+	ChildPlaylistPaths() []string
 }
 
 type (
@@ -16,9 +17,9 @@ func (all All) MarshalJSON() ([]byte, error) {
 	return marshalConjunction("all", all)
 }
 
-func (all All) ChildPlaylistIds() (ids []string) {
-	return extractPlaylistIds(all)
-}
+func (all All) ChildPlaylistIds() []string { return extractPlaylistField(all, "id") }
+
+func (all All) ChildPlaylistPaths() []string { return extractPlaylistField(all, "path") }
 
 type (
 	Any []Expression
@@ -31,9 +32,9 @@ func (any Any) MarshalJSON() ([]byte, error) {
 	return marshalConjunction("any", any)
 }
 
-func (any Any) ChildPlaylistIds() (ids []string) {
-	return extractPlaylistIds(any)
-}
+func (any Any) ChildPlaylistIds() []string { return extractPlaylistField(any, "id") }
+
+func (any Any) ChildPlaylistPaths() []string { return extractPlaylistField(any, "path") }
 
 type Is map[string]any
 type Eq = Is
@@ -172,28 +173,20 @@ func (ip IsPresent) MarshalJSON() ([]byte, error) {
 
 func (ip IsPresent) fields() map[string]any { return ip }
 
-func extractPlaylistIds(inputRule any) (ids []string) {
-	var id string
-	var ok bool
-
+func extractPlaylistField(inputRule any, field string) (values []string) {
 	switch rule := inputRule.(type) {
 	case Any:
 		for _, rules := range rule {
-			ids = append(ids, extractPlaylistIds(rules)...)
+			values = append(values, extractPlaylistField(rules, field)...)
 		}
 	case All:
 		for _, rules := range rule {
-			ids = append(ids, extractPlaylistIds(rules)...)
+			values = append(values, extractPlaylistField(rules, field)...)
 		}
-	case InPlaylist:
-		if id, ok = rule["id"].(string); ok {
-			ids = append(ids, id)
-		}
-	case NotInPlaylist:
-		if id, ok = rule["id"].(string); ok {
-			ids = append(ids, id)
+	case InPlaylist, NotInPlaylist:
+		if value, ok := rule.(Expression).fields()[field].(string); ok && value != "" {
+			values = append(values, value)
 		}
 	}
-
 	return
 }
diff --git a/model/playlist.go b/model/playlist.go
index f320d845b..19fedc9fa 100644
--- a/model/playlist.go
+++ b/model/playlist.go
@@ -2,12 +2,16 @@ package model
 
 import (
 	"iter"
+	"maps"
+	"os"
+	"path/filepath"
 	"slices"
 	"strconv"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model/criteria"
 )
 
@@ -137,6 +141,66 @@ func (pls Playlist) UploadedImagePath() string {
 	return UploadedImagePath(consts.EntityPlaylist, pls.UploadedImage)
 }
 
+// NormalizedRules returns the rules with child playlist paths resolved to absolute, OS-native paths.
+func (pls Playlist) NormalizedRules() *criteria.Criteria {
+	if pls.Rules == nil || pls.Rules.Expression == nil {
+		return pls.Rules
+	}
+
+	rules := *pls.Rules
+	rules.Expression = normalizePlaylistPaths(pls.Rules.Expression, pls.Path)
+	return &rules
+}
+
+func normalizePlaylistPaths(inputRule criteria.Expression, referencingPlaylistPath string) criteria.Expression {
+	switch rule := inputRule.(type) {
+	case criteria.Any:
+		anyCriteria := make(criteria.Any, len(rule))
+		for i, rules := range rule {
+			anyCriteria[i] = normalizePlaylistPaths(rules, referencingPlaylistPath)
+		}
+		return anyCriteria
+	case criteria.All:
+		allCriteria := make(criteria.All, len(rule))
+		for i, rules := range rule {
+			allCriteria[i] = normalizePlaylistPaths(rules, referencingPlaylistPath)
+		}
+		return allCriteria
+	case criteria.InPlaylist:
+		return criteria.InPlaylist(normalizeChildPathRule(rule, referencingPlaylistPath))
+	case criteria.NotInPlaylist:
+		return criteria.NotInPlaylist(normalizeChildPathRule(rule, referencingPlaylistPath))
+	}
+
+	return inputRule
+}
+
+func normalizeChildPathRule(rule map[string]any, referencingPlaylistPath string) map[string]any {
+	path, ok := rule["path"].(string)
+	if !ok || path == "" {
+		return rule
+	}
+
+	// References use forward slashes to stay portable, while Playlist.Path is OS-native.
+	path = filepath.FromSlash(path)
+	switch {
+	case isAbsPlaylistRef(path):
+		path = filepath.Clean(path)
+	case referencingPlaylistPath != "":
+		path = filepath.Join(filepath.Dir(referencingPlaylistPath), path)
+	default:
+		log.Warn("Cannot resolve relative playlist reference: playlist has no file path", "reference", path)
+	}
+	normalized := maps.Clone(rule)
+	normalized["path"] = path
+	return normalized
+}
+
+// filepath.IsAbs rejects a bare leading separator on Windows, but that is how Unix spells absolute.
+func isAbsPlaylistRef(path string) bool {
+	return filepath.IsAbs(path) || os.IsPathSeparator(path[0])
+}
+
 type Playlists []Playlist
 
 type PlaylistCursor iter.Seq2[Playlist, error]
diff --git a/model/playlist_test.go b/model/playlist_test.go
index d98c85716..7ffb69b63 100644
--- a/model/playlist_test.go
+++ b/model/playlist_test.go
@@ -1,6 +1,7 @@
 package model_test
 
 import (
+	"path/filepath"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -88,4 +89,102 @@ var _ = Describe("Playlist", func() {
 			Expect(model.Playlist{Sync: true}.TracksEditable()).To(BeFalse())
 		})
 	})
+
+	Describe("NormalizedRules()", func() {
+		// absPath builds an OS-native absolute path so these specs also run on Windows.
+		absPath := func(parts ...string) string {
+			abs, err := filepath.Abs(filepath.Join(parts...))
+			Expect(err).ToNot(HaveOccurred())
+			return abs
+		}
+		normalize := func(pls model.Playlist) criteria.Expression {
+			return pls.NormalizedRules().Expression
+		}
+
+		It("resolves relative references against the playlist folder", func() {
+			pls := model.Playlist{
+				Path: absPath("test", "nested", "my-playlist.nsp"),
+				Rules: &criteria.Criteria{Expression: criteria.All{
+					criteria.InPlaylist{"path": "../up.m3u"},
+					criteria.NotInPlaylist{"path": "./sibling.nsp"},
+					criteria.Any{criteria.InPlaylist{"path": "sub/deep.nsp"}},
+				}},
+			}
+			Expect(normalize(pls)).To(BeEquivalentTo(criteria.All{
+				criteria.InPlaylist{"path": absPath("test", "up.m3u")},
+				criteria.NotInPlaylist{"path": absPath("test", "nested", "sibling.nsp")},
+				criteria.Any{criteria.InPlaylist{"path": absPath("test", "nested", "sub", "deep.nsp")}},
+			}))
+		})
+
+		It("cleans absolute references", func() {
+			dirty := absPath("music") + string(filepath.Separator) + "." + string(filepath.Separator) + "child.nsp"
+			pls := model.Playlist{
+				Path:  absPath("test", "my-playlist.nsp"),
+				Rules: &criteria.Criteria{Expression: criteria.All{criteria.NotInPlaylist{"path": dirty}}},
+			}
+			Expect(normalize(pls)).To(BeEquivalentTo(criteria.All{
+				criteria.NotInPlaylist{"path": absPath("music", "child.nsp")},
+			}))
+		})
+
+		It("treats a leading slash as absolute on every OS", func() {
+			pls := model.Playlist{
+				Path:  absPath("test", "my-playlist.nsp"),
+				Rules: &criteria.Criteria{Expression: criteria.All{criteria.InPlaylist{"path": "/other/./root.m3u"}}},
+			}
+			Expect(normalize(pls)).To(BeEquivalentTo(criteria.All{
+				criteria.InPlaylist{"path": filepath.FromSlash("/other/root.m3u")},
+			}))
+		})
+
+		It("leaves empty paths and id references untouched", func() {
+			pls := model.Playlist{
+				Path: absPath("test", "my-playlist.nsp"),
+				Rules: &criteria.Criteria{Expression: criteria.All{
+					criteria.InPlaylist{"path": ""},
+					criteria.InPlaylist{"id": "94d8ba52-7aca-40e2-af82-4cb09c43d710"},
+					criteria.Eq{"artist": "Bob Dealin"},
+				}},
+			}
+			Expect(normalize(pls)).To(BeEquivalentTo(criteria.All{
+				criteria.InPlaylist{"path": ""},
+				criteria.InPlaylist{"id": "94d8ba52-7aca-40e2-af82-4cb09c43d710"},
+				criteria.Eq{"artist": "Bob Dealin"},
+			}))
+		})
+
+		It("skips relative references when the playlist has no path", func() {
+			pls := model.Playlist{
+				Rules: &criteria.Criteria{Expression: criteria.All{criteria.InPlaylist{"path": "../up.m3u"}}},
+			}
+			Expect(normalize(pls)).To(BeEquivalentTo(criteria.All{
+				criteria.InPlaylist{"path": filepath.FromSlash("../up.m3u")},
+			}))
+		})
+
+		It("preserves every other criteria field", func() {
+			rules := criteria.Criteria{
+				Expression:   criteria.All{criteria.InPlaylist{"path": "child.nsp"}},
+				Sort:         "title",
+				Order:        "desc",
+				Limit:        10,
+				LimitPercent: 25,
+				Offset:       5,
+				RefreshDelay: 3 * time.Hour,
+			}
+			pls := model.Playlist{Path: absPath("test", "my-playlist.nsp"), Rules: &rules}
+
+			normalized := *pls.NormalizedRules()
+			normalized.Expression = rules.Expression
+			Expect(normalized).To(Equal(rules))
+		})
+
+		It("does not mutate the original playlist rules", func() {
+			original := criteria.All{criteria.InPlaylist{"path": "child.nsp"}}
+			pls := model.Playlist{Path: absPath("test", "my-playlist.nsp"), Rules: &criteria.Criteria{Expression: original}}
+			_ = pls.NormalizedRules()
+			Expect(original[0]).To(BeEquivalentTo(criteria.InPlaylist{"path": "child.nsp"}))
+		})
+	})
 })
diff --git a/persistence/criteria_sql.go b/persistence/criteria_sql.go
index 890f757d7..d2f817438 100644
--- a/persistence/criteria_sql.go
+++ b/persistence/criteria_sql.go
@@ -13,6 +13,7 @@ import (
 	"github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/criteria"
+	"golang.org/x/text/unicode/norm"
 )
 
 type smartPlaylistJoinType int
@@ -344,11 +345,15 @@ func startOfPeriod(numDays int64, from time.Time) string {
 }
 
 func (c smartPlaylistCriteria) inList(values map[string]any, negate bool) (squirrel.Sqlizer, error) {
-	playlistID, ok := values["id"].(string)
-	if !ok {
-		return nil, errors.New("playlist id not given")
+	var condition squirrel.Sqlizer
+	if playlistId, ok := values["id"].(string); ok && playlistId != "" {
+		condition = squirrel.Eq{"pl.playlist_id": playlistId}
+	} else if playlistPath, ok := values["path"].(string); ok && playlistPath != "" {
+		condition = squirrel.Eq{"playlist.path": pathVariants(playlistPath)}
+	} else {
+		return nil, errors.New("playlist id or path not given")
 	}
-	filters := squirrel.And{squirrel.Eq{"pl.playlist_id": playlistID}}
+	filters := squirrel.And{condition}
 	if !c.owner.IsAdmin {
 		if c.owner.ID == "" {
 			filters = append(filters, squirrel.Eq{"playlist.public": 1})
@@ -373,6 +378,18 @@ func (c smartPlaylistCriteria) inList(values map[string]any, negate bool) (squir
 	return squirrel.Expr("media_file.id IN ("+subSQL+")", subArgs...), nil
 }
 
+// Filesystems disagree on the Unicode form of a name, so match the path in NFC and NFD.
+func pathVariants(path string) []string {
+	variants := []string{path}
+	if alt := norm.NFC.String(path); alt != path {
+		variants = append(variants, alt)
+	}
+	if alt := norm.NFD.String(path); alt != path {
+		variants = append(variants, alt)
+	}
+	return variants
+}
+
 func jsonExpr(info criteria.FieldInfo, cond squirrel.Sqlizer, negate bool) squirrel.Sqlizer {
 	if info.IsRole {
 		return roleCond{role: info.Name(), cond: cond, not: negate}
diff --git a/persistence/criteria_sql_test.go b/persistence/criteria_sql_test.go
index 8d0069b0d..ef91ec989 100644
--- a/persistence/criteria_sql_test.go
+++ b/persistence/criteria_sql_test.go
@@ -47,7 +47,10 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 		Entry("in range", criteria.InTheRange{"year": []int{1980, 1990}}, "(media_file.year >= ? AND media_file.year <= ?)", 1980, 1990),
 		Entry("before", criteria.Before{"lastPlayed": time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)}, "annotation.play_date < ?", time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)),
 		Entry("after", criteria.After{"lastPlayed": time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)}, "annotation.play_date > ?", time.Date(2021, 10, 1, 0, 0, 0, 0, time.Local)),
-		Entry("in playlist", criteria.InPlaylist{"id": "deadbeef-dead-beef"}, "media_file.id IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND playlist.public = ?))", "deadbeef-dead-beef", 1),
+		Entry("in playlist [path]", criteria.InPlaylist{"path": "lacuslacus.nsp"}, "media_file.id IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (playlist.path IN (?) AND playlist.public = ?))", "lacuslacus.nsp", 1),
+		Entry("in playlist [id]", criteria.InPlaylist{"id": "deadbeef-dead-beef"}, "media_file.id IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND playlist.public = ?))", "deadbeef-dead-beef", 1),
+		Entry("in playlist [empty id falls back to path]", criteria.InPlaylist{"id": "", "path": "/music/x.nsp"}, "media_file.id IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (playlist.path IN (?) AND playlist.public = ?))", "/music/x.nsp", 1),
+		Entry("in playlist [decomposed unicode path]", criteria.InPlaylist{"path": "/m\u00fasica/x.nsp"}, "media_file.id IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (playlist.path IN (?,?) AND playlist.public = ?))", "/m\u00fasica/x.nsp", "/mu\u0301sica/x.nsp", 1),
 		Entry("not in playlist", criteria.NotInPlaylist{"id": "deadbeef-dead-beef"}, "media_file.id NOT IN (SELECT media_file_id FROM playlist_tracks pl LEFT JOIN playlist on pl.playlist_id = playlist.id WHERE (pl.playlist_id = ? AND playlist.public = ?))", "deadbeef-dead-beef", 1),
 		Entry("album annotation", criteria.Gt{"albumRating": 3}, "album_annotation.rating > ?", 3),
 		Entry("artist annotation", criteria.Is{"artistLoved": true}, "artist_annotation.starred = ?", true),
@@ -268,6 +271,13 @@ var _ = Describe("Smart playlist criteria SQL", func() {
 		Expect(err).To(MatchError(ContainSubstring("invalid boolean value for 'missing' expression")))
 	})
 
+	It("returns an error when inPlaylist has empty path", func() {
+		_, err := newSmartPlaylistCriteria(
+			criteria.Criteria{Expression: criteria.InPlaylist{"path": ""}},
+			withSmartPlaylistOwner(model.User{ID: "owner-id", IsAdmin: false})).where()
+		Expect(err).To(MatchError(ContainSubstring("playlist id or path not given")))
+	})
+
 	It("returns an error for a range over a tag/role field", func() {
 		_, err := newSmartPlaylistCriteria(criteria.Criteria{Expression: criteria.InTheRange{"rate": []int{1, 5}}}).where()
 		Expect(err).To(MatchError(ContainSubstring("range operator not supported for tag/role field")))
diff --git a/persistence/smart_playlist_repository.go b/persistence/smart_playlist_repository.go
index 9d2ac9590..24c6f5fc5 100644
--- a/persistence/smart_playlist_repository.go
+++ b/persistence/smart_playlist_repository.go
@@ -1,11 +1,14 @@
 package persistence
 
 import (
+	"slices"
 	"time"
 
 	. "github.com/Masterminds/squirrel"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
+	"golang.org/x/text/unicode/norm"
 )
 
 // PlaylistRepository methods to handle smart playlists, which are defined by criteria and automatically populated
@@ -16,6 +19,17 @@ import (
 
 // refreshSmartPlaylist evaluates the criteria of a smart playlist and updates its tracks accordingly.
 func (r *playlistRepository) refreshSmartPlaylist(pls *model.Playlist) bool {
+	return r.refreshSmartPlaylistTree(pls, map[string]struct{}{})
+}
+
+// The visited set stops playlists that reference each other from recursing forever.
+func (r *playlistRepository) refreshSmartPlaylistTree(pls *model.Playlist, visited map[string]struct{}) bool {
+	if _, seen := visited[pls.ID]; seen {
+		log.Trace(r.ctx, "Skipping already visited smart playlist", "playlist", pls.Name, "id", pls.ID)
+		return false
+	}
+	visited[pls.ID] = struct{}{}
+
 	usr := loggedUser(r.ctx)
 	if !r.shouldRefreshSmartPlaylist(pls, usr) {
 		return false
@@ -30,9 +44,9 @@ func (r *playlistRepository) refreshSmartPlaylist(pls *model.Playlist) bool {
 		return false
 	}
 
-	rulesSQL := newSmartPlaylistCriteria(*pls.Rules, withSmartPlaylistOwner(*usr))
+	rulesSQL := newSmartPlaylistCriteria(*pls.NormalizedRules(), withSmartPlaylistOwner(*usr))
 
-	if !r.refreshChildPlaylists(pls, rulesSQL) {
+	if !r.refreshChildPlaylists(pls, rulesSQL, visited) {
 		return false
 	}
 
@@ -89,28 +103,47 @@ func (r *playlistRepository) shouldRefreshSmartPlaylist(pls *model.Playlist, usr
 
 // refreshChildPlaylists handles refreshing any child playlists that are referenced in the smart playlist criteria.
 // Returns false if child playlists could not be loaded (DB error), signaling the parent refresh should abort.
-func (r *playlistRepository) refreshChildPlaylists(pls *model.Playlist, rulesSQL smartPlaylistCriteria) bool {
+func (r *playlistRepository) refreshChildPlaylists(pls *model.Playlist, rulesSQL smartPlaylistCriteria, visited map[string]struct{}) bool {
 	childPlaylistIds := rulesSQL.ChildPlaylistIds()
-	if len(childPlaylistIds) == 0 {
+	childPlaylistPaths := rulesSQL.ChildPlaylistPaths()
+	if len(childPlaylistIds) == 0 && len(childPlaylistPaths) == 0 {
 		return true
 	}
 
-	childPlaylists, err := r.GetAll(model.QueryOptions{Filters: Eq{"playlist.id": childPlaylistIds}})
+	var conditions Or
+	if len(childPlaylistIds) > 0 {
+		conditions = append(conditions, Eq{"playlist.id": childPlaylistIds})
+	}
+	if len(childPlaylistPaths) > 0 {
+		lookupPaths := slices.Concat(slice.Map(childPlaylistPaths, pathVariants)...)
+		conditions = append(conditions, Eq{"playlist.path": lookupPaths})
+	}
+
+	childPlaylists, err := r.GetAll(model.QueryOptions{Filters: conditions})
 	if err != nil {
-		log.Error(r.ctx, "Error loading child playlists for smart playlist refresh", "playlist", pls.Name, "id", pls.ID, "childIds", childPlaylistIds, err)
+		log.Error(r.ctx, "Error loading child playlists for smart playlist refresh", "playlist", pls.Name, "id", pls.ID, "childIds", childPlaylistIds, "childPaths", childPlaylistPaths, err)
 		return false
 	}
 
-	found := make(map[string]struct{}, len(childPlaylists))
+	found := make(map[string]struct{}, len(childPlaylists)*2)
 	for i := range childPlaylists {
 		found[childPlaylists[i].ID] = struct{}{}
-		r.refreshSmartPlaylist(&childPlaylists[i])
+		if childPlaylists[i].Path != "" {
+			found[norm.NFC.String(childPlaylists[i].Path)] = struct{}{}
+		}
+		r.refreshSmartPlaylistTree(&childPlaylists[i], visited)
 	}
 	for _, id := range childPlaylistIds {
 		if _, ok := found[id]; !ok {
 			log.Warn(r.ctx, "Referenced playlist is not accessible to smart playlist owner", "playlist", pls.Name, "id", pls.ID, "childId", id, "ownerId", pls.OwnerID)
 		}
 	}
+
+	for _, path := range childPlaylistPaths {
+		if _, ok := found[norm.NFC.String(path)]; !ok {
+			log.Warn(r.ctx, "Referenced playlist is not accessible to smart playlist owner", "playlist", pls.Name, "id", pls.ID, "path", path, "ownerId", pls.OwnerID)
+		}
+	}
 	return true
 }
 
diff --git a/persistence/smart_playlist_repository_test.go b/persistence/smart_playlist_repository_test.go
index 6f8684d5c..33da0c1b7 100644
--- a/persistence/smart_playlist_repository_test.go
+++ b/persistence/smart_playlist_repository_test.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"path/filepath"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -124,13 +125,23 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 							criteria.Contains{"title": "Day"},
 						},
 					}
-					nestedPls := model.Playlist{Name: "Nested", OwnerID: "userid", Public: true, Rules: childRules}
+					nestedPls := model.Playlist{Name: "Nested [ID]", OwnerID: "userid", Public: true, Rules: childRules}
 					Expect(repo.Put(&nestedPls)).To(Succeed())
 					DeferCleanup(func() { _ = repo.Delete(nestedPls.ID) })
 
-					parentPls := model.Playlist{Name: "Parent", OwnerID: "userid", Rules: &criteria.Criteria{
+					childRules = &criteria.Criteria{
 						Expression: criteria.All{
+							criteria.Eq{"artist": "シートベルツ"},
+						},
+					}
+					nestedPathPls := model.Playlist{Name: "Nested [Path]", OwnerID: "userid", Path: "test.nsp", Public: true, Rules: childRules}
+					Expect(repo.Put(&nestedPathPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(nestedPathPls.ID) })
+
+					parentPls := model.Playlist{Name: "Parent", OwnerID: "userid", Rules: &criteria.Criteria{
+						Expression: criteria.Any{
 							criteria.InPlaylist{"id": nestedPls.ID},
+							criteria.InPlaylist{"path": nestedPathPls.Path},
 						},
 					}}
 					Expect(repo.Put(&parentPls)).To(Succeed())
@@ -148,17 +159,88 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 					Expect(*pls.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
 
 					// Parent should have tracks from the nested playlist
-					Expect(pls.Tracks).To(HaveLen(1))
+					Expect(pls.Tracks).To(HaveLen(2))
 					Expect(pls.Tracks[0].MediaFileID).To(Equal(songDayInALife.ID))
 
-					// Nested playlist should now have been refreshed (EvaluatedAt set)
+					// Nested playlists should now have been refreshed (EvaluatedAt set)
 					nestedPlsAfterParentGet, err := repo.Get(nestedPls.ID)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(nestedPlsAfterParentGet.EvaluatedAt).ToNot(BeNil())
 					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
+
+					nestedPlsAfterParentGet, err = repo.Get(nestedPathPls.ID)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(nestedPlsAfterParentGet.EvaluatedAt).ToNot(BeNil())
+					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
 				})
 			})
 
+			It("does not recurse forever when two smart playlists reference each other", func() {
+				conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+
+				plsA := model.Playlist{Name: "Cycle A", OwnerID: "userid", Public: true, Rules: &criteria.Criteria{
+					Expression: criteria.All{criteria.Contains{"title": "Day"}},
+				}}
+				Expect(repo.Put(&plsA)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(plsA.ID) })
+
+				plsB := model.Playlist{Name: "Cycle B", OwnerID: "userid", Public: true, Rules: &criteria.Criteria{
+					Expression: criteria.All{criteria.InPlaylist{"id": plsA.ID}},
+				}}
+				Expect(repo.Put(&plsB)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(plsB.ID) })
+
+				plsA.Rules = &criteria.Criteria{Expression: criteria.All{criteria.InPlaylist{"id": plsB.ID}}}
+				Expect(repo.Put(&plsA)).To(Succeed())
+
+				_, err := repo.GetWithTracks(plsA.ID, true, false)
+				Expect(err).ToNot(HaveOccurred())
+			})
+
+			It("does not treat an empty path as a reference to every playlist without a path", func() {
+				conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+
+				bystander := model.Playlist{Name: "Bystander", OwnerID: "userid", Public: true, Rules: &criteria.Criteria{
+					Expression: criteria.All{criteria.Contains{"title": "Day"}},
+				}}
+				Expect(repo.Put(&bystander)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(bystander.ID) })
+
+				parent := model.Playlist{Name: "Empty Path", OwnerID: "userid", Public: true, Rules: &criteria.Criteria{
+					Expression: criteria.All{criteria.InPlaylist{"path": ""}},
+				}}
+				Expect(repo.Put(&parent)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(parent.ID) })
+
+				_, err := repo.GetWithTracks(parent.ID, true, false)
+				Expect(err).ToNot(HaveOccurred())
+
+				reloaded, err := repo.Get(bystander.ID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(reloaded.EvaluatedAt).To(BeNil())
+			})
+
+			It("matches a child path stored in a different Unicode normalization form", func() {
+				conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
+
+				child := model.Playlist{Name: "NFD Child", OwnerID: "userid", Public: true, Path: filepath.FromSlash("/mu\u0301sica/child.nsp"), Rules: &criteria.Criteria{
+					Expression: criteria.All{criteria.Contains{"title": "Day"}},
+				}}
+				Expect(repo.Put(&child)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(child.ID) })
+
+				parent := model.Playlist{Name: "NFC Parent", OwnerID: "userid", Rules: &criteria.Criteria{
+					Expression: criteria.All{criteria.InPlaylist{"path": "/m\u00fasica/child.nsp"}},
+				}}
+				Expect(repo.Put(&parent)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(parent.ID) })
+
+				pls, err := repo.GetWithTracks(parent.ID, true, false)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(pls.Tracks).To(HaveLen(1))
+				Expect(pls.Tracks[0].MediaFileID).To(Equal(songDayInALife.ID))
+			})
+
 			When("refresh delay has not expired", func() {
 				It("should NOT refresh tracks for smart playlist referenced in parent smart playlist criteria", func() {
 					conf.Server.SmartPlaylistRefreshDelay = 1 * time.Hour

From 2913c13cdf7471eb632fbc87bc02df1d071711bf Mon Sep 17 00:00:00 2001
From: Jonatan Nyberg <84130654+NickWick13@users.noreply.github.com>
Date: Sun, 20 Sep 2026 19:10:47 +0300
Subject: [PATCH 156/200] fix(i18n): improve Swedish translation (#6177)

Signed-off-by: Jonatan Nyberg <84130654+NickWick13@users.noreply.github.com>
---
 resources/i18n/sv.json | 426 ++++++++++++++++++++++-------------------
 1 file changed, 226 insertions(+), 200 deletions(-)

diff --git a/resources/i18n/sv.json b/resources/i18n/sv.json
index 228cc2cf3..ff4f53a6b 100644
--- a/resources/i18n/sv.json
+++ b/resources/i18n/sv.json
@@ -11,22 +11,22 @@
         "title": "Titel",
         "artist": "Artist",
         "album": "Album",
-        "path": "Sökväg",
+        "path": "Filsökväg",
         "genre": "Genre",
-        "compilation": "Samling",
+        "compilation": "Samlingsalbum",
         "year": "År",
         "size": "Filstorlek",
         "updatedAt": "Uppdaterad",
-        "bitRate": "Bitrate",
-        "discSubtitle": "Underrubrik",
+        "bitRate": "Bithastighet",
+        "discSubtitle": "Skivans undertitel",
         "starred": "Favorit",
         "comment": "Kommentar",
         "rating": "Betyg",
         "quality": "Kvalitet",
         "bpm": "BPM",
         "playDate": "Senast spelad",
-        "channels": "Channels",
-        "createdAt": "Skapad",
+        "channels": "Kanaler",
+        "createdAt": "Tillagd",
         "grouping": "Gruppering",
         "mood": "Stämning",
         "participants": "Ytterligare medverkande",
@@ -35,19 +35,21 @@
         "rawTags": "Omodifierade taggar",
         "bitDepth": "Bitdjup",
         "sampleRate": "Samplingsfrekvens",
-        "missing": "Saknade",
+        "missing": "Saknas",
         "libraryName": "Bibliotek",
         "composer": "Kompositör",
-        "disc": "Disc %{discNumber}"
+        "disc": "Skiva %{discNumber}",
+        "albumGain": "Volymjustering (album)",
+        "trackGain": "Volymjustering (låt)"
       },
       "actions": {
         "addToQueue": "Lägg till i kön",
         "playNow": "Spela nu",
         "addToPlaylist": "Lägg till i spellista",
-        "shuffleAll": "Shuffle",
+        "shuffleAll": "Blanda alla",
         "download": "Ladda ner",
-        "playNext": "Spela nästa",
-        "info": "Mer information",
+        "playNext": "Spela härnäst",
+        "info": "Visa information",
         "showInPlaylist": "Visa i spellista",
         "instantMix": "Direktmix"
       }
@@ -62,12 +64,12 @@
         "playCount": "Spelningar",
         "name": "Namn",
         "genre": "Genre",
-        "compilation": "Samling",
+        "compilation": "Samlingsalbum",
         "year": "År",
         "updatedAt": "Uppdaterad",
         "comment": "Kommentar",
         "rating": "Betyg",
-        "createdAt": "Skapad",
+        "createdAt": "Tillagt",
         "size": "Storlek",
         "originalDate": "Originaldatum",
         "releaseDate": "Utgivningsdatum",
@@ -80,27 +82,28 @@
         "media": "Media",
         "mood": "Stämning",
         "date": "Inspelningsdatum",
-        "missing": "Saknade",
+        "missing": "Saknas",
         "libraryName": "Bibliotek"
       },
       "actions": {
         "playAll": "Spela",
         "playNext": "Spela härnäst",
         "addToQueue": "Lägg till i kön",
-        "shuffle": "Shuffle",
+        "shuffle": "Blanda",
         "addToPlaylist": "Lägg till i spellista",
         "download": "Ladda ner",
-        "info": "Mer information",
-        "share": "Dela"
+        "info": "Visa information",
+        "share": "Dela",
+        "refresh": "Uppdatera metadata"
       },
       "lists": {
         "all": "Alla",
-        "random": "Blanda",
-        "recentlyAdded": "Senast tillagda",
-        "recentlyPlayed": "Senast spelade",
+        "random": "Slumpmässiga",
+        "recentlyAdded": "Nyligen tillagda",
+        "recentlyPlayed": "Nyligen spelade",
         "mostPlayed": "Mest spelade",
         "starred": "Favoriter",
-        "topRated": "Bästa betyg"
+        "topRated": "Högst betygsatta"
       }
     },
     "artist": {
@@ -114,26 +117,26 @@
         "genre": "Genre",
         "size": "Storlek",
         "role": "Roll",
-        "missing": "Saknade"
+        "missing": "Saknas"
       },
       "roles": {
         "albumartist": "Albumartist |||| Albumartister",
         "artist": "Artist |||| Artister",
-        "composer": "Kompositör |||| Kompositörer",
+        "composer": "Kompositör |||| Kompositörer",
         "conductor": "Dirigent |||| Dirigenter",
         "lyricist": "Textförfattare |||| Textförfattare",
         "arranger": "Arrangör |||| Arrangörer",
         "producer": "Producent |||| Producenter",
         "director": "Inspelningsledare |||| Inspelningsledare",
         "engineer": "Ljudtekniker |||| Ljudtekniker",
-        "mixer": "Mixare |||| Mixare",
-        "remixer": "Remixare |||| Remixare",
-        "djmixer": "DJ-mixare |||| DJ-mixare",
-        "performer": "Utövande artist |||| Utövande artister",
-        "maincredit": "Albumartister eller Artist |||| Albumartister eller Artister"
+        "mixer": "Mixare |||| Mixare",
+        "remixer": "Remixare |||| Remixare",
+        "djmixer": "DJ-mixare |||| DJ-mixare",
+        "performer": "Utövande artist |||| Utövande artister",
+        "maincredit": "Albumartist eller artist |||| Albumartister eller artister"
       },
       "actions": {
-        "shuffle": "Shuffle",
+        "shuffle": "Blanda",
         "radio": "Radio",
         "topSongs": "Topplåtar"
       }
@@ -142,7 +145,7 @@
       "name": "Användare |||| Användare",
       "fields": {
         "userName": "Användarnamn",
-        "isAdmin": "Är admin",
+        "isAdmin": "Administratör",
         "lastLoginAt": "Senaste inloggning",
         "updatedAt": "Uppdaterad",
         "name": "Namn",
@@ -151,13 +154,15 @@
         "changePassword": "Byt lösenord?",
         "currentPassword": "Nuvarande lösenord",
         "newPassword": "Nytt lösenord",
-        "token": "Token",
+        "token": "Åtkomsttoken",
         "lastAccessAt": "Senaste åtkomst",
-        "libraries": "Bibliotek"
+        "libraries": "Bibliotek",
+        "scrobbleFilter": "Scrobblingsfilter"
       },
       "helperTexts": {
         "name": "Ändringar av ditt namn syns först vid nästa inloggning",
-        "libraries": "Välj ett bibliotek för denna användare eller lämna blankt för standardbibliotek"
+        "libraries": "Välj vilka bibliotek användaren ska ha tillgång till, eller lämna tomt för att använda standardbiblioteken",
+        "scrobbleFilter": "Låtar som matchar dessa regler för smarta spellistor skickas inte till Last.fm, ListenBrainz eller scrobblingtillägg. Samma JSON-syntax och beteende som för smarta spellistor används. Exempel: {\"all\":[{\"lt\":{\"rating\":4}}]}. Lämna tomt för att scrobbla allt. Antalet spelningar som lagras lokalt påverkas inte."
       },
       "notifications": {
         "created": "Användare skapad",
@@ -165,13 +170,14 @@
         "deleted": "Användare borttagen"
       },
       "message": {
-        "listenBrainzToken": "Ange din ListenBrainz användar-token.",
+        "listenBrainzToken": "Ange din användartoken för ListenBrainz.",
         "clickHereForToken": "Klicka här för att hämta din token",
         "selectAllLibraries": "Välj alla bibliotek",
-        "adminAutoLibraries": "Administratörer har automatiskt tillgång till alla bibliotek"
+        "adminAutoLibraries": "Administratörer har automatiskt åtkomst till alla bibliotek"
       },
       "validation": {
-        "librariesRequired": "Minst ett bibliotek måste väljas för icke-administratörer"
+        "librariesRequired": "Minst ett bibliotek måste väljas för användare som inte är administratörer",
+        "invalidScrobbleFilter": "Måste innehålla giltiga regler för smarta spellistor. Begränsning av antalet låtar, förskjutning och uppdateringsfördröjning stöds inte."
       }
     },
     "player": {
@@ -179,12 +185,12 @@
       "fields": {
         "name": "Namn",
         "transcodingId": "Omkodning",
-        "maxBitRate": "Max. bitrate",
+        "maxBitRate": "Högsta bithastighet",
         "client": "Klient",
         "userName": "Användarnamn",
         "lastSeen": "Senast sedd",
-        "reportRealPath": "Visa hela sökvägen",
-        "scrobbleEnabled": "Scrobbla till extern tjänst"
+        "reportRealPath": "Rapportera den faktiska sökvägen",
+        "scrobbleEnabled": "Scrobbla till externa tjänster"
       }
     },
     "transcoding": {
@@ -192,8 +198,11 @@
       "fields": {
         "name": "Namn",
         "targetFormat": "Målformat",
-        "defaultBitRate": "Standardbitrate",
+        "defaultBitRate": "Standardbithastighet",
         "command": "Kommando"
+      },
+      "choices": {
+        "noDefaultBitRate": "Ingen"
       }
     },
     "playlist": {
@@ -207,8 +216,9 @@
         "createdAt": "Skapad",
         "songCount": "Låtar",
         "comment": "Kommentar",
-        "sync": "Auto-import",
-        "path": "Importera från"
+        "sync": "Automatisk import",
+        "path": "Importera från",
+        "starred": "Favorit"
       },
       "actions": {
         "selectPlaylist": "Välj en spellista:",
@@ -216,24 +226,24 @@
         "export": "Exportera",
         "makePublic": "Gör offentlig",
         "makePrivate": "Gör privat",
-        "saveQueue": "Spara kö till spellista",
-        "searchOrCreate": "Sök spellista eller skapa ny...",
-        "pressEnterToCreate": "Tryck Enter för att skapa ny spellista",
-        "removeFromSelection": "Ta bort från urval"
+        "saveQueue": "Spara kön i en spellista",
+        "searchOrCreate": "Sök spellistor eller skriv för att skapa en ny...",
+        "pressEnterToCreate": "Tryck på Enter för att skapa en ny spellista",
+        "removeFromSelection": "Ta bort från urvalet"
       },
       "message": {
-        "duplicate_song": "Lägg till dubletter",
-        "song_exist": "Vissa låtar finns redan i spellistan. Vill du lägga till dubbletterna eller hoppa över dem?",
-        "noPlaylistsFound": "Hittade inga spellistor",
+        "duplicate_song": "Lägg till dubbletter",
+        "song_exist": "Du håller på att lägga till dubbletter i spellistan. Vill du lägga till dem eller hoppa över dem?",
+        "noPlaylistsFound": "Inga spellistor hittades",
         "noPlaylists": "Inga spellistor tillgängliga"
       }
     },
     "radio": {
-      "name": "Radio |||| Radior",
+      "name": "Radiostation |||| Radiostationer",
       "fields": {
         "name": "Namn",
-        "streamUrl": "Stream-URL",
-        "homePageUrl": "Hemside-URL",
+        "streamUrl": "Strömmens URL",
+        "homePageUrl": "Webbplatsens URL",
         "updatedAt": "Uppdaterad",
         "createdAt": "Skapad"
       },
@@ -242,7 +252,7 @@
       }
     },
     "share": {
-      "name": "Dela |||| Delningar",
+      "name": "Delning |||| Delningar",
       "fields": {
         "username": "Delad av",
         "url": "URL",
@@ -252,11 +262,13 @@
         "lastVisitedAt": "Senast besökt",
         "visitCount": "Besök",
         "format": "Format",
-        "maxBitRate": "Max. bitrate",
+        "maxBitRate": "Högsta bithastighet",
         "updatedAt": "Uppdaterad",
         "createdAt": "Skapad",
-        "downloadable": "Tillåt nedladdning?"
-      }
+        "downloadable": "Tillåt nedladdningar?"
+      },
+      "notifications": {},
+      "actions": {}
     },
     "missing": {
       "name": "Saknad fil |||| Saknade filer",
@@ -267,11 +279,11 @@
         "libraryName": "Bibliotek"
       },
       "actions": {
-        "remove": "Radera",
-        "remove_all": "Radera alla"
+        "remove": "Ta bort",
+        "remove_all": "Ta bort alla"
       },
       "notifications": {
-        "removed": "Saknade fil(er) borttagna"
+        "removed": "Saknade filer har tagits bort"
       },
       "empty": "Inga saknade filer"
     },
@@ -280,8 +292,8 @@
       "fields": {
         "name": "Namn",
         "path": "Sökväg",
-        "remotePath": "Ta bort sökväg",
-        "lastScanAt": "Senaste scan",
+        "remotePath": "Fjärrsökväg",
+        "lastScanAt": "Senaste skanning",
         "songCount": "Låtar",
         "albumCount": "Album",
         "artistCount": "Artister",
@@ -302,33 +314,33 @@
         "statistics": "Statistik"
       },
       "actions": {
-        "scan": "Scanna bibliotek",
+        "scan": "Skanna biblioteket",
         "manageUsers": "Hantera användaråtkomst",
-        "viewDetails": "Se detaljer",
-        "quickScan": "Snabbscan",
-        "fullScan": "Komplett scan"
+        "viewDetails": "Visa detaljer",
+        "quickScan": "Snabbskanning",
+        "fullScan": "Fullständig skanning"
       },
       "notifications": {
         "created": "Biblioteket har skapats",
         "updated": "Biblioteket har uppdaterats",
-        "deleted": "Biblioteket har raderats",
-        "scanStarted": "Biblioteksscan startad",
-        "scanCompleted": "Biblioteksscan avslutad",
-        "quickScanStarted": "Snabbscan startad",
-        "fullScanStarted": "Komplett scan startad",
-        "scanError": "Fel vid start av scan. Se loggarna"
+        "deleted": "Biblioteket har tagits bort",
+        "scanStarted": "Skanning av biblioteket har startat",
+        "scanCompleted": "Skanning av biblioteket är klar",
+        "quickScanStarted": "Snabbskanning har startat",
+        "fullScanStarted": "Fullständig skanning har startat",
+        "scanError": "Kunde inte starta skanningen. Kontrollera loggarna"
       },
       "validation": {
-        "nameRequired": "Biblioteksnamn krävs",
-        "pathRequired": "Bibliotekssökväg krävs",
-        "pathNotDirectory": "Bibliotekssökvägen måste vara en katalog",
-        "pathNotFound": "Bibliotekssökväg hittades inte",
-        "pathNotAccessible": "Bibliotekssökväg inte tillgänglig",
-        "pathInvalid": "Ogiltig bibliotekssökväg"
+        "nameRequired": "Ange ett biblioteksnamn",
+        "pathRequired": "Ange en sökväg till biblioteket",
+        "pathNotDirectory": "Bibliotekets sökväg måste peka på en katalog",
+        "pathNotFound": "Bibliotekets sökväg hittades inte",
+        "pathNotAccessible": "Bibliotekets sökväg är inte åtkomlig",
+        "pathInvalid": "Ogiltig sökväg till biblioteket"
       },
       "messages": {
-        "deleteConfirm": "Är du säker på att du vill ta bort detta bibliotek? Detta raderar all förbunden data och användartillgång.",
-        "scanInProgress": "Scanning pågår...",
+        "deleteConfirm": "Är du säker på att du vill ta bort det här biblioteket? Alla tillhörande data och användarnas åtkomst till biblioteket tas bort.",
+        "scanInProgress": "Skanning pågår...",
         "noLibrariesAssigned": "Inga bibliotek har tilldelats den här användaren"
       }
     },
@@ -339,44 +351,44 @@
         "name": "Namn",
         "description": "Beskrivning",
         "version": "Version",
-        "author": "Författare",
-        "website": "Website",
+        "author": "Upphovsperson",
+        "website": "Webbplats",
         "permissions": "Behörigheter",
-        "enabled": "Aktiverad",
+        "enabled": "Aktiverat",
         "status": "Status",
         "path": "Sökväg",
         "lastError": "Fel",
         "hasError": "Fel",
-        "updatedAt": "Uppdaterad",
-        "createdAt": "Installerad",
+        "updatedAt": "Uppdaterat",
+        "createdAt": "Installerat",
         "configKey": "Nyckel",
         "configValue": "Värde",
         "allUsers": "Tillåt alla användare",
         "selectedUsers": "Valda användare",
         "allLibraries": "Tillåt alla bibliotek",
         "selectedLibraries": "Valda bibliotek",
-        "allowWriteAccess": "Tillåt skrivrättigheter"
+        "allowWriteAccess": "Tillåt skrivåtkomst"
       },
       "sections": {
         "status": "Status",
-        "info": "Tilläggsinformation",
+        "info": "Information om tillägget",
         "configuration": "Konfiguration",
         "manifest": "Manifest",
-        "usersPermission": "Användarbehörigheter",
-        "libraryPermission": "Biblioteksbehörigheter"
+        "usersPermission": "Åtkomst till användare",
+        "libraryPermission": "Åtkomst till bibliotek"
       },
       "status": {
-        "enabled": "Aktiverad",
-        "disabled": "Inaktiverad"
+        "enabled": "Aktiverat",
+        "disabled": "Inaktiverat"
       },
       "actions": {
         "enable": "Aktivera",
         "disable": "Inaktivera",
-        "disabledDueToError": "Åtgärda felet innan aktivering",
+        "disabledDueToError": "Åtgärda felet före aktivering",
         "disabledUsersRequired": "Välj användare före aktivering",
         "disabledLibrariesRequired": "Välj bibliotek före aktivering",
         "addConfig": "Lägg till konfiguration",
-        "rescan": "Scanna om"
+        "rescan": "Skanna om"
       },
       "notifications": {
         "enabled": "Tillägg aktiverat",
@@ -391,17 +403,18 @@
         "configHelp": "Konfigurera tillägget med nyckel–värde-par. Lämna tomt om tillägget inte kräver någon konfiguration.",
         "clickPermissions": "Klicka på en behörighet för mer information",
         "noConfig": "Ingen konfiguration angiven",
-        "allUsersHelp": "När den är aktiverad får tillägget tillgång till alla användare, inklusive de som skapas i framtiden.",
+        "allUsersHelp": "När alternativet är aktiverat får tillägget åtkomst till alla användare, även de som skapas i framtiden.",
         "noUsers": "Inga användare valda",
         "permissionReason": "Orsak",
-        "usersRequired": "Detta tillägg kräver åtkomst till användarinformation. Välj vilka användare insticksprogrammet ska ha åtkomst till, eller aktivera 'Tillåt alla användare'.",
-        "allLibrariesHelp": "När den är aktiverad får tillägget tillgång till alla bibliotek, inklusive de som skapas i framtiden.",
+        "usersRequired": "Det här tillägget behöver åtkomst till användarinformation. Välj vilka användare tillägget får åtkomst till eller aktivera 'Tillåt alla användare'.",
+        "allLibrariesHelp": "När alternativet är aktiverat får tillägget åtkomst till alla bibliotek, även de som skapas i framtiden.",
         "noLibraries": "Inga bibliotek valda",
-        "librariesRequired": "Detta tillägg kräver tillgång till biblioteksinformation. Välj vilka bibliotek tillägget kan komma åt eller aktivera 'Tillåt alla bibliotek'.",
-        "requiredHosts": "Krävda värdar",
+        "librariesRequired": "Det här tillägget behöver åtkomst till biblioteksinformation. Välj vilka bibliotek tillägget får åtkomst till eller aktivera 'Tillåt alla bibliotek'.",
+        "requiredHosts": "Värdar som krävs",
         "configValidationError": "Validering av konfigurationen misslyckades:",
-        "schemaRenderError": "Kunde inte rendera konfigurationsformuläret. Tilläggets schema kan vara ogiltigt.",
-        "allowWriteAccessHelp": "När detta är aktiverat kan tillägget ändra filer i bibliotekets kataloger. Som standard har tillägget endast läsrättigheter."
+        "schemaRenderError": "Kunde inte visa konfigurationsformuläret. Tilläggets schema kan vara ogiltigt.",
+        "allowWriteAccessHelp": "När alternativet är aktiverat kan tillägget ändra filer i bibliotekens kataloger. Som standard har tillägg endast läsåtkomst.",
+        "idHelp": "Tilläggets ID hämtas från filnamnet. Använd det när du hänvisar till tillägget i konfigurationsalternativ, till exempel Agents."
       },
       "placeholders": {
         "configKey": "nyckel",
@@ -412,40 +425,40 @@
   "ra": {
     "auth": {
       "welcome1": "Tack för att du installerade Navidrome!",
-      "welcome2": "Skapa först ett admin-konto",
+      "welcome2": "Börja med att skapa ett administratörskonto",
       "confirmPassword": "Bekräfta lösenord",
-      "buttonCreateAdmin": "Skapa admin-konto",
+      "buttonCreateAdmin": "Skapa administratörskonto",
       "auth_check_error": "Logga in för att fortsätta",
       "user_menu": "Profil",
       "username": "Användarnamn",
       "password": "Lösenord",
       "sign_in": "Logga in",
-      "sign_in_error": "Felaktig inloggning, försök igen",
+      "sign_in_error": "Inloggningen misslyckades. Försök igen",
       "logout": "Logga ut",
-      "insightsCollectionNote": "Navidrome samlar anonym användardata för att\nhjälpa projektet att bli bättre. Klicka [här]\nför att läsa mer och avaktivera om du vill"
+      "insightsCollectionNote": "Navidrome samlar in anonyma användningsdata för\natt förbättra projektet. Klicka [här] för att läsa mer\noch välja bort insamlingen"
     },
     "validation": {
       "invalidChars": "Använd enbart bokstäver och siffror",
-      "passwordDoesNotMatch": "Lösenordet matchar inte",
-      "required": "Krävs",
-      "minLength": "Måste ha minst %{min} tecken",
-      "maxLength": "Får maximalt ha %{max} tecken",
+      "passwordDoesNotMatch": "Lösenorden stämmer inte överens",
+      "required": "Obligatoriskt",
+      "minLength": "Måste innehålla minst %{min} tecken",
+      "maxLength": "Får innehålla högst %{max} tecken",
       "minValue": "Måste vara minst %{min}",
-      "maxValue": "Får maximalt vara %{max}",
-      "number": "Måste vara ett nummer",
+      "maxValue": "Får vara högst %{max}",
+      "number": "Måste vara ett tal",
       "email": "Måste vara en giltig e-postadress",
-      "oneOf": "Måste vara en av: %{options}",
-      "regex": "Måste matcha ett specifikt format (regexp): %{pattern}",
-      "unique": "Måste vara unik",
+      "oneOf": "Måste vara något av: %{options}",
+      "regex": "Måste matcha det reguljära uttrycket: %{pattern}",
+      "unique": "Måste vara unikt",
       "url": "Måste vara en giltig URL"
     },
     "action": {
       "add_filter": "Lägg till filter",
       "add": "Lägg till",
       "back": "Tillbaka",
-      "bulk_actions": "1 objekt vald |||| %{smart_count} objekt valda",
+      "bulk_actions": "1 objekt valt |||| %{smart_count} objekt valda",
       "cancel": "Avbryt",
-      "clear_input_value": "Rensa",
+      "clear_input_value": "Rensa värdet",
       "clone": "Klona",
       "confirm": "Bekräfta",
       "create": "Skapa",
@@ -454,8 +467,8 @@
       "export": "Exportera",
       "list": "Lista",
       "refresh": "Uppdatera",
-      "remove_filter": "Ta bort filter",
-      "remove": "Radera",
+      "remove_filter": "Ta bort det här filtret",
+      "remove": "Ta bort",
       "save": "Spara",
       "search": "Sök",
       "show": "Visa",
@@ -477,15 +490,15 @@
     },
     "page": {
       "create": "Skapa %{name}",
-      "dashboard": "Dashboard",
+      "dashboard": "Översikt",
       "edit": "%{name} #%{id}",
       "error": "Ett fel uppstod",
       "list": "%{name}",
-      "loading": "Laddar",
-      "not_found": "Hittade inget",
+      "loading": "Läser in",
+      "not_found": "Hittades inte",
       "show": "%{name} #%{id}",
-      "empty": "Ingen %{name} ännu.",
-      "invite": "Vill du lägga till en?"
+      "empty": "%{name}: inga poster ännu.",
+      "invite": "Vill du lägga till något?"
     },
     "input": {
       "file": {
@@ -497,13 +510,13 @@
         "upload_single": "Dra och släpp en bild som ska laddas upp eller klicka för att välja en bild."
       },
       "references": {
-        "all_missing": "Hittade ingen referensdata.",
-        "many_missing": "Minst en av de associerade referenserna verkar inte längre vara tillgänglig.",
-        "single_missing": "Associerade referenser verkar inte längre vara tillgängliga."
+        "all_missing": "Kunde inte hitta referensdata.",
+        "many_missing": "Minst en av de kopplade referenserna verkar inte längre vara tillgänglig.",
+        "single_missing": "Den kopplade referensen verkar inte längre vara tillgänglig."
       },
       "password": {
-        "toggle_visible": "Dölj password",
-        "toggle_hidden": "Visa password"
+        "toggle_visible": "Dölj lösenord",
+        "toggle_hidden": "Visa lösenord"
       }
     },
     "message": {
@@ -511,16 +524,16 @@
       "are_you_sure": "Är du säker?",
       "bulk_delete_content": "Vill du verkligen ta bort %{name}? |||| Vill du verkligen ta bort dessa %{smart_count} objekt?",
       "bulk_delete_title": "Ta bort %{name} |||| Ta bort %{smart_count} %{name}",
-      "delete_content": "Vill du verkligen ta bort detta innehåll?",
+      "delete_content": "Vill du verkligen ta bort det här objektet?",
       "delete_title": "Ta bort %{name} #%{id}",
       "details": "Detaljer",
       "error": "Ett klientfel uppstod och begäran kunde inte slutföras.",
-      "invalid_form": "Formuläret är ogiltigt. Kontrollera eventuella fel",
-      "loading": "Sidan läses in, var god vänta",
+      "invalid_form": "Formuläret innehåller fel. Kontrollera uppgifterna",
+      "loading": "Sidan läses in. Vänta ett ögonblick",
       "no": "Nej",
       "not_found": "Antingen skrev du fel URL eller så följde du en ogiltig länk.",
       "yes": "Ja",
-      "unsaved_changes": "Du har osparade ändringar. Ignorera dem?"
+      "unsaved_changes": "Vissa ändringar har inte sparats. Vill du verkligen ignorera dem?"
     },
     "navigation": {
       "no_results": "Inga resultat hittades",
@@ -529,23 +542,23 @@
       "page_out_from_end": "Det finns inga fler sidor",
       "page_out_from_begin": "Det finns ingen sida före sida 1",
       "page_range_info": "%{offsetBegin}-%{offsetEnd} av %{total}",
-      "page_rows_per_page": "Antal per sida:",
+      "page_rows_per_page": "Objekt per sida:",
       "next": "Nästa",
       "prev": "Föregående",
       "skip_nav": "Hoppa till innehåll"
     },
     "notification": {
-      "updated": "Element uppdaterat |||| %{smart_count} element uppdaterade",
-      "created": "Element skapat",
-      "deleted": "Element borttaget |||| %{smart_count} element borttagna",
-      "bad_item": "Felaktigt element",
-      "item_doesnt_exist": "Element finns inte",
+      "updated": "Objekt uppdaterat |||| %{smart_count} objekt uppdaterade",
+      "created": "Objekt skapat",
+      "deleted": "Objekt borttaget |||| %{smart_count} objekt borttagna",
+      "bad_item": "Felaktigt objekt",
+      "item_doesnt_exist": "Objektet finns inte",
       "http_error": "Kommunikationsfel med servern",
-      "data_provider_error": "Fel i dataProvider. Kontrollera din konsol för mer information.",
-      "i18n_error": "Kunde inte läsa in översättningen av det valda språket",
+      "data_provider_error": "Fel i dataProvider. Kontrollera webbläsarens konsol för mer information.",
+      "i18n_error": "Kunde inte läsa in översättningarna för det valda språket",
       "canceled": "Åtgärden avbröts",
-      "logged_out": "Sessionen har avslutats, anslut på nytt.",
-      "new_version": "Det finns en ny version! Uppdatera detta fönster."
+      "logged_out": "Sessionen har avslutats. Logga in igen.",
+      "new_version": "En ny version finns tillgänglig! Ladda om det här fönstret."
     },
     "toggleFieldsMenu": {
       "columnsToDisplay": "Kolumner att visa",
@@ -556,39 +569,39 @@
   },
   "message": {
     "note": "OBSERVERA",
-    "transcodingDisabled": "Inställning för kodning via webbgränssnittet är av säkerhetsskäl ej aktiverat. Starta om servern med alternativet %{config} markerat om du vill göra ändringar (redigera eller lägga till).",
-    "transcodingEnabled": "Navidrome körs för närvarande med %{config}, vilket gör att systemkommandon kan köras från webbplattformen. Du rekommenderas av säkerhetsskäl att du stänger av den och bara slår på den när du ställer in omkodning.",
-    "songsAddedToPlaylist": "La till en låt i spellistan |||| La till %{smart_count} låtar i spellistan",
-    "noPlaylistsAvailable": "Ingen tillgänglig",
-    "delete_user_title": "Ta bort användare '%{name}'",
-    "delete_user_content": "Är du säker på att du vill ta bort denna användare (inklusive spellistor och inställningar)?",
-    "notifications_blocked": "Du har blockerat meddelanden från denna sajt in din webbläsares inställningar",
-    "notifications_not_available": "Denna webbläsare stödjer inte skrivbordsmeddelanden eller du använder inte Navidrome via https",
-    "lastfmLinkSuccess": "Last.fm är länkat och scrobbling är aktivt",
-    "lastfmLinkFailure": "Last.fm kunde inte länkas",
-    "lastfmUnlinkSuccess": "Last.fm är inte längre länkat och scrobbling är deaktiverat",
-    "lastfmUnlinkFailure": "Last.fm kunde inte avlänkas",
+    "transcodingDisabled": "Av säkerhetsskäl går det inte att ändra omkodningsinställningarna i webbgränssnittet. Starta om servern med konfigurationsalternativet %{config} för att redigera eller lägga till omkodningsinställningar.",
+    "transcodingEnabled": "Navidrome körs med %{config}. Det gör det möjligt att köra systemkommandon via omkodningsinställningarna i webbgränssnittet. Av säkerhetsskäl rekommenderar vi att alternativet är inaktiverat och bara aktiveras när omkodningen ska konfigureras.",
+    "songsAddedToPlaylist": "1 låt har lagts till i spellistan |||| %{smart_count} låtar har lagts till i spellistan",
+    "noPlaylistsAvailable": "Inga tillgängliga",
+    "delete_user_title": "Ta bort användaren '%{name}'",
+    "delete_user_content": "Är du säker på att du vill ta bort den här användaren och alla användarens data, inklusive spellistor och inställningar?",
+    "notifications_blocked": "Du har blockerat aviseringar från den här webbplatsen i webbläsarens inställningar",
+    "notifications_not_available": "Webbläsaren stöder inte skrivbordsaviseringar, eller så ansluter du inte till Navidrome via HTTPS",
+    "lastfmLinkSuccess": "Last.fm har kopplats och scrobbling har aktiverats",
+    "lastfmLinkFailure": "Det gick inte att koppla Last.fm",
+    "lastfmUnlinkSuccess": "Kopplingen till Last.fm har tagits bort och scrobbling har inaktiverats",
+    "lastfmUnlinkFailure": "Det gick inte att ta bort kopplingen till Last.fm",
     "openIn": {
       "lastfm": "Öppna i Last.fm",
       "musicbrainz": "Öppna i MusicBrainz"
     },
     "lastfmLink": "Läs mer...",
-    "listenBrainzLinkSuccess": "ListenBrainz är länkat och scrobbling är aktivt som användare: %{user}",
-    "listenBrainzLinkFailure": "ListenBrainz kunde inte länkas: %{error}",
-    "listenBrainzUnlinkSuccess": "ListenBrainz är inte längre länkat och scrobbling är deaktiverat",
-    "listenBrainzUnlinkFailure": "ListenBrainz kunde inte avlänkas",
+    "listenBrainzLinkSuccess": "ListenBrainz har kopplats och scrobbling har aktiverats för användaren: %{user}",
+    "listenBrainzLinkFailure": "Det gick inte att koppla ListenBrainz: %{error}",
+    "listenBrainzUnlinkSuccess": "Kopplingen till ListenBrainz har tagits bort och scrobbling har inaktiverats",
+    "listenBrainzUnlinkFailure": "Det gick inte att ta bort kopplingen till ListenBrainz",
     "downloadOriginalFormat": "Ladda ner i originalformat",
     "shareOriginalFormat": "Dela i originalformat",
     "shareDialogTitle": "Dela %{resource} '%{name}'",
-    "shareBatchDialogTitle": "Dela en %{resource} |||| Dela %{smart_count} %{resource}",
-    "shareSuccess": "URL kopierades till urklipp: %{url}",
-    "shareFailure": "Fel vid kopiering av URL %{url} till urklipp",
+    "shareBatchDialogTitle": "Dela 1 %{resource} |||| Dela %{smart_count} %{resource}",
+    "shareSuccess": "URL:en har kopierats till urklipp: %{url}",
+    "shareFailure": "Kunde inte kopiera URL:en %{url} till urklipp",
     "downloadDialogTitle": "Ladda ner %{resource} '%{name}' (%{size})",
     "shareCopyToClipboard": "Kopiera till urklipp: Ctrl+C, Enter",
     "remove_missing_title": "Ta bort saknade filer",
-    "remove_missing_content": "Är du säker på att du vill ta bort de valda saknade filerna från databasen? Detta kommer permanent radera alla referenser till dem, inklusive antal spelningar och betyg.",
+    "remove_missing_content": "Är du säker på att du vill ta bort de valda saknade filerna från databasen? Alla referenser till dem, inklusive antal spelningar och betyg, tas bort permanent.",
     "remove_all_missing_title": "Ta bort alla saknade filer",
-    "remove_all_missing_content": "Är du säker på att du vill ta bort alla saknade filer från databasen? Detta kommer permanent radera alla referenser till dem, inklusive antal spelningar och betyg.",
+    "remove_all_missing_content": "Är du säker på att du vill ta bort alla saknade filer från databasen? Alla referenser till dem, inklusive antal spelningar och betyg, tas bort permanent.",
     "noSimilarSongsFound": "Hittade inga liknande låtar",
     "noTopSongsFound": "Hittade inga topplåtar",
     "startingInstantMix": "Laddar direktmix...",
@@ -597,7 +610,11 @@
     "coverUploaded": "Omslagsbild uppdaterad",
     "coverRemoved": "Omslagsbild borttagen",
     "coverUploadError": "Fel vid uppladdning av omslagsbild",
-    "coverRemoveError": "Fel vid borttagning av omslagsbild"
+    "coverRemoveError": "Fel vid borttagning av omslagsbild",
+    "metadataRefreshStarted": "Metadata uppdateras i bakgrunden",
+    "quickConnectApproved": "%{app} på %{device} är nu inloggad",
+    "quickConnectInvalidCode": "Koden är ogiltig eller har gått ut",
+    "quickConnectError": "Kunde inte godkänna koden"
   },
   "menu": {
     "library": "Bibliotek",
@@ -610,17 +627,17 @@
         "theme": "Tema",
         "language": "Språk",
         "defaultView": "Standardvy",
-        "desktop_notifications": "Skrivbordsmeddelanden",
+        "desktop_notifications": "Skrivbordsaviseringar",
         "lastfmScrobbling": "Scrobbla till Last.fm",
         "listenBrainzScrobbling": "Scrobbla till ListenBrainz",
         "replaygain": "ReplayGain-läge",
-        "preAmp": "ReplayGain PreAmp (dB)",
+        "preAmp": "Förförstärkning för ReplayGain (dB)",
         "gain": {
           "none": "Inaktiverad",
-          "album": "Använd gain för album",
-          "track": "Använd gain für låtar"
+          "album": "Använd albumets volymjustering",
+          "track": "Använd låtens volymjustering"
         },
-        "lastfmNotConfigured": "Last.fm API-nyckel är inte konfigurerad"
+        "lastfmNotConfigured": "API-nyckeln för Last.fm är inte konfigurerad"
       }
     },
     "albumList": "Album",
@@ -632,10 +649,19 @@
       "multipleLibraries": "%{selected} av %{total} bibliotek",
       "selectLibraries": "Välj bibliotek",
       "none": "Inga"
-    }
+    },
+    "quickConnect": {
+      "name": "Snabbanslutning",
+      "code": "Kod",
+      "help": "Ange koden som visas i en Jellyfin-app för att logga in på ditt konto i appen",
+      "confirm": "Vill du logga in med ditt konto i %{app} %{version} på %{device}?",
+      "continue": "Fortsätt",
+      "approve": "Godkänn"
+    },
+    "onlyFavourites": "Visa endast favoriter"
   },
   "player": {
-    "playListsText": "Spela kön",
+    "playListsText": "Uppspelningskö",
     "openText": "Öppna",
     "closeText": "Stäng",
     "notContentText": "Ingen musik",
@@ -645,26 +671,26 @@
     "previousTrackText": "Föregående låt",
     "reloadText": "Ladda om",
     "volumeText": "Volym",
-    "toggleLyricText": "Låttext av/på",
+    "toggleLyricText": "Visa eller dölj låttexten",
     "toggleMiniModeText": "Minimera",
-    "destroyText": "Radera",
+    "destroyText": "Stäng spelaren och rensa kön",
     "downloadText": "Ladda ner",
-    "removeAudioListsText": "Ta bort audiolistor",
+    "removeAudioListsText": "Rensa kön",
     "clickToDeleteText": "Klicka för att ta bort %{name}",
     "emptyLyricText": "Ingen låttext",
     "playModeText": {
       "order": "I ordningsföljd",
-      "orderLoop": "Upprepa",
-      "singleLoop": "Upprepa en",
-      "shufflePlay": "Shuffle"
+      "orderLoop": "Upprepa alla",
+      "singleLoop": "Upprepa en låt",
+      "shufflePlay": "Blanda"
     }
   },
   "about": {
     "links": {
-      "homepage": "Hemsida",
+      "homepage": "Webbplats",
       "source": "Källkod",
-      "featureRequests": "Funktionalitetförfrågan",
-      "lastInsightsCollection": "Senaste Insights-kollektion",
+      "featureRequests": "Förslag på nya funktioner",
+      "lastInsightsCollection": "Senaste insamling av användningsdata",
       "insights": {
         "disabled": "Inaktiverad",
         "waiting": "Väntar"
@@ -672,16 +698,16 @@
     },
     "tabs": {
       "about": "Om",
-      "config": "Inställningar"
+      "config": "Konfiguration"
     },
     "config": {
-      "configName": "Inställningsnamn",
+      "configName": "Inställning",
       "environmentVariable": "Miljövariabel",
-      "currentValue": "Nuvarande värde",
-      "configurationFile": "Inställningsfil",
-      "exportToml": "Exportera inställningar (TOML)",
-      "exportSuccess": "Inställningarna kopierade till urklippet i TOML-format",
-      "exportFailed": "Kopiering av inställningarna misslyckades",
+      "currentValue": "Aktuellt värde",
+      "configurationFile": "Konfigurationsfil",
+      "exportToml": "Exportera konfiguration (TOML)",
+      "exportSuccess": "Konfigurationen har kopierats till urklipp i TOML-format",
+      "exportFailed": "Kunde inte kopiera konfigurationen",
       "devFlagsHeader": "Utvecklingsflaggor (kan ändras eller tas bort)",
       "devFlagsComment": "Dessa inställningar är experimentella och kan tas bort i framtida versioner",
       "downloadToml": "Ladda ner konfiguration (TOML)"
@@ -689,28 +715,28 @@
   },
   "activity": {
     "title": "Aktivitet",
-    "totalScanned": "Genomsökta mappar",
-    "quickScan": "Snabbscan",
-    "fullScan": "Komplett scan",
-    "serverUptime": "Serverdrifttid",
+    "totalScanned": "Skannade mappar totalt",
+    "quickScan": "Snabb",
+    "fullScan": "Fullständig",
+    "serverUptime": "Serverns drifttid",
     "serverDown": "OFFLINE",
-    "scanType": "Typ",
-    "status": "Fel vid scanning",
-    "elapsedTime": "Spelad tid",
-    "selectiveScan": "Urval"
+    "scanType": "Senaste skanning",
+    "status": "Skanningsfel",
+    "elapsedTime": "Förfluten tid",
+    "selectiveScan": "Selektiv"
   },
   "help": {
-    "title": "Navidrome kortkommandon",
+    "title": "Kortkommandon i Navidrome",
     "hotkeys": {
       "show_help": "Visa denna hjälp",
-      "toggle_menu": "Växla sidomeny",
+      "toggle_menu": "Visa eller dölj sidomenyn",
       "toggle_play": "Spela / pausa",
       "prev_song": "Föregående låt",
       "next_song": "Nästa låt",
-      "vol_up": "Volym upp",
-      "vol_down": "Volym ner",
-      "toggle_love": "Lägg till låt i favoriter",
-      "current_song": "Hoppa till nuvarande låt"
+      "vol_up": "Höj volymen",
+      "vol_down": "Sänk volymen",
+      "toggle_love": "Lägg till låten i favoriter",
+      "current_song": "Gå till aktuell låt"
     }
   },
   "nowPlaying": {
@@ -718,4 +744,4 @@
     "empty": "Inget spelas",
     "minutesAgo": "%{smart_count} minut sedan |||| %{smart_count} minuter sedan"
   }
-}
\ No newline at end of file
+}

From a5334ee46b9cbfc5fe3191c5ce9262117f543307 Mon Sep 17 00:00:00 2001
From: strecke <35091155+strecke@users.noreply.github.com>
Date: Sun, 20 Sep 2026 18:17:57 +0200
Subject: [PATCH 157/200] fix(ui): update missing German translations (#6146)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Update missing German translations

* Fix typo in idHelp message in German translation

* Update German translations to remove formal "Sie" forms

---------

Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 resources/i18n/de.json | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/resources/i18n/de.json b/resources/i18n/de.json
index 8f3df0b4d..400a2364d 100644
--- a/resources/i18n/de.json
+++ b/resources/i18n/de.json
@@ -94,7 +94,7 @@
         "download": "Herunterladen",
         "info": "Mehr Informationen",
         "share": "Freigabe erstellen",
-        "refresh": ""
+        "refresh": "Metadaten aktualisieren"
       },
       "lists": {
         "all": "Alle",
@@ -157,12 +157,12 @@
         "token": "Token",
         "lastAccessAt": "Letzter Zugriff am",
         "libraries": "Bibliotheken",
-        "scrobbleFilter": ""
+        "scrobbleFilter": "Scrobble-Filter"
       },
       "helperTexts": {
         "name": "Die Änderung wird erst nach dem nächsten Login gültig",
         "libraries": "Wähle spezifische Bibliotheken für diesen Benutzer, oder leer lassen für Standard Bibliotheken",
-        "scrobbleFilter": ""
+        "scrobbleFilter": "Titel, die diesen Regeln für intelligente Wiedergabelisten entsprechen, werden nicht an Last.fm, ListenBrainz oder Scrobbler-Plugins übermittelt. Es werden dieselbe JSON-Syntax und dasselbe Verhalten wie bei intelligenten Wiedergabelisten verwendet. Beispiel: {\"all\":[{\"lt\":{\"rating\":4}}]}. Ist das Feld leer, wird alles gescrobbelt. Lokale Wiedergabezahlen bleiben davon unberührt."
       },
       "notifications": {
         "created": "Benutzer erstellt",
@@ -177,7 +177,7 @@
       },
       "validation": {
         "librariesRequired": "Mindestens eine Bibliothek muss für nicht-administrator Benutzer ausgewählt sein",
-        "invalidScrobbleFilter": ""
+        "invalidScrobbleFilter": "Es müssen gültige Regeln für intelligente Wiedergabelisten sein. Limit, Offset und Aktualisierungsverzögerung werden nicht unterstützt."
       }
     },
     "player": {
@@ -202,7 +202,7 @@
         "command": "Befehl"
       },
       "choices": {
-        "noDefaultBitRate": ""
+        "noDefaultBitRate": "Keine"
       }
     },
     "playlist": {
@@ -398,6 +398,7 @@
         "invalidJson": "Konfiguration muss valides JSON sein"
       },
       "messages": {
+        "idHelp": "Die Plugin-ID, abgeleitet vom Dateinamen. Verwende diese, um in Konfigurationen (z. B. bei Agents) auf dieses Plugin zu verweisen.",
         "configHelp": "Plugin mit Schlüssel-Werte Paaren konfigurieren. Leer lassen wenn das Plugin keine Konfiguration benötigt.",
         "clickPermissions": "Berechtigung anklicken für mehr Details",
         "noConfig": "Keine Konfiguration gesetzt",
@@ -411,8 +412,7 @@
         "requiredHosts": "Benötigte Hosts",
         "configValidationError": "Validierung der Konfiguration fehlgeschlagen:",
         "schemaRenderError": "Rendern der Konfiguration fehlgeschlagen. Das Schema das Plugins ist eventuell nicht korrekt.",
-        "allowWriteAccessHelp": "Wenn aktiviert, kann das Plugin Dateien in den Bibliotheken verändern. Als Standard haben Plugins nur Lesezugriff.",
-        "idHelp": ""
+        "allowWriteAccessHelp": "Wenn aktiviert, kann das Plugin Dateien in den Bibliotheken verändern. Als Standard haben Plugins nur Lesezugriff."
       },
       "placeholders": {
         "configKey": "Schlüssel",
@@ -573,7 +573,7 @@
     "noPlaylistsAvailable": "Keine Wiedergabeliste verfügbar",
     "delete_user_title": "Benutzer '%{name}' löschen",
     "delete_user_content": "Möchtest du diesen Benutzer und alle seine Daten (einschließlich Wiedergabelisten und Einstellungen) wirklich löschen?",
-    "notifications_blocked": "Sie haben Benachrichtigungen für diese Seite in den Einstellungen Ihres Browsers blockiert",
+    "notifications_blocked": "Benachrichtigungen für diese Seite sind in den Browsereinstellungen blockiert",
     "notifications_not_available": "Dieser Browser unterstützt keine Desktop-Benachrichtigungen",
     "lastfmLinkSuccess": "Last.fm Verbindung hergestellt und scrobbling aktiviert",
     "lastfmLinkFailure": "Last.fm konnte nicht verbunden werden",
@@ -609,7 +609,7 @@
     "coverRemoved": "Cover entfernt",
     "coverUploadError": "Fehler beim Hochladen des Covers",
     "coverRemoveError": "Fehler beim Entfernen des Covers",
-    "metadataRefreshStarted": ""
+    "metadataRefreshStarted": "Aktualisiert Metadaten im Hintergrund"
   },
   "menu": {
     "library": "Bibliothek",
@@ -731,4 +731,4 @@
     "empty": "Keine Wiedergabe",
     "minutesAgo": "Vor %{smart_count} Minute |||| Vor %{smart_count} Minuten"
   }
-}
\ No newline at end of file
+}

From 8e784b6af7baa7ccfcfaf56edaecf56d598ad045 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 20 Sep 2026 12:37:18 -0400
Subject: [PATCH 158/200] fix: apply the per-user library filter to bookmarks,
 playlists and now-playing (#6179)

On a multi-library instance, a few reads and writes built their own queries
without the per-user library filter that every other media read applies. A
user granted only some libraries could see, and store, tracks from libraries
they had no access to.

- getBookmarks now filters the query. It has to be the query and not the
  result: the loop below it pre-sizes the response from the bookmark count,
  so a row dropped afterwards would emit an empty bookmark entry.
- createBookmark rejects an id the caller cannot read, returning error 70 to
  match getSong. Stored rows are left alone rather than purged, so a
  temporary revoke does not lose saved playback positions.
- playlistTrackRepository Read, Count and GetAlbumIDs get the filter their
  siblings CountAll and GetMediaFileIDs already had. Read is the one that
  mattered most: its id is the integer playlist position, so it needed no
  track id at all.
- Playlist track writes are filtered in playlistRepository.addTracks, the
  only writer of playlist_tracks rows apart from smart playlists, so Add,
  Insert, AddAlbums/AddArtists/AddDiscs and a full replace through Put all
  go through it. Insert reserves a slot per requested id, so when the filter
  drops one it renumbers to close the hole.
- playTracker.GetNowPlaying honours its context instead of discarding it.
  The cache is process-global, so the filter belongs in the tracker rather
  than in the Subsonic handler, and any future caller inherits it.

Admins and single-library installs are unaffected: applyLibraryFilter and
HasLibraryAccess both short-circuit for them. Scanner playlist sync runs as
admin, and M3U and CLI imports already resolve tracks through FindByPaths as
the same user, so neither changes.
---
 core/scrobbler/play_tracker.go                |   9 +-
 core/scrobbler/play_tracker_test.go           |  43 ++++-
 persistence/persistence_suite_test.go         |  22 +++
 persistence/playlist_repository.go            |  42 ++++-
 persistence/playlist_track_repository.go      |  16 +-
 persistence/playlist_track_repository_test.go | 149 ++++++++++++++++++
 persistence/sql_bookmarks.go                  |   1 +
 persistence/sql_bookmarks_test.go             |  48 ++++++
 server/subsonic/bookmarks.go                  |   8 +
 server/subsonic/bookmarks_test.go             |  48 ++++++
 .../e2e/subsonic_multilibrary_test.go         |  18 +++
 tests/mock_mediafile_repo.go                  |   9 ++
 12 files changed, 401 insertions(+), 12 deletions(-)
 create mode 100644 server/subsonic/bookmarks_test.go

diff --git a/core/scrobbler/play_tracker.go b/core/scrobbler/play_tracker.go
index 63397f8f6..e68fcd942 100644
--- a/core/scrobbler/play_tracker.go
+++ b/core/scrobbler/play_tracker.go
@@ -17,6 +17,7 @@ import (
 	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/utils/cache"
 	"github.com/navidrome/navidrome/utils/singleton"
+	"github.com/navidrome/navidrome/utils/slice"
 )
 
 const (
@@ -444,8 +445,14 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 	return nil
 }
 
-func (p *playTracker) GetNowPlaying(_ context.Context) ([]PlaybackSession, error) {
+func (p *playTracker) GetNowPlaying(ctx context.Context) ([]PlaybackSession, error) {
+	// The cache is process-global, so it holds every user's playback, across all libraries.
 	res := p.playMap.Values()
+	if user, ok := request.UserFrom(ctx); ok {
+		res = slice.Filter(res, func(s PlaybackSession) bool {
+			return user.HasLibraryAccess(s.MediaFile.LibraryID)
+		})
+	}
 	slices.SortFunc(res, func(a, b PlaybackSession) int {
 		return b.Start.Compare(a.Start)
 	})
diff --git a/core/scrobbler/play_tracker_test.go b/core/scrobbler/play_tracker_test.go
index 0e768c3f4..d79233e15 100644
--- a/core/scrobbler/play_tracker_test.go
+++ b/core/scrobbler/play_tracker_test.go
@@ -92,7 +92,7 @@ var _ = Describe("PlayTracker", func() {
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		ctx = GinkgoT().Context()
-		ctx = request.WithUser(ctx, model.User{ID: "u-1"})
+		ctx = request.WithUser(ctx, model.User{ID: "u-1", Libraries: model.Libraries{{ID: 1}}})
 		ctx = request.WithPlayer(ctx, model.Player{ScrobbleEnabled: true})
 		ds = &tests.MockDataStore{}
 		fake = &fakeScrobbler{Authorized: true}
@@ -108,6 +108,7 @@ var _ = Describe("PlayTracker", func() {
 
 		track = model.MediaFile{
 			ID:             "123",
+			LibraryID:      1,
 			Title:          "Track Title",
 			Album:          "Track Album",
 			AlbumID:        "al-1",
@@ -174,6 +175,46 @@ var _ = Describe("PlayTracker", func() {
 			Expect(playing[1].Username).To(Equal("user-1"))
 			Expect(playing[1].MediaFile.ID).To(Equal("123"))
 		})
+
+		It("hides sessions playing from libraries the caller cannot access", func() {
+			hidden := track
+			hidden.ID = "789"
+			hidden.LibraryID = 2
+			_ = ds.MediaFile(ctx).Put(&hidden)
+			reporter := request.WithPlayer(
+				request.WithUser(GinkgoT().Context(), model.User{ID: "u-2", UserName: "user-2"}),
+				model.Player{ScrobbleEnabled: true},
+			)
+			_ = tracker.ReportPlayback(reporter, ReportPlaybackParams{
+				MediaId: "789", PositionMs: 0, State: StatePlaying, PlaybackRate: 1.0, ClientId: "player-2", ClientName: "player-two",
+			})
+
+			playing, err := tracker.GetNowPlaying(ctx)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing).To(BeEmpty(), "u-1 is granted library 1 only")
+		})
+
+		It("shows every session to an admin", func() {
+			hidden := track
+			hidden.ID = "789"
+			hidden.LibraryID = 2
+			_ = ds.MediaFile(ctx).Put(&hidden)
+			reporter := request.WithPlayer(
+				request.WithUser(GinkgoT().Context(), model.User{ID: "u-2", UserName: "user-2"}),
+				model.Player{ScrobbleEnabled: true},
+			)
+			_ = tracker.ReportPlayback(reporter, ReportPlaybackParams{
+				MediaId: "789", PositionMs: 0, State: StatePlaying, PlaybackRate: 1.0, ClientId: "player-2", ClientName: "player-two",
+			})
+
+			adminCtx := request.WithUser(GinkgoT().Context(), model.User{ID: "adm", IsAdmin: true})
+			playing, err := tracker.GetNowPlaying(adminCtx)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(playing).To(HaveLen(1))
+			Expect(playing[0].MediaFile.ID).To(Equal("789"))
+		})
 	})
 
 	Describe("Expiration events", func() {
diff --git a/persistence/persistence_suite_test.go b/persistence/persistence_suite_test.go
index f146cb06b..644284c0b 100644
--- a/persistence/persistence_suite_test.go
+++ b/persistence/persistence_suite_test.go
@@ -169,6 +169,28 @@ func p(path string) string {
 	return filepath.FromSlash(path)
 }
 
+// restrictedFixture creates a second library plus a non-admin user granted library 1 only, so
+// specs can assert that a query filters by library. Cleans itself up after the spec.
+func restrictedFixture(name string) (context.Context, model.Library, model.User) {
+	adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
+	db := GetDBXBuilder()
+
+	lib := model.Library{Name: name + " Library", Path: "/" + name}
+	lr := NewLibraryRepository(adminCtx, db)
+	Expect(lr.Put(&lib)).To(Succeed())
+
+	user := createUserWithLibraries(name+"-restricted", []int{1})
+	ur := NewUserRepository(adminCtx, db)
+	Expect(ur.Put(&user)).To(Succeed())
+	Expect(ur.SetUserLibraries(user.ID, []int{1})).To(Succeed())
+
+	DeferCleanup(func() {
+		_ = NewUserRepository(adminCtx, db).Delete(user.ID)
+		_ = NewLibraryRepository(adminCtx, db).(*libraryRepository).delete(squirrel.Eq{"id": lib.ID})
+	})
+	return adminCtx, lib, user
+}
+
 var _ = BeforeSuite(func() {
 	conn := GetDBXBuilder()
 	ctx := log.NewContext(context.TODO())
diff --git a/persistence/playlist_repository.go b/persistence/playlist_repository.go
index cd3e48d18..2afef9f45 100644
--- a/persistence/playlist_repository.go
+++ b/persistence/playlist_repository.go
@@ -13,6 +13,7 @@ import (
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/pocketbase/dbx"
 )
 
@@ -276,10 +277,17 @@ func (r *playlistRepository) updatePlaylist(playlistId string, mediaFileIds []st
 		return err
 	}
 
-	return r.addTracks(playlistId, 1, mediaFileIds)
+	_, err = r.addTracks(playlistId, 1, mediaFileIds)
+	return err
 }
 
-func (r *playlistRepository) addTracks(playlistId string, startingPos int, mediaFileIds []string) error {
+// addTracks is the only path that writes playlist_tracks rows (smart playlists aside), so it owns
+// the library check: every caller, including a full replace through Put, goes through it.
+func (r *playlistRepository) addTracks(playlistId string, startingPos int, mediaFileIds []string) (int, error) {
+	mediaFileIds, err := r.keepAccessible(mediaFileIds)
+	if err != nil {
+		return 0, err
+	}
 	// Break the track list in chunks to avoid hitting SQLITE_MAX_VARIABLE_NUMBER limit
 	// Add new tracks, chunk by chunk
 	pos := startingPos
@@ -289,14 +297,36 @@ func (r *playlistRepository) addTracks(playlistId string, startingPos int, media
 			ins = ins.Values(playlistId, t, pos)
 			pos++
 		}
-		_, err := r.executeSQL(ins)
-		if err != nil {
-			return err
+		if _, err := r.executeSQL(ins); err != nil {
+			return 0, err
 		}
 	}
 
 	r.enqueueCoverRebuild(playlistId)
-	return r.refreshCounters(&model.Playlist{ID: playlistId})
+	return len(mediaFileIds), r.refreshCounters(&model.Playlist{ID: playlistId})
+}
+
+// keepAccessible drops ids the caller cannot read, preserving order and duplicates. Chunked
+// because callers pass unbounded id lists (M3U import), well past SQLITE_MAX_VARIABLE_NUMBER.
+func (r *playlistRepository) keepAccessible(mediaFileIds []string) ([]string, error) {
+	if visible, err := r.visibleLibraryIDs(); err == nil && r.userSeesAllLibraries(visible) {
+		return mediaFileIds, nil
+	}
+	accessible := make(map[string]struct{}, len(mediaFileIds))
+	for chunk := range slices.Chunk(slice.Unique(mediaFileIds), 200) {
+		sq := r.applyLibraryFilter(Select("id").From("media_file").Where(Eq{"id": chunk}), "media_file")
+		var found []string
+		if err := r.queryAllSlice(sq, &found); err != nil {
+			return nil, err
+		}
+		for _, id := range found {
+			accessible[id] = struct{}{}
+		}
+	}
+	return slice.Filter(mediaFileIds, func(id string) bool {
+		_, ok := accessible[id]
+		return ok
+	}), nil
 }
 
 // refreshCounters updates total playlist duration, size and count
diff --git a/persistence/playlist_track_repository.go b/persistence/playlist_track_repository.go
index 847316868..848b67be0 100644
--- a/persistence/playlist_track_repository.go
+++ b/persistence/playlist_track_repository.go
@@ -91,6 +91,7 @@ func (r *playlistTrackRepository) Count(options ...rest.QueryOptions) (int64, er
 	query := Select().
 		LeftJoin("media_file f on f.id = media_file_id").
 		Where(Eq{"playlist_id": r.playlistId})
+	query = r.applyLibraryFilter(query, "f")
 	return r.count(query, r.parseRestOptions(r.ctx, options...))
 }
 
@@ -113,6 +114,7 @@ func (r *playlistTrackRepository) Read(id string) (any, error) {
 		).
 		Join("media_file f on f.id = media_file_id").
 		Where(And{Eq{"playlist_id": r.playlistId}, Eq{"playlist_tracks.id": id}})
+	sel = r.applyLibraryFilter(sel, "f")
 	var trk dbPlaylistTrack
 	err := r.queryOne(sel, &trk)
 	return trk.PlaylistTrack, err
@@ -157,6 +159,7 @@ func (r *playlistTrackRepository) GetAlbumIDs(options ...model.QueryOptions) ([]
 	query := r.newSelect(options...).Columns("distinct mf.album_id").
 		Join("media_file mf on mf.id = media_file_id").
 		Where(Eq{"playlist_id": r.playlistId})
+	query = r.applyLibraryFilter(query, "mf")
 	var ids []string
 	err := r.queryAllSlice(query, &ids)
 	if err != nil {
@@ -187,12 +190,11 @@ func (r *playlistTrackRepository) Add(mediaFileIds []string) (int, error) {
 	// Get next pos (ID) in playlist
 	sq := r.newSelect().Columns("max(id) as max").Where(Eq{"playlist_id": r.playlistId})
 	var res struct{ Max sql.NullInt32 }
-	err := r.queryOne(sq, &res)
-	if err != nil {
+	if err := r.queryOne(sq, &res); err != nil {
 		return 0, err
 	}
 
-	return len(mediaFileIds), r.playlistRepo.addTracks(r.playlistId, int(res.Max.Int32+1), mediaFileIds)
+	return r.playlistRepo.addTracks(r.playlistId, int(res.Max.Int32+1), mediaFileIds)
 }
 
 // Insert adds tracks before the 1-based position pos, shifting the following entries down; a
@@ -215,7 +217,13 @@ func (r *playlistTrackRepository) Insert(mediaFileIds []string, pos int) (int, e
 	if res == 0 {
 		return r.Add(mediaFileIds)
 	}
-	return n, r.playlistRepo.addTracks(r.playlistId, pos, mediaFileIds)
+	inserted, err := r.playlistRepo.addTracks(r.playlistId, pos, mediaFileIds)
+	if err != nil || inserted == n {
+		return inserted, err
+	}
+	// The shift above reserved a slot per requested id, so ids dropped by the library filter
+	// leave a hole. Close it.
+	return inserted, r.playlistRepo.renumber(r.playlistId)
 }
 
 func (r *playlistTrackRepository) addMediaFileIds(cond Sqlizer) (int, error) {
diff --git a/persistence/playlist_track_repository_test.go b/persistence/playlist_track_repository_test.go
index e0360adb4..1a6bc9dc6 100644
--- a/persistence/playlist_track_repository_test.go
+++ b/persistence/playlist_track_repository_test.go
@@ -1,11 +1,13 @@
 package persistence
 
 import (
+	"context"
 	"strconv"
 
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/utils/slice"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -221,4 +223,151 @@ var _ = Describe("PlaylistTrackRepository", func() {
 			Expect(tracks.CountAll()).To(BeZero())
 		})
 	})
+
+	Describe("library access", func() {
+		var otherLib model.Library
+		var restrictedUser model.User
+		var adminCtx, userCtx context.Context
+		var userTracks model.PlaylistTrackRepository
+		var plsID string
+
+		BeforeEach(func() {
+			adminCtx, otherLib, restrictedUser = restrictedFixture("pls")
+			userCtx = request.WithUser(log.NewContext(GinkgoT().Context()), restrictedUser)
+			db := GetDBXBuilder()
+
+			adminMr := NewMediaFileRepository(adminCtx, db)
+			Expect(adminMr.Put(&model.MediaFile{
+				ID: "pls-otherlib-track", LibraryID: otherLib.ID, AlbumID: "pls-hidden-album",
+				Path: "hidden/in-playlist.mp3", Title: "Hidden In Playlist",
+			})).To(Succeed())
+			DeferCleanup(func() { _ = adminMr.Delete("pls-otherlib-track") })
+
+			adminPls := NewPlaylistRepository(adminCtx, db)
+			pls := model.Playlist{Name: "Public Mixed", OwnerID: adminUser.ID, OwnerName: adminUser.UserName, Public: true}
+			Expect(adminPls.Put(&pls)).To(Succeed())
+			plsID = pls.ID
+			DeferCleanup(func() { _ = adminPls.Delete(plsID) })
+			Expect(adminPls.Tracks(plsID, false).Add([]string{songDayInALife.ID, "pls-otherlib-track"})).To(Equal(2))
+
+			userTracks = NewPlaylistRepository(userCtx, db).Tracks(plsID, false)
+		})
+
+		It("Read does not return a track outside the user's libraries", func() {
+			_, err := userTracks.Read("2")
+			Expect(err).To(MatchError(model.ErrNotFound), "position 2 holds a track the user cannot access")
+		})
+
+		It("Read still returns a track inside the user's libraries", func() {
+			trk, err := userTracks.Read("1")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(trk.(*model.PlaylistTrack).MediaFile.ID).To(Equal(songDayInALife.ID))
+		})
+
+		It("Count excludes tracks outside the user's libraries", func() {
+			Expect(userTracks.Count()).To(Equal(int64(1)), "Count must agree with the filtered listing")
+		})
+
+		It("GetAlbumIDs excludes albums outside the user's libraries", func() {
+			Expect(userTracks.GetAlbumIDs()).ToNot(ContainElement("pls-hidden-album"))
+		})
+
+		Describe("Add", func() {
+			var ownTracks model.PlaylistTrackRepository
+
+			BeforeEach(func() {
+				userPls := NewPlaylistRepository(userCtx, GetDBXBuilder())
+				own := model.Playlist{Name: "Own Playlist", OwnerID: restrictedUser.ID, OwnerName: restrictedUser.UserName}
+				Expect(userPls.Put(&own)).To(Succeed())
+				DeferCleanup(func() { _ = NewPlaylistRepository(adminCtx, GetDBXBuilder()).Delete(own.ID) })
+				ownTracks = userPls.Tracks(own.ID, false)
+			})
+
+			It("drops ids outside the user's libraries", func() {
+				Expect(ownTracks.Add([]string{songDayInALife.ID, "pls-otherlib-track"})).To(Equal(1))
+				Expect(ownTracks.GetMediaFileIDs()).To(ConsistOf(songDayInALife.ID))
+			})
+
+			It("drops them when reached through AddAlbums", func() {
+				Expect(ownTracks.AddAlbums([]string{"pls-hidden-album"})).To(BeZero())
+			})
+
+			It("drops them when reached through Insert", func() {
+				Expect(ownTracks.Add([]string{songDayInALife.ID})).To(Equal(1))
+
+				Expect(ownTracks.Insert([]string{"pls-otherlib-track", songComeTogether.ID}, 1)).To(Equal(1))
+
+				Expect(ownTracks.GetMediaFileIDs()).To(Equal([]string{songComeTogether.ID, songDayInALife.ID}))
+				trks, err := ownTracks.GetAll(model.QueryOptions{Sort: "id"})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(slice.Map(trks, func(t model.PlaylistTrack) string { return t.ID })).To(Equal([]string{"1", "2"}),
+					"positions must stay contiguous when an id is dropped")
+			})
+		})
+
+		Describe("Put", func() {
+			storedIDs := func(id string) []string {
+				ids, err := NewPlaylistRepository(adminCtx, GetDBXBuilder()).Tracks(id, false).GetMediaFileIDs()
+				Expect(err).ToNot(HaveOccurred())
+				return ids
+			}
+			put := func(ctx context.Context, owner model.User, pls *model.Playlist, ids ...string) string {
+				pls.OwnerID = owner.ID
+				pls.Tracks = nil
+				pls.AddMediaFilesByID(ids)
+				Expect(NewPlaylistRepository(ctx, GetDBXBuilder()).Put(pls)).To(Succeed())
+				DeferCleanup(func() { _ = NewPlaylistRepository(adminCtx, GetDBXBuilder()).Delete(pls.ID) })
+				return pls.ID
+			}
+
+			It("drops ids outside the user's libraries when creating a playlist", func() {
+				id := put(userCtx, restrictedUser, &model.Playlist{Name: "Created"}, songDayInALife.ID, "pls-otherlib-track")
+
+				Expect(storedIDs(id)).To(Equal([]string{songDayInALife.ID}))
+			})
+
+			It("drops them when replacing the tracks of an existing playlist", func() {
+				pls := &model.Playlist{Name: "Replaced"}
+				put(userCtx, restrictedUser, pls, songDayInALife.ID)
+
+				put(userCtx, restrictedUser, pls, "pls-otherlib-track")
+
+				Expect(storedIDs(pls.ID)).To(BeEmpty())
+			})
+
+			It("does not count a dropped id, so it cannot be told apart from an unknown one", func() {
+				hidden := put(userCtx, restrictedUser, &model.Playlist{Name: "Hidden"}, songDayInALife.ID, "pls-otherlib-track")
+				unknown := put(userCtx, restrictedUser, &model.Playlist{Name: "Unknown"}, songDayInALife.ID, "no-such-track")
+
+				userPls := NewPlaylistRepository(userCtx, GetDBXBuilder())
+				h, err := userPls.Get(hidden)
+				Expect(err).ToNot(HaveOccurred())
+				u, err := userPls.Get(unknown)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(h.SongCount).To(Equal(u.SongCount))
+				Expect(h.Duration).To(Equal(u.Duration))
+				Expect(h.Size).To(Equal(u.Size))
+			})
+
+			It("keeps order and duplicates of the accessible ids", func() {
+				id := put(userCtx, restrictedUser, &model.Playlist{Name: "Ordered"},
+					songDayInALife.ID, "pls-otherlib-track", songComeTogether.ID, songDayInALife.ID)
+
+				Expect(storedIDs(id)).To(Equal([]string{songDayInALife.ID, songComeTogether.ID, songDayInALife.ID}))
+			})
+
+			It("keeps every id when run as an admin, as the scanner's playlist sync does", func() {
+				id := put(adminCtx, adminUser, &model.Playlist{Name: "Synced"}, songDayInALife.ID, "pls-otherlib-track")
+
+				Expect(storedIDs(id)).To(Equal([]string{songDayInALife.ID, "pls-otherlib-track"}))
+			})
+		})
+
+		It("still shows everything to an admin", func() {
+			adminTracks := NewPlaylistRepository(adminCtx, GetDBXBuilder()).Tracks(plsID, false)
+			Expect(adminTracks.Count()).To(Equal(int64(2)))
+			_, err := adminTracks.Read("2")
+			Expect(err).ToNot(HaveOccurred())
+		})
+	})
 })
diff --git a/persistence/sql_bookmarks.go b/persistence/sql_bookmarks.go
index a9f53430d..cff57dc9d 100644
--- a/persistence/sql_bookmarks.go
+++ b/persistence/sql_bookmarks.go
@@ -103,6 +103,7 @@ func (r sqlRepository) GetBookmarks() (model.Bookmarks, error) {
 	sq := r.newSelect().Columns(r.tableName + ".*")
 	sq = r.withAnnotation(sq, idField)
 	sq = r.withBookmark(sq, idField).Where(NotEq{bookmarkTable + ".item_id": nil})
+	sq = r.applyLibraryFilter(sq)
 	var mfs dbMediaFiles // TODO Decouple from media_file
 	err := r.queryAll(sq, &mfs)
 	if err != nil {
diff --git a/persistence/sql_bookmarks_test.go b/persistence/sql_bookmarks_test.go
index 712a928db..ae01a0e35 100644
--- a/persistence/sql_bookmarks_test.go
+++ b/persistence/sql_bookmarks_test.go
@@ -71,4 +71,52 @@ var _ = Describe("sqlBookmarks", func() {
 			Expect(mr.GetBookmarks()).To(BeEmpty())
 		})
 	})
+
+	Describe("library access", func() {
+		var otherLib model.Library
+		var restrictedUser model.User
+		var adminCtx context.Context
+		var userMr model.MediaFileRepository
+
+		BeforeEach(func() {
+			adminCtx, otherLib, restrictedUser = restrictedFixture("bmk")
+
+			adminMr := NewMediaFileRepository(adminCtx, GetDBXBuilder())
+			Expect(adminMr.Put(&model.MediaFile{
+				ID: "bmk-otherlib-track", LibraryID: otherLib.ID,
+				Path: "hidden/bookmarked.mp3", Title: "Hidden Bookmarked",
+			})).To(Succeed())
+			DeferCleanup(func() { _ = adminMr.Delete("bmk-otherlib-track") })
+
+			userCtx := request.WithUser(log.NewContext(GinkgoT().Context()), restrictedUser)
+			userMr = NewMediaFileRepository(userCtx, GetDBXBuilder())
+		})
+
+		It("does not return bookmarks for tracks outside the user's libraries", func() {
+			Expect(userMr.AddBookmark("bmk-otherlib-track", "sneaky", 1)).To(Succeed())
+
+			Expect(userMr.GetBookmarks()).To(BeEmpty())
+		})
+
+		It("still returns the bookmark for an admin", func() {
+			adminMr := NewMediaFileRepository(adminCtx, GetDBXBuilder())
+			Expect(adminMr.AddBookmark("bmk-otherlib-track", "mine", 1)).To(Succeed())
+			DeferCleanup(func() { _ = adminMr.DeleteBookmark("bmk-otherlib-track") })
+
+			bms, err := adminMr.GetBookmarks()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(bms).To(HaveLen(1))
+			Expect(bms[0].Item.ID).To(Equal("bmk-otherlib-track"))
+		})
+
+		It("keeps returning bookmarks for tracks inside the user's libraries", func() {
+			Expect(userMr.AddBookmark(songAntenna.ID, "allowed", 5)).To(Succeed())
+			DeferCleanup(func() { _ = userMr.DeleteBookmark(songAntenna.ID) })
+
+			bms, err := userMr.GetBookmarks()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(bms).To(HaveLen(1))
+			Expect(bms[0].Item.ID).To(Equal(songAntenna.ID))
+		})
+	})
 })
diff --git a/server/subsonic/bookmarks.go b/server/subsonic/bookmarks.go
index 4a7ebaa6c..7ac492ca8 100644
--- a/server/subsonic/bookmarks.go
+++ b/server/subsonic/bookmarks.go
@@ -47,6 +47,14 @@ func (api *Router) CreateBookmark(r *http.Request) (*responses.Subsonic, error)
 	position := p.Int64Or("position", 0)
 
 	repo := api.ds.MediaFile(r.Context())
+	ok, err := repo.Exists(id)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return nil, newError(responses.ErrorDataNotFound, "Song not found")
+	}
+
 	err = repo.AddBookmark(id, comment, position)
 	if err != nil {
 		return nil, err
diff --git a/server/subsonic/bookmarks_test.go b/server/subsonic/bookmarks_test.go
new file mode 100644
index 000000000..0fcb81ab9
--- /dev/null
+++ b/server/subsonic/bookmarks_test.go
@@ -0,0 +1,48 @@
+package subsonic
+
+import (
+	"context"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/server/subsonic/responses"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Bookmarks", func() {
+	var router *Router
+	var ds *tests.MockDataStore
+	var mfRepo *tests.MockMediaFileRepo
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ds = &tests.MockDataStore{}
+		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		ctx = request.WithUser(context.Background(), model.User{ID: "u1", UserName: "u1"})
+		mfRepo = ds.MediaFile(ctx).(*tests.MockMediaFileRepo)
+		mfRepo.SetData(model.MediaFiles{{ID: "visible"}})
+	})
+
+	Describe("CreateBookmark", func() {
+		It("rejects an id the user cannot read", func() {
+			r := newGetRequest("id=hidden", "position=1").WithContext(ctx)
+
+			_, err := router.CreateBookmark(r)
+
+			Expect(err).To(HaveOccurred())
+			Expect(mapToSubsonicError(err).code).To(Equal(responses.ErrorDataNotFound))
+			Expect(mfRepo.BookmarksAdded).To(BeEmpty())
+		})
+
+		It("accepts an id the user can read", func() {
+			r := newGetRequest("id=visible", "position=1").WithContext(ctx)
+
+			_, err := router.CreateBookmark(r)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(mfRepo.BookmarksAdded).To(ConsistOf("visible"))
+		})
+	})
+})
diff --git a/server/subsonic/e2e/subsonic_multilibrary_test.go b/server/subsonic/e2e/subsonic_multilibrary_test.go
index 98f87ca17..18e8c6391 100644
--- a/server/subsonic/e2e/subsonic_multilibrary_test.go
+++ b/server/subsonic/e2e/subsonic_multilibrary_test.go
@@ -224,6 +224,24 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 			Expect(resp.Playlist.Entry).To(HaveLen(1))
 			Expect(resp.Playlist.Entry[0].Id).To(Equal(lib1SongID))
 		})
+
+		It("non-admin user cannot store a song from another library through createPlaylist", func() {
+			resp := doReqWithUser(userLib1Only, "createPlaylist",
+				"name", "Restricted Playlist", "songId", lib1SongID, "songId", lib2SongID)
+			Expect(resp.Status).To(Equal(responses.StatusOK))
+			ownID := resp.Playlist.Id
+
+			stored := doReqWithUser(adminWithLibs, "getPlaylist", "id", ownID)
+			Expect(stored.Playlist.Entry).To(HaveLen(1), "the lib2 song must not be persisted")
+			Expect(stored.Playlist.Entry[0].Id).To(Equal(lib1SongID))
+
+			By("replacing the tracks of the same playlist")
+			resp = doReqWithUser(userLib1Only, "createPlaylist", "playlistId", ownID, "songId", lib2SongID)
+			Expect(resp.Status).To(Equal(responses.StatusOK))
+
+			stored = doReqWithUser(adminWithLibs, "getPlaylist", "id", ownID)
+			Expect(stored.Playlist.Entry).To(BeEmpty())
+		})
 	})
 
 	Describe("Cross-library shares", Ordered, func() {
diff --git a/tests/mock_mediafile_repo.go b/tests/mock_mediafile_repo.go
index a365bd2bd..2093a007d 100644
--- a/tests/mock_mediafile_repo.go
+++ b/tests/mock_mediafile_repo.go
@@ -37,6 +37,7 @@ type MockMediaFileRepo struct {
 	FindRecentFilesByPropertiesFunc func(missing model.MediaFile, since time.Time) (model.MediaFiles, error)
 	MatchesCriteriaValue            bool
 	MatchesCriteriaErr              error
+	BookmarksAdded                  []string
 }
 
 func (m *MockMediaFileRepo) SetError(err bool) {
@@ -76,6 +77,14 @@ func (m *MockMediaFileRepo) Get(id string) (*model.MediaFile, error) {
 	return nil, model.ErrNotFound
 }
 
+func (m *MockMediaFileRepo) AddBookmark(id, _ string, _ int64) error {
+	if m.Err {
+		return errors.New("error")
+	}
+	m.BookmarksAdded = append(m.BookmarksAdded, id)
+	return nil
+}
+
 func (m *MockMediaFileRepo) GetWithParticipants(id string) (*model.MediaFile, error) {
 	if m.Err {
 		return nil, errors.New("error")

From 8b4125267eda31c48c193776d8dc4653a2e5af48 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 20 Sep 2026 13:40:14 -0400
Subject: [PATCH 159/200] fix(artwork): only use image files as local artwork
 sources (#6180)

* fix(playlists): limit local cover paths to images in owner's libraries

A local #EXTALBUMARTURL path (absolute or file://) was only checked against the union of all
libraries. The artwork resolver then opened it with no further check and served the bytes as the
playlist cover, undecoded. Any user who can upload an M3U could read any file under any library
root, including libraries they were not granted, through getCoverArt (GHSA-vwq6-xrw5-phpg).

resolveImageURL now requires an image extension, and for uploaded playlists (no folder) the
library holding the cover must pass the owner's HasLibraryAccess. Scanner and CLI imports keep
the all-libraries check, since those files are admin-controlled.

resolveLocalFile, used by every file-backed artwork source, now ignores paths without an image
extension, which covers playlists stored before this fix that were not resolved yet. openOriginal
refuses a stored file-backed row whose path is not an image, so the existing dangling path
re-resolves it and the playlist falls back to the generated grid. No migration is needed.

* fix(artwork): skip non-image files matched by folder cover patterns

Album and disc folder sources opened any file in the folder's image list that matched a
cover pattern, without checking its extension. openOriginal now refuses to serve file-backed
rows whose path is not an image, so a stored row like that would be refused, re-resolved to
the same file, and refused again on every view. The list comes from the scanner, which only
records image files, but a database scanned where the OS mime table knows more image types
than the serving process could still reach this.

Both fromExternalFile variants now skip matches that are not image files, so the album falls
back to its next source instead. Also correct the parser comment: a playlist without a folder
can come from an API upload or from a CLI import of a file outside all libraries.

* fix(artwork): check stored source type before using the resize cache

The image-extension check for file-backed rows ran inside openOriginal, which the resize
cache skips on a hit. Before the fix, a resized request for a playlist pointing at a non-image
file cached the raw bytes, because a failed resize falls back to the original data. After the
upgrade the same request still hit that entry and returned the file.

serveHash now refuses a file-backed row whose path is not an image before calling serveSource,
so both full-size and resized requests go through dangling and re-resolve the item. The stale
cache entry is keyed by the old hash and is no longer reachable once the row changes.

* test: register mime_types.yaml in test binaries

Artwork resolution now skips candidates that are not image files, and model.IsImageFile answers
from the process mime table. The server registers the extra image types from
resources/mime_types.yaml through a conf hook, but a test binary only does that if it links
conf/mime, so the artwork e2e suite fell back to the host table: .jxl resolves on macOS and
Linux and does not on Windows, where the #5950 cover spec then found no source.

tests.Init now imports conf/mime for its side effect, so every suite that loads the test config
sees the same image types as the server.

* fix(artwork): drop the image-file guard from the disc art reader

The guard was added to both fromExternalFile variants, but disc artwork keeps no state row and
is never queued, so it cannot hit the refuse-and-re-resolve loop the guard exists to prevent.
The only case where it can fire is a real image whose extension this process's mime table does
not know, and there it drops a disc cover that used to work. The album variant keeps the guard,
since those resolutions are stored and re-served.
---
 core/artwork/artwork.go               |  5 +++
 core/artwork/artwork_test.go          | 47 +++++++++++++++++++++++++++
 core/artwork/resolve.go               |  2 +-
 core/artwork/resolve_test.go          | 17 ++++++++++
 core/artwork/sources.go               |  2 +-
 core/artwork/sources_internal_test.go | 12 +++++++
 core/playlists/import_test.go         | 31 ++++++++++++++++++
 core/playlists/parse_m3u.go           | 13 +++++---
 tests/init_tests.go                   |  1 +
 9 files changed, 123 insertions(+), 7 deletions(-)

diff --git a/core/artwork/artwork.go b/core/artwork/artwork.go
index 663d06d25..e27fa118e 100644
--- a/core/artwork/artwork.go
+++ b/core/artwork/artwork.go
@@ -168,6 +168,11 @@ func (s *service) serveHash(ctx context.Context, artID model.ArtworkID, ia *mode
 	if !entityExists(ctx, s.ds, artID) {
 		return nil, ErrUnavailable
 	}
+	// Checked here, not in openOriginal: a resize-cache hit never opens the source.
+	if isFileBacked(ia.Source) && !model.IsImageFile(ia.SourcePath) {
+		log.Warn(ctx, "Artwork: Stored source is not an image file, re-resolving", "artID", artID, "path", ia.SourcePath)
+		return s.dangling(ctx, artID)
+	}
 	art, err := s.ds.Artwork(ctx).GetImage(ia.Hash)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
diff --git a/core/artwork/artwork_test.go b/core/artwork/artwork_test.go
index 907b300de..8b35a872e 100644
--- a/core/artwork/artwork_test.go
+++ b/core/artwork/artwork_test.go
@@ -159,6 +159,53 @@ var _ = Describe("Artwork", func() {
 			Expect(readAll(img)).To(Equal(coverBytes))
 		})
 
+		It("treats a file-backed row pointing at a non-image file as dangling", func() {
+			dir := GinkgoT().TempDir()
+			secretPath := filepath.Join(dir, "config.ini")
+			Expect(os.WriteFile(secretPath, []byte("password=secret"), 0600)).To(Succeed())
+			Expect(artRepo.PutImage(&model.Artwork{Hash: "dddddddddddddddd", Mime: "image/jpeg"})).To(Succeed())
+			seedEntity("al", "alni")
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "alni", Hash: "dddddddddddddddd",
+				Source: "folder", SourcePath: secretPath, RefMtime: fileMtime(secretPath),
+			})).To(Succeed())
+
+			_, err := svc.Get(ctx, model.MustParseArtworkID("al-alni"), 0, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+			Expect(queueRepo.Data[primaryKey("al", "alni")].Priority).To(Equal(model.ArtworkPriorityScan))
+		})
+
+		It("refuses a non-image file-backed row even when a resized copy is already cached", func() {
+			secret := []byte("password=secret")
+			dir := GinkgoT().TempDir()
+			secretPath := filepath.Join(dir, "config.ini")
+			Expect(os.WriteFile(secretPath, secret, 0600)).To(Succeed())
+			Expect(artRepo.PutImage(&model.Artwork{Hash: "eeeeeeeeeeeeeeee", Mime: "image/jpeg"})).To(Succeed())
+			seedEntity("al", "alnic")
+			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+				ItemKind: "al", ItemID: "alnic", Hash: "eeeeeeeeeeeeeeee",
+				Source: "folder", SourcePath: secretPath, RefMtime: fileMtime(secretPath),
+			})).To(Succeed())
+
+			// Older versions cached the raw bytes when the resize failed.
+			seed := func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(secret)), nil }
+			stream, err := imgCache.Get(ctx, &resizedItem{hash: "eeeeeeeeeeeeeeee", size: 100, open: seed, ffmpeg: ffm})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(io.ReadAll(stream)).To(Equal(secret))
+			Expect(stream.Close()).To(Succeed())
+			Eventually(func(g Gomega) {
+				s, err := imgCache.Get(ctx, &resizedItem{hash: "eeeeeeeeeeeeeeee", size: 100, ffmpeg: ffm,
+					open: func() (io.ReadCloser, error) { return nil, os.ErrNotExist }})
+				g.Expect(err).ToNot(HaveOccurred())
+				g.Expect(s.Cached).To(BeTrue())
+				_ = s.Close()
+			}).Should(Succeed())
+
+			_, err = svc.Get(ctx, model.MustParseArtworkID("al-alnic"), 100, false)
+			Expect(err).To(MatchError(ErrUnavailable))
+			Expect(queueRepo.Data[primaryKey("al", "alnic")].Priority).To(Equal(model.ArtworkPriorityScan))
+		})
+
 		It("treats a full-size mtime mismatch as dangling: unavailable, re-enqueued at Scan, state untouched", func() {
 			dir := GinkgoT().TempDir()
 			imgPath := filepath.Join(dir, "cover.jpg")
diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
index e7a2d3765..f4f3ef725 100644
--- a/core/artwork/resolve.go
+++ b/core/artwork/resolve.go
@@ -572,7 +572,7 @@ func resolveArtistFolderPattern(ctx context.Context, lib libraryView, artistFold
 // resolveLocalFile opens an absolute path directly. A missing path is "no source"; any other
 // open failure says nothing about whether the image exists.
 func resolveLocalFile(path, source string) (resolution, bool) {
-	if path == "" {
+	if path == "" || !model.IsImageFile(path) {
 		return resolution{}, false
 	}
 	f, err := os.Open(path)
diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.go
index 402a11363..da144d8e2 100644
--- a/core/artwork/resolve_test.go
+++ b/core/artwork/resolve_test.go
@@ -498,6 +498,23 @@ var _ = Describe("resolveItem", func() {
 			Expect(res.refMtime).To(BeNumerically(">", 0))
 		})
 
+		It("never opens a local ExternalImageURL that is not an image file", func() {
+			folderRepo.result = nil // no grid tiles, so only the local file could produce a reader
+			dir := GinkgoT().TempDir()
+			secretPath := filepath.Join(dir, "config.ini")
+			Expect(os.WriteFile(secretPath, []byte("password=secret"), 0600)).To(Succeed())
+
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "plni", Name: "Playlist", ExternalImageURL: secretPath}})
+			plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1"}}
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plni"})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(res.reader).To(BeNil())
+			Expect(res.sourcePath).ToNot(Equal(secretPath))
+		})
+
 		It("routes ExternalImageURL through extGate and sets extError on transient failure", func() {
 			conf.Server.EnableM3UExternalAlbumArt = true
 			folderRepo.result = nil // no grid tiles, so the external failure is what surfaces
diff --git a/core/artwork/sources.go b/core/artwork/sources.go
index f2abf9da5..ae41acc48 100644
--- a/core/artwork/sources.go
+++ b/core/artwork/sources.go
@@ -37,7 +37,7 @@ func fromExternalFile(ctx context.Context, libFS fs.FS, files []string, pattern
 				log.Warn(ctx, "Artwork: Error matching cover art file to pattern", "pattern", pattern, "file", file)
 				continue
 			}
-			if !match {
+			if !match || !model.IsImageFile(name) {
 				continue
 			}
 			f, err := libFS.Open(file)
diff --git a/core/artwork/sources_internal_test.go b/core/artwork/sources_internal_test.go
index 4282575a5..5f70b1cc5 100644
--- a/core/artwork/sources_internal_test.go
+++ b/core/artwork/sources_internal_test.go
@@ -48,6 +48,18 @@ var _ = Describe("fromExternalFile", func() {
 		Expect(b).To(Equal([]byte("a")))
 		Expect(path).To(Equal("a/cover.jpg"))
 	})
+
+	It("skips a matching file that is not an image", func() {
+		fsys := fstest.MapFS{
+			"a/cover.ini": &fstest.MapFile{Data: []byte("password=secret")},
+			"a/cover.jpg": &fstest.MapFile{Data: []byte("a")},
+		}
+		f := fromExternalFile(GinkgoT().Context(), fsys, []string{"a/cover.ini", "a/cover.jpg"}, "cover.*")
+		r, path, err := f()
+		Expect(err).ToNot(HaveOccurred())
+		defer r.Close()
+		Expect(path).To(Equal("a/cover.jpg"))
+	})
 })
 
 var _ = Describe("fromTag", func() {
diff --git a/core/playlists/import_test.go b/core/playlists/import_test.go
index 445561266..a90a703d9 100644
--- a/core/playlists/import_test.go
+++ b/core/playlists/import_test.go
@@ -236,6 +236,24 @@ var _ = Describe("Playlists - Import", func() {
 				Expect(pls.ExternalImageURL).To(BeEmpty())
 			})
 
+			It("rejects #EXTALBUMARTURL pointing at a non-image file inside the library", func() {
+				tmpDir := GinkgoT().TempDir()
+				Expect(os.WriteFile(filepath.Join(tmpDir, "config.ini"), []byte("password=secret"), 0600)).To(Succeed())
+
+				m3u := "#EXTALBUMARTURL:config.ini\ntest.mp3\n"
+				plsFile := filepath.Join(tmpDir, "test.m3u")
+				Expect(os.WriteFile(plsFile, []byte(m3u), 0600)).To(Succeed())
+
+				mockLibRepo.SetData([]model.Library{{ID: 1, Path: tmpDir}})
+				ds.MockedMediaFile = &mockedMediaFileFromListRepo{data: []string{"test.mp3"}}
+				ps = playlists.NewPlaylists(ds, artwork.NewUploader(ds))
+
+				plsFolder := &model.Folder{ID: "1", LibraryID: 1, LibraryPath: tmpDir, Path: "", Name: ""}
+				pls, err := ps.ImportFromFolder(ctx, plsFolder, "test.m3u")
+				Expect(err).ToNot(HaveOccurred())
+				Expect(pls.ExternalImageURL).To(BeEmpty())
+			})
+
 			It("ignores HTTP #EXTALBUMARTURL when EnableM3UExternalAlbumArt is false", func() {
 				conf.Server.EnableM3UExternalAlbumArt = false
 
@@ -1011,6 +1029,19 @@ var _ = Describe("Playlists - Import", func() {
 			Expect(pls.ExternalImageURL).To(BeEmpty())
 		})
 
+		DescribeTable("restricts a local #EXTALBUMARTURL to the owner's libraries",
+			func(imageURL, expected string) {
+				ctx = request.WithUser(ctx, model.User{ID: "123", Libraries: model.Libraries{{ID: 1, Path: "/music"}}})
+				repo.data = []string{"tests/test.mp3"}
+				m3u := "#EXTALBUMARTURL:" + imageURL + "\n/music/tests/test.mp3\n"
+				pls, err := ps.ImportM3U(ctx, strings.NewReader(m3u))
+				Expect(err).ToNot(HaveOccurred())
+				Expect(pls.ExternalImageURL).To(Equal(expected))
+			},
+			Entry("accepts a library the owner can access", "file:///music/cover.jpg", filepath.Clean("/music/cover.jpg")),
+			Entry("ignores a library the owner cannot access", "file:///new/cover.jpg", ""),
+		)
+
 		// Fullwidth characters (e.g., ＡＢＣＤ) are not handled by SQLite's NOCASE collation,
 		// so we need exact matching for non-ASCII characters.
 		It("matches fullwidth characters exactly (SQLite NOCASE limitation)", func() {
diff --git a/core/playlists/parse_m3u.go b/core/playlists/parse_m3u.go
index 286f2e420..b9cb154cb 100644
--- a/core/playlists/parse_m3u.go
+++ b/core/playlists/parse_m3u.go
@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/utils/slice"
 	"golang.org/x/text/unicode/norm"
 )
@@ -36,7 +37,8 @@ func (s *playlists) parseM3U(ctx context.Context, pls *model.Playlist, folder *m
 				continue
 			}
 			if after, ok := strings.CutPrefix(line, "#EXTALBUMARTURL:"); ok {
-				pls.ExternalImageURL = resolveImageURL(after, folder, resolver.matcher)
+				owner, _ := request.UserFrom(ctx)
+				pls.ExternalImageURL = resolveImageURL(after, folder, resolver.matcher, owner)
 				continue
 			}
 			// Skip empty lines and extended info
@@ -286,7 +288,7 @@ func (r *pathResolver) resolvePaths(ctx context.Context, folder *model.Folder, l
 // HTTP(S) URLs are stored as-is (gated by EnableM3UExternalAlbumArt).
 // Local paths (file://, absolute, or relative) are resolved to an absolute path
 // and validated against known library boundaries via matcher.
-func resolveImageURL(value string, folder *model.Folder, matcher *libraryMatcher) string {
+func resolveImageURL(value string, folder *model.Folder, matcher *libraryMatcher, owner model.User) string {
 	value = strings.TrimSpace(value)
 	if value == "" {
 		return ""
@@ -302,12 +304,13 @@ func resolveImageURL(value string, folder *model.Folder, matcher *libraryMatcher
 
 	// Resolve to local absolute path
 	localPath, ok := resolveLocalPath(value, folder)
-	if !ok {
+	if !ok || !model.IsImageFile(localPath) {
 		return ""
 	}
 
-	// Validate path is within a known library
-	if libID, _ := matcher.findLibraryForPath(localPath); libID == 0 {
+	lib, ok := matcher.findLibrary(localPath)
+	// A playlist without a folder (API upload, or CLI import from outside all libraries) may only use the owner's libraries.
+	if !ok || (folder == nil && !owner.HasLibraryAccess(lib.ID)) {
 		return ""
 	}
 	return localPath
diff --git a/tests/init_tests.go b/tests/init_tests.go
index 902cf196d..eee4428a8 100644
--- a/tests/init_tests.go
+++ b/tests/init_tests.go
@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/navidrome/navidrome/conf"
+	_ "github.com/navidrome/navidrome/conf/mime" // registers mime_types.yaml, so tests see the same image types as the server
 	"github.com/navidrome/navidrome/log"
 )
 

From 0429fb3d40ffcc2c52d684334ad31c65f8a7e466 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 20 Sep 2026 15:27:20 -0400
Subject: [PATCH 160/200] fix(test): stop the Windows test job from failing at
 random (#6182)

* fix(persistence): don't format a nil-model row in wrapCursor

* test(plugins): assert task queue delay against the first dispatch, not consecutive gaps

* test(artwork): let the e2e worker wait outlast one retry

* chore: trim comments

* fix(persistence): guard dbFolder and dbMediaFile String() against a nil model
---
 core/artwork/e2e/e2e_suite_test.go       | 3 ++-
 persistence/folder_repository.go         | 8 ++++++++
 persistence/folder_repository_test.go    | 7 +++++++
 persistence/mediafile_repository.go      | 8 ++++++++
 persistence/mediafile_repository_test.go | 7 +++++++
 persistence/sql_base_repository.go       | 3 ++-
 plugins/host_taskqueue_test.go           | 9 +++++----
 7 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/core/artwork/e2e/e2e_suite_test.go b/core/artwork/e2e/e2e_suite_test.go
index 8881da3a6..390be14a7 100644
--- a/core/artwork/e2e/e2e_suite_test.go
+++ b/core/artwork/e2e/e2e_suite_test.go
@@ -56,7 +56,8 @@ func runWorkerUntil(ctx context.Context, worker *artwork.Worker, until func() bo
 	runCtx, cancel := context.WithCancel(ctx)
 	done := make(chan error, 1)
 	go func() { done <- worker.Run(runCtx) }()
-	Eventually(until, 5*time.Second, 10*time.Millisecond).Should(BeTrue())
+	// Long enough for one retry (3-7s backoff, 5s poll tick).
+	Eventually(until, 15*time.Second, 10*time.Millisecond).Should(BeTrue())
 	cancel()
 	Eventually(done, 2*time.Second).Should(Receive(BeNil()))
 }
diff --git a/persistence/folder_repository.go b/persistence/folder_repository.go
index a4b73d9d6..a1136ad8d 100644
--- a/persistence/folder_repository.go
+++ b/persistence/folder_repository.go
@@ -27,6 +27,14 @@ type dbFolder struct {
 	ImageFiles    string `structs:"-" json:"-"`
 }
 
+// String guards the promoted Folder.String(), which would dereference a nil Folder.
+func (f dbFolder) String() string {
+	if f.Folder == nil {
+		return "<nil>"
+	}
+	return f.Folder.String()
+}
+
 func (f *dbFolder) PostScan() error {
 	var err error
 	if f.ImageFiles != "" {
diff --git a/persistence/folder_repository_test.go b/persistence/folder_repository_test.go
index 545d8ad49..b7bc52751 100644
--- a/persistence/folder_repository_test.go
+++ b/persistence/folder_repository_test.go
@@ -310,6 +310,13 @@ var _ = Describe("FolderRepository", func() {
 		})
 	})
 
+	Describe("dbFolder.String", func() {
+		It("does not dereference a nil Folder", func() {
+			Expect(fmt.Sprint(dbFolder{})).To(Equal("<nil>"))
+			Expect(fmt.Sprint(&dbFolder{})).To(Equal("<nil>"))
+		})
+	})
+
 	Describe("wrapFolderCursor", func() {
 		It("does not panic when the cursor yields a dbFolder with nil Folder", func() {
 			// Simulate what queryWithStableResults does on the rows.Err() path:
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index 935a64bb9..835c39b1e 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -38,6 +38,14 @@ type dbMediaFile struct {
 	RgTrackPeak *float64 `structs:"-" json:"-"`
 }
 
+// String guards the promoted MediaFile.String(), which would dereference a nil MediaFile.
+func (m dbMediaFile) String() string {
+	if m.MediaFile == nil {
+		return "<nil>"
+	}
+	return m.MediaFile.String()
+}
+
 func (m *dbMediaFile) PostScan() error {
 	m.RGTrackGain = m.RgTrackGain
 	m.RGTrackPeak = m.RgTrackPeak
diff --git a/persistence/mediafile_repository_test.go b/persistence/mediafile_repository_test.go
index 1fb939415..d81b5e9ee 100644
--- a/persistence/mediafile_repository_test.go
+++ b/persistence/mediafile_repository_test.go
@@ -1203,6 +1203,13 @@ var _ = Describe("MediaRepository", func() {
 		})
 	})
 
+	Describe("dbMediaFile.String", func() {
+		It("does not dereference a nil MediaFile", func() {
+			Expect(fmt.Sprint(dbMediaFile{})).To(Equal("<nil>"))
+			Expect(fmt.Sprint(&dbMediaFile{})).To(Equal("<nil>"))
+		})
+	})
+
 	Describe("wrapMediaFileCursor", func() {
 		It("does not panic when the cursor yields a dbMediaFile with nil MediaFile", func() {
 			// Simulate what queryWithStableResults does on the rows.Err() path:
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index 9248f2a26..bc841db03 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -378,8 +378,9 @@ func wrapCursor[D, T any](cursor iter.Seq2[D, error], toModel func(D) *T) iter.S
 		for row, err := range cursor {
 			m := toModel(row)
 			if m == nil {
+				// Don't format row: its String() derefs the nil model (golang/go#81238).
 				var zero T
-				yield(zero, fmt.Errorf("unexpected nil %T (%v): %w", zero, row, err))
+				yield(zero, fmt.Errorf("unexpected nil %T: %w", zero, err))
 				return
 			}
 			if !yield(*m, err) || err != nil {
diff --git a/plugins/host_taskqueue_test.go b/plugins/host_taskqueue_test.go
index 72fb4cccd..993ddc7f6 100644
--- a/plugins/host_taskqueue_test.go
+++ b/plugins/host_taskqueue_test.go
@@ -689,11 +689,12 @@ var _ = Describe("TaskQueueService", func() {
 			copy(times, dispatchTimes)
 			mu.Unlock()
 
-			// Consecutive dispatches should have at least ~160ms gap (80% of 200ms)
+			// Wake-up latency varies per worker, so check offsets from the first dispatch, not gaps.
 			for i := 1; i < len(times); i++ {
-				gap := times[i].Sub(times[i-1])
-				Expect(gap).To(BeNumerically(">=", 160*time.Millisecond),
-					fmt.Sprintf("gap between dispatch %d and %d was %v, expected >= 160ms", i-1, i, gap))
+				offset := times[i].Sub(times[0])
+				minOffset := time.Duration(i)*200*time.Millisecond - 50*time.Millisecond
+				Expect(offset).To(BeNumerically(">=", minOffset),
+					fmt.Sprintf("dispatch %d ran %v after the first, expected >= %v", i, offset, minOffset))
 			}
 		})
 	})

From 237276efcd1e571714eff5e469eb7328b439fe69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 20 Sep 2026 20:46:46 -0400
Subject: [PATCH 161/200] fix(artwork): block private and loopback addresses in
 remote image fetches (#6181)

* fix(artwork): block private and loopback addresses in remote image fetches

fromURL fetched any URL with a plain HTTP client, and two untrusted inputs reach it. A playlist
can set #EXTALBUMARTURL to an http(s) URL, which the artwork worker later fetches when
EnableM3UExternalAlbumArt is on, so any user who can import a playlist controls the target.
Metadata agents, including WASM plugins without the http permission, return image URLs that the
core fetches too. Either path could make the server request loopback, LAN or link-local
addresses and store the response as artwork that is served back.

Add httpclient.NewExternal, which dials through a net.Dialer Control hook that rejects private,
loopback, link-local and unspecified addresses. The check runs at dial time on the resolved IP,
so DNS names, redirects and DNS rebinding are covered. fromURL now uses one shared client built
with it and treats a refused address as a definitive miss, so the item settles absent instead of
retrying and tripping the agent's circuit breaker. httpclient.New is unchanged for the other callers.

The IP classification moves from plugins to the new utils/netguard package, shared by the plugin
host client and the new constructor. The artwork test suite swaps in a client that allows
loopback so existing specs can keep using httptest servers; the fromURL specs use the production
client to assert the refusal.

* fix(httpclient): keep dialing a configured proxy in the guarded client

The guard runs on the resolved address, and with HTTP_PROXY set that address is the proxy, not
the image host. A proxy on a private address would have had every remote artwork fetch refused,
and a refusal settles the item as absent, so covers would silently disappear for those setups.

Dial the configured proxy endpoint directly and keep the guard for every other dial. A proxy
relays the request itself, so it is the operator's egress policy, the same one every other
httpclient.New caller already goes through.

* fix(httpclient): exempt only the hop that actually goes through the proxy

The exemption matched any dial to a configured proxy's address, but net/http never proxies
loopback targets, so a URL aimed at a loopback proxy was dialed directly and skipped the guard.
That let an image URL reach that one address.

Tag each request with the proxy it resolves to and exempt a dial only when it is that hop.
Redirects re-enter the RoundTripper, so every hop is tagged on its own.
---
 core/artwork/artwork_suite_test.go            | 11 +++
 core/artwork/sources.go                       | 13 +++-
 core/artwork/sources_internal_test.go         | 74 +++++++++++++++++++
 plugins/host_httpclient.go                    |  3 +-
 plugins/host_netguard.go                      |  8 +-
 utils/httpclient/httpclient.go                | 49 ++++++++++++
 .../httpclient_proxy_internal_test.go         | 68 +++++++++++++++++
 utils/httpclient/httpclient_test.go           | 31 ++++++++
 utils/netguard/netguard.go                    | 38 ++++++++++
 utils/netguard/netguard_suite_test.go         | 17 +++++
 utils/netguard/netguard_test.go               | 65 ++++++++++++++++
 11 files changed, 369 insertions(+), 8 deletions(-)
 create mode 100644 utils/httpclient/httpclient_proxy_internal_test.go
 create mode 100644 utils/netguard/netguard.go
 create mode 100644 utils/netguard/netguard_suite_test.go
 create mode 100644 utils/netguard/netguard_test.go

diff --git a/core/artwork/artwork_suite_test.go b/core/artwork/artwork_suite_test.go
index 1ea82b7fa..93aacc1fa 100644
--- a/core/artwork/artwork_suite_test.go
+++ b/core/artwork/artwork_suite_test.go
@@ -2,18 +2,21 @@ package artwork
 
 import (
 	"io/fs"
+	"net/netip"
 	"net/url"
 	"os"
 	"path/filepath"
 	"runtime"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/metadata"
 	"github.com/navidrome/navidrome/tests"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"go.uber.org/goleak"
@@ -37,6 +40,14 @@ func TestArtwork(t *testing.T) {
 	RunSpecs(t, "Artwork Suite")
 }
 
+// productionImageClient keeps the guarded client for the specs that assert it refuses loopback.
+var productionImageClient = remoteImageClient
+
+// httptest servers listen on loopback, which the production client refuses.
+var _ = BeforeSuite(func() {
+	remoteImageClient = httpclient.NewExternal(5*time.Second, netip.MustParsePrefix("127.0.0.0/8"), netip.MustParsePrefix("::1/128"))
+})
+
 // osDirFS wraps os.DirFS as a storage.MusicFS for integration tests.
 type osDirFS struct{ fs.FS }
 
diff --git a/core/artwork/sources.go b/core/artwork/sources.go
index ae41acc48..daa084c16 100644
--- a/core/artwork/sources.go
+++ b/core/artwork/sources.go
@@ -18,6 +18,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/httpclient"
+	"github.com/navidrome/navidrome/utils/netguard"
 	"go.senan.xyz/taglib"
 )
 
@@ -150,10 +151,18 @@ type readCloser struct {
 	io.Closer
 }
 
+// remoteImageClient fetches URLs from playlists and agents (plugins included), so it must not reach
+// internal hosts. Shared so fetches reuse connections.
+var remoteImageClient = httpclient.NewExternal(5 * time.Second)
+
 func fromURL(ctx context.Context, imageUrl *url.URL) (io.ReadCloser, string, error) {
-	hc := httpclient.New(5 * time.Second)
 	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, imageUrl.String(), nil)
-	resp, err := hc.Do(req) //nolint:gosec
+	resp, err := remoteImageClient.Do(req)
+	if errors.Is(err, netguard.ErrPrivateAddress) {
+		// Retrying cannot change where the URL points: settle absent instead of tripping the breaker.
+		log.Warn(ctx, "Artwork: Refused to fetch image from a private or loopback address", "url", imageUrl, err)
+		return nil, "", model.ErrNotFound
+	}
 	if err != nil {
 		return nil, "", err
 	}
diff --git a/core/artwork/sources_internal_test.go b/core/artwork/sources_internal_test.go
index 5f70b1cc5..bc81b56e7 100644
--- a/core/artwork/sources_internal_test.go
+++ b/core/artwork/sources_internal_test.go
@@ -5,13 +5,87 @@ import (
 	"errors"
 	"io"
 	"io/fs"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"net/url"
 	"os"
+	"strings"
+	"sync/atomic"
 	"testing/fstest"
+	"time"
 
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/utils/httpclient"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
+var _ = Describe("fromURL", func() {
+	var (
+		hits   atomic.Int32
+		target *httptest.Server
+	)
+
+	BeforeEach(func() {
+		hits.Store(0)
+		target = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			hits.Add(1)
+			_, _ = w.Write([]byte("image-bytes"))
+		}))
+		DeferCleanup(target.Close)
+	})
+
+	useClient := func(c *http.Client) {
+		prev := remoteImageClient
+		remoteImageClient = c
+		DeferCleanup(func() { remoteImageClient = prev })
+	}
+	fetch := func(rawURL string) ([]byte, error) {
+		u, err := url.Parse(rawURL)
+		Expect(err).ToNot(HaveOccurred())
+		r, _, err := fromURL(GinkgoT().Context(), u)
+		if err != nil {
+			return nil, err
+		}
+		defer r.Close()
+		return io.ReadAll(r)
+	}
+	// Stand-in for a public host: only 127.0.0.1 is allowed, so every other private address stays refused.
+	onlyLocalhostV4 := func() *http.Client {
+		return httpclient.NewExternal(5*time.Second, netip.MustParsePrefix("127.0.0.1/32"))
+	}
+
+	DescribeTable("refuses private and loopback targets as a definitive miss",
+		func(rawURL string) {
+			useClient(productionImageClient)
+			u, _ := url.Parse(target.URL)
+			_, err := fetch(strings.ReplaceAll(rawURL, "PORT", u.Port()))
+			Expect(err).To(MatchError(model.ErrNotFound))
+			Expect(hits.Load()).To(BeZero())
+		},
+		Entry("IPv4 loopback", "http://127.0.0.1:PORT/x"),
+		Entry("localhost", "http://localhost:PORT/x"),
+		Entry("cloud metadata", "http://169.254.169.254/"),
+		Entry("IPv6 loopback", "http://[::1]/"),
+	)
+
+	It("refuses a redirect from an allowed host to a loopback address", func() {
+		useClient(onlyLocalhostV4())
+		redirector := httptest.NewServer(http.RedirectHandler(strings.Replace(target.URL, "127.0.0.1", "127.0.0.2", 1), http.StatusFound))
+		DeferCleanup(redirector.Close)
+
+		_, err := fetch(redirector.URL)
+		Expect(err).To(MatchError(model.ErrNotFound))
+		Expect(hits.Load()).To(BeZero())
+	})
+
+	It("fetches from an allowed address", func() {
+		useClient(onlyLocalhostV4())
+		Expect(fetch(target.URL + "/cover.jpg")).To(Equal([]byte("image-bytes")))
+	})
+})
+
 var _ = Describe("fromExternalFile", func() {
 	It("opens a matching file via the library FS", func() {
 		fsys := fstest.MapFS{
diff --git a/plugins/host_httpclient.go b/plugins/host_httpclient.go
index 54875ae8a..3265ac4b7 100644
--- a/plugins/host_httpclient.go
+++ b/plugins/host_httpclient.go
@@ -16,6 +16,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/plugins/host"
 	"github.com/navidrome/navidrome/utils/httpclient"
+	"github.com/navidrome/navidrome/utils/netguard"
 )
 
 const (
@@ -201,7 +202,7 @@ func isPrivateOrLoopback(hostname string) bool {
 	if ip == nil {
 		return false
 	}
-	return isPrivateIP(ip)
+	return netguard.IsPrivateIP(ip)
 }
 
 // Verify interface implementation
diff --git a/plugins/host_netguard.go b/plugins/host_netguard.go
index 2244fed1f..f78aaf6a8 100644
--- a/plugins/host_netguard.go
+++ b/plugins/host_netguard.go
@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"net"
 	"slices"
+
+	"github.com/navidrome/navidrome/utils/netguard"
 )
 
 // checkPrivateDial runs at dial time on the resolved IP, so hostnames can't reach private addresses unless a
@@ -17,7 +19,7 @@ func checkPrivateDial(requiredHosts []string, address string) error {
 		return err
 	}
 	ip := net.ParseIP(host)
-	if ip == nil || !isPrivateIP(ip) {
+	if ip == nil || !netguard.IsPrivateIP(ip) {
 		return nil
 	}
 	for _, entry := range requiredHosts {
@@ -51,7 +53,3 @@ func ipMatchesEntry(entry string, ip net.IP) bool {
 	}
 	return false
 }
-
-func isPrivateIP(ip net.IP) bool {
-	return ip.IsLoopback() || ip.IsUnspecified() || ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()
-}
diff --git a/utils/httpclient/httpclient.go b/utils/httpclient/httpclient.go
index 7fb48f36d..b0e7b5681 100644
--- a/utils/httpclient/httpclient.go
+++ b/utils/httpclient/httpclient.go
@@ -3,10 +3,15 @@
 package httpclient
 
 import (
+	"context"
+	"net"
 	"net/http"
+	"net/netip"
+	"net/url"
 	"time"
 
 	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/utils/netguard"
 )
 
 type uaTransport struct {
@@ -33,3 +38,47 @@ func NewTransport(base http.RoundTripper) http.RoundTripper {
 func New(timeout time.Duration) *http.Client {
 	return &http.Client{Timeout: timeout, Transport: NewTransport(nil)}
 }
+
+// proxyFunc resolves the proxy for a request; tests replace it.
+var proxyFunc = http.ProxyFromEnvironment
+
+type proxyAddrKey struct{}
+
+// NewExternal is New for URLs from untrusted sources: it refuses to dial private, loopback,
+// link-local and unspecified addresses, except those covered by allowed.
+func NewExternal(timeout time.Duration, allowed ...netip.Prefix) *http.Client {
+	t := http.DefaultTransport.(*http.Transport).Clone()
+	t.Proxy = proxyFunc
+	direct := net.Dialer{Timeout: 30 * time.Second, KeepAlive: 30 * time.Second}
+	guarded := direct
+	guarded.Control = netguard.DialControl(allowed...)
+	t.DialContext = func(ctx context.Context, network, addr string) (net.Conn, error) {
+		// Exempt the hop to the proxy, which relays the request and is operator config. A URL
+		// aimed at the proxy's own address is not proxied, so it stays guarded.
+		if proxy, ok := ctx.Value(proxyAddrKey{}).(string); ok && proxy == addr {
+			return direct.DialContext(ctx, network, addr)
+		}
+		return guarded.DialContext(ctx, network, addr)
+	}
+	return &http.Client{Timeout: timeout, Transport: NewTransport(&proxyTagger{base: t})}
+}
+
+// proxyTagger records the proxy each request resolves to, so the dialer can tell a hop to the
+// proxy from a dial to the URL's own host.
+type proxyTagger struct{ base http.RoundTripper }
+
+func (p *proxyTagger) RoundTrip(req *http.Request) (*http.Response, error) {
+	if u, err := proxyFunc(req); err == nil && u != nil {
+		req = req.WithContext(context.WithValue(req.Context(), proxyAddrKey{}, proxyAddr(u)))
+	}
+	return p.base.RoundTrip(req)
+}
+
+// proxyAddr mirrors how net/http addresses a proxy connection.
+func proxyAddr(u *url.URL) string {
+	port := u.Port()
+	if port == "" {
+		port = map[string]string{"http": "80", "https": "443", "socks5": "1080", "socks5h": "1080"}[u.Scheme]
+	}
+	return net.JoinHostPort(u.Hostname(), port)
+}
diff --git a/utils/httpclient/httpclient_proxy_internal_test.go b/utils/httpclient/httpclient_proxy_internal_test.go
new file mode 100644
index 000000000..2d542d8fe
--- /dev/null
+++ b/utils/httpclient/httpclient_proxy_internal_test.go
@@ -0,0 +1,68 @@
+package httpclient
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync/atomic"
+	"time"
+
+	"github.com/navidrome/navidrome/utils/netguard"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("NewExternal with a proxy", func() {
+	var proxy *httptest.Server
+	var proxied atomic.Int32
+	var proxyURL *url.URL
+
+	BeforeEach(func() {
+		proxied.Store(0)
+		proxy = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			proxied.Add(1)
+			_, _ = w.Write([]byte("via proxy"))
+		}))
+		DeferCleanup(proxy.Close)
+		proxyURL, _ = url.Parse(proxy.URL)
+		prev := proxyFunc
+		DeferCleanup(func() { proxyFunc = prev })
+	})
+
+	It("dials the configured proxy even though it listens on a private address", func() {
+		proxyFunc = func(*http.Request) (*url.URL, error) { return proxyURL, nil }
+
+		resp, err := NewExternal(time.Second).Get("http://navidrome.example.com/cover.jpg")
+		Expect(err).ToNot(HaveOccurred())
+		defer resp.Body.Close()
+		Expect(proxied.Load()).To(Equal(int32(1)))
+	})
+
+	// net/http never proxies loopback targets, so a URL aimed at a loopback proxy is dialed directly.
+	It("refuses a direct dial to the proxy's own address when the request is not proxied", func() {
+		proxyFunc = func(r *http.Request) (*url.URL, error) {
+			if r.URL.Hostname() == "127.0.0.1" {
+				return nil, nil
+			}
+			return proxyURL, nil
+		}
+
+		_, err := NewExternal(time.Second).Get(proxy.URL + "/secret")
+		Expect(err).To(MatchError(netguard.ErrPrivateAddress))
+		Expect(proxied.Load()).To(BeZero())
+	})
+
+	It("still refuses a direct dial to a private address", func() {
+		proxyFunc = func(r *http.Request) (*url.URL, error) {
+			if r.URL.Scheme == "https" {
+				return proxyURL, nil
+			}
+			return nil, nil
+		}
+		target := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+		DeferCleanup(target.Close)
+
+		_, err := NewExternal(time.Second).Get(target.URL)
+		Expect(err).To(MatchError(netguard.ErrPrivateAddress))
+	})
+})
diff --git a/utils/httpclient/httpclient_test.go b/utils/httpclient/httpclient_test.go
index c86b51165..7b1e58797 100644
--- a/utils/httpclient/httpclient_test.go
+++ b/utils/httpclient/httpclient_test.go
@@ -3,10 +3,12 @@ package httpclient_test
 import (
 	"net/http"
 	"net/http/httptest"
+	"net/netip"
 	"time"
 
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/utils/httpclient"
+	"github.com/navidrome/navidrome/utils/netguard"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -16,6 +18,7 @@ var _ = Describe("httpclient", func() {
 	var receivedUA string
 
 	BeforeEach(func() {
+		receivedUA = ""
 		server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			receivedUA = r.Header.Get("User-Agent")
 		}))
@@ -48,6 +51,34 @@ var _ = Describe("httpclient", func() {
 		})
 	})
 
+	Describe("NewExternal", func() {
+		It("refuses to connect to a loopback server", func() {
+			c := httpclient.NewExternal(time.Second)
+			_, err := c.Get(server.URL)
+			Expect(err).To(MatchError(netguard.ErrPrivateAddress))
+			Expect(receivedUA).To(BeEmpty())
+		})
+
+		It("refuses a redirect from an allowed host to a private address", func() {
+			redirector := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				http.Redirect(w, r, "http://169.254.169.254/latest/meta-data/", http.StatusFound)
+			}))
+			DeferCleanup(redirector.Close)
+
+			c := httpclient.NewExternal(time.Second, netip.MustParsePrefix("127.0.0.1/32"))
+			_, err := c.Get(redirector.URL)
+			Expect(err).To(MatchError(netguard.ErrPrivateAddress))
+		})
+
+		It("connects to addresses covered by an allowed prefix and sets the User-Agent", func() {
+			c := httpclient.NewExternal(time.Second, netip.MustParsePrefix("127.0.0.0/8"))
+			resp, err := c.Get(server.URL)
+			Expect(err).ToNot(HaveOccurred())
+			resp.Body.Close()
+			Expect(receivedUA).To(Equal(consts.HTTPUserAgent))
+		})
+	})
+
 	Describe("NewTransport", func() {
 		It("uses the default transport when base is nil", func() {
 			c := &http.Client{Transport: httpclient.NewTransport(nil)}
diff --git a/utils/netguard/netguard.go b/utils/netguard/netguard.go
new file mode 100644
index 000000000..43d80ecc9
--- /dev/null
+++ b/utils/netguard/netguard.go
@@ -0,0 +1,38 @@
+// Package netguard keeps outbound connections driven by untrusted input away from internal addresses.
+package netguard
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"net/netip"
+	"syscall"
+)
+
+var ErrPrivateAddress = errors.New("dial to private/loopback address blocked")
+
+// IsPrivateIP reports whether ip is loopback, private, link-local or unspecified.
+func IsPrivateIP(ip net.IP) bool {
+	return ip.IsLoopback() || ip.IsUnspecified() || ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()
+}
+
+// DialControl returns a net.Dialer Control hook that rejects private addresses not covered by allowed.
+// It sees the resolved IP, so DNS names, redirects and rebinding cannot get around it.
+func DialControl(allowed ...netip.Prefix) func(network, address string, c syscall.RawConn) error {
+	return func(_, address string, _ syscall.RawConn) error {
+		ap, err := netip.ParseAddrPort(address)
+		if err != nil {
+			return fmt.Errorf("%w: unparseable address %q: %w", ErrPrivateAddress, address, err)
+		}
+		addr := ap.Addr().Unmap()
+		if !IsPrivateIP(addr.AsSlice()) {
+			return nil
+		}
+		for _, p := range allowed {
+			if p.Contains(addr) {
+				return nil
+			}
+		}
+		return fmt.Errorf("%w: %s", ErrPrivateAddress, address)
+	}
+}
diff --git a/utils/netguard/netguard_suite_test.go b/utils/netguard/netguard_suite_test.go
new file mode 100644
index 000000000..7769e0c82
--- /dev/null
+++ b/utils/netguard/netguard_suite_test.go
@@ -0,0 +1,17 @@
+package netguard_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestNetguard(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Netguard Suite")
+}
diff --git a/utils/netguard/netguard_test.go b/utils/netguard/netguard_test.go
new file mode 100644
index 000000000..733204226
--- /dev/null
+++ b/utils/netguard/netguard_test.go
@@ -0,0 +1,65 @@
+package netguard_test
+
+import (
+	"net"
+	"net/netip"
+
+	"github.com/navidrome/navidrome/utils/netguard"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("netguard", func() {
+	DescribeTable("IsPrivateIP",
+		func(addr string, expected bool) {
+			Expect(netguard.IsPrivateIP(net.ParseIP(addr))).To(Equal(expected))
+		},
+		Entry("IPv4 loopback", "127.0.0.1", true),
+		Entry("IPv4 loopback range", "127.0.0.2", true),
+		Entry("IPv6 loopback", "::1", true),
+		Entry("IPv4-mapped IPv6 loopback", "::ffff:127.0.0.1", true),
+		Entry("10.x", "10.1.2.3", true),
+		Entry("172.16.x", "172.16.0.1", true),
+		Entry("192.168.x", "192.168.1.10", true),
+		Entry("IPv6 unique local", "fd00::1", true),
+		Entry("link-local (cloud metadata)", "169.254.169.254", true),
+		Entry("IPv6 link-local", "fe80::1", true),
+		Entry("link-local multicast", "224.0.0.1", true),
+		Entry("IPv4 unspecified", "0.0.0.0", true),
+		Entry("IPv6 unspecified", "::", true),
+		Entry("public IPv4", "93.184.216.34", false),
+		Entry("172.32.x is outside the private block", "172.32.0.1", false),
+		Entry("public IPv6", "2606:4700:4700::1111", false),
+	)
+
+	Describe("DialControl", func() {
+		It("rejects private and loopback addresses", func() {
+			control := netguard.DialControl()
+			for _, addr := range []string{"127.0.0.1:80", "[::1]:443", "169.254.169.254:80", "10.0.0.1:8080", "0.0.0.0:80"} {
+				Expect(control("tcp", addr, nil)).To(MatchError(netguard.ErrPrivateAddress), addr)
+			}
+		})
+
+		It("allows public addresses", func() {
+			control := netguard.DialControl()
+			Expect(control("tcp", "93.184.216.34:443", nil)).To(Succeed())
+			Expect(control("tcp6", "[2606:4700:4700::1111]:443", nil)).To(Succeed())
+		})
+
+		It("allows private addresses covered by an allowed prefix, and only those", func() {
+			control := netguard.DialControl(netip.MustParsePrefix("127.0.0.1/32"))
+			Expect(control("tcp", "127.0.0.1:8080", nil)).To(Succeed())
+			Expect(control("tcp", "127.0.0.2:8080", nil)).To(MatchError(netguard.ErrPrivateAddress))
+		})
+
+		It("matches IPv4-mapped IPv6 addresses against IPv4 prefixes", func() {
+			control := netguard.DialControl(netip.MustParsePrefix("127.0.0.0/8"))
+			Expect(control("tcp", "[::ffff:127.0.0.1]:80", nil)).To(Succeed())
+		})
+
+		It("fails closed when the address is not an IP", func() {
+			Expect(netguard.DialControl()("tcp", "localhost:80", nil)).To(HaveOccurred())
+			Expect(netguard.DialControl()("tcp", "garbage", nil)).To(HaveOccurred())
+		})
+	})
+})

From 9e8811e4c5cfb22a73acdca840256836794d0f13 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 20 Sep 2026 21:10:41 -0400
Subject: [PATCH 162/200] fix(server): enforce player ownership on create and
 registration (#6184)

POST /api/player passed the ownership check using the userId from the request body, then
saved with the body id. When that id belonged to another user's player, the save became an
update with no owner restriction, overwriting the row and moving it to the caller. Save now
always creates a new player and ignores any id in the body; edits keep going through the
owner-scoped Update.

Player registration also reused a player by the id sent in the Subsonic player cookie or the
Jellyfin DeviceId without checking its owner, letting a user attach to another user's player
and overwrite its name, user agent and IP. Register now only reuses a player owned by the
requesting user, falling back to the user's own players otherwise.
---
 core/players.go                       |  2 +-
 core/players_test.go                  | 15 +++++++++++++--
 persistence/player_repository.go      |  2 +-
 persistence/player_repository_test.go | 21 +++++++++++++++++++++
 4 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/core/players.go b/core/players.go
index 963914514..b757f8460 100644
--- a/core/players.go
+++ b/core/players.go
@@ -38,7 +38,7 @@ func (p *players) Register(ctx context.Context, playerID, client, userAgent, ip
 	user, _ := request.UserFrom(ctx)
 	if playerID != "" {
 		plr, err = p.ds.Player(ctx).Get(playerID)
-		if err == nil && plr.Client != client {
+		if err == nil && (plr.Client != client || plr.UserId != user.ID) {
 			playerID = ""
 		}
 	}
diff --git a/core/players_test.go b/core/players_test.go
index 90c265fcc..55ec16833 100644
--- a/core/players_test.go
+++ b/core/players_test.go
@@ -61,8 +61,19 @@ var _ = Describe("Players", func() {
 			Expect(trc).To(BeNil())
 		})
 
+		It("does not reuse another user's player by ID", func() {
+			plr := &model.Player{ID: "123", Name: "A Player", Client: "client", UserId: "otheruser", UserAgent: "Pixel", TranscodingId: "1"}
+			repo.add(plr)
+			p, trc, err := players.Register(ctx, "123", "client", "chrome", "1.2.3.4")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(p.ID).ToNot(Equal("123"))
+			Expect(p.UserId).To(Equal("userid"))
+			Expect(repo.lastSaved).To(Equal(p))
+			Expect(trc).To(BeNil())
+		})
+
 		It("finds players by ID", func() {
-			plr := &model.Player{ID: "123", Name: "A Player", Client: "client", LastSeen: time.Time{}}
+			plr := &model.Player{ID: "123", Name: "A Player", Client: "client", UserId: "userid", LastSeen: time.Time{}}
 			repo.add(plr)
 			p, trc, err := players.Register(ctx, "123", "client", "chrome", "1.2.3.4")
 			Expect(err).ToNot(HaveOccurred())
@@ -93,7 +104,7 @@ var _ = Describe("Players", func() {
 		})
 
 		It("finds player by ID and return its transcoding", func() {
-			plr := &model.Player{ID: "123", Name: "A Player", Client: "client", LastSeen: time.Time{}, TranscodingId: "1"}
+			plr := &model.Player{ID: "123", Name: "A Player", Client: "client", UserId: "userid", LastSeen: time.Time{}, TranscodingId: "1"}
 			repo.add(plr)
 			p, trc, err := players.Register(ctx, "123", "client", "chrome", "1.2.3.4")
 			Expect(err).ToNot(HaveOccurred())
diff --git a/persistence/player_repository.go b/persistence/player_repository.go
index a2b079d53..a2114b060 100644
--- a/persistence/player_repository.go
+++ b/persistence/player_repository.go
@@ -126,7 +126,7 @@ func (r *playerRepository) Save(entity any) (string, error) {
 	if !r.isPermitted(t) {
 		return "", rest.ErrPermissionDenied
 	}
-	return r.put(t.ID, t)
+	return r.put("", t) // Save only creates; edits go through the owner-scoped Update
 }
 
 func (r *playerRepository) Update(id string, entity any, cols ...string) error {
diff --git a/persistence/player_repository_test.go b/persistence/player_repository_test.go
index b7085a1fb..4a7701ac2 100644
--- a/persistence/player_repository_test.go
+++ b/persistence/player_repository_test.go
@@ -288,6 +288,27 @@ var _ = Describe("PlayerRepository", func() {
 			Expect(*stored).To(Equal(adminPlayer1))
 		})
 
+		It("does not let a regular user overwrite another user's player via Save with a spoofed id", func() {
+			spoofed := model.Player{
+				ID:             adminPlayer1.ID,
+				Name:           "HIJACKED",
+				UserId:         regularUser.ID,
+				ReportRealPath: true,
+			}
+
+			id, err := regularRepo.Save(&spoofed)
+			Expect(err).To(BeNil())
+			Expect(id).ToNot(Equal(adminPlayer1.ID))
+
+			stored, err := adminRepo.Get(adminPlayer1.ID)
+			Expect(err).To(BeNil())
+			Expect(*stored).To(Equal(adminPlayer1))
+
+			created, err := adminRepo.Get(id)
+			Expect(err).To(BeNil())
+			Expect(created.UserId).To(Equal(regularUser.ID))
+		})
+
 		It("does not let a regular user reassign their own player to another user", func() {
 			// Owner updates their own player but tries to give it away to the admin. The update
 			// succeeds for the other fields, but user_id is never written, so ownership stays put.

From cabfd16f9faee4a205fc6470339df2fa009be359 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 20 Sep 2026 21:36:35 -0400
Subject: [PATCH 163/200] fix(ui): update Finnish, Dutch translations from
 POEditor (#6148)

Co-authored-by: navidrome-bot <navidrome-bot@navidrome.org>
---
 resources/i18n/fi.json | 17 ++++++++++++++---
 resources/i18n/nl.json | 36 +++++++++++++++++++++++++++++-------
 2 files changed, 43 insertions(+), 10 deletions(-)

diff --git a/resources/i18n/fi.json b/resources/i18n/fi.json
index 3d1edbbd5..f79d71f94 100644
--- a/resources/i18n/fi.json
+++ b/resources/i18n/fi.json
@@ -202,7 +202,7 @@
         "command": "Komento"
       },
       "choices": {
-        "noDefaultBitRate": ""
+        "noDefaultBitRate": "Ei mikään"
       }
     },
     "playlist": {
@@ -609,7 +609,10 @@
     "coverRemoved": "Kansikuva poistettu",
     "coverUploadError": "Virhe ladattaessa kansikuvaa",
     "coverRemoveError": "Virhe poistettaessa kansikuvaa",
-    "metadataRefreshStarted": "Metatietoja päivitetään taustalla"
+    "metadataRefreshStarted": "Metatietoja päivitetään taustalla",
+    "quickConnectApproved": "",
+    "quickConnectInvalidCode": "",
+    "quickConnectError": ""
   },
   "menu": {
     "library": "Kirjasto",
@@ -645,7 +648,15 @@
       "selectLibraries": "Valitse kirjastot",
       "none": "Ei mitään"
     },
-    "onlyFavourites": "Näytä vain suosikit"
+    "onlyFavourites": "Näytä vain suosikit",
+    "quickConnect": {
+      "name": "",
+      "code": "",
+      "help": "",
+      "confirm": "",
+      "continue": "",
+      "approve": ""
+    }
   },
   "player": {
     "playListsText": "Jono",
diff --git a/resources/i18n/nl.json b/resources/i18n/nl.json
index 46c3df9de..cb276b8f4 100644
--- a/resources/i18n/nl.json
+++ b/resources/i18n/nl.json
@@ -93,7 +93,8 @@
         "addToPlaylist": "Toevoegen aan afspeellijst",
         "download": "Downloaden",
         "info": "Meer info",
-        "share": "Delen"
+        "share": "Delen",
+        "refresh": "Metadata verversen"
       },
       "lists": {
         "all": "Alle",
@@ -155,11 +156,13 @@
         "newPassword": "Nieuw wachtwoord",
         "token": "Token",
         "lastAccessAt": "Meest recente toegang",
-        "libraries": "Bibliotheken"
+        "libraries": "Bibliotheken",
+        "scrobbleFilter": "Scrobble filter"
       },
       "helperTexts": {
         "name": "Naamswijziging wordt pas zichtbaar bij de volgende login",
-        "libraries": "Selecteer specifieke bibliotheken voor deze gebruiker, of laat leeg om de standaardbiblliotheken te gebruiken"
+        "libraries": "Selecteer specifieke bibliotheken voor deze gebruiker, of laat leeg om de standaardbiblliotheken te gebruiken",
+        "scrobbleFilter": "Nummers binnen deze slimme afspeellijst regels worden niet gestuurd naar Last.fm, ListenBrainz of scrobbler plugins. Gebruikt dezelfde JSON syntaxis en gedrag als slimme afspeellijsten. Voorbeeld:  {\"all\":[{\"lt\":{\"rating\":4}}]}. Leeglaten om alles te scrobblen. Lokale afspeelaantallen vallen hierbuiten."
       },
       "notifications": {
         "created": "Aangemaakt door gebruiker",
@@ -173,7 +176,8 @@
         "adminAutoLibraries": "Admin gebruikers hebben automatisch toegang tot alle bibliotheken"
       },
       "validation": {
-        "librariesRequired": "Minstens één bibliotheek moet geselecteerd worden voor niet-admin gebruikers"
+        "librariesRequired": "Minstens één bibliotheek moet geselecteerd worden voor niet-admin gebruikers",
+        "invalidScrobbleFilter": "Moeten geldige slimme afspeellijst regels zijn. Geen ondersteuning voor Limit, Offset en Refresh Delay"
       }
     },
     "player": {
@@ -196,6 +200,9 @@
         "targetFormat": "Doelformaat",
         "defaultBitRate": "Standaard bitrate",
         "command": "Commando"
+      },
+      "choices": {
+        "noDefaultBitRate": "Geen"
       }
     },
     "playlist": {
@@ -210,7 +217,8 @@
         "songCount": "Nummers",
         "comment": "Commentaar",
         "sync": "Auto-importeren",
-        "path": "Importeer vanuit"
+        "path": "Importeer vanuit",
+        "starred": "Favoriet"
       },
       "actions": {
         "selectPlaylist": "Selecteer een afspeellijst:",
@@ -403,7 +411,8 @@
         "requiredHosts": "Benodigde hosts",
         "configValidationError": "Configuratiecheck mislukt",
         "schemaRenderError": "Kan het configuratieformulier niet verwerken. Het plugin schema is wellicht ongeldig.",
-        "allowWriteAccessHelp": "Met dit ingeschakeld, kan de plug-in bestanden bewerken in de bibliotheekmappen. Standaard kunnen plug-ins alleen lezen."
+        "allowWriteAccessHelp": "Met dit ingeschakeld, kan de plug-in bestanden bewerken in de bibliotheekmappen. Standaard kunnen plug-ins alleen lezen.",
+        "idHelp": "De plugin ID, afgeleid van zijn bestandsnaam. Gebruik dit als gerefereerd wordt aan deze plugin in de configuratie opties, zoals Agenten."
       },
       "placeholders": {
         "configKey": "Sleutel",
@@ -599,7 +608,11 @@
     "coverUploaded": "Albumhoes bijgewerkt",
     "coverRemoved": "Albumhoes verwijderd",
     "coverUploadError": "Fout bij het toevoegen albumhoes",
-    "coverRemoveError": "Fout bij verwijderen albumhoes"
+    "coverRemoveError": "Fout bij verwijderen albumhoes",
+    "metadataRefreshStarted": "Metadata verversen op de achtergrond",
+    "quickConnectApproved": "",
+    "quickConnectInvalidCode": "",
+    "quickConnectError": ""
   },
   "menu": {
     "library": "Bibliotheek",
@@ -634,6 +647,15 @@
       "multipleLibraries": "%{selected} van %{total} bibliotheken",
       "selectLibraries": "Selecteer bibliotheken",
       "none": "Geen"
+    },
+    "onlyFavourites": "Toon alleen favorieten",
+    "quickConnect": {
+      "name": "",
+      "code": "",
+      "help": "",
+      "confirm": "",
+      "continue": "",
+      "approve": ""
     }
   },
   "player": {

From c3b9b4ecb37f443770866a2068db5326118e7b94 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 20 Sep 2026 22:02:23 -0400
Subject: [PATCH 164/200] fix(subsonic): rate limit failed authentication
 attempts (#6185)

* fix(subsonic): limit failed authentication attempts per client IP and username

The Subsonic API checked credentials on every request with no limit on failures, so any
account could be brute-forced over /rest/*. Failed u+p, t+s and jwt attempts are now capped
per (client IP, lower-cased username) using AuthRequestLimit and AuthWindowLength, the same
settings that guard the UI login. Every request carries credentials, so only failures count:
a slot is taken before the check and given back on success or on a server error, which also
stops concurrent guesses from overshooting the limit.

Blocked attempts get the same response as a wrong password (HTTP 200, error code 40, no
Retry-After), so an attacker cannot tell a block from a wrong guess. Reverse proxy and
internal authentication are not limited. The client IP helper behind ClientIPRateLimiter is
now exported as server.ClientIP, so spoofed forwarding headers cannot open a fresh bucket.

* refactor(subsonic): simplify failed authentication limiter

Release the limiter slot from a single place in authenticate(), after the user lookup and
credential check, instead of separately in the canceled branch. Store attempt counters by
value instead of by pointer, and drop limiter unit tests that only repeated the middleware
specs.

* fix(subsonic): wait for an in-flight auth check instead of rejecting

Slots were reserved before the credential check and only released afterwards, so once
AuthRequestLimit checks for the same client IP and username overlapped, the next request was
answered with error code 40 even when its credentials were valid. Clients that fan out parallel
requests hit this constantly: a burst of six valid logins lost one, a burst of fifty lost forty
five, and the web UI authenticates its own /rest calls the same way.

A key now carries a slot channel of AuthRequestLimit capacity, and a request waits on it rather
than failing when other checks for that key are in flight. Failures are recorded after the check,
and a request is only rejected when the key already reached the limit within the window. A waiting
request gives up if its context is canceled. Concurrent guesses still cannot run unchecked: at most
AuthRequestLimit checks run at once and the rest are turned away as soon as the failures land.

* docs(subsonic): state the real guess ceiling of the auth limiter

The comment claimed a burst cannot overshoot, which reads as a hard cap of AuthRequestLimit. Allowing concurrent checks means a window admits up to 2*limit-1 guesses, so say that instead.
---
 server/middlewares.go                |  13 +-
 server/subsonic/auth_limiter.go      | 134 +++++++++++++++++++
 server/subsonic/auth_limiter_test.go | 143 ++++++++++++++++++++
 server/subsonic/middlewares.go       |  30 +++--
 server/subsonic/middlewares_test.go  | 187 +++++++++++++++++++++++++++
 5 files changed, 494 insertions(+), 13 deletions(-)
 create mode 100644 server/subsonic/auth_limiter.go
 create mode 100644 server/subsonic/auth_limiter_test.go

diff --git a/server/middlewares.go b/server/middlewares.go
index c54e947f3..674337e92 100644
--- a/server/middlewares.go
+++ b/server/middlewares.go
@@ -232,15 +232,20 @@ func trustedProxyPrefixes(list string) []string {
 	return prefixes
 }
 
-// ClientIPRateLimiter returns a rate limiter keyed by the client IP resolved by realIPMiddleware,
-// so spoofed forwarding headers cannot be rotated for a fresh bucket. It falls back to the peer
-// address, so that a missing middleware degrades to per-peer limiting rather than one shared bucket.
+// ClientIPRateLimiter returns a rate limiter keyed by ClientIP, so spoofed forwarding headers
+// cannot be rotated for a fresh bucket.
 func ClientIPRateLimiter(requestLimit int, windowLength time.Duration) func(http.Handler) http.Handler {
 	return httprate.LimitBy(requestLimit, windowLength, func(r *http.Request) (string, error) {
-		return httprate.CanonicalizeIP(cmp.Or(middleware.GetClientIP(r.Context()), peerHost(r))), nil
+		return ClientIP(r), nil
 	})
 }
 
+// ClientIP returns the canonical client IP resolved by realIPMiddleware, for keying rate limits. The
+// peer address fallback degrades a missing middleware to per-peer limiting, not one shared bucket.
+func ClientIP(r *http.Request) string {
+	return httprate.CanonicalizeIP(cmp.Or(middleware.GetClientIP(r.Context()), peerHost(r)))
+}
+
 // reqToCtx creates a middleware that updates the request's context with a value computed from the request. A given key
 // can only be set once.
 func reqToCtx(key any, fn func(req *http.Request) any) func(http.Handler) http.Handler {
diff --git a/server/subsonic/auth_limiter.go b/server/subsonic/auth_limiter.go
new file mode 100644
index 000000000..88df6eb50
--- /dev/null
+++ b/server/subsonic/auth_limiter.go
@@ -0,0 +1,134 @@
+package subsonic
+
+import (
+	"cmp"
+	"context"
+	"hash/maphash"
+	"sync"
+	"time"
+
+	"github.com/navidrome/navidrome/consts"
+)
+
+// authLimiter caps failed Subsonic logins per key. Checks run at most `limit` at a time and failures
+// are recorded afterwards, so a window admits up to 2*limit-1 guesses and valid requests only wait.
+type authLimiter struct {
+	limit     int
+	window    time.Duration
+	seed      maphash.Seed
+	mu        sync.Mutex
+	keys      map[uint64]*authAttempts // hashed, so attacker-chosen usernames cannot bloat memory
+	lastSweep time.Time
+}
+
+type authAttempts struct {
+	failures int
+	start    time.Time
+	slots    chan struct{}
+	refs     int
+}
+
+// authSlot is a reserved credential check. A nil slot releases nothing, which is what a disabled
+// limiter hands back.
+type authSlot struct {
+	limiter *authLimiter
+	entry   *authAttempts
+}
+
+// newAuthLimiter returns nil when limit is not positive. A nil limiter allows everything.
+func newAuthLimiter(limit int, window time.Duration) *authLimiter {
+	if limit <= 0 {
+		return nil
+	}
+	return &authLimiter{
+		limit:  limit,
+		window: cmp.Or(window, consts.DefaultAuthWindowLength),
+		seed:   maphash.MakeSeed(),
+		keys:   map[uint64]*authAttempts{},
+	}
+}
+
+// acquire reserves a credential check for key, waiting while other checks for the same key are in
+// flight. It only fails when the key already reached `limit` failures in the current window.
+func (l *authLimiter) acquire(ctx context.Context, key string) (*authSlot, bool) {
+	if l == nil {
+		return nil, true
+	}
+	a, ok := l.reserve(key)
+	if !ok {
+		return nil, false
+	}
+
+	select {
+	case a.slots <- struct{}{}:
+	case <-ctx.Done():
+		l.unref(a)
+		return nil, false
+	}
+
+	l.mu.Lock()
+	blocked := a.failures >= l.limit
+	if blocked {
+		a.refs--
+	}
+	l.mu.Unlock()
+	if blocked {
+		<-a.slots
+		return nil, false
+	}
+	return &authSlot{limiter: l, entry: a}, true
+}
+
+func (l *authLimiter) reserve(key string) (*authAttempts, bool) {
+	now := time.Now()
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.sweep(now)
+
+	h := maphash.String(l.seed, key)
+	a := l.keys[h]
+	switch {
+	case a == nil:
+		a = &authAttempts{start: now, slots: make(chan struct{}, l.limit)}
+		l.keys[h] = a
+	case now.Sub(a.start) >= l.window:
+		a.failures, a.start = 0, now
+	}
+	if a.failures >= l.limit {
+		return nil, false
+	}
+	a.refs++
+	return a, true
+}
+
+func (l *authLimiter) unref(a *authAttempts) {
+	l.mu.Lock()
+	a.refs--
+	l.mu.Unlock()
+}
+
+func (s *authSlot) release(failed bool) {
+	if s == nil {
+		return
+	}
+	s.limiter.mu.Lock()
+	if failed {
+		s.entry.failures++
+	}
+	s.entry.refs--
+	s.limiter.mu.Unlock()
+	<-s.entry.slots
+}
+
+// sweep drops idle expired keys once per window, so memory is bounded by recent attempts.
+func (l *authLimiter) sweep(now time.Time) {
+	if now.Sub(l.lastSweep) < l.window {
+		return
+	}
+	for h, a := range l.keys {
+		if a.refs == 0 && now.Sub(a.start) >= l.window {
+			delete(l.keys, h)
+		}
+	}
+	l.lastSweep = now
+}
diff --git a/server/subsonic/auth_limiter_test.go b/server/subsonic/auth_limiter_test.go
new file mode 100644
index 000000000..66e1a594f
--- /dev/null
+++ b/server/subsonic/auth_limiter_test.go
@@ -0,0 +1,143 @@
+package subsonic
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("authLimiter", func() {
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = context.Background()
+	})
+
+	acquire := func(l *authLimiter, key string) (*authSlot, bool) {
+		GinkgoHelper()
+		return l.acquire(ctx, key)
+	}
+
+	It("blocks a key after the configured number of failures", func() {
+		l := newAuthLimiter(2, time.Minute)
+		for range 2 {
+			slot, ok := acquire(l, "k")
+			Expect(ok).To(BeTrue())
+			slot.release(true)
+		}
+
+		_, ok := acquire(l, "k")
+		Expect(ok).To(BeFalse())
+	})
+
+	It("never counts successful checks", func() {
+		l := newAuthLimiter(2, time.Minute)
+		for range 50 {
+			slot, ok := acquire(l, "k")
+			Expect(ok).To(BeTrue())
+			slot.release(false)
+		}
+	})
+
+	It("keeps keys independent", func() {
+		l := newAuthLimiter(1, time.Minute)
+		slot, _ := acquire(l, "a")
+		slot.release(true)
+		_, ok := acquire(l, "a")
+		Expect(ok).To(BeFalse())
+
+		_, ok = acquire(l, "b")
+		Expect(ok).To(BeTrue())
+	})
+
+	It("waits for an in-flight check instead of failing the request", func() {
+		l := newAuthLimiter(1, time.Minute)
+		held, ok := acquire(l, "k")
+		Expect(ok).To(BeTrue())
+
+		waiting := make(chan bool, 1)
+		go func() {
+			slot, ok := l.acquire(ctx, "k")
+			slot.release(false)
+			waiting <- ok
+		}()
+		Consistently(waiting, 50*time.Millisecond).ShouldNot(Receive())
+
+		held.release(false)
+		Eventually(waiting).Should(Receive(BeTrue()))
+	})
+
+	It("stops waiting when the request is canceled", func() {
+		l := newAuthLimiter(1, time.Minute)
+		held, _ := acquire(l, "k")
+		DeferCleanup(func() { held.release(false) })
+
+		canceled, cancel := context.WithCancel(context.Background())
+		cancel()
+		_, ok := l.acquire(canceled, "k")
+		Expect(ok).To(BeFalse())
+	})
+
+	It("does not let concurrent guesses overshoot the limit", func() {
+		l := newAuthLimiter(5, time.Minute)
+		hold := make(chan struct{})
+		var checks atomic.Int32
+		var wg sync.WaitGroup
+		for range 50 {
+			wg.Go(func() {
+				slot, ok := l.acquire(ctx, "k")
+				if !ok {
+					return
+				}
+				checks.Add(1)
+				<-hold
+				slot.release(true)
+			})
+		}
+
+		Eventually(checks.Load).Should(Equal(int32(5)))
+		Consistently(checks.Load, 100*time.Millisecond).Should(Equal(int32(5)))
+		close(hold)
+		wg.Wait()
+
+		_, ok := acquire(l, "k")
+		Expect(ok).To(BeFalse())
+	})
+
+	It("allows everything when the limit is disabled", func() {
+		l := newAuthLimiter(0, time.Minute)
+		for range 10 {
+			slot, ok := acquire(l, "k")
+			Expect(ok).To(BeTrue())
+			slot.release(true)
+		}
+	})
+})
+
+// testing/synctest's fake clock needs a *testing.T, which Ginkgo doesn't give.
+func TestAuthLimiterWindow(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		g := NewWithT(t)
+		ctx := context.Background()
+		l := newAuthLimiter(1, 20*time.Second)
+		for _, key := range []string{"a", "b"} {
+			slot, ok := l.acquire(ctx, key)
+			g.Expect(ok).To(BeTrue())
+			slot.release(true)
+		}
+		_, ok := l.acquire(ctx, "a")
+		g.Expect(ok).To(BeFalse())
+
+		time.Sleep(20 * time.Second)
+		slot, ok := l.acquire(ctx, "a")
+		g.Expect(ok).To(BeTrue())
+		slot.release(false)
+		g.Expect(l.keys).To(HaveLen(1), "expired keys must be dropped")
+	})
+}
diff --git a/server/subsonic/middlewares.go b/server/subsonic/middlewares.go
index 6dfa2263f..35e13eaa5 100644
--- a/server/subsonic/middlewares.go
+++ b/server/subsonic/middlewares.go
@@ -98,6 +98,7 @@ func checkRequiredParameters(next http.Handler) http.Handler {
 }
 
 func authenticate(ds model.DataStore) func(next http.Handler) http.Handler {
+	limiter := newAuthLimiter(conf.Server.AuthRequestLimit, conf.Server.AuthWindowLength)
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			ctx := r.Context()
@@ -126,21 +127,32 @@ func authenticate(ds model.DataStore) func(next http.Handler) http.Handler {
 				salt, _ := p.String("s")
 				jwt, _ := p.String("jwt")
 
-				usr, err = ds.User(ctx).FindByUsernameWithPassword(username)
-				if errors.Is(err, context.Canceled) {
-					log.Debug(ctx, "API: Request canceled when authenticating", "auth", "subsonic", "username", username, "remoteAddr", r.RemoteAddr, err)
+				// Blocked attempts get the same response as a wrong password, so they reveal nothing
+				limitKey := server.ClientIP(r) + "\x00" + strings.ToLower(username)
+				slot, allowed := limiter.acquire(ctx, limitKey)
+				if !allowed {
+					if ctx.Err() != nil {
+						return
+					}
+					log.Warn(ctx, "API: Too many failed login attempts", "auth", "subsonic", "username", username, "remoteAddr", r.RemoteAddr)
+					sendError(w, r, newError(responses.ErrorAuthenticationFail))
 					return
 				}
+
+				usr, err = ds.User(ctx).FindByUsernameWithPassword(username)
+				if err == nil {
+					err = validateCredentials(usr, pass, token, salt, jwt)
+				}
+				invalidLogin := errors.Is(err, model.ErrNotFound) || errors.Is(err, model.ErrInvalidAuth)
+				slot.release(invalidLogin)
 				switch {
-				case errors.Is(err, model.ErrNotFound):
+				case errors.Is(err, context.Canceled):
+					log.Debug(ctx, "API: Request canceled when authenticating", "auth", "subsonic", "username", username, "remoteAddr", r.RemoteAddr, err)
+					return
+				case invalidLogin:
 					log.Warn(ctx, "API: Invalid login", "auth", "subsonic", "username", username, "remoteAddr", r.RemoteAddr, err)
 				case err != nil:
 					log.Error(ctx, "API: Error authenticating username", "auth", "subsonic", "username", username, "remoteAddr", r.RemoteAddr, err)
-				default:
-					err = validateCredentials(usr, pass, token, salt, jwt)
-					if err != nil {
-						log.Warn(ctx, "API: Invalid login", "auth", "subsonic", "username", username, "remoteAddr", r.RemoteAddr, err)
-					}
 				}
 			}
 
diff --git a/server/subsonic/middlewares_test.go b/server/subsonic/middlewares_test.go
index cb34b92e7..62de09e76 100644
--- a/server/subsonic/middlewares_test.go
+++ b/server/subsonic/middlewares_test.go
@@ -8,6 +8,8 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -306,6 +308,166 @@ var _ = Describe("Middlewares", func() {
 				Expect(next.called).To(BeFalse())
 			})
 		})
+
+		When("failed attempts reach AuthRequestLimit", func() {
+			var cp http.Handler
+
+			BeforeEach(func() {
+				DeferCleanup(configtest.SetupConfig())
+				conf.Server.AuthRequestLimit = 3
+				conf.Server.AuthWindowLength = time.Minute
+				cp = authenticate(ds)(next)
+			})
+
+			serve := func(r *http.Request) *httptest.ResponseRecorder {
+				next.called = false
+				rec := httptest.NewRecorder()
+				cp.ServeHTTP(rec, r)
+				return rec
+			}
+			failTimes := func(n int, params ...string) {
+				for range n {
+					Expect(serve(newGetRequest(params...)).Body.String()).To(ContainSubstring(`code="40"`))
+				}
+			}
+
+			It("rejects the correct password exactly like a wrong one", func() {
+				failTimes(3, "u=admin", "p=WRONG")
+
+				rec := serve(newGetRequest("u=admin", "p=wordpass"))
+
+				Expect(next.called).To(BeFalse())
+				Expect(rec.Code).To(Equal(http.StatusOK))
+				Expect(rec.Body.String()).To(ContainSubstring(`code="40"`))
+				Expect(rec.Header().Get("Retry-After")).To(BeEmpty())
+			})
+
+			It("counts attempts against unknown usernames", func() {
+				failTimes(3, "u=newuser", "p=secret")
+				_ = ds.User(context.TODO()).Put(&model.User{UserName: "newuser", NewPassword: "secret"})
+
+				serve(newGetRequest("u=newuser", "p=secret"))
+				Expect(next.called).To(BeFalse())
+			})
+
+			It("treats usernames case-insensitively", func() {
+				failTimes(3, "u=ADMIN", "p=WRONG")
+
+				serve(newGetRequest("u=admin", "p=wordpass"))
+				Expect(next.called).To(BeFalse())
+			})
+
+			It("does not count successful logins", func() {
+				for range 10 {
+					serve(newGetRequest("u=admin", "p=wordpass"))
+					Expect(next.called).To(BeTrue())
+				}
+			})
+
+			It("does not count server errors", func() {
+				userRepo := ds.User(context.TODO()).(*tests.MockedUserRepo)
+				userRepo.Error = errors.New("db down")
+				failTimes(5, "u=admin", "p=wordpass")
+				userRepo.Error = nil
+
+				serve(newGetRequest("u=admin", "p=wordpass"))
+				Expect(next.called).To(BeTrue())
+			})
+
+			It("does not block other usernames from the same IP", func() {
+				_ = ds.User(context.TODO()).Put(&model.User{UserName: "other", NewPassword: "otherpass"})
+				failTimes(3, "u=admin", "p=WRONG")
+
+				serve(newGetRequest("u=other", "p=otherpass"))
+				Expect(next.called).To(BeTrue())
+			})
+
+			It("does not block the same username from another IP", func() {
+				failTimes(3, "u=admin", "p=WRONG")
+
+				r := newGetRequest("u=admin", "p=wordpass")
+				r.RemoteAddr = "198.51.100.7:1234"
+				serve(r)
+				Expect(next.called).To(BeTrue())
+			})
+
+			It("does not limit reverse proxy authentication", func() {
+				conf.Server.ExtAuth.TrustedSources = "192.168.1.1/24"
+				conf.Server.ExtAuth.UserHeader = "Remote-User"
+				failTimes(3, "u=admin", "p=WRONG")
+
+				r := newGetRequest()
+				r.Header.Add("Remote-User", "admin")
+				r = r.WithContext(request.WithReverseProxyIp(r.Context(), "192.168.1.1"))
+				serve(r)
+				Expect(next.called).To(BeTrue())
+			})
+
+			It("is disabled when AuthRequestLimit is 0", func() {
+				conf.Server.AuthRequestLimit = 0
+				cp = authenticate(ds)(next)
+				failTimes(10, "u=admin", "p=WRONG")
+
+				serve(newGetRequest("u=admin", "p=wordpass"))
+				Expect(next.called).To(BeTrue())
+			})
+		})
+
+		When("valid requests overlap", func() {
+			var gate *gatedUserRepo
+			var gatedDS model.DataStore
+
+			BeforeEach(func() {
+				DeferCleanup(configtest.SetupConfig())
+				conf.Server.AuthRequestLimit = 5
+				conf.Server.AuthWindowLength = time.Minute
+				gate = &gatedUserRepo{
+					UserRepository: ds.User(context.TODO()),
+					entered:        make(chan struct{}, 64),
+					proceed:        make(chan struct{}),
+				}
+				gatedDS = &gatedDataStore{DataStore: ds, users: gate}
+			})
+
+			It("lets every valid request through while checks are in flight", func() {
+				const burst = 6
+				cp := authenticate(gatedDS)(&countingHandler{})
+				var passed atomic.Int32
+				var wg sync.WaitGroup
+				for range burst {
+					wg.Go(func() {
+						rec := httptest.NewRecorder()
+						cp.ServeHTTP(rec, newGetRequest("u=admin", "p=wordpass"))
+						if !strings.Contains(rec.Body.String(), `code="40"`) {
+							passed.Add(1)
+						}
+					})
+				}
+				for range conf.Server.AuthRequestLimit {
+					Eventually(gate.entered).Should(Receive())
+				}
+				close(gate.proceed)
+				wg.Wait()
+
+				Expect(passed.Load()).To(Equal(int32(burst)))
+			})
+
+			It("caps concurrent credential checks for wrong passwords", func() {
+				cp := authenticate(gatedDS)(&countingHandler{})
+				var wg sync.WaitGroup
+				for i := range 100 {
+					wg.Go(func() {
+						cp.ServeHTTP(httptest.NewRecorder(), newGetRequest("u=admin", fmt.Sprintf("p=wrong%d", i)))
+					})
+				}
+
+				limit := int32(conf.Server.AuthRequestLimit)
+				Eventually(gate.lookups.Load).Should(Equal(limit))
+				Consistently(gate.lookups.Load, 100*time.Millisecond).Should(Equal(limit))
+				close(gate.proceed)
+				wg.Wait()
+			})
+		})
 	})
 
 	Describe("AdminOnly", func() {
@@ -560,3 +722,28 @@ func (mp *mockPlayers) Register(ctx context.Context, id, client, typ, ip string)
 	}
 	return &model.Player{ID: id}, mp.transcoding, nil
 }
+
+type gatedDataStore struct {
+	model.DataStore
+	users model.UserRepository
+}
+
+func (g *gatedDataStore) User(context.Context) model.UserRepository { return g.users }
+
+type gatedUserRepo struct {
+	model.UserRepository
+	entered chan struct{}
+	proceed chan struct{}
+	lookups atomic.Int32
+}
+
+func (g *gatedUserRepo) FindByUsernameWithPassword(username string) (*model.User, error) {
+	g.lookups.Add(1)
+	g.entered <- struct{}{}
+	<-g.proceed
+	return g.UserRepository.FindByUsernameWithPassword(username)
+}
+
+type countingHandler struct{ calls atomic.Int32 }
+
+func (c *countingHandler) ServeHTTP(http.ResponseWriter, *http.Request) { c.calls.Add(1) }

From 6b3938b5b659e1a9f707efb16649667084bfb3b9 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Sun, 20 Sep 2026 22:25:55 -0400
Subject: [PATCH 165/200] fix(subsonic): warn when a nowPlaying scrobble sends
 multiple ids

The scrobble endpoint accepts multiple ids, but a nowPlaying notification
(submission=false) describes a single track, so only the first id is used.
The extra ids were dropped silently, which made client bugs invisible. Log a
warning instead, keeping the existing behavior for clients that rely on it.
---
 server/subsonic/media_annotation.go | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/server/subsonic/media_annotation.go b/server/subsonic/media_annotation.go
index cfbff3ecb..a43162cf4 100644
--- a/server/subsonic/media_annotation.go
+++ b/server/subsonic/media_annotation.go
@@ -181,6 +181,9 @@ func (api *Router) Scrobble(r *http.Request) (*responses.Subsonic, error) {
 			log.Error(ctx, "Error registering scrobbles", "ids", ids, "times", times, err)
 		}
 	} else {
+		if len(ids) > 1 {
+			log.Warn(ctx, "Multiple ids sent to a nowPlaying notification, only the first one will be used", "ids", ids)
+		}
 		err := api.scrobblerNowPlaying(ctx, ids[0], position)
 		if err != nil {
 			log.Error(ctx, "Error setting NowPlaying", "id", ids[0], err)

From 00bb120288af84f3764e684b9b2bab70d5028219 Mon Sep 17 00:00:00 2001
From: Antonio Russo <aerusso@aerusso.net>
Date: Mon, 21 Sep 2026 07:06:12 -0600
Subject: [PATCH 166/200] fix(contrib): support libblas in systemd sandbox
 (#6190)

Navidrome calls out to ffprobe, which in turn may use libblas on some
setups (e.g., Debian 13).  The previous syscall filter excluded the
"mbind" syscall (via @resources).

Through direct experimentation, mbind is required by libblas, and so it
is added to the allowed syscall list.

Signed-off-by: Antonio Enrico Russo <aerusso@aerusso.net>
---
 contrib/navidrome.service | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contrib/navidrome.service b/contrib/navidrome.service
index 5e6cbedce..ef61d2c65 100644
--- a/contrib/navidrome.service
+++ b/contrib/navidrome.service
@@ -36,7 +36,7 @@ RestrictNamespaces=yes
 RestrictRealtime=yes
 SystemCallFilter=@system-service
 SystemCallFilter=~@privileged @resources
-SystemCallFilter=setrlimit
+SystemCallFilter=setrlimit mbind
 SystemCallArchitectures=native
 UMask=0066
 

From 07c756db3c0a4f44856a230d71cd40e4cf8e3768 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 21 Sep 2026 16:18:38 -0400
Subject: [PATCH 167/200] fix(ui): update Portuguese (BR) translations from
 POEditor (#6197)

Co-authored-by: navidrome-bot <navidrome-bot@navidrome.org>
---
 resources/i18n/pt-br.json | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/resources/i18n/pt-br.json b/resources/i18n/pt-br.json
index 2584da6cd..6fcde56ca 100644
--- a/resources/i18n/pt-br.json
+++ b/resources/i18n/pt-br.json
@@ -202,7 +202,7 @@
         "command": "Comando"
       },
       "choices": {
-        "noDefaultBitRate": ""
+        "noDefaultBitRate": "Nenhum"
       }
     },
     "playlist": {
@@ -609,7 +609,10 @@
     "coverRemoved": "Capa removida",
     "coverUploadError": "Erro ao enviar capa",
     "coverRemoveError": "Erro ao remover capa",
-    "metadataRefreshStarted": "Atualizando metadados em segundo plano"
+    "metadataRefreshStarted": "Atualizando metadados em segundo plano",
+    "quickConnectApproved": "%{app} em %{device} está conectado agora",
+    "quickConnectInvalidCode": "Código inválido ou expirado",
+    "quickConnectError": "Não foi possível aprovar o código"
   },
   "menu": {
     "library": "Biblioteca",
@@ -645,7 +648,15 @@
       "selectLibraries": "Selecionar Bibliotecas",
       "none": "Nenhuma"
     },
-    "onlyFavourites": "Somente favoritas"
+    "onlyFavourites": "Somente favoritas",
+    "quickConnect": {
+      "name": "Conexão Rápida",
+      "code": "Código",
+      "help": "Digite o código exibido por um aplicativo Jellyfin para conectá-lo à sua conta",
+      "confirm": "Conectar %{app} %{version} em %{device} à sua conta?",
+      "continue": "Continuar",
+      "approve": "Aprovar"
+    }
   },
   "player": {
     "playListsText": "Fila de Execução",

From cb7b042e36b00db3d20de83e175a30287361e8b0 Mon Sep 17 00:00:00 2001
From: Karl Ostendorf <karl@ostendorf.com>
Date: Mon, 21 Sep 2026 23:25:46 +0200
Subject: [PATCH 168/200] fix(artwork): make stored images group-readable
 (#6189)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Karl Ostendorf <karl@ostendorf.com>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 core/artwork/image_store.go      |  3 +++
 core/artwork/image_store_test.go | 11 +++++++++++
 2 files changed, 14 insertions(+)

diff --git a/core/artwork/image_store.go b/core/artwork/image_store.go
index 5dbe727e4..2ded3e636 100644
--- a/core/artwork/image_store.go
+++ b/core/artwork/image_store.go
@@ -98,6 +98,9 @@ func (s *ImageStore) Write(hash, mimeType string, r io.Reader) error {
 	if err := tmp.Close(); err != nil {
 		return err
 	}
+	if err := os.Chmod(tmp.Name(), 0640); err != nil {
+		return err
+	}
 	return os.Rename(tmp.Name(), dst)
 }
 
diff --git a/core/artwork/image_store_test.go b/core/artwork/image_store_test.go
index f7b2467ca..7de3ba761 100644
--- a/core/artwork/image_store_test.go
+++ b/core/artwork/image_store_test.go
@@ -48,6 +48,17 @@ var _ = Describe("ImageStore", func() {
 		Expect(got).To(Equal(data))
 	})
 
+	It("writes group-readable image files", func() {
+		tests.SkipOnWindows("uses Unix file permission bits")
+		data := []byte("jpeg-bytes")
+		h, _ := hashImage(bytes.NewReader(data))
+		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
+
+		info, err := os.Stat(store.path(h, "image/jpeg"))
+		Expect(err).ToNot(HaveOccurred())
+		Expect(info.Mode().Perm()).To(Equal(os.FileMode(0640)))
+	})
+
 	It("is idempotent on duplicate writes and preserves the original content", func() {
 		data := []byte("dup")
 		h, _ := hashImage(bytes.NewReader(data))

From 285dc4f39155954e6bb9af93f88da71b9b9cbe21 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 21 Sep 2026 17:34:32 -0400
Subject: [PATCH 169/200] fix(lastfm): report a failure when the artist page
 has no image (#6198)

GetArtistImages scrapes the og:image tag off the Last.fm artist page, because
the API only ever returns the placeholder image. Last.fm now answers non-browser
clients with a Fastly bot challenge, served as a 200 with valid HTML, so the
query found no og:image and the agent returned an empty list with no error. The
artwork worker read that as a definitive "this artist has no image" and settled
the state as absent, silently and with nothing in the log.

A real artist page always carries an og:image, so its absence now returns an
error instead. The worker keeps the previous state, other agents still get their
turn, and its per-agent circuit breaker bounds the retries. The error is
deliberately not a RetryLaterError: that would park the whole Last.fm agent,
including the API-backed biography, similar-artists and top-songs calls, which
the page block does not affect.

The new fixture is the real 3038-byte challenge page.

Fixes #6192
---
 adapters/lastfm/agent.go                      |  8 +-
 adapters/lastfm/agent_test.go                 | 27 +++++-
 .../lastfm.artist.page.challenge.html         | 88 +++++++++++++++++++
 3 files changed, 120 insertions(+), 3 deletions(-)
 create mode 100644 tests/fixtures/lastfm.artist.page.challenge.html

diff --git a/adapters/lastfm/agent.go b/adapters/lastfm/agent.go
index 7f005db1a..dbd73c30d 100644
--- a/adapters/lastfm/agent.go
+++ b/adapters/lastfm/agent.go
@@ -241,6 +241,10 @@ func (l *lastfmAgent) GetSimilarSongsByTrack(ctx context.Context, id, name, arti
 var (
 	artistOpenGraphQuery = cascadia.MustCompile(`html > head > meta[property="og:image"]`)
 	artistIgnoredImage   = "2a96cbd8b46e442fc41c2b86b821562f" // Last.fm artist placeholder image name
+
+	// Not a RetryLaterError on purpose: parking the agent would also stall its API-backed
+	// methods, which the page block does not affect.
+	errNoArtistPage = errors.New("no artist image in Last.fm page")
 )
 
 func (l *lastfmAgent) GetArtistImages(ctx context.Context, _, name, mbid string) ([]agents.ExternalImage, error) {
@@ -267,7 +271,9 @@ func (l *lastfmAgent) GetArtistImages(ctx context.Context, _, name, mbid string)
 	var res []agents.ExternalImage
 	n := cascadia.Query(node, artistOpenGraphQuery)
 	if n == nil {
-		return res, nil
+		// A real artist page always has og:image; its absence means a bot challenge or a redesign.
+		log.Warn(ctx, "Last.fm did not return a usable artist page", "name", name, "url", a.URL)
+		return nil, errNoArtistPage
 	}
 	for _, attr := range n.Attr {
 		if attr.Key != "content" {
diff --git a/adapters/lastfm/agent_test.go b/adapters/lastfm/agent_test.go
index ce81e0916..b9fb786c3 100644
--- a/adapters/lastfm/agent_test.go
+++ b/adapters/lastfm/agent_test.go
@@ -648,18 +648,41 @@ var _ = Describe("lastfmAgent", func() {
 			Expect(images).To(BeEmpty())
 		})
 
-		It("returns empty list if page has no meta tags", func() {
+		It("errors when the page has no meta tags", func() {
 			fApi, _ := os.Open("tests/fixtures/lastfm.artist.getinfo.json")
 			apiClient.Res = http.Response{Body: fApi, StatusCode: 200}
 
 			fScraper, _ := os.Open("tests/fixtures/lastfm.artist.page.no_meta.html")
 			httpClient.Res = http.Response{Body: fScraper, StatusCode: 200}
 
+			_, err := agent.GetArtistImages(ctx, "123", "U2", "")
+			Expect(err).To(MatchError(errNoArtistPage))
+		})
+
+		It("errors when Last.fm serves a bot challenge page", func() {
+			fApi, _ := os.Open("tests/fixtures/lastfm.artist.getinfo.json")
+			apiClient.Res = http.Response{Body: fApi, StatusCode: 200}
+
+			fScraper, _ := os.Open("tests/fixtures/lastfm.artist.page.challenge.html")
+			httpClient.Res = http.Response{Body: fScraper, StatusCode: 200}
+
 			images, err := agent.GetArtistImages(ctx, "123", "U2", "")
-			Expect(err).ToNot(HaveOccurred())
+			Expect(err).To(MatchError(errNoArtistPage))
 			Expect(images).To(BeEmpty())
 		})
 
+		It("does not park the agent: the failure is not a retry-later", func() {
+			// A RetryLaterError would cool down the agent's API-backed methods too.
+			fApi, _ := os.Open("tests/fixtures/lastfm.artist.getinfo.json")
+			apiClient.Res = http.Response{Body: fApi, StatusCode: 200}
+
+			fScraper, _ := os.Open("tests/fixtures/lastfm.artist.page.challenge.html")
+			httpClient.Res = http.Response{Body: fScraper, StatusCode: 200}
+
+			_, err := agent.GetArtistImages(ctx, "123", "U2", "")
+			Expect(errors.Is(err, agents.ErrRetryLater)).To(BeFalse())
+		})
+
 		It("returns error if API call fails", func() {
 			apiClient.Err = errors.New("api error")
 			_, err := agent.GetArtistImages(ctx, "123", "U2", "")
diff --git a/tests/fixtures/lastfm.artist.page.challenge.html b/tests/fixtures/lastfm.artist.page.challenge.html
new file mode 100644
index 000000000..f431891bd
--- /dev/null
+++ b/tests/fixtures/lastfm.artist.page.challenge.html
@@ -0,0 +1,88 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; img-src 'self' data:; media-src 'self' data:; object-src 'none'; style-src 'self' 'sha256-o4vzfmmUENEg4chMjjRP9EuW9ucGnGIGVdbl8d0SHQQ='; script-src 'self' 'sha256-a9bHdQGvRzDwDVzx8m+Rzw+0FHZad8L0zjtBwkxOIz4=';"
+    />
+    <link
+      href="/_fs-ch-1T1wmsGaOgGaSxcX/assets/inter-var.woff2"
+      rel="preload"
+      as="font"
+      type="font/woff2"
+      crossorigin
+    />
+    <link href="/_fs-ch-1T1wmsGaOgGaSxcX/assets/styles.css" rel="stylesheet" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Client Challenge</title>
+    <style>
+      #loading-error {
+        font-size: 16px;
+        font-family: 'Inter', sans-serif;
+        margin-top: 10px;
+        margin-left: 10px;
+        display: none;
+      }
+    </style>
+  </head>
+  <body>
+    <noscript>
+      <div class="noscript-container">
+        <div class="noscript-content">
+          <img
+            src="/_fs-ch-1T1wmsGaOgGaSxcX/assets/errorIcon.svg"
+            alt=""
+            role="presentation"
+            class="error-icon"
+          />
+          <span class="noscript-span"
+            >JavaScript is disabled in your browser.</span
+          >
+          <p>Please enable JavaScript to proceed.</p>
+        </div>
+      </div>
+    </noscript>
+    <div id="loading-error" role="alert" aria-live="polite">
+      A required part of this site couldn’t load. This may be due to a browser
+      extension, network issues, or browser settings. Please check your
+      connection, disable any ad blockers, or try using a different browser.
+    </div>
+    <script>
+      function loadScript(src) {
+        return new Promise((resolve, reject) => {
+          const script = document.createElement('script');
+          script.onload = resolve;
+          script.onerror = (event) => {
+            console.error('Script load error event:', event);
+            document.getElementById('loading-error').style.display = 'block';
+            reject(
+              new Error(
+                `Failed to load script: ${src}, Please contact the service administrator.`
+              )
+            );
+          };
+          script.src = src;
+          document.body.appendChild(script);
+        });
+      }
+
+      loadScript('/_fs-ch-1T1wmsGaOgGaSxcX/errors.js')
+        .then(() => {
+          const script = document.createElement('script');
+          script.src = '/_fs-ch-1T1wmsGaOgGaSxcX/script.js?reload=true';
+          script.onerror = (event) => {
+            console.error('Script load error event:', event);
+            const errorMsg = new Error(
+              `Failed to load script: ${script.src}. Please contact the service administrator.`
+            );
+            console.error(errorMsg);
+            handleScriptError();
+          };
+          document.body.appendChild(script);
+        })
+        .catch((error) => {
+          console.error(error);
+        });
+    </script>
+  </body>
+</html>

From 9e3deb4330b346ab0e78aa4e48605d074a6bcee3 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Mon, 21 Sep 2026 19:27:48 -0400
Subject: [PATCH 170/200] ci: scope digest artifact cleanup to the current run

The cleanup job listed artifacts repo-wide, so it deleted digest files
uploaded by any concurrent pipeline run. When the v0.64.1 tag run
overlapped with a master run, the master run's cleanup removed three of
the tag run's digests before the manifest job downloaded them, and
0.64.1/latest shipped with only linux/arm64, arm/v7 and riscv64.

List artifacts for the current run instead, so a run can only delete its
own digests.
---
 .github/workflows/pipeline.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index aa8e29e49..2702163d3 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -549,7 +549,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          for artifact in $(gh api repos/${{ github.repository }}/actions/artifacts | jq -r '.artifacts[] | select(.name | startswith("digests-")) | .id'); do
+          for artifact in $(gh api repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts | jq -r '.artifacts[] | select(.name | startswith("digests-")) | .id'); do
             gh api --method DELETE repos/${{ github.repository }}/actions/artifacts/$artifact
           done
 

From 961ee8c4136fbd18b78de1929ee5f97a1ae37f7c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 22 Sep 2026 19:51:32 -0400
Subject: [PATCH 171/200] fix(scanner): keep tag numbers within the int32 range
 (#6202)

* fix(scanner): keep tag numbers within the int32 range

A track number of 4294967295 (-1 stored as an unsigned 32-bit tag) was saved
as-is by 64-bit builds. 32-bit builds (armv5/6/7, 386) cannot read that value
back into an int, so every scan failed with "converting driver.Value type
int64 to a int: value out of range" when loading the folder's media files.

Track and disc numbers (and their totals) are now parsed as int32 and fall
back to 0 when out of range, matching how unparseable values are handled.
BPM values outside the int32 range are dropped. A migration resets existing
out-of-range track_number, disc_number and bpm values, and removes
out-of-range keys from album.discs, so databases written by 64-bit builds are
readable again by 32-bit ones. Persistent IDs are unaffected because they use
the raw tag text.

Fixes #6200

* fix(scanner): accept the int32 minimum as a BPM value

The BPM range check compared the absolute value against MaxInt32, which
rejected -2147483648 even though it fits in an int32. Compare against
MinInt32 and MaxInt32 separately, matching atoi32 and the migration.

* fix(scanner): treat negative track, disc and BPM values as missing

Track numbers, disc numbers and BPM can never be negative, so negative tag
values now map to 0 (track/disc, including totals) or nil (BPM), the same as
unparseable ones. The migration resets existing negative values as well as the
ones above the int32 range, and keeps only album disc keys from 0 to MaxInt32.
---
 ...428_clamp_media_file_int32_tag_numbers.sql | 24 +++++++++++++++++++
 model/metadata/map_mediafile.go               |  4 ++--
 model/metadata/map_mediafile_test.go          |  9 +++++++
 model/metadata/metadata.go                    | 19 +++++++++------
 model/metadata/metadata_test.go               |  4 ++++
 5 files changed, 51 insertions(+), 9 deletions(-)
 create mode 100644 db/migrations/20260922230428_clamp_media_file_int32_tag_numbers.sql

diff --git a/db/migrations/20260922230428_clamp_media_file_int32_tag_numbers.sql b/db/migrations/20260922230428_clamp_media_file_int32_tag_numbers.sql
new file mode 100644
index 000000000..dced5d744
--- /dev/null
+++ b/db/migrations/20260922230428_clamp_media_file_int32_tag_numbers.sql
@@ -0,0 +1,24 @@
+-- +goose Up
+-- +goose StatementBegin
+-- 32-bit builds cannot read values above the int32 range written by 64-bit builds.
+update media_file set track_number = 0
+where track_number < 0 or track_number > 2147483647;
+
+update media_file set disc_number = 0
+where disc_number < 0 or disc_number > 2147483647;
+
+update media_file set bpm = null
+where bpm < 0 or bpm > 2147483647;
+
+update album set discs = (
+	select json_group_object(key, value) from json_each(album.discs)
+	where cast(key as integer) between 0 and 2147483647
+)
+where json_valid(discs) and exists (
+	select 1 from json_each(album.discs)
+	where cast(key as integer) not between 0 and 2147483647
+);
+-- +goose StatementEnd
+
+-- +goose Down
+SELECT 1;
diff --git a/model/metadata/map_mediafile.go b/model/metadata/map_mediafile.go
index b3ce4ef02..6d12feba9 100644
--- a/model/metadata/map_mediafile.go
+++ b/model/metadata/map_mediafile.go
@@ -37,8 +37,8 @@ func (md Metadata) ToMediaFile(libID int, folderID string) model.MediaFile {
 	mf.CatalogNum = md.String(model.TagCatalogNumber)
 	mf.Comment = md.String(model.TagComment)
 	if f := md.NullableFloat(model.TagBPM); f != nil {
-		if v := int(math.Round(*f)); v != 0 {
-			mf.BPM = new(v)
+		if r := math.Round(*f); r > 0 && r <= math.MaxInt32 {
+			mf.BPM = new(int(r))
 		}
 	}
 	mf.Lyrics = md.mapLyrics()
diff --git a/model/metadata/map_mediafile_test.go b/model/metadata/map_mediafile_test.go
index 75a7ed358..baaf8fab5 100644
--- a/model/metadata/map_mediafile_test.go
+++ b/model/metadata/map_mediafile_test.go
@@ -131,6 +131,15 @@ var _ = Describe("ToMediaFile", func() {
 			Expect(toMediaFile(model.RawTags{"BPM": {"0"}}).BPM).To(BeNil())
 			Expect(toMediaFile(model.RawTags{"BPM": {"fast"}}).BPM).To(BeNil())
 		})
+		It("leaves BPM nil when the tag does not fit in 32 bits", func() {
+			Expect(toMediaFile(model.RawTags{"BPM": {"4294967295"}}).BPM).To(BeNil())
+		})
+		It("leaves BPM nil when the tag is negative", func() {
+			Expect(toMediaFile(model.RawTags{"BPM": {"-120"}}).BPM).To(BeNil())
+		})
+		It("keeps the largest 32-bit BPM value", func() {
+			Expect(toMediaFile(model.RawTags{"BPM": {"2147483647"}}).BPM).To(Equal(new(2147483647)))
+		})
 	})
 
 	Describe("BitDepth", func() {
diff --git a/model/metadata/metadata.go b/model/metadata/metadata.go
index 0efbe94ec..7843e7010 100644
--- a/model/metadata/metadata.go
+++ b/model/metadata/metadata.go
@@ -148,15 +148,20 @@ func (md Metadata) tuple(key model.TagName) (int, int) {
 		return 0, 0
 	}
 	tuple := strings.Split(tag, "/")
-	t1, t2 := 0, 0
-	t1, _ = strconv.Atoi(tuple[0])
+	total := md.first(key + "total")
 	if len(tuple) > 1 {
-		t2, _ = strconv.Atoi(tuple[1])
-	} else {
-		t2tag := md.first(key + "total")
-		t2, _ = strconv.Atoi(t2tag)
+		total = tuple[1]
 	}
-	return t1, t2
+	return tagNumber(tuple[0]), tagNumber(total)
+}
+
+// tagNumber rejects negatives and values above int32, so the DB stays readable by 32-bit builds.
+func tagNumber(s string) int {
+	v, err := strconv.ParseInt(s, 10, 32)
+	if err != nil || v < 0 {
+		return 0
+	}
+	return int(v)
 }
 
 var dateRegex = regexp.MustCompile(`([12]\d\d\d)`)
diff --git a/model/metadata/metadata_test.go b/model/metadata/metadata_test.go
index 09a2dfde0..c84d93981 100644
--- a/model/metadata/metadata_test.go
+++ b/model/metadata/metadata_test.go
@@ -226,6 +226,10 @@ var _ = Describe("Metadata", func() {
 			Entry(nil, "2/10", "", 2, 10),
 			Entry(nil, "", "", 0, 0),
 			Entry(nil, "A", "", 0, 0),
+			Entry("ignores values that do not fit in 32 bits", "4294967295", "4294967296", 0, 0),
+			Entry("ignores a total that does not fit in 32 bits", "2/4294967295", "", 2, 0),
+			Entry("keeps the largest 32-bit value", "2147483647", "", 2147483647, 0),
+			Entry("ignores negative values", "-1", "-2", 0, 0),
 		)
 
 		Describe("Performers", func() {

From a3f41fb422dee23036fd45ead569f0c278a036a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adri=C3=A1n=20S=C3=A1nchez=20Zapico?=
 <zapisanchez@users.noreply.github.com>
Date: Wed, 23 Sep 2026 15:47:16 +0200
Subject: [PATCH 172/200] sec(server): sanitize user-controlled filenames in
 Content-Disposition (#5895)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* sec(server): sanitize user-controlled filenames in Content-Disposition

Playlist export, Subsonic download and public share download built the
Content-Disposition header by interpolating a user-controlled name into a
quoted-string with fmt.Sprintf. A name containing a double quote closes the
string early and the rest is parsed as additional parameters, so a playlist
named `party"; filename="evil.html` yielded

    attachment; filename="party"; filename="evil.html.m3u"

letting whoever chose the name decide what the browser saves the download as.
The names come from playlists, album/artist names and media file tags.

Go's net/http already rewrites CR and LF in header values to spaces, so
response splitting was not reachable; parameter injection was.

Add str.ContentDispositionAttachment, which emits a sanitized ASCII-only
quoted `filename` plus an RFC 5987 `filename*` carrying the original UTF-8
name, and use it at all four call sites. The `filename*` parameter also fixes
non-ASCII names, which previously went out raw or were mangled by sanitizing.

Signed-off-by: zapisanchez <zapisanchez@gmail.com>

* fix(server): keep download names intact and sanitize filename*

Rework ContentDispositionAttachment after review. Names with no ASCII
letters now fall back to download.<ext> instead of a bare extension
(東京.mp3 gave filename="mp3"). filename* is built from the same
sanitized name as the ASCII fallback, so path separators, reserved
characters, control and bidi characters, and invalid UTF-8 no longer
reach it. The ASCII fallback transliterates accents and typographic
punctuation (Legião -> Legiao, She’s -> She's) through the existing
sanitize.Accents and str.Clear helpers, keeps leading dots, and only
trims trailing ones. Names are capped at 255 bytes, keeping the
extension.

Pure ASCII names now get only the quoted filename parameter, so the
header for them matches the previous output byte for byte. filename*
is encoded with mime.FormatMediaType instead of a hand-written RFC 5987
encoder. Adds tests for the M3U export and Subsonic download headers.

* fix(server): handle dot-only names and long fake extensions

A name made only of dots trimmed down to an empty filename. It now
falls back to download, like an empty stem does.

path.Ext treats anything after the last dot as the extension, so a long
suffix with no real extension was kept whole and replaced the stem with
download, going past the 255-byte cap. Suffixes longer than 16 bytes
are now treated as part of the stem and truncated with it.

Neither case is reachable from the current call sites, which always
append a short extension.

---------

Signed-off-by: zapisanchez <zapisanchez@gmail.com>
Co-authored-by: Deluan <deluan@navidrome.org>
---
 server/nativeapi/playlists.go                 |   4 +-
 server/nativeapi/playlists_test.go            |  40 ++++++
 server/public/handle_downloads.go             |   7 +-
 server/public/handle_downloads_test.go        |  21 +++
 .../e2e/subsonic_media_retrieval_test.go      |   4 +-
 server/subsonic/stream.go                     |  10 +-
 utils/str/content_disposition.go              |  80 ++++++++++++
 utils/str/content_disposition_test.go         | 120 ++++++++++++++++++
 8 files changed, 271 insertions(+), 15 deletions(-)
 create mode 100644 utils/str/content_disposition.go
 create mode 100644 utils/str/content_disposition_test.go

diff --git a/server/nativeapi/playlists.go b/server/nativeapi/playlists.go
index d215eb9dd..00c1575a5 100644
--- a/server/nativeapi/playlists.go
+++ b/server/nativeapi/playlists.go
@@ -16,6 +16,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/req"
+	"github.com/navidrome/navidrome/utils/str"
 )
 
 type restHandler = func(rest.RepositoryConstructor, ...rest.Logger) http.HandlerFunc
@@ -101,8 +102,7 @@ func handleExportPlaylist(pls playlists.Playlists) http.HandlerFunc {
 
 		log.Debug(ctx, "Exporting playlist as M3U", "playlistId", plsId, "name", playlist.Name)
 		w.Header().Set("Content-Type", "audio/x-mpegurl")
-		disposition := fmt.Sprintf("attachment; filename=\"%s.m3u\"", playlist.Name)
-		w.Header().Set("Content-Disposition", disposition)
+		w.Header().Set("Content-Disposition", str.ContentDispositionAttachment(playlist.Name+".m3u"))
 
 		_, err = w.Write([]byte(playlist.ToM3U8())) //nolint:gosec
 		if err != nil {
diff --git a/server/nativeapi/playlists_test.go b/server/nativeapi/playlists_test.go
index 2f6c578f9..349b4a662 100644
--- a/server/nativeapi/playlists_test.go
+++ b/server/nativeapi/playlists_test.go
@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/deluan/rest"
+	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
@@ -183,6 +184,37 @@ var _ = Describe("Playlist Tracks Endpoint", func() {
 	})
 })
 
+var _ = Describe("handleExportPlaylist", func() {
+	export := func(name string) *httptest.ResponseRecorder {
+		r := chi.NewRouter()
+		r.Get("/playlist/{playlistId}", handleExportPlaylist(&mockPlaylistsService{
+			playlist: &model.Playlist{ID: "pls-1", Name: name},
+		}))
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, httptest.NewRequest("GET", "/playlist/pls-1", nil))
+		return w
+	}
+
+	It("names the download after the playlist", func() {
+		w := export("Road Trip")
+
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="Road Trip.m3u"`))
+	})
+
+	It("does not let the playlist name inject a second filename parameter", func() {
+		w := export(`party"; filename="evil.html`)
+
+		Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="party_; filename=_evil.html.m3u"`))
+	})
+
+	It("keeps non-ASCII names in filename*", func() {
+		w := export("Кино")
+
+		Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="download.m3u"; filename*=utf-8''%D0%9A%D0%B8%D0%BD%D0%BE.m3u`))
+	})
+})
+
 var _ = Describe("writePlaylistError", func() {
 	DescribeTable("maps a service error to an HTTP status",
 		func(err error, expected int) {
@@ -231,6 +263,7 @@ func (m *mockPlaylistTrackRepo) Read(id string) (any, error) {
 type mockPlaylistsService struct {
 	playlists.Playlists
 	tracksRepo    rest.Repository
+	playlist      *model.Playlist
 	removeImageFn func(ctx context.Context, id string) error
 	setImageFn    func(ctx context.Context, id string, reader io.Reader, ext string) error
 }
@@ -249,6 +282,13 @@ func (m *mockPlaylistsService) SetImage(ctx context.Context, id string, reader i
 	return model.ErrNotFound
 }
 
+func (m *mockPlaylistsService) GetWithTracks(_ context.Context, _ string) (*model.Playlist, error) {
+	if m.playlist == nil {
+		return nil, model.ErrNotFound
+	}
+	return m.playlist, nil
+}
+
 func (m *mockPlaylistsService) TracksRepository(_ context.Context, _ string, _ bool) rest.Repository {
 	return m.tracksRepo
 }
diff --git a/server/public/handle_downloads.go b/server/public/handle_downloads.go
index 0012c4b35..e50d7609a 100644
--- a/server/public/handle_downloads.go
+++ b/server/public/handle_downloads.go
@@ -2,9 +2,7 @@ package public
 
 import (
 	"cmp"
-	"fmt"
 	"net/http"
-	"strings"
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/req"
@@ -31,9 +29,8 @@ func (pub *Router) handleDownloads(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	name := str.SanitizeFilename(cmp.Or(s.Description, s.ID))
-	name = strings.ReplaceAll(name, ",", "_")
-	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", name+".zip"))
+	name := cmp.Or(s.Description, s.ID)
+	w.Header().Set("Content-Disposition", str.ContentDispositionAttachment(name+".zip"))
 	w.Header().Set("Content-Type", "application/zip")
 
 	err = pub.archiver.ZipShare(ctx, s, w)
diff --git a/server/public/handle_downloads_test.go b/server/public/handle_downloads_test.go
index 1a97f4379..d2118f47e 100644
--- a/server/public/handle_downloads_test.go
+++ b/server/public/handle_downloads_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"io"
+	"mime"
 	"net/http"
 	"net/http/httptest"
 	"time"
@@ -95,6 +96,26 @@ var _ = Describe("handleDownloads", func() {
 		Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="AC_DC_ Live_ 1979.zip"`))
 	})
 
+	It("sanitizes the UTF-8 filename* as well", func() {
+		shareIs(&model.Share{ID: "abc123", Description: "Sigur Rós/Live", Downloadable: true})
+
+		w := makeRequest("abc123")
+
+		Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="Sigur Ros_Live.zip"; filename*=utf-8''Sigur%20R%C3%B3s_Live.zip`))
+	})
+
+	It("does not let the share description inject a second filename parameter", func() {
+		shareIs(&model.Share{ID: "abc123", Description: `mix"; filename="evil.html`, Downloadable: true})
+
+		w := makeRequest("abc123")
+
+		disposition := w.Header().Get("Content-Disposition")
+		Expect(disposition).ToNot(ContainSubstring(`filename="evil.html`))
+		_, params, err := mime.ParseMediaType(disposition)
+		Expect(err).ToNot(HaveOccurred())
+		Expect(params["filename"]).To(Equal(`mix_; filename=_evil.html.zip`))
+	})
+
 	It("returns 403 without invoking the archiver when the share is not downloadable", func() {
 		shareIs(&model.Share{ID: "abc123", Description: "No Download", Downloadable: false})
 
diff --git a/server/subsonic/e2e/subsonic_media_retrieval_test.go b/server/subsonic/e2e/subsonic_media_retrieval_test.go
index 079b131ff..268d93b82 100644
--- a/server/subsonic/e2e/subsonic_media_retrieval_test.go
+++ b/server/subsonic/e2e/subsonic_media_retrieval_test.go
@@ -106,7 +106,7 @@ var _ = Describe("Media Retrieval Endpoints", Ordered, func() {
 	})
 
 	Describe("Download", func() {
-		var trackID string
+		var trackID, trackTitle string
 
 		BeforeAll(func() {
 			// All test tracks are mp3 at 320kbps
@@ -114,6 +114,7 @@ var _ = Describe("Media Retrieval Endpoints", Ordered, func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			trackID = songs[0].ID
+			trackTitle = songs[0].Title
 		})
 
 		It("returns error when id parameter is missing", func() {
@@ -143,6 +144,7 @@ var _ = Describe("Media Retrieval Endpoints", Ordered, func() {
 			Expect(w.Code).To(Equal(http.StatusOK))
 			Expect(streamerSpy.LastRequest.Format).To(Equal("opus"))
 			Expect(streamerSpy.LastRequest.BitRate).To(Equal(128))
+			Expect(w.Header().Get("Content-Disposition")).To(Equal(`attachment; filename="` + trackTitle + `.opus"`))
 		})
 
 		It("returns error when downloads are disabled", func() {
diff --git a/server/subsonic/stream.go b/server/subsonic/stream.go
index 28b4585f0..b4a6b821c 100644
--- a/server/subsonic/stream.go
+++ b/server/subsonic/stream.go
@@ -3,10 +3,8 @@ package subsonic
 import (
 	"context"
 	"errors"
-	"fmt"
 	"net/http"
 	"strconv"
-	"strings"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/core/stream"
@@ -15,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/subsonic/responses"
 	"github.com/navidrome/navidrome/utils/req"
+	"github.com/navidrome/navidrome/utils/str"
 )
 
 func (api *Router) Stream(w http.ResponseWriter, r *http.Request) (*responses.Subsonic, error) {
@@ -94,9 +93,7 @@ func (api *Router) Download(w http.ResponseWriter, r *http.Request) (*responses.
 	}
 
 	setHeaders := func(name string) {
-		name = strings.ReplaceAll(name, ",", "_")
-		disposition := fmt.Sprintf("attachment; filename=\"%s.zip\"", name)
-		w.Header().Set("Content-Disposition", disposition)
+		w.Header().Set("Content-Disposition", str.ContentDispositionAttachment(name+".zip"))
 		w.Header().Set("Content-Type", "application/zip")
 	}
 
@@ -115,8 +112,7 @@ func (api *Router) Download(w http.ResponseWriter, r *http.Request) (*responses.
 			}
 		}()
 
-		disposition := fmt.Sprintf("attachment; filename=\"%s\"", stream.Name())
-		w.Header().Set("Content-Disposition", disposition)
+		w.Header().Set("Content-Disposition", str.ContentDispositionAttachment(stream.Name()))
 
 		_, err = stream.Serve(ctx, w, r)
 		return nil, err
diff --git a/utils/str/content_disposition.go b/utils/str/content_disposition.go
new file mode 100644
index 000000000..34ae8a5c6
--- /dev/null
+++ b/utils/str/content_disposition.go
@@ -0,0 +1,80 @@
+package str
+
+import (
+	"cmp"
+	"fmt"
+	"mime"
+	"path"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+
+	"github.com/deluan/sanitize"
+)
+
+const (
+	maxFilenameBytes  = 255
+	maxExtensionBytes = 16
+	fallbackFilename  = "download"
+)
+
+// ContentDispositionAttachment builds an RFC 6266 attachment header value for a user-controlled filename.
+// Non-ASCII names also get a filename* parameter, which clients prefer over the ASCII fallback.
+func ContentDispositionAttachment(filename string) string {
+	stem, ext := splitFilename(filename)
+	header := fmt.Sprintf("attachment; filename=%q", joinFilename(toASCII(stem), toASCII(ext)))
+	name := joinFilename(stem, ext)
+	if isASCII(name) {
+		return header
+	}
+	// FormatMediaType emits a percent-encoded filename* for non-ASCII values
+	extended := mime.FormatMediaType("attachment", map[string]string{"filename": name})
+	return header + strings.TrimPrefix(extended, "attachment")
+}
+
+func splitFilename(filename string) (stem, ext string) {
+	name := strings.Map(func(r rune) rune {
+		if unicode.IsControl(r) || unicode.Is(unicode.Bidi_Control, r) {
+			return -1
+		}
+		return r
+	}, SanitizeFilename(strings.ToValidUTF8(filename, "_")))
+	ext = path.Ext(name)
+	if len(ext) > maxExtensionBytes {
+		ext = ""
+	}
+	stem = strings.TrimSuffix(name, ext)
+	if limit := maxFilenameBytes - len(ext); len(stem) > limit {
+		for limit > 0 && !utf8.RuneStart(stem[limit]) {
+			limit--
+		}
+		stem = stem[:limit]
+	}
+	return stem, ext
+}
+
+func joinFilename(stem, ext string) string {
+	stem = cmp.Or(strings.TrimSpace(stem), fallbackFilename)
+	return cmp.Or(strings.TrimRight(stem+ext, " ."), fallbackFilename)
+}
+
+func toASCII(s string) string {
+	return strings.Map(func(r rune) rune {
+		switch {
+		case r == ',':
+			return '_'
+		case r >= ' ' && r <= '~':
+			return r
+		}
+		return -1
+	}, sanitize.Accents(SanitizeFilename(Clear(s))))
+}
+
+func isASCII(s string) bool {
+	for i := 0; i < len(s); i++ {
+		if s[i] >= utf8.RuneSelf {
+			return false
+		}
+	}
+	return true
+}
diff --git a/utils/str/content_disposition_test.go b/utils/str/content_disposition_test.go
new file mode 100644
index 000000000..944392a4e
--- /dev/null
+++ b/utils/str/content_disposition_test.go
@@ -0,0 +1,120 @@
+package str_test
+
+import (
+	"mime"
+	"regexp"
+	"strings"
+
+	"github.com/navidrome/navidrome/utils/str"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var asciiFilenameRe = regexp.MustCompile(`(?:^|; )filename="([^"]*)"`)
+
+// asciiName returns the quoted filename parameter, the one used by clients that ignore filename*.
+func asciiName(filename string) string {
+	m := asciiFilenameRe.FindAllStringSubmatch(str.ContentDispositionAttachment(filename), -1)
+	ExpectWithOffset(1, m).To(HaveLen(1), "expected exactly one quoted filename parameter")
+	return m[0][1]
+}
+
+// decodedName returns the name an RFC 6266 client picks, preferring filename* when present.
+func decodedName(filename string) string {
+	disp, params, err := mime.ParseMediaType(str.ContentDispositionAttachment(filename))
+	ExpectWithOffset(1, err).ToNot(HaveOccurred())
+	ExpectWithOffset(1, disp).To(Equal("attachment"))
+	return params["filename"]
+}
+
+var _ = Describe("ContentDispositionAttachment", func() {
+	Describe("parameter injection", func() {
+		const attack = `party"; filename="evil.html.m3u`
+
+		It("does not let a quote in the name open a second parameter", func() {
+			Expect(str.ContentDispositionAttachment(attack)).To(Equal(`attachment; filename="party_; filename=_evil.html.m3u"`))
+		})
+
+		It("keeps the header parseable", func() {
+			Expect(decodedName(attack)).To(Equal("party_; filename=_evil.html.m3u"))
+		})
+
+		It("does not let a quote in a non-ASCII name inject either", func() {
+			const utf8Attack = `東京"; filename="evil.html.m3u`
+			header := str.ContentDispositionAttachment(utf8Attack)
+			Expect(strings.Count(header, `"`)).To(Equal(2))
+			Expect(decodedName(utf8Attack)).To(Equal("東京_; filename=_evil.html.m3u"))
+		})
+	})
+
+	Describe("ASCII names", func() {
+		It("sends only the quoted filename, unchanged", func() {
+			Expect(str.ContentDispositionAttachment("My Playlist.m3u")).To(Equal(`attachment; filename="My Playlist.m3u"`))
+		})
+
+		It("keeps leading dots", func() {
+			Expect(asciiName("...And Justice for All.zip")).To(Equal("...And Justice for All.zip"))
+		})
+
+		It("trims surrounding spaces and trailing dots", func() {
+			Expect(asciiName("  Greatest Hits  .zip")).To(Equal("Greatest Hits.zip"))
+			Expect(asciiName("Loose End. ")).To(Equal("Loose End"))
+		})
+
+		It("falls back to a placeholder when only dots are left", func() {
+			Expect(str.ContentDispositionAttachment("...")).To(Equal(`attachment; filename="download"`))
+		})
+
+		It("caps a long name whose last dot is not an extension", func() {
+			name := asciiName("a." + strings.Repeat("x", 300))
+			Expect(len(name)).To(BeNumerically("<=", 255))
+			Expect(name).To(HavePrefix("a.xxx"))
+		})
+
+		It("replaces path separators and reserved characters", func() {
+			Expect(asciiName("AC/DC: Live, 1979?.zip")).To(Equal("AC_DC_ Live_ 1979_.zip"))
+		})
+
+		It("drops control characters", func() {
+			Expect(asciiName("line\r\nbreak\x00\t.mp3")).To(Equal("linebreak.mp3"))
+		})
+	})
+
+	Describe("non-ASCII names", func() {
+		It("transliterates accents in the ASCII fallback", func() {
+			Expect(asciiName("Legião Urbana.zip")).To(Equal("Legiao Urbana.zip"))
+		})
+
+		It("converts typographic punctuation in the ASCII fallback", func() {
+			Expect(asciiName("She’s a Woman — Live.mp3")).To(Equal("She's a Woman - Live.mp3"))
+			Expect(asciiName("“Heroes”.mp3")).To(Equal("_Heroes_.mp3"))
+			Expect(decodedName("She’s a Woman.mp3")).To(Equal("She’s a Woman.mp3"))
+		})
+
+		It("keeps the extension when no ASCII letters survive", func() {
+			Expect(asciiName("東京.mp3")).To(Equal("download.mp3"))
+			Expect(asciiName("Кино.m3u")).To(Equal("download.m3u"))
+			Expect(asciiName("東京")).To(Equal("download"))
+		})
+
+		DescribeTable("filename* carries the sanitized UTF-8 name",
+			func(filename, expected string) {
+				Expect(decodedName(filename)).To(Equal(expected))
+			},
+			Entry("accented", "Legião Urbana.zip", "Legião Urbana.zip"),
+			Entry("CJK", "東京.zip", "東京.zip"),
+			Entry("emoji", "🎵 mix.zip", "🎵 mix.zip"),
+			Entry("comma and percent", "Sigur Rós, 100%.zip", "Sigur Rós, 100%.zip"),
+			Entry("path separators", "Sigur Rós/Live: Heima.zip", "Sigur Rós_Live_ Heima.zip"),
+			Entry("control characters", "Sigur Rós\r\n\x00.zip", "Sigur Rós.zip"),
+			Entry("bidi override", "Björk\u202Eexe.mp3", "Björkexe.mp3"),
+			Entry("invalid UTF-8", "Bj\xf6rk Café.mp3", "Bj_rk Café.mp3"),
+		)
+
+		It("caps the name length and keeps the extension", func() {
+			name := decodedName(strings.Repeat("東", 300) + ".zip")
+			Expect(len(name)).To(BeNumerically("<=", 255))
+			Expect(name).To(HaveSuffix("東.zip"))
+		})
+	})
+})

From 39028f65c80734fcf8a00b2b40ce210cd3e5ea91 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 23 Sep 2026 09:54:35 -0400
Subject: [PATCH 173/200] fix(jellyfin): honor IsPublic when creating a
 playlist (#6204)

POST /Playlists dropped the client's IsPublic flag, so every playlist was
created private. JellyBox Player's create-playlist form defaults its "public"
checkbox to true, so JellyBox users could never create a public playlist.

Upstream's PlaylistsController passes IsPublic into PlaylistCreationRequest.
core/playlists.Create has no visibility parameter and widening it would ripple
into the Subsonic and native APIs, so createPlaylist follows the same pattern
updatePlaylist already uses: after Create succeeds, a non-nil IsPublic is
applied with a follow-up Update. The field is a pointer so an absent one keeps
today's default instead of forcing private.

If that second write fails the handler surfaces the error through playlistError
rather than returning the id: answering 200 for a playlist that is not as
visible as the client asked is the same silent drop this fixes.
---
 server/jellyfin/e2e/e2e_suite_test.go |  8 +++++-
 server/jellyfin/e2e/playlists_test.go | 22 +++++++++++++----
 server/jellyfin/playlists.go          |  8 ++++++
 server/jellyfin/playlists_test.go     | 35 +++++++++++++++++++++++++++
 4 files changed, 67 insertions(+), 6 deletions(-)

diff --git a/server/jellyfin/e2e/e2e_suite_test.go b/server/jellyfin/e2e/e2e_suite_test.go
index aa93f7e38..5aa38cba1 100644
--- a/server/jellyfin/e2e/e2e_suite_test.go
+++ b/server/jellyfin/e2e/e2e_suite_test.go
@@ -222,8 +222,14 @@ func createPlaylistAs(user model.User, name string, encodedIds ...string) string
 	}
 	body, err := json.Marshal(map[string]any{"Name": name, "Ids": encodedIds})
 	Expect(err).ToNot(HaveOccurred())
+	return createPlaylistBodyAs(user, string(body))
+}
+
+// createPlaylistBodyAs posts a raw create body, for tests that need fields the helpers above don't
+// build, and returns the new playlist's decoded id.
+func createPlaylistBodyAs(user model.User, body string) string {
 	var res map[string]string
-	parseInto(postAs(user, "/Playlists", string(body)), &res)
+	parseInto(postAs(user, "/Playlists", body), &res)
 	Expect(res["Id"]).ToNot(BeEmpty())
 	id, ok := dto.DecodeID(res["Id"])
 	Expect(ok).To(BeTrue())
diff --git a/server/jellyfin/e2e/playlists_test.go b/server/jellyfin/e2e/playlists_test.go
index 174ba8660..3dd53227f 100644
--- a/server/jellyfin/e2e/playlists_test.go
+++ b/server/jellyfin/e2e/playlists_test.go
@@ -21,12 +21,19 @@ var _ = Describe("Playlists", func() {
 	}
 	order := func(plID string) []string { return names(playlistItems(plID).Items) }
 
+	createWith := func(body string) string { return createPlaylistBodyAs(adminUser, body) }
+	openAccess := func(plID string) bool {
+		var info dto.PlaylistInfo
+		parseInto(get("/Playlists/"+enc(plID)), &info)
+		return info.OpenAccess
+	}
+
 	Describe("create", func() {
 		It("creates an empty playlist", func() {
 			plID := createPlaylist("Empty", nil)
 			var info dto.PlaylistInfo
 			parseInto(get("/Playlists/"+enc(plID)), &info)
-			Expect(info.OpenAccess).To(BeFalse())
+			Expect(info.OpenAccess).To(BeFalse(), "a playlist created without IsPublic stays private")
 			Expect(info.Shares).To(BeEmpty())
 			Expect(info.ItemIds).To(BeEmpty())
 		})
@@ -48,6 +55,14 @@ var _ = Describe("Playlists", func() {
 			Expect(playlistItems(plID).TotalRecordCount).To(Equal(3)) // Abbey Road (2) + Help! (1)
 		})
 
+		It("creates a public playlist when the client sends IsPublic true", func() {
+			Expect(openAccess(createWith(`{"Name":"Public","Ids":[],"IsPublic":true}`))).To(BeTrue())
+		})
+
+		It("creates a private playlist when the client sends IsPublic false", func() {
+			Expect(openAccess(createWith(`{"Name":"Private","Ids":[],"IsPublic":false}`))).To(BeFalse())
+		})
+
 		// dto.DecodeIDs is all-or-nothing: a malformed entry must 404 the whole request, not get
 		// dropped while the well-formed entries are still used to create a playlist.
 		It("404s when one of the Ids is malformed, without creating a playlist", func() {
@@ -355,10 +370,7 @@ var _ = Describe("Playlists", func() {
 		It("makes a playlist public", func() {
 			plID := createPlaylist("Make Public", nil)
 			Expect(post("/Playlists/"+enc(plID), `{"Name":"Make Public","IsPublic":true}`).Code).To(Equal(http.StatusNoContent))
-
-			var info dto.PlaylistInfo
-			parseInto(get("/Playlists/"+enc(plID)), &info)
-			Expect(info.OpenAccess).To(BeTrue())
+			Expect(openAccess(plID)).To(BeTrue())
 			// Now visible to other users.
 			Expect(queryResult(getAs(regularUser, "/Items?IncludeItemTypes=Playlist&Recursive=true")).TotalRecordCount).To(Equal(1))
 		})
diff --git a/server/jellyfin/playlists.go b/server/jellyfin/playlists.go
index 1052a398f..5fd2df8c9 100644
--- a/server/jellyfin/playlists.go
+++ b/server/jellyfin/playlists.go
@@ -48,6 +48,7 @@ type createPlaylistRequest struct {
 	Name      string   `json:"Name"`
 	Ids       []string `json:"Ids"`
 	MediaType string   `json:"MediaType"`
+	IsPublic  *bool    `json:"IsPublic"`
 }
 
 // createPlaylist always creates a new playlist (playlistId "" tells core/playlists.Create not to
@@ -69,6 +70,13 @@ func (api *Router) createPlaylist(w http.ResponseWriter, r *http.Request) {
 		api.internalError(w, r, err)
 		return
 	}
+	// Create takes no visibility, so a requested one costs a second write.
+	if body.IsPublic != nil {
+		if err := api.playlists.Update(r.Context(), id, nil, nil, body.IsPublic, nil, nil); err != nil {
+			api.playlistError(w, r, err)
+			return
+		}
+	}
 	api.ok(w, r, map[string]string{"Id": dto.EncodeID(id)})
 }
 
diff --git a/server/jellyfin/playlists_test.go b/server/jellyfin/playlists_test.go
index ae0a5da3c..edaa63dd1 100644
--- a/server/jellyfin/playlists_test.go
+++ b/server/jellyfin/playlists_test.go
@@ -55,6 +55,16 @@ type fakePlaylists struct {
 
 	deletePlaylistID string
 	deleteErr        error
+
+	updatePlaylistID string
+	updatePublic     *bool
+	updateErr        error
+}
+
+func (f *fakePlaylists) Update(_ context.Context, playlistID string, _ *string, _ *string, public *bool, _ []string, _ []int) error {
+	f.updatePlaylistID = playlistID
+	f.updatePublic = public
+	return f.updateErr
 }
 
 func (f *fakePlaylists) Delete(_ context.Context, id string) error {
@@ -184,6 +194,31 @@ var _ = Describe("Playlists", func() {
 			invoke(api.createPlaylist, w, r)
 			Expect(w.Code).To(Equal(http.StatusInternalServerError))
 		})
+
+		createReq := func(body string) *http.Request {
+			return httptest.NewRequest("POST", "/Playlists", strings.NewReader(body)).
+				WithContext(GinkgoT().Context())
+		}
+
+		DescribeTable("visibility",
+			func(body string, wantPublic *bool, wantUpdatedID string) {
+				w := httptest.NewRecorder()
+				invoke(api.createPlaylist, w, createReq(body))
+				Expect(w.Code).To(Equal(http.StatusOK))
+				Expect(fp.updatePublic).To(Equal(wantPublic))
+				Expect(fp.updatePlaylistID).To(Equal(wantUpdatedID))
+			},
+			Entry("applies IsPublic true", `{"Name":"Mix","IsPublic":true}`, new(true), testID("pl-new")),
+			Entry("applies an explicit IsPublic false", `{"Name":"Mix","IsPublic":false}`, new(false), testID("pl-new")),
+			Entry("leaves visibility alone when IsPublic is omitted", `{"Name":"Mix"}`, nil, ""),
+		)
+
+		It("returns 500 when the visibility update fails", func() {
+			fp.updateErr = errors.New("boom")
+			w := httptest.NewRecorder()
+			invoke(api.createPlaylist, w, createReq(`{"Name":"Mix","IsPublic":true}`))
+			Expect(w.Code).To(Equal(http.StatusInternalServerError))
+		})
 	})
 
 	Describe("getPlaylistItems", func() {

From 27483a46dcda604b5e494b3b2010b617878e0593 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adri=C3=A1n=20S=C3=A1nchez=20Zapico?=
 <zapisanchez@users.noreply.github.com>
Date: Wed, 23 Sep 2026 18:10:25 +0200
Subject: [PATCH 174/200] fix(server): fail startup on initial setup errors and
 fix JSON/M3U response headers (#5897)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(server): stop swallowing errors and correct two response bugs

Four independent bugs found while reviewing the HTTP layer:

initial_setup.go: createInitialAdminUser assigned the users.Put error to a
shadowed err, so the outer err (always nil by then, since a CountAll failure
panics) was returned instead. A failure to create the admin user was reported
as success, and initialSetup went on to commit the "setup complete" property
in the same transaction — so no admin user existed and initial setup was
skipped on every later boot.

auth.go: createAdminUser logged the Put error but returned nil, so createAdmin
fell through to doLogin and answered 401 "Invalid username or password"
instead of surfacing the real failure. It also logged the whole model.User,
which puts the new admin's password in the log in clear text; every other call
site logs user.UserName.

native_api.go: writeDeleteManyResponse did not return after http.Error when
marshaling failed, then wrote a nil body over the 500. It also built the
single-id body by hand with html.EscapeString, which does not escape
backslashes, so an id ending in one produced `{"id":"a\"}` — invalid JSON.
Both shapes now go through json.Marshal. A failed Write is now logged rather
than answered with http.Error, which could not work once the body had started.

handle_shares.go: handleM3U set Content-Type after WriteHeader, so it was
never sent and shared playlists were served with a sniffed type.

Signed-off-by: zapisanchez <zapisanchez@gmail.com>

* fix(server): address review feedback

- writeDeleteManyResponse uses rest.RespondWithJSON, so the response now
  has Content-Type: application/json. This also removes a marshal error
  branch that could never run.
- createInitialAdminUser returns the CountAll error instead of panicking,
  and wraps its errors. initialSetup now stops the server with log.Fatal
  when setup fails. Before, the error was dropped and the server started
  with a half-done setup.
- Trim comments that described PR history.

---------

Signed-off-by: zapisanchez <zapisanchez@gmail.com>
Co-authored-by: Deluan <deluan@navidrome.org>
---
 server/auth.go                                |  2 +-
 server/auth_test.go                           | 12 +++++
 server/initial_setup.go                       | 14 ++---
 server/initial_setup_test.go                  | 23 ++++++++
 server/nativeapi/delete_many_response_test.go | 49 +++++++++++++++++
 server/nativeapi/native_api.go                | 22 +++-----
 server/public/handle_shares.go                |  2 +-
 server/public/handle_shares_test.go           | 52 +++++++++++++++++++
 8 files changed, 154 insertions(+), 22 deletions(-)
 create mode 100644 server/nativeapi/delete_many_response_test.go
 create mode 100644 server/public/handle_shares_test.go

diff --git a/server/auth.go b/server/auth.go
index d9ade7b29..2aaa93e63 100644
--- a/server/auth.go
+++ b/server/auth.go
@@ -159,7 +159,7 @@ func createAdminUser(ctx context.Context, ds model.DataStore, username, password
 	}
 	err := ds.User(ctx).Put(&initialUser)
 	if err != nil {
-		log.Error(ctx, "Could not create initial user", "user", initialUser, err)
+		log.Error(ctx, "Could not create initial user", "user", initialUser.UserName, err)
 		return fmt.Errorf("creating initial user: %w", err)
 	}
 	return nil
diff --git a/server/auth_test.go b/server/auth_test.go
index a4d592c51..abe144a12 100644
--- a/server/auth_test.go
+++ b/server/auth_test.go
@@ -76,6 +76,18 @@ var _ = Describe("Auth", func() {
 			})
 		})
 
+		Describe("createAdmin when the user cannot be stored", func() {
+			It("responds 500 rather than falling through to login", func() {
+				failing := dsWithFailingPut(errors.New("db is down"))
+				req = httptest.NewRequest("POST", "/createAdmin", strings.NewReader(`{"username":"johndoe", "password":"secret"}`))
+				resp = httptest.NewRecorder()
+
+				createAdmin(failing)(resp, req)
+
+				Expect(resp.Code).To(Equal(http.StatusInternalServerError))
+			})
+		})
+
 		Describe("Login from HTTP headers", func() {
 			const (
 				trustedIpv4   = "192.168.0.42"
diff --git a/server/initial_setup.go b/server/initial_setup.go
index 7e974dc21..e75220abe 100644
--- a/server/initial_setup.go
+++ b/server/initial_setup.go
@@ -16,7 +16,7 @@ import (
 
 func initialSetup(ds model.DataStore) {
 	ctx := context.TODO()
-	_ = ds.WithTx(func(tx model.DataStore) error {
+	err := ds.WithTx(func(tx model.DataStore) error {
 		if err := tx.Library(ctx).StoreMusicFolder(); err != nil {
 			return err
 		}
@@ -36,6 +36,9 @@ func initialSetup(ds model.DataStore) {
 		err = properties.Put(consts.InitialSetupFlagKey, time.Now().String())
 		return err
 	}, "initial setup")
+	if err != nil {
+		log.Fatal("Error running initial setup", err)
+	}
 }
 
 // If the Dev Admin user is not present, create it
@@ -43,7 +46,7 @@ func createInitialAdminUser(ds model.DataStore, initialPassword string) error {
 	users := ds.User(context.TODO())
 	c, err := users.CountAll(model.QueryOptions{Filters: squirrel.Eq{"user_name": consts.DevInitialUserName}})
 	if err != nil {
-		panic(fmt.Sprintf("Could not access User table: %s", err))
+		return fmt.Errorf("could not access User table: %w", err)
 	}
 	if c == 0 {
 		newID := id.NewRandom()
@@ -57,12 +60,11 @@ func createInitialAdminUser(ds model.DataStore, initialPassword string) error {
 			NewPassword: initialPassword,
 			IsAdmin:     true,
 		}
-		err := users.Put(&initialUser)
-		if err != nil {
-			log.Error("Could not create initial admin user", "user", initialUser, err)
+		if err := users.Put(&initialUser); err != nil {
+			return fmt.Errorf("could not create initial admin user: %w", err)
 		}
 	}
-	return err
+	return nil
 }
 
 func checkFFmpegInstallation() {
diff --git a/server/initial_setup_test.go b/server/initial_setup_test.go
index 982046f78..0ce8a39fa 100644
--- a/server/initial_setup_test.go
+++ b/server/initial_setup_test.go
@@ -2,6 +2,7 @@ package server
 
 import (
 	"context"
+	"errors"
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
@@ -9,6 +10,17 @@ import (
 	. "github.com/onsi/gomega"
 )
 
+type failingPutUserRepo struct {
+	model.UserRepository
+	err error
+}
+
+func (r *failingPutUserRepo) Put(*model.User) error { return r.err }
+
+func dsWithFailingPut(err error) model.DataStore {
+	return &tests.MockDataStore{MockedUser: &failingPutUserRepo{UserRepository: tests.CreateMockUserRepo(), err: err}}
+}
+
 var _ = Describe("initial_setup", func() {
 	var ds model.DataStore
 
@@ -32,5 +44,16 @@ var _ = Describe("initial_setup", func() {
 			Expect(createInitialAdminUser(ds, "second")).To(BeNil())
 			Expect(ur.CountAll()).To(Equal(int64(1)))
 		})
+
+		It("returns the error when the user cannot be stored", func() {
+			boom := errors.New("db is down")
+			Expect(createInitialAdminUser(dsWithFailingPut(boom), "pass123")).To(MatchError(boom))
+		})
+
+		It("returns the error when the user table cannot be read", func() {
+			boom := errors.New("db is down")
+			ds = &tests.MockDataStore{MockedUser: &tests.MockedUserRepo{Error: boom}}
+			Expect(createInitialAdminUser(ds, "pass123")).To(MatchError(boom))
+		})
 	})
 })
diff --git a/server/nativeapi/delete_many_response_test.go b/server/nativeapi/delete_many_response_test.go
new file mode 100644
index 000000000..7d911d6cd
--- /dev/null
+++ b/server/nativeapi/delete_many_response_test.go
@@ -0,0 +1,49 @@
+package nativeapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("writeDeleteManyResponse", func() {
+	var w *httptest.ResponseRecorder
+
+	write := func(ids ...string) map[string]any {
+		w = httptest.NewRecorder()
+		writeDeleteManyResponse(w, httptest.NewRequest("DELETE", "/missing", nil), ids)
+
+		var body map[string]any
+		Expect(json.Unmarshal(w.Body.Bytes(), &body)).To(Succeed(), "response body must be valid JSON: %s", w.Body.String())
+		return body
+	}
+
+	It("returns a single id as an object", func() {
+		Expect(write("abc123")).To(HaveKeyWithValue("id", "abc123"))
+	})
+
+	It("returns multiple ids as a list", func() {
+		Expect(write("a", "b")).To(HaveKeyWithValue("ids", ConsistOf("a", "b")))
+	})
+
+	It("stays valid JSON when the id contains a backslash", func() {
+		Expect(write(`a\`)).To(HaveKeyWithValue("id", `a\`))
+	})
+
+	It("stays valid JSON when the id contains a quote", func() {
+		Expect(write(`a"b`)).To(HaveKeyWithValue("id", `a"b`))
+	})
+
+	It("does not HTML-escape the id into entities", func() {
+		Expect(write("a&b")).To(HaveKeyWithValue("id", "a&b"))
+	})
+
+	It("responds 200 with a JSON content type", func() {
+		write("abc123")
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Header().Get("Content-Type")).To(Equal("application/json"))
+	})
+})
diff --git a/server/nativeapi/native_api.go b/server/nativeapi/native_api.go
index f931834c6..a7c53df09 100644
--- a/server/nativeapi/native_api.go
+++ b/server/nativeapi/native_api.go
@@ -2,8 +2,6 @@ package nativeapi
 
 import (
 	"context"
-	"encoding/json"
-	"html"
 	"net/http"
 	"strconv"
 	"time"
@@ -206,22 +204,18 @@ func (api *Router) addMissingFilesRoute(r chi.Router) {
 }
 
 func writeDeleteManyResponse(w http.ResponseWriter, r *http.Request, ids []string) {
-	var resp []byte
-	var err error
+	var payload any
 	if len(ids) == 1 {
-		resp = []byte(`{"id":"` + html.EscapeString(ids[0]) + `"}`)
+		payload = struct {
+			ID string `json:"id"`
+		}{ID: ids[0]}
 	} else {
-		resp, err = json.Marshal(&struct {
+		payload = struct {
 			Ids []string `json:"ids"`
-		}{Ids: ids})
-		if err != nil {
-			log.Error(r.Context(), "Error marshaling response", "ids", ids, err)
-			http.Error(w, err.Error(), http.StatusInternalServerError)
-		}
+		}{Ids: ids}
 	}
-	_, err = w.Write(resp) //nolint:gosec
-	if err != nil {
-		http.Error(w, err.Error(), http.StatusInternalServerError)
+	if err := rest.RespondWithJSON(w, http.StatusOK, payload); err != nil {
+		log.Error(r.Context(), "Error writing response", "ids", ids, err)
 	}
 }
 
diff --git a/server/public/handle_shares.go b/server/public/handle_shares.go
index d67cfe456..367bff501 100644
--- a/server/public/handle_shares.go
+++ b/server/public/handle_shares.go
@@ -58,8 +58,8 @@ func (pub *Router) handleM3U(w http.ResponseWriter, r *http.Request) {
 	}
 
 	s = pub.mapShareToM3U(r, *s)
-	w.WriteHeader(http.StatusOK)
 	w.Header().Set("Content-Type", "audio/x-mpegurl")
+	w.WriteHeader(http.StatusOK)
 	_, _ = w.Write([]byte(s.ToM3U8())) //nolint:gosec
 }
 
diff --git a/server/public/handle_shares_test.go b/server/public/handle_shares_test.go
new file mode 100644
index 000000000..1bf631fd4
--- /dev/null
+++ b/server/public/handle_shares_test.go
@@ -0,0 +1,52 @@
+package public
+
+import (
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("handleM3U", func() {
+	var ds *tests.MockDataStore
+	var shareRepo *tests.MockShareRepo
+	var pub *Router
+
+	BeforeEach(func() {
+		ds = &tests.MockDataStore{}
+		shareRepo = &tests.MockShareRepo{}
+		ds.MockedShare = shareRepo
+		pub = &Router{ds: ds, share: core.NewShare(ds)}
+	})
+
+	makeRequest := func(id string) *httptest.ResponseRecorder {
+		r := httptest.NewRequest("GET", "/public/"+id+"/m3u?%3Aid="+id, nil)
+		w := httptest.NewRecorder()
+		pub.handleM3U(w, r)
+		return w
+	}
+
+	It("sets the M3U content type", func() {
+		share := &model.Share{ID: "abc123", Tracks: model.MediaFiles{{ID: "t1", Title: "Track 1"}}}
+		shareRepo.ID = share.ID
+		shareRepo.Entity = share
+
+		w := makeRequest("abc123")
+
+		Expect(w.Code).To(Equal(http.StatusOK))
+		// Result() has the headers sent at WriteHeader time, unlike w.Header()
+		Expect(w.Result().Header.Get("Content-Type")).To(Equal("audio/x-mpegurl"))
+		Expect(w.Body.String()).To(HavePrefix("#EXTM3U"))
+	})
+
+	It("returns 404 when the share does not exist", func() {
+		shareRepo.ID = "other"
+		shareRepo.Entity = &model.Share{ID: "other"}
+
+		Expect(makeRequest("missing").Code).To(Equal(http.StatusNotFound))
+	})
+})

From ee6dd1bc031154788988c7b62cac18f2a49c67b5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 23 Sep 2026 17:04:50 -0400
Subject: [PATCH 175/200] fix(scanner): stop DB lock starvation during scans on
 slow storage (#6201)

* fix(artwork): pause the artwork worker while a scan is running

The artwork worker added in 0.64 writes to the database continuously, including while a scan runs. On slow storage the scanner holds the write lock for many seconds per folder, so the two writers keep timing each other out: artwork writes fail with "database is locked", and a single busy timeout on the scanner side aborts the whole scan. The worker now stops dispatching queue items while scanner.IsScanning reports true, including mid-batch, and resumes on the next poll after the scan ends. Artwork requests are unaffected, since they serve local art without the worker.

* fix(db): run ANALYZE one index at a time so writers are not starved

A full ANALYZE is a single write transaction, so every other write waits for it to finish and fails after the 15s busy timeout. On slow NAS storage it was measured taking over 26 minutes. The analysis now runs ANALYZE per index (per table for unindexed and WITHOUT ROWID tables), which produces the same sqlite_stat1 rows as a full ANALYZE, and pauses briefly between steps (up to 150ms, just above SQLite's longest busy-handler sleep) so waiting writers get the lock.

* fix(scanner): ignore Synology @eaDir metadata folders

Synology creates an @eaDir folder next to media files, holding one subfolder per file with generated thumbnails. The scanner and watcher treated them as regular folders, which on one reported library added tens of thousands of extra folders to every scan.

* fix(db): analyze tables with only partial indexes as a whole

A partial index does not record the table's row count, so a table whose only indexes are partial needs a table-level ANALYZE to get the sqlite_stat1 row a full ANALYZE would write. Navidrome's schema has no such table today, but the stepped analysis should match a full ANALYZE for any schema a future migration creates.

* fix(scanner): retry busy folder saves and stop phase 1 on a fatal error

On slow storage, a single SQLITE_BUSY while saving a folder aborted the whole scan, even when another writer held the lock only briefly. The folder save now runs as a retryable unit: on a busy error it waits (5s, 10s, 15s) and reruns the transaction, up to three times, before failing. Side effects that do not survive a rollback (the album ID map consumed by persistAlbum, the artwork queue items, the image-change record) are rebuilt per attempt or recorded only after a successful commit.

When a folder save does fail, phase 1 used to keep walking the library and reading tags for every remaining folder, discarding the results, before reporting the error; a reporter saw 40 silent minutes. The walk now stops as soon as the save fails, and the walker honors cancellation instead of blocking on its channel. Because an early stop leaves folders unvisited, phase 1 no longer marks unvisited folders missing when the phase failed; the resumed scan handles them.

* refactor(persistence): move busy retry into DataStore.WithTxRetry

The scanner retried its folder save itself, which meant it had to know SQLite error codes. WithTxRetry now owns that policy: it reruns the block in a fresh transaction on SQLITE_BUSY, up to three times with growing delays, and runs it only once when already inside a transaction, since the outer transaction would still hold the lock. The block receives the context to use, and attempts that will be retried carry a marker so a busy statement in them is logged as a warning; only the final attempt logs errors. The scanner's inner error logs are folded into wrapped errors, so a recovered retry no longer prints error-level lines, and the folder path travels in the log context.

* fix(persistence): join the enclosing transaction in a nested WithTxRetry

Called on a store that is already inside a transaction, WithTxRetry went through WithTx, which opens a second, independent transaction on another connection. That transaction waits on the lock the outer one holds and fails with SQLITE_BUSY, and if it does succeed the outer transaction cannot roll it back. It now runs the block on the enclosing transaction, which owns the lock, the commit and the rollback. Found by a Codex (gpt-6-sol) review.

* fix(scanner): retry the remaining scan writes on a busy database

Every write step after phase 1 still aborted the whole scan on a single SQLITE_BUSY: phase 1 finalize, phase 2 moves and purge, phase 3 album saves and play count refreshes, the deferred playlist import flag, library ScanBegin, GC, the missing-artwork enqueue, tag counts, and the final library update. They now go through WithTxRetry. The phase 2 move had to be made rerun-safe first: it changed the target track's ID inside the transaction, so a rerun would have deleted the moved track itself, and it marked album annotations as handled even when the transaction rolled back. It now works on a copy per attempt and records the annotation reassignment only after a commit.

Artist.RefreshStats is left alone: it updates artists in batches outside a transaction, and one transaction around all of them would hold the write lock for the whole refresh on slow storage. Phase 4 playlist imports go through the playlist service and are left for a follow-up.

* fix(scanner): claim the album before moving its annotations

The rerun-safe moveMatched checked processedAlbumAnnotations before its transaction and marked the album only after the commit. Phase 2 runs same-library and cross-library moves in separate pipeline stages, so two moves into one album could both pass the check; the second would reassign annotations again and overwrite the album's created_at. The album is now claimed under the lock before the transaction, as the old code effectively did, and the claim is released if the move fails so a later move can still reassign. Found by a Codex (gpt-6-sol) review.

* fix(artwork): keep artwork housekeeping from writing during scans

The artwork worker already pauses while a scan runs, but its housekeeping jobs did not: the hourly missing-artwork recheck (a bulk INSERT ... SELECT over albums and artists), the startup run of the same recheck, and the daily prune all kept competing with the scanner for the write lock. They now run through LockForMaintenance, like the scheduled DB analysis: they skip while a scan is running and keep a scan from starting until they finish. Skipping the recheck loses nothing, since each scan with changes queues missing artwork at its end.

* refactor(scanner): log retried step errors once, from the caller

Blocks passed to WithTxRetry still logged their own errors at error level on every attempt, so a busy error that a retry absorbed printed several error lines (GC printed three). They now return wrapped errors and the callers, which already log them, report the final outcome once. Also: drop a leftover variable in phase 1 finalize, check the walk context once, stop repeating the folder field that is already in the log context, stop shadowing finalize's err in phase 3, and format the WithTxRetry scope the same way as WithTx.

* test(scanner): make the scanner suite's temp DB cleanup best effort

Which DB file the process-wide DB handle opens depends on which spec touches it first. When the Scanner container wins the random order, its temp DB stays open until db.Close after RunSpecs, and on Windows removing the temp dir fails with 'being used by another process'. Ginkgo pins that on the container's last spec, which is now one of the busy-database specs. The sibling suites skip Windows for the same reason; this one now removes its temp dir on a best-effort basis instead, so it keeps running there.
---
 cmd/root.go                            |  28 ++-
 core/artwork/worker.go                 |  13 ++
 core/artwork/worker_test.go            |  52 +++++
 db/db.go                               |   6 +
 db/db_test.go                          |  16 ++
 db/optimize.go                         |  56 ++++-
 db/optimize_test.go                    |  37 ++++
 model/datastore.go                     |   3 +
 persistence/persistence.go             |  60 +++++-
 persistence/persistence_test.go        |  73 +++++++
 persistence/sql_base_repository.go     |   4 +
 scanner/phase_1_folders.go             | 280 +++++++++++++------------
 scanner/phase_2_missing_tracks.go      |  97 +++++----
 scanner/phase_2_missing_tracks_test.go | 114 ++++++++++
 scanner/phase_3_refresh_albums.go      |  17 +-
 scanner/phase_4_playlists.go           |   5 +-
 scanner/scanner.go                     |  41 ++--
 scanner/scanner_test.go                |  62 +++++-
 scanner/walk_dir_tree.go               |  13 +-
 scanner/walk_dir_tree_test.go          |   1 +
 tests/mock_data_store.go               |   4 +
 21 files changed, 754 insertions(+), 228 deletions(-)

diff --git a/cmd/root.go b/cmd/root.go
index f632b0425..02cd30240 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -375,10 +375,26 @@ func startPlaybackServer(ctx context.Context) func() error {
 func startArtworkWorker(ctx context.Context, worker *artwork.Worker) func() error {
 	return func() error {
 		log.Info(ctx, "Starting artwork worker")
+		// The scanner writes to the DB for its whole run; competing for the write lock makes both fail.
+		worker.PauseWhile(scanner.IsScanning)
 		return worker.Run(ctx)
 	}
 }
 
+// outsideScan runs a DB maintenance job unless a scan is running, and keeps a scan from starting
+// until it ends; both write to the DB, and competing for the lock can make either fail.
+func outsideScan(ctx context.Context, job string, run func(context.Context) error) {
+	release, ok := scanner.LockForMaintenance()
+	if !ok {
+		log.Debug(ctx, "Skipping "+job+" because a scan is in progress")
+		return
+	}
+	defer release()
+	if err := run(ctx); err != nil {
+		log.Error(ctx, "Error running "+job, err)
+	}
+}
+
 // scheduleArtworkHousekeeping registers the recurring missing-state and prune jobs, and
 // reports an artwork config change without acting on it.
 func scheduleArtworkHousekeeping(ctx context.Context, worker *artwork.Worker) func() error {
@@ -386,26 +402,20 @@ func scheduleArtworkHousekeeping(ctx context.Context, worker *artwork.Worker) fu
 		schedulerInstance := scheduler.GetInstance()
 
 		if _, err := schedulerInstance.Add(consts.ArtworkEnqueueMissingSchedule, func() {
-			if err := worker.EnqueueMissingAll(ctx); err != nil {
-				log.Error(ctx, "Error enqueueing missing artwork rechecks", err)
-			}
+			outsideScan(ctx, "artwork missing-state recheck", worker.EnqueueMissingAll)
 		}); err != nil {
 			log.Error(ctx, "Error scheduling artwork missing-state recheck", err)
 		}
 
 		if _, err := schedulerInstance.Add(consts.ArtworkPruneSchedule, func() {
-			if err := worker.RunPrune(ctx); err != nil {
-				log.Error(ctx, "Error running artwork prune", err)
-			}
+			outsideScan(ctx, "artwork prune", worker.RunPrune)
 		}); err != nil {
 			log.Error(ctx, "Error scheduling artwork prune", err)
 		}
 
 		// Also run the missing-row recheck once at startup so a never-scanned entity is picked up
 		// immediately, not only on the next hourly tick (e.g. after enabling the feature).
-		if err := worker.EnqueueMissingAll(ctx); err != nil {
-			log.Error(ctx, "Error enqueueing missing artwork rechecks", err)
-		}
+		outsideScan(ctx, "artwork missing-state recheck", worker.EnqueueMissingAll)
 
 		if err := worker.ReconcileConfig(ctx); err != nil {
 			log.Error(ctx, "Error checking the artwork config fingerprint", err)
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index bb09be55e..e8fb3a11c 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -46,6 +46,7 @@ type Worker struct {
 	pruneMu sync.RWMutex
 	pools   []*drainPool
 	runCtx  context.Context
+	paused  func() bool
 
 	gatesMu sync.Mutex
 	gates   map[string]*extGate
@@ -59,6 +60,7 @@ func NewWorker(ds model.DataStore, store *ImageStore, ag *agents.Agents, ffmpeg
 		broker: broker,
 		pools:  newDrainPools(),
 		runCtx: context.Background(),
+		paused: func() bool { return false },
 		gates:  map[string]*extGate{},
 	}
 	w.proc.resolver = newResolver(ds, ag, ffmpeg, w.gate)
@@ -90,6 +92,11 @@ var (
 	}
 )
 
+// PauseWhile holds off queue draining whenever paused reports true. Call it before Run.
+func (w *Worker) PauseWhile(paused func() bool) {
+	w.paused = paused
+}
+
 // Run blocks draining the queue until ctx is cancelled.
 func (w *Worker) Run(ctx context.Context) error {
 	w.runCtx = ctx
@@ -143,6 +150,9 @@ func (w *Worker) EnqueueMissingAll(ctx context.Context) error {
 }
 
 func (w *Worker) drain(ctx context.Context, concurrency int, kinds ...string) (int, error) {
+	if w.paused() {
+		return 0, nil
+	}
 	// Dequeue well past the pool size so a slow external lookup never idles the other slots.
 	// DequeueBatch does not mark rows taken, so this is one query per pass, not per slot.
 	items, err := w.proc.ds.ArtworkQueue(ctx).DequeueBatch(max(16, 4*concurrency), kinds...)
@@ -170,6 +180,9 @@ func (w *Worker) drain(ctx context.Context, concurrency int, kinds ...string) (i
 			wg.Wait()
 			return len(items), nil //nolint:nilerr // a cancelled drain is a clean stop, not an error
 		}
+		if w.paused() {
+			break
+		}
 		wg.Go(func() {
 			defer func() { <-sem }()
 			out, got := w.process(ctx, item)
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index ebb8de251..d74e3a5ed 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -866,6 +866,34 @@ var _ = Describe("Worker", func() {
 			}
 		})
 
+		It("stops dispatching and leaves the rest queued when paused mid-batch", func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			albums := model.Albums{}
+			for i := range 8 {
+				id := fmt.Sprintf("alp%d", i)
+				albums = append(albums, model.Album{ID: id, Name: "Album", FolderIDs: []string{"f1"}})
+				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+					ItemKind: "al", ItemID: id, Priority: model.ArtworkPriorityScan,
+				})).To(Succeed())
+			}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(albums)
+			// Pauses as soon as the first item has left the queue.
+			w.PauseWhile(func() bool {
+				n, _ := queueRepo.Count()
+				return n < 8
+			})
+
+			_, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+
+			count, err := queueRepo.Count()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(count).To(Equal(int64(7)), "only the item dispatched before the pause may leave the queue")
+		})
+
 		It("dequeues past the worker pool so one drain covers many items", func() {
 			for i := range 16 {
 				ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: fmt.Sprintf("alb%d", i), Name: "Album"}})
@@ -896,6 +924,30 @@ var _ = Describe("Worker", func() {
 			Eventually(done, time.Second).Should(Receive(BeNil()))
 		})
 
+		It("does not drain the queue while paused", func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
+				{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				ItemKind: "al", ItemID: "al1", Priority: model.ArtworkPriorityScan,
+			})).To(Succeed())
+			w.PauseWhile(func() bool { return true })
+
+			runCtx, cancel := context.WithCancel(ctx)
+			done := make(chan error, 1)
+			go func() { done <- w.Run(runCtx) }()
+			DeferCleanup(func() {
+				cancel()
+				Eventually(done, 2*time.Second).Should(Receive(BeNil()))
+			})
+
+			Consistently(func() any { return findQueued(queueRepo, "al", "al1") }, 300*time.Millisecond).ShouldNot(BeNil())
+		})
+
 		It("does not leak goroutines after Run exits", func() {
 			DeferCleanup(configtest.SetupConfig())
 
diff --git a/db/db.go b/db/db.go
index 685886edb..a9c6c4a15 100644
--- a/db/db.go
+++ b/db/db.go
@@ -133,6 +133,12 @@ func ErrorCodes(err error) (code, extended int, ok bool) {
 	return int(se.Code), int(se.ExtendedCode), true
 }
 
+// IsBusy reports whether err is SQLITE_BUSY, including BUSY_SNAPSHOT, which only a new transaction clears.
+func IsBusy(err error) bool {
+	code, _, ok := ErrorCodes(err)
+	return ok && code == int(sqlite3.ErrBusy)
+}
+
 type statusLogger struct{ numPending int }
 
 func (*statusLogger) Fatalf(format string, v ...any) { log.Fatal(fmt.Sprintf(format, v...)) }
diff --git a/db/db_test.go b/db/db_test.go
index 2ce01dc3d..e3a52e1fb 100644
--- a/db/db_test.go
+++ b/db/db_test.go
@@ -3,8 +3,12 @@ package db_test
 import (
 	"context"
 	"database/sql"
+	"errors"
+	"fmt"
 	"testing"
 
+	"github.com/mattn/go-sqlite3"
+
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/tests"
@@ -19,6 +23,18 @@ func TestDB(t *testing.T) {
 	RunSpecs(t, "DB Suite")
 }
 
+var _ = DescribeTable("IsBusy",
+	func(err error, expected bool) {
+		Expect(db.IsBusy(err)).To(Equal(expected))
+	},
+	Entry("SQLITE_BUSY", sqlite3.Error{Code: sqlite3.ErrBusy}, true),
+	Entry("SQLITE_BUSY_SNAPSHOT", sqlite3.Error{Code: sqlite3.ErrBusy, ExtendedCode: sqlite3.ErrBusySnapshot}, true),
+	Entry("a wrapped SQLITE_BUSY", fmt.Errorf("persisting: %w", sqlite3.Error{Code: sqlite3.ErrBusy}), true),
+	Entry("another SQLite error", sqlite3.Error{Code: sqlite3.ErrConstraint}, false),
+	Entry("a non-SQLite error", errors.New("database is locked"), false),
+	Entry("nil", nil, false),
+)
+
 var _ = Describe("IsSchemaEmpty", func() {
 	var database *sql.DB
 	var ctx context.Context
diff --git a/db/optimize.go b/db/optimize.go
index f46906c4e..aff36e8fd 100644
--- a/db/optimize.go
+++ b/db/optimize.go
@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"strconv"
+	"strings"
 	"sync"
 	"time"
 
@@ -134,16 +135,65 @@ func optimizeAt(ctx context.Context, db *sql.DB, now time.Time) error {
 		return recordAnalyzeError(ctx, db, now, fmt.Errorf("marking ANALYZE pending: %w", err))
 	}
 	log.Debug(ctx, "Refreshing query planner statistics")
-	_, err := db.ExecContext(ctx, "ANALYZE")
-	if err != nil {
+	if err := analyzeInSteps(ctx, db); err != nil {
 		return recordAnalyzeError(ctx, db, now, fmt.Errorf("running ANALYZE: %w", err))
 	}
-	if err = recordAnalyzeSuccess(ctx, db, now); err != nil {
+	if err := recordAnalyzeSuccess(ctx, db, now); err != nil {
 		return recordAnalyzeError(ctx, db, now, err)
 	}
 	return nil
 }
 
+// One ANALYZE per index (whole table if WITHOUT ROWID or lacking a non-partial index) yields the
+// same sqlite_stat1 rows as a full ANALYZE, but frees the write lock between steps.
+const analyzeTargetsSQL = `
+SELECT i.name FROM sqlite_schema i JOIN pragma_table_list t ON t.schema = 'main' AND t.name = i.tbl_name
+WHERE i.type = 'index' AND t.wr = 0 AND EXISTS (SELECT 1 FROM pragma_index_list(t.name) l WHERE l.partial = 0)
+UNION ALL
+SELECT t.name FROM pragma_table_list t
+WHERE t.schema = 'main' AND t.type IN ('table', 'shadow') AND t.name NOT LIKE 'sqlite_%'
+  AND (t.wr = 1 OR NOT EXISTS (SELECT 1 FROM pragma_index_list(t.name) l WHERE l.partial = 0))`
+
+// analyzeMaxYield is just above SQLite's longest busy-handler sleep, so every waiting writer
+// retries during the pause.
+const analyzeMaxYield = 150 * time.Millisecond
+
+func analyzeInSteps(ctx context.Context, db *sql.DB) error {
+	targets, err := analyzeTargets(ctx, db)
+	if err != nil {
+		return err
+	}
+	for _, target := range targets {
+		start := time.Now()
+		if _, err := db.ExecContext(ctx, `ANALYZE "`+strings.ReplaceAll(target, `"`, `""`)+`"`); err != nil {
+			return fmt.Errorf("analyzing %s: %w", target, err)
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(min(time.Since(start), analyzeMaxYield)):
+		}
+	}
+	return nil
+}
+
+func analyzeTargets(ctx context.Context, db *sql.DB) ([]string, error) {
+	rows, err := db.QueryContext(ctx, analyzeTargetsSQL)
+	if err != nil {
+		return nil, fmt.Errorf("listing ANALYZE targets: %w", err)
+	}
+	defer rows.Close()
+	var targets []string
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			return nil, fmt.Errorf("listing ANALYZE targets: %w", err)
+		}
+		targets = append(targets, name)
+	}
+	return targets, rows.Err()
+}
+
 func recordAnalyzeSuccess(ctx context.Context, db *sql.DB, now time.Time) error {
 	tx, err := db.BeginTx(ctx, nil)
 	if err != nil {
diff --git a/db/optimize_test.go b/db/optimize_test.go
index da9b3b9c9..6ad9b9cb4 100644
--- a/db/optimize_test.go
+++ b/db/optimize_test.go
@@ -75,6 +75,43 @@ var _ = Describe("Optimize", func() {
 		Expect(getProperty(consts.DBAnalyzePendingKey)).To(Equal("0"))
 	})
 
+	It("produces the same statistics as a single full ANALYZE", func() {
+		putProperty(consts.DBAnalyzePendingKey, "1")
+		for _, stmt := range []string{
+			"create table unindexed(id integer primary key, v int)",
+			"insert into unindexed(v) select flag from analyze_probe",
+			"create table no_rowid(k text primary key, v int) without rowid",
+			"insert into no_rowid select 'k' || id, id % 7 from analyze_probe",
+			"create index no_rowid_v on no_rowid(v)",
+			"create table partial_only(id integer primary key, v int)",
+			"insert into partial_only(v) select id % 5 from analyze_probe",
+			"create index partial_only_v on partial_only(v) where v = 1",
+			"analyze",
+		} {
+			_, err := database.Exec(stmt)
+			Expect(err).ToNot(HaveOccurred())
+		}
+		statRows := func() []string {
+			rows, err := database.Query("select tbl || '|' || coalesce(idx, '') || '|' || stat from sqlite_stat1 order by 1")
+			Expect(err).ToNot(HaveOccurred())
+			defer rows.Close()
+			var res []string
+			for rows.Next() {
+				var s string
+				Expect(rows.Scan(&s)).To(Succeed())
+				res = append(res, s)
+			}
+			return res
+		}
+		fullAnalyze := statRows()
+		_, err := database.Exec("delete from sqlite_stat1")
+		Expect(err).ToNot(HaveOccurred())
+
+		Expect(db.OptimizeDBAt(ctx, database, now)).To(Succeed())
+
+		Expect(statRows()).To(Equal(fullAnalyze))
+	})
+
 	It("runs when no previous analysis was recorded", func() {
 		ran, err := db.OptimizeDBIfNeeded(ctx, database, now)
 		Expect(err).ToNot(HaveOccurred())
diff --git a/model/datastore.go b/model/datastore.go
index 273ca714b..26687d5d4 100644
--- a/model/datastore.go
+++ b/model/datastore.go
@@ -47,5 +47,8 @@ type DataStore interface {
 
 	WithTx(block func(tx DataStore) error, scope ...string) error
 	WithTxImmediate(block func(tx DataStore) error, scope ...string) error
+	// WithTxRetry runs block in a transaction, rerunning it while SQLite reports the database busy.
+	// For background work only (it can take minutes), and block must be safe to rerun after a rollback.
+	WithTxRetry(ctx context.Context, block func(ctx context.Context, tx DataStore) error, scope ...string) error
 	GC(ctx context.Context, libraryIDs ...int) error
 }
diff --git a/persistence/persistence.go b/persistence/persistence.go
index 9d3a33cfc..589812266 100644
--- a/persistence/persistence.go
+++ b/persistence/persistence.go
@@ -3,6 +3,7 @@ package persistence
 import (
 	"context"
 	"database/sql"
+	"fmt"
 	"reflect"
 	"time"
 
@@ -138,11 +139,15 @@ func (s *SQLStore) Resource(ctx context.Context, m any) model.ResourceRepository
 	return nil
 }
 
-func (s *SQLStore) WithTx(block func(tx model.DataStore) error, scope ...string) error {
-	var msg string
+func scopeLabel(scope []string) string {
 	if len(scope) > 0 {
-		msg = scope[0]
+		return scope[0]
 	}
+	return ""
+}
+
+func (s *SQLStore) WithTx(block func(tx model.DataStore) error, scope ...string) error {
+	msg := scopeLabel(scope)
 	start := time.Now()
 	conn, inTx := s.db.(*dbx.DB)
 	if !inTx {
@@ -177,6 +182,51 @@ func (s *SQLStore) WithTxImmediate(block func(tx model.DataStore) error, scope .
 	}, scope...)
 }
 
+// txRetryDelay spaces out reruns of a busy transaction. Each attempt has already waited out the
+// busy timeout, so WithTxRetry gives up only after a sustained lock.
+var txRetryDelay = 5 * time.Second
+
+const txMaxRetries = 3
+
+func (s *SQLStore) WithTxRetry(ctx context.Context, block func(ctx context.Context, tx model.DataStore) error, scope ...string) error {
+	// Inside a transaction, join it: the outer one holds the lock and owns commit and rollback
+	if _, ok := s.db.(*dbx.DB); !ok {
+		return block(ctx, s)
+	}
+	for attempt := 0; ; attempt++ {
+		attemptCtx := ctx
+		if attempt < txMaxRetries {
+			attemptCtx = withBusyRetry(ctx)
+		}
+		err := s.WithTx(func(tx model.DataStore) error { return block(attemptCtx, tx) }, scope...)
+		if attempt == txMaxRetries || !db.IsBusy(err) {
+			return err
+		}
+		log.Warn(ctx, "Database busy, retrying transaction", "scope", scopeLabel(scope), "attempt", attempt+1, err)
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(time.Duration(attempt+1) * txRetryDelay):
+		}
+	}
+}
+
+type busyRetryKey struct{}
+
+// withBusyRetry marks a transaction attempt that WithTxRetry will rerun, so a busy statement in it
+// is logged as a warning rather than an error.
+func withBusyRetry(ctx context.Context) context.Context {
+	return context.WithValue(ctx, busyRetryKey{}, true)
+}
+
+func hasBusyRetry(ctx context.Context) bool {
+	if ctx == nil {
+		return false
+	}
+	retry, _ := ctx.Value(busyRetryKey{}).(bool)
+	return retry
+}
+
 func (s *SQLStore) GC(ctx context.Context, libraryIDs ...int) error {
 	trace := func(ctx context.Context, msg string, f func() error) func() error {
 		return func() error {
@@ -207,9 +257,9 @@ func (s *SQLStore) GC(ctx context.Context, libraryIDs ...int) error {
 		trace(ctx, "remove orphan playlist tracks", func() error { return s.Playlist(ctx).(*playlistRepository).removeOrphans() }),
 	)
 	if err != nil {
-		log.Error(ctx, "Error tidying up database", err)
+		return fmt.Errorf("tidying up database: %w", err)
 	}
-	return err
+	return nil
 }
 
 func (s *SQLStore) getDBXBuilder() dbx.Builder {
diff --git a/persistence/persistence_test.go b/persistence/persistence_test.go
index 13e56bde1..e13f6a231 100644
--- a/persistence/persistence_test.go
+++ b/persistence/persistence_test.go
@@ -2,7 +2,10 @@ package persistence
 
 import (
 	"context"
+	"errors"
+	"time"
 
+	"github.com/mattn/go-sqlite3"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/model"
 	. "github.com/onsi/ginkgo/v2"
@@ -55,4 +58,74 @@ var _ = Describe("SQLStore", func() {
 			})
 		})
 	})
+
+	Describe("WithTxRetry", func() {
+		busy := sqlite3.Error{Code: sqlite3.ErrBusy}
+		BeforeEach(func() {
+			DeferCleanup(func(d time.Duration) { txRetryDelay = d }, txRetryDelay)
+			txRetryDelay = 0
+		})
+
+		It("reruns a busy transaction from a clean rollback", func() {
+			var attempts []bool
+			err := ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
+				attempts = append(attempts, hasBusyRetry(ctx))
+				Expect(tx.Property(ctx).Put("retry-key", "attempt")).To(Succeed())
+				if len(attempts) < 3 {
+					return busy
+				}
+				return nil
+			})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(attempts).To(Equal([]bool{true, true, true}))
+			Expect(ds.Property(ctx).Get("retry-key")).To(Equal("attempt"))
+		})
+
+		It("gives up after the last retry, which is not marked as retried", func() {
+			var attempts []bool
+			err := ds.WithTxRetry(ctx, func(ctx context.Context, _ model.DataStore) error {
+				attempts = append(attempts, hasBusyRetry(ctx))
+				return busy
+			})
+			Expect(db.IsBusy(err)).To(BeTrue())
+			Expect(attempts).To(Equal([]bool{true, true, true, false}))
+		})
+
+		It("does not rerun on other errors", func() {
+			calls := 0
+			err := ds.WithTxRetry(ctx, func(context.Context, model.DataStore) error {
+				calls++
+				return sqlite3.Error{Code: sqlite3.ErrConstraint}
+			})
+			Expect(err).To(HaveOccurred())
+			Expect(calls).To(Equal(1))
+		})
+
+		It("does not rerun when called inside a transaction", func() {
+			calls := 0
+			err := ds.WithTx(func(tx model.DataStore) error {
+				return tx.WithTxRetry(ctx, func(context.Context, model.DataStore) error {
+					calls++
+					return busy
+				})
+			})
+			Expect(db.IsBusy(err)).To(BeTrue())
+			Expect(calls).To(Equal(1))
+		})
+
+		It("joins the enclosing transaction instead of opening another", func() {
+			rollback := errors.New("rollback")
+			err := ds.WithTx(func(tx model.DataStore) error {
+				Expect(tx.Property(ctx).Put("outer-key", "v")).To(Succeed())
+				Expect(tx.WithTxRetry(ctx, func(ctx context.Context, inner model.DataStore) error {
+					Expect(inner.Property(ctx).Get("outer-key")).To(Equal("v"))
+					return inner.Property(ctx).Put("inner-key", "v")
+				})).To(Succeed())
+				return rollback
+			})
+			Expect(err).To(MatchError(rollback))
+			_, err = ds.Property(ctx).Get("inner-key")
+			Expect(err).To(MatchError(model.ErrNotFound))
+		})
+	})
 })
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index bc841db03..026e42b03 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -643,5 +643,9 @@ func (r sqlRepository) logSQL(sql string, args dbx.Params, err error, rowsAffect
 	if code, extended, ok := db.ErrorCodes(err); ok {
 		fields = append(fields, "sqliteCode", code, "sqliteExtended", extended)
 	}
+	if db.IsBusy(err) && hasBusyRetry(r.ctx) {
+		log.Warn(append(fields, err)...)
+		return
+	}
 	log.Error(append(fields, err)...)
 }
diff --git a/scanner/phase_1_folders.go b/scanner/phase_1_folders.go
index 6107b3316..feefde032 100644
--- a/scanner/phase_1_folders.go
+++ b/scanner/phase_1_folders.go
@@ -45,7 +45,9 @@ func createPhaseFolders(ctx context.Context, state *scanState, ds model.DataStor
 		jobs = append(jobs, job)
 	}
 
-	return &phaseFolders{jobs: jobs, ctx: ctx, ds: ds, state: state, imageChanges: &imageChangeCollector{ds: ds}}
+	walkCtx, stopWalk := context.WithCancelCause(ctx)
+	return &phaseFolders{jobs: jobs, ctx: ctx, walkCtx: walkCtx, stopWalk: stopWalk, ds: ds, state: state,
+		imageChanges: &imageChangeCollector{ds: ds}}
 }
 
 type scanJob struct {
@@ -123,6 +125,8 @@ type phaseFolders struct {
 	jobs             []*scanJob
 	ds               model.DataStore
 	ctx              context.Context
+	walkCtx          context.Context // cancelled when a folder fails to persist, so the walk stops early
+	stopWalk         context.CancelCauseFunc
 	state            *scanState
 	prevAlbumPIDConf string
 	imageChanges     *imageChangeCollector
@@ -144,15 +148,15 @@ func (p *phaseFolders) producer() ppl.Producer[*folderEntry] {
 		var total int64
 		var totalChanged int64
 		for _, job := range p.jobs {
-			if utils.IsCtxDone(p.ctx) {
+			if utils.IsCtxDone(p.walkCtx) {
 				break
 			}
 
-			outputChan, err := walkDirTree(p.ctx, job, job.targetFolders...)
+			outputChan, err := walkDirTree(p.walkCtx, job, job.targetFolders...)
 			if err != nil {
 				log.Warn(p.ctx, "Scanner: Error scanning library", "lib", job.lib.Name, err)
 			}
-			for folder := range pl.ReadOrDone(p.ctx, outputChan) {
+			for folder := range pl.ReadOrDone(p.walkCtx, outputChan) {
 				job.numFolders.Add(1)
 				p.state.sendProgress(&ProgressInfo{
 					LibID:     job.lib.ID,
@@ -208,6 +212,9 @@ func (p *phaseFolders) stages() []ppl.Stage[*folderEntry] {
 
 func (p *phaseFolders) processFolder(entry *folderEntry) (*folderEntry, error) {
 	defer p.measure(entry)()
+	if err := context.Cause(p.walkCtx); err != nil {
+		return entry, err
+	}
 
 	// Load children mediafiles from DB
 	cursor, err := p.ds.MediaFile(p.ctx).GetCursor(model.QueryOptions{
@@ -331,128 +338,129 @@ func (p *phaseFolders) persistChanges(entry *folderEntry) (*folderEntry, error)
 	defer p.measure(entry)()
 	p.state.changesDetected.Store(true)
 
-	// Collect artwork queue items for changed albums/artists, enqueued in the same transaction
-	var queueItems []model.ArtworkQueueItem
-
-	err := p.ds.WithTx(func(tx model.DataStore) error {
-		// Instantiate all repositories just once per folder
-		folderRepo := tx.Folder(p.ctx)
-		tagRepo := tx.Tag(p.ctx)
-		artistRepo := tx.Artist(p.ctx)
-		libraryRepo := tx.Library(p.ctx)
-		albumRepo := tx.Album(p.ctx)
-		mfRepo := tx.MediaFile(p.ctx)
-
-		// A new folder's albums/artists are enqueued below; only pre-existing folders need the diff.
-		if !entry.isNew() {
-			if changed, artistImage := entry.imagesChanged(); changed {
-				p.imageChanges.record(entry.job.lib, imageChangedFolder{
-					id: entry.id, path: entry.path, artistImage: artistImage,
-				})
-			}
-		}
-
-		// Save folder to DB
-		folder := entry.toFolder()
-		err := folderRepo.Put(folder)
-		if err != nil {
-			log.Error(p.ctx, "Scanner: Error persisting folder to DB", "folder", entry.path, err)
-			return err
-		}
-
-		// Save all tags to DB
-		err = tagRepo.Add(entry.job.lib.ID, entry.tags...)
-		if err != nil {
-			log.Error(p.ctx, "Scanner: Error persisting tags to DB", "folder", entry.path, err)
-			return err
-		}
-
-		// Save all new/modified artists to DB. Their information will be incomplete, but they will be refreshed later
-		for i := range entry.artists {
-			err = artistRepo.Put(&entry.artists[i], "name",
-				"mbz_artist_id", "sort_artist_name", "order_artist_name", "full_text", "search_normalized", "updated_at")
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error persisting artist to DB", "folder", entry.path, "artist", entry.artists[i].Name, err)
-				return err
-			}
-			err = libraryRepo.AddArtist(entry.job.lib.ID, entry.artists[i].ID)
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error adding artist to library", "lib", entry.job.lib.ID, "artist", entry.artists[i].Name, err)
-				return err
-			}
-			if entry.artists[i].Name != consts.UnknownArtist && entry.artists[i].Name != consts.VariousArtists {
-				queueItems = append(queueItems, scanArtworkItem(model.KindArtistArtwork, entry.artists[i].ID))
-			}
-		}
-
-		// Save all new/modified albums to DB. Their information will be incomplete, but they will be refreshed later
-		for i := range entry.albums {
-			err = p.persistAlbum(albumRepo, &entry.albums[i], entry.albumIDMap)
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error persisting album to DB", "folder", entry.path, "album", entry.albums[i], err)
-				return err
-			}
-			if entry.albums[i].Name != consts.UnknownAlbum {
-				queueItems = append(queueItems, scanArtworkItem(model.KindAlbumArtwork, entry.albums[i].ID))
-			}
-		}
-
-		// Save all tracks to DB
-		for i := range entry.tracks {
-			err = mfRepo.Put(&entry.tracks[i])
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error persisting mediafile to DB", "folder", entry.path, "track", entry.tracks[i], err)
-				return err
-			}
-		}
-
-		// A re-imported track returns to unresolved so new embedded art is picked up lazily.
-		if len(entry.tracks) > 0 {
-			trackIDs := slice.Map(entry.tracks, func(t model.MediaFile) string { return t.ID })
-			if err := tx.Artwork(p.ctx).DeleteForItems(model.KindMediaFileArtwork, trackIDs); err != nil {
-				log.Warn(p.ctx, "Scanner: could not invalidate media_file artwork", "folder", entry.path, err)
-			}
-		}
-
-		// Mark all missing tracks as not available
-		if len(entry.missingTracks) > 0 {
-			err = mfRepo.MarkMissing(true, entry.missingTracks...)
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error marking missing tracks", "folder", entry.path, err)
-				return err
-			}
-
-			// Touch all albums that have missing tracks, so they get refreshed in later phases
-			groupedMissingTracks := slice.ToMap(entry.missingTracks, func(mf *model.MediaFile) (string, struct{}) {
-				return mf.AlbumID, struct{}{}
-			})
-			albumsToUpdate := slices.Collect(maps.Keys(groupedMissingTracks))
-			err = albumRepo.Touch(albumsToUpdate...)
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error touching album", "folder", entry.path, "albums", albumsToUpdate, err)
-				return err
-			}
-		}
-
-		// Enqueue artwork resolution for changed albums/artists. Never fails the scan.
-		// A full scan re-imports every track, so a re-import is no evidence the art changed.
-		if len(queueItems) > 0 {
-			queue := tx.ArtworkQueue(p.ctx)
-			enqueue := queue.Enqueue
-			if p.state.fullScan {
-				enqueue = queue.EnqueueIfMissing
-			}
-			if err := enqueue(queueItems...); err != nil {
-				log.Warn(p.ctx, "Scanner: could not enqueue artwork resolution", "folder", entry.path, err)
-			}
-		}
-		return nil
+	ctx := log.NewContext(p.ctx, "folder", entry.path)
+	err := p.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
+		return p.persistFolder(ctx, tx, entry)
 	}, "scanner: persist changes")
 	if err != nil {
-		log.Error(p.ctx, "Scanner: Error persisting changes to DB", "folder", entry.path, err)
+		log.Error(ctx, "Scanner: Error persisting changes to DB", err)
+		p.stopWalk(err)
+		return entry, err
 	}
 
-	return entry, err
+	// A new folder's albums/artists were enqueued with it; only pre-existing folders need the diff.
+	if !entry.isNew() {
+		if changed, artistImage := entry.imagesChanged(); changed {
+			p.imageChanges.record(entry.job.lib, imageChangedFolder{
+				id: entry.id, path: entry.path, artistImage: artistImage,
+			})
+		}
+	}
+	return entry, nil
+}
+
+// persistFolder writes the folder in tx. WithTxRetry may rerun it after a rollback.
+func (p *phaseFolders) persistFolder(ctx context.Context, tx model.DataStore, entry *folderEntry) error {
+	// Collect artwork queue items for changed albums/artists, enqueued in the same transaction
+	var queueItems []model.ArtworkQueueItem
+	// persistAlbum consumes the map, so a rerun needs the original
+	albumIDMap := maps.Clone(entry.albumIDMap)
+
+	// Instantiate all repositories just once per folder
+	folderRepo := tx.Folder(ctx)
+	tagRepo := tx.Tag(ctx)
+	artistRepo := tx.Artist(ctx)
+	libraryRepo := tx.Library(ctx)
+	albumRepo := tx.Album(ctx)
+	mfRepo := tx.MediaFile(ctx)
+
+	// Save folder to DB
+	folder := entry.toFolder()
+	err := folderRepo.Put(folder)
+	if err != nil {
+		return fmt.Errorf("persisting folder: %w", err)
+	}
+
+	// Save all tags to DB
+	err = tagRepo.Add(entry.job.lib.ID, entry.tags...)
+	if err != nil {
+		return fmt.Errorf("persisting tags: %w", err)
+	}
+
+	// Save all new/modified artists to DB. Their information will be incomplete, but they will be refreshed later
+	for i := range entry.artists {
+		err = artistRepo.Put(&entry.artists[i], "name",
+			"mbz_artist_id", "sort_artist_name", "order_artist_name", "full_text", "search_normalized", "updated_at")
+		if err != nil {
+			return fmt.Errorf("persisting artist %q: %w", entry.artists[i].Name, err)
+		}
+		err = libraryRepo.AddArtist(entry.job.lib.ID, entry.artists[i].ID)
+		if err != nil {
+			return fmt.Errorf("adding artist %q to library: %w", entry.artists[i].Name, err)
+		}
+		if entry.artists[i].Name != consts.UnknownArtist && entry.artists[i].Name != consts.VariousArtists {
+			queueItems = append(queueItems, scanArtworkItem(model.KindArtistArtwork, entry.artists[i].ID))
+		}
+	}
+
+	// Save all new/modified albums to DB. Their information will be incomplete, but they will be refreshed later
+	for i := range entry.albums {
+		err = p.persistAlbum(albumRepo, &entry.albums[i], albumIDMap)
+		if err != nil {
+			return err
+		}
+		if entry.albums[i].Name != consts.UnknownAlbum {
+			queueItems = append(queueItems, scanArtworkItem(model.KindAlbumArtwork, entry.albums[i].ID))
+		}
+	}
+
+	// Save all tracks to DB
+	for i := range entry.tracks {
+		err = mfRepo.Put(&entry.tracks[i])
+		if err != nil {
+			return fmt.Errorf("persisting track %q: %w", entry.tracks[i].Path, err)
+		}
+	}
+
+	// A re-imported track returns to unresolved so new embedded art is picked up lazily.
+	if len(entry.tracks) > 0 {
+		trackIDs := slice.Map(entry.tracks, func(t model.MediaFile) string { return t.ID })
+		if err := tx.Artwork(ctx).DeleteForItems(model.KindMediaFileArtwork, trackIDs); err != nil {
+			log.Warn(ctx, "Scanner: could not invalidate media_file artwork", err)
+		}
+	}
+
+	// Mark all missing tracks as not available
+	if len(entry.missingTracks) > 0 {
+		err = mfRepo.MarkMissing(true, entry.missingTracks...)
+		if err != nil {
+			return fmt.Errorf("marking missing tracks: %w", err)
+		}
+
+		// Touch all albums that have missing tracks, so they get refreshed in later phases
+		groupedMissingTracks := slice.ToMap(entry.missingTracks, func(mf *model.MediaFile) (string, struct{}) {
+			return mf.AlbumID, struct{}{}
+		})
+		albumsToUpdate := slices.Collect(maps.Keys(groupedMissingTracks))
+		err = albumRepo.Touch(albumsToUpdate...)
+		if err != nil {
+			return fmt.Errorf("touching albums %v: %w", albumsToUpdate, err)
+		}
+	}
+
+	// Enqueue artwork resolution for changed albums/artists. Never fails the scan.
+	// A full scan re-imports every track, so a re-import is no evidence the art changed.
+	if len(queueItems) > 0 {
+		queue := tx.ArtworkQueue(ctx)
+		enqueue := queue.Enqueue
+		if p.state.fullScan {
+			enqueue = queue.EnqueueIfMissing
+		}
+		if err := enqueue(queueItems...); err != nil {
+			log.Warn(ctx, "Scanner: could not enqueue artwork resolution", err)
+		}
+	}
+	return nil
 }
 
 // persistAlbum persists the given album to the database, and reassigns annotations from the previous album ID
@@ -499,34 +507,32 @@ func (p *phaseFolders) logFolder(entry *folderEntry) (*folderEntry, error) {
 }
 
 func (p *phaseFolders) finalize(err error) error {
-	errF := p.ds.WithTx(func(tx model.DataStore) error {
+	p.stopWalk(nil)
+	defer p.imageChanges.enqueue(p.ctx)
+	// A failed phase may not have walked every folder, and unvisited ones must not be marked missing
+	if err != nil {
+		return err
+	}
+	return p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
 		for _, job := range p.jobs {
 			// Mark all folders that were not updated as missing
 			if len(job.lastUpdates) == 0 {
 				continue
 			}
 			folderIDs := slices.Collect(maps.Keys(job.lastUpdates))
-			err := tx.Folder(p.ctx).MarkMissing(true, folderIDs...)
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error marking missing folders", "lib", job.lib.Name, err)
-				return err
+			if err := tx.Folder(ctx).MarkMissing(true, folderIDs...); err != nil {
+				return fmt.Errorf("marking missing folders in %s: %w", job.lib.Name, err)
 			}
-			err = tx.MediaFile(p.ctx).MarkMissingByFolder(true, folderIDs...)
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error marking tracks in missing folders", "lib", job.lib.Name, err)
-				return err
+			if err := tx.MediaFile(ctx).MarkMissingByFolder(true, folderIDs...); err != nil {
+				return fmt.Errorf("marking tracks in missing folders in %s: %w", job.lib.Name, err)
 			}
 			// Touch all albums that have missing folders, so they get refreshed in later phases
-			_, err = tx.Album(p.ctx).TouchByMissingFolder()
-			if err != nil {
-				log.Error(p.ctx, "Scanner: Error touching albums with missing folders", "lib", job.lib.Name, err)
-				return err
+			if _, err := tx.Album(ctx).TouchByMissingFolder(); err != nil {
+				return fmt.Errorf("touching albums with missing folders in %s: %w", job.lib.Name, err)
 			}
 		}
 		return nil
 	}, "scanner: finalize phaseFolders")
-	p.imageChanges.enqueue(p.ctx)
-	return errors.Join(err, errF)
 }
 
 var _ phase[*folderEntry] = (*phaseFolders)(nil)
diff --git a/scanner/phase_2_missing_tracks.go b/scanner/phase_2_missing_tracks.go
index 8c258b833..6ccc9a46c 100644
--- a/scanner/phase_2_missing_tracks.go
+++ b/scanner/phase_2_missing_tracks.go
@@ -273,66 +273,68 @@ func (p *phaseMissingTracks) findCrossLibraryMatch(missing model.MediaFile) (mod
 }
 
 func (p *phaseMissingTracks) moveMatched(target, missing model.MediaFile) error {
-	return p.ds.WithTx(func(tx model.DataStore) error {
-		discardedID := target.ID
-		oldAlbumID := missing.AlbumID
-		newAlbumID := target.AlbumID
+	oldAlbumID := missing.AlbumID
+	newAlbumID := target.AlbumID
+	// Use newAlbumID as key since we only care about avoiding duplicate reassignments to the same target.
+	// Claimed before the transaction so a concurrent move skips it, and released if the move fails.
+	reassignAlbum := oldAlbumID != newAlbumID
+	if reassignAlbum {
+		p.annotationMutex.Lock()
+		reassignAlbum = !p.processedAlbumAnnotations[newAlbumID]
+		p.processedAlbumAnnotations[newAlbumID] = true
+		p.annotationMutex.Unlock()
+		if !reassignAlbum {
+			log.Trace(p.ctx, "Scanner: Skipping album annotation reassignment", "from", oldAlbumID, "to", newAlbumID)
+		}
+	}
 
+	err := p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
+		// A rerun must start from the original target, not the one the rolled-back attempt changed
+		moved := target
 		// Preserve the original created_at from the missing file, so moved tracks
 		// don't appear in "Recently Added"
-		target.CreatedAt = missing.CreatedAt
+		moved.CreatedAt = missing.CreatedAt
 
 		// Update the target media file with the missing file's ID. This effectively "moves" the track
 		// to the new location while keeping its annotations and references intact.
-		target.ID = missing.ID
-		err := tx.MediaFile(p.ctx).Put(&target)
-		if err != nil {
+		moved.ID = missing.ID
+		if err := tx.MediaFile(ctx).Put(&moved); err != nil {
 			return fmt.Errorf("update matched track: %w", err)
 		}
 
 		// Discard the new mediafile row (the one that was moved to)
-		err = tx.MediaFile(p.ctx).Delete(discardedID)
-		if err != nil {
+		if err := tx.MediaFile(ctx).Delete(target.ID); err != nil {
 			return fmt.Errorf("delete discarded track: %w", err)
 		}
 
-		// Handle album annotation reassignment if AlbumID changed
-		if oldAlbumID != newAlbumID {
-			// Use newAlbumID as key since we only care about avoiding duplicate reassignments to the same target
-			p.annotationMutex.RLock()
-			alreadyProcessed := p.processedAlbumAnnotations[newAlbumID]
-			p.annotationMutex.RUnlock()
-
-			if !alreadyProcessed {
-				p.annotationMutex.Lock()
-				// Double-check pattern to avoid race conditions
-				if !p.processedAlbumAnnotations[newAlbumID] {
-					// Reassign direct album annotations (starred, rating)
-					log.Debug(p.ctx, "Scanner: Reassigning album annotations", "from", oldAlbumID, "to", newAlbumID)
-					if err := tx.Album(p.ctx).ReassignAnnotation(oldAlbumID, newAlbumID); err != nil {
-						log.Warn(p.ctx, "Scanner: Could not reassign album annotations", "from", oldAlbumID, "to", newAlbumID, err)
-					}
-
-					// Keep created_at field from previous instance of the album, so moved albums
-					// don't appear in "Recently Added"
-					if err := tx.Album(p.ctx).CopyAttributes(oldAlbumID, newAlbumID, "created_at"); err != nil {
-						if !errors.Is(err, model.ErrNotFound) {
-							log.Warn(p.ctx, "Scanner: Could not copy album created_at", "from", oldAlbumID, "to", newAlbumID, err)
-						}
-					}
-
-					// Note: RefreshPlayCounts will be called in later phases, so we don't need to call it here
-					p.processedAlbumAnnotations[newAlbumID] = true
-				}
-				p.annotationMutex.Unlock()
-			} else {
-				log.Trace(p.ctx, "Scanner: Skipping album annotation reassignment", "from", oldAlbumID, "to", newAlbumID)
+		if reassignAlbum {
+			// Reassign direct album annotations (starred, rating)
+			log.Debug(ctx, "Scanner: Reassigning album annotations", "from", oldAlbumID, "to", newAlbumID)
+			if err := tx.Album(ctx).ReassignAnnotation(oldAlbumID, newAlbumID); err != nil {
+				log.Warn(ctx, "Scanner: Could not reassign album annotations", "from", oldAlbumID, "to", newAlbumID, err)
 			}
-		}
 
-		p.state.changesDetected.Store(true)
+			// Keep created_at field from previous instance of the album, so moved albums
+			// don't appear in "Recently Added"
+			if err := tx.Album(ctx).CopyAttributes(oldAlbumID, newAlbumID, "created_at"); err != nil {
+				if !errors.Is(err, model.ErrNotFound) {
+					log.Warn(ctx, "Scanner: Could not copy album created_at", "from", oldAlbumID, "to", newAlbumID, err)
+				}
+			}
+			// Note: RefreshPlayCounts will be called in later phases, so we don't need to call it here
+		}
 		return nil
-	})
+	}, "scanner: move matched track")
+	if err != nil {
+		if reassignAlbum {
+			p.annotationMutex.Lock()
+			delete(p.processedAlbumAnnotations, newAlbumID)
+			p.annotationMutex.Unlock()
+		}
+		return err
+	}
+	p.state.changesDetected.Store(true)
+	return nil
 }
 
 func (p *phaseMissingTracks) finalize(err error) error {
@@ -355,7 +357,12 @@ func (p *phaseMissingTracks) finalize(err error) error {
 }
 
 func (p *phaseMissingTracks) purgeMissing() error {
-	deletedCount, err := p.ds.MediaFile(p.ctx).DeleteAllMissing()
+	var deletedCount int64
+	err := p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
+		var err error
+		deletedCount, err = tx.MediaFile(ctx).DeleteAllMissing()
+		return err
+	}, "scanner: purge missing")
 	if err != nil {
 		return fmt.Errorf("error deleting missing files: %w", err)
 	}
diff --git a/scanner/phase_2_missing_tracks_test.go b/scanner/phase_2_missing_tracks_test.go
index f93b166c1..b7aa52f90 100644
--- a/scanner/phase_2_missing_tracks_test.go
+++ b/scanner/phase_2_missing_tracks_test.go
@@ -2,6 +2,8 @@ package scanner
 
 import (
 	"context"
+	"errors"
+	"maps"
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
@@ -146,6 +148,87 @@ var _ = Describe("phaseMissingTracks", func() {
 			Expect(movedTrack.Path).To(Equal(matchedTrack.Path))
 		})
 
+		Context("claiming the album annotation reassignment", func() {
+			var probe *probeTxDS
+			missingTrack := model.MediaFile{ID: "1", PID: "A", AlbumID: "old-album", Path: "dir1/path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
+			matchedTrack := model.MediaFile{ID: "2", PID: "A", AlbumID: "new-album", Path: "dir2/path2.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
+			BeforeEach(func() {
+				probe = &probeTxDS{MockDataStore: ds.(*tests.MockDataStore)}
+				probe.MockedAlbum = tests.CreateMockAlbumRepo()
+				phase = createPhaseMissingTracks(ctx, state, probe)
+				_ = ds.MediaFile(ctx).Put(&missingTrack)
+				_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			})
+
+			It("claims the target album before the transaction, so a concurrent move skips it", func() {
+				probe.during = func() {
+					phase.annotationMutex.RLock()
+					defer phase.annotationMutex.RUnlock()
+					Expect(phase.processedAlbumAnnotations).To(HaveKeyWithValue("new-album", true))
+				}
+				Expect(phase.moveMatched(matchedTrack, missingTrack)).To(Succeed())
+			})
+
+			It("releases the claim when the move fails, so a later move can reassign", func() {
+				probe.err = errors.New("boom")
+				Expect(phase.moveMatched(matchedTrack, missingTrack)).To(MatchError("boom"))
+				Expect(phase.processedAlbumAnnotations).ToNot(HaveKey("new-album"))
+			})
+		})
+
+		Context("when the move transaction is rerun after a busy rollback", func() {
+			var rerunDS *rerunTxDS
+			BeforeEach(func() {
+				rerunDS = &rerunTxDS{MockDataStore: ds.(*tests.MockDataStore)}
+				rerunDS.snapshot = func() func() {
+					saved := maps.Clone(mr.Data)
+					return func() { mr.Data = saved }
+				}
+				phase = createPhaseMissingTracks(ctx, state, rerunDS)
+			})
+
+			It("keeps the moved track", func() {
+				missingTrack := model.MediaFile{ID: "1", PID: "A", Path: "dir1/path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
+				matchedTrack := model.MediaFile{ID: "2", PID: "A", Path: "dir2/path2.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
+				_ = ds.MediaFile(ctx).Put(&missingTrack)
+				_ = ds.MediaFile(ctx).Put(&matchedTrack)
+
+				_, err := phase.processMissingTracks(&missingTracks{
+					missing: []model.MediaFile{missingTrack},
+					matched: []model.MediaFile{matchedTrack},
+				})
+				Expect(err).ToNot(HaveOccurred())
+
+				movedTrack, err := ds.MediaFile(ctx).Get("1")
+				Expect(err).ToNot(HaveOccurred())
+				Expect(movedTrack.Path).To(Equal(matchedTrack.Path))
+			})
+
+			It("reassigns the album annotations in the attempt that commits", func() {
+				albumRepo := tests.CreateMockAlbumRepo()
+				rerunDS.MockedAlbum = albumRepo
+				restoreTracks := rerunDS.snapshot
+				rerunDS.snapshot = func() func() {
+					restore := restoreTracks()
+					return func() {
+						restore()
+						albumRepo.ReassignAnnotationCalls = nil
+					}
+				}
+				missingTrack := model.MediaFile{ID: "1", PID: "A", AlbumID: "old-album", Path: "dir1/path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
+				matchedTrack := model.MediaFile{ID: "2", PID: "A", AlbumID: "new-album", Path: "dir2/path2.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
+				_ = ds.MediaFile(ctx).Put(&missingTrack)
+				_ = ds.MediaFile(ctx).Put(&matchedTrack)
+
+				_, err := phase.processMissingTracks(&missingTracks{
+					missing: []model.MediaFile{missingTrack},
+					matched: []model.MediaFile{matchedTrack},
+				})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(albumRepo.ReassignAnnotationCalls).To(HaveKeyWithValue("old-album", "new-album"))
+			})
+		})
+
 		It("should move the matched track when the missing track has the same tags and filename", func() {
 			missingTrack := model.MediaFile{ID: "1", PID: "A", Path: "path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
 			matchedTrack := model.MediaFile{ID: "2", PID: "A", Path: "path1.flac", Tags: model.Tags{"title": []string{"title1"}}, Size: 200}
@@ -957,3 +1040,34 @@ var _ = Describe("phaseMissingTracks", func() {
 		})
 	})
 })
+
+// rerunTxDS runs every WithTxRetry block twice, as a retry after a rolled-back busy attempt would.
+// The mock is not transactional, so snapshot returns the function that plays the rollback.
+type rerunTxDS struct {
+	*tests.MockDataStore
+	snapshot func() (rollback func())
+}
+
+func (d *rerunTxDS) WithTxRetry(ctx context.Context, block func(context.Context, model.DataStore) error, _ ...string) error {
+	rollback := d.snapshot()
+	_ = block(ctx, d.MockDataStore)
+	rollback()
+	return block(ctx, d.MockDataStore)
+}
+
+// probeTxDS runs a hook inside each WithTxRetry block, and can fail the transaction after it.
+type probeTxDS struct {
+	*tests.MockDataStore
+	during func()
+	err    error
+}
+
+func (d *probeTxDS) WithTxRetry(ctx context.Context, block func(context.Context, model.DataStore) error, _ ...string) error {
+	if err := block(ctx, d.MockDataStore); err != nil {
+		return err
+	}
+	if d.during != nil {
+		d.during()
+	}
+	return d.err
+}
diff --git a/scanner/phase_3_refresh_albums.go b/scanner/phase_3_refresh_albums.go
index 33e0fed01..964ab7408 100644
--- a/scanner/phase_3_refresh_albums.go
+++ b/scanner/phase_3_refresh_albums.go
@@ -103,7 +103,9 @@ func (p *phaseRefreshAlbums) refreshAlbum(album *model.Album) (*model.Album, err
 		return nil, nil
 	}
 	start := time.Now()
-	err := p.ds.Album(p.ctx).Put(album)
+	err := p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
+		return tx.Album(ctx).Put(album)
+	}, "scanner: refresh album")
 	log.Debug(p.ctx, "Scanner: refreshing album", "album_id", album.ID, "name", album.Name, "songCount", album.SongCount, "elapsed", time.Since(start), err)
 	if err != nil {
 		return nil, fmt.Errorf("refreshing album %s: %w", album.ID, err)
@@ -130,7 +132,12 @@ func (p *phaseRefreshAlbums) finalize(err error) error {
 	}
 	// Refresh album annotations
 	start := time.Now()
-	cnt, err := p.ds.Album(p.ctx).RefreshPlayCounts()
+	var cnt int64
+	err = p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
+		var txErr error
+		cnt, txErr = tx.Album(ctx).RefreshPlayCounts()
+		return txErr
+	}, "scanner: refresh album play counts")
 	if err != nil {
 		return fmt.Errorf("refreshing album annotations: %w", err)
 	}
@@ -138,7 +145,11 @@ func (p *phaseRefreshAlbums) finalize(err error) error {
 
 	// Refresh artist annotations
 	start = time.Now()
-	cnt, err = p.ds.Artist(p.ctx).RefreshPlayCounts()
+	err = p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
+		var txErr error
+		cnt, txErr = tx.Artist(ctx).RefreshPlayCounts()
+		return txErr
+	}, "scanner: refresh artist play counts")
 	if err != nil {
 		return fmt.Errorf("refreshing artist annotations: %w", err)
 	}
diff --git a/scanner/phase_4_playlists.go b/scanner/phase_4_playlists.go
index baa8b749a..4e11fa81d 100644
--- a/scanner/phase_4_playlists.go
+++ b/scanner/phase_4_playlists.go
@@ -101,7 +101,10 @@ func (p *phasePlaylists) produce(put func(entry *model.Folder)) error {
 // import the playlists, and returns an error if the flag can't be persisted (so
 // the scan does not complete as successful without recording the recovery).
 func (p *phasePlaylists) deferImport() error {
-	if err := p.ds.Property(p.ctx).Put(consts.PlaylistsImportPendingFlagKey, "1"); err != nil {
+	err := p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
+		return tx.Property(ctx).Put(consts.PlaylistsImportPendingFlagKey, "1")
+	}, "scanner: defer playlist import")
+	if err != nil {
 		return fmt.Errorf("recording pending playlist import: %w", err)
 	}
 	log.Warn(p.ctx, "Playlists will not be imported, as there are no admin users yet. "+
diff --git a/scanner/scanner.go b/scanner/scanner.go
index d73007bdd..a8a192771 100644
--- a/scanner/scanner.go
+++ b/scanner/scanner.go
@@ -217,7 +217,9 @@ func (s *scannerImpl) prepareLibrariesForScan(ctx context.Context, state *scanSt
 	for _, lib := range state.libraries {
 		if lib.LastScanStartedAt.IsZero() {
 			// This is a new scan - mark it as started
-			err := s.ds.Library(ctx).ScanBegin(lib.ID, state.fullScan)
+			err := s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
+				return tx.Library(ctx).ScanBegin(lib.ID, state.fullScan)
+			}, "scanner: begin library scan")
 			if err != nil {
 				log.Error(ctx, "Scanner: Error marking scan start", "lib", lib.Name, err)
 				state.sendWarning(err.Error())
@@ -253,7 +255,7 @@ func (s *scannerImpl) prepareLibrariesForScan(ctx context.Context, state *scanSt
 func (s *scannerImpl) runGC(ctx context.Context, state *scanState) func() error {
 	return func() error {
 		state.sendProgress(&ProgressInfo{ForceUpdate: true})
-		return s.ds.WithTx(func(tx model.DataStore) error {
+		return s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
 			if state.changesDetected.Load() {
 				start := time.Now()
 
@@ -264,9 +266,7 @@ func (s *scannerImpl) runGC(ctx context.Context, state *scanState) func() error
 					log.Debug(ctx, "Scanner: Running selective GC", "libraryIDs", libraryIDs)
 				}
 
-				err := tx.GC(ctx, libraryIDs...)
-				if err != nil {
-					log.Error(ctx, "Scanner: Error running GC", err)
+				if err := tx.GC(ctx, libraryIDs...); err != nil {
 					return fmt.Errorf("running GC: %w", err)
 				}
 				log.Debug(ctx, "Scanner: GC completed", "elapsed", time.Since(start))
@@ -286,10 +286,14 @@ func (s *scannerImpl) runEnqueueMissingArtwork(ctx context.Context, state *scanS
 			return nil
 		}
 		start := time.Now()
-		queue := s.ds.ArtworkQueue(ctx)
 		var total int64
 		for _, kind := range []model.Kind{model.KindAlbumArtwork, model.KindArtistArtwork} {
-			n, err := queue.EnqueueAllMissing(kind, model.ArtworkPriorityScan)
+			var n int64
+			err := s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
+				var err error
+				n, err = tx.ArtworkQueue(ctx).EnqueueAllMissing(kind, model.ArtworkPriorityScan)
+				return err
+			}, "scanner: enqueue missing artwork")
 			if err != nil {
 				log.Error(ctx, "Scanner: Error enqueueing missing artwork", "kind", kind, err)
 				return fmt.Errorf("enqueueing missing artwork: %w", err)
@@ -316,7 +320,9 @@ func (s *scannerImpl) runRefreshStats(ctx context.Context, state *scanState) fun
 		log.Debug(ctx, "Scanner: Refreshed artist stats", "stats", stats, "elapsed", time.Since(start))
 
 		start = time.Now()
-		err = s.ds.Tag(ctx).UpdateCounts()
+		err = s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
+			return tx.Tag(ctx).UpdateCounts()
+		}, "scanner: update tag counts")
 		if err != nil {
 			log.Error(ctx, "Scanner: Error updating tag counts", err)
 			return fmt.Errorf("updating tag counts: %w", err)
@@ -329,28 +335,21 @@ func (s *scannerImpl) runRefreshStats(ctx context.Context, state *scanState) fun
 func (s *scannerImpl) runUpdateLibraries(ctx context.Context, state *scanState) func() error {
 	return func() error {
 		start := time.Now()
-		return s.ds.WithTx(func(tx model.DataStore) error {
+		return s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
 			for _, lib := range state.libraries {
-				err := tx.Library(ctx).ScanEnd(lib.ID)
-				if err != nil {
-					log.Error(ctx, "Scanner: Error updating last scan completed", "lib", lib.Name, err)
-					return fmt.Errorf("updating last scan completed: %w", err)
+				if err := tx.Library(ctx).ScanEnd(lib.ID); err != nil {
+					return fmt.Errorf("updating last scan completed for %s: %w", lib.Name, err)
 				}
-				err = tx.Property(ctx).Put(consts.PIDTrackKey, conf.Server.PID.Track)
-				if err != nil {
-					log.Error(ctx, "Scanner: Error updating track PID conf", err)
+				if err := tx.Property(ctx).Put(consts.PIDTrackKey, conf.Server.PID.Track); err != nil {
 					return fmt.Errorf("updating track PID conf: %w", err)
 				}
-				err = tx.Property(ctx).Put(consts.PIDAlbumKey, conf.Server.PID.Album)
-				if err != nil {
-					log.Error(ctx, "Scanner: Error updating album PID conf", err)
+				if err := tx.Property(ctx).Put(consts.PIDAlbumKey, conf.Server.PID.Album); err != nil {
 					return fmt.Errorf("updating album PID conf: %w", err)
 				}
 				if state.changesDetected.Load() {
 					log.Debug(ctx, "Scanner: Refreshing library stats", "lib", lib.Name)
 					if err := tx.Library(ctx).RefreshStats(lib.ID); err != nil {
-						log.Error(ctx, "Scanner: Error refreshing library stats", "lib", lib.Name, err)
-						return fmt.Errorf("refreshing library stats: %w", err)
+						return fmt.Errorf("refreshing library stats for %s: %w", lib.Name, err)
 					}
 				} else {
 					log.Debug(ctx, "Scanner: No changes detected, skipping library stats refresh", "lib", lib.Name)
diff --git a/scanner/scanner_test.go b/scanner/scanner_test.go
index 8542b3ac6..30f4a2b97 100644
--- a/scanner/scanner_test.go
+++ b/scanner/scanner_test.go
@@ -4,12 +4,16 @@ import (
 	"context"
 	"database/sql"
 	"errors"
+	"fmt"
+	"os"
 	"path/filepath"
+	"sync/atomic"
 	"testing/fstest"
 	"time"
 
 	"github.com/Masterminds/squirrel"
 	"github.com/google/uuid"
+	"github.com/mattn/go-sqlite3"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
@@ -52,7 +56,10 @@ var _ = Describe("Scanner", Ordered, func() {
 
 	BeforeAll(func() {
 		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "123", IsAdmin: true})
-		tmpDir := GinkgoT().TempDir()
+		// The DB stays open until the suite ends, and Windows can't delete an open file
+		tmpDir, err := os.MkdirTemp("", "scanner-test")
+		Expect(err).ToNot(HaveOccurred())
+		DeferCleanup(func() { _ = os.RemoveAll(tmpDir) })
 		conf.Server.DbPath = filepath.Join(tmpDir, "test-scanner.db?_journal_mode=WAL")
 		log.Warn("Using DB at " + conf.Server.DbPath)
 		//conf.Server.DbPath = ":memory:"
@@ -1240,8 +1247,55 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(albumArtistStats.SongCount).To(Equal(3))  // 3 songs
 		})
 	})
+
+	Context("when the database is busy", func() {
+		var busyDS *busyPersistDS
+		BeforeEach(func() {
+			// One album across many folders: the suite's single DB connection deadlocks phase 3 on many albums
+			album := template(_t{"albumartist": "Artist", "album": "Album"})
+			files := fstest.MapFS{}
+			for i := range 30 {
+				files[fmt.Sprintf("Artist/Part %02d/%02d - Song.mp3", i, i+1)] = album(track(i+1, fmt.Sprintf("Song %02d", i+1)))
+			}
+			createFS(files)
+			busyDS = &busyPersistDS{MockDataStore: ds}
+			s = scanner.New(ctx, busyDS, events.NoopBroker(),
+				playlists.NewPlaylists(busyDS, artwork.NewUploader(busyDS)), metrics.NewNoopInstance())
+		})
+
+		It("gives up and stops walking the library when the database stays busy", func() {
+			busyDS.failures.Store(1000)
+
+			Expect(runScanner(ctx, true)).To(MatchError(ContainSubstring("database is locked")))
+
+			Expect(mfRepo.cursorCalls.Load()).To(BeNumerically("<", 30))
+		})
+
+		It("does not mark unvisited folders missing when the scan gives up", func() {
+			Expect(runScanner(ctx, true)).To(Succeed())
+			busyDS.failures.Store(1000)
+
+			Expect(runScanner(ctx, true)).ToNot(Succeed())
+
+			Expect(ds.Folder(ctx).CountAll(model.QueryOptions{Filters: squirrel.Eq{"missing": true}})).To(BeZero())
+			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{Filters: squirrel.Eq{"missing": true}})).To(BeZero())
+		})
+	})
 })
 
+// busyPersistDS fails the scanner's folder saves with SQLITE_BUSY, as if WithTxRetry ran out of retries.
+type busyPersistDS struct {
+	*tests.MockDataStore
+	failures atomic.Int32
+}
+
+func (b *busyPersistDS) WithTxRetry(ctx context.Context, block func(context.Context, model.DataStore) error, label ...string) error {
+	if len(label) > 0 && label[0] == "scanner: persist changes" && b.failures.Add(-1) >= 0 {
+		return sqlite3.Error{Code: sqlite3.ErrBusy}
+	}
+	return b.MockDataStore.WithTxRetry(ctx, block, label...)
+}
+
 func createFindByPath(ctx context.Context, ds model.DataStore) func(string) (*model.MediaFile, error) {
 	return func(path string) (*model.MediaFile, error) {
 		list, err := ds.MediaFile(ctx).FindByPaths([]string{path})
@@ -1258,6 +1312,12 @@ func createFindByPath(ctx context.Context, ds model.DataStore) func(string) (*mo
 type mockMediaFileRepo struct {
 	model.MediaFileRepository
 	GetMissingAndMatchingError error
+	cursorCalls                atomic.Int32
+}
+
+func (m *mockMediaFileRepo) GetCursor(options ...model.QueryOptions) (model.MediaFileCursor, error) {
+	m.cursorCalls.Add(1)
+	return m.MediaFileRepository.GetCursor(options...)
 }
 
 func (m *mockMediaFileRepo) GetMissingAndMatching(libId int) (model.MediaFileCursor, error) {
diff --git a/scanner/walk_dir_tree.go b/scanner/walk_dir_tree.go
index 20f6d4213..1864a6a44 100644
--- a/scanner/walk_dir_tree.go
+++ b/scanner/walk_dir_tree.go
@@ -53,6 +53,9 @@ func walkDirTree(ctx context.Context, job *scanJob, targetFolders ...string) (<-
 
 			// Recursively walk this folder and all its children
 			err = walkFolder(ctx, job, folderPath, checker, results)
+			if utils.IsCtxDone(ctx) {
+				return
+			}
 			if err != nil {
 				log.Error(ctx, "Scanner: Error walking target folder", "path", folderPath, err)
 				continue
@@ -87,9 +90,12 @@ func walkFolder(ctx context.Context, job *scanJob, currentFolder string, checker
 	folder.path = dir
 	folder.elapsed.Start()
 
-	results <- folder
-
-	return nil
+	select {
+	case results <- folder:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
 }
 
 func loadDir(ctx context.Context, job *scanJob, dirPath string, checker *IgnoreChecker) (folder *folderEntry, children []string, err error) {
@@ -291,6 +297,7 @@ var ignoredDirs = []string{
 	"$RECYCLE.BIN",
 	"#snapshot",
 	"@Recycle",
+	"@eaDir",
 	"@Recently-Snapshot",
 	".git",
 	".streams",
diff --git a/scanner/walk_dir_tree_test.go b/scanner/walk_dir_tree_test.go
index 9fb650c4d..43939e5c2 100644
--- a/scanner/walk_dir_tree_test.go
+++ b/scanner/walk_dir_tree_test.go
@@ -564,6 +564,7 @@ var _ = Describe("walk_dir_tree", func() {
 				Entry("dir starting with ellipsis", "...unhidden_folder", false),
 				Entry("recycle bin", "$Recycle.Bin", true),
 				Entry("snapshot dir", "#snapshot", true),
+				Entry("synology metadata dir", "@eaDir", true),
 			)
 		})
 
diff --git a/tests/mock_data_store.go b/tests/mock_data_store.go
index 32f56a4f0..6a0ebbb31 100644
--- a/tests/mock_data_store.go
+++ b/tests/mock_data_store.go
@@ -329,6 +329,10 @@ func (db *MockDataStore) WithTxImmediate(block func(tx model.DataStore) error, l
 	return block(db)
 }
 
+func (db *MockDataStore) WithTxRetry(ctx context.Context, block func(ctx context.Context, tx model.DataStore) error, label ...string) error {
+	return block(ctx, db)
+}
+
 func (db *MockDataStore) Resource(ctx context.Context, m any) model.ResourceRepository {
 	switch m.(type) {
 	case model.MediaFile, *model.MediaFile:

From 101145742f4762164202cb4858c9126258bdc463 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Wed, 23 Sep 2026 18:42:11 -0400
Subject: [PATCH 176/200] test(plugins): stub DNS in the host SSRF guard tests
 (#6208)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dial-time SSRF guard runs on the resolved IP, so the tests that prove a
symbolic hostname cannot reach loopback used "localhost." — a trailing dot never
matches /etc/hosts, so Go queries real DNS. Machines whose resolver does not
answer "localhost." (a VPN DNS, for example) got "no such host" before the dial
guard ever ran, failing three specs.

Add tests.StubResolver, a net.Resolver backed by an in-memory DNS responder over
net.Pipe, and let the plugin dialers take a resolver so tests can inject it.
Name resolution in those specs no longer depends on the machine's DNS.
---
 plugins/host_httpclient.go      |  1 +
 plugins/host_httpclient_test.go |  4 +++
 plugins/host_netguard.go        |  3 ++
 plugins/host_websocket.go       |  2 +-
 plugins/host_websocket_test.go  |  1 +
 plugins/plugins_suite_test.go   |  6 ++++
 tests/dns_stub.go               | 54 +++++++++++++++++++++++++++++++++
 7 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 tests/dns_stub.go

diff --git a/plugins/host_httpclient.go b/plugins/host_httpclient.go
index 3265ac4b7..6a9a4d2d6 100644
--- a/plugins/host_httpclient.go
+++ b/plugins/host_httpclient.go
@@ -54,6 +54,7 @@ func newHTTPService(pluginName string, permission *HTTPPermission) *httpServiceI
 		Timeout:   30 * time.Second,
 		KeepAlive: 30 * time.Second,
 		Control:   svc.dialControl,
+		Resolver:  dialResolver,
 	}).DialContext
 	// No client timeout: it is set per-request via context deadline.
 	svc.client = &http.Client{Transport: httpclient.NewTransport(svc.transport)}
diff --git a/plugins/host_httpclient_test.go b/plugins/host_httpclient_test.go
index 6edf75a97..81e3192fd 100644
--- a/plugins/host_httpclient_test.go
+++ b/plugins/host_httpclient_test.go
@@ -20,6 +20,10 @@ var _ = Describe("httpServiceImpl", func() {
 		ts  *httptest.Server
 	)
 
+	BeforeEach(func() {
+		stubLocalhostDNS()
+	})
+
 	AfterEach(func() {
 		if ts != nil {
 			ts.Close()
diff --git a/plugins/host_netguard.go b/plugins/host_netguard.go
index f78aaf6a8..ab092009a 100644
--- a/plugins/host_netguard.go
+++ b/plugins/host_netguard.go
@@ -8,6 +8,9 @@ import (
 	"github.com/navidrome/navidrome/utils/netguard"
 )
 
+// dialResolver is nil in production (the system resolver); tests swap in a stub to avoid real DNS.
+var dialResolver *net.Resolver
+
 // checkPrivateDial runs at dial time on the resolved IP, so hostnames can't reach private addresses unless a
 // literal IP/CIDR entry or a bare "*" (plugins targeting user-configured LAN services) allows it.
 func checkPrivateDial(requiredHosts []string, address string) error {
diff --git a/plugins/host_websocket.go b/plugins/host_websocket.go
index 933e53144..d9d82665c 100644
--- a/plugins/host_websocket.go
+++ b/plugins/host_websocket.go
@@ -114,7 +114,7 @@ func (s *webSocketServiceImpl) Connect(ctx context.Context, urlStr string, heade
 	// Establish WebSocket connection
 	dialer := websocket.Dialer{
 		HandshakeTimeout: 30 * time.Second,
-		NetDialContext:   (&net.Dialer{Control: s.dialControl}).DialContext,
+		NetDialContext:   (&net.Dialer{Control: s.dialControl, Resolver: dialResolver}).DialContext,
 	}
 
 	conn, resp, err := dialer.DialContext(ctx, urlStr, httpHeaders)
diff --git a/plugins/host_websocket_test.go b/plugins/host_websocket_test.go
index 772d83cc9..9b94e4b70 100644
--- a/plugins/host_websocket_test.go
+++ b/plugins/host_websocket_test.go
@@ -505,6 +505,7 @@ var _ = Describe("WebSocketService", Ordered, func() {
 		var savedHosts []string
 
 		BeforeEach(func() {
+			stubLocalhostDNS()
 			savedHosts = testService.requiredHosts
 			upgrader := websocket.Upgrader{CheckOrigin: func(r *http.Request) bool { return true }}
 			wsServer = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
diff --git a/plugins/plugins_suite_test.go b/plugins/plugins_suite_test.go
index cc1b45f97..aa07eae32 100644
--- a/plugins/plugins_suite_test.go
+++ b/plugins/plugins_suite_test.go
@@ -46,6 +46,12 @@ func TestPlugins(t *testing.T) {
 	RunSpecs(t, "Plugins Suite")
 }
 
+// stubLocalhostDNS resolves "localhost." without real DNS: the trailing dot never matches /etc/hosts.
+func stubLocalhostDNS() {
+	dialResolver = tests.StubResolver(map[string]string{"localhost.": "127.0.0.1"})
+	DeferCleanup(func() { dialResolver = nil })
+}
+
 // createTestManager creates a new plugin Manager with the given plugin config.
 // It creates a temp directory, copies the test-metadata-agent plugin, and starts the manager.
 // Returns the manager, temp directory path, and a cleanup function.
diff --git a/tests/dns_stub.go b/tests/dns_stub.go
new file mode 100644
index 000000000..7cd7faf6d
--- /dev/null
+++ b/tests/dns_stub.go
@@ -0,0 +1,54 @@
+package tests
+
+import (
+	"context"
+	"encoding/binary"
+	"io"
+	"net"
+	"net/netip"
+
+	"golang.org/x/net/dns/dnsmessage"
+)
+
+// StubResolver returns a net.Resolver that answers A queries from records (absolute name to IPv4,
+// e.g. "localhost." to "127.0.0.1") instead of the system DNS. Other names do not resolve.
+func StubResolver(records map[string]string) *net.Resolver {
+	return &net.Resolver{
+		PreferGo: true,
+		Dial: func(context.Context, string, string) (net.Conn, error) {
+			client, server := net.Pipe()
+			go serveStubDNS(server, records)
+			return client, nil
+		},
+	}
+}
+
+// net.Pipe is not a PacketConn, so the resolver sends one query framed with a 2-byte length prefix.
+func serveStubDNS(conn net.Conn, records map[string]string) {
+	defer conn.Close()
+	var size [2]byte
+	if _, err := io.ReadFull(conn, size[:]); err != nil {
+		return
+	}
+	buf := make([]byte, binary.BigEndian.Uint16(size[:]))
+	if _, err := io.ReadFull(conn, buf); err != nil {
+		return
+	}
+	var msg dnsmessage.Message
+	if err := msg.Unpack(buf); err != nil || len(msg.Questions) != 1 {
+		return
+	}
+	msg.Response = true
+	q := msg.Questions[0]
+	if ip, err := netip.ParseAddr(records[q.Name.String()]); err == nil && q.Type == dnsmessage.TypeA {
+		msg.Answers = []dnsmessage.Resource{{
+			Header: dnsmessage.ResourceHeader{Name: q.Name, Type: q.Type, Class: q.Class},
+			Body:   &dnsmessage.AResource{A: ip.As4()},
+		}}
+	}
+	resp, err := msg.Pack()
+	if err != nil {
+		return
+	}
+	_, _ = conn.Write(append(binary.BigEndian.AppendUint16(nil, uint16(len(resp))), resp...))
+}

From 69b496383deb9e58e3930da7628ab563af938946 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 24 Sep 2026 21:24:46 -0400
Subject: [PATCH 177/200] docs(jellyfin): refresh the README's known
 limitations (#6220)

* docs(jellyfin): refresh the README's known limitations

Rewrite the Known limitations list against the current code and Jellyfin
12.1, dropping stale entries (synthetic blurhash, unchecked artist access,
global genres) and adding the real gaps: search skipping filters, the
one-character minimum, the 2,000-item search cap, position-based playlist
entry ids, the rating param, missing endpoints and unemitted Fields.

Also move the lyrics description into its own section, add the missing
routes and filters to the endpoint table, and drop the stale artist-access
TODO in resolveItemByID.

* docs(jellyfin): list MaxConcurrentStreams env var and all e2e stubs
---
 server/jellyfin/README.md | 109 ++++++++++++++++++++++----------------
 server/jellyfin/items.go  |   3 +-
 2 files changed, 63 insertions(+), 49 deletions(-)

diff --git a/server/jellyfin/README.md b/server/jellyfin/README.md
index e38997569..9315ac4f9 100644
--- a/server/jellyfin/README.md
+++ b/server/jellyfin/README.md
@@ -40,6 +40,7 @@ ND_JELLYFIN_SERVERNAME="My Music Server"
 ND_JELLYFIN_EXPOSEDPUBLICUSERS="alice,bob"
 ND_JELLYFIN_AUTODISCOVERY=true
 ND_JELLYFIN_QUICKCONNECT=false
+ND_JELLYFIN_MAXCONCURRENTSTREAMS=4
 ```
 
 Once enabled, the API is mounted at:
@@ -140,8 +141,10 @@ Jellyfin has no native concept of multiple music libraries the way Navidrome doe
 Navidrome library the current user can access is exposed as its own top-level Jellyfin
 "CollectionFolder" view (`GET /UserViews`), instead of merging every library into a single view.
 Browsing (`/Items`), artists, and the "Latest" list are all scoped to the libraries the
-authenticated user has access to; a library (or item within it) the user cannot access returns
-`404`, never `403`, so ids can't be used as an existence oracle.
+authenticated user has access to. Fetching an item the user cannot access returns `404`, never
+`403`, so ids can't be used as an existence oracle. An inaccessible library id sent as `ParentId`
+is not a `404`: it is simply not treated as a library, so none of that library's content is
+returned.
 
 ### Browsing filters
 
@@ -152,7 +155,7 @@ tracks — Finamp's artist screen sends these *alongside* `ParentId=<libraryId>`
 album's tracks — Feishin fetches them this way instead of `ParentId`); `GenreIds` (a
 genre's albums or tracks — Finamp's genre screen sends it the same way; `/Artists/AlbumArtists`
 and `MusicArtist` queries accept it too, matching artists credited on an album of that genre);
-`SearchTerm`;
+`Years`; `StudioIds` (record labels, as listed by `GET Studios`); `SearchTerm`;
 `Filters` (`IsFavorite`, `IsFavoriteOrLikes`, `IsPlayed`, `IsUnplayed`) and the standalone
 `isFavorite`/`isPlayed` booleans it can also be expressed as — `Filters` wins when both are sent, as
 in Jellyfin; `Likes`, `Dislikes`, `IsFolder`, `IsNotFolder` and `IsResumable` have no Navidrome
@@ -169,9 +172,9 @@ returns direct children only (no tracks — no track is a library's direct child
 | Quick Connect | `GET QuickConnect/Enabled`, `POST QuickConnect/Initiate`, `GET QuickConnect/Connect`, `POST QuickConnect/Authorize` (authenticated), `POST Users/AuthenticateWithQuickConnect` |
 | Auth | `POST Users/AuthenticateByName`, `GET Users/Public` |
 | Users | `GET UserViews`, `GET Users/{userId}/Views`, `GET Users/Me`, `GET Users/{userId}` |
-| Browsing | `GET Items`, `GET Users/{userId}/Items`, `GET Items/{itemId}`, `GET Users/{userId}/Items/{itemId}`, `GET Users/{userId}/Items/Latest`, `DELETE Items/{itemId}` (playlists only) |
-| Artists / genres | `GET Artists`, `GET Artists/AlbumArtists`, `GET Genres`, `GET MusicGenres` |
-| Similar / mixes | `GET Artists/{itemId}/Similar`, `GET Items/{itemId}/Similar`, `GET {Items,Songs,Albums,Artists,Playlists}/{itemId}/InstantMix`, `GET Artists/InstantMix?id=`, `GET MusicGenres/InstantMix?id=` |
+| Browsing | `GET Items`, `GET Users/{userId}/Items`, `GET Items/{itemId}`, `GET Users/{userId}/Items/{itemId}`, `GET Items/Latest`, `GET Users/{userId}/Items/Latest`, `DELETE Items/{itemId}` (playlists only) |
+| Artists / genres / labels | `GET Artists`, `GET Artists/AlbumArtists`, `GET Genres`, `GET MusicGenres`, `GET Studios`, `GET Items/Filters` |
+| Similar / mixes | `GET Artists/{itemId}/Similar`, `GET Items/{itemId}/Similar`, `GET Albums/{itemId}/Similar`, `GET {Items,Songs,Albums,Artists,Playlists}/{itemId}/InstantMix`, `GET Artists/InstantMix?id=`, `GET MusicGenres/InstantMix?id=` |
 | Images | `GET Items/{itemId}/Images/{type}[/{index}]` (public), `POST`/`DELETE Items/{itemId}/Images/{type}` (playlist cover, authenticated) |
 | Favorites / ratings for songs, albums, artists, and playlists | `POST`/`DELETE UserFavoriteItems/{itemId}`, `POST`/`DELETE Users/{userId}/FavoriteItems/{itemId}`, `POST`/`DELETE Users/{userId}/Items/{itemId}/Rating`, `GET UserItems/{itemId}/UserData`, `GET Users/{userId}/Items/{itemId}/UserData` |
 | Streaming | `GET Audio/{itemId}/stream[.{container}]`, `GET Audio/{itemId}/universal`, `GET Audio/{itemId}/main.m3u8`, `GET Items/{itemId}/File`, `GET Items/{itemId}/Download`, `GET`/`POST Items/{itemId}/PlaybackInfo` (`HEAD` too on stream, universal, File, Download and images; a transcode HEAD answers without starting it) |
@@ -267,6 +270,22 @@ The stream endpoints reuse the same transcode-decision pipeline as the Subsonic
   Subsonic. `File`/`Download` stay raw. For HLS clients, force `aac` or `mp3`; other formats are
   advertised and served but packed-audio players won't decode them.
 
+## Lyrics
+
+`GET Audio/{id}/Lyrics` serves the main lyric track as a `LyricDto` (`Start` in 100ns ticks,
+word-level `Cues` when present), resolved through the full `core/lyrics` pipeline (embedded, `.lrc`
+sidecars, plugins per `LyricsPriority`). No lyrics returns `404`, never an empty `200`.
+
+Results, misses included, are cached for 5 minutes: Jellify fetches lyrics for every played track and
+Feishin on every song change, so lyric-less tracks are the hot path. Concurrent misses on the same
+track share one pipeline run. That run is detached from the request, so a cancelled request doesn't
+fail it for other waiters, and its context has a one-minute deadline.
+
+Finamp opens its lyrics view only when the track has a `Lyric` `MediaStream` (`HasLyrics` is just a
+list badge). Browse lists set both from embedded lyrics only. `PlaybackInfo` runs the full pipeline
+per track, so sidecar and plugin lyrics show up there. Feishin also requires server version ≥ 10.9
+(we advertise 12.1.0).
+
 ## AudioMuse-AI compatible endpoints
 
 Compatibility shim for Jellyfin front-ends that integrate [AudioMuse-AI](https://github.com/NeptuneHub/audiomuse-ai-plugin)
@@ -356,8 +375,9 @@ curl -s -X DELETE "${AUTH[@]}" "$BASE/Items/$PLAYLIST_ID"
 
 Handler-level unit tests live alongside each file (`*_test.go`). A full end-to-end suite in
 [`e2e/`](e2e) exercises every endpoint through the real router against a real SQLite database and
-real repositories (only artwork/streaming/ffmpeg are stubbed), with per-`Describe` snapshot
-isolation — mirroring the Subsonic `server/subsonic/e2e` suite. Run it with:
+real repositories (only artwork, streaming, ffmpeg, external metadata agents and sonic similarity
+are stubbed), with per-`Describe` snapshot isolation — mirroring the Subsonic `server/subsonic/e2e`
+suite. Run it with:
 
 ```bash
 make test PKG=./server/jellyfin/...
@@ -365,42 +385,37 @@ make test PKG=./server/jellyfin/...
 
 ## Known limitations
 
-- **Genres are global.** `GET Genres`/`MusicGenres` is not scoped to the current user's
-  libraries (genre tags aren't per-library entities in Navidrome's model).
-- **Artist item-access relies on list-time scoping.** Unlike albums and songs (which each
-  belong to exactly one library and are checked against `user.HasLibraryAccess` on every
-  fetch), an artist can have content across multiple libraries via `library_artist`, so there's
-  no single library id to gate a direct `GET Items/{artistId}` or favorite/rating call against.
-  Access control for artists is enforced by scoping the `Artists`/`Items?IncludeItemTypes=MusicArtist`
-  *list* to the user's libraries, plus the persistence layer's own defense-in-depth; a client
-  that already has an artist id from elsewhere is not re-checked against library membership.
-- **Blurhashes are synthetic, not computed from the artwork (follow-up).** `ImageBlurHashes` is
-  populated by `dto/blurhash.go`, which derives a well-formed **1-component (solid color)**
-  blurhash by hashing the item id — it never looks at the actual image. Real Jellyfin computes a
-  multi-component blurhash from the cover's pixels (downscaled to 128×128) once at scan time and
-  stores it per image, so its placeholder approximates the art. Ours satisfies the protocol
-  (Finamp gets a valid value to use as a de-dup key and a placeholder, no missing-blurhash
-  warning) but renders as a flat color while art loads. A proper implementation would compute the
-  real blurhash in the `core/artwork` pipeline (where the image is already decoded), cache it
-  keyed like the artwork, and have the mappers read it — keeping the synthetic value as a fallback
-  for art that hasn't been rendered yet.
-- **The WebSocket only keep-alives; it pushes no events (follow-up).** `GET socket` sends a
-  `ForceKeepAlive` and answers `KeepAlive` pings so real-time clients (Finamp) settle into a
-  working session instead of 404-loop-reconnecting, but it never pushes anything. A follow-up
-  would broadcast real session/playstate and library-change events over it (via `server/events`),
-  mirroring Jellyfin's session messages.
-- **Lyrics.** `GET Audio/{id}/Lyrics` serves the main lyric track as a `LyricDto` (`Start` in
-  100ns ticks, word-level `Cues` when present), resolved through the full `core/lyrics` pipeline
-  (embedded, `.lrc` sidecars, plugins per `LyricsPriority`) behind a 5-minute TTL cache that also
-  caches misses — Jellify fetches for every played track, Feishin per song change, so lyric-less
-  tracks are the hot path. No lyrics → 404 (never an empty 200), which all three clients degrade
-  gracefully. Finamp gates its lyrics view on a `Lyric` `MediaStream` (not `HasLyrics`, which is
-  just a list badge): browse lists advertise it from embedded lyrics only (the `"[]"` sentinel
-  check — the column is never `""` post-scan), while `PlaybackInfo` runs the full pipeline per
-  track so sidecar/plugin lyrics also light up. Feishin additionally requires server version
-  ≥ 10.9 (`jellyfinVersion` advertises 12.1.0).
-  Concurrent misses on the same track share one pipeline invocation (`SimpleCache.GetWithLoader`
-  is singleflighted), and the load runs detached from the request context with a one-minute bound,
-  so a cancelled request or hung plugin can't fail or pin the load for other waiters.
-  Follow-up: tracks whose only lyrics are sidecar/plugin-sourced show no `HasLyrics` badge in
-  lists (request-time sources can't be known at list time without per-row I/O).
+- **Genre lists ignore `ParentId`.** `GET Genres`/`MusicGenres` and
+  `Items?IncludeItemTypes=MusicGenre` list the genres of every library the user can access, never
+  only the `ParentId` library. `Items?IncludeItemTypes=MusicGenre` also ignores `SearchTerm`.
+  `GET Items/Filters` is the exception: its genres follow `ParentId`.
+- **Search skips some filters.** With `SearchTerm`, `Filters=IsFavorite`, `IsPlayed`, `IsUnplayed`
+  and `isFavorite`/`isPlayed` are skipped, so the response holds every search match. The full-text
+  search's first phase has no annotation join to filter on. Artist searches also skip the role (album
+  artist vs. artist) and `GenreIds`. Playlist lists ignore `SearchTerm`.
+- **Search pages are capped at 2,000 items.** A larger `Limit` is lowered to 2,000. Jellyfin has no
+  cap.
+- **One-character searches return nothing.** The shared search layer ignores terms shorter than two
+  characters, so album, artist and song searches for `a` come back empty. Real Jellyfin has no
+  minimum.
+- **Playlist entry ids are positions, not song ids.** `PlaylistItemId` encodes the entry's position
+  in the playlist, so ids change when entries are inserted or removed; re-read the list after an
+  edit. Real Jellyfin uses the song id. Clients that echo `PlaylistItemId` back (Finamp) work;
+  clients that send the song id as `EntryIds` or to `Move` (Jellify) get `404`.
+- **Rating uses the `rating` param.** `POST Users/{userId}/Items/{itemId}/Rating` reads a `rating`
+  (0-10) and stores it as 0-5 stars. Jellyfin's `likes` boolean is not read, so a client that sends
+  only `likes` clears the rating.
+- **Missing endpoints.** `UserPlayedItems` (mark played/unplayed), `Search/Hints` and the non-legacy
+  `UserItems/{itemId}/Rating` are not implemented. Play counts only change through playback
+  reporting.
+- **Some `Fields` are never emitted.** `ProviderIds`, `People`, `Etag` and `DateLastMediaAdded` are
+  accepted but never returned.
+- **Blurhashes can be missing.** `ImageBlurHashes` carries the real blurhash that the artwork
+  pipeline computes and stores. Until that happens for an item, the field is omitted: a fake value
+  would pin the wrong placeholder in clients that key their image cache on it.
+- **The WebSocket only keeps alive; it pushes no events.** `GET socket` sends `ForceKeepAlive` and
+  answers `KeepAlive` pings, so real-time clients (Finamp) keep a working session instead of
+  reconnecting in a loop. It never pushes session, playstate or library-change events.
+- **List lyric badges only see embedded lyrics.** Tracks with only sidecar or plugin lyrics show no
+  `HasLyrics` badge in lists, because those sources can't be known at list time without per-row I/O.
+  `PlaybackInfo` and `Audio/{id}/Lyrics` still find them (see "Lyrics").
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index 124d17920..23e35dd59 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -893,8 +893,7 @@ func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fi
 		return dto.AlbumToBaseItem(*al, fields), true
 	}
 	if ar, err := api.ds.Artist(ctx).Get(id); err == nil {
-		// TODO: an artist spans multiple libraries (library_artist), so there's no single
-		// LibraryID to gate here; artist access relies on list-time scoping and persistence.
+		// Artist.Get already scopes to the user's libraries via library_artist.
 		return dto.ArtistToBaseItem(*ar, fields), true
 	}
 	if mf, err := api.ds.MediaFile(ctx).Get(id); err == nil {

From a0c416037655a2d4476d3e055907540605f5bf87 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Thu, 24 Sep 2026 21:40:49 -0400
Subject: [PATCH 178/200] chore: update golangci-lint version to v2.14.0

---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 81a609422..eccccbffb 100644
--- a/Makefile
+++ b/Makefile
@@ -20,7 +20,7 @@ IMAGE_PLATFORMS ?= $(shell echo $(SUPPORTED_PLATFORMS) | tr ',' '\n' | grep "lin
 PLATFORMS ?= $(SUPPORTED_PLATFORMS)
 DOCKER_TAG ?= deluan/navidrome:develop
 
-GOLANGCI_LINT_VERSION ?= v2.13.2
+GOLANGCI_LINT_VERSION ?= v2.14.0
 
 UI_SRC_FILES := $(shell find ui -type f -not -path "ui/build/*" -not -path "ui/node_modules/*")
 

From 3f89baaec8f3285429496d5f0b796165034c70ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 24 Sep 2026 22:07:17 -0400
Subject: [PATCH 179/200] test(server): make the handleM3U spec independent of
 spec order (#6221)

It relied on another spec having set auth.PublicTokenAuth, so it panicked whenever Ginkgo ran it first.
---
 server/public/handle_shares_test.go | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/server/public/handle_shares_test.go b/server/public/handle_shares_test.go
index 1bf631fd4..4de2a75c1 100644
--- a/server/public/handle_shares_test.go
+++ b/server/public/handle_shares_test.go
@@ -4,7 +4,9 @@ import (
 	"net/http"
 	"net/http/httptest"
 
+	"github.com/go-chi/jwtauth/v5"
 	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -17,6 +19,7 @@ var _ = Describe("handleM3U", func() {
 	var pub *Router
 
 	BeforeEach(func() {
+		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
 		ds = &tests.MockDataStore{}
 		shareRepo = &tests.MockShareRepo{}
 		ds.MockedShare = shareRepo

From 336fa482f84f2600f7cf79464fd828549e4aa43b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 25 Sep 2026 12:19:33 -0400
Subject: [PATCH 180/200] fix(plugins): skip the startup error reset when no
 plugin has an error (#6223)

The plugin manager clears last_error on every startup with an UPDATE that takes the SQLite write lock even when no row matches. On slow storage the startup scan often holds the lock at that moment, so the reset waited out the busy timeout and logged "database is locked", even with no plugins installed. ClearErrors now checks for errors with a read first and only writes when there is something to clear.
---
 persistence/plugin_repository.go      |  8 ++++++++
 persistence/plugin_repository_test.go | 15 +++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/persistence/plugin_repository.go b/persistence/plugin_repository.go
index c1e36f0b1..7d5781f49 100644
--- a/persistence/plugin_repository.go
+++ b/persistence/plugin_repository.go
@@ -35,6 +35,14 @@ func (r *pluginRepository) ClearErrors() error {
 	if !r.isPermitted() {
 		return rest.ErrPermissionDenied
 	}
+	// An UPDATE takes the write lock even when nothing matches, so only run it when there is an error to clear
+	var hasErrors bool
+	if err := r.db.NewQuery("SELECT EXISTS (SELECT 1 FROM plugin WHERE last_error != '')").Row(&hasErrors); err != nil {
+		return err
+	}
+	if !hasErrors {
+		return nil
+	}
 	_, err := r.db.NewQuery("UPDATE plugin SET last_error = '' WHERE last_error != ''").Execute()
 	return err
 }
diff --git a/persistence/plugin_repository_test.go b/persistence/plugin_repository_test.go
index dc68b0892..9b135057e 100644
--- a/persistence/plugin_repository_test.go
+++ b/persistence/plugin_repository_test.go
@@ -1,7 +1,10 @@
 package persistence
 
 import (
+	"context"
+
 	"github.com/deluan/rest"
+	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	. "github.com/onsi/ginkgo/v2"
@@ -198,6 +201,18 @@ var _ = Describe("PluginRepository", func() {
 				err := repo.ClearErrors()
 				Expect(err).To(BeNil())
 			})
+
+			It("does not need the write lock when no plugins have errors", func() {
+				_ = repo.Put(&model.Plugin{ID: "clean-plugin", Path: "/plugins/c.wasm", Manifest: "{}", SHA256: "h1"})
+				conn, err := db.Db().Conn(GinkgoT().Context())
+				Expect(err).ToNot(HaveOccurred())
+				DeferCleanup(conn.Close)
+				_, err = conn.ExecContext(GinkgoT().Context(), "BEGIN IMMEDIATE")
+				Expect(err).ToNot(HaveOccurred())
+				DeferCleanup(func() { _, _ = conn.ExecContext(context.Background(), "ROLLBACK") })
+
+				Expect(repo.ClearErrors()).To(Succeed())
+			})
 		})
 	})
 

From 659d067abaaf31d4a261836331a1f6bc00746c88 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 25 Sep 2026 16:19:30 -0400
Subject: [PATCH 181/200] fix(archiver): give same-named albums their own
 folder in artist zips (#6225)

* refactor: add Tags.First and slice.GroupOrdered helpers

Tags.First returns the first value of a tag or an empty string, replacing the inline len-check-then-index pattern in FullTitle, FullAlbumName, Album.FullName and the Subsonic album version mapping.

slice.GroupOrdered is slice.Group returning the groups in first-seen order, for callers that need a deterministic order the map-based Group cannot give.

* fix(archiver): give same-named albums their own folder in artist zips

Artist zips put every album in a folder named after the album, so two albums with the same name (an original and a deluxe edition, or names that only differ in characters the sanitizer replaces) were merged into one folder, with tracks mixed together and duplicate zip entries when file names collided.

The folder is now named after FullAlbumName(), so with AppendAlbumVersion on (the default) the version is part of the name, matching what clients display. Albums whose sanitized names still clash get a " [suffix]" taken from the first field that has a distinct, non-empty value for all of them: album version, year, release type, record label, catalog number, then a short album id. This follows the shape of beets' %aunique{} path function.

Albums are also grouped with slice.GroupOrdered instead of a map, so the zip is deterministic.

* fix(archiver): use the release year to tell same-named albums apart

Taggers often write an edition's date to the Date tag next to an original date, and the scanner then stores the original year in Year and the edition's year in ReleaseYear. Reissues of the same album therefore share Year, so the year disambiguator could not tell them apart and they fell through to the album id suffix. Prefer ReleaseYear and fall back to Year when it is not set.

Found by downloading an artist zip from a live server built from this branch.

* fix(archiver): let one clashing album keep the plain folder name

A disambiguator was only accepted when every clashing album had a non-empty value, so an original and its deluxe edition (with the version not appended to the name) fell through to the album id suffix. Accept a field whose values are distinct across the group even when one of them is empty, as beets' %aunique{} does: that album keeps the plain name, which the suffixed folders cannot clash with. Two or more empty values still count as a tie.

* test(archiver): refactor tests for album naming conventions and query order
---
 core/archiver.go           |  70 +++++++++++++++++--
 core/archiver_test.go      | 136 +++++++++++++++++++++++++++++++++++++
 model/album.go             |   4 +-
 model/mediafile.go         |   8 +--
 model/tag.go               |   7 ++
 model/tag_test.go          |   4 ++
 server/subsonic/helpers.go |   4 +-
 utils/slice/slice.go       |  17 +++++
 utils/slice/slice_test.go  |  12 ++++
 9 files changed, 246 insertions(+), 16 deletions(-)

diff --git a/core/archiver.go b/core/archiver.go
index c9436279e..6406ca075 100644
--- a/core/archiver.go
+++ b/core/archiver.go
@@ -2,12 +2,14 @@ package core
 
 import (
 	"archive/zip"
+	"cmp"
 	"context"
 	"errors"
 	"fmt"
 	"io"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 
 	"github.com/Masterminds/squirrel"
@@ -58,16 +60,16 @@ func (a *archiver) zipAlbums(ctx context.Context, id string, format string, bitr
 	}
 
 	z := createZipWriter(out, format, bitrate)
-	albums := slice.Group(mfs, func(mf model.MediaFile) string {
-		return mf.AlbumID
-	})
+	albums := slice.GroupOrdered(mfs, func(mf model.MediaFile) string { return mf.AlbumID })
+	folders := albumFolders(albums)
 	for _, album := range albums {
 		discs := slice.Group(album, func(mf model.MediaFile) int { return mf.DiscNumber })
 		isMultiDisc := len(discs) > 1
-		log.Debug(ctx, "Zipping album", "name", album[0].Album, "artist", album[0].AlbumArtist,
+		folder := folders[album[0].AlbumID]
+		log.Debug(ctx, "Zipping album", "name", album[0].Album, "artist", album[0].AlbumArtist, "folder", folder,
 			"format", format, "bitrate", bitrate, "isMultiDisc", isMultiDisc, "numTracks", len(album))
 		for _, mf := range album {
-			file := a.albumFilename(mf, format, isMultiDisc)
+			file := a.albumFilename(mf, format, isMultiDisc, folder)
 			if addErr := a.addFileToZip(ctx, z, mf, format, bitrate, file); errors.Is(addErr, stream.ErrTooManyTranscodes) {
 				// Stop iterating: continuing would just rack up more
 				// rejections from the limiter. Close finalises whatever
@@ -96,7 +98,61 @@ func createZipWriter(out io.Writer, format string, bitrate int) *zip.Writer {
 	return z
 }
 
-func (a *archiver) albumFilename(mf model.MediaFile, format string, isMultiDisc bool) string {
+// Tried in order; the first one whose values are distinct across the clashing albums wins.
+// One album may have an empty value: it keeps the plain name, which the others can't clash with.
+var albumDisambiguators = []func(model.MediaFile) string{
+	func(mf model.MediaFile) string { return mf.Tags.First(model.TagAlbumVersion) },
+	func(mf model.MediaFile) string {
+		// Reissues share Year (often the original's) but not ReleaseYear.
+		if y := cmp.Or(mf.ReleaseYear, mf.Year); y != 0 {
+			return strconv.Itoa(y)
+		}
+		return ""
+	},
+	func(mf model.MediaFile) string { return mf.MbzAlbumType },
+	func(mf model.MediaFile) string { return mf.Tags.First(model.TagRecordLabel) },
+	func(mf model.MediaFile) string { return mf.CatalogNum },
+	func(mf model.MediaFile) string { return mf.AlbumID[:min(6, len(mf.AlbumID))] },
+	func(mf model.MediaFile) string { return mf.AlbumID },
+}
+
+// albumFolders maps each album id to its zip folder. Albums whose names sanitize to the
+// same folder get a " [suffix]" from the first disambiguator that tells them all apart.
+func albumFolders(albums [][]model.MediaFile) map[string]string {
+	byName := map[string][]model.MediaFile{}
+	for _, album := range albums {
+		name := str.SanitizeFilename(album[0].FullAlbumName())
+		byName[name] = append(byName[name], album[0])
+	}
+	folders := make(map[string]string, len(albums))
+	for name, group := range byName {
+		if len(group) == 1 {
+			folders[group[0].AlbumID] = name
+			continue
+		}
+	fields:
+		for _, field := range albumDisambiguators {
+			ids := make(map[string]string, len(group)) // suffix -> album id
+			for _, mf := range group {
+				s := str.SanitizeFilename(field(mf))
+				if _, dup := ids[s]; dup {
+					continue fields
+				}
+				ids[s] = mf.AlbumID
+			}
+			for s, id := range ids {
+				folders[id] = name
+				if s != "" {
+					folders[id] = fmt.Sprintf("%s [%s]", name, s)
+				}
+			}
+			break
+		}
+	}
+	return folders
+}
+
+func (a *archiver) albumFilename(mf model.MediaFile, format string, isMultiDisc bool, folder string) string {
 	_, file := filepath.Split(mf.Path)
 	if format != "raw" {
 		file = strings.TrimSuffix(file, mf.Suffix) + format
@@ -104,7 +160,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", str.SanitizeFilename(mf.Album), file)
+	return fmt.Sprintf("%s/%s", folder, file)
 }
 
 // ZipShare takes an already-loaded share: Share.Load records a visit, so
diff --git a/core/archiver_test.go b/core/archiver_test.go
index 461af1800..86833717a 100644
--- a/core/archiver_test.go
+++ b/core/archiver_test.go
@@ -8,6 +8,8 @@ import (
 	"strings"
 
 	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/stream"
 	"github.com/navidrome/navidrome/model"
@@ -91,6 +93,140 @@ var _ = Describe("Archiver", func() {
 			Expect(zr.File[0].Name).To(Equal("Album 1/01 - track1.mp3"))
 			Expect(zr.File[1].Name).To(Equal("Album 1/02 - track2.mp3"))
 		})
+
+		When("albums that share a name", func() {
+			BeforeEach(func() {
+				DeferCleanup(configtest.SetupConfig())
+			})
+
+			// zipArtistEntries zips the given tracks as artist "1" and returns the entry names in zip order.
+			zipArtistEntries := func(mfs model.MediaFiles) []string {
+				mfRepo := &mockMediaFileRepository{}
+				mfRepo.On("GetAll", mock.Anything).Return(mfs, nil)
+				ds.On("MediaFile", mock.Anything).Return(mfRepo)
+				ms.On("NewStream", mock.Anything, mock.Anything, mock.Anything).Return(io.NopCloser(strings.NewReader("test")), nil)
+
+				out := new(bytes.Buffer)
+				Expect(arch.ZipArtist(context.Background(), "1", "mp3", 128, out)).To(Succeed())
+				zr, err := zip.NewReader(bytes.NewReader(out.Bytes()), int64(out.Len()))
+				Expect(err).To(BeNil())
+				names := make([]string, len(zr.File))
+				for i, f := range zr.File {
+					names[i] = f.Name
+				}
+				return names
+			}
+
+			It("keeps the albums in query order", func() {
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "3", Album: "Album C"},
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Album A"},
+					{Path: "a/02.mp3", Suffix: "mp3", AlbumID: "1", Album: "Album A"},
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Album B"},
+				})
+				Expect(names).To(Equal([]string{"Album C/01.mp3", "Album A/01.mp3", "Album A/02.mp3", "Album B/01.mp3"}))
+			})
+
+			It("suffixes the year when it tells the albums apart", func() {
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01 - Intro.mp3", Suffix: "mp3", AlbumID: "1", Album: "Greatest Hits", Year: 2001},
+					{Path: "b/01 - Intro.mp3", Suffix: "mp3", AlbumID: "2", Album: "Greatest Hits", Year: 2005},
+				})
+				Expect(names).To(Equal([]string{"Greatest Hits [2001]/01 - Intro.mp3", "Greatest Hits [2005]/01 - Intro.mp3"}))
+			})
+
+			It("prefers the release year, so reissues of the same original are told apart", func() {
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Greatest Hits", Year: 1996, ReleaseYear: 2001},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Greatest Hits", Year: 1996, ReleaseYear: 2011},
+					{Path: "c/01.mp3", Suffix: "mp3", AlbumID: "3", Album: "Greatest Hits", Year: 1996},
+				})
+				Expect(names).To(Equal([]string{"Greatest Hits [2001]/01.mp3", "Greatest Hits [2011]/01.mp3", "Greatest Hits [1996]/01.mp3"}))
+			})
+
+			It("names the folder after the full album name", func() {
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Greatest Hits", Year: 2001,
+						Tags: model.Tags{model.TagAlbumVersion: {"Original"}}},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Greatest Hits", Year: 2005,
+						Tags: model.Tags{model.TagAlbumVersion: {"CD/Digital"}}},
+				})
+				Expect(names).To(Equal([]string{"Greatest Hits (Original)/01.mp3", "Greatest Hits (CD_Digital)/01.mp3"}))
+			})
+
+			It("prefers the album version over the year when it is not part of the name", func() {
+				conf.Server.Subsonic.AppendAlbumVersion = false
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Greatest Hits", Year: 2001,
+						Tags: model.Tags{model.TagAlbumVersion: {"Original"}}},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Greatest Hits", Year: 2005,
+						Tags: model.Tags{model.TagAlbumVersion: {"Deluxe Edition"}}},
+				})
+				Expect(names).To(Equal([]string{"Greatest Hits [Original]/01.mp3", "Greatest Hits [Deluxe Edition]/01.mp3"}))
+			})
+
+			It("leaves the one album without the field unsuffixed", func() {
+				conf.Server.Subsonic.AppendAlbumVersion = false
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Greatest Hits", Year: 2001},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Greatest Hits", Year: 2005,
+						Tags: model.Tags{model.TagAlbumVersion: {"Deluxe Edition"}}},
+				})
+				Expect(names).To(Equal([]string{"Greatest Hits/01.mp3", "Greatest Hits [Deluxe Edition]/01.mp3"}))
+			})
+
+			It("skips a field that is empty on more than one album", func() {
+				conf.Server.Subsonic.AppendAlbumVersion = false
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Greatest Hits", Year: 2001},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Greatest Hits", Year: 2005},
+					{Path: "c/01.mp3", Suffix: "mp3", AlbumID: "3", Album: "Greatest Hits", Year: 2010,
+						Tags: model.Tags{model.TagAlbumVersion: {"Deluxe Edition"}}},
+				})
+				Expect(names).To(Equal([]string{"Greatest Hits [2001]/01.mp3", "Greatest Hits [2005]/01.mp3", "Greatest Hits [2010]/01.mp3"}))
+			})
+
+			It("skips a field that is the same on every album", func() {
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Live", Year: 2001, MbzAlbumType: "album", CatalogNum: "CAT-1"},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Live", Year: 2001, MbzAlbumType: "album", CatalogNum: "CAT-2"},
+				})
+				Expect(names).To(Equal([]string{"Live [CAT-1]/01.mp3", "Live [CAT-2]/01.mp3"}))
+			})
+
+			It("falls back to the album id when nothing differs", func() {
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "0123456789abcdef", Album: "Greatest Hits", Year: 2001},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "fedcba9876543210", Album: "Greatest Hits", Year: 2001},
+				})
+				Expect(names).To(Equal([]string{"Greatest Hits [012345]/01.mp3", "Greatest Hits [fedcba]/01.mp3"}))
+			})
+
+			It("treats names that sanitize to the same folder as a clash", func() {
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "A/B", Year: 2001},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: `A\B`, Year: 2005},
+				})
+				Expect(names).To(Equal([]string{"A_B [2001]/01.mp3", "A_B [2005]/01.mp3"}))
+			})
+
+			It("sanitizes the suffix", func() {
+				conf.Server.Subsonic.AppendAlbumVersion = false
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Hits", Tags: model.Tags{model.TagAlbumVersion: {"Vinyl"}}},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Hits", Tags: model.Tags{model.TagAlbumVersion: {"CD/Digital"}}},
+				})
+				Expect(names).To(Equal([]string{"Hits [Vinyl]/01.mp3", "Hits [CD_Digital]/01.mp3"}))
+			})
+
+			It("leaves the folder name alone when only one album has it", func() {
+				names := zipArtistEntries(model.MediaFiles{
+					{Path: "a/01.mp3", Suffix: "mp3", AlbumID: "1", Album: "Greatest Hits", Year: 2001},
+					{Path: "b/01.mp3", Suffix: "mp3", AlbumID: "2", Album: "Other", Year: 2005},
+				})
+				Expect(names).To(Equal([]string{"Greatest Hits/01.mp3", "Other/01.mp3"}))
+			})
+		})
 	})
 
 	Context("when the transcode limiter rejects a file", func() {
diff --git a/model/album.go b/model/album.go
index ee24bfa96..114d19e1e 100644
--- a/model/album.go
+++ b/model/album.go
@@ -76,8 +76,8 @@ func (a Album) CoverArtID() ArtworkID {
 }
 
 func (a Album) FullName() string {
-	if conf.Server.Subsonic.AppendAlbumVersion && len(a.Tags[TagAlbumVersion]) > 0 {
-		return appendSuffix(a.Name, a.Tags[TagAlbumVersion][0])
+	if v := a.Tags.First(TagAlbumVersion); conf.Server.Subsonic.AppendAlbumVersion && v != "" {
+		return appendSuffix(a.Name, v)
 	}
 	return a.Name
 }
diff --git a/model/mediafile.go b/model/mediafile.go
index 7cbdb583c..1147eaa35 100644
--- a/model/mediafile.go
+++ b/model/mediafile.go
@@ -105,15 +105,15 @@ type MediaFile struct {
 }
 
 func (mf MediaFile) FullTitle() string {
-	if conf.Server.Subsonic.AppendSubtitle && len(mf.Tags[TagSubtitle]) > 0 {
-		return appendSuffix(mf.Title, mf.Tags[TagSubtitle][0])
+	if s := mf.Tags.First(TagSubtitle); conf.Server.Subsonic.AppendSubtitle && s != "" {
+		return appendSuffix(mf.Title, s)
 	}
 	return mf.Title
 }
 
 func (mf MediaFile) FullAlbumName() string {
-	if conf.Server.Subsonic.AppendAlbumVersion && len(mf.Tags[TagAlbumVersion]) > 0 {
-		return appendSuffix(mf.Album, mf.Tags[TagAlbumVersion][0])
+	if v := mf.Tags.First(TagAlbumVersion); conf.Server.Subsonic.AppendAlbumVersion && v != "" {
+		return appendSuffix(mf.Album, v)
 	}
 	return mf.Album
 }
diff --git a/model/tag.go b/model/tag.go
index 234cfb359..152b7164e 100644
--- a/model/tag.go
+++ b/model/tag.go
@@ -80,6 +80,13 @@ func (t Tags) Values(name TagName) []string {
 	return t[name]
 }
 
+func (t Tags) First(name TagName) string {
+	if v := t[name]; len(v) > 0 {
+		return v[0]
+	}
+	return ""
+}
+
 func (t Tags) IDs() []string {
 	var ids []string
 	for name, tag := range t {
diff --git a/model/tag_test.go b/model/tag_test.go
index 4dc99019b..c5a941b4e 100644
--- a/model/tag_test.go
+++ b/model/tag_test.go
@@ -43,6 +43,10 @@ var _ = Describe("Tag", func() {
 			Expect(tags.Values("genre")).To(ConsistOf("Rock", "Pop"))
 			Expect(tags.Values("artist")).To(ConsistOf("The Beatles"))
 		})
+		It("should get the first value by name", func() {
+			Expect(tags.First("genre")).To(Equal("Rock"))
+			Expect(tags.First("missing")).To(BeEmpty())
+		})
 
 		Describe("Hash", func() {
 			It("should always return the same value for the same tags ", func() {
diff --git a/server/subsonic/helpers.go b/server/subsonic/helpers.go
index 2d9d53b18..55b1b213e 100644
--- a/server/subsonic/helpers.go
+++ b/server/subsonic/helpers.go
@@ -515,9 +515,7 @@ func buildOSAlbumID3(ctx context.Context, album model.Album) *responses.OpenSubs
 	dir.IsCompilation = album.Compilation
 	dir.DiscTitles = buildDiscSubtitles(album)
 	dir.ExplicitStatus = mapExplicitStatus(album.ExplicitStatus)
-	if len(album.Tags.Values(model.TagAlbumVersion)) > 0 {
-		dir.Version = album.Tags.Values(model.TagAlbumVersion)[0]
-	}
+	dir.Version = album.Tags.First(model.TagAlbumVersion)
 
 	return &dir
 }
diff --git a/utils/slice/slice.go b/utils/slice/slice.go
index 73537c8f8..e3677e754 100644
--- a/utils/slice/slice.go
+++ b/utils/slice/slice.go
@@ -33,6 +33,23 @@ func Group[T any, K comparable](s []T, keyFunc func(T) K) map[K][]T {
 	return m
 }
 
+// GroupOrdered is Group with the groups in first-seen order.
+func GroupOrdered[T any, K comparable](s []T, keyFunc func(T) K) [][]T {
+	var groups [][]T
+	index := map[K]int{}
+	for _, item := range s {
+		k := keyFunc(item)
+		i, ok := index[k]
+		if !ok {
+			i = len(groups)
+			index[k] = i
+			groups = append(groups, nil)
+		}
+		groups[i] = append(groups[i], item)
+	}
+	return groups
+}
+
 func ToMap[T any, K comparable, V any](s []T, transformFunc func(T) (K, V)) map[K]V {
 	m := make(map[K]V, len(s))
 	for _, item := range s {
diff --git a/utils/slice/slice_test.go b/utils/slice/slice_test.go
index 27548d693..506b61b9f 100644
--- a/utils/slice/slice_test.go
+++ b/utils/slice/slice_test.go
@@ -63,6 +63,18 @@ var _ = Describe("Slice Utils", func() {
 		})
 	})
 
+	Describe("GroupOrdered", func() {
+		It("returns nil for an empty input", func() {
+			Expect(slice.GroupOrdered([]int{}, func(v int) int { return v })).To(BeNil())
+		})
+
+		It("keeps groups in first-seen order and items in input order", func() {
+			keyFunc := func(v int) int { return v % 3 }
+			result := slice.GroupOrdered([]int{2, 1, 4, 3, 5, 6, 8}, keyFunc)
+			Expect(result).To(Equal([][]int{{2, 5, 8}, {1, 4}, {3, 6}}))
+		})
+	})
+
 	Describe("ToMap", func() {
 		It("returns empty map for an empty input", func() {
 			transformFunc := func(v int) (int, string) { return v, strconv.Itoa(v) }

From 83fff44c822d47d1275b9dfb0142bdfefac90cd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 25 Sep 2026 16:42:49 -0400
Subject: [PATCH 182/200] feat(archiver): add folder cover image to downloaded
 zips (#6224)

* feat(archiver): add folder cover image to downloaded zips

Album, artist, playlist and share downloads now include the item's cover as
folder.<ext>, the image most players and car stereos show for the files next to
it. This helps users who copy transcoded downloads to offline devices, since
transcoding drops the embedded artwork (#5841).

Album folders get the album cover, the artist zip root gets the artist image,
and playlist and share zips get the playlist or shared item's cover at the root.
The image is the same one getCoverArt serves, resized to 500px (not square),
and named by its detected type. Items without artwork get no image, and a cover
that fails to load is logged and skipped so it never breaks the archive.

The archiver reads covers through a new core.CoverArtReader interface,
implemented by artwork.CoverArtReader, to avoid an import cycle between core
and core/artwork.

* refactor(archiver): read covers through artwork.Artwork directly

The archiver no longer needs a local CoverArtReader interface and adapter.
The only reason core/artwork imported core was a core.AbsolutePath call in
loadArtistFolder, which now reads the library path from the repository and
cleans it the same way. With the import cycle gone, the archiver takes
artwork.Artwork and treats ErrUnavailable and ErrNotFound as no cover.

Covers are now written after each album's tracks (and after all tracks for
the archive root), so a slow artwork lookup does not delay the first bytes
of the download.

* fix(archiver): read share covers as admin so private playlists keep theirs

Public share downloads run with an anonymous context, and the playlist
repository hides private playlists from anonymous users, so a zip of a shared
private playlist silently had no folder image. Like the public image handler,
the share itself is the authorization: the cover lookup now runs with an admin
user. Only the cover read is elevated; streaming keeps the anonymous context,
so the transcode limiter still keys public downloads the same way.

* style(archiver): trim comments

Shorten the comments added by the folder cover image change and drop the ones the names already explain.

* fix(archiver): add one cover per album folder in artist zips

Albums with the same name share a zip folder (pre-existing naming), so an
artist zip with two such albums wrote two folder.<ext> entries at the same
path. Keep the first cover and skip the rest for that folder.
---
 cmd/wire_gen.go                           |   4 +-
 core/archiver.go                          |  96 ++++++++++--
 core/archiver_test.go                     | 178 +++++++++++++++++++++-
 core/artwork/folders_artist.go            |   6 +-
 core/artwork/folders_artist_paths_test.go |  15 +-
 5 files changed, 270 insertions(+), 29 deletions(-)

diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index 43ba808d0..cb06cc047 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -95,7 +95,7 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
 	share := core.NewShare(dataStore)
-	archiver := core.NewArchiver(mediaStreamer, dataStore, share)
+	archiver := core.NewArchiver(mediaStreamer, dataStore, share, artworkArtwork)
 	players := core.NewPlayers(dataStore)
 	broker := events.GetBroker()
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
@@ -152,7 +152,7 @@ func CreatePublicRouter() *public.Router {
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
 	share := core.NewShare(dataStore)
-	archiver := core.NewArchiver(mediaStreamer, dataStore, share)
+	archiver := core.NewArchiver(mediaStreamer, dataStore, share, artworkArtwork)
 	router := public.New(dataStore, artworkArtwork, mediaStreamer, share, archiver)
 	return router
 }
diff --git a/core/archiver.go b/core/archiver.go
index 6406ca075..33236d889 100644
--- a/core/archiver.go
+++ b/core/archiver.go
@@ -7,20 +7,27 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net/http"
 	"os"
+	"path"
 	"path/filepath"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/Masterminds/squirrel"
+	"github.com/navidrome/navidrome/core/artwork"
 	"github.com/navidrome/navidrome/core/stream"
 	"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/utils/slice"
 	"github.com/navidrome/navidrome/utils/str"
 )
 
+const archiveCoverArtSize = 500
+
 type Archiver interface {
 	ZipAlbum(ctx context.Context, id string, format string, bitrate int, w io.Writer) error
 	ZipArtist(ctx context.Context, id string, format string, bitrate int, w io.Writer) error
@@ -28,18 +35,19 @@ type Archiver interface {
 	ZipPlaylist(ctx context.Context, id string, format string, bitrate int, w io.Writer) error
 }
 
-func NewArchiver(ms stream.MediaStreamer, ds model.DataStore, shares Share) Archiver {
-	return &archiver{ds: ds, ms: ms, shares: shares}
+func NewArchiver(ms stream.MediaStreamer, ds model.DataStore, shares Share, artwork artwork.Artwork) Archiver {
+	return &archiver{ds: ds, ms: ms, shares: shares, artwork: artwork}
 }
 
 type archiver struct {
-	ds     model.DataStore
-	ms     stream.MediaStreamer
-	shares Share
+	ds      model.DataStore
+	ms      stream.MediaStreamer
+	shares  Share
+	artwork artwork.Artwork
 }
 
 func (a *archiver) ZipAlbum(ctx context.Context, id string, format string, bitrate int, out io.Writer) error {
-	return a.zipAlbums(ctx, id, format, bitrate, out, squirrel.Eq{"album_id": id})
+	return a.zipAlbums(ctx, id, format, bitrate, out, squirrel.Eq{"album_id": id}, model.ArtworkID{})
 }
 
 func (a *archiver) ZipArtist(ctx context.Context, id string, format string, bitrate int, out io.Writer) error {
@@ -49,10 +57,11 @@ func (a *archiver) ZipArtist(ctx context.Context, id string, format string, bitr
 		persistence.ParticipantIDFilter("media_file", id, model.RoleAlbumArtist),
 		squirrel.Eq{"missing": false},
 	}
-	return a.zipAlbums(ctx, id, format, bitrate, out, filter)
+	return a.zipAlbums(ctx, id, format, bitrate, out, filter, model.Artist{ID: id}.CoverArtID())
 }
 
-func (a *archiver) zipAlbums(ctx context.Context, id string, format string, bitrate int, out io.Writer, filters squirrel.Sqlizer) error {
+// rootArt, when set, is added to the archive root.
+func (a *archiver) zipAlbums(ctx context.Context, id string, format string, bitrate int, out io.Writer, filters squirrel.Sqlizer, rootArt model.ArtworkID) error {
 	mfs, err := a.ds.MediaFile(ctx).GetAll(model.QueryOptions{Filters: filters, Sort: "album"})
 	if err != nil {
 		log.Error(ctx, "Error loading mediafiles from artist", "id", id, err)
@@ -80,7 +89,10 @@ func (a *archiver) zipAlbums(ctx context.Context, id string, format string, bitr
 				return addErr
 			}
 		}
+		// After the tracks, so a slow artwork lookup doesn't delay the first bytes.
+		a.addCoverArtToZip(ctx, z, album[0].AlbumCoverArtID(), folder)
 	}
+	a.addCoverArtToZip(ctx, z, rootArt, "")
 	err = z.Close()
 	if err != nil {
 		log.Error(ctx, "Error closing zip file", "id", id, err)
@@ -170,7 +182,10 @@ func (a *archiver) ZipShare(ctx context.Context, s *model.Share, out io.Writer)
 		return model.ErrNotAuthorized
 	}
 	log.Debug(ctx, "Zipping share", "name", s.ID, "format", s.Format, "bitrate", s.MaxBitRate, "numTracks", len(s.Tracks))
-	return a.zipMediaFiles(ctx, s.ID, s.ID, s.Format, s.MaxBitRate, out, s.Tracks, false)
+	// The share is the authorization (as in the public image handler): an anonymous lookup would
+	// hide a private playlist. Only the cover read is elevated.
+	coverCtx := request.WithUser(ctx, model.User{IsAdmin: true})
+	return a.zipMediaFiles(ctx, s.ID, s.ID, s.Format, s.MaxBitRate, out, s.Tracks, coverCtx, s.CoverArtID(), false)
 }
 
 func (a *archiver) ZipPlaylist(ctx context.Context, id string, format string, bitrate int, out io.Writer) error {
@@ -181,10 +196,10 @@ func (a *archiver) ZipPlaylist(ctx context.Context, id string, format string, bi
 	}
 	mfs := pls.MediaFiles()
 	log.Debug(ctx, "Zipping playlist", "name", pls.Name, "format", format, "bitrate", bitrate, "numTracks", len(mfs))
-	return a.zipMediaFiles(ctx, id, pls.Name, format, bitrate, out, mfs, true)
+	return a.zipMediaFiles(ctx, id, pls.Name, format, bitrate, out, mfs, ctx, pls.CoverArtID(), true)
 }
 
-func (a *archiver) zipMediaFiles(ctx context.Context, id, name string, format string, bitrate int, out io.Writer, mfs model.MediaFiles, addM3U bool) error {
+func (a *archiver) zipMediaFiles(ctx context.Context, id, name string, format string, bitrate int, out io.Writer, mfs model.MediaFiles, coverCtx context.Context, coverArt model.ArtworkID, addM3U bool) error {
 	z := createZipWriter(out, format, bitrate)
 
 	zippedMfs := make(model.MediaFiles, len(mfs))
@@ -199,6 +214,7 @@ func (a *archiver) zipMediaFiles(ctx context.Context, id, name string, format st
 		mf.Path = file
 		zippedMfs[idx] = mf
 	}
+	a.addCoverArtToZip(coverCtx, z, coverArt, "")
 
 	// Add M3U file if requested
 	if addM3U && len(zippedMfs) > 0 {
@@ -276,3 +292,61 @@ func (a *archiver) addFileToZip(ctx context.Context, z *zip.Writer, mf model.Med
 
 	return nil
 }
+
+// addCoverArtToZip adds the cover as dir/folder.<ext>. Errors are logged, never returned.
+func (a *archiver) addCoverArtToZip(ctx context.Context, z *zip.Writer, artID model.ArtworkID, dir string) {
+	if artID.ID == "" {
+		return
+	}
+	// Buffered so a failed read leaves no empty entry.
+	data, err := a.readCoverArt(ctx, artID)
+	if errors.Is(err, artwork.ErrUnavailable) || errors.Is(err, model.ErrNotFound) {
+		log.Debug(ctx, "No cover art to add to zip", "artID", artID)
+		return
+	}
+	if err != nil {
+		log.Warn(ctx, "Error reading cover art for zipping", "artID", artID, err)
+		return
+	}
+	ext := coverArtExtension(data)
+	if ext == "" {
+		log.Warn(ctx, "Unknown cover art image type, not adding it to zip", "artID", artID)
+		return
+	}
+	w, err := z.CreateHeader(&zip.FileHeader{
+		Name:     path.Join(dir, "folder."+ext),
+		Modified: time.Now(),
+		Method:   zip.Store,
+	})
+	if err != nil {
+		log.Warn(ctx, "Error creating cover art zip entry", "artID", artID, err)
+		return
+	}
+	if _, err = w.Write(data); err != nil {
+		log.Warn(ctx, "Error zipping cover art", "artID", artID, err)
+	}
+}
+
+func (a *archiver) readCoverArt(ctx context.Context, artID model.ArtworkID) ([]byte, error) {
+	img, err := a.artwork.Get(ctx, artID, archiveCoverArtSize, false)
+	if err != nil {
+		return nil, err
+	}
+	defer img.Close()
+	return io.ReadAll(img)
+}
+
+// Resizing may re-encode the image, so the type comes from its bytes.
+func coverArtExtension(data []byte) string {
+	switch http.DetectContentType(data) {
+	case "image/jpeg":
+		return "jpg"
+	case "image/png":
+		return "png"
+	case "image/webp":
+		return "webp"
+	case "image/gif":
+		return "gif"
+	}
+	return ""
+}
diff --git a/core/archiver_test.go b/core/archiver_test.go
index 86833717a..9dab44cef 100644
--- a/core/archiver_test.go
+++ b/core/archiver_test.go
@@ -4,6 +4,7 @@ import (
 	"archive/zip"
 	"bytes"
 	"context"
+	"errors"
 	"io"
 	"strings"
 
@@ -11,8 +12,10 @@ import (
 	"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/stream"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/persistence"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -25,13 +28,15 @@ var _ = Describe("Archiver", func() {
 		ms   *mockMediaStreamer
 		ds   *mockDataStore
 		sh   *mockShare
+		ca   *mockCoverArt
 	)
 
 	BeforeEach(func() {
 		ms = &mockMediaStreamer{}
 		sh = &mockShare{}
 		ds = &mockDataStore{}
-		arch = core.NewArchiver(ms, ds, sh)
+		ca = &mockCoverArt{images: map[string][]byte{}}
+		arch = core.NewArchiver(ms, ds, sh, ca)
 	})
 
 	Context("ZipAlbum", func() {
@@ -332,8 +337,179 @@ var _ = Describe("Archiver", func() {
 			Expect(string(m3uContent)).To(Equal(expectedM3U))
 		})
 	})
+	Context("cover art", func() {
+		var (
+			jpegData = []byte("\xff\xd8\xff\xe0 fake jpeg")
+			pngData  = []byte("\x89PNG\x0d\x0a\x1a\x0a fake png")
+		)
+
+		mockAlbumTracks := func(filter squirrel.Sqlizer, mfs model.MediaFiles) {
+			mfRepo := &mockMediaFileRepository{}
+			mfRepo.On("GetAll", []model.QueryOptions{{Filters: filter, Sort: "album"}}).Return(mfs, nil)
+			ds.On("MediaFile", mock.Anything).Return(mfRepo)
+			ms.On("NewStream", mock.Anything, mock.Anything, mock.Anything).Return(io.NopCloser(strings.NewReader("test")), nil)
+		}
+
+		It("adds the album cover to the album folder", func() {
+			ca.images["al-1"] = jpegData
+			mockAlbumTracks(squirrel.Eq{"album_id": "1"}, model.MediaFiles{
+				{Path: "test_data/01 - track1.mp3", Suffix: "mp3", AlbumID: "1", Album: "Album/Promo", DiscNumber: 1},
+			})
+
+			out := new(bytes.Buffer)
+			Expect(arch.ZipAlbum(context.Background(), "1", "mp3", 128, out)).To(Succeed())
+
+			files := readZip(out)
+			Expect(files).To(HaveLen(2))
+			Expect(files).To(HaveKeyWithValue("Album_Promo/folder.jpg", jpegData))
+			Expect(ca.requests).To(ConsistOf(coverRequest{id: "al-1", size: 500, square: false}))
+		})
+
+		It("adds the artist image to the root and each album cover to its folder", func() {
+			ca.images["ar-1"] = pngData
+			ca.images["al-1"] = jpegData
+			ca.images["al-2"] = jpegData
+			mockAlbumTracks(squirrel.And{
+				persistence.ParticipantIDFilter("media_file", "1", model.RoleAlbumArtist),
+				squirrel.Eq{"missing": false},
+			}, model.MediaFiles{
+				{Path: "test_data/01 - track1.mp3", Suffix: "mp3", AlbumID: "1", Album: "Album 1", DiscNumber: 1},
+				{Path: "test_data/02 - track2.mp3", Suffix: "mp3", AlbumID: "2", Album: "Album 2", DiscNumber: 1},
+			})
+
+			out := new(bytes.Buffer)
+			Expect(arch.ZipArtist(context.Background(), "1", "mp3", 128, out)).To(Succeed())
+
+			files := readZip(out)
+			Expect(files).To(HaveLen(5))
+			Expect(files).To(HaveKeyWithValue("folder.png", pngData))
+			Expect(files).To(HaveKeyWithValue("Album 1/folder.jpg", jpegData))
+			Expect(files).To(HaveKeyWithValue("Album 2/folder.jpg", jpegData))
+		})
+
+		It("puts each same-named album's cover in that album's own folder", func() {
+			ca.images["al-1"] = jpegData
+			ca.images["al-2"] = pngData
+			mockAlbumTracks(squirrel.And{
+				persistence.ParticipantIDFilter("media_file", "1", model.RoleAlbumArtist),
+				squirrel.Eq{"missing": false},
+			}, model.MediaFiles{
+				{Path: "test_data/01 - track1.mp3", Suffix: "mp3", AlbumID: "1", Album: "Greatest Hits", Year: 2001, DiscNumber: 1},
+				{Path: "test_data/02 - track2.mp3", Suffix: "mp3", AlbumID: "2", Album: "Greatest Hits", Year: 2005, DiscNumber: 1},
+			})
+
+			out := new(bytes.Buffer)
+			Expect(arch.ZipArtist(context.Background(), "1", "mp3", 128, out)).To(Succeed())
+
+			files := readZip(out)
+			Expect(files).To(HaveKeyWithValue("Greatest Hits [2001]/folder.jpg", jpegData))
+			Expect(files).To(HaveKeyWithValue("Greatest Hits [2005]/folder.png", pngData))
+		})
+
+		It("adds the playlist cover to the root", func() {
+			ca.images["pl-1"] = jpegData
+			plRepo := &mockPlaylistRepository{}
+			plRepo.On("GetWithTracks", "1", true, false).Return(&model.Playlist{
+				ID:   "1",
+				Name: "Test Playlist",
+				Tracks: []model.PlaylistTrack{
+					{MediaFile: model.MediaFile{Path: "test_data/01 - track1.mp3", Suffix: "mp3", AlbumID: "1", Artist: "Artist 1", Title: "track1"}},
+				},
+			}, nil)
+			ds.On("Playlist", mock.Anything).Return(plRepo)
+			ms.On("NewStream", mock.Anything, mock.Anything, mock.Anything).Return(io.NopCloser(strings.NewReader("test")), nil)
+
+			out := new(bytes.Buffer)
+			Expect(arch.ZipPlaylist(context.Background(), "1", "mp3", 128, out)).To(Succeed())
+
+			files := readZip(out)
+			Expect(files).To(HaveLen(3))
+			Expect(files).To(HaveKeyWithValue("folder.jpg", jpegData))
+			Expect(files).To(HaveKey("Test Playlist.m3u"))
+		})
+
+		It("adds the shared item's cover to the root, even for a private playlist", func() {
+			ca.images["pl-10"] = jpegData
+			ms.On("NewStream", mock.Anything, mock.Anything, mock.Anything).Return(io.NopCloser(strings.NewReader("test")), nil)
+			share := &model.Share{
+				ID:           "1",
+				Downloadable: true,
+				Format:       "mp3",
+				MaxBitRate:   128,
+				ResourceType: "playlist",
+				ResourceIDs:  "10",
+				Tracks: model.MediaFiles{
+					{ID: "1", Path: "test_data/01 - track1.mp3", Suffix: "mp3", Artist: "Artist 1", Title: "track1"},
+				},
+			}
+
+			out := new(bytes.Buffer)
+			Expect(arch.ZipShare(context.Background(), share, out)).To(Succeed())
+
+			files := readZip(out)
+			Expect(files).To(HaveLen(2))
+			Expect(files).To(HaveKeyWithValue("folder.jpg", jpegData))
+			Expect(ca.requests).To(ConsistOf(coverRequest{id: "pl-10", size: 500, square: false, admin: true}))
+		})
+
+		It("still builds the archive when the cover cannot be read", func() {
+			ca.err = errors.New("boom")
+			mockAlbumTracks(squirrel.Eq{"album_id": "1"}, model.MediaFiles{
+				{Path: "test_data/01 - track1.mp3", Suffix: "mp3", AlbumID: "1", Album: "Album", DiscNumber: 1},
+			})
+
+			out := new(bytes.Buffer)
+			Expect(arch.ZipAlbum(context.Background(), "1", "mp3", 128, out)).To(Succeed())
+
+			files := readZip(out)
+			Expect(files).To(HaveLen(1))
+			Expect(files).To(HaveKey("Album/01 - track1.mp3"))
+		})
+	})
 })
 
+func readZip(out *bytes.Buffer) map[string][]byte {
+	zr, err := zip.NewReader(bytes.NewReader(out.Bytes()), int64(out.Len()))
+	Expect(err).ToNot(HaveOccurred())
+	files := make(map[string][]byte, len(zr.File))
+	for _, f := range zr.File {
+		r, err := f.Open()
+		Expect(err).ToNot(HaveOccurred())
+		data, err := io.ReadAll(r)
+		Expect(err).ToNot(HaveOccurred())
+		_ = r.Close()
+		files[f.Name] = data
+	}
+	return files
+}
+
+type coverRequest struct {
+	id     string
+	size   int
+	square bool
+	admin  bool
+}
+
+type mockCoverArt struct {
+	artwork.Artwork
+	images   map[string][]byte
+	err      error
+	requests []coverRequest
+}
+
+func (m *mockCoverArt) Get(ctx context.Context, artID model.ArtworkID, size int, square bool) (*artwork.Image, error) {
+	user, _ := request.UserFrom(ctx)
+	m.requests = append(m.requests, coverRequest{id: artID.String(), size: size, square: square, admin: user.IsAdmin})
+	if m.err != nil {
+		return nil, m.err
+	}
+	data, ok := m.images[artID.String()]
+	if !ok {
+		return nil, artwork.ErrUnavailable
+	}
+	return &artwork.Image{ReadCloser: io.NopCloser(bytes.NewReader(data))}, nil
+}
+
 type mockDataStore struct {
 	mock.Mock
 	model.DataStore
diff --git a/core/artwork/folders_artist.go b/core/artwork/folders_artist.go
index 1ca1ce034..efef42f81 100644
--- a/core/artwork/folders_artist.go
+++ b/core/artwork/folders_artist.go
@@ -14,7 +14,6 @@ import (
 	"time"
 
 	"github.com/Masterminds/squirrel"
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils"
@@ -169,8 +168,9 @@ func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albu
 		folderPath = filepath.Dir(folderPath)
 	}
 
-	// TODO: Hacky, but the easiest way to get the folder ID ATM
-	libPath := core.AbsolutePath(ctx, ds, libID, "")
+	// Cleaned like the album paths; Join keeps an empty path empty, Clean would return ".".
+	libPath, _ := ds.Library(ctx).GetPath(libID)
+	libPath = filepath.Join(libPath)
 	folderID := model.FolderID(model.Library{ID: libID, Path: libPath}, folderPath)
 
 	log.Trace(ctx, "Artwork: Calculating artist folder details", "folderPath", folderPath, "folderID", folderID,
diff --git a/core/artwork/folders_artist_paths_test.go b/core/artwork/folders_artist_paths_test.go
index cc8af3e63..127661891 100644
--- a/core/artwork/folders_artist_paths_test.go
+++ b/core/artwork/folders_artist_paths_test.go
@@ -6,7 +6,6 @@ import (
 	"path/filepath"
 	"time"
 
-	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -47,11 +46,11 @@ var _ = Describe("loadArtistFolder", func() {
 
 	BeforeEach(func() {
 		ctx = context.Background()
-		DeferCleanup(stubCoreAbsolutePath())
-
 		updatedAt = time.Now().Truncate(time.Second).Add(5 * time.Minute)
 		repo = &fakeFolderRepo{result: []model.Folder{{ImagesUpdatedAt: updatedAt}}}
-		ds = &tests.MockDataStore{MockedFolder: repo}
+		libRepo := &tests.MockLibraryRepo{}
+		libRepo.SetData(model.Libraries{{ID: 1, Path: filepath.FromSlash("/music")}})
+		ds = &tests.MockDataStore{MockedFolder: repo, MockedLibrary: libRepo}
 		albums = model.Albums{{LibraryID: 1, ID: "album1", Name: "Album 1"}}
 	})
 
@@ -107,11 +106,3 @@ var _ = Describe("loadArtistFolder", func() {
 		Expect(upd).To(BeZero())
 	})
 })
-
-func stubCoreAbsolutePath() func() {
-	original := core.AbsolutePath
-	core.AbsolutePath = func(context.Context, model.DataStore, int, string) string {
-		return filepath.FromSlash("/music")
-	}
-	return func() { core.AbsolutePath = original }
-}

From b293b962566019d33c3e094164649b75c777b657 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 25 Sep 2026 18:06:10 -0400
Subject: [PATCH 183/200] refactor(persistence): stateless repositories with
 per-call context (#6149)

* refactor(persistence): adopt generic deluan/rest repository API

Pin deluan/rest to the refactor branch. REST-facing repository methods
take a context and return typed values. Drop DataStore.Resource and
ResourceRepository; the native API names typed repositories directly
through a per-request adapter that later commits remove.

* refactor(persistence): base repository helpers take a context

* refactor(persistence): LibraryRepository takes a context per call

* refactor(persistence): PropertyRepository takes a context per call

* refactor(persistence): UserPropsRepository takes a context per call

* refactor(persistence): TranscodingRepository takes a context per call

* refactor(persistence): ShareRepository takes a context per call

* refactor(persistence): PlayerRepository takes a context per call

* refactor(persistence): RadioRepository takes a context per call

* refactor(persistence): PlayQueueRepository takes a context per call

* refactor(persistence): Tag and Genre repositories take a context per call

* refactor(persistence): PluginRepository takes a context per call

* refactor(persistence): Scrobble repositories take a context per call

* refactor(persistence): FolderRepository takes a context per call

* refactor(persistence): Artwork repositories take a context per call

* refactor(persistence): UserRepository takes a context per call

* refactor(persistence): ArtistRepository takes a context per call

ReadAll no longer rewrites the shared sort mappings for the role filter;
it works on a per-call copy.

* test(persistence): assert artist role sort sanitization in ReadAll

* refactor(persistence): AlbumRepository takes a context per call

* test(persistence): pass the test context to album repository helpers

* refactor(persistence): MediaFileRepository takes a context per call

* refactor(persistence): Playlist repositories take a context per call

* refactor(persistence): build all repositories once per store

* refactor(core): REST repository wrappers are built once

* refactor(persistence): repositories are stateless

Remove the context field from the base repository and the per-request
REST adapter. Enable the containedctx linter so no repository can hold a
request context again.

* chore(lint): skip containedctx in test files

* refactor: share simplifications from the stateless repositories sweep

Add deleteOwnedAll on sqlRepository and use it in player/share Delete
to remove the duplicated bulk-delete loop; have Share.Repository()
return model.ShareRepository so subsonic sharing.go drops its repeated
type assertions.

* chore(core): assert REST wrappers implement Persistable

* chore: reformat imports

* perf(persistence): build repositories on first use

Each transaction store used to construct all 21 repositories up front,
paying for filter and sort mapping setup the block never touched. Fields
are now sync.OnceValue thunks, so a store only builds what it uses.

* fix(persistence): clean plugin references per deleted user

A bulk user delete that fails on a later id had already removed the
earlier rows but skipped their plugin cleanup. Cleanup now runs right
after each successful delete.

* fix(core): unload disabled plugins even when a user delete fails

A bulk delete can fail on a later id after earlier users were removed
and their plugins auto-disabled. The wrapper returned before unloading,
leaving those plugins running until the next successful delete or a
restart.

* chore(deps): pin deluan/rest to v1.0.1

Replaces the pseudo-version of the refactor branch with the tagged
release. REST error messages now name the bare type (Artist, not
model.Artist).

* test: use the spec context instead of context.Background()

Replace the context.Background()/context.TODO() calls this branch added
to tests with the spec's ctx, GinkgoT().Context(), or t/b.Context(), so
repository calls are bound to the running spec's lifetime.

* test: declare the spec context once per Describe

Set ctx from GinkgoT().Context() first in each top-level BeforeEach and reuse it, building user contexts on top of it instead of repeating inline calls.
---
 .golangci.yml                                 |   4 +
 adapters/lastfm/agent_test.go                 |   2 +-
 adapters/lastfm/auth_router_test.go           |   2 +-
 adapters/listenbrainz/agent_test.go           |   2 +-
 cmd/artwork.go                                |  34 +-
 cmd/artwork_test.go                           |  90 ++--
 cmd/missing.go                                |   6 +-
 cmd/pls.go                                    |  10 +-
 cmd/plugin.go                                 |   8 +-
 cmd/root.go                                   |  10 +-
 cmd/svc.go                                    |   2 +-
 cmd/user.go                                   |  26 +-
 cmd/utils.go                                  |   4 +-
 core/agents/local_agent.go                    |   6 +-
 core/agents/session_keys.go                   |   6 +-
 core/archiver.go                              |   4 +-
 core/archiver_test.go                         |  24 +-
 core/artwork/artwork.go                       |  24 +-
 core/artwork/artwork_suite_test.go            |   7 +-
 core/artwork/artwork_test.go                  |  44 +-
 core/artwork/disc.go                          |   6 +-
 core/artwork/e2e/acquire_serve_test.go        |  36 +-
 core/artwork/e2e/artist_test.go               |   4 +-
 core/artwork/e2e/e2e_suite_test.go            |  10 +-
 core/artwork/e2e/mediafile_test.go            |   2 +-
 core/artwork/e2e/playlist_test.go             |  10 +-
 core/artwork/e2e/radio_test.go                |   4 +-
 core/artwork/e2e/resolution_harness_test.go   |  18 +-
 core/artwork/folders_album.go                 |   6 +-
 core/artwork/folders_artist.go                |   4 +-
 core/artwork/housekeeping.go                  |  24 +-
 core/artwork/housekeeping_test.go             |   8 +-
 core/artwork/library_fs.go                    |   2 +-
 core/artwork/library_fs_test.go               |   4 +-
 core/artwork/processor.go                     |  10 +-
 core/artwork/processor_test.go                |  54 +--
 core/artwork/prune.go                         |  10 +-
 core/artwork/prune_test.go                    |  48 +-
 core/artwork/resolve.go                       |  16 +-
 core/artwork/uploader_test.go                 |  25 +-
 core/artwork/worker.go                        |  18 +-
 core/artwork/worker_soak_test.go              |  10 +-
 core/artwork/worker_test.go                   | 119 ++---
 core/auth/auth.go                             |   8 +-
 core/common.go                                |   2 +-
 core/external/extdata_helper_test.go          |  18 +-
 core/external/provider.go                     |  16 +-
 core/external/provider_refreshinfo_test.go    |   8 +-
 core/external/provider_similarsongs.go        |   8 +-
 .../external/provider_updatealbuminfo_test.go |   2 +-
 .../provider_updateartistinfo_test.go         |   2 +-
 core/library.go                               | 140 +++---
 core/library_test.go                          | 110 ++---
 core/lyrics/lyrics.go                         |   2 +-
 core/maintenance.go                           |  36 +-
 core/maintenance_test.go                      |  20 +-
 core/matcher/matcher.go                       |  10 +-
 core/matcher/matcher_test.go                  |   8 +-
 core/metrics/insights.go                      |  28 +-
 core/metrics/prometheus.go                    |   8 +-
 core/playback/device.go                       |   2 +-
 core/playback/playbackserver.go               |   2 +-
 core/players.go                               |  10 +-
 core/players_test.go                          |   6 +-
 core/playlists/import.go                      |  14 +-
 core/playlists/import_test.go                 |   6 +-
 core/playlists/parse_m3u.go                   |   6 +-
 core/playlists/parse_m3u_test.go              |   2 +-
 core/playlists/playlists.go                   |  61 +--
 core/playlists/playlists_test.go              |   6 +-
 core/playlists/rest_adapter.go                |  45 +-
 core/playlists/rest_adapter_test.go           | 120 ++---
 core/scrobbler/buffered_scrobbler.go          |  16 +-
 core/scrobbler/buffered_scrobbler_test.go     |  24 +-
 core/scrobbler/play_tracker.go                |  24 +-
 core/scrobbler/play_tracker_test.go           |  42 +-
 core/share.go                                 |  91 ++--
 core/share_test.go                            |  41 +-
 core/sonic/sonic.go                           |   6 +-
 core/stream/decider.go                        |   6 +-
 core/stream/media_streamer.go                 |   2 +-
 core/stream/media_streamer_test.go            |   6 +-
 core/user.go                                  |  56 +--
 core/user_test.go                             |  42 +-
 db/db.go                                      |   2 +-
 go.mod                                        |   2 +-
 go.sum                                        |  18 +-
 model/album.go                                |  34 +-
 model/annotation.go                           |  13 +-
 model/artist.go                               |  23 +-
 model/artwork.go                              |  55 ++-
 model/bookmark.go                             |  11 +-
 model/datastore.go                            |  49 +-
 model/folder.go                               |  21 +-
 model/genre.go                                |  11 +-
 model/get_entity.go                           |  10 +-
 model/get_entity_test.go                      |   6 +-
 model/library.go                              |  29 +-
 model/mediafile.go                            |  51 +-
 model/player.go                               |  15 +-
 model/playlist.go                             |  54 ++-
 model/playqueue.go                            |   9 +-
 model/plugin.go                               |  21 +-
 model/properties.go                           |  10 +-
 model/radio.go                                |  16 +-
 model/scrobble.go                             |  16 +-
 model/scrobble_buffer.go                      |  17 +-
 model/searchable.go                           |   4 +-
 model/share.go                                |  12 +-
 model/tag.go                                  |   9 +-
 model/transcoding.go                          |  16 +-
 model/user.go                                 |  29 +-
 model/user_props.go                           |  10 +-
 persistence/album_repository.go               | 137 +++---
 persistence/album_repository_test.go          | 338 +++++++------
 persistence/artist_repository.go              | 177 +++----
 persistence/artist_repository_test.go         | 434 ++++++++++-------
 persistence/artwork_hydration.go              |   2 +-
 persistence/artwork_hydration_test.go         | 120 ++---
 persistence/artwork_queue_repository.go       |  71 ++-
 persistence/artwork_queue_repository_test.go  | 228 ++++-----
 persistence/artwork_repository.go             |  48 +-
 persistence/artwork_repository_test.go        | 140 +++---
 persistence/criteria_sql_benchmark_test.go    |   6 +-
 persistence/e2e/e2e_suite_test.go             |  36 +-
 persistence/e2e/smartplaylist_test.go         |   4 +-
 persistence/folder_repository.go              |  87 ++--
 persistence/folder_repository_test.go         |  98 ++--
 persistence/genre_repository.go               |  36 +-
 persistence/genre_repository_test.go          |  79 ++-
 persistence/item_tags_test.go                 |  35 +-
 persistence/library_repository.go             | 136 +++---
 persistence/library_repository_test.go        |  81 ++--
 persistence/mediafile_repository.go           | 211 ++++----
 persistence/mediafile_repository_test.go      | 450 +++++++++---------
 persistence/persistence.go                    | 207 ++++----
 persistence/persistence_suite_test.go         |  62 +--
 persistence/persistence_test.go               |  36 +-
 persistence/player_repository.go              |  88 ++--
 persistence/player_repository_test.go         | 109 ++---
 persistence/playlist_repository.go            | 214 ++++-----
 persistence/playlist_repository_test.go       | 176 +++----
 persistence/playlist_track_repository.go      | 140 +++---
 persistence/playlist_track_repository_test.go | 153 +++---
 persistence/playqueue_repository.go           |  51 +-
 persistence/playqueue_repository_test.go      | 124 ++---
 persistence/plugin_cleanup_test.go            |  81 ++--
 persistence/plugin_repository.go              |  67 ++-
 persistence/plugin_repository_test.go         |  99 ++--
 persistence/property_repository.go            |  21 +-
 persistence/property_repository_test.go       |  14 +-
 persistence/radio_repository.go               |  97 ++--
 persistence/radio_repository_test.go          |  74 +--
 persistence/scrobble_buffer_repository.go     |  29 +-
 .../scrobble_buffer_repository_test.go        |  54 +--
 persistence/scrobble_repository.go            |  53 +--
 persistence/scrobble_repository_test.go       |  37 +-
 persistence/share_repository.go               | 116 +++--
 persistence/share_repository_test.go          | 260 +++++-----
 persistence/smart_playlist_repository.go      |  73 +--
 persistence/smart_playlist_repository_test.go | 191 ++++----
 persistence/sort_index_coverage_test.go       |   6 +-
 persistence/sql_annotations.go                |  55 +--
 persistence/sql_annotations_test.go           |  75 +--
 persistence/sql_base_repository.go            | 151 +++---
 persistence/sql_base_repository_test.go       |  61 +--
 persistence/sql_bookmarks.go                  |  77 +--
 persistence/sql_bookmarks_test.go             |  58 +--
 persistence/sql_participations.go             |  13 +-
 persistence/sql_restful.go                    |  14 +-
 persistence/sql_search.go                     |  21 +-
 persistence/sql_search_fts.go                 |   5 +-
 persistence/sql_search_fts_test.go            |  42 +-
 persistence/sql_search_like.go                |   5 +-
 persistence/sql_search_like_test.go           |  12 +-
 persistence/sql_tags.go                       |  49 +-
 persistence/tag_library_filtering_test.go     |  16 +-
 persistence/tag_repository.go                 |  31 +-
 persistence/tag_repository_test.go            |  65 +--
 persistence/transcoding_repository.go         |  81 ++--
 persistence/transcoding_repository_test.go    |  78 ++-
 persistence/user_props_repository.go          |  21 +-
 persistence/user_repository.go                | 188 ++++----
 persistence/user_repository_test.go           | 218 +++++----
 plugins/host_library.go                       |   4 +-
 plugins/host_library_test.go                  |  22 +-
 plugins/host_matcher_test.go                  |  44 +-
 plugins/host_scrobbleretriever.go             |   6 +-
 plugins/host_scrobbleretriever_test.go        |  28 +-
 plugins/host_storage_test.go                  |   2 +-
 plugins/host_subsonicapi.go                   |   2 +-
 plugins/host_subsonicapi_test.go              |  33 +-
 plugins/host_taskqueue.go                     |   2 +-
 plugins/host_users.go                         |   2 +-
 plugins/host_users_test.go                    |  26 +-
 plugins/host_websocket.go                     |   2 +-
 plugins/manager.go                            |  36 +-
 plugins/manager_loader.go                     |  10 +-
 plugins/manager_plugin.go                     |   2 +-
 plugins/manager_readonly_test.go              |  22 +-
 plugins/manager_sync.go                       |  22 +-
 plugins/manager_sync_test.go                  |  28 +-
 plugins/manager_watcher.go                    |  14 +-
 plugins/manager_watcher_test.go               |  20 +-
 scanner/controller.go                         |  16 +-
 scanner/controller_test.go                    |   6 +-
 scanner/image_changes.go                      |   6 +-
 scanner/phase_1_folders.go                    |  54 +--
 scanner/phase_2_missing_tracks.go             |  18 +-
 scanner/phase_2_missing_tracks_test.go        | 132 ++---
 scanner/phase_3_refresh_albums.go             |  12 +-
 scanner/phase_3_refresh_albums_test.go        |   4 +-
 scanner/phase_4_playlists.go                  |  16 +-
 scanner/phase_4_playlists_test.go             |  22 +-
 scanner/scanner.go                            |  32 +-
 scanner/scanner_benchmark_test.go             |   2 +-
 scanner/scanner_multilibrary_test.go          | 112 ++---
 scanner/scanner_selective_test.go             |  42 +-
 scanner/scanner_test.go                       | 148 +++---
 scanner/watcher.go                            |   4 +-
 server/auth.go                                |  31 +-
 server/auth_test.go                           |  28 +-
 server/events/sse.go                          |   2 +-
 server/initial_setup.go                       |  18 +-
 server/initial_setup_test.go                  |  24 +-
 server/jellyfin/annotations.go                |  12 +-
 server/jellyfin/annotations_test.go           |  44 +-
 server/jellyfin/api_test.go                   |  13 +-
 server/jellyfin/auth.go                       |   4 +-
 server/jellyfin/auth_test.go                  |  18 +-
 server/jellyfin/browsing.go                   |   6 +-
 server/jellyfin/browsing_test.go              |  30 +-
 server/jellyfin/e2e/auth_test.go              |   4 +-
 server/jellyfin/e2e/e2e_suite_test.go         |  10 +-
 server/jellyfin/e2e/multiuser_test.go         |   4 +-
 server/jellyfin/e2e/playlists_test.go         |  18 +-
 server/jellyfin/e2e/sessions_test.go          |   6 +-
 server/jellyfin/e2e/similar_test.go           |   4 +-
 server/jellyfin/images.go                     |   8 +-
 server/jellyfin/images_test.go                |  14 +-
 server/jellyfin/items.go                      |  52 +-
 server/jellyfin/items_test.go                 | 158 +++---
 server/jellyfin/lyrics_test.go                |   2 +-
 server/jellyfin/middlewares.go                |   2 +-
 server/jellyfin/middlewares_test.go           |  10 +-
 server/jellyfin/playlists.go                  |  16 +-
 server/jellyfin/playlists_test.go             |  14 +-
 server/jellyfin/quickconnect.go               |   4 +-
 server/jellyfin/quickconnect_test.go          |   7 +-
 server/jellyfin/similar.go                    |   2 +-
 server/jellyfin/similar_test.go               |   8 +-
 server/jellyfin/socket_test.go                |   5 +-
 server/jellyfin/stream.go                     |   2 +-
 server/jellyfin/stream_test.go                |  38 +-
 server/jellyfin/system.go                     |   4 +-
 server/jellyfin/system_test.go                |   8 +-
 server/jellyfin/users.go                      |   4 +-
 server/jellyfin/users_test.go                 |  14 +-
 server/middlewares.go                         |   2 +-
 server/middlewares_test.go                    |  10 +-
 server/nativeapi/artists.go                   |  16 +-
 server/nativeapi/config_test.go               |   9 +-
 server/nativeapi/inspect.go                   |   2 +-
 server/nativeapi/library_test.go              |  15 +-
 server/nativeapi/metadata_test.go             |  21 +-
 server/nativeapi/missing.go                   |  29 +-
 server/nativeapi/missing_test.go              |   5 +-
 server/nativeapi/native_api.go                |  57 +--
 server/nativeapi/native_api_song_test.go      |  12 +-
 server/nativeapi/playlists.go                 |  10 +-
 server/nativeapi/playlists_test.go            |  25 +-
 server/nativeapi/plugin.go                    |  20 +-
 server/nativeapi/plugin_test.go               |  42 +-
 server/nativeapi/queue.go                     |  12 +-
 server/nativeapi/queue_test.go                |   2 +-
 server/nativeapi/radios.go                    |  22 +-
 server/nativeapi/translations.go              |  20 +-
 .../user_password_token_refresh_test.go       |   9 +-
 server/public/handle_streams.go               |   6 +-
 server/public/handle_streams_test.go          |   6 +-
 server/serve_index.go                         |   2 +-
 server/serve_index_test.go                    |   3 +-
 server/subsonic/album_lists.go                |  14 +-
 server/subsonic/album_lists_test.go           |  20 +-
 server/subsonic/bookmarks.go                  |  30 +-
 server/subsonic/bookmarks_test.go             |   2 +-
 server/subsonic/browsing.go                   |  20 +-
 server/subsonic/browsing_test.go              |   8 +-
 server/subsonic/e2e/e2e_suite_test.go         |   6 +-
 .../subsonic/e2e/subsonic_album_lists_test.go |   4 +-
 server/subsonic/e2e/subsonic_artwork_test.go  |  14 +-
 .../subsonic/e2e/subsonic_bookmarks_test.go   |   4 +-
 server/subsonic/e2e/subsonic_browsing_test.go |  24 +-
 .../e2e/subsonic_media_annotation_test.go     |  14 +-
 .../e2e/subsonic_media_retrieval_test.go      |   4 +-
 .../e2e/subsonic_multilibrary_test.go         |  16 +-
 .../subsonic/e2e/subsonic_playlists_test.go   |  30 +-
 server/subsonic/e2e/subsonic_sharing_test.go  |  14 +-
 .../e2e/subsonic_sonic_similarity_test.go     |   4 +-
 server/subsonic/e2e/subsonic_stream_test.go   |   2 +-
 .../subsonic/e2e/subsonic_transcode_test.go   |  22 +-
 server/subsonic/library_scanning.go           |   4 +-
 server/subsonic/library_scanning_test.go      |  12 +-
 server/subsonic/media_annotation.go           |  22 +-
 server/subsonic/media_annotation_test.go      |   2 +-
 server/subsonic/media_retrieval.go            |   4 +-
 server/subsonic/media_retrieval_test.go       |   6 +-
 server/subsonic/middlewares.go                |   4 +-
 server/subsonic/middlewares_test.go           |  26 +-
 server/subsonic/radio.go                      |   8 +-
 server/subsonic/searching.go                  |  10 +-
 server/subsonic/searching_test.go             |   6 +-
 server/subsonic/sharing.go                    |  22 +-
 server/subsonic/stream.go                     |   2 +-
 server/subsonic/transcode.go                  |   4 +-
 tests/harness/harness.go                      |   8 +-
 tests/mock_album_repo.go                      |  35 +-
 tests/mock_artist_repo.go                     |  37 +-
 tests/mock_artwork_queue_repo.go              |  31 +-
 tests/mock_artwork_repo.go                    |  21 +-
 tests/mock_data_store.go                      | 123 ++---
 tests/mock_genre_repo.go                      |  25 +-
 tests/mock_library_repo.go                    |  55 +--
 tests/mock_library_service.go                 |  15 +-
 tests/mock_mediafile_repo.go                  |  81 ++--
 tests/mock_playlist_repo.go                   |  37 +-
 tests/mock_playlist_track_repo.go             |  28 +-
 tests/mock_playqueue_repo.go                  |   9 +-
 tests/mock_plugin_repo.go                     |  45 +-
 tests/mock_property_repo.go                   |  16 +-
 tests/mock_radio_repository.go                |  25 +-
 tests/mock_scrobble_buffer_repo.go            |  15 +-
 tests/mock_scrobble_repo.go                   |  24 +-
 tests/mock_share_repo.go                      |  16 +-
 tests/mock_tag_repo.go                        |   4 +-
 tests/mock_transcoding_repo.go                |  10 +-
 tests/mock_user_props_repo.go                 |  16 +-
 tests/mock_user_repo.go                       |  48 +-
 tests/mock_user_service.go                    |   7 +-
 339 files changed, 6220 insertions(+), 6173 deletions(-)

diff --git a/.golangci.yml b/.golangci.yml
index 7df4f8ec3..923c06c7a 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -9,6 +9,7 @@ linters:
     - asciicheck
     - bidichk
     - bodyclose
+    - containedctx
     - copyloopvar
     - dogsled
     - durationcheck
@@ -57,6 +58,9 @@ linters:
           - gosec
         path: _test\.go
         text: "G703"
+      - path: _test\.go
+        linters:
+          - containedctx
       - path-except: 'db/migrations/'
         linters:
           - forbidigo
diff --git a/adapters/lastfm/agent_test.go b/adapters/lastfm/agent_test.go
index b9fb786c3..0f68bd46b 100644
--- a/adapters/lastfm/agent_test.go
+++ b/adapters/lastfm/agent_test.go
@@ -357,7 +357,7 @@ var _ = Describe("lastfmAgent", func() {
 		var httpClient *tests.FakeHttpClient
 		var track *model.MediaFile
 		BeforeEach(func() {
-			_ = ds.UserProps(ctx).Put("user-1", sessionKeyProperty, "SK-1")
+			_ = ds.UserProps().Put(ctx, "user-1", sessionKeyProperty, "SK-1")
 			httpClient = &tests.FakeHttpClient{}
 			client := newClient("API_KEY", "SECRET", httpClient)
 			agent = lastFMConstructor(ds)
diff --git a/adapters/lastfm/auth_router_test.go b/adapters/lastfm/auth_router_test.go
index 1f65c059e..476daf443 100644
--- a/adapters/lastfm/auth_router_test.go
+++ b/adapters/lastfm/auth_router_test.go
@@ -50,7 +50,7 @@ var _ = Describe("auth_router", func() {
 	})
 
 	storedSessionKey := func(userID string) string {
-		key, _ := userProps.Get(userID, sessionKeyProperty)
+		key, _ := userProps.Get(GinkgoT().Context(), userID, sessionKeyProperty)
 		return key
 	}
 
diff --git a/adapters/listenbrainz/agent_test.go b/adapters/listenbrainz/agent_test.go
index a201b7c3a..d2aa07f1a 100644
--- a/adapters/listenbrainz/agent_test.go
+++ b/adapters/listenbrainz/agent_test.go
@@ -30,7 +30,7 @@ var _ = Describe("listenBrainzAgent", func() {
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
 		ctx = context.Background()
-		_ = ds.UserProps(ctx).Put("user-1", sessionKeyProperty, "SK-1")
+		_ = ds.UserProps().Put(ctx, "user-1", sessionKeyProperty, "SK-1")
 		httpClient = &tests.FakeHttpClient{}
 		agent = listenBrainzConstructor(ds)
 		agent.client = newClient("http://localhost:8080", httpClient)
diff --git a/cmd/artwork.go b/cmd/artwork.go
index 9a64cd8c3..72685678e 100644
--- a/cmd/artwork.go
+++ b/cmd/artwork.go
@@ -174,28 +174,28 @@ func queueTotal(stats []model.ArtworkQueueStat) int64 {
 }
 
 func collectStatus(ctx context.Context, ds model.DataStore) (statusReport, error) {
-	q := ds.ArtworkQueue(ctx)
+	q := ds.ArtworkQueue()
 	var rep statusReport
 	var err error
-	if rep.queue, err = q.CountQueued(nil, nil); err != nil {
+	if rep.queue, err = q.CountQueued(ctx, nil, nil); err != nil {
 		return rep, fmt.Errorf("breaking the artwork queue down by kind: %w", err)
 	}
 
 	for _, k := range artwork.ReprocessKinds {
-		sources, err := q.SourcesInUse(k)
+		sources, err := q.SourcesInUse(ctx, k)
 		if err != nil {
 			return rep, fmt.Errorf("listing the sources in use by %s artwork: %w", k, err)
 		}
 		slices.Sort(sources)
 		for _, s := range sources {
-			n, err := q.CountBySource(k, []string{s})
+			n, err := q.CountBySource(ctx, k, []string{s})
 			if err != nil {
 				return rep, fmt.Errorf("counting %s artwork resolved from %s: %w", k, displaySource(s), err)
 			}
 			rep.sources = append(rep.sources, sourceCount{kind: k, source: s, count: n})
 			// An absent state is exactly a row with no source, so it needs no second query.
 			if s == "" {
-				failed, err := q.CountBySource(k, []string{model.ArtworkSourceFailed})
+				failed, err := q.CountBySource(ctx, k, []string{model.ArtworkSourceFailed})
 				if err != nil {
 					return rep, fmt.Errorf("counting failed %s artwork: %w", k, err)
 				}
@@ -205,7 +205,7 @@ func collectStatus(ctx context.Context, ds model.DataStore) (statusReport, error
 	}
 
 	rep.current, rep.inputs = artwork.ConfigFingerprint(), artwork.FingerprintInputs()
-	if rep.stored, err = ds.Property(ctx).DefaultGet(consts.ArtConfFingerprintPropertyKey, ""); err != nil {
+	if rep.stored, err = ds.Property().DefaultGet(ctx, consts.ArtConfFingerprintPropertyKey, ""); err != nil {
 		return rep, fmt.Errorf("reading the stored artwork fingerprint: %w", err)
 	}
 	return rep, nil
@@ -442,13 +442,13 @@ func promptConfirm(in io.Reader, verb string) confirmFunc {
 
 // validateSources rejects a typo'd source: matching nothing silently reads as "nothing to do" when
 // it means the filter was wrong. Checked table-wide, so a filter is never a typo for one --kind only.
-func validateSources(q model.ArtworkQueueRepository, sources []string) error {
+func validateSources(ctx context.Context, q model.ArtworkQueueRepository, sources []string) error {
 	if len(sources) == 0 {
 		return nil
 	}
 	var inUse []string
 	for _, k := range artwork.ReprocessKinds {
-		found, err := q.SourcesInUse(k)
+		found, err := q.SourcesInUse(ctx, k)
 		if err != nil {
 			return fmt.Errorf("listing the sources in use by %s artwork: %w", k, err)
 		}
@@ -475,8 +475,8 @@ func validateSources(q model.ArtworkQueueRepository, sources []string) error {
 // actually inserted; the two differ because an already-queued row is left untouched.
 func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kind, sources []string,
 	imageAgents artwork.ImageAgentCount, dryRun bool, confirm confirmFunc, out io.Writer) error {
-	q := ds.ArtworkQueue(ctx)
-	if err := validateSources(q, sources); err != nil {
+	q := ds.ArtworkQueue()
+	if err := validateSources(ctx, q, sources); err != nil {
 		return err
 	}
 
@@ -495,7 +495,7 @@ func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kin
 	matched := make([]int64, len(kinds))
 	var total, external int64
 	for i, k := range kinds {
-		n, err := q.CountBySource(k, sources)
+		n, err := q.CountBySource(ctx, k, sources)
 		if err != nil {
 			return fmt.Errorf("counting %s artwork: %w", k, err)
 		}
@@ -523,7 +523,7 @@ func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kin
 		if matched[i] == 0 {
 			continue
 		}
-		n, err := q.EnqueueBySource(k, sources, model.ArtworkPriorityRecheck)
+		n, err := q.EnqueueBySource(ctx, k, sources, model.ArtworkPriorityRecheck)
 		if err != nil {
 			return fmt.Errorf("queueing %s artwork: %w", k, err)
 		}
@@ -590,8 +590,8 @@ func parseAll[T comparable](values []string, parse func(string) (T, error)) ([]T
 
 func cancelArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kind, priorities []int,
 	dryRun bool, confirm confirmFunc, out io.Writer) error {
-	q := ds.ArtworkQueue(ctx)
-	matched, err := q.CountQueued(kinds, priorities)
+	q := ds.ArtworkQueue()
+	matched, err := q.CountQueued(ctx, kinds, priorities)
 	if err != nil {
 		return fmt.Errorf("counting queued artwork: %w", err)
 	}
@@ -612,7 +612,7 @@ func cancelArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kind,
 		return nil
 	}
 
-	cancelled, err := q.PurgeQueued(kinds, priorities)
+	cancelled, err := q.PurgeQueued(ctx, kinds, priorities)
 	if err != nil {
 		return fmt.Errorf("cancelling queued artwork: %w", err)
 	}
@@ -984,11 +984,11 @@ func runExplain(ctx context.Context, args []string) {
 	}
 	rep := explainReport{kind: kind, id: id, name: name}
 	if artwork.KeepsState(kind) {
-		rep.stored, err = ds.Artwork(ctx).GetItemArtwork(kind, id, model.ImageTypePrimary)
+		rep.stored, err = ds.Artwork().GetItemArtwork(ctx, kind, id, model.ImageTypePrimary)
 		if err != nil && !errors.Is(err, model.ErrNotFound) {
 			log.Fatal(ctx, "Failed to read artwork state", "kind", kind, "id", id, err)
 		}
-		rep.queued, err = ds.ArtworkQueue(ctx).Get(kind, id, model.ImageTypePrimary)
+		rep.queued, err = ds.ArtworkQueue().Get(ctx, kind, id, model.ImageTypePrimary)
 		if err != nil && !errors.Is(err, model.ErrNotFound) {
 			log.Fatal(ctx, "Failed to read the artwork queue", "kind", kind, "id", id, err)
 		}
diff --git a/cmd/artwork_test.go b/cmd/artwork_test.go
index 71b450914..df0ea0665 100644
--- a/cmd/artwork_test.go
+++ b/cmd/artwork_test.go
@@ -491,17 +491,17 @@ var _ = Describe("explain/reprocess source round trip", func() {
 
 	It("names the absent state as reprocess --source accepts it", func() {
 		ds := &tests.MockDataStore{}
-		art := ds.Artwork(ctx).(*tests.MockArtworkRepo)
-		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: model.KindArtistArtwork.Prefix(),
+		art := ds.Artwork().(*tests.MockArtworkRepo)
+		Expect(art.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: model.KindArtistArtwork.Prefix(),
 			ItemID: "ar-1", ImageType: model.ImageTypePrimary})).To(Succeed())
 
 		shown := storedSource(formatExplain(explainReport{kind: model.KindArtistArtwork, id: "ar-1",
 			stored: &model.ItemArtwork{AttemptedAt: time.Now()}}))
 
-		q := ds.ArtworkQueue(ctx)
-		Expect(validateSources(q, repositorySources([]string{shown}))).To(Succeed(),
+		q := ds.ArtworkQueue()
+		Expect(validateSources(ctx, q, repositorySources([]string{shown}))).To(Succeed(),
 			"explain's spelling of a source must be pasteable into --source")
-		Expect(validateSources(q, repositorySources([]string{"(" + shown + ")"}))).ToNot(Succeed(),
+		Expect(validateSources(ctx, q, repositorySources([]string{"(" + shown + ")"}))).ToNot(Succeed(),
 			"a parenthesised name would be rejected, so explain must not print one")
 	})
 })
@@ -573,7 +573,7 @@ var _ = Describe("reprocessArtwork", func() {
 	decline := func(io.Writer, int64, int64) bool { return false }
 
 	put := func(kind model.Kind, id, source string) {
-		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: kind.Prefix(), ItemID: id,
+		Expect(art.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: kind.Prefix(), ItemID: id,
 			ImageType: model.ImageTypePrimary, Hash: "h" + id, Source: source})).To(Succeed())
 	}
 
@@ -584,8 +584,8 @@ var _ = Describe("reprocessArtwork", func() {
 		conf.Server.EnableM3UExternalAlbumArt = false
 		imageAgents = artwork.ImageAgentCount{Artist: 1, Album: 1}
 		ds = &tests.MockDataStore{}
-		art = ds.Artwork(ctx).(*tests.MockArtworkRepo)
-		queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)
+		art = ds.Artwork().(*tests.MockArtworkRepo)
+		queue = ds.ArtworkQueue().(*tests.MockArtworkQueueRepo)
 		out.Reset()
 		put(model.KindArtistArtwork, "ar-1", "external:deezer")
 		put(model.KindArtistArtwork, "ar-2", "")
@@ -601,19 +601,19 @@ var _ = Describe("reprocessArtwork", func() {
 		Expect(out.String()).To(ContainSubstring("album"))
 		Expect(out.String()).To(ContainSubstring("TOTAL"))
 		Expect(out.String()).To(ContainSubstring("Dry run"))
-		Expect(queue.Count()).To(BeZero())
+		Expect(queue.Count(ctx)).To(BeZero())
 	})
 
 	It("queues nothing when the operator declines", func() {
 		Expect(reprocessArtwork(ctx, ds, kinds, nil, imageAgents, false, decline, &out)).To(Succeed())
 
 		Expect(out.String()).To(ContainSubstring("Aborted"))
-		Expect(queue.Count()).To(BeZero())
+		Expect(queue.Count(ctx)).To(BeZero())
 	})
 
 	DescribeTable("records the applied config only for a run that leaves nothing on the old one",
 		func(selected []model.Kind, sources []string, dryRun, applied bool) {
-			Expect(ds.Property(ctx).Put(consts.ArtConfFingerprintPropertyKey, "stale-fingerprint")).To(Succeed())
+			Expect(ds.Property().Put(ctx, consts.ArtConfFingerprintPropertyKey, "stale-fingerprint")).To(Succeed())
 
 			Expect(reprocessArtwork(ctx, ds, selected, sources, imageAgents, dryRun, accept, &out)).To(Succeed())
 
@@ -621,7 +621,7 @@ var _ = Describe("reprocessArtwork", func() {
 			if applied {
 				want = artwork.ConfigFingerprint()
 			}
-			Expect(ds.Property(ctx).Get(consts.ArtConfFingerprintPropertyKey)).To(Equal(want))
+			Expect(ds.Property().Get(ctx, consts.ArtConfFingerprintPropertyKey)).To(Equal(want))
 		},
 		Entry("every kind, unfiltered", artwork.ReprocessKinds, nil, false, true),
 		Entry("every kind, but nothing matched", artwork.ReprocessKinds, []string{}, false, true),
@@ -633,14 +633,14 @@ var _ = Describe("reprocessArtwork", func() {
 	It("queues the matching items at recheck priority, leaving their artwork state alone", func() {
 		Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, false, accept, &out)).To(Succeed())
 
-		Expect(queue.Count()).To(Equal(int64(2)))
-		queued, err := queue.Get(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+		Expect(queue.Count(ctx)).To(Equal(int64(2)))
+		queued, err := queue.Get(ctx, model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(queued.Priority).To(Equal(model.ArtworkPriorityRecheck))
-		_, err = queue.Get(model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)
+		_, err = queue.Get(ctx, model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound), "a non-matching source must not be queued")
 
-		stored, err := art.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+		stored, err := art.GetItemArtwork(ctx, model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(stored.Hash).To(Equal("hal-1"), "bulk reprocessing must not blank the current artwork")
 	})
@@ -648,20 +648,20 @@ var _ = Describe("reprocessArtwork", func() {
 	It("targets the absent state", func() {
 		Expect(reprocessArtwork(ctx, ds, kinds, []string{""}, imageAgents, false, accept, &out)).To(Succeed())
 
-		Expect(queue.Count()).To(Equal(int64(1)))
-		_, err := queue.Get(model.KindArtistArtwork, "ar-2", model.ImageTypePrimary)
+		Expect(queue.Count(ctx)).To(Equal(int64(1)))
+		_, err := queue.Get(ctx, model.KindArtistArtwork, "ar-2", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 	})
 
 	It("reports matched and queued separately when part of the set is already queued", func() {
-		Expect(queue.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-1",
+		Expect(queue.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-1",
 			ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBump})).To(Succeed())
 
 		Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, false, accept, &out)).To(Succeed())
 
 		Expect(out.String()).To(ContainSubstring("Queued 1 of 2 matched items"))
 		Expect(out.String()).To(ContainSubstring("Already queued, left unchanged: 1"))
-		queued, err := queue.Get(model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
+		queued, err := queue.Get(ctx, model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(queued.Priority).To(Equal(model.ArtworkPriorityBump),
 			"an already-queued row keeps its priority and backoff")
@@ -675,7 +675,7 @@ var _ = Describe("reprocessArtwork", func() {
 			}, &out)).To(Succeed())
 
 		Expect(out.String()).To(ContainSubstring("Nothing"))
-		Expect(queue.Count()).To(BeZero())
+		Expect(queue.Count(ctx)).To(BeZero())
 	})
 
 	It("reports an empty selection as a dry run when one was asked for", func() {
@@ -767,7 +767,7 @@ var _ = Describe("reprocessArtwork", func() {
 		Expect(err.Error()).To(ContainSubstring("external:deezer"))
 		Expect(err.Error()).To(ContainSubstring("folder"))
 		Expect(err.Error()).To(ContainSubstring("absent"), "the empty source prints under its user-facing name")
-		Expect(queue.Count()).To(BeZero())
+		Expect(queue.Count(ctx)).To(BeZero())
 	})
 
 	It("accepts the absent filter with nothing absent, still rejecting a typo", func() {
@@ -777,7 +777,7 @@ var _ = Describe("reprocessArtwork", func() {
 			imageAgents, false, accept, &out)).To(Succeed(),
 			"a reserved source must stay valid once the library has none of it")
 		Expect(out.String()).To(ContainSubstring("Nothing matches"))
-		Expect(queue.Count()).To(BeZero())
+		Expect(queue.Count(ctx)).To(BeZero())
 
 		Expect(reprocessArtwork(ctx, ds, kinds, repositorySources([]string{"absnt"}),
 			imageAgents, true, accept, &out)).ToNot(Succeed(), "a typo must still be rejected")
@@ -797,7 +797,7 @@ var _ = Describe("reprocessArtwork", func() {
 
 		Expect(out.String()).To(ContainSubstring("Nothing matches"),
 			"a well-formed filter must not be reported as a typo because of the kinds selected")
-		Expect(queue.Count()).To(BeZero())
+		Expect(queue.Count(ctx)).To(BeZero())
 	})
 })
 
@@ -816,19 +816,19 @@ var _ = Describe("collectStatus", func() {
 
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
-		art = ds.Artwork(ctx).(*tests.MockArtworkRepo)
-		queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)
+		art = ds.Artwork().(*tests.MockArtworkRepo)
+		queue = ds.ArtworkQueue().(*tests.MockArtworkQueueRepo)
 		put := func(kind model.Kind, id, source, hash string, attempted time.Time) {
-			Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: kind.Prefix(), ItemID: id,
+			Expect(art.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: kind.Prefix(), ItemID: id,
 				ImageType: model.ImageTypePrimary, Source: source, Hash: hash, AttemptedAt: attempted})).To(Succeed())
 		}
 		put(model.KindArtistArtwork, "ar-1", "external:deezer", "h1", time.Now())
 		put(model.KindArtistArtwork, "ar-2", "", "", time.Now().Add(-24*time.Hour))
 		// ar-3 is absent because it gave up, so the two absent artists split across the columns.
-		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "ar-3",
+		Expect(art.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: "ar-3",
 			ImageType: model.ImageTypePrimary, LastFailure: "[]", AttemptedAt: time.Now()})).To(Succeed())
 		put(model.KindAlbumArtwork, "al-1", "folder", "h2", time.Now())
-		Expect(queue.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-9",
+		Expect(queue.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-9",
 			ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBackfill})).To(Succeed())
 	})
 
@@ -848,7 +848,7 @@ var _ = Describe("collectStatus", func() {
 	})
 
 	It("compares the stored fingerprint against the current one", func() {
-		Expect(ds.Property(ctx).Put(consts.ArtConfFingerprintPropertyKey, "old-fingerprint")).To(Succeed())
+		Expect(ds.Property().Put(ctx, consts.ArtConfFingerprintPropertyKey, "old-fingerprint")).To(Succeed())
 
 		rep, err := collectStatus(ctx, ds)
 		Expect(err).ToNot(HaveOccurred())
@@ -860,7 +860,7 @@ var _ = Describe("collectStatus", func() {
 	It("queues nothing", func() {
 		_, err := collectStatus(ctx, ds)
 		Expect(err).ToNot(HaveOccurred())
-		Expect(queue.Count()).To(Equal(int64(1)), "status must not enqueue anything")
+		Expect(queue.Count(ctx)).To(Equal(int64(1)), "status must not enqueue anything")
 	})
 })
 
@@ -973,21 +973,21 @@ var _ = Describe("refreshItems", func() {
 		albums := tests.CreateMockAlbumRepo()
 		albums.SetData(model.Albums{{ID: "al-1"}, {ID: "al-3"}})
 		ds = &tests.MockDataStore{MockedAlbum: albums}
-		art = ds.Artwork(ctx).(*tests.MockArtworkRepo)
-		queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)
+		art = ds.Artwork().(*tests.MockArtworkRepo)
+		queue = ds.ArtworkQueue().(*tests.MockArtworkQueueRepo)
 		out.Reset()
 	})
 
 	It("clears the stored state and queues each id at Bump priority", func() {
-		Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: model.KindAlbumArtwork.Prefix(),
+		Expect(art.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: model.KindAlbumArtwork.Prefix(),
 			ItemID: "al-1", ImageType: model.ImageTypePrimary, Hash: "abc123"})).To(Succeed())
 
 		Expect(refreshItems(ctx, ds, []model.ArtworkID{
 			{Kind: model.KindAlbumArtwork, ID: "al-1"}, {Kind: model.KindAlbumArtwork, ID: "al-3"}}, &out)).To(BeZero())
 
-		_, err := art.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+		_, err := art.GetItemArtwork(ctx, model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
-		queued, err := queue.Get(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+		queued, err := queue.Get(ctx, model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(queued.Priority).To(Equal(model.ArtworkPriorityBump))
 		Expect(out.String()).To(Equal("al/al-1: queued\nal/al-3: queued\n"))
@@ -996,7 +996,7 @@ var _ = Describe("refreshItems", func() {
 	It("skips an id that does not exist instead of queuing it", func() {
 		Expect(refreshItems(ctx, ds, []model.ArtworkID{{Kind: model.KindAlbumArtwork, ID: "al-2"}}, &out)).To(Equal(1))
 
-		_, err := queue.Get(model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)
+		_, err := queue.Get(ctx, model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound), "a typo must not leave an orphan queue row")
 		Expect(out.String()).To(BeEmpty())
 	})
@@ -1145,9 +1145,9 @@ var _ = Describe("cancelArtwork", func() {
 
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
-		queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)
+		queue = ds.ArtworkQueue().(*tests.MockArtworkQueueRepo)
 		out.Reset()
-		Expect(queue.Enqueue(
+		Expect(queue.Enqueue(ctx,
 			model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-1", ImageType: model.ImageTypePrimary,
 				Priority: model.ArtworkPriorityBackfill},
 			model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-2", ImageType: model.ImageTypePrimary,
@@ -1164,28 +1164,28 @@ var _ = Describe("cancelArtwork", func() {
 		Expect(out.String()).To(ContainSubstring("backfill"))
 		Expect(out.String()).To(ContainSubstring("TOTAL"))
 		Expect(out.String()).To(ContainSubstring("Dry run"))
-		Expect(queue.Count()).To(BeNumerically("==", 3))
+		Expect(queue.Count(ctx)).To(BeNumerically("==", 3))
 	})
 
 	It("cancels nothing when the operator declines", func() {
 		Expect(cancelArtwork(ctx, ds, nil, nil, false, decline, &out)).To(Succeed())
 
 		Expect(out.String()).To(ContainSubstring("Aborted"))
-		Expect(queue.Count()).To(BeNumerically("==", 3))
+		Expect(queue.Count(ctx)).To(BeNumerically("==", 3))
 	})
 
 	It("deletes the selected rows and leaves the rest queued", func() {
 		Expect(cancelArtwork(ctx, ds, nil, []int{model.ArtworkPriorityBackfill}, false, accept, &out)).To(Succeed())
 
-		Expect(queue.Count()).To(BeNumerically("==", 1))
-		_, err := queue.Get(model.KindArtistArtwork, "ar-2", model.ImageTypePrimary)
+		Expect(queue.Count(ctx)).To(BeNumerically("==", 1))
+		_, err := queue.Get(ctx, model.KindArtistArtwork, "ar-2", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred(), "a non-matching priority must stay queued")
 		Expect(out.String()).To(ContainSubstring("Cancelled 2 of 2 matched items."))
 	})
 
 	It("cancels every kind and priority when neither filter is given", func() {
 		Expect(cancelArtwork(ctx, ds, nil, nil, false, accept, &out)).To(Succeed())
-		Expect(queue.Count()).To(BeZero())
+		Expect(queue.Count(ctx)).To(BeZero())
 	})
 
 	It("stops at a selection that matches nothing instead of prompting", func() {
@@ -1196,7 +1196,7 @@ var _ = Describe("cancelArtwork", func() {
 		Expect(cancelArtwork(ctx, ds, []model.Kind{model.KindPlaylistArtwork}, nil, false, refuse, &out)).To(Succeed())
 
 		Expect(out.String()).To(ContainSubstring("Nothing matches this selection."))
-		Expect(queue.Count()).To(BeNumerically("==", 3))
+		Expect(queue.Count(ctx)).To(BeNumerically("==", 3))
 	})
 
 	It("reports a queue read failure instead of reporting nothing to cancel", func() {
diff --git a/cmd/missing.go b/cmd/missing.go
index 65f571661..ce95e39f0 100644
--- a/cmd/missing.go
+++ b/cmd/missing.go
@@ -72,7 +72,7 @@ func runMissingList(ctx context.Context) {
 	}
 
 	ds, ctx := getAdminContext(ctx)
-	mfs, err := ds.MediaFile(ctx).GetCursor(model.QueryOptions{
+	mfs, err := ds.MediaFile().GetCursor(ctx, model.QueryOptions{
 		Filters: squirrel.Eq{"missing": true},
 		Sort:    "path",
 	})
@@ -128,7 +128,7 @@ func runMissingFix(ctx context.Context, missingRef, targetRef string) {
 
 // resolveMediaFile looks up a media file by ID first, then by path (optionally libraryID:path).
 func resolveMediaFile(ctx context.Context, ds model.DataStore, ref string) *model.MediaFile {
-	mf, err := ds.MediaFile(ctx).Get(ref)
+	mf, err := ds.MediaFile().Get(ctx, ref)
 	if err == nil {
 		return mf
 	}
@@ -136,7 +136,7 @@ func resolveMediaFile(ctx context.Context, ds model.DataStore, ref string) *mode
 		log.Fatal(ctx, "Error looking up media file", "ref", ref, err)
 	}
 
-	mfs, err := ds.MediaFile(ctx).FindByPaths([]string{ref})
+	mfs, err := ds.MediaFile().FindByPaths(ctx, []string{ref})
 	if err != nil {
 		log.Fatal(ctx, "Error looking up media file by path", "ref", ref, err)
 	}
diff --git a/cmd/pls.go b/cmd/pls.go
index 93b411483..bf16ea420 100644
--- a/cmd/pls.go
+++ b/cmd/pls.go
@@ -109,7 +109,7 @@ func fetchPlaylists(ctx context.Context, ds model.DataStore, sort string) model.
 		}
 		options.Filters = squirrel.Eq{"owner_id": user.ID}
 	}
-	pls, err := ds.Playlist(ctx).GetAll(options)
+	pls, err := ds.Playlist().GetAll(ctx, options)
 	if err != nil {
 		log.Fatal(ctx, "Failed to retrieve playlists", err)
 	}
@@ -117,17 +117,17 @@ func fetchPlaylists(ctx context.Context, ds model.DataStore, sort string) model.
 }
 
 func findPlaylist(ctx context.Context, ds model.DataStore, nameOrID string) *model.Playlist {
-	playlist, err := ds.Playlist(ctx).GetWithTracks(nameOrID, true, false)
+	playlist, err := ds.Playlist().GetWithTracks(ctx, nameOrID, true, false)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		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": nameOrID}})
+		playlists, err := ds.Playlist().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"playlist.name": nameOrID}})
 		if err != nil {
 			log.Fatal("Error retrieving playlist", "name", nameOrID, err)
 		}
 		if len(playlists) > 0 {
-			playlist, err = ds.Playlist(ctx).GetWithTracks(playlists[0].ID, true, false)
+			playlist, err = ds.Playlist().GetWithTracks(ctx, playlists[0].ID, true, false)
 			if err != nil {
 				log.Fatal("Error retrieving playlist", "name", nameOrID, err)
 			}
@@ -194,7 +194,7 @@ func runExport(ctx context.Context) {
 
 	exported := 0
 	for _, pls := range allPls {
-		plsWithTracks, err := ds.Playlist(ctx).GetWithTracks(pls.ID, true, false)
+		plsWithTracks, err := ds.Playlist().GetWithTracks(ctx, pls.ID, true, false)
 		if err != nil {
 			log.Error("Error loading playlist tracks", "playlist", pls.Name, err)
 			continue
diff --git a/cmd/plugin.go b/cmd/plugin.go
index ded28e969..7b8a9a393 100644
--- a/cmd/plugin.go
+++ b/cmd/plugin.go
@@ -243,7 +243,7 @@ func runPluginInfo(ctx context.Context, arg string) {
 	}
 	requirePluginsEnabled(ctx)
 	ds, ctx := getAdminContext(ctx)
-	p, err := ds.Plugin(ctx).Get(arg)
+	p, err := ds.Plugin().Get(ctx, arg)
 	if err != nil {
 		log.Fatal(ctx, "Plugin not found", "id", arg, err)
 	}
@@ -264,7 +264,7 @@ func runPluginValidate(ctx context.Context, arg string) {
 	}
 	requirePluginsEnabled(ctx)
 	ds, ctx := getAdminContext(ctx)
-	p, err := ds.Plugin(ctx).Get(arg)
+	p, err := ds.Plugin().Get(ctx, arg)
 	if err != nil {
 		log.Fatal(ctx, "Plugin not found", "id", arg, err)
 	}
@@ -329,7 +329,7 @@ func formatPluginList(list model.Plugins, format string) (string, error) {
 func runPluginList(ctx context.Context) {
 	requirePluginsEnabled(ctx)
 	ds, ctx := getAdminContext(ctx)
-	list, err := ds.Plugin(ctx).GetAll()
+	list, err := ds.Plugin().GetAll(ctx)
 	if err != nil {
 		log.Fatal(ctx, "Failed to list plugins", err)
 	}
@@ -372,7 +372,7 @@ var pluginEditCmd = &cobra.Command{
 	Run: func(cmd *cobra.Command, args []string) {
 		requirePluginsEnabled(cmd.Context())
 		ds, ctx := getAdminContext(cmd.Context())
-		cur, err := ds.Plugin(ctx).Get(args[0])
+		cur, err := ds.Plugin().Get(ctx, args[0])
 		if err != nil {
 			log.Fatal(ctx, "Plugin not found", "id", args[0], err)
 		}
diff --git a/cmd/root.go b/cmd/root.go
index 02cd30240..b23674441 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -184,11 +184,11 @@ func schedulePeriodicScan(ctx context.Context) func() error {
 }
 
 func pidHashChanged(ds model.DataStore) (bool, error) {
-	pidAlbum, err := ds.Property(context.Background()).DefaultGet(consts.PIDAlbumKey, "")
+	pidAlbum, err := ds.Property().DefaultGet(context.Background(), consts.PIDAlbumKey, "")
 	if err != nil {
 		return false, err
 	}
-	pidTrack, err := ds.Property(context.Background()).DefaultGet(consts.PIDTrackKey, "")
+	pidTrack, err := ds.Property().DefaultGet(context.Background(), consts.PIDTrackKey, "")
 	if err != nil {
 		return false, err
 	}
@@ -199,11 +199,11 @@ func pidHashChanged(ds model.DataStore) (bool, error) {
 func runInitialScan(ctx context.Context) func() error {
 	return func() error {
 		ds := CreateDataStore()
-		fullScanRequired, err := ds.Property(ctx).DefaultGet(consts.FullScanAfterMigrationFlagKey, "0")
+		fullScanRequired, err := ds.Property().DefaultGet(ctx, consts.FullScanAfterMigrationFlagKey, "0")
 		if err != nil {
 			return err
 		}
-		inProgress, err := ds.Library(ctx).ScanInProgress()
+		inProgress, err := ds.Library().ScanInProgress(ctx)
 		if err != nil {
 			return err
 		}
@@ -219,7 +219,7 @@ func runInitialScan(ctx context.Context) func() error {
 			switch {
 			case fullScanRequired == "1":
 				log.Warn(ctx, "Full scan required after migration")
-				_ = ds.Property(ctx).Delete(consts.FullScanAfterMigrationFlagKey)
+				_ = ds.Property().Delete(ctx, consts.FullScanAfterMigrationFlagKey)
 			case pidHasChanged:
 				log.Warn(ctx, "PID config changed, performing full scan")
 				fullScanRequired = "1"
diff --git a/cmd/svc.go b/cmd/svc.go
index 7fec708ff..c71f5ef2b 100644
--- a/cmd/svc.go
+++ b/cmd/svc.go
@@ -44,7 +44,7 @@ var svcCmd = &cobra.Command{
 }
 
 type svcControl struct {
-	ctx    context.Context
+	ctx    context.Context //nolint:containedctx // service lifecycle ctx, cancelled by Stop
 	cancel context.CancelFunc
 	done   chan struct{}
 }
diff --git a/cmd/user.go b/cmd/user.go
index 1abf157b7..eb64e69fe 100644
--- a/cmd/user.go
+++ b/cmd/user.go
@@ -183,7 +183,7 @@ func runCreateUser(ctx context.Context) {
 	ds, ctx := getAdminContext(ctx)
 
 	err := ds.WithTx(func(tx model.DataStore) error {
-		existingUser, err := tx.User(ctx).FindByUsername(userID)
+		existingUser, err := tx.User().FindByUsername(ctx, userID)
 		if existingUser != nil {
 			return fmt.Errorf("existing user '%s'", userID)
 		}
@@ -193,7 +193,7 @@ func runCreateUser(ctx context.Context) {
 		}
 
 		if len(libraryIds) > 0 && !setAdmin {
-			user.Libraries, err = tx.Library(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"id": libraryIds}})
+			user.Libraries, err = tx.Library().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"id": libraryIds}})
 			if err != nil {
 				return err
 			}
@@ -202,13 +202,13 @@ func runCreateUser(ctx context.Context) {
 				return libraryError(user.Libraries)
 			}
 		} else {
-			user.Libraries, err = tx.Library(ctx).GetAll()
+			user.Libraries, err = tx.Library().GetAll(ctx)
 			if err != nil {
 				return err
 			}
 		}
 
-		err = tx.User(ctx).Put(&user)
+		err = tx.User().Put(ctx, &user)
 		if err != nil {
 			return err
 		}
@@ -218,7 +218,7 @@ func runCreateUser(ctx context.Context) {
 			updatedIds[idx] = lib.ID
 		}
 
-		err = tx.User(ctx).SetUserLibraries(user.ID, updatedIds)
+		err = tx.User().SetUserLibraries(ctx, user.ID, updatedIds)
 		return err
 	})
 
@@ -236,7 +236,7 @@ func runDeleteUser(ctx context.Context) {
 	var user *model.User
 
 	err = ds.WithTx(func(tx model.DataStore) error {
-		count, err := tx.User(ctx).CountAll()
+		count, err := tx.User().CountAll(ctx)
 		if err != nil {
 			return err
 		}
@@ -250,7 +250,7 @@ func runDeleteUser(ctx context.Context) {
 			return err
 		}
 
-		return tx.User(ctx).Delete(user.ID)
+		return tx.User().Delete(ctx, user.ID)
 	})
 
 	if err != nil {
@@ -276,7 +276,7 @@ func runUserEdit(ctx context.Context) {
 		}
 
 		if len(libraryIds) > 0 && !setAdmin {
-			libraries, err := tx.Library(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"id": libraryIds}})
+			libraries, err := tx.Library().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"id": libraryIds}})
 
 			if err != nil {
 				return err
@@ -291,7 +291,7 @@ func runUserEdit(ctx context.Context) {
 		}
 
 		if setAdmin && !user.IsAdmin {
-			libraries, err := tx.Library(ctx).GetAll()
+			libraries, err := tx.Library().GetAll(ctx)
 			if err != nil {
 				return err
 			}
@@ -337,7 +337,7 @@ func runUserEdit(ctx context.Context) {
 			return nil
 		}
 
-		err := tx.User(ctx).Put(user)
+		err := tx.User().Put(ctx, user)
 		if err != nil {
 			return err
 		}
@@ -348,7 +348,7 @@ func runUserEdit(ctx context.Context) {
 				updatedIds[idx] = lib.ID
 			}
 
-			err := tx.User(ctx).SetUserLibraries(user.ID, updatedIds)
+			err := tx.User().SetUserLibraries(ctx, user.ID, updatedIds)
 			if err != nil {
 				return err
 			}
@@ -393,13 +393,11 @@ func runUserList(ctx context.Context) {
 
 	ds, ctx := getAdminContext(ctx)
 
-	users, err := ds.User(ctx).ReadAll()
+	userList, err := ds.User().ReadAll(ctx)
 	if err != nil {
 		log.Fatal(ctx, "Failed to retrieve users", err)
 	}
 
-	userList := users.(model.Users)
-
 	if outputFormat == "csv" {
 		w := csv.NewWriter(os.Stdout)
 		_ = w.Write([]string{
diff --git a/cmd/utils.go b/cmd/utils.go
index a67f720ac..72ec67f90 100644
--- a/cmd/utils.go
+++ b/cmd/utils.go
@@ -52,14 +52,14 @@ func getAdminContext(ctx context.Context) (model.DataStore, context.Context) {
 }
 
 func getUser(ctx context.Context, id string, ds model.DataStore) (*model.User, error) {
-	user, err := ds.User(ctx).FindByUsername(id)
+	user, err := ds.User().FindByUsername(ctx, id)
 
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return nil, fmt.Errorf("finding user by name: %w", err)
 	}
 
 	if errors.Is(err, model.ErrNotFound) {
-		user, err = ds.User(ctx).Get(id)
+		user, err = ds.User().Get(ctx, id)
 		if err != nil {
 			return nil, fmt.Errorf("finding user by id: %w", err)
 		}
diff --git a/core/agents/local_agent.go b/core/agents/local_agent.go
index 1cb9060a1..c777ab46d 100644
--- a/core/agents/local_agent.go
+++ b/core/agents/local_agent.go
@@ -24,7 +24,7 @@ func (p *localAgent) AgentName() string {
 }
 
 func (p *localAgent) GetArtistTopSongs(ctx context.Context, id, artistName, mbid string, count int) ([]Song, error) {
-	top, err := p.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	top, err := p.ds.MediaFile().GetAll(ctx, model.QueryOptions{
 		Sort:  "playCount",
 		Order: "desc",
 		Max:   count,
@@ -43,7 +43,7 @@ func (p *localAgent) GetArtistTopSongs(ctx context.Context, id, artistName, mbid
 }
 
 func (p *localAgent) GetSimilarSongsByTrack(ctx context.Context, id, name, artist, mbid string, count int) ([]Song, error) {
-	seed, err := p.ds.MediaFile(ctx).Get(id)
+	seed, err := p.ds.MediaFile().Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
@@ -53,7 +53,7 @@ func (p *localAgent) GetSimilarSongsByTrack(ctx context.Context, id, name, artis
 		return nil, nil
 	}
 	// Ask for extra so we can drop the seed itself and still fill the count.
-	candidates, err := p.ds.MediaFile(ctx).GetRandom(model.QueryOptions{
+	candidates, err := p.ds.MediaFile().GetRandom(ctx, model.QueryOptions{
 		Filters: squirrel.And{
 			persistence.SongGenres.ByID(genreIDs),
 			squirrel.Eq{"missing": false},
diff --git a/core/agents/session_keys.go b/core/agents/session_keys.go
index cea6005ff..1eb414b15 100644
--- a/core/agents/session_keys.go
+++ b/core/agents/session_keys.go
@@ -13,13 +13,13 @@ type SessionKeys struct {
 }
 
 func (sk *SessionKeys) Put(ctx context.Context, userId, sessionKey string) error {
-	return sk.DataStore.UserProps(ctx).Put(userId, sk.KeyName, sessionKey)
+	return sk.DataStore.UserProps().Put(ctx, userId, sk.KeyName, sessionKey)
 }
 
 func (sk *SessionKeys) Get(ctx context.Context, userId string) (string, error) {
-	return sk.DataStore.UserProps(ctx).Get(userId, sk.KeyName)
+	return sk.DataStore.UserProps().Get(ctx, userId, sk.KeyName)
 }
 
 func (sk *SessionKeys) Delete(ctx context.Context, userId string) error {
-	return sk.DataStore.UserProps(ctx).Delete(userId, sk.KeyName)
+	return sk.DataStore.UserProps().Delete(ctx, userId, sk.KeyName)
 }
diff --git a/core/archiver.go b/core/archiver.go
index 33236d889..6f362322a 100644
--- a/core/archiver.go
+++ b/core/archiver.go
@@ -62,7 +62,7 @@ func (a *archiver) ZipArtist(ctx context.Context, id string, format string, bitr
 
 // rootArt, when set, is added to the archive root.
 func (a *archiver) zipAlbums(ctx context.Context, id string, format string, bitrate int, out io.Writer, filters squirrel.Sqlizer, rootArt model.ArtworkID) error {
-	mfs, err := a.ds.MediaFile(ctx).GetAll(model.QueryOptions{Filters: filters, Sort: "album"})
+	mfs, err := a.ds.MediaFile().GetAll(ctx, model.QueryOptions{Filters: filters, Sort: "album"})
 	if err != nil {
 		log.Error(ctx, "Error loading mediafiles from artist", "id", id, err)
 		return err
@@ -189,7 +189,7 @@ func (a *archiver) ZipShare(ctx context.Context, s *model.Share, out io.Writer)
 }
 
 func (a *archiver) ZipPlaylist(ctx context.Context, id string, format string, bitrate int, out io.Writer) error {
-	pls, err := a.ds.Playlist(ctx).GetWithTracks(id, true, false)
+	pls, err := a.ds.Playlist().GetWithTracks(ctx, id, true, false)
 	if err != nil {
 		log.Error(ctx, "Error loading mediafiles from playlist", "id", id, err)
 		return err
diff --git a/core/archiver_test.go b/core/archiver_test.go
index 9dab44cef..4e00ce78c 100644
--- a/core/archiver_test.go
+++ b/core/archiver_test.go
@@ -52,7 +52,7 @@ var _ = Describe("Archiver", func() {
 				Sort:    "album",
 			}}).Return(mfs, nil)
 
-			ds.On("MediaFile", mock.Anything).Return(mfRepo)
+			ds.On("MediaFile").Return(mfRepo)
 			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)
@@ -84,7 +84,7 @@ var _ = Describe("Archiver", func() {
 				Sort: "album",
 			}}).Return(mfs, nil)
 
-			ds.On("MediaFile", mock.Anything).Return(mfRepo)
+			ds.On("MediaFile").Return(mfRepo)
 			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)
@@ -246,7 +246,7 @@ var _ = Describe("Archiver", func() {
 				Filters: squirrel.Eq{"album_id": "1"},
 				Sort:    "album",
 			}}).Return(mfs, nil)
-			ds.On("MediaFile", mock.Anything).Return(mfRepo)
+			ds.On("MediaFile").Return(mfRepo)
 
 			ms.On("NewStream", mock.Anything, mock.Anything, stream.Request{Format: "mp3", BitRate: 128}).
 				Return(nil, stream.ErrTooManyTranscodes).Once()
@@ -310,7 +310,7 @@ var _ = Describe("Archiver", func() {
 
 			plRepo := &mockPlaylistRepository{}
 			plRepo.On("GetWithTracks", "1", true, false).Return(pls, nil)
-			ds.On("Playlist", mock.Anything).Return(plRepo)
+			ds.On("Playlist").Return(plRepo)
 			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)
@@ -515,17 +515,17 @@ type mockDataStore struct {
 	model.DataStore
 }
 
-func (m *mockDataStore) MediaFile(ctx context.Context) model.MediaFileRepository {
-	args := m.Called(ctx)
+func (m *mockDataStore) MediaFile() model.MediaFileRepository {
+	args := m.Called()
 	return args.Get(0).(model.MediaFileRepository)
 }
 
-func (m *mockDataStore) Playlist(ctx context.Context) model.PlaylistRepository {
-	args := m.Called(ctx)
+func (m *mockDataStore) Playlist() model.PlaylistRepository {
+	args := m.Called()
 	return args.Get(0).(model.PlaylistRepository)
 }
 
-func (m *mockDataStore) Library(context.Context) model.LibraryRepository {
+func (m *mockDataStore) Library() model.LibraryRepository {
 	return &mockLibraryRepository{}
 }
 
@@ -534,7 +534,7 @@ type mockLibraryRepository struct {
 	model.LibraryRepository
 }
 
-func (m *mockLibraryRepository) GetPath(id int) (string, error) {
+func (m *mockLibraryRepository) GetPath(_ context.Context, id int) (string, error) {
 	return "/music", nil
 }
 
@@ -543,7 +543,7 @@ type mockMediaFileRepository struct {
 	model.MediaFileRepository
 }
 
-func (m *mockMediaFileRepository) GetAll(options ...model.QueryOptions) (model.MediaFiles, error) {
+func (m *mockMediaFileRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.MediaFiles, error) {
 	args := m.Called(options)
 	return args.Get(0).(model.MediaFiles), args.Error(1)
 }
@@ -553,7 +553,7 @@ type mockPlaylistRepository struct {
 	model.PlaylistRepository
 }
 
-func (m *mockPlaylistRepository) GetWithTracks(id string, refreshSmartPlaylists, includeMissing bool) (*model.Playlist, error) {
+func (m *mockPlaylistRepository) GetWithTracks(_ context.Context, id string, refreshSmartPlaylists, includeMissing bool) (*model.Playlist, error) {
 	args := m.Called(id, refreshSmartPlaylists, includeMissing)
 	return args.Get(0).(*model.Playlist), args.Error(1)
 }
diff --git a/core/artwork/artwork.go b/core/artwork/artwork.go
index e27fa118e..2a9ebe771 100644
--- a/core/artwork/artwork.go
+++ b/core/artwork/artwork.go
@@ -59,21 +59,21 @@ func entityExists(ctx context.Context, ds model.DataStore, artID model.ArtworkID
 	var err error
 	switch artID.Kind {
 	case model.KindArtistArtwork:
-		found, err = ds.Artist(ctx).Exists(artID.ID)
+		found, err = ds.Artist().Exists(ctx, artID.ID)
 	case model.KindAlbumArtwork:
-		found, err = ds.Album(ctx).Exists(artID.ID)
+		found, err = ds.Album().Exists(ctx, artID.ID)
 	case model.KindMediaFileArtwork:
-		found, err = ds.MediaFile(ctx).Exists(artID.ID)
+		found, err = ds.MediaFile().Exists(ctx, artID.ID)
 	case model.KindPlaylistArtwork:
-		found, err = ds.Playlist(ctx).Exists(artID.ID)
+		found, err = ds.Playlist().Exists(ctx, artID.ID)
 	case model.KindRadioArtwork:
-		found, err = ds.Radio(ctx).Exists(artID.ID)
+		found, err = ds.Radio().Exists(ctx, artID.ID)
 	case model.KindDiscArtwork:
 		albumID, _, perr := model.ParseDiscArtworkID(artID.ID)
 		if perr != nil {
 			return false
 		}
-		found, err = ds.Album(ctx).Exists(albumID)
+		found, err = ds.Album().Exists(ctx, albumID)
 	default:
 		return false
 	}
@@ -119,7 +119,7 @@ func (s *service) Get(ctx context.Context, artID model.ArtworkID, size int, squa
 }
 
 func (s *service) serveEntity(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {
-	ia, err := s.ds.Artwork(ctx).GetItemArtwork(artID.Kind, artID.ID, model.ImageTypePrimary)
+	ia, err := s.ds.Artwork().GetItemArtwork(ctx, artID.Kind, artID.ID, model.ImageTypePrimary)
 	switch {
 	case errors.Is(err, model.ErrNotFound):
 		return s.provisional(ctx, artID, size, square)
@@ -173,7 +173,7 @@ func (s *service) serveHash(ctx context.Context, artID model.ArtworkID, ia *mode
 		log.Warn(ctx, "Artwork: Stored source is not an image file, re-resolving", "artID", artID, "path", ia.SourcePath)
 		return s.dangling(ctx, artID)
 	}
-	art, err := s.ds.Artwork(ctx).GetImage(ia.Hash)
+	art, err := s.ds.Artwork().GetImage(ctx, ia.Hash)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
 			return s.dangling(ctx, artID)
@@ -264,13 +264,13 @@ func (s *service) serveMediaFile(ctx context.Context, artID model.ArtworkID, siz
 	// The setting is not in the config fingerprint, so honor it at serve time: a direct mf- URL
 	// must fall back to disc/album instead of serving stale persisted embedded art.
 	if !conf.Server.EnableMediaFileCoverArt {
-		mf, err := s.ds.MediaFile(ctx).Get(artID.ID)
+		mf, err := s.ds.MediaFile().Get(ctx, artID.ID)
 		if err != nil {
 			return nil, err
 		}
 		return s.Get(ctx, mf.DiscCoverArtID(), size, square)
 	}
-	ia, err := s.ds.Artwork(ctx).GetItemArtwork(model.KindMediaFileArtwork, artID.ID, model.ImageTypePrimary)
+	ia, err := s.ds.Artwork().GetItemArtwork(ctx, model.KindMediaFileArtwork, artID.ID, model.ImageTypePrimary)
 	switch {
 	case err == nil && ia.Hash != "":
 		return s.serveHash(ctx, artID, ia, size, square)
@@ -283,7 +283,7 @@ func (s *service) serveMediaFile(ctx context.Context, artID model.ArtworkID, siz
 	}
 	noRow := errors.Is(err, model.ErrNotFound)
 
-	mf, err := s.ds.MediaFile(ctx).Get(artID.ID)
+	mf, err := s.ds.MediaFile().Get(ctx, artID.ID)
 	if err != nil {
 		return nil, err
 	}
@@ -342,7 +342,7 @@ func (s *service) dangling(ctx context.Context, artID model.ArtworkID) (*Image,
 }
 
 func (s *service) enqueue(ctx context.Context, artID model.ArtworkID, priority int) {
-	err := s.ds.ArtworkQueue(ctx).EnqueuePreservingBackoff(model.ArtworkQueueItem{
+	err := s.ds.ArtworkQueue().EnqueuePreservingBackoff(ctx, model.ArtworkQueueItem{
 		ItemKind:  artID.Kind.Prefix(),
 		ItemID:    artID.ID,
 		ImageType: model.ImageTypePrimary,
diff --git a/core/artwork/artwork_suite_test.go b/core/artwork/artwork_suite_test.go
index 93aacc1fa..921a77b89 100644
--- a/core/artwork/artwork_suite_test.go
+++ b/core/artwork/artwork_suite_test.go
@@ -1,6 +1,7 @@
 package artwork
 
 import (
+	"context"
 	"io/fs"
 	"net/netip"
 	"net/url"
@@ -108,15 +109,15 @@ type fakeFolderRepo struct {
 	otherAudioErr error
 }
 
-func (f *fakeFolderRepo) GetAll(...model.QueryOptions) ([]model.Folder, error) {
+func (f *fakeFolderRepo) GetAll(context.Context, ...model.QueryOptions) ([]model.Folder, error) {
 	return f.result, f.err
 }
 
-func (f *fakeFolderRepo) HasAudioOutsideFolders(model.Folder, []string) (bool, error) {
+func (f *fakeFolderRepo) HasAudioOutsideFolders(context.Context, model.Folder, []string) (bool, error) {
 	return f.hasOtherAudio, f.otherAudioErr
 }
 
-func (f *fakeFolderRepo) Get(string) (*model.Folder, error) {
+func (f *fakeFolderRepo) Get(context.Context, string) (*model.Folder, error) {
 	f.getCallCount++
 	if f.getErr != nil {
 		return nil, f.getErr
diff --git a/core/artwork/artwork_test.go b/core/artwork/artwork_test.go
index 8b35a872e..2e8ed070e 100644
--- a/core/artwork/artwork_test.go
+++ b/core/artwork/artwork_test.go
@@ -45,8 +45,8 @@ var _ = Describe("Artwork", func() {
 		hash, err := hashImage(bytes.NewReader(imgBytes))
 		Expect(err).ToNot(HaveOccurred())
 		Expect(store.Write(hash, "image/jpeg", bytes.NewReader(imgBytes))).To(Succeed())
-		Expect(artRepo.PutImage(&model.Artwork{Hash: hash, Mime: "image/jpeg"})).To(Succeed())
-		Expect(artRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: kind, ItemID: id, Hash: hash, Source: "external"})).To(Succeed())
+		Expect(artRepo.PutImage(ctx, &model.Artwork{Hash: hash, Mime: "image/jpeg"})).To(Succeed())
+		Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: kind, ItemID: id, Hash: hash, Source: "external"})).To(Succeed())
 		seedEntity(kind, id)
 		return hash
 	}
@@ -56,9 +56,9 @@ var _ = Describe("Artwork", func() {
 		GinkgoHelper()
 		switch kind {
 		case "al":
-			Expect(albumRepo.Put(&model.Album{ID: id, Name: "Album"})).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{ID: id, Name: "Album"})).To(Succeed())
 		case "mf":
-			Expect(mfRepo.Put(&model.MediaFile{ID: id})).To(Succeed())
+			Expect(mfRepo.Put(ctx, &model.MediaFile{ID: id})).To(Succeed())
 		}
 	}
 
@@ -147,9 +147,9 @@ var _ = Describe("Artwork", func() {
 			imgPath := filepath.Join(dir, "cover.jpg")
 			Expect(os.WriteFile(imgPath, coverBytes, 0600)).To(Succeed())
 			mtime := fileMtime(imgPath)
-			Expect(artRepo.PutImage(&model.Artwork{Hash: "aaaaaaaaaaaaaaaa", Mime: "image/jpeg"})).To(Succeed())
+			Expect(artRepo.PutImage(ctx, &model.Artwork{Hash: "aaaaaaaaaaaaaaaa", Mime: "image/jpeg"})).To(Succeed())
 			seedEntity("al", "al2")
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "al2", Hash: "aaaaaaaaaaaaaaaa",
 				Source: "folder", SourcePath: imgPath, RefMtime: mtime,
 			})).To(Succeed())
@@ -163,9 +163,9 @@ var _ = Describe("Artwork", func() {
 			dir := GinkgoT().TempDir()
 			secretPath := filepath.Join(dir, "config.ini")
 			Expect(os.WriteFile(secretPath, []byte("password=secret"), 0600)).To(Succeed())
-			Expect(artRepo.PutImage(&model.Artwork{Hash: "dddddddddddddddd", Mime: "image/jpeg"})).To(Succeed())
+			Expect(artRepo.PutImage(ctx, &model.Artwork{Hash: "dddddddddddddddd", Mime: "image/jpeg"})).To(Succeed())
 			seedEntity("al", "alni")
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "alni", Hash: "dddddddddddddddd",
 				Source: "folder", SourcePath: secretPath, RefMtime: fileMtime(secretPath),
 			})).To(Succeed())
@@ -180,9 +180,9 @@ var _ = Describe("Artwork", func() {
 			dir := GinkgoT().TempDir()
 			secretPath := filepath.Join(dir, "config.ini")
 			Expect(os.WriteFile(secretPath, secret, 0600)).To(Succeed())
-			Expect(artRepo.PutImage(&model.Artwork{Hash: "eeeeeeeeeeeeeeee", Mime: "image/jpeg"})).To(Succeed())
+			Expect(artRepo.PutImage(ctx, &model.Artwork{Hash: "eeeeeeeeeeeeeeee", Mime: "image/jpeg"})).To(Succeed())
 			seedEntity("al", "alnic")
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "alnic", Hash: "eeeeeeeeeeeeeeee",
 				Source: "folder", SourcePath: secretPath, RefMtime: fileMtime(secretPath),
 			})).To(Succeed())
@@ -210,9 +210,9 @@ var _ = Describe("Artwork", func() {
 			dir := GinkgoT().TempDir()
 			imgPath := filepath.Join(dir, "cover.jpg")
 			Expect(os.WriteFile(imgPath, coverBytes, 0600)).To(Succeed())
-			Expect(artRepo.PutImage(&model.Artwork{Hash: "bbbbbbbbbbbbbbbb", Mime: "image/jpeg"})).To(Succeed())
+			Expect(artRepo.PutImage(ctx, &model.Artwork{Hash: "bbbbbbbbbbbbbbbb", Mime: "image/jpeg"})).To(Succeed())
 			seedEntity("al", "al3")
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "al3", Hash: "bbbbbbbbbbbbbbbb",
 				Source: "folder", SourcePath: imgPath, RefMtime: fileMtime(imgPath) + 999,
 			})).To(Succeed())
@@ -220,7 +220,7 @@ var _ = Describe("Artwork", func() {
 			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al3"), 0, false)
 			Expect(err).To(MatchError(ErrUnavailable))
 			Expect(queueRepo.Data[primaryKey("al", "al3")].Priority).To(Equal(model.ArtworkPriorityScan))
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Hash).To(Equal("bbbbbbbbbbbbbbbb"))
 		})
@@ -229,9 +229,9 @@ var _ = Describe("Artwork", func() {
 			dir := GinkgoT().TempDir()
 			imgPath := filepath.Join(dir, "cover.jpg")
 			Expect(os.WriteFile(imgPath, coverBytes, 0600)).To(Succeed())
-			Expect(artRepo.PutImage(&model.Artwork{Hash: "cccccccccccccccc", Mime: "image/jpeg"})).To(Succeed())
+			Expect(artRepo.PutImage(ctx, &model.Artwork{Hash: "cccccccccccccccc", Mime: "image/jpeg"})).To(Succeed())
 			seedEntity("al", "al3b")
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "al3b", Hash: "cccccccccccccccc",
 				Source: "folder", SourcePath: imgPath, RefMtime: fileMtime(imgPath) + 999,
 			})).To(Succeed())
@@ -252,7 +252,7 @@ var _ = Describe("Artwork", func() {
 		})
 
 		It("never re-enqueues an absent state on view, however old", func() {
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "al4", AttemptedAt: time.Now().Add(-365 * 24 * time.Hour),
 			})).To(Succeed())
 
@@ -272,7 +272,7 @@ var _ = Describe("Artwork", func() {
 			Expect(readAll(img)).To(Equal(coverBytes))
 
 			Expect(queueRepo.Data[primaryKey("al", "al5")].Priority).To(Equal(model.ArtworkPriorityBump))
-			_, err = artRepo.GetItemArtwork(model.KindAlbumArtwork, "al5", model.ImageTypePrimary)
+			_, err = artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al5", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
@@ -283,7 +283,7 @@ var _ = Describe("Artwork", func() {
 			_, err := svc.Get(ctx, model.MustParseArtworkID("al-al6"), 0, false)
 			Expect(err).To(MatchError(ErrUnavailable))
 			Expect(queueRepo.Data[primaryKey("al", "al6")].Priority).To(Equal(model.ArtworkPriorityBump))
-			_, err = artRepo.GetItemArtwork(model.KindAlbumArtwork, "al6", model.ImageTypePrimary)
+			_, err = artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al6", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 	})
@@ -310,7 +310,7 @@ var _ = Describe("Artwork", func() {
 
 		It("delegates to the album when the track's state is absent", func() {
 			seedFoundStore("al", "albm", coverBytes)
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: "mf2"})).To(Succeed())
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "mf", ItemID: "mf2"})).To(Succeed())
 			mfRepo.SetData(model.MediaFiles{{ID: "mf2", AlbumID: "albm"}})
 
 			img, err := svc.Get(ctx, model.MustParseArtworkID("mf-mf2"), 0, false)
@@ -343,7 +343,7 @@ var _ = Describe("Artwork", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(len(readAll(img))).To(BeNumerically(">", 0))
 			Expect(queueRepo.Data[primaryKey("mf", "mf4")].Priority).To(Equal(model.ArtworkPriorityBump))
-			_, err = artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mf4", model.ImageTypePrimary)
+			_, err = artRepo.GetItemArtwork(ctx, model.KindMediaFileArtwork, "mf4", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
@@ -494,7 +494,7 @@ var _ = Describe("Artwork", func() {
 		})
 
 		It("falls back to the artist placeholder for an absent artist", func() {
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "arph"})).To(Succeed())
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: "arph"})).To(Succeed())
 
 			img, err := svc.GetOrPlaceholder(ctx, "ar-arph", 300, false)
 			Expect(err).ToNot(HaveOccurred())
@@ -535,7 +535,7 @@ var _ = Describe("EntityExists", func() {
 		artistRepo := tests.CreateMockArtistRepo()
 		artistRepo.SetData(model.Artists{{ID: "ar1"}})
 		radioRepo := tests.CreateMockedRadioRepo()
-		Expect(radioRepo.Put(&model.Radio{ID: "ra1", Name: "R"})).To(Succeed())
+		Expect(radioRepo.Put(ctx, &model.Radio{ID: "ra1", Name: "R"})).To(Succeed())
 		ds = &tests.MockDataStore{MockedAlbum: albumRepo, MockedArtist: artistRepo, MockedRadio: radioRepo}
 	})
 
diff --git a/core/artwork/disc.go b/core/artwork/disc.go
index acd8a3740..a050f6685 100644
--- a/core/artwork/disc.go
+++ b/core/artwork/disc.go
@@ -45,7 +45,7 @@ func newDiscArtworkReader(ctx context.Context, ds model.DataStore, artID model.A
 		return nil, fmt.Errorf("invalid disc artwork id '%s': %w", artID.ID, err)
 	}
 
-	al, err := ds.Album(ctx).Get(albumID)
+	al, err := ds.Album().Get(ctx, albumID)
 	if err != nil {
 		return nil, err
 	}
@@ -61,7 +61,7 @@ func newDiscArtworkReader(ctx context.Context, ds model.DataStore, artID model.A
 	}
 
 	// Query mediafiles for this album + disc to find folder associations and first track
-	mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 		Sort:    "track_number",
 		Order:   "ASC",
 		Filters: squirrel.Eq{"album_id": albumID, "disc_number": discNumber},
@@ -88,7 +88,7 @@ func newDiscArtworkReader(ctx context.Context, ds model.DataStore, artID model.A
 	// Resolve folder IDs to library-relative paths
 	discFoldersRel := make(map[string]bool)
 	if len(folderIDs) > 0 {
-		folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{
+		folders, err := ds.Folder().GetAll(ctx, model.QueryOptions{
 			Filters: squirrel.Eq{"folder.id": folderIDs},
 		})
 		if err != nil {
diff --git a/core/artwork/e2e/acquire_serve_test.go b/core/artwork/e2e/acquire_serve_test.go
index 34dfb2cac..8cfa54113 100644
--- a/core/artwork/e2e/acquire_serve_test.go
+++ b/core/artwork/e2e/acquire_serve_test.go
@@ -44,20 +44,20 @@ var _ = Describe("Acquisition → serve loop", func() {
 
 	itemFound := func(kind model.Kind, id string) func() bool {
 		return func() bool {
-			ia, err := artRepo.GetItemArtwork(kind, id, model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, kind, id, model.ImageTypePrimary)
 			return err == nil && ia.Hash != ""
 		}
 	}
 	itemAbsent := func(kind model.Kind, id string) func() bool {
 		return func() bool {
-			ia, err := artRepo.GetItemArtwork(kind, id, model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, kind, id, model.ImageTypePrimary)
 			return err == nil && ia.Hash == ""
 		}
 	}
 	// Enqueues the way the serving paths do, so the drain is driven by a plain queue row.
 	bump := func(kind, id string) {
 		GinkgoHelper()
-		Expect(ds.ArtworkQueue(ctx).EnqueuePreservingBackoff(model.ArtworkQueueItem{
+		Expect(ds.ArtworkQueue().EnqueuePreservingBackoff(ctx, model.ArtworkQueueItem{
 			ItemKind: kind, ItemID: id, ImageType: model.ImageTypePrimary,
 			Priority: model.ArtworkPriorityBump,
 		})).To(Succeed())
@@ -141,7 +141,7 @@ var _ = Describe("Acquisition → serve loop", func() {
 		bump("al", "al1")
 		runWorkerUntil(ctx, worker, itemFound(model.KindAlbumArtwork, "al1"))
 
-		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("folder"))
 
@@ -158,7 +158,7 @@ var _ = Describe("Acquisition → serve loop", func() {
 		bump("ar", "ar1")
 		runWorkerUntil(ctx, worker, itemFound(model.KindArtistArtwork, "ar1"))
 
-		ia, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("upload"))
 
@@ -175,14 +175,14 @@ var _ = Describe("Acquisition → serve loop", func() {
 		bump("pl", "pl1")
 		runWorkerUntil(ctx, worker, itemFound(model.KindPlaylistArtwork, "pl1"))
 
-		ia, err := artRepo.GetItemArtwork(model.KindPlaylistArtwork, "pl1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindPlaylistArtwork, "pl1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("generated"))
 
 		img, err := svc.Get(ctx, model.MustParseArtworkID("pl-pl1"), 0, false)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(img.Hash).To(Equal(ia.Hash))
-		art, err := artRepo.GetImage(ia.Hash)
+		art, err := artRepo.GetImage(ctx, ia.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(art.Mime).To(Equal("image/png"))
 		Expect(len(readAll(img))).To(BeNumerically(">", 0))
@@ -194,7 +194,7 @@ var _ = Describe("Acquisition → serve loop", func() {
 		bump("ra", "ra1")
 		runWorkerUntil(ctx, worker, itemFound(model.KindRadioArtwork, "ra1"))
 
-		ia, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("upload"))
 
@@ -216,12 +216,12 @@ var _ = Describe("Acquisition → serve loop", func() {
 		provisionalBytes := readAll(provisional)
 		Expect(len(provisionalBytes)).To(BeNumerically(">", 0))
 
-		_, err = artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
+		_, err = artRepo.GetItemArtwork(ctx, model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound), "provisional serving must not write a state row")
 
 		// The provisional read enqueued a Bump; drain it.
 		runWorkerUntil(ctx, worker, itemFound(model.KindMediaFileArtwork, "mf1"))
-		ia, err := artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("embedded"))
 		Expect(ia.Hash).To(Equal(provisional.Hash))
@@ -237,9 +237,9 @@ var _ = Describe("Acquisition → serve loop", func() {
 		bump("al", "al1")
 		runWorkerUntil(ctx, worker, itemFound(model.KindAlbumArtwork, "al1"))
 
-		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
-		art, err := artRepo.GetImage(ia.Hash)
+		art, err := artRepo.GetImage(ctx, ia.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(art.Mime).To(Equal("image/jpeg"))
 		Expect(art.Width).To(BeNumerically(">", 0))
@@ -259,9 +259,9 @@ var _ = Describe("Acquisition → serve loop", func() {
 		bump("ra", "ra1")
 		runWorkerUntil(ctx, worker, itemFound(model.KindRadioArtwork, "ra1"))
 
-		ia, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
-		art, err := artRepo.GetImage(ia.Hash)
+		art, err := artRepo.GetImage(ctx, ia.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(art.Mime).To(Equal("image/gif"))
 		Expect(art.Width).To(BeNumerically("==", 4))
@@ -279,9 +279,9 @@ var _ = Describe("Acquisition → serve loop", func() {
 			return itemFound(model.KindAlbumArtwork, "al1")() && itemFound(model.KindAlbumArtwork, "al2")()
 		})
 
-		ia1, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+		ia1, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
-		ia2, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al2", model.ImageTypePrimary)
+		ia2, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al2", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia1.Hash).To(Equal(ia2.Hash), "identical bytes must share one content hash")
 		Expect(readAll(mustGet(svc.Get(ctx, model.MustParseArtworkID("al-al2"), 0, false)))).To(Equal(coverBytes))
@@ -293,7 +293,7 @@ var _ = Describe("Acquisition → serve loop", func() {
 		bump("ra", "ra1")
 		runWorkerUntil(ctx, worker, itemFound(model.KindRadioArtwork, "ra1"))
 
-		ia, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		staleHash := ia.Hash
 
@@ -308,7 +308,7 @@ var _ = Describe("Acquisition → serve loop", func() {
 
 		// That failed read enqueued a re-resolution.
 		runWorkerUntil(ctx, worker, func() bool {
-			cur, gerr := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+			cur, gerr := artRepo.GetItemArtwork(ctx, model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
 			return gerr == nil && cur.Hash != "" && cur.Hash != staleHash
 		})
 		img, err := svc.Get(ctx, model.MustParseArtworkID("ra-ra1"), 0, false)
diff --git a/core/artwork/e2e/artist_test.go b/core/artwork/e2e/artist_test.go
index 4a6959d95..38c28a9b2 100644
--- a/core/artwork/e2e/artist_test.go
+++ b/core/artwork/e2e/artist_test.go
@@ -201,7 +201,7 @@ var _ = Describe("Artist artwork resolution", func() {
 			uploaded := ar.ID + "_upload.jpg"
 			writeUploadedImage(consts.EntityArtist, uploaded, pngBytes("artist-uploaded"))
 			ar.UploadedImage = uploaded
-			Expect(rds.Artist(rctx).Put(&ar)).To(Succeed())
+			Expect(rds.Artist().Put(rctx, &ar)).To(Succeed())
 
 			ia := acquire(model.KindArtistArtwork, ar.ID)
 			Expect(ia.Source).To(Equal("upload"))
@@ -279,7 +279,7 @@ var _ = Describe("Artist artwork resolution", func() {
 
 func soleArtist() model.Artist {
 	GinkgoHelper()
-	artists, err := rds.Artist(rctx).GetAll(model.QueryOptions{
+	artists, err := rds.Artist().GetAll(rctx, model.QueryOptions{
 		Filters: squirrel.Eq{"artist.name": "Artist"},
 	})
 	Expect(err).ToNot(HaveOccurred())
diff --git a/core/artwork/e2e/e2e_suite_test.go b/core/artwork/e2e/e2e_suite_test.go
index 390be14a7..d03e22228 100644
--- a/core/artwork/e2e/e2e_suite_test.go
+++ b/core/artwork/e2e/e2e_suite_test.go
@@ -67,13 +67,17 @@ type fakeFolderRepo struct {
 	result []model.Folder
 }
 
-func (f *fakeFolderRepo) GetAll(...model.QueryOptions) ([]model.Folder, error) { return f.result, nil }
+func (f *fakeFolderRepo) GetAll(context.Context, ...model.QueryOptions) ([]model.Folder, error) {
+	return f.result, nil
+}
 
-func (f *fakeFolderRepo) HasAudioOutsideFolders(model.Folder, []string) (bool, error) {
+func (f *fakeFolderRepo) HasAudioOutsideFolders(context.Context, model.Folder, []string) (bool, error) {
 	return false, nil
 }
 
-func (f *fakeFolderRepo) Get(string) (*model.Folder, error) { return nil, model.ErrNotFound }
+func (f *fakeFolderRepo) Get(context.Context, string) (*model.Folder, error) {
+	return nil, model.ErrNotFound
+}
 
 func writeUpload(entityType, name, srcFixture string) string {
 	GinkgoHelper()
diff --git a/core/artwork/e2e/mediafile_test.go b/core/artwork/e2e/mediafile_test.go
index d26756dcd..3ddb9dc48 100644
--- a/core/artwork/e2e/mediafile_test.go
+++ b/core/artwork/e2e/mediafile_test.go
@@ -137,7 +137,7 @@ var _ = Describe("MediaFile artwork resolution", func() {
 
 func mediafileOn(relPath string) model.MediaFile {
 	GinkgoHelper()
-	mfs, err := rds.MediaFile(rctx).GetAll(model.QueryOptions{
+	mfs, err := rds.MediaFile().GetAll(rctx, model.QueryOptions{
 		Filters: squirrel.Like{"media_file.path": relPath},
 	})
 	Expect(err).ToNot(HaveOccurred())
diff --git a/core/artwork/e2e/playlist_test.go b/core/artwork/e2e/playlist_test.go
index f5ac8a7e3..0d862b20e 100644
--- a/core/artwork/e2e/playlist_test.go
+++ b/core/artwork/e2e/playlist_test.go
@@ -142,13 +142,13 @@ var _ = Describe("Playlist artwork resolution", func() {
 			})
 			scan()
 
-			mfs, err := rds.MediaFile(rctx).GetAll(model.QueryOptions{})
+			mfs, err := rds.MediaFile().GetAll(rctx, 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(rds.Playlist(rctx).Put(&pl)).To(Succeed())
+			Expect(rds.Playlist().Put(rctx, &pl)).To(Succeed())
 
 			ia := acquire(model.KindPlaylistArtwork, pl.ID)
 			Expect(ia.Source).To(Equal("generated"))
@@ -180,14 +180,14 @@ var _ = Describe("Playlist artwork resolution", func() {
 			setLayout(layout)
 			scan()
 
-			mfs, err := rds.MediaFile(rctx).GetAll(model.QueryOptions{})
+			mfs, err := rds.MediaFile().GetAll(rctx, model.QueryOptions{})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(mfs).To(HaveLen(4))
 			ids := slice.Map(mfs, func(mf model.MediaFile) string { return mf.ID })
 
 			pl := model.Playlist{ID: "pl-8", Name: "Four", OwnerID: "admin-1"}
 			pl.AddMediaFilesByID(ids)
-			Expect(rds.Playlist(rctx).Put(&pl)).To(Succeed())
+			Expect(rds.Playlist().Put(rctx, &pl)).To(Succeed())
 
 			ia := acquire(model.KindPlaylistArtwork, pl.ID)
 			Expect(ia.Source).To(Equal("generated"))
@@ -208,6 +208,6 @@ func putPlaylist(pl model.Playlist) model.Playlist {
 	if pl.OwnerID == "" {
 		pl.OwnerID = "admin-1"
 	}
-	Expect(rds.Playlist(rctx).Put(&pl)).To(Succeed())
+	Expect(rds.Playlist().Put(rctx, &pl)).To(Succeed())
 	return pl
 }
diff --git a/core/artwork/e2e/radio_test.go b/core/artwork/e2e/radio_test.go
index bba85224a..72af215d1 100644
--- a/core/artwork/e2e/radio_test.go
+++ b/core/artwork/e2e/radio_test.go
@@ -23,7 +23,7 @@ var _ = Describe("Radio artwork resolution", func() {
 		It("returns the uploaded image bytes", func() {
 			writeUploadedImage(consts.EntityRadio, "rd-1_logo.jpg", pngBytes("radio-logo"))
 			rd := model.Radio{ID: "rd-1", Name: "Test Radio", StreamUrl: "https://example.com/stream", UploadedImage: "rd-1_logo.jpg"}
-			Expect(rds.Radio(rctx).Put(&rd)).To(Succeed())
+			Expect(rds.Radio().Put(rctx, &rd)).To(Succeed())
 
 			ia := acquire(model.KindRadioArtwork, rd.ID)
 			Expect(ia.Source).To(Equal("upload"))
@@ -35,7 +35,7 @@ var _ = Describe("Radio artwork resolution", func() {
 		// (no files on disk — the resolver has no sources to fall back to)
 		It("settles absent", func() {
 			rd := model.Radio{ID: "rd-2", Name: "Bare Radio", StreamUrl: "https://example.com/stream"}
-			Expect(rds.Radio(rctx).Put(&rd)).To(Succeed())
+			Expect(rds.Radio().Put(rctx, &rd)).To(Succeed())
 
 			ia := acquire(model.KindRadioArtwork, rd.ID)
 			Expect(ia.Hash).To(BeEmpty())
diff --git a/core/artwork/e2e/resolution_harness_test.go b/core/artwork/e2e/resolution_harness_test.go
index fff62ce69..fbd89925e 100644
--- a/core/artwork/e2e/resolution_harness_test.go
+++ b/core/artwork/e2e/resolution_harness_test.go
@@ -99,11 +99,11 @@ func setupResolutionHarness() {
 	rds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
 
 	adminUser := model.User{ID: "admin-1", UserName: "admin", Name: "Admin", IsAdmin: true, NewPassword: "password"}
-	Expect(rds.User(rctx).Put(&adminUser)).To(Succeed())
+	Expect(rds.User().Put(rctx, &adminUser)).To(Succeed())
 
 	lib := model.Library{ID: 1, Name: "Music", Path: fakeLibPath}
-	Expect(rds.Library(rctx).Put(&lib)).To(Succeed())
-	Expect(rds.User(rctx).SetUserLibraries(adminUser.ID, []int{lib.ID})).To(Succeed())
+	Expect(rds.Library().Put(rctx, &lib)).To(Succeed())
+	Expect(rds.User().SetUserLibraries(rctx, adminUser.ID, []int{lib.ID})).To(Succeed())
 
 	loadEmbeddedFixture()
 
@@ -140,13 +140,13 @@ func scan() {
 func acquire(kind model.Kind, id string) model.ItemArtwork {
 	GinkgoHelper()
 	// Enqueues the way the serving paths do, so the drain is driven by a plain queue row.
-	Expect(rds.ArtworkQueue(rctx).EnqueuePreservingBackoff(model.ArtworkQueueItem{
+	Expect(rds.ArtworkQueue().EnqueuePreservingBackoff(rctx, model.ArtworkQueueItem{
 		ItemKind: kind.Prefix(), ItemID: id, ImageType: model.ImageTypePrimary,
 		Priority: model.ArtworkPriorityBump,
 	})).To(Succeed())
 	var ia *model.ItemArtwork
 	runResolutionWorkerUntil(func() bool {
-		got, err := rds.Artwork(rctx).GetItemArtwork(kind, id, model.ImageTypePrimary)
+		got, err := rds.Artwork().GetItemArtwork(rctx, kind, id, model.ImageTypePrimary)
 		if err != nil {
 			return false
 		}
@@ -211,7 +211,7 @@ func expectAlbumFolderCover(al model.Album, suffix string) {
 // A drain settles every ready item, so byte-level folder assertions must precede any acquire.
 func requireNoStateRow(kind model.Kind, id string) {
 	GinkgoHelper()
-	_, err := rds.Artwork(rctx).GetItemArtwork(kind, id, model.ImageTypePrimary)
+	_, err := rds.Artwork().GetItemArtwork(rctx, kind, id, model.ImageTypePrimary)
 	Expect(err).To(MatchError(model.ErrNotFound),
 		"assert %s %q before acquiring any other entity in this spec", kind, id)
 }
@@ -266,7 +266,7 @@ func gridQuadrants(data []byte) [4]color.RGBA {
 // Store-backed sources only (embedded/generated); file-backed ones assert on ia.SourcePath.
 func storedBytes(ia model.ItemArtwork) []byte {
 	GinkgoHelper()
-	art, err := rds.Artwork(rctx).GetImage(ia.Hash)
+	art, err := rds.Artwork().GetImage(rctx, ia.Hash)
 	Expect(err).ToNot(HaveOccurred())
 	r, err := rstore.Open(ia.Hash, art.Mime)
 	Expect(err).ToNot(HaveOccurred())
@@ -345,7 +345,7 @@ func replaceWithRealMP3(relPath string) {
 
 func firstAlbum() model.Album {
 	GinkgoHelper()
-	albums, err := rds.Album(rctx).GetAll(model.QueryOptions{})
+	albums, err := rds.Album().GetAll(rctx, model.QueryOptions{})
 	Expect(err).ToNot(HaveOccurred())
 	Expect(albums).To(HaveLen(1), "expected exactly one album, got %d", len(albums))
 	return albums[0]
@@ -353,7 +353,7 @@ func firstAlbum() model.Album {
 
 func albumByName(name string) model.Album {
 	GinkgoHelper()
-	albums, err := rds.Album(rctx).GetAll(model.QueryOptions{})
+	albums, err := rds.Album().GetAll(rctx, model.QueryOptions{})
 	Expect(err).ToNot(HaveOccurred())
 	for _, al := range albums {
 		if al.Name == name {
diff --git a/core/artwork/folders_album.go b/core/artwork/folders_album.go
index 88f0181a3..7b423adb6 100644
--- a/core/artwork/folders_album.go
+++ b/core/artwork/folders_album.go
@@ -36,7 +36,7 @@ func loadAlbumFoldersPaths(ctx context.Context, ds model.DataStore, album model.
 }
 
 func loadFolders(ctx context.Context, ds model.DataStore, folderIDs []string) ([]model.Folder, error) {
-	return ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderIDs, "missing": false}})
+	return ds.Folder().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderIDs, "missing": false}})
 }
 
 // folderImages collects the folders' image files, sorted so files without
@@ -79,7 +79,7 @@ func albumRootParent(ctx context.Context, ds model.DataStore, folders []model.Fo
 	if len(folders) < 2 && anyFolderHasImages(folders) {
 		return nil, nil
 	}
-	parent, err := ds.Folder(ctx).Get(commonParentID)
+	parent, err := ds.Folder().Get(ctx, commonParentID)
 	if errors.Is(err, model.ErrNotFound) {
 		log.Warn(ctx, "Artwork: Parent folder not found for album cover art lookup", "parentID", commonParentID)
 		return nil, nil
@@ -91,7 +91,7 @@ func albumRootParent(ctx context.Context, ds model.DataStore, folders []model.Fo
 		// The library root can never be an album root
 		return nil, nil
 	}
-	hasOtherAudio, err := ds.Folder(ctx).HasAudioOutsideFolders(*parent, folderIDs)
+	hasOtherAudio, err := ds.Folder().HasAudioOutsideFolders(ctx, *parent, folderIDs)
 	if err != nil {
 		return nil, err
 	}
diff --git a/core/artwork/folders_artist.go b/core/artwork/folders_artist.go
index efef42f81..3403935db 100644
--- a/core/artwork/folders_artist.go
+++ b/core/artwork/folders_artist.go
@@ -169,14 +169,14 @@ func loadArtistFolder(ctx context.Context, ds model.DataStore, albums model.Albu
 	}
 
 	// Cleaned like the album paths; Join keeps an empty path empty, Clean would return ".".
-	libPath, _ := ds.Library(ctx).GetPath(libID)
+	libPath, _ := ds.Library().GetPath(ctx, libID)
 	libPath = filepath.Join(libPath)
 	folderID := model.FolderID(model.Library{ID: libID, Path: libPath}, folderPath)
 
 	log.Trace(ctx, "Artwork: Calculating artist folder details", "folderPath", folderPath, "folderID", folderID,
 		"libPath", libPath, "libID", libID, "albumPaths", paths)
 
-	folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderID, "missing": false}})
+	folders, err := ds.Folder().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"folder.id": folderID, "missing": false}})
 	if err != nil || len(folders) == 0 {
 		log.Warn(ctx, "Artwork: Could not find folder for artist", "folderPath", folderPath, "id", folderID,
 			"libPath", libPath, "libID", libID, err)
diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.go
index 3ca452bdc..5ec701541 100644
--- a/core/artwork/housekeeping.go
+++ b/core/artwork/housekeeping.go
@@ -70,7 +70,7 @@ func ConfigFingerprint() string {
 // resolved under it. Nothing re-resolves on its own; applying a change is an explicit reprocess.
 func ReconcileConfigFingerprint(ctx context.Context, ds model.DataStore) error {
 	current := ConfigFingerprint()
-	stored, err := ds.Property(ctx).DefaultGet(consts.ArtConfFingerprintPropertyKey, "")
+	stored, err := ds.Property().DefaultGet(ctx, consts.ArtConfFingerprintPropertyKey, "")
 	if err != nil {
 		return err
 	}
@@ -89,14 +89,14 @@ func ReconcileConfigFingerprint(ctx context.Context, ds model.DataStore) error {
 
 // MarkConfigApplied records the current fingerprint as the one the library is resolved under.
 func MarkConfigApplied(ctx context.Context, ds model.DataStore) error {
-	return ds.Property(ctx).Put(consts.ArtConfFingerprintPropertyKey, ConfigFingerprint())
+	return ds.Property().Put(ctx, consts.ArtConfFingerprintPropertyKey, ConfigFingerprint())
 }
 
 // enqueueMissingAll is the safety net for entities a scan never enqueued (added between scans, or scanner off).
 func enqueueMissingAll(ctx context.Context, ds model.DataStore) error {
-	queue := ds.ArtworkQueue(ctx)
+	queue := ds.ArtworkQueue()
 	for _, kind := range ReprocessKinds {
-		if _, err := queue.EnqueueAllMissing(kind, model.ArtworkPriorityRecheck); err != nil {
+		if _, err := queue.EnqueueAllMissing(ctx, kind, model.ArtworkPriorityRecheck); err != nil {
 			return err
 		}
 	}
@@ -108,31 +108,31 @@ func enqueueMissingAll(ctx context.Context, ds model.DataStore) error {
 func ItemName(ctx context.Context, ds model.DataStore, kind model.Kind, id string) (string, error) {
 	switch kind {
 	case model.KindArtistArtwork:
-		ar, err := ds.Artist(ctx).Get(id)
+		ar, err := ds.Artist().Get(ctx, id)
 		if err != nil {
 			return "", err
 		}
 		return ar.Name, nil
 	case model.KindAlbumArtwork:
-		al, err := ds.Album(ctx).Get(id)
+		al, err := ds.Album().Get(ctx, id)
 		if err != nil {
 			return "", err
 		}
 		return al.Name, nil
 	case model.KindPlaylistArtwork:
-		pls, err := ds.Playlist(ctx).Get(id)
+		pls, err := ds.Playlist().Get(ctx, id)
 		if err != nil {
 			return "", err
 		}
 		return pls.Name, nil
 	case model.KindRadioArtwork:
-		rd, err := ds.Radio(ctx).Get(id)
+		rd, err := ds.Radio().Get(ctx, id)
 		if err != nil {
 			return "", err
 		}
 		return rd.Name, nil
 	case model.KindMediaFileArtwork:
-		mf, err := ds.MediaFile(ctx).Get(id)
+		mf, err := ds.MediaFile().Get(ctx, id)
 		if err != nil {
 			return "", err
 		}
@@ -148,7 +148,7 @@ func discArtworkName(ctx context.Context, ds model.DataStore, id string) (string
 	if err != nil {
 		return "", err
 	}
-	al, err := ds.Album(ctx).Get(albumID)
+	al, err := ds.Album().Get(ctx, albumID)
 	if err != nil {
 		return "", err
 	}
@@ -162,11 +162,11 @@ func discArtworkName(ctx context.Context, ds model.DataStore, id string) (string
 
 // Refresh drops an item's resolved artwork state and re-queues it at Bump priority.
 func Refresh(ctx context.Context, ds model.DataStore, kind model.Kind, id string) error {
-	if err := ds.Artwork(ctx).DeleteForItems(kind, []string{id}); err != nil {
+	if err := ds.Artwork().DeleteForItems(ctx, kind, []string{id}); err != nil {
 		return fmt.Errorf("clearing artwork state: %w", err)
 	}
 	item := model.ArtworkQueueItem{ItemKind: kind.Prefix(), ItemID: id, ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBump}
-	if err := ds.ArtworkQueue(ctx).Enqueue(item); err != nil {
+	if err := ds.ArtworkQueue().Enqueue(ctx, item); err != nil {
 		return fmt.Errorf("enqueuing artwork refresh: %w", err)
 	}
 	return nil
diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.go
index 2027cba9a..0f501d0b1 100644
--- a/core/artwork/housekeeping_test.go
+++ b/core/artwork/housekeeping_test.go
@@ -95,15 +95,15 @@ var _ = Describe("Housekeeping", func() {
 		It("records the current fingerprint when none was ever stored", func() {
 			Expect(ReconcileConfigFingerprint(ctx, ds)).To(Succeed())
 
-			Expect(propRepo.Get(consts.ArtConfFingerprintPropertyKey)).To(Equal(ConfigFingerprint()))
+			Expect(propRepo.Get(ctx, consts.ArtConfFingerprintPropertyKey)).To(Equal(ConfigFingerprint()))
 		})
 
 		It("leaves a stale fingerprint stored, so the warning survives a restart", func() {
-			Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, "stale-fingerprint")).To(Succeed())
+			Expect(propRepo.Put(ctx, consts.ArtConfFingerprintPropertyKey, "stale-fingerprint")).To(Succeed())
 
 			Expect(ReconcileConfigFingerprint(ctx, ds)).To(Succeed())
 
-			Expect(propRepo.Get(consts.ArtConfFingerprintPropertyKey)).To(Equal("stale-fingerprint"))
+			Expect(propRepo.Get(ctx, consts.ArtConfFingerprintPropertyKey)).To(Equal("stale-fingerprint"))
 		})
 	})
 
@@ -153,7 +153,7 @@ var _ = Describe("ItemName", func() {
 			{ID: "al-2", Name: "Sandinista!", Discs: model.Discs{2: "Side Three"}},
 		})
 		ds = &tests.MockDataStore{MockedAlbum: albumRepo}
-		Expect(ds.Artist(ctx).(*tests.MockArtistRepo).Put(&model.Artist{ID: "ar-1", Name: "Radiohead"})).To(Succeed())
+		Expect(ds.Artist().(*tests.MockArtistRepo).Put(ctx, &model.Artist{ID: "ar-1", Name: "Radiohead"})).To(Succeed())
 	})
 
 	It("returns the album name", func() {
diff --git a/core/artwork/library_fs.go b/core/artwork/library_fs.go
index 6e6099325..84e088c68 100644
--- a/core/artwork/library_fs.go
+++ b/core/artwork/library_fs.go
@@ -30,7 +30,7 @@ func (v libraryView) Abs(rel string) string {
 // 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)
+	lib, err := ds.Library().Get(ctx, libID)
 	if err != nil {
 		return libraryView{}, err
 	}
diff --git a/core/artwork/library_fs_test.go b/core/artwork/library_fs_test.go
index 22498e7a1..868c5e45a 100644
--- a/core/artwork/library_fs_test.go
+++ b/core/artwork/library_fs_test.go
@@ -24,7 +24,7 @@ var _ = Describe("loadLibraryView", Ordered, func() {
 	})
 
 	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())
+		Expect(ds.Library().Put(ctx, &model.Library{ID: 1, Path: "fake:///music"})).To(Succeed())
 
 		lib, err := loadLibraryView(ctx, ds, 1)
 		Expect(err).ToNot(HaveOccurred())
@@ -45,7 +45,7 @@ var _ = Describe("loadLibraryView", Ordered, func() {
 	})
 
 	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())
+		Expect(ds.Library().Put(ctx, &model.Library{ID: 2, Path: "unsupported:///music"})).To(Succeed())
 		_, err := loadLibraryView(ctx, ds, 2)
 		Expect(err).To(HaveOccurred())
 	})
diff --git a/core/artwork/processor.go b/core/artwork/processor.go
index cf2176775..78e625e94 100644
--- a/core/artwork/processor.go
+++ b/core/artwork/processor.go
@@ -82,7 +82,7 @@ type processor struct {
 // acquire resolves one queue item end to end: find an image, hash/decode/
 // blurhash it, place its bytes, and persist the resulting state.
 func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (out outcome, got *acquired, retryIn time.Duration) {
-	repo := p.ds.Artwork(ctx)
+	repo := p.ds.Artwork()
 	start := time.Now()
 	defer func() {
 		log.Debug(ctx, "Artwork: Acquisition finished", "kind", item.ItemKind, "id", item.ItemID,
@@ -137,7 +137,7 @@ func (p *processor) acquire(ctx context.Context, item model.ArtworkQueueItem) (o
 	log.Trace(ctx, "Artwork: Hashed image", "kind", item.ItemKind, "id", item.ItemID,
 		"hash", hash, "bytes", len(data), "elapsed", time.Since(hashStart))
 
-	art, err := repo.GetImage(hash)
+	art, err := repo.GetImage(ctx, hash)
 	switch {
 	case err == nil && art.Width > 0:
 		log.Debug(ctx, "Artwork: Reusing a known image, skipping decode", "kind", item.ItemKind,
@@ -195,7 +195,7 @@ func (p *processor) persist(ctx context.Context, repo model.ArtworkRepository, i
 	if err != nil {
 		return nil, fmt.Errorf("writing image store: %w", err)
 	}
-	if err := repo.PutImage(art); err != nil {
+	if err := repo.PutImage(ctx, art); err != nil {
 		return nil, fmt.Errorf("persisting artwork image: %w", err)
 	}
 	ia := &model.ItemArtwork{
@@ -210,7 +210,7 @@ func (p *processor) persist(ctx context.Context, repo model.ArtworkRepository, i
 		Trace:       traceFrom(ctx).encode(sourcePath),
 	}
 	// PutItemArtwork stamps UpdatedAt on ia, so the returned struct matches the persisted row.
-	if err := repo.PutItemArtwork(ia); err != nil {
+	if err := repo.PutItemArtwork(ctx, ia); err != nil {
 		return nil, fmt.Errorf("persisting item artwork state: %w", err)
 	}
 	return ia, nil
@@ -218,7 +218,7 @@ func (p *processor) persist(ctx context.Context, repo model.ArtworkRepository, i
 
 // writeAbsent records a known-absent state: every source answered definitively "no".
 func writeAbsent(ctx context.Context, repo model.ArtworkRepository, item model.ArtworkQueueItem) outcome {
-	err := repo.PutItemArtwork(&model.ItemArtwork{
+	err := repo.PutItemArtwork(ctx, &model.ItemArtwork{
 		ItemKind:    item.ItemKind,
 		ItemID:      item.ItemID,
 		ImageType:   item.ImageType,
diff --git a/core/artwork/processor_test.go b/core/artwork/processor_test.go
index 554ca08dc..8eec97cde 100644
--- a/core/artwork/processor_test.go
+++ b/core/artwork/processor_test.go
@@ -93,14 +93,14 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"})
 		Expect(out).To(Equal(outcomeFound))
 
-		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Hash).ToNot(BeEmpty())
 		Expect(ia.Source).To(Equal("folder"))
 		Expect(filepath.ToSlash(ia.SourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/cover.jpg"))
 		Expect(ia.RefMtime).To(BeNumerically(">", 0))
 
-		art, err := artRepo.GetImage(ia.Hash)
+		art, err := artRepo.GetImage(ctx, ia.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		// Every placeholder is derived from the one shared thumbnail, so all three land together.
 		Expect(art.BlurHash).ToNot(BeEmpty())
@@ -156,12 +156,12 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"})
 		Expect(out).To(Equal(outcomeFound))
 
-		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al2", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al2", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("embedded"))
 		Expect(filepath.ToSlash(ia.SourcePath)).To(HaveSuffix("tests/fixtures/artist/an-album/test.mp3"))
 
-		art, err := artRepo.GetImage(ia.Hash)
+		art, err := artRepo.GetImage(ctx, ia.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(art.BlurHash).ToNot(BeEmpty())
 
@@ -179,7 +179,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"})
 		Expect(out).To(Equal(outcomeAbsent))
 
-		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Hash).To(BeEmpty())
 		Expect(ia.Source).To(BeEmpty())
@@ -200,7 +200,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al-io"})
 		Expect(out).To(Equal(outcomeFailed))
 
-		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al-io", model.ImageTypePrimary)
+		_, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al-io", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound), "an I/O fault must not be recorded as absent")
 	})
 
@@ -225,7 +225,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra-io"})
 		Expect(out).To(Equal(outcomeFailed))
 
-		_, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra-io", model.ImageTypePrimary)
+		_, err := artRepo.GetItemArtwork(ctx, model.KindRadioArtwork, "ra-io", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound), "an unreadable upload must not be recorded as absent")
 	})
 
@@ -269,7 +269,7 @@ var _ = Describe("processor.acquire", func() {
 		Expect(out).To(Equal(outcomeFailed))
 		Expect(retryIn).To(BeZero(), "a plain failure asks for no particular delay")
 
-		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al4", model.ImageTypePrimary)
+		_, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al4", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
@@ -299,7 +299,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alstale"})
 		Expect(out).To(Equal(outcomeFoundStale))
 
-		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alstale", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alstale", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Hash).ToNot(BeEmpty())
 		Expect(ia.Source).To(Equal("folder"))
@@ -316,10 +316,10 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alU"})
 		Expect(out).To(Equal(outcomeFound))
 
-		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alU", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alU", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("folder"))
-		art, err := artRepo.GetImage(ia.Hash)
+		art, err := artRepo.GetImage(ctx, ia.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(art.Width).To(BeZero())
 		Expect(art.BlurHash).To(BeEmpty())
@@ -336,7 +336,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alE"})
 		Expect(out).To(Equal(outcomeFailed))
 
-		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alE", model.ImageTypePrimary)
+		_, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alE", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
@@ -354,7 +354,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alX"})
 		Expect(out).To(Equal(outcomeFailed))
 
-		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alX", model.ImageTypePrimary)
+		_, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alX", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
@@ -373,12 +373,12 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alext"})
 		Expect(out).To(Equal(outcomeFound))
 
-		ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alext", model.ImageTypePrimary)
+		ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alext", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("external:deezerFake"))
 		Expect(ia.Hash).ToNot(BeEmpty())
 
-		art, err := artRepo.GetImage(ia.Hash)
+		art, err := artRepo.GetImage(ctx, ia.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		rc, err := store.Open(ia.Hash, art.Mime)
 		Expect(err).ToNot(HaveOccurred())
@@ -397,7 +397,7 @@ var _ = Describe("processor.acquire", func() {
 
 		out1, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al5"})
 		Expect(out1).To(Equal(outcomeFound))
-		ia1, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al5", model.ImageTypePrimary)
+		ia1, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al5", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 
 		// A re-decode instead of a hash dedup would overwrite this sentinel.
@@ -407,11 +407,11 @@ var _ = Describe("processor.acquire", func() {
 
 		out2, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al6"})
 		Expect(out2).To(Equal(outcomeFound))
-		ia2, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al6", model.ImageTypePrimary)
+		ia2, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al6", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia2.Hash).To(Equal(ia1.Hash))
 
-		reused, err := artRepo.GetImage(ia1.Hash)
+		reused, err := artRepo.GetImage(ctx, ia1.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(reused.BlurHash).To(Equal("SENTINEL"))
 	})
@@ -437,7 +437,7 @@ var _ = Describe("processor.acquire", func() {
 		folderRepo.result = []model.Folder{{Path: "album-a", ImageFiles: []string{"cover.jpg"}}}
 		outN, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alA"})
 		Expect(outN).To(Equal(outcomeFound))
-		iaA, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alA", model.ImageTypePrimary)
+		iaA, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alA", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(iaA.Source).To(Equal("folder"))
 		Expect(filepath.ToSlash(iaA.SourcePath)).To(HaveSuffix("album-a/cover.jpg"))
@@ -451,19 +451,19 @@ var _ = Describe("processor.acquire", func() {
 		folderRepo.result = []model.Folder{{Path: "album-b", ImageFiles: []string{"cover.jpg"}}}
 		outN, _, _ = proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alB"})
 		Expect(outN).To(Equal(outcomeFound))
-		iaB, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alB", model.ImageTypePrimary)
+		iaB, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alB", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(iaB.Hash).To(Equal(iaA.Hash))
 		Expect(filepath.ToSlash(iaB.SourcePath)).To(HaveSuffix("album-b/cover.jpg"))
 		Expect(iaB.RefMtime).To(Equal(time.Unix(2000, 0).UnixNano()))
 
-		iaAafter, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alA", model.ImageTypePrimary)
+		iaAafter, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alA", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(filepath.ToSlash(iaAafter.SourcePath)).To(HaveSuffix("album-a/cover.jpg"))
 		Expect(iaAafter.RefMtime).To(Equal(time.Unix(1000, 0).UnixNano()))
 
 		Expect(artRepo.Data).To(HaveLen(1))
-		reused, err := artRepo.GetImage(iaA.Hash)
+		reused, err := artRepo.GetImage(ctx, iaA.Hash)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(reused.BlurHash).To(Equal("SENTINEL"))
 	})
@@ -483,7 +483,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "ra1"})
 		Expect(out).To(Equal(outcomeFailed))
 
-		_, err := artRepo.GetItemArtwork(model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
+		_, err := artRepo.GetItemArtwork(ctx, model.KindRadioArtwork, "ra1", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
@@ -504,7 +504,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "ra", ItemID: "big"})
 		Expect(out).To(Equal(outcomeFailed))
 
-		_, err = artRepo.GetItemArtwork(model.KindRadioArtwork, "big", model.ImageTypePrimary)
+		_, err = artRepo.GetItemArtwork(ctx, model.KindRadioArtwork, "big", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
@@ -565,12 +565,12 @@ var _ = Describe("processor.acquire", func() {
 
 		hash, err := hashImage(bytes.NewReader(imgBytes))
 		Expect(err).ToNot(HaveOccurred())
-		Expect(artRepo.PutImage(&model.Artwork{Hash: hash, Mime: "application/octet-stream"})).To(Succeed())
+		Expect(artRepo.PutImage(ctx, &model.Artwork{Hash: hash, Mime: "application/octet-stream"})).To(Succeed())
 
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alM"})
 		Expect(out).To(Equal(outcomeFound))
 
-		upgraded, err := artRepo.GetImage(hash)
+		upgraded, err := artRepo.GetImage(ctx, hash)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(upgraded.Width).To(BeNumerically(">", 0))
 		Expect(upgraded.BlurHash).ToNot(BeEmpty())
@@ -590,7 +590,7 @@ var _ = Describe("processor.acquire", func() {
 		out, _, _ := proc.acquire(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al7"})
 		Expect(out).To(Equal(outcomeFailed))
 
-		_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al7", model.ImageTypePrimary)
+		_, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al7", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 })
diff --git a/core/artwork/prune.go b/core/artwork/prune.go
index c79458b8f..15b4a5673 100644
--- a/core/artwork/prune.go
+++ b/core/artwork/prune.go
@@ -14,9 +14,9 @@ const pruneMinAge = time.Hour
 func prune(ctx context.Context, ds model.DataStore, store *ImageStore) error {
 	start := time.Now()
 	defer func() { log.Debug(ctx, "Artwork: Prune finished", "elapsed", time.Since(start)) }()
-	repo := ds.Artwork(ctx)
+	repo := ds.Artwork()
 
-	purged, err := repo.PurgeDanglingItems()
+	purged, err := repo.PurgeDanglingItems(ctx)
 	if err != nil {
 		return err
 	}
@@ -25,7 +25,7 @@ func prune(ctx context.Context, ds model.DataStore, store *ImageStore) error {
 	}
 
 	// Queue rows for deleted entities would otherwise retry forever (Get -> not found -> failed).
-	queuePurged, err := ds.ArtworkQueue(ctx).PurgeDangling()
+	queuePurged, err := ds.ArtworkQueue().PurgeDangling(ctx)
 	if err != nil {
 		return err
 	}
@@ -35,7 +35,7 @@ func prune(ctx context.Context, ds model.DataStore, store *ImageStore) error {
 
 	// Files younger than the grace window may belong to acquisitions whose rows aren't committed yet.
 	cutoff := time.Now().Add(-pruneMinAge)
-	orphans, err := repo.PurgeOrphans(cutoff)
+	orphans, err := repo.PurgeOrphans(ctx, cutoff)
 	if err != nil {
 		return err
 	}
@@ -44,7 +44,7 @@ func prune(ctx context.Context, ds model.DataStore, store *ImageStore) error {
 	}
 
 	// Read after the delete, so the sweep below reclaims the files of the rows just removed.
-	mimes, err := repo.GetMimeByHash()
+	mimes, err := repo.GetMimeByHash(ctx)
 	if err != nil {
 		return err
 	}
diff --git a/core/artwork/prune_test.go b/core/artwork/prune_test.go
index 8b8504f89..674211dfa 100644
--- a/core/artwork/prune_test.go
+++ b/core/artwork/prune_test.go
@@ -18,18 +18,20 @@ type flakyGetArtworkRepo struct {
 	*tests.MockArtworkRepo
 }
 
-func (f *flakyGetArtworkRepo) GetMimeByHash() (map[string]string, error) {
+func (f *flakyGetArtworkRepo) GetMimeByHash(context.Context) (map[string]string, error) {
 	return nil, errors.New("db locked")
 }
 
 var _ = Describe("Prune", func() {
+	var ctx context.Context
 	var ds *tests.MockDataStore
 	var store *ImageStore
 	var awRepo *tests.MockArtworkRepo
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		ds = &tests.MockDataStore{}
-		awRepo = ds.Artwork(context.Background()).(*tests.MockArtworkRepo)
+		awRepo = ds.Artwork().(*tests.MockArtworkRepo)
 		store = NewImageStore(GinkgoT().TempDir())
 	})
 
@@ -41,9 +43,9 @@ var _ = Describe("Prune", func() {
 	}
 
 	It("purges dangling item_artwork state for gone entities, summed across kinds", func() {
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "gone-album", ImageType: model.ImageTypePrimary})).To(Succeed())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "gone-artist", ImageType: model.ImageTypePrimary})).To(Succeed())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "live-artist", ImageType: model.ImageTypePrimary})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "gone-album", ImageType: model.ImageTypePrimary})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: "gone-artist", ImageType: model.ImageTypePrimary})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: "live-artist", ImageType: model.ImageTypePrimary})).To(Succeed())
 		awRepo.ExistingIDs = map[string]map[string]bool{
 			"al": {},
 			"ar": {"live-artist": true},
@@ -51,17 +53,17 @@ var _ = Describe("Prune", func() {
 
 		Expect(prune(context.Background(), ds, store)).To(Succeed())
 
-		_, err := awRepo.GetItemArtwork(model.KindAlbumArtwork, "gone-album", model.ImageTypePrimary)
+		_, err := awRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "gone-album", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
-		_, err = awRepo.GetItemArtwork(model.KindArtistArtwork, "gone-artist", model.ImageTypePrimary)
+		_, err = awRepo.GetItemArtwork(ctx, model.KindArtistArtwork, "gone-artist", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
-		_, err = awRepo.GetItemArtwork(model.KindArtistArtwork, "live-artist", model.ImageTypePrimary)
+		_, err = awRepo.GetItemArtwork(ctx, model.KindArtistArtwork, "live-artist", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 	})
 
 	It("purges dangling artwork_queue rows for gone entities", func() {
 		queueRepo := tests.CreateMockArtworkQueueRepo()
-		Expect(queueRepo.Enqueue(
+		Expect(queueRepo.Enqueue(ctx,
 			model.ArtworkQueueItem{ItemKind: "al", ItemID: "gone-album", ImageType: model.ImageTypePrimary},
 			model.ArtworkQueueItem{ItemKind: "al", ItemID: "live-album", ImageType: model.ImageTypePrimary},
 		)).To(Succeed())
@@ -80,17 +82,17 @@ var _ = Describe("Prune", func() {
 		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
 		old := time.Now().Add(-2 * time.Hour)
 		Expect(os.Chtimes(store.path(h, "image/jpeg"), old, old)).To(Succeed())
-		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+		Expect(awRepo.PutImage(ctx, &model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
 		ageArtwork(h, old)
 
 		kept := []byte("kept-bytes")
 		hk, _ := hashImage(bytes.NewReader(kept))
 		Expect(store.Write(hk, "image/jpeg", bytes.NewReader(kept))).To(Succeed())
-		Expect(awRepo.PutImage(&model.Artwork{Hash: hk, Mime: "image/jpeg"})).To(Succeed())
+		Expect(awRepo.PutImage(ctx, &model.Artwork{Hash: hk, Mime: "image/jpeg"})).To(Succeed())
 
 		Expect(prune(context.Background(), ds, store)).To(Succeed())
 
-		_, err := awRepo.GetImage(h)
+		_, err := awRepo.GetImage(ctx, h)
 		Expect(err).To(MatchError(model.ErrNotFound))
 		_, err = store.Open(h, "image/jpeg")
 		Expect(os.IsNotExist(err)).To(BeTrue())
@@ -103,14 +105,14 @@ var _ = Describe("Prune", func() {
 		data := []byte("reacquired-bytes")
 		h, _ := hashImage(bytes.NewReader(data))
 		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
-		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+		Expect(awRepo.PutImage(ctx, &model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
 		ageArtwork(h, time.Now().Add(-2*time.Hour))
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "a1",
+		Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "a1",
 			ImageType: model.ImageTypePrimary, Hash: h, Source: "folder"})).To(Succeed())
 
 		Expect(prune(context.Background(), ds, store)).To(Succeed())
 
-		_, err := awRepo.GetImage(h)
+		_, err := awRepo.GetImage(ctx, h)
 		Expect(err).ToNot(HaveOccurred())
 		rc, err := store.Open(h, "image/jpeg")
 		Expect(err).ToNot(HaveOccurred())
@@ -122,11 +124,11 @@ var _ = Describe("Prune", func() {
 		h, _ := hashImage(bytes.NewReader(data))
 		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
 		// Reacquisition refreshed created_at, so the row is unreferenced but too young to drop.
-		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+		Expect(awRepo.PutImage(ctx, &model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
 
 		Expect(prune(context.Background(), ds, store)).To(Succeed())
 
-		_, err := awRepo.GetImage(h)
+		_, err := awRepo.GetImage(ctx, h)
 		Expect(err).ToNot(HaveOccurred())
 		rc, err := store.Open(h, "image/jpeg")
 		Expect(err).ToNot(HaveOccurred())
@@ -137,7 +139,7 @@ var _ = Describe("Prune", func() {
 		data := []byte("racing-bytes")
 		h, _ := hashImage(bytes.NewReader(data))
 		Expect(store.Write(h, "image/jpeg", bytes.NewReader(data))).To(Succeed())
-		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+		Expect(awRepo.PutImage(ctx, &model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
 		ageArtwork(h, time.Now().Add(-2*time.Hour))
 		// The row is orphaned, but a concurrent acquisition just touched the file's mtime.
 
@@ -170,7 +172,7 @@ var _ = Describe("Prune", func() {
 		Expect(os.Chtimes(store.path(h, "image/png"), old, old)).To(Succeed())
 		Expect(os.Chtimes(store.path(h, "image/jpeg"), old, old)).To(Succeed())
 		// The row records the current mime; the .png file is a superseded variant.
-		Expect(awRepo.PutImage(&model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
+		Expect(awRepo.PutImage(ctx, &model.Artwork{Hash: h, Mime: "image/jpeg"})).To(Succeed())
 
 		Expect(prune(context.Background(), ds, store)).To(Succeed())
 
@@ -192,14 +194,14 @@ var _ = Describe("Prune", func() {
 		hb, _ := hashImage(bytes.NewReader(blocked))
 		Expect(store.Write(hb, "image/jpeg", bytes.NewReader(blocked))).To(Succeed())
 		Expect(os.Chtimes(store.path(hb, "image/jpeg"), old, old)).To(Succeed())
-		Expect(awRepo.PutImage(&model.Artwork{Hash: hb, Mime: "image/jpeg"})).To(Succeed())
+		Expect(awRepo.PutImage(ctx, &model.Artwork{Hash: hb, Mime: "image/jpeg"})).To(Succeed())
 		ageArtwork(hb, old)
 
 		good := []byte("good-bytes")
 		hg, _ := hashImage(bytes.NewReader(good))
 		Expect(store.Write(hg, "image/jpeg", bytes.NewReader(good))).To(Succeed())
 		Expect(os.Chtimes(store.path(hg, "image/jpeg"), old, old)).To(Succeed())
-		Expect(awRepo.PutImage(&model.Artwork{Hash: hg, Mime: "image/jpeg"})).To(Succeed())
+		Expect(awRepo.PutImage(ctx, &model.Artwork{Hash: hg, Mime: "image/jpeg"})).To(Succeed())
 		ageArtwork(hg, old)
 
 		// A read-only shard directory makes os.Remove fail (EACCES) for hb's file only.
@@ -210,13 +212,13 @@ var _ = Describe("Prune", func() {
 
 		Expect(prune(context.Background(), ds, store)).To(Succeed())
 
-		_, err := awRepo.GetImage(hg)
+		_, err := awRepo.GetImage(ctx, hg)
 		Expect(err).To(MatchError(model.ErrNotFound))
 		_, err = store.Open(hg, "image/jpeg")
 		Expect(os.IsNotExist(err)).To(BeTrue())
 
 		// The row purge does not depend on file removal, so only the file survives.
-		_, err = awRepo.GetImage(hb)
+		_, err = awRepo.GetImage(ctx, hb)
 		Expect(err).To(MatchError(model.ErrNotFound))
 		rc, err := store.Open(hb, "image/jpeg")
 		Expect(err).ToNot(HaveOccurred())
diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
index f4f3ef725..40baa2495 100644
--- a/core/artwork/resolve.go
+++ b/core/artwork/resolve.go
@@ -198,7 +198,7 @@ func (r *resolver) fetchExternalArtist(ctx context.Context, ar model.Artist) (io
 
 // resolveAlbum walks conf.Server.CoverArtPriority over the folder, embedded and external sources.
 func (r *resolver) resolveAlbum(ctx context.Context, albumID string) (resolution, error) {
-	al, err := r.ds.Album(ctx).Get(albumID)
+	al, err := r.ds.Album().Get(ctx, albumID)
 	if err != nil {
 		return resolution{}, err
 	}
@@ -243,7 +243,7 @@ func (r *resolver) resolveAlbum(ctx context.Context, albumID string) (resolution
 
 // resolveArtist tries the uploaded image first, then walks conf.Server.ArtistArtPriority.
 func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resolution, error) {
-	ar, err := r.ds.Artist(ctx).Get(artistID)
+	ar, err := r.ds.Artist().Get(ctx, artistID)
 	if err != nil {
 		return resolution{}, err
 	}
@@ -259,7 +259,7 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resoluti
 	}
 
 	// Only consider albums where the artist is the sole album artist.
-	als, err := r.ds.Album(ctx).GetAll(model.QueryOptions{Filters: persistence.SoleAlbumArtistFilter(artistID)})
+	als, err := r.ds.Album().GetAll(ctx, model.QueryOptions{Filters: persistence.SoleAlbumArtistFilter(artistID)})
 	if err != nil {
 		return resolution{}, err
 	}
@@ -328,7 +328,7 @@ const PlaylistGridSamples = 4
 
 // resolvePlaylist tries the uploaded image, the sidecar and ExternalImageURL, then a generated grid.
 func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (resolution, error) {
-	pl, err := r.ds.Playlist(ctx).Get(playlistID)
+	pl, err := r.ds.Playlist().Get(ctx, playlistID)
 	if err != nil {
 		return resolution{}, err
 	}
@@ -374,8 +374,8 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 		}
 	}
 
-	albumIDs, err := r.ds.Playlist(ctx).Tracks(pl.ID, false).
-		GetAlbumIDs(model.QueryOptions{Max: PlaylistGridSamples, Sort: "random()"})
+	albumIDs, err := r.ds.Playlist().Tracks(ctx, pl.ID, false).
+		GetAlbumIDs(ctx, model.QueryOptions{Max: PlaylistGridSamples, Sort: "random()"})
 	if err != nil {
 		return resolution{}, err
 	}
@@ -428,7 +428,7 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 
 // resolveRadio serves only an uploaded image; there is no fallback.
 func (r *resolver) resolveRadio(ctx context.Context, radioID string) (resolution, error) {
-	radio, err := r.ds.Radio(ctx).Get(radioID)
+	radio, err := r.ds.Radio().Get(ctx, radioID)
 	if err != nil {
 		return resolution{}, err
 	}
@@ -439,7 +439,7 @@ func (r *resolver) resolveRadio(ctx context.Context, radioID string) (resolution
 // resolveMediaFile resolves a track's own embedded art only, so disabled or missing cover art
 // is a definitive absent.
 func (r *resolver) resolveMediaFile(ctx context.Context, id string) (resolution, error) {
-	mf, err := r.ds.MediaFile(ctx).Get(id)
+	mf, err := r.ds.MediaFile().Get(ctx, id)
 	if err != nil {
 		return resolution{}, err
 	}
diff --git a/core/artwork/uploader_test.go b/core/artwork/uploader_test.go
index 44f5ede26..b1420c935 100644
--- a/core/artwork/uploader_test.go
+++ b/core/artwork/uploader_test.go
@@ -16,12 +16,14 @@ import (
 )
 
 var _ = Describe("Uploader", func() {
+	var ctx context.Context
 	var svc Uploader
 	var tmpDir string
 	var artRepo *tests.MockArtworkRepo
 	var queueRepo *tests.MockArtworkQueueRepo
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		DeferCleanup(configtest.SetupConfig())
 		tmpDir = GinkgoT().TempDir()
 		conf.Server.DataFolder = conf.NewDir(tmpDir)
@@ -33,7 +35,6 @@ var _ = Describe("Uploader", func() {
 
 	Describe("SetImage", func() {
 		It("creates directory and saves image file", func() {
-			ctx := context.Background()
 			reader := strings.NewReader("fake image data")
 			filename, err := svc.SetImage(ctx, consts.EntityArtist, "ar-1", "Pink Floyd", "", reader, ".jpg")
 			Expect(err).ToNot(HaveOccurred())
@@ -46,7 +47,6 @@ var _ = Describe("Uploader", func() {
 		})
 
 		It("falls back to ID-only filename when name cleans to empty", func() {
-			ctx := context.Background()
 			reader := strings.NewReader("data")
 			filename, err := svc.SetImage(ctx, consts.EntityPlaylist, "pl-1", "!!!", "", reader, ".png")
 			Expect(err).ToNot(HaveOccurred())
@@ -54,7 +54,6 @@ var _ = Describe("Uploader", func() {
 		})
 
 		It("removes old image when replacing", func() {
-			ctx := context.Background()
 			oldDir := filepath.Join(tmpDir, "artwork", "artist")
 			Expect(os.MkdirAll(oldDir, 0755)).To(Succeed())
 			oldFile := filepath.Join(oldDir, "ar-1_old.png")
@@ -70,15 +69,13 @@ var _ = Describe("Uploader", func() {
 		})
 
 		It("ignores missing old file without error", func() {
-			ctx := context.Background()
 			reader := strings.NewReader("data")
 			_, err := svc.SetImage(ctx, consts.EntityArtist, "ar-1", "Name", "/nonexistent/path.jpg", reader, ".jpg")
 			Expect(err).ToNot(HaveOccurred())
 		})
 
 		It("does not touch artwork state or the queue (that is EnqueueArtwork's job, post-Put)", func() {
-			ctx := context.Background()
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "ar", ItemID: "ar-1", Hash: "oldhash", Source: "external",
 			})).To(Succeed())
 
@@ -87,25 +84,24 @@ var _ = Describe("Uploader", func() {
 
 			// SetImage only writes the file; the state row survives and nothing is queued until
 			// the caller has persisted the new filename and called EnqueueArtwork.
-			_, err = artRepo.GetItemArtwork(model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
+			_, err = artRepo.GetItemArtwork(ctx, model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(queueRepo.DequeueBatch(1000)).To(BeEmpty())
+			Expect(queueRepo.DequeueBatch(ctx, 1000)).To(BeEmpty())
 		})
 	})
 
 	Describe("EnqueueArtwork", func() {
 		It("clears artwork state and enqueues a Bump", func() {
-			ctx := context.Background()
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "ar", ItemID: "ar-1", Hash: "oldhash", Source: "external",
 			})).To(Succeed())
 
 			svc.EnqueueArtwork(ctx, consts.EntityArtist, "ar-1")
 
-			_, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
+			_, err := artRepo.GetItemArtwork(ctx, model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound))
 
-			queued, err := queueRepo.DequeueBatch(1000)
+			queued, err := queueRepo.DequeueBatch(ctx, 1000)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(queued).To(ContainElement(SatisfyAll(
 				HaveField("ItemKind", "ar"),
@@ -116,13 +112,12 @@ var _ = Describe("Uploader", func() {
 
 		It("is a no-op for an unknown entity type", func() {
 			svc.EnqueueArtwork(context.Background(), "unknown", "x-1")
-			Expect(queueRepo.DequeueBatch(1000)).To(BeEmpty())
+			Expect(queueRepo.DequeueBatch(ctx, 1000)).To(BeEmpty())
 		})
 	})
 
 	Describe("RemoveImage", func() {
 		It("removes the file at the given path", func() {
-			ctx := context.Background()
 			dir := filepath.Join(tmpDir, "artwork", "artist")
 			Expect(os.MkdirAll(dir, 0755)).To(Succeed())
 			path := filepath.Join(dir, "ar-1_test.jpg")
@@ -134,13 +129,11 @@ var _ = Describe("Uploader", func() {
 		})
 
 		It("succeeds when file does not exist", func() {
-			ctx := context.Background()
 			err := svc.RemoveImage(ctx, "/nonexistent/file.jpg")
 			Expect(err).ToNot(HaveOccurred())
 		})
 
 		It("succeeds with empty path", func() {
-			ctx := context.Background()
 			err := svc.RemoveImage(ctx, "")
 			Expect(err).ToNot(HaveOccurred())
 		})
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index e8fb3a11c..28e51958c 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -45,7 +45,7 @@ type Worker struct {
 	broker  events.Broker
 	pruneMu sync.RWMutex
 	pools   []*drainPool
-	runCtx  context.Context
+	runCtx  context.Context //nolint:containedctx // worker lifecycle ctx, set at Run
 	paused  func() bool
 
 	gatesMu sync.Mutex
@@ -155,7 +155,7 @@ func (w *Worker) drain(ctx context.Context, concurrency int, kinds ...string) (i
 	}
 	// Dequeue well past the pool size so a slow external lookup never idles the other slots.
 	// DequeueBatch does not mark rows taken, so this is one query per pass, not per slot.
-	items, err := w.proc.ds.ArtworkQueue(ctx).DequeueBatch(max(16, 4*concurrency), kinds...)
+	items, err := w.proc.ds.ArtworkQueue().DequeueBatch(ctx, max(16, 4*concurrency), kinds...)
 	if err != nil {
 		return 0, err
 	}
@@ -246,12 +246,12 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 	ctx = withTrace(ctx, trace)
 	out, got, retryIn := w.proc.acquire(ctx, item)
 
-	queue := w.proc.ds.ArtworkQueue(ctx)
+	queue := w.proc.ds.ArtworkQueue()
 	switch out {
 	case outcomeFound, outcomeAbsent:
 		// A scan that re-enqueued this row mid-flight reset its retry_at, so the row survives
 		// here and the next drain re-resolves it.
-		if err := queue.DeleteIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt); err != nil {
+		if err := queue.DeleteIfUnchanged(ctx, item.ItemKind, item.ItemID, item.ImageType, item.RetryAt); err != nil {
 			log.Warn(ctx, "Artwork: Could not delete processed queue item", "kind", item.ItemKind, "id", item.ItemID, err)
 		}
 	case outcomeFoundStale, outcomeFailed:
@@ -260,7 +260,7 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 		if retryAt.Before(item.EnqueuedAt.Add(giveUpAfter)) {
 			// A mid-flight re-enqueue reset retry_at; stale backoff must not stomp its
 			// fresh, immediate eligibility.
-			if err := queue.MarkFailedIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt, retryAt, encoded); err != nil {
+			if err := queue.MarkFailedIfUnchanged(ctx, item.ItemKind, item.ItemID, item.ImageType, item.RetryAt, retryAt, encoded); err != nil {
 				log.Warn(ctx, "Artwork: Could not reschedule failed queue item", "kind", item.ItemKind, "id", item.ItemID, err)
 			}
 			log.Debug(ctx, "Artwork: Rescheduled item", "kind", item.ItemKind, "id", item.ItemID,
@@ -271,7 +271,7 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 		// Art already being served is kept: exhaustion means unreachable, not removed.
 		settled := "kept previous state"
 		if out == outcomeFailed && settlesAbsentOnGiveUp(item.ItemKind) && !w.hasResolvedArtwork(ctx, item) {
-			writeAbsent(ctx, w.proc.ds.Artwork(ctx), item)
+			writeAbsent(ctx, w.proc.ds.Artwork(), item)
 			settled = "recorded absent"
 		}
 		// The queue row is about to go, taking the only record of the failure with it. This write is
@@ -279,7 +279,7 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 		w.recordGiveUp(ctx, item, encoded)
 		log.Info(ctx, "Artwork: Retry budget exhausted, giving up", "kind", item.ItemKind, "id", item.ItemID,
 			"outcome", out, "attempts", item.Attempts+1, "budget", giveUpAfter, "settled", settled)
-		if err := queue.DeleteIfUnchanged(item.ItemKind, item.ItemID, item.ImageType, item.RetryAt); err != nil {
+		if err := queue.DeleteIfUnchanged(ctx, item.ItemKind, item.ItemID, item.ImageType, item.RetryAt); err != nil {
 			log.Warn(ctx, "Artwork: Could not remove exhausted queue item", "kind", item.ItemKind, "id", item.ItemID, err)
 		}
 	}
@@ -293,7 +293,7 @@ func (w *Worker) recordGiveUp(ctx context.Context, item model.ArtworkQueueItem,
 	if !ok {
 		return
 	}
-	if err := w.proc.ds.Artwork(ctx).PutLastFailure(kind, item.ItemID, item.ImageType, trace); err != nil {
+	if err := w.proc.ds.Artwork().PutLastFailure(ctx, kind, item.ItemID, item.ImageType, trace); err != nil {
 		log.Warn(ctx, "Artwork: Could not record the last failure", "kind", item.ItemKind, "id", item.ItemID, err)
 	}
 }
@@ -303,7 +303,7 @@ func (w *Worker) hasResolvedArtwork(ctx context.Context, item model.ArtworkQueue
 	if !ok {
 		return false
 	}
-	ia, err := w.proc.ds.Artwork(ctx).GetItemArtwork(kind, item.ItemID, item.ImageType)
+	ia, err := w.proc.ds.Artwork().GetItemArtwork(ctx, kind, item.ItemID, item.ImageType)
 	return err == nil && ia.Hash != ""
 }
 
diff --git a/core/artwork/worker_soak_test.go b/core/artwork/worker_soak_test.go
index 803cc2dfe..9be95cf2a 100644
--- a/core/artwork/worker_soak_test.go
+++ b/core/artwork/worker_soak_test.go
@@ -21,6 +21,12 @@ import (
 const soakCycles = 2200
 
 var _ = Describe("Worker soak", func() {
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+	})
+
 	It("does not leak goroutines, heap, or fds over many acquisition cycles", func() {
 		if testing.Short() {
 			Skip("skipping soak test in short mode")
@@ -100,9 +106,9 @@ var _ = Describe("Worker soak", func() {
 			// Read-back exercises the surfaces a caller would use after acquisition.
 			if out == outcomeFound {
 				kind, _ := model.ParseKind(it.ItemKind)
-				ia, err := artRepo.GetItemArtwork(kind, it.ItemID, model.ImageTypePrimary)
+				ia, err := artRepo.GetItemArtwork(ctx, kind, it.ItemID, model.ImageTypePrimary)
 				Expect(err).ToNot(HaveOccurred(), "cycle %d: GetItemArtwork", i)
-				art, err := artRepo.GetImage(ia.Hash)
+				art, err := artRepo.GetImage(ctx, ia.Hash)
 				Expect(err).ToNot(HaveOccurred(), "cycle %d: GetImage", i)
 				rc, err := store.Open(ia.Hash, art.Mime)
 				switch {
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index d74e3a5ed..a6c07b763 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -56,8 +56,8 @@ type reenqueueOnDequeue struct {
 	done bool
 }
 
-func (r *reenqueueOnDequeue) DequeueBatch(n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
-	items, err := r.MockArtworkQueueRepo.DequeueBatch(n, kinds...)
+func (r *reenqueueOnDequeue) DequeueBatch(ctx context.Context, n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
+	items, err := r.MockArtworkQueueRepo.DequeueBatch(ctx, n, kinds...)
 	if !r.done && len(items) > 0 {
 		r.done = true
 		for k, it := range r.Data {
@@ -124,18 +124,27 @@ type visibilityPlaylistDS struct {
 	tracks  model.PlaylistTrackRepository
 }
 
-func (v *visibilityPlaylistDS) Playlist(ctx context.Context) model.PlaylistRepository {
+func (v *visibilityPlaylistDS) Playlist() model.PlaylistRepository {
 	repo := tests.CreateMockPlaylistRepo()
 	repo.TracksRepo = v.tracks
-	if u, ok := request.UserFrom(ctx); ok && u.IsAdmin {
-		repo.SetData(model.Playlists{v.private})
+	repo.SetData(model.Playlists{v.private})
+	return &visibilityPlaylistRepo{MockPlaylistRepo: repo}
+}
+
+type visibilityPlaylistRepo struct {
+	*tests.MockPlaylistRepo
+}
+
+func (v *visibilityPlaylistRepo) Get(ctx context.Context, id string) (*model.Playlist, error) {
+	if u, ok := request.UserFrom(ctx); !ok || !u.IsAdmin {
+		return nil, model.ErrNotFound
 	}
-	return repo
+	return v.MockPlaylistRepo.Get(ctx, id)
 }
 
 func adminUserRepo() *tests.MockedUserRepo {
 	repo := tests.CreateMockUserRepo()
-	Expect(repo.Put(&model.User{ID: "admin", UserName: "admin", IsAdmin: true})).To(Succeed())
+	Expect(repo.Put(GinkgoT().Context(), &model.User{ID: "admin", UserName: "admin", IsAdmin: true})).To(Succeed())
 	return repo
 }
 
@@ -157,8 +166,8 @@ var _ = Describe("Worker", func() {
 	)
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		DeferCleanup(configtest.SetupConfig())
-		ctx = context.Background()
 		var err error
 		repoRoot, err = os.Getwd()
 		Expect(err).ToNot(HaveOccurred())
@@ -200,7 +209,7 @@ var _ = Describe("Worker", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}},
 			})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 				ItemKind: "al", ItemID: "al1", Priority: model.ArtworkPriorityScan,
 			})).To(Succeed())
 
@@ -208,11 +217,11 @@ var _ = Describe("Worker", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(n).To(Equal(1))
 
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Source).To(Equal("folder"))
 
-			count, err := queueRepo.Count()
+			count, err := queueRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(BeZero(), "a found item must be deleted from the queue")
 		})
@@ -223,7 +232,7 @@ var _ = Describe("Worker", func() {
 			ds.MockedMediaFile.(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: "mf1", LibraryID: 0, Path: "tests/fixtures/artist/an-album/test.mp3", HasCoverArt: true},
 			})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 				ItemKind: "mf", ItemID: "mf1", Priority: model.ArtworkPriorityBump,
 			})).To(Succeed())
 
@@ -231,12 +240,12 @@ var _ = Describe("Worker", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(n).To(Equal(1))
 
-			ia, err := artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindMediaFileArtwork, "mf1", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Source).To(Equal("embedded"))
 			Expect(ia.Hash).ToNot(BeEmpty())
 
-			art, err := artRepo.GetImage(ia.Hash)
+			art, err := artRepo.GetImage(ctx, ia.Hash)
 			Expect(err).ToNot(HaveOccurred())
 			r, err := store.Open(ia.Hash, art.Mime)
 			Expect(err).ToNot(HaveOccurred())
@@ -245,7 +254,7 @@ var _ = Describe("Worker", func() {
 			Expect(err).ToNot(HaveOccurred())
 			Expect(data).ToNot(BeEmpty(), "embedded bytes must be written to the store")
 
-			count, err := queueRepo.Count()
+			count, err := queueRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(BeZero())
 		})
@@ -254,7 +263,7 @@ var _ = Describe("Worker", func() {
 			conf.Server.CoverArtPriority = "external"
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al4", Name: "Album"}})
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al4"})).To(Succeed())
 
 			n, err := w.drain(ctx, 2)
 			Expect(err).ToNot(HaveOccurred())
@@ -265,7 +274,7 @@ var _ = Describe("Worker", func() {
 			Expect(it.Attempts).To(Equal(1))
 			Expect(it.RetryAt).To(BeTemporally(">", time.Now()))
 
-			_, err = artRepo.GetItemArtwork(model.KindAlbumArtwork, "al4", model.ImageTypePrimary)
+			_, err = artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al4", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound), "a timeout must never settle on absent")
 		})
 
@@ -275,7 +284,7 @@ var _ = Describe("Worker", func() {
 			// Well above backoff(0)'s jittered ceiling, so only the hint can produce this retry_at.
 			const askedFor = 90 * time.Minute
 			imageAgents(&fakeImageAgent{name: "throttledAgent", err: &agents.RetryLaterError{RetryIn: askedFor}})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al9"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al9"})).To(Succeed())
 
 			n, err := w.drain(ctx, 2)
 			Expect(err).ToNot(HaveOccurred())
@@ -296,7 +305,7 @@ var _ = Describe("Worker", func() {
 				{ID: "alstale", Name: "Album", FolderIDs: []string{"f1"}},
 			})
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "alstale"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alstale"})).To(Succeed())
 
 			n, err := w.drain(ctx, 2)
 			Expect(err).ToNot(HaveOccurred())
@@ -307,7 +316,7 @@ var _ = Describe("Worker", func() {
 			Expect(it.Attempts).To(Equal(1))
 			Expect(it.RetryAt).To(BeTemporally(">", time.Now()))
 
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alstale", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alstale", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Source).To(Equal("folder"), "the fallback art is served meanwhile")
 
@@ -327,7 +336,7 @@ var _ = Describe("Worker", func() {
 			racing := &reenqueueOnDequeue{MockArtworkQueueRepo: queueRepo}
 			ds.MockedArtworkQueue = racing
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 				ItemKind: "al", ItemID: "al7", Priority: model.ArtworkPriorityScan,
 			})).To(Succeed())
 
@@ -337,7 +346,7 @@ var _ = Describe("Worker", func() {
 
 			// The concurrent re-enqueue changed retry_at, so the found-path delete was a no-op.
 			Expect(findQueued(queueRepo, "al", "al7")).ToNot(BeNil())
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al7", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al7", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Source).To(Equal("folder"))
 		})
@@ -349,7 +358,7 @@ var _ = Describe("Worker", func() {
 			racing := &reenqueueOnDequeue{MockArtworkQueueRepo: queueRepo}
 			ds.MockedArtworkQueue = racing
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al8"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al8"})).To(Succeed())
 			dequeued := findQueued(queueRepo, "al", "al8").RetryAt
 
 			n, err := w.drain(ctx, 1)
@@ -368,7 +377,7 @@ var _ = Describe("Worker", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al9", Name: "Album"}})
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al9"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al9"})).To(Succeed())
 			// Age the row past the retry budget.
 			expireQueued(queueRepo, "al9")
 
@@ -377,7 +386,7 @@ var _ = Describe("Worker", func() {
 			Expect(n).To(Equal(1))
 
 			Expect(findQueued(queueRepo, "al", "al9")).To(BeNil())
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al9", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al9", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Hash).To(BeEmpty())
 		})
@@ -385,13 +394,13 @@ var _ = Describe("Worker", func() {
 		It("keeps already-served art when the retry budget is exhausted", func() {
 			conf.Server.CoverArtPriority = "external"
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al10", Name: "Album"}})
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "al10", ImageType: model.ImageTypePrimary,
 				Hash: "cafebabe", Source: "external:lastfm",
 			})).To(Succeed())
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al10"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al10"})).To(Succeed())
 			expireQueued(queueRepo, "al10")
 
 			n, err := w.drain(ctx, 1)
@@ -399,7 +408,7 @@ var _ = Describe("Worker", func() {
 			Expect(n).To(Equal(1))
 
 			Expect(findQueued(queueRepo, "al", "al10")).To(BeNil())
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al10", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al10", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Hash).To(Equal("cafebabe"), "a persistent outage must not discard served art")
 		})
@@ -409,7 +418,7 @@ var _ = Describe("Worker", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al11", Name: "Album"}})
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al11"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al11"})).To(Succeed())
 
 			_, err := w.drain(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
@@ -430,13 +439,13 @@ var _ = Describe("Worker", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al13", Name: "Album"}})
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al13"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al13"})).To(Succeed())
 			expireQueued(queueRepo, "al13")
 
 			_, err := w.drain(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
 
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al13", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al13", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred(), "settling absent must create the row the failure is written to")
 			Expect(ia.Hash).To(BeEmpty())
 			Expect(DecodeTrace(ia.LastFailure, "")).ToNot(BeEmpty())
@@ -445,20 +454,20 @@ var _ = Describe("Worker", func() {
 		It("keeps the failure on the state row after the queue row is deleted", func() {
 			conf.Server.CoverArtPriority = "external"
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al12", Name: "Album"}})
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "al12", ImageType: model.ImageTypePrimary,
 				Hash: "cafebabe", Source: "external:lastfm",
 			})).To(Succeed())
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
 			w = NewWorker(ds, store, ag, ffm, broker, imgCache)
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al12"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al12"})).To(Succeed())
 			expireQueued(queueRepo, "al12")
 
 			_, err := w.drain(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(findQueued(queueRepo, "al", "al12")).To(BeNil())
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al12", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al12", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(DecodeTrace(ia.LastFailure, "")).ToNot(BeEmpty(),
 				"the queue row is gone, so this is the only remaining record of the failure")
@@ -473,7 +482,7 @@ var _ = Describe("Worker", func() {
 			ds.MockedMediaFile.(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: "mfX", LibraryID: 0, Path: "tests/fixtures/artist/an-album/gone.mp3", HasCoverArt: true},
 			})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mfX"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "mf", ItemID: "mfX"})).To(Succeed())
 			expireQueued(queueRepo, "mfX")
 
 			n, err := w.drain(ctx, 1)
@@ -481,7 +490,7 @@ var _ = Describe("Worker", func() {
 			Expect(n).To(Equal(1))
 
 			Expect(findQueued(queueRepo, "mf", "mfX")).To(BeNil(), "the row must stop retrying")
-			_, err = artRepo.GetItemArtwork(model.KindMediaFileArtwork, "mfX", model.ImageTypePrimary)
+			_, err = artRepo.GetItemArtwork(ctx, model.KindMediaFileArtwork, "mfX", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound),
 				"no row leaves the track unresolved, so a later view can still recover it")
 			// Known gap: with no row and no absent settle, there is nowhere to keep the failure.
@@ -496,14 +505,14 @@ var _ = Describe("Worker", func() {
 				tracks:        &tests.MockPlaylistTrackRepo{},
 			}
 			w = NewWorker(vds, store, ag, ffm, broker, imgCache)
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plPriv"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plPriv"})).To(Succeed())
 
 			n, err := w.drain(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(n).To(Equal(1))
 
 			Expect(findQueued(queueRepo, "pl", "plPriv")).To(BeNil())
-			ia, err := artRepo.GetItemArtwork(model.KindPlaylistArtwork, "plPriv", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindPlaylistArtwork, "plPriv", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Hash).To(BeEmpty())
 		})
@@ -523,9 +532,9 @@ var _ = Describe("Worker", func() {
 				{ID: "al1", Name: "Album 1", FolderIDs: []string{"f1"}},
 				{ID: "al2", Name: "Album 2", FolderIDs: []string{"f1"}},
 			})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1", Priority: model.ArtworkPriorityScan})).To(Succeed())
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2", Priority: model.ArtworkPriorityScan})).To(Succeed())
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar1", Priority: model.ArtworkPriorityScan})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1", Priority: model.ArtworkPriorityScan})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2", Priority: model.ArtworkPriorityScan})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar1", Priority: model.ArtworkPriorityScan})).To(Succeed())
 
 			n, err := w.drain(ctx, 3)
 			Expect(err).ToNot(HaveOccurred())
@@ -572,7 +581,7 @@ var _ = Describe("Worker", func() {
 			conf.Server.CoverArtPriority = "cover.*" // local-only; no folder image → absent
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al3", Name: "Artless"}})
 			folderRepo.result = nil
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3", Priority: model.ArtworkPriorityScan})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3", Priority: model.ArtworkPriorityScan})).To(Succeed())
 
 			n, err := w.drain(ctx, 2)
 			Expect(err).ToNot(HaveOccurred())
@@ -582,7 +591,7 @@ var _ = Describe("Worker", func() {
 			Expect(evts).To(HaveLen(1), "a removed cover must live-refresh clients so they drop it")
 			Expect(evts[0].(*events.RefreshResource).Data(evts[0])).To(ContainSubstring("al3"))
 
-			ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al3", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Hash).To(BeEmpty(), "the outcome was absent, not found")
 		})
@@ -591,7 +600,7 @@ var _ = Describe("Worker", func() {
 			conf.Server.CoverArtPriority = "external"
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "alx", Name: "Album"}})
 			imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("agent timed out")})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{ItemKind: "al", ItemID: "alx"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alx"})).To(Succeed())
 
 			n, err := w.drain(ctx, 2)
 			Expect(err).ToNot(HaveOccurred())
@@ -725,7 +734,7 @@ var _ = Describe("Worker", func() {
 				{ID: "alpc", Name: "Album", FolderIDs: []string{"f1"}},
 			})
 			conf.Server.UICoverArtSize = 300
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 				ItemKind: "al", ItemID: "alpc", Priority: model.ArtworkPriorityScan,
 			})).To(Succeed())
 		})
@@ -813,11 +822,11 @@ var _ = Describe("Worker", func() {
 
 			// Artists first, exactly as Backfill orders them.
 			for _, a := range artists {
-				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 					ItemKind: "ar", ItemID: a.ID, Priority: model.ArtworkPriorityBackfill,
 				})).To(Succeed())
 			}
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 				ItemKind: "al", ItemID: "alx", Priority: model.ArtworkPriorityBackfill,
 			})).To(Succeed())
 
@@ -832,12 +841,12 @@ var _ = Describe("Worker", func() {
 			})
 
 			Eventually(func() bool {
-				ia, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "alx", model.ImageTypePrimary)
+				ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alx", model.ImageTypePrimary)
 				return err == nil && ia.Hash != ""
 			}, 5*time.Second, 50*time.Millisecond).Should(BeTrue(),
 				"a blocked external pool must not hold up local artwork")
 
-			_, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "arx0", model.ImageTypePrimary)
+			_, err := artRepo.GetItemArtwork(ctx, model.KindArtistArtwork, "arx0", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound), "artists are still blocked, as intended")
 		})
 	})
@@ -849,7 +858,7 @@ var _ = Describe("Worker", func() {
 			for i := range 8 {
 				id := fmt.Sprintf("alc%d", i)
 				albums = append(albums, model.Album{ID: id, Name: "Album"})
-				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 					ItemKind: "al", ItemID: id, Priority: model.ArtworkPriorityScan,
 				})).To(Succeed())
 			}
@@ -875,21 +884,21 @@ var _ = Describe("Worker", func() {
 			for i := range 8 {
 				id := fmt.Sprintf("alp%d", i)
 				albums = append(albums, model.Album{ID: id, Name: "Album", FolderIDs: []string{"f1"}})
-				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 					ItemKind: "al", ItemID: id, Priority: model.ArtworkPriorityScan,
 				})).To(Succeed())
 			}
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(albums)
 			// Pauses as soon as the first item has left the queue.
 			w.PauseWhile(func() bool {
-				n, _ := queueRepo.Count()
+				n, _ := queueRepo.Count(ctx)
 				return n < 8
 			})
 
 			_, err := w.drain(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
 
-			count, err := queueRepo.Count()
+			count, err := queueRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(int64(7)), "only the item dispatched before the pause may leave the queue")
 		})
@@ -897,7 +906,7 @@ var _ = Describe("Worker", func() {
 		It("dequeues past the worker pool so one drain covers many items", func() {
 			for i := range 16 {
 				ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: fmt.Sprintf("alb%d", i), Name: "Album"}})
-				Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+				Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 					ItemKind: "al", ItemID: fmt.Sprintf("alb%d", i), Priority: model.ArtworkPriorityScan,
 				})).To(Succeed())
 			}
@@ -932,7 +941,7 @@ var _ = Describe("Worker", func() {
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{
 				{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}},
 			})
-			Expect(queueRepo.Enqueue(model.ArtworkQueueItem{
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{
 				ItemKind: "al", ItemID: "al1", Priority: model.ArtworkPriorityScan,
 			})).To(Succeed())
 			w.PauseWhile(func() bool { return true })
diff --git a/core/auth/auth.go b/core/auth/auth.go
index b36bb2696..1bdc917da 100644
--- a/core/auth/auth.go
+++ b/core/auth/auth.go
@@ -48,7 +48,7 @@ func Init(ds model.DataStore) {
 }
 
 func loadOrCreateSecret(ctx context.Context, ds model.DataStore, key string) string {
-	secret, err := ds.Property(ctx).Get(key)
+	secret, err := ds.Property().Get(ctx, key)
 	if err != nil || secret == "" {
 		log.Info(ctx, "Creating new JWT secret", "key", key)
 		return createNewSecret(ctx, ds, key)
@@ -154,9 +154,9 @@ func CheckClaims(c Claims, usr model.User, audience string) error {
 }
 
 func WithAdminUser(ctx context.Context, ds model.DataStore) context.Context {
-	u, err := ds.User(ctx).FindFirstAdmin()
+	u, err := ds.User().FindFirstAdmin(ctx)
 	if err != nil {
-		c, err := ds.User(ctx).CountAll()
+		c, err := ds.User().CountAll(ctx)
 		if c == 0 && err == nil {
 			log.Debug(ctx, "No admin user yet!", err)
 		} else {
@@ -176,7 +176,7 @@ func createNewSecret(ctx context.Context, ds model.DataStore, key string) string
 		log.Error(ctx, "Could not encrypt JWT secret", err)
 		return secret
 	}
-	if err := ds.Property(ctx).Put(key, encSecret); err != nil {
+	if err := ds.Property().Put(ctx, key, encSecret); err != nil {
 		log.Error(ctx, "Could not save JWT secret in DB", err)
 	}
 	return secret
diff --git a/core/common.go b/core/common.go
index 6ff349b1b..db2dbbf1b 100644
--- a/core/common.go
+++ b/core/common.go
@@ -19,7 +19,7 @@ func userName(ctx context.Context) string {
 // BFR We should only access files through the `storage.Storage` interface. This will require changing how
 // TagLib and ffmpeg access files
 var AbsolutePath = func(ctx context.Context, ds model.DataStore, libId int, path string) string {
-	libPath, err := ds.Library(ctx).GetPath(libId)
+	libPath, err := ds.Library().GetPath(ctx, libId)
 	if err != nil {
 		return path
 	}
diff --git a/core/external/extdata_helper_test.go b/core/external/extdata_helper_test.go
index f7a155cd9..73d88e5b4 100644
--- a/core/external/extdata_helper_test.go
+++ b/core/external/extdata_helper_test.go
@@ -31,7 +31,7 @@ func (m *mockArtistRepo) SetData(artists model.Artists) {
 }
 
 // Get implements model.ArtistRepository.
-func (m *mockArtistRepo) Get(id string) (*model.Artist, error) {
+func (m *mockArtistRepo) Get(_ context.Context, id string) (*model.Artist, error) {
 	args := m.Called(id)
 	if args.Get(0) == nil {
 		return nil, args.Error(1)
@@ -40,7 +40,7 @@ func (m *mockArtistRepo) Get(id string) (*model.Artist, error) {
 }
 
 // GetAll implements model.ArtistRepository.
-func (m *mockArtistRepo) GetAll(options ...model.QueryOptions) (model.Artists, error) {
+func (m *mockArtistRepo) GetAll(_ context.Context, options ...model.QueryOptions) (model.Artists, error) {
 	argsSlice := make([]any, len(options))
 	for i, v := range options {
 		argsSlice[i] = v
@@ -85,7 +85,7 @@ func (m *mockMediaFileRepo) SetData(mediaFiles model.MediaFiles) {
 }
 
 // Get implements model.MediaFileRepository.
-func (m *mockMediaFileRepo) Get(id string) (*model.MediaFile, error) {
+func (m *mockMediaFileRepo) Get(ctx context.Context, id string) (*model.MediaFile, error) {
 	args := m.Called(id)
 	if args.Get(0) == nil {
 		return nil, args.Error(1)
@@ -94,12 +94,12 @@ func (m *mockMediaFileRepo) Get(id string) (*model.MediaFile, error) {
 }
 
 // GetAllByTags implements model.MediaFileRepository.
-func (m *mockMediaFileRepo) GetAllByTags(_ model.TagName, _ []string, options ...model.QueryOptions) (model.MediaFiles, error) {
-	return m.GetAll(options...)
+func (m *mockMediaFileRepo) GetAllByTags(ctx context.Context, _ model.TagName, _ []string, options ...model.QueryOptions) (model.MediaFiles, error) {
+	return m.GetAll(ctx, options...)
 }
 
 // GetAll implements model.MediaFileRepository.
-func (m *mockMediaFileRepo) GetAll(options ...model.QueryOptions) (model.MediaFiles, error) {
+func (m *mockMediaFileRepo) GetAll(ctx context.Context, options ...model.QueryOptions) (model.MediaFiles, error) {
 	argsSlice := make([]any, len(options))
 	for i, v := range options {
 		argsSlice[i] = v
@@ -112,7 +112,7 @@ func (m *mockMediaFileRepo) GetAll(options ...model.QueryOptions) (model.MediaFi
 }
 
 // GetRandom implements model.MediaFileRepository.
-func (m *mockMediaFileRepo) GetRandom(options ...model.QueryOptions) (model.MediaFiles, error) {
+func (m *mockMediaFileRepo) GetRandom(ctx context.Context, options ...model.QueryOptions) (model.MediaFiles, error) {
 	argsSlice := make([]any, len(options))
 	for i, v := range options {
 		argsSlice[i] = v
@@ -156,7 +156,7 @@ func newMockAlbumRepo() *mockAlbumRepo {
 }
 
 // Get implements model.AlbumRepository.
-func (m *mockAlbumRepo) Get(id string) (*model.Album, error) {
+func (m *mockAlbumRepo) Get(_ context.Context, id string) (*model.Album, error) {
 	args := m.Called(id)
 	if args.Get(0) == nil {
 		return nil, args.Error(1)
@@ -165,7 +165,7 @@ func (m *mockAlbumRepo) Get(id string) (*model.Album, error) {
 }
 
 // GetAll implements model.AlbumRepository.
-func (m *mockAlbumRepo) GetAll(options ...model.QueryOptions) (model.Albums, error) {
+func (m *mockAlbumRepo) GetAll(_ context.Context, options ...model.QueryOptions) (model.Albums, error) {
 	argsSlice := make([]any, len(options))
 	for i, v := range options {
 		argsSlice[i] = v
diff --git a/core/external/provider.go b/core/external/provider.go
index 3a3f4bd46..185725259 100644
--- a/core/external/provider.go
+++ b/core/external/provider.go
@@ -182,7 +182,7 @@ func (e *provider) populateAlbumInfo(ctx context.Context, album auxAlbum) (auxAl
 		}
 	}
 
-	err = e.ds.Album(ctx).UpdateExternalInfo(&album.Album)
+	err = e.ds.Album().UpdateExternalInfo(ctx, &album.Album)
 	if err != nil {
 		log.Error(ctx, "Error trying to update album external information", "id", album.ID, "name", albumName,
 			"elapsed", time.Since(start), err)
@@ -285,7 +285,7 @@ func (e *provider) populateArtistInfo(ctx context.Context, artist auxArtist) (au
 	if !throttled {
 		artist.ExternalInfoUpdatedAt = new(time.Now())
 	}
-	err := e.ds.Artist(ctx).UpdateExternalInfo(&artist.Artist)
+	err := e.ds.Artist().UpdateExternalInfo(ctx, &artist.Artist)
 	if err != nil {
 		log.Error(ctx, "Error trying to update artist external information", "id", artist.ID, "name", artistName,
 			"elapsed", time.Since(start), err)
@@ -548,7 +548,7 @@ func (e *provider) loadArtistsByID(ctx context.Context, similar []agents.Artist)
 	if len(ids) == 0 {
 		return matches, nil
 	}
-	res, err := e.ds.Artist(ctx).GetAll(model.QueryOptions{
+	res, err := e.ds.Artist().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.Eq{"artist.id": ids},
 	})
 	if err != nil {
@@ -577,7 +577,7 @@ func (e *provider) loadArtistsByMBID(ctx context.Context, similar []agents.Artis
 	if len(mbids) == 0 {
 		return matches, nil
 	}
-	res, err := e.ds.Artist(ctx).GetAll(model.QueryOptions{
+	res, err := e.ds.Artist().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.Eq{"mbz_artist_id": mbids},
 	})
 	if err != nil {
@@ -612,7 +612,7 @@ func (e *provider) loadArtistsByName(ctx context.Context, similar []agents.Artis
 	clauses := slice.Map(names, func(name string) squirrel.Sqlizer {
 		return squirrel.Like{"artist.name": name}
 	})
-	res, err := e.ds.Artist(ctx).GetAll(model.QueryOptions{
+	res, err := e.ds.Artist().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.Or(clauses),
 	})
 	if err != nil {
@@ -628,7 +628,7 @@ func (e *provider) loadArtistsByName(ctx context.Context, similar []agents.Artis
 
 func (e *provider) findArtist(ctx context.Context, artistName, id string) (*auxArtist, error) {
 	if id != "" {
-		artist, err := e.ds.Artist(ctx).Get(id)
+		artist, err := e.ds.Artist().Get(ctx, id)
 		if err == nil {
 			return &auxArtist{Artist: *artist}, nil
 		}
@@ -644,7 +644,7 @@ func (e *provider) findArtist(ctx context.Context, artistName, id string) (*auxA
 		return nil, model.ErrNotFound
 	}
 
-	artists, err := e.ds.Artist(ctx).GetAll(model.QueryOptions{
+	artists, err := e.ds.Artist().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.Like{"artist.name": artistName},
 		Max:     1,
 	})
@@ -666,7 +666,7 @@ func (e *provider) loadSimilar(ctx context.Context, artist *auxArtist, count int
 		ids = append(ids, sa.ID)
 	}
 
-	similar, err := e.ds.Artist(ctx).GetAll(model.QueryOptions{
+	similar, err := e.ds.Artist().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.Eq{"artist.id": ids},
 	})
 	if err != nil {
diff --git a/core/external/provider_refreshinfo_test.go b/core/external/provider_refreshinfo_test.go
index e7910a734..a1216dd94 100644
--- a/core/external/provider_refreshinfo_test.go
+++ b/core/external/provider_refreshinfo_test.go
@@ -71,8 +71,8 @@ var _ = Describe("Provider - RefreshInfo", func() {
 		ag = new(mockAgents)
 		broker = &fakeBroker{}
 		p = external.NewProvider(ds, ag, matcher.New(ds), broker)
-		mockArtistRepo = ds.Artist(ctx).(*tests.MockArtistRepo)
-		mockAlbumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
+		mockArtistRepo = ds.Artist().(*tests.MockArtistRepo)
+		mockAlbumRepo = ds.Album().(*tests.MockAlbumRepo)
 	})
 
 	It("repopulates an artist even when its info is fresh", func() {
@@ -84,7 +84,7 @@ var _ = Describe("Provider - RefreshInfo", func() {
 
 		Expect(p.RefreshInfo(ctx, model.KindArtistArtwork, "ar-1")).To(Succeed())
 
-		saved, err := mockArtistRepo.Get("ar-1")
+		saved, err := mockArtistRepo.Get(ctx, "ar-1")
 		Expect(err).ToNot(HaveOccurred())
 		Expect(saved.Biography).To(Equal("Fresh Bio"))
 	})
@@ -99,7 +99,7 @@ var _ = Describe("Provider - RefreshInfo", func() {
 
 		Expect(p.RefreshInfo(ctx, model.KindAlbumArtwork, "al-1")).To(Succeed())
 
-		saved, err := mockAlbumRepo.Get("al-1")
+		saved, err := mockAlbumRepo.Get(ctx, "al-1")
 		Expect(err).ToNot(HaveOccurred())
 		Expect(saved.Description).To(Equal("Fresh Notes"))
 	})
diff --git a/core/external/provider_similarsongs.go b/core/external/provider_similarsongs.go
index 4ab465b03..305b8d6ec 100644
--- a/core/external/provider_similarsongs.go
+++ b/core/external/provider_similarsongs.go
@@ -37,7 +37,7 @@ func (e *provider) SimilarSongs(ctx context.Context, id string, count int) (mode
 		if !errors.Is(err, model.ErrNotFound) {
 			return nil, err
 		}
-		genre, err := e.ds.Genre(ctx).Get(id)
+		genre, err := e.ds.Genre().Get(ctx, id)
 		if err != nil {
 			return nil, err
 		}
@@ -178,13 +178,13 @@ func (e *provider) seedMix(ctx context.Context, count int, sample func() (model.
 func (e *provider) samplePlaylistTracks(ctx context.Context, playlistID string, n int) (model.MediaFiles, error) {
 	// Refresh: a smart playlist materializes no tracks until it is evaluated, so skipping it would
 	// mix an empty seed set. It is a no-op for regular playlists and inside the refresh delay.
-	repo := e.ds.Playlist(ctx).Tracks(playlistID, true)
+	repo := e.ds.Playlist().Tracks(ctx, playlistID, true)
 	if repo == nil {
 		return nil, model.ErrNotFound
 	}
 	// A playlist can hold the same file at several positions, so over-fetch and dedup: a repeated
 	// seed wastes an agent call and can reach the mix twice through the seed fallback.
-	tracks, err := repo.GetAll(model.QueryOptions{
+	tracks, err := repo.GetAll(ctx, model.QueryOptions{
 		Sort:    "random",
 		Max:     n * 4,
 		Filters: squirrel.Eq{"missing": false},
@@ -225,7 +225,7 @@ func (e *provider) sampleGenreTracks(ctx context.Context, genre *model.Genre, n
 // sampleTracks returns up to n random present tracks. Seeds can end up in the mix verbatim, so
 // missing files would surface as unplayable entries.
 func (e *provider) sampleTracks(ctx context.Context, filter squirrel.Sqlizer, n int) (model.MediaFiles, error) {
-	return e.ds.MediaFile(ctx).GetRandom(model.QueryOptions{
+	return e.ds.MediaFile().GetRandom(ctx, model.QueryOptions{
 		Filters: squirrel.And{filter, squirrel.Eq{"missing": false}},
 		Max:     n,
 	})
diff --git a/core/external/provider_updatealbuminfo_test.go b/core/external/provider_updatealbuminfo_test.go
index e168aa026..d2fd4364e 100644
--- a/core/external/provider_updatealbuminfo_test.go
+++ b/core/external/provider_updatealbuminfo_test.go
@@ -35,7 +35,7 @@ var _ = Describe("Provider - UpdateAlbumInfo", func() {
 		ds = new(tests.MockDataStore)
 		ag = new(mockAgents)
 		p = external.NewProvider(ds, ag, matcher.New(ds), &fakeBroker{})
-		mockAlbumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
+		mockAlbumRepo = ds.Album().(*tests.MockAlbumRepo)
 		conf.Server.DevAlbumInfoTimeToLive = 1 * time.Hour
 	})
 
diff --git a/core/external/provider_updateartistinfo_test.go b/core/external/provider_updateartistinfo_test.go
index c722aaee8..5e2087d35 100644
--- a/core/external/provider_updateartistinfo_test.go
+++ b/core/external/provider_updateartistinfo_test.go
@@ -38,7 +38,7 @@ var _ = Describe("Provider - UpdateArtistInfo", func() {
 		ds = new(tests.MockDataStore)
 		ag = new(mockAgents)
 		p = external.NewProvider(ds, ag, matcher.New(ds), &fakeBroker{})
-		mockArtistRepo = ds.Artist(ctx).(*tests.MockArtistRepo)
+		mockArtistRepo = ds.Artist().(*tests.MockArtistRepo)
 	})
 
 	It("returns error when artist is not found", func() {
diff --git a/core/library.go b/core/library.go
index 6df0e95b5..628ee4b7b 100644
--- a/core/library.go
+++ b/core/library.go
@@ -32,25 +32,28 @@ type Library interface {
 	SetUserLibraries(ctx context.Context, userID string, libraryIDs []int) error
 	ValidateLibraryAccess(ctx context.Context, userID string, libraryID int) error
 
-	NewRepository(ctx context.Context) rest.Repository
+	Repository() rest.Repository[model.Library]
 }
 
 type libraryService struct {
-	ds            model.DataStore
-	scanner       model.Scanner
-	watcher       Watcher
-	broker        events.Broker
-	pluginManager PluginUnloader
+	ds     model.DataStore
+	broker events.Broker
+	repo   *libraryRepositoryWrapper
 }
 
 // NewLibrary creates a new Library service
 func NewLibrary(ds model.DataStore, scanner model.Scanner, watcher Watcher, broker events.Broker, pluginManager PluginUnloader) Library {
 	return &libraryService{
-		ds:            ds,
-		scanner:       scanner,
-		watcher:       watcher,
-		broker:        broker,
-		pluginManager: pluginManager,
+		ds:     ds,
+		broker: broker,
+		repo: &libraryRepositoryWrapper{
+			LibraryRepository: ds.Library(),
+			ds:                ds,
+			scanner:           scanner,
+			watcher:           watcher,
+			broker:            broker,
+			pluginManager:     pluginManager,
+		},
 	}
 }
 
@@ -58,16 +61,16 @@ func NewLibrary(ds model.DataStore, scanner model.Scanner, watcher Watcher, brok
 
 func (s *libraryService) GetUserLibraries(ctx context.Context, userID string) (model.Libraries, error) {
 	// Verify user exists
-	if _, err := s.ds.User(ctx).Get(userID); err != nil {
+	if _, err := s.ds.User().Get(ctx, userID); err != nil {
 		return nil, err
 	}
 
-	return s.ds.User(ctx).GetUserLibraries(userID)
+	return s.ds.User().GetUserLibraries(ctx, userID)
 }
 
 func (s *libraryService) SetUserLibraries(ctx context.Context, userID string, libraryIDs []int) error {
 	// Verify user exists
-	user, err := s.ds.User(ctx).Get(userID)
+	user, err := s.ds.User().Get(ctx, userID)
 	if err != nil {
 		return err
 	}
@@ -90,7 +93,7 @@ func (s *libraryService) SetUserLibraries(ctx context.Context, userID string, li
 	}
 
 	// Set user libraries
-	err = s.ds.User(ctx).SetUserLibraries(userID, libraryIDs)
+	err = s.ds.User().SetUserLibraries(ctx, userID, libraryIDs)
 	if err != nil {
 		return fmt.Errorf("error setting user libraries: %w", err)
 	}
@@ -115,7 +118,7 @@ func (s *libraryService) ValidateLibraryAccess(ctx context.Context, userID strin
 	}
 
 	// Check if user has explicit access to this library
-	libraries, err := s.ds.User(ctx).GetUserLibraries(userID)
+	libraries, err := s.ds.User().GetUserLibraries(ctx, userID)
 	if err != nil {
 		log.Error(ctx, "Error checking library access", "userID", userID, "libraryID", libraryID, err)
 		return fmt.Errorf("error checking library access: %w", err)
@@ -132,25 +135,14 @@ func (s *libraryService) ValidateLibraryAccess(ctx context.Context, userID strin
 
 // REST repository wrapper
 
-func (s *libraryService) NewRepository(ctx context.Context) rest.Repository {
-	repo := s.ds.Library(ctx)
-	wrapper := &libraryRepositoryWrapper{
-		ctx:               ctx,
-		LibraryRepository: repo,
-		Repository:        repo.(rest.Repository),
-		ds:                s.ds,
-		scanner:           s.scanner,
-		watcher:           s.watcher,
-		broker:            s.broker,
-		pluginManager:     s.pluginManager,
-	}
-	return wrapper
+func (s *libraryService) Repository() rest.Repository[model.Library] {
+	return s.repo
 }
 
+var _ rest.Persistable[model.Library] = (*libraryRepositoryWrapper)(nil)
+
 type libraryRepositoryWrapper struct {
-	rest.Repository
 	model.LibraryRepository
-	ctx           context.Context
 	ds            model.DataStore
 	scanner       model.Scanner
 	watcher       Watcher
@@ -158,59 +150,58 @@ type libraryRepositoryWrapper struct {
 	pluginManager PluginUnloader
 }
 
-func (r *libraryRepositoryWrapper) Save(entity any) (string, error) {
-	lib := entity.(*model.Library)
-	if err := r.validateLibrary(lib); err != nil {
+func (r *libraryRepositoryWrapper) Save(ctx context.Context, lib *model.Library) (string, error) {
+	if err := r.validateLibrary(ctx, lib); err != nil {
 		return "", err
 	}
 
-	err := r.LibraryRepository.Put(lib)
+	err := r.LibraryRepository.Put(ctx, lib)
 	if err != nil {
 		return "", r.mapError(err)
 	}
 
 	// Start watcher and trigger scan after successful library creation
 	if r.watcher != nil {
-		if err := r.watcher.Watch(r.ctx, lib); err != nil {
-			log.Warn(r.ctx, "Failed to start watcher for new library", "libraryID", lib.ID, "name", lib.Name, "path", lib.Path, err)
+		if err := r.watcher.Watch(ctx, lib); err != nil {
+			log.Warn(ctx, "Failed to start watcher for new library", "libraryID", lib.ID, "name", lib.Name, "path", lib.Path, err)
 		}
 	}
 
 	if r.scanner != nil {
-		go r.triggerScan(lib, "new")
+		go r.triggerScan(ctx, lib, "new")
 	}
 
 	// Send library refresh event to all clients
 	if r.broker != nil {
 		event := &events.RefreshResource{}
-		r.broker.SendBroadcastMessage(r.ctx, event.With("library", strconv.Itoa(lib.ID)))
-		log.Debug(r.ctx, "Library created - sent refresh event", "libraryID", lib.ID, "name", lib.Name)
+		r.broker.SendBroadcastMessage(ctx, event.With("library", strconv.Itoa(lib.ID)))
+		log.Debug(ctx, "Library created - sent refresh event", "libraryID", lib.ID, "name", lib.Name)
 	}
 
 	return strconv.Itoa(lib.ID), nil
 }
 
-func (r *libraryRepositoryWrapper) Update(id string, entity any, cols ...string) error {
-	lib := entity.(*model.Library)
+func (r *libraryRepositoryWrapper) Update(ctx context.Context, id string, entity model.Library, cols ...string) error {
+	lib := &entity
 	libID, err := strconv.Atoi(id)
 	if err != nil {
 		return fmt.Errorf("invalid library ID: %s", id)
 	}
 
 	lib.ID = libID
-	if err := r.validateLibrary(lib); err != nil {
+	if err := r.validateLibrary(ctx, lib); err != nil {
 		return err
 	}
 
 	// Get the original library to check if path changed
-	originalLib, err := r.Get(libID)
+	originalLib, err := r.Get(ctx, libID)
 	if err != nil {
 		return r.mapError(err)
 	}
 
 	pathChanged := originalLib.Path != lib.Path
 
-	err = r.LibraryRepository.Put(lib, cols...)
+	err = r.LibraryRepository.Put(ctx, lib, cols...)
 	if err != nil {
 		return r.mapError(err)
 	}
@@ -218,27 +209,36 @@ func (r *libraryRepositoryWrapper) Update(id string, entity any, cols ...string)
 	// Restart watcher and trigger scan if path was updated
 	if pathChanged {
 		if r.watcher != nil {
-			if err := r.watcher.Watch(r.ctx, lib); err != nil {
-				log.Warn(r.ctx, "Failed to restart watcher for updated library", "libraryID", lib.ID, "name", lib.Name, "path", lib.Path, err)
+			if err := r.watcher.Watch(ctx, lib); err != nil {
+				log.Warn(ctx, "Failed to restart watcher for updated library", "libraryID", lib.ID, "name", lib.Name, "path", lib.Path, err)
 			}
 		}
 
 		if r.scanner != nil {
-			go r.triggerScan(lib, "updated")
+			go r.triggerScan(ctx, lib, "updated")
 		}
 	}
 
 	// Send library refresh event to all clients
 	if r.broker != nil {
 		event := &events.RefreshResource{}
-		r.broker.SendBroadcastMessage(r.ctx, event.With("library", id))
-		log.Debug(r.ctx, "Library updated - sent refresh event", "libraryID", libID, "name", lib.Name)
+		r.broker.SendBroadcastMessage(ctx, event.With("library", id))
+		log.Debug(ctx, "Library updated - sent refresh event", "libraryID", libID, "name", lib.Name)
 	}
 
 	return nil
 }
 
-func (r *libraryRepositoryWrapper) Delete(id string) error {
+func (r *libraryRepositoryWrapper) Delete(ctx context.Context, ids ...string) error {
+	for _, id := range ids {
+		if err := r.deleteOne(ctx, id); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (r *libraryRepositoryWrapper) deleteOne(ctx context.Context, id string) error {
 	libID, err := strconv.Atoi(id)
 	if err != nil {
 		return &rest.ValidationError{Errors: map[string]string{
@@ -247,7 +247,7 @@ func (r *libraryRepositoryWrapper) Delete(id string) error {
 	}
 
 	// Get library info before deletion for logging
-	lib, err := r.Get(libID)
+	lib, err := r.Get(ctx, libID)
 	if err != nil {
 		return r.mapError(err)
 	}
@@ -255,7 +255,7 @@ func (r *libraryRepositoryWrapper) Delete(id string) error {
 	// Run the deletion in a transaction so the cascade delete and the orphaned-artist
 	// reconciliation it triggers (see libraryRepository.Delete) commit atomically.
 	err = r.ds.WithTx(func(tx model.DataStore) error {
-		return tx.Library(r.ctx).Delete(libID)
+		return tx.Library().Delete(ctx, libID)
 	}, "delete library")
 	if err != nil {
 		return r.mapError(err)
@@ -263,25 +263,25 @@ func (r *libraryRepositoryWrapper) Delete(id string) error {
 
 	// Stop watcher and trigger scan after successful library deletion to clean up orphaned data
 	if r.watcher != nil {
-		if err := r.watcher.StopWatching(r.ctx, libID); err != nil {
-			log.Warn(r.ctx, "Failed to stop watcher for deleted library", "libraryID", libID, "name", lib.Name, "path", lib.Path, err)
+		if err := r.watcher.StopWatching(ctx, libID); err != nil {
+			log.Warn(ctx, "Failed to stop watcher for deleted library", "libraryID", libID, "name", lib.Name, "path", lib.Path, err)
 		}
 	}
 
 	if r.scanner != nil {
-		go r.triggerScan(lib, "deleted")
+		go r.triggerScan(ctx, lib, "deleted")
 	}
 
 	// Send library refresh event to all clients
 	if r.broker != nil {
 		event := &events.RefreshResource{}
-		r.broker.SendBroadcastMessage(r.ctx, event.With("library", id))
-		log.Debug(r.ctx, "Library deleted - sent refresh event", "libraryID", libID, "name", lib.Name)
+		r.broker.SendBroadcastMessage(ctx, event.With("library", id))
+		log.Debug(ctx, "Library deleted - sent refresh event", "libraryID", libID, "name", lib.Name)
 	}
 
 	// After successful deletion, check if any plugins were auto-disabled
 	// and need to be unloaded from memory
-	r.pluginManager.UnloadDisabledPlugins(r.ctx)
+	r.pluginManager.UnloadDisabledPlugins(ctx)
 
 	return nil
 }
@@ -309,7 +309,7 @@ func (r *libraryRepositoryWrapper) mapError(err error) error {
 	return err
 }
 
-func (r *libraryRepositoryWrapper) validateLibrary(library *model.Library) error {
+func (r *libraryRepositoryWrapper) validateLibrary(ctx context.Context, library *model.Library) error {
 	validationErrors := make(map[string]string)
 
 	if library.Name == "" {
@@ -320,7 +320,7 @@ func (r *libraryRepositoryWrapper) validateLibrary(library *model.Library) error
 		validationErrors["path"] = "ra.validation.required"
 	} else {
 		// Validate path format and accessibility
-		if err := r.validateLibraryPath(library); err != nil {
+		if err := r.validateLibraryPath(ctx, library); err != nil {
 			validationErrors["path"] = err.Error()
 		}
 	}
@@ -332,7 +332,7 @@ func (r *libraryRepositoryWrapper) validateLibrary(library *model.Library) error
 	return nil
 }
 
-func (r *libraryRepositoryWrapper) validateLibraryPath(library *model.Library) error {
+func (r *libraryRepositoryWrapper) validateLibraryPath(ctx context.Context, library *model.Library) error {
 	// Validate path format
 	if !filepath.IsAbs(library.Path) {
 		return fmt.Errorf("library path must be absolute")
@@ -350,7 +350,7 @@ func (r *libraryRepositoryWrapper) validateLibraryPath(library *model.Library) e
 
 	fsys, err := fileStore.FS()
 	if err != nil {
-		log.Warn(r.ctx, "Error validating library.path", "path", library.Path, err)
+		log.Warn(ctx, "Error validating library.path", "path", library.Path, err)
 		return fmt.Errorf("resources.library.validation.pathInvalid")
 	}
 
@@ -358,7 +358,7 @@ func (r *libraryRepositoryWrapper) validateLibraryPath(library *model.Library) e
 	info, err := fs.Stat(fsys, ".")
 	if err != nil {
 		// Parse the error message to check for "not a directory"
-		log.Warn(r.ctx, "Error stating library.path", "path", library.Path, err)
+		log.Warn(ctx, "Error stating library.path", "path", library.Path, err)
 		errStr := err.Error()
 		if strings.Contains(errStr, "not a directory") ||
 			strings.Contains(errStr, "The directory name is invalid.") {
@@ -385,7 +385,7 @@ func (s *libraryService) validateLibraryIDs(ctx context.Context, libraryIDs []in
 	}
 
 	// Use CountAll to efficiently validate library IDs exist
-	count, err := s.ds.Library(ctx).CountAll(model.QueryOptions{
+	count, err := s.ds.Library().CountAll(ctx, model.QueryOptions{
 		Filters: squirrel.Eq{"id": libraryIDs},
 	})
 	if err != nil {
@@ -399,13 +399,13 @@ func (s *libraryService) validateLibraryIDs(ctx context.Context, libraryIDs []in
 	return nil
 }
 
-func (r *libraryRepositoryWrapper) triggerScan(lib *model.Library, action string) {
-	log.Info(r.ctx, fmt.Sprintf("Triggering scan for %s library", action), "libraryID", lib.ID, "name", lib.Name, "path", lib.Path)
+func (r *libraryRepositoryWrapper) triggerScan(ctx context.Context, lib *model.Library, action string) {
+	log.Info(ctx, fmt.Sprintf("Triggering scan for %s library", action), "libraryID", lib.ID, "name", lib.Name, "path", lib.Path)
 	start := time.Now()
-	warnings, err := r.scanner.ScanAll(r.ctx, false) // Quick scan for new library
+	warnings, err := r.scanner.ScanAll(ctx, false) // Quick scan for new library
 	if err != nil {
-		log.Error(r.ctx, fmt.Sprintf("Error scanning %s library", action), "libraryID", lib.ID, "name", lib.Name, err)
+		log.Error(ctx, fmt.Sprintf("Error scanning %s library", action), "libraryID", lib.ID, "name", lib.Name, err)
 	} else {
-		log.Info(r.ctx, fmt.Sprintf("Scan completed for %s library", action), "libraryID", lib.ID, "name", lib.Name, "warnings", len(warnings), "elapsed", time.Since(start))
+		log.Info(ctx, fmt.Sprintf("Scan completed for %s library", action), "libraryID", lib.ID, "name", lib.Name, "warnings", len(warnings), "elapsed", time.Since(start))
 	}
 }
diff --git a/core/library_test.go b/core/library_test.go
index 43097414d..5402eac22 100644
--- a/core/library_test.go
+++ b/core/library_test.go
@@ -66,18 +66,18 @@ var _ = Describe("Library Service", func() {
 	})
 
 	Describe("Library CRUD Operations", func() {
-		var repo rest.Persistable
+		var repo rest.Persistable[model.Library]
 
 		BeforeEach(func() {
-			r := service.NewRepository(ctx)
-			repo = r.(rest.Persistable)
+			r := service.Repository()
+			repo = r.(rest.Persistable[model.Library])
 		})
 
 		Describe("Create", func() {
 			It("creates a new library successfully", func() {
 				library := &model.Library{ID: 1, Name: "New Library", Path: tempDir}
 
-				_, err := repo.Save(library)
+				_, err := repo.Save(ctx, library)
 
 				Expect(err).NotTo(HaveOccurred())
 				Expect(libraryRepo.Data[1].Name).To(Equal("New Library"))
@@ -87,7 +87,7 @@ var _ = Describe("Library Service", func() {
 			It("fails when library name is empty", func() {
 				library := &model.Library{Path: tempDir}
 
-				_, err := repo.Save(library)
+				_, err := repo.Save(ctx, library)
 
 				Expect(err).To(HaveOccurred())
 				Expect(err.Error()).To(ContainSubstring("ra.validation.required"))
@@ -96,7 +96,7 @@ var _ = Describe("Library Service", func() {
 			It("fails when library path is empty", func() {
 				library := &model.Library{Name: "Test"}
 
-				_, err := repo.Save(library)
+				_, err := repo.Save(ctx, library)
 
 				Expect(err).To(HaveOccurred())
 				Expect(err.Error()).To(ContainSubstring("ra.validation.required"))
@@ -105,7 +105,7 @@ var _ = Describe("Library Service", func() {
 			It("fails when library path is not absolute", func() {
 				library := &model.Library{Name: "Test", Path: "relative/path"}
 
-				_, err := repo.Save(library)
+				_, err := repo.Save(ctx, library)
 
 				Expect(err).To(HaveOccurred())
 				var validationErr *rest.ValidationError
@@ -140,7 +140,7 @@ var _ = Describe("Library Service", func() {
 						return errors.New("UNIQUE constraint failed: library.name")
 					}
 
-					_, err = repo.Save(library)
+					_, err = repo.Save(ctx, library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -157,7 +157,7 @@ var _ = Describe("Library Service", func() {
 						return errors.New("UNIQUE constraint failed: library.path")
 					}
 
-					_, err := repo.Save(library)
+					_, err := repo.Save(ctx, library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -181,7 +181,7 @@ var _ = Describe("Library Service", func() {
 
 				library := &model.Library{ID: 1, Name: "Updated Library", Path: newTempDir}
 
-				err = repo.Update("1", library)
+				err = repo.Update(ctx, "1", *library)
 
 				Expect(err).NotTo(HaveOccurred())
 				Expect(libraryRepo.Data[1].Name).To(Equal("Updated Library"))
@@ -191,7 +191,7 @@ var _ = Describe("Library Service", func() {
 			It("forwards the columns sent by the client to the repository", func() {
 				library := &model.Library{ID: 1, Name: "Updated Library", Path: tempDir}
 
-				err := repo.Update("1", library, "name", "path")
+				err := repo.Update(ctx, "1", *library, "name", "path")
 
 				Expect(err).NotTo(HaveOccurred())
 				Expect(libraryRepo.PutCols).To(Equal([]string{"name", "path"}))
@@ -205,7 +205,7 @@ var _ = Describe("Library Service", func() {
 
 				library := &model.Library{ID: 999, Name: "Non-existent", Path: uniqueTempDir}
 
-				err = repo.Update("999", library)
+				err = repo.Update(ctx, "999", *library)
 
 				Expect(err).To(HaveOccurred())
 				Expect(err).To(Equal(model.ErrNotFound))
@@ -214,7 +214,7 @@ var _ = Describe("Library Service", func() {
 			It("fails when library name is empty", func() {
 				library := &model.Library{ID: 1, Path: tempDir}
 
-				err := repo.Update("1", library)
+				err := repo.Update(ctx, "1", *library)
 
 				Expect(err).To(HaveOccurred())
 				Expect(err.Error()).To(ContainSubstring("ra.validation.required"))
@@ -224,7 +224,7 @@ var _ = Describe("Library Service", func() {
 				unnormalizedPath := tempDir + "//../" + filepath.Base(tempDir)
 				library := &model.Library{ID: 1, Name: "Updated Library", Path: unnormalizedPath}
 
-				err := repo.Update("1", library)
+				err := repo.Update(ctx, "1", *library)
 
 				Expect(err).NotTo(HaveOccurred())
 				Expect(libraryRepo.Data[1].Path).To(Equal(filepath.Clean(unnormalizedPath)))
@@ -239,7 +239,7 @@ var _ = Describe("Library Service", func() {
 				// Update the library keeping the same name (should be allowed)
 				library := &model.Library{ID: 1, Name: "Test Library", Path: tempDir}
 
-				err := repo.Update("1", library)
+				err := repo.Update(ctx, "1", *library)
 
 				Expect(err).NotTo(HaveOccurred())
 			})
@@ -253,7 +253,7 @@ var _ = Describe("Library Service", func() {
 				// Update the library keeping the same path (should be allowed)
 				library := &model.Library{ID: 1, Name: "Test Library", Path: tempDir}
 
-				err := repo.Update("1", library)
+				err := repo.Update(ctx, "1", *library)
 
 				Expect(err).NotTo(HaveOccurred())
 			})
@@ -284,7 +284,7 @@ var _ = Describe("Library Service", func() {
 					// Try to update library 2 to have the same name as library 1
 					library := &model.Library{ID: 2, Name: "Library One", Path: otherTempDir}
 
-					err = repo.Update("2", library)
+					err = repo.Update(ctx, "2", *library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -312,7 +312,7 @@ var _ = Describe("Library Service", func() {
 					// Try to update library 2 to have the same path as library 1
 					library := &model.Library{ID: 2, Name: "Library Two", Path: tempDir}
 
-					err = repo.Update("2", library)
+					err = repo.Update(ctx, "2", *library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -327,7 +327,7 @@ var _ = Describe("Library Service", func() {
 				It("fails when path is not absolute", func() {
 					library := &model.Library{Name: "Test", Path: "relative/path"}
 
-					_, err := repo.Save(library)
+					_, err := repo.Save(ctx, library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -339,7 +339,7 @@ var _ = Describe("Library Service", func() {
 					nonExistentPath := filepath.Join(tempDir, "nonexistent")
 					library := &model.Library{Name: "Test", Path: nonExistentPath}
 
-					_, err := repo.Save(library)
+					_, err := repo.Save(ctx, library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -354,7 +354,7 @@ var _ = Describe("Library Service", func() {
 
 					library := &model.Library{Name: "Test", Path: testFile}
 
-					_, err = repo.Save(library)
+					_, err = repo.Save(ctx, library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -371,7 +371,7 @@ var _ = Describe("Library Service", func() {
 				It("handles multiple validation errors", func() {
 					library := &model.Library{Name: "", Path: "relative/path"}
 
-					_, err := repo.Save(library)
+					_, err := repo.Save(ctx, library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -393,7 +393,7 @@ var _ = Describe("Library Service", func() {
 				It("fails when updated path is not absolute", func() {
 					library := &model.Library{ID: 1, Name: "Test", Path: "relative/path"}
 
-					err := repo.Update("1", library)
+					err := repo.Update(ctx, "1", *library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -410,7 +410,7 @@ var _ = Describe("Library Service", func() {
 					// Update the library keeping the same name (should be allowed)
 					library := &model.Library{ID: 1, Name: "Test Library", Path: tempDir}
 
-					err := repo.Update("1", library)
+					err := repo.Update(ctx, "1", *library)
 
 					Expect(err).NotTo(HaveOccurred())
 				})
@@ -419,7 +419,7 @@ var _ = Describe("Library Service", func() {
 					nonExistentPath := filepath.Join(tempDir, "nonexistent")
 					library := &model.Library{ID: 1, Name: "Test", Path: nonExistentPath}
 
-					err := repo.Update("1", library)
+					err := repo.Update(ctx, "1", *library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -434,7 +434,7 @@ var _ = Describe("Library Service", func() {
 
 					library := &model.Library{ID: 1, Name: "Test", Path: testFile}
 
-					err = repo.Update("1", library)
+					err = repo.Update(ctx, "1", *library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -446,7 +446,7 @@ var _ = Describe("Library Service", func() {
 					// Try to update with empty name and invalid path
 					library := &model.Library{ID: 1, Name: "", Path: "relative/path"}
 
-					err := repo.Update("1", library)
+					err := repo.Update(ctx, "1", *library)
 
 					Expect(err).To(HaveOccurred())
 					var validationErr *rest.ValidationError
@@ -467,14 +467,14 @@ var _ = Describe("Library Service", func() {
 			})
 
 			It("deletes an existing library successfully", func() {
-				err := repo.Delete("1")
+				err := repo.Delete(ctx, "1")
 
 				Expect(err).NotTo(HaveOccurred())
 				Expect(libraryRepo.Data).To(HaveLen(0))
 			})
 
 			It("fails when library doesn't exist", func() {
-				err := repo.Delete("999")
+				err := repo.Delete(ctx, "999")
 
 				Expect(err).To(HaveOccurred())
 				Expect(err).To(Equal(model.ErrNotFound))
@@ -613,17 +613,17 @@ var _ = Describe("Library Service", func() {
 	})
 
 	Describe("Scan Triggering", func() {
-		var repo rest.Persistable
+		var repo rest.Persistable[model.Library]
 
 		BeforeEach(func() {
-			r := service.NewRepository(ctx)
-			repo = r.(rest.Persistable)
+			r := service.Repository()
+			repo = r.(rest.Persistable[model.Library])
 		})
 
 		It("triggers scan when creating a new library", func() {
 			library := &model.Library{ID: 1, Name: "New Library", Path: tempDir}
 
-			_, err := repo.Save(library)
+			_, err := repo.Save(ctx, library)
 			Expect(err).NotTo(HaveOccurred())
 
 			// Wait briefly for the goroutine to complete
@@ -649,7 +649,7 @@ var _ = Describe("Library Service", func() {
 
 			// Update the library with a new path
 			library := &model.Library{ID: 1, Name: "Updated Library", Path: newTempDir}
-			err = repo.Update("1", library)
+			err = repo.Update(ctx, "1", *library)
 			Expect(err).NotTo(HaveOccurred())
 
 			// Wait briefly for the goroutine to complete
@@ -670,7 +670,7 @@ var _ = Describe("Library Service", func() {
 
 			// Update the library name only (same path)
 			library := &model.Library{ID: 1, Name: "Updated Name", Path: tempDir}
-			err := repo.Update("1", library)
+			err := repo.Update(ctx, "1", *library)
 			Expect(err).NotTo(HaveOccurred())
 
 			// Wait a bit to ensure no scan was triggered
@@ -683,7 +683,7 @@ var _ = Describe("Library Service", func() {
 			// Try to create library with invalid data (empty name)
 			library := &model.Library{Path: tempDir}
 
-			_, err := repo.Save(library)
+			_, err := repo.Save(ctx, library)
 			Expect(err).To(HaveOccurred())
 
 			// Ensure no scan was triggered since creation failed
@@ -700,7 +700,7 @@ var _ = Describe("Library Service", func() {
 
 			// Try to update with invalid data (empty name)
 			library := &model.Library{ID: 1, Name: "", Path: tempDir}
-			err := repo.Update("1", library)
+			err := repo.Update(ctx, "1", *library)
 			Expect(err).To(HaveOccurred())
 
 			// Ensure no scan was triggered since update failed
@@ -716,7 +716,7 @@ var _ = Describe("Library Service", func() {
 			})
 
 			// Delete the library
-			err := repo.Delete("1")
+			err := repo.Delete(ctx, "1")
 			Expect(err).NotTo(HaveOccurred())
 
 			// Wait briefly for the goroutine to complete
@@ -731,7 +731,7 @@ var _ = Describe("Library Service", func() {
 
 		It("does not trigger scan when library deletion fails", func() {
 			// Try to delete a non-existent library
-			err := repo.Delete("999")
+			err := repo.Delete(ctx, "999")
 			Expect(err).To(HaveOccurred())
 
 			// Ensure no scan was triggered since deletion failed
@@ -744,7 +744,7 @@ var _ = Describe("Library Service", func() {
 			It("starts watcher when creating a new library", func() {
 				library := &model.Library{ID: 1, Name: "New Library", Path: tempDir}
 
-				_, err := repo.Save(library)
+				_, err := repo.Save(ctx, library)
 				Expect(err).NotTo(HaveOccurred())
 
 				// Verify watcher was started
@@ -773,7 +773,7 @@ var _ = Describe("Library Service", func() {
 
 				// Update library with new path
 				library := &model.Library{ID: 1, Name: "Updated Library", Path: newTempDir}
-				err = repo.Update("1", library)
+				err = repo.Update(ctx, "1", *library)
 				Expect(err).NotTo(HaveOccurred())
 
 				// Verify watcher was restarted
@@ -793,7 +793,7 @@ var _ = Describe("Library Service", func() {
 
 				// Update library with same path but different name
 				library := &model.Library{ID: 1, Name: "Updated Name", Path: tempDir}
-				err := repo.Update("1", library)
+				err := repo.Update(ctx, "1", *library)
 				Expect(err).NotTo(HaveOccurred())
 
 				// Verify watcher was NOT restarted (since path didn't change)
@@ -808,7 +808,7 @@ var _ = Describe("Library Service", func() {
 					{ID: 1, Name: "Test Library", Path: tempDir},
 				})
 
-				err := repo.Delete("1")
+				err := repo.Delete(ctx, "1")
 				Expect(err).NotTo(HaveOccurred())
 
 				// Verify watcher was stopped
@@ -826,7 +826,7 @@ var _ = Describe("Library Service", func() {
 				})
 
 				// Mock deletion to fail by trying to delete non-existent library
-				err := repo.Delete("999")
+				err := repo.Delete(ctx, "999")
 				Expect(err).To(HaveOccurred())
 
 				// Verify watcher was NOT stopped since deletion failed
@@ -838,11 +838,11 @@ var _ = Describe("Library Service", func() {
 	})
 
 	Describe("Event Broadcasting", func() {
-		var repo rest.Persistable
+		var repo rest.Persistable[model.Library]
 
 		BeforeEach(func() {
-			r := service.NewRepository(ctx)
-			repo = r.(rest.Persistable)
+			r := service.Repository()
+			repo = r.(rest.Persistable[model.Library])
 			// Clear any events from broker
 			broker.Events = []events.Event{}
 		})
@@ -850,7 +850,7 @@ var _ = Describe("Library Service", func() {
 		It("sends refresh event when creating a library", func() {
 			library := &model.Library{ID: 1, Name: "New Library", Path: tempDir}
 
-			_, err := repo.Save(library)
+			_, err := repo.Save(ctx, library)
 
 			Expect(err).NotTo(HaveOccurred())
 			Expect(broker.Events).To(HaveLen(1))
@@ -863,7 +863,7 @@ var _ = Describe("Library Service", func() {
 			})
 
 			library := &model.Library{ID: 1, Name: "Updated Library", Path: tempDir}
-			err := repo.Update("1", library)
+			err := repo.Update(ctx, "1", *library)
 
 			Expect(err).NotTo(HaveOccurred())
 			Expect(broker.Events).To(HaveLen(1))
@@ -875,7 +875,7 @@ var _ = Describe("Library Service", func() {
 				{ID: 2, Name: "Library to Delete", Path: tempDir},
 			})
 
-			err := repo.Delete("2")
+			err := repo.Delete(ctx, "2")
 
 			Expect(err).NotTo(HaveOccurred())
 			Expect(broker.Events).To(HaveLen(1))
@@ -883,13 +883,13 @@ var _ = Describe("Library Service", func() {
 	})
 
 	Describe("Plugin Manager Integration", func() {
-		var repo rest.Persistable
+		var repo rest.Persistable[model.Library]
 
 		BeforeEach(func() {
 			// Reset the call count for each test
 			pluginManager.unloadCalls = 0
-			r := service.NewRepository(ctx)
-			repo = r.(rest.Persistable)
+			r := service.Repository()
+			repo = r.(rest.Persistable[model.Library])
 		})
 
 		It("calls UnloadDisabledPlugins after successful library deletion", func() {
@@ -897,14 +897,14 @@ var _ = Describe("Library Service", func() {
 				{ID: 2, Name: "Library to Delete", Path: tempDir},
 			})
 
-			err := repo.Delete("2")
+			err := repo.Delete(ctx, "2")
 			Expect(err).NotTo(HaveOccurred())
 			Expect(pluginManager.unloadCalls).To(Equal(1))
 		})
 
 		It("does not call UnloadDisabledPlugins when library deletion fails", func() {
 			// Try to delete non-existent library
-			err := repo.Delete("999")
+			err := repo.Delete(ctx, "999")
 			Expect(err).To(HaveOccurred())
 			Expect(pluginManager.unloadCalls).To(Equal(0))
 		})
diff --git a/core/lyrics/lyrics.go b/core/lyrics/lyrics.go
index b9fb8cb74..d3e8d72b8 100644
--- a/core/lyrics/lyrics.go
+++ b/core/lyrics/lyrics.go
@@ -57,7 +57,7 @@ func (l *lyricsService) GetLyrics(ctx context.Context, mf *model.MediaFile) (mod
 func (l *lyricsService) GetLyricsByArtistTitle(ctx context.Context, artist, title string) (model.LyricList, error) {
 	opts := songsByArtistTitleWithLyricsFirst(artist, title)
 	opts.Max = maxLegacyLyricsCandidates
-	mediaFiles, err := l.ds.MediaFile(ctx).GetAll(opts)
+	mediaFiles, err := l.ds.MediaFile().GetAll(ctx, opts)
 	if err != nil {
 		return nil, err
 	}
diff --git a/core/maintenance.go b/core/maintenance.go
index 56c0ac18d..58265ea2c 100644
--- a/core/maintenance.go
+++ b/core/maintenance.go
@@ -58,7 +58,7 @@ func (s *maintenanceService) RemapMissingFile(ctx context.Context, missingID, ta
 		return fmt.Errorf("%w: %q", ErrSameFile, missingID)
 	}
 
-	missing, err := s.ds.MediaFile(ctx).Get(missingID)
+	missing, err := s.ds.MediaFile().Get(ctx, missingID)
 	if err != nil {
 		return fmt.Errorf("loading missing file %q: %w", missingID, err)
 	}
@@ -66,7 +66,7 @@ func (s *maintenanceService) RemapMissingFile(ctx context.Context, missingID, ta
 		return fmt.Errorf("%w: %q", ErrNotMissing, missingID)
 	}
 
-	target, err := s.ds.MediaFile(ctx).GetWithParticipants(targetID)
+	target, err := s.ds.MediaFile().GetWithParticipants(ctx, targetID)
 	if err != nil {
 		return fmt.Errorf("loading target file %q: %w", targetID, err)
 	}
@@ -82,27 +82,27 @@ func (s *maintenanceService) RemapMissingFile(ctx context.Context, missingID, ta
 		// Preserve the original created_at so the remapped track doesn't resurface in "Recently Added"
 		target.CreatedAt = missing.CreatedAt
 		target.ID = missing.ID
-		if err := tx.MediaFile(ctx).Put(target); err != nil {
+		if err := tx.MediaFile().Put(ctx, target); err != nil {
 			return fmt.Errorf("update matched track: %w", err)
 		}
 		// Unlike the scanner's freshly-imported target, this one may carry history of its own
-		if err := tx.MediaFile(ctx).ReassignReferences(discardedID, missing.ID); err != nil {
+		if err := tx.MediaFile().ReassignReferences(ctx, discardedID, missing.ID); err != nil {
 			return fmt.Errorf("reassign target references: %w", err)
 		}
-		if err := tx.MediaFile(ctx).Delete(discardedID); err != nil {
+		if err := tx.MediaFile().Delete(ctx, discardedID); err != nil {
 			return fmt.Errorf("delete discarded track: %w", err)
 		}
 
 		if oldAlbumID != newAlbumID {
-			oldAlbumTracks, err := tx.MediaFile(ctx).CountAll(model.QueryOptions{Filters: squirrel.Eq{"album_id": oldAlbumID}})
+			oldAlbumTracks, err := tx.MediaFile().CountAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"album_id": oldAlbumID}})
 			if err != nil {
 				return fmt.Errorf("get old album tracks: %w", err)
 			}
 			if oldAlbumTracks == 0 {
-				if err := tx.Album(ctx).ReassignAnnotation(oldAlbumID, newAlbumID); err != nil {
+				if err := tx.Album().ReassignAnnotation(ctx, oldAlbumID, newAlbumID); err != nil {
 					return fmt.Errorf("reassign album annotations: %w", err)
 				}
-				if err := tx.Album(ctx).CopyAttributes(oldAlbumID, newAlbumID, "created_at"); err != nil && !errors.Is(err, model.ErrNotFound) {
+				if err := tx.Album().CopyAttributes(ctx, oldAlbumID, newAlbumID, "created_at"); err != nil && !errors.Is(err, model.ErrNotFound) {
 					return fmt.Errorf("copy album attributes: %w", err)
 				}
 			}
@@ -121,7 +121,7 @@ func (s *maintenanceService) RemapMissingFile(ctx context.Context, missingID, ta
 
 	// Stats are refreshed synchronously, unlike deleteMissing, so the CLI sees them before it exits.
 	// album/artist play count aggregates are not recalculated here; they are refreshed by the next scan.
-	if _, err := s.ds.Artist(ctx).RefreshStats(true); err != nil {
+	if _, err := s.ds.Artist().RefreshStats(ctx, true); err != nil {
 		log.Error(ctx, "Error refreshing artist stats after remapping missing file", err)
 	}
 	affectedAlbumIDs := []string{newAlbumID}
@@ -146,10 +146,10 @@ func (s *maintenanceService) deleteMissing(ctx context.Context, ids []string) er
 	// Delete missing files within a transaction
 	err = s.ds.WithTx(func(tx model.DataStore) error {
 		if len(ids) == 0 {
-			_, err := tx.MediaFile(ctx).DeleteAllMissing()
+			_, err := tx.MediaFile().DeleteAllMissing(ctx)
 			return err
 		}
-		return tx.MediaFile(ctx).DeleteMissing(ids)
+		return tx.MediaFile().DeleteMissing(ctx, ids)
 	})
 	if err != nil {
 		log.Error(ctx, "Error deleting missing tracks from DB", "ids", ids, err)
@@ -192,11 +192,11 @@ func (s *maintenanceService) refreshAlbums(ctx context.Context, albumIDs []strin
 
 // refreshAlbumChunk processes a single chunk of album IDs
 func (s *maintenanceService) refreshAlbumChunk(ctx context.Context, albumIDs []string) error {
-	albumRepo := s.ds.Album(ctx)
-	mfRepo := s.ds.MediaFile(ctx)
+	albumRepo := s.ds.Album()
+	mfRepo := s.ds.MediaFile()
 
 	// Batch load existing albums
-	albums, err := albumRepo.GetAll(model.QueryOptions{
+	albums, err := albumRepo.GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.Eq{"album.id": albumIDs},
 	})
 	if err != nil {
@@ -210,7 +210,7 @@ func (s *maintenanceService) refreshAlbumChunk(ctx context.Context, albumIDs []s
 	}
 
 	// Batch load all media files for these albums
-	mediaFiles, err := mfRepo.GetAll(model.QueryOptions{
+	mediaFiles, err := mfRepo.GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.Eq{"album_id": albumIDs},
 		Sort:    "album_id, path",
 	})
@@ -243,7 +243,7 @@ func (s *maintenanceService) refreshAlbumChunk(ctx context.Context, albumIDs []s
 			newAlbum.UpdatedAt = time.Now()
 			newAlbum.CreatedAt = oldAlbum.CreatedAt
 
-			if err := albumRepo.Put(&newAlbum); err != nil {
+			if err := albumRepo.Put(ctx, &newAlbum); err != nil {
 				log.Error(ctx, "Error updating album during refresh", "albumID", albumID, err)
 				// Continue with other albums instead of failing entirely
 				continue
@@ -265,7 +265,7 @@ func (s *maintenanceService) getAffectedAlbumIDs(ctx context.Context, ids []stri
 		}
 	}
 
-	mfs, err := s.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	mfs, err := s.ds.MediaFile().GetAll(ctx, model.QueryOptions{
 		Filters: filters,
 	})
 	if err != nil {
@@ -293,7 +293,7 @@ func (s *maintenanceService) refreshStatsAsync(ctx context.Context, affectedAlbu
 	// Refresh artist stats in background
 	s.wg.Go(func() {
 		bgCtx := request.AddValues(context.Background(), ctx)
-		if _, err := s.ds.Artist(bgCtx).RefreshStats(true); err != nil {
+		if _, err := s.ds.Artist().RefreshStats(bgCtx, true); err != nil {
 			log.Error(bgCtx, "Error refreshing artist stats after deleting missing files", err)
 		} else {
 			log.Debug(bgCtx, "Successfully refreshed artist stats after deleting missing files")
diff --git a/core/maintenance_test.go b/core/maintenance_test.go
index 56e6d13b5..4ffc098d9 100644
--- a/core/maintenance_test.go
+++ b/core/maintenance_test.go
@@ -262,12 +262,12 @@ var _ = Describe("Maintenance", func() {
 
 			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
 
-			got, err := mfRepo.Get("m1")
+			got, err := mfRepo.Get(ctx, "m1")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Path).To(Equal("new/song.mp3")) // moved to target's location
 			Expect(got.Missing).To(BeFalse())
 			Expect(got.CreatedAt).To(BeTemporally("==", created)) // created_at preserved
-			exists, _ := mfRepo.Exists("t1")
+			exists, _ := mfRepo.Exists(ctx, "t1")
 			Expect(exists).To(BeFalse()) // discarded row removed
 			Expect(ds.GCCalled).To(BeTrue())
 		})
@@ -369,14 +369,14 @@ var _ = Describe("Maintenance", func() {
 			Expect(artistRepo.IsRefreshStatsCalled()).To(BeTrue(), "Artist stats should be refreshed")
 
 			// The old album lost the remapped track, so its stats are recalculated from the remaining one
-			oldAlbum, err := albumRepo.Get("album1")
+			oldAlbum, err := albumRepo.Get(ctx, "album1")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(oldAlbum.SongCount).To(Equal(1))
 			Expect(oldAlbum.Size).To(Equal(int64(1000)))
 			Expect(oldAlbum.Duration).To(BeNumerically("==", 100))
 
 			// The target album keeps the track, now under the missing file's ID
-			newAlbum, err := albumRepo.Get("album2")
+			newAlbum, err := albumRepo.Get(ctx, "album2")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(newAlbum.SongCount).To(Equal(1))
 			Expect(newAlbum.Size).To(Equal(int64(2000)))
@@ -407,7 +407,7 @@ var _ = Describe("Maintenance", func() {
 			Expect(service.RemapMissingFile(ctx, "m1", "t1")).To(Succeed())
 
 			// The surviving row is the missing file's ID, holding the target's data
-			got, err := mfRepo.GetWithParticipants("m1")
+			got, err := mfRepo.GetWithParticipants(ctx, "m1")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Participants).To(HaveKeyWithValue(model.RoleArtist, model.ParticipantList{participant}))
 		})
@@ -447,7 +447,7 @@ type extendedMediaFileRepo struct {
 	deleteMissingError  error
 }
 
-func (m *extendedMediaFileRepo) DeleteMissing(ids []string) error {
+func (m *extendedMediaFileRepo) DeleteMissing(ctx context.Context, ids []string) error {
 	m.deleteMissingCalled = true
 	m.deletedIDs = ids
 	if m.deleteMissingError != nil {
@@ -470,7 +470,7 @@ type extendedAlbumRepo struct {
 	failOnce     bool
 }
 
-func (m *extendedAlbumRepo) Put(album *model.Album) error {
+func (m *extendedAlbumRepo) Put(ctx context.Context, album *model.Album) error {
 	m.mu.Lock()
 	m.putCallCount++
 	m.lastPutData = album
@@ -490,7 +490,7 @@ func (m *extendedAlbumRepo) Put(album *model.Album) error {
 	}
 	m.mu.Unlock()
 
-	return m.MockAlbumRepo.Put(album)
+	return m.MockAlbumRepo.Put(ctx, album)
 }
 
 func (m *extendedAlbumRepo) GetPutCallCount() int {
@@ -507,7 +507,7 @@ type extendedArtistRepo struct {
 	refreshStatsError  error
 }
 
-func (m *extendedArtistRepo) RefreshStats(allArtists bool) (int64, error) {
+func (m *extendedArtistRepo) RefreshStats(ctx context.Context, allArtists bool) (int64, error) {
 	m.mu.Lock()
 	m.refreshStatsCalled = true
 	err := m.refreshStatsError
@@ -516,7 +516,7 @@ func (m *extendedArtistRepo) RefreshStats(allArtists bool) (int64, error) {
 	if err != nil {
 		return 0, err
 	}
-	return m.MockArtistRepo.RefreshStats(allArtists)
+	return m.MockArtistRepo.RefreshStats(ctx, allArtists)
 }
 
 func (m *extendedArtistRepo) IsRefreshStatsCalled() bool {
diff --git a/core/matcher/matcher.go b/core/matcher/matcher.go
index 25b8fda5f..3eb4db152 100644
--- a/core/matcher/matcher.go
+++ b/core/matcher/matcher.go
@@ -95,7 +95,7 @@ func (m *Matcher) matchByID(ctx context.Context, songs []agents.Song, result map
 	if len(ids) == 0 {
 		return nil
 	}
-	res, err := m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	res, err := m.ds.MediaFile().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.And{
 			squirrel.Eq{"media_file.id": ids},
 			squirrel.Eq{"missing": false},
@@ -134,7 +134,7 @@ func (m *Matcher) matchByMBID(ctx context.Context, songs []agents.Song, result m
 	if len(mbids) == 0 {
 		return nil
 	}
-	res, err := m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	res, err := m.ds.MediaFile().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.And{
 			squirrel.Eq{"mbz_recording_id": mbids},
 			squirrel.Eq{"missing": false},
@@ -180,7 +180,7 @@ func (m *Matcher) matchByISRC(ctx context.Context, songs []agents.Song, result m
 	if len(isrcs) == 0 {
 		return nil
 	}
-	res, err := m.ds.MediaFile(ctx).GetAllByTags(model.TagISRC, isrcs, model.QueryOptions{
+	res, err := m.ds.MediaFile().GetAllByTags(ctx, model.TagISRC, isrcs, model.QueryOptions{
 		Filters: squirrel.Eq{"missing": false},
 		Sort:    "starred desc, rating desc, year asc, compilation asc",
 	})
@@ -442,7 +442,7 @@ func (m *Matcher) resolveArtists(ctx context.Context, queries []indexedQuery) (r
 		filter = append(filter, squirrel.Eq{"id": slices.Collect(maps.Keys(allIDs))})
 	}
 	if len(filter) > 0 {
-		artists, err := m.ds.Artist(ctx).GetAll(model.QueryOptions{Filters: filter})
+		artists, err := m.ds.Artist().GetAll(ctx, model.QueryOptions{Filters: filter})
 		if err != nil {
 			return resolvedArtists{}, err
 		}
@@ -543,7 +543,7 @@ func (m *Matcher) fetchTracksCreditedTo(ctx context.Context, artistIDs []string)
 		return nil, nil
 	}
 	args := slice.Map(artistIDs, func(id string) any { return id })
-	return m.ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	return m.ds.MediaFile().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.And{
 			squirrel.Expr(
 				"media_file.id IN (SELECT media_file_id FROM media_file_artists "+
diff --git a/core/matcher/matcher_test.go b/core/matcher/matcher_test.go
index a46db8a09..0f5389ca5 100644
--- a/core/matcher/matcher_test.go
+++ b/core/matcher/matcher_test.go
@@ -1267,7 +1267,7 @@ func newMockMediaFileRepo() *mockMediaFileRepo {
 	return &mockMediaFileRepo{}
 }
 
-func (m *mockMediaFileRepo) GetAll(options ...model.QueryOptions) (model.MediaFiles, error) {
+func (m *mockMediaFileRepo) GetAll(ctx context.Context, options ...model.QueryOptions) (model.MediaFiles, error) {
 	argsSlice := make([]any, len(options))
 	for i, v := range options {
 		argsSlice[i] = v
@@ -1279,8 +1279,8 @@ func (m *mockMediaFileRepo) GetAll(options ...model.QueryOptions) (model.MediaFi
 	return args.Get(0).(model.MediaFiles), args.Error(1)
 }
 
-func (m *mockMediaFileRepo) GetAllByTags(_ model.TagName, _ []string, options ...model.QueryOptions) (model.MediaFiles, error) {
-	return m.GetAll(options...)
+func (m *mockMediaFileRepo) GetAllByTags(ctx context.Context, _ model.TagName, _ []string, options ...model.QueryOptions) (model.MediaFiles, error) {
+	return m.GetAll(ctx, options...)
 }
 
 func (m *mockMediaFileRepo) SetError(hasError bool) {
@@ -1298,7 +1298,7 @@ func newMockArtistRepo() *mockArtistRepo {
 	return &mockArtistRepo{}
 }
 
-func (m *mockArtistRepo) GetAll(options ...model.QueryOptions) (model.Artists, error) {
+func (m *mockArtistRepo) GetAll(_ context.Context, options ...model.QueryOptions) (model.Artists, error) {
 	argsSlice := make([]any, len(options))
 	for i, v := range options {
 		argsSlice[i] = v
diff --git a/core/metrics/insights.go b/core/metrics/insights.go
index d952f517a..4a78a7f3f 100644
--- a/core/metrics/insights.go
+++ b/core/metrics/insights.go
@@ -47,11 +47,11 @@ type insightsCollector struct {
 
 func GetInstance(ds model.DataStore) Insights {
 	return singleton.GetInstance(func() *insightsCollector {
-		id, err := ds.Property(context.TODO()).Get(consts.InsightsIDKey)
+		id, err := ds.Property().Get(context.TODO(), consts.InsightsIDKey)
 		if err != nil {
 			log.Trace("Could not get Insights ID from DB. Creating one", err)
 			id = uuid.NewString()
-			err = ds.Property(context.TODO()).Put(consts.InsightsIDKey, id)
+			err = ds.Property().Put(context.TODO(), consts.InsightsIDKey, id)
 			if err != nil {
 				log.Trace("Could not save Insights ID to DB", err)
 			}
@@ -87,7 +87,7 @@ func (c *insightsCollector) LastRun(context.Context) (timestamp time.Time, succe
 }
 
 func (c *insightsCollector) sendInsights(ctx context.Context) {
-	count, err := c.ds.User(ctx).CountAll(model.QueryOptions{})
+	count, err := c.ds.User().CountAll(ctx, model.QueryOptions{})
 	if err != nil {
 		log.Trace(ctx, "Could not check user count", err)
 		return
@@ -245,41 +245,41 @@ func (c *insightsCollector) collect(ctx context.Context) []byte {
 
 	// Library info
 	var err error
-	data.Library.Tracks, err = c.ds.MediaFile(ctx).CountAll()
+	data.Library.Tracks, err = c.ds.MediaFile().CountAll(ctx)
 	if err != nil {
 		log.Trace(ctx, "Error reading tracks count", err)
 	}
-	data.Library.Albums, err = c.ds.Album(ctx).CountAll()
+	data.Library.Albums, err = c.ds.Album().CountAll(ctx)
 	if err != nil {
 		log.Trace(ctx, "Error reading albums count", err)
 	}
-	data.Library.Artists, err = c.ds.Artist(ctx).CountAll()
+	data.Library.Artists, err = c.ds.Artist().CountAll(ctx)
 	if err != nil {
 		log.Trace(ctx, "Error reading artists count", err)
 	}
-	data.Library.Playlists, err = c.ds.Playlist(ctx).CountAll()
+	data.Library.Playlists, err = c.ds.Playlist().CountAll(ctx)
 	if err != nil {
 		log.Trace(ctx, "Error reading playlists count", err)
 	}
-	data.Library.Shares, err = c.ds.Share(ctx).CountAll()
+	data.Library.Shares, err = c.ds.Share().CountAll(ctx)
 	if err != nil {
 		log.Trace(ctx, "Error reading shares count", err)
 	}
-	data.Library.Radios, err = c.ds.Radio(ctx).Count()
+	data.Library.Radios, err = c.ds.Radio().CountAll(ctx)
 	if err != nil {
 		log.Trace(ctx, "Error reading radios count", err)
 	}
-	data.Library.Libraries, err = c.ds.Library(ctx).CountAll()
+	data.Library.Libraries, err = c.ds.Library().CountAll(ctx)
 	if err != nil {
 		log.Trace(ctx, "Error reading libraries count", err)
 	}
-	data.Library.ActiveUsers, err = c.ds.User(ctx).CountAll(model.QueryOptions{
+	data.Library.ActiveUsers, err = c.ds.User().CountAll(ctx, model.QueryOptions{
 		Filters: squirrel.Gt{"last_access_at": time.Now().Add(-7 * 24 * time.Hour)},
 	})
 	if err != nil {
 		log.Trace(ctx, "Error reading active users count", err)
 	}
-	data.Library.FileSuffixes, err = c.ds.MediaFile(ctx).CountBySuffix()
+	data.Library.FileSuffixes, err = c.ds.MediaFile().CountBySuffix(ctx)
 	if err != nil {
 		log.Trace(ctx, "Error reading file suffixes count", err)
 	}
@@ -297,7 +297,7 @@ func (c *insightsCollector) collect(ctx context.Context) []byte {
 
 	// Collect active players if permitted
 	if conf.Server.DevEnablePlayerInsights {
-		data.Library.ActivePlayers, err = c.ds.Player(ctx).CountByClient(model.QueryOptions{
+		data.Library.ActivePlayers, err = c.ds.Player().CountByClient(ctx, model.QueryOptions{
 			Filters: squirrel.Gt{"last_seen": time.Now().Add(-7 * 24 * time.Hour)},
 		})
 		if err != nil {
@@ -324,7 +324,7 @@ func (c *insightsCollector) collect(ctx context.Context) []byte {
 
 // hasSmartPlaylists checks if there are any smart playlists (playlists with rules)
 func (c *insightsCollector) hasSmartPlaylists(ctx context.Context) (bool, error) {
-	count, err := c.ds.Playlist(ctx).CountAll(model.QueryOptions{
+	count, err := c.ds.Playlist().CountAll(ctx, model.QueryOptions{
 		Filters: squirrel.And{squirrel.NotEq{"rules": ""}, squirrel.NotEq{"rules": nil}},
 	})
 	return count > 0, err
diff --git a/core/metrics/prometheus.go b/core/metrics/prometheus.go
index 412483156..c85706560 100644
--- a/core/metrics/prometheus.go
+++ b/core/metrics/prometheus.go
@@ -197,28 +197,28 @@ var getPrometheusMetrics = sync.OnceValue(func() *prometheusMetrics {
 })
 
 func processSqlAggregateMetrics(ctx context.Context, ds model.DataStore, targetGauge *prometheus.GaugeVec) {
-	albumsCount, err := ds.Album(ctx).CountAll()
+	albumsCount, err := ds.Album().CountAll(ctx)
 	if err != nil {
 		log.Warn("album CountAll error", err)
 		return
 	}
 	targetGauge.With(prometheus.Labels{"model": "album"}).Set(float64(albumsCount))
 
-	artistCount, err := ds.Artist(ctx).CountAll()
+	artistCount, err := ds.Artist().CountAll(ctx)
 	if err != nil {
 		log.Warn("artist CountAll error", err)
 		return
 	}
 	targetGauge.With(prometheus.Labels{"model": "artist"}).Set(float64(artistCount))
 
-	songsCount, err := ds.MediaFile(ctx).CountAll()
+	songsCount, err := ds.MediaFile().CountAll(ctx)
 	if err != nil {
 		log.Warn("media CountAll error", err)
 		return
 	}
 	targetGauge.With(prometheus.Labels{"model": "media"}).Set(float64(songsCount))
 
-	usersCount, err := ds.User(ctx).CountAll()
+	usersCount, err := ds.User().CountAll(ctx)
 	if err != nil {
 		log.Warn("user CountAll error", err)
 		return
diff --git a/core/playback/device.go b/core/playback/device.go
index fd08b340e..8e4e8880e 100644
--- a/core/playback/device.go
+++ b/core/playback/device.go
@@ -23,7 +23,7 @@ type Track interface {
 }
 
 type playbackDevice struct {
-	serviceCtx           context.Context
+	serviceCtx           context.Context //nolint:containedctx // playback service lifecycle ctx
 	ParentPlaybackServer PlaybackServer
 	Default              bool
 	User                 string
diff --git a/core/playback/playbackserver.go b/core/playback/playbackserver.go
index 7dd02dcb1..48e3bcfaf 100644
--- a/core/playback/playbackserver.go
+++ b/core/playback/playbackserver.go
@@ -111,7 +111,7 @@ func (ps *playbackServer) getDefaultDevice() (*playbackDevice, error) {
 
 // GetMediaFile retrieves the MediaFile given by the id parameter
 func (ps *playbackServer) GetMediaFile(id string) (*model.MediaFile, error) {
-	return ps.datastore.MediaFile(*ps.ctx).Get(id)
+	return ps.datastore.MediaFile().Get(*ps.ctx, id)
 }
 
 // GetDeviceForUser returns the audio playback device for the given user. As of now this is but only the default device.
diff --git a/core/players.go b/core/players.go
index b757f8460..e03d8caa2 100644
--- a/core/players.go
+++ b/core/players.go
@@ -37,14 +37,14 @@ func (p *players) Register(ctx context.Context, playerID, client, userAgent, ip
 	var err error
 	user, _ := request.UserFrom(ctx)
 	if playerID != "" {
-		plr, err = p.ds.Player(ctx).Get(playerID)
+		plr, err = p.ds.Player().Get(ctx, playerID)
 		if err == nil && (plr.Client != client || plr.UserId != user.ID) {
 			playerID = ""
 		}
 	}
 	username := userName(ctx)
 	if err != nil || playerID == "" {
-		plr, err = p.ds.Player(ctx).FindMatch(user.ID, client, userAgent)
+		plr, err = p.ds.Player().FindMatch(ctx, user.ID, client, userAgent)
 		if err == nil {
 			log.Debug(ctx, "Found matching player", "id", plr.ID, "client", client, "username", username, "type", userAgent)
 		} else {
@@ -66,17 +66,17 @@ func (p *players) Register(ctx context.Context, playerID, client, userAgent, ip
 		ctx, cancel := context.WithTimeout(ctx, time.Second)
 		defer cancel()
 
-		err = p.ds.Player(ctx).Put(plr)
+		err = p.ds.Player().Put(ctx, plr)
 		if err != nil {
 			log.Warn(ctx, "Could not save player", "id", plr.ID, "client", client, "username", username, "type", userAgent, err)
 		}
 	})
 	if plr.TranscodingId != "" {
-		trc, err = p.ds.Transcoding(ctx).Get(plr.TranscodingId)
+		trc, err = p.ds.Transcoding().Get(ctx, plr.TranscodingId)
 	}
 	return plr, trc, err
 }
 
 func (p *players) Get(ctx context.Context, playerId string) (*model.Player, error) {
-	return p.ds.Player(ctx).Get(playerId)
+	return p.ds.Player().Get(ctx, playerId)
 }
diff --git a/core/players_test.go b/core/players_test.go
index 55ec16833..302d63157 100644
--- a/core/players_test.go
+++ b/core/players_test.go
@@ -145,14 +145,14 @@ func (m *mockPlayerRepository) add(p *model.Player) {
 	m.data[p.ID] = *p
 }
 
-func (m *mockPlayerRepository) Get(id string) (*model.Player, error) {
+func (m *mockPlayerRepository) Get(_ context.Context, id string) (*model.Player, error) {
 	if p, ok := m.data[id]; ok {
 		return &p, nil
 	}
 	return nil, model.ErrNotFound
 }
 
-func (m *mockPlayerRepository) FindMatch(userId, client, userAgent string) (*model.Player, error) {
+func (m *mockPlayerRepository) FindMatch(_ context.Context, userId, client, userAgent string) (*model.Player, error) {
 	for _, p := range m.data {
 		if p.Client == client && p.UserId == userId && p.UserAgent == userAgent {
 			return &p, nil
@@ -161,7 +161,7 @@ func (m *mockPlayerRepository) FindMatch(userId, client, userAgent string) (*mod
 	return nil, model.ErrNotFound
 }
 
-func (m *mockPlayerRepository) Put(p *model.Player) error {
+func (m *mockPlayerRepository) Put(_ context.Context, p *model.Player) error {
 	m.lastSaved = p
 	return nil
 }
diff --git a/core/playlists/import.go b/core/playlists/import.go
index e41f61bd1..658bd92dc 100644
--- a/core/playlists/import.go
+++ b/core/playlists/import.go
@@ -39,7 +39,7 @@ func (s *playlists) ImportFile(ctx context.Context, absolutePath string, sync bo
 		}
 		if pls.ID != "" && pls.Sync != sync {
 			pls.Sync = sync
-			if putErr := s.ds.Playlist(ctx).Put(pls); putErr != nil {
+			if putErr := s.ds.Playlist().Put(ctx, pls); putErr != nil {
 				return nil, putErr
 			}
 		}
@@ -74,7 +74,7 @@ func (s *playlists) ImportFile(ctx context.Context, absolutePath string, sync bo
 var errNotInLibrary = fmt.Errorf("path not in any library")
 
 func (s *playlists) resolveFolder(ctx context.Context, dir string) (*model.Folder, error) {
-	libs, err := s.ds.Library(ctx).GetAll()
+	libs, err := s.ds.Library().GetAll(ctx)
 	if err != nil {
 		return nil, err
 	}
@@ -84,7 +84,7 @@ func (s *playlists) resolveFolder(ctx context.Context, dir string) (*model.Folde
 		return nil, fmt.Errorf("%w: %s", errNotInLibrary, dir)
 	}
 
-	folder, err := s.ds.Folder(ctx).GetByPath(lib, dir)
+	folder, err := s.ds.Folder().GetByPath(ctx, lib, dir)
 	if err != nil {
 		return nil, fmt.Errorf("resolving folder for path %s: %w", dir, err)
 	}
@@ -122,7 +122,7 @@ func (s *playlists) ImportM3U(ctx context.Context, reader io.Reader) (*model.Pla
 		log.Error(ctx, "Error parsing playlist", err)
 		return nil, err
 	}
-	err = s.ds.Playlist(ctx).Put(pls)
+	err = s.ds.Playlist().Put(ctx, pls)
 	if err != nil {
 		log.Error(ctx, "Error saving playlist", err)
 		return nil, err
@@ -166,14 +166,14 @@ func fingerprint(h *xxh3.Hasher) string {
 // findByPathNormalized looks up a playlist by path, trying both NFC and NFD Unicode
 // normalization forms to handle cross-platform filesystem differences.
 func (s *playlists) findByPathNormalized(ctx context.Context, path string) (*model.Playlist, error) {
-	pls, err := s.ds.Playlist(ctx).FindByPath(path)
+	pls, err := s.ds.Playlist().FindByPath(ctx, path)
 	if errors.Is(err, model.ErrNotFound) {
 		altPath := norm.NFD.String(path)
 		if altPath == path {
 			altPath = norm.NFC.String(path)
 		}
 		if altPath != path {
-			pls, err = s.ds.Playlist(ctx).FindByPath(altPath)
+			pls, err = s.ds.Playlist().FindByPath(ctx, altPath)
 		}
 	}
 	return pls, err
@@ -221,5 +221,5 @@ func (s *playlists) updatePlaylist(ctx context.Context, newPls *model.Playlist,
 			newPls.Public = conf.Server.DefaultPlaylistPublicVisibility
 		}
 	}
-	return s.ds.Playlist(ctx).Put(newPls)
+	return s.ds.Playlist().Put(ctx, newPls)
 }
diff --git a/core/playlists/import_test.go b/core/playlists/import_test.go
index a90a703d9..25960f0fe 100644
--- a/core/playlists/import_test.go
+++ b/core/playlists/import_test.go
@@ -1172,7 +1172,7 @@ type mockedMediaFileRepo struct {
 	data map[string]model.MediaFile
 }
 
-func (r *mockedMediaFileRepo) FindByPaths(paths []string) (model.MediaFiles, error) {
+func (r *mockedMediaFileRepo) FindByPaths(ctx context.Context, paths []string) (model.MediaFiles, error) {
 	var mfs model.MediaFiles
 
 	// If data map provided, look up files
@@ -1212,7 +1212,7 @@ type mockedMediaFileFromListRepo struct {
 	data []string
 }
 
-func (r *mockedMediaFileFromListRepo) FindByPaths(paths []string) (model.MediaFiles, error) {
+func (r *mockedMediaFileFromListRepo) FindByPaths(ctx context.Context, paths []string) (model.MediaFiles, error) {
 	var mfs model.MediaFiles
 
 	for idx, dataPath := range r.data {
@@ -1247,7 +1247,7 @@ type mockFolderRepoForImport struct {
 	folder *model.Folder
 }
 
-func (m *mockFolderRepoForImport) GetByPath(_ model.Library, _ string) (*model.Folder, error) {
+func (m *mockFolderRepoForImport) GetByPath(_ context.Context, _ model.Library, _ string) (*model.Folder, error) {
 	if m.folder != nil {
 		return m.folder, nil
 	}
diff --git a/core/playlists/parse_m3u.go b/core/playlists/parse_m3u.go
index b9cb154cb..9610e9dbb 100644
--- a/core/playlists/parse_m3u.go
+++ b/core/playlists/parse_m3u.go
@@ -20,7 +20,7 @@ import (
 )
 
 func (s *playlists) parseM3U(ctx context.Context, pls *model.Playlist, folder *model.Folder, reader io.Reader) error {
-	mediaFileRepository := s.ds.MediaFile(ctx)
+	mediaFileRepository := s.ds.MediaFile()
 	resolver, err := newPathResolver(ctx, s.ds)
 	if err != nil {
 		return err
@@ -96,7 +96,7 @@ func (s *playlists) parseM3U(ctx context.Context, pls *model.Playlist, folder *m
 			}
 		}
 
-		found, err := mediaFileRepository.FindByPaths(lookupCandidates)
+		found, err := mediaFileRepository.FindByPaths(ctx, lookupCandidates)
 		if err != nil {
 			log.Warn(ctx, "Error reading files from DB", "playlist", pls.Name, err)
 			continue
@@ -215,7 +215,7 @@ type pathResolver struct {
 
 // newPathResolver creates a pathResolver with libraries loaded from the datastore.
 func newPathResolver(ctx context.Context, ds model.DataStore) (*pathResolver, error) {
-	libs, err := ds.Library(ctx).GetAll()
+	libs, err := ds.Library().GetAll(ctx)
 	if err != nil {
 		return nil, err
 	}
diff --git a/core/playlists/parse_m3u_test.go b/core/playlists/parse_m3u_test.go
index d7fd5e001..b6a3a96f9 100644
--- a/core/playlists/parse_m3u_test.go
+++ b/core/playlists/parse_m3u_test.go
@@ -24,7 +24,7 @@ var _ = Describe("libraryMatcher", func() {
 
 	// Helper function to create a libraryMatcher from the mock datastore
 	createMatcher := func(ds model.DataStore) *libraryMatcher {
-		libs, err := ds.Library(ctx).GetAll()
+		libs, err := ds.Library().GetAll(ctx)
 		Expect(err).ToNot(HaveOccurred())
 		return newLibraryMatcher(libs)
 	}
diff --git a/core/playlists/playlists.go b/core/playlists/playlists.go
index 1f8cc9581..c9bc03b97 100644
--- a/core/playlists/playlists.go
+++ b/core/playlists/playlists.go
@@ -49,8 +49,8 @@ type Playlists interface {
 	ImportM3U(ctx context.Context, reader io.Reader) (*model.Playlist, error)
 
 	// REST adapters
-	NewRepository(ctx context.Context) rest.Repository
-	TracksRepository(ctx context.Context, playlistId string, refreshSmartPlaylist bool) rest.Repository
+	Repository() rest.Repository[model.Playlist]
+	TracksRepository(ctx context.Context, playlistId string, refreshSmartPlaylist bool) rest.Repository[model.PlaylistTrack]
 }
 
 // ImageUploadService is a local interface satisfied by artwork.Uploader.
@@ -64,10 +64,13 @@ type ImageUploadService interface {
 type playlists struct {
 	ds        model.DataStore
 	imgUpload ImageUploadService
+	repo      *playlistRepositoryWrapper
 }
 
 func NewPlaylists(ds model.DataStore, imgUpload ImageUploadService) Playlists {
-	return &playlists{ds: ds, imgUpload: imgUpload}
+	s := &playlists{ds: ds, imgUpload: imgUpload}
+	s.repo = &playlistRepositoryWrapper{PlaylistRepository: ds.Playlist(), service: s}
+	return s
 }
 
 func InPath(folder model.Folder) bool {
@@ -86,30 +89,30 @@ func InPath(folder model.Folder) bool {
 // --- Read operations ---
 
 func (s *playlists) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Playlists, error) {
-	return s.ds.Playlist(ctx).GetAll(options...)
+	return s.ds.Playlist().GetAll(ctx, options...)
 }
 
 func (s *playlists) Get(ctx context.Context, id string) (*model.Playlist, error) {
-	return s.ds.Playlist(ctx).Get(id)
+	return s.ds.Playlist().Get(ctx, id)
 }
 
 func (s *playlists) GetWithTracks(ctx context.Context, id string) (*model.Playlist, error) {
-	return s.ds.Playlist(ctx).GetWithTracks(id, true, false)
+	return s.ds.Playlist().GetWithTracks(ctx, id, true, false)
 }
 
 func (s *playlists) GetPlaylists(ctx context.Context, mediaFileId string) (model.Playlists, error) {
-	return s.ds.Playlist(ctx).GetPlaylists(mediaFileId)
+	return s.ds.Playlist().GetPlaylists(ctx, mediaFileId)
 }
 
 // Tracks scopes a repository to one playlist's tracks, for callers that page or stream them rather
 // than loading every one like GetWithTracks. Gets first because PlaylistRepository.Tracks discards
 // its error behind a nil (and warns), and this is probed with ids that are usually not playlists.
 func (s *playlists) Tracks(ctx context.Context, id string) (model.PlaylistTrackRepository, error) {
-	repo := s.ds.Playlist(ctx)
-	if _, err := repo.Get(id); err != nil {
+	repo := s.ds.Playlist()
+	if _, err := repo.Get(ctx, id); err != nil {
 		return nil, err
 	}
-	tracks := repo.Tracks(id, true)
+	tracks := repo.Tracks(ctx, id, true)
 	if tracks == nil {
 		return nil, model.ErrNotFound
 	}
@@ -127,7 +130,7 @@ func (s *playlists) Create(ctx context.Context, playlistId string, name string,
 		var err error
 
 		if playlistId != "" {
-			pls, err = tx.Playlist(ctx).Get(playlistId)
+			pls, err = tx.Playlist().Get(ctx, playlistId)
 			if err != nil {
 				return err
 			}
@@ -145,7 +148,7 @@ func (s *playlists) Create(ctx context.Context, playlistId string, name string,
 		pls.Tracks = nil
 		pls.AddMediaFilesByID(ids)
 
-		err = tx.Playlist(ctx).Put(pls)
+		err = tx.Playlist().Put(ctx, pls)
 		playlistId = pls.ID
 		return err
 	})
@@ -165,7 +168,7 @@ func (s *playlists) Delete(ctx context.Context, id string) error {
 		}
 	}
 
-	return s.ds.Playlist(ctx).Delete(id)
+	return s.ds.Playlist().Delete(ctx, id)
 }
 
 func (s *playlists) Update(ctx context.Context, playlistID string,
@@ -183,21 +186,21 @@ func (s *playlists) Update(ctx context.Context, playlistID string,
 		return err
 	}
 	return s.ds.WithTxImmediate(func(tx model.DataStore) error {
-		repo := tx.Playlist(ctx)
+		repo := tx.Playlist()
 
 		if len(idxToRemove) > 0 {
-			tracksRepo := repo.Tracks(playlistID, false)
+			tracksRepo := repo.Tracks(ctx, playlistID, false)
 			// Convert 0-based indices to 1-based position IDs and delete them directly,
 			// avoiding the need to load all tracks into memory.
 			positions := make([]string, len(idxToRemove))
 			for i, idx := range idxToRemove {
 				positions[i] = strconv.Itoa(idx + 1)
 			}
-			if err := tracksRepo.Delete(positions...); err != nil {
+			if err := tracksRepo.Delete(ctx, positions...); err != nil {
 				return err
 			}
 			if len(idsToAdd) > 0 {
-				if _, err := tracksRepo.Add(idsToAdd); err != nil {
+				if _, err := tracksRepo.Add(ctx, idsToAdd); err != nil {
 					return err
 				}
 			}
@@ -205,7 +208,7 @@ func (s *playlists) Update(ctx context.Context, playlistID string,
 		}
 
 		if len(idsToAdd) > 0 {
-			if _, err := repo.Tracks(playlistID, false).Add(idsToAdd); err != nil {
+			if _, err := repo.Tracks(ctx, playlistID, false).Add(ctx, idsToAdd); err != nil {
 				return err
 			}
 		}
@@ -221,7 +224,7 @@ func (s *playlists) Update(ctx context.Context, playlistID string,
 
 // checkWritable fetches the playlist and verifies the current user can modify it.
 func (s *playlists) checkWritable(ctx context.Context, id string) (*model.Playlist, error) {
-	pls, err := s.ds.Playlist(ctx).Get(id)
+	pls, err := s.ds.Playlist().Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
@@ -257,7 +260,7 @@ func (s *playlists) updateMetadata(ctx context.Context, ds model.DataStore, pls
 	if public != nil {
 		pls.Public = *public
 	}
-	return ds.Playlist(ctx).Put(pls)
+	return ds.Playlist().Put(ctx, pls)
 }
 
 // --- Track management operations ---
@@ -266,7 +269,7 @@ func (s *playlists) AddTracks(ctx context.Context, playlistID string, ids []stri
 	if _, err := s.checkTracksEditable(ctx, playlistID); err != nil {
 		return 0, err
 	}
-	return s.ds.Playlist(ctx).Tracks(playlistID, false).Add(ids)
+	return s.ds.Playlist().Tracks(ctx, playlistID, false).Add(ctx, ids)
 }
 
 // InsertTracks adds tracks before the 1-based position pos; a position past the end appends.
@@ -279,7 +282,7 @@ func (s *playlists) InsertTracks(ctx context.Context, playlistID string, ids []s
 	// concurrent writers instead of waiting for the lock.
 	err := s.ds.WithTxImmediate(func(tx model.DataStore) error {
 		var err error
-		count, err = tx.Playlist(ctx).Tracks(playlistID, false).Insert(ids, pos)
+		count, err = tx.Playlist().Tracks(ctx, playlistID, false).Insert(ctx, ids, pos)
 		return err
 	})
 	return count, err
@@ -289,21 +292,21 @@ func (s *playlists) AddAlbums(ctx context.Context, playlistID string, albumIds [
 	if _, err := s.checkTracksEditable(ctx, playlistID); err != nil {
 		return 0, err
 	}
-	return s.ds.Playlist(ctx).Tracks(playlistID, false).AddAlbums(albumIds)
+	return s.ds.Playlist().Tracks(ctx, playlistID, false).AddAlbums(ctx, albumIds)
 }
 
 func (s *playlists) AddArtists(ctx context.Context, playlistID string, artistIds []string) (int, error) {
 	if _, err := s.checkTracksEditable(ctx, playlistID); err != nil {
 		return 0, err
 	}
-	return s.ds.Playlist(ctx).Tracks(playlistID, false).AddArtists(artistIds)
+	return s.ds.Playlist().Tracks(ctx, playlistID, false).AddArtists(ctx, artistIds)
 }
 
 func (s *playlists) AddDiscs(ctx context.Context, playlistID string, discs []model.DiscID) (int, error) {
 	if _, err := s.checkTracksEditable(ctx, playlistID); err != nil {
 		return 0, err
 	}
-	return s.ds.Playlist(ctx).Tracks(playlistID, false).AddDiscs(discs)
+	return s.ds.Playlist().Tracks(ctx, playlistID, false).AddDiscs(ctx, discs)
 }
 
 func (s *playlists) RemoveTracks(ctx context.Context, playlistID string, trackIds []string) error {
@@ -311,7 +314,7 @@ func (s *playlists) RemoveTracks(ctx context.Context, playlistID string, trackId
 		return err
 	}
 	return s.ds.WithTx(func(tx model.DataStore) error {
-		return tx.Playlist(ctx).Tracks(playlistID, false).Delete(trackIds...)
+		return tx.Playlist().Tracks(ctx, playlistID, false).Delete(ctx, trackIds...)
 	})
 }
 
@@ -320,7 +323,7 @@ func (s *playlists) ReorderTrack(ctx context.Context, playlistID string, pos int
 		return err
 	}
 	return s.ds.WithTxImmediate(func(tx model.DataStore) error {
-		return tx.Playlist(ctx).Tracks(playlistID, false).Reorder(pos, newPos)
+		return tx.Playlist().Tracks(ctx, playlistID, false).Reorder(ctx, pos, newPos)
 	})
 }
 
@@ -339,7 +342,7 @@ func (s *playlists) SetImage(ctx context.Context, playlistID string, reader io.R
 	}
 
 	pls.UploadedImage = filename
-	if err := s.ds.Playlist(ctx).Put(pls); err != nil {
+	if err := s.ds.Playlist().Put(ctx, pls); err != nil {
 		return err
 	}
 	s.imgUpload.EnqueueArtwork(ctx, consts.EntityPlaylist, pls.ID)
@@ -357,7 +360,7 @@ func (s *playlists) RemoveImage(ctx context.Context, playlistID string) error {
 	}
 
 	pls.UploadedImage = ""
-	if err := s.ds.Playlist(ctx).Put(pls); err != nil {
+	if err := s.ds.Playlist().Put(ctx, pls); err != nil {
 		return err
 	}
 	s.imgUpload.EnqueueArtwork(ctx, consts.EntityPlaylist, pls.ID)
diff --git a/core/playlists/playlists_test.go b/core/playlists/playlists_test.go
index dd6213555..ec44de3bc 100644
--- a/core/playlists/playlists_test.go
+++ b/core/playlists/playlists_test.go
@@ -493,15 +493,15 @@ var _ = Describe("Playlists", func() {
 
 		It("clears the resolved artwork state and re-queues after removing an upload", func() {
 			ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-			Expect(ds.Artwork(ctx).PutItemArtwork(&model.ItemArtwork{
+			Expect(ds.Artwork().PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "pl", ItemID: "pls-1", Hash: "oldhash", Source: "upload",
 			})).To(Succeed())
 
 			Expect(ps.RemoveImage(ctx, "pls-1")).To(Succeed())
 
-			_, err := ds.Artwork(ctx).GetItemArtwork(model.KindPlaylistArtwork, "pls-1", model.ImageTypePrimary)
+			_, err := ds.Artwork().GetItemArtwork(ctx, model.KindPlaylistArtwork, "pls-1", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound))
-			queued, _ := ds.ArtworkQueue(ctx).DequeueBatch(100)
+			queued, _ := ds.ArtworkQueue().DequeueBatch(ctx, 100)
 			Expect(queued).To(ContainElement(SatisfyAll(
 				HaveField("ItemKind", "pl"),
 				HaveField("ItemID", "pls-1"),
diff --git a/core/playlists/rest_adapter.go b/core/playlists/rest_adapter.go
index 45642c819..f8e8a9d41 100644
--- a/core/playlists/rest_adapter.go
+++ b/core/playlists/rest_adapter.go
@@ -14,42 +14,43 @@ import (
 
 // --- REST adapter (follows Share/Library pattern) ---
 
-func (s *playlists) NewRepository(ctx context.Context) rest.Repository {
-	return &playlistRepositoryWrapper{
-		ctx:                ctx,
-		PlaylistRepository: s.ds.Playlist(ctx),
-		service:            s,
-	}
+func (s *playlists) Repository() rest.Repository[model.Playlist] {
+	return s.repo
 }
 
-// playlistRepositoryWrapper wraps the playlist repository as a thin REST-to-service adapter.
-// It satisfies rest.Repository through the embedded PlaylistRepository (via ResourceRepository),
-// and rest.Persistable by delegating to service methods for all mutations.
+// playlistRepositoryWrapper wraps the playlist repository as a thin REST-to-service adapter,
+// delegating to service methods for all mutations.
 type playlistRepositoryWrapper struct {
 	model.PlaylistRepository
-	ctx     context.Context
 	service *playlists
 }
 
-func (r *playlistRepositoryWrapper) Save(entity any) (string, error) {
-	return r.service.savePlaylist(r.ctx, entity.(*model.Playlist))
+var _ rest.Persistable[model.Playlist] = (*playlistRepositoryWrapper)(nil)
+
+func (r *playlistRepositoryWrapper) Save(ctx context.Context, entity *model.Playlist) (string, error) {
+	return r.service.savePlaylist(ctx, entity)
 }
 
-func (r *playlistRepositoryWrapper) Update(id string, entity any, cols ...string) error {
-	return r.service.updatePlaylistEntity(r.ctx, id, entity.(*model.Playlist), cols...)
+func (r *playlistRepositoryWrapper) Update(ctx context.Context, id string, entity model.Playlist, cols ...string) error {
+	return r.service.updatePlaylistEntity(ctx, id, &entity, cols...)
 }
 
-func (r *playlistRepositoryWrapper) Delete(id string) error {
-	return r.service.Delete(r.ctx, id)
+func (r *playlistRepositoryWrapper) Delete(ctx context.Context, ids ...string) error {
+	for _, id := range ids {
+		if err := r.service.Delete(ctx, id); err != nil {
+			return err
+		}
+	}
+	return nil
 }
 
-func (s *playlists) TracksRepository(ctx context.Context, playlistId string, refreshSmartPlaylist bool) rest.Repository {
-	repo := s.ds.Playlist(ctx)
-	tracks := repo.Tracks(playlistId, refreshSmartPlaylist)
+func (s *playlists) TracksRepository(ctx context.Context, playlistId string, refreshSmartPlaylist bool) rest.Repository[model.PlaylistTrack] {
+	repo := s.ds.Playlist()
+	tracks := repo.Tracks(ctx, playlistId, refreshSmartPlaylist)
 	if tracks == nil {
 		return nil
 	}
-	return tracks.(rest.Repository)
+	return tracks
 }
 
 // savePlaylist creates a new playlist, assigning the owner from context.
@@ -63,7 +64,7 @@ func (s *playlists) savePlaylist(ctx context.Context, pls *model.Playlist) (stri
 	pls.UploadedImage = ""    // Managed by image upload endpoint
 	pls.ExternalImageURL = "" // Managed by M3U import / plugins only
 	pls.EvaluatedAt = nil     // Server-managed
-	err := s.ds.Playlist(ctx).Put(pls)
+	err := s.ds.Playlist().Put(ctx, pls)
 	if err != nil {
 		return "", err
 	}
@@ -156,7 +157,7 @@ func (s *playlists) applyFlagsOnly(ctx context.Context, current, entity *model.P
 	if len(updateCols) == 0 {
 		return nil
 	}
-	return s.ds.Playlist(ctx).Put(current, updateCols...)
+	return s.ds.Playlist().Put(ctx, current, updateCols...)
 }
 
 // sentFields returns a predicate that reports whether a JSON field was present
diff --git a/core/playlists/rest_adapter_test.go b/core/playlists/rest_adapter_test.go
index fbfab350c..e82dd9df5 100644
--- a/core/playlists/rest_adapter_test.go
+++ b/core/playlists/rest_adapter_test.go
@@ -31,7 +31,7 @@ var _ = Describe("REST Adapter", func() {
 	})
 
 	Describe("NewRepository", func() {
-		var repo rest.Persistable
+		var repo rest.Persistable[model.Playlist]
 
 		BeforeEach(func() {
 			mockPlsRepo.Data = map[string]*model.Playlist{
@@ -43,9 +43,9 @@ var _ = Describe("REST Adapter", func() {
 		Describe("Save", func() {
 			It("sets the owner from the context user", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "New Playlist"}
-				id, err := repo.Save(pls)
+				id, err := repo.Save(ctx, pls)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(id).ToNot(BeEmpty())
 				Expect(pls.OwnerID).To(Equal("user-1"))
@@ -53,16 +53,16 @@ var _ = Describe("REST Adapter", func() {
 
 			It("forces a new creation by clearing ID", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{ID: "should-be-cleared", Name: "New"}
-				_, err := repo.Save(pls)
+				_, err := repo.Save(ctx, pls)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.ID).ToNot(Equal("should-be-cleared"))
 			})
 
 			It("clears server-managed fields to prevent injection via REST API", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{
 					Name:             "Legit Playlist",
 					Comment:          "A comment",
@@ -74,7 +74,7 @@ var _ = Describe("REST Adapter", func() {
 					ExternalImageURL: "http://evil.example.com/ssrf",
 					EvaluatedAt:      new(time.Now()),
 				}
-				_, err := repo.Save(pls)
+				_, err := repo.Save(ctx, pls)
 				Expect(err).ToNot(HaveOccurred())
 
 				saved := mockPlsRepo.Last
@@ -95,33 +95,33 @@ var _ = Describe("REST Adapter", func() {
 		Describe("Update", func() {
 			It("allows owner to update their playlist", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "Updated"}
-				err := repo.Update("pls-1", pls)
+				err := repo.Update(ctx, "pls-1", *pls)
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("allows admin to update any playlist", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "admin-1", IsAdmin: true})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "Updated"}
-				err := repo.Update("pls-1", pls)
+				err := repo.Update(ctx, "pls-1", *pls)
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("denies non-owner, non-admin", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "other-user", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "Updated"}
-				err := repo.Update("pls-1", pls)
+				err := repo.Update(ctx, "pls-1", *pls)
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
 
 			It("denies regular user from changing ownership", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "Updated", OwnerID: "other-user"}
-				err := repo.Update("pls-1", pls)
+				err := repo.Update(ctx, "pls-1", *pls)
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
 
@@ -133,9 +133,9 @@ var _ = Describe("REST Adapter", func() {
 					// entity.OwnerID. sentFields normalizes both sides so the
 					// permission gate fires regardless of casing.
 					ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-					repo = ps.NewRepository(ctx).(rest.Persistable)
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
 					pls := &model.Playlist{OwnerID: "other-user"}
-					err := repo.Update("pls-1", pls, colName)
+					err := repo.Update(ctx, "pls-1", *pls, colName)
 					Expect(err).To(Equal(rest.ErrPermissionDenied))
 				},
 				Entry("canonical camelCase", "ownerId"),
@@ -152,10 +152,10 @@ var _ = Describe("REST Adapter", func() {
 					Rules:   &criteria.Criteria{Expression: criteria.Contains{"title": "old"}},
 				}
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				newRules := &criteria.Criteria{Expression: criteria.Contains{"title": "new"}}
 				pls := &model.Playlist{Name: "Smart Playlist", Rules: newRules}
-				err := repo.Update("smart-1", pls)
+				err := repo.Update(ctx, "smart-1", *pls)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Last.Rules).To(Equal(newRules))
 			})
@@ -171,10 +171,10 @@ var _ = Describe("REST Adapter", func() {
 					Rules:        &criteria.Criteria{Expression: criteria.Contains{"title": "old"}},
 				}
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				newRules := &criteria.Criteria{Expression: criteria.Contains{"title": "new"}}
 				pls := &model.Playlist{Rules: newRules}
-				err := repo.Update("smart-1", pls, "rules")
+				err := repo.Update(ctx, "smart-1", *pls, "rules")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Last.ImportedHash).To(BeEmpty())
 			})
@@ -190,9 +190,9 @@ var _ = Describe("REST Adapter", func() {
 					UpdatedAt: originalTime,
 				}
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "File Playlist", Sync: false}
-				err := repo.Update("file-pls", pls)
+				err := repo.Update(ctx, "file-pls", *pls)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Last.Sync).To(BeFalse())
 				Expect(mockPlsRepo.Last.UpdatedAt).To(Equal(originalTime))
@@ -207,9 +207,9 @@ var _ = Describe("REST Adapter", func() {
 					Sync:    false,
 				}
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "Manual Playlist", Sync: true}
-				err := repo.Update("manual-pls", pls)
+				err := repo.Update(ctx, "manual-pls", *pls)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Last).To(BeNil())
 			})
@@ -224,9 +224,9 @@ var _ = Describe("REST Adapter", func() {
 					UpdatedAt: originalTime,
 				}
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "My Playlist", Public: true}
-				err := repo.Update("pls-pub", pls)
+				err := repo.Update(ctx, "pls-pub", *pls)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Last.Public).To(BeTrue())
 				Expect(mockPlsRepo.Last.UpdatedAt).To(Equal(originalTime))
@@ -241,9 +241,9 @@ var _ = Describe("REST Adapter", func() {
 					Sync:    true,
 				}
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "New Name", Sync: false}
-				err := repo.Update("file-pls2", pls)
+				err := repo.Update(ctx, "file-pls2", *pls)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Last.Name).To(Equal("New Name"))
 				Expect(mockPlsRepo.Last.Sync).To(BeFalse())
@@ -251,9 +251,9 @@ var _ = Describe("REST Adapter", func() {
 
 			It("returns rest.ErrNotFound when playlist doesn't exist", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
 				pls := &model.Playlist{Name: "Updated"}
-				err := repo.Update("nonexistent", pls)
+				err := repo.Update(ctx, "nonexistent", *pls)
 				Expect(err).To(Equal(rest.ErrNotFound))
 			})
 
@@ -274,8 +274,8 @@ var _ = Describe("REST Adapter", func() {
 				})
 
 				It("preserves name and comment when only public is sent (bulk Make Public)", func() {
-					repo = ps.NewRepository(ctx).(rest.Persistable)
-					err := repo.Update("partial", &model.Playlist{Public: true}, "public")
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
+					err := repo.Update(ctx, "partial", model.Playlist{Public: true}, "public")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.Name).To(Equal("Original Name"))
 					Expect(mockPlsRepo.Last.Comment).To(Equal("Original comment"))
@@ -290,16 +290,16 @@ var _ = Describe("REST Adapter", func() {
 						Path:    "/music/p.m3u",
 						Sync:    true,
 					}
-					repo = ps.NewRepository(ctx).(rest.Persistable)
-					err := repo.Update("file-partial", &model.Playlist{Sync: false}, "sync")
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
+					err := repo.Update(ctx, "file-partial", model.Playlist{Sync: false}, "sync")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.Name).To(Equal("Keep Me"))
 					Expect(mockPlsRepo.Last.Sync).To(BeFalse())
 				})
 
 				It("renames the playlist when only name is sent", func() {
-					repo = ps.NewRepository(ctx).(rest.Persistable)
-					err := repo.Update("partial", &model.Playlist{Name: "Renamed"}, "name")
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
+					err := repo.Update(ctx, "partial", model.Playlist{Name: "Renamed"}, "name")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.Name).To(Equal("Renamed"))
 					Expect(mockPlsRepo.Last.Comment).To(Equal("Original comment"))
@@ -307,8 +307,8 @@ var _ = Describe("REST Adapter", func() {
 				})
 
 				It("clears the comment when an empty comment is sent explicitly", func() {
-					repo = ps.NewRepository(ctx).(rest.Persistable)
-					err := repo.Update("partial", &model.Playlist{Comment: ""}, "comment")
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
+					err := repo.Update(ctx, "partial", model.Playlist{Comment: ""}, "comment")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.Comment).To(BeEmpty())
 					Expect(mockPlsRepo.Last.Name).To(Equal("Original Name"))
@@ -323,9 +323,9 @@ var _ = Describe("REST Adapter", func() {
 						Public:  true,
 						Rules:   &criteria.Criteria{Expression: criteria.Is{"genre": "Rock"}},
 					}
-					repo = ps.NewRepository(ctx).(rest.Persistable)
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
 					newRules := &criteria.Criteria{Expression: criteria.Is{"genre": "Jazz"}, Sort: "year DESC"}
-					err := repo.Update("smart-partial", &model.Playlist{Rules: newRules}, "rules")
+					err := repo.Update(ctx, "smart-partial", model.Playlist{Rules: newRules}, "rules")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.Rules).To(Equal(newRules))
 					Expect(mockPlsRepo.Last.Name).To(Equal("Smart Original"))
@@ -342,9 +342,9 @@ var _ = Describe("REST Adapter", func() {
 						Rules:       &criteria.Criteria{Expression: criteria.Is{"genre": "Rock"}},
 						EvaluatedAt: &evaluatedAt,
 					}
-					repo = ps.NewRepository(ctx).(rest.Persistable)
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
 					newRules := &criteria.Criteria{Expression: criteria.Is{"genre": "Jazz"}}
-					err := repo.Update("smart-reset", &model.Playlist{Rules: newRules}, "rules")
+					err := repo.Update(ctx, "smart-reset", model.Playlist{Rules: newRules}, "rules")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.EvaluatedAt).To(BeNil())
 				})
@@ -358,8 +358,8 @@ var _ = Describe("REST Adapter", func() {
 						Rules:       &criteria.Criteria{Expression: criteria.Is{"genre": "Rock"}},
 						EvaluatedAt: &evaluatedAt,
 					}
-					repo = ps.NewRepository(ctx).(rest.Persistable)
-					err := repo.Update("smart-keep", &model.Playlist{Name: "Renamed Smart"}, "name")
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
+					err := repo.Update(ctx, "smart-keep", model.Playlist{Name: "Renamed Smart"}, "name")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.EvaluatedAt).ToNot(BeNil())
 					Expect(*mockPlsRepo.Last.EvaluatedAt).To(BeTemporally("~", evaluatedAt, time.Second))
@@ -373,10 +373,10 @@ var _ = Describe("REST Adapter", func() {
 						OwnerID: "user-1",
 						Rules:   &criteria.Criteria{Expression: criteria.Is{"genre": "Rock"}},
 					}
-					repo = ps.NewRepository(ctx).(rest.Persistable)
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
 					newRules := &criteria.Criteria{Expression: criteria.Is{"artist": "Miles Davis"}, Sort: "album"}
-					err := repo.Update("smart-edit",
-						&model.Playlist{Name: "Smart Renamed", Rules: newRules},
+					err := repo.Update(ctx, "smart-edit",
+						model.Playlist{Name: "Smart Renamed", Rules: newRules},
 						"name", "rules")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.Name).To(Equal("Smart Renamed"))
@@ -392,11 +392,11 @@ var _ = Describe("REST Adapter", func() {
 						OwnerID: "user-1",
 						Rules:   rules,
 					}
-					repo = ps.NewRepository(ctx).(rest.Persistable)
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
 					// Same rules sent back — rulesEqual should report no change and
 					// the request should no-op (no Put call).
 					sameRules := &criteria.Criteria{Expression: criteria.Is{"genre": "Rock"}}
-					err := repo.Update("smart-idempotent", &model.Playlist{Rules: sameRules}, "rules")
+					err := repo.Update(ctx, "smart-idempotent", model.Playlist{Rules: sameRules}, "rules")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last).To(BeNil()) // no Put happened
 				})
@@ -410,8 +410,8 @@ var _ = Describe("REST Adapter", func() {
 						Public:  false,
 						Rules:   rules,
 					}
-					repo = ps.NewRepository(ctx).(rest.Persistable)
-					err := repo.Update("smart-public", &model.Playlist{Public: true}, "public")
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
+					err := repo.Update(ctx, "smart-public", model.Playlist{Public: true}, "public")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.Public).To(BeTrue())
 					Expect(mockPlsRepo.Last.Rules).To(Equal(rules))
@@ -421,8 +421,8 @@ var _ = Describe("REST Adapter", func() {
 				It("does not treat a missing ownerId as an ownership transfer attempt", func() {
 					// A non-admin user sending only {public:true} should not be blocked
 					// just because OwnerID is the zero value in the deserialized entity.
-					repo = ps.NewRepository(ctx).(rest.Persistable)
-					err := repo.Update("partial", &model.Playlist{Public: true}, "public")
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
+					err := repo.Update(ctx, "partial", model.Playlist{Public: true}, "public")
 					Expect(err).ToNot(HaveOccurred())
 				})
 
@@ -431,8 +431,8 @@ var _ = Describe("REST Adapter", func() {
 					// like {"Name":"x"}, but rest.Put's field-name extraction is
 					// case-sensitive. sentFields normalizes both sides so a request
 					// with {"Name":"Renamed"} is honored, not silently ignored.
-					repo = ps.NewRepository(ctx).(rest.Persistable)
-					err := repo.Update("partial", &model.Playlist{Name: "Renamed"}, "Name")
+					repo = ps.Repository().(rest.Persistable[model.Playlist])
+					err := repo.Update(ctx, "partial", model.Playlist{Name: "Renamed"}, "Name")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(mockPlsRepo.Last.Name).To(Equal("Renamed"))
 					Expect(mockPlsRepo.Last.Comment).To(Equal("Original comment"))
@@ -443,16 +443,16 @@ var _ = Describe("REST Adapter", func() {
 		Describe("Delete", func() {
 			It("delegates to service Delete with permission checks", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "user-1", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
-				err := repo.Delete("pls-1")
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
+				err := repo.Delete(ctx, "pls-1")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockPlsRepo.Deleted).To(ContainElement("pls-1"))
 			})
 
 			It("denies non-owner", func() {
 				ctx = request.WithUser(ctx, model.User{ID: "other-user", IsAdmin: false})
-				repo = ps.NewRepository(ctx).(rest.Persistable)
-				err := repo.Delete("pls-1")
+				repo = ps.Repository().(rest.Persistable[model.Playlist])
+				err := repo.Delete(ctx, "pls-1")
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
 		})
diff --git a/core/scrobbler/buffered_scrobbler.go b/core/scrobbler/buffered_scrobbler.go
index c5c096a0b..30bced623 100644
--- a/core/scrobbler/buffered_scrobbler.go
+++ b/core/scrobbler/buffered_scrobbler.go
@@ -70,7 +70,7 @@ type bufferedScrobbler struct {
 	loader     Loader
 	service    string
 	wakeSignal chan struct{}
-	ctx        context.Context
+	ctx        context.Context //nolint:containedctx // scrobbler lifecycle ctx, cancelled by Stop
 	cancel     context.CancelFunc
 }
 
@@ -97,7 +97,7 @@ func (b *bufferedScrobbler) NowPlaying(ctx context.Context, userId string, track
 }
 
 func (b *bufferedScrobbler) Scrobble(ctx context.Context, userId string, s Scrobble) error {
-	err := b.ds.ScrobbleBuffer(ctx).Enqueue(b.service, userId, s.ID, s.TimeStamp)
+	err := b.ds.ScrobbleBuffer().Enqueue(ctx, b.service, userId, s.ID, s.TimeStamp)
 	if err != nil {
 		return err
 	}
@@ -154,8 +154,8 @@ func (b *bufferedScrobbler) run(ctx context.Context) {
 }
 
 func (b *bufferedScrobbler) processQueue(ctx context.Context) (bool, time.Duration) {
-	buffer := b.ds.ScrobbleBuffer(ctx)
-	userIds, err := buffer.UserIDs(b.service)
+	buffer := b.ds.ScrobbleBuffer()
+	userIds, err := buffer.UserIDs(ctx, b.service)
 	if err != nil {
 		log.Error(ctx, "Error retrieving userIds from scrobble buffer", "scrobbler", b.service, err)
 		return false, 0
@@ -176,14 +176,14 @@ func (b *bufferedScrobbler) processUserQueue(ctx context.Context, userId string)
 	// Scrobbles are drained on a background context that no longer carries the
 	// request's authenticated user. Restore it from the buffered userId so that
 	// scrobblers relying on the user in the context (e.g. plugins) still get it.
-	if user, err := b.ds.User(ctx).Get(userId); err != nil {
+	if user, err := b.ds.User().Get(ctx, userId); err != nil {
 		log.Warn(ctx, "Could not load user for buffered scrobble", "userId", userId, "scrobbler", b.service, err)
 	} else {
 		ctx = request.WithUser(ctx, *user)
 	}
-	buffer := b.ds.ScrobbleBuffer(ctx)
+	buffer := b.ds.ScrobbleBuffer()
 	for {
-		entry, err := buffer.Next(b.service, userId)
+		entry, err := buffer.Next(ctx, b.service, userId)
 		if err != nil {
 			log.Error(ctx, "Error reading from scrobble buffer", "scrobbler", b.service, err)
 			return false, 0
@@ -210,7 +210,7 @@ func (b *bufferedScrobbler) processUserQueue(ctx context.Context, userId string)
 			log.Error(ctx, "Error sending scrobble to service. Discarding", "scrobbler", b.service,
 				"userId", entry.UserID, "artist", entry.Artist, "track", entry.Title, err)
 		}
-		err = buffer.Dequeue(entry)
+		err = buffer.Dequeue(ctx, entry)
 		if err != nil {
 			log.Error(ctx, "Error removing entry from scrobble buffer", "userId", entry.UserID,
 				"track", entry.Title, "artist", entry.Artist, "scrobbler", b.service, err)
diff --git a/core/scrobbler/buffered_scrobbler_test.go b/core/scrobbler/buffered_scrobbler_test.go
index 16172194b..6ecd92cab 100644
--- a/core/scrobbler/buffered_scrobbler_test.go
+++ b/core/scrobbler/buffered_scrobbler_test.go
@@ -26,7 +26,7 @@ var _ = Describe("BufferedScrobbler", func() {
 		ctx = context.Background()
 		buffer = tests.CreateMockedScrobbleBufferRepo()
 		userRepo := tests.CreateMockUserRepo()
-		Expect(userRepo.Put(&model.User{ID: "user1", UserName: "alice"})).To(Succeed())
+		Expect(userRepo.Put(ctx, &model.User{ID: "user1", UserName: "alice"})).To(Succeed())
 		ds = &tests.MockDataStore{
 			MockedScrobbleBuffer: buffer,
 			MockedUser:           userRepo,
@@ -55,7 +55,7 @@ var _ = Describe("BufferedScrobbler", func() {
 		track := model.MediaFile{ID: "123", Title: "Test Track"}
 		now := time.Now()
 		scrobble := Scrobble{MediaFile: track, TimeStamp: now}
-		Expect(buffer.Length()).To(Equal(int64(0)))
+		Expect(buffer.Length(ctx)).To(Equal(int64(0)))
 		Expect(scr.ScrobbleCalled.Load()).To(BeFalse())
 
 		Expect(bs.Scrobble(ctx, "user1", scrobble)).To(Succeed())
@@ -131,7 +131,7 @@ func TestBufferedScrobblerBackoffSchedule(t *testing.T) {
 		g := NewWithT(t)
 		buffer := tests.CreateMockedScrobbleBufferRepo()
 		userRepo := tests.CreateMockUserRepo()
-		g.Expect(userRepo.Put(&model.User{ID: "user1", UserName: "alice"})).To(Succeed())
+		g.Expect(userRepo.Put(t.Context(), &model.User{ID: "user1", UserName: "alice"})).To(Succeed())
 		ds := &tests.MockDataStore{MockedScrobbleBuffer: buffer, MockedUser: userRepo}
 
 		flaky := &recoveringScrobbler{}
@@ -147,7 +147,7 @@ func TestBufferedScrobblerBackoffSchedule(t *testing.T) {
 		// First attempt fires immediately on the enqueue wake and is left buffered.
 		synctest.Wait()
 		g.Expect(flaky.count.Load()).To(Equal(int32(1)))
-		g.Expect(buffer.Length()).To(Equal(int64(1)))
+		g.Expect(buffer.Length(t.Context())).To(Equal(int64(1)))
 
 		// Each subsequent retry waits exactly double the previous: 5s, 10s, 20s, 40s.
 		for i, gap := range []time.Duration{5 * time.Second, 10 * time.Second, 20 * time.Second, 40 * time.Second} {
@@ -165,10 +165,10 @@ func TestBufferedScrobblerBackoffSchedule(t *testing.T) {
 		flaky.succeed()
 		bs.sendWakeSignal()
 		synctest.Wait()
-		g.Expect(buffer.Length()).To(Equal(int64(1)), "wake during backoff drained early")
+		g.Expect(buffer.Length(t.Context())).To(Equal(int64(1)), "wake during backoff drained early")
 		time.Sleep(80 * time.Second)
 		synctest.Wait()
-		g.Expect(buffer.Length()).To(Equal(int64(0)))
+		g.Expect(buffer.Length(t.Context())).To(Equal(int64(0)))
 	})
 }
 
@@ -176,7 +176,7 @@ func TestBufferedScrobblerBackoffWindow(t *testing.T) {
 	synctest.Test(t, func(t *testing.T) {
 		buffer := tests.CreateMockedScrobbleBufferRepo()
 		userRepo := tests.CreateMockUserRepo()
-		_ = userRepo.Put(&model.User{ID: "user1", UserName: "alice"})
+		_ = userRepo.Put(t.Context(), &model.User{ID: "user1", UserName: "alice"})
 		ds := &tests.MockDataStore{MockedScrobbleBuffer: buffer, MockedUser: userRepo}
 		scr := &fakeScrobbler{Authorized: true}
 		scr.SetError(errors.Join(errors.New("boom"), ErrRetryLater))
@@ -211,7 +211,7 @@ func TestBufferedScrobblerHonorsServerDelay(t *testing.T) {
 	synctest.Test(t, func(t *testing.T) {
 		buffer := tests.CreateMockedScrobbleBufferRepo()
 		userRepo := tests.CreateMockUserRepo()
-		_ = userRepo.Put(&model.User{ID: "user1", UserName: "alice"})
+		_ = userRepo.Put(t.Context(), &model.User{ID: "user1", UserName: "alice"})
 		ds := &tests.MockDataStore{MockedScrobbleBuffer: buffer, MockedUser: userRepo}
 		scr := &fakeScrobbler{Authorized: true}
 		scr.SetError(errors.Join(errors.New("429"), &agents.RetryLaterError{RetryIn: 30 * time.Second}))
@@ -244,8 +244,8 @@ func TestBufferedScrobblerTakesTheLongestServerDelayAcrossUsers(t *testing.T) {
 	synctest.Test(t, func(t *testing.T) {
 		buffer := tests.CreateMockedScrobbleBufferRepo()
 		userRepo := tests.CreateMockUserRepo()
-		_ = userRepo.Put(&model.User{ID: "user1", UserName: "alice"})
-		_ = userRepo.Put(&model.User{ID: "user2", UserName: "bob"})
+		_ = userRepo.Put(t.Context(), &model.User{ID: "user1", UserName: "alice"})
+		_ = userRepo.Put(t.Context(), &model.User{ID: "user2", UserName: "bob"})
 		ds := &tests.MockDataStore{MockedScrobbleBuffer: buffer, MockedUser: userRepo}
 		scr := &recoveringScrobbler{delays: map[string]time.Duration{
 			"user1": 10 * time.Second,
@@ -253,8 +253,8 @@ func TestBufferedScrobblerTakesTheLongestServerDelayAcrossUsers(t *testing.T) {
 		}}
 		// Both are buffered before the drain goroutine exists: it drains once on startup, and
 		// seeing only one user there would park it on that user's delay, ignoring the other.
-		_ = buffer.Enqueue("test", "user1", "1", time.Now())
-		_ = buffer.Enqueue("test", "user2", "2", time.Now())
+		_ = buffer.Enqueue(t.Context(), "test", "user1", "1", time.Now())
+		_ = buffer.Enqueue(t.Context(), "test", "user2", "2", time.Now())
 		bs := newBufferedScrobbler(ds, scr, "test")
 		defer bs.Stop()
 
diff --git a/core/scrobbler/play_tracker.go b/core/scrobbler/play_tracker.go
index e68fcd942..541a8e92b 100644
--- a/core/scrobbler/play_tracker.go
+++ b/core/scrobbler/play_tracker.go
@@ -68,14 +68,14 @@ type ReportPlaybackParams struct {
 }
 
 type nowPlayingEntry struct {
-	ctx      context.Context
+	ctx      context.Context //nolint:containedctx // queued work item carries the request ctx to the worker
 	userId   string
 	track    *model.MediaFile
 	position int
 }
 
 type playbackReportEntry struct {
-	ctx      context.Context
+	ctx      context.Context //nolint:containedctx // queued work item carries the request ctx to the worker
 	info     PlaybackSession
 	filtered bool
 }
@@ -293,7 +293,7 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 			log.Trace(ctx, "Ignoring out-of-order starting report for playing session", "clientId", clientId, "mediaId", params.MediaId)
 			return nil
 		}
-		mf, err := p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
+		mf, err := p.ds.MediaFile().GetWithParticipants(ctx, params.MediaId)
 		if err != nil {
 			return err
 		}
@@ -328,7 +328,7 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 	case StatePlaying, StatePaused:
 		info, getErr := p.playMap.Get(clientId)
 		if getErr != nil || info.MediaFile.ID != params.MediaId {
-			mf, err := p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
+			mf, err := p.ds.MediaFile().GetWithParticipants(ctx, params.MediaId)
 			if err != nil {
 				return err
 			}
@@ -364,7 +364,7 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 		var loadedMF *model.MediaFile
 		haveVerdict := false
 		if !params.IgnoreScrobble && player.ScrobbleEnabled {
-			mf, err := p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
+			mf, err := p.ds.MediaFile().GetWithParticipants(ctx, params.MediaId)
 			if err != nil {
 				return err
 			}
@@ -409,7 +409,7 @@ func (p *playTracker) ReportPlayback(ctx context.Context, params ReportPlaybackP
 			mf := loadedMF
 			if mf == nil {
 				var mfErr error
-				mf, mfErr = p.ds.MediaFile(ctx).GetWithParticipants(params.MediaId)
+				mf, mfErr = p.ds.MediaFile().GetWithParticipants(ctx, params.MediaId)
 				if mfErr != nil {
 					return mfErr
 				}
@@ -477,7 +477,7 @@ func (p *playTracker) Submit(ctx context.Context, submissions []Submission) erro
 	success := 0
 
 	for _, s := range submissions {
-		mf, err := p.ds.MediaFile(ctx).GetWithParticipants(s.TrackID)
+		mf, err := p.ds.MediaFile().GetWithParticipants(ctx, s.TrackID)
 		if err != nil {
 			log.Error(ctx, "Cannot find track for scrobbling", "id", s.TrackID, "user", username, err)
 			continue
@@ -504,22 +504,22 @@ func (p *playTracker) Submit(ctx context.Context, submissions []Submission) erro
 
 func (p *playTracker) incPlay(ctx context.Context, track *model.MediaFile, timestamp time.Time) error {
 	return p.ds.WithTx(func(tx model.DataStore) error {
-		err := tx.MediaFile(ctx).IncPlayCount(track.ID, timestamp)
+		err := tx.MediaFile().IncPlayCount(ctx, track.ID, timestamp)
 		if err != nil {
 			return err
 		}
-		err = tx.Album(ctx).IncPlayCount(track.AlbumID, timestamp)
+		err = tx.Album().IncPlayCount(ctx, track.AlbumID, timestamp)
 		if err != nil {
 			return err
 		}
 		for _, artist := range track.Participants[model.RoleArtist] {
-			err = tx.Artist(ctx).IncPlayCount(artist.ID, timestamp)
+			err = tx.Artist().IncPlayCount(ctx, artist.ID, timestamp)
 			if err != nil {
 				return err
 			}
 		}
 		if conf.Server.EnableScrobbleHistory {
-			return tx.Scrobble(ctx).RecordScrobble(track.ID, timestamp)
+			return tx.Scrobble().RecordScrobble(ctx, track.ID, timestamp)
 		}
 		return nil
 	})
@@ -538,7 +538,7 @@ func (p *playTracker) isFilteredOut(ctx context.Context, t *model.MediaFile) boo
 		log.Warn(ctx, "Invalid scrobble filter, ignoring", "user", u.UserName, err)
 		return false
 	}
-	match, err := p.ds.MediaFile(ctx).MatchesCriteria(t.ID, c)
+	match, err := p.ds.MediaFile().MatchesCriteria(ctx, t.ID, c)
 	if err != nil {
 		log.Warn(ctx, "Error evaluating scrobble filter, ignoring", "user", u.UserName, "track", t.Title, err)
 		return false
diff --git a/core/scrobbler/play_tracker_test.go b/core/scrobbler/play_tracker_test.go
index d79233e15..045827811 100644
--- a/core/scrobbler/play_tracker_test.go
+++ b/core/scrobbler/play_tracker_test.go
@@ -55,12 +55,12 @@ type flipOnPlayRepo struct {
 	played        atomic.Bool
 }
 
-func (r *flipOnPlayRepo) IncPlayCount(id string, ts time.Time) error {
+func (r *flipOnPlayRepo) IncPlayCount(ctx context.Context, id string, ts time.Time) error {
 	r.played.Store(true)
-	return r.MediaFileRepository.IncPlayCount(id, ts)
+	return r.MediaFileRepository.IncPlayCount(ctx, id, ts)
 }
 
-func (r *flipOnPlayRepo) MatchesCriteria(string, criteria.Criteria) (bool, error) {
+func (r *flipOnPlayRepo) MatchesCriteria(context.Context, string, criteria.Criteria) (bool, error) {
 	if r.played.Load() {
 		return r.after, nil
 	}
@@ -73,9 +73,9 @@ type slowMediaFileRepo struct {
 	model.MediaFileRepository
 }
 
-func (s *slowMediaFileRepo) GetWithParticipants(id string) (*model.MediaFile, error) {
+func (s *slowMediaFileRepo) GetWithParticipants(ctx context.Context, id string) (*model.MediaFile, error) {
 	time.Sleep(5 * time.Millisecond)
-	return s.MediaFileRepository.GetWithParticipants(id)
+	return s.MediaFileRepository.GetWithParticipants(ctx, id)
 }
 
 var _ = Describe("PlayTracker", func() {
@@ -119,13 +119,13 @@ var _ = Describe("PlayTracker", func() {
 				model.RoleArtist: []model.Participant{_p("ar-1", "Artist 1"), _p("ar-2", "Artist 2")},
 			},
 		}
-		_ = ds.MediaFile(ctx).Put(&track)
+		_ = ds.MediaFile().Put(ctx, &track)
 		artist1 = model.Artist{ID: "ar-1"}
-		_ = ds.Artist(ctx).Put(&artist1)
+		_ = ds.Artist().Put(ctx, &artist1)
 		artist2 = model.Artist{ID: "ar-2"}
-		_ = ds.Artist(ctx).Put(&artist2)
+		_ = ds.Artist().Put(ctx, &artist2)
 		album = model.Album{ID: "al-1"}
-		_ = ds.Album(ctx).(*tests.MockAlbumRepo).Put(&album)
+		_ = ds.Album().(*tests.MockAlbumRepo).Put(ctx, &album)
 	})
 
 	AfterEach(func() {
@@ -149,7 +149,7 @@ var _ = Describe("PlayTracker", func() {
 		It("returns current playing music", func() {
 			track2 := track
 			track2.ID = "456"
-			_ = ds.MediaFile(ctx).Put(&track2)
+			_ = ds.MediaFile().Put(ctx, &track2)
 			ctx1 := request.WithUser(GinkgoT().Context(), model.User{UserName: "user-1"})
 			ctx1 = request.WithPlayer(ctx1, model.Player{ScrobbleEnabled: true})
 			_ = tracker.ReportPlayback(ctx1, ReportPlaybackParams{
@@ -180,7 +180,7 @@ var _ = Describe("PlayTracker", func() {
 			hidden := track
 			hidden.ID = "789"
 			hidden.LibraryID = 2
-			_ = ds.MediaFile(ctx).Put(&hidden)
+			_ = ds.MediaFile().Put(ctx, &hidden)
 			reporter := request.WithPlayer(
 				request.WithUser(GinkgoT().Context(), model.User{ID: "u-2", UserName: "user-2"}),
 				model.Player{ScrobbleEnabled: true},
@@ -199,7 +199,7 @@ var _ = Describe("PlayTracker", func() {
 			hidden := track
 			hidden.ID = "789"
 			hidden.LibraryID = 2
-			_ = ds.MediaFile(ctx).Put(&hidden)
+			_ = ds.MediaFile().Put(ctx, &hidden)
 			reporter := request.WithPlayer(
 				request.WithUser(GinkgoT().Context(), model.User{ID: "u-2", UserName: "user-2"}),
 				model.Player{ScrobbleEnabled: true},
@@ -360,7 +360,7 @@ var _ = Describe("PlayTracker", func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				mockDS := ds.(*tests.MockDataStore)
-				mockScrobble := mockDS.Scrobble(ctx).(*tests.MockScrobbleRepo)
+				mockScrobble := mockDS.Scrobble().(*tests.MockScrobbleRepo)
 				Expect(mockScrobble.RecordedScrobbles).To(HaveLen(1))
 				Expect(mockScrobble.RecordedScrobbles[0].MediaFileID).To(Equal("123"))
 				Expect(mockScrobble.RecordedScrobbles[0].UserID).To(Equal("u-1"))
@@ -376,7 +376,7 @@ var _ = Describe("PlayTracker", func() {
 
 				Expect(err).ToNot(HaveOccurred())
 				mockDS := ds.(*tests.MockDataStore)
-				mockScrobble := mockDS.Scrobble(ctx).(*tests.MockScrobbleRepo)
+				mockScrobble := mockDS.Scrobble().(*tests.MockScrobbleRepo)
 				Expect(mockScrobble.RecordedScrobbles).To(HaveLen(0))
 			})
 		})
@@ -388,7 +388,7 @@ var _ = Describe("PlayTracker", func() {
 		BeforeEach(func() {
 			ctx = request.WithUser(ctx, model.User{ID: "u-1", UserName: "user-1",
 				ScrobbleFilter: `{"all":[{"contains":{"title":"Track"}}]}`})
-			repo = ds.MediaFile(ctx).(*tests.MockMediaFileRepo)
+			repo = ds.MediaFile().(*tests.MockMediaFileRepo)
 		})
 
 		It("does not send a matching track to the agent", func() {
@@ -489,7 +489,7 @@ var _ = Describe("PlayTracker", func() {
 			var flip *flipOnPlayRepo
 
 			install := func(before, after bool) {
-				flip = &flipOnPlayRepo{MediaFileRepository: ds.MediaFile(ctx), before: before, after: after}
+				flip = &flipOnPlayRepo{MediaFileRepository: ds.MediaFile(), before: before, after: after}
 				ds.(*tests.MockDataStore).MockedMediaFile = flip
 			}
 
@@ -632,7 +632,7 @@ var _ = Describe("PlayTracker", func() {
 		It("starting replaces existing entry when switching tracks on same player", func() {
 			track2 := track
 			track2.ID = "456"
-			_ = ds.MediaFile(ctx).Put(&track2)
+			_ = ds.MediaFile().Put(ctx, &track2)
 
 			err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
 				MediaId: "123", PositionMs: 50000, State: "playing", PlaybackRate: 1.0, ClientId: defaultClientId,
@@ -659,7 +659,7 @@ var _ = Describe("PlayTracker", func() {
 
 			track2 := track
 			track2.ID = "456"
-			_ = ds.MediaFile(ctx).Put(&track2)
+			_ = ds.MediaFile().Put(ctx, &track2)
 
 			err := tracker.ReportPlayback(ctx1, ReportPlaybackParams{
 				MediaId: "123", PositionMs: 0, State: "playing", PlaybackRate: 1.0, ClientId: "client-1",
@@ -760,7 +760,7 @@ var _ = Describe("PlayTracker", func() {
 						model.RoleArtist: []model.Participant{_p("ar-1", "Artist 1")},
 					},
 				}
-				_ = ds.MediaFile(ctx).Put(&longTrack)
+				_ = ds.MediaFile().Put(ctx, &longTrack)
 
 				err := tracker.ReportPlayback(ctx, ReportPlaybackParams{
 					MediaId: "long", PositionMs: 0, State: "starting", PlaybackRate: 1.0, ClientId: defaultClientId,
@@ -958,7 +958,7 @@ var _ = Describe("PlayTracker", func() {
 			BeforeEach(func() {
 				track2 := track
 				track2.ID = "456"
-				_ = ds.MediaFile(ctx).Put(&track2)
+				_ = ds.MediaFile().Put(ctx, &track2)
 			})
 
 			It("does not downgrade an actively playing session when a late starting report arrives for the same track", func() {
@@ -1023,7 +1023,7 @@ var _ = Describe("PlayTracker", func() {
 			})
 
 			It("never lets a concurrent starting report downgrade the playing session", func() {
-				ds.(*tests.MockDataStore).MockedMediaFile = &slowMediaFileRepo{MediaFileRepository: ds.MediaFile(ctx)}
+				ds.(*tests.MockDataStore).MockedMediaFile = &slowMediaFileRepo{MediaFileRepository: ds.MediaFile()}
 				for i := range 20 {
 					raceClientId := fmt.Sprintf("race-client-%d", i)
 					var wg sync.WaitGroup
diff --git a/core/share.go b/core/share.go
index a291a060c..33c8996ef 100644
--- a/core/share.go
+++ b/core/share.go
@@ -8,7 +8,6 @@ import (
 	"time"
 
 	"github.com/Masterminds/squirrel"
-	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -21,22 +20,24 @@ import (
 
 type Share interface {
 	Load(ctx context.Context, id string) (*model.Share, error)
-	NewRepository(ctx context.Context) rest.Repository
+	Repository() model.ShareRepository
 }
 
 func NewShare(ds model.DataStore) Share {
 	return &shareService{
-		ds: ds,
+		ds:   ds,
+		repo: &shareRepositoryWrapper{ShareRepository: ds.Share(), ds: ds},
 	}
 }
 
 type shareService struct {
-	ds model.DataStore
+	ds   model.DataStore
+	repo *shareRepositoryWrapper
 }
 
 func (s *shareService) Load(ctx context.Context, id string) (*model.Share, error) {
-	repo := s.ds.Share(ctx)
-	share, err := repo.Get(id)
+	repo := s.ds.Share()
+	share, err := repo.Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
@@ -47,40 +48,29 @@ func (s *shareService) Load(ctx context.Context, id string) (*model.Share, error
 	share.LastVisitedAt = new(time.Now())
 	share.VisitCount++
 
-	err = repo.(rest.Persistable).Update(id, share, "last_visited_at", "visit_count")
+	err = repo.Update(ctx, id, *share, "last_visited_at", "visit_count")
 	if err != nil {
 		log.Warn(ctx, "Could not increment visit count for share", "share", share.ID)
 	}
 	return share, nil
 }
 
-func (s *shareService) NewRepository(ctx context.Context) rest.Repository {
-	repo := s.ds.Share(ctx)
-	wrapper := &shareRepositoryWrapper{
-		ctx:             ctx,
-		ShareRepository: repo,
-		Repository:      repo.(rest.Repository),
-		Persistable:     repo.(rest.Persistable),
-		ds:              s.ds,
-	}
-	return wrapper
+func (s *shareService) Repository() model.ShareRepository {
+	return s.repo
 }
 
 type shareRepositoryWrapper struct {
 	model.ShareRepository
-	rest.Repository
-	rest.Persistable
-	ctx context.Context
-	ds  model.DataStore
+	ds model.DataStore
 }
 
-func (r *shareRepositoryWrapper) newId() (string, error) {
+func (r *shareRepositoryWrapper) newId(ctx context.Context) (string, error) {
 	for {
 		id, err := nanoid.Generate("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz", 10)
 		if err != nil {
 			return "", err
 		}
-		exists, err := r.Exists(id)
+		exists, err := r.Exists(ctx, id)
 		if err != nil {
 			return "", err
 		}
@@ -90,14 +80,13 @@ func (r *shareRepositoryWrapper) newId() (string, error) {
 	}
 }
 
-func (r *shareRepositoryWrapper) Save(entity any) (string, error) {
-	s := entity.(*model.Share)
+func (r *shareRepositoryWrapper) Save(ctx context.Context, s *model.Share) (string, error) {
 	// Owner is always the caller; never trust a client-supplied UserID, as it
 	// determines the library-access context used to resolve the share contents.
-	if user, ok := request.UserFrom(r.ctx); ok {
+	if user, ok := request.UserFrom(ctx); ok {
 		s.UserID = user.ID
 	}
-	id, err := r.newId()
+	id, err := r.newId(ctx)
 	if err != nil {
 		return "", err
 	}
@@ -106,39 +95,39 @@ func (r *shareRepositoryWrapper) Save(entity any) (string, error) {
 		s.ExpiresAt = new(time.Now().Add(conf.Server.DefaultShareExpiration))
 	}
 
-	s.ResourceType, err = r.resourceType(s.ResourceIDs)
+	s.ResourceType, err = r.resourceType(ctx, s.ResourceIDs)
 	if err != nil {
 		return "", err
 	}
 	switch s.ResourceType {
 	case "artist":
-		s.Contents = r.contentsLabelFromArtist(s.ID, s.ResourceIDs)
+		s.Contents = r.contentsLabelFromArtist(ctx, s.ID, s.ResourceIDs)
 	case "album":
-		s.Contents = r.contentsLabelFromAlbums(s.ID, s.ResourceIDs)
+		s.Contents = r.contentsLabelFromAlbums(ctx, s.ID, s.ResourceIDs)
 	case "playlist":
-		s.Contents = r.contentsLabelFromPlaylist(s.ID, s.ResourceIDs)
+		s.Contents = r.contentsLabelFromPlaylist(ctx, s.ID, s.ResourceIDs)
 	case "media_file":
-		s.Contents = r.contentsLabelFromMediaFiles(s.ID, s.ResourceIDs)
+		s.Contents = r.contentsLabelFromMediaFiles(ctx, s.ID, s.ResourceIDs)
 	}
 
 	s.Contents = str.TruncateRunes(s.Contents, 30, "...")
 
-	return r.Persistable.Save(s)
+	return r.ShareRepository.Save(ctx, s)
 }
 
 var shareableKinds = []model.Kind{model.KindArtistArtwork, model.KindAlbumArtwork, model.KindPlaylistArtwork, model.KindMediaFileArtwork}
 
 // resourceType resolves every ID as the current user, so an entity they cannot see cannot
 // ride along behind a valid first one, and requires all IDs to be of the same kind.
-func (r *shareRepositoryWrapper) resourceType(resourceIDs string) (string, error) {
+func (r *shareRepositoryWrapper) resourceType(ctx context.Context, resourceIDs string) (string, error) {
 	resourceType := ""
 	for _, id := range strings.Split(resourceIDs, ",") {
-		kind, err := model.GetEntityKindByID(r.ctx, r.ds, id)
+		kind, err := model.GetEntityKindByID(ctx, r.ds, id)
 		if err != nil {
 			return "", err
 		}
 		if !slices.Contains(shareableKinds, kind) {
-			log.Error(r.ctx, "Invalid Resource ID", "id", id)
+			log.Error(ctx, "Invalid Resource ID", "id", id)
 			return "", model.ErrNotFound
 		}
 		if resourceType != "" && kind.String() != resourceType {
@@ -149,53 +138,53 @@ func (r *shareRepositoryWrapper) resourceType(resourceIDs string) (string, error
 	return resourceType, nil
 }
 
-func (r *shareRepositoryWrapper) Update(id string, entity any, _ ...string) error {
+func (r *shareRepositoryWrapper) Update(ctx context.Context, id string, entity model.Share, _ ...string) error {
 	cols := []string{"description", "downloadable"}
 
 	// TODO Better handling of Share expiration
-	if !V(entity.(*model.Share).ExpiresAt).IsZero() {
+	if !V(entity.ExpiresAt).IsZero() {
 		cols = append(cols, "expires_at")
 	}
-	return r.Persistable.Update(id, entity, cols...)
+	return r.ShareRepository.Update(ctx, id, entity, cols...)
 }
 
-func (r *shareRepositoryWrapper) contentsLabelFromArtist(shareID string, ids string) string {
+func (r *shareRepositoryWrapper) contentsLabelFromArtist(ctx context.Context, shareID string, ids string) string {
 	idList := strings.SplitN(ids, ",", 2)
-	a, err := r.ds.Artist(r.ctx).Get(idList[0])
+	a, err := r.ds.Artist().Get(ctx, idList[0])
 	if err != nil {
-		log.Error(r.ctx, "Error retrieving artist name for share", "share", shareID, err)
+		log.Error(ctx, "Error retrieving artist name for share", "share", shareID, err)
 		return ""
 	}
 	return a.Name
 }
 
-func (r *shareRepositoryWrapper) contentsLabelFromAlbums(shareID string, ids string) string {
+func (r *shareRepositoryWrapper) contentsLabelFromAlbums(ctx context.Context, shareID string, ids string) string {
 	idList := strings.Split(ids, ",")
-	all, err := r.ds.Album(r.ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.id": idList}})
+	all, err := r.ds.Album().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"album.id": idList}})
 	if err != nil {
-		log.Error(r.ctx, "Error retrieving album names for share", "share", shareID, err)
+		log.Error(ctx, "Error retrieving album names for share", "share", shareID, err)
 		return ""
 	}
 	names := slice.Map(all, func(a model.Album) string { return a.Name })
 	return strings.Join(names, ", ")
 }
-func (r *shareRepositoryWrapper) contentsLabelFromPlaylist(shareID string, id string) string {
-	pls, err := r.ds.Playlist(r.ctx).Get(id)
+func (r *shareRepositoryWrapper) contentsLabelFromPlaylist(ctx context.Context, shareID string, id string) string {
+	pls, err := r.ds.Playlist().Get(ctx, id)
 	if err != nil {
-		log.Error(r.ctx, "Error retrieving album names for share", "share", shareID, err)
+		log.Error(ctx, "Error retrieving album names for share", "share", shareID, err)
 		return ""
 	}
 	return pls.Name
 }
 
-func (r *shareRepositoryWrapper) contentsLabelFromMediaFiles(shareID string, ids string) string {
+func (r *shareRepositoryWrapper) contentsLabelFromMediaFiles(ctx context.Context, shareID string, ids string) string {
 	idList := strings.Split(ids, ",")
-	mfs, err := r.ds.MediaFile(r.ctx).GetAll(model.QueryOptions{Filters: squirrel.And{
+	mfs, err := r.ds.MediaFile().GetAll(ctx, model.QueryOptions{Filters: squirrel.And{
 		squirrel.Eq{"media_file.id": idList},
 		squirrel.Eq{"missing": false},
 	}})
 	if err != nil {
-		log.Error(r.ctx, "Error retrieving media files for share", "share", shareID, err)
+		log.Error(ctx, "Error retrieving media files for share", "share", shareID, err)
 		return ""
 	}
 
diff --git a/core/share_test.go b/core/share_test.go
index e6dec1b92..8ce2bf270 100644
--- a/core/share_test.go
+++ b/core/share_test.go
@@ -14,27 +14,27 @@ import (
 var _ = Describe("Share", func() {
 	var ds model.DataStore
 	var share Share
-	var mockedRepo rest.Persistable
+	var mockedRepo rest.Persistable[model.Share]
 	ctx := context.Background()
 
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
-		mockedRepo = ds.Share(ctx).(rest.Persistable)
+		mockedRepo = ds.Share().(rest.Persistable[model.Share])
 		share = NewShare(ds)
 	})
 
 	Describe("NewRepository", func() {
-		var repo rest.Persistable
+		var repo rest.Persistable[model.Share]
 
 		BeforeEach(func() {
-			repo = share.NewRepository(ctx).(rest.Persistable)
-			_ = ds.Album(ctx).Put(&model.Album{ID: "123", Name: "Album"})
+			repo = share.Repository().(rest.Persistable[model.Share])
+			_ = ds.Album().Put(ctx, &model.Album{ID: "123", Name: "Album"})
 		})
 
 		Describe("Save", func() {
 			It("it sets a random ID", func() {
 				entity := &model.Share{Description: "test", ResourceIDs: "123"}
-				id, err := repo.Save(entity)
+				id, err := repo.Save(ctx, entity)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(id).ToNot(BeEmpty())
 				Expect(entity.ID).To(Equal(id))
@@ -42,63 +42,62 @@ var _ = Describe("Share", func() {
 
 			It("assigns the logged-in user as owner, ignoring a client-supplied UserID", func() {
 				loggedInCtx := request.WithUser(context.Background(), model.User{ID: "logged-in-user"})
-				repo := share.NewRepository(loggedInCtx).(rest.Persistable)
+				repo := share.Repository().(rest.Persistable[model.Share])
 				entity := &model.Share{Description: "test", ResourceIDs: "123", UserID: "victim-user"}
-				_, err := repo.Save(entity)
+				_, err := repo.Save(loggedInCtx, entity)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(entity.UserID).To(Equal("logged-in-user"))
 			})
 
 			It("does not truncate ASCII labels shorter than 30 characters", func() {
-				_ = ds.MediaFile(ctx).Put(&model.MediaFile{ID: "456", Title: "Example Media File"})
+				_ = ds.MediaFile().Put(ctx, &model.MediaFile{ID: "456", Title: "Example Media File"})
 				entity := &model.Share{Description: "test", ResourceIDs: "456"}
-				_, err := repo.Save(entity)
+				_, err := repo.Save(ctx, entity)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(entity.Contents).To(Equal("Example Media File"))
 			})
 
 			It("truncates ASCII labels longer than 30 characters", func() {
-				_ = ds.MediaFile(ctx).Put(&model.MediaFile{ID: "789", Title: "Example Media File But The Title Is Really Long For Testing Purposes"})
+				_ = ds.MediaFile().Put(ctx, &model.MediaFile{ID: "789", Title: "Example Media File But The Title Is Really Long For Testing Purposes"})
 				entity := &model.Share{Description: "test", ResourceIDs: "789"}
-				_, err := repo.Save(entity)
+				_, err := repo.Save(ctx, entity)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(entity.Contents).To(Equal("Example Media File But The ..."))
 			})
 
 			It("does not truncate CJK labels shorter than 30 runes", func() {
-				_ = ds.MediaFile(ctx).Put(&model.MediaFile{ID: "456", Title: "青春コンプレックス"})
+				_ = ds.MediaFile().Put(ctx, &model.MediaFile{ID: "456", Title: "青春コンプレックス"})
 				entity := &model.Share{Description: "test", ResourceIDs: "456"}
-				_, err := repo.Save(entity)
+				_, err := repo.Save(ctx, entity)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(entity.Contents).To(Equal("青春コンプレックス"))
 			})
 
 			It("truncates CJK labels longer than 30 runes", func() {
-				_ = ds.MediaFile(ctx).Put(&model.MediaFile{ID: "789", Title: "私の中の幻想的世界観及びその顕現を想起させたある現実での出来事に関する一考察"})
+				_ = ds.MediaFile().Put(ctx, &model.MediaFile{ID: "789", Title: "私の中の幻想的世界観及びその顕現を想起させたある現実での出来事に関する一考察"})
 				entity := &model.Share{Description: "test", ResourceIDs: "789"}
-				_, err := repo.Save(entity)
+				_, err := repo.Save(ctx, entity)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(entity.Contents).To(Equal("私の中の幻想的世界観及びその顕現を想起させたある現実で..."))
 			})
 
 			It("fails when any of the resource IDs does not exist", func() {
 				entity := &model.Share{Description: "test", ResourceIDs: "123,missing"}
-				_, err := repo.Save(entity)
+				_, err := repo.Save(ctx, entity)
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 
 			It("fails when the resource IDs are of mixed types", func() {
-				_ = ds.MediaFile(ctx).Put(&model.MediaFile{ID: "456", Title: "Example Media File"})
+				_ = ds.MediaFile().Put(ctx, &model.MediaFile{ID: "456", Title: "Example Media File"})
 				entity := &model.Share{Description: "test", ResourceIDs: "123,456"}
-				_, err := repo.Save(entity)
+				_, err := repo.Save(ctx, entity)
 				Expect(err).To(HaveOccurred())
 			})
 		})
 
 		Describe("Update", func() {
 			It("filters out read-only fields", func() {
-				entity := &model.Share{}
-				err := repo.Update("id", entity)
+				err := repo.Update(ctx, "id", model.Share{})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mockedRepo.(*tests.MockShareRepo).Cols).To(ConsistOf("description", "downloadable"))
 			})
diff --git a/core/sonic/sonic.go b/core/sonic/sonic.go
index 67f5cc7da..8645d3d28 100644
--- a/core/sonic/sonic.go
+++ b/core/sonic/sonic.go
@@ -100,7 +100,7 @@ func (s *Sonic) GetSonicSimilarTracks(ctx context.Context, id string, count int)
 		return nil, err
 	}
 
-	mf, err := s.ds.MediaFile(ctx).Get(id)
+	mf, err := s.ds.MediaFile().Get(ctx, id)
 	if err != nil {
 		return nil, fmt.Errorf("getting media file %s: %w", id, err)
 	}
@@ -120,11 +120,11 @@ func (s *Sonic) FindSonicPath(ctx context.Context, startID, endID string, count
 		return nil, err
 	}
 
-	startMF, err := s.ds.MediaFile(ctx).Get(startID)
+	startMF, err := s.ds.MediaFile().Get(ctx, startID)
 	if err != nil {
 		return nil, fmt.Errorf("getting start media file %s: %w", startID, err)
 	}
-	endMF, err := s.ds.MediaFile(ctx).Get(endID)
+	endMF, err := s.ds.MediaFile().Get(ctx, endID)
 	if err != nil {
 		return nil, fmt.Errorf("getting end media file %s: %w", endID, err)
 	}
diff --git a/core/stream/decider.go b/core/stream/decider.go
index 886898206..38839cdf0 100644
--- a/core/stream/decider.go
+++ b/core/stream/decider.go
@@ -312,7 +312,7 @@ func (s *deciderService) computeTranscodedStream(ctx context.Context, src *Detai
 // It checks the DB first (for user-customized values), then falls back to
 // the built-in defaults, and finally to fallbackBitrate.
 func lookupDefaultBitrate(ctx context.Context, ds model.DataStore, format string) int {
-	if t, err := ds.Transcoding(ctx).FindByFormat(format); err == nil && t.DefaultBitRate > 0 {
+	if t, err := ds.Transcoding().FindByFormat(ctx, format); err == nil && t.DefaultBitRate > 0 {
 		return t.DefaultBitRate
 	}
 	for _, dt := range consts.DefaultTranscodings {
@@ -327,7 +327,7 @@ func lookupDefaultBitrate(ctx context.Context, ds model.DataStore, format string
 // It checks the DB first (for user-customized commands), then falls back to
 // the built-in default command. Returns "" if the format is unknown.
 func LookupTranscodeCommand(ctx context.Context, ds model.DataStore, format string) string {
-	t, err := ds.Transcoding(ctx).FindByFormat(format)
+	t, err := ds.Transcoding().FindByFormat(ctx, format)
 	if err == nil && t.Command != "" {
 		return t.Command
 	}
@@ -447,7 +447,7 @@ func (s *deciderService) ensureProbed(ctx context.Context, mf *model.MediaFile)
 	}
 	mf.ProbeData = string(data)
 
-	if err := s.ds.MediaFile(ctx).UpdateProbeData(mf.ID, mf.ProbeData); err != nil {
+	if err := s.ds.MediaFile().UpdateProbeData(ctx, mf.ID, mf.ProbeData); err != nil {
 		log.Error(ctx, "Failed to persist probe data", "mediaID", mf.ID, err)
 		// Don't fail the decision — we have the data in memory
 	}
diff --git a/core/stream/media_streamer.go b/core/stream/media_streamer.go
index 6db2f6338..c250b0c4e 100644
--- a/core/stream/media_streamer.go
+++ b/core/stream/media_streamer.go
@@ -133,7 +133,7 @@ func (ms *mediaStreamer) NewStream(ctx context.Context, mf *model.MediaFile, req
 }
 
 type Stream struct {
-	ctx     context.Context
+	ctx     context.Context //nolint:containedctx // stream outlives the call that built it; Read has no ctx
 	mf      *model.MediaFile
 	bitRate int
 	format  string
diff --git a/core/stream/media_streamer_test.go b/core/stream/media_streamer_test.go
index e06599208..5a4bcd480 100644
--- a/core/stream/media_streamer_test.go
+++ b/core/stream/media_streamer_test.go
@@ -36,7 +36,7 @@ var _ = Describe("MediaStreamer", func() {
 		conf.Server.CacheFolder = conf.NewDir(cacheDir)
 		conf.Server.TranscodingCacheSize = "100MB"
 		ds = &tests.MockDataStore{MockedTranscoding: &tests.MockTranscodingRepo{}}
-		ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+		ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 			{ID: "123", Path: "tests/fixtures/test.mp3", Suffix: "mp3", BitRate: 128, Duration: 257.0},
 		})
 		testCache := stream.NewTranscodingCache()
@@ -51,7 +51,7 @@ var _ = Describe("MediaStreamer", func() {
 		var mf *model.MediaFile
 		BeforeEach(func() {
 			var err error
-			mf, err = ds.MediaFile(ctx).Get("123")
+			mf, err = ds.MediaFile().Get(ctx, "123")
 			Expect(err).ToNot(HaveOccurred())
 		})
 		It("returns a seekable stream if format is 'raw'", func() {
@@ -151,7 +151,7 @@ var _ = Describe("MediaStreamer", func() {
 		var mf *model.MediaFile
 		BeforeEach(func() {
 			var err error
-			mf, err = ds.MediaFile(ctx).Get("123")
+			mf, err = ds.MediaFile().Get(ctx, "123")
 			Expect(err).ToNot(HaveOccurred())
 		})
 
diff --git a/core/user.go b/core/user.go
index f13e90167..d67d69dcb 100644
--- a/core/user.go
+++ b/core/user.go
@@ -15,62 +15,40 @@ type PluginUnloader interface {
 
 // User provides business logic for user management with plugin coordination.
 type User interface {
-	NewRepository(ctx context.Context) rest.Repository
+	Repository() rest.Repository[model.User]
 }
 
 type userService struct {
-	ds            model.DataStore
-	pluginManager PluginUnloader
+	repo *userRepositoryWrapper
 }
 
 // NewUser creates a new User service
 func NewUser(ds model.DataStore, pluginManager PluginUnloader) User {
 	return &userService{
-		ds:            ds,
-		pluginManager: pluginManager,
+		repo: &userRepositoryWrapper{
+			UserRepository: ds.User(),
+			pluginManager:  pluginManager,
+		},
 	}
 }
 
-// NewRepository returns a REST repository wrapper for user operations.
+// Repository returns a REST repository wrapper for user operations.
 // The wrapper intercepts Delete operations to coordinate plugin unloading.
-func (s *userService) NewRepository(ctx context.Context) rest.Repository {
-	repo := s.ds.User(ctx)
-	wrapper := &userRepositoryWrapper{
-		ctx:            ctx,
-		UserRepository: repo,
-		pluginManager:  s.pluginManager,
-	}
-	return wrapper
+func (s *userService) Repository() rest.Repository[model.User] {
+	return s.repo
 }
 
 type userRepositoryWrapper struct {
 	model.UserRepository
-	ctx           context.Context
 	pluginManager PluginUnloader
 }
 
-// Save implements rest.Persistable by delegating to the underlying repository.
-func (r *userRepositoryWrapper) Save(entity any) (string, error) {
-	return r.UserRepository.(rest.Persistable).Save(entity)
-}
-
-// Update implements rest.Persistable by delegating to the underlying repository.
-func (r *userRepositoryWrapper) Update(id string, entity any, cols ...string) error {
-	return r.UserRepository.(rest.Persistable).Update(id, entity, cols...)
-}
-
-// Delete implements rest.Persistable and coordinates plugin unloading.
-func (r *userRepositoryWrapper) Delete(id string) error {
-	// The underlying repository Delete handles the database cleanup
-	// including calling cleanupPluginUserReferences
-	err := r.UserRepository.(rest.Persistable).Delete(id)
-	if err != nil {
-		return err
-	}
-
-	// After successful deletion, check if any plugins were auto-disabled
-	// and need to be unloaded from memory
-	r.pluginManager.UnloadDisabledPlugins(r.ctx)
-
-	return nil
+var _ rest.Persistable[model.User] = (*userRepositoryWrapper)(nil)
+
+// Delete unloads plugins even on error: a bulk delete can fail after earlier users were removed
+// and their plugins auto-disabled.
+func (r *userRepositoryWrapper) Delete(ctx context.Context, ids ...string) error {
+	err := r.UserRepository.Delete(ctx, ids...)
+	r.pluginManager.UnloadDisabledPlugins(ctx)
+	return err
 }
diff --git a/core/user_test.go b/core/user_test.go
index b2d3117f8..880637770 100644
--- a/core/user_test.go
+++ b/core/user_test.go
@@ -29,19 +29,19 @@ var _ = Describe("User Service", func() {
 	})
 
 	Describe("NewRepository", func() {
-		It("returns a rest.Persistable", func() {
-			repo := service.NewRepository(ctx)
-			_, ok := repo.(rest.Persistable)
+		It("returns a rest.Persistable[model.User]", func() {
+			repo := service.Repository()
+			_, ok := repo.(rest.Persistable[model.User])
 			Expect(ok).To(BeTrue())
 		})
 	})
 
 	Describe("Delete", func() {
-		var repo rest.Persistable
+		var repo rest.Persistable[model.User]
 
 		BeforeEach(func() {
-			r := service.NewRepository(ctx)
-			repo = r.(rest.Persistable)
+			r := service.Repository()
+			repo = r.(rest.Persistable[model.User])
 
 			// Add a test user
 			user := &model.User{
@@ -50,37 +50,45 @@ var _ = Describe("User Service", func() {
 				IsAdmin:  false,
 			}
 			user.NewPassword = "password"
-			Expect(userRepo.Put(user)).To(Succeed())
+			Expect(userRepo.Put(ctx, user)).To(Succeed())
 		})
 
 		It("deletes the user successfully", func() {
-			err := repo.Delete("user-123")
+			err := repo.Delete(ctx, "user-123")
 			Expect(err).NotTo(HaveOccurred())
 
 			// Verify user is deleted
-			_, err = userRepo.Get("user-123")
+			_, err = userRepo.Get(ctx, "user-123")
 			Expect(err).To(Equal(model.ErrNotFound))
 		})
 
 		It("calls UnloadDisabledPlugins after successful deletion", func() {
-			err := repo.Delete("user-123")
+			err := repo.Delete(ctx, "user-123")
 			Expect(err).NotTo(HaveOccurred())
 			Expect(pluginManager.unloadCalls).To(Equal(1))
 		})
 
-		It("does not call UnloadDisabledPlugins when deletion fails", func() {
-			// Try to delete non-existent user
-			err := repo.Delete("non-existent")
-			Expect(err).To(HaveOccurred())
-			Expect(pluginManager.unloadCalls).To(Equal(0))
+		It("still calls UnloadDisabledPlugins when deletion fails", func() {
+			err := repo.Delete(ctx, "non-existent")
+			Expect(err).To(MatchError(model.ErrNotFound))
+			Expect(pluginManager.unloadCalls).To(Equal(1))
+		})
+
+		It("unloads plugins when a bulk delete fails after removing earlier users", func() {
+			err := repo.Delete(ctx, "user-123", "non-existent")
+			Expect(err).To(MatchError(model.ErrNotFound))
+
+			_, err = userRepo.Get(ctx, "user-123")
+			Expect(err).To(Equal(model.ErrNotFound))
+			Expect(pluginManager.unloadCalls).To(Equal(1))
 		})
 
 		It("returns error when repository fails", func() {
 			userRepo.Error = errors.New("database error")
-			err := repo.Delete("user-123")
+			err := repo.Delete(ctx, "user-123")
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("database error"))
-			Expect(pluginManager.unloadCalls).To(Equal(0))
+			Expect(pluginManager.unloadCalls).To(Equal(1))
 		})
 	})
 })
diff --git a/db/db.go b/db/db.go
index a9c6c4a15..66e48cede 100644
--- a/db/db.go
+++ b/db/db.go
@@ -184,7 +184,7 @@ func isSchemaEmpty(ctx context.Context, db *sql.DB) bool {
 }
 
 type logAdapter struct {
-	ctx    context.Context
+	ctx    context.Context //nolint:containedctx // goose logger interface has no ctx
 	silent bool
 }
 
diff --git a/go.mod b/go.mod
index 9a693d651..01fb0f73d 100644
--- a/go.mod
+++ b/go.mod
@@ -9,7 +9,7 @@ require (
 	github.com/Masterminds/squirrel v1.5.4
 	github.com/andybalholm/cascadia v1.3.5
 	github.com/bmatcuk/doublestar/v4 v4.10.0
-	github.com/deluan/rest v0.0.0-20260913134927-47b21f30cc12
+	github.com/deluan/rest v1.0.1
 	github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55
 	github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36
 	github.com/djherbis/atime v1.1.0
diff --git a/go.sum b/go.sum
index 4cda9a2f3..bcc1395ba 100644
--- a/go.sum
+++ b/go.sum
@@ -31,8 +31,8 @@ github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3h
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
 github.com/deluan/go-taglib v0.0.0-20260913142955-d55e0c9353cb h1:CGVY6RtDsqaleUFogGP03m3a/9OKi3ZMDr5nhm51Emk=
 github.com/deluan/go-taglib v0.0.0-20260913142955-d55e0c9353cb/go.mod h1:QGxQ4Z1IWyY9w56xNEFjYAaWE8uSxA/gneQ7RPcFJrY=
-github.com/deluan/rest v0.0.0-20260913134927-47b21f30cc12 h1:x4N/tx0XC9zcnipk5rpdI4qaG9JmovHW5HL97XYnO1I=
-github.com/deluan/rest v0.0.0-20260913134927-47b21f30cc12/go.mod h1:tSgDythFsl0QgS/PFWfIZqcJKnkADWneY80jaVRlqK8=
+github.com/deluan/rest v1.0.1 h1:Enuzzfd88C1/lG6Jqr2NgRreJoClaFuWcOuspeKWHZ8=
+github.com/deluan/rest v1.0.1/go.mod h1:r0yO0VgBWOb5Xb7aCPIedtcOuwmA2Oe5lGailC5pvc4=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55 h1:wSCnggTs2f2ji6nFwQmfwgINcmSMj0xF0oHnoyRSPe4=
 github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55/go.mod h1:ZNCLJfehvEf34B7BbLKjgpsL9lyW7q938w/GY1XgV4E=
 github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36 h1:KtPfdSST6e0vJbMzMmVqPa5mO1u8vMBlybRCW2ieXpA=
@@ -109,8 +109,6 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/wire v0.7.0 h1:JxUKI6+CVBgCO2WToKy/nQk0sS+amI9z9EjVmdaocj4=
 github.com/google/wire v0.7.0/go.mod h1:n6YbUQD9cPKTnHXEBN2DXlOp/mVADhVErcMFb0v3J18=
-github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1 h1:EGx4pi6eqNxGaHF6qqu48+N2wcFQ5qg5FXgOdqsJ5d8=
-github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
 github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
 github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
@@ -128,8 +126,6 @@ github.com/jellydator/ttlcache/v3 v3.4.1 h1:bOdXmXiycyK6E6Qjyuj5vl+/vU3SCOoDs8a8
 github.com/jellydator/ttlcache/v3 v3.4.1/go.mod h1:j7LO12PNghFg5+0v9budMAT4rDK4JY969jb9vOdOBBk=
 github.com/joshdk/go-junit v1.0.0 h1:S86cUKIdwBHWwA6xCmFlf3RTLfVXYQfvanM5Uh+K6GE=
 github.com/joshdk/go-junit v1.0.0/go.mod h1:TiiV0PqkaNfFXjEiyjWM3XXrhVyCa1K4Zfga6W52ung=
-github.com/jtolds/gls v4.20.0+incompatible h1:xdiiI2gbIgH/gLH7ADydsJ1uDOEzR8yvV7C0MuV77Wo=
-github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
 github.com/kardianos/service v1.3.0 h1:/LGy+xPP2TM+GLTiCZ2di7cy0Jd/qrawlTUfqKYFdTI=
 github.com/kardianos/service v1.3.0/go.mod h1:E4V9ufUuY82F7Ztlu1eN9VXWIQxg8NoLQlmFe0MtrXc=
 github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 h1:Z9n2FFNUXsshfwJMBgNA0RU6/i7WVaAegv3PtuIHPMs=
@@ -138,7 +134,6 @@ github.com/klauspost/compress v1.19.2 h1:hMRETovs/pu/dVWN7zIT1PGG8t509MwT6bO7XSi
 github.com/klauspost/compress v1.19.2/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/klauspost/cpuid/v2 v2.4.0 h1:S6Hrbc7+ywsr0r+RLapfGBHfyefhCTwEh3A0tV913Dw=
 github.com/klauspost/cpuid/v2 v2.4.0/go.mod h1:19jmZ9mjzoF//ddRSUsv0zfBTJWh3QJh9FNxZTMrGxU=
-github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -231,13 +226,8 @@ github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
 github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/sethvargo/go-retry v0.4.0 h1:9qy1OoIAxBL+gBYnkTnTnWle5wlfsXQlwRzIbbpdqPw=
 github.com/sethvargo/go-retry v0.4.0/go.mod h1:tvsjdKG6xfiCx4LSiUZ06kcv38xvdVQwv8R6/VnnVWg=
-github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=
 github.com/sirupsen/logrus v1.10.2 h1:G2SED73/qrAu6YwbdxOD6peLkCBI3z7L+ykJFTXJBBo=
 github.com/sirupsen/logrus v1.10.2/go.mod h1:SLEg8TqYulVKKfIGHldVp2K2aYz2DKSVBq4g/H5bR7Q=
-github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d h1:zE9ykElWQ6/NYmHa3jpm/yHnI4xSofP+UP6SpjHcSeM=
-github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
-github.com/smartystreets/goconvey v1.6.4 h1:fv0U8FUIMPNf1L9lnHLvLhgicrIVChEkdzIKYqbNC9s=
-github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
 github.com/sosodev/duration v1.3.1 h1:qtHBDMQ6lvMQsL15g4aopM4HEfOaYuhWBw3NPTtlqq4=
 github.com/sosodev/duration v1.3.1/go.mod h1:RQIBBX0+fMLc/D9+Jb/fwvVmo0eZvDDEERAikUR6SDg=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
@@ -252,7 +242,6 @@ github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3A
 github.com/spf13/viper v1.21.0 h1:x5S+0EU27Lbphp4UKm1C+1oQO+rKx36vfCoaVebLFSU=
 github.com/spf13/viper v1.21.0/go.mod h1:P0lhsswPGWD/1lZJ9ny3fYnVqxiegrlNrEmgLjbTCAY=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.1.1/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
@@ -310,7 +299,6 @@ golang.org/x/image v0.46.0 h1:b1+oYj0Jbp6K5MDT4i4/eZpYlk3V8SJhhDKh6LBHAyQ=
 golang.org/x/image v0.46.0/go.mod h1:3B3W05VGVQyuXucLINLjXKrqISASfi4Xj+iCVkLMwew=
 golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
 golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o=
-golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
 golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues=
 golang.org/x/net v0.59.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg=
@@ -318,7 +306,6 @@ golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
 golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
 golang.org/x/sys v0.0.0-20180926160741-c2ed4eda69e7/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20190422165155-953cdadca894/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20220615213510-4f61da869c0c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
 golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
@@ -333,7 +320,6 @@ golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
 golang.org/x/time v0.16.0 h1:vMb6ptszcQMkcwiRTAuNNU50gom6++Q/6gY2hDM6VDE=
 golang.org/x/time v0.16.0/go.mod h1:rVKOqvZeKvrDKTQiAHJ7wmwP0RzleSphoEA9RcdLA0s=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
-golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
 golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
 golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
 google.golang.org/appengine v1.6.5/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCIDZVag1xfc=
diff --git a/model/album.go b/model/album.go
index 114d19e1e..a43195419 100644
--- a/model/album.go
+++ b/model/album.go
@@ -1,14 +1,15 @@
 package model
 
 import (
+	"context"
 	"iter"
 	"math"
 	"sync"
 	"time"
 
-	"github.com/navidrome/navidrome/conf"
-
+	"github.com/deluan/rest"
 	"github.com/gohugoio/hashstructure"
+	"github.com/navidrome/navidrome/conf"
 )
 
 type Album struct {
@@ -137,24 +138,25 @@ type Albums []Album
 type AlbumCursor iter.Seq2[Album, error]
 
 type AlbumRepository interface {
-	CountAll(...QueryOptions) (int64, error)
-	Exists(id string) (bool, error)
-	Put(*Album) error
-	UpdateExternalInfo(*Album) error
-	Get(id string) (*Album, error)
-	GetAll(...QueryOptions) (Albums, error)
+	rest.Repository[Album]
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Exists(ctx context.Context, id string) (bool, error)
+	Put(ctx context.Context, m *Album) error
+	UpdateExternalInfo(ctx context.Context, m *Album) error
+	Get(ctx context.Context, id string) (*Album, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Albums, error)
 	// GetSoleAlbumArtistIDsInSubtrees returns the sole album artists of the albums with folders in
 	// any of the given library-relative subtrees.
-	GetSoleAlbumArtistIDsInSubtrees(lib Library, paths ...string) ([]string, error)
-	GetCursor(...QueryOptions) (AlbumCursor, error)
-	GetYears(libraryIDs ...int) ([]int, error)
+	GetSoleAlbumArtistIDsInSubtrees(ctx context.Context, lib Library, paths ...string) ([]string, error)
+	GetCursor(ctx context.Context, options ...QueryOptions) (AlbumCursor, error)
+	GetYears(ctx context.Context, libraryIDs ...int) ([]int, error)
 
 	// The following methods are used exclusively by the scanner:
-	Touch(ids ...string) error
-	TouchByMissingFolder() (int64, error)
-	GetTouchedAlbums(libID int) (AlbumCursor, error)
-	RefreshPlayCounts() (int64, error)
-	CopyAttributes(fromID, toID string, columns ...string) error
+	Touch(ctx context.Context, ids ...string) error
+	TouchByMissingFolder(ctx context.Context) (int64, error)
+	GetTouchedAlbums(ctx context.Context, libID int) (AlbumCursor, error)
+	RefreshPlayCounts(ctx context.Context) (int64, error)
+	CopyAttributes(ctx context.Context, fromID, toID string, columns ...string) error
 
 	AnnotatedRepository
 	SearchableRepository[Albums]
diff --git a/model/annotation.go b/model/annotation.go
index 5228028a6..64b8ddc17 100644
--- a/model/annotation.go
+++ b/model/annotation.go
@@ -1,6 +1,9 @@
 package model
 
-import "time"
+import (
+	"context"
+	"time"
+)
 
 type Annotations struct {
 	PlayCount     int64      `structs:"play_count"     json:"playCount,omitempty"`
@@ -13,8 +16,8 @@ type Annotations struct {
 }
 
 type AnnotatedRepository interface {
-	IncPlayCount(itemID string, ts time.Time) error
-	SetStar(starred bool, itemIDs ...string) error
-	SetRating(rating int, itemID string) error
-	ReassignAnnotation(prevID string, newID string) error
+	IncPlayCount(ctx context.Context, itemID string, ts time.Time) error
+	SetStar(ctx context.Context, starred bool, itemIDs ...string) error
+	SetRating(ctx context.Context, rating int, itemID string) error
+	ReassignAnnotation(ctx context.Context, prevID string, newID string) error
 }
diff --git a/model/artist.go b/model/artist.go
index f88b3a974..985cc6c7b 100644
--- a/model/artist.go
+++ b/model/artist.go
@@ -1,11 +1,13 @@
 package model
 
 import (
+	"context"
 	"iter"
 	"maps"
 	"slices"
 	"time"
 
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/consts"
 )
 
@@ -84,18 +86,19 @@ type ArtistIndexes []ArtistIndex
 type ArtistCursor iter.Seq2[Artist, error]
 
 type ArtistRepository interface {
-	CountAll(options ...QueryOptions) (int64, error)
-	Exists(id string) (bool, error)
-	Put(m *Artist, colsToUpdate ...string) error
-	UpdateExternalInfo(a *Artist) error
-	Get(id string) (*Artist, error)
-	GetAll(options ...QueryOptions) (Artists, error)
-	GetCursor(options ...QueryOptions) (ArtistCursor, error)
-	GetIndex(includeMissing bool, libraryIds []int, roles ...Role) (ArtistIndexes, error)
+	rest.Repository[Artist]
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Exists(ctx context.Context, id string) (bool, error)
+	Put(ctx context.Context, m *Artist, colsToUpdate ...string) error
+	UpdateExternalInfo(ctx context.Context, a *Artist) error
+	Get(ctx context.Context, id string) (*Artist, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Artists, error)
+	GetCursor(ctx context.Context, options ...QueryOptions) (ArtistCursor, error)
+	GetIndex(ctx context.Context, includeMissing bool, libraryIds []int, roles ...Role) (ArtistIndexes, error)
 
 	// The following methods are used exclusively by the scanner:
-	RefreshPlayCounts() (int64, error)
-	RefreshStats(allArtists bool) (int64, error)
+	RefreshPlayCounts(ctx context.Context) (int64, error)
+	RefreshStats(ctx context.Context, allArtists bool) (int64, error)
 
 	AnnotatedRepository
 	SearchableRepository[Artists]
diff --git a/model/artwork.go b/model/artwork.go
index 8856a35fa..d5f62ab13 100644
--- a/model/artwork.go
+++ b/model/artwork.go
@@ -1,6 +1,9 @@
 package model
 
-import "time"
+import (
+	"context"
+	"time"
+)
 
 // Artwork is one unique image, identified by the XXH3-64 hash of its bytes.
 type Artwork struct {
@@ -116,60 +119,60 @@ const (
 
 // Delete* takes the rows to remove; Purge* finds them itself and reports how many went.
 type ArtworkRepository interface {
-	GetImage(hash string) (*Artwork, error)
-	PutImage(a *Artwork) error
+	GetImage(ctx context.Context, hash string) (*Artwork, error)
+	PutImage(ctx context.Context, a *Artwork) error
 	// PurgeOrphans deletes rows referenced by no item_artwork row and older than cutoff.
-	PurgeOrphans(createdBefore time.Time) (int64, error)
-	GetItemArtwork(kind Kind, id, imageType string) (*ItemArtwork, error)
-	PutItemArtwork(ia *ItemArtwork) error
+	PurgeOrphans(ctx context.Context, createdBefore time.Time) (int64, error)
+	GetItemArtwork(ctx context.Context, kind Kind, id, imageType string) (*ItemArtwork, error)
+	PutItemArtwork(ctx context.Context, ia *ItemArtwork) error
 	// PutLastFailure records the trace of the attempt that exhausted the retry budget.
-	PutLastFailure(kind Kind, id, imageType, trace string) error
-	DeleteForItems(kind Kind, ids []string) error
+	PutLastFailure(ctx context.Context, kind Kind, id, imageType, trace string) error
+	DeleteForItems(ctx context.Context, kind Kind, ids []string) error
 	// GetInfoForItems hydrates a page in one batched query.
-	GetInfoForItems(kind Kind, ids []string) (map[string]ItemArtworkInfo, error)
+	GetInfoForItems(ctx context.Context, kind Kind, ids []string) (map[string]ItemArtworkInfo, error)
 	// GetMimeByHash returns hash -> current mime for every stored artwork.
-	GetMimeByHash() (map[string]string, error)
+	GetMimeByHash(ctx context.Context) (map[string]string, error)
 	// PurgeDanglingItems removes state rows whose entity no longer exists.
-	PurgeDanglingItems() (int64, error)
+	PurgeDanglingItems(ctx context.Context) (int64, error)
 }
 
 type ArtworkQueueRepository interface {
 	// Get returns the pending row for an item, or ErrNotFound when it is not queued.
-	Get(kind Kind, id, imageType string) (*ArtworkQueueItem, error)
+	Get(ctx context.Context, kind Kind, id, imageType string) (*ArtworkQueueItem, error)
 	// Enqueue upserts; an existing row keeps the higher priority and has its retry_at reset.
-	Enqueue(items ...ArtworkQueueItem) error
+	Enqueue(ctx context.Context, items ...ArtworkQueueItem) error
 	// EnqueuePreservingBackoff upserts like Enqueue but preserves an existing row's retry_at, so a
 	// request-triggered read-through never resets a failed resolution's backoff.
-	EnqueuePreservingBackoff(items ...ArtworkQueueItem) error
+	EnqueuePreservingBackoff(ctx context.Context, items ...ArtworkQueueItem) error
 	// EnqueueAllMissing inserts queue rows for all entities with no item_artwork row, at the given priority.
-	EnqueueAllMissing(kind Kind, priority int) (int64, error)
+	EnqueueAllMissing(ctx context.Context, kind Kind, priority int) (int64, error)
 	// EnqueueIfMissing inserts only for items with no item_artwork row yet.
-	EnqueueIfMissing(items ...ArtworkQueueItem) error
+	EnqueueIfMissing(ctx context.Context, items ...ArtworkQueueItem) error
 	// CountBySource reports how many items of a kind currently resolve from the given sources.
 	// An empty sources slice means every source; "" matches absent state, and the pseudo-source
 	// ArtworkSourceFailed matches the absent states that gave up.
-	CountBySource(kind Kind, sources []string) (int64, error)
+	CountBySource(ctx context.Context, kind Kind, sources []string) (int64, error)
 	// SourcesInUse lists the distinct sources items of a kind currently resolve from, "" included.
-	SourcesInUse(kind Kind) ([]string, error)
+	SourcesInUse(ctx context.Context, kind Kind) ([]string, error)
 	// EnqueueBySource inserts queue rows for items of a kind whose current source matches.
 	// It does not clear existing artwork state: the current image stays until it is replaced.
-	EnqueueBySource(kind Kind, sources []string, priority int) (int64, error)
+	EnqueueBySource(ctx context.Context, kind Kind, sources []string, priority int) (int64, error)
 	// DequeueBatch returns up to n items with retry_at <= now, priority desc, enqueued_at asc.
 	// Restricted to the given kinds when any are passed, so one kind cannot block another's drain.
-	DequeueBatch(n int, kinds ...string) ([]ArtworkQueueItem, error)
+	DequeueBatch(ctx context.Context, n int, kinds ...string) ([]ArtworkQueueItem, error)
 	// MarkFailedIfUnchanged applies the failure backoff only while retry_at still matches
 	// seenRetryAt, so a concurrent re-enqueue keeps its fresh eligibility.
-	MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error
+	MarkFailedIfUnchanged(ctx context.Context, kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error
 	// DeleteIfUnchanged deletes only while retry_at still matches, sparing a concurrent re-enqueue.
-	DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error
-	Count() (int64, error)
+	DeleteIfUnchanged(ctx context.Context, kind, id, imageType string, retryAt time.Time) error
+	Count(ctx context.Context) (int64, error)
 	// CountQueued reports the pending rows matching the kinds and priorities, grouped by both;
 	// an empty filter means every one.
-	CountQueued(kinds []Kind, priorities []int) ([]ArtworkQueueStat, error)
+	CountQueued(ctx context.Context, kinds []Kind, priorities []int) ([]ArtworkQueueStat, error)
 	// PurgeDangling removes queue rows whose entity no longer exists.
-	PurgeDangling() (int64, error)
+	PurgeDangling(ctx context.Context) (int64, error)
 	// PurgeQueued removes pending rows matching the kinds and priorities; an empty filter means every one.
-	PurgeQueued(kinds []Kind, priorities []int) (int64, error)
+	PurgeQueued(ctx context.Context, kinds []Kind, priorities []int) (int64, error)
 }
 
 type ArtworkQueueStat struct {
diff --git a/model/bookmark.go b/model/bookmark.go
index 7c6637ce9..768d4a462 100644
--- a/model/bookmark.go
+++ b/model/bookmark.go
@@ -1,15 +1,18 @@
 package model
 
-import "time"
+import (
+	"context"
+	"time"
+)
 
 type Bookmarkable struct {
 	BookmarkPosition int64 `structs:"-" json:"bookmarkPosition"`
 }
 
 type BookmarkableRepository interface {
-	AddBookmark(id, comment string, position int64) error
-	DeleteBookmark(id string) error
-	GetBookmarks() (Bookmarks, error)
+	AddBookmark(ctx context.Context, id, comment string, position int64) error
+	DeleteBookmark(ctx context.Context, id string) error
+	GetBookmarks(ctx context.Context) (Bookmarks, error)
 }
 
 type Bookmark struct {
diff --git a/model/datastore.go b/model/datastore.go
index 26687d5d4..6ded8c575 100644
--- a/model/datastore.go
+++ b/model/datastore.go
@@ -4,7 +4,6 @@ import (
 	"context"
 
 	"github.com/Masterminds/squirrel"
-	"github.com/deluan/rest"
 )
 
 type QueryOptions struct {
@@ -16,34 +15,28 @@ type QueryOptions struct {
 	Seed    string // for random sorting
 }
 
-type ResourceRepository interface {
-	rest.Repository
-}
-
 type DataStore interface {
-	Library(ctx context.Context) LibraryRepository
-	Folder(ctx context.Context) FolderRepository
-	Album(ctx context.Context) AlbumRepository
-	Artist(ctx context.Context) ArtistRepository
-	MediaFile(ctx context.Context) MediaFileRepository
-	Genre(ctx context.Context) GenreRepository
-	Tag(ctx context.Context) TagRepository
-	Playlist(ctx context.Context) PlaylistRepository
-	PlayQueue(ctx context.Context) PlayQueueRepository
-	Transcoding(ctx context.Context) TranscodingRepository
-	Player(ctx context.Context) PlayerRepository
-	Radio(ctx context.Context) RadioRepository
-	Share(ctx context.Context) ShareRepository
-	Property(ctx context.Context) PropertyRepository
-	User(ctx context.Context) UserRepository
-	UserProps(ctx context.Context) UserPropsRepository
-	ScrobbleBuffer(ctx context.Context) ScrobbleBufferRepository
-	Scrobble(ctx context.Context) ScrobbleRepository
-	Plugin(ctx context.Context) PluginRepository
-	Artwork(ctx context.Context) ArtworkRepository
-	ArtworkQueue(ctx context.Context) ArtworkQueueRepository
-
-	Resource(ctx context.Context, model any) ResourceRepository
+	Library() LibraryRepository
+	Folder() FolderRepository
+	Album() AlbumRepository
+	Artist() ArtistRepository
+	MediaFile() MediaFileRepository
+	Genre() GenreRepository
+	Tag() TagRepository
+	Playlist() PlaylistRepository
+	PlayQueue() PlayQueueRepository
+	Transcoding() TranscodingRepository
+	Player() PlayerRepository
+	Radio() RadioRepository
+	Share() ShareRepository
+	Property() PropertyRepository
+	User() UserRepository
+	UserProps() UserPropsRepository
+	ScrobbleBuffer() ScrobbleBufferRepository
+	Scrobble() ScrobbleRepository
+	Plugin() PluginRepository
+	Artwork() ArtworkRepository
+	ArtworkQueue() ArtworkQueueRepository
 
 	WithTx(block func(tx DataStore) error, scope ...string) error
 	WithTxImmediate(block func(tx DataStore) error, scope ...string) error
diff --git a/model/folder.go b/model/folder.go
index 5207a9db0..701fca8cd 100644
--- a/model/folder.go
+++ b/model/folder.go
@@ -1,6 +1,7 @@
 package model
 
 import (
+	"context"
 	"fmt"
 	"iter"
 	"os"
@@ -83,19 +84,19 @@ type FolderUpdateInfo struct {
 }
 
 type FolderRepository interface {
-	Get(id string) (*Folder, error)
-	GetByPath(lib Library, path string) (*Folder, error)
-	GetAll(...QueryOptions) ([]Folder, error)
-	CountAll(...QueryOptions) (int64, error)
-	GetFolderUpdateInfo(lib Library, targetPaths ...string) (map[string]FolderUpdateInfo, error)
+	Get(ctx context.Context, id string) (*Folder, error)
+	GetByPath(ctx context.Context, lib Library, path string) (*Folder, error)
+	GetAll(ctx context.Context, options ...QueryOptions) ([]Folder, error)
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	GetFolderUpdateInfo(ctx context.Context, lib Library, targetPaths ...string) (map[string]FolderUpdateInfo, error)
 	// HasAudioOutsideFolders reports whether any folder in parent's subtree
 	// (including parent itself) contains audio files and is not one of the
 	// given folder IDs.
-	HasAudioOutsideFolders(parent Folder, excludeFolderIDs []string) (bool, error)
-	Put(*Folder) error
-	MarkMissing(missing bool, ids ...string) error
-	GetTouchedWithPlaylists() (FolderCursor, error)
+	HasAudioOutsideFolders(ctx context.Context, parent Folder, excludeFolderIDs []string) (bool, error)
+	Put(ctx context.Context, f *Folder) error
+	MarkMissing(ctx context.Context, missing bool, ids ...string) error
+	GetTouchedWithPlaylists(ctx context.Context) (FolderCursor, error)
 	// GetAllWithPlaylists returns all non-missing folders with playlists, ignoring
 	// the scan-timestamp gate used by GetTouchedWithPlaylists.
-	GetAllWithPlaylists() (FolderCursor, error)
+	GetAllWithPlaylists(ctx context.Context) (FolderCursor, error)
 }
diff --git a/model/genre.go b/model/genre.go
index fa5b6ec62..147422e67 100644
--- a/model/genre.go
+++ b/model/genre.go
@@ -1,5 +1,11 @@
 package model
 
+import (
+	"context"
+
+	"github.com/deluan/rest"
+)
+
 type Genre struct {
 	ID         string `structs:"id" json:"id,omitempty" toml:"id,omitempty" yaml:"id,omitempty"`
 	Name       string `structs:"name" json:"name"`
@@ -10,6 +16,7 @@ type Genre struct {
 type Genres []Genre
 
 type GenreRepository interface {
-	GetAll(...QueryOptions) (Genres, error)
-	Get(id string) (*Genre, error)
+	rest.Repository[Genre]
+	GetAll(ctx context.Context, options ...QueryOptions) (Genres, error)
+	Get(ctx context.Context, id string) (*Genre, error)
 }
diff --git a/model/get_entity.go b/model/get_entity.go
index e5d41f1be..cfb3968ef 100644
--- a/model/get_entity.go
+++ b/model/get_entity.go
@@ -23,11 +23,11 @@ func getEntity(ctx context.Context, ds DataStore, id string) (any, Kind, error)
 		kind Kind
 		get  func() (any, error)
 	}{
-		{KindArtistArtwork, func() (any, error) { return ds.Artist(ctx).Get(id) }},
-		{KindAlbumArtwork, func() (any, error) { return ds.Album(ctx).Get(id) }},
-		{KindPlaylistArtwork, func() (any, error) { return ds.Playlist(ctx).Get(id) }},
-		{KindMediaFileArtwork, func() (any, error) { return ds.MediaFile(ctx).Get(id) }},
-		{KindRadioArtwork, func() (any, error) { return ds.Radio(ctx).Get(id) }},
+		{KindArtistArtwork, func() (any, error) { return ds.Artist().Get(ctx, id) }},
+		{KindAlbumArtwork, func() (any, error) { return ds.Album().Get(ctx, id) }},
+		{KindPlaylistArtwork, func() (any, error) { return ds.Playlist().Get(ctx, id) }},
+		{KindMediaFileArtwork, func() (any, error) { return ds.MediaFile().Get(ctx, id) }},
+		{KindRadioArtwork, func() (any, error) { return ds.Radio().Get(ctx, id) }},
 	}
 	for _, g := range getters {
 		entity, err := g.get()
diff --git a/model/get_entity_test.go b/model/get_entity_test.go
index 4e589406a..73e21a036 100644
--- a/model/get_entity_test.go
+++ b/model/get_entity_test.go
@@ -19,7 +19,7 @@ var _ = Describe("GetEntityByID", func() {
 	})
 
 	It("returns the entity matching the id", func() {
-		ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1", Name: "One"}})
 		entity, err := model.GetEntityByID(ctx, ds, "a1")
 		Expect(err).ToNot(HaveOccurred())
 		Expect(entity).To(BeAssignableToTypeOf(&model.Album{}))
@@ -32,7 +32,7 @@ var _ = Describe("GetEntityByID", func() {
 	})
 
 	It("propagates unexpected repository errors instead of reporting not-found", func() {
-		ds.Album(ctx).(*tests.MockAlbumRepo).SetError(true)
+		ds.Album().(*tests.MockAlbumRepo).SetError(true)
 		_, err := model.GetEntityByID(ctx, ds, "a1")
 		Expect(err).To(HaveOccurred())
 		Expect(err).ToNot(MatchError(model.ErrNotFound))
@@ -49,7 +49,7 @@ var _ = Describe("GetEntityKindByID", func() {
 	})
 
 	It("returns the artwork kind for the matching id", func() {
-		ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1"}})
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "a1"}})
 		kind, err := model.GetEntityKindByID(ctx, ds, "a1")
 		Expect(err).ToNot(HaveOccurred())
 		Expect(kind).To(Equal(model.KindAlbumArtwork))
diff --git a/model/library.go b/model/library.go
index aceab533a..1e33222ac 100644
--- a/model/library.go
+++ b/model/library.go
@@ -1,8 +1,10 @@
 package model
 
 import (
+	"context"
 	"time"
 
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
@@ -39,23 +41,24 @@ func (l Libraries) IDs() []int {
 }
 
 type LibraryRepository interface {
-	Get(id int) (*Library, error)
+	rest.Repository[Library]
+	Get(ctx context.Context, id int) (*Library, error)
 	// GetPath returns the path of the library with the given ID.
 	// Its implementation must be optimized to avoid unnecessary queries.
-	GetPath(id int) (string, error)
-	GetAll(...QueryOptions) (Libraries, error)
-	CountAll(...QueryOptions) (int64, error)
-	Put(l *Library, colsToUpdate ...string) error
-	Delete(id int) error
-	StoreMusicFolder() error
-	AddArtist(id int, artistID string) error
+	GetPath(ctx context.Context, id int) (string, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Libraries, error)
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Put(ctx context.Context, l *Library, colsToUpdate ...string) error
+	Delete(ctx context.Context, id int) error
+	StoreMusicFolder(ctx context.Context) error
+	AddArtist(ctx context.Context, id int, artistID string) error
 
 	// User-library association methods
-	GetUsersWithLibraryAccess(libraryID int) (Users, error)
+	GetUsersWithLibraryAccess(ctx context.Context, libraryID int) (Users, error)
 
 	// TODO These methods should be moved to a core service
-	ScanBegin(id int, fullScan bool) error
-	ScanEnd(id int) error
-	ScanInProgress() (bool, error)
-	RefreshStats(id int) error
+	ScanBegin(ctx context.Context, id int, fullScan bool) error
+	ScanEnd(ctx context.Context, id int) error
+	ScanInProgress(ctx context.Context) (bool, error)
+	RefreshStats(ctx context.Context, id int) error
 }
diff --git a/model/mediafile.go b/model/mediafile.go
index 1147eaa35..0c56b4825 100644
--- a/model/mediafile.go
+++ b/model/mediafile.go
@@ -2,6 +2,7 @@ package model
 
 import (
 	"cmp"
+	"context"
 	"encoding/json"
 	"fmt"
 	"iter"
@@ -11,6 +12,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/deluan/rest"
 	"github.com/gohugoio/hashstructure"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
@@ -537,42 +539,43 @@ func (mfs MediaFiles) ToM3U8(title string, absolutePaths bool) string {
 type MediaFileCursor iter.Seq2[MediaFile, error]
 
 type MediaFileRepository interface {
-	CountAll(options ...QueryOptions) (int64, error)
-	CountBySuffix(options ...QueryOptions) (map[string]int64, error)
-	Exists(id string) (bool, error)
-	Put(m *MediaFile) error
-	UpdateProbeData(id string, data string) error
-	Get(id string) (*MediaFile, error)
-	GetWithParticipants(id string) (*MediaFile, error)
-	GetAll(options ...QueryOptions) (MediaFiles, error)
+	rest.Repository[MediaFile]
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	CountBySuffix(ctx context.Context, options ...QueryOptions) (map[string]int64, error)
+	Exists(ctx context.Context, id string) (bool, error)
+	Put(ctx context.Context, m *MediaFile) error
+	UpdateProbeData(ctx context.Context, id string, data string) error
+	Get(ctx context.Context, id string) (*MediaFile, error)
+	GetWithParticipants(ctx context.Context, id string) (*MediaFile, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (MediaFiles, error)
 	// GetRandom returns up to options.Max media files in random order, applying the same
 	// filters as GetAll. Sort/Order are ignored.
-	GetRandom(options ...QueryOptions) (MediaFiles, error)
-	GetAllByTags(tag TagName, values []string, options ...QueryOptions) (MediaFiles, error)
+	GetRandom(ctx context.Context, options ...QueryOptions) (MediaFiles, error)
+	GetAllByTags(ctx context.Context, tag TagName, values []string, options ...QueryOptions) (MediaFiles, error)
 	// MatchesCriteria reports whether the media file matches the criteria's rule
 	// expression, using the logged user's annotations. Limit and offset are ignored.
-	MatchesCriteria(id string, c criteria.Criteria) (bool, error)
-	GetCursor(options ...QueryOptions) (MediaFileCursor, error)
+	MatchesCriteria(ctx context.Context, id string, c criteria.Criteria) (bool, error)
+	GetCursor(ctx context.Context, options ...QueryOptions) (MediaFileCursor, error)
 	// GetAlbumIDsByFolder returns the distinct IDs of albums with non-missing tracks in the given
 	// folders or their direct children.
-	GetAlbumIDsByFolder(lib Library, folderIDs ...string) ([]string, error)
+	GetAlbumIDsByFolder(ctx context.Context, lib Library, folderIDs ...string) ([]string, error)
 	// GetCursorWithArtwork streams like GetCursor, hydrated, so callers that render images don't
 	// pay the scanner's per-row cost; it uses the same id pre-pass as the other cursors.
-	GetCursorWithArtwork(options ...QueryOptions) (MediaFileCursor, error)
-	Delete(id string) error
-	DeleteMissing(ids []string) error
-	DeleteAllMissing() (int64, error)
-	FindByPaths(paths []string) (MediaFiles, error)
+	GetCursorWithArtwork(ctx context.Context, options ...QueryOptions) (MediaFileCursor, error)
+	Delete(ctx context.Context, id string) error
+	DeleteMissing(ctx context.Context, ids []string) error
+	DeleteAllMissing(ctx context.Context) (int64, error)
+	FindByPaths(ctx context.Context, paths []string) (MediaFiles, error)
 	// ReassignReferences moves annotations, bookmarks and playlist entries from prevID to newID,
 	// keeping newID's own row wherever a user has both.
-	ReassignReferences(prevID, newID string) error
+	ReassignReferences(ctx context.Context, prevID, newID string) error
 
 	// The following methods are used exclusively by the scanner:
-	MarkMissing(bool, ...*MediaFile) error
-	MarkMissingByFolder(missing bool, folderIDs ...string) error
-	GetMissingAndMatching(libId int) (MediaFileCursor, error)
-	FindRecentFilesByMBZTrackID(missing MediaFile, since time.Time) (MediaFiles, error)
-	FindRecentFilesByProperties(missing MediaFile, since time.Time) (MediaFiles, error)
+	MarkMissing(ctx context.Context, missing bool, mfs ...*MediaFile) error
+	MarkMissingByFolder(ctx context.Context, missing bool, folderIDs ...string) error
+	GetMissingAndMatching(ctx context.Context, libId int) (MediaFileCursor, error)
+	FindRecentFilesByMBZTrackID(ctx context.Context, missing MediaFile, since time.Time) (MediaFiles, error)
+	FindRecentFilesByProperties(ctx context.Context, missing MediaFile, since time.Time) (MediaFiles, error)
 
 	AnnotatedRepository
 	BookmarkableRepository
diff --git a/model/player.go b/model/player.go
index 39ea99d1a..2e4484a10 100644
--- a/model/player.go
+++ b/model/player.go
@@ -1,7 +1,10 @@
 package model
 
 import (
+	"context"
 	"time"
+
+	"github.com/deluan/rest"
 )
 
 type Player struct {
@@ -23,9 +26,11 @@ type Player struct {
 type Players []Player
 
 type PlayerRepository interface {
-	Get(id string) (*Player, error)
-	FindMatch(userId, client, userAgent string) (*Player, error)
-	Put(p *Player) error
-	CountAll(...QueryOptions) (int64, error)
-	CountByClient(...QueryOptions) (map[string]int64, error)
+	rest.Repository[Player]
+	rest.Persistable[Player]
+	Get(ctx context.Context, id string) (*Player, error)
+	FindMatch(ctx context.Context, userId, client, userAgent string) (*Player, error)
+	Put(ctx context.Context, p *Player) error
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	CountByClient(ctx context.Context, options ...QueryOptions) (map[string]int64, error)
 }
diff --git a/model/playlist.go b/model/playlist.go
index 19fedc9fa..d2ed97682 100644
--- a/model/playlist.go
+++ b/model/playlist.go
@@ -1,6 +1,7 @@
 package model
 
 import (
+	"context"
 	"iter"
 	"maps"
 	"os"
@@ -9,6 +10,7 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
@@ -206,19 +208,19 @@ type Playlists []Playlist
 type PlaylistCursor iter.Seq2[Playlist, error]
 
 type PlaylistRepository interface {
-	ResourceRepository
+	rest.Repository[Playlist]
+	rest.Persistable[Playlist]
 	AnnotatedRepository
-	CountAll(options ...QueryOptions) (int64, error)
-	Exists(id string) (bool, error)
-	Put(pls *Playlist, cols ...string) error
-	Get(id string) (*Playlist, error)
-	GetWithTracks(id string, refreshSmartPlaylist, includeMissing bool) (*Playlist, error)
-	GetAll(options ...QueryOptions) (Playlists, error)
-	GetCursor(options ...QueryOptions) (PlaylistCursor, error)
-	FindByPath(path string) (*Playlist, error)
-	Delete(id string) error
-	Tracks(playlistId string, refreshSmartPlaylist bool) PlaylistTrackRepository
-	GetPlaylists(mediaFileId string) (Playlists, error)
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Exists(ctx context.Context, id string) (bool, error)
+	Put(ctx context.Context, pls *Playlist, cols ...string) error
+	Get(ctx context.Context, id string) (*Playlist, error)
+	GetWithTracks(ctx context.Context, id string, refreshSmartPlaylist, includeMissing bool) (*Playlist, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Playlists, error)
+	GetCursor(ctx context.Context, options ...QueryOptions) (PlaylistCursor, error)
+	FindByPath(ctx context.Context, path string) (*Playlist, error)
+	Tracks(ctx context.Context, playlistId string, refreshSmartPlaylist bool) PlaylistTrackRepository
+	GetPlaylists(ctx context.Context, mediaFileId string) (Playlists, error)
 }
 
 type PlaylistTrack struct {
@@ -241,18 +243,18 @@ func (plt PlaylistTracks) MediaFiles() MediaFiles {
 type PlaylistTrackCursor iter.Seq2[PlaylistTrack, error]
 
 type PlaylistTrackRepository interface {
-	ResourceRepository
-	CountAll(options ...QueryOptions) (int64, error)
-	GetAll(options ...QueryOptions) (PlaylistTracks, error)
-	GetCursor(options ...QueryOptions) (PlaylistTrackCursor, error)
-	GetAlbumIDs(options ...QueryOptions) ([]string, error)
-	GetMediaFileIDs(options ...QueryOptions) ([]string, error)
-	Add(mediaFileIds []string) (int, error)
-	Insert(mediaFileIds []string, pos int) (int, error)
-	AddAlbums(albumIds []string) (int, error)
-	AddArtists(artistIds []string) (int, error)
-	AddDiscs(discs []DiscID) (int, error)
-	Delete(id ...string) error
-	DeleteAll() error
-	Reorder(pos int, newPos int) error
+	rest.Repository[PlaylistTrack]
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (PlaylistTracks, error)
+	GetCursor(ctx context.Context, options ...QueryOptions) (PlaylistTrackCursor, error)
+	GetAlbumIDs(ctx context.Context, options ...QueryOptions) ([]string, error)
+	GetMediaFileIDs(ctx context.Context, options ...QueryOptions) ([]string, error)
+	Add(ctx context.Context, mediaFileIds []string) (int, error)
+	Insert(ctx context.Context, mediaFileIds []string, pos int) (int, error)
+	AddAlbums(ctx context.Context, albumIds []string) (int, error)
+	AddArtists(ctx context.Context, artistIds []string) (int, error)
+	AddDiscs(ctx context.Context, discs []DiscID) (int, error)
+	Delete(ctx context.Context, id ...string) error
+	DeleteAll(ctx context.Context) error
+	Reorder(ctx context.Context, pos int, newPos int) error
 }
diff --git a/model/playqueue.go b/model/playqueue.go
index 03b562253..ddc53d7da 100644
--- a/model/playqueue.go
+++ b/model/playqueue.go
@@ -1,6 +1,7 @@
 package model
 
 import (
+	"context"
 	"time"
 )
 
@@ -18,11 +19,11 @@ type PlayQueue struct {
 type PlayQueues []PlayQueue
 
 type PlayQueueRepository interface {
-	Store(queue *PlayQueue, colNames ...string) error
+	Store(ctx context.Context, queue *PlayQueue, colNames ...string) error
 	// Retrieve returns the playqueue without loading the full MediaFiles
 	// (Items only contain IDs)
-	Retrieve(userId string) (*PlayQueue, error)
+	Retrieve(ctx context.Context, userId string) (*PlayQueue, error)
 	// RetrieveWithMediaFiles returns the playqueue with full MediaFiles loaded
-	RetrieveWithMediaFiles(userId string) (*PlayQueue, error)
-	Clear(userId string) error
+	RetrieveWithMediaFiles(ctx context.Context, userId string) (*PlayQueue, error)
+	Clear(ctx context.Context, userId string) error
 }
diff --git a/model/plugin.go b/model/plugin.go
index 18d66e305..a448a9633 100644
--- a/model/plugin.go
+++ b/model/plugin.go
@@ -1,6 +1,11 @@
 package model
 
-import "time"
+import (
+	"context"
+	"time"
+
+	"github.com/deluan/rest"
+)
 
 type Plugin struct {
 	ID               string    `structs:"id"                 json:"id"`
@@ -22,11 +27,11 @@ type Plugin struct {
 type Plugins []Plugin
 
 type PluginRepository interface {
-	ResourceRepository
-	ClearErrors() error
-	CountAll(options ...QueryOptions) (int64, error)
-	Delete(id string) error
-	Get(id string) (*Plugin, error)
-	GetAll(options ...QueryOptions) (Plugins, error)
-	Put(p *Plugin) error
+	rest.Repository[Plugin]
+	ClearErrors(ctx context.Context) error
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Delete(ctx context.Context, id string) error
+	Get(ctx context.Context, id string) (*Plugin, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Plugins, error)
+	Put(ctx context.Context, p *Plugin) error
 }
diff --git a/model/properties.go b/model/properties.go
index 06bb9ebec..24b56db26 100644
--- a/model/properties.go
+++ b/model/properties.go
@@ -1,8 +1,10 @@
 package model
 
+import "context"
+
 type PropertyRepository interface {
-	Put(id string, value string) error
-	Get(id string) (string, error)
-	Delete(id string) error
-	DefaultGet(id string, defaultValue string) (string, error)
+	Put(ctx context.Context, id string, value string) error
+	Get(ctx context.Context, id string) (string, error)
+	Delete(ctx context.Context, id string) error
+	DefaultGet(ctx context.Context, id string, defaultValue string) (string, error)
 }
diff --git a/model/radio.go b/model/radio.go
index 013a24beb..a7e0e9218 100644
--- a/model/radio.go
+++ b/model/radio.go
@@ -1,8 +1,10 @@
 package model
 
 import (
+	"context"
 	"time"
 
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/consts"
 )
 
@@ -29,11 +31,11 @@ func (r Radio) UploadedImagePath() string {
 type Radios []Radio
 
 type RadioRepository interface {
-	ResourceRepository
-	CountAll(options ...QueryOptions) (int64, error)
-	Delete(id string) error
-	Exists(id string) (bool, error)
-	Get(id string) (*Radio, error)
-	GetAll(options ...QueryOptions) (Radios, error)
-	Put(u *Radio, colsToUpdate ...string) error
+	rest.Repository[Radio]
+	rest.Persistable[Radio]
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Exists(ctx context.Context, id string) (bool, error)
+	Get(ctx context.Context, id string) (*Radio, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Radios, error)
+	Put(ctx context.Context, u *Radio, colsToUpdate ...string) error
 }
diff --git a/model/scrobble.go b/model/scrobble.go
index a8022fc16..b99d25b6a 100644
--- a/model/scrobble.go
+++ b/model/scrobble.go
@@ -1,6 +1,11 @@
 package model
 
-import "time"
+import (
+	"context"
+	"time"
+
+	"github.com/deluan/rest"
+)
 
 type Scrobble struct {
 	ID             int64  `structs:"id" json:"id"`
@@ -10,10 +15,11 @@ type Scrobble struct {
 }
 
 type ScrobbleRepository interface {
-	CountAll(options ...QueryOptions) (int64, error)
-	Get(id string) (*Scrobble, error)
-	GetAll(options ...QueryOptions) (Scrobbles, error)
-	RecordScrobble(mediaFileID string, submissionTime time.Time) error
+	rest.Repository[Scrobble]
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Get(ctx context.Context, id string) (*Scrobble, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Scrobbles, error)
+	RecordScrobble(ctx context.Context, mediaFileID string, submissionTime time.Time) error
 }
 
 type Scrobbles []Scrobble
diff --git a/model/scrobble_buffer.go b/model/scrobble_buffer.go
index 43ee2cc01..dda8dfce3 100644
--- a/model/scrobble_buffer.go
+++ b/model/scrobble_buffer.go
@@ -1,6 +1,9 @@
 package model
 
-import "time"
+import (
+	"context"
+	"time"
+)
 
 type ScrobbleEntry struct {
 	ID          string
@@ -15,10 +18,10 @@ type ScrobbleEntry struct {
 type ScrobbleEntries []ScrobbleEntry
 
 type ScrobbleBufferRepository interface {
-	UserIDs(service string) ([]string, error)
-	Enqueue(service, userId, mediaFileId string, playTime time.Time) error
-	Next(service string, userId string) (*ScrobbleEntry, error)
-	Dequeue(entry *ScrobbleEntry) error
-	Length() (int64, error)
-	Discard(service string) error
+	UserIDs(ctx context.Context, service string) ([]string, error)
+	Enqueue(ctx context.Context, service, userId, mediaFileId string, playTime time.Time) error
+	Next(ctx context.Context, service string, userId string) (*ScrobbleEntry, error)
+	Dequeue(ctx context.Context, entry *ScrobbleEntry) error
+	Length(ctx context.Context) (int64, error)
+	Discard(ctx context.Context, service string) error
 }
diff --git a/model/searchable.go b/model/searchable.go
index a64a0171c..6dba989c1 100644
--- a/model/searchable.go
+++ b/model/searchable.go
@@ -1,5 +1,7 @@
 package model
 
+import "context"
+
 type SearchableRepository[T any] interface {
-	Search(q string, options ...QueryOptions) (T, error)
+	Search(ctx context.Context, q string, options ...QueryOptions) (T, error)
 }
diff --git a/model/share.go b/model/share.go
index cf1f4cb34..952fd9759 100644
--- a/model/share.go
+++ b/model/share.go
@@ -2,9 +2,11 @@ package model
 
 import (
 	"cmp"
+	"context"
 	"strings"
 	"time"
 
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/utils/random"
 )
 
@@ -56,8 +58,10 @@ func (s Share) ToM3U8() string {
 }
 
 type ShareRepository interface {
-	Exists(id string) (bool, error)
-	Get(id string) (*Share, error)
-	GetAll(options ...QueryOptions) (Shares, error)
-	CountAll(options ...QueryOptions) (int64, error)
+	rest.Repository[Share]
+	rest.Persistable[Share]
+	Exists(ctx context.Context, id string) (bool, error)
+	Get(ctx context.Context, id string) (*Share, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Shares, error)
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
 }
diff --git a/model/tag.go b/model/tag.go
index 152b7164e..60fa252dd 100644
--- a/model/tag.go
+++ b/model/tag.go
@@ -2,10 +2,12 @@ package model
 
 import (
 	"cmp"
+	"context"
 	"fmt"
 	"slices"
 	"strings"
 
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model/id"
 	"github.com/navidrome/navidrome/utils/slice"
 	"github.com/zeebo/xxh3"
@@ -162,9 +164,10 @@ func (t Tags) Add(name TagName, v string) {
 }
 
 type TagRepository interface {
-	Add(libraryID int, tags ...Tag) error
-	UpdateCounts() error
-	GetAll(name TagName, options ...QueryOptions) (TagList, error)
+	rest.Repository[Tag]
+	Add(ctx context.Context, libraryID int, tags ...Tag) error
+	UpdateCounts(ctx context.Context) error
+	GetAll(ctx context.Context, name TagName, options ...QueryOptions) (TagList, error)
 }
 
 type TagName string
diff --git a/model/transcoding.go b/model/transcoding.go
index 9b81a7c9c..da5e09e91 100644
--- a/model/transcoding.go
+++ b/model/transcoding.go
@@ -1,5 +1,11 @@
 package model
 
+import (
+	"context"
+
+	"github.com/deluan/rest"
+)
+
 type Transcoding struct {
 	ID             string `structs:"id" json:"id"`
 	Name           string `structs:"name" json:"name"`
@@ -11,8 +17,10 @@ type Transcoding struct {
 type Transcodings []Transcoding
 
 type TranscodingRepository interface {
-	Get(id string) (*Transcoding, error)
-	CountAll(...QueryOptions) (int64, error)
-	Put(*Transcoding) error
-	FindByFormat(format string) (*Transcoding, error)
+	rest.Repository[Transcoding]
+	rest.Persistable[Transcoding]
+	Get(ctx context.Context, id string) (*Transcoding, error)
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Put(ctx context.Context, t *Transcoding) error
+	FindByFormat(ctx context.Context, format string) (*Transcoding, error)
 }
diff --git a/model/user.go b/model/user.go
index 37bdca33d..bbeb4a05d 100644
--- a/model/user.go
+++ b/model/user.go
@@ -1,7 +1,10 @@
 package model
 
 import (
+	"context"
 	"time"
+
+	"github.com/deluan/rest"
 )
 
 type User struct {
@@ -46,21 +49,21 @@ func (u User) HasLibraryAccess(libraryID int) bool {
 type Users []User
 
 type UserRepository interface {
-	ResourceRepository
-	CountAll(...QueryOptions) (int64, error)
-	Delete(id string) error
-	Get(id string) (*User, error)
-	GetAll(options ...QueryOptions) (Users, error)
-	Put(*User) error
-	UpdateLastLoginAt(id string) error
-	UpdateLastAccessAt(id string) error
-	FindFirstAdmin() (*User, error)
+	rest.Repository[User]
+	rest.Persistable[User]
+	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
+	Get(ctx context.Context, id string) (*User, error)
+	GetAll(ctx context.Context, options ...QueryOptions) (Users, error)
+	Put(ctx context.Context, u *User) error
+	UpdateLastLoginAt(ctx context.Context, id string) error
+	UpdateLastAccessAt(ctx context.Context, id string) error
+	FindFirstAdmin(ctx context.Context) (*User, error)
 	// FindByUsername must be case-insensitive
-	FindByUsername(username string) (*User, error)
+	FindByUsername(ctx context.Context, username string) (*User, error)
 	// FindByUsernameWithPassword is the same as above, but also returns the decrypted password
-	FindByUsernameWithPassword(username string) (*User, error)
+	FindByUsernameWithPassword(ctx context.Context, username string) (*User, error)
 
 	// Library association methods
-	GetUserLibraries(userID string) (Libraries, error)
-	SetUserLibraries(userID string, libraryIDs []int) error
+	GetUserLibraries(ctx context.Context, userID string) (Libraries, error)
+	SetUserLibraries(ctx context.Context, userID string, libraryIDs []int) error
 }
diff --git a/model/user_props.go b/model/user_props.go
index c2eb536ec..af19f34f1 100644
--- a/model/user_props.go
+++ b/model/user_props.go
@@ -1,8 +1,10 @@
 package model
 
+import "context"
+
 type UserPropsRepository interface {
-	Put(userId, key string, value string) error
-	Get(userId, key string) (string, error)
-	Delete(userId, key string) error
-	DefaultGet(userId, key string, defaultValue string) (string, error)
+	Put(ctx context.Context, userId, key string, value string) error
+	Get(ctx context.Context, userId, key string) (string, error)
+	Delete(ctx context.Context, userId, key string) error
+	DefaultGet(ctx context.Context, userId, key string, defaultValue string) (string, error)
 }
diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 808c880fb..8e7662b8f 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -102,9 +102,8 @@ func (as dbAlbums) toModels() model.Albums {
 	return slice.Map(as, func(a dbAlbum) model.Album { return *a.Album })
 }
 
-func NewAlbumRepository(ctx context.Context, db dbx.Builder) model.AlbumRepository {
+func NewAlbumRepository(db dbx.Builder) model.AlbumRepository {
 	r := &albumRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "album"
 	r.registerModel(&model.Album{}, albumFilters())
@@ -190,49 +189,49 @@ func allRolesFilter(_ string, value any) Sqlizer {
 	return ParticipantIDFilter("album", value)
 }
 
-func (r *albumRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	query := r.newSelect()
-	query = r.applyLibraryFilter(query)
+func (r *albumRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	query := r.newSelect(ctx)
+	query = r.applyLibraryFilter(ctx, query)
 	if filtersNeedAnnotation(r.applyFilters(query, options...)) {
-		query = r.withAnnotation(query, "album.id")
+		query = r.withAnnotation(ctx, query, "album.id")
 	}
-	return r.count(query, options...)
+	return r.count(ctx, query, options...)
 }
 
-func (r *albumRepository) Exists(id string) (bool, error) {
+func (r *albumRepository) Exists(ctx context.Context, id string) (bool, error) {
 	// The exists() helper applies no library filter, so it would report rows the caller cannot see.
-	c, err := r.count(r.applyLibraryFilter(r.newSelect().Where(Eq{"album.id": id})))
+	c, err := r.count(ctx, r.applyLibraryFilter(ctx, r.newSelect(ctx).Where(Eq{"album.id": id})))
 	return c > 0, err
 }
 
-func (r *albumRepository) Put(al *model.Album) error {
+func (r *albumRepository) Put(ctx context.Context, al *model.Album) error {
 	al.ImportedAt = time.Now()
-	id, err := r.put(al.ID, &dbAlbum{Album: al})
+	id, err := r.put(ctx, al.ID, &dbAlbum{Album: al})
 	if err != nil {
 		return err
 	}
 	al.ID = id
-	if err := r.updateParticipants(al.ID, al.Participants); err != nil {
+	if err := r.updateParticipants(ctx, al.ID, al.Participants); err != nil {
 		return err
 	}
-	return r.updateTags(al.ID, al.Tags)
+	return r.updateTags(ctx, al.ID, al.Tags)
 }
 
 // TODO Move external metadata to a separated table
-func (r *albumRepository) UpdateExternalInfo(al *model.Album) error {
-	_, err := r.put(al.ID, &dbAlbum{Album: al}, "description", "small_image_url", "medium_image_url", "large_image_url", "external_url", "external_info_updated_at")
+func (r *albumRepository) UpdateExternalInfo(ctx context.Context, al *model.Album) error {
+	_, err := r.put(ctx, al.ID, &dbAlbum{Album: al}, "description", "small_image_url", "medium_image_url", "large_image_url", "external_url", "external_info_updated_at")
 	return err
 }
 
-func (r *albumRepository) selectAlbum(options ...model.QueryOptions) SelectBuilder {
-	sql := r.newSelect(options...).Columns("album.*", "library.path as library_path", "library.name as library_name").
+func (r *albumRepository) selectAlbum(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	sql := r.newSelect(ctx, options...).Columns("album.*", "library.path as library_path", "library.name as library_name").
 		LeftJoin("library on album.library_id = library.id")
-	sql = r.withAnnotation(sql, "album.id")
-	return r.applyLibraryFilter(sql)
+	sql = r.withAnnotation(ctx, sql, "album.id")
+	return r.applyLibraryFilter(ctx, sql)
 }
 
-func (r *albumRepository) Get(id string) (*model.Album, error) {
-	res, err := r.GetAll(model.QueryOptions{Filters: Eq{"album.id": id}})
+func (r *albumRepository) Get(ctx context.Context, id string) (*model.Album, error) {
+	res, err := r.GetAll(ctx, model.QueryOptions{Filters: Eq{"album.id": id}})
 	if err != nil {
 		return nil, err
 	}
@@ -242,31 +241,31 @@ func (r *albumRepository) Get(id string) (*model.Album, error) {
 	return &res[0], nil
 }
 
-func (r *albumRepository) GetAll(options ...model.QueryOptions) (model.Albums, error) {
-	sq := r.selectAlbum(options...)
+func (r *albumRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Albums, error) {
+	sq := r.selectAlbum(ctx, options...)
 	var res dbAlbums
-	err := r.queryAll(sq, &res)
+	err := r.queryAll(ctx, sq, &res)
 	if err != nil {
 		return nil, err
 	}
 	albums := res.toModels()
-	r.hydrateArtwork(albums)
+	r.hydrateArtwork(ctx, albums)
 	return albums, nil
 }
 
-func (r *albumRepository) hydrateArtwork(albums model.Albums) {
-	hydrateItems(r.ctx, r.db, model.KindAlbumArtwork, albums,
+func (r *albumRepository) hydrateArtwork(ctx context.Context, albums model.Albums) {
+	hydrateItems(ctx, r.db, model.KindAlbumArtwork, albums,
 		func(a *model.Album) (string, *model.ItemImage) { return a.ID, &a.ItemImage })
 }
 
 // getAllIDs returns the IDs of GetAll's row set, skipping its column projection and JSON decoding.
-func (r *albumRepository) getAllIDs(options ...model.QueryOptions) ([]string, error) {
-	sq := r.applyLibraryFilter(r.newSelect(options...).Columns("album.id"))
+func (r *albumRepository) getAllIDs(ctx context.Context, options ...model.QueryOptions) ([]string, error) {
+	sq := r.applyLibraryFilter(ctx, r.newSelect(ctx, options...).Columns("album.id"))
 	if filtersNeedAnnotation(sq) {
-		sq = r.withAnnotation(sq, "album.id")
+		sq = r.withAnnotation(ctx, sq, "album.id")
 	}
 	ids := []string{}
-	err := r.queryAllSlice(sq, &ids)
+	err := r.queryAllSlice(ctx, sq, &ids)
 	return ids, err
 }
 
@@ -282,7 +281,7 @@ func SoleAlbumArtistFilter(artistID string) Sqlizer {
 
 // GetSoleAlbumArtistIDsInSubtrees matches albums by their own folder_ids, which is the resolver's
 // notion of an album's folders.
-func (r *albumRepository) GetSoleAlbumArtistIDsInSubtrees(lib model.Library, paths ...string) ([]string, error) {
+func (r *albumRepository) GetSoleAlbumArtistIDsInSubtrees(ctx context.Context, lib model.Library, paths ...string) ([]string, error) {
 	if len(paths) == 0 {
 		return nil, nil
 	}
@@ -295,7 +294,7 @@ func (r *albumRepository) GetSoleAlbumArtistIDsInSubtrees(lib model.Library, pat
 		sq := Select("distinct json_extract(participants, '$.albumartist[0].id')").From("album").
 			Where(And{soleAlbumArtistFilter, inSubtree})
 		var chunkIDs []string
-		if err := r.queryAllSlice(sq, &chunkIDs); err != nil {
+		if err := r.queryAllSlice(ctx, sq, &chunkIDs); err != nil {
 			return nil, err
 		}
 		ids = append(ids, chunkIDs...)
@@ -303,37 +302,37 @@ func (r *albumRepository) GetSoleAlbumArtistIDsInSubtrees(lib model.Library, pat
 	return ids, nil
 }
 
-func (r *albumRepository) GetCursor(options ...model.QueryOptions) (model.AlbumCursor, error) {
-	ids, err := r.getAllIDs(options...)
+func (r *albumRepository) GetCursor(ctx context.Context, options ...model.QueryOptions) (model.AlbumCursor, error) {
+	ids, err := r.getAllIDs(ctx, options...)
 	if err != nil {
 		return nil, err
 	}
 	opts := chunkOptions(options, "album.id")
 	return model.AlbumCursor(streamByIDs(ids, func(chunk []string) (model.Albums, error) {
-		return r.GetAll(opts(chunk))
+		return r.GetAll(ctx, opts(chunk))
 	})), nil
 }
 
-func (r *albumRepository) GetYears(libraryIDs ...int) ([]int, error) {
+func (r *albumRepository) GetYears(ctx context.Context, libraryIDs ...int) ([]int, error) {
 	cond := And{Gt{"max_year": 0}, Eq{"missing": false}}
 	if len(libraryIDs) > 0 {
 		cond = append(cond, Eq{"library_id": libraryIDs})
 	}
-	sq := r.applyLibraryFilter(Select("distinct max_year").From("album").Where(cond).OrderBy("max_year"))
+	sq := r.applyLibraryFilter(ctx, Select("distinct max_year").From("album").Where(cond).OrderBy("max_year"))
 	years := []int{}
-	err := r.queryAllSlice(sq, &years)
+	err := r.queryAllSlice(ctx, sq, &years)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return nil, err
 	}
 	return years, nil
 }
 
-func (r *albumRepository) CopyAttributes(fromID, toID string, columns ...string) error {
+func (r *albumRepository) CopyAttributes(ctx context.Context, fromID, toID string, columns ...string) error {
 	// Cast values to text so go-sqlite3 does not decode datetime columns as time.Time
 	// and reformat them as RFC3339 when written back.
 	sel := slice.Map(columns, func(c string) string { return fmt.Sprintf("cast(%[1]s as text) as %[1]s", c) })
 	var from dbx.NullStringMap
-	err := r.queryOne(Select(sel...).From(r.tableName).Where(Eq{"id": fromID}), &from)
+	err := r.queryOne(ctx, Select(sel...).From(r.tableName).Where(Eq{"id": fromID}), &from)
 	if err != nil {
 		return fmt.Errorf("getting album to copy fields from: %w", err)
 	}
@@ -351,35 +350,35 @@ func (r *albumRepository) CopyAttributes(fromID, toID string, columns ...string)
 	if len(to) == 0 {
 		return nil
 	}
-	_, err = r.executeSQL(Update(r.tableName).SetMap(to).Where(Eq{"id": toID}))
+	_, err = r.executeSQL(ctx, Update(r.tableName).SetMap(to).Where(Eq{"id": toID}))
 	return err
 }
 
 // Touch flags an album as being scanned by the scanner, but not necessarily updated.
 // This is used for when missing tracks are detected for an album during scan.
-func (r *albumRepository) Touch(ids ...string) error {
+func (r *albumRepository) Touch(ctx context.Context, ids ...string) error {
 	if len(ids) == 0 {
 		return nil
 	}
 	for ids := range slices.Chunk(ids, 200) {
 		upd := Update(r.tableName).Set("imported_at", time.Now()).Where(Eq{"id": ids})
-		c, err := r.executeSQL(upd)
+		c, err := r.executeSQL(ctx, upd)
 		if err != nil {
 			return fmt.Errorf("error touching albums: %w", err)
 		}
-		log.Debug(r.ctx, "Touching albums", "ids", ids, "updated", c)
+		log.Debug(ctx, "Touching albums", "ids", ids, "updated", c)
 	}
 	return nil
 }
 
 // TouchByMissingFolder touches all albums that have missing folders
-func (r *albumRepository) TouchByMissingFolder() (int64, error) {
+func (r *albumRepository) TouchByMissingFolder(ctx context.Context) (int64, error) {
 	upd := Update(r.tableName).Set("imported_at", time.Now()).
 		Where(And{
 			NotEq{"folder_ids": nil},
 			ConcatExpr("EXISTS (SELECT 1 FROM json_each(folder_ids) AS je JOIN main.folder AS f ON je.value = f.id WHERE f.missing = true)"),
 		})
-	c, err := r.executeSQL(upd)
+	c, err := r.executeSQL(ctx, upd)
 	if err != nil {
 		return 0, fmt.Errorf("error touching albums by missing folder: %w", err)
 	}
@@ -389,13 +388,13 @@ func (r *albumRepository) TouchByMissingFolder() (int64, error) {
 // GetTouchedAlbums returns all albums that were touched by the scanner for a given library, in the
 // current library scan run.
 // It does not need to load participants, as they are not used by the scanner.
-func (r *albumRepository) GetTouchedAlbums(libID int) (model.AlbumCursor, error) {
-	query := r.selectAlbum().
+func (r *albumRepository) GetTouchedAlbums(ctx context.Context, libID int) (model.AlbumCursor, error) {
+	query := r.selectAlbum(ctx).
 		Where(And{
 			Eq{"library.id": libID},
 			ConcatExpr("album.imported_at > library.last_scan_at"),
 		})
-	cursor, err := queryWithStableResults[dbAlbum](r.sqlRepository, query)
+	cursor, err := queryWithStableResults[dbAlbum](ctx, r.sqlRepository, query)
 	if err != nil {
 		return nil, err
 	}
@@ -408,7 +407,7 @@ func wrapAlbumCursor(cursor iter.Seq2[dbAlbum, error]) model.AlbumCursor {
 
 // RefreshPlayCounts updates the play count and last play date annotations for all albums, based
 // on the media files associated with them.
-func (r *albumRepository) RefreshPlayCounts() (int64, error) {
+func (r *albumRepository) RefreshPlayCounts(ctx context.Context) (int64, error) {
 	query := Expr(`
 with play_counts as (
     select user_id, album_id, sum(play_count) as total_play_count, max(play_date) as last_play_date
@@ -424,21 +423,21 @@ on conflict (user_id, item_id, item_type) do update
     set play_count = excluded.play_count,
         play_date  = excluded.play_date;
 `)
-	return r.executeSQL(query)
+	return r.executeSQL(ctx, query)
 }
 
-func (r *albumRepository) purgeEmpty(libraryIDs ...int) error {
+func (r *albumRepository) purgeEmpty(ctx context.Context, libraryIDs ...int) error {
 	del := Delete(r.tableName).Where("id not in (select distinct(album_id) from media_file)")
 	// If libraryIDs are specified, only purge albums from those libraries
 	if len(libraryIDs) > 0 {
 		del = del.Where(Eq{"library_id": libraryIDs})
 	}
-	c, err := r.executeSQL(del)
+	c, err := r.executeSQL(ctx, del)
 	if err != nil {
 		return fmt.Errorf("purging empty albums: %w", err)
 	}
 	if c > 0 {
-		log.Debug(r.ctx, "Purged empty albums", "totalDeleted", c)
+		log.Debug(ctx, "Purged empty albums", "totalDeleted", c)
 	}
 	return nil
 }
@@ -449,40 +448,32 @@ var albumSearchConfig = searchConfig{
 	MBIDFields:   []string{"mbz_album_id", "mbz_release_group_id"},
 }
 
-func (r *albumRepository) Search(q string, options ...model.QueryOptions) (model.Albums, error) {
+func (r *albumRepository) Search(ctx context.Context, q string, options ...model.QueryOptions) (model.Albums, error) {
 	var opts model.QueryOptions
 	if len(options) > 0 {
 		opts = options[0]
 	}
 	var res dbAlbums
-	err := r.doSearch(r.selectAlbum(options...), q, &res, albumSearchConfig, opts)
+	err := r.doSearch(ctx, r.selectAlbum(ctx, options...), q, &res, albumSearchConfig, opts)
 	if err != nil {
 		return nil, fmt.Errorf("searching album %q: %w", q, err)
 	}
 	albums := res.toModels()
-	r.hydrateArtwork(albums)
+	r.hydrateArtwork(ctx, albums)
 	return albums, nil
 }
 
-func (r *albumRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *albumRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *albumRepository) Read(id string) (any, error) {
-	return r.Get(id)
+func (r *albumRepository) Read(ctx context.Context, id string) (*model.Album, error) {
+	return r.Get(ctx, id)
 }
 
-func (r *albumRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
-}
-
-func (r *albumRepository) EntityName() string {
-	return "album"
-}
-
-func (r *albumRepository) NewInstance() any {
-	return &model.Album{}
+func (r *albumRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Album, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
 var _ model.AlbumRepository = (*albumRepository)(nil)
-var _ model.ResourceRepository = (*albumRepository)(nil)
+var _ rest.Repository[model.Album] = (*albumRepository)(nil)
diff --git a/persistence/album_repository_test.go b/persistence/album_repository_test.go
index c3d7f018f..7652e703d 100644
--- a/persistence/album_repository_test.go
+++ b/persistence/album_repository_test.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"sort"
+	"sync"
 	"time"
 
 	"github.com/Masterminds/squirrel"
@@ -22,11 +23,11 @@ import (
 
 // rawColumn returns a column exactly as stored, bypassing go-sqlite3's decoding of
 // `datetime` columns into time.Time.
-func rawColumn(r sqlRepository, id, column string) string {
+func rawColumn(ctx context.Context, r sqlRepository, id, column string) string {
 	var res struct{ Value string }
 	sel := squirrel.Select("cast(" + column + " as text) as value").
 		From(r.tableName).Where(squirrel.Eq{"id": id})
-	ExpectWithOffset(1, r.queryOne(sel, &res)).To(Succeed())
+	ExpectWithOffset(1, r.queryOne(ctx, sel, &res)).To(Succeed())
 	return res.Value
 }
 
@@ -36,7 +37,7 @@ var _ = Describe("AlbumRepository", func() {
 
 	BeforeEach(func() {
 		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "userid", UserName: "johndoe"})
-		albumRepo = NewAlbumRepository(ctx, GetDBXBuilder()).(*albumRepository)
+		albumRepo = NewAlbumRepository(GetDBXBuilder()).(*albumRepository)
 	})
 
 	Describe("natural sorting", func() {
@@ -48,12 +49,12 @@ var _ = Describe("AlbumRepository", func() {
 			for _, n := range []string{"foo 1", "foo 10", "foo 2", "foo 20", "foo 3"} {
 				aid := "nat-" + n
 				ids = append(ids, aid)
-				Expect(albumRepo.Put(&model.Album{
+				Expect(albumRepo.Put(ctx, &model.Album{
 					ID: aid, LibraryID: 1, Name: n, OrderAlbumName: n,
 				})).To(Succeed())
 			}
 			DeferCleanup(func() {
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": ids}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": ids}))
 			})
 		})
 
@@ -61,8 +62,8 @@ var _ = Describe("AlbumRepository", func() {
 			func(naturalSorting, preferSortTags bool, expected []string) {
 				conf.Server.EnableNaturalSorting = naturalSorting
 				conf.Server.PreferSortTags = preferSortTags
-				albumRepo = NewAlbumRepository(ctx, GetDBXBuilder()).(*albumRepository)
-				albums, err := albumRepo.GetAll(model.QueryOptions{
+				albumRepo = NewAlbumRepository(GetDBXBuilder()).(*albumRepository)
+				albums, err := albumRepo.GetAll(ctx, model.QueryOptions{
 					Sort: "name", Filters: squirrel.Eq{"album.id": ids},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -79,7 +80,7 @@ var _ = Describe("AlbumRepository", func() {
 
 	Describe("Get", func() {
 		var Get = func(id string) (*model.Album, error) {
-			album, err := albumRepo.Get(id)
+			album, err := albumRepo.Get(ctx, id)
 			if album != nil {
 				album.ImportedAt = time.Time{}
 			}
@@ -99,29 +100,29 @@ var _ = Describe("AlbumRepository", func() {
 		BeforeEach(func() {
 			srcTime = time.Date(2020, 1, 2, 3, 4, 5, 0, time.UTC)
 			dstTime = time.Date(2024, 6, 7, 8, 9, 10, 0, time.UTC)
-			Expect(albumRepo.Put(&model.Album{ID: "copy-src", Name: "src", LibraryID: 1, CreatedAt: srcTime})).To(Succeed())
-			Expect(albumRepo.Put(&model.Album{ID: "copy-dst", Name: "dst", LibraryID: 1, CreatedAt: dstTime})).To(Succeed())
-			Expect(albumRepo.Put(&model.Album{ID: "copy-zero", Name: "zero", LibraryID: 1})).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{ID: "copy-src", Name: "src", LibraryID: 1, CreatedAt: srcTime})).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{ID: "copy-dst", Name: "dst", LibraryID: 1, CreatedAt: dstTime})).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{ID: "copy-zero", Name: "zero", LibraryID: 1})).To(Succeed())
 			DeferCleanup(func() {
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"copy-src", "copy-dst", "copy-zero"}}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"copy-src", "copy-dst", "copy-zero"}}))
 			})
 		})
 		It("copies a valid created_at from source to destination", func() {
-			Expect(albumRepo.CopyAttributes("copy-src", "copy-dst", "created_at")).To(Succeed())
-			got, err := albumRepo.Get("copy-dst")
+			Expect(albumRepo.CopyAttributes(ctx, "copy-src", "copy-dst", "created_at")).To(Succeed())
+			got, err := albumRepo.Get(ctx, "copy-dst")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.CreatedAt).To(BeTemporally("~", srcTime, time.Second))
 		})
 		It("leaves destination untouched when source created_at is zero", func() {
-			Expect(albumRepo.CopyAttributes("copy-zero", "copy-dst", "created_at")).To(Succeed())
-			got, err := albumRepo.Get("copy-dst")
+			Expect(albumRepo.CopyAttributes(ctx, "copy-zero", "copy-dst", "created_at")).To(Succeed())
+			got, err := albumRepo.Get(ctx, "copy-dst")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.CreatedAt).To(BeTemporally("~", dstTime, time.Second))
 		})
 		It("returns not found and leaves destination untouched when source does not exist", func() {
-			err := albumRepo.CopyAttributes("copy-missing", "copy-dst", "created_at")
+			err := albumRepo.CopyAttributes(ctx, "copy-missing", "copy-dst", "created_at")
 			Expect(errors.Is(err, model.ErrNotFound)).To(BeTrue())
-			got, getErr := albumRepo.Get("copy-dst")
+			got, getErr := albumRepo.Get(ctx, "copy-dst")
 			Expect(getErr).ToNot(HaveOccurred())
 			Expect(got.CreatedAt).To(BeTemporally("~", dstTime, time.Second))
 		})
@@ -129,35 +130,35 @@ var _ = Describe("AlbumRepository", func() {
 			// Copying through a Go string would rewrite it as RFC3339 ("2020-01-02T03:04:05Z"),
 			// which string-sorts above every space-format timestamp and pins the album to the
 			// top of "Recently Added".
-			Expect(albumRepo.CopyAttributes("copy-src", "copy-dst", "created_at")).To(Succeed())
-			Expect(rawColumn(albumRepo.sqlRepository, "copy-dst", "created_at")).
-				To(Equal(rawColumn(albumRepo.sqlRepository, "copy-src", "created_at")))
-			Expect(rawColumn(albumRepo.sqlRepository, "copy-dst", "created_at")).ToNot(ContainSubstring("T"))
+			Expect(albumRepo.CopyAttributes(ctx, "copy-src", "copy-dst", "created_at")).To(Succeed())
+			Expect(rawColumn(ctx, albumRepo.sqlRepository, "copy-dst", "created_at")).
+				To(Equal(rawColumn(ctx, albumRepo.sqlRepository, "copy-src", "created_at")))
+			Expect(rawColumn(ctx, albumRepo.sqlRepository, "copy-dst", "created_at")).ToNot(ContainSubstring("T"))
 		})
 	})
 
 	Describe("GetCursor", func() {
 		It("yields the same albums as GetAll", func() {
 			opts := model.QueryOptions{Sort: "name"}
-			want, err := albumRepo.GetAll(opts)
+			want, err := albumRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(collectCursor(albumRepo.GetCursor(opts))).To(Equal([]model.Album(want)))
+			Expect(collectCursor(albumRepo.GetCursor(ctx, opts))).To(Equal([]model.Album(want)))
 		})
 
 		It("honors Max/Offset like GetAll", func() {
 			opts := model.QueryOptions{Sort: "name", Max: 2, Offset: 1}
-			want, err := albumRepo.GetAll(opts)
+			want, err := albumRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(collectCursor(albumRepo.GetCursor(opts))).To(Equal([]model.Album(want)))
+			Expect(collectCursor(albumRepo.GetCursor(ctx, opts))).To(Equal([]model.Album(want)))
 		})
 	})
 
 	Describe("getAllIDs", func() {
 		It("returns the same id set as GetAll", func() {
-			want, err := albumRepo.GetAll()
+			want, err := albumRepo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).ToNot(BeEmpty())
-			ids, err := albumRepo.getAllIDs()
+			ids, err := albumRepo.getAllIDs(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(ConsistOf(slice.Map(want, func(a model.Album) string { return a.ID })))
 		})
@@ -165,13 +166,13 @@ var _ = Describe("AlbumRepository", func() {
 
 	Describe("GetSoleAlbumArtistIDsInSubtrees", func() {
 		It("returns the sole album artists of albums with folders in the subtree", func() {
-			folderRepo := newFolderRepository(ctx, GetDBXBuilder())
-			lib, err := NewLibraryRepository(ctx, GetDBXBuilder()).Get(1)
+			folderRepo := newFolderRepository(GetDBXBuilder())
+			lib, err := NewLibraryRepository(GetDBXBuilder()).Get(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
 			inTree := model.NewFolder(*lib, "SubtreeAlbums/Artist")
 			outTree := model.NewFolder(*lib, "OtherTree/Artist")
-			Expect(folderRepo.Put(inTree)).To(Succeed())
-			Expect(folderRepo.Put(outTree)).To(Succeed())
+			Expect(folderRepo.Put(ctx, inTree)).To(Succeed())
+			Expect(folderRepo.Put(ctx, outTree)).To(Succeed())
 
 			// album_artist_id is deliberately wrong: the artist must come from participants
 			inAl := model.Album{ID: "subtree-in-al", Name: "In", LibraryID: 1, AlbumArtistID: "999", FolderIDs: []string{inTree.ID},
@@ -181,34 +182,34 @@ var _ = Describe("AlbumRepository", func() {
 			duoAl := model.Album{ID: "subtree-duo-al", Name: "Duo", LibraryID: 1, AlbumArtistID: "5", FolderIDs: []string{inTree.ID},
 				Participants: model.Participants{model.RoleAlbumArtist: []model.Participant{{Artist: artistPunctuation}, {Artist: artistBeatles}}}}
 			for _, al := range []model.Album{inAl, outAl, duoAl} {
-				Expect(albumRepo.Put(&al)).To(Succeed())
+				Expect(albumRepo.Put(ctx, &al)).To(Succeed())
 			}
 			DeferCleanup(func() {
 				_, _ = GetDBXBuilder().NewQuery("DELETE FROM album WHERE id LIKE 'subtree-%'").Execute()
 				_, _ = GetDBXBuilder().NewQuery("DELETE FROM folder WHERE path LIKE 'SubtreeAlbums%' OR path LIKE 'OtherTree%'").Execute()
 			})
 
-			ids, err := albumRepo.GetSoleAlbumArtistIDsInSubtrees(*lib, "SubtreeAlbums")
+			ids, err := albumRepo.GetSoleAlbumArtistIDsInSubtrees(ctx, *lib, "SubtreeAlbums")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(ConsistOf("2")) // sole artist in the subtree; the duo and the outside album are excluded
 		})
 
 		It("stays under SQLite's expression tree depth limit with many paths", func() {
-			lib, err := NewLibraryRepository(ctx, GetDBXBuilder()).Get(1)
+			lib, err := NewLibraryRepository(GetDBXBuilder()).Get(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
 			paths := make([]string, 200)
 			for i := range paths {
 				paths[i] = fmt.Sprintf("DepthProbe/Folder%d", i)
 			}
 
-			_, err = albumRepo.GetSoleAlbumArtistIDsInSubtrees(*lib, paths...)
+			_, err = albumRepo.GetSoleAlbumArtistIDsInSubtrees(ctx, *lib, paths...)
 			Expect(err).ToNot(HaveOccurred())
 		})
 
 		It("returns nothing when given no paths", func() {
-			lib, err := NewLibraryRepository(ctx, GetDBXBuilder()).Get(1)
+			lib, err := NewLibraryRepository(GetDBXBuilder()).Get(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
-			ids, err := albumRepo.GetSoleAlbumArtistIDsInSubtrees(*lib)
+			ids, err := albumRepo.GetSoleAlbumArtistIDsInSubtrees(ctx, *lib)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(BeEmpty())
 		})
@@ -221,13 +222,13 @@ var _ = Describe("AlbumRepository", func() {
 				Participants: model.Participants{model.RoleAlbumArtist: []model.Participant{{Artist: artistKraftwerk}}}}
 			duo := model.Album{ID: "duo-artist-al", Name: "Duo", LibraryID: 1, AlbumArtistID: "999",
 				Participants: model.Participants{model.RoleAlbumArtist: []model.Participant{{Artist: artistKraftwerk}, {Artist: artistBeatles}}}}
-			Expect(albumRepo.Put(&sole)).To(Succeed())
-			Expect(albumRepo.Put(&duo)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &sole)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &duo)).To(Succeed())
 			DeferCleanup(func() {
 				_, _ = GetDBXBuilder().NewQuery("DELETE FROM album WHERE id IN ('sole-artist-al', 'duo-artist-al')").Execute()
 			})
 
-			als, err := albumRepo.GetAll(model.QueryOptions{Filters: SoleAlbumArtistFilter("2")})
+			als, err := albumRepo.GetAll(ctx, model.QueryOptions{Filters: SoleAlbumArtistFilter("2")})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(als).To(HaveLen(1))
 			Expect(als[0].ID).To(Equal(sole.ID))
@@ -236,7 +237,7 @@ var _ = Describe("AlbumRepository", func() {
 
 	Describe("GetAll", func() {
 		var GetAll = func(opts ...model.QueryOptions) (model.Albums, error) {
-			albums, err := albumRepo.GetAll(opts...)
+			albums, err := albumRepo.GetAll(ctx, opts...)
 			for i := range albums {
 				albums[i].ImportedAt = time.Time{}
 			}
@@ -280,7 +281,7 @@ var _ = Describe("AlbumRepository", func() {
 
 	Describe("recently_added sort", func() {
 		AfterEach(func() {
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").
 				Where(squirrel.Like{"id": "ra-%"}))
 		})
 
@@ -299,18 +300,18 @@ var _ = Describe("AlbumRepository", func() {
 			// Same second, different nanoseconds: datetime() would tie these.
 			earlier := &model.Album{LibraryID: 1, ID: "ra-earlier", Name: "Earlier"}
 			later := &model.Album{LibraryID: 1, ID: "ra-later", Name: "Later"}
-			Expect(albumRepo.Put(earlier)).To(Succeed())
-			Expect(albumRepo.Put(later)).To(Succeed())
-			_, err := albumRepo.executeSQL(squirrel.Update("album").
+			Expect(albumRepo.Put(ctx, earlier)).To(Succeed())
+			Expect(albumRepo.Put(ctx, later)).To(Succeed())
+			_, err := albumRepo.executeSQL(ctx, squirrel.Update("album").
 				Set("created_at", "2024-01-15 10:00:00.100000000+00:00").
 				Where(squirrel.Eq{"id": "ra-earlier"}))
 			Expect(err).ToNot(HaveOccurred())
-			_, err = albumRepo.executeSQL(squirrel.Update("album").
+			_, err = albumRepo.executeSQL(ctx, squirrel.Update("album").
 				Set("created_at", "2024-01-15 10:00:00.900000000+00:00").
 				Where(squirrel.Eq{"id": "ra-later"}))
 			Expect(err).ToNot(HaveOccurred())
 
-			albums, err := albumRepo.GetAll(model.QueryOptions{Sort: "recently_added", Order: "desc"})
+			albums, err := albumRepo.GetAll(ctx, model.QueryOptions{Sort: "recently_added", Order: "desc"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(indexOf(albums, "ra-later")).To(BeNumerically("<", indexOf(albums, "ra-earlier")),
 				".900 should sort before .100 in desc order")
@@ -321,17 +322,17 @@ var _ = Describe("AlbumRepository", func() {
 			// match the unfiltered order (the inversion mechanism in #5673).
 			ids := []string{"ra-t1", "ra-t2", "ra-t3", "ra-t4"}
 			for _, aid := range ids {
-				Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: aid, Name: aid})).To(Succeed())
+				Expect(albumRepo.Put(ctx, &model.Album{LibraryID: 1, ID: aid, Name: aid})).To(Succeed())
 			}
-			_, err := albumRepo.executeSQL(squirrel.Update("album").
+			_, err := albumRepo.executeSQL(ctx, squirrel.Update("album").
 				Set("created_at", "2024-02-20 12:00:00+00:00").
 				Where(squirrel.Eq{"id": ids}))
 			Expect(err).ToNot(HaveOccurred())
 
-			all, err := albumRepo.GetAll(model.QueryOptions{Sort: "recently_added", Order: "desc"})
+			all, err := albumRepo.GetAll(ctx, model.QueryOptions{Sort: "recently_added", Order: "desc"})
 			Expect(err).ToNot(HaveOccurred())
 
-			subset, err := albumRepo.GetAll(model.QueryOptions{
+			subset, err := albumRepo.GetAll(ctx, model.QueryOptions{
 				Sort: "recently_added", Order: "desc",
 				Filters: squirrel.Eq{"album.id": []string{"ra-t1", "ra-t3"}}})
 			Expect(err).ToNot(HaveOccurred())
@@ -348,20 +349,20 @@ var _ = Describe("AlbumRepository", func() {
 		BeforeEach(func() {
 			// Create album without any annotation (no star, no rating)
 			albumWithoutAnnotation = model.Album{ID: "no-annotation-album", Name: "No Annotation", LibraryID: 1}
-			Expect(albumRepo.Put(&albumWithoutAnnotation)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &albumWithoutAnnotation)).To(Succeed())
 		})
 
 		AfterEach(func() {
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": albumWithoutAnnotation.ID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": albumWithoutAnnotation.ID}))
 		})
 
 		Describe("starred", func() {
 			It("false includes items without annotations", func() {
-				res, err := albumRepo.ReadAll(rest.QueryOptions{
+				res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
 					Filters: map[string]any{"starred": "false"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				albums := res.(model.Albums)
+				albums := res
 
 				var found bool
 				for _, a := range albums {
@@ -374,11 +375,11 @@ var _ = Describe("AlbumRepository", func() {
 			})
 
 			It("true excludes items without annotations", func() {
-				res, err := albumRepo.ReadAll(rest.QueryOptions{
+				res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
 					Filters: map[string]any{"starred": "true"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				albums := res.(model.Albums)
+				albums := res
 
 				for _, a := range albums {
 					Expect(a.ID).ToNot(Equal(albumWithoutAnnotation.ID))
@@ -388,11 +389,11 @@ var _ = Describe("AlbumRepository", func() {
 
 		Describe("has_rating", func() {
 			It("false includes items without annotations", func() {
-				res, err := albumRepo.ReadAll(rest.QueryOptions{
+				res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
 					Filters: map[string]any{"has_rating": "false"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				albums := res.(model.Albums)
+				albums := res
 
 				var found bool
 				for _, a := range albums {
@@ -405,11 +406,11 @@ var _ = Describe("AlbumRepository", func() {
 			})
 
 			It("true excludes items without annotations", func() {
-				res, err := albumRepo.ReadAll(rest.QueryOptions{
+				res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
 					Filters: map[string]any{"has_rating": "true"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				albums := res.(model.Albums)
+				albums := res
 
 				for _, a := range albums {
 					Expect(a.ID).ToNot(Equal(albumWithoutAnnotation.ID))
@@ -425,12 +426,12 @@ var _ = Describe("AlbumRepository", func() {
 				conf.Server.AlbumPlayCountMode = consts.AlbumPlayCountModeAbsolute
 
 				newID := id.NewRandom()
-				Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "name", SongCount: songCount})).To(Succeed())
+				Expect(albumRepo.Put(ctx, &model.Album{LibraryID: 1, ID: newID, Name: "name", SongCount: songCount})).To(Succeed())
 				for range playCount {
-					Expect(albumRepo.IncPlayCount(newID, time.Now())).To(Succeed())
+					Expect(albumRepo.IncPlayCount(ctx, newID, time.Now())).To(Succeed())
 				}
 
-				album, err := albumRepo.Get(newID)
+				album, err := albumRepo.Get(ctx, newID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(album.PlayCount).To(Equal(int64(expected)))
 			},
@@ -448,12 +449,12 @@ var _ = Describe("AlbumRepository", func() {
 				conf.Server.AlbumPlayCountMode = consts.AlbumPlayCountModeNormalized
 
 				newID := id.NewRandom()
-				Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "name", SongCount: songCount})).To(Succeed())
+				Expect(albumRepo.Put(ctx, &model.Album{LibraryID: 1, ID: newID, Name: "name", SongCount: songCount})).To(Succeed())
 				for range playCount {
-					Expect(albumRepo.IncPlayCount(newID, time.Now())).To(Succeed())
+					Expect(albumRepo.IncPlayCount(ctx, newID, time.Now())).To(Succeed())
 				}
 
-				album, err := albumRepo.Get(newID)
+				album, err := albumRepo.Get(ctx, newID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(album.PlayCount).To(Equal(int64(expected)))
 			},
@@ -470,83 +471,79 @@ var _ = Describe("AlbumRepository", func() {
 	Describe("Album.AverageRating", func() {
 		It("returns 0 when no ratings exist", func() {
 			newID := id.NewRandom()
-			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "no ratings album"})).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{LibraryID: 1, ID: newID, Name: "no ratings album"})).To(Succeed())
 
-			album, err := albumRepo.Get(newID)
+			album, err := albumRepo.Get(ctx, newID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(album.AverageRating).To(Equal(0.0))
 
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
 		})
 
 		It("returns the user's rating as average when only one user rated", func() {
 			newID := id.NewRandom()
-			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "single rating album"})).To(Succeed())
-			Expect(albumRepo.SetRating(4, newID)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{LibraryID: 1, ID: newID, Name: "single rating album"})).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 4, newID)).To(Succeed())
 
-			album, err := albumRepo.Get(newID)
+			album, err := albumRepo.Get(ctx, newID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(album.AverageRating).To(Equal(4.0))
 
-			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
 		})
 
 		It("calculates average across multiple users", func() {
 			newID := id.NewRandom()
-			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "multi rating album"})).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{LibraryID: 1, ID: newID, Name: "multi rating album"})).To(Succeed())
 
-			Expect(albumRepo.SetRating(4, newID)).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 4, newID)).To(Succeed())
 
 			user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
-			user2Repo := NewAlbumRepository(user2Ctx, GetDBXBuilder()).(*albumRepository)
-			Expect(user2Repo.SetRating(5, newID)).To(Succeed())
+			Expect(albumRepo.SetRating(user2Ctx, 5, newID)).To(Succeed())
 
-			album, err := albumRepo.Get(newID)
+			album, err := albumRepo.Get(ctx, newID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(album.AverageRating).To(Equal(4.5))
 
-			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
 		})
 
 		It("excludes zero ratings from average calculation", func() {
 			newID := id.NewRandom()
-			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "zero rating excluded album"})).To(Succeed())
-			Expect(albumRepo.SetRating(3, newID)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{LibraryID: 1, ID: newID, Name: "zero rating excluded album"})).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 3, newID)).To(Succeed())
 
 			user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
-			user2Repo := NewAlbumRepository(user2Ctx, GetDBXBuilder()).(*albumRepository)
-			Expect(user2Repo.SetRating(0, newID)).To(Succeed())
+			Expect(albumRepo.SetRating(user2Ctx, 0, newID)).To(Succeed())
 
-			album, err := albumRepo.Get(newID)
+			album, err := albumRepo.Get(ctx, newID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(album.AverageRating).To(Equal(3.0))
 
-			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
 		})
 
 		It("rounds to 2 decimal places", func() {
 			newID := id.NewRandom()
-			Expect(albumRepo.Put(&model.Album{LibraryID: 1, ID: newID, Name: "rounding test album"})).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{LibraryID: 1, ID: newID, Name: "rounding test album"})).To(Succeed())
 
-			Expect(albumRepo.SetRating(5, newID)).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 5, newID)).To(Succeed())
 
 			user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
-			user2Repo := NewAlbumRepository(user2Ctx, GetDBXBuilder()).(*albumRepository)
-			Expect(user2Repo.SetRating(4, newID)).To(Succeed())
+			Expect(albumRepo.SetRating(user2Ctx, 4, newID)).To(Succeed())
 
 			user3Ctx := request.WithUser(GinkgoT().Context(), thirdUser)
-			user3Repo := NewAlbumRepository(user3Ctx, GetDBXBuilder()).(*albumRepository)
-			Expect(user3Repo.SetRating(4, newID)).To(Succeed())
+			Expect(albumRepo.SetRating(user3Ctx, 4, newID)).To(Succeed())
 
-			album, err := albumRepo.Get(newID)
+			album, err := albumRepo.Get(ctx, newID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(album.AverageRating).To(Equal(4.33)) // (5 + 4 + 4) / 3 = 4.333...
 
-			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": newID}))
 		})
 	})
 
@@ -715,10 +712,11 @@ var _ = Describe("AlbumRepository", func() {
 		}
 
 		var artistRepo *artistRepository
+		var artistCtx context.Context
 
 		BeforeEach(func() {
-			ctx := request.WithUser(GinkgoT().Context(), adminUser)
-			artistRepo = NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)
+			artistCtx = request.WithUser(ctx, adminUser)
+			artistRepo = NewArtistRepository(GetDBXBuilder()).(*artistRepository)
 		})
 
 		// Helper to verify album_artists records
@@ -730,7 +728,7 @@ var _ = Describe("AlbumRepository", func() {
 				Where(squirrel.Eq{"album_id": albumID}).
 				OrderBy("role", "artist_id", "sub_role")
 
-			err := albumRepo.queryAll(sq, &actual)
+			err := albumRepo.queryAll(ctx, sq, &actual)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual).To(Equal(expected))
 		}
@@ -743,7 +741,7 @@ var _ = Describe("AlbumRepository", func() {
 				OrderArtistName: "real artist",
 				SortArtistName:  "Artist, Real",
 			}
-			err := createArtistWithLibrary(artistRepo, artist, 1)
+			err := createArtistWithLibrary(artistCtx, artistRepo, artist, 1)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Create an album with participants that reference the real artist
@@ -764,7 +762,7 @@ var _ = Describe("AlbumRepository", func() {
 			}
 
 			// Insert the album
-			err = albumRepo.Put(album)
+			err = albumRepo.Put(ctx, album)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Verify that participant records were actually inserted into album_artists table
@@ -775,13 +773,13 @@ var _ = Describe("AlbumRepository", func() {
 			verifyAlbumArtists(album.ID, expected)
 
 			// Clean up the test artist and album created for this test
-			_, _ = artistRepo.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+			_, _ = artistRepo.executeSQL(artistCtx, squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
 		})
 
 		It("finds albums through the participant-based filters", func() {
 			artist := &model.Artist{ID: "filter-artist-1", Name: "Filter Artist", OrderArtistName: "filter artist"}
-			Expect(createArtistWithLibrary(artistRepo, artist, 1)).To(Succeed())
+			Expect(createArtistWithLibrary(artistCtx, artistRepo, artist, 1)).To(Succeed())
 
 			album := &model.Album{
 				LibraryID:     1,
@@ -794,36 +792,36 @@ var _ = Describe("AlbumRepository", func() {
 					model.RoleComposer:    {{Artist: model.Artist{ID: artist.ID, Name: artist.Name}}},
 				},
 			}
-			Expect(albumRepo.Put(album)).To(Succeed())
+			Expect(albumRepo.Put(ctx, album)).To(Succeed())
 
-			byArtist, err := albumRepo.GetAll(model.QueryOptions{Filters: artistFilter("artist_id", artist.ID)})
+			byArtist, err := albumRepo.GetAll(ctx, model.QueryOptions{Filters: artistFilter("artist_id", artist.ID)})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(byArtist).To(HaveLen(1))
 			Expect(byArtist[0].ID).To(Equal(album.ID))
 
-			byComposer, err := albumRepo.GetAll(model.QueryOptions{Filters: artistRoleFilter("role_composer_id", artist.ID)})
+			byComposer, err := albumRepo.GetAll(ctx, model.QueryOptions{Filters: artistRoleFilter("role_composer_id", artist.ID)})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(byComposer).To(HaveLen(1))
 
-			byLyricist, err := albumRepo.GetAll(model.QueryOptions{Filters: artistRoleFilter("role_lyricist_id", artist.ID)})
+			byLyricist, err := albumRepo.GetAll(ctx, model.QueryOptions{Filters: artistRoleFilter("role_lyricist_id", artist.ID)})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(byLyricist).To(BeEmpty())
 
-			byAnyRole, err := albumRepo.GetAll(model.QueryOptions{Filters: allRolesFilter("role_total_id", artist.ID)})
+			byAnyRole, err := albumRepo.GetAll(ctx, model.QueryOptions{Filters: allRolesFilter("role_total_id", artist.ID)})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(byAnyRole).To(HaveLen(1))
 
-			count, err := albumRepo.CountAll(model.QueryOptions{Filters: artistFilter("artist_id", artist.ID)})
+			count, err := albumRepo.CountAll(ctx, model.QueryOptions{Filters: artistFilter("artist_id", artist.ID)})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(int64(1)))
 
-			_, _ = artistRepo.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+			_, _ = artistRepo.executeSQL(artistCtx, squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
 		})
 
 		It("clears album_artists rows when saved with empty participants", func() {
 			artist := &model.Artist{ID: "clear-artist-1", Name: "Clear Artist", OrderArtistName: "clear artist"}
-			Expect(createArtistWithLibrary(artistRepo, artist, 1)).To(Succeed())
+			Expect(createArtistWithLibrary(artistCtx, artistRepo, artist, 1)).To(Succeed())
 
 			album := &model.Album{
 				LibraryID:     1,
@@ -836,14 +834,14 @@ var _ = Describe("AlbumRepository", func() {
 				},
 			}
 			DeferCleanup(func() {
-				_, _ = artistRepo.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+				_, _ = artistRepo.executeSQL(artistCtx, squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
 			})
-			Expect(albumRepo.Put(album)).To(Succeed())
+			Expect(albumRepo.Put(ctx, album)).To(Succeed())
 			verifyAlbumArtists(album.ID, []albumArtistRecord{{ArtistID: artist.ID, Role: "albumartist", SubRole: ""}})
 
 			album.Participants = model.Participants{}
-			Expect(albumRepo.Put(album)).To(Succeed())
+			Expect(albumRepo.Put(ctx, album)).To(Succeed())
 			verifyAlbumArtists(album.ID, []albumArtistRecord{})
 		})
 
@@ -859,9 +857,9 @@ var _ = Describe("AlbumRepository", func() {
 				Name:            "Real Artist 2",
 				OrderArtistName: "real artist 2",
 			}
-			err := createArtistWithLibrary(artistRepo, artist1, 1)
+			err := createArtistWithLibrary(artistCtx, artistRepo, artist1, 1)
 			Expect(err).ToNot(HaveOccurred())
-			err = createArtistWithLibrary(artistRepo, artist2, 1)
+			err = createArtistWithLibrary(artistCtx, artistRepo, artist2, 1)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Create an album with mix of valid and invalid artist IDs
@@ -885,7 +883,7 @@ var _ = Describe("AlbumRepository", func() {
 			}
 
 			// This should not fail - only valid artists should be inserted
-			err = albumRepo.Put(album)
+			err = albumRepo.Put(ctx, album)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Verify that only valid artist IDs were inserted into album_artists table
@@ -899,8 +897,8 @@ var _ = Describe("AlbumRepository", func() {
 
 			// Clean up the test artists and album created for this test
 			artistIDs := []string{artist1.ID, artist2.ID}
-			_, _ = artistRepo.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": artistIDs}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+			_, _ = artistRepo.executeSQL(artistCtx, squirrel.Delete("artist").Where(squirrel.Eq{"id": artistIDs}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
 		})
 
 		It("handles complex nested JSON with multiple roles and sub-roles", func() {
@@ -913,7 +911,7 @@ var _ = Describe("AlbumRepository", func() {
 			}
 
 			for _, artist := range artists {
-				err := createArtistWithLibrary(artistRepo, artist, 1)
+				err := createArtistWithLibrary(artistCtx, artistRepo, artist, 1)
 				Expect(err).ToNot(HaveOccurred())
 			}
 
@@ -940,7 +938,7 @@ var _ = Describe("AlbumRepository", func() {
 				},
 			}
 
-			err := albumRepo.Put(album)
+			err := albumRepo.Put(ctx, album)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Verify complex JSON structure was correctly parsed and inserted
@@ -959,8 +957,8 @@ var _ = Describe("AlbumRepository", func() {
 			for i, artist := range artists {
 				artistIDs[i] = artist.ID
 			}
-			_, _ = artistRepo.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": artistIDs}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+			_, _ = artistRepo.executeSQL(artistCtx, squirrel.Delete("artist").Where(squirrel.Eq{"id": artistIDs}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
 		})
 
 		It("handles albums with non-existent artist IDs without constraint errors", func() {
@@ -991,7 +989,7 @@ var _ = Describe("AlbumRepository", func() {
 
 			// This should not fail with foreign key constraint error
 			// The updateParticipants method should handle non-existent artist IDs gracefully
-			err := albumRepo.Put(album)
+			err := albumRepo.Put(ctx, album)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Verify that no participant records were inserted since all artist IDs were invalid
@@ -999,7 +997,7 @@ var _ = Describe("AlbumRepository", func() {
 			verifyAlbumArtists(album.ID, []albumArtistRecord{})
 
 			// Clean up the test album created for this test
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
 		})
 
 		It("removes stale role associations when artist role changes", func() {
@@ -1013,7 +1011,7 @@ var _ = Describe("AlbumRepository", func() {
 				Name:            "Role Change Artist",
 				OrderArtistName: "role change artist",
 			}
-			err := createArtistWithLibrary(artistRepo, artist, 1)
+			err := createArtistWithLibrary(artistCtx, artistRepo, artist, 1)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Create album with artist as both albumartist and composer
@@ -1033,7 +1031,7 @@ var _ = Describe("AlbumRepository", func() {
 				},
 			}
 
-			err = albumRepo.Put(album)
+			err = albumRepo.Put(ctx, album)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Verify initial state: artist has both albumartist and composer roles
@@ -1050,7 +1048,7 @@ var _ = Describe("AlbumRepository", func() {
 				},
 			}
 
-			err = albumRepo.Put(album)
+			err = albumRepo.Put(ctx, album)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Verify that the albumartist role was removed - only composer should remain
@@ -1062,14 +1060,14 @@ var _ = Describe("AlbumRepository", func() {
 			verifyAlbumArtists(album.ID, expectedAfter)
 
 			// Clean up
-			_, _ = artistRepo.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
+			_, _ = artistRepo.executeSQL(artistCtx, squirrel.Delete("artist").Where(squirrel.Eq{"id": artist.ID}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": album.ID}))
 		})
 	})
 
 	Describe("GetYears", func() {
 		It("returns distinct album years ascending, excluding zero", func() {
-			years, err := albumRepo.GetYears()
+			years, err := albumRepo.GetYears(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			// Sorted ascending, no duplicates, no zero-year entries.
 			Expect(sort.IsSorted(sort.IntSlice(years))).To(BeTrue())
@@ -1084,13 +1082,13 @@ var _ = Describe("AlbumRepository", func() {
 			// Insert two albums with the same non-zero max_year (2005).
 			album1 := &model.Album{LibraryID: 1, ID: "dedup-test-1", Name: "Album 1", MaxYear: 2005}
 			album2 := &model.Album{LibraryID: 1, ID: "dedup-test-2", Name: "Album 2", MaxYear: 2005}
-			Expect(albumRepo.Put(album1)).To(Succeed())
-			Expect(albumRepo.Put(album2)).To(Succeed())
+			Expect(albumRepo.Put(ctx, album1)).To(Succeed())
+			Expect(albumRepo.Put(ctx, album2)).To(Succeed())
 			DeferCleanup(func() {
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"dedup-test-1", "dedup-test-2"}}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"dedup-test-1", "dedup-test-2"}}))
 			})
 
-			years, err := albumRepo.GetYears()
+			years, err := albumRepo.GetYears(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Count occurrences of 2005 in the result
@@ -1104,10 +1102,10 @@ var _ = Describe("AlbumRepository", func() {
 		})
 
 		It("scopes years to the given libraries", func() {
-			all, err := albumRepo.GetYears()
+			all, err := albumRepo.GetYears(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			// A library with no albums yields no years.
-			scoped, err := albumRepo.GetYears(99999)
+			scoped, err := albumRepo.GetYears(ctx, 99999)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(scoped).To(BeEmpty())
 			Expect(all).ToNot(BeEmpty())
@@ -1115,12 +1113,12 @@ var _ = Describe("AlbumRepository", func() {
 
 		It("excludes years that belong only to missing albums", func() {
 			gone := &model.Album{LibraryID: 1, ID: "missing-year-1", Name: "Gone", MaxYear: 1911, Missing: true}
-			Expect(albumRepo.Put(gone)).To(Succeed())
+			Expect(albumRepo.Put(ctx, gone)).To(Succeed())
 			DeferCleanup(func() {
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": "missing-year-1"}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": "missing-year-1"}))
 			})
 
-			years, err := albumRepo.GetYears()
+			years, err := albumRepo.GetYears(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(years).ToNot(ContainElement(1911))
 		})
@@ -1169,15 +1167,15 @@ var _ = Describe("AlbumRepository", func() {
 	Describe("ReplayGain", func() {
 		BeforeEach(func() {
 			DeferCleanup(func() {
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"rg-1", "rg-2"}}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"rg-1", "rg-2"}}))
 			})
 		})
 		It("round-trips album ReplayGain gain and peak", func() {
-			Expect(albumRepo.Put(&model.Album{
+			Expect(albumRepo.Put(ctx, &model.Album{
 				ID: "rg-1", Name: "rg", LibraryID: 1,
 				RGAlbumGain: new(-7.5), RGAlbumPeak: new(0.98),
 			})).To(Succeed())
-			got, err := albumRepo.Get("rg-1")
+			got, err := albumRepo.Get(ctx, "rg-1")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.RGAlbumGain).ToNot(BeNil())
 			Expect(*got.RGAlbumGain).To(Equal(-7.5))
@@ -1185,8 +1183,8 @@ var _ = Describe("AlbumRepository", func() {
 			Expect(*got.RGAlbumPeak).To(Equal(0.98))
 		})
 		It("reads nil when ReplayGain is unset", func() {
-			Expect(albumRepo.Put(&model.Album{ID: "rg-2", Name: "rg2", LibraryID: 1})).To(Succeed())
-			got, err := albumRepo.Get("rg-2")
+			Expect(albumRepo.Put(ctx, &model.Album{ID: "rg-2", Name: "rg2", LibraryID: 1})).To(Succeed())
+			got, err := albumRepo.Get(ctx, "rg-2")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.RGAlbumGain).To(BeNil())
 			Expect(got.RGAlbumPeak).To(BeNil())
@@ -1196,16 +1194,46 @@ var _ = Describe("AlbumRepository", func() {
 	// Exists must apply the same library filter as Get/GetAll/CountAll.
 	Describe("Exists library visibility", func() {
 		It("hides an album the user has no library access to", func() {
-			Expect(albumRepo.Put(&model.Album{ID: "vis-album", Name: "Vis", LibraryID: 1})).To(Succeed())
+			Expect(albumRepo.Put(ctx, &model.Album{ID: "vis-album", Name: "Vis", LibraryID: 1})).To(Succeed())
 			DeferCleanup(func() {
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": "vis-album"}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": "vis-album"}))
 			})
 
-			Expect(albumRepo.Exists("vis-album")).To(BeTrue(), "admin sees it")
+			Expect(albumRepo.Exists(ctx, "vis-album")).To(BeTrue(), "admin sees it")
 
 			restricted := model.User{ID: "restricted_album_user", UserName: "ra", Name: "RA", Email: "ra@t.com"}
 			rctx := request.WithUser(GinkgoT().Context(), restricted)
-			Expect(NewAlbumRepository(rctx, GetDBXBuilder()).Exists("vis-album")).To(BeFalse())
+			Expect(albumRepo.Exists(rctx, "vis-album")).To(BeFalse())
+		})
+
+		It("keeps per-user library visibility separate on a shared repository", func() {
+			adminCtx := request.WithUser(ctx, adminUser)
+			adminCount, err := albumRepo.CountAll(adminCtx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(adminCount).To(BeNumerically(">", 0))
+
+			// A user with no library grants, so its visibility can't drift with other specs
+			restrictedCtx := request.WithUser(ctx, model.User{ID: "shared-repo-restricted"})
+			restrictedCount, err := albumRepo.CountAll(restrictedCtx)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(restrictedCount).To(BeZero())
+
+			var wg sync.WaitGroup
+			for i := range 20 {
+				wg.Add(1)
+				go func(i int) {
+					defer GinkgoRecover()
+					defer wg.Done()
+					c, want := adminCtx, adminCount
+					if i%2 == 1 {
+						c, want = restrictedCtx, restrictedCount
+					}
+					got, err := albumRepo.CountAll(c)
+					Expect(err).ToNot(HaveOccurred())
+					Expect(got).To(Equal(want))
+				}(i)
+			}
+			wg.Wait()
 		})
 	})
 })
diff --git a/persistence/artist_repository.go b/persistence/artist_repository.go
index 97c1452cb..b90a48c48 100644
--- a/persistence/artist_repository.go
+++ b/persistence/artist_repository.go
@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"maps"
 	"os"
 	"slices"
 	"strings"
@@ -129,9 +130,8 @@ func (dba dbArtists) toModels() model.Artists {
 	return res
 }
 
-func NewArtistRepository(ctx context.Context, db dbx.Builder) model.ArtistRepository {
+func NewArtistRepository(db dbx.Builder) model.ArtistRepository {
 	r := &artistRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.indexGroups = utils.ParseIndexGroups(conf.Server.IndexGroups)
 	r.tableName = "artist" // To be used by the idFilter below
@@ -188,8 +188,8 @@ func artistLibraryIdFilter(_ string, value any) Sqlizer {
 }
 
 // applyLibraryFilterToArtistQuery applies library filtering to artist queries through the library_artist junction table
-func (r *artistRepository) applyLibraryFilterToArtistQuery(query SelectBuilder) SelectBuilder {
-	user := loggedUser(r.ctx)
+func (r *artistRepository) applyLibraryFilterToArtistQuery(ctx context.Context, query SelectBuilder) SelectBuilder {
+	user := loggedUser(ctx)
 	// Join with library_artist first to ensure only artists with content in libraries are included
 	// Exclude artists with empty stats (no actual content in the library)
 	query = query.Join("library_artist on library_artist.artist_id = artist.id")
@@ -204,106 +204,106 @@ func (r *artistRepository) applyLibraryFilterToArtistQuery(query SelectBuilder)
 	return query
 }
 
-func (r *artistRepository) selectArtist(options ...model.QueryOptions) SelectBuilder {
+func (r *artistRepository) selectArtist(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
 	// Stats Format: {"1": {"albumartist": {"m": 10, "a": 5, "s": 1024}, "artist": {...}}, "2": {...}}
-	query := r.newSelect(options...).Columns("artist.*",
+	query := r.newSelect(ctx, options...).Columns("artist.*",
 		"JSON_GROUP_OBJECT(library_artist.library_id, JSONB(library_artist.stats)) as library_stats_json")
 
-	query = r.applyLibraryFilterToArtistQuery(query)
+	query = r.applyLibraryFilterToArtistQuery(ctx, query)
 	query = query.GroupBy("artist.id")
-	return r.withAnnotation(query, "artist.id")
+	return r.withAnnotation(ctx, query, "artist.id")
 }
 
-func (r *artistRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	query := r.newSelect()
-	query = r.applyLibraryFilterToArtistQuery(query)
+func (r *artistRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	query := r.newSelect(ctx)
+	query = r.applyLibraryFilterToArtistQuery(ctx, query)
 	// Only the annotation join is gated; the library_artist join above (and its count(distinct))
 	// must stay, since an artist can span multiple libraries.
 	if filtersNeedAnnotation(r.applyFilters(query, options...)) {
-		query = r.withAnnotation(query, "artist.id")
+		query = r.withAnnotation(ctx, query, "artist.id")
 	}
-	return r.count(query, options...)
+	return r.count(ctx, query, options...)
 }
 
 // Exists checks if an artist with the given ID exists in the database and is accessible by the current user.
-func (r *artistRepository) Exists(id string) (bool, error) {
+func (r *artistRepository) Exists(ctx context.Context, id string) (bool, error) {
 	// Create a query using the same library filtering logic as selectArtist()
-	query := r.newSelect().Columns("count(distinct artist.id) as exist").Where(Eq{"artist.id": id})
-	query = r.applyLibraryFilterToArtistQuery(query)
+	query := r.newSelect(ctx).Columns("count(distinct artist.id) as exist").Where(Eq{"artist.id": id})
+	query = r.applyLibraryFilterToArtistQuery(ctx, query)
 
 	var res struct{ Exist int64 }
-	err := r.queryOne(query, &res)
+	err := r.queryOne(ctx, query, &res)
 	return res.Exist > 0, err
 }
 
-func (r *artistRepository) Put(a *model.Artist, colsToUpdate ...string) error {
+func (r *artistRepository) Put(ctx context.Context, a *model.Artist, colsToUpdate ...string) error {
 	dba := &dbArtist{Artist: a}
 	dba.CreatedAt = new(time.Now())
 	dba.UpdatedAt = dba.CreatedAt
-	_, err := r.put(dba.ID, dba, colsToUpdate...)
+	_, err := r.put(ctx, dba.ID, dba, colsToUpdate...)
 	return err
 }
 
-func (r *artistRepository) UpdateExternalInfo(a *model.Artist) error {
+func (r *artistRepository) UpdateExternalInfo(ctx context.Context, a *model.Artist) error {
 	dba := &dbArtist{Artist: a}
-	_, err := r.put(a.ID, dba,
+	_, err := r.put(ctx, a.ID, dba,
 		"biography", "small_image_url", "medium_image_url", "large_image_url",
 		"similar_artists", "external_url", "external_info_updated_at")
 	return err
 }
 
-func (r *artistRepository) Get(id string) (*model.Artist, error) {
-	sel := r.selectArtist().Where(Eq{"artist.id": id})
+func (r *artistRepository) Get(ctx context.Context, id string) (*model.Artist, error) {
+	sel := r.selectArtist(ctx).Where(Eq{"artist.id": id})
 	var dba dbArtists
-	if err := r.queryAll(sel, &dba); err != nil {
+	if err := r.queryAll(ctx, sel, &dba); err != nil {
 		return nil, err
 	}
 	if len(dba) == 0 {
 		return nil, model.ErrNotFound
 	}
 	res := dba.toModels()
-	r.hydrateArtwork(res)
+	r.hydrateArtwork(ctx, res)
 	return &res[0], nil
 }
 
-func (r *artistRepository) GetAll(options ...model.QueryOptions) (model.Artists, error) {
-	sel := r.selectArtist(options...)
+func (r *artistRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Artists, error) {
+	sel := r.selectArtist(ctx, options...)
 	var dba dbArtists
-	err := r.queryAll(sel, &dba)
+	err := r.queryAll(ctx, sel, &dba)
 	if err != nil {
 		return nil, err
 	}
 	res := dba.toModels()
-	r.hydrateArtwork(res)
+	r.hydrateArtwork(ctx, res)
 	return res, err
 }
 
 // getAllIDs returns just the artist IDs for the same row set as GetAll, skipping the
 // heavy stats columns and JSON post-processing.
-func (r *artistRepository) getAllIDs(options ...model.QueryOptions) ([]string, error) {
-	sq := r.applyLibraryFilterToArtistQuery(r.newSelect(options...).Columns("artist.id")).GroupBy("artist.id")
+func (r *artistRepository) getAllIDs(ctx context.Context, options ...model.QueryOptions) ([]string, error) {
+	sq := r.applyLibraryFilterToArtistQuery(ctx, r.newSelect(ctx, options...).Columns("artist.id")).GroupBy("artist.id")
 	if filtersNeedAnnotation(sq) {
-		sq = r.withAnnotation(sq, "artist.id")
+		sq = r.withAnnotation(ctx, sq, "artist.id")
 	}
 	ids := []string{}
-	err := r.queryAllSlice(sq, &ids)
+	err := r.queryAllSlice(ctx, sq, &ids)
 	return ids, err
 }
 
 // hydrateArtwork fills each artist's ImageHash/ImageAbsent from one batched item_artwork lookup.
-func (r *artistRepository) hydrateArtwork(artists model.Artists) {
-	hydrateItems(r.ctx, r.db, model.KindArtistArtwork, artists,
+func (r *artistRepository) hydrateArtwork(ctx context.Context, artists model.Artists) {
+	hydrateItems(ctx, r.db, model.KindArtistArtwork, artists,
 		func(a *model.Artist) (string, *model.ItemImage) { return a.ID, &a.ItemImage })
 }
 
-func (r *artistRepository) GetCursor(options ...model.QueryOptions) (model.ArtistCursor, error) {
-	ids, err := r.getAllIDs(options...)
+func (r *artistRepository) GetCursor(ctx context.Context, options ...model.QueryOptions) (model.ArtistCursor, error) {
+	ids, err := r.getAllIDs(ctx, options...)
 	if err != nil {
 		return nil, err
 	}
 	opts := chunkOptions(options, "artist.id")
 	return model.ArtistCursor(streamByIDs(ids, func(chunk []string) (model.Artists, error) {
-		return r.GetAll(opts(chunk))
+		return r.GetAll(ctx, opts(chunk))
 	})), nil
 }
 
@@ -324,7 +324,7 @@ func (r *artistRepository) getIndexKey(a model.Artist) string {
 // GetIndex returns a list of artists grouped by the first letter of their name, or by the index group if configured.
 // It can filter by roles and libraries, and optionally include artists that are missing (i.e., have no albums).
 // TODO Cache the index (recalculate at scan time)
-func (r *artistRepository) GetIndex(includeMissing bool, libraryIds []int, roles ...model.Role) (model.ArtistIndexes, error) {
+func (r *artistRepository) GetIndex(ctx context.Context, includeMissing bool, libraryIds []int, roles ...model.Role) (model.ArtistIndexes, error) {
 	// Validate library IDs. If no library IDs are provided, return an empty index.
 	if len(libraryIds) == 0 {
 		return nil, nil
@@ -352,7 +352,7 @@ func (r *artistRepository) GetIndex(includeMissing bool, libraryIds []int, roles
 		options.Filters = And{options.Filters, libFilter}
 	}
 
-	artists, err := r.GetAll(options)
+	artists, err := r.GetAll(ctx, options)
 	if err != nil {
 		return nil, err
 	}
@@ -367,7 +367,7 @@ func (r *artistRepository) GetIndex(includeMissing bool, libraryIds []int, roles
 	return result, nil
 }
 
-func (r *artistRepository) purgeEmpty() error {
+func (r *artistRepository) purgeEmpty(ctx context.Context) error {
 	orphanFilter := "id not in (select artist_id from album_artists)"
 
 	// Collect uploaded image filenames before deleting
@@ -375,18 +375,18 @@ func (r *artistRepository) purgeEmpty() error {
 		Where(orphanFilter).
 		Where("uploaded_image != ''")
 	var imageFiles []string
-	if err := r.queryAllSlice(sel, &imageFiles); err != nil && !errors.Is(err, model.ErrNotFound) {
+	if err := r.queryAllSlice(ctx, sel, &imageFiles); err != nil && !errors.Is(err, model.ErrNotFound) {
 		return fmt.Errorf("collecting artist images for cleanup: %w", err)
 	}
 
 	// Delete orphan artists
 	del := Delete(r.tableName).Where(orphanFilter)
-	c, err := r.executeSQL(del)
+	c, err := r.executeSQL(ctx, del)
 	if err != nil {
 		return fmt.Errorf("purging empty artists: %w", err)
 	}
 	if c > 0 {
-		log.Debug(r.ctx, "Purged empty artists", "totalDeleted", c)
+		log.Debug(ctx, "Purged empty artists", "totalDeleted", c)
 	}
 
 	if len(imageFiles) == 0 {
@@ -394,11 +394,11 @@ func (r *artistRepository) purgeEmpty() error {
 	}
 
 	// Best-effort cleanup of uploaded image files
-	log.Debug(r.ctx, "Cleaning up artist images", "totalImages", len(imageFiles))
+	log.Debug(ctx, "Cleaning up artist images", "totalImages", len(imageFiles))
 	for _, filename := range imageFiles {
 		path := model.UploadedImagePath(consts.EntityArtist, filename)
 		if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
-			log.Warn(r.ctx, "Failed to remove artist image during GC", "path", path, err)
+			log.Warn(ctx, "Failed to remove artist image during GC", "path", path, err)
 		}
 	}
 	return nil
@@ -407,9 +407,9 @@ func (r *artistRepository) purgeEmpty() error {
 // markOrphansMissing flags as missing any non-missing artist with no library_artist row, keeping the
 // search fast-path's `missing = false` filter correct (see searchCfg). Called wherever such a row can
 // be dropped: RefreshStats cleanup and library deletion cascade.
-func (r *artistRepository) markOrphansMissing() error {
-	_, err := r.executeSQL(Expr(
-		"update artist set missing = true where missing = false " +
+func (r *artistRepository) markOrphansMissing(ctx context.Context) error {
+	_, err := r.executeSQL(ctx, Expr(
+		"update artist set missing = true where missing = false "+
 			"and not exists (select 1 from library_artist where library_artist.artist_id = artist.id)"))
 	if err != nil {
 		return fmt.Errorf("marking orphaned artists missing: %w", err)
@@ -418,7 +418,7 @@ func (r *artistRepository) markOrphansMissing() error {
 }
 
 // markMissing marks artists as missing if all their albums are missing.
-func (r *artistRepository) markMissing() error {
+func (r *artistRepository) markMissing(ctx context.Context) error {
 	q := Expr(`
 with artists_with_non_missing_albums as (
     select distinct aa.artist_id
@@ -429,7 +429,7 @@ with artists_with_non_missing_albums as (
 update artist
 set missing = (artist.id not in (select artist_id from artists_with_non_missing_albums));
         `)
-	_, err := r.executeSQL(q)
+	_, err := r.executeSQL(ctx, q)
 	if err != nil {
 		return fmt.Errorf("marking missing artists: %w", err)
 	}
@@ -438,7 +438,7 @@ set missing = (artist.id not in (select artist_id from artists_with_non_missing_
 
 // RefreshPlayCounts updates the play count and last play date annotations for all artists, based
 // on the media files associated with them.
-func (r *artistRepository) RefreshPlayCounts() (int64, error) {
+func (r *artistRepository) RefreshPlayCounts(ctx context.Context) (int64, error) {
 	query := Expr(`
 with play_counts as (
     select user_id, atom as artist_id, sum(play_count) as total_play_count, max(play_date) as last_play_date
@@ -456,13 +456,13 @@ on conflict (user_id, item_id, item_type) do update
     set play_count = excluded.play_count,
         play_date  = excluded.play_date;
 `)
-	return r.executeSQL(query)
+	return r.executeSQL(ctx, query)
 }
 
 // RefreshStats updates the stats field for artists whose associated media files were updated after the oldest recorded library scan time.
 // When allArtists is true, it refreshes stats for all artists. It processes artists in batches to handle potentially large updates.
 // This method now calculates per-library statistics and stores them in the library_artist junction table.
-func (r *artistRepository) RefreshStats(allArtists bool) (int64, error) {
+func (r *artistRepository) RefreshStats(ctx context.Context, allArtists bool) (int64, error) {
 	var allTouchedArtistIDs []string
 	if allArtists {
 		// Refresh stats for all artists
@@ -470,7 +470,7 @@ func (r *artistRepository) RefreshStats(allArtists bool) (int64, error) {
 		if err := r.db.NewQuery(allArtistsQuerySQL).Column(&allTouchedArtistIDs); err != nil {
 			return 0, fmt.Errorf("fetching all artist IDs: %w", err)
 		}
-		log.Debug(r.ctx, "RefreshStats: Refreshing all artists.", "count", len(allTouchedArtistIDs))
+		log.Debug(ctx, "RefreshStats: Refreshing all artists.", "count", len(allTouchedArtistIDs))
 	} else {
 		// Only refresh artists with updated timestamps
 		touchedArtistsQuerySQL := `
@@ -481,11 +481,11 @@ func (r *artistRepository) RefreshStats(allArtists bool) (int64, error) {
 		if err := r.db.NewQuery(touchedArtistsQuerySQL).Column(&allTouchedArtistIDs); err != nil {
 			return 0, fmt.Errorf("fetching touched artist IDs: %w", err)
 		}
-		log.Debug(r.ctx, "RefreshStats: Refreshing touched artists.", "count", len(allTouchedArtistIDs))
+		log.Debug(ctx, "RefreshStats: Refreshing touched artists.", "count", len(allTouchedArtistIDs))
 	}
 
 	if len(allTouchedArtistIDs) == 0 {
-		log.Debug(r.ctx, "RefreshStats: No artists to update.")
+		log.Debug(ctx, "RefreshStats: No artists to update.")
 		return 0, nil
 	}
 
@@ -558,7 +558,7 @@ func (r *artistRepository) RefreshStats(allArtists bool) (int64, error) {
 	batchCounter := 0
 	for artistIDBatch := range slice.CollectChunks(slices.Values(allTouchedArtistIDs), batchSize) {
 		batchCounter++
-		log.Trace(r.ctx, "RefreshStats: Processing batch", "batchNum", batchCounter, "batchSize", len(artistIDBatch))
+		log.Trace(ctx, "RefreshStats: Processing batch", "batchNum", batchCounter, "batchSize", len(artistIDBatch))
 
 		// Create placeholders for each ID in the IN clauses
 		placeholders := make([]string, len(artistIDBatch))
@@ -584,7 +584,7 @@ func (r *artistRepository) RefreshStats(allArtists bool) (int64, error) {
 		// Now use Expr with the expanded SQL and all parameters
 		sqlizer := Expr(batchSQL, args...)
 
-		rowsAffected, err := r.executeSQL(sqlizer)
+		rowsAffected, err := r.executeSQL(ctx, sqlizer)
 		if err != nil {
 			return totalRowsAffected, fmt.Errorf("executing batch update for artist stats (batch %d): %w", batchCounter, err)
 		}
@@ -593,23 +593,23 @@ func (r *artistRepository) RefreshStats(allArtists bool) (int64, error) {
 
 	// Remove library_artist entries for artists that no longer have any content in a library.
 	cleanupSQL := Delete("library_artist").Where("stats = '{}'")
-	cleanupRows, err := r.executeSQL(cleanupSQL)
+	cleanupRows, err := r.executeSQL(ctx, cleanupSQL)
 	if err != nil {
-		log.Warn(r.ctx, "Failed to cleanup empty library_artist entries", err)
+		log.Warn(ctx, "Failed to cleanup empty library_artist entries", err)
 	} else {
 		if cleanupRows > 0 {
-			log.Debug(r.ctx, "Cleaned up empty library_artist entries", "rowsDeleted", cleanupRows)
+			log.Debug(ctx, "Cleaned up empty library_artist entries", "rowsDeleted", cleanupRows)
 		}
 		// Reconcile orphans whenever the cleanup removed rows, and on a full refresh so a full scan
 		// also heals any left by older versions.
 		if cleanupRows > 0 || allArtists {
-			if err := r.markOrphansMissing(); err != nil {
-				log.Warn(r.ctx, "Failed to mark orphaned artists missing after library_artist cleanup", err)
+			if err := r.markOrphansMissing(ctx); err != nil {
+				log.Warn(ctx, "Failed to mark orphaned artists missing after library_artist cleanup", err)
 			}
 		}
 	}
 
-	log.Debug(r.ctx, "RefreshStats: Successfully updated stats.", "totalArtistsProcessed", len(allTouchedArtistIDs), "totalDBRowsAffected", totalRowsAffected)
+	log.Debug(ctx, "RefreshStats: Successfully updated stats.", "totalArtistsProcessed", len(allTouchedArtistIDs), "totalDBRowsAffected", totalRowsAffected)
 	return totalRowsAffected, nil
 }
 
@@ -649,39 +649,39 @@ func artistLibraryFilter(libraryIDs []int) Sqlizer {
 	return Expr("EXISTS ("+sub+")", args...)
 }
 
-func (r *artistRepository) Search(q string, options ...model.QueryOptions) (model.Artists, error) {
+func (r *artistRepository) Search(ctx context.Context, q string, options ...model.QueryOptions) (model.Artists, error) {
 	var opts model.QueryOptions
 	if len(options) > 0 {
 		opts = options[0]
 	}
 	// Artists have no library_id column, so the library_id filter callers pass (same as albums/songs)
 	// can't be applied directly: consume it and realize it as a join-free Phase-1 scope (searchCfg).
-	scope := r.searchScope(opts.Filters)
+	scope := r.searchScope(ctx, opts.Filters)
 	if isLibraryIDFilter(opts.Filters) {
 		opts.Filters = nil
 	}
 	var res dbArtists
-	err := r.doSearch(r.selectArtist(opts), q, &res, r.searchCfg(scope), opts)
+	err := r.doSearch(ctx, r.selectArtist(ctx, opts), q, &res, r.searchCfg(scope), opts)
 	if err != nil {
 		return nil, fmt.Errorf("searching artist %q: %w", q, err)
 	}
 	artists := res.toModels()
-	r.hydrateArtwork(artists)
+	r.hydrateArtwork(ctx, artists)
 	return artists, nil
 }
 
 // searchScope returns the library IDs the search must be restricted to, or nil to skip the filter
 // entirely (the fast-path: the user sees everything the search could return, so a filter would be
 // pure O(offset) overhead). It intersects the requested libraries with what the user can see.
-func (r *artistRepository) searchScope(filter Sqlizer) []int {
-	visible, err := r.visibleLibraryIDs()
+func (r *artistRepository) searchScope(ctx context.Context, filter Sqlizer) []int {
+	visible, err := r.visibleLibraryIDs(ctx)
 	if err != nil {
 		return r.requestedLibraryIDs(filter) // fail safe: narrow to the request rather than widen
 	}
 	requested := r.requestedLibraryIDs(filter)
 	if requested == nil {
 		// No explicit request: scope to the visible set, unless the user sees everything.
-		if r.userSeesAllLibraries(visible) {
+		if r.userSeesAllLibraries(ctx, visible) {
 			return nil
 		}
 		return visible
@@ -717,15 +717,17 @@ func isLibraryIDFilter(filter Sqlizer) bool {
 	return ok
 }
 
-func (r *artistRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *artistRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *artistRepository) Read(id string) (any, error) {
-	return r.Get(id)
+func (r *artistRepository) Read(ctx context.Context, id string) (*model.Artist, error) {
+	return r.Get(ctx, id)
 }
 
-func (r *artistRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
+// sortMappingsForRole copies the shared mappings so a role-specific sort never leaks into them.
+// Anything sanitizeArtistStatsRole rejects falls back to the "total" aggregate.
+func (r *artistRepository) sortMappingsForRole(options ...rest.QueryOptions) map[string]string {
 	role := "total"
 	if len(options) > 0 {
 		if v, ok := options[0].Filters["role"].(string); ok {
@@ -734,19 +736,18 @@ func (r *artistRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
 			}
 		}
 	}
-	r.sortMappings["song_count"] = "sum(stats->>'" + role + "'->>'m')"
-	r.sortMappings["album_count"] = "sum(stats->>'" + role + "'->>'a')"
-	r.sortMappings["size"] = "sum(stats->>'" + role + "'->>'s')"
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
+	mappings := maps.Clone(r.sortMappings)
+	mappings["song_count"] = "sum(stats->>'" + role + "'->>'m')"
+	mappings["album_count"] = "sum(stats->>'" + role + "'->>'a')"
+	mappings["size"] = "sum(stats->>'" + role + "'->>'s')"
+	return mappings
 }
 
-func (r *artistRepository) EntityName() string {
-	return "artist"
-}
-
-func (r *artistRepository) NewInstance() any {
-	return &model.Artist{}
+func (r *artistRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Artist, error) {
+	scoped := *r
+	scoped.sortMappings = r.sortMappingsForRole(options...)
+	return scoped.GetAll(ctx, scoped.parseRestOptions(ctx, options...))
 }
 
 var _ model.ArtistRepository = (*artistRepository)(nil)
-var _ model.ResourceRepository = (*artistRepository)(nil)
+var _ rest.Repository[model.Artist] = (*artistRepository)(nil)
diff --git a/persistence/artist_repository_test.go b/persistence/artist_repository_test.go
index f6612acc4..914c2f89a 100644
--- a/persistence/artist_repository_test.go
+++ b/persistence/artist_repository_test.go
@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sync"
 
 	"github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
@@ -49,6 +50,11 @@ func createUserWithLibraries(userID string, libraryIDs []int) model.User {
 }
 
 var _ = Describe("ArtistRepository", func() {
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+	})
 
 	Context("Core Functionality", func() {
 		Describe("GetIndexKey", func() {
@@ -130,31 +136,70 @@ var _ = Describe("ArtistRepository", func() {
 			})
 		})
 
-		Describe("ReadAll role sort SQL injection", func() {
-			It("does not interpolate attacker-controlled role into ORDER BY", func() {
-				ctx := request.WithUser(GinkgoT().Context(), adminUser)
-				repo := NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)
-				payload := "total') OR 1=1--"
-				_, err := repo.ReadAll(rest.QueryOptions{
-					Sort:    "songCount",
-					Order:   "ASC",
-					Filters: map[string]any{"role": payload},
-				})
-				Expect(err).ToNot(HaveOccurred())
-				Expect(repo.sortMappings["song_count"]).To(Equal("sum(stats->>'total'->>'m')"))
-				Expect(repo.sortMappings["song_count"]).ToNot(ContainSubstring(payload))
+		Describe("ReadAll role sort", func() {
+			payload := "total') OR 1=1--"
+
+			songCountSortFor := func(role any) string {
+				repo := NewArtistRepository(GetDBXBuilder()).(*artistRepository)
+				return repo.sortMappingsForRole(rest.QueryOptions{Filters: map[string]any{"role": role}})["song_count"]
+			}
+
+			It("falls back to the total stats role for an attacker-controlled role", func() {
+				Expect(songCountSortFor(payload)).To(Equal("sum(stats->>'total'->>'m')"))
+				Expect(songCountSortFor("bogus")).To(Equal("sum(stats->>'total'->>'m')"))
+				Expect(songCountSortFor(42)).To(Equal("sum(stats->>'total'->>'m')"))
 			})
 
 			It("keeps valid role sort paths", func() {
+				Expect(songCountSortFor("composer")).To(Equal("sum(stats->>'composer'->>'m')"))
+				Expect(songCountSortFor("albumartist")).To(Equal("sum(stats->>'albumartist'->>'m')"))
+			})
+
+			It("leaves the shared mappings untouched", func() {
+				repo := NewArtistRepository(GetDBXBuilder()).(*artistRepository)
+				Expect(repo.sortMappingsForRole(rest.QueryOptions{Filters: map[string]any{"role": "composer"}})).
+					ToNot(Equal(repo.sortMappings))
+				Expect(repo.sortMappings["song_count"]).To(Equal("stats->>'total'->>'m'"))
+			})
+
+			It("orders by the requested role's stats, not the total", func() {
 				ctx := request.WithUser(GinkgoT().Context(), adminUser)
-				repo := NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)
-				_, err := repo.ReadAll(rest.QueryOptions{
+				repo := NewArtistRepository(GetDBXBuilder()).(*artistRepository)
+				// Composer and total counts rank the two artists in opposite orders, so the
+				// resulting order alone proves which mapping the sort used.
+				seed := func(artistID, stats string) {
+					_, err := repo.executeSQL(ctx, squirrel.Insert("library_artist").
+						Columns("library_id", "artist_id", "stats").
+						Values(1, artistID, stats).
+						Suffix("ON CONFLICT(library_id, artist_id) DO UPDATE SET stats = excluded.stats"))
+					Expect(err).ToNot(HaveOccurred())
+					DeferCleanup(func() {
+						_, _ = repo.executeSQL(ctx, squirrel.Update("library_artist").Set("stats", "{}").
+							Where(squirrel.Eq{"library_id": 1, "artist_id": artistID}))
+					})
+				}
+				seed(artistBeatles.ID, `{"composer": {"s": 1, "m": 1, "a": 1}, "total": {"s": 1, "m": 100, "a": 1}}`)
+				seed(artistKraftwerk.ID, `{"composer": {"s": 1, "m": 9, "a": 1}, "total": {"s": 1, "m": 2, "a": 1}}`)
+
+				res, err := repo.ReadAll(ctx, rest.QueryOptions{
 					Sort:    "songCount",
 					Order:   "DESC",
 					Filters: map[string]any{"role": "composer"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				Expect(repo.sortMappings["song_count"]).To(Equal("sum(stats->>'composer'->>'m')"))
+				Expect(slice.Map(res, func(a model.Artist) string { return a.ID })).
+					To(Equal([]string{artistKraftwerk.ID, artistBeatles.ID}))
+			})
+
+			It("still returns results when the role is an injection payload", func() {
+				ctx := request.WithUser(GinkgoT().Context(), adminUser)
+				repo := NewArtistRepository(GetDBXBuilder()).(*artistRepository)
+				_, err := repo.ReadAll(ctx, rest.QueryOptions{
+					Sort:    "songCount",
+					Order:   "ASC",
+					Filters: map[string]any{"role": payload},
+				})
+				Expect(err).ToNot(HaveOccurred())
 			})
 		})
 
@@ -163,8 +208,8 @@ var _ = Describe("ArtistRepository", func() {
 			// the way Search() does, for a repo whose context carries the given user.
 			scope := func(user model.User, filter squirrel.Sqlizer) []int {
 				ctx := request.WithUser(GinkgoT().Context(), user)
-				r := NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)
-				return r.searchScope(filter)
+				r := NewArtistRepository(GetDBXBuilder()).(*artistRepository)
+				return r.searchScope(ctx, filter)
 			}
 			subsetUser := model.User{ID: "u", Libraries: model.Libraries{{ID: 1}, {ID: 2}, {ID: 3}}}
 
@@ -185,7 +230,7 @@ var _ = Describe("ArtistRepository", func() {
 				// A restricted user (strictly fewer libs than exist) with no musicFolderId is still
 				// confined to their granted libs. Build the user with total-1 libraries derived from
 				// the real DB total, so the "sees all" fast-path can't kick in regardless of count.
-				total, err := NewLibraryRepository(GinkgoT().Context(), GetDBXBuilder()).CountAll()
+				total, err := NewLibraryRepository(GetDBXBuilder()).CountAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(total).To(BeNumerically(">", 0))
 				libs := make(model.Libraries, 0, total-1)
@@ -201,8 +246,8 @@ var _ = Describe("ArtistRepository", func() {
 				// Admins see every library, so the visible set is the whole library table — derive
 				// it from the DB rather than assuming a count.
 				var allLibs []int
-				Expect(NewLibraryRepository(GinkgoT().Context(), GetDBXBuilder()).(*libraryRepository).
-					queryAllSlice(squirrel.Select("id").From("library"), &allLibs)).To(Succeed())
+				Expect(NewLibraryRepository(GetDBXBuilder()).(*libraryRepository).
+					queryAllSlice(ctx, squirrel.Select("id").From("library"), &allLibs)).To(Succeed())
 				admin := model.User{ID: "a", IsAdmin: true}
 				Expect(scope(admin, squirrel.Eq{"library_id": allLibs})).To(BeNil())
 				Expect(scope(admin, nil)).To(BeNil())
@@ -310,33 +355,54 @@ var _ = Describe("ArtistRepository", func() {
 		var repo model.ArtistRepository
 
 		BeforeEach(func() {
-			ctx := GinkgoT().Context()
 			ctx = request.WithUser(ctx, adminUser)
-			repo = NewArtistRepository(ctx, GetDBXBuilder())
+			repo = NewArtistRepository(GetDBXBuilder())
+		})
+
+		Describe("ReadAll with role sort", func() {
+			It("does not change the shared sort mappings", func() {
+				original := repo.(*artistRepository).sortMappings["song_count"]
+				var wg sync.WaitGroup
+				for i := 0; i < 20; i++ {
+					role := "artist"
+					if i%2 == 1 {
+						role = "composer"
+					}
+					wg.Add(1)
+					go func() {
+						defer GinkgoRecover()
+						defer wg.Done()
+						_, err := repo.ReadAll(ctx, rest.QueryOptions{Sort: "song_count", Filters: map[string]any{"role": role}})
+						Expect(err).ToNot(HaveOccurred())
+					}()
+				}
+				wg.Wait()
+				Expect(repo.(*artistRepository).sortMappings["song_count"]).To(Equal(original))
+			})
 		})
 
 		Describe("GetCursor", func() {
 			It("yields the same artists as GetAll", func() {
 				opts := model.QueryOptions{Sort: "name"}
-				want, err := repo.GetAll(opts)
+				want, err := repo.GetAll(ctx, opts)
 				Expect(err).ToNot(HaveOccurred())
-				Expect(collectCursor(repo.GetCursor(opts))).To(Equal([]model.Artist(want)))
+				Expect(collectCursor(repo.GetCursor(ctx, opts))).To(Equal([]model.Artist(want)))
 			})
 
 			It("honors Max/Offset like GetAll", func() {
 				opts := model.QueryOptions{Sort: "name", Max: 2, Offset: 1}
-				want, err := repo.GetAll(opts)
+				want, err := repo.GetAll(ctx, opts)
 				Expect(err).ToNot(HaveOccurred())
-				Expect(collectCursor(repo.GetCursor(opts))).To(Equal([]model.Artist(want)))
+				Expect(collectCursor(repo.GetCursor(ctx, opts))).To(Equal([]model.Artist(want)))
 			})
 		})
 
 		Describe("getAllIDs", func() {
 			It("returns the same id set as GetAll", func() {
-				want, err := repo.GetAll()
+				want, err := repo.GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(want).ToNot(BeEmpty())
-				ids, err := repo.(*artistRepository).getAllIDs()
+				ids, err := repo.(*artistRepository).getAllIDs(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(ids).To(ConsistOf(slice.Map(want, func(a model.Artist) string { return a.ID })))
 			})
@@ -345,12 +411,12 @@ var _ = Describe("ArtistRepository", func() {
 		Describe("Basic Operations", func() {
 			Describe("Count", func() {
 				It("returns the number of artists in the DB", func() {
-					Expect(repo.CountAll()).To(Equal(int64(4)))
+					Expect(repo.CountAll(ctx)).To(Equal(int64(4)))
 				})
 
 				It("counts starred artists when an annotation filter is present", func() {
 					// The Beatles (id 3) is starred for the admin user in the seed data
-					count, err := repo.CountAll(model.QueryOptions{
+					count, err := repo.CountAll(ctx, model.QueryOptions{
 						Filters: annotationBoolFilter("starred")("starred", "true"),
 					})
 					Expect(err).ToNot(HaveOccurred())
@@ -358,7 +424,7 @@ var _ = Describe("ArtistRepository", func() {
 				})
 
 				It("counts with has_rating=false without a 'no such column' error (join kept)", func() {
-					count, err := repo.CountAll(model.QueryOptions{
+					count, err := repo.CountAll(ctx, model.QueryOptions{
 						Filters: annotationBoolFilter("rating")("rating", "false"),
 					})
 					Expect(err).ToNot(HaveOccurred())
@@ -368,16 +434,16 @@ var _ = Describe("ArtistRepository", func() {
 
 			Describe("Exists", func() {
 				It("returns true for an artist that is in the DB", func() {
-					Expect(repo.Exists("3")).To(BeTrue())
+					Expect(repo.Exists(ctx, "3")).To(BeTrue())
 				})
 				It("returns false for an artist that is NOT in the DB", func() {
-					Expect(repo.Exists("666")).To(BeFalse())
+					Expect(repo.Exists(ctx, "666")).To(BeFalse())
 				})
 			})
 
 			Describe("Get", func() {
 				It("retrieves existing artist data", func() {
-					artist, err := repo.Get("2")
+					artist, err := repo.Get(ctx, "2")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(artist.Name).To(Equal(artistKraftwerk.Name))
 				})
@@ -392,10 +458,10 @@ var _ = Describe("ArtistRepository", func() {
 				It("returns the index when PreferSortTags is true and SortArtistName is not empty", func() {
 					// Set SortArtistName to "Foo" for Beatles
 					artistBeatles.SortArtistName = "Foo"
-					er := repo.Put(&artistBeatles)
+					er := repo.Put(ctx, &artistBeatles)
 					Expect(er).To(BeNil())
 
-					idx, err := repo.GetIndex(false, []int{1})
+					idx, err := repo.GetIndex(ctx, false, []int{1})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(4))
 					Expect(idx[0].ID).To(Equal("F"))
@@ -413,13 +479,13 @@ var _ = Describe("ArtistRepository", func() {
 
 					// Restore the original value
 					artistBeatles.SortArtistName = ""
-					er = repo.Put(&artistBeatles)
+					er = repo.Put(ctx, &artistBeatles)
 					Expect(er).To(BeNil())
 				})
 
 				// BFR Empty SortArtistName is not saved in the DB anymore
 				XIt("returns the index when PreferSortTags is true and SortArtistName is empty", func() {
-					idx, err := repo.GetIndex(false, []int{1})
+					idx, err := repo.GetIndex(ctx, false, []int{1})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(4))
 					Expect(idx[0].ID).To(Equal("B"))
@@ -444,10 +510,10 @@ var _ = Describe("ArtistRepository", func() {
 				It("returns the index when SortArtistName is NOT empty", func() {
 					// Set SortArtistName to "Foo" for Beatles
 					artistBeatles.SortArtistName = "Foo"
-					er := repo.Put(&artistBeatles)
+					er := repo.Put(ctx, &artistBeatles)
 					Expect(er).To(BeNil())
 
-					idx, err := repo.GetIndex(false, []int{1})
+					idx, err := repo.GetIndex(ctx, false, []int{1})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(4))
 					Expect(idx[0].ID).To(Equal("B"))
@@ -465,12 +531,12 @@ var _ = Describe("ArtistRepository", func() {
 
 					// Restore the original value
 					artistBeatles.SortArtistName = ""
-					er = repo.Put(&artistBeatles)
+					er = repo.Put(ctx, &artistBeatles)
 					Expect(er).To(BeNil())
 				})
 
 				It("returns the index when SortArtistName is empty", func() {
-					idx, err := repo.GetIndex(false, []int{1})
+					idx, err := repo.GetIndex(ctx, false, []int{1})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(4))
 					Expect(idx[0].ID).To(Equal("B"))
@@ -498,14 +564,14 @@ var _ = Describe("ArtistRepository", func() {
 					producerStats := `{"producer": {"s": 500, "m": 3, "a": 1}}`
 
 					// Set Beatles as composer in library 1
-					_, err := raw.executeSQL(squirrel.Insert("library_artist").
+					_, err := raw.executeSQL(ctx, squirrel.Insert("library_artist").
 						Columns("library_id", "artist_id", "stats").
 						Values(1, artistBeatles.ID, composerStats).
 						Suffix("ON CONFLICT(library_id, artist_id) DO UPDATE SET stats = excluded.stats"))
 					Expect(err).ToNot(HaveOccurred())
 
 					// Set Kraftwerk as producer in library 1
-					_, err = raw.executeSQL(squirrel.Insert("library_artist").
+					_, err = raw.executeSQL(ctx, squirrel.Insert("library_artist").
 						Columns("library_id", "artist_id", "stats").
 						Values(1, artistKraftwerk.ID, producerStats).
 						Suffix("ON CONFLICT(library_id, artist_id) DO UPDATE SET stats = excluded.stats"))
@@ -514,16 +580,16 @@ var _ = Describe("ArtistRepository", func() {
 
 				AfterEach(func() {
 					// Clean up stats from library_artist table
-					_, _ = raw.executeSQL(squirrel.Update("library_artist").
+					_, _ = raw.executeSQL(ctx, squirrel.Update("library_artist").
 						Set("stats", "{}").
 						Where(squirrel.Eq{"artist_id": artistBeatles.ID, "library_id": 1}))
-					_, _ = raw.executeSQL(squirrel.Update("library_artist").
+					_, _ = raw.executeSQL(ctx, squirrel.Update("library_artist").
 						Set("stats", "{}").
 						Where(squirrel.Eq{"artist_id": artistKraftwerk.ID, "library_id": 1}))
 				})
 
 				It("returns only artists with the specified role", func() {
-					idx, err := repo.GetIndex(false, []int{1}, model.RoleComposer)
+					idx, err := repo.GetIndex(ctx, false, []int{1}, model.RoleComposer)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(1))
 					Expect(idx[0].ID).To(Equal("B"))
@@ -532,7 +598,7 @@ var _ = Describe("ArtistRepository", func() {
 				})
 
 				It("returns artists with any of the specified roles", func() {
-					idx, err := repo.GetIndex(false, []int{1}, model.RoleComposer, model.RoleProducer)
+					idx, err := repo.GetIndex(ctx, false, []int{1}, model.RoleComposer, model.RoleProducer)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(2))
 
@@ -553,7 +619,7 @@ var _ = Describe("ArtistRepository", func() {
 				})
 
 				It("returns empty index when no artists have the specified role", func() {
-					idx, err := repo.GetIndex(false, []int{1}, model.RoleDirector)
+					idx, err := repo.GetIndex(ctx, false, []int{1}, model.RoleDirector)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(0))
 				})
@@ -561,19 +627,19 @@ var _ = Describe("ArtistRepository", func() {
 
 			When("validating library IDs", func() {
 				It("returns nil when no library IDs are provided", func() {
-					idx, err := repo.GetIndex(false, []int{})
+					idx, err := repo.GetIndex(ctx, false, []int{})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(BeNil())
 				})
 
 				It("returns artists when library IDs are provided (admin user sees all content)", func() {
 					// Admin users can see all content when valid library IDs are provided
-					idx, err := repo.GetIndex(false, []int{1})
+					idx, err := repo.GetIndex(ctx, false, []int{1})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(4))
 
 					// With non-existent library ID, admin users see no content because no artists are associated with that library
-					idx, err = repo.GetIndex(false, []int{999})
+					idx, err = repo.GetIndex(ctx, false, []int{999})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(idx).To(HaveLen(0)) // Even admin users need valid library associations
 				})
@@ -586,23 +652,23 @@ var _ = Describe("ArtistRepository", func() {
 			BeforeEach(func() {
 				// Create artist without any annotation
 				artistWithoutAnnotation = model.Artist{ID: "no-annotation-artist", Name: "No Annotation Artist"}
-				err := createArtistWithLibrary(repo, &artistWithoutAnnotation, 1)
+				err := createArtistWithLibrary(ctx, repo, &artistWithoutAnnotation, 1)
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			AfterEach(func() {
 				if raw, ok := repo.(*artistRepository); ok {
-					_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": artistWithoutAnnotation.ID}))
+					_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": artistWithoutAnnotation.ID}))
 				}
 			})
 
 			Describe("starred", func() {
 				It("false includes items without annotations", func() {
-					res, err := repo.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+					res, err := repo.ReadAll(ctx, rest.QueryOptions{
 						Filters: map[string]any{"starred": "false"},
 					})
 					Expect(err).ToNot(HaveOccurred())
-					artists := res.(model.Artists)
+					artists := res
 
 					var found bool
 					for _, a := range artists {
@@ -615,11 +681,11 @@ var _ = Describe("ArtistRepository", func() {
 				})
 
 				It("true excludes items without annotations", func() {
-					res, err := repo.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+					res, err := repo.ReadAll(ctx, rest.QueryOptions{
 						Filters: map[string]any{"starred": "true"},
 					})
 					Expect(err).ToNot(HaveOccurred())
-					artists := res.(model.Artists)
+					artists := res
 
 					for _, a := range artists {
 						Expect(a.ID).ToNot(Equal(artistWithoutAnnotation.ID))
@@ -631,57 +697,63 @@ var _ = Describe("ArtistRepository", func() {
 		Describe("MBID and Text Search", func() {
 			var lib2 model.Library
 			var lr model.LibraryRepository
+			var lrCtx context.Context
 			var restrictedUser model.User
 			var restrictedRepo model.ArtistRepository
+			var restrictedCtx context.Context
 			var headlessRepo model.ArtistRepository
+			var headlessCtx context.Context
 
 			BeforeEach(func() {
 				// Set up headless repo (no user context)
-				headlessRepo = NewArtistRepository(context.Background(), GetDBXBuilder())
+				headlessCtx = GinkgoT().Context()
+				headlessRepo = NewArtistRepository(GetDBXBuilder())
 
 				// Create library for testing access restrictions
 				lib2 = model.Library{ID: 0, Name: "Artist Test Library", Path: "/artist/test/lib"}
-				lr = NewLibraryRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
-				err := lr.Put(&lib2)
+				lrCtx = request.WithUser(ctx, adminUser)
+				lr = NewLibraryRepository(GetDBXBuilder())
+				err := lr.Put(lrCtx, &lib2)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Create a user with access to only library 1
 				restrictedUser = createUserWithLibraries("search_user", []int{1})
 
 				// Create repository context for the restricted user
-				ctx := request.WithUser(GinkgoT().Context(), restrictedUser)
-				restrictedRepo = NewArtistRepository(ctx, GetDBXBuilder())
+				restrictedCtx = request.WithUser(ctx, restrictedUser)
+				restrictedRepo = NewArtistRepository(GetDBXBuilder())
 
 				// Ensure both test artists are associated with library 1
-				err = lr.AddArtist(1, artistBeatles.ID)
+				err = lr.AddArtist(lrCtx, 1, artistBeatles.ID)
 				Expect(err).ToNot(HaveOccurred())
-				err = lr.AddArtist(1, artistKraftwerk.ID)
+				err = lr.AddArtist(lrCtx, 1, artistKraftwerk.ID)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Create the restricted user in the database
-				ur := NewUserRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
-				err = ur.Put(&restrictedUser)
+				urCtx := request.WithUser(ctx, adminUser)
+				ur := NewUserRepository(GetDBXBuilder())
+				err = ur.Put(urCtx, &restrictedUser)
 				Expect(err).ToNot(HaveOccurred())
-				err = ur.SetUserLibraries(restrictedUser.ID, []int{1})
+				err = ur.SetUserLibraries(urCtx, restrictedUser.ID, []int{1})
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			AfterEach(func() {
 				// Clean up library 2
-				lr := NewLibraryRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
-				_ = lr.(*libraryRepository).delete(squirrel.Eq{"id": lib2.ID})
+				lr := NewLibraryRepository(GetDBXBuilder())
+				_ = lr.(*libraryRepository).delete(ctx, squirrel.Eq{"id": lib2.ID})
 			})
 
 			DescribeTable("MBID search behavior across different user types",
-				func(testRepo *model.ArtistRepository, shouldFind bool, testDesc string) {
+				func(testRepo *model.ArtistRepository, testCtx *context.Context, shouldFind bool, testDesc string) {
 					// Create test artist with MBID
 					artistWithMBID := createTestArtistWithMBID("test-mbid-artist", "Test MBID Artist", "550e8400-e29b-41d4-a716-446655440010")
 
-					err := createArtistWithLibrary(*testRepo, &artistWithMBID, 1)
+					err := createArtistWithLibrary(*testCtx, *testRepo, &artistWithMBID, 1)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Test the search
-					results, err := (*testRepo).Search("550e8400-e29b-41d4-a716-446655440010", model.QueryOptions{Max: 10})
+					results, err := (*testRepo).Search(*testCtx, "550e8400-e29b-41d4-a716-446655440010", model.QueryOptions{Max: 10})
 					Expect(err).ToNot(HaveOccurred())
 
 					if shouldFind {
@@ -693,43 +765,43 @@ var _ = Describe("ArtistRepository", func() {
 
 					// Clean up
 					if raw, ok := (*testRepo).(*artistRepository); ok {
-						_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": artistWithMBID.ID}))
+						_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": artistWithMBID.ID}))
 					}
 				},
-				Entry("Admin user can find artist by MBID", &repo, true, "Admin should find MBID artist"),
-				Entry("Restricted user can find artist by MBID in accessible library", &restrictedRepo, true, "Restricted user should find MBID artist in accessible library"),
-				Entry("Headless process can find artist by MBID", &headlessRepo, true, "Headless process should find MBID artist"),
+				Entry("Admin user can find artist by MBID", &repo, &ctx, true, "Admin should find MBID artist"),
+				Entry("Restricted user can find artist by MBID in accessible library", &restrictedRepo, &restrictedCtx, true, "Restricted user should find MBID artist in accessible library"),
+				Entry("Headless process can find artist by MBID", &headlessRepo, &headlessCtx, true, "Headless process should find MBID artist"),
 			)
 
 			It("prevents restricted user from finding artist by MBID when not in accessible library", func() {
 				// Create an artist in library 2 (not accessible to restricted user)
 				inaccessibleArtist := createTestArtistWithMBID("inaccessible-mbid-artist", "Inaccessible MBID Artist", "a74b1b7f-71a5-4011-9441-d0b5e4122711")
-				err := repo.Put(&inaccessibleArtist)
+				err := repo.Put(ctx, &inaccessibleArtist)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Add to library 2 (not accessible to restricted user)
-				err = lr.AddArtist(lib2.ID, inaccessibleArtist.ID)
+				err = lr.AddArtist(lrCtx, lib2.ID, inaccessibleArtist.ID)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Restricted user should not find this artist
-				results, err := restrictedRepo.Search("a74b1b7f-71a5-4011-9441-d0b5e4122711", model.QueryOptions{Max: 10})
+				results, err := restrictedRepo.Search(restrictedCtx, "a74b1b7f-71a5-4011-9441-d0b5e4122711", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 
 				// But admin should find it
-				results, err = repo.Search("a74b1b7f-71a5-4011-9441-d0b5e4122711", model.QueryOptions{Max: 10})
+				results, err = repo.Search(ctx, "a74b1b7f-71a5-4011-9441-d0b5e4122711", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(1))
 
 				// Clean up
 				if raw, ok := repo.(*artistRepository); ok {
-					_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": inaccessibleArtist.ID}))
+					_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": inaccessibleArtist.ID}))
 				}
 			})
 
 			Context("Text Search", func() {
 				It("allows admin to find artists by name regardless of library", func() {
-					results, err := repo.Search("Beatles", model.QueryOptions{Max: 10})
+					results, err := repo.Search(ctx, "Beatles", model.QueryOptions{Max: 10})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(results).To(HaveLen(1))
 					Expect(results[0].Name).To(Equal("The Beatles"))
@@ -741,21 +813,21 @@ var _ = Describe("ArtistRepository", func() {
 						ID:   "inaccessible-text-artist",
 						Name: "Unique Search Name Artist",
 					}
-					err := repo.Put(&inaccessibleArtist)
+					err := repo.Put(ctx, &inaccessibleArtist)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Add to library 2 (not accessible to restricted user)
-					err = lr.AddArtist(lib2.ID, inaccessibleArtist.ID)
+					err = lr.AddArtist(lrCtx, lib2.ID, inaccessibleArtist.ID)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Restricted user should not find this artist
-					results, err := restrictedRepo.Search("Unique Search Name", model.QueryOptions{Max: 10})
+					results, err := restrictedRepo.Search(restrictedCtx, "Unique Search Name", model.QueryOptions{Max: 10})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(results).To(BeEmpty(), "Text search should respect library filtering")
 
 					// Clean up
 					if raw, ok := repo.(*artistRepository); ok {
-						_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": inaccessibleArtist.ID}))
+						_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": inaccessibleArtist.ID}))
 					}
 				})
 			})
@@ -764,15 +836,15 @@ var _ = Describe("ArtistRepository", func() {
 				It("does not duplicate artists that belong to multiple libraries", func() {
 					// An artist in two libraries has two library_artist rows; pagination
 					// must still enumerate it exactly once, at a stable offset.
-					Expect(lr.AddArtist(lib2.ID, artistBeatles.ID)).To(Succeed())
+					Expect(lr.AddArtist(lrCtx, lib2.ID, artistBeatles.ID)).To(Succeed())
 
-					all, err := repo.Search("", model.QueryOptions{Max: 1000})
+					all, err := repo.Search(ctx, "", model.QueryOptions{Max: 1000})
 					Expect(err).ToNot(HaveOccurred())
 
 					seen := map[string]bool{}
 					var paged model.Artists
 					for offset := range len(all) {
-						page, err := repo.Search("", model.QueryOptions{Max: 1, Offset: offset})
+						page, err := repo.Search(ctx, "", model.QueryOptions{Max: 1, Offset: offset})
 						Expect(err).ToNot(HaveOccurred())
 						for _, a := range page {
 							Expect(seen[a.ID]).To(BeFalse(), fmt.Sprintf("artist %s returned twice", a.ID))
@@ -784,14 +856,14 @@ var _ = Describe("ArtistRepository", func() {
 				})
 
 				It("paginates all artists in natural order without overlaps or gaps", func() {
-					all, err := repo.Search("", model.QueryOptions{Max: 1000})
+					all, err := repo.Search(ctx, "", model.QueryOptions{Max: 1000})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(len(all)).To(BeNumerically(">", 1))
 
 					var paged model.Artists
 					pageSize := 2
 					for offset := 0; offset < len(all); offset += pageSize {
-						page, err := repo.Search("", model.QueryOptions{Max: pageSize, Offset: offset})
+						page, err := repo.Search(ctx, "", model.QueryOptions{Max: pageSize, Offset: offset})
 						Expect(err).ToNot(HaveOccurred())
 						paged = append(paged, page...)
 					}
@@ -804,10 +876,10 @@ var _ = Describe("ArtistRepository", func() {
 				It("respects library filtering for restricted users", func() {
 					// Create an artist only in library 2 (not accessible to restricted user)
 					lib2Artist := model.Artist{ID: "empty-query-lib2-artist", Name: "Empty Query Lib2 Artist"}
-					Expect(repo.Put(&lib2Artist)).To(Succeed())
-					Expect(lr.AddArtist(lib2.ID, lib2Artist.ID)).To(Succeed())
+					Expect(repo.Put(ctx, &lib2Artist)).To(Succeed())
+					Expect(lr.AddArtist(lrCtx, lib2.ID, lib2Artist.ID)).To(Succeed())
 
-					results, err := restrictedRepo.Search("", model.QueryOptions{Max: 1000})
+					results, err := restrictedRepo.Search(restrictedCtx, "", model.QueryOptions{Max: 1000})
 					Expect(err).ToNot(HaveOccurred())
 					for _, a := range results {
 						Expect(a.ID).ToNot(Equal(lib2Artist.ID), "Empty query search should respect library filtering")
@@ -815,7 +887,7 @@ var _ = Describe("ArtistRepository", func() {
 
 					// Clean up
 					if raw, ok := repo.(*artistRepository); ok {
-						_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": lib2Artist.ID}))
+						_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": lib2Artist.ID}))
 					}
 				})
 
@@ -823,15 +895,15 @@ var _ = Describe("ArtistRepository", func() {
 					// ID "25" sorts between base fixtures "2" and "3", so this lib2-only artist lands
 					// inside the restricted user's visible range — exercising the no-gap guarantee.
 					lib2Artist := model.Artist{ID: "25", Name: "Restricted Lib2 Artist"}
-					Expect(repo.Put(&lib2Artist)).To(Succeed())
-					Expect(lr.AddArtist(lib2.ID, lib2Artist.ID)).To(Succeed())
+					Expect(repo.Put(ctx, &lib2Artist)).To(Succeed())
+					Expect(lr.AddArtist(lrCtx, lib2.ID, lib2Artist.ID)).To(Succeed())
 					DeferCleanup(func() {
 						if raw, ok := repo.(*artistRepository); ok {
-							_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": lib2Artist.ID}))
+							_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": lib2Artist.ID}))
 						}
 					})
 
-					all, err := restrictedRepo.Search("", model.QueryOptions{Max: 1000})
+					all, err := restrictedRepo.Search(restrictedCtx, "", model.QueryOptions{Max: 1000})
 					Expect(err).ToNot(HaveOccurred())
 					Expect(len(all)).To(BeNumerically(">", 1))
 					for _, a := range all {
@@ -840,7 +912,7 @@ var _ = Describe("ArtistRepository", func() {
 
 					var paged model.Artists
 					for offset := range len(all) {
-						page, err := restrictedRepo.Search("", model.QueryOptions{Max: 1, Offset: offset})
+						page, err := restrictedRepo.Search(restrictedCtx, "", model.QueryOptions{Max: 1, Offset: offset})
 						Expect(err).ToNot(HaveOccurred())
 						Expect(page).To(HaveLen(1), fmt.Sprintf("page at offset %d should be full", offset))
 						paged = append(paged, page...)
@@ -855,11 +927,11 @@ var _ = Describe("ArtistRepository", func() {
 			Context("Headless Processes (No User Context)", func() {
 				It("should see all artists from all libraries when no user is in context", func() {
 					// Add artists to different libraries
-					err := lr.AddArtist(lib2.ID, artistBeatles.ID)
+					err := lr.AddArtist(lrCtx, lib2.ID, artistBeatles.ID)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Headless processes should see all artists regardless of library
-					artists, err := headlessRepo.GetAll()
+					artists, err := headlessRepo.GetAll(headlessCtx)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Should see all artists from all libraries
@@ -875,11 +947,11 @@ var _ = Describe("ArtistRepository", func() {
 
 				It("should allow headless processes to apply explicit library_id filters", func() {
 					// Add artists to different libraries
-					err := lr.AddArtist(lib2.ID, artistBeatles.ID)
+					err := lr.AddArtist(lrCtx, lib2.ID, artistBeatles.ID)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Filter by specific library
-					artists, err := headlessRepo.GetAll(model.QueryOptions{
+					artists, err := headlessRepo.GetAll(headlessCtx, model.QueryOptions{
 						Filters: squirrel.Eq{"library_id": lib2.ID},
 					})
 					Expect(err).ToNot(HaveOccurred())
@@ -895,11 +967,11 @@ var _ = Describe("ArtistRepository", func() {
 
 				It("should get individual artists when no user is in context", func() {
 					// Add artist to a library
-					err := lr.AddArtist(lib2.ID, artistBeatles.ID)
+					err := lr.AddArtist(lrCtx, lib2.ID, artistBeatles.ID)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Headless process should be able to get the artist
-					artist, err := headlessRepo.Get(artistBeatles.ID)
+					artist, err := headlessRepo.Get(headlessCtx, artistBeatles.ID)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(artist.ID).To(Equal(artistBeatles.ID))
 				})
@@ -908,15 +980,15 @@ var _ = Describe("ArtistRepository", func() {
 
 		Describe("Admin User Library Access", func() {
 			It("sees all artists regardless of library permissions", func() {
-				count, err := repo.CountAll()
+				count, err := repo.CountAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(4)))
 
-				artists, err := repo.GetAll()
+				artists, err := repo.GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(artists).To(HaveLen(4))
 
-				exists, err := repo.Exists(artistBeatles.ID)
+				exists, err := repo.Exists(ctx, artistBeatles.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(exists).To(BeTrue())
 			})
@@ -931,25 +1003,25 @@ var _ = Describe("ArtistRepository", func() {
 				missingArtist = model.Artist{ID: "missing_test", Name: "Missing Artist", OrderArtistName: "missing artist"}
 
 				// Create and mark as missing
-				err := createArtistWithLibrary(repo, &missingArtist, 1)
+				err := createArtistWithLibrary(ctx, repo, &missingArtist, 1)
 				Expect(err).ToNot(HaveOccurred())
 
-				_, err = raw.executeSQL(squirrel.Update(raw.tableName).Set("missing", true).Where(squirrel.Eq{"id": missingArtist.ID}))
+				_, err = raw.executeSQL(ctx, squirrel.Update(raw.tableName).Set("missing", true).Where(squirrel.Eq{"id": missingArtist.ID}))
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			AfterEach(func() {
-				_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": missingArtist.ID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": missingArtist.ID}))
 			})
 
 			It("missing artists are never returned by search", func() {
 				// Should see missing artist in GetAll by default for admin users
-				artists, err := repo.GetAll()
+				artists, err := repo.GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(artists).To(HaveLen(5)) // Including the missing artist
 
 				// Search never returns missing artists (hardcoded behavior)
-				results, err := repo.Search("Missing Artist", model.QueryOptions{Max: 10})
+				results, err := repo.Search(ctx, "Missing Artist", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 			})
@@ -958,6 +1030,7 @@ var _ = Describe("ArtistRepository", func() {
 
 	Context("Regular User Operations", func() {
 		var restrictedRepo model.ArtistRepository
+		var restrictedCtx context.Context
 		var unauthorizedUser model.User
 
 		BeforeEach(func() {
@@ -965,55 +1038,54 @@ var _ = Describe("ArtistRepository", func() {
 			unauthorizedUser = model.User{ID: "restricted_user", UserName: "restricted", Name: "Restricted User", Email: "restricted@test.com", IsAdmin: false}
 
 			// Create repository context for the unauthorized user
-			ctx := GinkgoT().Context()
-			ctx = request.WithUser(ctx, unauthorizedUser)
-			restrictedRepo = NewArtistRepository(ctx, GetDBXBuilder())
+			restrictedCtx = request.WithUser(ctx, unauthorizedUser)
+			restrictedRepo = NewArtistRepository(GetDBXBuilder())
 		})
 
 		Describe("Library Access Restrictions", func() {
 			It("CountAll returns 0 for users without library access", func() {
-				count, err := restrictedRepo.CountAll()
+				count, err := restrictedRepo.CountAll(restrictedCtx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(0)))
 			})
 
 			It("GetAll returns empty list for users without library access", func() {
-				artists, err := restrictedRepo.GetAll()
+				artists, err := restrictedRepo.GetAll(restrictedCtx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(artists).To(BeEmpty())
 			})
 
 			It("Exists returns false for existing artists when user has no library access", func() {
 				// These artists exist in the DB but the user has no access to them
-				exists, err := restrictedRepo.Exists(artistBeatles.ID)
+				exists, err := restrictedRepo.Exists(restrictedCtx, artistBeatles.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(exists).To(BeFalse())
 
-				exists, err = restrictedRepo.Exists(artistKraftwerk.ID)
+				exists, err = restrictedRepo.Exists(restrictedCtx, artistKraftwerk.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(exists).To(BeFalse())
 			})
 
 			It("Get returns ErrNotFound for existing artists when user has no library access", func() {
-				_, err := restrictedRepo.Get(artistBeatles.ID)
+				_, err := restrictedRepo.Get(restrictedCtx, artistBeatles.ID)
 				Expect(err).To(Equal(model.ErrNotFound))
 
-				_, err = restrictedRepo.Get(artistKraftwerk.ID)
+				_, err = restrictedRepo.Get(restrictedCtx, artistKraftwerk.ID)
 				Expect(err).To(Equal(model.ErrNotFound))
 			})
 
 			It("Search returns empty results for users without library access", func() {
-				results, err := restrictedRepo.Search("Beatles", model.QueryOptions{Max: 10})
+				results, err := restrictedRepo.Search(restrictedCtx, "Beatles", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 
-				results, err = restrictedRepo.Search("Kraftwerk", model.QueryOptions{Max: 10})
+				results, err = restrictedRepo.Search(restrictedCtx, "Kraftwerk", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 			})
 
 			It("GetIndex returns empty index for users without library access", func() {
-				idx, err := restrictedRepo.GetIndex(false, []int{1})
+				idx, err := restrictedRepo.GetIndex(restrictedCtx, false, []int{1})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(idx).To(HaveLen(0))
 			})
@@ -1021,42 +1093,43 @@ var _ = Describe("ArtistRepository", func() {
 
 		Context("when user gains library access", func() {
 			BeforeEach(func() {
-				ctx := GinkgoT().Context()
 				// Give the user access to library 1
-				ur := NewUserRepository(request.WithUser(ctx, adminUser), GetDBXBuilder())
+				urCtx := request.WithUser(ctx, adminUser)
+				ur := NewUserRepository(GetDBXBuilder())
 
 				// First create the user if not exists
-				err := ur.Put(&unauthorizedUser)
+				err := ur.Put(urCtx, &unauthorizedUser)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Then add library access
-				err = ur.SetUserLibraries(unauthorizedUser.ID, []int{1})
+				err = ur.SetUserLibraries(urCtx, unauthorizedUser.ID, []int{1})
 				Expect(err).ToNot(HaveOccurred())
 
 				// Update the user object with the libraries to simulate middleware behavior
-				libraries, err := ur.GetUserLibraries(unauthorizedUser.ID)
+				libraries, err := ur.GetUserLibraries(urCtx, unauthorizedUser.ID)
 				Expect(err).ToNot(HaveOccurred())
 				unauthorizedUser.Libraries = libraries
 
 				// Recreate repository context with updated user
-				ctx = request.WithUser(ctx, unauthorizedUser)
-				restrictedRepo = NewArtistRepository(ctx, GetDBXBuilder())
+				restrictedCtx = request.WithUser(ctx, unauthorizedUser)
+				restrictedRepo = NewArtistRepository(GetDBXBuilder())
 			})
 
 			AfterEach(func() {
 				// Clean up: remove the user's library access
-				ur := NewUserRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
-				_ = ur.SetUserLibraries(unauthorizedUser.ID, []int{})
+				urCtx := request.WithUser(ctx, adminUser)
+				ur := NewUserRepository(GetDBXBuilder())
+				_ = ur.SetUserLibraries(urCtx, unauthorizedUser.ID, []int{})
 			})
 
 			It("CountAll returns correct count after gaining access", func() {
-				count, err := restrictedRepo.CountAll()
+				count, err := restrictedRepo.CountAll(restrictedCtx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(4))) // Beatles, Kraftwerk, Seatbelts, and The Roots
 			})
 
 			It("GetAll returns artists after gaining access", func() {
-				artists, err := restrictedRepo.GetAll()
+				artists, err := restrictedRepo.GetAll(restrictedCtx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(artists).To(HaveLen(4))
 
@@ -1068,23 +1141,23 @@ var _ = Describe("ArtistRepository", func() {
 			})
 
 			It("Exists returns true for accessible artists", func() {
-				exists, err := restrictedRepo.Exists(artistBeatles.ID)
+				exists, err := restrictedRepo.Exists(restrictedCtx, artistBeatles.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(exists).To(BeTrue())
 
-				exists, err = restrictedRepo.Exists(artistKraftwerk.ID)
+				exists, err = restrictedRepo.Exists(restrictedCtx, artistKraftwerk.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(exists).To(BeTrue())
 			})
 
 			It("GetIndex returns artists with proper library filtering", func() {
 				// With valid library access, should see artists
-				idx, err := restrictedRepo.GetIndex(false, []int{1})
+				idx, err := restrictedRepo.GetIndex(restrictedCtx, false, []int{1})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(idx).To(HaveLen(4))
 
 				// With non-existent library ID, should see nothing (non-admin user)
-				idx, err = restrictedRepo.GetIndex(false, []int{999})
+				idx, err = restrictedRepo.GetIndex(restrictedCtx, false, []int{999})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(idx).To(HaveLen(0))
 			})
@@ -1092,11 +1165,12 @@ var _ = Describe("ArtistRepository", func() {
 			It("takes the unfiltered fast-path when the user can access every library", func() {
 				// The fixture DB has a single library and the user was granted it, so it has access
 				// to all libraries: search results must match what an admin sees.
-				adminRepo := NewArtistRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
-				adminAll, err := adminRepo.Search("", model.QueryOptions{Max: 1000})
+				adminCtx := request.WithUser(ctx, adminUser)
+				adminRepo := NewArtistRepository(GetDBXBuilder())
+				adminAll, err := adminRepo.Search(adminCtx, "", model.QueryOptions{Max: 1000})
 				Expect(err).ToNot(HaveOccurred())
 
-				userAll, err := restrictedRepo.Search("", model.QueryOptions{Max: 1000})
+				userAll, err := restrictedRepo.Search(restrictedCtx, "", model.QueryOptions{Max: 1000})
 				Expect(err).ToNot(HaveOccurred())
 
 				ids := func(artists model.Artists) []string {
@@ -1115,7 +1189,7 @@ var _ = Describe("ArtistRepository", func() {
 				// visible-library count reaches the DB total. Derive the total from the DB so the
 				// assertion doesn't depend on how many libraries other specs left behind.
 				raw := restrictedRepo.(*artistRepository) // context carries a non-admin user
-				total, err := NewLibraryRepository(GinkgoT().Context(), GetDBXBuilder()).CountAll()
+				total, err := NewLibraryRepository(GetDBXBuilder()).CountAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(total).To(BeNumerically(">", 0))
 
@@ -1123,9 +1197,9 @@ var _ = Describe("ArtistRepository", func() {
 				for i := range allLibs {
 					allLibs[i] = i + 1
 				}
-				Expect(raw.userSeesAllLibraries(allLibs)).To(BeTrue())
-				Expect(raw.userSeesAllLibraries(allLibs[:total-1])).To(BeFalse())
-				Expect(raw.userSeesAllLibraries([]int{})).To(BeFalse())
+				Expect(raw.userSeesAllLibraries(restrictedCtx, allLibs)).To(BeTrue())
+				Expect(raw.userSeesAllLibraries(restrictedCtx, allLibs[:total-1])).To(BeFalse())
+				Expect(raw.userSeesAllLibraries(restrictedCtx, []int{})).To(BeFalse())
 			})
 		})
 	})
@@ -1139,8 +1213,8 @@ var _ = Describe("ArtistRepository", func() {
 			tmpDir = GinkgoT().TempDir()
 			conf.Server.DataFolder = conf.NewDir(tmpDir)
 
-			ctx := request.WithUser(GinkgoT().Context(), adminUser)
-			repo = NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)
+			ctx = request.WithUser(ctx, adminUser)
+			repo = NewArtistRepository(GetDBXBuilder()).(*artistRepository)
 		})
 
 		// Helper to create an artist image file on disk and return its path
@@ -1155,13 +1229,13 @@ var _ = Describe("ArtistRepository", func() {
 		It("removes uploaded image files for purged artists", func() {
 			// Create an orphan artist (not in album_artists) with an uploaded image
 			orphanArtist := model.Artist{ID: "orphan-with-image", Name: "Orphan Artist", UploadedImage: "orphan-with-image_Orphan_Artist.jpg"}
-			Expect(repo.Put(&orphanArtist)).To(Succeed())
+			Expect(repo.Put(ctx, &orphanArtist)).To(Succeed())
 			imgPath := createImageFile("orphan-with-image_Orphan_Artist.jpg")
 
-			Expect(repo.purgeEmpty()).To(Succeed())
+			Expect(repo.purgeEmpty(ctx)).To(Succeed())
 
 			// Artist should be gone from DB
-			exists, err := repo.Exists("orphan-with-image")
+			exists, err := repo.Exists(ctx, "orphan-with-image")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(exists).To(BeFalse())
 
@@ -1173,12 +1247,12 @@ var _ = Describe("ArtistRepository", func() {
 		It("handles missing image files gracefully", func() {
 			// Artist has UploadedImage set but no actual file on disk
 			orphanArtist := model.Artist{ID: "orphan-no-file", Name: "Ghost Image", UploadedImage: "orphan-no-file_Ghost_Image.jpg"}
-			Expect(repo.Put(&orphanArtist)).To(Succeed())
+			Expect(repo.Put(ctx, &orphanArtist)).To(Succeed())
 
-			Expect(repo.purgeEmpty()).To(Succeed())
+			Expect(repo.purgeEmpty(ctx)).To(Succeed())
 
 			// Artist should be gone from DB
-			exists, err := repo.Exists("orphan-no-file")
+			exists, err := repo.Exists(ctx, "orphan-no-file")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(exists).To(BeFalse())
 		})
@@ -1186,24 +1260,24 @@ var _ = Describe("ArtistRepository", func() {
 		It("does not delete images for artists that are kept", func() {
 			// Create an artist with an uploaded image AND an album_artists entry so it won't be purged
 			keptArtist := model.Artist{ID: "kept-artist", Name: "Kept Artist", UploadedImage: "kept-artist_Kept_Artist.jpg"}
-			Expect(repo.Put(&keptArtist)).To(Succeed())
+			Expect(repo.Put(ctx, &keptArtist)).To(Succeed())
 			imgPath := createImageFile("kept-artist_Kept_Artist.jpg")
 
 			// Insert an album_artists record to keep this artist from being purged
-			_, err := repo.executeSQL(squirrel.Insert("album_artists").
+			_, err := repo.executeSQL(ctx, squirrel.Insert("album_artists").
 				SetMap(map[string]any{"album_id": "101", "artist_id": "kept-artist", "role": "artist", "sub_role": ""}))
 			Expect(err).ToNot(HaveOccurred())
 
 			DeferCleanup(func() {
-				_, _ = repo.executeSQL(squirrel.Delete("album_artists").Where(squirrel.Eq{"artist_id": "kept-artist"}))
-				_ = repo.delete(squirrel.Eq{"id": "kept-artist"})
+				_, _ = repo.executeSQL(ctx, squirrel.Delete("album_artists").Where(squirrel.Eq{"artist_id": "kept-artist"}))
+				_ = repo.delete(ctx, squirrel.Eq{"id": "kept-artist"})
 			})
 
-			Expect(repo.purgeEmpty()).To(Succeed())
+			Expect(repo.purgeEmpty(ctx)).To(Succeed())
 
 			// Artist should still exist (check directly, bypassing library filter)
 			var ids []string
-			err = repo.queryAllSlice(squirrel.Select("id").From("artist").Where(squirrel.Eq{"id": "kept-artist"}), &ids)
+			err = repo.queryAllSlice(ctx, squirrel.Select("id").From("artist").Where(squirrel.Eq{"id": "kept-artist"}), &ids)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(HaveLen(1))
 
@@ -1218,37 +1292,37 @@ var _ = Describe("ArtistRepository", func() {
 
 		missing := func(id string) bool {
 			var vals []bool
-			Expect(repo.queryAllSlice(squirrel.Select("missing").From("artist").Where(squirrel.Eq{"id": id}), &vals)).To(Succeed())
+			Expect(repo.queryAllSlice(ctx, squirrel.Select("missing").From("artist").Where(squirrel.Eq{"id": id}), &vals)).To(Succeed())
 			Expect(vals).To(HaveLen(1))
 			return vals[0]
 		}
 
 		BeforeEach(func() {
-			ctx := request.WithUser(GinkgoT().Context(), adminUser)
-			repo = NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)
+			ctx = request.WithUser(ctx, adminUser)
+			repo = NewArtistRepository(GetDBXBuilder()).(*artistRepository)
 		})
 
 		It("marks artists missing when the empty-stats cleanup drops their last library_artist row", func() {
 			// A library_artist row with stats '{}' (no content) gets deleted by the cleanup,
 			// which would orphan this non-missing artist.
 			emptyArtist := model.Artist{ID: "refresh-empty", Name: "No Content Artist"}
-			Expect(repo.Put(&emptyArtist)).To(Succeed())
-			_, err := repo.executeSQL(squirrel.Insert("library_artist").
+			Expect(repo.Put(ctx, &emptyArtist)).To(Succeed())
+			_, err := repo.executeSQL(ctx, squirrel.Insert("library_artist").
 				SetMap(map[string]any{"library_id": 1, "artist_id": emptyArtist.ID, "stats": "{}"}))
 			Expect(err).ToNot(HaveOccurred())
 			DeferCleanup(func() {
-				_, _ = repo.executeSQL(squirrel.Delete("library_artist").Where(squirrel.Eq{"artist_id": emptyArtist.ID}))
-				_ = repo.delete(squirrel.Eq{"id": emptyArtist.ID})
+				_, _ = repo.executeSQL(ctx, squirrel.Delete("library_artist").Where(squirrel.Eq{"artist_id": emptyArtist.ID}))
+				_ = repo.delete(ctx, squirrel.Eq{"id": emptyArtist.ID})
 			})
 
 			Expect(missing(emptyArtist.ID)).To(BeFalse())
 
-			_, err = repo.RefreshStats(true)
+			_, err = repo.RefreshStats(ctx, true)
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(missing(emptyArtist.ID)).To(BeTrue())
 			var orphanIDs []string
-			Expect(repo.queryAllSlice(squirrel.Select("id").From("artist").
+			Expect(repo.queryAllSlice(ctx, squirrel.Select("id").From("artist").
 				Where("missing = false").
 				Where("id not in (select artist_id from library_artist)"), &orphanIDs)).To(Succeed())
 			Expect(orphanIDs).ToNot(ContainElement(emptyArtist.ID))
@@ -1259,14 +1333,14 @@ var _ = Describe("ArtistRepository", func() {
 			// all. The cleanup deletes nothing for it, so a full refresh (allArtists) must still
 			// reconcile it.
 			legacyOrphan := model.Artist{ID: "refresh-legacy-orphan", Name: "Legacy Orphan"}
-			Expect(repo.Put(&legacyOrphan)).To(Succeed())
+			Expect(repo.Put(ctx, &legacyOrphan)).To(Succeed())
 			DeferCleanup(func() {
-				_ = repo.delete(squirrel.Eq{"id": legacyOrphan.ID})
+				_ = repo.delete(ctx, squirrel.Eq{"id": legacyOrphan.ID})
 			})
 
 			Expect(missing(legacyOrphan.ID)).To(BeFalse())
 
-			_, err := repo.RefreshStats(true)
+			_, err := repo.RefreshStats(ctx, true)
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(missing(legacyOrphan.ID)).To(BeTrue())
@@ -1276,13 +1350,13 @@ var _ = Describe("ArtistRepository", func() {
 
 // Helper function to create an artist with proper library association.
 // This ensures test artists always have library_artist associations to avoid orphaned artists in tests.
-func createArtistWithLibrary(repo model.ArtistRepository, artist *model.Artist, libraryID int) error {
-	err := repo.Put(artist)
+func createArtistWithLibrary(ctx context.Context, repo model.ArtistRepository, artist *model.Artist, libraryID int) error {
+	err := repo.Put(ctx, artist)
 	if err != nil {
 		return err
 	}
 
 	// Add the artist to the specified library
-	lr := NewLibraryRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
-	return lr.AddArtist(libraryID, artist.ID)
+	lr := NewLibraryRepository(GetDBXBuilder())
+	return lr.AddArtist(request.WithUser(ctx, adminUser), libraryID, artist.ID)
 }
diff --git a/persistence/artwork_hydration.go b/persistence/artwork_hydration.go
index fa9920f27..76646ec74 100644
--- a/persistence/artwork_hydration.go
+++ b/persistence/artwork_hydration.go
@@ -59,7 +59,7 @@ func hydrateItemImages(ctx context.Context, db dbx.Builder, kind model.Kind, ids
 	if len(ids) == 0 {
 		return map[string]model.ItemArtworkInfo{}
 	}
-	infos, err := NewArtworkRepository(ctx, db).GetInfoForItems(kind, ids)
+	infos, err := NewArtworkRepository(db).GetInfoForItems(ctx, kind, ids)
 	if err != nil {
 		log.Error(ctx, "Failed to hydrate artwork info onto page", "kind", kind, err)
 		return map[string]model.ItemArtworkInfo{}
diff --git a/persistence/artwork_hydration_test.go b/persistence/artwork_hydration_test.go
index bb9cda04d..89182d6cc 100644
--- a/persistence/artwork_hydration_test.go
+++ b/persistence/artwork_hydration_test.go
@@ -45,7 +45,7 @@ var _ = Describe("Artwork hydration", func() {
 	var aw model.ArtworkRepository
 
 	putInfo := func(kind, id, hash string) {
-		Expect(aw.PutItemArtwork(&model.ItemArtwork{
+		Expect(aw.PutItemArtwork(ctx, &model.ItemArtwork{
 			ItemKind: kind, ItemID: id, ImageType: model.ImageTypePrimary, Hash: hash,
 		})).To(Succeed())
 	}
@@ -54,19 +54,19 @@ var _ = Describe("Artwork hydration", func() {
 		clearArtworkTables()
 		DeferCleanup(clearArtworkTables)
 		ctx = request.WithUser(log.NewContext(context.Background()), adminUser)
-		aw = NewArtworkRepository(ctx, GetDBXBuilder())
+		aw = NewArtworkRepository(GetDBXBuilder())
 	})
 
 	Describe("albums", func() {
 		var repo model.AlbumRepository
-		BeforeEach(func() { repo = NewAlbumRepository(ctx, GetDBXBuilder()) })
+		BeforeEach(func() { repo = NewAlbumRepository(GetDBXBuilder()) })
 
 		It("hydrates the found / known-absent / unresolved states", func() {
 			putInfo("al", albumSgtPeppers.ID, "althash11111111")
 			putInfo("al", albumAbbeyRoad.ID, "")
 			// albumRadioactivity: no row -> unresolved
 
-			all, err := repo.GetAll()
+			all, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			byID := slice.ToMap(all, func(a model.Album) (string, model.Album) { return a.ID, a })
 
@@ -80,14 +80,14 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates Get", func() {
 			putInfo("al", albumSgtPeppers.ID, "gethash22222222")
-			got, err := repo.Get(albumSgtPeppers.ID)
+			got, err := repo.Get(ctx, albumSgtPeppers.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.ImageHash).To(Equal("gethash22222222"))
 		})
 
 		It("hydrates Search", func() {
 			putInfo("al", albumSgtPeppers.ID, "srchash33333333")
-			res, err := repo.Search("Peppers", model.QueryOptions{})
+			res, err := repo.Search(ctx, "Peppers", model.QueryOptions{})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res).ToNot(BeEmpty())
 			Expect(res[0].ImageHash).To(Equal("srchash33333333"))
@@ -97,9 +97,9 @@ var _ = Describe("Artwork hydration", func() {
 			al := albumSgtPeppers
 			al.ImageHash = "shouldnotpersist"
 			al.ImageAbsent = true
-			Expect(repo.(*albumRepository).Put(&al)).To(Succeed())
+			Expect(repo.(*albumRepository).Put(ctx, &al)).To(Succeed())
 
-			got, err := repo.Get(al.ID)
+			got, err := repo.Get(ctx, al.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.ImageHash).To(BeEmpty())
 			Expect(got.ImageAbsent).To(BeFalse())
@@ -108,14 +108,14 @@ var _ = Describe("Artwork hydration", func() {
 
 	Describe("artists", func() {
 		var repo model.ArtistRepository
-		BeforeEach(func() { repo = NewArtistRepository(ctx, GetDBXBuilder()) })
+		BeforeEach(func() { repo = NewArtistRepository(GetDBXBuilder()) })
 
 		It("hydrates the found / known-absent / unresolved states", func() {
 			putInfo("ar", artistBeatles.ID, "arhash444444444")
 			putInfo("ar", artistKraftwerk.ID, "")
 			// artistCJK: no row -> unresolved
 
-			all, err := repo.GetAll()
+			all, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			byID := slice.ToMap(all, func(a model.Artist) (string, model.Artist) { return a.ID, a })
 
@@ -129,14 +129,14 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates Get", func() {
 			putInfo("ar", artistBeatles.ID, "arget5555555555")
-			got, err := repo.Get(artistBeatles.ID)
+			got, err := repo.Get(ctx, artistBeatles.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.ImageHash).To(Equal("arget5555555555"))
 		})
 
 		It("hydrates Search", func() {
 			putInfo("ar", artistBeatles.ID, "arsrch666666666")
-			res, err := repo.Search("Beatles", model.QueryOptions{})
+			res, err := repo.Search(ctx, "Beatles", model.QueryOptions{})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res).ToNot(BeEmpty())
 			Expect(res[0].ImageHash).To(Equal("arsrch666666666"))
@@ -145,13 +145,13 @@ var _ = Describe("Artwork hydration", func() {
 
 	Describe("playlists", func() {
 		var repo model.PlaylistRepository
-		BeforeEach(func() { repo = NewPlaylistRepository(ctx, GetDBXBuilder()) })
+		BeforeEach(func() { repo = NewPlaylistRepository(GetDBXBuilder()) })
 
 		It("hydrates the found / known-absent states", func() {
 			putInfo("pl", plsBest.ID, "plhash777777777")
 			putInfo("pl", plsCool.ID, "")
 
-			all, err := repo.GetAll()
+			all, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			byID := slice.ToMap(all, func(p model.Playlist) (string, model.Playlist) { return p.ID, p })
 
@@ -163,16 +163,16 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates Get", func() {
 			putInfo("pl", plsBest.ID, "plget8888888888")
-			got, err := repo.Get(plsBest.ID)
+			got, err := repo.Get(ctx, plsBest.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.ImageHash).To(Equal("plget8888888888"))
 		})
 
 		It("hydrates the tracks reached through a playlist", func() {
-			Expect(aw.PutImage(&model.Artwork{Hash: "pltrackhash1234", Mime: "image/jpeg", BlurHash: "LPLBLURhash"})).To(Succeed())
+			Expect(aw.PutImage(ctx, &model.Artwork{Hash: "pltrackhash1234", Mime: "image/jpeg", BlurHash: "LPLBLURhash"})).To(Succeed())
 			putInfo("al", songDayInALife.AlbumID, "pltrackhash1234")
 
-			pls, err := repo.GetWithTracks(plsBest.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, plsBest.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 			tracks := pls.Tracks
 			Expect(tracks).ToNot(BeEmpty())
@@ -181,7 +181,7 @@ var _ = Describe("Artwork hydration", func() {
 			Expect(byID[songDayInALife.ID].AlbumImage.ImageHash).To(Equal("pltrackhash1234"))
 			Expect(byID[songDayInALife.ID].BlurHash).To(Equal("LPLBLURhash"))
 
-			cursor, err := repo.Tracks(plsBest.ID, true).GetCursor()
+			cursor, err := repo.Tracks(ctx, plsBest.ID, true).GetCursor(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			var streamed *model.PlaylistTrack
 			for t, err := range cursor {
@@ -198,13 +198,13 @@ var _ = Describe("Artwork hydration", func() {
 
 	Describe("radios", func() {
 		var repo model.RadioRepository
-		BeforeEach(func() { repo = NewRadioRepository(ctx, GetDBXBuilder()) })
+		BeforeEach(func() { repo = NewRadioRepository(GetDBXBuilder()) })
 
 		It("hydrates the found / known-absent states", func() {
 			putInfo("ra", radioWithHomePage.ID, "rahash999999999")
 			putInfo("ra", radioWithoutHomePage.ID, "")
 
-			all, err := repo.GetAll()
+			all, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			byID := slice.ToMap(all, func(rd model.Radio) (string, model.Radio) { return rd.ID, rd })
 
@@ -216,7 +216,7 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates Get", func() {
 			putInfo("ra", radioWithHomePage.ID, "ragetaaaaaaaaaa")
-			got, err := repo.Get(radioWithHomePage.ID)
+			got, err := repo.Get(ctx, radioWithHomePage.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.ImageHash).To(Equal("ragetaaaaaaaaaa"))
 		})
@@ -232,13 +232,13 @@ var _ = Describe("Artwork hydration", func() {
 		}
 
 		getByID := func() map[string]model.MediaFile {
-			all, err := repo.GetAll()
+			all, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			return slice.ToMap(all, func(mf model.MediaFile) (string, model.MediaFile) { return mf.ID, mf })
 		}
 
 		BeforeEach(func() {
-			repo = NewMediaFileRepository(ctx, GetDBXBuilder())
+			repo = NewMediaFileRepository(GetDBXBuilder())
 			DeferCleanup(configtest.SetupConfig())
 			conf.Server.EnableMediaFileCoverArt = true
 		})
@@ -293,8 +293,8 @@ var _ = Describe("Artwork hydration", func() {
 			setCover("1001", true) // eligible, resolves its own art -> own-art-wins branch
 			DeferCleanup(func() { setCover("1001", false) })
 
-			Expect(aw.PutImage(&model.Artwork{Hash: "mfh1001blurxxxxx", Mime: "image/jpeg", BlurHash: "LTRACKblur", ThumbHash: "THtrack", Width: 640, Height: 480})).To(Succeed())
-			Expect(aw.PutImage(&model.Artwork{Hash: "alh102blurxxxxxx", Mime: "image/jpeg", BlurHash: "LALBUMblur", ThumbHash: "THalbum", Width: 1200, Height: 800})).To(Succeed())
+			Expect(aw.PutImage(ctx, &model.Artwork{Hash: "mfh1001blurxxxxx", Mime: "image/jpeg", BlurHash: "LTRACKblur", ThumbHash: "THtrack", Width: 640, Height: 480})).To(Succeed())
+			Expect(aw.PutImage(ctx, &model.Artwork{Hash: "alh102blurxxxxxx", Mime: "image/jpeg", BlurHash: "LALBUMblur", ThumbHash: "THalbum", Width: 1200, Height: 800})).To(Succeed())
 			putInfo("mf", "1001", "mfh1001blurxxxxx")
 			putInfo("al", "102", "alh102blurxxxxxx") // 1002's album: single-disc inheritance branch
 
@@ -374,7 +374,7 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates Search", func() {
 			putInfo("al", "101", "alsrchhhhhhhhhhh")
-			res, err := repo.Search("A Day In A Life", model.QueryOptions{})
+			res, err := repo.Search(ctx, "A Day In A Life", model.QueryOptions{})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res).ToNot(BeEmpty())
 			Expect(res[0].ImageHash).To(Equal("alsrchhhhhhhhhhh"))
@@ -397,9 +397,9 @@ var _ = Describe("Artwork hydration", func() {
 		}
 
 		BeforeEach(func() {
-			albumRepo = NewAlbumRepository(ctx, GetDBXBuilder())
-			artistRepo = NewArtistRepository(ctx, GetDBXBuilder())
-			playlistRepo = NewPlaylistRepository(ctx, GetDBXBuilder())
+			albumRepo = NewAlbumRepository(GetDBXBuilder())
+			artistRepo = NewArtistRepository(GetDBXBuilder())
+			playlistRepo = NewPlaylistRepository(GetDBXBuilder())
 			// Other specs leave rows behind, so scope every cursor spec to the fixtures.
 			onlyAlbums = squirrel.Eq{"album.id": []string{albumSgtPeppers.ID, albumAbbeyRoad.ID,
 				albumRadioactivity.ID, albumMultiDisc.ID, albumCJK.ID, albumPunctuation.ID}}
@@ -408,8 +408,8 @@ var _ = Describe("Artwork hydration", func() {
 			// Both fixture playlists share an owner, leaving the owner_name sort a single value to
 			// order by; this one is also private, which the non-admin visibility spec needs.
 			foreign := model.Playlist{Name: "Foreign", OwnerID: thirdUser.ID, OwnerName: thirdUser.UserName}
-			Expect(playlistRepo.Put(&foreign)).To(Succeed())
-			DeferCleanup(func() { Expect(playlistRepo.Delete(foreign.ID)).To(Succeed()) })
+			Expect(playlistRepo.Put(ctx, &foreign)).To(Succeed())
+			DeferCleanup(func() { Expect(playlistRepo.Delete(ctx, foreign.ID)).To(Succeed()) })
 			onlyPlaylists = squirrel.Eq{"playlist.id": []string{plsBest.ID, plsCool.ID, foreign.ID}}
 
 			// The suite annotates a single album and artist, leaving the annotation-backed sorts
@@ -417,7 +417,7 @@ var _ = Describe("Artwork hydration", func() {
 			seedAnnotations("album", albumSgtPeppers.ID, albumAbbeyRoad.ID)
 			seedAnnotations("artist", artistKraftwerk.ID, artistCJK.ID)
 
-			Expect(aw.PutImage(&model.Artwork{
+			Expect(aw.PutImage(ctx, &model.Artwork{
 				Hash: "curhash11111111", Mime: "image/jpeg", BlurHash: "LEHV6nWB2yk8",
 			})).To(Succeed())
 			putInfo("al", albumSgtPeppers.ID, "curhash11111111")
@@ -428,10 +428,10 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates every streamed album, like GetAll", func() {
 			opts := model.QueryOptions{Sort: "name", Filters: onlyAlbums}
-			want, err := albumRepo.GetAll(opts)
+			want, err := albumRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 
-			got := collectCursor(albumRepo.GetCursor(opts))
+			got := collectCursor(albumRepo.GetCursor(ctx, opts))
 
 			Expect(got).To(ConsistOf(want))
 			byID := map[string]model.Album{}
@@ -447,10 +447,10 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates every streamed artist, like GetAll", func() {
 			opts := model.QueryOptions{Sort: "name", Filters: onlyArtists}
-			want, err := artistRepo.GetAll(opts)
+			want, err := artistRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 
-			got := collectCursor(artistRepo.GetCursor(opts))
+			got := collectCursor(artistRepo.GetCursor(ctx, opts))
 
 			Expect(got).To(ConsistOf(want))
 			Expect(slice.Map(got, func(a model.Artist) string { return a.ImageHash })).
@@ -459,10 +459,10 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates every streamed playlist, like GetAll", func() {
 			opts := model.QueryOptions{Sort: "name", Filters: onlyPlaylists}
-			want, err := playlistRepo.GetAll(opts)
+			want, err := playlistRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 
-			got := collectCursor(playlistRepo.GetCursor(opts))
+			got := collectCursor(playlistRepo.GetCursor(ctx, opts))
 
 			Expect(got).To(ConsistOf(want))
 			Expect(slice.Map(got, func(p model.Playlist) string { return p.ImageHash })).
@@ -471,11 +471,11 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("honors Max and Offset exactly once", func() {
 			opts := model.QueryOptions{Sort: "name", Filters: onlyAlbums, Max: 2, Offset: 1}
-			want, err := albumRepo.GetAll(opts)
+			want, err := albumRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).To(HaveLen(2))
 
-			got := collectCursor(albumRepo.GetCursor(opts))
+			got := collectCursor(albumRepo.GetCursor(ctx, opts))
 
 			Expect(slice.Map(got, func(a model.Album) string { return a.ID })).
 				To(Equal(slice.Map(want, func(a model.Album) string { return a.ID })))
@@ -485,11 +485,11 @@ var _ = Describe("Artwork hydration", func() {
 		DescribeTable("orders albums like GetAll",
 			func(opts model.QueryOptions, key func(model.Album) string) {
 				opts = scoped(opts, onlyAlbums)
-				want, err := albumRepo.GetAll(opts)
+				want, err := albumRepo.GetAll(ctx, opts)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(want).ToNot(BeEmpty())
 
-				got := collectCursor(albumRepo.GetCursor(opts))
+				got := collectCursor(albumRepo.GetCursor(ctx, opts))
 
 				Expect(slice.Map(got, key)).To(Equal(slice.Map(want, key)))
 				Expect(slice.Map(got, func(a model.Album) string { return a.ID })).
@@ -517,11 +517,11 @@ var _ = Describe("Artwork hydration", func() {
 		DescribeTable("orders artists like GetAll",
 			func(opts model.QueryOptions, key func(model.Artist) string) {
 				opts = scoped(opts, onlyArtists)
-				want, err := artistRepo.GetAll(opts)
+				want, err := artistRepo.GetAll(ctx, opts)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(want).ToNot(BeEmpty())
 
-				got := collectCursor(artistRepo.GetCursor(opts))
+				got := collectCursor(artistRepo.GetCursor(ctx, opts))
 
 				Expect(slice.Map(got, key)).To(Equal(slice.Map(want, key)))
 				Expect(slice.Map(got, func(a model.Artist) string { return a.ID })).
@@ -543,11 +543,11 @@ var _ = Describe("Artwork hydration", func() {
 		DescribeTable("orders playlists like GetAll",
 			func(opts model.QueryOptions, key func(model.Playlist) string) {
 				opts = scoped(opts, onlyPlaylists)
-				want, err := playlistRepo.GetAll(opts)
+				want, err := playlistRepo.GetAll(ctx, opts)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(want).ToNot(BeEmpty())
 
-				got := collectCursor(playlistRepo.GetCursor(opts))
+				got := collectCursor(playlistRepo.GetCursor(ctx, opts))
 
 				Expect(slice.Map(got, key)).To(Equal(slice.Map(want, key)))
 				Expect(slice.Map(got, func(p model.Playlist) string { return p.ID })).
@@ -563,10 +563,10 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("streams every album exactly once when sorted randomly", func() {
 			opts := model.QueryOptions{Sort: "random", Filters: onlyAlbums}
-			want, err := albumRepo.GetAll(opts)
+			want, err := albumRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 
-			got := collectCursor(albumRepo.GetCursor(opts))
+			got := collectCursor(albumRepo.GetCursor(ctx, opts))
 
 			Expect(slice.Map(got, func(a model.Album) string { return a.ID })).
 				To(ConsistOf(slice.Map(want, func(a model.Album) string { return a.ID })))
@@ -574,16 +574,16 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("keeps a non-admin from streaming another user's private playlists", func() {
 			otherCtx := request.WithUser(log.NewContext(context.Background()), regularUser)
-			repo := NewPlaylistRepository(otherCtx, GetDBXBuilder())
+			repo := NewPlaylistRepository(GetDBXBuilder())
 			opts := model.QueryOptions{Sort: "name", Filters: onlyPlaylists}
 
 			// Both phases must filter on their own: the id pre-pass and the chunk fetch.
-			Expect(repo.(*playlistRepository).getAllIDs(opts)).To(ConsistOf(plsBest.ID))
-			all, err := repo.GetAll(model.QueryOptions{Filters: onlyPlaylists})
+			Expect(repo.(*playlistRepository).getAllIDs(otherCtx, opts)).To(ConsistOf(plsBest.ID))
+			all, err := repo.GetAll(otherCtx, model.QueryOptions{Filters: onlyPlaylists})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(slice.Map(all, func(p model.Playlist) string { return p.ID })).To(ConsistOf(plsBest.ID))
 
-			got := collectCursor(repo.GetCursor(opts))
+			got := collectCursor(repo.GetCursor(otherCtx, opts))
 
 			Expect(slice.Map(got, func(p model.Playlist) string { return p.Name })).
 				To(ConsistOf(plsBest.Name))
@@ -595,7 +595,7 @@ var _ = Describe("Artwork hydration", func() {
 		var onlySongs squirrel.Eq
 
 		BeforeEach(func() {
-			mfRepo = NewMediaFileRepository(ctx, GetDBXBuilder())
+			mfRepo = NewMediaFileRepository(GetDBXBuilder())
 			putInfo("al", albumSgtPeppers.ID, "curhash11111111")
 			// Distinct titles only: other fixture songs share titles (e.g. "Antenna" x3), which
 			// would make the positional comparisons against GetAll pass by tie-order coincidence.
@@ -605,11 +605,11 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("hydrates artwork onto every streamed track, unlike GetCursor", func() {
 			opts := model.QueryOptions{Sort: "title", Filters: onlySongs}
-			want, err := mfRepo.GetAll(opts)
+			want, err := mfRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).ToNot(BeEmpty())
 
-			cursor, err := mfRepo.GetCursorWithArtwork(opts)
+			cursor, err := mfRepo.GetCursorWithArtwork(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 			var got model.MediaFiles
 			cursor(func(mf model.MediaFile, err error) bool {
@@ -631,7 +631,7 @@ var _ = Describe("Artwork hydration", func() {
 		})
 
 		It("leaves the scanner's GetCursor unhydrated", func() {
-			cursor, err := mfRepo.GetCursor(model.QueryOptions{Sort: "title"})
+			cursor, err := mfRepo.GetCursor(ctx, model.QueryOptions{Sort: "title"})
 			Expect(err).ToNot(HaveOccurred())
 			var seen int
 			cursor(func(mf model.MediaFile, err error) bool {
@@ -645,11 +645,11 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("streams the same ids in the same order as GetAll", func() {
 			opts := model.QueryOptions{Sort: "title", Filters: onlySongs}
-			want, err := mfRepo.GetAll(opts)
+			want, err := mfRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).ToNot(BeEmpty())
 
-			got := collectCursor(mfRepo.GetCursorWithArtwork(opts))
+			got := collectCursor(mfRepo.GetCursorWithArtwork(ctx, opts))
 
 			Expect(slice.Map(got, func(mf model.MediaFile) string { return mf.ID })).
 				To(Equal(slice.Map(want, func(mf model.MediaFile) string { return mf.ID })))
@@ -657,11 +657,11 @@ var _ = Describe("Artwork hydration", func() {
 
 		It("honors Max and Offset exactly once", func() {
 			opts := model.QueryOptions{Sort: "title", Filters: onlySongs, Max: 2, Offset: 1}
-			want, err := mfRepo.GetAll(opts)
+			want, err := mfRepo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).To(HaveLen(2))
 
-			got := collectCursor(mfRepo.GetCursorWithArtwork(opts))
+			got := collectCursor(mfRepo.GetCursorWithArtwork(ctx, opts))
 
 			Expect(slice.Map(got, func(mf model.MediaFile) string { return mf.ID })).
 				To(Equal(slice.Map(want, func(mf model.MediaFile) string { return mf.ID })))
diff --git a/persistence/artwork_queue_repository.go b/persistence/artwork_queue_repository.go
index 88b6f6f80..321fe8a95 100644
--- a/persistence/artwork_queue_repository.go
+++ b/persistence/artwork_queue_repository.go
@@ -25,17 +25,16 @@ type artworkQueueRepository struct {
 	sqlRepository
 }
 
-func NewArtworkQueueRepository(ctx context.Context, db dbx.Builder) model.ArtworkQueueRepository {
+func NewArtworkQueueRepository(db dbx.Builder) model.ArtworkQueueRepository {
 	r := &artworkQueueRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "artwork_queue"
 	return r
 }
 
-func (r *artworkQueueRepository) Get(kind model.Kind, id, imageType string) (*model.ArtworkQueueItem, error) {
+func (r *artworkQueueRepository) Get(ctx context.Context, kind model.Kind, id, imageType string) (*model.ArtworkQueueItem, error) {
 	var res model.ArtworkQueueItem
-	err := r.queryOne(Select("*").From(r.tableName).
+	err := r.queryOne(ctx, Select("*").From(r.tableName).
 		Where(Eq{"item_kind": kind.Prefix(), "item_id": id, "image_type": imageType}), &res)
 	if err != nil {
 		return nil, err
@@ -45,30 +44,30 @@ func (r *artworkQueueRepository) Get(kind model.Kind, id, imageType string) (*mo
 
 // Enqueue starts a fresh lifecycle: it resets enqueued_at (so a fresh request does not inherit an old
 // row's spent retry budget) and clears trace (so explain does not show a prior failure at attempts 0).
-func (r *artworkQueueRepository) Enqueue(items ...model.ArtworkQueueItem) error {
-	return r.enqueue(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
+func (r *artworkQueueRepository) Enqueue(ctx context.Context, items ...model.ArtworkQueueItem) error {
+	return r.enqueue(ctx, `ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
 		priority = MAX(priority, excluded.priority), retry_at = excluded.retry_at,
 		attempts = 0, enqueued_at = excluded.enqueued_at, trace = '[]'`, items)
 }
 
-func (r *artworkQueueRepository) EnqueuePreservingBackoff(items ...model.ArtworkQueueItem) error {
-	return r.enqueue(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
+func (r *artworkQueueRepository) EnqueuePreservingBackoff(ctx context.Context, items ...model.ArtworkQueueItem) error {
+	return r.enqueue(ctx, `ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET
 		priority = MAX(priority, excluded.priority)`, items)
 }
 
-func (r *artworkQueueRepository) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {
+func (r *artworkQueueRepository) EnqueueAllMissing(ctx context.Context, kind model.Kind, priority int) (int64, error) {
 	entityTable, ok := artworkOwnerTables[kind]
 	if !ok {
 		return 0, fmt.Errorf("artwork queue: no entity table for kind %q", kind.Prefix())
 	}
 	now := time.Now()
-	return r.insertIfNotQueued("", `SELECT ?, id, ?, ?, 0, ?, ?
+	return r.insertIfNotQueued(ctx, "", `SELECT ?, id, ?, ?, 0, ?, ?
 		FROM `+entityTable+`
 		WHERE id NOT IN (SELECT item_id FROM `+itemArtworkTable+` WHERE item_kind = ?)`,
 		kind.Prefix(), model.ImageTypePrimary, priority, now, now, kind.Prefix())
 }
 
-func (r *artworkQueueRepository) EnqueueIfMissing(items ...model.ArtworkQueueItem) error {
+func (r *artworkQueueRepository) EnqueueIfMissing(ctx context.Context, items ...model.ArtworkQueueItem) error {
 	now := time.Now()
 	for chunk := range slices.Chunk(items, enqueueChunkSize) {
 		rows := make([]string, 0, len(chunk))
@@ -78,7 +77,7 @@ func (r *artworkQueueRepository) EnqueueIfMissing(items ...model.ArtworkQueueIte
 			args = append(args, it.ItemKind, it.ItemID, cmp.Or(it.ImageType, model.ImageTypePrimary), it.Priority)
 		}
 		args = append(args, now, now)
-		_, err := r.insertIfNotQueued(
+		_, err := r.insertIfNotQueued(ctx,
 			`WITH new_items(item_kind, item_id, image_type, priority) AS (VALUES `+strings.Join(rows, ",")+`) `,
 			`SELECT n.item_kind, n.item_id, n.image_type, n.priority, 0, ?, ?
 			FROM new_items n
@@ -97,8 +96,8 @@ func (r *artworkQueueRepository) EnqueueIfMissing(items ...model.ArtworkQueueIte
 const skipIfQueued = ` ON CONFLICT (item_kind, item_id, image_type) DO NOTHING`
 
 // insertIfNotQueued inserts the rows selected by the given SQL, optionally prefixed by a CTE.
-func (r *artworkQueueRepository) insertIfNotQueued(with, sql string, args ...any) (int64, error) {
-	return r.executeSQL(Expr(with+`INSERT INTO `+r.tableName+
+func (r *artworkQueueRepository) insertIfNotQueued(ctx context.Context, with, sql string, args ...any) (int64, error) {
+	return r.executeSQL(ctx, Expr(with+`INSERT INTO `+r.tableName+
 		` (`+strings.Join(enqueueColumns, ", ")+`) `+sql+skipIfQueued, args...))
 }
 
@@ -121,16 +120,16 @@ func artworkSourceFilter(kind model.Kind, sources []string) Sqlizer {
 	return append(f, match)
 }
 
-func (r *artworkQueueRepository) CountBySource(kind model.Kind, sources []string) (int64, error) {
+func (r *artworkQueueRepository) CountBySource(ctx context.Context, kind model.Kind, sources []string) (int64, error) {
 	var res struct{ Count int64 }
-	err := r.queryOne(Select("count(*) as count").From(itemArtworkTable).
+	err := r.queryOne(ctx, Select("count(*) as count").From(itemArtworkTable).
 		Where(artworkSourceFilter(kind, sources)), &res)
 	return res.Count, err
 }
 
-func (r *artworkQueueRepository) SourcesInUse(kind model.Kind) ([]string, error) {
+func (r *artworkQueueRepository) SourcesInUse(ctx context.Context, kind model.Kind) ([]string, error) {
 	var res []struct{ Source string }
-	err := r.queryAll(Select("distinct source").From(itemArtworkTable).
+	err := r.queryAll(ctx, Select("distinct source").From(itemArtworkTable).
 		Where(Eq{"item_kind": kind.Prefix()}), &res)
 	if err != nil {
 		return nil, err
@@ -140,15 +139,15 @@ func (r *artworkQueueRepository) SourcesInUse(kind model.Kind) ([]string, error)
 
 // EnqueueBySource deliberately leaves item_artwork alone: clearing state in bulk would blank the
 // library's artwork until every item is resolved again.
-func (r *artworkQueueRepository) EnqueueBySource(kind model.Kind, sources []string, priority int) (int64, error) {
+func (r *artworkQueueRepository) EnqueueBySource(ctx context.Context, kind model.Kind, sources []string, priority int) (int64, error) {
 	now := time.Now()
 	sel := Select("item_kind", "item_id", "image_type").
 		Column(Expr("?", priority)).Column("0").Column(Expr("?", now)).Column(Expr("?", now)).
 		From(itemArtworkTable).Where(artworkSourceFilter(kind, sources))
-	return r.executeSQL(Insert(r.tableName).Columns(enqueueColumns...).Select(sel).Suffix(skipIfQueued))
+	return r.executeSQL(ctx, Insert(r.tableName).Columns(enqueueColumns...).Select(sel).Suffix(skipIfQueued))
 }
 
-func (r *artworkQueueRepository) enqueue(conflict string, items []model.ArtworkQueueItem) error {
+func (r *artworkQueueRepository) enqueue(ctx context.Context, conflict string, items []model.ArtworkQueueItem) error {
 	now := time.Now()
 	for chunk := range slices.Chunk(items, enqueueChunkSize) {
 		ins := Insert(r.tableName).Columns(enqueueColumns...)
@@ -156,14 +155,14 @@ func (r *artworkQueueRepository) enqueue(conflict string, items []model.ArtworkQ
 			ins = ins.Values(it.ItemKind, it.ItemID, cmp.Or(it.ImageType, model.ImageTypePrimary), it.Priority, 0, now, now)
 		}
 		ins = ins.Suffix(conflict)
-		if _, err := r.executeSQL(ins); err != nil {
+		if _, err := r.executeSQL(ctx, ins); err != nil {
 			return err
 		}
 	}
 	return nil
 }
 
-func (r *artworkQueueRepository) DequeueBatch(n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
+func (r *artworkQueueRepository) DequeueBatch(ctx context.Context, n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
 	sel := Select(enqueueColumns...).From(r.tableName).
 		Where(LtOrEq{"retry_at": time.Now()}).
 		OrderBy("priority DESC", "enqueued_at ASC").
@@ -172,26 +171,26 @@ func (r *artworkQueueRepository) DequeueBatch(n int, kinds ...string) ([]model.A
 		sel = sel.Where(Eq{"item_kind": kinds})
 	}
 	var res []model.ArtworkQueueItem
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	return res, err
 }
 
-func (r *artworkQueueRepository) MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error {
+func (r *artworkQueueRepository) MarkFailedIfUnchanged(ctx context.Context, kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error {
 	upd := Update(r.tableName).
 		Set("attempts", Expr("attempts + 1")).
 		Set("retry_at", retryAt).
 		Set("trace", trace).
 		Where(Eq{"item_kind": kind, "item_id": id, "image_type": imageType, "retry_at": seenRetryAt})
-	_, err := r.executeSQL(upd)
+	_, err := r.executeSQL(ctx, upd)
 	return err
 }
 
-func (r *artworkQueueRepository) DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error {
-	return r.delete(Eq{"item_kind": kind, "item_id": id, "image_type": imageType, "retry_at": retryAt})
+func (r *artworkQueueRepository) DeleteIfUnchanged(ctx context.Context, kind, id, imageType string, retryAt time.Time) error {
+	return r.delete(ctx, Eq{"item_kind": kind, "item_id": id, "image_type": imageType, "retry_at": retryAt})
 }
 
-func (r *artworkQueueRepository) PurgeDangling() (int64, error) {
-	return purgeDangling(r.sqlRepository)
+func (r *artworkQueueRepository) PurgeDangling(ctx context.Context) (int64, error) {
+	return purgeDangling(ctx, r.sqlRepository)
 }
 
 // artworkQueueFilter returns no conditions for an empty filter, so an unfiltered DELETE keeps
@@ -208,28 +207,28 @@ func artworkQueueFilter(kinds []model.Kind, priorities []int) And {
 }
 
 // CountQueued shares its filter with PurgeQueued, so a preview cannot count rows the delete misses.
-func (r *artworkQueueRepository) CountQueued(kinds []model.Kind, priorities []int) ([]model.ArtworkQueueStat, error) {
+func (r *artworkQueueRepository) CountQueued(ctx context.Context, kinds []model.Kind, priorities []int) ([]model.ArtworkQueueStat, error) {
 	sel := Select("item_kind", "priority", "count(*) as count").From(r.tableName).
 		GroupBy("item_kind", "priority").OrderBy("item_kind", "priority desc")
 	if f := artworkQueueFilter(kinds, priorities); len(f) > 0 {
 		sel = sel.Where(f)
 	}
 	var res []model.ArtworkQueueStat
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	return res, err
 }
 
-func (r *artworkQueueRepository) PurgeQueued(kinds []model.Kind, priorities []int) (int64, error) {
+func (r *artworkQueueRepository) PurgeQueued(ctx context.Context, kinds []model.Kind, priorities []int) (int64, error) {
 	del := Delete(r.tableName)
 	if f := artworkQueueFilter(kinds, priorities); len(f) > 0 {
 		del = del.Where(f)
 	}
-	return r.executeSQL(del)
+	return r.executeSQL(ctx, del)
 }
 
-func (r *artworkQueueRepository) Count() (int64, error) {
+func (r *artworkQueueRepository) Count(ctx context.Context) (int64, error) {
 	var res struct{ Count int64 }
-	err := r.queryOne(Select("count(*) as count").From(r.tableName), &res)
+	err := r.queryOne(ctx, Select("count(*) as count").From(r.tableName), &res)
 	return res.Count, err
 }
 
diff --git a/persistence/artwork_queue_repository_test.go b/persistence/artwork_queue_repository_test.go
index 0481d4193..6ce4be8e2 100644
--- a/persistence/artwork_queue_repository_test.go
+++ b/persistence/artwork_queue_repository_test.go
@@ -14,6 +14,7 @@ import (
 
 var _ = Describe("ArtworkQueueRepository", func() {
 	var repo model.ArtworkQueueRepository
+	var ctx context.Context
 
 	item := func(kind, id string, prio int) model.ArtworkQueueItem {
 		return model.ArtworkQueueItem{ItemKind: kind, ItemID: id,
@@ -25,7 +26,7 @@ var _ = Describe("ArtworkQueueRepository", func() {
 	backOff := func(kind, id string, retryAt time.Time) {
 		GinkgoHelper()
 		r := repo.(*artworkQueueRepository)
-		_, err := r.executeSQL(squirrel.Update(r.tableName).
+		_, err := r.executeSQL(ctx, squirrel.Update(r.tableName).
 			Set("attempts", squirrel.Expr("attempts + 1")).
 			Set("retry_at", retryAt).
 			Where(squirrel.Eq{"item_kind": kind, "item_id": id, "image_type": model.ImageTypePrimary}))
@@ -35,30 +36,31 @@ var _ = Describe("ArtworkQueueRepository", func() {
 	remove := func(kind, id string) {
 		GinkgoHelper()
 		r := repo.(*artworkQueueRepository)
-		Expect(r.delete(squirrel.Eq{"item_kind": kind, "item_id": id, "image_type": model.ImageTypePrimary})).To(Succeed())
+		Expect(r.delete(ctx, squirrel.Eq{"item_kind": kind, "item_id": id, "image_type": model.ImageTypePrimary})).To(Succeed())
 	}
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		clearArtworkTables()
 		DeferCleanup(clearArtworkTables)
-		repo = NewArtworkQueueRepository(context.Background(), GetDBXBuilder())
+		repo = NewArtworkQueueRepository(GetDBXBuilder())
 	})
 
 	It("enqueues and dequeues by priority then FIFO", func() {
-		Expect(repo.Enqueue(item("al", "low", model.ArtworkPriorityBackfill))).To(Succeed())
-		Expect(repo.Enqueue(item("ar", "high", model.ArtworkPriorityBump))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "low", model.ArtworkPriorityBackfill))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("ar", "high", model.ArtworkPriorityBump))).To(Succeed())
 
-		got, err := repo.DequeueBatch(10)
+		got, err := repo.DequeueBatch(ctx, 10)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(got).To(HaveLen(2))
 		Expect(got[0].ItemID).To(Equal("high"))
 	})
 
 	It("Get returns a queued row, including one still backing off", func() {
-		Expect(repo.Enqueue(item("ar", "g1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("ar", "g1", model.ArtworkPriorityScan))).To(Succeed())
 		backOff("ar", "g1", time.Now().Add(time.Hour))
 
-		got, err := repo.Get(model.KindArtistArtwork, "g1", model.ImageTypePrimary)
+		got, err := repo.Get(ctx, model.KindArtistArtwork, "g1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(got.Priority).To(Equal(model.ArtworkPriorityScan))
 		Expect(got.Attempts).To(Equal(1))
@@ -66,114 +68,114 @@ var _ = Describe("ArtworkQueueRepository", func() {
 	})
 
 	It("Get reports ErrNotFound when the item is not queued", func() {
-		_, err := repo.Get(model.KindArtistArtwork, "nope", model.ImageTypePrimary)
+		_, err := repo.Get(ctx, model.KindArtistArtwork, "nope", model.ImageTypePrimary)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
 	It("keeps the higher priority on duplicate enqueue", func() {
-		Expect(repo.Enqueue(item("al", "a1", model.ArtworkPriorityBump))).To(Succeed())
-		Expect(repo.Enqueue(item("al", "a1", model.ArtworkPriorityBackfill))).To(Succeed())
-		got, _ := repo.DequeueBatch(10)
+		Expect(repo.Enqueue(ctx, item("al", "a1", model.ArtworkPriorityBump))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "a1", model.ArtworkPriorityBackfill))).To(Succeed())
+		got, _ := repo.DequeueBatch(ctx, 10)
 		Expect(got).To(HaveLen(1))
 		Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump))
 	})
 
 	It("EnqueuePreservingBackoff raises priority without resetting a backing-off row's retry_at", func() {
-		Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
 		backOff("al", "b1", time.Now().Add(time.Hour))
-		Expect(repo.DequeueBatch(10)).To(BeEmpty())
+		Expect(repo.DequeueBatch(ctx, 10)).To(BeEmpty())
 
-		Expect(repo.EnqueuePreservingBackoff(item("al", "b1", model.ArtworkPriorityBump))).To(Succeed())
-		Expect(repo.DequeueBatch(10)).To(BeEmpty(), "bump must not reset retry_at")
+		Expect(repo.EnqueuePreservingBackoff(ctx, item("al", "b1", model.ArtworkPriorityBump))).To(Succeed())
+		Expect(repo.DequeueBatch(ctx, 10)).To(BeEmpty(), "bump must not reset retry_at")
 
 		// Enqueue (scan/manual), by contrast, resets retry_at and makes it eligible now.
-		Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
-		got, _ := repo.DequeueBatch(10)
+		Expect(repo.Enqueue(ctx, item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
+		got, _ := repo.DequeueBatch(ctx, 10)
 		Expect(got).To(HaveLen(1))
 		Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump), "bump's higher priority is preserved")
 	})
 
 	It("EnqueuePreservingBackoff inserts a brand-new row eligible immediately", func() {
-		Expect(repo.EnqueuePreservingBackoff(item("ar", "n1", model.ArtworkPriorityBump))).To(Succeed())
-		got, _ := repo.DequeueBatch(10)
+		Expect(repo.EnqueuePreservingBackoff(ctx, item("ar", "n1", model.ArtworkPriorityBump))).To(Succeed())
+		got, _ := repo.DequeueBatch(ctx, 10)
 		Expect(got).To(HaveLen(1))
 		Expect(got[0].ItemID).To(Equal("n1"))
 	})
 
 	It("hides failed items until retry_at", func() {
-		Expect(repo.Enqueue(item("al", "f1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "f1", model.ArtworkPriorityScan))).To(Succeed())
 		backOff("al", "f1", time.Now().Add(time.Hour))
 
-		got, err := repo.DequeueBatch(10)
+		got, err := repo.DequeueBatch(ctx, 10)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(got).To(BeEmpty())
 
 		backOff("al", "f1", time.Now().Add(-time.Minute))
-		got, _ = repo.DequeueBatch(10)
+		got, _ = repo.DequeueBatch(ctx, 10)
 		Expect(got).To(HaveLen(1))
 		Expect(got[0].Attempts).To(Equal(2))
 	})
 
 	It("MarkFailedIfUnchanged applies backoff only while retry_at is unchanged", func() {
-		Expect(repo.Enqueue(item("al", "m1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "m1", model.ArtworkPriorityScan))).To(Succeed())
 		// Anchor retry_at in the past so it can never collide with the re-enqueue's now.
 		backOff("al", "m1", time.Now().Add(-time.Hour))
-		got, err := repo.DequeueBatch(10)
+		got, err := repo.DequeueBatch(ctx, 10)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(got).To(HaveLen(1))
 		original := got[0].RetryAt
 
 		// A concurrent scan re-enqueues, resetting retry_at to now.
-		Expect(repo.Enqueue(item("al", "m1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "m1", model.ArtworkPriorityScan))).To(Succeed())
 
 		future := time.Now().Add(48 * time.Hour)
-		Expect(repo.MarkFailedIfUnchanged("al", "m1", model.ImageTypePrimary, original, future, "[]")).To(Succeed())
-		got, _ = repo.DequeueBatch(10)
+		Expect(repo.MarkFailedIfUnchanged(ctx, "al", "m1", model.ImageTypePrimary, original, future, "[]")).To(Succeed())
+		got, _ = repo.DequeueBatch(ctx, 10)
 		Expect(got).To(HaveLen(1), "the fresh re-enqueue stays immediately eligible")
 		Expect(got[0].Attempts).To(BeZero(), "re-enqueue clears attempts, and the stale failure must not bump them")
 		current := got[0].RetryAt
 
-		Expect(repo.MarkFailedIfUnchanged("al", "m1", model.ImageTypePrimary, current, future, `[{"c":"read","o":"error"}]`)).To(Succeed())
-		got, _ = repo.DequeueBatch(10)
+		Expect(repo.MarkFailedIfUnchanged(ctx, "al", "m1", model.ImageTypePrimary, current, future, `[{"c":"read","o":"error"}]`)).To(Succeed())
+		got, _ = repo.DequeueBatch(ctx, 10)
 		Expect(got).To(BeEmpty(), "backed-off row is hidden until the future retry_at")
-		all, _ := repo.Count()
+		all, _ := repo.Count(ctx)
 		Expect(all).To(Equal(int64(1)))
 	})
 
 	It("Enqueue clears a prior lifecycle's failure trace; EnqueuePreservingBackoff keeps it", func() {
 		// Fail an attempt so the queue row carries a failure trace.
-		Expect(repo.Enqueue(item("al", "t1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "t1", model.ArtworkPriorityScan))).To(Succeed())
 		backOff("al", "t1", time.Now().Add(-time.Hour))
-		got, _ := repo.DequeueBatch(10)
+		got, _ := repo.DequeueBatch(ctx, 10)
 		Expect(got).To(HaveLen(1))
 		future := time.Now().Add(48 * time.Hour)
-		Expect(repo.MarkFailedIfUnchanged("al", "t1", model.ImageTypePrimary, got[0].RetryAt, future, `[{"c":"read","o":"error"}]`)).To(Succeed())
+		Expect(repo.MarkFailedIfUnchanged(ctx, "al", "t1", model.ImageTypePrimary, got[0].RetryAt, future, `[{"c":"read","o":"error"}]`)).To(Succeed())
 
 		// A continuation of the same lifecycle must retain the trace.
-		Expect(repo.EnqueuePreservingBackoff(item("al", "t1", model.ArtworkPriorityBump))).To(Succeed())
-		kept, err := repo.Get(model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
+		Expect(repo.EnqueuePreservingBackoff(ctx, item("al", "t1", model.ArtworkPriorityBump))).To(Succeed())
+		kept, err := repo.Get(ctx, model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(kept.Trace).To(Equal(`[{"c":"read","o":"error"}]`))
 
 		// A fresh Enqueue resets attempts to 0, so the stale failure trace must be cleared with it.
-		Expect(repo.Enqueue(item("al", "t1", model.ArtworkPriorityScan))).To(Succeed())
-		fresh, err := repo.Get(model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
+		Expect(repo.Enqueue(ctx, item("al", "t1", model.ArtworkPriorityScan))).To(Succeed())
+		fresh, err := repo.Get(ctx, model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(fresh.Attempts).To(BeZero())
 		Expect(fresh.Trace).To(Equal("[]"), "a fresh lifecycle has no last-attempt trace")
 	})
 
 	It("Enqueue restarts the retry budget an existing row had spent", func() {
-		Expect(repo.Enqueue(item("al", "e1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "e1", model.ArtworkPriorityScan))).To(Succeed())
 		backOff("al", "e1", time.Now().Add(-time.Hour))
 		stale := time.Now().Add(-48 * time.Hour)
 		_, err := GetDBXBuilder().NewQuery("UPDATE artwork_queue SET enqueued_at = {:t} WHERE item_id = 'e1'").
 			Bind(dbx.Params{"t": stale}).Execute()
 		Expect(err).ToNot(HaveOccurred())
 
-		Expect(repo.Enqueue(item("al", "e1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "e1", model.ArtworkPriorityScan))).To(Succeed())
 
-		got, err := repo.DequeueBatch(10)
+		got, err := repo.DequeueBatch(ctx, 10)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(got).To(HaveLen(1))
 		Expect(got[0].EnqueuedAt).To(BeTemporally("~", time.Now(), time.Minute),
@@ -182,40 +184,40 @@ var _ = Describe("ArtworkQueueRepository", func() {
 	})
 
 	It("deletes on completion and counts", func() {
-		Expect(repo.Enqueue(item("al", "c1", 0))).To(Succeed())
-		n, _ := repo.Count()
+		Expect(repo.Enqueue(ctx, item("al", "c1", 0))).To(Succeed())
+		n, _ := repo.Count(ctx)
 		Expect(n).To(Equal(int64(1)))
 		remove("al", "c1")
-		n, _ = repo.Count()
+		n, _ = repo.Count(ctx)
 		Expect(n).To(BeZero())
 	})
 
 	It("DeleteIfUnchanged deletes only while retry_at is unchanged", func() {
-		Expect(repo.Enqueue(item("al", "d1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "d1", model.ArtworkPriorityScan))).To(Succeed())
 		// Anchor retry_at in the past so it can never collide with the re-enqueue's now.
 		backOff("al", "d1", time.Now().Add(-time.Hour))
-		got, err := repo.DequeueBatch(10)
+		got, err := repo.DequeueBatch(ctx, 10)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(got).To(HaveLen(1))
 		original := got[0].RetryAt
 
 		// A concurrent scan re-enqueues, resetting retry_at to now.
-		Expect(repo.Enqueue(item("al", "d1", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "d1", model.ArtworkPriorityScan))).To(Succeed())
 
 		// Deleting with the stale retry_at is a no-op: the re-enqueued row survives.
-		Expect(repo.DeleteIfUnchanged("al", "d1", model.ImageTypePrimary, original)).To(Succeed())
-		n, _ := repo.Count()
+		Expect(repo.DeleteIfUnchanged(ctx, "al", "d1", model.ImageTypePrimary, original)).To(Succeed())
+		n, _ := repo.Count(ctx)
 		Expect(n).To(Equal(int64(1)))
 
-		got, _ = repo.DequeueBatch(10)
+		got, _ = repo.DequeueBatch(ctx, 10)
 		Expect(got).To(HaveLen(1))
-		Expect(repo.DeleteIfUnchanged("al", "d1", model.ImageTypePrimary, got[0].RetryAt)).To(Succeed())
-		n, _ = repo.Count()
+		Expect(repo.DeleteIfUnchanged(ctx, "al", "d1", model.ImageTypePrimary, got[0].RetryAt)).To(Succeed())
+		n, _ = repo.Count(ctx)
 		Expect(n).To(BeZero())
 	})
 
 	It("purges queue rows whose entity no longer exists, per kind", func() {
-		Expect(repo.Enqueue(
+		Expect(repo.Enqueue(ctx,
 			item("al", albumSgtPeppers.ID, model.ArtworkPriorityScan),
 			item("al", "no-such-album", model.ArtworkPriorityScan),
 			item("ar", artistKraftwerk.ID, model.ArtworkPriorityScan),
@@ -228,25 +230,25 @@ var _ = Describe("ArtworkQueueRepository", func() {
 			item("mf", "no-such-mediafile", model.ArtworkPriorityScan),
 		)).To(Succeed())
 
-		purged, err := repo.PurgeDangling()
+		purged, err := repo.PurgeDangling(ctx)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(purged).To(Equal(int64(5)))
 
-		got, _ := repo.DequeueBatch(100)
+		got, _ := repo.DequeueBatch(ctx, 100)
 		ids := slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })
 		Expect(ids).To(ConsistOf(albumSgtPeppers.ID, artistKraftwerk.ID, plsBest.ID, radioWithHomePage.ID, songDayInALife.ID))
 	})
 
 	It("enqueues entities that have no item_artwork row at all", func() {
-		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: albumSgtPeppers.ID, ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: time.Now()})).To(Succeed())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: albumAbbeyRoad.ID, ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
+		awRepo := NewArtworkRepository(GetDBXBuilder())
+		Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: albumSgtPeppers.ID, ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: time.Now()})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: albumAbbeyRoad.ID, ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
 
-		n, err := repo.EnqueueAllMissing(model.KindAlbumArtwork, model.ArtworkPriorityRecheck)
+		n, err := repo.EnqueueAllMissing(ctx, model.KindAlbumArtwork, model.ArtworkPriorityRecheck)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(n).To(BeNumerically(">=", 1))
 
-		got, err := repo.DequeueBatch(1000)
+		got, err := repo.DequeueBatch(ctx, 1000)
 		Expect(err).ToNot(HaveOccurred())
 		ids := make([]string, 0, len(got))
 		for _, it := range got {
@@ -260,122 +262,122 @@ var _ = Describe("ArtworkQueueRepository", func() {
 	})
 
 	It("EnqueueIfMissing skips items that already have an item_artwork row", func() {
-		awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "resolved", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: time.Now()})).To(Succeed())
-		Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "absent", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
+		awRepo := NewArtworkRepository(GetDBXBuilder())
+		Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "resolved", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: time.Now()})).To(Succeed())
+		Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "absent", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
 
-		Expect(repo.EnqueueIfMissing(
+		Expect(repo.EnqueueIfMissing(ctx,
 			item("al", "resolved", model.ArtworkPriorityScan),
 			item("al", "absent", model.ArtworkPriorityScan),
 			item("al", "brandnew", model.ArtworkPriorityScan),
 		)).To(Succeed())
 
-		got, err := repo.DequeueBatch(100)
+		got, err := repo.DequeueBatch(ctx, 100)
 		Expect(err).ToNot(HaveOccurred())
 		ids := slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })
 		Expect(ids).To(ConsistOf("brandnew"), "only an item with no state row may be enqueued")
 	})
 
 	It("EnqueueIfMissing leaves an already-queued row untouched", func() {
-		Expect(repo.Enqueue(item("al", "queued", model.ArtworkPriorityBump))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", "queued", model.ArtworkPriorityBump))).To(Succeed())
 
-		Expect(repo.EnqueueIfMissing(item("al", "queued", model.ArtworkPriorityScan))).To(Succeed())
+		Expect(repo.EnqueueIfMissing(ctx, item("al", "queued", model.ArtworkPriorityScan))).To(Succeed())
 
-		got, _ := repo.DequeueBatch(100)
+		got, _ := repo.DequeueBatch(ctx, 100)
 		Expect(got).To(HaveLen(1))
 		Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump), "the existing priority must survive")
 	})
 
 	Describe("EnqueueBySource", func() {
 		BeforeEach(func() {
-			artRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+			artRepo := NewArtworkRepository(GetDBXBuilder())
 			for _, ia := range []model.ItemArtwork{
 				{ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: "h1", Source: "external:deezer"},
 				{ItemKind: "ar", ItemID: "ar2", ImageType: model.ImageTypePrimary, Hash: "h2", Source: "external:lastfm"},
 				{ItemKind: "ar", ItemID: "ar3", ImageType: model.ImageTypePrimary, Hash: "", Source: ""},
 				{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "h4", Source: "external:deezer"},
 			} {
-				Expect(artRepo.PutItemArtwork(&ia)).To(Succeed())
+				Expect(artRepo.PutItemArtwork(ctx, &ia)).To(Succeed())
 			}
 		})
 
 		It("enqueues only the matching source within the kind", func() {
-			n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
+			n, err := repo.EnqueueBySource(ctx, model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(n).To(Equal(int64(1)), "al1 is a different kind and must not be touched")
 
-			got, err := repo.DequeueBatch(10)
+			got, err := repo.DequeueBatch(ctx, 10)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })).To(ConsistOf("ar1"))
 		})
 
 		It("treats the empty source as absent", func() {
-			n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{""}, model.ArtworkPriorityRecheck)
+			n, err := repo.EnqueueBySource(ctx, model.KindArtistArtwork, []string{""}, model.ArtworkPriorityRecheck)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(n).To(Equal(int64(1)))
 
-			got, _ := repo.DequeueBatch(10)
+			got, _ := repo.DequeueBatch(ctx, 10)
 			Expect(slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })).To(ConsistOf("ar3"))
 		})
 
 		It("enqueues every source when none is given", func() {
-			n, err := repo.EnqueueBySource(model.KindArtistArtwork, nil, model.ArtworkPriorityRecheck)
+			n, err := repo.EnqueueBySource(ctx, model.KindArtistArtwork, nil, model.ArtworkPriorityRecheck)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(n).To(Equal(int64(3)))
 		})
 
 		It("leaves the current artwork state in place", func() {
-			_, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
+			_, err := repo.EnqueueBySource(ctx, model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
 			Expect(err).ToNot(HaveOccurred())
 
-			artRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
-			ia, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
+			artRepo := NewArtworkRepository(GetDBXBuilder())
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ia.Hash).To(Equal("h1"), "the current image must survive until it is replaced")
 			Expect(ia.Source).To(Equal("external:deezer"))
 		})
 
 		It("does not disturb an already-queued row", func() {
-			Expect(repo.Enqueue(item("ar", "ar1", model.ArtworkPriorityBump))).To(Succeed())
+			Expect(repo.Enqueue(ctx, item("ar", "ar1", model.ArtworkPriorityBump))).To(Succeed())
 
-			n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
+			n, err := repo.EnqueueBySource(ctx, model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(n).To(BeZero())
 
-			got, _ := repo.DequeueBatch(10)
+			got, _ := repo.DequeueBatch(ctx, 10)
 			Expect(got).To(HaveLen(1))
 			Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump))
 		})
 
 		It("counts without enqueueing", func() {
-			n, err := repo.CountBySource(model.KindArtistArtwork, []string{"external:deezer"})
+			n, err := repo.CountBySource(ctx, model.KindArtistArtwork, []string{"external:deezer"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(n).To(Equal(int64(1)))
 
-			queued, err := repo.Count()
+			queued, err := repo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(queued).To(BeZero(), "CountBySource must not enqueue")
 		})
 
 		It("counts the absent source and every source", func() {
-			Expect(repo.CountBySource(model.KindArtistArtwork, []string{""})).To(Equal(int64(1)))
-			Expect(repo.CountBySource(model.KindArtistArtwork, nil)).To(Equal(int64(3)))
+			Expect(repo.CountBySource(ctx, model.KindArtistArtwork, []string{""})).To(Equal(int64(1)))
+			Expect(repo.CountBySource(ctx, model.KindArtistArtwork, nil)).To(Equal(int64(3)))
 		})
 
 		It("lists the distinct sources in use by a kind", func() {
-			Expect(repo.SourcesInUse(model.KindArtistArtwork)).To(ConsistOf("", "external:deezer", "external:lastfm"))
-			Expect(repo.SourcesInUse(model.KindAlbumArtwork)).To(ConsistOf("external:deezer"))
-			Expect(repo.SourcesInUse(model.KindRadioArtwork)).To(BeEmpty())
+			Expect(repo.SourcesInUse(ctx, model.KindArtistArtwork)).To(ConsistOf("", "external:deezer", "external:lastfm"))
+			Expect(repo.SourcesInUse(ctx, model.KindAlbumArtwork)).To(ConsistOf("external:deezer"))
+			Expect(repo.SourcesInUse(ctx, model.KindRadioArtwork)).To(BeEmpty())
 		})
 	})
 
 	It("does not disturb an already-queued entity when enqueueing missing rows", func() {
-		Expect(repo.Enqueue(item("al", albumRadioactivity.ID, model.ArtworkPriorityBump))).To(Succeed())
+		Expect(repo.Enqueue(ctx, item("al", albumRadioactivity.ID, model.ArtworkPriorityBump))).To(Succeed())
 
-		_, err := repo.EnqueueAllMissing(model.KindAlbumArtwork, model.ArtworkPriorityRecheck)
+		_, err := repo.EnqueueAllMissing(ctx, model.KindAlbumArtwork, model.ArtworkPriorityRecheck)
 		Expect(err).ToNot(HaveOccurred())
 
-		got, _ := repo.DequeueBatch(1000)
+		got, _ := repo.DequeueBatch(ctx, 1000)
 		var count int
 		for _, it := range got {
 			if it.ItemID == albumRadioactivity.ID {
@@ -388,12 +390,12 @@ var _ = Describe("ArtworkQueueRepository", func() {
 
 	Describe("status counters", func() {
 		It("groups queue rows by kind and priority", func() {
-			Expect(repo.Enqueue(item("ar", "a1", model.ArtworkPriorityBackfill))).To(Succeed())
-			Expect(repo.Enqueue(item("ar", "a2", model.ArtworkPriorityBackfill))).To(Succeed())
-			Expect(repo.Enqueue(item("ar", "a3", model.ArtworkPriorityBump))).To(Succeed())
-			Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
+			Expect(repo.Enqueue(ctx, item("ar", "a1", model.ArtworkPriorityBackfill))).To(Succeed())
+			Expect(repo.Enqueue(ctx, item("ar", "a2", model.ArtworkPriorityBackfill))).To(Succeed())
+			Expect(repo.Enqueue(ctx, item("ar", "a3", model.ArtworkPriorityBump))).To(Succeed())
+			Expect(repo.Enqueue(ctx, item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())
 
-			Expect(repo.CountQueued(nil, nil)).To(ConsistOf(
+			Expect(repo.CountQueued(ctx, nil, nil)).To(ConsistOf(
 				model.ArtworkQueueStat{ItemKind: "ar", Priority: model.ArtworkPriorityBackfill, Count: 2},
 				model.ArtworkQueueStat{ItemKind: "ar", Priority: model.ArtworkPriorityBump, Count: 1},
 				model.ArtworkQueueStat{ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1},
@@ -401,46 +403,46 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		})
 
 		It("selects only the absent states that gave up, not those a source answered", func() {
-			awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+			awRepo := NewArtworkRepository(GetDBXBuilder())
 			for _, ia := range []model.ItemArtwork{
 				{ItemKind: "ar", ItemID: "gaveup", ImageType: model.ImageTypePrimary, LastFailure: "[]"},
 				{ItemKind: "ar", ItemID: "toldno", ImageType: model.ImageTypePrimary},
 				{ItemKind: "ar", ItemID: "hasart", ImageType: model.ImageTypePrimary, Hash: "hX", LastFailure: "[]"},
 			} {
-				Expect(awRepo.PutItemArtwork(&ia)).To(Succeed())
+				Expect(awRepo.PutItemArtwork(ctx, &ia)).To(Succeed())
 			}
 
-			Expect(repo.CountBySource(model.KindArtistArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(1)),
+			Expect(repo.CountBySource(ctx, model.KindArtistArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(1)),
 				"an item still serving art is not absent, however its last attempt went")
 
 			// A later success rewrites the row, clearing the record.
-			Expect(awRepo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "gaveup",
+			Expect(awRepo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: "gaveup",
 				ImageType: model.ImageTypePrimary, Hash: "hZ"})).To(Succeed())
-			Expect(repo.CountBySource(model.KindArtistArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(0)))
+			Expect(repo.CountBySource(ctx, model.KindArtistArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(0)))
 		})
 
 		It("unions the failed pseudo-source with a real one, so absent plus failed is just absent", func() {
-			awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())
+			awRepo := NewArtworkRepository(GetDBXBuilder())
 			for _, ia := range []model.ItemArtwork{
 				{ItemKind: "ar", ItemID: "gaveup", ImageType: model.ImageTypePrimary, LastFailure: "[]"},
 				{ItemKind: "ar", ItemID: "toldno", ImageType: model.ImageTypePrimary},
 				{ItemKind: "ar", ItemID: "folder", ImageType: model.ImageTypePrimary, Hash: "hX", Source: "folder"},
 			} {
-				Expect(awRepo.PutItemArtwork(&ia)).To(Succeed())
+				Expect(awRepo.PutItemArtwork(ctx, &ia)).To(Succeed())
 			}
 			failedAndAbsent := []string{model.ArtworkSourceFailed, ""}
-			Expect(repo.CountBySource(model.KindArtistArtwork, failedAndAbsent)).To(Equal(int64(2)),
+			Expect(repo.CountBySource(ctx, model.KindArtistArtwork, failedAndAbsent)).To(Equal(int64(2)),
 				"failed is a subset of absent, so asking for both is asking for absent")
-			Expect(repo.CountBySource(model.KindArtistArtwork, []string{model.ArtworkSourceFailed, "folder"})).
+			Expect(repo.CountBySource(ctx, model.KindArtistArtwork, []string{model.ArtworkSourceFailed, "folder"})).
 				To(Equal(int64(2)), "a pseudo-source and a stored source combine as a union")
 		})
 
 		It("reports a kind with nothing failed as zero", func() {
-			Expect(repo.CountBySource(model.KindRadioArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(0)))
+			Expect(repo.CountBySource(ctx, model.KindRadioArtwork, []string{model.ArtworkSourceFailed})).To(Equal(int64(0)))
 		})
 
 		It("reports an empty queue as no rows", func() {
-			Expect(repo.CountQueued(nil, nil)).To(BeEmpty())
+			Expect(repo.CountQueued(ctx, nil, nil)).To(BeEmpty())
 		})
 
 	})
@@ -448,13 +450,13 @@ var _ = Describe("ArtworkQueueRepository", func() {
 	Describe("PurgeQueued", func() {
 		queuedIDs := func() []string {
 			GinkgoHelper()
-			got, err := repo.DequeueBatch(100)
+			got, err := repo.DequeueBatch(ctx, 100)
 			Expect(err).ToNot(HaveOccurred())
 			return slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })
 		}
 
 		BeforeEach(func() {
-			Expect(repo.Enqueue(
+			Expect(repo.Enqueue(ctx,
 				item("ar", "ar-backfill", model.ArtworkPriorityBackfill),
 				item("ar", "ar-bump", model.ArtworkPriorityBump),
 				item("al", "al-backfill", model.ArtworkPriorityBackfill),
@@ -466,7 +468,7 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		// every selection must count exactly what it deletes.
 		DescribeTable("selects the same rows to count and to delete",
 			func(kinds []model.Kind, priorities []int, deleted int, remaining []string) {
-				counted, err := repo.CountQueued(kinds, priorities)
+				counted, err := repo.CountQueued(ctx, kinds, priorities)
 				Expect(err).ToNot(HaveOccurred())
 				var total int64
 				for _, s := range counted {
@@ -474,7 +476,7 @@ var _ = Describe("ArtworkQueueRepository", func() {
 				}
 				Expect(total).To(BeNumerically("==", deleted), "the preview must match the delete")
 
-				Expect(repo.PurgeQueued(kinds, priorities)).To(BeNumerically("==", deleted))
+				Expect(repo.PurgeQueued(ctx, kinds, priorities)).To(BeNumerically("==", deleted))
 				Expect(queuedIDs()).To(ConsistOf(remaining))
 			},
 			Entry("only the given kinds", []model.Kind{model.KindArtistArtwork}, nil,
@@ -496,8 +498,8 @@ var _ = Describe("ArtworkQueueRepository", func() {
 		It("deletes a row that is still backing off", func() {
 			backOff("ar", "ar-bump", time.Now().Add(time.Hour))
 
-			Expect(repo.PurgeQueued([]model.Kind{model.KindArtistArtwork}, nil)).To(BeNumerically("==", 2))
-			Expect(repo.Get(model.KindArtistArtwork, "ar-bump", model.ImageTypePrimary)).
+			Expect(repo.PurgeQueued(ctx, []model.Kind{model.KindArtistArtwork}, nil)).To(BeNumerically("==", 2))
+			Expect(repo.Get(ctx, model.KindArtistArtwork, "ar-bump", model.ImageTypePrimary)).
 				Error().To(MatchError(model.ErrNotFound))
 		})
 
diff --git a/persistence/artwork_repository.go b/persistence/artwork_repository.go
index 89eb1d415..bd3a3d87c 100644
--- a/persistence/artwork_repository.go
+++ b/persistence/artwork_repository.go
@@ -21,27 +21,25 @@ type artworkRepository struct {
 	items sqlRepository
 }
 
-func NewArtworkRepository(ctx context.Context, db dbx.Builder) model.ArtworkRepository {
+func NewArtworkRepository(db dbx.Builder) model.ArtworkRepository {
 	r := &artworkRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "artwork"
-	r.items.ctx = ctx
 	r.items.db = db
 	r.items.tableName = itemArtworkTable
 	return r
 }
 
-func (r *artworkRepository) GetImage(hash string) (*model.Artwork, error) {
+func (r *artworkRepository) GetImage(ctx context.Context, hash string) (*model.Artwork, error) {
 	sel := Select("*").From(r.tableName).Where(Eq{"hash": hash})
 	var res model.Artwork
-	if err := r.queryOne(sel, &res); err != nil {
+	if err := r.queryOne(ctx, sel, &res); err != nil {
 		return nil, err
 	}
 	return &res, nil
 }
 
-func (r *artworkRepository) PutImage(a *model.Artwork) error {
+func (r *artworkRepository) PutImage(ctx context.Context, a *model.Artwork) error {
 	// created_at is the last-acquisition-write time the prune grace window keys on.
 	a.CreatedAt = time.Now()
 	values, err := toSQLArgs(*a)
@@ -53,17 +51,17 @@ func (r *artworkRepository) PutImage(a *model.Artwork) error {
 		height=excluded.height, size_bytes=excluded.size_bytes, blur_hash=excluded.blur_hash,
 		thumb_hash=excluded.thumb_hash, dominant_color=excluded.dominant_color,
 		created_at=excluded.created_at`)
-	_, err = r.executeSQL(ins)
+	_, err = r.executeSQL(ctx, ins)
 	return err
 }
 
-func (r *artworkRepository) GetMimeByHash() (map[string]string, error) {
+func (r *artworkRepository) GetMimeByHash(ctx context.Context) (map[string]string, error) {
 	sel := Select("hash", "mime").From(r.tableName)
 	var rows []struct {
 		Hash string
 		Mime string
 	}
-	if err := r.queryAll(sel, &rows); err != nil {
+	if err := r.queryAll(ctx, sel, &rows); err != nil {
 		return nil, err
 	}
 	res := make(map[string]string, len(rows))
@@ -73,12 +71,12 @@ func (r *artworkRepository) GetMimeByHash() (map[string]string, error) {
 	return res, nil
 }
 
-func (r *artworkRepository) PurgeOrphans(createdBefore time.Time) (int64, error) {
+func (r *artworkRepository) PurgeOrphans(ctx context.Context, createdBefore time.Time) (int64, error) {
 	del := Delete(r.tableName).Where(And{
 		Lt{"created_at": createdBefore},
 		Expr("hash NOT IN (SELECT hash FROM " + itemArtworkTable + " WHERE hash <> '')"),
 	})
-	return r.executeSQL(del)
+	return r.executeSQL(ctx, del)
 }
 
 // artworkOwnerTables maps an artwork kind to the table that owns the entity.
@@ -91,14 +89,14 @@ var artworkOwnerTables = map[model.Kind]string{
 }
 
 // purgeDangling deletes rows in r's table whose owning entity is gone, one statement per kind.
-func purgeDangling(r sqlRepository) (int64, error) {
+func purgeDangling(ctx context.Context, r sqlRepository) (int64, error) {
 	var total int64
 	for kind, entityTable := range artworkOwnerTables {
 		del := Delete(r.tableName).Where(And{
 			Eq{"item_kind": kind.Prefix()},
 			Expr("item_id NOT IN (SELECT id FROM " + entityTable + ")"),
 		})
-		c, err := r.executeSQL(del)
+		c, err := r.executeSQL(ctx, del)
 		if err != nil {
 			return total, err
 		}
@@ -107,21 +105,21 @@ func purgeDangling(r sqlRepository) (int64, error) {
 	return total, nil
 }
 
-func (r *artworkRepository) PurgeDanglingItems() (int64, error) {
-	return purgeDangling(r.items)
+func (r *artworkRepository) PurgeDanglingItems(ctx context.Context) (int64, error) {
+	return purgeDangling(ctx, r.items)
 }
 
-func (r *artworkRepository) GetItemArtwork(kind model.Kind, id, imageType string) (*model.ItemArtwork, error) {
+func (r *artworkRepository) GetItemArtwork(ctx context.Context, kind model.Kind, id, imageType string) (*model.ItemArtwork, error) {
 	sel := Select("*").From(itemArtworkTable).
 		Where(Eq{"item_kind": kind.Prefix(), "item_id": id, "image_type": imageType})
 	var res model.ItemArtwork
-	if err := r.items.queryOne(sel, &res); err != nil {
+	if err := r.items.queryOne(ctx, sel, &res); err != nil {
 		return nil, err
 	}
 	return &res, nil
 }
 
-func (r *artworkRepository) PutItemArtwork(ia *model.ItemArtwork) error {
+func (r *artworkRepository) PutItemArtwork(ctx context.Context, ia *model.ItemArtwork) error {
 	ia.ImageType = cmp.Or(ia.ImageType, model.ImageTypePrimary)
 	ia.UpdatedAt = time.Now()
 	// PutItemArtwork records the outcome of an attempt, so an unset attempted_at is now.
@@ -136,29 +134,29 @@ func (r *artworkRepository) PutItemArtwork(ia *model.ItemArtwork) error {
 		hash=excluded.hash, source=excluded.source, source_path=excluded.source_path, ref_mtime=excluded.ref_mtime,
 		trace=excluded.trace, last_failure=excluded.last_failure,
 		attempted_at=excluded.attempted_at, updated_at=excluded.updated_at`)
-	_, err = r.items.executeSQL(ins)
+	_, err = r.items.executeSQL(ctx, ins)
 	return err
 }
 
 // PutLastFailure records why an item exhausted its retry budget. It only updates an existing row:
 // inserting one would write an empty hash, which the rest of the system reads as a settled absent.
-func (r *artworkRepository) PutLastFailure(kind model.Kind, id, imageType, trace string) error {
+func (r *artworkRepository) PutLastFailure(ctx context.Context, kind model.Kind, id, imageType, trace string) error {
 	upd := Update(itemArtworkTable).Set("last_failure", trace).
 		Where(Eq{"item_kind": kind.Prefix(), "item_id": id, "image_type": imageType})
-	_, err := r.items.executeSQL(upd)
+	_, err := r.items.executeSQL(ctx, upd)
 	return err
 }
 
-func (r *artworkRepository) DeleteForItems(kind model.Kind, ids []string) error {
+func (r *artworkRepository) DeleteForItems(ctx context.Context, kind model.Kind, ids []string) error {
 	for chunk := range slices.Chunk(ids, artworkBatchSize) {
-		if err := r.items.delete(Eq{"item_kind": kind.Prefix(), "item_id": chunk}); err != nil {
+		if err := r.items.delete(ctx, Eq{"item_kind": kind.Prefix(), "item_id": chunk}); err != nil {
 			return err
 		}
 	}
 	return nil
 }
 
-func (r *artworkRepository) GetInfoForItems(kind model.Kind, ids []string) (map[string]model.ItemArtworkInfo, error) {
+func (r *artworkRepository) GetInfoForItems(ctx context.Context, kind model.Kind, ids []string) (map[string]model.ItemArtworkInfo, error) {
 	res := map[string]model.ItemArtworkInfo{}
 	for chunk := range slices.Chunk(ids, artworkBatchSize) {
 		sel := Select("ia.item_id", "ia.hash", "COALESCE(a.blur_hash, '') as blur_hash",
@@ -173,7 +171,7 @@ func (r *artworkRepository) GetInfoForItems(kind model.Kind, ids []string) (map[
 				Eq{"ia.item_id": chunk},
 			})
 		var rows []model.ItemArtworkInfo
-		if err := r.items.queryAll(sel, &rows); err != nil {
+		if err := r.items.queryAll(ctx, sel, &rows); err != nil {
 			return nil, err
 		}
 		for _, row := range rows {
diff --git a/persistence/artwork_repository_test.go b/persistence/artwork_repository_test.go
index a9687f76b..338a7c3ab 100644
--- a/persistence/artwork_repository_test.go
+++ b/persistence/artwork_repository_test.go
@@ -20,55 +20,57 @@ func clearArtworkTables() {
 }
 
 var _ = Describe("ArtworkRepository", func() {
+	var ctx context.Context
 	var repo model.ArtworkRepository
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		clearArtworkTables()
 		DeferCleanup(clearArtworkTables)
-		repo = NewArtworkRepository(context.Background(), GetDBXBuilder())
+		repo = NewArtworkRepository(GetDBXBuilder())
 	})
 
 	Context("resolution traces", func() {
 		const traceJSON = `[{"c":"cover.*","o":"hit"}]`
 
 		It("round-trips the trace with the state row", func() {
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "t1",
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "t1",
 				ImageType: model.ImageTypePrimary, Hash: "h1", Trace: traceJSON})).To(Succeed())
 
-			got, err := repo.GetItemArtwork(model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
+			got, err := repo.GetItemArtwork(ctx, model.KindAlbumArtwork, "t1", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Trace).To(Equal(traceJSON))
 			Expect(got.LastFailure).To(BeEmpty())
 		})
 
 		It("replaces the trace when the item is resolved again", func() {
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "t2",
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "t2",
 				ImageType: model.ImageTypePrimary, Trace: traceJSON})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "t2",
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "t2",
 				ImageType: model.ImageTypePrimary, Trace: `[{"c":"embedded","o":"hit"}]`})).To(Succeed())
 
-			got, _ := repo.GetItemArtwork(model.KindAlbumArtwork, "t2", model.ImageTypePrimary)
+			got, _ := repo.GetItemArtwork(ctx, model.KindAlbumArtwork, "t2", model.ImageTypePrimary)
 			Expect(got.Trace).To(Equal(`[{"c":"embedded","o":"hit"}]`))
 		})
 
 		It("records a last failure on an existing row", func() {
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "t3",
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "t3",
 				ImageType: model.ImageTypePrimary, Hash: "h3"})).To(Succeed())
 
-			Expect(repo.PutLastFailure(model.KindAlbumArtwork, "t3", model.ImageTypePrimary,
+			Expect(repo.PutLastFailure(ctx, model.KindAlbumArtwork, "t3", model.ImageTypePrimary,
 				`[{"c":"decode","o":"error"}]`)).To(Succeed())
 
-			got, _ := repo.GetItemArtwork(model.KindAlbumArtwork, "t3", model.ImageTypePrimary)
+			got, _ := repo.GetItemArtwork(ctx, model.KindAlbumArtwork, "t3", model.ImageTypePrimary)
 			Expect(got.LastFailure).To(Equal(`[{"c":"decode","o":"error"}]`))
 			Expect(got.Hash).To(Equal("h3"), "recording a failure must not disturb the served artwork")
 		})
 
 		// Inserting here would write hash='', which every reader treats as a settled absent.
 		It("never creates a row for an item that has no state", func() {
-			Expect(repo.PutLastFailure(model.KindAlbumArtwork, "ghost", model.ImageTypePrimary,
+			Expect(repo.PutLastFailure(ctx, model.KindAlbumArtwork, "ghost", model.ImageTypePrimary,
 				`[{"c":"decode","o":"error"}]`)).To(Succeed())
 
-			_, err := repo.GetItemArtwork(model.KindAlbumArtwork, "ghost", model.ImageTypePrimary)
+			_, err := repo.GetItemArtwork(ctx, model.KindAlbumArtwork, "ghost", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 	})
@@ -76,9 +78,9 @@ var _ = Describe("ArtworkRepository", func() {
 	Context("image identity", func() {
 		It("stores and retrieves an artwork by hash", func() {
 			a := &model.Artwork{Hash: "abc123", Mime: "image/jpeg", Width: 500, Height: 500, SizeBytes: 1234, BlurHash: "LKO2?U%2Tw=w"}
-			Expect(repo.PutImage(a)).To(Succeed())
+			Expect(repo.PutImage(ctx, a)).To(Succeed())
 
-			got, err := repo.GetImage("abc123")
+			got, err := repo.GetImage(ctx, "abc123")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Mime).To(Equal("image/jpeg"))
 			Expect(got.BlurHash).To(Equal("LKO2?U%2Tw=w"))
@@ -88,9 +90,9 @@ var _ = Describe("ArtworkRepository", func() {
 		It("round-trips the thumbhash alongside the blurhash", func() {
 			a := &model.Artwork{Hash: "both1", Mime: "image/jpeg", BlurHash: "LKO2?U%2Tw=w",
 				ThumbHash: "1QcSHQRnh493V4dIh4eXh1h4kJUI", DominantColor: "#336699"}
-			Expect(repo.PutImage(a)).To(Succeed())
+			Expect(repo.PutImage(ctx, a)).To(Succeed())
 
-			got, err := repo.GetImage("both1")
+			got, err := repo.GetImage(ctx, "both1")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.BlurHash).To(Equal("LKO2?U%2Tw=w"))
 			Expect(got.ThumbHash).To(Equal("1QcSHQRnh493V4dIh4eXh1h4kJUI"))
@@ -98,10 +100,10 @@ var _ = Describe("ArtworkRepository", func() {
 		})
 
 		It("overwrites the thumbhash on re-acquisition", func() {
-			Expect(repo.PutImage(&model.Artwork{Hash: "th2", Mime: "image/png", ThumbHash: "first", DominantColor: "#111111"})).To(Succeed())
-			Expect(repo.PutImage(&model.Artwork{Hash: "th2", Mime: "image/png", ThumbHash: "second", DominantColor: "#222222"})).To(Succeed())
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "th2", Mime: "image/png", ThumbHash: "first", DominantColor: "#111111"})).To(Succeed())
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "th2", Mime: "image/png", ThumbHash: "second", DominantColor: "#222222"})).To(Succeed())
 
-			got, err := repo.GetImage("th2")
+			got, err := repo.GetImage(ctx, "th2")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.ThumbHash).To(Equal("second"))
 			Expect(got.DominantColor).To(Equal("#222222"))
@@ -109,76 +111,76 @@ var _ = Describe("ArtworkRepository", func() {
 
 		It("is idempotent on Put (upsert by hash)", func() {
 			a := &model.Artwork{Hash: "dup1", Mime: "image/png"}
-			Expect(repo.PutImage(a)).To(Succeed())
+			Expect(repo.PutImage(ctx, a)).To(Succeed())
 			a.BlurHash = "XYZ"
-			Expect(repo.PutImage(a)).To(Succeed())
-			got, _ := repo.GetImage("dup1")
+			Expect(repo.PutImage(ctx, a)).To(Succeed())
+			got, _ := repo.GetImage(ctx, "dup1")
 			Expect(got.BlurHash).To(Equal("XYZ"))
 		})
 
 		It("refreshes created_at when reacquiring an existing hash", func() {
-			Expect(repo.PutImage(&model.Artwork{Hash: "reacq", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "reacq", Mime: "image/jpeg"})).To(Succeed())
 			_, err := GetDBXBuilder().NewQuery("UPDATE artwork SET created_at={:t} WHERE hash='reacq'").
 				Bind(dbx.Params{"t": "2000-01-01 00:00:00"}).Execute()
 			Expect(err).ToNot(HaveOccurred())
 
-			Expect(repo.PutImage(&model.Artwork{Hash: "reacq", Mime: "image/png"})).To(Succeed())
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "reacq", Mime: "image/png"})).To(Succeed())
 
-			got, err := repo.GetImage("reacq")
+			got, err := repo.GetImage(ctx, "reacq")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.CreatedAt).To(BeTemporally(">", time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)))
 		})
 
 		It("returns ErrNotFound for a missing hash", func() {
-			_, err := repo.GetImage("nope")
+			_, err := repo.GetImage(ctx, "nope")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
 		It("returns every stored hash with its current mime", func() {
-			Expect(repo.PutImage(&model.Artwork{Hash: "all1", Mime: "image/jpeg"})).To(Succeed())
-			Expect(repo.PutImage(&model.Artwork{Hash: "all2", Mime: "image/png"})).To(Succeed())
-			mimes, err := repo.GetMimeByHash()
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "all1", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "all2", Mime: "image/png"})).To(Succeed())
+			mimes, err := repo.GetMimeByHash(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(mimes).To(HaveKeyWithValue("all1", "image/jpeg"))
 			Expect(mimes).To(HaveKeyWithValue("all2", "image/png"))
 		})
 
 		It("deletes only unreferenced rows older than the cutoff, reporting the count", func() {
-			Expect(repo.PutImage(&model.Artwork{Hash: "d1", Mime: "image/jpeg"})).To(Succeed())
-			Expect(repo.PutImage(&model.Artwork{Hash: "dref", Mime: "image/jpeg"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "a1",
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "d1", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "dref", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "a1",
 				ImageType: model.ImageTypePrimary, Hash: "dref", Source: "folder"})).To(Succeed())
 
-			Expect(repo.PurgeOrphans(time.Now().Add(time.Minute))).To(BeNumerically("==", 1))
+			Expect(repo.PurgeOrphans(ctx, time.Now().Add(time.Minute))).To(BeNumerically("==", 1))
 
-			_, err := repo.GetImage("d1")
+			_, err := repo.GetImage(ctx, "d1")
 			Expect(err).To(MatchError(model.ErrNotFound))
-			_, err = repo.GetImage("dref")
+			_, err = repo.GetImage(ctx, "dref")
 			Expect(err).ToNot(HaveOccurred())
 		})
 
 		It("spares an unreferenced row younger than the cutoff", func() {
-			Expect(repo.PutImage(&model.Artwork{Hash: "young", Mime: "image/jpeg"})).To(Succeed())
-			Expect(repo.PurgeOrphans(time.Now().Add(-time.Hour))).To(BeNumerically("==", 0))
-			_, err := repo.GetImage("young")
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "young", Mime: "image/jpeg"})).To(Succeed())
+			Expect(repo.PurgeOrphans(ctx, time.Now().Add(-time.Hour))).To(BeNumerically("==", 0))
+			_, err := repo.GetImage(ctx, "young")
 			Expect(err).ToNot(HaveOccurred())
 		})
 	})
 
 	Context("dangling state cleanup", func() {
 		It("purges item_artwork rows per kind whose entity no longer exists, summing counts", func() {
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: albumSgtPeppers.ID, ImageType: model.ImageTypePrimary, Hash: "keepAl"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "no-such-album", ImageType: model.ImageTypePrimary, Hash: "danglingAl"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: artistKraftwerk.ID, ImageType: model.ImageTypePrimary, Hash: "keepAr"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "no-such-artist", ImageType: model.ImageTypePrimary, Hash: "danglingAr"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "pl", ItemID: plsBest.ID, ImageType: model.ImageTypePrimary, Hash: "keepPl"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "pl", ItemID: "no-such-playlist", ImageType: model.ImageTypePrimary, Hash: "danglingPl"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ra", ItemID: radioWithHomePage.ID, ImageType: model.ImageTypePrimary, Hash: "keepRa"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ra", ItemID: "no-such-radio", ImageType: model.ImageTypePrimary, Hash: "danglingRa"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: songDayInALife.ID, ImageType: model.ImageTypePrimary, Hash: "keepMf"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: "no-such-mediafile", ImageType: model.ImageTypePrimary, Hash: "danglingMf"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: albumSgtPeppers.ID, ImageType: model.ImageTypePrimary, Hash: "keepAl"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "no-such-album", ImageType: model.ImageTypePrimary, Hash: "danglingAl"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: artistKraftwerk.ID, ImageType: model.ImageTypePrimary, Hash: "keepAr"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: "no-such-artist", ImageType: model.ImageTypePrimary, Hash: "danglingAr"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "pl", ItemID: plsBest.ID, ImageType: model.ImageTypePrimary, Hash: "keepPl"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "pl", ItemID: "no-such-playlist", ImageType: model.ImageTypePrimary, Hash: "danglingPl"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ra", ItemID: radioWithHomePage.ID, ImageType: model.ImageTypePrimary, Hash: "keepRa"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ra", ItemID: "no-such-radio", ImageType: model.ImageTypePrimary, Hash: "danglingRa"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "mf", ItemID: songDayInALife.ID, ImageType: model.ImageTypePrimary, Hash: "keepMf"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "mf", ItemID: "no-such-mediafile", ImageType: model.ImageTypePrimary, Hash: "danglingMf"})).To(Succeed())
 
-			purged, err := repo.PurgeDanglingItems()
+			purged, err := repo.PurgeDanglingItems(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(purged).To(Equal(int64(5)))
 
@@ -190,7 +192,7 @@ var _ = Describe("ArtworkRepository", func() {
 				{ItemKind: "mf", ItemID: songDayInALife.ID},
 			} {
 				k, _ := model.ParseKind(kept.ItemKind)
-				_, err := repo.GetItemArtwork(k, kept.ItemID, model.ImageTypePrimary)
+				_, err := repo.GetItemArtwork(ctx, k, kept.ItemID, model.ImageTypePrimary)
 				Expect(err).ToNot(HaveOccurred())
 			}
 			for _, gone := range []model.ItemArtwork{
@@ -201,7 +203,7 @@ var _ = Describe("ArtworkRepository", func() {
 				{ItemKind: "mf", ItemID: "no-such-mediafile"},
 			} {
 				k, _ := model.ParseKind(gone.ItemKind)
-				_, err := repo.GetItemArtwork(k, gone.ItemID, model.ImageTypePrimary)
+				_, err := repo.GetItemArtwork(ctx, k, gone.ItemID, model.ImageTypePrimary)
 				Expect(err).To(MatchError(model.ErrNotFound))
 			}
 		})
@@ -211,13 +213,13 @@ var _ = Describe("ArtworkRepository", func() {
 		It("upserts and reads state, including per-item provenance", func() {
 			ia := &model.ItemArtwork{ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary,
 				Hash: "h1", Source: "folder", SourcePath: "/music/a/cover.jpg", RefMtime: 111, AttemptedAt: time.Now()}
-			Expect(repo.PutItemArtwork(ia)).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, ia)).To(Succeed())
 			ia.Source = "embedded"
 			ia.SourcePath = "/music/a/track.mp3"
 			ia.RefMtime = 222
-			Expect(repo.PutItemArtwork(ia)).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, ia)).To(Succeed())
 
-			got, err := repo.GetItemArtwork(model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
+			got, err := repo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al1", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Source).To(Equal("embedded"))
 			Expect(got.SourcePath).To(Equal("/music/a/track.mp3"))
@@ -227,28 +229,28 @@ var _ = Describe("ArtworkRepository", func() {
 
 		It("defaults attempted_at to now when unset", func() {
 			before := time.Now().Add(-time.Second)
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "noattempt",
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: "noattempt",
 				ImageType: model.ImageTypePrimary, Hash: ""})).To(Succeed())
-			got, err := repo.GetItemArtwork(model.KindArtistArtwork, "noattempt", model.ImageTypePrimary)
+			got, err := repo.GetItemArtwork(ctx, model.KindArtistArtwork, "noattempt", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.AttemptedAt).To(BeTemporally(">", before))
 		})
 
 		It("represents known-absent as empty hash", func() {
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "ar", ItemID: "ar1",
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "ar", ItemID: "ar1",
 				ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()})).To(Succeed())
-			got, err := repo.GetItemArtwork(model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
+			got, err := repo.GetItemArtwork(ctx, model.KindArtistArtwork, "ar1", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Hash).To(BeEmpty())
 		})
 
 		It("hydrates a page in one batch, including blurhash, dimensions and absence", func() {
-			Expect(repo.PutImage(&model.Artwork{Hash: "h9", Mime: "image/jpeg", BlurHash: "BH9",
+			Expect(repo.PutImage(ctx, &model.Artwork{Hash: "h9", Mime: "image/jpeg", BlurHash: "BH9",
 				DominantColor: "#abcdef", Width: 1200, Height: 800})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "x1", ImageType: model.ImageTypePrimary, Hash: "h9", Source: "folder"})).To(Succeed())
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "al", ItemID: "x2", ImageType: model.ImageTypePrimary, Hash: "", Source: ""})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "x1", ImageType: model.ImageTypePrimary, Hash: "h9", Source: "folder"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "al", ItemID: "x2", ImageType: model.ImageTypePrimary, Hash: "", Source: ""})).To(Succeed())
 
-			info, err := repo.GetInfoForItems(model.KindAlbumArtwork, []string{"x1", "x2", "x3"})
+			info, err := repo.GetInfoForItems(ctx, model.KindAlbumArtwork, []string{"x1", "x2", "x3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(info).To(HaveLen(2))
 			Expect(info["x1"].Hash).To(Equal("h9"))
@@ -263,9 +265,9 @@ var _ = Describe("ArtworkRepository", func() {
 		})
 
 		It("deletes all rows for a single item", func() {
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "pl", ItemID: "p1", ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
-			Expect(repo.DeleteForItems(model.KindPlaylistArtwork, []string{"p1"})).To(Succeed())
-			_, err := repo.GetItemArtwork(model.KindPlaylistArtwork, "p1", model.ImageTypePrimary)
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "pl", ItemID: "p1", ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
+			Expect(repo.DeleteForItems(ctx, model.KindPlaylistArtwork, []string{"p1"})).To(Succeed())
+			_, err := repo.GetItemArtwork(ctx, model.KindPlaylistArtwork, "p1", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
@@ -275,17 +277,17 @@ var _ = Describe("ArtworkRepository", func() {
 			for i := range n {
 				id := fmt.Sprintf("mf-%d", i)
 				ids[i] = id
-				Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: id, ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
+				Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "mf", ItemID: id, ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
 			}
-			Expect(repo.PutItemArtwork(&model.ItemArtwork{ItemKind: "mf", ItemID: "keep", ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
+			Expect(repo.PutItemArtwork(ctx, &model.ItemArtwork{ItemKind: "mf", ItemID: "keep", ImageType: model.ImageTypePrimary, Hash: "h1"})).To(Succeed())
 
-			Expect(repo.DeleteForItems(model.KindMediaFileArtwork, ids)).To(Succeed())
+			Expect(repo.DeleteForItems(ctx, model.KindMediaFileArtwork, ids)).To(Succeed())
 
 			for _, id := range ids {
-				_, err := repo.GetItemArtwork(model.KindMediaFileArtwork, id, model.ImageTypePrimary)
+				_, err := repo.GetItemArtwork(ctx, model.KindMediaFileArtwork, id, model.ImageTypePrimary)
 				Expect(err).To(MatchError(model.ErrNotFound))
 			}
-			kept, err := repo.GetItemArtwork(model.KindMediaFileArtwork, "keep", model.ImageTypePrimary)
+			kept, err := repo.GetItemArtwork(ctx, model.KindMediaFileArtwork, "keep", model.ImageTypePrimary)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(kept.ItemID).To(Equal("keep"))
 		})
diff --git a/persistence/criteria_sql_benchmark_test.go b/persistence/criteria_sql_benchmark_test.go
index 523a5d825..30c1ba100 100644
--- a/persistence/criteria_sql_benchmark_test.go
+++ b/persistence/criteria_sql_benchmark_test.go
@@ -189,11 +189,11 @@ func setupBenchData(b *testing.B, ctx context.Context, conn *dbx.DB, user model.
 
 	sqlDB := db.Db()
 
-	ur := NewUserRepository(ctx, conn)
-	if err := ur.Put(&user); err != nil {
+	ur := NewUserRepository(conn)
+	if err := ur.Put(ctx, &user); err != nil {
 		b.Fatal(err)
 	}
-	if err := ur.SetUserLibraries(user.ID, []int{1}); err != nil {
+	if err := ur.SetUserLibraries(ctx, user.ID, []int{1}); err != nil {
 		b.Fatal(err)
 	}
 
diff --git a/persistence/e2e/e2e_suite_test.go b/persistence/e2e/e2e_suite_test.go
index 2b617f5b0..a757901d3 100644
--- a/persistence/e2e/e2e_suite_test.go
+++ b/persistence/e2e/e2e_suite_test.go
@@ -143,7 +143,7 @@ func buildTestFS() {
 }
 
 func findMediaFileByTitle(title string) string {
-	mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+	mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 		Filters: squirrel.Eq{"media_file.title": title},
 	})
 	Expect(err).ToNot(HaveOccurred())
@@ -178,10 +178,10 @@ func evaluateRuleOrderedAs(owner model.User, jsonRule string) []string {
 		OwnerID: owner.ID,
 		Rules:   &rules,
 	}
-	err = ds.Playlist(userCtx).Put(pls)
+	err = ds.Playlist().Put(userCtx, pls)
 	Expect(err).ToNot(HaveOccurred())
 
-	loaded, err := ds.Playlist(userCtx).GetWithTracks(pls.ID, true, false)
+	loaded, err := ds.Playlist().GetWithTracks(userCtx, pls.ID, true, false)
 	Expect(err).ToNot(HaveOccurred())
 
 	titles := make([]string, len(loaded.Tracks))
@@ -201,7 +201,7 @@ func createPlaylist(owner model.User, public bool, titles ...string) string {
 		mfID := findMediaFileByTitle(title)
 		pls.AddMediaFilesByID([]string{mfID})
 	}
-	Expect(ds.Playlist(ctx).Put(pls)).To(Succeed())
+	Expect(ds.Playlist().Put(ctx, pls)).To(Succeed())
 	return pls.ID
 }
 
@@ -230,7 +230,7 @@ func createSmartPlaylist(owner model.User, public bool, jsonRule string) string
 		Public:  public,
 		Rules:   &rules,
 	}
-	Expect(ds.Playlist(ctx).Put(pls)).To(Succeed())
+	Expect(ds.Playlist().Put(ctx, pls)).To(Succeed())
 	return pls.ID
 }
 
@@ -252,22 +252,22 @@ var _ = BeforeSuite(func() {
 
 	userWithPass := adminUser
 	userWithPass.NewPassword = "password"
-	Expect(initDS.User(ctx).Put(&userWithPass)).To(Succeed())
+	Expect(initDS.User().Put(ctx, &userWithPass)).To(Succeed())
 
 	regularUserWithPass := regularUser
 	regularUserWithPass.NewPassword = "password"
-	Expect(initDS.User(ctx).Put(&regularUserWithPass)).To(Succeed())
+	Expect(initDS.User().Put(ctx, &regularUserWithPass)).To(Succeed())
 
 	lib = model.Library{ID: 1, Name: "Music Library", Path: "fake:///music"}
-	Expect(initDS.Library(ctx).Put(&lib)).To(Succeed())
-	Expect(initDS.User(ctx).SetUserLibraries(adminUser.ID, []int{lib.ID})).To(Succeed())
-	Expect(initDS.User(ctx).SetUserLibraries(regularUser.ID, []int{lib.ID})).To(Succeed())
+	Expect(initDS.Library().Put(ctx, &lib)).To(Succeed())
+	Expect(initDS.User().SetUserLibraries(ctx, adminUser.ID, []int{lib.ID})).To(Succeed())
+	Expect(initDS.User().SetUserLibraries(ctx, regularUser.ID, []int{lib.ID})).To(Succeed())
 
-	loadedUser, err := initDS.User(ctx).FindByUsername(adminUser.UserName)
+	loadedUser, err := initDS.User().FindByUsername(ctx, adminUser.UserName)
 	Expect(err).ToNot(HaveOccurred())
 	adminUser.Libraries = loadedUser.Libraries
 
-	loadedOther, err := initDS.User(ctx).FindByUsername(regularUser.UserName)
+	loadedOther, err := initDS.User().FindByUsername(ctx, regularUser.UserName)
 	Expect(err).ToNot(HaveOccurred())
 	regularUser.Libraries = loadedOther.Libraries
 
@@ -282,14 +282,14 @@ var _ = BeforeSuite(func() {
 	ds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
 
 	comeTogetherID := findMediaFileByTitle("Come Together")
-	Expect(ds.MediaFile(ctx).SetStar(true, comeTogetherID)).To(Succeed())
-	Expect(ds.MediaFile(ctx).SetStar(true, findMediaFileByTitle("So What"))).To(Succeed())
-	Expect(ds.MediaFile(ctx).SetRating(3, findMediaFileByTitle("Stairway To Heaven"))).To(Succeed())
-	Expect(ds.MediaFile(ctx).SetRating(5, findMediaFileByTitle("Bohemian Rhapsody"))).To(Succeed())
+	Expect(ds.MediaFile().SetStar(ctx, true, comeTogetherID)).To(Succeed())
+	Expect(ds.MediaFile().SetStar(ctx, true, findMediaFileByTitle("So What"))).To(Succeed())
+	Expect(ds.MediaFile().SetRating(ctx, 3, findMediaFileByTitle("Stairway To Heaven"))).To(Succeed())
+	Expect(ds.MediaFile().SetRating(ctx, 5, findMediaFileByTitle("Bohemian Rhapsody"))).To(Succeed())
 	for range 10 {
-		Expect(ds.MediaFile(ctx).IncPlayCount(comeTogetherID, time.Now())).To(Succeed())
+		Expect(ds.MediaFile().IncPlayCount(ctx, comeTogetherID, time.Now())).To(Succeed())
 	}
-	Expect(ds.MediaFile(ctx).IncPlayCount(findMediaFileByTitle("Black Dog"), time.Now())).To(Succeed())
+	Expect(ds.MediaFile().IncPlayCount(ctx, findMediaFileByTitle("Black Dog"), time.Now())).To(Succeed())
 
 	rows, err := db.Db().Query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '%_fts' AND name NOT LIKE '%_fts_%'")
 	Expect(err).ToNot(HaveOccurred())
diff --git a/persistence/e2e/smartplaylist_test.go b/persistence/e2e/smartplaylist_test.go
index b96605d09..51442c822 100644
--- a/persistence/e2e/smartplaylist_test.go
+++ b/persistence/e2e/smartplaylist_test.go
@@ -317,12 +317,12 @@ var _ = Describe("Smart Playlists", func() {
 			smartBID := createPrivateSmartPlaylist(adminUser, `{"all":[{"is":{"genre":"Jazz"}}]}`)
 			smartAID := createPublicSmartPlaylist(regularUser, `{"all":[{"inPlaylist":{"id":"`+smartBID+`"}}]}`)
 
-			loadedA, err := ds.Playlist(ctx).GetWithTracks(smartAID, true, false)
+			loadedA, err := ds.Playlist().GetWithTracks(ctx, smartAID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(loadedA.Tracks).To(BeEmpty())
 			Expect(loadedA.EvaluatedAt).To(BeNil())
 
-			loadedB, err := ds.Playlist(ctx).Get(smartBID)
+			loadedB, err := ds.Playlist().Get(ctx, smartBID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(loadedB.EvaluatedAt).To(BeNil())
 		})
diff --git a/persistence/folder_repository.go b/persistence/folder_repository.go
index a1136ad8d..b4f7c9069 100644
--- a/persistence/folder_repository.go
+++ b/persistence/folder_repository.go
@@ -64,55 +64,54 @@ func (fs dbFolders) toModels() []model.Folder {
 	return slice.Map(fs, func(f dbFolder) model.Folder { return *f.Folder })
 }
 
-func newFolderRepository(ctx context.Context, db dbx.Builder) model.FolderRepository {
+func newFolderRepository(db dbx.Builder) model.FolderRepository {
 	r := &folderRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "folder"
 	return r
 }
 
-func (r folderRepository) selectFolder(options ...model.QueryOptions) SelectBuilder {
-	sql := r.newSelect(options...).Columns("folder.*", "library.path as library_path").
+func (r folderRepository) selectFolder(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	sql := r.newSelect(ctx, options...).Columns("folder.*", "library.path as library_path").
 		Join("library on library.id = folder.library_id")
-	return r.applyLibraryFilter(sql)
+	return r.applyLibraryFilter(ctx, sql)
 }
 
-func (r folderRepository) Get(id string) (*model.Folder, error) {
-	sq := r.selectFolder().Where(Eq{"folder.id": id})
+func (r folderRepository) Get(ctx context.Context, id string) (*model.Folder, error) {
+	sq := r.selectFolder(ctx).Where(Eq{"folder.id": id})
 	var res dbFolder
-	err := r.queryOne(sq, &res)
+	err := r.queryOne(ctx, sq, &res)
 	return res.Folder, err
 }
 
-func (r folderRepository) GetByPath(lib model.Library, path string) (*model.Folder, error) {
+func (r folderRepository) GetByPath(ctx context.Context, lib model.Library, path string) (*model.Folder, error) {
 	id := model.NewFolder(lib, path).ID
-	return r.Get(id)
+	return r.Get(ctx, id)
 }
 
-func (r folderRepository) GetAll(opt ...model.QueryOptions) ([]model.Folder, error) {
-	sq := r.selectFolder(opt...)
+func (r folderRepository) GetAll(ctx context.Context, opt ...model.QueryOptions) ([]model.Folder, error) {
+	sq := r.selectFolder(ctx, opt...)
 	var res dbFolders
-	err := r.queryAll(sq, &res)
+	err := r.queryAll(ctx, sq, &res)
 	return res.toModels(), err
 }
 
-func (r folderRepository) CountAll(opt ...model.QueryOptions) (int64, error) {
-	query := r.newSelect(opt...).Columns("count(*)")
-	query = r.applyLibraryFilter(query)
-	return r.count(query)
+func (r folderRepository) CountAll(ctx context.Context, opt ...model.QueryOptions) (int64, error) {
+	query := r.newSelect(ctx, opt...).Columns("count(*)")
+	query = r.applyLibraryFilter(ctx, query)
+	return r.count(ctx, query)
 }
 
-func (r folderRepository) GetFolderUpdateInfo(lib model.Library, targetPaths ...string) (map[string]model.FolderUpdateInfo, error) {
+func (r folderRepository) GetFolderUpdateInfo(ctx context.Context, lib model.Library, targetPaths ...string) (map[string]model.FolderUpdateInfo, error) {
 	// If no specific paths, return all folders in the library
 	if len(targetPaths) == 0 {
-		return r.getFolderUpdateInfoAll(lib)
+		return r.getFolderUpdateInfoAll(ctx, lib)
 	}
 
 	// Check if any path is root (return all folders)
 	for _, targetPath := range targetPaths {
 		if targetPath == "" || targetPath == "." {
-			return r.getFolderUpdateInfoAll(lib)
+			return r.getFolderUpdateInfoAll(ctx, lib)
 		}
 	}
 
@@ -122,7 +121,7 @@ func (r folderRepository) GetFolderUpdateInfo(lib model.Library, targetPaths ...
 	result := make(map[string]model.FolderUpdateInfo)
 
 	for batch := range slices.Chunk(targetPaths, batchSize) {
-		batchResult, err := r.getFolderUpdateInfoBatch(lib, batch)
+		batchResult, err := r.getFolderUpdateInfoBatch(ctx, lib, batch)
 		if err != nil {
 			return nil, err
 		}
@@ -133,16 +132,16 @@ func (r folderRepository) GetFolderUpdateInfo(lib model.Library, targetPaths ...
 }
 
 // getFolderUpdateInfoAll returns update info for all non-missing folders in the library
-func (r folderRepository) getFolderUpdateInfoAll(lib model.Library) (map[string]model.FolderUpdateInfo, error) {
+func (r folderRepository) getFolderUpdateInfoAll(ctx context.Context, lib model.Library) (map[string]model.FolderUpdateInfo, error) {
 	where := And{
 		Eq{"library_id": lib.ID},
 		Eq{"missing": false},
 	}
-	return r.queryFolderUpdateInfo(where)
+	return r.queryFolderUpdateInfo(ctx, where)
 }
 
 // getFolderUpdateInfoBatch returns update info for a batch of target paths and their descendants
-func (r folderRepository) getFolderUpdateInfoBatch(lib model.Library, targetPaths []string) (map[string]model.FolderUpdateInfo, error) {
+func (r folderRepository) getFolderUpdateInfoBatch(ctx context.Context, lib model.Library, targetPaths []string) (map[string]model.FolderUpdateInfo, error) {
 	where := And{
 		Eq{"library_id": lib.ID},
 		Eq{"missing": false},
@@ -172,12 +171,12 @@ func (r folderRepository) getFolderUpdateInfoBatch(lib model.Library, targetPath
 		where = append(where, pathConditions)
 	}
 
-	return r.queryFolderUpdateInfo(where)
+	return r.queryFolderUpdateInfo(ctx, where)
 }
 
 // queryFolderUpdateInfo executes the query and returns the result map
-func (r folderRepository) queryFolderUpdateInfo(where And) (map[string]model.FolderUpdateInfo, error) {
-	sq := r.newSelect().Columns("id", "updated_at", "hash", "image_files", "images_updated_at").Where(where)
+func (r folderRepository) queryFolderUpdateInfo(ctx context.Context, where And) (map[string]model.FolderUpdateInfo, error) {
+	sq := r.newSelect(ctx).Columns("id", "updated_at", "hash", "image_files", "images_updated_at").Where(where)
 	var res []struct {
 		ID              string
 		UpdatedAt       time.Time
@@ -185,7 +184,7 @@ func (r folderRepository) queryFolderUpdateInfo(where And) (map[string]model.Fol
 		ImageFiles      string
 		ImagesUpdatedAt time.Time
 	}
-	err := r.queryAll(sq, &res)
+	err := r.queryAll(ctx, sq, &res)
 	if err != nil {
 		return nil, err
 	}
@@ -230,12 +229,12 @@ func folderSubtreeFilter(lib model.Library, paths []string) Sqlizer {
 // (including parent itself) contains audio files and is not one of the given
 // folder IDs. LIKE wildcards in the parent path are escaped, so it is always
 // matched as a literal prefix.
-func (r folderRepository) HasAudioOutsideFolders(parent model.Folder, excludeFolderIDs []string) (bool, error) {
+func (r folderRepository) HasAudioOutsideFolders(ctx context.Context, parent model.Folder, excludeFolderIDs []string) (bool, error) {
 	if parent.NumAudioFiles > 0 {
 		return true, nil
 	}
 	parentPath := strings.TrimPrefix(path.Join(parent.Path, parent.Name), "/")
-	return r.exists(And{
+	return r.exists(ctx, And{
 		Eq{"library_id": parent.LibraryID, "missing": false},
 		Gt{"num_audio_files": 0},
 		NotEq{"id": excludeFolderIDs},
@@ -253,20 +252,20 @@ func escapeLikePrefix(s string) string {
 	return strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(s)
 }
 
-func (r folderRepository) Put(f *model.Folder) error {
+func (r folderRepository) Put(ctx context.Context, f *model.Folder) error {
 	dbf := dbFolder{Folder: f}
-	_, err := r.put(dbf.ID, &dbf)
+	_, err := r.put(ctx, dbf.ID, &dbf)
 	return err
 }
 
-func (r folderRepository) MarkMissing(missing bool, ids ...string) error {
-	log.Debug(r.ctx, "Marking folders as missing", "ids", ids, "missing", missing)
+func (r folderRepository) MarkMissing(ctx context.Context, missing bool, ids ...string) error {
+	log.Debug(ctx, "Marking folders as missing", "ids", ids, "missing", missing)
 	for chunk := range slices.Chunk(ids, 200) {
 		sq := Update(r.tableName).
 			Set("missing", missing).
 			Set("updated_at", time.Now()).
 			Where(Eq{"id": chunk})
-		_, err := r.executeSQL(sq)
+		_, err := r.executeSQL(ctx, sq)
 		if err != nil {
 			return err
 		}
@@ -274,25 +273,25 @@ func (r folderRepository) MarkMissing(missing bool, ids ...string) error {
 	return nil
 }
 
-func (r folderRepository) GetTouchedWithPlaylists() (model.FolderCursor, error) {
-	query := r.selectFolder().Where(And{
+func (r folderRepository) GetTouchedWithPlaylists(ctx context.Context) (model.FolderCursor, error) {
+	query := r.selectFolder(ctx).Where(And{
 		Eq{"missing": false},
 		Gt{"num_playlists": 0},
 		ConcatExpr("folder.updated_at > library.last_scan_at"),
 	})
-	cursor, err := queryWithStableResults[dbFolder](r.sqlRepository, query)
+	cursor, err := queryWithStableResults[dbFolder](ctx, r.sqlRepository, query)
 	if err != nil {
 		return nil, err
 	}
 	return wrapFolderCursor(cursor), nil
 }
 
-func (r folderRepository) GetAllWithPlaylists() (model.FolderCursor, error) {
-	query := r.selectFolder().Where(And{
+func (r folderRepository) GetAllWithPlaylists(ctx context.Context) (model.FolderCursor, error) {
+	query := r.selectFolder(ctx).Where(And{
 		Eq{"missing": false},
 		Gt{"num_playlists": 0},
 	})
-	cursor, err := queryWithStableResults[dbFolder](r.sqlRepository, query)
+	cursor, err := queryWithStableResults[dbFolder](ctx, r.sqlRepository, query)
 	if err != nil {
 		return nil, err
 	}
@@ -303,7 +302,7 @@ func wrapFolderCursor(cursor iter.Seq2[dbFolder, error]) model.FolderCursor {
 	return model.FolderCursor(wrapCursor(cursor, func(f dbFolder) *model.Folder { return f.Folder }))
 }
 
-func (r folderRepository) purgeEmpty(libraryIDs ...int) error {
+func (r folderRepository) purgeEmpty(ctx context.Context, libraryIDs ...int) error {
 	sq := Delete(r.tableName).Where(And{
 		Eq{"num_audio_files": 0},
 		Eq{"num_playlists": 0},
@@ -315,12 +314,12 @@ func (r folderRepository) purgeEmpty(libraryIDs ...int) error {
 	if len(libraryIDs) > 0 {
 		sq = sq.Where(Eq{"library_id": libraryIDs})
 	}
-	c, err := r.executeSQL(sq)
+	c, err := r.executeSQL(ctx, sq)
 	if err != nil {
 		return fmt.Errorf("purging empty folders: %w", err)
 	}
 	if c > 0 {
-		log.Debug(r.ctx, "Purging empty folders", "totalDeleted", c)
+		log.Debug(ctx, "Purging empty folders", "totalDeleted", c)
 	}
 	return nil
 }
diff --git a/persistence/folder_repository_test.go b/persistence/folder_repository_test.go
index b7bc52751..4b1c54a3d 100644
--- a/persistence/folder_repository_test.go
+++ b/persistence/folder_repository_test.go
@@ -23,17 +23,17 @@ var _ = Describe("FolderRepository", func() {
 	BeforeEach(func() {
 		ctx = request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid"})
 		conn = GetDBXBuilder()
-		repo = newFolderRepository(ctx, conn)
+		repo = newFolderRepository(conn)
 
 		// Use existing library ID 1 from test fixtures
-		libRepo := NewLibraryRepository(ctx, conn)
-		lib, err := libRepo.Get(1)
+		libRepo := NewLibraryRepository(conn)
+		lib, err := libRepo.Get(ctx, 1)
 		Expect(err).ToNot(HaveOccurred())
 		testLib = *lib
 
 		// Create a second library with its own folder to verify isolation
 		otherLib = model.Library{Name: "Other Library", Path: "/other/path"}
-		Expect(libRepo.Put(&otherLib)).To(Succeed())
+		Expect(libRepo.Put(ctx, &otherLib)).To(Succeed())
 	})
 
 	AfterEach(func() {
@@ -48,7 +48,7 @@ var _ = Describe("FolderRepository", func() {
 
 		matching := func(paths ...string) []string {
 			GinkgoHelper()
-			folders, err := repo.GetAll(model.QueryOptions{Filters: folderSubtreeFilter(testLib, paths)})
+			folders, err := repo.GetAll(ctx, model.QueryOptions{Filters: folderSubtreeFilter(testLib, paths)})
 			Expect(err).ToNot(HaveOccurred())
 			return slice.Map(folders, func(f model.Folder) string { return f.ID })
 		}
@@ -59,7 +59,7 @@ var _ = Describe("FolderRepository", func() {
 			grandchild = model.NewFolder(testLib, "TestSubtree/Child/Grandchild")
 			other = model.NewFolder(testLib, "TestSubtreeOther")
 			for _, f := range []*model.Folder{parent, child, grandchild, other} {
-				Expect(repo.Put(f)).To(Succeed())
+				Expect(repo.Put(ctx, f)).To(Succeed())
 			}
 			DeferCleanup(func() {
 				_, _ = conn.NewQuery("DELETE FROM folder WHERE name LIKE 'TestSubtree%' OR path LIKE 'TestSubtree%'").Execute()
@@ -86,17 +86,17 @@ var _ = Describe("FolderRepository", func() {
 				folder1 := model.NewFolder(testLib, "TestGetLastUpdates/Folder1")
 				folder2 := model.NewFolder(testLib, "TestGetLastUpdates/Folder2")
 
-				err := repo.Put(folder1)
+				err := repo.Put(ctx, folder1)
 				Expect(err).ToNot(HaveOccurred())
-				err = repo.Put(folder2)
+				err = repo.Put(ctx, folder2)
 				Expect(err).ToNot(HaveOccurred())
 
 				otherFolder := model.NewFolder(otherLib, "TestOtherLib/Folder")
-				err = repo.Put(otherFolder)
+				err = repo.Put(ctx, otherFolder)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Query all folders (no target paths) - should only return folders from testLib
-				results, err := repo.GetFolderUpdateInfo(testLib)
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib)
 				Expect(err).ToNot(HaveOccurred())
 				// Should include folders from testLib
 				Expect(results).To(HaveKey(folder1.ID))
@@ -113,15 +113,15 @@ var _ = Describe("FolderRepository", func() {
 				folder2 := model.NewFolder(testLib, "TestSpecific/Jazz")
 				folder3 := model.NewFolder(testLib, "TestSpecific/Classical")
 
-				err := repo.Put(folder1)
+				err := repo.Put(ctx, folder1)
 				Expect(err).ToNot(HaveOccurred())
-				err = repo.Put(folder2)
+				err = repo.Put(ctx, folder2)
 				Expect(err).ToNot(HaveOccurred())
-				err = repo.Put(folder3)
+				err = repo.Put(ctx, folder3)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Query specific paths
-				results, err := repo.GetFolderUpdateInfo(testLib, "TestSpecific/Rock", "TestSpecific/Classical")
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib, "TestSpecific/Rock", "TestSpecific/Classical")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(2))
 
@@ -142,12 +142,12 @@ var _ = Describe("FolderRepository", func() {
 				child2 := model.NewFolder(testLib, "TestParent/Music/Jazz")
 				otherParent := model.NewFolder(testLib, "TestParent2/Music/Jazz")
 
-				Expect(repo.Put(parent)).To(Succeed())
-				Expect(repo.Put(child1)).To(Succeed())
-				Expect(repo.Put(child2)).To(Succeed())
+				Expect(repo.Put(ctx, parent)).To(Succeed())
+				Expect(repo.Put(ctx, child1)).To(Succeed())
+				Expect(repo.Put(ctx, child2)).To(Succeed())
 
 				// Query the parent folder - should return parent and all children
-				results, err := repo.GetFolderUpdateInfo(testLib, "TestParent/Music")
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib, "TestParent/Music")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(3))
 				Expect(results).To(HaveKey(parent.ID))
@@ -161,18 +161,18 @@ var _ = Describe("FolderRepository", func() {
 				parent := model.NewFolder(testLib, "TestIsolation/Parent")
 				child := model.NewFolder(testLib, "TestIsolation/Parent/Child")
 
-				Expect(repo.Put(parent)).To(Succeed())
-				Expect(repo.Put(child)).To(Succeed())
+				Expect(repo.Put(ctx, parent)).To(Succeed())
+				Expect(repo.Put(ctx, child)).To(Succeed())
 
 				// Create similar path in other library
 				otherParent := model.NewFolder(otherLib, "TestIsolation/Parent")
 				otherChild := model.NewFolder(otherLib, "TestIsolation/Parent/Child")
 
-				Expect(repo.Put(otherParent)).To(Succeed())
-				Expect(repo.Put(otherChild)).To(Succeed())
+				Expect(repo.Put(ctx, otherParent)).To(Succeed())
+				Expect(repo.Put(ctx, otherChild)).To(Succeed())
 
 				// Query should only return folders from testLib
-				results, err := repo.GetFolderUpdateInfo(testLib, "TestIsolation/Parent")
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib, "TestIsolation/Parent")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(2))
 				Expect(results).To(HaveKey(parent.ID))
@@ -188,12 +188,12 @@ var _ = Describe("FolderRepository", func() {
 				child2 := model.NewFolder(testLib, "TestMissingChild/Parent/Child2")
 				child2.Missing = true
 
-				Expect(repo.Put(parent)).To(Succeed())
-				Expect(repo.Put(child1)).To(Succeed())
-				Expect(repo.Put(child2)).To(Succeed())
+				Expect(repo.Put(ctx, parent)).To(Succeed())
+				Expect(repo.Put(ctx, child1)).To(Succeed())
+				Expect(repo.Put(ctx, child2)).To(Succeed())
 
 				// Query parent - should only return parent and non-missing child
-				results, err := repo.GetFolderUpdateInfo(testLib, "TestMissingChild/Parent")
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib, "TestMissingChild/Parent")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(2))
 				Expect(results).To(HaveKey(parent.ID))
@@ -206,11 +206,11 @@ var _ = Describe("FolderRepository", func() {
 				existingParent := model.NewFolder(testLib, "TestMixed/Exists")
 				existingChild := model.NewFolder(testLib, "TestMixed/Exists/Child")
 
-				Expect(repo.Put(existingParent)).To(Succeed())
-				Expect(repo.Put(existingChild)).To(Succeed())
+				Expect(repo.Put(ctx, existingParent)).To(Succeed())
+				Expect(repo.Put(ctx, existingChild)).To(Succeed())
 
 				// Query both existing and non-existing paths
-				results, err := repo.GetFolderUpdateInfo(testLib, "TestMixed/Exists", "TestMixed/DoesNotExist")
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib, "TestMixed/Exists", "TestMixed/DoesNotExist")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(2))
 				Expect(results).To(HaveKey(existingParent.ID))
@@ -221,7 +221,7 @@ var _ = Describe("FolderRepository", func() {
 				// Test querying for root folder without creating it (fixtures should have one)
 				rootFolderID := model.FolderID(testLib, ".")
 
-				results, err := repo.GetFolderUpdateInfo(testLib, "")
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib, "")
 				Expect(err).ToNot(HaveOccurred())
 				// Should return the root folder if it exists
 				if len(results) > 0 {
@@ -230,7 +230,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("returns empty map for non-existent folders", func() {
-				results, err := repo.GetFolderUpdateInfo(testLib, "NonExistent/Path")
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib, "NonExistent/Path")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 			})
@@ -239,10 +239,10 @@ var _ = Describe("FolderRepository", func() {
 				// Create a folder and mark it as missing
 				folder := model.NewFolder(testLib, "TestMissing/Folder")
 				folder.Missing = true
-				err := repo.Put(folder)
+				err := repo.Put(ctx, folder)
 				Expect(err).ToNot(HaveOccurred())
 
-				results, err := repo.GetFolderUpdateInfo(testLib, "TestMissing/Folder")
+				results, err := repo.GetFolderUpdateInfo(ctx, testLib, "TestMissing/Folder")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 			})
@@ -262,51 +262,51 @@ var _ = Describe("FolderRepository", func() {
 			disc2 = model.NewFolder(testLib, "TestHasAudio/Album/CD2")
 			disc2.NumAudioFiles = 5
 			for _, f := range []*model.Folder{albumRoot, disc1, disc2} {
-				Expect(repo.Put(f)).To(Succeed())
+				Expect(repo.Put(ctx, f)).To(Succeed())
 			}
 		})
 
 		It("returns false when all audio under the parent belongs to the given folders", func() {
-			Expect(repo.HasAudioOutsideFolders(*albumRoot, []string{disc1.ID, disc2.ID})).To(BeFalse())
+			Expect(repo.HasAudioOutsideFolders(ctx, *albumRoot, []string{disc1.ID, disc2.ID})).To(BeFalse())
 		})
 
 		It("returns true when another folder under the parent has audio", func() {
 			bonus := model.NewFolder(testLib, "TestHasAudio/Album/Bonus")
 			bonus.NumAudioFiles = 1
-			Expect(repo.Put(bonus)).To(Succeed())
+			Expect(repo.Put(ctx, bonus)).To(Succeed())
 
-			Expect(repo.HasAudioOutsideFolders(*albumRoot, []string{disc1.ID, disc2.ID})).To(BeTrue())
+			Expect(repo.HasAudioOutsideFolders(ctx, *albumRoot, []string{disc1.ID, disc2.ID})).To(BeTrue())
 		})
 
 		It("returns true when the parent itself contains audio files", func() {
 			albumRoot.NumAudioFiles = 2
 
-			Expect(repo.HasAudioOutsideFolders(*albumRoot, []string{disc1.ID, disc2.ID})).To(BeTrue())
+			Expect(repo.HasAudioOutsideFolders(ctx, *albumRoot, []string{disc1.ID, disc2.ID})).To(BeTrue())
 		})
 
 		It("ignores audio outside the parent's subtree", func() {
 			other := model.NewFolder(testLib, "TestHasAudio/Other Album")
 			other.NumAudioFiles = 10
-			Expect(repo.Put(other)).To(Succeed())
+			Expect(repo.Put(ctx, other)).To(Succeed())
 
-			Expect(repo.HasAudioOutsideFolders(*albumRoot, []string{disc1.ID, disc2.ID})).To(BeFalse())
+			Expect(repo.HasAudioOutsideFolders(ctx, *albumRoot, []string{disc1.ID, disc2.ID})).To(BeFalse())
 		})
 
 		It("ignores missing folders", func() {
 			gone := model.NewFolder(testLib, "TestHasAudio/Album/Gone")
 			gone.NumAudioFiles = 3
 			gone.Missing = true
-			Expect(repo.Put(gone)).To(Succeed())
+			Expect(repo.Put(ctx, gone)).To(Succeed())
 
-			Expect(repo.HasAudioOutsideFolders(*albumRoot, []string{disc1.ID, disc2.ID})).To(BeFalse())
+			Expect(repo.HasAudioOutsideFolders(ctx, *albumRoot, []string{disc1.ID, disc2.ID})).To(BeFalse())
 		})
 
 		It("does not treat LIKE wildcards in the parent path as patterns", func() {
 			// "TestHas_udio" would LIKE-match "TestHasAudio" if "_" were not escaped
 			wildcardRoot := model.NewFolder(testLib, "TestHas_udio/Album")
-			Expect(repo.Put(wildcardRoot)).To(Succeed())
+			Expect(repo.Put(ctx, wildcardRoot)).To(Succeed())
 
-			Expect(repo.HasAudioOutsideFolders(*wildcardRoot, []string{"none"})).To(BeFalse())
+			Expect(repo.HasAudioOutsideFolders(ctx, *wildcardRoot, []string{"none"})).To(BeFalse())
 		})
 	})
 
@@ -367,9 +367,9 @@ var _ = Describe("FolderRepository", func() {
 			missingWithPls.NumPlaylists = 1
 			missingWithPls.Missing = true
 
-			Expect(repo.Put(withPls)).To(Succeed())
-			Expect(repo.Put(noPls)).To(Succeed())
-			Expect(repo.Put(missingWithPls)).To(Succeed())
+			Expect(repo.Put(ctx, withPls)).To(Succeed())
+			Expect(repo.Put(ctx, noPls)).To(Succeed())
+			Expect(repo.Put(ctx, missingWithPls)).To(Succeed())
 
 			// Force the folder's updated_at to the past so GetTouchedWithPlaylists
 			// (which gates on updated_at > last_scan_at) would NOT return it.
@@ -378,7 +378,7 @@ var _ = Describe("FolderRepository", func() {
 			Expect(err).ToNot(HaveOccurred())
 
 			var ids []string
-			cursor, err := repo.GetAllWithPlaylists()
+			cursor, err := repo.GetAllWithPlaylists(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			for f, err := range cursor {
 				Expect(err).ToNot(HaveOccurred())
diff --git a/persistence/genre_repository.go b/persistence/genre_repository.go
index 0bb22c21b..d88cb8672 100644
--- a/persistence/genre_repository.go
+++ b/persistence/genre_repository.go
@@ -13,43 +13,39 @@ type genreRepository struct {
 	*baseTagRepository
 }
 
-func NewGenreRepository(ctx context.Context, db dbx.Builder) model.GenreRepository {
+func NewGenreRepository(db dbx.Builder) model.GenreRepository {
 	return &genreRepository{
-		baseTagRepository: newBaseTagRepository(ctx, db, new(model.TagGenre)),
+		baseTagRepository: newBaseTagRepository(db, new(model.TagGenre)),
 	}
 }
 
-func (r *genreRepository) selectGenre(opt ...model.QueryOptions) SelectBuilder {
-	return r.newSelect(opt...).Columns("tag.tag_value as name")
+func (r *genreRepository) selectGenre(ctx context.Context, opt ...model.QueryOptions) SelectBuilder {
+	return r.newSelect(ctx, opt...).Columns("tag.tag_value as name")
 }
 
-func (r *genreRepository) GetAll(opt ...model.QueryOptions) (model.Genres, error) {
-	sq := r.selectGenre(opt...)
+func (r *genreRepository) GetAll(ctx context.Context, opt ...model.QueryOptions) (model.Genres, error) {
+	sq := r.selectGenre(ctx, opt...)
 	res := model.Genres{}
-	err := r.queryAll(sq, &res)
+	err := r.queryAll(ctx, sq, &res)
 	return res, err
 }
 
-func (r *genreRepository) Get(id string) (*model.Genre, error) {
-	sel := r.selectGenre().Where(Eq{"tag.id": id})
+func (r *genreRepository) Get(ctx context.Context, id string) (*model.Genre, error) {
+	sel := r.selectGenre(ctx).Where(Eq{"tag.id": id})
 	var res model.Genre
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-// Override ResourceRepository methods to return Genre objects instead of Tag objects
+// Override the base tag REST methods to return Genre objects instead of Tag objects
 
-func (r *genreRepository) Read(id string) (any, error) {
-	return r.Get(id)
+func (r *genreRepository) Read(ctx context.Context, id string) (*model.Genre, error) {
+	return r.Get(ctx, id)
 }
 
-func (r *genreRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
-}
-
-func (r *genreRepository) NewInstance() any {
-	return &model.Genre{}
+func (r *genreRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Genre, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
 var _ model.GenreRepository = (*genreRepository)(nil)
-var _ model.ResourceRepository = (*genreRepository)(nil)
+var _ rest.Repository[model.Genre] = (*genreRepository)(nil)
diff --git a/persistence/genre_repository_test.go b/persistence/genre_repository_test.go
index e3779725c..52bebf446 100644
--- a/persistence/genre_repository_test.go
+++ b/persistence/genre_repository_test.go
@@ -16,16 +16,16 @@ import (
 
 var _ = Describe("GenreRepository", func() {
 	var repo model.GenreRepository
-	var restRepo model.ResourceRepository
+	var restRepo rest.Repository[model.Genre]
 	var tagRepo model.TagRepository
 	var ctx context.Context
 
 	BeforeEach(func() {
 		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "userid", UserName: "johndoe", IsAdmin: true})
-		genreRepo := NewGenreRepository(ctx, GetDBXBuilder())
+		genreRepo := NewGenreRepository(GetDBXBuilder())
 		repo = genreRepo
-		restRepo = genreRepo.(model.ResourceRepository)
-		tagRepo = NewTagRepository(ctx, GetDBXBuilder())
+		restRepo = genreRepo
+		tagRepo = NewTagRepository(GetDBXBuilder())
 
 		// Clear any existing tags to ensure test isolation
 		db := GetDBXBuilder()
@@ -43,7 +43,7 @@ var _ = Describe("GenreRepository", func() {
 			return model.Tag{ID: id.NewTagID(name, value), TagName: model.TagName(name), TagValue: value}
 		}
 
-		err = tagRepo.Add(1,
+		err = tagRepo.Add(ctx, 1,
 			newTag("genre", "rock"),
 			newTag("genre", "pop"),
 			newTag("genre", "jazz"),
@@ -65,7 +65,7 @@ var _ = Describe("GenreRepository", func() {
 
 	Describe("GetAll", func() {
 		It("should return all genres", func() {
-			genres, err := repo.GetAll()
+			genres, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(genres).To(HaveLen(12))
 
@@ -83,7 +83,7 @@ var _ = Describe("GenreRepository", func() {
 
 		It("should support query options", func() {
 			// Test with limiting results
-			genres, err := repo.GetAll(model.QueryOptions{Max: 1})
+			genres, err := repo.GetAll(ctx, model.QueryOptions{Max: 1})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(genres).To(HaveLen(1))
 		})
@@ -93,7 +93,7 @@ var _ = Describe("GenreRepository", func() {
 			_, err := GetDBXBuilder().NewQuery("DELETE FROM tag WHERE tag_name = 'genre'").Execute()
 			Expect(err).ToNot(HaveOccurred())
 
-			genres, err := repo.GetAll()
+			genres, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(genres).To(BeEmpty())
 		})
@@ -103,7 +103,7 @@ var _ = Describe("GenreRepository", func() {
 				options := model.QueryOptions{
 					Filters: squirrel.Like{"tag_value": "%rock%"}, // Direct field access
 				}
-				genres, err := repo.GetAll(options)
+				genres, err := repo.GetAll(ctx, options)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(genres).To(HaveLen(2)) // Should match "rock" and "Alternative Rock"
 
@@ -119,7 +119,7 @@ var _ = Describe("GenreRepository", func() {
 					Filters: squirrel.Like{"tag_value": "%e%"}, // Should match genres containing "e"
 					Sort:    "name",
 				}
-				genres, err := repo.GetAll(options)
+				genres, err := repo.GetAll(ctx, options)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(genres).To(HaveLen(7))
 
@@ -135,7 +135,7 @@ var _ = Describe("GenreRepository", func() {
 					Sort:    "name",
 					Order:   "desc",
 				}
-				genres, err := repo.GetAll(options)
+				genres, err := repo.GetAll(ctx, options)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(genres).To(HaveLen(7))
 
@@ -148,7 +148,7 @@ var _ = Describe("GenreRepository", func() {
 
 	Describe("Count", func() {
 		It("should return correct count of genres", func() {
-			count, err := restRepo.Count()
+			count, err := restRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(int64(12))) // We have 12 genre tags
 		})
@@ -158,7 +158,7 @@ var _ = Describe("GenreRepository", func() {
 			_, err := GetDBXBuilder().NewQuery("DELETE FROM tag WHERE tag_name = 'genre'").Execute()
 			Expect(err).ToNot(HaveOccurred())
 
-			count, err := restRepo.Count()
+			count, err := restRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(BeZero())
 		})
@@ -170,10 +170,10 @@ var _ = Describe("GenreRepository", func() {
 				TagName:  "mood",
 				TagValue: "energetic",
 			}
-			err := tagRepo.Add(1, nonGenreTag)
+			err := tagRepo.Add(ctx, 1, nonGenreTag)
 			Expect(err).ToNot(HaveOccurred())
 
-			count, err := restRepo.Count()
+			count, err := restRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			// Count should not include the mood tag
 			Expect(count).To(Equal(int64(12))) // Should still be 12 genre tags
@@ -184,7 +184,7 @@ var _ = Describe("GenreRepository", func() {
 			options := rest.QueryOptions{
 				Filters: map[string]any{"name": "%rock%"},
 			}
-			count, err := restRepo.Count(options)
+			count, err := restRepo.Count(ctx, options)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(BeNumerically("==", 2))
 		})
@@ -194,30 +194,28 @@ var _ = Describe("GenreRepository", func() {
 		It("should return existing genre", func() {
 			// Use one of the existing genres from our consolidated dataset
 			genreID := id.NewTagID("genre", "rock")
-			result, err := restRepo.Read(genreID)
+			genre, err := restRepo.Read(ctx, genreID)
 			Expect(err).ToNot(HaveOccurred())
-			genre := result.(*model.Genre)
 			Expect(genre.ID).To(Equal(genreID))
 			Expect(genre.Name).To(Equal("rock"))
 		})
 
 		It("should return error for non-existent genre", func() {
-			_, err := restRepo.Read("non-existent-id")
+			_, err := restRepo.Read(ctx, "non-existent-id")
 			Expect(err).To(HaveOccurred())
 		})
 
 		It("should not return non-genre tags", func() {
 			moodID := id.NewTagID("mood", "happy") // This exists as a mood tag, not genre
-			_, err := restRepo.Read(moodID)
+			_, err := restRepo.Read(ctx, moodID)
 			Expect(err).To(HaveOccurred()) // Should not find it as a genre
 		})
 	})
 
 	Describe("ReadAll", func() {
 		It("should return all genres through ReadAll", func() {
-			result, err := restRepo.ReadAll()
+			genres, err := restRepo.ReadAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
-			genres := result.(model.Genres)
 			Expect(genres).To(HaveLen(12)) // We have 12 genre tags
 
 			genreNames := make([]string, len(genres))
@@ -231,7 +229,7 @@ var _ = Describe("GenreRepository", func() {
 		})
 
 		It("should support rest query options", func() {
-			result, err := restRepo.ReadAll()
+			result, err := restRepo.ReadAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(result).ToNot(BeNil())
 		})
@@ -240,13 +238,15 @@ var _ = Describe("GenreRepository", func() {
 	Describe("Library Filtering", func() {
 		Context("Headless Processes (No User Context)", func() {
 			var headlessRepo model.GenreRepository
-			var headlessRestRepo model.ResourceRepository
+			var headlessRestRepo rest.Repository[model.Genre]
+			var headlessCtx context.Context
 
 			BeforeEach(func() {
+				headlessCtx = GinkgoT().Context()
 				// Create a repository with no user context (headless)
-				headlessGenreRepo := NewGenreRepository(context.Background(), GetDBXBuilder())
+				headlessGenreRepo := NewGenreRepository(GetDBXBuilder())
 				headlessRepo = headlessGenreRepo
-				headlessRestRepo = headlessGenreRepo.(model.ResourceRepository)
+				headlessRestRepo = headlessGenreRepo
 
 				// Add genres to different libraries
 				db := GetDBXBuilder()
@@ -258,13 +258,13 @@ var _ = Describe("GenreRepository", func() {
 					return model.Tag{ID: id.NewTagID(name, value), TagName: model.TagName(name), TagValue: value}
 				}
 
-				err = tagRepo.Add(2, newTag("genre", "jazz"))
+				err = tagRepo.Add(ctx, 2, newTag("genre", "jazz"))
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("should see all genres from all libraries when no user is in context", func() {
 				// Headless processes should see all genres regardless of library
-				genres, err := headlessRepo.GetAll()
+				genres, err := headlessRepo.GetAll(headlessCtx)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Should see genres from all libraries
@@ -279,7 +279,7 @@ var _ = Describe("GenreRepository", func() {
 			})
 
 			It("should count all genres from all libraries when no user is in context", func() {
-				count, err := headlessRestRepo.Count()
+				count, err := headlessRestRepo.Count(headlessCtx)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Should count all genres from all libraries
@@ -288,12 +288,11 @@ var _ = Describe("GenreRepository", func() {
 
 			It("should allow headless processes to apply explicit library_id filters", func() {
 				// Filter by specific library
-				genres, err := headlessRestRepo.ReadAll(rest.QueryOptions{
+				genreList, err := headlessRestRepo.ReadAll(headlessCtx, rest.QueryOptions{
 					Filters: map[string]any{"library_id": 2},
 				})
 				Expect(err).ToNot(HaveOccurred())
 
-				genreList := genres.(model.Genres)
 				// Should see only genres from library 2
 				Expect(genreList).To(HaveLen(1))
 				Expect(genreList[0].Name).To(Equal("jazz"))
@@ -301,29 +300,15 @@ var _ = Describe("GenreRepository", func() {
 
 			It("should get individual genres when no user is in context", func() {
 				// Get all genres first to find an ID
-				genres, err := headlessRepo.GetAll()
+				genres, err := headlessRepo.GetAll(headlessCtx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(genres).ToNot(BeEmpty())
 
 				// Headless process should be able to get the genre
-				genre, err := headlessRestRepo.Read(genres[0].ID)
+				genre, err := headlessRestRepo.Read(headlessCtx, genres[0].ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(genre).ToNot(BeNil())
 			})
 		})
 	})
-
-	Describe("EntityName", func() {
-		It("should return correct entity name", func() {
-			name := restRepo.EntityName()
-			Expect(name).To(Equal("tag")) // Genre repository uses tag table
-		})
-	})
-
-	Describe("NewInstance", func() {
-		It("should return new genre instance", func() {
-			instance := restRepo.NewInstance()
-			Expect(instance).To(BeAssignableToTypeOf(&model.Genre{}))
-		})
-	})
 })
diff --git a/persistence/item_tags_test.go b/persistence/item_tags_test.go
index a2317a1a5..1106c7e9c 100644
--- a/persistence/item_tags_test.go
+++ b/persistence/item_tags_test.go
@@ -1,6 +1,8 @@
 package persistence
 
 import (
+	"context"
+
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -14,17 +16,18 @@ var _ = Describe("item genre tag indexes", func() {
 	var mr model.MediaFileRepository
 	var ar model.AlbumRepository
 	var rock, jazz model.Tag
+	var ctx context.Context
 
 	BeforeEach(func() {
-		ctx := request.WithUser(GinkgoT().Context(), model.User{ID: "userid"})
+		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "userid"})
 		conn = GetDBXBuilder()
-		mr = NewMediaFileRepository(ctx, conn)
-		ar = NewAlbumRepository(ctx, conn)
+		mr = NewMediaFileRepository(conn)
+		ar = NewAlbumRepository(conn)
 		// Test-only genre values, so they can't collide with the golden fixtures.
 		rock = model.NewTag(model.TagGenre, "GenreIdxRock")
 		jazz = model.NewTag(model.TagGenre, "GenreIdxJazz")
 		// The join tables FK to tag(id); the scanner adds tags before saving items.
-		Expect(NewTagRepository(ctx, conn).Add(1, rock, jazz)).To(Succeed())
+		Expect(NewTagRepository(conn).Add(ctx, 1, rock, jazz)).To(Succeed())
 		// The suite shares one golden DB with no per-test restore, so undo the rows we add
 		// (media_file/album deletes cascade to the *_tags join rows; tag deletes cascade too).
 		DeferCleanup(func() {
@@ -53,25 +56,25 @@ var _ = Describe("item genre tag indexes", func() {
 		It("writes a media_file_tags row for each genre when the track is saved", func() {
 			mf := model.MediaFile{ID: "mf-g1", LibraryID: 1, Path: "/m/g1.mp3", Title: "G1",
 				Tags: model.Tags{model.TagGenre: []string{rock.TagValue, jazz.TagValue}}}
-			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(mr.Put(ctx, &mf)).To(Succeed())
 			Expect(tagIDsFor("media_file_tags", "media_file_id", "mf-g1")).To(ConsistOf(rock.ID, jazz.ID))
 		})
 
 		It("replaces the rows when the genres change", func() {
 			mf := model.MediaFile{ID: "mf-g2", LibraryID: 1, Path: "/m/g2.mp3", Title: "G2",
 				Tags: model.Tags{model.TagGenre: []string{rock.TagValue}}}
-			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(mr.Put(ctx, &mf)).To(Succeed())
 			mf.Tags = model.Tags{model.TagGenre: []string{jazz.TagValue}}
-			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(mr.Put(ctx, &mf)).To(Succeed())
 			Expect(tagIDsFor("media_file_tags", "media_file_id", "mf-g2")).To(ConsistOf(jazz.ID))
 		})
 
 		It("clears the rows when all genres are removed", func() {
 			mf := model.MediaFile{ID: "mf-g3", LibraryID: 1, Path: "/m/g3.mp3", Title: "G3",
 				Tags: model.Tags{model.TagGenre: []string{rock.TagValue}}}
-			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(mr.Put(ctx, &mf)).To(Succeed())
 			mf.Tags = model.Tags{}
-			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(mr.Put(ctx, &mf)).To(Succeed())
 			Expect(tagIDsFor("media_file_tags", "media_file_id", "mf-g3")).To(BeEmpty())
 		})
 	})
@@ -80,7 +83,7 @@ var _ = Describe("item genre tag indexes", func() {
 		It("writes an album_tags row for each genre when the album is saved", func() {
 			al := model.Album{ID: "al-g1", LibraryID: 1, Name: "AG1",
 				Tags: model.Tags{model.TagGenre: []string{rock.TagValue, jazz.TagValue}}}
-			Expect(ar.Put(&al)).To(Succeed())
+			Expect(ar.Put(ctx, &al)).To(Succeed())
 			Expect(tagIDsFor("album_tags", "album_id", "al-g1")).To(ConsistOf(rock.ID, jazz.ID))
 		})
 	})
@@ -90,19 +93,19 @@ var _ = Describe("item genre tag indexes", func() {
 		It("filters media files by genre_id", func() {
 			mf := model.MediaFile{ID: "mf-nat1", LibraryID: 1, Path: "/m/nat1.mp3", Title: "Nat1",
 				Tags: model.Tags{model.TagGenre: []string{rock.TagValue}}}
-			Expect(mr.Put(&mf)).To(Succeed())
-			res, err := mr.(model.ResourceRepository).ReadAll(rest.QueryOptions{Filters: map[string]any{"genre_id": rock.ID}})
+			Expect(mr.Put(ctx, &mf)).To(Succeed())
+			res, err := mr.ReadAll(ctx, rest.QueryOptions{Filters: map[string]any{"genre_id": rock.ID}})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.(model.MediaFiles)).To(ContainElement(HaveField("ID", "mf-nat1")))
+			Expect(res).To(ContainElement(HaveField("ID", "mf-nat1")))
 		})
 
 		It("filters albums by genre_id", func() {
 			al := model.Album{ID: "al-nat1", LibraryID: 1, Name: "ANat1",
 				Tags: model.Tags{model.TagGenre: []string{rock.TagValue}}}
-			Expect(ar.Put(&al)).To(Succeed())
-			res, err := ar.(model.ResourceRepository).ReadAll(rest.QueryOptions{Filters: map[string]any{"genre_id": rock.ID}})
+			Expect(ar.Put(ctx, &al)).To(Succeed())
+			res, err := ar.ReadAll(ctx, rest.QueryOptions{Filters: map[string]any{"genre_id": rock.ID}})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.(model.Albums)).To(ContainElement(HaveField("ID", "al-nat1")))
+			Expect(res).To(ContainElement(HaveField("ID", "al-nat1")))
 		})
 	})
 })
diff --git a/persistence/library_repository.go b/persistence/library_repository.go
index 2e8feea7a..bf6b8995e 100644
--- a/persistence/library_repository.go
+++ b/persistence/library_repository.go
@@ -25,22 +25,21 @@ var (
 	libLock  sync.RWMutex
 )
 
-func NewLibraryRepository(ctx context.Context, db dbx.Builder) model.LibraryRepository {
+func NewLibraryRepository(db dbx.Builder) model.LibraryRepository {
 	r := &libraryRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.registerModel(&model.Library{}, nil)
 	return r
 }
 
-func (r *libraryRepository) Get(id int) (*model.Library, error) {
-	sq := r.newSelect().Columns("*").Where(Eq{"id": id})
+func (r *libraryRepository) Get(ctx context.Context, id int) (*model.Library, error) {
+	sq := r.newSelect(ctx).Columns("*").Where(Eq{"id": id})
 	var res model.Library
-	err := r.queryOne(sq, &res)
+	err := r.queryOne(ctx, sq, &res)
 	return &res, err
 }
 
-func (r *libraryRepository) GetPath(id int) (string, error) {
+func (r *libraryRepository) GetPath(ctx context.Context, id int) (string, error) {
 	l := func() string {
 		libLock.RLock()
 		defer libLock.RUnlock()
@@ -55,9 +54,9 @@ func (r *libraryRepository) GetPath(id int) (string, error) {
 
 	libLock.Lock()
 	defer libLock.Unlock()
-	libs, err := r.GetAll()
+	libs, err := r.GetAll(ctx)
 	if err != nil {
-		log.Error(r.ctx, "Error loading libraries from DB", err)
+		log.Error(ctx, "Error loading libraries from DB", err)
 		return "", err
 	}
 	for _, l := range libs {
@@ -70,9 +69,9 @@ func (r *libraryRepository) GetPath(id int) (string, error) {
 	}
 }
 
-func (r *libraryRepository) Put(l *model.Library, colsToUpdate ...string) error {
+func (r *libraryRepository) Put(ctx context.Context, l *model.Library, colsToUpdate ...string) error {
 	if l.ID == model.DefaultLibraryID {
-		currentLib, err := r.Get(1)
+		currentLib, err := r.Get(ctx, 1)
 		// if we are creating it, it's ok.
 		if err == nil { // it exists, so we are updating it
 			if currentLib.Path != l.Path {
@@ -97,7 +96,7 @@ func (r *libraryRepository) Put(l *model.Library, colsToUpdate ...string) error
 		}, colsToUpdate...)
 		cols["updated_at"] = l.UpdatedAt
 		sq := Update(r.tableName).SetMap(cols).Where(Eq{"id": l.ID})
-		rowsAffected, updateErr := r.executeSQL(sq)
+		rowsAffected, updateErr := r.executeSQL(ctx, sq)
 		if updateErr != nil {
 			return updateErr
 		}
@@ -122,7 +121,7 @@ CROSS JOIN library l
 WHERE u.is_admin = true
 ON CONFLICT (user_id, library_id) DO NOTHING;`,
 	)
-	if _, err = r.executeSQL(sql); err != nil {
+	if _, err = r.executeSQL(ctx, sql); err != nil {
 		return fmt.Errorf("failed to assign library to admin users: %w", err)
 	}
 
@@ -134,12 +133,12 @@ ON CONFLICT (user_id, library_id) DO NOTHING;`,
 
 // TODO Remove this method when we have a proper UI to add libraries
 // This is a temporary method to store the music folder path from the config in the DB
-func (r *libraryRepository) StoreMusicFolder() error {
+func (r *libraryRepository) StoreMusicFolder(ctx context.Context) error {
 	sq := Update(r.tableName).Set("path", conf.Server.MusicFolder).
 		Set("updated_at", time.Now()).
 		Where(Eq{"id": model.DefaultLibraryID}).
 		Where(NotEq{"path": conf.Server.MusicFolder})
-	rowsAffected, err := r.executeSQL(sq)
+	rowsAffected, err := r.executeSQL(ctx, sq)
 	if err == nil && rowsAffected > 0 {
 		libLock.Lock()
 		defer libLock.Unlock()
@@ -148,77 +147,77 @@ func (r *libraryRepository) StoreMusicFolder() error {
 	return err
 }
 
-func (r *libraryRepository) AddArtist(id int, artistID string) error {
+func (r *libraryRepository) AddArtist(ctx context.Context, id int, artistID string) error {
 	sq := Insert("library_artist").Columns("library_id", "artist_id").Values(id, artistID).
 		Suffix(`on conflict(library_id, artist_id) do nothing`)
-	_, err := r.executeSQL(sq)
+	_, err := r.executeSQL(ctx, sq)
 	if err != nil {
 		return err
 	}
 	return nil
 }
 
-func (r *libraryRepository) ScanBegin(id int, fullScan bool) error {
+func (r *libraryRepository) ScanBegin(ctx context.Context, id int, fullScan bool) error {
 	sq := Update(r.tableName).
 		Set("last_scan_started_at", time.Now()).
 		Set("full_scan_in_progress", fullScan).
 		Where(Eq{"id": id})
-	_, err := r.executeSQL(sq)
+	_, err := r.executeSQL(ctx, sq)
 	return err
 }
 
-func (r *libraryRepository) ScanEnd(id int) error {
+func (r *libraryRepository) ScanEnd(ctx context.Context, id int) error {
 	sq := Update(r.tableName).
 		Set("last_scan_at", time.Now()).
 		Set("full_scan_in_progress", false).
 		Set("last_scan_started_at", time.Time{}).
 		Where(Eq{"id": id})
-	_, err := r.executeSQL(sq)
+	_, err := r.executeSQL(ctx, sq)
 	return err
 }
 
-func (r *libraryRepository) ScanInProgress() (bool, error) {
-	query := r.newSelect().Where(NotEq{"last_scan_started_at": time.Time{}})
-	count, err := r.count(query)
+func (r *libraryRepository) ScanInProgress(ctx context.Context) (bool, error) {
+	query := r.newSelect(ctx).Where(NotEq{"last_scan_started_at": time.Time{}})
+	count, err := r.count(ctx, query)
 	return count > 0, err
 }
 
-func (r *libraryRepository) RefreshStats(id int) error {
+func (r *libraryRepository) RefreshStats(ctx context.Context, id int) error {
 	var songsRes, albumsRes, artistsRes, foldersRes, filesRes, missingRes struct{ Count int64 }
 	var sizeRes struct{ Sum int64 }
 	var durationRes struct{ Sum float64 }
 
 	err := run.Parallel(
 		func() error {
-			return r.queryOne(Select("count(*) as count").From("media_file").Where(Eq{"library_id": id, "missing": false}), &songsRes)
+			return r.queryOne(ctx, Select("count(*) as count").From("media_file").Where(Eq{"library_id": id, "missing": false}), &songsRes)
 		},
 		func() error {
-			return r.queryOne(Select("count(*) as count").From("album").Where(Eq{"library_id": id, "missing": false}), &albumsRes)
+			return r.queryOne(ctx, Select("count(*) as count").From("album").Where(Eq{"library_id": id, "missing": false}), &albumsRes)
 		},
 		func() error {
-			return r.queryOne(Select("count(*) as count").From("library_artist la").
+			return r.queryOne(ctx, Select("count(*) as count").From("library_artist la").
 				Join("artist a on la.artist_id = a.id").
 				Where(Eq{"la.library_id": id, "a.missing": false}), &artistsRes)
 		},
 		func() error {
-			return r.queryOne(Select("count(*) as count").From("folder").
+			return r.queryOne(ctx, Select("count(*) as count").From("folder").
 				Where(And{
 					Eq{"library_id": id, "missing": false},
 					Gt{"num_audio_files": 0},
 				}), &foldersRes)
 		},
 		func() error {
-			return r.queryOne(Select("ifnull(sum(num_audio_files + num_playlists + json_array_length(image_files)),0) as count").
+			return r.queryOne(ctx, Select("ifnull(sum(num_audio_files + num_playlists + json_array_length(image_files)),0) as count").
 				From("folder").Where(Eq{"library_id": id, "missing": false}), &filesRes)
 		},
 		func() error {
-			return r.queryOne(Select("count(*) as count").From("media_file").Where(Eq{"library_id": id, "missing": true}), &missingRes)
+			return r.queryOne(ctx, Select("count(*) as count").From("media_file").Where(Eq{"library_id": id, "missing": true}), &missingRes)
 		},
 		func() error {
-			return r.queryOne(Select("ifnull(sum(size),0) as sum").From("album").Where(Eq{"library_id": id, "missing": false}), &sizeRes)
+			return r.queryOne(ctx, Select("ifnull(sum(size),0) as sum").From("album").Where(Eq{"library_id": id, "missing": false}), &sizeRes)
 		},
 		func() error {
-			return r.queryOne(Select("ifnull(sum(duration),0) as sum").From("album").Where(Eq{"library_id": id, "missing": false}), &durationRes)
+			return r.queryOne(ctx, Select("ifnull(sum(duration),0) as sum").From("album").Where(Eq{"library_id": id, "missing": false}), &durationRes)
 		},
 	)()
 	if err != nil {
@@ -236,25 +235,25 @@ func (r *libraryRepository) RefreshStats(id int) error {
 		Set("total_duration", durationRes.Sum).
 		Set("updated_at", time.Now()).
 		Where(Eq{"id": id})
-	_, err = r.executeSQL(sq)
+	_, err = r.executeSQL(ctx, sq)
 	return err
 }
 
-func (r *libraryRepository) Delete(id int) error {
-	if !loggedUser(r.ctx).IsAdmin {
+func (r *libraryRepository) Delete(ctx context.Context, id int) error {
+	if !loggedUser(ctx).IsAdmin {
 		return model.ErrNotAuthorized
 	}
 	if id == 1 {
 		return fmt.Errorf("%w: library with ID 1 cannot be deleted", model.ErrValidation)
 	}
 
-	err := r.delete(Eq{"id": id})
+	err := r.delete(ctx, Eq{"id": id})
 	if err != nil {
 		return err
 	}
 
 	// The cascade above can drop an artist's last library_artist row; reconcile any such orphans.
-	if err := NewArtistRepository(r.ctx, r.db).(*artistRepository).markOrphansMissing(); err != nil {
+	if err := NewArtistRepository(r.db).(*artistRepository).markOrphansMissing(ctx); err != nil {
 		return fmt.Errorf("marking orphaned artists missing after deleting library %d: %w", id, err)
 	}
 
@@ -265,26 +264,26 @@ func (r *libraryRepository) Delete(id int) error {
 
 	// Clean up orphaned plugin references for the deleted library
 	if err := cleanupPluginLibraryReferences(r.db, id); err != nil {
-		log.Error(r.ctx, "Failed to cleanup plugin library references", "libraryID", id, err)
+		log.Error(ctx, "Failed to cleanup plugin library references", "libraryID", id, err)
 	}
 	return nil
 }
 
-func (r *libraryRepository) GetAll(ops ...model.QueryOptions) (model.Libraries, error) {
-	sq := r.newSelect(ops...).Columns("*")
+func (r *libraryRepository) GetAll(ctx context.Context, ops ...model.QueryOptions) (model.Libraries, error) {
+	sq := r.newSelect(ctx, ops...).Columns("*")
 	res := model.Libraries{}
-	err := r.queryAll(sq, &res)
+	err := r.queryAll(ctx, sq, &res)
 	return res, err
 }
 
-func (r *libraryRepository) CountAll(ops ...model.QueryOptions) (int64, error) {
-	sq := r.newSelect(ops...)
-	return r.count(sq)
+func (r *libraryRepository) CountAll(ctx context.Context, ops ...model.QueryOptions) (int64, error) {
+	sq := r.newSelect(ctx, ops...)
+	return r.count(ctx, sq)
 }
 
 // User-library association methods
 
-func (r *libraryRepository) GetUsersWithLibraryAccess(libraryID int) (model.Users, error) {
+func (r *libraryRepository) GetUsersWithLibraryAccess(ctx context.Context, libraryID int) (model.Users, error) {
 	sel := Select("u.*").
 		From("user u").
 		Join("user_library ul ON u.id = ul.user_id").
@@ -292,57 +291,28 @@ func (r *libraryRepository) GetUsersWithLibraryAccess(libraryID int) (model.User
 		OrderBy("u.name")
 
 	var res model.Users
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	return res, err
 }
 
 // REST interface methods
 
-func (r *libraryRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *libraryRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *libraryRepository) Read(id string) (any, error) {
+func (r *libraryRepository) Read(ctx context.Context, id string) (*model.Library, error) {
 	idInt, err := strconv.Atoi(id)
 	if err != nil {
-		log.Trace(r.ctx, "invalid library id: %s", id, err)
+		log.Trace(ctx, "invalid library id: %s", id, err)
 		return nil, rest.ErrNotFound
 	}
-	return r.Get(idInt)
+	return r.Get(ctx, idInt)
 }
 
-func (r *libraryRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
-}
-
-func (r *libraryRepository) EntityName() string {
-	return "library"
-}
-
-func (r *libraryRepository) NewInstance() any {
-	return &model.Library{}
-}
-
-func (r *libraryRepository) Save(entity any) (string, error) {
-	lib := entity.(*model.Library)
-	lib.ID = 0 // Reset ID to ensure we create a new library
-	err := r.Put(lib)
-	if err != nil {
-		return "", err
-	}
-	return strconv.Itoa(lib.ID), nil
-}
-
-func (r *libraryRepository) Update(id string, entity any, cols ...string) error {
-	lib := entity.(*model.Library)
-	idInt, err := strconv.Atoi(id)
-	if err != nil {
-		return fmt.Errorf("invalid library ID: %s", id)
-	}
-
-	lib.ID = idInt
-	return r.Put(lib, cols...)
+func (r *libraryRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Library, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
 var _ model.LibraryRepository = (*libraryRepository)(nil)
-var _ rest.Repository = (*libraryRepository)(nil)
+var _ rest.Repository[model.Library] = (*libraryRepository)(nil)
diff --git a/persistence/library_repository_test.go b/persistence/library_repository_test.go
index 6aede8c4e..0ff470861 100644
--- a/persistence/library_repository_test.go
+++ b/persistence/library_repository_test.go
@@ -23,7 +23,7 @@ var _ = Describe("LibraryRepository", func() {
 	BeforeEach(func() {
 		ctx = request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid"})
 		conn = GetDBXBuilder()
-		repo = NewLibraryRepository(ctx, conn)
+		repo = NewLibraryRepository(conn)
 	})
 
 	AfterEach(func() {
@@ -40,14 +40,14 @@ var _ = Describe("LibraryRepository", func() {
 					Path: "/music/test",
 				}
 
-				err := repo.Put(lib)
+				err := repo.Put(ctx, lib)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lib.ID).To(BeNumerically(">", 0))
 				Expect(lib.CreatedAt).ToNot(BeZero())
 				Expect(lib.UpdatedAt).ToNot(BeZero())
 
 				// Verify it was inserted
-				savedLib, err := repo.Get(lib.ID)
+				savedLib, err := repo.Get(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(savedLib.Name).To(Equal("Test Library"))
 				Expect(savedLib.Path).To(Equal("/music/test"))
@@ -62,11 +62,11 @@ var _ = Describe("LibraryRepository", func() {
 					RemotePath:      "/remote/original",
 					DefaultNewUsers: true,
 				}
-				Expect(repo.Put(lib)).To(Succeed())
+				Expect(repo.Put(ctx, lib)).To(Succeed())
 
-				Expect(repo.Put(&model.Library{ID: lib.ID, Name: "Renamed", Path: lib.Path}, "name", "path")).To(Succeed())
+				Expect(repo.Put(ctx, &model.Library{ID: lib.ID, Name: "Renamed", Path: lib.Path}, "name", "path")).To(Succeed())
 
-				saved, err := repo.Get(lib.ID)
+				saved, err := repo.Get(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(saved.Name).To(Equal("Renamed"))
 				Expect(saved.RemotePath).To(Equal("/remote/original"))
@@ -82,7 +82,7 @@ var _ = Describe("LibraryRepository", func() {
 					Name: "Original Library",
 					Path: "/music/original",
 				}
-				err := repo.Put(lib)
+				err := repo.Put(ctx, lib)
 				Expect(err).ToNot(HaveOccurred())
 
 				originalID := lib.ID
@@ -96,7 +96,7 @@ var _ = Describe("LibraryRepository", func() {
 				// Now update it
 				lib.Name = "Updated Library"
 				lib.Path = "/music/updated"
-				err = repo.Put(lib)
+				err = repo.Put(ctx, lib)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Verify it was updated, not inserted
@@ -105,7 +105,7 @@ var _ = Describe("LibraryRepository", func() {
 				Expect(lib.UpdatedAt).To(BeTemporally(">", originalCreatedAt))
 
 				// Verify the changes were saved
-				savedLib, err := repo.Get(lib.ID)
+				savedLib, err := repo.Get(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(savedLib.Name).To(Equal("Updated Library"))
 				Expect(savedLib.Path).To(Equal("/music/updated"))
@@ -121,18 +121,18 @@ var _ = Describe("LibraryRepository", func() {
 				}
 
 				// Ensure the record doesn't exist
-				_, err := repo.Get(999)
+				_, err := repo.Get(ctx, 999)
 				Expect(err).To(HaveOccurred())
 
 				// Put should insert it
-				err = repo.Put(lib)
+				err = repo.Put(ctx, lib)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lib.ID).To(Equal(999))
 				Expect(lib.CreatedAt).ToNot(BeZero())
 				Expect(lib.UpdatedAt).ToNot(BeZero())
 
 				// Verify it was inserted with the correct ID
-				savedLib, err := repo.Get(999)
+				savedLib, err := repo.Get(ctx, 999)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(savedLib.ID).To(Equal(999))
 				Expect(savedLib.Name).To(Equal("New Library with ID"))
@@ -146,7 +146,7 @@ var _ = Describe("LibraryRepository", func() {
 
 		BeforeEach(func() {
 			var err error
-			libBefore, err = repo.Get(model.DefaultLibraryID)
+			libBefore, err = repo.Get(ctx, model.DefaultLibraryID)
 			Expect(err).ToNot(HaveOccurred())
 
 			DeferCleanup(configtest.SetupConfig())
@@ -162,9 +162,9 @@ var _ = Describe("LibraryRepository", func() {
 
 		It("skips updating the default library when the configured path is unchanged", func() {
 			conf.Server.MusicFolder = libBefore.Path
-			Expect(repo.StoreMusicFolder()).To(Succeed())
+			Expect(repo.StoreMusicFolder(ctx)).To(Succeed())
 
-			libAfter, err := repo.Get(model.DefaultLibraryID)
+			libAfter, err := repo.Get(ctx, model.DefaultLibraryID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(libAfter.Path).To(Equal(libBefore.Path))
 			Expect(libAfter.UpdatedAt).To(Equal(libBefore.UpdatedAt))
@@ -172,9 +172,9 @@ var _ = Describe("LibraryRepository", func() {
 
 		It("updates the default library only when the configured path changes", func() {
 			conf.Server.MusicFolder = libBefore.Path + "-updated"
-			Expect(repo.StoreMusicFolder()).To(Succeed())
+			Expect(repo.StoreMusicFolder(ctx)).To(Succeed())
 
-			libAfter, err := repo.Get(model.DefaultLibraryID)
+			libAfter, err := repo.Get(ctx, model.DefaultLibraryID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(libAfter.Path).To(Equal(conf.Server.MusicFolder))
 			Expect(libAfter.UpdatedAt).ToNot(Equal(libBefore.UpdatedAt))
@@ -182,10 +182,10 @@ var _ = Describe("LibraryRepository", func() {
 	})
 
 	It("refreshes stats", func() {
-		libBefore, err := repo.Get(1)
+		libBefore, err := repo.Get(ctx, 1)
 		Expect(err).ToNot(HaveOccurred())
-		Expect(repo.RefreshStats(1)).To(Succeed())
-		libAfter, err := repo.Get(1)
+		Expect(repo.RefreshStats(ctx, 1)).To(Succeed())
+		libAfter, err := repo.Get(ctx, 1)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(libAfter.UpdatedAt).To(BeTemporally(">", libBefore.UpdatedAt))
 
@@ -221,16 +221,16 @@ var _ = Describe("LibraryRepository", func() {
 				Name: "Test Scan Library",
 				Path: "/music/test-scan",
 			}
-			err := repo.Put(lib)
+			err := repo.Put(ctx, lib)
 			Expect(err).ToNot(HaveOccurred())
 		})
 
 		DescribeTable("ScanBegin",
 			func(fullScan bool, expectedFullScanInProgress bool) {
-				err := repo.ScanBegin(lib.ID, fullScan)
+				err := repo.ScanBegin(ctx, lib.ID, fullScan)
 				Expect(err).ToNot(HaveOccurred())
 
-				updatedLib, err := repo.Get(lib.ID)
+				updatedLib, err := repo.Get(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(updatedLib.LastScanStartedAt).ToNot(BeZero())
 				Expect(updatedLib.FullScanInProgress).To(Equal(expectedFullScanInProgress))
@@ -241,15 +241,15 @@ var _ = Describe("LibraryRepository", func() {
 
 		Context("ScanEnd", func() {
 			BeforeEach(func() {
-				err := repo.ScanBegin(lib.ID, true)
+				err := repo.ScanBegin(ctx, lib.ID, true)
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("sets LastScanAt and clears FullScanInProgress and LastScanStartedAt", func() {
-				err := repo.ScanEnd(lib.ID)
+				err := repo.ScanEnd(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 
-				updatedLib, err := repo.Get(lib.ID)
+				updatedLib, err := repo.Get(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(updatedLib.LastScanAt).ToNot(BeZero())
 				Expect(updatedLib.FullScanInProgress).To(BeFalse())
@@ -257,13 +257,13 @@ var _ = Describe("LibraryRepository", func() {
 			})
 
 			It("sets LastScanAt to be after LastScanStartedAt", func() {
-				libBefore, err := repo.Get(lib.ID)
+				libBefore, err := repo.Get(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 
-				err = repo.ScanEnd(lib.ID)
+				err = repo.ScanEnd(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 
-				libAfter, err := repo.Get(lib.ID)
+				libAfter, err := repo.Get(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(libAfter.LastScanAt).To(BeTemporally(">=", libBefore.LastScanStartedAt))
 			})
@@ -273,6 +273,7 @@ var _ = Describe("LibraryRepository", func() {
 	Describe("Delete", func() {
 		var adminRepo model.LibraryRepository
 		var artistRepo model.ArtistRepository
+		var adminCtx context.Context
 
 		artistMissing := func(id string) bool {
 			var missing bool
@@ -283,32 +284,32 @@ var _ = Describe("LibraryRepository", func() {
 		}
 
 		BeforeEach(func() {
-			adminCtx := request.WithUser(log.NewContext(context.TODO()), adminUser)
-			adminRepo = NewLibraryRepository(adminCtx, conn)
-			artistRepo = NewArtistRepository(adminCtx, conn)
+			adminCtx = request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
+			adminRepo = NewLibraryRepository(conn)
+			artistRepo = NewArtistRepository(conn)
 		})
 
 		It("marks artists orphaned by the delete as missing", func() {
 			lib := model.Library{Name: "Doomed Library", Path: "/doomed"}
-			Expect(adminRepo.Put(&lib)).To(Succeed())
+			Expect(adminRepo.Put(adminCtx, &lib)).To(Succeed())
 
 			orphanArtist := model.Artist{ID: "delete-orphan", Name: "Orphan To Be"}
 			sharedArtist := model.Artist{ID: "delete-shared", Name: "Shared Artist"}
-			Expect(artistRepo.Put(&orphanArtist)).To(Succeed())
-			Expect(artistRepo.Put(&sharedArtist)).To(Succeed())
-			Expect(adminRepo.AddArtist(lib.ID, orphanArtist.ID)).To(Succeed())
-			Expect(adminRepo.AddArtist(lib.ID, sharedArtist.ID)).To(Succeed())
-			Expect(adminRepo.AddArtist(1, sharedArtist.ID)).To(Succeed())
+			Expect(artistRepo.Put(adminCtx, &orphanArtist)).To(Succeed())
+			Expect(artistRepo.Put(adminCtx, &sharedArtist)).To(Succeed())
+			Expect(adminRepo.AddArtist(adminCtx, lib.ID, orphanArtist.ID)).To(Succeed())
+			Expect(adminRepo.AddArtist(adminCtx, lib.ID, sharedArtist.ID)).To(Succeed())
+			Expect(adminRepo.AddArtist(adminCtx, 1, sharedArtist.ID)).To(Succeed())
 			DeferCleanup(func() {
 				if raw, ok := artistRepo.(*artistRepository); ok {
-					_, _ = raw.executeSQL(squirrel.Delete("artist").
+					_, _ = raw.executeSQL(adminCtx, squirrel.Delete("artist").
 						Where(squirrel.Eq{"id": []string{orphanArtist.ID, sharedArtist.ID}}))
 				}
 			})
 
 			Expect(artistMissing(orphanArtist.ID)).To(BeFalse())
 
-			Expect(adminRepo.Delete(lib.ID)).To(Succeed())
+			Expect(adminRepo.Delete(adminCtx, lib.ID)).To(Succeed())
 
 			Expect(artistMissing(orphanArtist.ID)).To(BeTrue(), "orphaned artist should be marked missing")
 			Expect(artistMissing(sharedArtist.ID)).To(BeFalse(), "artist still in another library must stay visible")
diff --git a/persistence/mediafile_repository.go b/persistence/mediafile_repository.go
index 835c39b1e..b9a5c3374 100644
--- a/persistence/mediafile_repository.go
+++ b/persistence/mediafile_repository.go
@@ -85,9 +85,8 @@ func (m dbMediaFiles) toModels() model.MediaFiles {
 	return slice.Map(m, func(mf dbMediaFile) model.MediaFile { return *mf.MediaFile })
 }
 
-func NewMediaFileRepository(ctx context.Context, db dbx.Builder) model.MediaFileRepository {
+func NewMediaFileRepository(db dbx.Builder) model.MediaFileRepository {
 	r := &mediaFileRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "media_file"
 	r.registerModel(&model.MediaFile{}, mediaFileFilter())
@@ -147,25 +146,25 @@ func mediaFileRecentlyAddedSort() string {
 	return "media_file.created_at, media_file.id"
 }
 
-func (r *mediaFileRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	query := r.newSelect()
-	query = r.applyLibraryFilter(query)
+func (r *mediaFileRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	query := r.newSelect(ctx)
+	query = r.applyLibraryFilter(ctx, query)
 	// The annotation join is expensive with count(distinct) and pointless unless a filter uses it.
 	if filtersNeedAnnotation(r.applyFilters(query, options...)) {
-		query = r.withAnnotation(query, "media_file.id")
+		query = r.withAnnotation(ctx, query, "media_file.id")
 	}
-	return r.count(query, options...)
+	return r.count(ctx, query, options...)
 }
 
-func (r *mediaFileRepository) CountBySuffix(options ...model.QueryOptions) (map[string]int64, error) {
-	sel := r.newSelect(options...).
+func (r *mediaFileRepository) CountBySuffix(ctx context.Context, options ...model.QueryOptions) (map[string]int64, error) {
+	sel := r.newSelect(ctx, options...).
 		Columns("lower(suffix) as suffix", "count(*) as count").
 		GroupBy("lower(suffix)")
 	var res []struct {
 		Suffix string
 		Count  int64
 	}
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
@@ -176,42 +175,42 @@ func (r *mediaFileRepository) CountBySuffix(options ...model.QueryOptions) (map[
 	return counts, nil
 }
 
-func (r *mediaFileRepository) Exists(id string) (bool, error) {
+func (r *mediaFileRepository) Exists(ctx context.Context, id string) (bool, error) {
 	// The exists() helper applies no library filter, so it would report rows the caller cannot see.
-	c, err := r.count(r.applyLibraryFilter(r.newSelect().Where(Eq{"media_file.id": id})))
+	c, err := r.count(ctx, r.applyLibraryFilter(ctx, r.newSelect(ctx).Where(Eq{"media_file.id": id})))
 	return c > 0, err
 }
 
-func (r *mediaFileRepository) Put(m *model.MediaFile) error {
+func (r *mediaFileRepository) Put(ctx context.Context, m *model.MediaFile) error {
 	if m.CreatedAt.IsZero() {
 		m.CreatedAt = time.Now()
 	}
-	id, err := r.putByMatch(Eq{"path": m.Path, "library_id": m.LibraryID}, m.ID, &dbMediaFile{MediaFile: m})
+	id, err := r.putByMatch(ctx, Eq{"path": m.Path, "library_id": m.LibraryID}, m.ID, &dbMediaFile{MediaFile: m})
 	if err != nil {
 		return err
 	}
 	m.ID = id
-	if err := r.updateParticipants(m.ID, m.Participants); err != nil {
+	if err := r.updateParticipants(ctx, m.ID, m.Participants); err != nil {
 		return err
 	}
-	return r.updateTags(m.ID, m.Tags)
+	return r.updateTags(ctx, m.ID, m.Tags)
 }
 
-func (r *mediaFileRepository) UpdateProbeData(id string, data string) error {
-	_, err := r.executeSQL(Update(r.tableName).Set("probe_data", data).Where(Eq{"id": id}))
+func (r *mediaFileRepository) UpdateProbeData(ctx context.Context, id string, data string) error {
+	_, err := r.executeSQL(ctx, Update(r.tableName).Set("probe_data", data).Where(Eq{"id": id}))
 	return err
 }
 
-func (r *mediaFileRepository) selectMediaFile(options ...model.QueryOptions) SelectBuilder {
-	sql := r.newSelect(options...).Columns("media_file.*", "library.path as library_path", "library.name as library_name").
+func (r *mediaFileRepository) selectMediaFile(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	sql := r.newSelect(ctx, options...).Columns("media_file.*", "library.path as library_path", "library.name as library_name").
 		LeftJoin("library on media_file.library_id = library.id")
-	sql = r.withAnnotation(sql, "media_file.id")
-	sql = r.withBookmark(sql, "media_file.id")
-	return r.applyLibraryFilter(sql)
+	sql = r.withAnnotation(ctx, sql, "media_file.id")
+	sql = r.withBookmark(ctx, sql, "media_file.id")
+	return r.applyLibraryFilter(ctx, sql)
 }
 
-func (r *mediaFileRepository) Get(id string) (*model.MediaFile, error) {
-	res, err := r.GetAll(model.QueryOptions{Filters: Eq{"media_file.id": id}})
+func (r *mediaFileRepository) Get(ctx context.Context, id string) (*model.MediaFile, error) {
+	res, err := r.GetAll(ctx, model.QueryOptions{Filters: Eq{"media_file.id": id}})
 	if err != nil {
 		return nil, err
 	}
@@ -221,34 +220,34 @@ func (r *mediaFileRepository) Get(id string) (*model.MediaFile, error) {
 	return &res[0], nil
 }
 
-func (r *mediaFileRepository) GetWithParticipants(id string) (*model.MediaFile, error) {
-	m, err := r.Get(id)
+func (r *mediaFileRepository) GetWithParticipants(ctx context.Context, id string) (*model.MediaFile, error) {
+	m, err := r.Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
-	m.Participants, err = r.getParticipants(m)
+	m.Participants, err = r.getParticipants(ctx, m)
 	return m, err
 }
 
-func (r *mediaFileRepository) GetAll(options ...model.QueryOptions) (model.MediaFiles, error) {
-	sq := r.selectMediaFile(options...)
+func (r *mediaFileRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.MediaFiles, error) {
+	sq := r.selectMediaFile(ctx, options...)
 	var res dbMediaFiles
-	err := r.queryAll(sq, &res, options...)
+	err := r.queryAll(ctx, sq, &res, options...)
 	if err != nil {
 		return nil, err
 	}
 	mfs := res.toModels()
-	r.hydrateArtwork(mfs)
+	r.hydrateArtwork(ctx, mfs)
 	return mfs, nil
 }
 
-func (r *mediaFileRepository) hydrateArtwork(mfs model.MediaFiles) {
-	hydrateMediaFileArtwork(r.ctx, r.db, mfs)
+func (r *mediaFileRepository) hydrateArtwork(ctx context.Context, mfs model.MediaFiles) {
+	hydrateMediaFileArtwork(ctx, r.db, mfs)
 }
 
 // GetRandom uses two passes so the random sort runs over a narrow rowid index instead of the
 // wide media_file row: pick random rowids first, then hydrate only those.
-func (r *mediaFileRepository) GetRandom(options ...model.QueryOptions) (model.MediaFiles, error) {
+func (r *mediaFileRepository) GetRandom(ctx context.Context, options ...model.QueryOptions) (model.MediaFiles, error) {
 	var opt model.QueryOptions
 	if len(options) > 0 {
 		opt = options[0]
@@ -256,14 +255,14 @@ func (r *mediaFileRepository) GetRandom(options ...model.QueryOptions) (model.Me
 
 	rowidQuery := Select("media_file.rowid").From(r.tableName)
 	rowidQuery = r.applyFilters(rowidQuery, model.QueryOptions{Filters: opt.Filters})
-	rowidQuery = r.applyLibraryFilter(rowidQuery)
+	rowidQuery = r.applyLibraryFilter(ctx, rowidQuery)
 	rowidQuery = rowidQuery.OrderBy("random()")
 	if opt.Max > 0 {
 		rowidQuery = rowidQuery.Limit(uint64(opt.Max))
 	}
 
 	var rowids []int64
-	if err := r.queryAllSlice(rowidQuery, &rowids); err != nil {
+	if err := r.queryAllSlice(ctx, rowidQuery, &rowids); err != nil {
 		return nil, err
 	}
 	if len(rowids) == 0 {
@@ -272,17 +271,17 @@ func (r *mediaFileRepository) GetRandom(options ...model.QueryOptions) (model.Me
 
 	// Re-shuffle in Phase 2: `WHERE rowid IN (...)` returns rows in ascending rowid order, not
 	// the random order from Phase 1. Sorting only the (<=Max) hydrated rows is negligible.
-	sq := r.selectMediaFile().Where(Eq{"media_file.rowid": rowids}).OrderBy("random()")
+	sq := r.selectMediaFile(ctx).Where(Eq{"media_file.rowid": rowids}).OrderBy("random()")
 	var res dbMediaFiles
-	if err := r.queryAll(sq, &res); err != nil {
+	if err := r.queryAll(ctx, sq, &res); err != nil {
 		return nil, err
 	}
 	mfs := res.toModels()
-	r.hydrateArtwork(mfs)
+	r.hydrateArtwork(ctx, mfs)
 	return mfs, nil
 }
 
-func (r *mediaFileRepository) GetAllByTags(tag model.TagName, values []string, options ...model.QueryOptions) (model.MediaFiles, error) {
+func (r *mediaFileRepository) GetAllByTags(ctx context.Context, tag model.TagName, values []string, options ...model.QueryOptions) (model.MediaFiles, error) {
 	placeholders := make([]string, len(values))
 	args := make([]any, len(values))
 	for i, v := range values {
@@ -304,12 +303,12 @@ func (r *mediaFileRepository) GetAllByTags(tag model.TagName, values []string, o
 	} else {
 		opts.Filters = tagFilter
 	}
-	return r.GetAll(opts)
+	return r.GetAll(ctx, opts)
 }
 
-func (r *mediaFileRepository) GetCursor(options ...model.QueryOptions) (model.MediaFileCursor, error) {
-	sq := r.selectMediaFile(options...)
-	cursor, err := queryWithStableResults[dbMediaFile](r.sqlRepository, sq)
+func (r *mediaFileRepository) GetCursor(ctx context.Context, options ...model.QueryOptions) (model.MediaFileCursor, error) {
+	sq := r.selectMediaFile(ctx, options...)
+	cursor, err := queryWithStableResults[dbMediaFile](ctx, r.sqlRepository, sq)
 	if err != nil {
 		return nil, err
 	}
@@ -317,17 +316,17 @@ func (r *mediaFileRepository) GetCursor(options ...model.QueryOptions) (model.Me
 }
 
 // getAllIDs returns the IDs of GetAll's row set, skipping its wide column projection.
-func (r *mediaFileRepository) getAllIDs(options ...model.QueryOptions) ([]string, error) {
-	sq := r.applyLibraryFilter(r.newSelect(options...).Columns("media_file.id"))
+func (r *mediaFileRepository) getAllIDs(ctx context.Context, options ...model.QueryOptions) ([]string, error) {
+	sq := r.applyLibraryFilter(ctx, r.newSelect(ctx, options...).Columns("media_file.id"))
 	if filtersNeedAnnotation(sq) {
-		sq = r.withAnnotation(sq, "media_file.id")
+		sq = r.withAnnotation(ctx, sq, "media_file.id")
 	}
 	ids := []string{}
-	err := r.queryAllSlice(sq, &ids)
+	err := r.queryAllSlice(ctx, sq, &ids)
 	return ids, err
 }
 
-func (r *mediaFileRepository) GetAlbumIDsByFolder(lib model.Library, folderIDs ...string) ([]string, error) {
+func (r *mediaFileRepository) GetAlbumIDsByFolder(ctx context.Context, lib model.Library, folderIDs ...string) ([]string, error) {
 	ids := []string{}
 	for chunk := range slices.Chunk(folderIDs, 200) {
 		// A folder's own cover also covers albums whose tracks sit in its disc subfolders.
@@ -339,7 +338,7 @@ func (r *mediaFileRepository) GetAlbumIDsByFolder(lib model.Library, folderIDs .
 		sq := Select("distinct album_id").From("media_file").
 			Where(And{Eq{"missing": false}, ConcatExpr("folder_id IN (", inFolders, ")")})
 		var chunkIDs []string
-		if err := r.queryAllSlice(sq, &chunkIDs); err != nil {
+		if err := r.queryAllSlice(ctx, sq, &chunkIDs); err != nil {
 			return nil, err
 		}
 		ids = append(ids, chunkIDs...)
@@ -348,14 +347,14 @@ func (r *mediaFileRepository) GetAlbumIDsByFolder(lib model.Library, folderIDs .
 }
 
 // GetCursorWithArtwork streams the same rows as GetCursor, hydrated, via an id pre-pass.
-func (r *mediaFileRepository) GetCursorWithArtwork(options ...model.QueryOptions) (model.MediaFileCursor, error) {
-	ids, err := r.getAllIDs(options...)
+func (r *mediaFileRepository) GetCursorWithArtwork(ctx context.Context, options ...model.QueryOptions) (model.MediaFileCursor, error) {
+	ids, err := r.getAllIDs(ctx, options...)
 	if err != nil {
 		return nil, err
 	}
 	opts := chunkOptions(options, "media_file.id")
 	return model.MediaFileCursor(streamByIDs(ids, func(chunk []string) (model.MediaFiles, error) {
-		return r.GetAll(opts(chunk))
+		return r.GetAll(ctx, opts(chunk))
 	})), nil
 }
 
@@ -363,7 +362,7 @@ func (r *mediaFileRepository) GetCursorWithArtwork(options ...model.QueryOptions
 // The paths can be library-qualified (format: "libraryID:path") or unqualified ("path").
 // Library-qualified paths search within the specified library, while unqualified paths
 // search across all libraries for backward compatibility.
-func (r *mediaFileRepository) FindByPaths(paths []string) (model.MediaFiles, error) {
+func (r *mediaFileRepository) FindByPaths(ctx context.Context, paths []string) (model.MediaFiles, error) {
 	// One IN list per library instead of one OR term per path: SQLite abandons the
 	// path index at just two OR-ed equality terms and scans the whole table.
 	byLibrary := map[int][]string{}
@@ -395,57 +394,57 @@ func (r *mediaFileRepository) FindByPaths(paths []string) (model.MediaFiles, err
 		return model.MediaFiles{}, nil
 	}
 
-	sel := r.applyLibraryFilter(r.newSelect().Columns("*").Where(query))
+	sel := r.applyLibraryFilter(ctx, r.newSelect(ctx).Columns("*").Where(query))
 	var res dbMediaFiles
-	if err := r.queryAll(sel, &res); err != nil {
+	if err := r.queryAll(ctx, sel, &res); err != nil {
 		return nil, err
 	}
 
 	return res.toModels(), nil
 }
 
-func (r *mediaFileRepository) Delete(id string) error {
-	return r.delete(Eq{"id": id})
+func (r *mediaFileRepository) Delete(ctx context.Context, id string) error {
+	return r.delete(ctx, Eq{"id": id})
 }
 
-func (r *mediaFileRepository) ReassignReferences(prevID, newID string) error {
-	if err := r.ReassignAnnotation(prevID, newID); err != nil {
+func (r *mediaFileRepository) ReassignReferences(ctx context.Context, prevID, newID string) error {
+	if err := r.ReassignAnnotation(ctx, prevID, newID); err != nil {
 		return fmt.Errorf("reassigning annotations: %w", err)
 	}
-	if err := r.reassignBookmark(prevID, newID); err != nil {
+	if err := r.reassignBookmark(ctx, prevID, newID); err != nil {
 		return fmt.Errorf("reassigning bookmarks: %w", err)
 	}
 	upd := Update("playlist_tracks").Set("media_file_id", newID).Where(Eq{"media_file_id": prevID})
-	if _, err := r.executeSQL(upd); err != nil {
+	if _, err := r.executeSQL(ctx, upd); err != nil {
 		return fmt.Errorf("reassigning playlist tracks: %w", err)
 	}
 	upd = Update("scrobbles").Set("media_file_id", newID).Where(Eq{"media_file_id": prevID})
-	if _, err := r.executeSQL(upd); err != nil {
+	if _, err := r.executeSQL(ctx, upd); err != nil {
 		return fmt.Errorf("reassigning scrobbles: %w", err)
 	}
 	// OR IGNORE: scrobble_buffer is unique on (user_id, service, media_file_id, play_time)
 	buf := Expr("update or ignore scrobble_buffer set media_file_id = ? where media_file_id = ?", newID, prevID)
-	if _, err := r.executeSQL(buf); err != nil {
+	if _, err := r.executeSQL(ctx, buf); err != nil {
 		return fmt.Errorf("reassigning buffered scrobbles: %w", err)
 	}
 	return nil
 }
 
-func (r *mediaFileRepository) DeleteAllMissing() (int64, error) {
-	user := loggedUser(r.ctx)
+func (r *mediaFileRepository) DeleteAllMissing(ctx context.Context) (int64, error) {
+	user := loggedUser(ctx)
 	if !user.IsAdmin {
 		return 0, rest.ErrPermissionDenied
 	}
 	del := Delete(r.tableName).Where(Eq{"missing": true})
-	return r.executeSQL(del)
+	return r.executeSQL(ctx, del)
 }
 
-func (r *mediaFileRepository) DeleteMissing(ids []string) error {
-	user := loggedUser(r.ctx)
+func (r *mediaFileRepository) DeleteMissing(ctx context.Context, ids []string) error {
+	user := loggedUser(ctx)
 	if !user.IsAdmin {
 		return rest.ErrPermissionDenied
 	}
-	return r.delete(
+	return r.delete(ctx,
 		And{
 			Eq{"missing": true},
 			Eq{"id": ids},
@@ -453,24 +452,24 @@ func (r *mediaFileRepository) DeleteMissing(ids []string) error {
 	)
 }
 
-func (r *mediaFileRepository) MarkMissing(missing bool, mfs ...*model.MediaFile) error {
+func (r *mediaFileRepository) MarkMissing(ctx context.Context, missing bool, mfs ...*model.MediaFile) error {
 	ids := slice.SeqFunc(mfs, func(m *model.MediaFile) string { return m.ID })
 	for chunk := range slice.CollectChunks(ids, 200) {
 		upd := Update(r.tableName).
 			Set("missing", missing).
 			Set("updated_at", time.Now()).
 			Where(Eq{"id": chunk})
-		c, err := r.executeSQL(upd)
+		c, err := r.executeSQL(ctx, upd)
 		if err != nil || c == 0 {
-			log.Error(r.ctx, "Error setting mediafile missing flag", "ids", chunk, err)
+			log.Error(ctx, "Error setting mediafile missing flag", "ids", chunk, err)
 			return err
 		}
-		log.Debug(r.ctx, "Marked missing mediafiles", "total", c, "ids", chunk)
+		log.Debug(ctx, "Marked missing mediafiles", "total", c, "ids", chunk)
 	}
 	return nil
 }
 
-func (r *mediaFileRepository) MarkMissingByFolder(missing bool, folderIDs ...string) error {
+func (r *mediaFileRepository) MarkMissingByFolder(ctx context.Context, missing bool, folderIDs ...string) error {
 	for chunk := range slices.Chunk(folderIDs, 200) {
 		upd := Update(r.tableName).
 			Set("missing", missing).
@@ -479,12 +478,12 @@ func (r *mediaFileRepository) MarkMissingByFolder(missing bool, folderIDs ...str
 				Eq{"folder_id": chunk},
 				Eq{"missing": !missing},
 			})
-		c, err := r.executeSQL(upd)
+		c, err := r.executeSQL(ctx, upd)
 		if err != nil {
-			log.Error(r.ctx, "Error setting mediafile missing flag", "folderIDs", chunk, err)
+			log.Error(ctx, "Error setting mediafile missing flag", "folderIDs", chunk, err)
 			return err
 		}
-		log.Debug(r.ctx, "Marked missing mediafiles from missing folders", "total", c, "folders", chunk)
+		log.Debug(ctx, "Marked missing mediafiles from missing folders", "total", c, "folders", chunk)
 	}
 	return nil
 }
@@ -492,8 +491,8 @@ func (r *mediaFileRepository) MarkMissingByFolder(missing bool, folderIDs ...str
 // GetMissingAndMatching returns all mediafiles that are missing and their potential matches (comparing PIDs)
 // that were added/updated after the last scan started. The result is ordered by PID.
 // It does not need to load bookmarks, annotations and participants, as they are not used by the scanner.
-func (r *mediaFileRepository) GetMissingAndMatching(libId int) (model.MediaFileCursor, error) {
-	subQ := r.newSelect().Columns("pid").
+func (r *mediaFileRepository) GetMissingAndMatching(ctx context.Context, libId int) (model.MediaFileCursor, error) {
+	subQ := r.newSelect(ctx).Columns("pid").
 		Where(And{
 			Eq{"media_file.missing": true},
 			Eq{"library_id": libId},
@@ -502,7 +501,7 @@ func (r *mediaFileRepository) GetMissingAndMatching(libId int) (model.MediaFileC
 	if err != nil {
 		return nil, err
 	}
-	sel := r.newSelect().Columns("media_file.*", "library.path as library_path", "library.name as library_name").
+	sel := r.newSelect(ctx).Columns("media_file.*", "library.path as library_path", "library.name as library_name").
 		LeftJoin("library on media_file.library_id = library.id").
 		Where("pid in ("+subQText+")", subQArgs...).
 		Where(Or{
@@ -510,7 +509,7 @@ func (r *mediaFileRepository) GetMissingAndMatching(libId int) (model.MediaFileC
 			ConcatExpr("media_file.created_at > library.last_scan_started_at"),
 		}).
 		OrderBy("pid")
-	cursor, err := queryWithStableResults[dbMediaFile](r.sqlRepository, sel)
+	cursor, err := queryWithStableResults[dbMediaFile](ctx, r.sqlRepository, sel)
 	if err != nil {
 		return nil, err
 	}
@@ -523,8 +522,8 @@ func wrapMediaFileCursor(cursor iter.Seq2[dbMediaFile, error]) model.MediaFileCu
 
 // FindRecentFilesByMBZTrackID finds recently added files by MusicBrainz Track ID in other libraries
 // It uses a lightweight query without annotation/bookmark joins since those are not needed for matching
-func (r *mediaFileRepository) FindRecentFilesByMBZTrackID(missing model.MediaFile, since time.Time) (model.MediaFiles, error) {
-	sel := r.newSelect().Columns("media_file.*", "library.path as library_path", "library.name as library_name").
+func (r *mediaFileRepository) FindRecentFilesByMBZTrackID(ctx context.Context, missing model.MediaFile, since time.Time) (model.MediaFiles, error) {
+	sel := r.newSelect(ctx).Columns("media_file.*", "library.path as library_path", "library.name as library_name").
 		LeftJoin("library on media_file.library_id = library.id").
 		Where(And{
 			NotEq{"media_file.library_id": missing.LibraryID},
@@ -536,7 +535,7 @@ func (r *mediaFileRepository) FindRecentFilesByMBZTrackID(missing model.MediaFil
 		}).OrderBy("media_file.created_at DESC")
 
 	var res dbMediaFiles
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
@@ -545,8 +544,8 @@ func (r *mediaFileRepository) FindRecentFilesByMBZTrackID(missing model.MediaFil
 
 // FindRecentFilesByProperties finds recently added files by intrinsic properties in other libraries
 // It uses a lightweight query without annotation/bookmark joins since those are not needed for matching
-func (r *mediaFileRepository) FindRecentFilesByProperties(missing model.MediaFile, since time.Time) (model.MediaFiles, error) {
-	sel := r.newSelect().Columns("media_file.*", "library.path as library_path", "library.name as library_name").
+func (r *mediaFileRepository) FindRecentFilesByProperties(ctx context.Context, missing model.MediaFile, since time.Time) (model.MediaFiles, error) {
+	sel := r.newSelect(ctx).Columns("media_file.*", "library.path as library_path", "library.name as library_name").
 		LeftJoin("library on media_file.library_id = library.id").
 		Where(And{
 			NotEq{"media_file.library_id": missing.LibraryID},
@@ -562,7 +561,7 @@ func (r *mediaFileRepository) FindRecentFilesByProperties(missing model.MediaFil
 		}).OrderBy("media_file.created_at DESC")
 
 	var res dbMediaFiles
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
@@ -575,8 +574,8 @@ var mediaFileSearchConfig = searchConfig{
 	MBIDFields:   []string{"mbz_recording_id", "mbz_release_track_id"},
 }
 
-func (r *mediaFileRepository) MatchesCriteria(id string, c criteria.Criteria) (bool, error) {
-	usr := loggedUser(r.ctx)
+func (r *mediaFileRepository) MatchesCriteria(ctx context.Context, id string, c criteria.Criteria) (bool, error) {
+	usr := loggedUser(ctx)
 	rulesSQL := newSmartPlaylistCriteria(c, withSmartPlaylistOwner(*usr))
 	cond, err := rulesSQL.where()
 	if err != nil {
@@ -586,46 +585,38 @@ func (r *mediaFileRepository) MatchesCriteria(id string, c criteria.Criteria) (b
 	sq = rulesSQL.applyExpressionJoins(sq, usr.ID)
 	sq = sq.Where(And{Eq{"media_file.id": id}, cond})
 	var res struct{ Count int64 }
-	if err := r.queryOne(sq, &res); err != nil {
+	if err := r.queryOne(ctx, sq, &res); err != nil {
 		return false, err
 	}
 	return res.Count > 0, nil
 }
 
-func (r *mediaFileRepository) Search(q string, options ...model.QueryOptions) (model.MediaFiles, error) {
+func (r *mediaFileRepository) Search(ctx context.Context, q string, options ...model.QueryOptions) (model.MediaFiles, error) {
 	var opts model.QueryOptions
 	if len(options) > 0 {
 		opts = options[0]
 	}
 	var res dbMediaFiles
-	err := r.doSearch(r.selectMediaFile(options...), q, &res, mediaFileSearchConfig, opts)
+	err := r.doSearch(ctx, r.selectMediaFile(ctx, options...), q, &res, mediaFileSearchConfig, opts)
 	if err != nil {
 		return nil, fmt.Errorf("searching media_file %q: %w", q, err)
 	}
 	mfs := res.toModels()
-	r.hydrateArtwork(mfs)
+	r.hydrateArtwork(ctx, mfs)
 	return mfs, nil
 }
 
-func (r *mediaFileRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *mediaFileRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *mediaFileRepository) Read(id string) (any, error) {
-	return r.Get(id)
+func (r *mediaFileRepository) Read(ctx context.Context, id string) (*model.MediaFile, error) {
+	return r.Get(ctx, id)
 }
 
-func (r *mediaFileRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
-}
-
-func (r *mediaFileRepository) EntityName() string {
-	return "mediafile"
-}
-
-func (r *mediaFileRepository) NewInstance() any {
-	return &model.MediaFile{}
+func (r *mediaFileRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.MediaFile, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
 var _ model.MediaFileRepository = (*mediaFileRepository)(nil)
-var _ model.ResourceRepository = (*mediaFileRepository)(nil)
+var _ rest.Repository[model.MediaFile] = (*mediaFileRepository)(nil)
diff --git a/persistence/mediafile_repository_test.go b/persistence/mediafile_repository_test.go
index d81b5e9ee..14590090c 100644
--- a/persistence/mediafile_repository_test.go
+++ b/persistence/mediafile_repository_test.go
@@ -24,11 +24,11 @@ import (
 
 var _ = Describe("MediaRepository", func() {
 	var mr model.MediaFileRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
-		ctx := log.NewContext(context.TODO())
-		ctx = request.WithUser(ctx, model.User{ID: "userid"})
-		mr = NewMediaFileRepository(ctx, GetDBXBuilder())
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid"})
+		mr = NewMediaFileRepository(GetDBXBuilder())
 	})
 
 	Describe("GetAlbumIDsByFolder", func() {
@@ -37,22 +37,22 @@ var _ = Describe("MediaRepository", func() {
 
 		BeforeEach(func() {
 			ctx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid"})
-			libPtr, err := NewLibraryRepository(ctx, GetDBXBuilder()).Get(1)
+			libPtr, err := NewLibraryRepository(GetDBXBuilder()).Get(ctx, 1)
 			Expect(err).ToNot(HaveOccurred())
 			lib = *libPtr
 
-			folderRepo := newFolderRepository(ctx, GetDBXBuilder())
+			folderRepo := newFolderRepository(GetDBXBuilder())
 			albumRoot = model.NewFolder(lib, "ByFolder/Album")
 			disc1 = model.NewFolder(lib, "ByFolder/Album/CD1")
 			sibling = model.NewFolder(lib, "ByFolder/Other")
 			for _, f := range []*model.Folder{albumRoot, disc1, sibling} {
-				Expect(folderRepo.Put(f)).To(Succeed())
+				Expect(folderRepo.Put(ctx, f)).To(Succeed())
 			}
 			// Tracks live in the disc subfolder; the sibling album is the negative control.
-			Expect(mr.Put(&model.MediaFile{ID: "fol-mf-1", LibraryID: 1, AlbumID: "fol-al-1", FolderID: disc1.ID, Path: "t/1.mp3"})).To(Succeed())
-			Expect(mr.Put(&model.MediaFile{ID: "fol-mf-2", LibraryID: 1, AlbumID: "fol-al-1", FolderID: disc1.ID, Path: "t/2.mp3"})).To(Succeed())
-			Expect(mr.Put(&model.MediaFile{ID: "fol-mf-3", LibraryID: 1, AlbumID: "fol-al-2", FolderID: sibling.ID, Path: "t/3.mp3"})).To(Succeed())
-			Expect(mr.Put(&model.MediaFile{ID: "fol-mf-4", LibraryID: 1, AlbumID: "fol-al-3", FolderID: disc1.ID, Path: "t/4.mp3", Missing: true})).To(Succeed())
+			Expect(mr.Put(ctx, &model.MediaFile{ID: "fol-mf-1", LibraryID: 1, AlbumID: "fol-al-1", FolderID: disc1.ID, Path: "t/1.mp3"})).To(Succeed())
+			Expect(mr.Put(ctx, &model.MediaFile{ID: "fol-mf-2", LibraryID: 1, AlbumID: "fol-al-1", FolderID: disc1.ID, Path: "t/2.mp3"})).To(Succeed())
+			Expect(mr.Put(ctx, &model.MediaFile{ID: "fol-mf-3", LibraryID: 1, AlbumID: "fol-al-2", FolderID: sibling.ID, Path: "t/3.mp3"})).To(Succeed())
+			Expect(mr.Put(ctx, &model.MediaFile{ID: "fol-mf-4", LibraryID: 1, AlbumID: "fol-al-3", FolderID: disc1.ID, Path: "t/4.mp3", Missing: true})).To(Succeed())
 			DeferCleanup(func() {
 				_, _ = GetDBXBuilder().NewQuery("DELETE FROM media_file WHERE id LIKE 'fol-mf-%'").Execute()
 				_, _ = GetDBXBuilder().NewQuery("DELETE FROM folder WHERE path LIKE 'ByFolder%' OR name = 'ByFolder'").Execute()
@@ -60,20 +60,20 @@ var _ = Describe("MediaRepository", func() {
 		})
 
 		It("returns the distinct album IDs of non-missing tracks in the folder", func() {
-			ids, err := mr.GetAlbumIDsByFolder(lib, disc1.ID)
+			ids, err := mr.GetAlbumIDsByFolder(ctx, lib, disc1.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(ConsistOf("fol-al-1"))
 		})
 
 		It("also matches albums whose tracks are in a direct child of the folder", func() {
 			// A cover in the album root must reach the album whose tracks sit in CD1
-			ids, err := mr.GetAlbumIDsByFolder(lib, albumRoot.ID)
+			ids, err := mr.GetAlbumIDsByFolder(ctx, lib, albumRoot.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(ConsistOf("fol-al-1"))
 		})
 
 		It("does not match albums outside the folder", func() {
-			ids, err := mr.GetAlbumIDsByFolder(lib, albumRoot.ID)
+			ids, err := mr.GetAlbumIDsByFolder(ctx, lib, albumRoot.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).ToNot(ContainElement("fol-al-2"))
 		})
@@ -82,46 +82,47 @@ var _ = Describe("MediaRepository", func() {
 	Describe("GetCursor", func() {
 		It("yields the same media files as GetAll", func() {
 			opts := model.QueryOptions{Sort: "title"}
-			want, err := mr.GetAll(opts)
+			want, err := mr.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(collectCursor(mr.GetCursor(opts))).To(Equal([]model.MediaFile(want)))
+			Expect(collectCursor(mr.GetCursor(ctx, opts))).To(Equal([]model.MediaFile(want)))
 		})
 
 		It("honors Max/Offset like GetAll", func() {
 			opts := model.QueryOptions{Sort: "title", Max: 2, Offset: 1}
-			want, err := mr.GetAll(opts)
+			want, err := mr.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(collectCursor(mr.GetCursor(opts))).To(Equal([]model.MediaFile(want)))
+			Expect(collectCursor(mr.GetCursor(ctx, opts))).To(Equal([]model.MediaFile(want)))
 		})
 	})
 
 	It("gets mediafile from the DB", func() {
-		actual, err := mr.Get("1004")
+		actual, err := mr.Get(ctx, "1004")
 		Expect(err).ToNot(HaveOccurred())
 		actual.CreatedAt = time.Time{}
 		Expect(actual).To(Equal(&songAntenna))
 	})
 
 	It("returns ErrNotFound", func() {
-		_, err := mr.Get("56")
+		_, err := mr.Get(ctx, "56")
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
 	It("counts the number of mediafiles in the DB", func() {
-		Expect(mr.CountAll()).To(Equal(int64(13)))
+		Expect(mr.CountAll(ctx)).To(Equal(int64(13)))
 	})
 
 	Describe("CountAll annotation-join gating", func() {
 		var adminRepo model.MediaFileRepository
+		var adminCtx context.Context
 
 		BeforeEach(func() {
-			adminCtx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid", IsAdmin: true})
-			adminRepo = NewMediaFileRepository(adminCtx, GetDBXBuilder())
+			adminCtx = request.WithUser(ctx, model.User{ID: "userid", IsAdmin: true})
+			adminRepo = NewMediaFileRepository(GetDBXBuilder())
 		})
 
 		It("counts starred songs when an annotation filter is present", func() {
 			// Come Together (id 1002) is starred for the admin user in the seed data
-			count, err := adminRepo.CountAll(model.QueryOptions{
+			count, err := adminRepo.CountAll(adminCtx, model.QueryOptions{
 				Filters: annotationBoolFilter("starred")("starred", "true"),
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -129,7 +130,7 @@ var _ = Describe("MediaRepository", func() {
 		})
 
 		It("counts with starred=false without a 'no such column' error (join kept)", func() {
-			count, err := adminRepo.CountAll(model.QueryOptions{
+			count, err := adminRepo.CountAll(adminCtx, model.QueryOptions{
 				Filters: annotationBoolFilter("starred")("starred", "false"),
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -138,7 +139,7 @@ var _ = Describe("MediaRepository", func() {
 		})
 
 		It("counts unfiltered with the join dropped", func() {
-			Expect(adminRepo.CountAll()).To(Equal(int64(13)))
+			Expect(adminRepo.CountAll(adminCtx)).To(Equal(int64(13)))
 		})
 	})
 
@@ -151,21 +152,21 @@ var _ = Describe("MediaRepository", func() {
 			flacFile2 = model.MediaFile{ID: "suffix-flac2", LibraryID: 1, Suffix: "flac", Path: "test/file2.flac"}
 			flacUpperFile = model.MediaFile{ID: "suffix-FLAC", LibraryID: 1, Suffix: "FLAC", Path: "test/file.FLAC"}
 
-			Expect(mr.Put(&mp3File)).To(Succeed())
-			Expect(mr.Put(&flacFile1)).To(Succeed())
-			Expect(mr.Put(&flacFile2)).To(Succeed())
-			Expect(mr.Put(&flacUpperFile)).To(Succeed())
+			Expect(mr.Put(ctx, &mp3File)).To(Succeed())
+			Expect(mr.Put(ctx, &flacFile1)).To(Succeed())
+			Expect(mr.Put(ctx, &flacFile2)).To(Succeed())
+			Expect(mr.Put(ctx, &flacUpperFile)).To(Succeed())
 		})
 
 		AfterEach(func() {
-			_ = mr.Delete(mp3File.ID)
-			_ = mr.Delete(flacFile1.ID)
-			_ = mr.Delete(flacFile2.ID)
-			_ = mr.Delete(flacUpperFile.ID)
+			_ = mr.Delete(ctx, mp3File.ID)
+			_ = mr.Delete(ctx, flacFile1.ID)
+			_ = mr.Delete(ctx, flacFile2.ID)
+			_ = mr.Delete(ctx, flacUpperFile.ID)
 		})
 
 		It("counts media files grouped by suffix with lowercase normalization", func() {
-			counts, err := mr.CountBySuffix()
+			counts, err := mr.CountBySuffix(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Should have lowercase keys only
@@ -182,7 +183,7 @@ var _ = Describe("MediaRepository", func() {
 
 	It("returns songs ordered by lyrics with a specific title/artist", func() {
 		// attempt to mimic filters.SongsByArtistTitleWithLyricsFirst, except we want all items
-		results, err := mr.GetAll(model.QueryOptions{
+		results, err := mr.GetAll(ctx, model.QueryOptions{
 			Sort:  "lyrics, updated_at",
 			Order: "desc",
 			Filters: squirrel.And{
@@ -206,14 +207,14 @@ var _ = Describe("MediaRepository", func() {
 
 	Describe("GetRandom", func() {
 		It("returns the requested number of distinct, fully-hydrated media files", func() {
-			results, err := mr.GetRandom(model.QueryOptions{Max: 5})
+			results, err := mr.GetRandom(ctx, model.QueryOptions{Max: 5})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(5))
 
 			// Each returned row must match its GetAll counterpart exactly — proves Phase 2
 			// hydrates full rows (not bare rowids) — and ids must be distinct.
 			byID := map[string]model.MediaFile{}
-			all, err := mr.GetAll()
+			all, err := mr.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			for _, mf := range all {
 				byID[mf.ID] = mf
@@ -229,13 +230,13 @@ var _ = Describe("MediaRepository", func() {
 		})
 
 		It("returns all matching files when Max exceeds the total", func() {
-			results, err := mr.GetRandom(model.QueryOptions{Max: 1000})
+			results, err := mr.GetRandom(ctx, model.QueryOptions{Max: 1000})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(13))
 		})
 
 		It("honors filters", func() {
-			results, err := mr.GetRandom(model.QueryOptions{
+			results, err := mr.GetRandom(ctx, model.QueryOptions{
 				Max:     10,
 				Filters: squirrel.Eq{"media_file.title": "Antenna"},
 			})
@@ -248,7 +249,7 @@ var _ = Describe("MediaRepository", func() {
 
 		It("returns varying results across calls", func() {
 			// Retry a few times: two random draws of 5 from 13 rows differ with near-certainty.
-			first, err := mr.GetRandom(model.QueryOptions{Max: 5})
+			first, err := mr.GetRandom(ctx, model.QueryOptions{Max: 5})
 			Expect(err).ToNot(HaveOccurred())
 			firstIDs := func() []string {
 				ids := make([]string, len(first))
@@ -259,7 +260,7 @@ var _ = Describe("MediaRepository", func() {
 			}()
 			differed := false
 			for range 10 {
-				next, err := mr.GetRandom(model.QueryOptions{Max: 5})
+				next, err := mr.GetRandom(ctx, model.QueryOptions{Max: 5})
 				Expect(err).ToNot(HaveOccurred())
 				nextIDs := make([]string, len(next))
 				for i, mf := range next {
@@ -276,7 +277,7 @@ var _ = Describe("MediaRepository", func() {
 		It("randomizes order even when Max exceeds the total", func() {
 			// Same set of rows every time (all 13), but the order must still be shuffled —
 			// guards against Phase 2's `rowid IN (...)` returning rows in rowid order.
-			first, err := mr.GetRandom(model.QueryOptions{Max: 100})
+			first, err := mr.GetRandom(ctx, model.QueryOptions{Max: 100})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(first).To(HaveLen(13))
 			firstIDs := make([]string, len(first))
@@ -285,7 +286,7 @@ var _ = Describe("MediaRepository", func() {
 			}
 			differed := false
 			for range 10 {
-				next, err := mr.GetRandom(model.QueryOptions{Max: 100})
+				next, err := mr.GetRandom(ctx, model.QueryOptions{Max: 100})
 				Expect(err).ToNot(HaveOccurred())
 				nextIDs := make([]string, len(next))
 				for i, mf := range next {
@@ -304,13 +305,13 @@ var _ = Describe("MediaRepository", func() {
 		It("sets CreatedAt to now when inserting a new file with zero CreatedAt", func() {
 			before := time.Now().Add(-time.Second)
 			newFile := model.MediaFile{ID: id.NewRandom(), LibraryID: 1, Path: "test/created-at-zero.mp3"}
-			Expect(mr.Put(&newFile)).To(Succeed())
+			Expect(mr.Put(ctx, &newFile)).To(Succeed())
 
-			retrieved, err := mr.Get(newFile.ID)
+			retrieved, err := mr.Get(ctx, newFile.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(retrieved.CreatedAt).To(BeTemporally(">", before))
 
-			_ = mr.Delete(newFile.ID)
+			_ = mr.Delete(ctx, newFile.ID)
 		})
 
 		It("preserves CreatedAt when inserting a new file with non-zero CreatedAt", func() {
@@ -321,13 +322,13 @@ var _ = Describe("MediaRepository", func() {
 				Path:      "test/created-at-preserved.mp3",
 				CreatedAt: originalTime,
 			}
-			Expect(mr.Put(&newFile)).To(Succeed())
+			Expect(mr.Put(ctx, &newFile)).To(Succeed())
 
-			retrieved, err := mr.Get(newFile.ID)
+			retrieved, err := mr.Get(ctx, newFile.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(retrieved.CreatedAt).To(BeTemporally("~", originalTime, time.Second))
 
-			_ = mr.Delete(newFile.ID)
+			_ = mr.Delete(ctx, newFile.ID)
 		})
 
 		It("does not reset CreatedAt when updating an existing file", func() {
@@ -340,7 +341,7 @@ var _ = Describe("MediaRepository", func() {
 				Title:     "Original Title",
 				CreatedAt: originalTime,
 			}
-			Expect(mr.Put(&newFile)).To(Succeed())
+			Expect(mr.Put(ctx, &newFile)).To(Succeed())
 
 			// Update the file with a new title but zero CreatedAt
 			updatedFile := model.MediaFile{
@@ -350,66 +351,66 @@ var _ = Describe("MediaRepository", func() {
 				Title:     "Updated Title",
 				// CreatedAt is zero - should NOT overwrite the stored value
 			}
-			Expect(mr.Put(&updatedFile)).To(Succeed())
+			Expect(mr.Put(ctx, &updatedFile)).To(Succeed())
 
-			retrieved, err := mr.Get(fileID)
+			retrieved, err := mr.Get(ctx, fileID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(retrieved.Title).To(Equal("Updated Title"))
 			// CreatedAt should still be the original time (not reset)
 			Expect(retrieved.CreatedAt).To(BeTemporally("~", originalTime, time.Second))
 
-			_ = mr.Delete(fileID)
+			_ = mr.Delete(ctx, fileID)
 		})
 	})
 
 	It("checks existence of mediafiles in the DB", func() {
-		Expect(mr.Exists(songAntenna.ID)).To(BeTrue())
-		Expect(mr.Exists("666")).To(BeFalse())
+		Expect(mr.Exists(ctx, songAntenna.ID)).To(BeTrue())
+		Expect(mr.Exists(ctx, "666")).To(BeFalse())
 	})
 
 	It("delete tracks by id", func() {
 		newID := id.NewRandom()
-		Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID})).To(Succeed())
+		Expect(mr.Put(ctx, &model.MediaFile{LibraryID: 1, ID: newID})).To(Succeed())
 
-		Expect(mr.Delete(newID)).To(Succeed())
+		Expect(mr.Delete(ctx, newID)).To(Succeed())
 
-		_, err := mr.Get(newID)
+		_, err := mr.Get(ctx, newID)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
 	It("deletes all missing files", func() {
 		new1 := model.MediaFile{ID: id.NewRandom(), LibraryID: 1}
 		new2 := model.MediaFile{ID: id.NewRandom(), LibraryID: 1}
-		Expect(mr.Put(&new1)).To(Succeed())
-		Expect(mr.Put(&new2)).To(Succeed())
-		Expect(mr.MarkMissing(true, &new1, &new2)).To(Succeed())
+		Expect(mr.Put(ctx, &new1)).To(Succeed())
+		Expect(mr.Put(ctx, &new2)).To(Succeed())
+		Expect(mr.MarkMissing(ctx, true, &new1, &new2)).To(Succeed())
 
 		adminCtx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid", IsAdmin: true})
-		adminRepo := NewMediaFileRepository(adminCtx, GetDBXBuilder())
+		adminRepo := NewMediaFileRepository(GetDBXBuilder())
 
 		// Ensure the files are marked as missing and we have 2 of them
-		count, err := adminRepo.CountAll(model.QueryOptions{Filters: squirrel.Eq{"missing": true}})
+		count, err := adminRepo.CountAll(adminCtx, model.QueryOptions{Filters: squirrel.Eq{"missing": true}})
 		Expect(count).To(BeNumerically("==", 2))
 		Expect(err).ToNot(HaveOccurred())
 
-		count, err = adminRepo.DeleteAllMissing()
+		count, err = adminRepo.DeleteAllMissing(adminCtx)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(count).To(BeNumerically("==", 2))
 
-		_, err = mr.Get(new1.ID)
+		_, err = mr.Get(ctx, new1.ID)
 		Expect(err).To(MatchError(model.ErrNotFound))
-		_, err = mr.Get(new2.ID)
+		_, err = mr.Get(ctx, new2.ID)
 		Expect(err).To(MatchError(model.ErrNotFound))
 	})
 
 	Context("Annotations", func() {
 		It("increments play count when the tracks does not have annotations", func() {
 			id := "incplay.firsttime"
-			Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: id})).To(BeNil())
+			Expect(mr.Put(ctx, &model.MediaFile{LibraryID: 1, ID: id})).To(BeNil())
 			playDate := time.Now()
-			Expect(mr.IncPlayCount(id, playDate)).To(BeNil())
+			Expect(mr.IncPlayCount(ctx, id, playDate)).To(BeNil())
 
-			mf, err := mr.Get(id)
+			mf, err := mr.Get(ctx, id)
 			Expect(err).To(BeNil())
 
 			Expect(mf.PlayDate.Unix()).To(Equal(playDate.Unix()))
@@ -425,85 +426,85 @@ var _ = Describe("MediaRepository", func() {
 
 			It("returns 0 when no ratings exist", func() {
 				newID := id.NewRandom()
-				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "test/no-rating.mp3"})).To(Succeed())
+				Expect(mr.Put(ctx, &model.MediaFile{LibraryID: 1, ID: newID, Path: "test/no-rating.mp3"})).To(Succeed())
 
-				mf, err := mr.Get(newID)
+				mf, err := mr.Get(ctx, newID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mf.AverageRating).To(Equal(0.0))
 
-				_, _ = raw.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
 			})
 
 			It("returns the user's rating as average when only one user rated", func() {
 				newID := id.NewRandom()
-				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "test/single-rating.mp3"})).To(Succeed())
-				Expect(mr.SetRating(5, newID)).To(Succeed())
+				Expect(mr.Put(ctx, &model.MediaFile{LibraryID: 1, ID: newID, Path: "test/single-rating.mp3"})).To(Succeed())
+				Expect(mr.SetRating(ctx, 5, newID)).To(Succeed())
 
-				mf, err := mr.Get(newID)
+				mf, err := mr.Get(ctx, newID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mf.AverageRating).To(Equal(5.0))
 
-				_, _ = raw.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
-				_, _ = raw.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
 			})
 
 			It("calculates average across multiple users", func() {
 				newID := id.NewRandom()
-				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "test/multi-rating.mp3"})).To(Succeed())
+				Expect(mr.Put(ctx, &model.MediaFile{LibraryID: 1, ID: newID, Path: "test/multi-rating.mp3"})).To(Succeed())
 
-				Expect(mr.SetRating(3, newID)).To(Succeed())
+				Expect(mr.SetRating(ctx, 3, newID)).To(Succeed())
 
 				user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
-				user2Repo := NewMediaFileRepository(user2Ctx, GetDBXBuilder())
-				Expect(user2Repo.SetRating(5, newID)).To(Succeed())
+				user2Repo := NewMediaFileRepository(GetDBXBuilder())
+				Expect(user2Repo.SetRating(user2Ctx, 5, newID)).To(Succeed())
 
-				mf, err := mr.Get(newID)
+				mf, err := mr.Get(ctx, newID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mf.AverageRating).To(Equal(4.0))
 
-				_, _ = raw.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
-				_, _ = raw.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
 			})
 
 			It("excludes zero ratings from average calculation", func() {
 				newID := id.NewRandom()
-				Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: newID, Path: "test/zero-excluded.mp3"})).To(Succeed())
+				Expect(mr.Put(ctx, &model.MediaFile{LibraryID: 1, ID: newID, Path: "test/zero-excluded.mp3"})).To(Succeed())
 
-				Expect(mr.SetRating(4, newID)).To(Succeed())
+				Expect(mr.SetRating(ctx, 4, newID)).To(Succeed())
 
 				user2Ctx := request.WithUser(GinkgoT().Context(), regularUser)
-				user2Repo := NewMediaFileRepository(user2Ctx, GetDBXBuilder())
-				Expect(user2Repo.SetRating(0, newID)).To(Succeed())
+				user2Repo := NewMediaFileRepository(GetDBXBuilder())
+				Expect(user2Repo.SetRating(user2Ctx, 0, newID)).To(Succeed())
 
-				mf, err := mr.Get(newID)
+				mf, err := mr.Get(ctx, newID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mf.AverageRating).To(Equal(4.0))
 
-				_, _ = raw.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
-				_, _ = raw.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": newID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete("media_file").Where(squirrel.Eq{"id": newID}))
 			})
 		})
 
 		It("preserves play date if and only if provided date is older", func() {
 			id := "incplay.playdate"
-			Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: id})).To(BeNil())
+			Expect(mr.Put(ctx, &model.MediaFile{LibraryID: 1, ID: id})).To(BeNil())
 			playDate := time.Now()
-			Expect(mr.IncPlayCount(id, playDate)).To(BeNil())
-			mf, err := mr.Get(id)
+			Expect(mr.IncPlayCount(ctx, id, playDate)).To(BeNil())
+			mf, err := mr.Get(ctx, id)
 			Expect(err).To(BeNil())
 			Expect(mf.PlayDate.Unix()).To(Equal(playDate.Unix()))
 			Expect(mf.PlayCount).To(Equal(int64(1)))
 
 			playDateLate := playDate.AddDate(0, 0, 1)
-			Expect(mr.IncPlayCount(id, playDateLate)).To(BeNil())
-			mf, err = mr.Get(id)
+			Expect(mr.IncPlayCount(ctx, id, playDateLate)).To(BeNil())
+			mf, err = mr.Get(ctx, id)
 			Expect(err).To(BeNil())
 			Expect(mf.PlayDate.Unix()).To(Equal(playDateLate.Unix()))
 			Expect(mf.PlayCount).To(Equal(int64(2)))
 
 			playDateEarly := playDate.AddDate(0, 0, -1)
-			Expect(mr.IncPlayCount(id, playDateEarly)).To(BeNil())
-			mf, err = mr.Get(id)
+			Expect(mr.IncPlayCount(ctx, id, playDateEarly)).To(BeNil())
+			mf, err = mr.Get(ctx, id)
 			Expect(err).To(BeNil())
 			Expect(mf.PlayDate.Unix()).To(Equal(playDateLate.Unix()))
 			Expect(mf.PlayCount).To(Equal(int64(3)))
@@ -511,12 +512,12 @@ var _ = Describe("MediaRepository", func() {
 
 		It("increments play count on newly starred items", func() {
 			id := "star.incplay"
-			Expect(mr.Put(&model.MediaFile{LibraryID: 1, ID: id})).To(BeNil())
-			Expect(mr.SetStar(true, id)).To(BeNil())
+			Expect(mr.Put(ctx, &model.MediaFile{LibraryID: 1, ID: id})).To(BeNil())
+			Expect(mr.SetStar(ctx, true, id)).To(BeNil())
 			playDate := time.Now()
-			Expect(mr.IncPlayCount(id, playDate)).To(BeNil())
+			Expect(mr.IncPlayCount(ctx, id, playDate)).To(BeNil())
 
-			mf, err := mr.Get(id)
+			mf, err := mr.Get(ctx, id)
 			Expect(err).To(BeNil())
 
 			Expect(mf.PlayDate.Unix()).To(Equal(playDate.Unix()))
@@ -555,7 +556,7 @@ var _ = Describe("MediaRepository", func() {
 
 				// Insert test data first
 				for i := range testMediaFiles {
-					Expect(mr.Put(&testMediaFiles[i])).To(Succeed())
+					Expect(mr.Put(ctx, &testMediaFiles[i])).To(Succeed())
 				}
 
 				// Then manually update timestamps using direct SQL to bypass the repository logic
@@ -597,7 +598,7 @@ var _ = Describe("MediaRepository", func() {
 			AfterEach(func() {
 				// Clean up test data
 				for _, mf := range testMediaFiles {
-					_ = mr.Delete(mf.ID)
+					_ = mr.Delete(ctx, mf.ID)
 				}
 			})
 
@@ -607,14 +608,12 @@ var _ = Describe("MediaRepository", func() {
 				BeforeEach(func() {
 					conf.Server.RecentlyAddedByModTime = false
 					// Create repository AFTER setting config
-					ctx := log.NewContext(GinkgoT().Context())
-					ctx = request.WithUser(ctx, model.User{ID: "userid"})
-					testRepo = NewMediaFileRepository(ctx, GetDBXBuilder())
+					testRepo = NewMediaFileRepository(GetDBXBuilder())
 				})
 
 				It("sorts by created_at", func() {
 					// Get results sorted by recently_added (should use created_at)
-					results, err := testRepo.GetAll(model.QueryOptions{
+					results, err := testRepo.GetAll(ctx, model.QueryOptions{
 						Sort:    "recently_added",
 						Order:   "desc",
 						Filters: squirrel.Eq{"media_file.id": []string{testMediaFiles[0].ID, testMediaFiles[1].ID, testMediaFiles[2].ID}},
@@ -630,7 +629,7 @@ var _ = Describe("MediaRepository", func() {
 
 				It("sorts in ascending order when specified", func() {
 					// Get results sorted by recently_added in ascending order
-					results, err := testRepo.GetAll(model.QueryOptions{
+					results, err := testRepo.GetAll(ctx, model.QueryOptions{
 						Sort:    "recently_added",
 						Order:   "asc",
 						Filters: squirrel.Eq{"media_file.id": []string{testMediaFiles[0].ID, testMediaFiles[1].ID, testMediaFiles[2].ID}},
@@ -651,14 +650,12 @@ var _ = Describe("MediaRepository", func() {
 				BeforeEach(func() {
 					conf.Server.RecentlyAddedByModTime = true
 					// Create repository AFTER setting config
-					ctx := log.NewContext(GinkgoT().Context())
-					ctx = request.WithUser(ctx, model.User{ID: "userid"})
-					testRepo = NewMediaFileRepository(ctx, GetDBXBuilder())
+					testRepo = NewMediaFileRepository(GetDBXBuilder())
 				})
 
 				It("sorts by updated_at", func() {
 					// Get results sorted by recently_added (should use updated_at)
-					results, err := testRepo.GetAll(model.QueryOptions{
+					results, err := testRepo.GetAll(ctx, model.QueryOptions{
 						Sort:    "recently_added",
 						Order:   "desc",
 						Filters: squirrel.Eq{"media_file.id": []string{testMediaFiles[0].ID, testMediaFiles[1].ID, testMediaFiles[2].ID}},
@@ -677,7 +674,7 @@ var _ = Describe("MediaRepository", func() {
 				conf.Server.RecentlyAddedByModTime = false
 				ctx := log.NewContext(GinkgoT().Context())
 				ctx = request.WithUser(ctx, model.User{ID: "userid"})
-				repo := NewMediaFileRepository(ctx, GetDBXBuilder())
+				repo := NewMediaFileRepository(GetDBXBuilder())
 
 				ids := []string{testMediaFiles[0].ID, testMediaFiles[1].ID, testMediaFiles[2].ID}
 				sameTime := time.Date(2024, 3, 1, 0, 0, 0, 0, time.UTC)
@@ -687,7 +684,7 @@ var _ = Describe("MediaRepository", func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				order := func() []string {
-					res, err := repo.GetAll(model.QueryOptions{
+					res, err := repo.GetAll(ctx, model.QueryOptions{
 						Sort: "recently_added", Order: "desc",
 						Filters: squirrel.Eq{"media_file.id": ids}})
 					Expect(err).ToNot(HaveOccurred())
@@ -709,20 +706,20 @@ var _ = Describe("MediaRepository", func() {
 
 		BeforeEach(func() {
 			mfWithoutAnnotation = model.MediaFile{ID: "no-annotation-file", LibraryID: 1, Path: "test/no-annotation.mp3", Title: "No Annotation"}
-			Expect(mr.Put(&mfWithoutAnnotation)).To(Succeed())
+			Expect(mr.Put(ctx, &mfWithoutAnnotation)).To(Succeed())
 		})
 
 		AfterEach(func() {
-			_ = mr.Delete(mfWithoutAnnotation.ID)
+			_ = mr.Delete(ctx, mfWithoutAnnotation.ID)
 		})
 
 		Describe("starred", func() {
 			It("false includes items without annotations", func() {
-				res, err := mr.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+				res, err := mr.ReadAll(ctx, rest.QueryOptions{
 					Filters: map[string]any{"starred": "false"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				files := res.(model.MediaFiles)
+				files := res
 
 				var found bool
 				for _, f := range files {
@@ -735,11 +732,11 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It("true excludes items without annotations", func() {
-				res, err := mr.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+				res, err := mr.ReadAll(ctx, rest.QueryOptions{
 					Filters: map[string]any{"starred": "true"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				files := res.(model.MediaFiles)
+				files := res
 
 				for _, f := range files {
 					Expect(f.ID).ToNot(Equal(mfWithoutAnnotation.ID))
@@ -749,11 +746,11 @@ var _ = Describe("MediaRepository", func() {
 
 		Describe("path", func() {
 			It("matches files whose path starts with the given prefix", func() {
-				res, err := mr.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+				res, err := mr.ReadAll(ctx, rest.QueryOptions{
 					Filters: map[string]any{"path": "test/"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				files := res.(model.MediaFiles)
+				files := res
 
 				var found bool
 				for _, f := range files {
@@ -766,11 +763,11 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It("excludes files whose path does not start with the given prefix", func() {
-				res, err := mr.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+				res, err := mr.ReadAll(ctx, rest.QueryOptions{
 					Filters: map[string]any{"path": "no-such-prefix/"},
 				})
 				Expect(err).ToNot(HaveOccurred())
-				files := res.(model.MediaFiles)
+				files := res
 				Expect(files).To(BeEmpty())
 			})
 		})
@@ -779,7 +776,7 @@ var _ = Describe("MediaRepository", func() {
 	Describe("Search", func() {
 		Context("text search", func() {
 			It("finds media files by title", func() {
-				results, err := mr.Search("Antenna", model.QueryOptions{Max: 10})
+				results, err := mr.Search(ctx, "Antenna", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(3)) // songAntenna, songAntennaWithLyrics, songAntenna2
 				for _, result := range results {
@@ -788,7 +785,7 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It("finds media files case insensitively", func() {
-				results, err := mr.Search("antenna", model.QueryOptions{Max: 10})
+				results, err := mr.Search(ctx, "antenna", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(3))
 				for _, result := range results {
@@ -797,7 +794,7 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It("returns empty result when no matches found", func() {
-				results, err := mr.Search("nonexistent", model.QueryOptions{Max: 10})
+				results, err := mr.Search(ctx, "nonexistent", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 			})
@@ -820,17 +817,17 @@ var _ = Describe("MediaRepository", func() {
 				}
 
 				// Insert the test media file into the database
-				err := mr.Put(&mediaFileWithMBID)
+				err := mr.Put(ctx, &mediaFileWithMBID)
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			AfterEach(func() {
 				// Clean up test data using direct SQL
-				_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": mediaFileWithMBID.ID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": mediaFileWithMBID.ID}))
 			})
 
 			It("finds media file by mbz_recording_id", func() {
-				results, err := mr.Search("550e8400-e29b-41d4-a716-446655440020", model.QueryOptions{Max: 10})
+				results, err := mr.Search(ctx, "550e8400-e29b-41d4-a716-446655440020", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(1))
 				Expect(results[0].ID).To(Equal("test-mbid-mediafile"))
@@ -838,7 +835,7 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It("finds media file by mbz_release_track_id", func() {
-				results, err := mr.Search("550e8400-e29b-41d4-a716-446655440021", model.QueryOptions{Max: 10})
+				results, err := mr.Search(ctx, "550e8400-e29b-41d4-a716-446655440021", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(1))
 				Expect(results[0].ID).To(Equal("test-mbid-mediafile"))
@@ -846,7 +843,7 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It("returns empty result when MBID is not found", func() {
-				results, err := mr.Search("550e8400-e29b-41d4-a716-446655440099", model.QueryOptions{Max: 10})
+				results, err := mr.Search(ctx, "550e8400-e29b-41d4-a716-446655440099", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 			})
@@ -862,22 +859,22 @@ var _ = Describe("MediaRepository", func() {
 					Missing:        true,
 				}
 
-				err := mr.Put(&missingMediaFile)
+				err := mr.Put(ctx, &missingMediaFile)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Search never returns missing media files (hardcoded behavior)
-				results, err := mr.Search("550e8400-e29b-41d4-a716-446655440022", model.QueryOptions{Max: 10})
+				results, err := mr.Search(ctx, "550e8400-e29b-41d4-a716-446655440022", model.QueryOptions{Max: 10})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 
 				// Clean up
-				_, _ = raw.executeSQL(squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": missingMediaFile.ID}))
+				_, _ = raw.executeSQL(ctx, squirrel.Delete(raw.tableName).Where(squirrel.Eq{"id": missingMediaFile.ID}))
 			})
 		})
 
 		Context("empty query (natural order pagination)", func() {
 			It("returns all non-missing files in natural order", func() {
-				results, err := mr.Search("", model.QueryOptions{Max: 1000})
+				results, err := mr.Search(ctx, "", model.QueryOptions{Max: 1000})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).ToNot(BeEmpty())
 				for _, result := range results {
@@ -886,22 +883,22 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It(`treats quoted empty query ("") the same as empty`, func() {
-				all, err := mr.Search("", model.QueryOptions{Max: 1000})
+				all, err := mr.Search(ctx, "", model.QueryOptions{Max: 1000})
 				Expect(err).ToNot(HaveOccurred())
-				quoted, err := mr.Search(`""`, model.QueryOptions{Max: 1000})
+				quoted, err := mr.Search(ctx, `""`, model.QueryOptions{Max: 1000})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(quoted).To(HaveLen(len(all)))
 			})
 
 			It("paginates without overlaps or gaps", func() {
-				all, err := mr.Search("", model.QueryOptions{Max: 1000})
+				all, err := mr.Search(ctx, "", model.QueryOptions{Max: 1000})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(len(all)).To(BeNumerically(">", 3))
 
 				var paged model.MediaFiles
 				pageSize := 3
 				for offset := 0; offset < len(all); offset += pageSize {
-					page, err := mr.Search("", model.QueryOptions{Max: pageSize, Offset: offset})
+					page, err := mr.Search(ctx, "", model.QueryOptions{Max: pageSize, Offset: offset})
 					Expect(err).ToNot(HaveOccurred())
 					paged = append(paged, page...)
 				}
@@ -912,7 +909,7 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It("returns empty page when offset is beyond the total", func() {
-				results, err := mr.Search("", model.QueryOptions{Max: 10, Offset: 100000})
+				results, err := mr.Search(ctx, "", model.QueryOptions{Max: 10, Offset: 100000})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty())
 			})
@@ -926,41 +923,41 @@ var _ = Describe("MediaRepository", func() {
 
 		BeforeEach(func() {
 			ctx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid"})
-			pr = NewPlaylistRepository(ctx, GetDBXBuilder())
+			pr = NewPlaylistRepository(GetDBXBuilder())
 			prev = model.MediaFile{ID: "reassign-prev", LibraryID: 1, Path: "reassign/prev.mp3", Title: "Prev"}
 			next = model.MediaFile{ID: "reassign-next", LibraryID: 1, Path: "reassign/next.mp3", Title: "Next"}
-			Expect(mr.Put(&prev)).To(Succeed())
-			Expect(mr.Put(&next)).To(Succeed())
+			Expect(mr.Put(ctx, &prev)).To(Succeed())
+			Expect(mr.Put(ctx, &next)).To(Succeed())
 			pls = model.Playlist{Name: "Reassign", OwnerID: "userid"}
 			pls.AddMediaFilesByID([]string{prev.ID})
-			Expect(pr.Put(&pls)).To(Succeed())
+			Expect(pr.Put(ctx, &pls)).To(Succeed())
 		})
 
 		AfterEach(func() {
-			_ = pr.Delete(pls.ID)
-			_ = mr.Delete(prev.ID)
-			_ = mr.Delete(next.ID)
-			_, _ = mr.(*mediaFileRepository).executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
-			_, _ = mr.(*mediaFileRepository).executeSQL(squirrel.Delete("bookmark").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
-			_, _ = mr.(*mediaFileRepository).executeSQL(squirrel.Delete("scrobbles").Where(squirrel.Eq{"media_file_id": []string{prev.ID, next.ID}}))
-			_, _ = mr.(*mediaFileRepository).executeSQL(squirrel.Delete("scrobble_buffer").Where(squirrel.Eq{"media_file_id": []string{prev.ID, next.ID}}))
+			_ = pr.Delete(ctx, pls.ID)
+			_ = mr.Delete(ctx, prev.ID)
+			_ = mr.Delete(ctx, next.ID)
+			_, _ = mr.(*mediaFileRepository).executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
+			_, _ = mr.(*mediaFileRepository).executeSQL(ctx, squirrel.Delete("bookmark").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
+			_, _ = mr.(*mediaFileRepository).executeSQL(ctx, squirrel.Delete("scrobbles").Where(squirrel.Eq{"media_file_id": []string{prev.ID, next.ID}}))
+			_, _ = mr.(*mediaFileRepository).executeSQL(ctx, squirrel.Delete("scrobble_buffer").Where(squirrel.Eq{"media_file_id": []string{prev.ID, next.ID}}))
 		})
 
 		It("moves annotations, bookmarks and playlist entries onto the new id", func() {
-			Expect(mr.SetRating(5, prev.ID)).To(Succeed())
-			Expect(mr.AddBookmark(prev.ID, "here", 42)).To(Succeed())
+			Expect(mr.SetRating(ctx, 5, prev.ID)).To(Succeed())
+			Expect(mr.AddBookmark(ctx, prev.ID, "here", 42)).To(Succeed())
 
-			Expect(mr.ReassignReferences(prev.ID, next.ID)).To(Succeed())
+			Expect(mr.ReassignReferences(ctx, prev.ID, next.ID)).To(Succeed())
 
-			got, err := mr.Get(next.ID)
+			got, err := mr.Get(ctx, next.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Rating).To(Equal(5))
 
-			bookmarks, err := mr.GetBookmarks()
+			bookmarks, err := mr.GetBookmarks(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(bookmarks).To(ContainElement(HaveField("Item.ID", next.ID)))
 
-			withTracks, err := pr.GetWithTracks(pls.ID, false, false)
+			withTracks, err := pr.GetWithTracks(ctx, pls.ID, false, false)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(withTracks.Tracks).To(HaveLen(1))
 			Expect(withTracks.Tracks[0].MediaFileID).To(Equal(next.ID))
@@ -968,51 +965,52 @@ var _ = Describe("MediaRepository", func() {
 
 		It("moves scrobbles and buffered scrobbles onto the new id", func() {
 			ctx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid"})
-			scrobbles := NewScrobbleRepository(ctx, GetDBXBuilder())
-			buffer := NewScrobbleBufferRepository(ctx, GetDBXBuilder())
-			Expect(scrobbles.RecordScrobble(prev.ID, time.Now())).To(Succeed())
-			Expect(buffer.Enqueue("lastfm", "userid", prev.ID, time.Now())).To(Succeed())
+			scrobbles := NewScrobbleRepository(GetDBXBuilder())
+			buffer := NewScrobbleBufferRepository(GetDBXBuilder())
+			Expect(scrobbles.RecordScrobble(ctx, prev.ID, time.Now())).To(Succeed())
+			Expect(buffer.Enqueue(ctx, "lastfm", "userid", prev.ID, time.Now())).To(Succeed())
 
-			Expect(mr.ReassignReferences(prev.ID, next.ID)).To(Succeed())
-			Expect(mr.Delete(prev.ID)).To(Succeed())
+			Expect(mr.ReassignReferences(ctx, prev.ID, next.ID)).To(Succeed())
+			Expect(mr.Delete(ctx, prev.ID)).To(Succeed())
 
-			all, err := scrobbles.GetAll()
+			all, err := scrobbles.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			mine := slice.Map(slice.Filter(all, func(sc model.Scrobble) bool {
 				return sc.MediaFileID == prev.ID || sc.MediaFileID == next.ID
 			}), func(sc model.Scrobble) string { return sc.MediaFileID })
 			Expect(mine).To(ConsistOf(next.ID))
 
-			entry, err := buffer.Next("lastfm", "userid")
+			entry, err := buffer.Next(ctx, "lastfm", "userid")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(entry).ToNot(BeNil())
 			Expect(entry.MediaFile.ID).To(Equal(next.ID))
 		})
 
 		It("recomputes the average rating after merging another user's annotation", func() {
-			other := NewMediaFileRepository(request.WithUser(log.NewContext(context.TODO()), model.User{ID: "2222"}), GetDBXBuilder())
-			Expect(mr.SetRating(5, next.ID)).To(Succeed())
-			Expect(other.SetRating(3, prev.ID)).To(Succeed())
+			otherCtx := request.WithUser(ctx, model.User{ID: "2222"})
+			other := NewMediaFileRepository(GetDBXBuilder())
+			Expect(mr.SetRating(ctx, 5, next.ID)).To(Succeed())
+			Expect(other.SetRating(otherCtx, 3, prev.ID)).To(Succeed())
 
-			Expect(mr.ReassignReferences(prev.ID, next.ID)).To(Succeed())
+			Expect(mr.ReassignReferences(ctx, prev.ID, next.ID)).To(Succeed())
 
-			got, err := mr.Get(next.ID)
+			got, err := mr.Get(ctx, next.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.AverageRating).To(Equal(4.0))
 		})
 
 		It("keeps the new id's own annotation and bookmark when both exist", func() {
-			Expect(mr.SetRating(5, prev.ID)).To(Succeed())
-			Expect(mr.SetRating(1, next.ID)).To(Succeed())
-			Expect(mr.AddBookmark(prev.ID, "prev", 42)).To(Succeed())
-			Expect(mr.AddBookmark(next.ID, "next", 7)).To(Succeed())
+			Expect(mr.SetRating(ctx, 5, prev.ID)).To(Succeed())
+			Expect(mr.SetRating(ctx, 1, next.ID)).To(Succeed())
+			Expect(mr.AddBookmark(ctx, prev.ID, "prev", 42)).To(Succeed())
+			Expect(mr.AddBookmark(ctx, next.ID, "next", 7)).To(Succeed())
 
-			Expect(mr.ReassignReferences(prev.ID, next.ID)).To(Succeed())
+			Expect(mr.ReassignReferences(ctx, prev.ID, next.ID)).To(Succeed())
 
-			got, err := mr.Get(next.ID)
+			got, err := mr.Get(ctx, next.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Rating).To(Equal(1))
-			bookmarks, err := mr.GetBookmarks()
+			bookmarks, err := mr.GetBookmarks(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(bookmarks).To(ContainElement(SatisfyAll(HaveField("Item.ID", next.ID), HaveField("Comment", "next"))))
 		})
@@ -1034,39 +1032,39 @@ var _ = Describe("MediaRepository", func() {
 				{ID: "findpath-6", LibraryID: 1, Path: "1999: A Different Life/01.mp3", Title: "Numeric colon"},
 			}
 			for _, mf := range testFiles {
-				Expect(mr.Put(&mf)).To(Succeed())
+				Expect(mr.Put(ctx, &mf)).To(Succeed())
 			}
 		})
 
 		AfterEach(func() {
 			for _, mf := range testFiles {
-				_ = mr.Delete(mf.ID)
+				_ = mr.Delete(ctx, mf.ID)
 			}
 		})
 
 		It("treats a path whose prefix is not a library id as unqualified", func() {
-			results, err := mr.FindByPaths([]string{"Bach: Goldberg Variations/01.mp3"})
+			results, err := mr.FindByPaths(ctx, []string{"Bach: Goldberg Variations/01.mp3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].ID).To(Equal("findpath-5"))
 		})
 
 		It("finds a plain path whose colon prefix looks like a library id", func() {
-			results, err := mr.FindByPaths([]string{"1999: A Different Life/01.mp3"})
+			results, err := mr.FindByPaths(ctx, []string{"1999: A Different Life/01.mp3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].ID).To(Equal("findpath-6"))
 		})
 
 		It("splits only the first colon of a library-qualified path", func() {
-			results, err := mr.FindByPaths([]string{"1:Bach: Goldberg Variations/01.mp3"})
+			results, err := mr.FindByPaths(ctx, []string{"1:Bach: Goldberg Variations/01.mp3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].ID).To(Equal("findpath-5"))
 		})
 
 		It("finds files by exact path", func() {
-			results, err := mr.FindByPaths([]string{"1:artist/Album/track.mp3"})
+			results, err := mr.FindByPaths(ctx, []string{"1:artist/Album/track.mp3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].ID).To(Equal("findpath-1"))
@@ -1074,7 +1072,7 @@ var _ = Describe("MediaRepository", func() {
 
 		It("finds files case-insensitively for ASCII characters (NOCASE)", func() {
 			// SQLite's COLLATE NOCASE handles ASCII case-insensitivity
-			results, err := mr.FindByPaths([]string{"1:ARTIST/ALBUM/TRACK.MP3"})
+			results, err := mr.FindByPaths(ctx, []string{"1:ARTIST/ALBUM/TRACK.MP3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].ID).To(Equal("findpath-1"))
@@ -1083,20 +1081,20 @@ var _ = Describe("MediaRepository", func() {
 		It("finds fullwidth characters only with exact case match (SQLite NOCASE limitation)", func() {
 			// SQLite's NOCASE does NOT handle fullwidth uppercase/lowercase equivalence
 			// The DB has fullwidth uppercase ＡＣＲＯＳＳ, searching with exact match should work
-			results, err := mr.FindByPaths([]string{"1:plex/02 - ＡＣＲＯＳＳ.flac"})
+			results, err := mr.FindByPaths(ctx, []string{"1:plex/02 - ＡＣＲＯＳＳ.flac"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].ID).To(Equal("findpath-3"))
 
 			// Searching with fullwidth lowercase ａｃｒｏｓｓ should NOT match
 			// (this is the SQLite limitation that requires exact matching for non-ASCII)
-			results, err = mr.FindByPaths([]string{"1:plex/02 - ａｃｒｏｓｓ.flac"})
+			results, err = mr.FindByPaths(ctx, []string{"1:plex/02 - ａｃｒｏｓｓ.flac"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(BeEmpty())
 		})
 
 		It("returns multiple files when querying multiple paths", func() {
-			results, err := mr.FindByPaths([]string{
+			results, err := mr.FindByPaths(ctx, []string{
 				"1:artist/Album/track.mp3",
 				"1:artist/Album/UPPER.mp3",
 			})
@@ -1105,25 +1103,25 @@ var _ = Describe("MediaRepository", func() {
 		})
 
 		It("returns empty slice for non-existent paths", func() {
-			results, err := mr.FindByPaths([]string{"1:nonexistent/path.mp3"})
+			results, err := mr.FindByPaths(ctx, []string{"1:nonexistent/path.mp3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(BeEmpty())
 		})
 
 		It("returns empty slice for empty input", func() {
-			results, err := mr.FindByPaths([]string{})
+			results, err := mr.FindByPaths(ctx, []string{})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(BeEmpty())
 		})
 
 		It("handles library-qualified paths correctly", func() {
 			// Library 1 should find the file
-			results, err := mr.FindByPaths([]string{"1:artist/Album/track.mp3"})
+			results, err := mr.FindByPaths(ctx, []string{"1:artist/Album/track.mp3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 
 			// Library 2 should NOT find it (file is in library 1)
-			results, err = mr.FindByPaths([]string{"2:artist/Album/track.mp3"})
+			results, err = mr.FindByPaths(ctx, []string{"2:artist/Album/track.mp3"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(BeEmpty())
 		})
@@ -1134,54 +1132,57 @@ var _ = Describe("MediaRepository", func() {
 
 			BeforeEach(func() {
 				adminCtx := request.WithUser(GinkgoT().Context(), adminUser)
-				lr := NewLibraryRepository(adminCtx, GetDBXBuilder())
+				lr := NewLibraryRepository(GetDBXBuilder())
 
 				// A second library the restricted user has no access to
 				otherLib = model.Library{ID: 0, Name: "Other Library", Path: "/other/lib"}
-				Expect(lr.Put(&otherLib)).To(Succeed())
+				Expect(lr.Put(adminCtx, &otherLib)).To(Succeed())
 
 				// A track that lives only in the other library (created as admin)
-				adminMr := NewMediaFileRepository(adminCtx, GetDBXBuilder())
-				Expect(adminMr.Put(&model.MediaFile{
+				adminMr := NewMediaFileRepository(GetDBXBuilder())
+				Expect(adminMr.Put(adminCtx, &model.MediaFile{
 					ID: "otherlib-track", LibraryID: otherLib.ID,
 					Path: "hidden/test.mp3", Title: "Hidden",
 				})).To(Succeed())
 
 				// Non-admin user with access to library 1 ONLY
 				restrictedUser = createUserWithLibraries("restricted-finder", []int{1})
-				ur := NewUserRepository(adminCtx, GetDBXBuilder())
-				Expect(ur.Put(&restrictedUser)).To(Succeed())
-				Expect(ur.SetUserLibraries(restrictedUser.ID, []int{1})).To(Succeed())
+				ur := NewUserRepository(GetDBXBuilder())
+				Expect(ur.Put(adminCtx, &restrictedUser)).To(Succeed())
+				Expect(ur.SetUserLibraries(adminCtx, restrictedUser.ID, []int{1})).To(Succeed())
 			})
 
 			AfterEach(func() {
 				adminCtx := request.WithUser(GinkgoT().Context(), adminUser)
-				_ = NewMediaFileRepository(adminCtx, GetDBXBuilder()).Delete("otherlib-track")
-				lr := NewLibraryRepository(adminCtx, GetDBXBuilder()).(*libraryRepository)
-				_ = lr.delete(squirrel.Eq{"id": otherLib.ID})
-				_ = NewUserRepository(adminCtx, GetDBXBuilder()).Delete(restrictedUser.ID)
+				_ = NewMediaFileRepository(GetDBXBuilder()).Delete(adminCtx, "otherlib-track")
+				lr := NewLibraryRepository(GetDBXBuilder()).(*libraryRepository)
+				_ = lr.delete(adminCtx, squirrel.Eq{"id": otherLib.ID})
+				_ = NewUserRepository(GetDBXBuilder()).Delete(adminCtx, restrictedUser.ID)
 			})
 
 			It("does not resolve paths in libraries the user cannot access", func() {
-				userMr := NewMediaFileRepository(request.WithUser(GinkgoT().Context(), restrictedUser), GetDBXBuilder())
+				userCtx := request.WithUser(ctx, restrictedUser)
+				userMr := NewMediaFileRepository(GetDBXBuilder())
 				qualified := fmt.Sprintf("%d:hidden/test.mp3", otherLib.ID)
-				results, err := userMr.FindByPaths([]string{qualified})
+				results, err := userMr.FindByPaths(userCtx, []string{qualified})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(BeEmpty(), "a track outside the user's libraries must not be resolvable")
 			})
 
 			It("still resolves the path for an admin", func() {
-				adminMr := NewMediaFileRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
+				adminCtx := request.WithUser(ctx, adminUser)
+				adminMr := NewMediaFileRepository(GetDBXBuilder())
 				qualified := fmt.Sprintf("%d:hidden/test.mp3", otherLib.ID)
-				results, err := adminMr.FindByPaths([]string{qualified})
+				results, err := adminMr.FindByPaths(adminCtx, []string{qualified})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(results).To(HaveLen(1))
 				Expect(results[0].ID).To(Equal("otherlib-track"))
 			})
 
 			It("resolves paths from multiple libraries in a single call", func() {
-				adminMr := NewMediaFileRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
-				results, err := adminMr.FindByPaths([]string{
+				adminCtx := request.WithUser(ctx, adminUser)
+				adminMr := NewMediaFileRepository(GetDBXBuilder())
+				results, err := adminMr.FindByPaths(adminCtx, []string{
 					"1:artist/Album/track.mp3",
 					fmt.Sprintf("%d:hidden/test.mp3", otherLib.ID),
 				})
@@ -1191,9 +1192,10 @@ var _ = Describe("MediaRepository", func() {
 			})
 
 			It("keeps each path scoped to its own library when several are queried", func() {
-				adminMr := NewMediaFileRepository(request.WithUser(GinkgoT().Context(), adminUser), GetDBXBuilder())
+				adminCtx := request.WithUser(ctx, adminUser)
+				adminMr := NewMediaFileRepository(GetDBXBuilder())
 				// Each path exists, but under the other library's ID, so neither must match.
-				results, err := adminMr.FindByPaths([]string{
+				results, err := adminMr.FindByPaths(adminCtx, []string{
 					fmt.Sprintf("%d:artist/Album/track.mp3", otherLib.ID),
 					"1:hidden/test.mp3",
 				})
@@ -1254,9 +1256,9 @@ var _ = Describe("MediaRepository", func() {
 		It("stores nil BPM and BitDepth as NULL and retrieves them as nil", func() {
 			newID := id.NewRandom()
 			mf := model.MediaFile{LibraryID: 1, ID: newID, Path: "test/bpm-nil.mp3"}
-			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(mr.Put(ctx, &mf)).To(Succeed())
 
-			retrieved, err := mr.Get(newID)
+			retrieved, err := mr.Get(ctx, newID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(retrieved.BPM).To(BeNil())
 			Expect(retrieved.BitDepth).To(BeNil())
@@ -1274,7 +1276,7 @@ var _ = Describe("MediaRepository", func() {
 			Expect(row.BPM).To(BeNil(), "bpm should be stored as NULL in the database")
 			Expect(row.BitDepth).To(BeNil(), "bit_depth should be stored as NULL in the database")
 
-			_ = mr.Delete(newID)
+			_ = mr.Delete(ctx, newID)
 		})
 
 		It("stores non-nil BPM and BitDepth and retrieves correct values", func() {
@@ -1282,16 +1284,16 @@ var _ = Describe("MediaRepository", func() {
 			bpm := 120
 			bitDepth := 24
 			mf := model.MediaFile{LibraryID: 1, ID: newID, Path: "test/bpm-set.mp3", BPM: &bpm, BitDepth: &bitDepth}
-			Expect(mr.Put(&mf)).To(Succeed())
+			Expect(mr.Put(ctx, &mf)).To(Succeed())
 
-			retrieved, err := mr.Get(newID)
+			retrieved, err := mr.Get(ctx, newID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(retrieved.BPM).ToNot(BeNil())
 			Expect(*retrieved.BPM).To(Equal(120))
 			Expect(retrieved.BitDepth).ToNot(BeNil())
 			Expect(*retrieved.BitDepth).To(Equal(24))
 
-			_ = mr.Delete(newID)
+			_ = mr.Delete(ctx, newID)
 		})
 	})
 
@@ -1326,34 +1328,34 @@ var _ = Describe("MediaRepository", func() {
 			restricted := model.User{ID: "restricted_mf_user", UserName: "rm", Name: "RM", Email: "rm@t.com"}
 			rctx := request.WithUser(GinkgoT().Context(), restricted)
 
-			Expect(mr.Exists(songAntenna.ID)).To(BeTrue(), "admin sees it")
-			Expect(NewMediaFileRepository(rctx, GetDBXBuilder()).Exists(songAntenna.ID)).To(BeFalse())
+			Expect(mr.Exists(ctx, songAntenna.ID)).To(BeTrue(), "admin sees it")
+			Expect(NewMediaFileRepository(GetDBXBuilder()).Exists(rctx, songAntenna.ID)).To(BeFalse())
 		})
 	})
 
 	Describe("MatchesCriteria", func() {
 		It("returns true when the track matches", func() {
 			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "Day"}}}
-			match, err := mr.MatchesCriteria(songDayInALife.ID, c)
+			match, err := mr.MatchesCriteria(ctx, songDayInALife.ID, c)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(match).To(BeTrue())
 		})
 		It("returns false when the track does not match", func() {
 			c := criteria.Criteria{Expression: criteria.All{criteria.Contains{"title": "Nickelback"}}}
-			match, err := mr.MatchesCriteria(songDayInALife.ID, c)
+			match, err := mr.MatchesCriteria(ctx, songDayInALife.ID, c)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(match).To(BeFalse())
 		})
 		It("treats missing annotations as their COALESCE default", func() {
 			// unrated track: rating coalesces to 0, so "rating < 4" matches
 			c := criteria.Criteria{Expression: criteria.All{criteria.Lt{"rating": 4}}}
-			match, err := mr.MatchesCriteria(songDayInALife.ID, c)
+			match, err := mr.MatchesCriteria(ctx, songDayInALife.ID, c)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(match).To(BeTrue())
 		})
 		It("returns an error for an invalid field", func() {
 			c := criteria.Criteria{Expression: criteria.All{criteria.Is{"bogusfield": 1}}}
-			_, err := mr.MatchesCriteria(songDayInALife.ID, c)
+			_, err := mr.MatchesCriteria(ctx, songDayInALife.ID, c)
 			Expect(err).To(HaveOccurred())
 		})
 	})
diff --git a/persistence/persistence.go b/persistence/persistence.go
index 589812266..44e944bff 100644
--- a/persistence/persistence.go
+++ b/persistence/persistence.go
@@ -4,7 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
-	"reflect"
+	"sync"
 	"time"
 
 	"github.com/navidrome/navidrome/db"
@@ -15,128 +15,144 @@ import (
 )
 
 type SQLStore struct {
-	db dbx.Builder
+	db           dbx.Builder
+	library      func() model.LibraryRepository
+	folder       func() model.FolderRepository
+	album        func() model.AlbumRepository
+	artist       func() model.ArtistRepository
+	mediaFile    func() model.MediaFileRepository
+	genre        func() model.GenreRepository
+	tag          func() model.TagRepository
+	playlist     func() model.PlaylistRepository
+	playQueue    func() model.PlayQueueRepository
+	transcoding  func() model.TranscodingRepository
+	player       func() model.PlayerRepository
+	radio        func() model.RadioRepository
+	share        func() model.ShareRepository
+	property     func() model.PropertyRepository
+	user         func() model.UserRepository
+	userProps    func() model.UserPropsRepository
+	scrobbleBuf  func() model.ScrobbleBufferRepository
+	scrobble     func() model.ScrobbleRepository
+	plugin       func() model.PluginRepository
+	artwork      func() model.ArtworkRepository
+	artworkQueue func() model.ArtworkQueueRepository
+}
+
+// Repositories are built on first use, so a transaction store only pays for the ones its block touches.
+func newSQLStore(db dbx.Builder) *SQLStore {
+	return &SQLStore{
+		db:           db,
+		library:      sync.OnceValue(func() model.LibraryRepository { return NewLibraryRepository(db) }),
+		folder:       sync.OnceValue(func() model.FolderRepository { return newFolderRepository(db) }),
+		album:        sync.OnceValue(func() model.AlbumRepository { return NewAlbumRepository(db) }),
+		artist:       sync.OnceValue(func() model.ArtistRepository { return NewArtistRepository(db) }),
+		mediaFile:    sync.OnceValue(func() model.MediaFileRepository { return NewMediaFileRepository(db) }),
+		genre:        sync.OnceValue(func() model.GenreRepository { return NewGenreRepository(db) }),
+		tag:          sync.OnceValue(func() model.TagRepository { return NewTagRepository(db) }),
+		playlist:     sync.OnceValue(func() model.PlaylistRepository { return NewPlaylistRepository(db) }),
+		playQueue:    sync.OnceValue(func() model.PlayQueueRepository { return NewPlayQueueRepository(db) }),
+		transcoding:  sync.OnceValue(func() model.TranscodingRepository { return NewTranscodingRepository(db) }),
+		player:       sync.OnceValue(func() model.PlayerRepository { return NewPlayerRepository(db) }),
+		radio:        sync.OnceValue(func() model.RadioRepository { return NewRadioRepository(db) }),
+		share:        sync.OnceValue(func() model.ShareRepository { return NewShareRepository(db) }),
+		property:     sync.OnceValue(func() model.PropertyRepository { return NewPropertyRepository(db) }),
+		user:         sync.OnceValue(func() model.UserRepository { return NewUserRepository(db) }),
+		userProps:    sync.OnceValue(func() model.UserPropsRepository { return NewUserPropsRepository(db) }),
+		scrobbleBuf:  sync.OnceValue(func() model.ScrobbleBufferRepository { return NewScrobbleBufferRepository(db) }),
+		scrobble:     sync.OnceValue(func() model.ScrobbleRepository { return NewScrobbleRepository(db) }),
+		plugin:       sync.OnceValue(func() model.PluginRepository { return NewPluginRepository(db) }),
+		artwork:      sync.OnceValue(func() model.ArtworkRepository { return NewArtworkRepository(db) }),
+		artworkQueue: sync.OnceValue(func() model.ArtworkQueueRepository { return NewArtworkQueueRepository(db) }),
+	}
 }
 
 func New(conn *sql.DB) model.DataStore {
-	return &SQLStore{db: dbx.NewFromDB(conn, db.Driver)}
+	return newSQLStore(dbx.NewFromDB(conn, db.Driver))
 }
 
-func (s *SQLStore) Album(ctx context.Context) model.AlbumRepository {
-	return NewAlbumRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Album() model.AlbumRepository {
+	return s.album()
 }
 
-func (s *SQLStore) Artist(ctx context.Context) model.ArtistRepository {
-	return NewArtistRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Artist() model.ArtistRepository {
+	return s.artist()
 }
 
-func (s *SQLStore) MediaFile(ctx context.Context) model.MediaFileRepository {
-	return NewMediaFileRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) MediaFile() model.MediaFileRepository {
+	return s.mediaFile()
 }
 
-func (s *SQLStore) Library(ctx context.Context) model.LibraryRepository {
-	return NewLibraryRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Library() model.LibraryRepository {
+	return s.library()
 }
 
-func (s *SQLStore) Folder(ctx context.Context) model.FolderRepository {
-	return newFolderRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Folder() model.FolderRepository {
+	return s.folder()
 }
 
-func (s *SQLStore) Genre(ctx context.Context) model.GenreRepository {
-	return NewGenreRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Genre() model.GenreRepository {
+	return s.genre()
 }
 
-func (s *SQLStore) Tag(ctx context.Context) model.TagRepository {
-	return NewTagRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Tag() model.TagRepository {
+	return s.tag()
 }
 
-func (s *SQLStore) PlayQueue(ctx context.Context) model.PlayQueueRepository {
-	return NewPlayQueueRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) PlayQueue() model.PlayQueueRepository {
+	return s.playQueue()
 }
 
-func (s *SQLStore) Playlist(ctx context.Context) model.PlaylistRepository {
-	return NewPlaylistRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Playlist() model.PlaylistRepository {
+	return s.playlist()
 }
 
-func (s *SQLStore) Property(ctx context.Context) model.PropertyRepository {
-	return NewPropertyRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Property() model.PropertyRepository {
+	return s.property()
 }
 
-func (s *SQLStore) Radio(ctx context.Context) model.RadioRepository {
-	return NewRadioRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Radio() model.RadioRepository {
+	return s.radio()
 }
 
-func (s *SQLStore) UserProps(ctx context.Context) model.UserPropsRepository {
-	return NewUserPropsRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) UserProps() model.UserPropsRepository {
+	return s.userProps()
 }
 
-func (s *SQLStore) Share(ctx context.Context) model.ShareRepository {
-	return NewShareRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Share() model.ShareRepository {
+	return s.share()
 }
 
-func (s *SQLStore) User(ctx context.Context) model.UserRepository {
-	return NewUserRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) User() model.UserRepository {
+	return s.user()
 }
 
-func (s *SQLStore) Transcoding(ctx context.Context) model.TranscodingRepository {
-	return NewTranscodingRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Transcoding() model.TranscodingRepository {
+	return s.transcoding()
 }
 
-func (s *SQLStore) Player(ctx context.Context) model.PlayerRepository {
-	return NewPlayerRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Player() model.PlayerRepository {
+	return s.player()
 }
 
-func (s *SQLStore) ScrobbleBuffer(ctx context.Context) model.ScrobbleBufferRepository {
-	return NewScrobbleBufferRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) ScrobbleBuffer() model.ScrobbleBufferRepository {
+	return s.scrobbleBuf()
 }
 
-func (s *SQLStore) Scrobble(ctx context.Context) model.ScrobbleRepository {
-	return NewScrobbleRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Scrobble() model.ScrobbleRepository {
+	return s.scrobble()
 }
 
-func (s *SQLStore) Plugin(ctx context.Context) model.PluginRepository {
-	return NewPluginRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Plugin() model.PluginRepository {
+	return s.plugin()
 }
 
-func (s *SQLStore) Artwork(ctx context.Context) model.ArtworkRepository {
-	return NewArtworkRepository(ctx, s.getDBXBuilder())
+func (s *SQLStore) Artwork() model.ArtworkRepository {
+	return s.artwork()
 }
 
-func (s *SQLStore) ArtworkQueue(ctx context.Context) model.ArtworkQueueRepository {
-	return NewArtworkQueueRepository(ctx, s.getDBXBuilder())
-}
-
-func (s *SQLStore) Resource(ctx context.Context, m any) model.ResourceRepository {
-	switch m.(type) {
-	case model.User:
-		return s.User(ctx).(model.ResourceRepository)
-	case model.Transcoding:
-		return s.Transcoding(ctx).(model.ResourceRepository)
-	case model.Player:
-		return s.Player(ctx).(model.ResourceRepository)
-	case model.Artist:
-		return s.Artist(ctx).(model.ResourceRepository)
-	case model.Album:
-		return s.Album(ctx).(model.ResourceRepository)
-	case model.MediaFile:
-		return s.MediaFile(ctx).(model.ResourceRepository)
-	case model.Genre:
-		return s.Genre(ctx).(model.ResourceRepository)
-	case model.Playlist:
-		return s.Playlist(ctx).(model.ResourceRepository)
-	case model.Radio:
-		return s.Radio(ctx).(model.ResourceRepository)
-	case model.Share:
-		return s.Share(ctx).(model.ResourceRepository)
-	case model.Tag:
-		return s.Tag(ctx).(model.ResourceRepository)
-	case model.Plugin:
-		return s.Plugin(ctx).(model.ResourceRepository)
-	case model.Scrobble:
-		return s.Scrobble(ctx).(model.ResourceRepository)
-	}
-	log.Error("Resource not implemented", "model", reflect.TypeOf(m).Name())
-	return nil
+func (s *SQLStore) ArtworkQueue() model.ArtworkQueueRepository {
+	return s.artworkQueue()
 }
 
 func scopeLabel(scope []string) string {
@@ -157,7 +173,7 @@ func (s *SQLStore) WithTx(block func(tx model.DataStore) error, scope ...string)
 		log.Trace("Transaction started", "scope", msg)
 	}
 	return conn.Transactional(func(tx *dbx.Tx) error {
-		newDb := &SQLStore{db: tx}
+		newDb := newSQLStore(tx)
 		err := block(newDb)
 		if !inTx {
 			log.Trace("Nested Transaction finished", "scope", msg, "elapsed", time.Since(start), err)
@@ -173,9 +189,9 @@ func (s *SQLStore) WithTxImmediate(block func(tx model.DataStore) error, scope .
 	return s.WithTx(func(tx model.DataStore) error {
 		// Workaround to force the transaction to be upgraded to immediate mode to avoid deadlocks
 		// See https://berthub.eu/articles/posts/a-brief-post-on-sqlite3-database-locked-despite-timeout/
-		_ = tx.Property(ctx).Put("tmp_lock_flag", "")
+		_ = tx.Property().Put(ctx, "tmp_lock_flag", "")
 		defer func() {
-			_ = tx.Property(ctx).Delete("tmp_lock_flag")
+			_ = tx.Property().Delete(ctx, "tmp_lock_flag")
 		}()
 
 		return block(tx)
@@ -244,27 +260,20 @@ func (s *SQLStore) GC(ctx context.Context, libraryIDs ...int) error {
 	}
 
 	err := run.Sequentially(
-		trace(ctx, "purge empty albums", func() error { return s.Album(ctx).(*albumRepository).purgeEmpty(libraryIDs...) }),
-		trace(ctx, "purge empty artists", func() error { return s.Artist(ctx).(*artistRepository).purgeEmpty() }),
-		trace(ctx, "mark missing artists", func() error { return s.Artist(ctx).(*artistRepository).markMissing() }),
-		trace(ctx, "purge empty folders", func() error { return s.Folder(ctx).(*folderRepository).purgeEmpty(libraryIDs...) }),
-		trace(ctx, "clean album annotations", func() error { return s.Album(ctx).(*albumRepository).cleanAnnotations() }),
-		trace(ctx, "clean artist annotations", func() error { return s.Artist(ctx).(*artistRepository).cleanAnnotations() }),
-		trace(ctx, "clean media file annotations", func() error { return s.MediaFile(ctx).(*mediaFileRepository).cleanAnnotations() }),
-		trace(ctx, "clean playlist annotations", func() error { return s.Playlist(ctx).(*playlistRepository).cleanAnnotations() }),
-		trace(ctx, "clean media file bookmarks", func() error { return s.MediaFile(ctx).(*mediaFileRepository).cleanBookmarks() }),
-		trace(ctx, "purge non used tags", func() error { return s.Tag(ctx).(*tagRepository).purgeUnused() }),
-		trace(ctx, "remove orphan playlist tracks", func() error { return s.Playlist(ctx).(*playlistRepository).removeOrphans() }),
+		trace(ctx, "purge empty albums", func() error { return s.album().(*albumRepository).purgeEmpty(ctx, libraryIDs...) }),
+		trace(ctx, "purge empty artists", func() error { return s.artist().(*artistRepository).purgeEmpty(ctx) }),
+		trace(ctx, "mark missing artists", func() error { return s.artist().(*artistRepository).markMissing(ctx) }),
+		trace(ctx, "purge empty folders", func() error { return s.folder().(*folderRepository).purgeEmpty(ctx, libraryIDs...) }),
+		trace(ctx, "clean album annotations", func() error { return s.album().(*albumRepository).cleanAnnotations(ctx) }),
+		trace(ctx, "clean artist annotations", func() error { return s.artist().(*artistRepository).cleanAnnotations(ctx) }),
+		trace(ctx, "clean media file annotations", func() error { return s.mediaFile().(*mediaFileRepository).cleanAnnotations(ctx) }),
+		trace(ctx, "clean playlist annotations", func() error { return s.playlist().(*playlistRepository).cleanAnnotations(ctx) }),
+		trace(ctx, "clean media file bookmarks", func() error { return s.mediaFile().(*mediaFileRepository).cleanBookmarks(ctx) }),
+		trace(ctx, "purge non used tags", func() error { return s.tag().(*tagRepository).purgeUnused(ctx) }),
+		trace(ctx, "remove orphan playlist tracks", func() error { return s.playlist().(*playlistRepository).removeOrphans(ctx) }),
 	)
 	if err != nil {
 		return fmt.Errorf("tidying up database: %w", err)
 	}
 	return nil
 }
-
-func (s *SQLStore) getDBXBuilder() dbx.Builder {
-	if s.db == nil {
-		return dbx.NewFromDB(db.Db(), db.Driver)
-	}
-	return s.db
-}
diff --git a/persistence/persistence_suite_test.go b/persistence/persistence_suite_test.go
index 644284c0b..ee2794454 100644
--- a/persistence/persistence_suite_test.go
+++ b/persistence/persistence_suite_test.go
@@ -176,17 +176,17 @@ func restrictedFixture(name string) (context.Context, model.Library, model.User)
 	db := GetDBXBuilder()
 
 	lib := model.Library{Name: name + " Library", Path: "/" + name}
-	lr := NewLibraryRepository(adminCtx, db)
-	Expect(lr.Put(&lib)).To(Succeed())
+	lr := NewLibraryRepository(db)
+	Expect(lr.Put(adminCtx, &lib)).To(Succeed())
 
 	user := createUserWithLibraries(name+"-restricted", []int{1})
-	ur := NewUserRepository(adminCtx, db)
-	Expect(ur.Put(&user)).To(Succeed())
-	Expect(ur.SetUserLibraries(user.ID, []int{1})).To(Succeed())
+	ur := NewUserRepository(db)
+	Expect(ur.Put(adminCtx, &user)).To(Succeed())
+	Expect(ur.SetUserLibraries(adminCtx, user.ID, []int{1})).To(Succeed())
 
 	DeferCleanup(func() {
-		_ = NewUserRepository(adminCtx, db).Delete(user.ID)
-		_ = NewLibraryRepository(adminCtx, db).(*libraryRepository).delete(squirrel.Eq{"id": lib.ID})
+		_ = NewUserRepository(db).Delete(adminCtx, user.ID)
+		_ = NewLibraryRepository(db).(*libraryRepository).delete(adminCtx, squirrel.Eq{"id": lib.ID})
 	})
 	return adminCtx, lib, user
 }
@@ -196,9 +196,9 @@ var _ = BeforeSuite(func() {
 	ctx := log.NewContext(context.TODO())
 	ctx = request.WithUser(ctx, adminUser)
 
-	ur := NewUserRepository(ctx, conn)
+	ur := NewUserRepository(conn)
 	for i := range testUsers {
-		err := ur.Put(&testUsers[i])
+		err := ur.Put(ctx, &testUsers[i])
 		if err != nil {
 			panic(err)
 		}
@@ -206,32 +206,32 @@ var _ = BeforeSuite(func() {
 
 	// Associate users with library 1 (default test library)
 	for i := range testUsers {
-		err := ur.SetUserLibraries(testUsers[i].ID, []int{1})
+		err := ur.SetUserLibraries(ctx, testUsers[i].ID, []int{1})
 		if err != nil {
 			panic(err)
 		}
 	}
 
-	alr := NewAlbumRepository(ctx, conn).(*albumRepository)
+	alr := NewAlbumRepository(conn).(*albumRepository)
 	for i := range testAlbums {
-		err := alr.Put(new(testAlbums[i]))
+		err := alr.Put(ctx, new(testAlbums[i]))
 		if err != nil {
 			panic(err)
 		}
 	}
 
-	arr := NewArtistRepository(ctx, conn)
+	arr := NewArtistRepository(conn)
 	for i := range testArtists {
-		err := arr.Put(new(testArtists[i]))
+		err := arr.Put(ctx, new(testArtists[i]))
 		if err != nil {
 			panic(err)
 		}
 	}
 
 	// Associate artists with library 1 (default test library)
-	lr := NewLibraryRepository(ctx, conn)
+	lr := NewLibraryRepository(conn)
 	for i := range testArtists {
-		err := lr.AddArtist(1, testArtists[i].ID)
+		err := lr.AddArtist(ctx, 1, testArtists[i].ID)
 		if err != nil {
 			panic(err)
 		}
@@ -247,7 +247,7 @@ var _ = BeforeSuite(func() {
 		if a.AlbumArtistID == "" || !artistIDs[a.AlbumArtistID] {
 			continue
 		}
-		_, err := alr.executeSQL(squirrel.Insert("album_artists").SetMap(map[string]any{
+		_, err := alr.executeSQL(ctx, squirrel.Insert("album_artists").SetMap(map[string]any{
 			"album_id":  a.ID,
 			"artist_id": a.AlbumArtistID,
 			"role":      "artist",
@@ -258,17 +258,17 @@ var _ = BeforeSuite(func() {
 		}
 	}
 
-	mr := NewMediaFileRepository(ctx, conn)
+	mr := NewMediaFileRepository(conn)
 	for i := range testSongs {
-		err := mr.Put(&testSongs[i])
+		err := mr.Put(ctx, &testSongs[i])
 		if err != nil {
 			panic(err)
 		}
 	}
 
-	rar := NewRadioRepository(ctx, conn)
+	rar := NewRadioRepository(conn)
 	for i := range testRadios {
-		err := rar.Put(new(testRadios[i]))
+		err := rar.Put(ctx, new(testRadios[i]))
 		if err != nil {
 			panic(err)
 		}
@@ -287,19 +287,19 @@ var _ = BeforeSuite(func() {
 	plsCool.AddMediaFilesByID([]string{"1004"})
 	testPlaylists = []*model.Playlist{&plsBest, &plsCool}
 
-	pr := NewPlaylistRepository(ctx, conn)
+	pr := NewPlaylistRepository(conn)
 	for i := range testPlaylists {
-		err := pr.Put(testPlaylists[i])
+		err := pr.Put(ctx, testPlaylists[i])
 		if err != nil {
 			panic(err)
 		}
 	}
 
 	// Prepare annotations
-	if err := arr.SetStar(true, artistBeatles.ID); err != nil {
+	if err := arr.SetStar(ctx, true, artistBeatles.ID); err != nil {
 		panic(err)
 	}
-	ar, err := arr.Get(artistBeatles.ID)
+	ar, err := arr.Get(ctx, artistBeatles.ID)
 	if err != nil {
 		panic(err)
 	}
@@ -310,10 +310,10 @@ var _ = BeforeSuite(func() {
 	artistBeatles.StarredAt = ar.StarredAt
 	testArtists[1] = artistBeatles
 
-	if err := alr.SetStar(true, albumRadioactivity.ID); err != nil {
+	if err := alr.SetStar(ctx, true, albumRadioactivity.ID); err != nil {
 		panic(err)
 	}
-	al, err := alr.Get(albumRadioactivity.ID)
+	al, err := alr.Get(ctx, albumRadioactivity.ID)
 	if err != nil {
 		panic(err)
 	}
@@ -324,10 +324,10 @@ var _ = BeforeSuite(func() {
 	albumRadioactivity.StarredAt = al.StarredAt
 	testAlbums[2] = albumRadioactivity
 
-	if err := mr.SetStar(true, songComeTogether.ID); err != nil {
+	if err := mr.SetStar(ctx, true, songComeTogether.ID); err != nil {
 		panic(err)
 	}
-	mf, err := mr.Get(songComeTogether.ID)
+	mf, err := mr.Get(ctx, songComeTogether.ID)
 	if err != nil {
 		panic(err)
 	}
@@ -335,9 +335,9 @@ var _ = BeforeSuite(func() {
 	songComeTogether.StarredAt = mf.StarredAt
 	testSongs[1] = songComeTogether
 
-	scrobbleRepo := NewScrobbleRepository(ctx, conn).(*scrobbleRepository)
+	scrobbleRepo := NewScrobbleRepository(conn).(*scrobbleRepository)
 	for _, s := range scrobbles {
-		_, err := scrobbleRepo.executeSQL(squirrel.Insert("scrobbles").SetMap(map[string]any{
+		_, err := scrobbleRepo.executeSQL(ctx, squirrel.Insert("scrobbles").SetMap(map[string]any{
 			"media_file_id":   s.MediaFileID,
 			"user_id":         s.UserID,
 			"submission_time": s.SubmissionTime,
diff --git a/persistence/persistence_test.go b/persistence/persistence_test.go
index e13f6a231..43d2e81ed 100644
--- a/persistence/persistence_test.go
+++ b/persistence/persistence_test.go
@@ -23,37 +23,37 @@ var _ = Describe("SQLStore", func() {
 		Context("When block returns nil", func() {
 			It("commits changes to the DB", func() {
 				err := ds.WithTx(func(tx model.DataStore) error {
-					pl := tx.Player(ctx)
-					err := pl.Put(&model.Player{ID: "666", UserId: "userid"})
+					pl := tx.Player()
+					err := pl.Put(ctx, &model.Player{ID: "666", UserId: "userid"})
 					Expect(err).ToNot(HaveOccurred())
 
-					pr := tx.Property(ctx)
-					err = pr.Put("777", "value")
+					pr := tx.Property()
+					err = pr.Put(ctx, "777", "value")
 					Expect(err).ToNot(HaveOccurred())
 					return nil
 				})
 				Expect(err).ToNot(HaveOccurred())
-				Expect(ds.Player(ctx).Get("666")).To(Equal(&model.Player{ID: "666", UserId: "userid", Username: "userid"}))
-				Expect(ds.Property(ctx).Get("777")).To(Equal("value"))
+				Expect(ds.Player().Get(ctx, "666")).To(Equal(&model.Player{ID: "666", UserId: "userid", Username: "userid"}))
+				Expect(ds.Property().Get(ctx, "777")).To(Equal("value"))
 			})
 		})
 		Context("When block returns an error", func() {
 			It("rollbacks changes to the DB", func() {
 				err := ds.WithTx(func(tx model.DataStore) error {
-					pr := tx.Property(ctx)
-					err := pr.Put("999", "value")
+					pr := tx.Property()
+					err := pr.Put(ctx, "999", "value")
 					Expect(err).ToNot(HaveOccurred())
 
 					// Will fail as it is missing the UserName
-					pl := tx.Player(ctx)
-					err = pl.Put(&model.Player{ID: "888"})
+					pl := tx.Player()
+					err = pl.Put(ctx, &model.Player{ID: "888"})
 					Expect(err).To(HaveOccurred())
 					return err
 				})
 				Expect(err).To(HaveOccurred())
-				_, err = ds.Property(ctx).Get("999")
+				_, err = ds.Property().Get(ctx, "999")
 				Expect(err).To(MatchError(model.ErrNotFound))
-				_, err = ds.Player(ctx).Get("888")
+				_, err = ds.Player().Get(ctx, "888")
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 		})
@@ -70,7 +70,7 @@ var _ = Describe("SQLStore", func() {
 			var attempts []bool
 			err := ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
 				attempts = append(attempts, hasBusyRetry(ctx))
-				Expect(tx.Property(ctx).Put("retry-key", "attempt")).To(Succeed())
+				Expect(tx.Property().Put(ctx, "retry-key", "attempt")).To(Succeed())
 				if len(attempts) < 3 {
 					return busy
 				}
@@ -78,7 +78,7 @@ var _ = Describe("SQLStore", func() {
 			})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(attempts).To(Equal([]bool{true, true, true}))
-			Expect(ds.Property(ctx).Get("retry-key")).To(Equal("attempt"))
+			Expect(ds.Property().Get(ctx, "retry-key")).To(Equal("attempt"))
 		})
 
 		It("gives up after the last retry, which is not marked as retried", func() {
@@ -116,15 +116,15 @@ var _ = Describe("SQLStore", func() {
 		It("joins the enclosing transaction instead of opening another", func() {
 			rollback := errors.New("rollback")
 			err := ds.WithTx(func(tx model.DataStore) error {
-				Expect(tx.Property(ctx).Put("outer-key", "v")).To(Succeed())
+				Expect(tx.Property().Put(ctx, "outer-key", "v")).To(Succeed())
 				Expect(tx.WithTxRetry(ctx, func(ctx context.Context, inner model.DataStore) error {
-					Expect(inner.Property(ctx).Get("outer-key")).To(Equal("v"))
-					return inner.Property(ctx).Put("inner-key", "v")
+					Expect(inner.Property().Get(ctx, "outer-key")).To(Equal("v"))
+					return inner.Property().Put(ctx, "inner-key", "v")
 				})).To(Succeed())
 				return rollback
 			})
 			Expect(err).To(MatchError(rollback))
-			_, err = ds.Property(ctx).Get("inner-key")
+			_, err = ds.Property().Get(ctx, "inner-key")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 	})
diff --git a/persistence/player_repository.go b/persistence/player_repository.go
index a2114b060..e46a8d82d 100644
--- a/persistence/player_repository.go
+++ b/persistence/player_repository.go
@@ -13,9 +13,8 @@ type playerRepository struct {
 	sqlRepository
 }
 
-func NewPlayerRepository(ctx context.Context, db dbx.Builder) model.PlayerRepository {
+func NewPlayerRepository(db dbx.Builder) model.PlayerRepository {
 	r := &playerRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.registerModel(&model.Player{}, map[string]filterFunc{
 		"name": containsFilter("player.name"),
@@ -26,43 +25,43 @@ func NewPlayerRepository(ctx context.Context, db dbx.Builder) model.PlayerReposi
 	return r
 }
 
-func (r *playerRepository) Put(p *model.Player) error {
-	_, err := r.put(p.ID, p)
+func (r *playerRepository) Put(ctx context.Context, p *model.Player) error {
+	_, err := r.put(ctx, p.ID, p)
 	return err
 }
 
-func (r *playerRepository) selectPlayer(options ...model.QueryOptions) SelectBuilder {
-	return r.newSelect(options...).
+func (r *playerRepository) selectPlayer(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	return r.newSelect(ctx, options...).
 		Columns("player.*").
 		Join("user ON player.user_id = user.id").
 		Columns("user.user_name username")
 }
 
-func (r *playerRepository) Get(id string) (*model.Player, error) {
-	sel := r.selectPlayer().Where(Eq{"player.id": id})
+func (r *playerRepository) Get(ctx context.Context, id string) (*model.Player, error) {
+	sel := r.selectPlayer(ctx).Where(Eq{"player.id": id})
 	var res model.Player
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-func (r *playerRepository) FindMatch(userId, client, userAgent string) (*model.Player, error) {
-	sel := r.selectPlayer().Where(And{
+func (r *playerRepository) FindMatch(ctx context.Context, userId, client, userAgent string) (*model.Player, error) {
+	sel := r.selectPlayer(ctx).Where(And{
 		Eq{"client": client},
 		Eq{"user_agent": userAgent},
 		Eq{"user_id": userId},
 	})
 	var res model.Player
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-func (r *playerRepository) newRestSelect(options ...model.QueryOptions) SelectBuilder {
-	s := r.selectPlayer(options...)
-	return s.Where(r.addRestriction())
+func (r *playerRepository) newRestSelect(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	s := r.selectPlayer(ctx, options...)
+	return s.Where(r.addRestriction(ctx))
 }
 
-func (r *playerRepository) CountByClient(options ...model.QueryOptions) (map[string]int64, error) {
-	sel := r.newSelect(options...).
+func (r *playerRepository) CountByClient(ctx context.Context, options ...model.QueryOptions) (map[string]int64, error) {
+	sel := r.newSelect(ctx, options...).
 		Columns(
 			"case when client = 'NavidromeUI' then name else client end as player",
 			"count(*) as count",
@@ -71,7 +70,7 @@ func (r *playerRepository) CountByClient(options ...model.QueryOptions) (map[str
 		Player string
 		Count  int64
 	}
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
@@ -82,63 +81,54 @@ func (r *playerRepository) CountByClient(options ...model.QueryOptions) (map[str
 	return counts, nil
 }
 
-func (r *playerRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	return r.count(r.newRestSelect(), options...)
+func (r *playerRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	return r.count(ctx, r.newRestSelect(ctx), options...)
 }
 
-func (r *playerRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *playerRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *playerRepository) Read(id string) (any, error) {
-	sel := r.newRestSelect().Where(Eq{"player.id": id})
+func (r *playerRepository) Read(ctx context.Context, id string) (*model.Player, error) {
+	sel := r.newRestSelect(ctx).Where(Eq{"player.id": id})
 	var res model.Player
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-func (r *playerRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	sel := r.newRestSelect(r.parseRestOptions(r.ctx, options...))
+func (r *playerRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Player, error) {
+	sel := r.newRestSelect(ctx, r.parseRestOptions(ctx, options...))
 	res := model.Players{}
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	return res, err
 }
 
-func (r *playerRepository) EntityName() string {
-	return "player"
-}
-
-func (r *playerRepository) NewInstance() any {
-	return &model.Player{}
-}
-
 // isPermitted authorizes creating a new record, based on the owner declared in the request body.
 // This is only safe for inserts: there is no stored row yet, and a non-admin may only create a
 // player they own. Updates must not use this (the body owner is attacker-controlled); they go
 // through updateOwned, which authorizes against the persisted user_id in the WHERE clause.
-func (r *playerRepository) isPermitted(p *model.Player) bool {
-	u := loggedUser(r.ctx)
+func (r *playerRepository) isPermitted(ctx context.Context, p *model.Player) bool {
+	u := loggedUser(ctx)
 	return u.IsAdmin || p.UserId == u.ID
 }
 
-func (r *playerRepository) Save(entity any) (string, error) {
-	t := entity.(*model.Player)
-	if !r.isPermitted(t) {
+func (r *playerRepository) Save(ctx context.Context, t *model.Player) (string, error) {
+	if !r.isPermitted(ctx, t) {
 		return "", rest.ErrPermissionDenied
 	}
-	return r.put("", t) // Save only creates; edits go through the owner-scoped Update
+	return r.put(ctx, "", t) // Save only creates; edits go through the owner-scoped Update
 }
 
-func (r *playerRepository) Update(id string, entity any, cols ...string) error {
-	t := entity.(*model.Player)
+func (r *playerRepository) Update(ctx context.Context, id string, entity model.Player, cols ...string) error {
+	t := &entity
 	t.ID = id
-	return r.updateOwned(id, t, cols...)
+	return r.updateOwned(ctx, id, t, cols...)
 }
 
-func (r *playerRepository) Delete(id string) error {
-	return r.deleteOwned(id)
+func (r *playerRepository) Delete(ctx context.Context, ids ...string) error {
+	return r.deleteOwnedAll(ctx, ids...)
 }
 
 var _ model.PlayerRepository = (*playerRepository)(nil)
-var _ rest.Repository = (*playerRepository)(nil)
-var _ rest.Persistable = (*playerRepository)(nil)
+var _ rest.Repository[model.Player] = (*playerRepository)(nil)
+var _ rest.Persistable[model.Player] = (*playerRepository)(nil)
diff --git a/persistence/player_repository_test.go b/persistence/player_repository_test.go
index 4a7701ac2..f12f3e74e 100644
--- a/persistence/player_repository_test.go
+++ b/persistence/player_repository_test.go
@@ -15,6 +15,7 @@ import (
 var _ = Describe("PlayerRepository", func() {
 	var adminRepo *playerRepository
 	var database *dbx.DB
+	var ctx context.Context
 
 	var (
 		adminPlayer1  = model.Player{ID: "1", Name: "NavidromeUI [Firefox/Linux]", UserAgent: "Firefox/Linux", UserId: adminUser.ID, Username: adminUser.UserName, Client: "NavidromeUI", IP: "127.0.0.1", ReportRealPath: true, ScrobbleEnabled: true}
@@ -25,77 +26,69 @@ var _ = Describe("PlayerRepository", func() {
 	)
 
 	BeforeEach(func() {
-		ctx := log.NewContext(context.TODO())
-		ctx = request.WithUser(ctx, adminUser)
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
 
 		database = GetDBXBuilder()
-		adminRepo = NewPlayerRepository(ctx, database).(*playerRepository)
+		adminRepo = NewPlayerRepository(database).(*playerRepository)
 
 		for idx := range players {
-			err := adminRepo.Put(&players[idx])
+			err := adminRepo.Put(ctx, &players[idx])
 			Expect(err).To(BeNil())
 		}
 	})
 
 	AfterEach(func() {
-		items, err := adminRepo.ReadAll()
+		players, err := adminRepo.ReadAll(ctx)
 		Expect(err).To(BeNil())
-		players, ok := items.(model.Players)
-		Expect(ok).To(BeTrue())
 		for i := range players {
-			err = adminRepo.Delete(players[i].ID)
+			err = adminRepo.Delete(ctx, players[i].ID)
 			Expect(err).To(BeNil())
 		}
 	})
 
-	Describe("EntityName", func() {
-		It("returns the right name", func() {
-			Expect(adminRepo.EntityName()).To(Equal("player"))
-		})
-	})
-
 	Describe("FindMatch", func() {
 		It("finds existing match", func() {
-			player, err := adminRepo.FindMatch(adminUser.ID, "NavidromeUI", "Firefox/Linux")
+			player, err := adminRepo.FindMatch(ctx, adminUser.ID, "NavidromeUI", "Firefox/Linux")
 			Expect(err).To(BeNil())
 			Expect(*player).To(Equal(adminPlayer1))
 		})
 
 		It("doesn't find bad match", func() {
-			_, err := adminRepo.FindMatch(regularUser.ID, "NavidromeUI", "Firefox/Linux")
+			_, err := adminRepo.FindMatch(ctx, regularUser.ID, "NavidromeUI", "Firefox/Linux")
 			Expect(err).To(Equal(model.ErrNotFound))
 		})
 	})
 
 	Describe("Get", func() {
 		It("Gets an existing item from user", func() {
-			player, err := adminRepo.Get(adminPlayer1.ID)
+			player, err := adminRepo.Get(ctx, adminPlayer1.ID)
 			Expect(err).To(BeNil())
 			Expect(*player).To(Equal(adminPlayer1))
 		})
 
 		It("Gets an existing item from another user", func() {
-			player, err := adminRepo.Get(regularPlayer.ID)
+			player, err := adminRepo.Get(ctx, regularPlayer.ID)
 			Expect(err).To(BeNil())
 			Expect(*player).To(Equal(regularPlayer))
 		})
 
 		It("does not get nonexistent item", func() {
-			_, err := adminRepo.Get("i don't exist")
+			_, err := adminRepo.Get(ctx, "i don't exist")
 			Expect(err).To(Equal(model.ErrNotFound))
 		})
 	})
 
 	DescribeTableSubtree("per context", func(admin bool, players model.Players, userPlayer model.Player, otherPlayer model.Player) {
 		var repo *playerRepository
+		var repoCtx context.Context
 
 		BeforeEach(func() {
+			repoCtx = ctx
 			if admin {
 				repo = adminRepo
 			} else {
-				ctx := log.NewContext(context.TODO())
-				ctx = request.WithUser(ctx, regularUser)
-				repo = NewPlayerRepository(ctx, database).(*playerRepository)
+				repoCtx = request.WithUser(ctx, regularUser)
+				repo = NewPlayerRepository(database).(*playerRepository)
 			}
 		})
 
@@ -103,7 +96,7 @@ var _ = Describe("PlayerRepository", func() {
 
 		Describe("Count", func() {
 			It("should return all", func() {
-				count, err := repo.Count()
+				count, err := repo.Count(repoCtx)
 				Expect(err).To(BeNil())
 				Expect(count).To(Equal(baseCount))
 			})
@@ -111,53 +104,53 @@ var _ = Describe("PlayerRepository", func() {
 
 		Describe("Delete", func() {
 			It("deletes a player owned by the current user", func() {
-				err := repo.Delete(userPlayer.ID)
+				err := repo.Delete(repoCtx, userPlayer.ID)
 				Expect(err).To(BeNil())
 
-				count, err := repo.Count()
+				count, err := repo.Count(repoCtx)
 				Expect(err).To(BeNil())
 				Expect(count).To(Equal(baseCount - 1))
 
-				_, err = repo.Get(userPlayer.ID)
+				_, err = repo.Get(repoCtx, userPlayer.ID)
 				Expect(err).To(Equal(model.ErrNotFound))
 			})
 
 			It("does not delete another user's player when not admin", func() {
-				err := repo.Delete(otherPlayer.ID)
+				err := repo.Delete(repoCtx, otherPlayer.ID)
 
 				if admin {
 					// Admins may delete any player.
 					Expect(err).To(BeNil())
-					Expect(repo.Count()).To(Equal(baseCount - 1))
-					_, err = repo.Get(otherPlayer.ID)
+					Expect(repo.Count(repoCtx)).To(Equal(baseCount - 1))
+					_, err = repo.Get(repoCtx, otherPlayer.ID)
 					Expect(err).To(Equal(model.ErrNotFound))
 				} else {
 					// The ownership-restricted delete matches no owned row, so it reports
 					// permission-denied and leaves the other user's player untouched.
 					Expect(err).To(Equal(rest.ErrPermissionDenied))
-					Expect(repo.Count()).To(Equal(baseCount))
-					item, err := repo.Get(otherPlayer.ID)
+					Expect(repo.Count(repoCtx)).To(Equal(baseCount))
+					item, err := repo.Get(repoCtx, otherPlayer.ID)
 					Expect(err).To(BeNil())
 					Expect(*item).To(Equal(otherPlayer))
 				}
 			})
 
 			It("returns not-found for a nonexistent player", func() {
-				err := repo.Delete("i don't exist")
+				err := repo.Delete(repoCtx, "i don't exist")
 				Expect(err).To(Equal(rest.ErrNotFound))
-				Expect(repo.Count()).To(Equal(baseCount))
+				Expect(repo.Count(repoCtx)).To(Equal(baseCount))
 			})
 		})
 
 		Describe("Read", func() {
 			It("can read from current user", func() {
-				player, err := repo.Read(userPlayer.ID)
+				player, err := repo.Read(repoCtx, userPlayer.ID)
 				Expect(err).To(BeNil())
 				Expect(player).To(Equal(&userPlayer))
 			})
 
 			It("can read from other user or fail if not admin", func() {
-				player, err := repo.Read(otherPlayer.ID)
+				player, err := repo.Read(repoCtx, otherPlayer.ID)
 				if admin {
 					Expect(err).To(BeNil())
 					Expect(player).To(Equal(&otherPlayer))
@@ -167,16 +160,16 @@ var _ = Describe("PlayerRepository", func() {
 			})
 
 			It("does not get nonexistent item", func() {
-				_, err := repo.Read("i don't exist")
+				_, err := repo.Read(repoCtx, "i don't exist")
 				Expect(err).To(Equal(model.ErrNotFound))
 			})
 		})
 
 		Describe("ReadAll", func() {
 			It("should get all items", func() {
-				data, err := repo.ReadAll()
+				data, err := repo.ReadAll(repoCtx)
 				Expect(err).To(BeNil())
-				Expect(data).To(Equal(players))
+				Expect(model.Players(data)).To(Equal(players))
 			})
 		})
 
@@ -185,7 +178,7 @@ var _ = Describe("PlayerRepository", func() {
 				clone := player
 				clone.ID = ""
 				clone.IP = "192.168.1.1"
-				id, err := repo.Save(&clone)
+				id, err := repo.Save(repoCtx, &clone)
 
 				if clone.UserId == "" {
 					Expect(err).To(HaveOccurred())
@@ -197,11 +190,11 @@ var _ = Describe("PlayerRepository", func() {
 					Expect(id).ToNot(BeEmpty())
 				}
 
-				count, err := repo.Count()
+				count, err := repo.Count(repoCtx)
 				Expect(err).To(BeNil())
 
 				clone.ID = id
-				newItem, err := repo.Get(id)
+				newItem, err := repo.Get(repoCtx, id)
 
 				if clone.UserId == "" {
 					Expect(count).To(Equal(baseCount))
@@ -223,7 +216,7 @@ var _ = Describe("PlayerRepository", func() {
 				clone := player
 				clone.IP = "192.168.1.1"
 				clone.MaxBitRate = 10000
-				err := repo.Update(clone.ID, &clone, "ip")
+				err := repo.Update(repoCtx, clone.ID, clone, "ip")
 
 				if player.UserId == "" {
 					Expect(err).To(HaveOccurred())
@@ -238,7 +231,7 @@ var _ = Describe("PlayerRepository", func() {
 				}
 
 				clone.MaxBitRate = player.MaxBitRate
-				newItem, err := repo.Get(clone.ID)
+				newItem, err := repo.Get(repoCtx, clone.ID)
 
 				if player.UserId == "" {
 					Expect(err).To(Equal(model.ErrNotFound))
@@ -260,11 +253,11 @@ var _ = Describe("PlayerRepository", func() {
 
 	Describe("Ownership enforcement (cross-tenant write protection)", func() {
 		var regularRepo *playerRepository
+		var regularCtx context.Context
 
 		BeforeEach(func() {
-			ctx := log.NewContext(context.TODO())
-			ctx = request.WithUser(ctx, regularUser)
-			regularRepo = NewPlayerRepository(ctx, database).(*playerRepository)
+			regularCtx = request.WithUser(ctx, regularUser)
+			regularRepo = NewPlayerRepository(database).(*playerRepository)
 		})
 
 		It("does not let a regular user hijack another user's player by spoofing userId in the body", func() {
@@ -279,11 +272,11 @@ var _ = Describe("PlayerRepository", func() {
 
 			// The ownership-restricted update matches no row owned by the attacker, so the write
 			// targets nothing and reports permission-denied rather than overwriting the victim's row.
-			err := regularRepo.Update(adminPlayer1.ID, &spoofed, "name", "user_id", "max_bit_rate")
+			err := regularRepo.Update(regularCtx, adminPlayer1.ID, spoofed, "name", "user_id", "max_bit_rate")
 			Expect(err).To(Equal(rest.ErrPermissionDenied))
 
 			// The victim's player must remain untouched.
-			stored, err := adminRepo.Get(adminPlayer1.ID)
+			stored, err := adminRepo.Get(ctx, adminPlayer1.ID)
 			Expect(err).To(BeNil())
 			Expect(*stored).To(Equal(adminPlayer1))
 		})
@@ -296,15 +289,15 @@ var _ = Describe("PlayerRepository", func() {
 				ReportRealPath: true,
 			}
 
-			id, err := regularRepo.Save(&spoofed)
+			id, err := regularRepo.Save(regularCtx, &spoofed)
 			Expect(err).To(BeNil())
 			Expect(id).ToNot(Equal(adminPlayer1.ID))
 
-			stored, err := adminRepo.Get(adminPlayer1.ID)
+			stored, err := adminRepo.Get(ctx, adminPlayer1.ID)
 			Expect(err).To(BeNil())
 			Expect(*stored).To(Equal(adminPlayer1))
 
-			created, err := adminRepo.Get(id)
+			created, err := adminRepo.Get(ctx, id)
 			Expect(err).To(BeNil())
 			Expect(created.UserId).To(Equal(regularUser.ID))
 		})
@@ -316,11 +309,11 @@ var _ = Describe("PlayerRepository", func() {
 			reassign.UserId = adminUser.ID
 			reassign.Name = "given-away"
 
-			err := regularRepo.Update(regularPlayer.ID, &reassign, "name", "user_id")
+			err := regularRepo.Update(regularCtx, regularPlayer.ID, reassign, "name", "user_id")
 			Expect(err).To(BeNil())
 
 			// Ownership must not have changed.
-			stored, err := adminRepo.Get(regularPlayer.ID)
+			stored, err := adminRepo.Get(ctx, regularPlayer.ID)
 			Expect(err).To(BeNil())
 			Expect(stored.UserId).To(Equal(regularUser.ID))
 		})
@@ -331,11 +324,11 @@ var _ = Describe("PlayerRepository", func() {
 			reassign.UserId = adminUser.ID
 			reassign.Name = "admin-renamed"
 
-			err := adminRepo.Update(regularPlayer.ID, &reassign, "name", "user_id")
+			err := adminRepo.Update(regularCtx, regularPlayer.ID, reassign, "name", "user_id")
 			Expect(err).To(BeNil())
 
 			// The name change applies, but ownership must not have moved.
-			stored, err := adminRepo.Get(regularPlayer.ID)
+			stored, err := adminRepo.Get(ctx, regularPlayer.ID)
 			Expect(err).To(BeNil())
 			Expect(stored.Name).To(Equal("admin-renamed"))
 			Expect(stored.UserId).To(Equal(regularUser.ID))
@@ -345,10 +338,10 @@ var _ = Describe("PlayerRepository", func() {
 			update := regularPlayer
 			update.Name = "renamed-by-owner"
 
-			err := regularRepo.Update(regularPlayer.ID, &update, "name")
+			err := regularRepo.Update(regularCtx, regularPlayer.ID, update, "name")
 			Expect(err).To(BeNil())
 
-			stored, err := adminRepo.Get(regularPlayer.ID)
+			stored, err := adminRepo.Get(ctx, regularPlayer.ID)
 			Expect(err).To(BeNil())
 			Expect(stored.Name).To(Equal("renamed-by-owner"))
 			Expect(stored.UserId).To(Equal(regularUser.ID))
@@ -356,7 +349,7 @@ var _ = Describe("PlayerRepository", func() {
 
 		It("returns not found when updating a nonexistent player", func() {
 			ghost := model.Player{ID: "does-not-exist", Name: "ghost", UserId: regularUser.ID}
-			err := regularRepo.Update("does-not-exist", &ghost, "name")
+			err := regularRepo.Update(regularCtx, "does-not-exist", ghost, "name")
 			Expect(err).To(Equal(rest.ErrNotFound))
 		})
 	})
diff --git a/persistence/playlist_repository.go b/persistence/playlist_repository.go
index 2afef9f45..41b75266c 100644
--- a/persistence/playlist_repository.go
+++ b/persistence/playlist_repository.go
@@ -50,9 +50,8 @@ func (p dbPlaylist) PostMapArgs(args map[string]any) error {
 	return nil
 }
 
-func NewPlaylistRepository(ctx context.Context, db dbx.Builder) model.PlaylistRepository {
+func NewPlaylistRepository(db dbx.Builder) model.PlaylistRepository {
 	r := &playlistRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.registerModel(&model.Playlist{}, map[string]filterFunc{
 		"id":      idFilter("playlist"),
@@ -81,8 +80,8 @@ func smartPlaylistFilter(string, any) Sqlizer {
 	}
 }
 
-func (r *playlistRepository) userFilter() Sqlizer {
-	user := loggedUser(r.ctx)
+func (r *playlistRepository) userFilter(ctx context.Context) Sqlizer {
+	user := loggedUser(ctx)
 	if user.IsAdmin {
 		return And{}
 	}
@@ -92,29 +91,29 @@ func (r *playlistRepository) userFilter() Sqlizer {
 	}
 }
 
-func (r *playlistRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	query := Select().Where(r.userFilter())
+func (r *playlistRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	query := Select().Where(r.userFilter(ctx))
 	if filtersNeedAnnotation(r.applyFilters(query, options...)) {
-		query = r.withAnnotation(query, "playlist.id")
+		query = r.withAnnotation(ctx, query, "playlist.id")
 	}
-	return r.count(query, options...)
+	return r.count(ctx, query, options...)
 }
 
-func (r *playlistRepository) Exists(id string) (bool, error) {
-	return r.exists(And{Eq{"id": id}, r.userFilter()})
+func (r *playlistRepository) Exists(ctx context.Context, id string) (bool, error) {
+	return r.exists(ctx, And{Eq{"id": id}, r.userFilter(ctx)})
 }
 
-func (r *playlistRepository) Delete(id string) error {
-	return r.delete(And{Eq{"id": id}, r.userFilter()})
+func (r *playlistRepository) Delete(ctx context.Context, ids ...string) error {
+	return r.delete(ctx, And{Eq{"id": ids}, r.userFilter(ctx)})
 }
 
-func (r *playlistRepository) Put(p *model.Playlist, cols ...string) error {
+func (r *playlistRepository) Put(ctx context.Context, p *model.Playlist, cols ...string) error {
 	pls := dbPlaylist{Playlist: *p}
 	if len(cols) > 0 {
 		if pls.ID == "" {
 			return errors.New("playlist id is required for partial update")
 		}
-		_, err := r.put(pls.ID, pls, cols...)
+		_, err := r.put(ctx, pls.ID, pls, cols...)
 		return err
 	}
 	isNew := pls.ID == ""
@@ -123,7 +122,7 @@ func (r *playlistRepository) Put(p *model.Playlist, cols ...string) error {
 	}
 	pls.UpdatedAt = time.Now()
 
-	id, err := r.put(pls.ID, pls)
+	id, err := r.put(ctx, pls.ID, pls)
 	if err != nil {
 		return err
 	}
@@ -135,48 +134,48 @@ func (r *playlistRepository) Put(p *model.Playlist, cols ...string) error {
 	}
 	// Only update tracks if they were specified
 	if len(pls.Tracks) > 0 {
-		return r.updateTracks(id, p.MediaFiles())
+		return r.updateTracks(ctx, id, p.MediaFiles())
 	}
 	pls.ID = id // r.put assigns the generated id to p, not to this copy
 	if isNew {
 		// Even a trackless new playlist has art to find (an imported m3u can carry an
 		// ExternalImageURL); an update landing here changed only metadata, so leave its cover be.
-		r.enqueueCoverRebuild(id)
+		r.enqueueCoverRebuild(ctx, id)
 	}
-	return r.refreshCounters(&pls.Playlist)
+	return r.refreshCounters(ctx, &pls.Playlist)
 }
 
-func (r *playlistRepository) Get(id string) (*model.Playlist, error) {
-	return r.findBy(And{Eq{"playlist.id": id}, r.userFilter()})
+func (r *playlistRepository) Get(ctx context.Context, id string) (*model.Playlist, error) {
+	return r.findBy(ctx, And{Eq{"playlist.id": id}, r.userFilter(ctx)})
 }
 
-func (r *playlistRepository) GetWithTracks(id string, refreshSmartPlaylist, includeMissing bool) (*model.Playlist, error) {
-	pls, err := r.Get(id)
+func (r *playlistRepository) GetWithTracks(ctx context.Context, id string, refreshSmartPlaylist, includeMissing bool) (*model.Playlist, error) {
+	pls, err := r.Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
 	if refreshSmartPlaylist {
-		r.refreshSmartPlaylist(pls)
+		r.refreshSmartPlaylist(ctx, pls)
 	}
-	tracks, err := r.loadTracks(Select().From("playlist_tracks").
+	tracks, err := r.loadTracks(ctx, Select().From("playlist_tracks").
 		Where(Eq{"missing": false}).
 		OrderBy("playlist_tracks.id"), id)
 	if err != nil {
-		log.Error(r.ctx, "Error loading playlist tracks ", "playlist", pls.Name, "id", pls.ID, err)
+		log.Error(ctx, "Error loading playlist tracks ", "playlist", pls.Name, "id", pls.ID, err)
 		return nil, err
 	}
 	pls.SetTracks(tracks)
 	return pls, nil
 }
 
-func (r *playlistRepository) FindByPath(path string) (*model.Playlist, error) {
-	return r.findBy(Eq{"path": path})
+func (r *playlistRepository) FindByPath(ctx context.Context, path string) (*model.Playlist, error) {
+	return r.findBy(ctx, Eq{"path": path})
 }
 
-func (r *playlistRepository) findBy(sql Sqlizer) (*model.Playlist, error) {
-	sel := r.selectPlaylist().Where(sql)
+func (r *playlistRepository) findBy(ctx context.Context, sql Sqlizer) (*model.Playlist, error) {
+	sel := r.selectPlaylist(ctx).Where(sql)
 	var pls []dbPlaylist
-	err := r.queryAll(sel, &pls)
+	err := r.queryAll(ctx, sel, &pls)
 	if err != nil {
 		return nil, err
 	}
@@ -185,19 +184,19 @@ func (r *playlistRepository) findBy(sql Sqlizer) (*model.Playlist, error) {
 	}
 
 	list := model.Playlists{pls[0].Playlist}
-	r.hydrateArtwork(list)
+	r.hydrateArtwork(ctx, list)
 	return &list[0], nil
 }
 
-func (r *playlistRepository) hydrateArtwork(playlists model.Playlists) {
-	hydrateItems(r.ctx, r.db, model.KindPlaylistArtwork, playlists,
+func (r *playlistRepository) hydrateArtwork(ctx context.Context, playlists model.Playlists) {
+	hydrateItems(ctx, r.db, model.KindPlaylistArtwork, playlists,
 		func(p *model.Playlist) (string, *model.ItemImage) { return p.ID, &p.ItemImage })
 }
 
-func (r *playlistRepository) GetAll(options ...model.QueryOptions) (model.Playlists, error) {
-	sel := r.selectPlaylist(options...).Where(r.userFilter())
+func (r *playlistRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Playlists, error) {
+	sel := r.selectPlaylist(ctx, options...).Where(r.userFilter(ctx))
 	var res []dbPlaylist
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
@@ -205,42 +204,42 @@ func (r *playlistRepository) GetAll(options ...model.QueryOptions) (model.Playli
 	for i, p := range res {
 		playlists[i] = p.Playlist
 	}
-	r.hydrateArtwork(playlists)
+	r.hydrateArtwork(ctx, playlists)
 	return playlists, err
 }
 
 // getAllIDs returns the IDs of GetAll's row set, skipping its per-row processing.
-func (r *playlistRepository) getAllIDs(options ...model.QueryOptions) ([]string, error) {
+func (r *playlistRepository) getAllIDs(ctx context.Context, options ...model.QueryOptions) ([]string, error) {
 	// Joins a projection of user, not the table: its name/created_at columns would make an ORDER BY
 	// on the playlist's own ambiguous.
-	sq := r.newSelect(options...).Columns("playlist.id", "user.user_name as owner_name").
-		Join("(select id, user_name from user) user on user.id = owner_id").Where(r.userFilter())
+	sq := r.newSelect(ctx, options...).Columns("playlist.id", "user.user_name as owner_name").
+		Join("(select id, user_name from user) user on user.id = owner_id").Where(r.userFilter(ctx))
 	if filtersNeedAnnotation(sq) {
-		sq = r.withAnnotation(sq, "playlist.id")
+		sq = r.withAnnotation(ctx, sq, "playlist.id")
 	}
 	ids := []string{}
-	err := r.queryAllSlice(sq, &ids)
+	err := r.queryAllSlice(ctx, sq, &ids)
 	return ids, err
 }
 
-func (r *playlistRepository) GetCursor(options ...model.QueryOptions) (model.PlaylistCursor, error) {
+func (r *playlistRepository) GetCursor(ctx context.Context, options ...model.QueryOptions) (model.PlaylistCursor, error) {
 	// Both passes apply userFilter, so a visibility change between them cannot widen the cursor.
-	ids, err := r.getAllIDs(options...)
+	ids, err := r.getAllIDs(ctx, options...)
 	if err != nil {
 		return nil, err
 	}
 	opts := chunkOptions(options, "playlist.id")
 	return model.PlaylistCursor(streamByIDs(ids, func(chunk []string) (model.Playlists, error) {
-		return r.GetAll(opts(chunk))
+		return r.GetAll(ctx, opts(chunk))
 	})), nil
 }
 
-func (r *playlistRepository) GetPlaylists(mediaFileId string) (model.Playlists, error) {
-	sel := r.selectPlaylist(model.QueryOptions{Sort: "name"}).
+func (r *playlistRepository) GetPlaylists(ctx context.Context, mediaFileId string) (model.Playlists, error) {
+	sel := r.selectPlaylist(ctx, model.QueryOptions{Sort: "name"}).
 		Join("playlist_tracks on playlist.id = playlist_tracks.playlist_id").
-		Where(And{Eq{"playlist_tracks.media_file_id": mediaFileId}, r.userFilter()})
+		Where(And{Eq{"playlist_tracks.media_file_id": mediaFileId}, r.userFilter(ctx)})
 	var res []dbPlaylist
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
 			return model.Playlists{}, nil
@@ -251,40 +250,40 @@ func (r *playlistRepository) GetPlaylists(mediaFileId string) (model.Playlists,
 	for i, p := range res {
 		playlists[i] = p.Playlist
 	}
-	r.hydrateArtwork(playlists)
+	r.hydrateArtwork(ctx, playlists)
 	return playlists, nil
 }
 
-func (r *playlistRepository) selectPlaylist(options ...model.QueryOptions) SelectBuilder {
-	sel := r.newSelect(options...).Join("user on user.id = owner_id").
+func (r *playlistRepository) selectPlaylist(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	sel := r.newSelect(ctx, options...).Join("user on user.id = owner_id").
 		Columns(r.tableName+".*", "user.user_name as owner_name")
-	return r.withAnnotation(sel, r.tableName+".id")
+	return r.withAnnotation(ctx, sel, r.tableName+".id")
 }
 
-func (r *playlistRepository) updateTracks(id string, tracks model.MediaFiles) error {
+func (r *playlistRepository) updateTracks(ctx context.Context, id string, tracks model.MediaFiles) error {
 	ids := make([]string, len(tracks))
 	for i := range tracks {
 		ids[i] = tracks[i].ID
 	}
-	return r.updatePlaylist(id, ids)
+	return r.updatePlaylist(ctx, id, ids)
 }
 
-func (r *playlistRepository) updatePlaylist(playlistId string, mediaFileIds []string) error {
+func (r *playlistRepository) updatePlaylist(ctx context.Context, playlistId string, mediaFileIds []string) error {
 	// Remove old tracks
 	del := Delete("playlist_tracks").Where(Eq{"playlist_id": playlistId})
-	_, err := r.executeSQL(del)
+	_, err := r.executeSQL(ctx, del)
 	if err != nil {
 		return err
 	}
 
-	_, err = r.addTracks(playlistId, 1, mediaFileIds)
+	_, err = r.addTracks(ctx, playlistId, 1, mediaFileIds)
 	return err
 }
 
 // addTracks is the only path that writes playlist_tracks rows (smart playlists aside), so it owns
 // the library check: every caller, including a full replace through Put, goes through it.
-func (r *playlistRepository) addTracks(playlistId string, startingPos int, mediaFileIds []string) (int, error) {
-	mediaFileIds, err := r.keepAccessible(mediaFileIds)
+func (r *playlistRepository) addTracks(ctx context.Context, playlistId string, startingPos int, mediaFileIds []string) (int, error) {
+	mediaFileIds, err := r.keepAccessible(ctx, mediaFileIds)
 	if err != nil {
 		return 0, err
 	}
@@ -297,26 +296,26 @@ func (r *playlistRepository) addTracks(playlistId string, startingPos int, media
 			ins = ins.Values(playlistId, t, pos)
 			pos++
 		}
-		if _, err := r.executeSQL(ins); err != nil {
+		if _, err := r.executeSQL(ctx, ins); err != nil {
 			return 0, err
 		}
 	}
 
-	r.enqueueCoverRebuild(playlistId)
-	return len(mediaFileIds), r.refreshCounters(&model.Playlist{ID: playlistId})
+	r.enqueueCoverRebuild(ctx, playlistId)
+	return len(mediaFileIds), r.refreshCounters(ctx, &model.Playlist{ID: playlistId})
 }
 
 // keepAccessible drops ids the caller cannot read, preserving order and duplicates. Chunked
 // because callers pass unbounded id lists (M3U import), well past SQLITE_MAX_VARIABLE_NUMBER.
-func (r *playlistRepository) keepAccessible(mediaFileIds []string) ([]string, error) {
-	if visible, err := r.visibleLibraryIDs(); err == nil && r.userSeesAllLibraries(visible) {
+func (r *playlistRepository) keepAccessible(ctx context.Context, mediaFileIds []string) ([]string, error) {
+	if visible, err := r.visibleLibraryIDs(ctx); err == nil && r.userSeesAllLibraries(ctx, visible) {
 		return mediaFileIds, nil
 	}
 	accessible := make(map[string]struct{}, len(mediaFileIds))
 	for chunk := range slices.Chunk(slice.Unique(mediaFileIds), 200) {
-		sq := r.applyLibraryFilter(Select("id").From("media_file").Where(Eq{"id": chunk}), "media_file")
+		sq := r.applyLibraryFilter(ctx, Select("id").From("media_file").Where(Eq{"id": chunk}), "media_file")
 		var found []string
-		if err := r.queryAllSlice(sq, &found); err != nil {
+		if err := r.queryAllSlice(ctx, sq, &found); err != nil {
 			return nil, err
 		}
 		for _, id := range found {
@@ -330,7 +329,7 @@ func (r *playlistRepository) keepAccessible(mediaFileIds []string) ([]string, er
 }
 
 // refreshCounters updates total playlist duration, size and count
-func (r *playlistRepository) refreshCounters(pls *model.Playlist) error {
+func (r *playlistRepository) refreshCounters(ctx context.Context, pls *model.Playlist) error {
 	statsSql := Select(
 		"coalesce(sum(duration), 0) as duration",
 		"coalesce(sum(size), 0) as size",
@@ -340,7 +339,7 @@ func (r *playlistRepository) refreshCounters(pls *model.Playlist) error {
 		Join("playlist_tracks f on f.media_file_id = media_file.id").
 		Where(Eq{"playlist_id": pls.ID})
 	var res struct{ Duration, Size, Count float32 }
-	err := r.queryOne(statsSql, &res)
+	err := r.queryOne(ctx, statsSql, &res)
 	if err != nil {
 		return err
 	}
@@ -353,7 +352,7 @@ func (r *playlistRepository) refreshCounters(pls *model.Playlist) error {
 		Set("song_count", res.Count).
 		Set("updated_at", now).
 		Where(Eq{"id": pls.ID})
-	_, err = r.executeSQL(upd)
+	_, err = r.executeSQL(ctx, upd)
 	if err != nil {
 		return err
 	}
@@ -366,18 +365,18 @@ func (r *playlistRepository) refreshCounters(pls *model.Playlist) error {
 
 // enqueueCoverRebuild re-resolves the generated 2x2 grid. Call it only when the track set changes:
 // the grid samples albums at random, so rebuilding after a mere rename would change the cover.
-func (r *playlistRepository) enqueueCoverRebuild(id string) {
+func (r *playlistRepository) enqueueCoverRebuild(ctx context.Context, id string) {
 	item := model.ArtworkQueueItem{ItemKind: model.KindPlaylistArtwork.Prefix(), ItemID: id,
 		ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityScan}
-	if err := NewArtworkQueueRepository(r.ctx, r.db).Enqueue(item); err != nil {
-		log.Warn(r.ctx, "could not enqueue playlist artwork after content change", "id", id, err)
+	if err := NewArtworkQueueRepository(r.db).Enqueue(ctx, item); err != nil {
+		log.Warn(ctx, "could not enqueue playlist artwork after content change", "id", id, err)
 	}
 }
 
 // tracksQuery is shared by loadTracks and GetCursor, so both hydrate rows identically.
-func (r *playlistRepository) tracksQuery(query SelectBuilder, id string) SelectBuilder {
-	query = r.applyLibraryFilter(query, "f")
-	userID := loggedUser(r.ctx).ID
+func (r *playlistRepository) tracksQuery(ctx context.Context, query SelectBuilder, id string) SelectBuilder {
+	query = r.applyLibraryFilter(ctx, query, "f")
+	userID := loggedUser(ctx).ID
 	return query.
 		Columns(
 			"coalesce(starred, 0) as starred",
@@ -400,56 +399,47 @@ func (r *playlistRepository) tracksQuery(query SelectBuilder, id string) SelectB
 		Where(Eq{"playlist_id": id})
 }
 
-func (r *playlistRepository) loadTracks(query SelectBuilder, id string) (model.PlaylistTracks, error) {
+func (r *playlistRepository) loadTracks(ctx context.Context, query SelectBuilder, id string) (model.PlaylistTracks, error) {
 	tracks := dbPlaylistTracks{}
-	err := r.queryAll(r.tracksQuery(query, id), &tracks)
+	err := r.queryAll(ctx, r.tracksQuery(ctx, query, id), &tracks)
 	if err != nil {
 		return nil, err
 	}
 	res := tracks.toModels()
-	hydratePlaylistTrackArtwork(r.ctx, r.db, res)
+	hydratePlaylistTrackArtwork(ctx, r.db, res)
 	return res, err
 }
 
-func (r *playlistRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *playlistRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *playlistRepository) Read(id string) (any, error) {
-	return r.Get(id)
+func (r *playlistRepository) Read(ctx context.Context, id string) (*model.Playlist, error) {
+	return r.Get(ctx, id)
 }
 
-func (r *playlistRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
+func (r *playlistRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Playlist, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *playlistRepository) EntityName() string {
-	return "playlist"
-}
-
-func (r *playlistRepository) NewInstance() any {
-	return &model.Playlist{}
-}
-
-func (r *playlistRepository) Save(entity any) (string, error) {
-	pls := entity.(*model.Playlist)
+func (r *playlistRepository) Save(ctx context.Context, pls *model.Playlist) (string, error) {
 	pls.ID = "" // Force new creation
-	err := r.Put(pls)
+	err := r.Put(ctx, pls)
 	if err != nil {
 		return "", err
 	}
 	return pls.ID, err
 }
 
-func (r *playlistRepository) Update(id string, entity any, cols ...string) error {
-	pls := dbPlaylist{Playlist: *entity.(*model.Playlist)}
+func (r *playlistRepository) Update(ctx context.Context, id string, entity model.Playlist, cols ...string) error {
+	pls := dbPlaylist{Playlist: entity}
 	pls.ID = id
 	pls.UpdatedAt = time.Now()
-	_, err := r.put(id, pls, append(cols, "updatedAt")...)
+	_, err := r.put(ctx, id, pls, append(cols, "updatedAt")...)
 	return err
 }
 
-func (r *playlistRepository) removeOrphans() error {
+func (r *playlistRepository) removeOrphans(ctx context.Context) error {
 	sel := Select("playlist_tracks.playlist_id as id", "p.name").From("playlist_tracks").
 		Join("playlist p on playlist_tracks.playlist_id = p.id").
 		LeftJoin("media_file mf on playlist_tracks.media_file_id = mf.id").
@@ -457,25 +447,25 @@ func (r *playlistRepository) removeOrphans() error {
 		GroupBy("playlist_tracks.playlist_id")
 
 	var pls []struct{ Id, Name string }
-	err := r.queryAll(sel, &pls)
+	err := r.queryAll(ctx, sel, &pls)
 	if err != nil {
 		return fmt.Errorf("fetching playlists with orphan tracks: %w", err)
 	}
 
 	for _, pl := range pls {
-		log.Debug(r.ctx, "Cleaning-up orphan tracks from playlist", "id", pl.Id, "name", pl.Name)
+		log.Debug(ctx, "Cleaning-up orphan tracks from playlist", "id", pl.Id, "name", pl.Name)
 		del := Delete("playlist_tracks").Where(And{
 			ConcatExpr("media_file_id not in (select id from media_file)"),
 			Eq{"playlist_id": pl.Id},
 		})
-		n, err := r.executeSQL(del)
+		n, err := r.executeSQL(ctx, del)
 		if n == 0 || err != nil {
 			return fmt.Errorf("deleting orphan tracks from playlist %s: %w", pl.Name, err)
 		}
-		log.Debug(r.ctx, "Deleted tracks, now reordering", "id", pl.Id, "name", pl.Name, "deleted", n)
+		log.Debug(ctx, "Deleted tracks, now reordering", "id", pl.Id, "name", pl.Name, "deleted", n)
 
 		// Renumber the playlist if any track was removed
-		if err := r.renumber(pl.Id); err != nil {
+		if err := r.renumber(ctx, pl.Id); err != nil {
 			return fmt.Errorf("renumbering playlist %s: %w", pl.Name, err)
 		}
 	}
@@ -485,9 +475,9 @@ func (r *playlistRepository) removeOrphans() error {
 // renumber updates the position of all tracks in the playlist to be sequential starting from 1, ordered by their
 // current position. This is needed after removing orphan tracks, to ensure there are no gaps in the track numbering.
 // The two-step approach (negate then reassign via CTE) avoids UNIQUE constraint violations on (playlist_id, id).
-func (r *playlistRepository) renumber(id string) error {
+func (r *playlistRepository) renumber(ctx context.Context, id string) error {
 	// Step 1: Negate all IDs to clear the positive ID space
-	_, err := r.executeSQL(Expr(
+	_, err := r.executeSQL(ctx, Expr(
 		`UPDATE playlist_tracks SET id = -id WHERE playlist_id = ? AND id > 0`, id))
 	if err != nil {
 		return err
@@ -495,7 +485,7 @@ func (r *playlistRepository) renumber(id string) error {
 	// Step 2: Assign new sequential positive IDs using UPDATE...FROM with a CTE.
 	// The CTE is fully materialized before the UPDATE begins, avoiding self-referencing issues.
 	// ORDER BY id DESC restores original order since IDs are now negative.
-	_, err = r.executeSQL(Expr(
+	_, err = r.executeSQL(ctx, Expr(
 		`WITH new_ids AS (
 			SELECT rowid as rid, ROW_NUMBER() OVER (ORDER BY id DESC) as new_id
 			FROM playlist_tracks WHERE playlist_id = ?
@@ -506,10 +496,10 @@ func (r *playlistRepository) renumber(id string) error {
 	if err != nil {
 		return err
 	}
-	r.enqueueCoverRebuild(id)
-	return r.refreshCounters(&model.Playlist{ID: id})
+	r.enqueueCoverRebuild(ctx, id)
+	return r.refreshCounters(ctx, &model.Playlist{ID: id})
 }
 
 var _ model.PlaylistRepository = (*playlistRepository)(nil)
-var _ rest.Repository = (*playlistRepository)(nil)
-var _ rest.Persistable = (*playlistRepository)(nil)
+var _ rest.Repository[model.Playlist] = (*playlistRepository)(nil)
+var _ rest.Persistable[model.Playlist] = (*playlistRepository)(nil)
diff --git a/persistence/playlist_repository_test.go b/persistence/playlist_repository_test.go
index 60263807a..93d37c928 100644
--- a/persistence/playlist_repository_test.go
+++ b/persistence/playlist_repository_test.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"slices"
 
 	"github.com/Masterminds/squirrel"
@@ -19,11 +20,11 @@ import (
 
 var _ = Describe("PlaylistRepository", func() {
 	var repo model.PlaylistRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
-		ctx := log.NewContext(GinkgoT().Context())
-		ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-		repo = NewPlaylistRepository(ctx, GetDBXBuilder())
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+		repo = NewPlaylistRepository(GetDBXBuilder())
 	})
 
 	Describe("natural sorting", func() {
@@ -34,23 +35,23 @@ var _ = Describe("PlaylistRepository", func() {
 			conf.Server.EnableNaturalSorting = true
 			ctx := log.NewContext(GinkgoT().Context())
 			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			repo = NewPlaylistRepository(ctx, GetDBXBuilder())
+			repo = NewPlaylistRepository(GetDBXBuilder())
 
 			ids = nil
 			for _, n := range []string{"mix 1", "mix 10", "mix 2"} {
 				pls := model.Playlist{Name: n, OwnerID: "userid"}
-				Expect(repo.Put(&pls)).To(Succeed())
+				Expect(repo.Put(ctx, &pls)).To(Succeed())
 				ids = append(ids, pls.ID)
 			}
 			DeferCleanup(func() {
 				for _, id := range ids {
-					_ = repo.Delete(id)
+					_ = repo.Delete(ctx, id)
 				}
 			})
 		})
 
 		It("sorts playlist names by number value", func() {
-			all, err := repo.GetAll(model.QueryOptions{
+			all, err := repo.GetAll(ctx, model.QueryOptions{
 				Sort: "name", Filters: squirrel.Eq{"playlist.id": ids},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -61,25 +62,25 @@ var _ = Describe("PlaylistRepository", func() {
 
 	Describe("Count", func() {
 		It("returns the number of playlists in the DB", func() {
-			Expect(repo.CountAll()).To(Equal(int64(2)))
+			Expect(repo.CountAll(ctx)).To(Equal(int64(2)))
 		})
 	})
 
 	Describe("GetCursor", func() {
 		It("yields the same playlists as GetAll", func() {
 			opts := model.QueryOptions{Sort: "name"}
-			want, err := repo.GetAll(opts)
+			want, err := repo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(collectCursor(repo.GetCursor(opts))).To(Equal([]model.Playlist(want)))
+			Expect(collectCursor(repo.GetCursor(ctx, opts))).To(Equal([]model.Playlist(want)))
 		})
 	})
 
 	Describe("getAllIDs", func() {
 		It("returns the same id set as GetAll", func() {
-			want, err := repo.GetAll()
+			want, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).ToNot(BeEmpty())
-			ids, err := repo.(*playlistRepository).getAllIDs()
+			ids, err := repo.(*playlistRepository).getAllIDs(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(ids).To(ConsistOf(slice.Map(want, func(p model.Playlist) string { return p.ID })))
 		})
@@ -87,16 +88,16 @@ var _ = Describe("PlaylistRepository", func() {
 
 	Describe("Exists", func() {
 		It("returns true for an existing playlist", func() {
-			Expect(repo.Exists(plsCool.ID)).To(BeTrue())
+			Expect(repo.Exists(ctx, plsCool.ID)).To(BeTrue())
 		})
 		It("returns false for a non-existing playlist", func() {
-			Expect(repo.Exists("666")).To(BeFalse())
+			Expect(repo.Exists(ctx, "666")).To(BeFalse())
 		})
 	})
 
 	Describe("Get", func() {
 		It("returns an existing playlist", func() {
-			p, err := repo.Get(plsBest.ID)
+			p, err := repo.Get(ctx, plsBest.ID)
 			Expect(err).To(BeNil())
 			// Compare all but Tracks and timestamps
 			p2 := *p
@@ -110,11 +111,11 @@ var _ = Describe("PlaylistRepository", func() {
 			}
 		})
 		It("returns ErrNotFound for a non-existing playlist", func() {
-			_, err := repo.Get("666")
+			_, err := repo.Get(ctx, "666")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 		It("returns all tracks", func() {
-			pls, err := repo.GetWithTracks(plsBest.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, plsBest.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(pls.Name).To(Equal(plsBest.Name))
 			Expect(pls.Tracks).To(HaveLen(2))
@@ -138,7 +139,7 @@ var _ = Describe("PlaylistRepository", func() {
 
 		BeforeEach(func() {
 			pls := model.Playlist{Name: "Annotated", OwnerID: "userid"}
-			Expect(repo.Put(&pls)).To(Succeed())
+			Expect(repo.Put(ctx, &pls)).To(Succeed())
 			plsID = pls.ID
 		})
 
@@ -151,18 +152,18 @@ var _ = Describe("PlaylistRepository", func() {
 		}
 
 		It("stores and reads back starred", func() {
-			Expect(repo.SetStar(true, plsID)).To(Succeed())
+			Expect(repo.SetStar(ctx, true, plsID)).To(Succeed())
 
-			p, err := repo.Get(plsID)
+			p, err := repo.Get(ctx, plsID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(p.Starred).To(BeTrue())
 			Expect(p.StarredAt).ToNot(BeNil())
 		})
 
 		It("stores and reads back rating and average_rating", func() {
-			Expect(repo.SetRating(4, plsID)).To(Succeed())
+			Expect(repo.SetRating(ctx, 4, plsID)).To(Succeed())
 
-			p, err := repo.Get(plsID)
+			p, err := repo.Get(ctx, plsID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(p.Rating).To(Equal(4))
 			Expect(p.RatedAt).ToNot(BeNil())
@@ -170,21 +171,21 @@ var _ = Describe("PlaylistRepository", func() {
 		})
 
 		It("keeps annotations isolated per user", func() {
-			Expect(repo.SetStar(true, plsID)).To(Succeed())
+			Expect(repo.SetStar(ctx, true, plsID)).To(Succeed())
 
 			otherCtx := request.WithUser(log.NewContext(GinkgoT().Context()),
 				model.User{ID: "otheruser", UserName: "otheruser", IsAdmin: true})
-			otherRepo := NewPlaylistRepository(otherCtx, GetDBXBuilder())
+			otherRepo := NewPlaylistRepository(GetDBXBuilder())
 
-			p, err := otherRepo.Get(plsID)
+			p, err := otherRepo.Get(otherCtx, plsID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(p.Starred).To(BeFalse())
 		})
 
 		It("reads starred back through GetAll", func() {
-			Expect(repo.SetStar(true, plsID)).To(Succeed())
+			Expect(repo.SetStar(ctx, true, plsID)).To(Succeed())
 
-			all, err := repo.GetAll()
+			all, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			idx := slices.IndexFunc(all, func(p model.Playlist) bool { return p.ID == plsID })
 			Expect(idx).To(BeNumerically(">=", 0))
@@ -192,44 +193,43 @@ var _ = Describe("PlaylistRepository", func() {
 		})
 
 		It("counts playlists using annotation filters", func() {
-			Expect(repo.SetStar(true, plsID)).To(Succeed())
+			Expect(repo.SetStar(ctx, true, plsID)).To(Succeed())
 
 			options := model.QueryOptions{Filters: squirrel.Eq{"starred": true}}
-			starred, err := repo.GetAll(options)
+			starred, err := repo.GetAll(ctx, options)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(starred).To(ContainElement(HaveField("ID", plsID)))
 
-			count, err := repo.CountAll(options)
+			count, err := repo.CountAll(ctx, options)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(int64(len(starred))))
 		})
 
 		It("filters starred playlists through the registered REST filter", func() {
-			Expect(repo.SetStar(true, plsID)).To(Succeed())
+			Expect(repo.SetStar(ctx, true, plsID)).To(Succeed())
 
-			res, err := repo.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+			res, err := repo.ReadAll(ctx, rest.QueryOptions{
 				Filters: map[string]any{"starred": "true"},
 			})
 			Expect(err).ToNot(HaveOccurred())
-			starred := res.(model.Playlists)
-			Expect(starred).To(ContainElement(HaveField("ID", plsID)))
-			for _, p := range starred {
+			Expect(res).To(ContainElement(HaveField("ID", plsID)))
+			for _, p := range res {
 				Expect(p.Starred).To(BeTrue())
 			}
 
-			res, err = repo.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+			res, err = repo.ReadAll(ctx, rest.QueryOptions{
 				Filters: map[string]any{"starred": "false"},
 			})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.(model.Playlists)).ToNot(ContainElement(HaveField("ID", plsID)))
+			Expect(res).ToNot(ContainElement(HaveField("ID", plsID)))
 		})
 
 		It("reads a playlist by id through the REST id filter without ambiguity", func() {
-			res, err := repo.(model.ResourceRepository).ReadAll(rest.QueryOptions{
+			res, err := repo.ReadAll(ctx, rest.QueryOptions{
 				Filters: map[string]any{"id": plsID},
 			})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.(model.Playlists)).To(ContainElement(HaveField("ID", plsID)))
+			Expect(res).To(ContainElement(HaveField("ID", plsID)))
 		})
 
 		It("does not leak an annotation row of another item_type sharing the playlist id", func() {
@@ -240,11 +240,11 @@ var _ = Describe("PlaylistRepository", func() {
 				Bind(dbx.Params{"uid": "userid", "id": plsID}).Execute()
 			Expect(err).ToNot(HaveOccurred())
 
-			p, err := repo.Get(plsID)
+			p, err := repo.Get(ctx, plsID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(p.Starred).To(BeFalse())
 
-			all, err := repo.GetAll()
+			all, err := repo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			matches := 0
 			for _, pl := range all {
@@ -256,12 +256,12 @@ var _ = Describe("PlaylistRepository", func() {
 		})
 
 		It("relies on the annotation sweep, not Delete, to clean up annotations", func() {
-			Expect(repo.SetStar(true, plsID)).To(Succeed())
+			Expect(repo.SetStar(ctx, true, plsID)).To(Succeed())
 
-			Expect(repo.Delete(plsID)).To(Succeed())
+			Expect(repo.Delete(ctx, plsID)).To(Succeed())
 			Expect(countAnnotations()).To(Equal(1))
 
-			Expect(repo.(*playlistRepository).cleanAnnotations()).To(Succeed())
+			Expect(repo.(*playlistRepository).cleanAnnotations(ctx)).To(Succeed())
 			Expect(countAnnotations()).To(Equal(0))
 		})
 	})
@@ -271,8 +271,8 @@ var _ = Describe("PlaylistRepository", func() {
 			pls := model.Playlist{Name: "Smart Counters", OwnerID: "userid", Rules: &criteria.Criteria{
 				Expression: criteria.All{criteria.Contains{"title": "love"}},
 			}}
-			Expect(repo.Put(&pls)).To(Succeed())
-			DeferCleanup(func() { Expect(repo.Delete(pls.ID)).To(Succeed()) })
+			Expect(repo.Put(ctx, &pls)).To(Succeed())
+			DeferCleanup(func() { Expect(repo.Delete(ctx, pls.ID)).To(Succeed()) })
 
 			// Simulate a previous evaluation having stored the counters
 			_, err := GetDBXBuilder().NewQuery("update playlist set song_count = 42, duration = 123, size = 456 where id = {:id}").
@@ -282,9 +282,9 @@ var _ = Describe("PlaylistRepository", func() {
 			pls.SongCount = 0
 			pls.Duration = 0
 			pls.Size = 0
-			Expect(repo.Put(&pls)).To(Succeed())
+			Expect(repo.Put(ctx, &pls)).To(Succeed())
 
-			saved, err := repo.Get(pls.ID)
+			saved, err := repo.Get(ctx, pls.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(saved.SongCount).To(Equal(42))
 			Expect(saved.Duration).To(Equal(float32(123)))
@@ -298,35 +298,35 @@ var _ = Describe("PlaylistRepository", func() {
 		newPls.AddMediaFilesByID([]string{"1004", "1003"})
 
 		By("saves the playlist to the DB")
-		Expect(repo.Put(&newPls)).To(BeNil())
+		Expect(repo.Put(ctx, &newPls)).To(BeNil())
 
 		By("adds repeated songs to a playlist and keeps the order")
 		newPls.AddMediaFilesByID([]string{"1004"})
-		Expect(repo.Put(&newPls)).To(BeNil())
-		saved, _ := repo.GetWithTracks(newPls.ID, true, false)
+		Expect(repo.Put(ctx, &newPls)).To(BeNil())
+		saved, _ := repo.GetWithTracks(ctx, newPls.ID, true, false)
 		Expect(saved.Tracks).To(HaveLen(3))
 		Expect(saved.Tracks[0].MediaFileID).To(Equal("1004"))
 		Expect(saved.Tracks[1].MediaFileID).To(Equal("1003"))
 		Expect(saved.Tracks[2].MediaFileID).To(Equal("1004"))
 
 		By("returns the newly created playlist")
-		Expect(repo.Exists(newPls.ID)).To(BeTrue())
+		Expect(repo.Exists(ctx, newPls.ID)).To(BeTrue())
 
 		By("returns deletes the playlist")
-		Expect(repo.Delete(newPls.ID)).To(BeNil())
+		Expect(repo.Delete(ctx, newPls.ID)).To(BeNil())
 
 		By("returns error if tries to retrieve the deleted playlist")
-		Expect(repo.Exists(newPls.ID)).To(BeFalse())
+		Expect(repo.Exists(ctx, newPls.ID)).To(BeFalse())
 	})
 
 	It("enqueues a new empty playlist's artwork under its generated id, not an empty id", func() {
 		ctx := request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
 		newPls := model.Playlist{Name: "Empty PL", OwnerID: "userid"} // no tracks → refreshCounters path
-		Expect(repo.Put(&newPls)).To(Succeed())
+		Expect(repo.Put(ctx, &newPls)).To(Succeed())
 		Expect(newPls.ID).ToNot(BeEmpty())
-		DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+		DeferCleanup(func() { _ = repo.Delete(ctx, newPls.ID) })
 
-		queued, err := NewArtworkQueueRepository(ctx, GetDBXBuilder()).DequeueBatch(1000)
+		queued, err := NewArtworkQueueRepository(GetDBXBuilder()).DequeueBatch(ctx, 1000)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(queued).To(ContainElement(SatisfyAll(HaveField("ItemKind", "pl"), HaveField("ItemID", newPls.ID))))
 		Expect(queued).ToNot(ContainElement(HaveField("ItemID", "")), "must not enqueue an empty playlist id")
@@ -336,23 +336,23 @@ var _ = Describe("PlaylistRepository", func() {
 	It("does not enqueue artwork when only metadata changes", func() {
 		ctx := request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
 		newPls := model.Playlist{Name: "Rename Me", OwnerID: "userid"}
-		Expect(repo.Put(&newPls)).To(Succeed())
-		DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+		Expect(repo.Put(ctx, &newPls)).To(Succeed())
+		DeferCleanup(func() { _ = repo.Delete(ctx, newPls.ID) })
 		// Clear the row creation just enqueued, so anything present afterwards came from the update.
-		queueRepo := NewArtworkQueueRepository(ctx, GetDBXBuilder())
-		queued, err := queueRepo.DequeueBatch(1000)
+		queueRepo := NewArtworkQueueRepository(GetDBXBuilder())
+		queued, err := queueRepo.DequeueBatch(ctx, 1000)
 		Expect(err).ToNot(HaveOccurred())
 		for _, q := range queued {
 			if q.ItemID == newPls.ID {
-				Expect(queueRepo.DeleteIfUnchanged(q.ItemKind, q.ItemID, q.ImageType, q.RetryAt)).To(Succeed())
+				Expect(queueRepo.DeleteIfUnchanged(ctx, q.ItemKind, q.ItemID, q.ImageType, q.RetryAt)).To(Succeed())
 			}
 		}
 
 		newPls.Name = "Renamed"
 		newPls.Comment = "edited"
-		Expect(repo.Put(&newPls)).To(Succeed())
+		Expect(repo.Put(ctx, &newPls)).To(Succeed())
 
-		queued, err = queueRepo.DequeueBatch(1000)
+		queued, err = queueRepo.DequeueBatch(ctx, 1000)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(queued).ToNot(ContainElement(HaveField("ItemID", newPls.ID)))
 	})
@@ -361,10 +361,10 @@ var _ = Describe("PlaylistRepository", func() {
 		ctx := request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
 		newPls := model.Playlist{Name: "Grid PL", OwnerID: "userid"}
 		newPls.AddMediaFilesByID([]string{"1001", "1002"})
-		Expect(repo.Put(&newPls)).To(Succeed())
-		DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+		Expect(repo.Put(ctx, &newPls)).To(Succeed())
+		DeferCleanup(func() { _ = repo.Delete(ctx, newPls.ID) })
 
-		queued, err := NewArtworkQueueRepository(ctx, GetDBXBuilder()).DequeueBatch(1000)
+		queued, err := NewArtworkQueueRepository(GetDBXBuilder()).DequeueBatch(ctx, 1000)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(queued).To(ContainElement(SatisfyAll(
 			HaveField("ItemKind", "pl"),
@@ -374,7 +374,7 @@ var _ = Describe("PlaylistRepository", func() {
 
 	Describe("GetAll", func() {
 		It("returns all playlists from DB", func() {
-			all, err := repo.GetAll()
+			all, err := repo.GetAll(ctx)
 			Expect(err).To(BeNil())
 			Expect(all[0].ID).To(Equal(plsBest.ID))
 			Expect(all[1].ID).To(Equal(plsCool.ID))
@@ -383,14 +383,14 @@ var _ = Describe("PlaylistRepository", func() {
 
 	Describe("GetPlaylists", func() {
 		It("returns playlists for a track", func() {
-			pls, err := repo.GetPlaylists(songRadioactivity.ID)
+			pls, err := repo.GetPlaylists(ctx, songRadioactivity.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(pls).To(HaveLen(1))
 			Expect(pls[0].ID).To(Equal(plsBest.ID))
 		})
 
 		It("returns empty when none", func() {
-			pls, err := repo.GetPlaylists("9999")
+			pls, err := repo.GetPlaylists(ctx, "9999")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(pls).To(HaveLen(0))
 		})
@@ -401,14 +401,14 @@ var _ = Describe("PlaylistRepository", func() {
 
 		AfterEach(func() {
 			if testPlaylistID != "" {
-				Expect(repo.Delete(testPlaylistID)).To(BeNil())
+				Expect(repo.Delete(ctx, testPlaylistID)).To(BeNil())
 				testPlaylistID = ""
 			}
 		})
 
 		// helper to get track positions and media file IDs
 		getTrackInfo := func(playlistID string) (ids []string, mediaFileIDs []string) {
-			pls, err := repo.GetWithTracks(playlistID, false, false)
+			pls, err := repo.GetWithTracks(ctx, playlistID, false, false)
 			Expect(err).ToNot(HaveOccurred())
 			for _, t := range pls.Tracks {
 				ids = append(ids, t.ID)
@@ -421,12 +421,12 @@ var _ = Describe("PlaylistRepository", func() {
 			By("creating a playlist with 4 tracks")
 			newPls := model.Playlist{Name: "Renumber Test Middle", OwnerID: "userid"}
 			newPls.AddMediaFilesByID([]string{"1001", "1002", "1003", "1004"})
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			By("deleting the second track (position 2)")
-			tracksRepo := repo.Tracks(newPls.ID, false)
-			Expect(tracksRepo.Delete("2")).To(Succeed())
+			tracksRepo := repo.Tracks(ctx, newPls.ID, false)
+			Expect(tracksRepo.Delete(ctx, "2")).To(Succeed())
 
 			By("verifying remaining tracks are renumbered sequentially")
 			ids, mediaFileIDs := getTrackInfo(newPls.ID)
@@ -438,12 +438,12 @@ var _ = Describe("PlaylistRepository", func() {
 			By("creating a playlist with 3 tracks")
 			newPls := model.Playlist{Name: "Renumber Test First", OwnerID: "userid"}
 			newPls.AddMediaFilesByID([]string{"1001", "1002", "1003"})
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			By("deleting the first track (position 1)")
-			tracksRepo := repo.Tracks(newPls.ID, false)
-			Expect(tracksRepo.Delete("1")).To(Succeed())
+			tracksRepo := repo.Tracks(ctx, newPls.ID, false)
+			Expect(tracksRepo.Delete(ctx, "1")).To(Succeed())
 
 			By("verifying remaining tracks are renumbered sequentially")
 			ids, mediaFileIDs := getTrackInfo(newPls.ID)
@@ -455,12 +455,12 @@ var _ = Describe("PlaylistRepository", func() {
 			By("creating a playlist with 3 tracks")
 			newPls := model.Playlist{Name: "Renumber Test Last", OwnerID: "userid"}
 			newPls.AddMediaFilesByID([]string{"1001", "1002", "1003"})
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			By("deleting the last track (position 3)")
-			tracksRepo := repo.Tracks(newPls.ID, false)
-			Expect(tracksRepo.Delete("3")).To(Succeed())
+			tracksRepo := repo.Tracks(ctx, newPls.ID, false)
+			Expect(tracksRepo.Delete(ctx, "3")).To(Succeed())
 
 			By("verifying remaining tracks are renumbered sequentially")
 			ids, mediaFileIDs := getTrackInfo(newPls.ID)
@@ -476,18 +476,18 @@ var _ = Describe("PlaylistRepository", func() {
 			// "userid" is the fixture user; playlist.owner_id has a FK to user(id).
 			owner := model.User{ID: "userid", UserName: "userid"}
 			octx := request.WithUser(GinkgoT().Context(), owner)
-			ownerRepo := NewPlaylistRepository(octx, GetDBXBuilder())
+			ownerRepo := NewPlaylistRepository(GetDBXBuilder())
 			pls := model.Playlist{Name: "Private One", OwnerID: owner.ID, Public: false}
-			Expect(ownerRepo.Put(&pls)).To(Succeed())
-			DeferCleanup(func() { _ = ownerRepo.Delete(pls.ID) })
+			Expect(ownerRepo.Put(octx, &pls)).To(Succeed())
+			DeferCleanup(func() { _ = ownerRepo.Delete(octx, pls.ID) })
 
-			Expect(ownerRepo.Exists(pls.ID)).To(BeTrue(), "the owner sees it")
+			Expect(ownerRepo.Exists(octx, pls.ID)).To(BeTrue(), "the owner sees it")
 
-			anon := NewPlaylistRepository(GinkgoT().Context(), GetDBXBuilder())
-			Expect(anon.Exists(pls.ID)).To(BeFalse(), "no user: userFilter hides it")
+			anon := NewPlaylistRepository(GetDBXBuilder())
+			Expect(anon.Exists(GinkgoT().Context(), pls.ID)).To(BeFalse(), "no user: userFilter hides it")
 
 			admin := request.WithUser(GinkgoT().Context(), model.User{ID: "userid", IsAdmin: true})
-			Expect(NewPlaylistRepository(admin, GetDBXBuilder()).Exists(pls.ID)).To(BeTrue(),
+			Expect(NewPlaylistRepository(GetDBXBuilder()).Exists(admin, pls.ID)).To(BeTrue(),
 				"elevating is what the public image route relies on")
 		})
 	})
diff --git a/persistence/playlist_track_repository.go b/persistence/playlist_track_repository.go
index 848b67be0..341aab8af 100644
--- a/persistence/playlist_track_repository.go
+++ b/persistence/playlist_track_repository.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"database/sql"
 	"slices"
 
@@ -40,11 +41,10 @@ func (t dbPlaylistTracks) toModels() model.PlaylistTracks {
 	})
 }
 
-func (r *playlistRepository) Tracks(playlistId string, refreshSmartPlaylist bool) model.PlaylistTrackRepository {
+func (r *playlistRepository) Tracks(ctx context.Context, playlistId string, refreshSmartPlaylist bool) model.PlaylistTrackRepository {
 	p := &playlistTrackRepository{}
 	p.playlistRepo = r
 	p.playlistId = playlistId
-	p.ctx = r.ctx
 	p.db = r.db
 	p.tableName = "playlist_tracks"
 	p.registerModel(&model.PlaylistTrack{}, map[string]filterFunc{
@@ -67,37 +67,37 @@ func (r *playlistRepository) Tracks(playlistId string, refreshSmartPlaylist bool
 		},
 		"f") // TODO I don't like this solution, but I won't change it now as it's not the focus of BFR.
 
-	pls, err := r.Get(playlistId)
+	pls, err := r.Get(ctx, playlistId)
 	if err != nil {
-		log.Warn(r.ctx, "Error getting playlist's tracks", "playlistId", playlistId, err)
+		log.Warn(ctx, "Error getting playlist's tracks", "playlistId", playlistId, err)
 		return nil
 	}
 	if refreshSmartPlaylist {
-		r.refreshSmartPlaylist(pls)
+		r.refreshSmartPlaylist(ctx, pls)
 	}
 	p.playlist = pls
 	return p
 }
 
-func (r *playlistTrackRepository) CountAll(options ...model.QueryOptions) (int64, error) {
+func (r *playlistTrackRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
 	query := Select().
 		Join("media_file f on f.id = media_file_id").
 		Where(Eq{"playlist_id": r.playlistId})
-	query = r.applyLibraryFilter(query, "f")
-	return r.count(query, options...)
+	query = r.applyLibraryFilter(ctx, query, "f")
+	return r.count(ctx, query, options...)
 }
 
-func (r *playlistTrackRepository) Count(options ...rest.QueryOptions) (int64, error) {
+func (r *playlistTrackRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
 	query := Select().
 		LeftJoin("media_file f on f.id = media_file_id").
 		Where(Eq{"playlist_id": r.playlistId})
-	query = r.applyLibraryFilter(query, "f")
-	return r.count(query, r.parseRestOptions(r.ctx, options...))
+	query = r.applyLibraryFilter(ctx, query, "f")
+	return r.count(ctx, query, r.parseRestOptions(ctx, options...))
 }
 
-func (r *playlistTrackRepository) Read(id string) (any, error) {
-	userID := loggedUser(r.ctx).ID
-	sel := r.newSelect().
+func (r *playlistTrackRepository) Read(ctx context.Context, id string) (*model.PlaylistTrack, error) {
+	userID := loggedUser(ctx).ID
+	sel := r.newSelect(ctx).
 		LeftJoin("annotation on ("+
 			"annotation.item_id = media_file_id"+
 			" AND annotation.item_type = 'media_file'"+
@@ -114,23 +114,23 @@ func (r *playlistTrackRepository) Read(id string) (any, error) {
 		).
 		Join("media_file f on f.id = media_file_id").
 		Where(And{Eq{"playlist_id": r.playlistId}, Eq{"playlist_tracks.id": id}})
-	sel = r.applyLibraryFilter(sel, "f")
+	sel = r.applyLibraryFilter(ctx, sel, "f")
 	var trk dbPlaylistTrack
-	err := r.queryOne(sel, &trk)
+	err := r.queryOne(ctx, sel, &trk)
 	return trk.PlaylistTrack, err
 }
 
-func (r *playlistTrackRepository) GetAll(options ...model.QueryOptions) (model.PlaylistTracks, error) {
-	tracks, err := r.playlistRepo.loadTracks(r.newSelect(options...), r.playlistId)
+func (r *playlistTrackRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.PlaylistTracks, error) {
+	tracks, err := r.playlistRepo.loadTracks(ctx, r.newSelect(ctx, options...), r.playlistId)
 	if err != nil {
 		return nil, err
 	}
 	return tracks, err
 }
 
-func (r *playlistTrackRepository) GetCursor(options ...model.QueryOptions) (model.PlaylistTrackCursor, error) {
-	sel := r.playlistRepo.tracksQuery(r.newSelect(options...), r.playlistId)
-	cursor, err := queryWithStableResults[dbPlaylistTrack](r.sqlRepository, sel)
+func (r *playlistTrackRepository) GetCursor(ctx context.Context, options ...model.QueryOptions) (model.PlaylistTrackCursor, error) {
+	sel := r.playlistRepo.tracksQuery(ctx, r.newSelect(ctx, options...), r.playlistId)
+	cursor, err := queryWithStableResults[dbPlaylistTrack](ctx, r.sqlRepository, sel)
 	if err != nil {
 		return nil, err
 	}
@@ -138,114 +138,106 @@ func (r *playlistTrackRepository) GetCursor(options ...model.QueryOptions) (mode
 		return t.PlaylistTrack
 	})
 	return model.PlaylistTrackCursor(hydrateCursor(tracks, func(batch []model.PlaylistTrack) {
-		hydratePlaylistTrackArtwork(r.ctx, r.db, batch)
+		hydratePlaylistTrackArtwork(ctx, r.db, batch)
 	})), nil
 }
 
 // GetMediaFileIDs returns the tracks' song ids, for callers that need every id but no track data.
-func (r *playlistTrackRepository) GetMediaFileIDs(options ...model.QueryOptions) ([]string, error) {
-	query := r.newSelect(options...).Columns("media_file_id").
+func (r *playlistTrackRepository) GetMediaFileIDs(ctx context.Context, options ...model.QueryOptions) ([]string, error) {
+	query := r.newSelect(ctx, options...).Columns("media_file_id").
 		Join("media_file f on f.id = media_file_id").
 		Where(Eq{"playlist_id": r.playlistId})
-	query = r.applyLibraryFilter(query, "f")
+	query = r.applyLibraryFilter(ctx, query, "f")
 	var ids []string
-	if err := r.queryAllSlice(query, &ids); err != nil {
+	if err := r.queryAllSlice(ctx, query, &ids); err != nil {
 		return nil, err
 	}
 	return ids, nil
 }
 
-func (r *playlistTrackRepository) GetAlbumIDs(options ...model.QueryOptions) ([]string, error) {
-	query := r.newSelect(options...).Columns("distinct mf.album_id").
+func (r *playlistTrackRepository) GetAlbumIDs(ctx context.Context, options ...model.QueryOptions) ([]string, error) {
+	query := r.newSelect(ctx, options...).Columns("distinct mf.album_id").
 		Join("media_file mf on mf.id = media_file_id").
 		Where(Eq{"playlist_id": r.playlistId})
-	query = r.applyLibraryFilter(query, "mf")
+	query = r.applyLibraryFilter(ctx, query, "mf")
 	var ids []string
-	err := r.queryAllSlice(query, &ids)
+	err := r.queryAllSlice(ctx, query, &ids)
 	if err != nil {
 		return nil, err
 	}
 	return ids, nil
 }
 
-func (r *playlistTrackRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
+func (r *playlistTrackRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.PlaylistTrack, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *playlistTrackRepository) EntityName() string {
-	return "playlist_tracks"
-}
-
-func (r *playlistTrackRepository) NewInstance() any {
-	return &model.PlaylistTrack{}
-}
-
-func (r *playlistTrackRepository) Add(mediaFileIds []string) (int, error) {
+func (r *playlistTrackRepository) Add(ctx context.Context, mediaFileIds []string) (int, error) {
 	if len(mediaFileIds) > 0 {
-		log.Debug(r.ctx, "Adding songs to playlist", "playlistId", r.playlistId, "mediaFileIds", mediaFileIds)
+		log.Debug(ctx, "Adding songs to playlist", "playlistId", r.playlistId, "mediaFileIds", mediaFileIds)
 	} else {
 		return 0, nil
 	}
 
 	// Get next pos (ID) in playlist
-	sq := r.newSelect().Columns("max(id) as max").Where(Eq{"playlist_id": r.playlistId})
+	sq := r.newSelect(ctx).Columns("max(id) as max").Where(Eq{"playlist_id": r.playlistId})
 	var res struct{ Max sql.NullInt32 }
-	if err := r.queryOne(sq, &res); err != nil {
+	if err := r.queryOne(ctx, sq, &res); err != nil {
 		return 0, err
 	}
 
-	return r.playlistRepo.addTracks(r.playlistId, int(res.Max.Int32+1), mediaFileIds)
+	return r.playlistRepo.addTracks(ctx, r.playlistId, int(res.Max.Int32+1), mediaFileIds)
 }
 
 // Insert adds tracks before the 1-based position pos, shifting the following entries down; a
 // position past the end appends. Callers must run it in a transaction.
-func (r *playlistTrackRepository) Insert(mediaFileIds []string, pos int) (int, error) {
+func (r *playlistTrackRepository) Insert(ctx context.Context, mediaFileIds []string, pos int) (int, error) {
 	if len(mediaFileIds) == 0 {
 		return 0, nil
 	}
 	pos = max(pos, 1)
 	n := len(mediaFileIds)
 	// Negate while shifting, so no intermediate row hits the unique (playlist_id, id) index.
-	_, err := r.executeSQL(Expr(`UPDATE playlist_tracks SET id = -(id + ?) WHERE playlist_id = ? AND id >= ?`, n, r.playlistId, pos))
+	_, err := r.executeSQL(ctx, Expr(`UPDATE playlist_tracks SET id = -(id + ?) WHERE playlist_id = ? AND id >= ?`, n, r.playlistId, pos))
 	if err != nil {
 		return 0, err
 	}
-	res, err := r.executeSQL(Expr(`UPDATE playlist_tracks SET id = -id WHERE playlist_id = ? AND id < 0`, r.playlistId))
+	res, err := r.executeSQL(ctx, Expr(`UPDATE playlist_tracks SET id = -id WHERE playlist_id = ? AND id < 0`, r.playlistId))
 	if err != nil {
 		return 0, err
 	}
 	if res == 0 {
-		return r.Add(mediaFileIds)
+		return r.Add(ctx, mediaFileIds)
 	}
-	inserted, err := r.playlistRepo.addTracks(r.playlistId, pos, mediaFileIds)
+	inserted, err := r.playlistRepo.addTracks(ctx, r.playlistId, pos, mediaFileIds)
 	if err != nil || inserted == n {
 		return inserted, err
 	}
 	// The shift above reserved a slot per requested id, so ids dropped by the library filter
 	// leave a hole. Close it.
-	return inserted, r.playlistRepo.renumber(r.playlistId)
+	return inserted, r.playlistRepo.renumber(ctx, r.playlistId)
 }
 
-func (r *playlistTrackRepository) addMediaFileIds(cond Sqlizer) (int, error) {
+func (r *playlistTrackRepository) addMediaFileIds(ctx context.Context, cond Sqlizer) (int, error) {
 	sq := Select("id").From("media_file").Where(cond).OrderBy("album_artist, album, release_date, disc_number, track_number")
 	var ids []string
-	err := r.queryAllSlice(sq, &ids)
+	err := r.queryAllSlice(ctx, sq, &ids)
 	if err != nil {
-		log.Error(r.ctx, "Error getting tracks to add to playlist", err)
+		log.Error(ctx, "Error getting tracks to add to playlist", err)
 		return 0, err
 	}
-	return r.Add(ids)
+	return r.Add(ctx, ids)
 }
 
-func (r *playlistTrackRepository) AddAlbums(albumIds []string) (int, error) {
-	return r.addMediaFileIds(Eq{"album_id": albumIds})
+func (r *playlistTrackRepository) AddAlbums(ctx context.Context, albumIds []string) (int, error) {
+	return r.addMediaFileIds(ctx, Eq{"album_id": albumIds})
 }
 
-func (r *playlistTrackRepository) AddArtists(artistIds []string) (int, error) {
-	return r.addMediaFileIds(Eq{"album_artist_id": artistIds})
+func (r *playlistTrackRepository) AddArtists(ctx context.Context, artistIds []string) (int, error) {
+	return r.addMediaFileIds(ctx, Eq{"album_artist_id": artistIds})
 }
 
-func (r *playlistTrackRepository) AddDiscs(discs []model.DiscID) (int, error) {
+func (r *playlistTrackRepository) AddDiscs(ctx context.Context, discs []model.DiscID) (int, error) {
 	if len(discs) == 0 {
 		return 0, nil
 	}
@@ -253,36 +245,36 @@ func (r *playlistTrackRepository) AddDiscs(discs []model.DiscID) (int, error) {
 	for _, d := range discs {
 		clauses = append(clauses, And{Eq{"album_id": d.AlbumID}, Eq{"release_date": d.ReleaseDate}, Eq{"disc_number": d.DiscNumber}})
 	}
-	return r.addMediaFileIds(clauses)
+	return r.addMediaFileIds(ctx, clauses)
 }
 
 // deleteChunkSize keeps each DELETE under SQLITE_MAX_VARIABLE_NUMBER, matching addTracks.
 const deleteChunkSize = 200
 
-func (r *playlistTrackRepository) Delete(ids ...string) error {
+func (r *playlistTrackRepository) Delete(ctx context.Context, ids ...string) error {
 	for chunk := range slices.Chunk(ids, deleteChunkSize) {
-		if err := r.delete(And{Eq{"playlist_id": r.playlistId}, Eq{"id": chunk}}); err != nil {
+		if err := r.delete(ctx, And{Eq{"playlist_id": r.playlistId}, Eq{"id": chunk}}); err != nil {
 			return err
 		}
 	}
 
-	return r.playlistRepo.renumber(r.playlistId)
+	return r.playlistRepo.renumber(ctx, r.playlistId)
 }
 
-func (r *playlistTrackRepository) DeleteAll() error {
-	err := r.delete(Eq{"playlist_id": r.playlistId})
+func (r *playlistTrackRepository) DeleteAll(ctx context.Context) error {
+	err := r.delete(ctx, Eq{"playlist_id": r.playlistId})
 	if err != nil {
 		return err
 	}
 
-	return r.playlistRepo.renumber(r.playlistId)
+	return r.playlistRepo.renumber(ctx, r.playlistId)
 }
 
 // Reorder moves a track from pos to newPos, shifting other tracks accordingly. newPos is clamped
 // to the playlist; a pos outside it is ErrNotFound, since shifting around it would leave a gap.
-func (r *playlistTrackRepository) Reorder(pos int, newPos int) error {
+func (r *playlistTrackRepository) Reorder(ctx context.Context, pos int, newPos int) error {
 	var res struct{ Max sql.NullInt32 }
-	if err := r.queryOne(r.newSelect().Columns("max(id) as max").Where(Eq{"playlist_id": r.playlistId}), &res); err != nil {
+	if err := r.queryOne(ctx, r.newSelect(ctx).Columns("max(id) as max").Where(Eq{"playlist_id": r.playlistId}), &res); err != nil {
 		return err
 	}
 	last := int(res.Max.Int32)
@@ -296,7 +288,7 @@ func (r *playlistTrackRepository) Reorder(pos int, newPos int) error {
 	pid := r.playlistId
 
 	// Step 1: Move the source track out of the way (temporary sentinel value)
-	_, err := r.executeSQL(Expr(
+	_, err := r.executeSQL(ctx, Expr(
 		`UPDATE playlist_tracks SET id = -999999 WHERE playlist_id = ? AND id = ?`, pid, pos))
 	if err != nil {
 		return err
@@ -304,11 +296,11 @@ func (r *playlistTrackRepository) Reorder(pos int, newPos int) error {
 
 	// Step 2: Shift the affected range using negative values to avoid unique constraint violations
 	if pos < newPos {
-		_, err = r.executeSQL(Expr(
+		_, err = r.executeSQL(ctx, Expr(
 			`UPDATE playlist_tracks SET id = -(id - 1) WHERE playlist_id = ? AND id > ? AND id <= ?`,
 			pid, pos, newPos))
 	} else {
-		_, err = r.executeSQL(Expr(
+		_, err = r.executeSQL(ctx, Expr(
 			`UPDATE playlist_tracks SET id = -(id + 1) WHERE playlist_id = ? AND id >= ? AND id < ?`,
 			pid, newPos, pos))
 	}
@@ -317,14 +309,14 @@ func (r *playlistTrackRepository) Reorder(pos int, newPos int) error {
 	}
 
 	// Step 3: Flip the shifted range back to positive
-	_, err = r.executeSQL(Expr(
+	_, err = r.executeSQL(ctx, Expr(
 		`UPDATE playlist_tracks SET id = -id WHERE playlist_id = ? AND id < 0 AND id != -999999`, pid))
 	if err != nil {
 		return err
 	}
 
 	// Step 4: Place the source track at its new position
-	_, err = r.executeSQL(Expr(
+	_, err = r.executeSQL(ctx, Expr(
 		`UPDATE playlist_tracks SET id = ? WHERE playlist_id = ? AND id = -999999`, newPos, pid))
 	return err
 }
diff --git a/persistence/playlist_track_repository_test.go b/persistence/playlist_track_repository_test.go
index 1a6bc9dc6..3c532c405 100644
--- a/persistence/playlist_track_repository_test.go
+++ b/persistence/playlist_track_repository_test.go
@@ -17,30 +17,31 @@ const sqliteMaxVariables = 32766
 
 var _ = Describe("PlaylistTrackRepository", func() {
 	var repo model.PlaylistTrackRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
-		ctx := log.NewContext(GinkgoT().Context())
+		ctx = log.NewContext(GinkgoT().Context())
 		ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-		repo = NewPlaylistRepository(ctx, GetDBXBuilder()).Tracks(plsBest.ID, true)
+		repo = NewPlaylistRepository(GetDBXBuilder()).Tracks(ctx, plsBest.ID, true)
 	})
 
 	Describe("GetCursor", func() {
 		It("yields the same tracks as GetAll", func() {
 			opts := model.QueryOptions{Sort: "id"}
-			want, err := repo.GetAll(opts)
+			want, err := repo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).To(HaveLen(2))
 
-			Expect(collectCursor(repo.GetCursor(opts))).To(Equal([]model.PlaylistTrack(want)))
+			Expect(collectCursor(repo.GetCursor(ctx, opts))).To(Equal([]model.PlaylistTrack(want)))
 		})
 
 		It("honors Max and Offset", func() {
 			opts := model.QueryOptions{Sort: "id", Max: 1, Offset: 1}
-			want, err := repo.GetAll(opts)
+			want, err := repo.GetAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(want).To(HaveLen(1))
 
-			Expect(collectCursor(repo.GetCursor(opts))).To(Equal([]model.PlaylistTrack(want)))
+			Expect(collectCursor(repo.GetCursor(ctx, opts))).To(Equal([]model.PlaylistTrack(want)))
 		})
 	})
 
@@ -48,11 +49,11 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		It("returns every row under a random sort, despite the integer id", func() {
 			// playlist_tracks.id is an INTEGER, so SEEDEDRAND drops every row unless it is cast to
 			// TEXT, and it fails silently: no error, just no rows.
-			all, err := repo.GetAll(model.QueryOptions{Sort: "random"})
+			all, err := repo.GetAll(ctx, model.QueryOptions{Sort: "random"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(all).To(HaveLen(2), "a random sort must not silently drop rows")
 
-			got, err := repo.GetAll(model.QueryOptions{Sort: "random", Max: 1})
+			got, err := repo.GetAll(ctx, model.QueryOptions{Sort: "random", Max: 1})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got).To(HaveLen(1))
 		})
@@ -60,22 +61,22 @@ var _ = Describe("PlaylistTrackRepository", func() {
 
 	Describe("CountAll", func() {
 		It("returns the number of tracks in the playlist", func() {
-			Expect(repo.CountAll()).To(Equal(int64(2)))
+			Expect(repo.CountAll(ctx)).To(Equal(int64(2)))
 		})
 
 		It("ignores Max and Offset", func() {
-			Expect(repo.CountAll(model.QueryOptions{Max: 1, Offset: 1})).To(Equal(int64(2)))
+			Expect(repo.CountAll(ctx, model.QueryOptions{Max: 1, Offset: 1})).To(Equal(int64(2)))
 		})
 	})
 
 	Describe("GetMediaFileIDs", func() {
 		It("returns the song ids in playlist order", func() {
-			Expect(repo.GetMediaFileIDs(model.QueryOptions{Sort: "id"})).
+			Expect(repo.GetMediaFileIDs(ctx, model.QueryOptions{Sort: "id"})).
 				To(Equal([]string{songDayInALife.ID, songRadioactivity.ID}))
 		})
 
 		It("honors Max and Offset", func() {
-			Expect(repo.GetMediaFileIDs(model.QueryOptions{Sort: "id", Max: 1, Offset: 1})).
+			Expect(repo.GetMediaFileIDs(ctx, model.QueryOptions{Sort: "id", Max: 1, Offset: 1})).
 				To(Equal([]string{songRadioactivity.ID}))
 		})
 	})
@@ -84,28 +85,26 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		var tracks model.PlaylistTrackRepository
 
 		BeforeEach(func() {
-			ctx := log.NewContext(GinkgoT().Context())
-			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			plsRepo := NewPlaylistRepository(ctx, GetDBXBuilder())
+			plsRepo := NewPlaylistRepository(GetDBXBuilder())
 			pls := model.Playlist{Name: "Insert", OwnerID: "userid", OwnerName: "userid"}
-			Expect(plsRepo.Put(&pls)).To(Succeed())
-			DeferCleanup(func() { Expect(plsRepo.Delete(pls.ID)).To(Succeed()) })
+			Expect(plsRepo.Put(ctx, &pls)).To(Succeed())
+			DeferCleanup(func() { Expect(plsRepo.Delete(ctx, pls.ID)).To(Succeed()) })
 
-			tracks = plsRepo.Tracks(pls.ID, false)
-			Expect(tracks.Add([]string{songDayInALife.ID, songRadioactivity.ID})).To(Equal(2))
+			tracks = plsRepo.Tracks(ctx, pls.ID, false)
+			Expect(tracks.Add(ctx, []string{songDayInALife.ID, songRadioactivity.ID})).To(Equal(2))
 		})
 
 		order := func() []string {
-			ids, err := tracks.GetMediaFileIDs(model.QueryOptions{Sort: "id"})
+			ids, err := tracks.GetMediaFileIDs(ctx, model.QueryOptions{Sort: "id"})
 			Expect(err).ToNot(HaveOccurred())
 			return ids
 		}
 
 		DescribeTable("inserts before a 1-based position, keeping the new tracks' order",
 			func(pos int, want func() []string) {
-				Expect(tracks.Insert([]string{songComeTogether.ID, songAntenna.ID}, pos)).To(Equal(2))
+				Expect(tracks.Insert(ctx, []string{songComeTogether.ID, songAntenna.ID}, pos)).To(Equal(2))
 				Expect(order()).To(Equal(want()))
-				Expect(tracks.CountAll()).To(Equal(int64(4)))
+				Expect(tracks.CountAll(ctx)).To(Equal(int64(4)))
 			},
 			Entry("in the middle", 2, func() []string {
 				return []string{songDayInALife.ID, songComeTogether.ID, songAntenna.ID, songRadioactivity.ID}
@@ -119,8 +118,8 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		)
 
 		It("renumbers positions contiguously", func() {
-			Expect(tracks.Insert([]string{songComeTogether.ID}, 1)).To(Equal(1))
-			all, err := tracks.GetAll(model.QueryOptions{Sort: "id"})
+			Expect(tracks.Insert(ctx, []string{songComeTogether.ID}, 1)).To(Equal(1))
+			all, err := tracks.GetAll(ctx, model.QueryOptions{Sort: "id"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect([]string{all[0].ID, all[1].ID, all[2].ID}).To(Equal([]string{"1", "2", "3"}))
 		})
@@ -130,19 +129,17 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		var tracks model.PlaylistTrackRepository
 
 		BeforeEach(func() {
-			ctx := log.NewContext(GinkgoT().Context())
-			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			plsRepo := NewPlaylistRepository(ctx, GetDBXBuilder())
+			plsRepo := NewPlaylistRepository(GetDBXBuilder())
 			pls := model.Playlist{Name: "Reorder", OwnerID: "userid", OwnerName: "userid"}
-			Expect(plsRepo.Put(&pls)).To(Succeed())
-			DeferCleanup(func() { Expect(plsRepo.Delete(pls.ID)).To(Succeed()) })
+			Expect(plsRepo.Put(ctx, &pls)).To(Succeed())
+			DeferCleanup(func() { Expect(plsRepo.Delete(ctx, pls.ID)).To(Succeed()) })
 
-			tracks = plsRepo.Tracks(pls.ID, false)
-			Expect(tracks.Add([]string{songDayInALife.ID, songRadioactivity.ID, songComeTogether.ID})).To(Equal(3))
+			tracks = plsRepo.Tracks(ctx, pls.ID, false)
+			Expect(tracks.Add(ctx, []string{songDayInALife.ID, songRadioactivity.ID, songComeTogether.ID})).To(Equal(3))
 		})
 
 		rows := func() ([]string, []string) {
-			all, err := tracks.GetAll(model.QueryOptions{Sort: "id"})
+			all, err := tracks.GetAll(ctx, model.QueryOptions{Sort: "id"})
 			Expect(err).ToNot(HaveOccurred())
 			var ids, songs []string
 			for _, t := range all {
@@ -154,7 +151,7 @@ var _ = Describe("PlaylistTrackRepository", func() {
 
 		DescribeTable("clamps the destination to the playlist",
 			func(newPos int, want func() []string) {
-				Expect(tracks.Reorder(1, newPos)).To(Succeed())
+				Expect(tracks.Reorder(ctx, 1, newPos)).To(Succeed())
 				ids, songs := rows()
 				Expect(ids).To(Equal([]string{"1", "2", "3"}))
 				Expect(songs).To(Equal(want()))
@@ -169,7 +166,7 @@ var _ = Describe("PlaylistTrackRepository", func() {
 
 		DescribeTable("rejects a source position outside the playlist, leaving rows untouched",
 			func(pos int) {
-				Expect(tracks.Reorder(pos, 1)).To(MatchError(model.ErrNotFound))
+				Expect(tracks.Reorder(ctx, pos, 1)).To(MatchError(model.ErrNotFound))
 				ids, songs := rows()
 				Expect(ids).To(Equal([]string{"1", "2", "3"}))
 				Expect(songs).To(Equal([]string{songDayInALife.ID, songRadioactivity.ID, songComeTogether.ID}))
@@ -192,35 +189,33 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		}
 
 		BeforeEach(func() {
-			ctx := log.NewContext(GinkgoT().Context())
-			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			plsRepo := NewPlaylistRepository(ctx, GetDBXBuilder())
+			plsRepo := NewPlaylistRepository(GetDBXBuilder())
 
 			pls := model.Playlist{Name: "Chunked Delete", OwnerID: "userid", OwnerName: "userid"}
-			Expect(plsRepo.Put(&pls)).To(Succeed())
-			DeferCleanup(func() { Expect(plsRepo.Delete(pls.ID)).To(Succeed()) })
+			Expect(plsRepo.Put(ctx, &pls)).To(Succeed())
+			DeferCleanup(func() { Expect(plsRepo.Delete(ctx, pls.ID)).To(Succeed()) })
 
-			tracks = plsRepo.Tracks(pls.ID, false)
+			tracks = plsRepo.Tracks(ctx, pls.ID, false)
 			songIds := make([]string, numTracks)
 			for i := range songIds {
 				songIds[i] = songDayInALife.ID
 			}
-			Expect(tracks.Add(songIds)).To(Equal(numTracks))
+			Expect(tracks.Add(ctx, songIds)).To(Equal(numTracks))
 		})
 
 		It("removes positions spanning several chunks, and renumbers what is left", func() {
-			Expect(tracks.Delete(positionsUpTo(numTracks - 1)...)).To(Succeed())
+			Expect(tracks.Delete(ctx, positionsUpTo(numTracks-1)...)).To(Succeed())
 
-			Expect(tracks.CountAll()).To(Equal(int64(1)))
-			remaining, err := tracks.GetAll(model.QueryOptions{Sort: "id"})
+			Expect(tracks.CountAll(ctx)).To(Equal(int64(1)))
+			remaining, err := tracks.GetAll(ctx, model.QueryOptions{Sort: "id"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(remaining[0].ID).To(Equal("1"), "the surviving track must be renumbered to position 1")
 		})
 
 		It("accepts more ids than SQLite allows as bind variables", func() {
-			Expect(tracks.Delete(positionsUpTo(sqliteMaxVariables + 100)...)).To(Succeed())
+			Expect(tracks.Delete(ctx, positionsUpTo(sqliteMaxVariables+100)...)).To(Succeed())
 
-			Expect(tracks.CountAll()).To(BeZero())
+			Expect(tracks.CountAll(ctx)).To(BeZero())
 		})
 	})
 
@@ -236,69 +231,69 @@ var _ = Describe("PlaylistTrackRepository", func() {
 			userCtx = request.WithUser(log.NewContext(GinkgoT().Context()), restrictedUser)
 			db := GetDBXBuilder()
 
-			adminMr := NewMediaFileRepository(adminCtx, db)
-			Expect(adminMr.Put(&model.MediaFile{
+			adminMr := NewMediaFileRepository(db)
+			Expect(adminMr.Put(adminCtx, &model.MediaFile{
 				ID: "pls-otherlib-track", LibraryID: otherLib.ID, AlbumID: "pls-hidden-album",
 				Path: "hidden/in-playlist.mp3", Title: "Hidden In Playlist",
 			})).To(Succeed())
-			DeferCleanup(func() { _ = adminMr.Delete("pls-otherlib-track") })
+			DeferCleanup(func() { _ = adminMr.Delete(adminCtx, "pls-otherlib-track") })
 
-			adminPls := NewPlaylistRepository(adminCtx, db)
+			adminPls := NewPlaylistRepository(db)
 			pls := model.Playlist{Name: "Public Mixed", OwnerID: adminUser.ID, OwnerName: adminUser.UserName, Public: true}
-			Expect(adminPls.Put(&pls)).To(Succeed())
+			Expect(adminPls.Put(adminCtx, &pls)).To(Succeed())
 			plsID = pls.ID
-			DeferCleanup(func() { _ = adminPls.Delete(plsID) })
-			Expect(adminPls.Tracks(plsID, false).Add([]string{songDayInALife.ID, "pls-otherlib-track"})).To(Equal(2))
+			DeferCleanup(func() { _ = adminPls.Delete(adminCtx, plsID) })
+			Expect(adminPls.Tracks(adminCtx, plsID, false).Add(adminCtx, []string{songDayInALife.ID, "pls-otherlib-track"})).To(Equal(2))
 
-			userTracks = NewPlaylistRepository(userCtx, db).Tracks(plsID, false)
+			userTracks = NewPlaylistRepository(db).Tracks(userCtx, plsID, false)
 		})
 
 		It("Read does not return a track outside the user's libraries", func() {
-			_, err := userTracks.Read("2")
+			_, err := userTracks.Read(userCtx, "2")
 			Expect(err).To(MatchError(model.ErrNotFound), "position 2 holds a track the user cannot access")
 		})
 
 		It("Read still returns a track inside the user's libraries", func() {
-			trk, err := userTracks.Read("1")
+			trk, err := userTracks.Read(userCtx, "1")
 			Expect(err).ToNot(HaveOccurred())
-			Expect(trk.(*model.PlaylistTrack).MediaFile.ID).To(Equal(songDayInALife.ID))
+			Expect(trk.MediaFile.ID).To(Equal(songDayInALife.ID))
 		})
 
 		It("Count excludes tracks outside the user's libraries", func() {
-			Expect(userTracks.Count()).To(Equal(int64(1)), "Count must agree with the filtered listing")
+			Expect(userTracks.Count(userCtx)).To(Equal(int64(1)), "Count must agree with the filtered listing")
 		})
 
 		It("GetAlbumIDs excludes albums outside the user's libraries", func() {
-			Expect(userTracks.GetAlbumIDs()).ToNot(ContainElement("pls-hidden-album"))
+			Expect(userTracks.GetAlbumIDs(userCtx)).ToNot(ContainElement("pls-hidden-album"))
 		})
 
 		Describe("Add", func() {
 			var ownTracks model.PlaylistTrackRepository
 
 			BeforeEach(func() {
-				userPls := NewPlaylistRepository(userCtx, GetDBXBuilder())
+				userPls := NewPlaylistRepository(GetDBXBuilder())
 				own := model.Playlist{Name: "Own Playlist", OwnerID: restrictedUser.ID, OwnerName: restrictedUser.UserName}
-				Expect(userPls.Put(&own)).To(Succeed())
-				DeferCleanup(func() { _ = NewPlaylistRepository(adminCtx, GetDBXBuilder()).Delete(own.ID) })
-				ownTracks = userPls.Tracks(own.ID, false)
+				Expect(userPls.Put(userCtx, &own)).To(Succeed())
+				DeferCleanup(func() { _ = NewPlaylistRepository(GetDBXBuilder()).Delete(adminCtx, own.ID) })
+				ownTracks = userPls.Tracks(userCtx, own.ID, false)
 			})
 
 			It("drops ids outside the user's libraries", func() {
-				Expect(ownTracks.Add([]string{songDayInALife.ID, "pls-otherlib-track"})).To(Equal(1))
-				Expect(ownTracks.GetMediaFileIDs()).To(ConsistOf(songDayInALife.ID))
+				Expect(ownTracks.Add(userCtx, []string{songDayInALife.ID, "pls-otherlib-track"})).To(Equal(1))
+				Expect(ownTracks.GetMediaFileIDs(userCtx)).To(ConsistOf(songDayInALife.ID))
 			})
 
 			It("drops them when reached through AddAlbums", func() {
-				Expect(ownTracks.AddAlbums([]string{"pls-hidden-album"})).To(BeZero())
+				Expect(ownTracks.AddAlbums(userCtx, []string{"pls-hidden-album"})).To(BeZero())
 			})
 
 			It("drops them when reached through Insert", func() {
-				Expect(ownTracks.Add([]string{songDayInALife.ID})).To(Equal(1))
+				Expect(ownTracks.Add(userCtx, []string{songDayInALife.ID})).To(Equal(1))
 
-				Expect(ownTracks.Insert([]string{"pls-otherlib-track", songComeTogether.ID}, 1)).To(Equal(1))
+				Expect(ownTracks.Insert(userCtx, []string{"pls-otherlib-track", songComeTogether.ID}, 1)).To(Equal(1))
 
-				Expect(ownTracks.GetMediaFileIDs()).To(Equal([]string{songComeTogether.ID, songDayInALife.ID}))
-				trks, err := ownTracks.GetAll(model.QueryOptions{Sort: "id"})
+				Expect(ownTracks.GetMediaFileIDs(userCtx)).To(Equal([]string{songComeTogether.ID, songDayInALife.ID}))
+				trks, err := ownTracks.GetAll(userCtx, model.QueryOptions{Sort: "id"})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(slice.Map(trks, func(t model.PlaylistTrack) string { return t.ID })).To(Equal([]string{"1", "2"}),
 					"positions must stay contiguous when an id is dropped")
@@ -307,7 +302,7 @@ var _ = Describe("PlaylistTrackRepository", func() {
 
 		Describe("Put", func() {
 			storedIDs := func(id string) []string {
-				ids, err := NewPlaylistRepository(adminCtx, GetDBXBuilder()).Tracks(id, false).GetMediaFileIDs()
+				ids, err := NewPlaylistRepository(GetDBXBuilder()).Tracks(adminCtx, id, false).GetMediaFileIDs(adminCtx)
 				Expect(err).ToNot(HaveOccurred())
 				return ids
 			}
@@ -315,8 +310,8 @@ var _ = Describe("PlaylistTrackRepository", func() {
 				pls.OwnerID = owner.ID
 				pls.Tracks = nil
 				pls.AddMediaFilesByID(ids)
-				Expect(NewPlaylistRepository(ctx, GetDBXBuilder()).Put(pls)).To(Succeed())
-				DeferCleanup(func() { _ = NewPlaylistRepository(adminCtx, GetDBXBuilder()).Delete(pls.ID) })
+				Expect(NewPlaylistRepository(GetDBXBuilder()).Put(ctx, pls)).To(Succeed())
+				DeferCleanup(func() { _ = NewPlaylistRepository(GetDBXBuilder()).Delete(adminCtx, pls.ID) })
 				return pls.ID
 			}
 
@@ -339,10 +334,10 @@ var _ = Describe("PlaylistTrackRepository", func() {
 				hidden := put(userCtx, restrictedUser, &model.Playlist{Name: "Hidden"}, songDayInALife.ID, "pls-otherlib-track")
 				unknown := put(userCtx, restrictedUser, &model.Playlist{Name: "Unknown"}, songDayInALife.ID, "no-such-track")
 
-				userPls := NewPlaylistRepository(userCtx, GetDBXBuilder())
-				h, err := userPls.Get(hidden)
+				userPls := NewPlaylistRepository(GetDBXBuilder())
+				h, err := userPls.Get(userCtx, hidden)
 				Expect(err).ToNot(HaveOccurred())
-				u, err := userPls.Get(unknown)
+				u, err := userPls.Get(userCtx, unknown)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(h.SongCount).To(Equal(u.SongCount))
 				Expect(h.Duration).To(Equal(u.Duration))
@@ -364,9 +359,9 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		})
 
 		It("still shows everything to an admin", func() {
-			adminTracks := NewPlaylistRepository(adminCtx, GetDBXBuilder()).Tracks(plsID, false)
-			Expect(adminTracks.Count()).To(Equal(int64(2)))
-			_, err := adminTracks.Read("2")
+			adminTracks := NewPlaylistRepository(GetDBXBuilder()).Tracks(adminCtx, plsID, false)
+			Expect(adminTracks.Count(adminCtx)).To(Equal(int64(2)))
+			_, err := adminTracks.Read(adminCtx, "2")
 			Expect(err).ToNot(HaveOccurred())
 		})
 	})
diff --git a/persistence/playqueue_repository.go b/persistence/playqueue_repository.go
index ba69ec746..9dc520c44 100644
--- a/persistence/playqueue_repository.go
+++ b/persistence/playqueue_repository.go
@@ -17,9 +17,8 @@ type playQueueRepository struct {
 	sqlRepository
 }
 
-func NewPlayQueueRepository(ctx context.Context, db dbx.Builder) model.PlayQueueRepository {
+func NewPlayQueueRepository(db dbx.Builder) model.PlayQueueRepository {
 	r := &playQueueRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "playqueue"
 	return r
@@ -36,13 +35,13 @@ type playQueue struct {
 	UpdatedAt time.Time `structs:"updated_at"`
 }
 
-func (r *playQueueRepository) Store(q *model.PlayQueue, colNames ...string) error {
-	u := loggedUser(r.ctx)
+func (r *playQueueRepository) Store(ctx context.Context, q *model.PlayQueue, colNames ...string) error {
+	u := loggedUser(ctx)
 
 	// Always find existing playqueue for this user
-	existingQueue, err := r.Retrieve(q.UserID)
+	existingQueue, err := r.Retrieve(ctx, q.UserID)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
-		log.Error(r.ctx, "Error retrieving existing playqueue", "user", u.UserName, err)
+		log.Error(ctx, "Error retrieving existing playqueue", "user", u.UserName, err)
 		return err
 	}
 
@@ -53,9 +52,9 @@ func (r *playQueueRepository) Store(q *model.PlayQueue, colNames ...string) erro
 
 	// When no specific columns are provided, we replace the whole queue
 	if len(colNames) == 0 {
-		err := r.clearPlayQueue(q.UserID)
+		err := r.clearPlayQueue(ctx, q.UserID)
 		if err != nil {
-			log.Error(r.ctx, "Error deleting previous playqueue", "user", u.UserName, err)
+			log.Error(ctx, "Error deleting previous playqueue", "user", u.UserName, err)
 			return err
 		}
 		if len(q.Items) == 0 {
@@ -68,27 +67,27 @@ func (r *playQueueRepository) Store(q *model.PlayQueue, colNames ...string) erro
 		pq.CreatedAt = time.Now()
 	}
 	pq.UpdatedAt = time.Now()
-	_, err = r.put(pq.ID, pq, colNames...)
+	_, err = r.put(ctx, pq.ID, pq, colNames...)
 	if err != nil {
-		log.Error(r.ctx, "Error saving playqueue", "user", u.UserName, err)
+		log.Error(ctx, "Error saving playqueue", "user", u.UserName, err)
 		return err
 	}
 	return nil
 }
 
-func (r *playQueueRepository) RetrieveWithMediaFiles(userId string) (*model.PlayQueue, error) {
-	sel := r.newSelect().Columns("*").Where(Eq{"user_id": userId})
+func (r *playQueueRepository) RetrieveWithMediaFiles(ctx context.Context, userId string) (*model.PlayQueue, error) {
+	sel := r.newSelect(ctx).Columns("*").Where(Eq{"user_id": userId})
 	var res playQueue
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	q := r.toModel(&res)
-	q.Items = r.loadTracks(q.Items)
+	q.Items = r.loadTracks(ctx, q.Items)
 	return &q, err
 }
 
-func (r *playQueueRepository) Retrieve(userId string) (*model.PlayQueue, error) {
-	sel := r.newSelect().Columns("*").Where(Eq{"user_id": userId})
+func (r *playQueueRepository) Retrieve(ctx context.Context, userId string) (*model.PlayQueue, error) {
+	sel := r.newSelect(ctx).Columns("*").Where(Eq{"user_id": userId})
 	var res playQueue
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return new(r.toModel(&res)), err
 }
 
@@ -131,12 +130,12 @@ func (r *playQueueRepository) toModel(pq *playQueue) model.PlayQueue {
 
 // loadTracks loads the tracks from the database. It receives a list of track IDs and returns a list of MediaFiles
 // in the same order as the input list.
-func (r *playQueueRepository) loadTracks(tracks model.MediaFiles) model.MediaFiles {
+func (r *playQueueRepository) loadTracks(ctx context.Context, tracks model.MediaFiles) model.MediaFiles {
 	if len(tracks) == 0 {
 		return nil
 	}
 
-	mfRepo := NewMediaFileRepository(r.ctx, r.db)
+	mfRepo := NewMediaFileRepository(r.db)
 	trackMap := map[string]model.MediaFile{}
 
 	// Create an iterator to collect all track IDs
@@ -145,10 +144,10 @@ func (r *playQueueRepository) loadTracks(tracks model.MediaFiles) model.MediaFil
 	// Break the list in chunks, up to 500 items, to avoid hitting SQLITE_MAX_VARIABLE_NUMBER limit
 	for chunk := range slice.CollectChunks(ids, 500) {
 		idsFilter := Eq{"media_file.id": chunk}
-		tracks, err := mfRepo.GetAll(model.QueryOptions{Filters: idsFilter})
+		tracks, err := mfRepo.GetAll(ctx, model.QueryOptions{Filters: idsFilter})
 		if err != nil {
-			u := loggedUser(r.ctx)
-			log.Error(r.ctx, "Could not load playqueue/bookmark's tracks", "user", u.UserName, err)
+			u := loggedUser(ctx)
+			log.Error(ctx, "Could not load playqueue/bookmark's tracks", "user", u.UserName, err)
 		}
 		for _, t := range tracks {
 			trackMap[t.ID] = t
@@ -166,12 +165,12 @@ func (r *playQueueRepository) loadTracks(tracks model.MediaFiles) model.MediaFil
 	return newTracks
 }
 
-func (r *playQueueRepository) clearPlayQueue(userId string) error {
-	return r.delete(Eq{"user_id": userId})
+func (r *playQueueRepository) clearPlayQueue(ctx context.Context, userId string) error {
+	return r.delete(ctx, Eq{"user_id": userId})
 }
 
-func (r *playQueueRepository) Clear(userId string) error {
-	return r.clearPlayQueue(userId)
+func (r *playQueueRepository) Clear(ctx context.Context, userId string) error {
+	return r.clearPlayQueue(ctx, userId)
 }
 
 var _ model.PlayQueueRepository = (*playQueueRepository)(nil)
diff --git a/persistence/playqueue_repository_test.go b/persistence/playqueue_repository_test.go
index 2bcc88fd0..877faddfc 100644
--- a/persistence/playqueue_repository_test.go
+++ b/persistence/playqueue_repository_test.go
@@ -22,15 +22,15 @@ var _ = Describe("PlayQueueRepository", func() {
 		DeferCleanup(configtest.SetupConfig())
 		ctx = log.NewContext(context.TODO())
 		ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-		repo = NewPlayQueueRepository(ctx, GetDBXBuilder())
+		repo = NewPlayQueueRepository(GetDBXBuilder())
 	})
 
 	Describe("Store", func() {
 		It("stores a complete playqueue", func() {
 			expected := aPlayQueue("userid", 1, 123, songComeTogether, songDayInALife)
-			Expect(repo.Store(expected)).To(Succeed())
+			Expect(repo.Store(ctx, expected)).To(Succeed())
 
-			actual, err := repo.RetrieveWithMediaFiles("userid")
+			actual, err := repo.RetrieveWithMediaFiles(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 			AssertPlayQueue(expected, actual)
 			Expect(countPlayQueues(repo, "userid")).To(Equal(1))
@@ -39,13 +39,13 @@ var _ = Describe("PlayQueueRepository", func() {
 		It("replaces existing playqueue when storing without column names", func() {
 			By("Storing initial playqueue")
 			initial := aPlayQueue("userid", 0, 100, songComeTogether)
-			Expect(repo.Store(initial)).To(Succeed())
+			Expect(repo.Store(ctx, initial)).To(Succeed())
 
 			By("Storing replacement playqueue")
 			replacement := aPlayQueue("userid", 1, 200, songDayInALife, songAntenna)
-			Expect(repo.Store(replacement)).To(Succeed())
+			Expect(repo.Store(ctx, replacement)).To(Succeed())
 
-			actual, err := repo.RetrieveWithMediaFiles("userid")
+			actual, err := repo.RetrieveWithMediaFiles(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 			AssertPlayQueue(replacement, actual)
 			Expect(countPlayQueues(repo, "userid")).To(Equal(1))
@@ -54,24 +54,24 @@ var _ = Describe("PlayQueueRepository", func() {
 		It("clears playqueue when storing empty items", func() {
 			By("Storing initial playqueue")
 			initial := aPlayQueue("userid", 0, 100, songComeTogether)
-			Expect(repo.Store(initial)).To(Succeed())
+			Expect(repo.Store(ctx, initial)).To(Succeed())
 
 			By("Storing empty playqueue")
 			empty := aPlayQueue("userid", 0, 0)
-			Expect(repo.Store(empty)).To(Succeed())
+			Expect(repo.Store(ctx, empty)).To(Succeed())
 
 			By("Verifying playqueue is cleared")
-			_, err := repo.Retrieve("userid")
+			_, err := repo.Retrieve(ctx, "userid")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
 		It("updates only current field when specified", func() {
 			By("Storing initial playqueue")
 			initial := aPlayQueue("userid", 0, 100, songComeTogether, songDayInALife)
-			Expect(repo.Store(initial)).To(Succeed())
+			Expect(repo.Store(ctx, initial)).To(Succeed())
 
 			By("Getting the existing playqueue to obtain its ID")
-			existing, err := repo.Retrieve("userid")
+			existing, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			By("Updating only current field")
@@ -81,10 +81,10 @@ var _ = Describe("PlayQueueRepository", func() {
 				Current:   1,
 				ChangedBy: "test-update",
 			}
-			Expect(repo.Store(update, "current")).To(Succeed())
+			Expect(repo.Store(ctx, update, "current")).To(Succeed())
 
 			By("Verifying only current was updated")
-			actual, err := repo.Retrieve("userid")
+			actual, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Current).To(Equal(1))
 			Expect(actual.Position).To(Equal(int64(100))) // Should remain unchanged
@@ -94,10 +94,10 @@ var _ = Describe("PlayQueueRepository", func() {
 		It("updates only position field when specified", func() {
 			By("Storing initial playqueue")
 			initial := aPlayQueue("userid", 1, 100, songComeTogether, songDayInALife)
-			Expect(repo.Store(initial)).To(Succeed())
+			Expect(repo.Store(ctx, initial)).To(Succeed())
 
 			By("Getting the existing playqueue to obtain its ID")
-			existing, err := repo.Retrieve("userid")
+			existing, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			By("Updating only position field")
@@ -107,10 +107,10 @@ var _ = Describe("PlayQueueRepository", func() {
 				Position:  500,
 				ChangedBy: "test-update",
 			}
-			Expect(repo.Store(update, "position")).To(Succeed())
+			Expect(repo.Store(ctx, update, "position")).To(Succeed())
 
 			By("Verifying only position was updated")
-			actual, err := repo.Retrieve("userid")
+			actual, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Position).To(Equal(int64(500)))
 			Expect(actual.Current).To(Equal(1)) // Should remain unchanged
@@ -120,10 +120,10 @@ var _ = Describe("PlayQueueRepository", func() {
 		It("updates multiple specified fields", func() {
 			By("Storing initial playqueue")
 			initial := aPlayQueue("userid", 0, 100, songComeTogether)
-			Expect(repo.Store(initial)).To(Succeed())
+			Expect(repo.Store(ctx, initial)).To(Succeed())
 
 			By("Getting the existing playqueue to obtain its ID")
-			existing, err := repo.Retrieve("userid")
+			existing, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			By("Updating current and position fields")
@@ -134,10 +134,10 @@ var _ = Describe("PlayQueueRepository", func() {
 				Position:  300,
 				ChangedBy: "test-update",
 			}
-			Expect(repo.Store(update, "current", "position")).To(Succeed())
+			Expect(repo.Store(ctx, update, "current", "position")).To(Succeed())
 
 			By("Verifying both fields were updated")
-			actual, err := repo.Retrieve("userid")
+			actual, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Current).To(Equal(1))
 			Expect(actual.Position).To(Equal(int64(300)))
@@ -147,10 +147,10 @@ var _ = Describe("PlayQueueRepository", func() {
 		It("preserves existing data when updating with empty items list and column names", func() {
 			By("Storing initial playqueue")
 			initial := aPlayQueue("userid", 0, 100, songComeTogether, songDayInALife)
-			Expect(repo.Store(initial)).To(Succeed())
+			Expect(repo.Store(ctx, initial)).To(Succeed())
 
 			By("Getting the existing playqueue to obtain its ID")
-			existing, err := repo.Retrieve("userid")
+			existing, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			By("Updating only position with empty items")
@@ -161,10 +161,10 @@ var _ = Describe("PlayQueueRepository", func() {
 				ChangedBy: "test-update",
 				Items:     []model.MediaFile{}, // Empty items
 			}
-			Expect(repo.Store(update, "position")).To(Succeed())
+			Expect(repo.Store(ctx, update, "position")).To(Succeed())
 
 			By("Verifying items are preserved")
-			actual, err := repo.Retrieve("userid")
+			actual, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Position).To(Equal(int64(200)))
 			Expect(actual.Items).To(HaveLen(2)) // Should remain unchanged
@@ -173,21 +173,21 @@ var _ = Describe("PlayQueueRepository", func() {
 		It("ensures only one record per user by reusing existing record ID", func() {
 			By("Storing initial playqueue")
 			initial := aPlayQueue("userid", 0, 100, songComeTogether)
-			Expect(repo.Store(initial)).To(Succeed())
+			Expect(repo.Store(ctx, initial)).To(Succeed())
 			initialCount := countPlayQueues(repo, "userid")
 			Expect(initialCount).To(Equal(1))
 
 			By("Storing another playqueue with different ID but same user")
 			different := aPlayQueue("userid", 1, 200, songDayInALife)
 			different.ID = "different-id" // Force a different ID
-			Expect(repo.Store(different)).To(Succeed())
+			Expect(repo.Store(ctx, different)).To(Succeed())
 
 			By("Verifying only one record exists for the user")
 			finalCount := countPlayQueues(repo, "userid")
 			Expect(finalCount).To(Equal(1))
 
 			By("Verifying the record was updated, not duplicated")
-			actual, err := repo.Retrieve("userid")
+			actual, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Current).To(Equal(1))           // Should be updated value
 			Expect(actual.Position).To(Equal(int64(200))) // Should be updated value
@@ -198,7 +198,7 @@ var _ = Describe("PlayQueueRepository", func() {
 		It("ensures only one record per user even with partial updates", func() {
 			By("Storing initial playqueue")
 			initial := aPlayQueue("userid", 0, 100, songComeTogether, songDayInALife)
-			Expect(repo.Store(initial)).To(Succeed())
+			Expect(repo.Store(ctx, initial)).To(Succeed())
 			initialCount := countPlayQueues(repo, "userid")
 			Expect(initialCount).To(Equal(1))
 
@@ -209,14 +209,14 @@ var _ = Describe("PlayQueueRepository", func() {
 				Current:   1,
 				ChangedBy: "test-partial",
 			}
-			Expect(repo.Store(partialUpdate, "current")).To(Succeed())
+			Expect(repo.Store(ctx, partialUpdate, "current")).To(Succeed())
 
 			By("Verifying only one record still exists for the user")
 			finalCount := countPlayQueues(repo, "userid")
 			Expect(finalCount).To(Equal(1))
 
 			By("Verifying the existing record was updated with new current value")
-			actual, err := repo.Retrieve("userid")
+			actual, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Current).To(Equal(1))           // Should be updated value
 			Expect(actual.Position).To(Equal(int64(100))) // Should remain unchanged
@@ -226,7 +226,7 @@ var _ = Describe("PlayQueueRepository", func() {
 
 	Describe("Retrieve", func() {
 		It("returns notfound error if there's no playqueue for the user", func() {
-			_, err := repo.Retrieve("user999")
+			_, err := repo.Retrieve(ctx, "user999")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
@@ -234,9 +234,9 @@ var _ = Describe("PlayQueueRepository", func() {
 			By("Storing a playqueue for the user")
 
 			expected := aPlayQueue("userid", 1, 123, songComeTogether, songDayInALife)
-			Expect(repo.Store(expected)).To(Succeed())
+			Expect(repo.Store(ctx, expected)).To(Succeed())
 
-			actual, err := repo.Retrieve("userid")
+			actual, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			// Basic playqueue properties should match
@@ -263,19 +263,19 @@ var _ = Describe("PlayQueueRepository", func() {
 			newSong := songRadioactivity
 			newSong.ID = "temp-track"
 			newSong.Path = "/new-path"
-			mfRepo := NewMediaFileRepository(ctx, GetDBXBuilder())
+			mfRepo := NewMediaFileRepository(GetDBXBuilder())
 
-			Expect(mfRepo.Put(&newSong)).To(Succeed())
+			Expect(mfRepo.Put(ctx, &newSong)).To(Succeed())
 
 			// Create a playqueue with the new song
 			pq := aPlayQueue("userid", 0, 0, newSong, songAntenna)
-			Expect(repo.Store(pq)).To(Succeed())
+			Expect(repo.Store(ctx, pq)).To(Succeed())
 
 			// Delete the new song from the database
-			Expect(mfRepo.Delete("temp-track")).To(Succeed())
+			Expect(mfRepo.Delete(ctx, "temp-track")).To(Succeed())
 
 			// Retrieve the playqueue with Retrieve method
-			actual, err := repo.Retrieve("userid")
+			actual, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			// The playqueue should still contain both track IDs (including the deleted one)
@@ -295,7 +295,7 @@ var _ = Describe("PlayQueueRepository", func() {
 
 	Describe("RetrieveWithMediaFiles", func() {
 		It("returns notfound error if there's no playqueue for the user", func() {
-			_, err := repo.RetrieveWithMediaFiles("user999")
+			_, err := repo.RetrieveWithMediaFiles(ctx, "user999")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
@@ -303,9 +303,9 @@ var _ = Describe("PlayQueueRepository", func() {
 			By("Storing a playqueue for the user")
 
 			expected := aPlayQueue("userid", 1, 123, songComeTogether, songDayInALife)
-			Expect(repo.Store(expected)).To(Succeed())
+			Expect(repo.Store(ctx, expected)).To(Succeed())
 
-			actual, err := repo.RetrieveWithMediaFiles("userid")
+			actual, err := repo.RetrieveWithMediaFiles(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			AssertPlayQueue(expected, actual)
@@ -316,26 +316,26 @@ var _ = Describe("PlayQueueRepository", func() {
 			newSong := songRadioactivity
 			newSong.ID = "temp-track"
 			newSong.Path = "/new-path"
-			mfRepo := NewMediaFileRepository(ctx, GetDBXBuilder())
+			mfRepo := NewMediaFileRepository(GetDBXBuilder())
 
-			Expect(mfRepo.Put(&newSong)).To(Succeed())
+			Expect(mfRepo.Put(ctx, &newSong)).To(Succeed())
 
 			// Create a playqueue with the new song
 			pq := aPlayQueue("userid", 0, 0, newSong, songAntenna)
-			Expect(repo.Store(pq)).To(Succeed())
+			Expect(repo.Store(ctx, pq)).To(Succeed())
 
 			// Retrieve the playqueue
-			actual, err := repo.RetrieveWithMediaFiles("userid")
+			actual, err := repo.RetrieveWithMediaFiles(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			// The playqueue should contain both tracks
 			AssertPlayQueue(pq, actual)
 
 			// Delete the new song
-			Expect(mfRepo.Delete("temp-track")).To(Succeed())
+			Expect(mfRepo.Delete(ctx, "temp-track")).To(Succeed())
 
 			// Retrieve the playqueue
-			actual, err = repo.RetrieveWithMediaFiles("userid")
+			actual, err = repo.RetrieveWithMediaFiles(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			// The playqueue should not contain the deleted track
@@ -348,48 +348,48 @@ var _ = Describe("PlayQueueRepository", func() {
 		It("clears an existing playqueue", func() {
 			By("Storing a playqueue")
 			expected := aPlayQueue("userid", 1, 123, songComeTogether, songDayInALife)
-			Expect(repo.Store(expected)).To(Succeed())
+			Expect(repo.Store(ctx, expected)).To(Succeed())
 
 			By("Verifying playqueue exists")
-			_, err := repo.Retrieve("userid")
+			_, err := repo.Retrieve(ctx, "userid")
 			Expect(err).ToNot(HaveOccurred())
 
 			By("Clearing the playqueue")
-			Expect(repo.Clear("userid")).To(Succeed())
+			Expect(repo.Clear(ctx, "userid")).To(Succeed())
 
 			By("Verifying playqueue is cleared")
-			_, err = repo.Retrieve("userid")
+			_, err = repo.Retrieve(ctx, "userid")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
 		It("does not error when clearing non-existent playqueue", func() {
 			// Clear should not error even if no playqueue exists
-			Expect(repo.Clear("nonexistent-user")).To(Succeed())
+			Expect(repo.Clear(ctx, "nonexistent-user")).To(Succeed())
 		})
 
 		It("only clears the specified user's playqueue", func() {
 			By("Creating users in the database to avoid foreign key constraints")
-			userRepo := NewUserRepository(ctx, GetDBXBuilder())
+			userRepo := NewUserRepository(GetDBXBuilder())
 			user1 := &model.User{ID: "user1", UserName: "user1", Name: "User 1", Email: "user1@test.com"}
 			user2 := &model.User{ID: "user2", UserName: "user2", Name: "User 2", Email: "user2@test.com"}
-			Expect(userRepo.Put(user1)).To(Succeed())
-			Expect(userRepo.Put(user2)).To(Succeed())
+			Expect(userRepo.Put(ctx, user1)).To(Succeed())
+			Expect(userRepo.Put(ctx, user2)).To(Succeed())
 
 			By("Storing playqueues for two users")
 			user1Queue := aPlayQueue("user1", 0, 100, songComeTogether)
 			user2Queue := aPlayQueue("user2", 1, 200, songDayInALife)
-			Expect(repo.Store(user1Queue)).To(Succeed())
-			Expect(repo.Store(user2Queue)).To(Succeed())
+			Expect(repo.Store(ctx, user1Queue)).To(Succeed())
+			Expect(repo.Store(ctx, user2Queue)).To(Succeed())
 
 			By("Clearing only user1's playqueue")
-			Expect(repo.Clear("user1")).To(Succeed())
+			Expect(repo.Clear(ctx, "user1")).To(Succeed())
 
 			By("Verifying user1's playqueue is cleared")
-			_, err := repo.Retrieve("user1")
+			_, err := repo.Retrieve(ctx, "user1")
 			Expect(err).To(MatchError(model.ErrNotFound))
 
 			By("Verifying user2's playqueue still exists")
-			actual, err := repo.Retrieve("user2")
+			actual, err := repo.Retrieve(ctx, "user2")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.UserID).To(Equal("user2"))
 			Expect(actual.Current).To(Equal(1))
@@ -400,7 +400,7 @@ var _ = Describe("PlayQueueRepository", func() {
 
 func countPlayQueues(repo model.PlayQueueRepository, userId string) int {
 	r := repo.(*playQueueRepository)
-	c, err := r.count(squirrel.Select().Where(squirrel.Eq{"user_id": userId}))
+	c, err := r.count(GinkgoT().Context(), squirrel.Select().Where(squirrel.Eq{"user_id": userId}))
 	if err != nil {
 		panic(err)
 	}
diff --git a/persistence/plugin_cleanup_test.go b/persistence/plugin_cleanup_test.go
index bfe6d60ca..08959075d 100644
--- a/persistence/plugin_cleanup_test.go
+++ b/persistence/plugin_cleanup_test.go
@@ -1,6 +1,8 @@
 package persistence
 
 import (
+	"context"
+
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	. "github.com/onsi/ginkgo/v2"
@@ -11,30 +13,47 @@ var _ = Describe("Plugin Cleanup", func() {
 	var pluginRepo model.PluginRepository
 	var userRepo model.UserRepository
 	var libraryRepo model.LibraryRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
-		ctx := GinkgoT().Context()
-		ctx = request.WithUser(ctx, model.User{ID: "admin", UserName: "admin", IsAdmin: true})
+		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "admin", UserName: "admin", IsAdmin: true})
 		db := GetDBXBuilder()
-		pluginRepo = NewPluginRepository(ctx, db)
-		userRepo = NewUserRepository(ctx, db)
-		libraryRepo = NewLibraryRepository(ctx, db)
+		pluginRepo = NewPluginRepository(db)
+		userRepo = NewUserRepository(db)
+		libraryRepo = NewLibraryRepository(db)
 
 		// Clean up any existing plugins
-		all, _ := pluginRepo.GetAll()
+		all, _ := pluginRepo.GetAll(ctx)
 		for _, p := range all {
-			_ = pluginRepo.Delete(p.ID)
+			_ = pluginRepo.Delete(ctx, p.ID)
 		}
 	})
 
 	AfterEach(func() {
 		// Clean up after tests
-		all, _ := pluginRepo.GetAll()
+		all, _ := pluginRepo.GetAll(ctx)
 		for _, p := range all {
-			_ = pluginRepo.Delete(p.ID)
+			_ = pluginRepo.Delete(ctx, p.ID)
 		}
 	})
 
+	Describe("UserRepository.Delete", func() {
+		It("cleans up plugin references for users deleted before a later id fails", func() {
+			Expect(userRepo.Put(ctx, &model.User{ID: "bulk-1", UserName: "bulk-1", NewPassword: "x"})).To(Succeed())
+			DeferCleanup(func() { _ = userRepo.Delete(ctx, "bulk-1") })
+			Expect(pluginRepo.Put(ctx, &model.Plugin{
+				ID: "bulk-plugin", Path: "/plugins/bulk.wasm", Manifest: `{"name":"bulk"}`, SHA256: "def456",
+				Users: `["bulk-1","other"]`, Enabled: true,
+			})).To(Succeed())
+
+			Expect(userRepo.Delete(ctx, "bulk-1", "does-not-exist")).To(MatchError(model.ErrNotFound))
+
+			updated, err := pluginRepo.Get(ctx, "bulk-plugin")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(updated.Users).To(Equal(`["other"]`))
+		})
+	})
+
 	Describe("cleanupPluginUserReferences", func() {
 		It("removes user ID from plugin users array", func() {
 			// Create a plugin with multiple users
@@ -46,14 +65,14 @@ var _ = Describe("Plugin Cleanup", func() {
 				Users:    `["user1","user2","user3"]`,
 				Enabled:  true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Clean up user2 reference
 			db := GetDBXBuilder()
 			Expect(cleanupPluginUserReferences(db, "user2")).To(Succeed())
 
 			// Verify user2 was removed
-			updated, err := pluginRepo.Get("test-plugin")
+			updated, err := pluginRepo.Get(ctx, "test-plugin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Users).To(Equal(`["user1","user3"]`))
 			Expect(updated.Enabled).To(BeTrue()) // Still has users, should remain enabled
@@ -70,14 +89,14 @@ var _ = Describe("Plugin Cleanup", func() {
 				AllUsers: false,
 				Enabled:  true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Remove the only user
 			db := GetDBXBuilder()
 			Expect(cleanupPluginUserReferences(db, "only-user")).To(Succeed())
 
 			// Verify plugin was auto-disabled
-			updated, err := pluginRepo.Get("user-plugin")
+			updated, err := pluginRepo.Get(ctx, "user-plugin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Users).To(Equal(`[]`))
 			Expect(updated.Enabled).To(BeFalse())
@@ -93,14 +112,14 @@ var _ = Describe("Plugin Cleanup", func() {
 				AllUsers: true,
 				Enabled:  true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Remove the user (but allUsers is true)
 			db := GetDBXBuilder()
 			Expect(cleanupPluginUserReferences(db, "user1")).To(Succeed())
 
 			// Plugin should still be enabled because allUsers is true
-			updated, err := pluginRepo.Get("all-users-plugin")
+			updated, err := pluginRepo.Get(ctx, "all-users-plugin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Enabled).To(BeTrue())
 		})
@@ -114,14 +133,14 @@ var _ = Describe("Plugin Cleanup", func() {
 				Users:    `["user1"]`,
 				Enabled:  true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Remove the user
 			db := GetDBXBuilder()
 			Expect(cleanupPluginUserReferences(db, "user1")).To(Succeed())
 
 			// Plugin should still be enabled (no users permission requirement)
-			updated, err := pluginRepo.Get("no-users-perm")
+			updated, err := pluginRepo.Get(ctx, "no-users-perm")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Users).To(Equal(`[]`))
 			Expect(updated.Enabled).To(BeTrue())
@@ -139,14 +158,14 @@ var _ = Describe("Plugin Cleanup", func() {
 				Libraries: `[1,2,3]`,
 				Enabled:   true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Clean up library 2 reference
 			db := GetDBXBuilder()
 			Expect(cleanupPluginLibraryReferences(db, 2)).To(Succeed())
 
 			// Verify library 2 was removed
-			updated, err := pluginRepo.Get("lib-plugin")
+			updated, err := pluginRepo.Get(ctx, "lib-plugin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Libraries).To(Equal(`[1,3]`))
 		})
@@ -162,14 +181,14 @@ var _ = Describe("Plugin Cleanup", func() {
 				AllLibraries: false,
 				Enabled:      true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Remove the only library
 			db := GetDBXBuilder()
 			Expect(cleanupPluginLibraryReferences(db, 99)).To(Succeed())
 
 			// Verify plugin was auto-disabled
-			updated, err := pluginRepo.Get("lib-only-plugin")
+			updated, err := pluginRepo.Get(ctx, "lib-only-plugin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Libraries).To(Equal(`[]`))
 			Expect(updated.Enabled).To(BeFalse())
@@ -185,14 +204,14 @@ var _ = Describe("Plugin Cleanup", func() {
 				AllLibraries: true,
 				Enabled:      true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Remove the library (but allLibraries is true)
 			db := GetDBXBuilder()
 			Expect(cleanupPluginLibraryReferences(db, 1)).To(Succeed())
 
 			// Plugin should still be enabled
-			updated, err := pluginRepo.Get("all-libs-plugin")
+			updated, err := pluginRepo.Get(ctx, "all-libs-plugin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Enabled).To(BeTrue())
 		})
@@ -207,7 +226,7 @@ var _ = Describe("Plugin Cleanup", func() {
 				IsAdmin:  false,
 			}
 			user.NewPassword = "password123"
-			Expect(userRepo.Put(user)).To(Succeed())
+			Expect(userRepo.Put(ctx, user)).To(Succeed())
 
 			// Create a plugin referencing this user
 			plugin := &model.Plugin{
@@ -218,13 +237,13 @@ var _ = Describe("Plugin Cleanup", func() {
 				Users:    `["test-delete-user","other-user"]`,
 				Enabled:  true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Delete the user
-			Expect(userRepo.Delete("test-delete-user")).To(Succeed())
+			Expect(userRepo.Delete(ctx, "test-delete-user")).To(Succeed())
 
 			// Verify user was removed from plugin
-			updated, err := pluginRepo.Get("user-ref-plugin")
+			updated, err := pluginRepo.Get(ctx, "user-ref-plugin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Users).To(Equal(`["other-user"]`))
 		})
@@ -238,7 +257,7 @@ var _ = Describe("Plugin Cleanup", func() {
 				Name: "Test Library",
 				Path: "/tmp/test-lib",
 			}
-			Expect(libraryRepo.Put(library)).To(Succeed())
+			Expect(libraryRepo.Put(ctx, library)).To(Succeed())
 
 			// Create a plugin referencing this library
 			plugin := &model.Plugin{
@@ -249,13 +268,13 @@ var _ = Describe("Plugin Cleanup", func() {
 				Libraries: `[99,1]`,
 				Enabled:   true,
 			}
-			Expect(pluginRepo.Put(plugin)).To(Succeed())
+			Expect(pluginRepo.Put(ctx, plugin)).To(Succeed())
 
 			// Delete the library
-			Expect(libraryRepo.Delete(99)).To(Succeed())
+			Expect(libraryRepo.Delete(ctx, 99)).To(Succeed())
 
 			// Verify library was removed from plugin
-			updated, err := pluginRepo.Get("lib-ref-plugin")
+			updated, err := pluginRepo.Get(ctx, "lib-ref-plugin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(updated.Libraries).To(Equal(`[1]`))
 		})
diff --git a/persistence/plugin_repository.go b/persistence/plugin_repository.go
index 7d5781f49..1545ce2ba 100644
--- a/persistence/plugin_repository.go
+++ b/persistence/plugin_repository.go
@@ -15,9 +15,8 @@ type pluginRepository struct {
 	sqlRepository
 }
 
-func NewPluginRepository(ctx context.Context, db dbx.Builder) model.PluginRepository {
+func NewPluginRepository(db dbx.Builder) model.PluginRepository {
 	r := &pluginRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.registerModel(&model.Plugin{}, map[string]filterFunc{
 		"id":      idFilter("plugin"),
@@ -26,13 +25,13 @@ func NewPluginRepository(ctx context.Context, db dbx.Builder) model.PluginReposi
 	return r
 }
 
-func (r *pluginRepository) isPermitted() bool {
-	user := loggedUser(r.ctx)
+func (r *pluginRepository) isPermitted(ctx context.Context) bool {
+	user := loggedUser(ctx)
 	return user.IsAdmin
 }
 
-func (r *pluginRepository) ClearErrors() error {
-	if !r.isPermitted() {
+func (r *pluginRepository) ClearErrors(ctx context.Context) error {
+	if !r.isPermitted(ctx) {
 		return rest.ErrPermissionDenied
 	}
 	// An UPDATE takes the write lock even when nothing matches, so only run it when there is an error to clear
@@ -47,43 +46,43 @@ func (r *pluginRepository) ClearErrors() error {
 	return err
 }
 
-func (r *pluginRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	if !r.isPermitted() {
+func (r *pluginRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	if !r.isPermitted(ctx) {
 		return 0, rest.ErrPermissionDenied
 	}
-	sql := r.newSelect()
-	return r.count(sql, options...)
+	sql := r.newSelect(ctx)
+	return r.count(ctx, sql, options...)
 }
 
-func (r *pluginRepository) Delete(id string) error {
-	if !r.isPermitted() {
+func (r *pluginRepository) Delete(ctx context.Context, id string) error {
+	if !r.isPermitted(ctx) {
 		return rest.ErrPermissionDenied
 	}
-	return r.delete(Eq{"id": id})
+	return r.delete(ctx, Eq{"id": id})
 }
 
-func (r *pluginRepository) Get(id string) (*model.Plugin, error) {
-	if !r.isPermitted() {
+func (r *pluginRepository) Get(ctx context.Context, id string) (*model.Plugin, error) {
+	if !r.isPermitted(ctx) {
 		return nil, rest.ErrPermissionDenied
 	}
-	sel := r.newSelect().Where(Eq{"id": id}).Columns("*")
+	sel := r.newSelect(ctx).Where(Eq{"id": id}).Columns("*")
 	res := model.Plugin{}
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-func (r *pluginRepository) GetAll(options ...model.QueryOptions) (model.Plugins, error) {
-	if !r.isPermitted() {
+func (r *pluginRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Plugins, error) {
+	if !r.isPermitted(ctx) {
 		return nil, rest.ErrPermissionDenied
 	}
-	sel := r.newSelect(options...).Columns("*")
+	sel := r.newSelect(ctx, options...).Columns("*")
 	res := model.Plugins{}
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	return res, err
 }
 
-func (r *pluginRepository) Put(plugin *model.Plugin) error {
-	if !r.isPermitted() {
+func (r *pluginRepository) Put(ctx context.Context, plugin *model.Plugin) error {
+	if !r.isPermitted(ctx) {
 		return rest.ErrPermissionDenied
 	}
 
@@ -129,25 +128,17 @@ func (r *pluginRepository) Put(plugin *model.Plugin) error {
 	return err
 }
 
-func (r *pluginRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *pluginRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *pluginRepository) EntityName() string {
-	return "plugin"
+func (r *pluginRepository) Read(ctx context.Context, id string) (*model.Plugin, error) {
+	return r.Get(ctx, id)
 }
 
-func (r *pluginRepository) NewInstance() any {
-	return &model.Plugin{}
-}
-
-func (r *pluginRepository) Read(id string) (any, error) {
-	return r.Get(id)
-}
-
-func (r *pluginRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
+func (r *pluginRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Plugin, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
 var _ model.PluginRepository = (*pluginRepository)(nil)
-var _ rest.Repository = (*pluginRepository)(nil)
+var _ rest.Repository[model.Plugin] = (*pluginRepository)(nil)
diff --git a/persistence/plugin_repository_test.go b/persistence/plugin_repository_test.go
index 9b135057e..44330250b 100644
--- a/persistence/plugin_repository_test.go
+++ b/persistence/plugin_repository_test.go
@@ -13,50 +13,54 @@ import (
 
 var _ = Describe("PluginRepository", func() {
 	var repo model.PluginRepository
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+	})
 
 	Describe("Admin User", func() {
 		BeforeEach(func() {
-			ctx := GinkgoT().Context()
 			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			repo = NewPluginRepository(ctx, GetDBXBuilder())
+			repo = NewPluginRepository(GetDBXBuilder())
 
 			// Clean up any existing plugins
-			all, _ := repo.GetAll()
+			all, _ := repo.GetAll(ctx)
 			for _, p := range all {
-				_ = repo.Delete(p.ID)
+				_ = repo.Delete(ctx, p.ID)
 			}
 		})
 
 		AfterEach(func() {
 			// Clean up after tests
-			all, _ := repo.GetAll()
+			all, _ := repo.GetAll(ctx)
 			for _, p := range all {
-				_ = repo.Delete(p.ID)
+				_ = repo.Delete(ctx, p.ID)
 			}
 		})
 
 		Describe("CountAll", func() {
 			It("returns 0 when no plugins exist", func() {
-				Expect(repo.CountAll()).To(Equal(int64(0)))
+				Expect(repo.CountAll(ctx)).To(Equal(int64(0)))
 			})
 
 			It("returns the number of plugins in the DB", func() {
-				_ = repo.Put(&model.Plugin{ID: "test-plugin-1", Path: "/plugins/test1.wasm", Manifest: "{}", SHA256: "abc123"})
-				_ = repo.Put(&model.Plugin{ID: "test-plugin-2", Path: "/plugins/test2.wasm", Manifest: "{}", SHA256: "def456"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "test-plugin-1", Path: "/plugins/test1.wasm", Manifest: "{}", SHA256: "abc123"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "test-plugin-2", Path: "/plugins/test2.wasm", Manifest: "{}", SHA256: "def456"})
 
-				Expect(repo.CountAll()).To(Equal(int64(2)))
+				Expect(repo.CountAll(ctx)).To(Equal(int64(2)))
 			})
 		})
 
 		Describe("Delete", func() {
 			It("deletes existing item", func() {
 				plugin := &model.Plugin{ID: "to-delete", Path: "/plugins/delete.wasm", Manifest: "{}", SHA256: "hash"}
-				_ = repo.Put(plugin)
+				_ = repo.Put(ctx, plugin)
 
-				err := repo.Delete(plugin.ID)
+				err := repo.Delete(ctx, plugin.ID)
 				Expect(err).To(BeNil())
 
-				_, err = repo.Get(plugin.ID)
+				_, err = repo.Get(ctx, plugin.ID)
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 		})
@@ -64,9 +68,9 @@ var _ = Describe("PluginRepository", func() {
 		Describe("Get", func() {
 			It("returns an existing item", func() {
 				plugin := &model.Plugin{ID: "test-get", Path: "/plugins/test.wasm", Manifest: `{"name":"test"}`, SHA256: "hash123"}
-				_ = repo.Put(plugin)
+				_ = repo.Put(ctx, plugin)
 
-				res, err := repo.Get(plugin.ID)
+				res, err := repo.Get(ctx, plugin.ID)
 				Expect(err).To(BeNil())
 				Expect(res.ID).To(Equal(plugin.ID))
 				Expect(res.Path).To(Equal(plugin.Path))
@@ -74,31 +78,31 @@ var _ = Describe("PluginRepository", func() {
 			})
 
 			It("errors when missing", func() {
-				_, err := repo.Get("notanid")
+				_, err := repo.Get(ctx, "notanid")
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 		})
 
 		Describe("GetAll", func() {
 			It("returns all items from the DB", func() {
-				_ = repo.Put(&model.Plugin{ID: "plugin-a", Path: "/plugins/a.wasm", Manifest: "{}", SHA256: "hash1"})
-				_ = repo.Put(&model.Plugin{ID: "plugin-b", Path: "/plugins/b.wasm", Manifest: "{}", SHA256: "hash2"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "plugin-a", Path: "/plugins/a.wasm", Manifest: "{}", SHA256: "hash1"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "plugin-b", Path: "/plugins/b.wasm", Manifest: "{}", SHA256: "hash2"})
 
-				all, err := repo.GetAll()
+				all, err := repo.GetAll(ctx)
 				Expect(err).To(BeNil())
 				Expect(all).To(HaveLen(2))
 			})
 
 			It("supports pagination", func() {
-				_ = repo.Put(&model.Plugin{ID: "plugin-1", Path: "/plugins/1.wasm", Manifest: "{}", SHA256: "h1"})
-				_ = repo.Put(&model.Plugin{ID: "plugin-2", Path: "/plugins/2.wasm", Manifest: "{}", SHA256: "h2"})
-				_ = repo.Put(&model.Plugin{ID: "plugin-3", Path: "/plugins/3.wasm", Manifest: "{}", SHA256: "h3"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "plugin-1", Path: "/plugins/1.wasm", Manifest: "{}", SHA256: "h1"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "plugin-2", Path: "/plugins/2.wasm", Manifest: "{}", SHA256: "h2"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "plugin-3", Path: "/plugins/3.wasm", Manifest: "{}", SHA256: "h3"})
 
-				page1, err := repo.GetAll(model.QueryOptions{Max: 2, Offset: 0, Sort: "id"})
+				page1, err := repo.GetAll(ctx, model.QueryOptions{Max: 2, Offset: 0, Sort: "id"})
 				Expect(err).To(BeNil())
 				Expect(page1).To(HaveLen(2))
 
-				page2, err := repo.GetAll(model.QueryOptions{Max: 2, Offset: 2, Sort: "id"})
+				page2, err := repo.GetAll(ctx, model.QueryOptions{Max: 2, Offset: 2, Sort: "id"})
 				Expect(err).To(BeNil())
 				Expect(page2).To(HaveLen(1))
 			})
@@ -115,10 +119,10 @@ var _ = Describe("PluginRepository", func() {
 					Enabled:  false,
 				}
 
-				err := repo.Put(plugin)
+				err := repo.Put(ctx, plugin)
 				Expect(err).To(BeNil())
 
-				saved, err := repo.Get(plugin.ID)
+				saved, err := repo.Get(ctx, plugin.ID)
 				Expect(err).To(BeNil())
 				Expect(saved.Path).To(Equal(plugin.Path))
 				Expect(saved.Manifest).To(Equal(plugin.Manifest))
@@ -136,15 +140,15 @@ var _ = Describe("PluginRepository", func() {
 					SHA256:   "original",
 					Enabled:  false,
 				}
-				_ = repo.Put(plugin)
+				_ = repo.Put(ctx, plugin)
 
 				plugin.Enabled = true
 				plugin.Config = `{"new":"config"}`
 				plugin.SHA256 = "updated"
-				err := repo.Put(plugin)
+				err := repo.Put(ctx, plugin)
 				Expect(err).To(BeNil())
 
-				saved, err := repo.Get(plugin.ID)
+				saved, err := repo.Get(ctx, plugin.ID)
 				Expect(err).To(BeNil())
 				Expect(saved.Enabled).To(BeTrue())
 				Expect(saved.Config).To(Equal(`{"new":"config"}`))
@@ -159,10 +163,10 @@ var _ = Describe("PluginRepository", func() {
 					SHA256:    "hash",
 					LastError: "failed to load: missing export",
 				}
-				err := repo.Put(plugin)
+				err := repo.Put(ctx, plugin)
 				Expect(err).To(BeNil())
 
-				saved, err := repo.Get(plugin.ID)
+				saved, err := repo.Get(ctx, plugin.ID)
 				Expect(err).To(BeNil())
 				Expect(saved.LastError).To(Equal("failed to load: missing export"))
 			})
@@ -173,7 +177,7 @@ var _ = Describe("PluginRepository", func() {
 					Manifest: "{}",
 					SHA256:   "hash",
 				}
-				err := repo.Put(plugin)
+				err := repo.Put(ctx, plugin)
 				Expect(err).To(HaveOccurred())
 				Expect(err.Error()).To(ContainSubstring("ID cannot be empty"))
 			})
@@ -181,14 +185,14 @@ var _ = Describe("PluginRepository", func() {
 
 		Describe("ClearErrors", func() {
 			It("clears last_error on all plugins with errors", func() {
-				_ = repo.Put(&model.Plugin{ID: "ok-plugin", Path: "/plugins/ok.wasm", Manifest: "{}", SHA256: "h1"})
-				_ = repo.Put(&model.Plugin{ID: "err-plugin-1", Path: "/plugins/e1.wasm", Manifest: "{}", SHA256: "h2", LastError: "incompatible version"})
-				_ = repo.Put(&model.Plugin{ID: "err-plugin-2", Path: "/plugins/e2.wasm", Manifest: "{}", SHA256: "h3", LastError: "missing export"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "ok-plugin", Path: "/plugins/ok.wasm", Manifest: "{}", SHA256: "h1"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "err-plugin-1", Path: "/plugins/e1.wasm", Manifest: "{}", SHA256: "h2", LastError: "incompatible version"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "err-plugin-2", Path: "/plugins/e2.wasm", Manifest: "{}", SHA256: "h3", LastError: "missing export"})
 
-				err := repo.ClearErrors()
+				err := repo.ClearErrors(ctx)
 				Expect(err).To(BeNil())
 
-				all, err := repo.GetAll()
+				all, err := repo.GetAll(ctx)
 				Expect(err).To(BeNil())
 				for _, p := range all {
 					Expect(p.LastError).To(BeEmpty(), "plugin %s should have no error", p.ID)
@@ -196,14 +200,14 @@ var _ = Describe("PluginRepository", func() {
 			})
 
 			It("succeeds when no plugins have errors", func() {
-				_ = repo.Put(&model.Plugin{ID: "clean-plugin", Path: "/plugins/c.wasm", Manifest: "{}", SHA256: "h1"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "clean-plugin", Path: "/plugins/c.wasm", Manifest: "{}", SHA256: "h1"})
 
-				err := repo.ClearErrors()
+				err := repo.ClearErrors(ctx)
 				Expect(err).To(BeNil())
 			})
 
 			It("does not need the write lock when no plugins have errors", func() {
-				_ = repo.Put(&model.Plugin{ID: "clean-plugin", Path: "/plugins/c.wasm", Manifest: "{}", SHA256: "h1"})
+				_ = repo.Put(ctx, &model.Plugin{ID: "clean-plugin", Path: "/plugins/c.wasm", Manifest: "{}", SHA256: "h1"})
 				conn, err := db.Db().Conn(GinkgoT().Context())
 				Expect(err).ToNot(HaveOccurred())
 				DeferCleanup(conn.Close)
@@ -211,49 +215,48 @@ var _ = Describe("PluginRepository", func() {
 				Expect(err).ToNot(HaveOccurred())
 				DeferCleanup(func() { _, _ = conn.ExecContext(context.Background(), "ROLLBACK") })
 
-				Expect(repo.ClearErrors()).To(Succeed())
+				Expect(repo.ClearErrors(ctx)).To(Succeed())
 			})
 		})
 	})
 
 	Describe("Regular User", func() {
 		BeforeEach(func() {
-			ctx := GinkgoT().Context()
 			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: false})
-			repo = NewPluginRepository(ctx, GetDBXBuilder())
+			repo = NewPluginRepository(GetDBXBuilder())
 		})
 
 		Describe("CountAll", func() {
 			It("fails to count items", func() {
-				_, err := repo.CountAll()
+				_, err := repo.CountAll(ctx)
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
 		})
 
 		Describe("Delete", func() {
 			It("fails to delete items", func() {
-				err := repo.Delete("any-id")
+				err := repo.Delete(ctx, "any-id")
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
 		})
 
 		Describe("Get", func() {
 			It("fails to get items", func() {
-				_, err := repo.Get("any-id")
+				_, err := repo.Get(ctx, "any-id")
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
 		})
 
 		Describe("GetAll", func() {
 			It("fails to get all items", func() {
-				_, err := repo.GetAll()
+				_, err := repo.GetAll(ctx)
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
 		})
 
 		Describe("Put", func() {
 			It("fails to create/update item", func() {
-				err := repo.Put(&model.Plugin{
+				err := repo.Put(ctx, &model.Plugin{
 					ID:       "user-create",
 					Path:     "/plugins/create.wasm",
 					Manifest: "{}",
diff --git a/persistence/property_repository.go b/persistence/property_repository.go
index 14f9051f7..29bb2b564 100644
--- a/persistence/property_repository.go
+++ b/persistence/property_repository.go
@@ -13,17 +13,16 @@ type propertyRepository struct {
 	sqlRepository
 }
 
-func NewPropertyRepository(ctx context.Context, db dbx.Builder) model.PropertyRepository {
+func NewPropertyRepository(db dbx.Builder) model.PropertyRepository {
 	r := &propertyRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "property"
 	return r
 }
 
-func (r propertyRepository) Put(id string, value string) error {
+func (r propertyRepository) Put(ctx context.Context, id string, value string) error {
 	update := Update(r.tableName).Set("value", value).Where(Eq{"id": id})
-	count, err := r.executeSQL(update)
+	count, err := r.executeSQL(ctx, update)
 	if err != nil {
 		return err
 	}
@@ -31,24 +30,24 @@ func (r propertyRepository) Put(id string, value string) error {
 		return nil
 	}
 	insert := Insert(r.tableName).Columns("id", "value").Values(id, value)
-	_, err = r.executeSQL(insert)
+	_, err = r.executeSQL(ctx, insert)
 	return err
 }
 
-func (r propertyRepository) Get(id string) (string, error) {
+func (r propertyRepository) Get(ctx context.Context, id string) (string, error) {
 	sel := Select("value").From(r.tableName).Where(Eq{"id": id})
 	resp := struct {
 		Value string
 	}{}
-	err := r.queryOne(sel, &resp)
+	err := r.queryOne(ctx, sel, &resp)
 	if err != nil {
 		return "", err
 	}
 	return resp.Value, nil
 }
 
-func (r propertyRepository) DefaultGet(id string, defaultValue string) (string, error) {
-	value, err := r.Get(id)
+func (r propertyRepository) DefaultGet(ctx context.Context, id string, defaultValue string) (string, error) {
+	value, err := r.Get(ctx, id)
 	if errors.Is(err, model.ErrNotFound) {
 		return defaultValue, nil
 	}
@@ -58,6 +57,6 @@ func (r propertyRepository) DefaultGet(id string, defaultValue string) (string,
 	return value, nil
 }
 
-func (r propertyRepository) Delete(id string) error {
-	return r.delete(Eq{"id": id})
+func (r propertyRepository) Delete(ctx context.Context, id string) error {
+	return r.delete(ctx, Eq{"id": id})
 }
diff --git a/persistence/property_repository_test.go b/persistence/property_repository_test.go
index 3a0495e9f..880b315ec 100644
--- a/persistence/property_repository_test.go
+++ b/persistence/property_repository_test.go
@@ -10,25 +10,27 @@ import (
 )
 
 var _ = Describe("Property Repository", func() {
+	var ctx context.Context
 	var pr model.PropertyRepository
 
 	BeforeEach(func() {
-		pr = NewPropertyRepository(log.NewContext(context.TODO()), GetDBXBuilder())
+		ctx = log.NewContext(GinkgoT().Context())
+		pr = NewPropertyRepository(GetDBXBuilder())
 	})
 
 	It("saves and restore a new property", func() {
 		id := "1"
 		value := "a_value"
-		Expect(pr.Put(id, value)).To(BeNil())
-		Expect(pr.Get(id)).To(Equal("a_value"))
+		Expect(pr.Put(ctx, id, value)).To(BeNil())
+		Expect(pr.Get(ctx, id)).To(Equal("a_value"))
 	})
 
 	It("updates a property", func() {
-		Expect(pr.Put("1", "another_value")).To(BeNil())
-		Expect(pr.Get("1")).To(Equal("another_value"))
+		Expect(pr.Put(ctx, "1", "another_value")).To(BeNil())
+		Expect(pr.Get(ctx, "1")).To(Equal("another_value"))
 	})
 
 	It("returns a default value if property does not exist", func() {
-		Expect(pr.DefaultGet("2", "default")).To(Equal("default"))
+		Expect(pr.DefaultGet(ctx, "2", "default")).To(Equal("default"))
 	})
 })
diff --git a/persistence/radio_repository.go b/persistence/radio_repository.go
index 4584ceaed..b5d4f3a07 100644
--- a/persistence/radio_repository.go
+++ b/persistence/radio_repository.go
@@ -16,9 +16,8 @@ type radioRepository struct {
 	sqlRepository
 }
 
-func NewRadioRepository(ctx context.Context, db dbx.Builder) model.RadioRepository {
+func NewRadioRepository(db dbx.Builder) model.RadioRepository {
 	r := &radioRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.registerModel(&model.Radio{}, map[string]filterFunc{
 		"name": containsFilter("name"),
@@ -26,60 +25,65 @@ func NewRadioRepository(ctx context.Context, db dbx.Builder) model.RadioReposito
 	return r
 }
 
-func (r *radioRepository) isPermitted() bool {
-	user := loggedUser(r.ctx)
+func (r *radioRepository) isPermitted(ctx context.Context) bool {
+	user := loggedUser(ctx)
 	return user.IsAdmin
 }
 
-func (r *radioRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	sql := r.newSelect()
-	return r.count(sql, options...)
+func (r *radioRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	sql := r.newSelect(ctx)
+	return r.count(ctx, sql, options...)
 }
 
 // Exists needs no library or ownership filter: radios are visible to every user.
-func (r *radioRepository) Exists(id string) (bool, error) {
-	return r.exists(Eq{"id": id})
+func (r *radioRepository) Exists(ctx context.Context, id string) (bool, error) {
+	return r.exists(ctx, Eq{"id": id})
 }
 
-func (r *radioRepository) Delete(id string) error {
-	if !r.isPermitted() {
+func (r *radioRepository) Delete(ctx context.Context, ids ...string) error {
+	if !r.isPermitted(ctx) {
 		return rest.ErrPermissionDenied
 	}
 
-	return r.deleteByID(id)
+	for _, id := range ids {
+		if err := r.deleteByID(ctx, id); err != nil {
+			return err
+		}
+	}
+	return nil
 }
 
-func (r *radioRepository) Get(id string) (*model.Radio, error) {
-	sel := r.newSelect().Where(Eq{"id": id}).Columns("*")
+func (r *radioRepository) Get(ctx context.Context, id string) (*model.Radio, error) {
+	sel := r.newSelect(ctx).Where(Eq{"id": id}).Columns("*")
 	res := model.Radio{}
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	if err != nil {
 		return &res, err
 	}
 	list := model.Radios{res}
-	r.hydrateArtwork(list)
+	r.hydrateArtwork(ctx, list)
 	return &list[0], nil
 }
 
-func (r *radioRepository) GetAll(options ...model.QueryOptions) (model.Radios, error) {
-	sel := r.newSelect(options...).Columns("*")
+func (r *radioRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Radios, error) {
+	sel := r.newSelect(ctx, options...).Columns("*")
 	res := model.Radios{}
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		return res, err
 	}
-	r.hydrateArtwork(res)
+	r.hydrateArtwork(ctx, res)
 	return res, nil
 }
 
 // hydrateArtwork fills each radio's ImageHash/ImageAbsent from one batched item_artwork lookup.
-func (r *radioRepository) hydrateArtwork(radios model.Radios) {
-	hydrateItems(r.ctx, r.db, model.KindRadioArtwork, radios,
+func (r *radioRepository) hydrateArtwork(ctx context.Context, radios model.Radios) {
+	hydrateItems(ctx, r.db, model.KindRadioArtwork, radios,
 		func(rd *model.Radio) (string, *model.ItemImage) { return rd.ID, &rd.ItemImage })
 }
 
-func (r *radioRepository) Put(radio *model.Radio, colsToUpdate ...string) error {
-	if !r.isPermitted() {
+func (r *radioRepository) Put(ctx context.Context, radio *model.Radio, colsToUpdate ...string) error {
+	if !r.isPermitted(ctx) {
 		return rest.ErrPermissionDenied
 	}
 
@@ -91,7 +95,7 @@ func (r *radioRepository) Put(radio *model.Radio, colsToUpdate ...string) error
 	if len(colsToUpdate) > 0 {
 		colsToUpdate = append(colsToUpdate, "UpdatedAt")
 	}
-	_, err := r.put(radio.ID, radio, colsToUpdate...)
+	_, err := r.put(ctx, radio.ID, radio, colsToUpdate...)
 	if err != nil {
 		return err
 	}
@@ -99,50 +103,41 @@ func (r *radioRepository) Put(radio *model.Radio, colsToUpdate ...string) error
 	// radio's cover resolves proactively. Never fails the save.
 	item := model.ArtworkQueueItem{ItemKind: model.KindRadioArtwork.Prefix(), ItemID: radio.ID, ImageType: model.ImageTypePrimary,
 		Priority: model.ArtworkPriorityBump}
-	if err := NewArtworkQueueRepository(r.ctx, r.db).Enqueue(item); err != nil {
-		log.Warn(r.ctx, "could not enqueue radio artwork", "id", radio.ID, err)
+	if err := NewArtworkQueueRepository(r.db).Enqueue(ctx, item); err != nil {
+		log.Warn(ctx, "could not enqueue radio artwork", "id", radio.ID, err)
 	}
 	return nil
 }
 
-func (r *radioRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *radioRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *radioRepository) EntityName() string {
-	return "radio"
+func (r *radioRepository) Read(ctx context.Context, id string) (*model.Radio, error) {
+	return r.Get(ctx, id)
 }
 
-func (r *radioRepository) NewInstance() any {
-	return &model.Radio{}
+func (r *radioRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Radio, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *radioRepository) Read(id string) (any, error) {
-	return r.Get(id)
-}
-
-func (r *radioRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
-}
-
-func (r *radioRepository) Save(entity any) (string, error) {
-	t := entity.(*model.Radio)
-	if !r.isPermitted() {
+func (r *radioRepository) Save(ctx context.Context, t *model.Radio) (string, error) {
+	if !r.isPermitted(ctx) {
 		return "", rest.ErrPermissionDenied
 	}
-	err := r.Put(t)
+	err := r.Put(ctx, t)
 	return t.ID, err
 }
 
-func (r *radioRepository) Update(id string, entity any, cols ...string) error {
-	t := entity.(*model.Radio)
+func (r *radioRepository) Update(ctx context.Context, id string, entity model.Radio, cols ...string) error {
+	t := &entity
 	t.ID = id
-	if !r.isPermitted() {
+	if !r.isPermitted(ctx) {
 		return rest.ErrPermissionDenied
 	}
-	return r.Put(t, cols...)
+	return r.Put(ctx, t, cols...)
 }
 
 var _ model.RadioRepository = (*radioRepository)(nil)
-var _ rest.Repository = (*radioRepository)(nil)
-var _ rest.Persistable = (*radioRepository)(nil)
+var _ rest.Repository[model.Radio] = (*radioRepository)(nil)
+var _ rest.Persistable[model.Radio] = (*radioRepository)(nil)
diff --git a/persistence/radio_repository_test.go b/persistence/radio_repository_test.go
index 8d4b685d9..aba776853 100644
--- a/persistence/radio_repository_test.go
+++ b/persistence/radio_repository_test.go
@@ -13,24 +13,28 @@ import (
 
 var _ = Describe("RadioRepository", func() {
 	var repo model.RadioRepository
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+	})
 
 	Describe("Admin User", func() {
 		BeforeEach(func() {
-			ctx := log.NewContext(context.TODO())
-			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			repo = NewRadioRepository(ctx, GetDBXBuilder())
-			_ = repo.Put(&radioWithHomePage)
+			ctx = request.WithUser(log.NewContext(ctx), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+			repo = NewRadioRepository(GetDBXBuilder())
+			_ = repo.Put(ctx, &radioWithHomePage)
 		})
 
 		AfterEach(func() {
-			all, _ := repo.GetAll()
+			all, _ := repo.GetAll(ctx)
 
 			for _, radio := range all {
-				_ = repo.Delete(radio.ID)
+				_ = repo.Delete(ctx, radio.ID)
 			}
 
 			for i := range testRadios {
-				err := repo.Put(new(testRadios[i]))
+				err := repo.Put(ctx, new(testRadios[i]))
 				if err != nil {
 					panic(err)
 				}
@@ -39,35 +43,35 @@ var _ = Describe("RadioRepository", func() {
 
 		Describe("Count", func() {
 			It("returns the number of radios in the DB", func() {
-				Expect(repo.CountAll()).To(Equal(int64(2)))
+				Expect(repo.CountAll(ctx)).To(Equal(int64(2)))
 			})
 		})
 
 		Describe("Delete", func() {
 			It("deletes existing item", func() {
-				err := repo.Delete(radioWithHomePage.ID)
+				err := repo.Delete(ctx, radioWithHomePage.ID)
 
 				Expect(err).To(BeNil())
 
-				_, err = repo.Get(radioWithHomePage.ID)
+				_, err = repo.Get(ctx, radioWithHomePage.ID)
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 
 			It("errors when missing", func() {
-				Expect(repo.Delete("notanid")).To(MatchError(model.ErrNotFound))
+				Expect(repo.Delete(ctx, "notanid")).To(MatchError(model.ErrNotFound))
 			})
 		})
 
 		Describe("Get", func() {
 			It("returns an existing item", func() {
-				res, err := repo.Get(radioWithHomePage.ID)
+				res, err := repo.Get(ctx, radioWithHomePage.ID)
 
 				Expect(err).To(BeNil())
 				Expect(res.ID).To(Equal(radioWithHomePage.ID))
 			})
 
 			It("errors when missing", func() {
-				_, err := repo.Get("notanid")
+				_, err := repo.Get(ctx, "notanid")
 
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
@@ -75,7 +79,7 @@ var _ = Describe("RadioRepository", func() {
 
 		Describe("GetAll", func() {
 			It("returns all items from the DB", func() {
-				all, err := repo.GetAll()
+				all, err := repo.GetAll(ctx)
 				Expect(err).To(BeNil())
 				Expect(all[0].ID).To(Equal(radioWithoutHomePage.ID))
 				Expect(all[1].ID).To(Equal(radioWithHomePage.ID))
@@ -84,7 +88,7 @@ var _ = Describe("RadioRepository", func() {
 
 		Describe("Put", func() {
 			It("successfully updates item", func() {
-				err := repo.Put(&model.Radio{
+				err := repo.Put(ctx, &model.Radio{
 					ID:        radioWithHomePage.ID,
 					Name:      "New Name",
 					StreamUrl: "https://example.com:4533/app",
@@ -92,39 +96,39 @@ var _ = Describe("RadioRepository", func() {
 
 				Expect(err).To(BeNil())
 
-				item, err := repo.Get(radioWithHomePage.ID)
+				item, err := repo.Get(ctx, radioWithHomePage.ID)
 				Expect(err).To(BeNil())
 
 				Expect(item.HomePageUrl).To(Equal(""))
 			})
 
 			It("successfully creates item", func() {
-				err := repo.Put(&model.Radio{
+				err := repo.Put(ctx, &model.Radio{
 					Name:      "New radio",
 					StreamUrl: "https://example.com:4533/app",
 				})
 
 				Expect(err).To(BeNil())
-				Expect(repo.CountAll()).To(Equal(int64(3)))
+				Expect(repo.CountAll(ctx)).To(Equal(int64(3)))
 
-				all, err := repo.GetAll()
+				all, err := repo.GetAll(ctx)
 				Expect(err).To(BeNil())
 				Expect(all[2].StreamUrl).To(Equal("https://example.com:4533/app"))
 			})
 
 			It("enqueues artwork resolution for the saved radio", func() {
-				err := repo.Put(&model.Radio{
+				err := repo.Put(ctx, &model.Radio{
 					Name:      "Artwork radio",
 					StreamUrl: "https://example.com:4533/artwork",
 				})
 				Expect(err).To(BeNil())
 
-				all, err := repo.GetAll()
+				all, err := repo.GetAll(ctx)
 				Expect(err).To(BeNil())
 				created := all[len(all)-1]
 
-				queueRepo := NewArtworkQueueRepository(context.Background(), GetDBXBuilder())
-				queued, err := queueRepo.DequeueBatch(1000)
+				queueRepo := NewArtworkQueueRepository(GetDBXBuilder())
+				queued, err := queueRepo.DequeueBatch(ctx, 1000)
 				Expect(err).To(BeNil())
 				Expect(queued).To(ContainElement(SatisfyAll(
 					HaveField("ItemKind", "ra"),
@@ -138,12 +142,11 @@ var _ = Describe("RadioRepository", func() {
 			It("only writes the columns sent by the client", func() {
 				radio := radioWithHomePage
 				radio.UploadedImage = "cover.png"
-				Expect(repo.Put(&radio)).To(Succeed())
+				Expect(repo.Put(ctx, &radio)).To(Succeed())
 
-				persistable := repo.(rest.Persistable)
-				Expect(persistable.Update(radio.ID, &model.Radio{Name: "Renamed"}, "name")).To(Succeed())
+				Expect(repo.Update(ctx, radio.ID, model.Radio{Name: "Renamed"}, "name")).To(Succeed())
 
-				item, err := repo.Get(radio.ID)
+				item, err := repo.Get(ctx, radio.ID)
 				Expect(err).To(BeNil())
 				Expect(item.Name).To(Equal("Renamed"))
 				Expect(item.UploadedImage).To(Equal("cover.png"))
@@ -155,20 +158,19 @@ var _ = Describe("RadioRepository", func() {
 
 	Describe("Regular User", func() {
 		BeforeEach(func() {
-			ctx := log.NewContext(context.TODO())
-			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: false})
-			repo = NewRadioRepository(ctx, GetDBXBuilder())
+			ctx = request.WithUser(log.NewContext(ctx), model.User{ID: "userid", UserName: "userid", IsAdmin: false})
+			repo = NewRadioRepository(GetDBXBuilder())
 		})
 
 		Describe("Count", func() {
 			It("returns the number of radios in the DB", func() {
-				Expect(repo.CountAll()).To(Equal(int64(2)))
+				Expect(repo.CountAll(ctx)).To(Equal(int64(2)))
 			})
 		})
 
 		Describe("Delete", func() {
 			It("fails to delete items", func() {
-				err := repo.Delete(radioWithHomePage.ID)
+				err := repo.Delete(ctx, radioWithHomePage.ID)
 
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
@@ -176,14 +178,14 @@ var _ = Describe("RadioRepository", func() {
 
 		Describe("Get", func() {
 			It("returns an existing item", func() {
-				res, err := repo.Get(radioWithHomePage.ID)
+				res, err := repo.Get(ctx, radioWithHomePage.ID)
 
 				Expect(err).To(BeNil())
 				Expect(res.ID).To(Equal(radioWithHomePage.ID))
 			})
 
 			It("errors when missing", func() {
-				_, err := repo.Get("notanid")
+				_, err := repo.Get(ctx, "notanid")
 
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
@@ -191,7 +193,7 @@ var _ = Describe("RadioRepository", func() {
 
 		Describe("GetAll", func() {
 			It("returns all items from the DB", func() {
-				all, err := repo.GetAll()
+				all, err := repo.GetAll(ctx)
 				Expect(err).To(BeNil())
 				Expect(all[0].ID).To(Equal(radioWithoutHomePage.ID))
 				Expect(all[1].ID).To(Equal(radioWithHomePage.ID))
@@ -200,7 +202,7 @@ var _ = Describe("RadioRepository", func() {
 
 		Describe("Put", func() {
 			It("fails to update item", func() {
-				err := repo.Put(&model.Radio{
+				err := repo.Put(ctx, &model.Radio{
 					ID:        radioWithHomePage.ID,
 					Name:      "New Name",
 					StreamUrl: "https://example.com:4533/app",
diff --git a/persistence/scrobble_buffer_repository.go b/persistence/scrobble_buffer_repository.go
index cf54c664a..0daf2b0e7 100644
--- a/persistence/scrobble_buffer_repository.go
+++ b/persistence/scrobble_buffer_repository.go
@@ -29,15 +29,14 @@ func (t *dbScrobbleBuffer) PostScan() error {
 	return nil
 }
 
-func NewScrobbleBufferRepository(ctx context.Context, db dbx.Builder) model.ScrobbleBufferRepository {
+func NewScrobbleBufferRepository(db dbx.Builder) model.ScrobbleBufferRepository {
 	r := &scrobbleBufferRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "scrobble_buffer"
 	return r
 }
 
-func (r *scrobbleBufferRepository) UserIDs(service string) ([]string, error) {
+func (r *scrobbleBufferRepository) UserIDs(ctx context.Context, service string) ([]string, error) {
 	sql := Select().Columns("user_id").
 		From(r.tableName).
 		Where(And{
@@ -46,11 +45,11 @@ func (r *scrobbleBufferRepository) UserIDs(service string) ([]string, error) {
 		GroupBy("user_id").
 		OrderBy("count(*)")
 	var userIds []string
-	err := r.queryAllSlice(sql, &userIds)
+	err := r.queryAllSlice(ctx, sql, &userIds)
 	return userIds, err
 }
 
-func (r *scrobbleBufferRepository) Enqueue(service, userId, mediaFileId string, playTime time.Time) error {
+func (r *scrobbleBufferRepository) Enqueue(ctx context.Context, service, userId, mediaFileId string, playTime time.Time) error {
 	ins := Insert(r.tableName).SetMap(map[string]any{
 		"id":            id.NewRandom(),
 		"user_id":       userId,
@@ -59,11 +58,11 @@ func (r *scrobbleBufferRepository) Enqueue(service, userId, mediaFileId string,
 		"play_time":     playTime,
 		"enqueue_time":  time.Now(),
 	})
-	_, err := r.executeSQL(ins)
+	_, err := r.executeSQL(ctx, ins)
 	return err
 }
 
-func (r *scrobbleBufferRepository) Next(service string, userId string) (*model.ScrobbleEntry, error) {
+func (r *scrobbleBufferRepository) Next(ctx context.Context, service string, userId string) (*model.ScrobbleEntry, error) {
 	// Put `s.*` last or else m.id overrides s.id
 	sql := Select().Columns("m.*, s.*").
 		From(r.tableName+" s").
@@ -75,30 +74,30 @@ func (r *scrobbleBufferRepository) Next(service string, userId string) (*model.S
 		OrderBy("play_time", "s.rowid").Limit(1)
 
 	var res dbScrobbleBuffer
-	err := r.queryOne(sql, &res)
+	err := r.queryOne(ctx, sql, &res)
 	if errors.Is(err, model.ErrNotFound) {
 		return nil, nil
 	}
 	if err != nil {
 		return nil, err
 	}
-	res.ScrobbleEntry.Participants, err = r.getParticipants(&res.ScrobbleEntry.MediaFile)
+	res.ScrobbleEntry.Participants, err = r.getParticipants(ctx, &res.ScrobbleEntry.MediaFile)
 	if err != nil {
 		return nil, err
 	}
 	return res.ScrobbleEntry, nil
 }
 
-func (r *scrobbleBufferRepository) Dequeue(entry *model.ScrobbleEntry) error {
-	return r.delete(Eq{"id": entry.ID})
+func (r *scrobbleBufferRepository) Dequeue(ctx context.Context, entry *model.ScrobbleEntry) error {
+	return r.delete(ctx, Eq{"id": entry.ID})
 }
 
-func (r *scrobbleBufferRepository) Discard(service string) error {
-	return r.delete(Eq{"service": service})
+func (r *scrobbleBufferRepository) Discard(ctx context.Context, service string) error {
+	return r.delete(ctx, Eq{"service": service})
 }
 
-func (r *scrobbleBufferRepository) Length() (int64, error) {
-	return r.count(Select())
+func (r *scrobbleBufferRepository) Length(ctx context.Context) (int64, error) {
+	return r.count(ctx, Select())
 }
 
 var _ model.ScrobbleBufferRepository = (*scrobbleBufferRepository)(nil)
diff --git a/persistence/scrobble_buffer_repository_test.go b/persistence/scrobble_buffer_repository_test.go
index 3aa71070e..38b0e4e63 100644
--- a/persistence/scrobble_buffer_repository_test.go
+++ b/persistence/scrobble_buffer_repository_test.go
@@ -16,6 +16,7 @@ import (
 var _ = Describe("ScrobbleBufferRepository", func() {
 	var scrobble model.ScrobbleBufferRepository
 	var rawRepo sqlRepository
+	var ctx context.Context
 
 	enqueueTime := time.Date(2025, 01, 01, 00, 00, 00, 00, time.Local)
 	var ids []string
@@ -32,17 +33,16 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 			"play_time":     playTime,
 			"enqueue_time":  enqueueTime,
 		})
-		_, err := rawRepo.executeSQL(ins)
+		_, err := rawRepo.executeSQL(ctx, ins)
 		Expect(err).ToNot(HaveOccurred())
 	}
 
 	BeforeEach(func() {
-		ctx := request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid", UserName: "johndoe", IsAdmin: true})
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "johndoe", IsAdmin: true})
 		db := GetDBXBuilder()
-		scrobble = NewScrobbleBufferRepository(ctx, db)
+		scrobble = NewScrobbleBufferRepository(db)
 
 		rawRepo = sqlRepository{
-			ctx:       ctx,
 			tableName: "scrobble_buffer",
 			db:        db,
 		}
@@ -51,14 +51,14 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 
 	AfterEach(func() {
 		del := squirrel.Delete(rawRepo.tableName)
-		_, err := rawRepo.executeSQL(del)
+		_, err := rawRepo.executeSQL(ctx, del)
 		Expect(err).ToNot(HaveOccurred())
 	})
 
 	Describe("Without data", func() {
 		Describe("Count", func() {
 			It("returns zero when empty", func() {
-				count, err := scrobble.Length()
+				count, err := scrobble.Length(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(BeZero())
 			})
@@ -66,10 +66,10 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 
 		Describe("Dequeue", func() {
 			It("is a no-op when deleting a nonexistent item", func() {
-				err := scrobble.Dequeue(&model.ScrobbleEntry{ID: "fake"})
+				err := scrobble.Dequeue(ctx, &model.ScrobbleEntry{ID: "fake"})
 				Expect(err).ToNot(HaveOccurred())
 
-				count, err := scrobble.Length()
+				count, err := scrobble.Length(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(0)))
 			})
@@ -77,7 +77,7 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 
 		Describe("Next", func() {
 			It("should not fail with no item for the service", func() {
-				entry, err := scrobble.Next("fake", "userid")
+				entry, err := scrobble.Next(ctx, "fake", "userid")
 				Expect(entry).To(BeNil())
 				Expect(err).ToNot(HaveOccurred())
 			})
@@ -85,7 +85,7 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 
 		Describe("UserIds", func() {
 			It("should return empty list with no data", func() {
-				ids, err := scrobble.UserIDs("service")
+				ids, err := scrobble.UserIDs(ctx, "service")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(ids).To(BeEmpty())
 			})
@@ -107,7 +107,7 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 
 		Describe("Count", func() {
 			It("Returns count when populated", func() {
-				count, err := scrobble.Length()
+				count, err := scrobble.Length(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(4)))
 			})
@@ -115,23 +115,23 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 
 		Describe("Dequeue", func() {
 			It("is a no-op when deleting a nonexistent item", func() {
-				err := scrobble.Dequeue(&model.ScrobbleEntry{ID: "fake"})
+				err := scrobble.Dequeue(ctx, &model.ScrobbleEntry{ID: "fake"})
 				Expect(err).ToNot(HaveOccurred())
 
-				count, err := scrobble.Length()
+				count, err := scrobble.Length(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(4)))
 			})
 
 			It("deletes an item when specified properly", func() {
-				err := scrobble.Dequeue(&model.ScrobbleEntry{ID: ids[3]})
+				err := scrobble.Dequeue(ctx, &model.ScrobbleEntry{ID: ids[3]})
 				Expect(err).ToNot(HaveOccurred())
 
-				count, err := scrobble.Length()
+				count, err := scrobble.Length(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(3)))
 
-				entry, err := scrobble.Next("b", "2222")
+				entry, err := scrobble.Next(ctx, "b", "2222")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(entry).To(BeNil())
 			})
@@ -141,14 +141,14 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 			DescribeTable("enqueues an item properly",
 				func(service, userId, fileId string, playTime time.Time) {
 					now := time.Now()
-					err := scrobble.Enqueue(service, userId, fileId, playTime)
+					err := scrobble.Enqueue(ctx, service, userId, fileId, playTime)
 					Expect(err).ToNot(HaveOccurred())
 
-					count, err := scrobble.Length()
+					count, err := scrobble.Length(ctx)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(count).To(Equal(int64(5)))
 
-					entry, err := scrobble.Next(service, userId)
+					entry, err := scrobble.Next(ctx, service, userId)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(entry).ToNot(BeNil())
 
@@ -165,7 +165,7 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 		Describe("Next", func() {
 			DescribeTable("Returns the next item when populated",
 				func(service, id string, playTime time.Time, fileId, artistId string) {
-					entry, err := scrobble.Next(service, id)
+					entry, err := scrobble.Next(ctx, service, id)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(entry).ToNot(BeNil())
 
@@ -193,21 +193,21 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 
 		Describe("Discard", func() {
 			It("deletes all entries for a service, keeping other services intact", func() {
-				Expect(scrobble.Discard("a")).To(Succeed())
+				Expect(scrobble.Discard(ctx, "a")).To(Succeed())
 
-				count, err := scrobble.Length()
+				count, err := scrobble.Length(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(1)))
 
-				entry, err := scrobble.Next("b", "2222")
+				entry, err := scrobble.Next(ctx, "b", "2222")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(entry).ToNot(BeNil())
 			})
 
 			It("is a no-op for a service without entries", func() {
-				Expect(scrobble.Discard("nonexistent")).To(Succeed())
+				Expect(scrobble.Discard(ctx, "nonexistent")).To(Succeed())
 
-				count, err := scrobble.Length()
+				count, err := scrobble.Length(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(count).To(Equal(int64(4)))
 			})
@@ -215,13 +215,13 @@ var _ = Describe("ScrobbleBufferRepository", func() {
 
 		Describe("UserIds", func() {
 			It("should return ordered list for services", func() {
-				ids, err := scrobble.UserIDs("a")
+				ids, err := scrobble.UserIDs(ctx, "a")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(ids).To(Equal([]string{"2222", "userid"}))
 			})
 
 			It("should return for a different service", func() {
-				ids, err := scrobble.UserIDs("b")
+				ids, err := scrobble.UserIDs(ctx, "b")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(ids).To(Equal([]string{"2222"}))
 			})
diff --git a/persistence/scrobble_repository.go b/persistence/scrobble_repository.go
index 7cc60ae23..3d9882b99 100644
--- a/persistence/scrobble_repository.go
+++ b/persistence/scrobble_repository.go
@@ -22,17 +22,16 @@ func toTs(_ string, value any) Sqlizer {
 	return LtOrEq{"scrobbles.submission_time": value}
 }
 
-func (r *scrobbleRepository) baseQuery(options ...model.QueryOptions) SelectBuilder {
-	user := loggedUser(r.ctx)
+func (r *scrobbleRepository) baseQuery(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	user := loggedUser(ctx)
 
-	return r.newSelect(options...).
+	return r.newSelect(ctx, options...).
 		Columns("id", "media_file_id", "submission_time").
 		Where(Eq{"scrobbles.user_id": user.ID})
 }
 
-func NewScrobbleRepository(ctx context.Context, db dbx.Builder) model.ScrobbleRepository {
+func NewScrobbleRepository(db dbx.Builder) model.ScrobbleRepository {
 	r := &scrobbleRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "scrobbles"
 	r.registerModel(&model.Scrobble{}, map[string]filterFunc{
@@ -45,55 +44,47 @@ func NewScrobbleRepository(ctx context.Context, db dbx.Builder) model.ScrobbleRe
 	return r
 }
 
-func (r *scrobbleRepository) RecordScrobble(mediaFileID string, submissionTime time.Time) error {
-	userID := loggedUser(r.ctx).ID
+func (r *scrobbleRepository) RecordScrobble(ctx context.Context, mediaFileID string, submissionTime time.Time) error {
+	userID := loggedUser(ctx).ID
 	values := map[string]any{
 		"media_file_id":   mediaFileID,
 		"user_id":         userID,
 		"submission_time": submissionTime.Unix(),
 	}
 	insert := Insert(r.tableName).SetMap(values)
-	_, err := r.executeSQL(insert)
+	_, err := r.executeSQL(ctx, insert)
 	return err
 }
 
-func (r *scrobbleRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	return r.count(r.baseQuery(), options...)
+func (r *scrobbleRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	return r.count(ctx, r.baseQuery(ctx), options...)
 }
 
-func (r *scrobbleRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *scrobbleRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *scrobbleRepository) Get(id string) (*model.Scrobble, error) {
-	sel := r.baseQuery().Where(Eq{"id": id})
+func (r *scrobbleRepository) Get(ctx context.Context, id string) (*model.Scrobble, error) {
+	sel := r.baseQuery(ctx).Where(Eq{"id": id})
 	var res model.Scrobble
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-func (r *scrobbleRepository) GetAll(options ...model.QueryOptions) (model.Scrobbles, error) {
-	sel := r.baseQuery(options...)
+func (r *scrobbleRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Scrobbles, error) {
+	sel := r.baseQuery(ctx, options...)
 	var scrobbles model.Scrobbles
-	err := r.queryAll(sel, &scrobbles)
+	err := r.queryAll(ctx, sel, &scrobbles)
 	return scrobbles, err
 }
 
-func (r *scrobbleRepository) Read(id string) (any, error) {
-	return r.Get(id)
+func (r *scrobbleRepository) Read(ctx context.Context, id string) (*model.Scrobble, error) {
+	return r.Get(ctx, id)
 }
 
-func (r *scrobbleRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
-}
-
-func (r *scrobbleRepository) EntityName() string {
-	return "scrobble"
-}
-
-func (r *scrobbleRepository) NewInstance() any {
-	return &model.Scrobble{}
+func (r *scrobbleRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Scrobble, error) {
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
 var _ model.ScrobbleRepository = (*scrobbleRepository)(nil)
-var _ model.ResourceRepository = (*scrobbleRepository)(nil)
+var _ rest.Repository[model.Scrobble] = (*scrobbleRepository)(nil)
diff --git a/persistence/scrobble_repository_test.go b/persistence/scrobble_repository_test.go
index e9103b127..860b1ad02 100644
--- a/persistence/scrobble_repository_test.go
+++ b/persistence/scrobble_repository_test.go
@@ -28,10 +28,9 @@ var _ = Describe("ScrobbleRepository", func() {
 			userID = id.NewRandom()
 			ctx = request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: userID, UserName: "johndoe", IsAdmin: true})
 			db := GetDBXBuilder()
-			repo = NewScrobbleRepository(ctx, db)
+			repo = NewScrobbleRepository(db)
 
 			rawRepo = sqlRepository{
-				ctx:       ctx,
 				tableName: "scrobbles",
 				db:        db,
 			}
@@ -65,7 +64,7 @@ var _ = Describe("ScrobbleRepository", func() {
 			}).Execute()
 			Expect(err).ToNot(HaveOccurred())
 
-			err = repo.RecordScrobble(fileID, submissionTime)
+			err = repo.RecordScrobble(ctx, fileID, submissionTime)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Verify insertion
@@ -87,22 +86,22 @@ var _ = Describe("ScrobbleRepository", func() {
 	Context("admin user (id userid)", func() {
 		BeforeEach(func() {
 			ctx = request.WithUser(log.NewContext(context.TODO()), adminUser)
-			repo = NewScrobbleRepository(ctx, GetDBXBuilder())
+			repo = NewScrobbleRepository(GetDBXBuilder())
 		})
 
 		Describe("Count", func() {
 			It("Returns the number of scrobbles in the DB for admin user", func() {
-				Expect(repo.CountAll()).To(Equal(int64(2)))
+				Expect(repo.CountAll(ctx)).To(Equal(int64(2)))
 			})
 
 			It("returns scrobbles in a range", func() {
-				Expect(repo.CountAll(model.QueryOptions{Filters: squirrel.LtOrEq{"submission_time": 1}})).To(Equal(int64(1)))
+				Expect(repo.CountAll(ctx, model.QueryOptions{Filters: squirrel.LtOrEq{"submission_time": 1}})).To(Equal(int64(1)))
 			})
 		})
 
 		Describe("Get", func() {
 			It("returns an existing scrobble for the user", func() {
-				scrobble, err := repo.Get("1")
+				scrobble, err := repo.Get(ctx, "1")
 				Expect(err).To(BeNil())
 				Expect(scrobble.ID).To(Equal(int64(1)))
 				Expect(scrobble.MediaFileID).To(Equal("1001"))
@@ -111,19 +110,19 @@ var _ = Describe("ScrobbleRepository", func() {
 			})
 
 			It("does not return a scrobble that exists for another user", func() {
-				_, err := repo.Get("2")
+				_, err := repo.Get(ctx, "2")
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 
 			It("does not return a scrobble that does not exist", func() {
-				_, err := repo.Get("444")
+				_, err := repo.Get(ctx, "444")
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 		})
 
 		Describe("GetAll", func() {
 			It("returns all scrobbles in reverse order", func() {
-				scrobbles, err := repo.GetAll(model.QueryOptions{
+				scrobbles, err := repo.GetAll(ctx, model.QueryOptions{
 					Sort:  "submission_time",
 					Order: "DESC",
 				})
@@ -140,7 +139,7 @@ var _ = Describe("ScrobbleRepository", func() {
 			})
 
 			It("returns scrobbles in a range", func() {
-				scrobbles, err := repo.GetAll(model.QueryOptions{
+				scrobbles, err := repo.GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.GtOrEq{"submission_time": 1}})
 
 				Expect(err).To(BeNil())
@@ -156,22 +155,22 @@ var _ = Describe("ScrobbleRepository", func() {
 	Context("non-admin user", func() {
 		BeforeEach(func() {
 			ctx = request.WithUser(log.NewContext(context.TODO()), regularUser)
-			repo = NewScrobbleRepository(ctx, GetDBXBuilder())
+			repo = NewScrobbleRepository(GetDBXBuilder())
 		})
 
 		Describe("Count", func() {
 			It("Returns the number of scrobbles in the DB for admin user", func() {
-				Expect(repo.CountAll()).To(Equal(int64(1)))
+				Expect(repo.CountAll(ctx)).To(Equal(int64(1)))
 			})
 
 			It("returns scrobbles in a range", func() {
-				Expect(repo.CountAll(model.QueryOptions{Filters: squirrel.LtOrEq{"submission_time": 1}})).To(Equal(int64(0)))
+				Expect(repo.CountAll(ctx, model.QueryOptions{Filters: squirrel.LtOrEq{"submission_time": 1}})).To(Equal(int64(0)))
 			})
 		})
 
 		Describe("Get", func() {
 			It("returns an existing scrobble for the user", func() {
-				scrobble, err := repo.Get("2")
+				scrobble, err := repo.Get(ctx, "2")
 				Expect(err).To(BeNil())
 				Expect(scrobble.ID).To(Equal(int64(2)))
 				Expect(scrobble.MediaFileID).To(Equal("1003"))
@@ -179,19 +178,19 @@ var _ = Describe("ScrobbleRepository", func() {
 			})
 
 			It("does not return a scrobble that exists for another user", func() {
-				_, err := repo.Get("1")
+				_, err := repo.Get(ctx, "1")
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 
 			It("does not return a scrobble that does not exist", func() {
-				_, err := repo.Get("444")
+				_, err := repo.Get(ctx, "444")
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 		})
 
 		Describe("GetAll", func() {
 			It("returns all scrobbles in reverse order", func() {
-				scrobbles, err := repo.GetAll(model.QueryOptions{
+				scrobbles, err := repo.GetAll(ctx, model.QueryOptions{
 					Sort:  "submission_time",
 					Order: "DESC",
 				})
@@ -204,7 +203,7 @@ var _ = Describe("ScrobbleRepository", func() {
 			})
 
 			It("returns scrobbles in a range", func() {
-				scrobbles, err := repo.GetAll(model.QueryOptions{
+				scrobbles, err := repo.GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.GtOrEq{"submission_time": 1}})
 
 				Expect(err).To(BeNil())
diff --git a/persistence/share_repository.go b/persistence/share_repository.go
index 0cf23068a..6dd9c3d85 100644
--- a/persistence/share_repository.go
+++ b/persistence/share_repository.go
@@ -18,9 +18,8 @@ type shareRepository struct {
 	sqlRepository
 }
 
-func NewShareRepository(ctx context.Context, db dbx.Builder) model.ShareRepository {
+func NewShareRepository(db dbx.Builder) model.ShareRepository {
 	r := &shareRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.registerModel(&model.Share{}, nil)
 	r.setSortMappings(map[string]string{
@@ -29,40 +28,40 @@ func NewShareRepository(ctx context.Context, db dbx.Builder) model.ShareReposito
 	return r
 }
 
-func (r *shareRepository) Delete(id string) error {
-	return r.deleteOwned(id)
+func (r *shareRepository) Delete(ctx context.Context, ids ...string) error {
+	return r.deleteOwnedAll(ctx, ids...)
 }
 
-func (r *shareRepository) selectShare(options ...model.QueryOptions) SelectBuilder {
-	return r.newSelect(options...).Join("user u on u.id = share.user_id").
+func (r *shareRepository) selectShare(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	return r.newSelect(ctx, options...).Join("user u on u.id = share.user_id").
 		Columns("share.*", "user_name as username").
-		Where(r.addRestriction())
+		Where(r.addRestriction(ctx))
 }
 
-func (r *shareRepository) Exists(id string) (bool, error) {
-	return r.exists(r.addRestriction(And{Eq{"id": id}}))
+func (r *shareRepository) Exists(ctx context.Context, id string) (bool, error) {
+	return r.exists(ctx, r.addRestriction(ctx, And{Eq{"id": id}}))
 }
 
-func (r *shareRepository) Get(id string) (*model.Share, error) {
-	sel := r.selectShare().Where(Eq{"share.id": id})
+func (r *shareRepository) Get(ctx context.Context, id string) (*model.Share, error) {
+	sel := r.selectShare(ctx).Where(Eq{"share.id": id})
 	var res model.Share
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
-	err = r.loadMedia(&res)
+	err = r.loadMedia(ctx, &res)
 	return &res, err
 }
 
-func (r *shareRepository) GetAll(options ...model.QueryOptions) (model.Shares, error) {
-	sq := r.selectShare(options...)
+func (r *shareRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Shares, error) {
+	sq := r.selectShare(ctx, options...)
 	res := model.Shares{}
-	err := r.queryAll(sq, &res)
+	err := r.queryAll(ctx, sq, &res)
 	if err != nil {
 		return nil, err
 	}
 	for i := range res {
-		err = r.loadMedia(&res[i])
+		err = r.loadMedia(ctx, &res[i])
 		if err != nil {
 			return nil, fmt.Errorf("error loading media for share %s: %w", res[i].ID, err)
 		}
@@ -70,7 +69,7 @@ func (r *shareRepository) GetAll(options ...model.QueryOptions) (model.Shares, e
 	return res, err
 }
 
-func (r *shareRepository) loadMedia(share *model.Share) error {
+func (r *shareRepository) loadMedia(ctx context.Context, share *model.Share) error {
 	ids := strings.Split(share.ResourceIDs, ",")
 	if len(ids) == 0 {
 		return nil
@@ -79,7 +78,7 @@ func (r *shareRepository) loadMedia(share *model.Share) error {
 		return And{cond, Eq{"missing": false}}
 	}
 	// Load as the share owner so their library access is applied, whoever renders the share.
-	ctx, err := r.ownerContext(share)
+	ownerCtx, err := r.ownerContext(ctx, share)
 	if err != nil {
 		return err
 	}
@@ -87,59 +86,59 @@ func (r *shareRepository) loadMedia(share *model.Share) error {
 	case "artist":
 		// Match by album-artist participation, not the deprecated album_artist_id
 		// column (first album artist only), so co-album-artists are included too.
-		albumRepo := NewAlbumRepository(ctx, r.db)
-		share.Albums, err = albumRepo.GetAll(model.QueryOptions{Filters: noMissing(ParticipantIDFilter("album", ids, model.RoleAlbumArtist)), Sort: "artist"})
+		albumRepo := NewAlbumRepository(r.db)
+		share.Albums, err = albumRepo.GetAll(ownerCtx, model.QueryOptions{Filters: noMissing(ParticipantIDFilter("album", ids, model.RoleAlbumArtist)), Sort: "artist"})
 		if err != nil {
 			return err
 		}
-		mfRepo := NewMediaFileRepository(ctx, r.db)
-		share.Tracks, err = mfRepo.GetAll(model.QueryOptions{Filters: noMissing(ParticipantIDFilter("media_file", ids, model.RoleAlbumArtist)), Sort: "artist"})
+		mfRepo := NewMediaFileRepository(r.db)
+		share.Tracks, err = mfRepo.GetAll(ownerCtx, model.QueryOptions{Filters: noMissing(ParticipantIDFilter("media_file", ids, model.RoleAlbumArtist)), Sort: "artist"})
 		return err
 	case "album":
-		albumRepo := NewAlbumRepository(ctx, r.db)
-		share.Albums, err = albumRepo.GetAll(model.QueryOptions{Filters: noMissing(Eq{"album.id": ids})})
+		albumRepo := NewAlbumRepository(r.db)
+		share.Albums, err = albumRepo.GetAll(ownerCtx, model.QueryOptions{Filters: noMissing(Eq{"album.id": ids})})
 		if err != nil {
 			return err
 		}
-		mfRepo := NewMediaFileRepository(ctx, r.db)
-		share.Tracks, err = mfRepo.GetAll(model.QueryOptions{Filters: noMissing(Eq{"album_id": ids}), Sort: "album"})
+		mfRepo := NewMediaFileRepository(r.db)
+		share.Tracks, err = mfRepo.GetAll(ownerCtx, model.QueryOptions{Filters: noMissing(Eq{"album_id": ids}), Sort: "album"})
 		return err
 	case "playlist":
-		plsRepo := NewPlaylistRepository(ctx, r.db)
+		plsRepo := NewPlaylistRepository(r.db)
 		// Tracks returns nil when the playlist is no longer visible to the owner
 		// (e.g. it was made private after the share was created); leave the share
 		// with no tracks rather than exposing it.
-		trackRepo := plsRepo.Tracks(ids[0], true)
+		trackRepo := plsRepo.Tracks(ownerCtx, ids[0], true)
 		if trackRepo == nil {
 			return nil
 		}
-		tracks, err := trackRepo.GetAll(model.QueryOptions{Sort: "id", Filters: noMissing(Eq{})})
+		tracks, err := trackRepo.GetAll(ownerCtx, model.QueryOptions{Sort: "id", Filters: noMissing(Eq{})})
 		if err != nil {
 			return err
 		}
 		share.Tracks = tracks.MediaFiles()
 		return nil
 	case "media_file":
-		mfRepo := NewMediaFileRepository(ctx, r.db)
-		tracks, err := mfRepo.GetAll(model.QueryOptions{Filters: noMissing(Eq{"media_file.id": ids})})
+		mfRepo := NewMediaFileRepository(r.db)
+		tracks, err := mfRepo.GetAll(ownerCtx, model.QueryOptions{Filters: noMissing(Eq{"media_file.id": ids})})
 		share.Tracks = sortByIdPosition(tracks, ids)
 		return err
 	}
-	log.Warn(r.ctx, "Unsupported Share ResourceType", "share", share.ID, "resourceType", share.ResourceType)
+	log.Warn(ctx, "Unsupported Share ResourceType", "share", share.ID, "resourceType", share.ResourceType)
 	return nil
 }
 
 // ownerContext returns a context scoped to the share owner, so repository
 // queries apply the owner's library access when a public share is rendered.
-func (r *shareRepository) ownerContext(share *model.Share) (context.Context, error) {
-	owner, err := NewUserRepository(r.ctx, r.db).Get(share.UserID)
+func (r *shareRepository) ownerContext(ctx context.Context, share *model.Share) (context.Context, error) {
+	owner, err := NewUserRepository(r.db).Get(ctx, share.UserID)
 	if err != nil {
 		return nil, fmt.Errorf("loading share owner %q: %w", share.UserID, err)
 	}
 	if owner == nil {
 		return nil, fmt.Errorf("share owner %q not found", share.UserID)
 	}
-	return request.WithUser(r.ctx, *owner), nil
+	return request.WithUser(ctx, *owner), nil
 }
 
 func sortByIdPosition(mfs model.MediaFiles, ids []string) model.MediaFiles {
@@ -156,60 +155,51 @@ func sortByIdPosition(mfs model.MediaFiles, ids []string) model.MediaFiles {
 	return sorted
 }
 
-func (r *shareRepository) Update(id string, entity any, cols ...string) error {
-	s := entity.(*model.Share)
+func (r *shareRepository) Update(ctx context.Context, id string, entity model.Share, cols ...string) error {
+	s := &entity
 	s.ID = id
 	s.UpdatedAt = time.Now()
 	if len(cols) > 0 {
 		cols = append(cols, "updated_at")
 	}
-	return r.updateOwned(id, s, cols...)
+	return r.updateOwned(ctx, id, s, cols...)
 }
 
-func (r *shareRepository) Save(entity any) (string, error) {
-	s := entity.(*model.Share)
+func (r *shareRepository) Save(ctx context.Context, s *model.Share) (string, error) {
 	// TODO Validate record
 	// Owner is server-managed: for an authenticated request, never trust a
 	// client-supplied UserID, as it drives the share's library-access context.
-	u := loggedUser(r.ctx)
+	u := loggedUser(ctx)
 	if u.ID != invalidUserId || s.UserID == "" {
 		s.UserID = u.ID
 	}
 	s.CreatedAt = time.Now()
 	s.UpdatedAt = time.Now()
-	return r.put(s.ID, s)
+	return r.put(ctx, s.ID, s)
 }
 
-func (r *shareRepository) CountAll(options ...model.QueryOptions) (int64, error) {
-	return r.count(r.selectShare(), options...)
+func (r *shareRepository) CountAll(ctx context.Context, options ...model.QueryOptions) (int64, error) {
+	return r.count(ctx, r.selectShare(ctx), options...)
 }
 
-func (r *shareRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+func (r *shareRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *shareRepository) EntityName() string {
-	return "share"
-}
-
-func (r *shareRepository) NewInstance() any {
-	return &model.Share{}
-}
-
-func (r *shareRepository) Read(id string) (any, error) {
-	sel := r.selectShare().Where(Eq{"share.id": id})
+func (r *shareRepository) Read(ctx context.Context, id string) (*model.Share, error) {
+	sel := r.selectShare(ctx).Where(Eq{"share.id": id})
 	var res model.Share
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-func (r *shareRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	sq := r.selectShare(r.parseRestOptions(r.ctx, options...))
+func (r *shareRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Share, error) {
+	sq := r.selectShare(ctx, r.parseRestOptions(ctx, options...))
 	res := model.Shares{}
-	err := r.queryAll(sq, &res)
+	err := r.queryAll(ctx, sq, &res)
 	return res, err
 }
 
 var _ model.ShareRepository = (*shareRepository)(nil)
-var _ rest.Repository = (*shareRepository)(nil)
-var _ rest.Persistable = (*shareRepository)(nil)
+var _ rest.Repository[model.Share] = (*shareRepository)(nil)
+var _ rest.Persistable[model.Share] = (*shareRepository)(nil)
diff --git a/persistence/share_repository_test.go b/persistence/share_repository_test.go
index af8cf2ae9..33b5e2110 100644
--- a/persistence/share_repository_test.go
+++ b/persistence/share_repository_test.go
@@ -22,11 +22,11 @@ var _ = Describe("ShareRepository", func() {
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
-		repo = NewShareRepository(ctx, GetDBXBuilder())
+		repo = NewShareRepository(GetDBXBuilder())
 
 		// Insert the admin user into the database (required for foreign key constraint)
-		ur := NewUserRepository(ctx, GetDBXBuilder())
-		err := ur.Put(&adminUser)
+		ur := NewUserRepository(GetDBXBuilder())
+		err := ur.Put(ctx, &adminUser)
 		Expect(err).ToNot(HaveOccurred())
 
 		// Clean up shares
@@ -37,9 +37,15 @@ var _ = Describe("ShareRepository", func() {
 
 	Describe("Headless Access", func() {
 		Context("Repository creation and basic operations", func() {
+			var headlessCtx context.Context
+
+			BeforeEach(func() {
+				headlessCtx = GinkgoT().Context()
+			})
+
 			It("should create repository successfully with no user context", func() {
 				// Create repository with no user context (headless)
-				headlessRepo := NewShareRepository(GinkgoT().Context(), GetDBXBuilder())
+				headlessRepo := NewShareRepository(GetDBXBuilder())
 				Expect(headlessRepo).ToNot(BeNil())
 			})
 
@@ -61,8 +67,8 @@ var _ = Describe("ShareRepository", func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				// Headless process should see all shares
-				headlessRepo := NewShareRepository(GinkgoT().Context(), GetDBXBuilder())
-				shares, err := headlessRepo.GetAll()
+				headlessRepo := NewShareRepository(GetDBXBuilder())
+				shares, err := headlessRepo.GetAll(headlessCtx)
 				Expect(err).ToNot(HaveOccurred())
 
 				found := false
@@ -93,8 +99,8 @@ var _ = Describe("ShareRepository", func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				// Headless process should be able to get the share
-				headlessRepo := NewShareRepository(GinkgoT().Context(), GetDBXBuilder())
-				share, err := headlessRepo.Get(shareID)
+				headlessRepo := NewShareRepository(GetDBXBuilder())
+				share, err := headlessRepo.Get(headlessCtx, shareID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(share.ID).To(Equal(shareID))
 				Expect(share.Description).To(Equal("Headless Get Share"))
@@ -125,7 +131,7 @@ var _ = Describe("ShareRepository", func() {
 
 			// The Get operation should work without SQL ambiguity errors
 			// even if no albums are found
-			share, err := repo.Get(shareID)
+			share, err := repo.Get(ctx, shareID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(share.ID).To(Equal(shareID))
 			// Albums array should be empty since we used non-existent album ID
@@ -142,26 +148,26 @@ var _ = Describe("ShareRepository", func() {
 			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
 
 			// A second library the owner has no access to, plus a track in it
-			lr := NewLibraryRepository(adminCtx, GetDBXBuilder())
+			lr := NewLibraryRepository(GetDBXBuilder())
 			otherLib = model.Library{ID: 0, Name: "Share Other Library", Path: "/share/other/lib"}
-			Expect(lr.Put(&otherLib)).To(Succeed())
-			mr := NewMediaFileRepository(adminCtx, GetDBXBuilder())
-			Expect(mr.Put(&model.MediaFile{ID: "share-other", LibraryID: otherLib.ID, Path: "s/other.mp3", Title: "ShareOther"})).To(Succeed())
-			Expect(mr.Put(&model.MediaFile{ID: "share-ok", LibraryID: 1, Path: "s/ok.mp3", Title: "ShareOK"})).To(Succeed())
+			Expect(lr.Put(adminCtx, &otherLib)).To(Succeed())
+			mr := NewMediaFileRepository(GetDBXBuilder())
+			Expect(mr.Put(adminCtx, &model.MediaFile{ID: "share-other", LibraryID: otherLib.ID, Path: "s/other.mp3", Title: "ShareOther"})).To(Succeed())
+			Expect(mr.Put(adminCtx, &model.MediaFile{ID: "share-ok", LibraryID: 1, Path: "s/ok.mp3", Title: "ShareOK"})).To(Succeed())
 
 			// Non-admin owner with access to library 1 only
 			owner = createUserWithLibraries("share-owner", []int{1})
-			ur := NewUserRepository(adminCtx, GetDBXBuilder())
-			Expect(ur.Put(&owner)).To(Succeed())
-			Expect(ur.SetUserLibraries(owner.ID, []int{1})).To(Succeed())
+			ur := NewUserRepository(GetDBXBuilder())
+			Expect(ur.Put(adminCtx, &owner)).To(Succeed())
+			Expect(ur.SetUserLibraries(adminCtx, owner.ID, []int{1})).To(Succeed())
 
 			// Owner-owned playlist containing tracks from both libraries
 			plsID = "share-scope-pls"
 			ownerCtx := request.WithUser(log.NewContext(GinkgoT().Context()), owner)
-			pr := NewPlaylistRepository(ownerCtx, GetDBXBuilder())
+			pr := NewPlaylistRepository(GetDBXBuilder())
 			pls := &model.Playlist{ID: plsID, Name: "Scope Test", OwnerID: owner.ID}
 			pls.AddMediaFiles(model.MediaFiles{{ID: "share-ok"}, {ID: "share-other"}})
-			Expect(pr.Put(pls)).To(Succeed())
+			Expect(pr.Put(ownerCtx, pls)).To(Succeed())
 
 			// Share row owned by the non-admin owner
 			_, err := GetDBXBuilder().NewQuery(`
@@ -178,20 +184,21 @@ var _ = Describe("ShareRepository", func() {
 			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
 			b := GetDBXBuilder()
 			_, _ = b.NewQuery(`DELETE FROM share WHERE id = 'share-scope'`).Execute()
-			pr := NewPlaylistRepository(adminCtx, b)
-			_ = pr.Delete(plsID)
-			mr := NewMediaFileRepository(adminCtx, b).(*mediaFileRepository)
-			_, _ = mr.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": []string{"share-other", "share-ok"}}))
-			lr := NewLibraryRepository(adminCtx, b).(*libraryRepository)
-			_ = lr.delete(squirrel.Eq{"id": otherLib.ID})
-			_ = NewUserRepository(adminCtx, b).Delete(owner.ID)
+			pr := NewPlaylistRepository(b)
+			_ = pr.Delete(adminCtx, plsID)
+			mr := NewMediaFileRepository(b).(*mediaFileRepository)
+			_, _ = mr.executeSQL(adminCtx, squirrel.Delete("media_file").Where(squirrel.Eq{"id": []string{"share-other", "share-ok"}}))
+			lr := NewLibraryRepository(b).(*libraryRepository)
+			_ = lr.delete(adminCtx, squirrel.Eq{"id": otherLib.ID})
+			_ = NewUserRepository(b).Delete(adminCtx, owner.ID)
 		})
 
 		It("excludes tracks the owner cannot access from the shared playlist", func() {
 			// Read the share as admin (mimics the public-share render path, which uses
 			// the share repository's own context). loadMedia must scope to the owner.
-			adminRepo := NewShareRepository(request.WithUser(log.NewContext(GinkgoT().Context()), adminUser), GetDBXBuilder())
-			share, err := adminRepo.Get("share-scope")
+			adminCtx := request.WithUser(ctx, adminUser)
+			adminRepo := NewShareRepository(GetDBXBuilder())
+			share, err := adminRepo.Get(adminCtx, "share-scope")
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(share.Tracks).To(ContainElement(HaveField("ID", "share-ok")))
@@ -205,11 +212,11 @@ var _ = Describe("ShareRepository", func() {
 			// instead of panicking.
 			privatePlsID := "private-pls"
 			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
-			pr := NewPlaylistRepository(adminCtx, GetDBXBuilder())
+			pr := NewPlaylistRepository(GetDBXBuilder())
 			privatePls := &model.Playlist{ID: privatePlsID, Name: "Private", OwnerID: adminUser.ID, Public: false}
 			privatePls.AddMediaFiles(model.MediaFiles{{ID: "share-ok"}})
-			Expect(pr.Put(privatePls)).To(Succeed())
-			DeferCleanup(func() { _ = pr.Delete(privatePlsID) })
+			Expect(pr.Put(adminCtx, privatePls)).To(Succeed())
+			DeferCleanup(func() { _ = pr.Delete(adminCtx, privatePlsID) })
 
 			_, err := GetDBXBuilder().NewQuery(`
 				INSERT INTO share (id, user_id, description, resource_type, resource_ids, created_at, updated_at)
@@ -221,8 +228,8 @@ var _ = Describe("ShareRepository", func() {
 			Expect(err).ToNot(HaveOccurred())
 			DeferCleanup(func() { _, _ = GetDBXBuilder().NewQuery(`DELETE FROM share WHERE id = 'share-private'`).Execute() })
 
-			adminRepo := NewShareRepository(adminCtx, GetDBXBuilder())
-			share, err := adminRepo.Get("share-private")
+			adminRepo := NewShareRepository(GetDBXBuilder())
+			share, err := adminRepo.Get(adminCtx, "share-private")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(share.Tracks).To(BeEmpty())
 		})
@@ -239,13 +246,13 @@ var _ = Describe("ShareRepository", func() {
 			b := GetDBXBuilder()
 
 			// A second library the owner has no access to
-			lr := NewLibraryRepository(adminCtx, b)
+			lr := NewLibraryRepository(b)
 			otherLib = model.Library{ID: 0, Name: "Artist Share Other Library", Path: "/share/artist/other"}
-			Expect(lr.Put(&otherLib)).To(Succeed())
+			Expect(lr.Put(adminCtx, &otherLib)).To(Succeed())
 
-			ar := NewArtistRepository(adminCtx, b)
-			Expect(createArtistWithLibrary(ar, &model.Artist{ID: primaryID, Name: "AA Primary", OrderArtistName: "aa primary"}, 1)).To(Succeed())
-			Expect(createArtistWithLibrary(ar, &model.Artist{ID: secondaryID, Name: "AA Secondary", OrderArtistName: "aa secondary"}, 1)).To(Succeed())
+			ar := NewArtistRepository(b)
+			Expect(createArtistWithLibrary(adminCtx, ar, &model.Artist{ID: primaryID, Name: "AA Primary", OrderArtistName: "aa primary"}, 1)).To(Succeed())
+			Expect(createArtistWithLibrary(adminCtx, ar, &model.Artist{ID: secondaryID, Name: "AA Secondary", OrderArtistName: "aa secondary"}, 1)).To(Succeed())
 
 			// Secondary is a co-album-artist (not the first): album_artist_id points at
 			// primary, so the legacy-column filter would miss both tracks.
@@ -253,19 +260,19 @@ var _ = Describe("ShareRepository", func() {
 				{Artist: model.Artist{ID: primaryID, Name: "AA Primary"}},
 				{Artist: model.Artist{ID: secondaryID, Name: "AA Secondary"}},
 			}}
-			alr := NewAlbumRepository(adminCtx, b)
-			Expect(alr.Put(&model.Album{ID: "art-album-ok", LibraryID: 1, Name: "Art Album OK", AlbumArtistID: primaryID, AlbumArtist: "AA Primary", Participants: aaParticipants})).To(Succeed())
-			Expect(alr.Put(&model.Album{ID: "art-album-other", LibraryID: otherLib.ID, Name: "Art Album Other", AlbumArtistID: primaryID, AlbumArtist: "AA Primary", Participants: aaParticipants})).To(Succeed())
+			alr := NewAlbumRepository(b)
+			Expect(alr.Put(ctx, &model.Album{ID: "art-album-ok", LibraryID: 1, Name: "Art Album OK", AlbumArtistID: primaryID, AlbumArtist: "AA Primary", Participants: aaParticipants})).To(Succeed())
+			Expect(alr.Put(ctx, &model.Album{ID: "art-album-other", LibraryID: otherLib.ID, Name: "Art Album Other", AlbumArtistID: primaryID, AlbumArtist: "AA Primary", Participants: aaParticipants})).To(Succeed())
 
-			mr := NewMediaFileRepository(adminCtx, b)
-			Expect(mr.Put(&model.MediaFile{ID: "art-ok", LibraryID: 1, AlbumID: "art-album-ok", Path: "a/ok.mp3", Title: "ArtOK", AlbumArtistID: primaryID, Participants: aaParticipants})).To(Succeed())
-			Expect(mr.Put(&model.MediaFile{ID: "art-other", LibraryID: otherLib.ID, AlbumID: "art-album-other", Path: "a/other.mp3", Title: "ArtOther", AlbumArtistID: primaryID, Participants: aaParticipants})).To(Succeed())
+			mr := NewMediaFileRepository(b)
+			Expect(mr.Put(adminCtx, &model.MediaFile{ID: "art-ok", LibraryID: 1, AlbumID: "art-album-ok", Path: "a/ok.mp3", Title: "ArtOK", AlbumArtistID: primaryID, Participants: aaParticipants})).To(Succeed())
+			Expect(mr.Put(adminCtx, &model.MediaFile{ID: "art-other", LibraryID: otherLib.ID, AlbumID: "art-album-other", Path: "a/other.mp3", Title: "ArtOther", AlbumArtistID: primaryID, Participants: aaParticipants})).To(Succeed())
 
 			// Non-admin owner with access to library 1 only
 			owner = createUserWithLibraries("artist-share-owner", []int{1})
-			ur := NewUserRepository(adminCtx, b)
-			Expect(ur.Put(&owner)).To(Succeed())
-			Expect(ur.SetUserLibraries(owner.ID, []int{1})).To(Succeed())
+			ur := NewUserRepository(b)
+			Expect(ur.Put(adminCtx, &owner)).To(Succeed())
+			Expect(ur.SetUserLibraries(adminCtx, owner.ID, []int{1})).To(Succeed())
 
 			for _, s := range []struct{ id, typ, ids string }{
 				{"art-share", "artist", secondaryID},
@@ -287,22 +294,23 @@ var _ = Describe("ShareRepository", func() {
 			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
 			b := GetDBXBuilder()
 			_, _ = b.NewQuery(`DELETE FROM share WHERE id IN ('art-share', 'art-album-share', 'art-mf-share')`).Execute()
-			mr := NewMediaFileRepository(adminCtx, b).(*mediaFileRepository)
-			_, _ = mr.executeSQL(squirrel.Delete("media_file").Where(squirrel.Eq{"id": []string{"art-ok", "art-other"}}))
-			alr := NewAlbumRepository(adminCtx, b).(*albumRepository)
-			_, _ = alr.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"art-album-ok", "art-album-other"}}))
-			ar := NewArtistRepository(adminCtx, b).(*artistRepository)
-			_, _ = ar.executeSQL(squirrel.Delete("artist").Where(squirrel.Eq{"id": []string{primaryID, secondaryID}}))
-			lr := NewLibraryRepository(adminCtx, b).(*libraryRepository)
-			_ = lr.delete(squirrel.Eq{"id": otherLib.ID})
-			_ = NewUserRepository(adminCtx, b).Delete(owner.ID)
+			mr := NewMediaFileRepository(b).(*mediaFileRepository)
+			_, _ = mr.executeSQL(adminCtx, squirrel.Delete("media_file").Where(squirrel.Eq{"id": []string{"art-ok", "art-other"}}))
+			alr := NewAlbumRepository(b).(*albumRepository)
+			_, _ = alr.executeSQL(adminCtx, squirrel.Delete("album").Where(squirrel.Eq{"id": []string{"art-album-ok", "art-album-other"}}))
+			ar := NewArtistRepository(b).(*artistRepository)
+			_, _ = ar.executeSQL(adminCtx, squirrel.Delete("artist").Where(squirrel.Eq{"id": []string{primaryID, secondaryID}}))
+			lr := NewLibraryRepository(b).(*libraryRepository)
+			_ = lr.delete(adminCtx, squirrel.Eq{"id": otherLib.ID})
+			_ = NewUserRepository(b).Delete(adminCtx, owner.ID)
 		})
 
 		It("includes co-album-artist tracks the owner can access and excludes those they cannot", func() {
 			// Read as admin (mimics the public-share render path); loadMedia must still
 			// scope to the owner's libraries.
-			adminRepo := NewShareRepository(request.WithUser(log.NewContext(GinkgoT().Context()), adminUser), GetDBXBuilder())
-			share, err := adminRepo.Get("art-share")
+			adminCtx := request.WithUser(ctx, adminUser)
+			adminRepo := NewShareRepository(GetDBXBuilder())
+			share, err := adminRepo.Get(adminCtx, "art-share")
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(share.Tracks).To(ContainElement(HaveField("ID", "art-ok")),
@@ -318,7 +326,7 @@ var _ = Describe("ShareRepository", func() {
 
 		It("excludes albums and their tracks outside the owner's libraries from an album share", func() {
 			// Public share rendering has no user in the context.
-			share, err := NewShareRepository(log.NewContext(GinkgoT().Context()), GetDBXBuilder()).Get("art-album-share")
+			share, err := NewShareRepository(GetDBXBuilder()).Get(log.NewContext(GinkgoT().Context()), "art-album-share")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(share.Albums).To(ContainElement(HaveField("ID", "art-album-ok")))
 			Expect(share.Albums).ToNot(ContainElement(HaveField("ID", "art-album-other")))
@@ -327,7 +335,7 @@ var _ = Describe("ShareRepository", func() {
 		})
 
 		It("excludes tracks outside the owner's libraries from a media file share", func() {
-			share, err := NewShareRepository(log.NewContext(GinkgoT().Context()), GetDBXBuilder()).Get("art-mf-share")
+			share, err := NewShareRepository(GetDBXBuilder()).Get(log.NewContext(GinkgoT().Context()), "art-mf-share")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(share.Tracks).To(ContainElement(HaveField("ID", "art-ok")))
 			Expect(share.Tracks).ToNot(ContainElement(HaveField("ID", "art-other")))
@@ -358,58 +366,59 @@ var _ = Describe("ShareRepository", func() {
 			It("allows a non-admin user to delete their own share", func() {
 				insertShare("own-share-del", ownerUser.ID)
 				ctx := request.WithUser(log.NewContext(GinkgoT().Context()), ownerUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
-				err := repo.(rest.Persistable).Delete("own-share-del")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Delete(ctx, "own-share-del")
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("denies a non-admin user from deleting another user's share", func() {
 				insertShare("other-share-del", ownerUser.ID)
 				ctx := request.WithUser(log.NewContext(GinkgoT().Context()), otherUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
-				err := repo.(rest.Persistable).Delete("other-share-del")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Delete(ctx, "other-share-del")
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 
 				// The share was not deleted: the owner can still read it.
 				ownerCtx := request.WithUser(log.NewContext(GinkgoT().Context()), ownerUser)
-				ownerRepo := NewShareRepository(ownerCtx, GetDBXBuilder())
-				_, err = ownerRepo.(rest.Repository).Read("other-share-del")
+				ownerRepo := NewShareRepository(GetDBXBuilder())
+				_, err = ownerRepo.Read(ownerCtx, "other-share-del")
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("allows an admin to delete any user's share", func() {
 				insertShare("admin-del-share", ownerUser.ID)
 				ctx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
-				err := repo.(rest.Persistable).Delete("admin-del-share")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Delete(ctx, "admin-del-share")
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("allows headless context (no user) to delete a share", func() {
 				insertShare("headless-del-share", ownerUser.ID)
-				repo := NewShareRepository(GinkgoT().Context(), GetDBXBuilder())
-				err := repo.(rest.Persistable).Delete("headless-del-share")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Delete(GinkgoT().Context(), "headless-del-share")
 				Expect(err).ToNot(HaveOccurred())
 			})
 		})
 
 		Describe("Save", func() {
 			It("assigns the logged-in user as owner, ignoring a client-supplied UserID", func() {
-				ur := NewUserRepository(ctx, GetDBXBuilder())
-				Expect(ur.Put(&ownerUser)).To(Succeed())
-				Expect(ur.Put(&otherUser)).To(Succeed())
+				ur := NewUserRepository(GetDBXBuilder())
+				Expect(ur.Put(ctx, &ownerUser)).To(Succeed())
+				Expect(ur.Put(ctx, &otherUser)).To(Succeed())
 
 				attackerCtx := request.WithUser(log.NewContext(GinkgoT().Context()), ownerUser)
-				attackerRepo := NewShareRepository(attackerCtx, GetDBXBuilder()).(rest.Persistable)
+				attackerRepo := NewShareRepository(GetDBXBuilder())
 
-				id, err := attackerRepo.Save(&model.Share{
+				id, err := attackerRepo.Save(attackerCtx, &model.Share{
 					ID: "spoof-save-share", UserID: otherUser.ID,
 					ResourceType: "media_file", ResourceIDs: "1001",
 				})
 				Expect(err).ToNot(HaveOccurred())
 
-				adminRepo := NewShareRepository(request.WithUser(log.NewContext(GinkgoT().Context()), adminUser), GetDBXBuilder())
-				got, err := adminRepo.Get(id)
+				adminCtx := request.WithUser(ctx, adminUser)
+				adminRepo := NewShareRepository(GetDBXBuilder())
+				got, err := adminRepo.Get(adminCtx, id)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(got.UserID).To(Equal(ownerUser.ID))
 			})
@@ -419,53 +428,52 @@ var _ = Describe("ShareRepository", func() {
 			It("allows a non-admin user to update their own share", func() {
 				insertShare("own-share-upd", ownerUser.ID)
 				ctx := request.WithUser(log.NewContext(GinkgoT().Context()), ownerUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
-				err := repo.(rest.Persistable).Update("own-share-upd", &model.Share{Description: "Updated"}, "description")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Update(ctx, "own-share-upd", model.Share{Description: "Updated"}, "description")
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("denies a non-admin user from updating another user's share", func() {
 				insertShare("other-share-upd", ownerUser.ID)
 				ctx := request.WithUser(log.NewContext(GinkgoT().Context()), otherUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
-				err := repo.(rest.Persistable).Update("other-share-upd", &model.Share{Description: "Hacked"}, "description")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Update(ctx, "other-share-upd", model.Share{Description: "Hacked"}, "description")
 				Expect(err).To(Equal(rest.ErrPermissionDenied))
 			})
 
 			It("allows an admin to update any user's share", func() {
 				insertShare("admin-upd-share", ownerUser.ID)
 				ctx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
-				err := repo.(rest.Persistable).Update("admin-upd-share", &model.Share{Description: "Admin Updated"}, "description")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Update(ctx, "admin-upd-share", model.Share{Description: "Admin Updated"}, "description")
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("allows headless context (no user) to update a share", func() {
 				insertShare("headless-upd-share", ownerUser.ID)
-				repo := NewShareRepository(GinkgoT().Context(), GetDBXBuilder())
-				err := repo.(rest.Persistable).Update("headless-upd-share", &model.Share{Description: "Headless"}, "description")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Update(GinkgoT().Context(), "headless-upd-share", model.Share{Description: "Headless"}, "description")
 				Expect(err).ToNot(HaveOccurred())
 			})
 
 			It("returns not found when updating a nonexistent share", func() {
 				ctx := request.WithUser(log.NewContext(context.TODO()), ownerUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
-				err := repo.(rest.Persistable).Update("does-not-exist", &model.Share{Description: "Ghost"}, "description")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Update(ctx, "does-not-exist", model.Share{Description: "Ghost"}, "description")
 				Expect(err).To(Equal(rest.ErrNotFound))
 			})
 
 			It("updates all columns when no specific columns are given", func() {
 				insertShare("all-cols-share", ownerUser.ID)
 				ctx := request.WithUser(log.NewContext(context.TODO()), ownerUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
+				repo := NewShareRepository(GetDBXBuilder())
 				// No cols: the update must write every column, not just updated_at.
-				err := repo.(rest.Persistable).Update("all-cols-share",
-					&model.Share{Description: "All Updated", MaxBitRate: 192, ResourceType: "album", ResourceIDs: "2002"})
+				err := repo.Update(ctx, "all-cols-share",
+					model.Share{Description: "All Updated", MaxBitRate: 192, ResourceType: "album", ResourceIDs: "2002"})
 				Expect(err).ToNot(HaveOccurred())
 
-				got, err := repo.(rest.Repository).Read("all-cols-share")
+				share, err := repo.Read(ctx, "all-cols-share")
 				Expect(err).ToNot(HaveOccurred())
-				share := got.(*model.Share)
 				Expect(share.Description).To(Equal("All Updated"))
 				Expect(share.MaxBitRate).To(Equal(192))
 				Expect(share.ResourceType).To(Equal("album"))
@@ -474,24 +482,24 @@ var _ = Describe("ShareRepository", func() {
 			It("does not let an owner reassign their share to another user", func() {
 				insertShare("reassign-share", ownerUser.ID)
 				ctx := request.WithUser(log.NewContext(context.TODO()), ownerUser)
-				repo := NewShareRepository(ctx, GetDBXBuilder())
-				err := repo.(rest.Persistable).Update("reassign-share",
-					&model.Share{UserID: otherUser.ID, Description: "Given away"}, "user_id", "description")
+				repo := NewShareRepository(GetDBXBuilder())
+				err := repo.Update(ctx, "reassign-share",
+					model.Share{UserID: otherUser.ID, Description: "Given away"}, "user_id", "description")
 				Expect(err).ToNot(HaveOccurred())
 
 				// Ownership must not have moved, even though user_id was passed in the body and cols.
-				got, err := repo.(rest.Repository).Read("reassign-share")
+				got, err := repo.Read(ctx, "reassign-share")
 				Expect(err).ToNot(HaveOccurred())
-				Expect(got.(*model.Share).UserID).To(Equal(ownerUser.ID))
+				Expect(got.UserID).To(Equal(ownerUser.ID))
 			})
 		})
 
 		Describe("Read scoping", func() {
 			BeforeEach(func() {
 				// Persist owner/other users so the JOIN in selectShare resolves.
-				ur := NewUserRepository(ctx, GetDBXBuilder())
-				Expect(ur.Put(&ownerUser)).To(Succeed())
-				Expect(ur.Put(&otherUser)).To(Succeed())
+				ur := NewUserRepository(GetDBXBuilder())
+				Expect(ur.Put(ctx, &ownerUser)).To(Succeed())
+				Expect(ur.Put(ctx, &otherUser)).To(Succeed())
 
 				insertShare("share-owner-1", ownerUser.ID)
 				insertShare("share-owner-2", ownerUser.ID)
@@ -500,16 +508,15 @@ var _ = Describe("ShareRepository", func() {
 
 			Context("non-admin user", func() {
 				var nonAdminRepo model.ShareRepository
-				var nonAdminRest rest.Repository
+				var nonAdminCtx context.Context
 
 				BeforeEach(func() {
-					nonAdminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), ownerUser)
-					nonAdminRepo = NewShareRepository(nonAdminCtx, GetDBXBuilder())
-					nonAdminRest = nonAdminRepo.(rest.Repository)
+					nonAdminCtx = request.WithUser(ctx, ownerUser)
+					nonAdminRepo = NewShareRepository(GetDBXBuilder())
 				})
 
 				It("GetAll returns only own shares", func() {
-					shares, err := nonAdminRepo.GetAll()
+					shares, err := nonAdminRepo.GetAll(nonAdminCtx)
 					Expect(err).ToNot(HaveOccurred())
 					ids := make([]string, len(shares))
 					for i, s := range shares {
@@ -519,9 +526,8 @@ var _ = Describe("ShareRepository", func() {
 				})
 
 				It("ReadAll returns only own shares", func() {
-					res, err := nonAdminRest.ReadAll()
+					shares, err := nonAdminRepo.ReadAll(nonAdminCtx)
 					Expect(err).ToNot(HaveOccurred())
-					shares := res.(model.Shares)
 					ids := make([]string, len(shares))
 					for i, s := range shares {
 						ids[i] = s.ID
@@ -530,41 +536,41 @@ var _ = Describe("ShareRepository", func() {
 				})
 
 				It("Get returns own share", func() {
-					s, err := nonAdminRepo.Get("share-owner-1")
+					s, err := nonAdminRepo.Get(nonAdminCtx, "share-owner-1")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(s.ID).To(Equal("share-owner-1"))
 				})
 
 				It("Get returns ErrNotFound for another user's share", func() {
-					_, err := nonAdminRepo.Get("share-other-1")
+					_, err := nonAdminRepo.Get(nonAdminCtx, "share-other-1")
 					Expect(err).To(MatchError(model.ErrNotFound))
 				})
 
 				It("Read returns ErrNotFound for another user's share", func() {
-					_, err := nonAdminRest.Read("share-other-1")
+					_, err := nonAdminRepo.Read(nonAdminCtx, "share-other-1")
 					Expect(err).To(MatchError(model.ErrNotFound))
 				})
 
 				It("Exists returns true for own share", func() {
-					exists, err := nonAdminRepo.Exists("share-owner-1")
+					exists, err := nonAdminRepo.Exists(nonAdminCtx, "share-owner-1")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(exists).To(BeTrue())
 				})
 
 				It("Exists returns false for another user's share", func() {
-					exists, err := nonAdminRepo.Exists("share-other-1")
+					exists, err := nonAdminRepo.Exists(nonAdminCtx, "share-other-1")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(exists).To(BeFalse())
 				})
 
 				It("CountAll counts only own shares", func() {
-					count, err := nonAdminRepo.CountAll()
+					count, err := nonAdminRepo.CountAll(nonAdminCtx)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(count).To(BeNumerically("==", 2))
 				})
 
 				It("Count (rest) counts only own shares", func() {
-					count, err := nonAdminRest.Count()
+					count, err := nonAdminRepo.Count(nonAdminCtx)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(count).To(BeNumerically("==", 2))
 				})
@@ -573,8 +579,8 @@ var _ = Describe("ShareRepository", func() {
 			Context("admin user", func() {
 				It("GetAll returns all shares", func() {
 					adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
-					adminRepo := NewShareRepository(adminCtx, GetDBXBuilder())
-					shares, err := adminRepo.GetAll()
+					adminRepo := NewShareRepository(GetDBXBuilder())
+					shares, err := adminRepo.GetAll(adminCtx)
 					Expect(err).ToNot(HaveOccurred())
 					ids := make([]string, len(shares))
 					for i, s := range shares {
@@ -585,31 +591,37 @@ var _ = Describe("ShareRepository", func() {
 
 				It("CountAll counts all shares", func() {
 					adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
-					adminRepo := NewShareRepository(adminCtx, GetDBXBuilder())
-					count, err := adminRepo.CountAll()
+					adminRepo := NewShareRepository(GetDBXBuilder())
+					count, err := adminRepo.CountAll(adminCtx)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(count).To(BeNumerically("==", 3))
 				})
 			})
 
 			Context("headless context (public share route)", func() {
+				var headlessCtx context.Context
+
+				BeforeEach(func() {
+					headlessCtx = GinkgoT().Context()
+				})
+
 				It("GetAll returns all shares", func() {
-					headlessRepo := NewShareRepository(GinkgoT().Context(), GetDBXBuilder())
-					shares, err := headlessRepo.GetAll()
+					headlessRepo := NewShareRepository(GetDBXBuilder())
+					shares, err := headlessRepo.GetAll(headlessCtx)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(shares).To(HaveLen(3))
 				})
 
 				It("Get returns another user's share", func() {
-					headlessRepo := NewShareRepository(GinkgoT().Context(), GetDBXBuilder())
-					s, err := headlessRepo.Get("share-other-1")
+					headlessRepo := NewShareRepository(GetDBXBuilder())
+					s, err := headlessRepo.Get(headlessCtx, "share-other-1")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(s.ID).To(Equal("share-other-1"))
 				})
 
 				It("Exists returns true for any share", func() {
-					headlessRepo := NewShareRepository(GinkgoT().Context(), GetDBXBuilder())
-					exists, err := headlessRepo.Exists("share-other-1")
+					headlessRepo := NewShareRepository(GetDBXBuilder())
+					exists, err := headlessRepo.Exists(headlessCtx, "share-other-1")
 					Expect(err).ToNot(HaveOccurred())
 					Expect(exists).To(BeTrue())
 				})
diff --git a/persistence/smart_playlist_repository.go b/persistence/smart_playlist_repository.go
index 24c6f5fc5..871f53dd2 100644
--- a/persistence/smart_playlist_repository.go
+++ b/persistence/smart_playlist_repository.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"slices"
 	"time"
 
@@ -18,76 +19,76 @@ import (
 // configured refresh delay.
 
 // refreshSmartPlaylist evaluates the criteria of a smart playlist and updates its tracks accordingly.
-func (r *playlistRepository) refreshSmartPlaylist(pls *model.Playlist) bool {
-	return r.refreshSmartPlaylistTree(pls, map[string]struct{}{})
+func (r *playlistRepository) refreshSmartPlaylist(ctx context.Context, pls *model.Playlist) bool {
+	return r.refreshSmartPlaylistTree(ctx, pls, map[string]struct{}{})
 }
 
 // The visited set stops playlists that reference each other from recursing forever.
-func (r *playlistRepository) refreshSmartPlaylistTree(pls *model.Playlist, visited map[string]struct{}) bool {
+func (r *playlistRepository) refreshSmartPlaylistTree(ctx context.Context, pls *model.Playlist, visited map[string]struct{}) bool {
 	if _, seen := visited[pls.ID]; seen {
-		log.Trace(r.ctx, "Skipping already visited smart playlist", "playlist", pls.Name, "id", pls.ID)
+		log.Trace(ctx, "Skipping already visited smart playlist", "playlist", pls.Name, "id", pls.ID)
 		return false
 	}
 	visited[pls.ID] = struct{}{}
 
-	usr := loggedUser(r.ctx)
-	if !r.shouldRefreshSmartPlaylist(pls, usr) {
+	usr := loggedUser(ctx)
+	if !r.shouldRefreshSmartPlaylist(ctx, pls, usr) {
 		return false
 	}
 
-	log.Debug(r.ctx, "Refreshing smart playlist", "playlist", pls.Name, "id", pls.ID)
+	log.Debug(ctx, "Refreshing smart playlist", "playlist", pls.Name, "id", pls.ID)
 	start := time.Now()
 
 	del := Delete("playlist_tracks").Where(Eq{"playlist_id": pls.ID})
-	if _, err := r.executeSQL(del); err != nil {
-		log.Error(r.ctx, "Error deleting old smart playlist tracks", "playlist", pls.Name, "id", pls.ID, err)
+	if _, err := r.executeSQL(ctx, del); err != nil {
+		log.Error(ctx, "Error deleting old smart playlist tracks", "playlist", pls.Name, "id", pls.ID, err)
 		return false
 	}
 
 	rulesSQL := newSmartPlaylistCriteria(*pls.NormalizedRules(), withSmartPlaylistOwner(*usr))
 
-	if !r.refreshChildPlaylists(pls, rulesSQL, visited) {
+	if !r.refreshChildPlaylists(ctx, pls, rulesSQL, visited) {
 		return false
 	}
 
-	if err := r.resolvePercentageLimit(pls, &rulesSQL, usr.ID); err != nil {
+	if err := r.resolvePercentageLimit(ctx, pls, &rulesSQL, usr.ID); err != nil {
 		return false
 	}
 
-	sq := r.buildSmartPlaylistQuery(pls, rulesSQL, usr.ID)
+	sq := r.buildSmartPlaylistQuery(ctx, pls, rulesSQL, usr.ID)
 	sq, err := r.addCriteria(sq, rulesSQL)
 	if err != nil {
-		log.Error(r.ctx, "Error building smart playlist criteria", "playlist", pls.Name, "id", pls.ID, err)
+		log.Error(ctx, "Error building smart playlist criteria", "playlist", pls.Name, "id", pls.ID, err)
 		return false
 	}
 
 	insSql := Insert("playlist_tracks").Columns("id", "playlist_id", "media_file_id").Select(sq)
-	if _, err = r.executeSQL(insSql); err != nil {
-		log.Error(r.ctx, "Error refreshing smart playlist tracks", "playlist", pls.Name, "id", pls.ID, err)
+	if _, err = r.executeSQL(ctx, insSql); err != nil {
+		log.Error(ctx, "Error refreshing smart playlist tracks", "playlist", pls.Name, "id", pls.ID, err)
 		return false
 	}
 
-	if err = r.refreshCounters(pls); err != nil {
-		log.Error(r.ctx, "Error updating smart playlist stats", "playlist", pls.Name, "id", pls.ID, err)
+	if err = r.refreshCounters(ctx, pls); err != nil {
+		log.Error(ctx, "Error updating smart playlist stats", "playlist", pls.Name, "id", pls.ID, err)
 		return false
 	}
 
 	// Reuse the stamp refreshCounters just wrote, so evaluated_at and updated_at agree
 	now := pls.UpdatedAt
 	updSql := Update(r.tableName).Set("evaluated_at", now).Where(Eq{"id": pls.ID})
-	if _, err = r.executeSQL(updSql); err != nil {
-		log.Error(r.ctx, "Error updating smart playlist", "playlist", pls.Name, "id", pls.ID, err)
+	if _, err = r.executeSQL(ctx, updSql); err != nil {
+		log.Error(ctx, "Error updating smart playlist", "playlist", pls.Name, "id", pls.ID, err)
 		return false
 	}
 	pls.EvaluatedAt = &now
 
-	log.Debug(r.ctx, "Refreshed playlist", "playlist", pls.Name, "id", pls.ID, "numTracks", pls.SongCount, "elapsed", time.Since(start))
+	log.Debug(ctx, "Refreshed playlist", "playlist", pls.Name, "id", pls.ID, "numTracks", pls.SongCount, "elapsed", time.Since(start))
 	return true
 }
 
 // shouldRefreshSmartPlaylist determines if a smart playlist needs to be refreshed based on its type, last evaluated
 // time, and ownership.
-func (r *playlistRepository) shouldRefreshSmartPlaylist(pls *model.Playlist, usr *model.User) bool {
+func (r *playlistRepository) shouldRefreshSmartPlaylist(ctx context.Context, pls *model.Playlist, usr *model.User) bool {
 	if !pls.IsSmartPlaylist() {
 		return false
 	}
@@ -95,7 +96,7 @@ func (r *playlistRepository) shouldRefreshSmartPlaylist(pls *model.Playlist, usr
 		return false
 	}
 	if pls.OwnerID != usr.ID {
-		log.Trace(r.ctx, "Not refreshing smart playlist from other user", "playlist", pls.Name, "id", pls.ID)
+		log.Trace(ctx, "Not refreshing smart playlist from other user", "playlist", pls.Name, "id", pls.ID)
 		return false
 	}
 	return true
@@ -103,7 +104,7 @@ func (r *playlistRepository) shouldRefreshSmartPlaylist(pls *model.Playlist, usr
 
 // refreshChildPlaylists handles refreshing any child playlists that are referenced in the smart playlist criteria.
 // Returns false if child playlists could not be loaded (DB error), signaling the parent refresh should abort.
-func (r *playlistRepository) refreshChildPlaylists(pls *model.Playlist, rulesSQL smartPlaylistCriteria, visited map[string]struct{}) bool {
+func (r *playlistRepository) refreshChildPlaylists(ctx context.Context, pls *model.Playlist, rulesSQL smartPlaylistCriteria, visited map[string]struct{}) bool {
 	childPlaylistIds := rulesSQL.ChildPlaylistIds()
 	childPlaylistPaths := rulesSQL.ChildPlaylistPaths()
 	if len(childPlaylistIds) == 0 && len(childPlaylistPaths) == 0 {
@@ -119,9 +120,9 @@ func (r *playlistRepository) refreshChildPlaylists(pls *model.Playlist, rulesSQL
 		conditions = append(conditions, Eq{"playlist.path": lookupPaths})
 	}
 
-	childPlaylists, err := r.GetAll(model.QueryOptions{Filters: conditions})
+	childPlaylists, err := r.GetAll(ctx, model.QueryOptions{Filters: conditions})
 	if err != nil {
-		log.Error(r.ctx, "Error loading child playlists for smart playlist refresh", "playlist", pls.Name, "id", pls.ID, "childIds", childPlaylistIds, "childPaths", childPlaylistPaths, err)
+		log.Error(ctx, "Error loading child playlists for smart playlist refresh", "playlist", pls.Name, "id", pls.ID, "childIds", childPlaylistIds, "childPaths", childPlaylistPaths, err)
 		return false
 	}
 
@@ -131,58 +132,58 @@ func (r *playlistRepository) refreshChildPlaylists(pls *model.Playlist, rulesSQL
 		if childPlaylists[i].Path != "" {
 			found[norm.NFC.String(childPlaylists[i].Path)] = struct{}{}
 		}
-		r.refreshSmartPlaylistTree(&childPlaylists[i], visited)
+		r.refreshSmartPlaylistTree(ctx, &childPlaylists[i], visited)
 	}
 	for _, id := range childPlaylistIds {
 		if _, ok := found[id]; !ok {
-			log.Warn(r.ctx, "Referenced playlist is not accessible to smart playlist owner", "playlist", pls.Name, "id", pls.ID, "childId", id, "ownerId", pls.OwnerID)
+			log.Warn(ctx, "Referenced playlist is not accessible to smart playlist owner", "playlist", pls.Name, "id", pls.ID, "childId", id, "ownerId", pls.OwnerID)
 		}
 	}
 
 	for _, path := range childPlaylistPaths {
 		if _, ok := found[norm.NFC.String(path)]; !ok {
-			log.Warn(r.ctx, "Referenced playlist is not accessible to smart playlist owner", "playlist", pls.Name, "id", pls.ID, "path", path, "ownerId", pls.OwnerID)
+			log.Warn(ctx, "Referenced playlist is not accessible to smart playlist owner", "playlist", pls.Name, "id", pls.ID, "path", path, "ownerId", pls.OwnerID)
 		}
 	}
 	return true
 }
 
 // resolvePercentageLimit calculates the actual limit for a smart playlist criteria that uses a percentage-based limit.
-func (r *playlistRepository) resolvePercentageLimit(pls *model.Playlist, rulesSQL *smartPlaylistCriteria, userID string) error {
+func (r *playlistRepository) resolvePercentageLimit(ctx context.Context, pls *model.Playlist, rulesSQL *smartPlaylistCriteria, userID string) error {
 	if !rulesSQL.IsPercentageLimit() {
 		return nil
 	}
 
 	countSq := Select("count(*) as count").From("media_file")
 	countSq = rulesSQL.applyExpressionJoins(countSq, userID)
-	countSq = r.applyLibraryFilter(countSq, "media_file")
+	countSq = r.applyLibraryFilter(ctx, countSq, "media_file")
 
 	cond, err := rulesSQL.where()
 	if err != nil {
-		log.Error(r.ctx, "Error building smart playlist criteria", "playlist", pls.Name, "id", pls.ID, err)
+		log.Error(ctx, "Error building smart playlist criteria", "playlist", pls.Name, "id", pls.ID, err)
 		return err
 	}
 	countSq = countSq.Where(cond)
 
 	var res struct{ Count int64 }
-	if err = r.queryOne(countSq, &res); err != nil {
-		log.Error(r.ctx, "Error counting matching tracks for percentage limit", "playlist", pls.Name, "id", pls.ID, err)
+	if err = r.queryOne(ctx, countSq, &res); err != nil {
+		log.Error(ctx, "Error counting matching tracks for percentage limit", "playlist", pls.Name, "id", pls.ID, err)
 		return err
 	}
 
 	rulesSQL.ResolveLimit(res.Count)
-	log.Debug(r.ctx, "Resolved percentage limit", "playlist", pls.Name, "percent", rulesSQL.LimitPercent, "totalMatching", res.Count, "resolvedLimit", rulesSQL.Limit)
+	log.Debug(ctx, "Resolved percentage limit", "playlist", pls.Name, "percent", rulesSQL.LimitPercent, "totalMatching", res.Count, "resolvedLimit", rulesSQL.Limit)
 	return nil
 }
 
 // buildSmartPlaylistQuery constructs the SQL query to select media files matching the smart playlist criteria,
 // including the joins its fields require and library filtering.
-func (r *playlistRepository) buildSmartPlaylistQuery(pls *model.Playlist, rulesSQL smartPlaylistCriteria, userID string) SelectBuilder {
+func (r *playlistRepository) buildSmartPlaylistQuery(ctx context.Context, pls *model.Playlist, rulesSQL smartPlaylistCriteria, userID string) SelectBuilder {
 	orderBy := rulesSQL.orderBy()
 	sq := Select("row_number() over (order by "+orderBy+") as id", "'"+pls.ID+"' as playlist_id", "media_file.id as media_file_id").
 		From("media_file")
 	sq = rulesSQL.applyRequiredJoins(sq, userID)
-	sq = r.applyLibraryFilter(sq, "media_file")
+	sq = r.applyLibraryFilter(ctx, sq, "media_file")
 	return sq
 }
 
diff --git a/persistence/smart_playlist_repository_test.go b/persistence/smart_playlist_repository_test.go
index 33da0c1b7..4d4c5edb0 100644
--- a/persistence/smart_playlist_repository_test.go
+++ b/persistence/smart_playlist_repository_test.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"path/filepath"
 	"time"
 
@@ -18,11 +19,11 @@ import (
 
 var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 	var repo model.PlaylistRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
-		ctx := log.NewContext(GinkgoT().Context())
-		ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-		repo = NewPlaylistRepository(ctx, GetDBXBuilder())
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid", UserName: "userid", IsAdmin: true})
+		repo = NewPlaylistRepository(GetDBXBuilder())
 	})
 
 	Context("Smart Playlists", func() {
@@ -37,10 +38,10 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 		Context("valid rules", func() {
 			Specify("Put/Get", func() {
 				newPls := model.Playlist{Name: "Great!", OwnerID: "userid", Rules: rules}
-				Expect(repo.Put(&newPls)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+				Expect(repo.Put(ctx, &newPls)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, newPls.ID) })
 
-				savedPls, err := repo.Get(newPls.ID)
+				savedPls, err := repo.Get(ctx, newPls.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(savedPls.Rules).To(Equal(rules))
 			})
@@ -49,13 +50,13 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 		Context("after an evaluation", func() {
 			It("stamps updated_at and evaluated_at with the same instant", func() {
 				newPls := model.Playlist{Name: "Evaluated", OwnerID: "userid", Rules: rules}
-				Expect(repo.Put(&newPls)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+				Expect(repo.Put(ctx, &newPls)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, newPls.ID) })
 
-				refreshed, err := repo.GetWithTracks(newPls.ID, true, false)
+				refreshed, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 				Expect(err).ToNot(HaveOccurred())
 
-				stored, err := repo.Get(newPls.ID)
+				stored, err := repo.Get(ctx, newPls.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(stored.EvaluatedAt).ToNot(BeNil())
 				Expect(stored.UpdatedAt).To(BeTemporally("==", *stored.EvaluatedAt))
@@ -72,7 +73,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 					},
 				}
 				newPls := model.Playlist{Name: "Great!", OwnerID: "userid", Rules: rules}
-				Expect(repo.Put(&newPls)).To(MatchError(ContainSubstring("invalid criteria expression")))
+				Expect(repo.Put(ctx, &newPls)).To(MatchError(ContainSubstring("invalid criteria expression")))
 			})
 		})
 
@@ -86,14 +87,14 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 					},
 				}
 				pls := model.Playlist{Name: "Smart", OwnerID: "userid", Rules: rules, Path: "/music/smart.nsp", Sync: true}
-				Expect(repo.Put(&pls)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(pls.ID) })
+				Expect(repo.Put(ctx, &pls)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, pls.ID) })
 
-				evaluated, err := repo.GetWithTracks(pls.ID, true, false)
+				evaluated, err := repo.GetWithTracks(ctx, pls.ID, true, false)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(evaluated.SongCount).To(BeNumerically(">", 0))
 
-				stored, err := repo.Get(pls.ID)
+				stored, err := repo.Get(ctx, pls.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(stored.SongCount).To(Equal(evaluated.SongCount))
 
@@ -101,9 +102,9 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 					ID: pls.ID, Name: pls.Name, OwnerID: "userid", Rules: rules,
 					Path: pls.Path, Sync: true,
 				}
-				Expect(repo.Put(&reimported)).To(Succeed())
+				Expect(repo.Put(ctx, &reimported)).To(Succeed())
 
-				afterImport, err := repo.Get(pls.ID)
+				afterImport, err := repo.Get(ctx, pls.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(afterImport.SongCount).To(Equal(stored.SongCount))
 				Expect(afterImport.Duration).To(Equal(stored.Duration))
@@ -126,8 +127,8 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 						},
 					}
 					nestedPls := model.Playlist{Name: "Nested [ID]", OwnerID: "userid", Public: true, Rules: childRules}
-					Expect(repo.Put(&nestedPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(nestedPls.ID) })
+					Expect(repo.Put(ctx, &nestedPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(ctx, nestedPls.ID) })
 
 					childRules = &criteria.Criteria{
 						Expression: criteria.All{
@@ -135,8 +136,8 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 						},
 					}
 					nestedPathPls := model.Playlist{Name: "Nested [Path]", OwnerID: "userid", Path: "test.nsp", Public: true, Rules: childRules}
-					Expect(repo.Put(&nestedPathPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(nestedPathPls.ID) })
+					Expect(repo.Put(ctx, &nestedPathPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(ctx, nestedPathPls.ID) })
 
 					parentPls := model.Playlist{Name: "Parent", OwnerID: "userid", Rules: &criteria.Criteria{
 						Expression: criteria.Any{
@@ -144,16 +145,16 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 							criteria.InPlaylist{"path": nestedPathPls.Path},
 						},
 					}}
-					Expect(repo.Put(&parentPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(parentPls.ID) })
+					Expect(repo.Put(ctx, &parentPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(ctx, parentPls.ID) })
 
 					// Nested playlist has not been evaluated yet
-					nestedPlsRead, err := repo.Get(nestedPls.ID)
+					nestedPlsRead, err := repo.Get(ctx, nestedPls.ID)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(nestedPlsRead.EvaluatedAt).To(BeNil())
 
 					// Getting parent with refresh should recursively refresh the nested playlist
-					pls, err := repo.GetWithTracks(parentPls.ID, true, false)
+					pls, err := repo.GetWithTracks(ctx, parentPls.ID, true, false)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(pls.EvaluatedAt).ToNot(BeNil())
 					Expect(*pls.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
@@ -163,12 +164,12 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 					Expect(pls.Tracks[0].MediaFileID).To(Equal(songDayInALife.ID))
 
 					// Nested playlists should now have been refreshed (EvaluatedAt set)
-					nestedPlsAfterParentGet, err := repo.Get(nestedPls.ID)
+					nestedPlsAfterParentGet, err := repo.Get(ctx, nestedPls.ID)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(nestedPlsAfterParentGet.EvaluatedAt).ToNot(BeNil())
 					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
 
-					nestedPlsAfterParentGet, err = repo.Get(nestedPathPls.ID)
+					nestedPlsAfterParentGet, err = repo.Get(ctx, nestedPathPls.ID)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(nestedPlsAfterParentGet.EvaluatedAt).ToNot(BeNil())
 					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
@@ -181,19 +182,19 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				plsA := model.Playlist{Name: "Cycle A", OwnerID: "userid", Public: true, Rules: &criteria.Criteria{
 					Expression: criteria.All{criteria.Contains{"title": "Day"}},
 				}}
-				Expect(repo.Put(&plsA)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(plsA.ID) })
+				Expect(repo.Put(ctx, &plsA)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, plsA.ID) })
 
 				plsB := model.Playlist{Name: "Cycle B", OwnerID: "userid", Public: true, Rules: &criteria.Criteria{
 					Expression: criteria.All{criteria.InPlaylist{"id": plsA.ID}},
 				}}
-				Expect(repo.Put(&plsB)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(plsB.ID) })
+				Expect(repo.Put(ctx, &plsB)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, plsB.ID) })
 
 				plsA.Rules = &criteria.Criteria{Expression: criteria.All{criteria.InPlaylist{"id": plsB.ID}}}
-				Expect(repo.Put(&plsA)).To(Succeed())
+				Expect(repo.Put(ctx, &plsA)).To(Succeed())
 
-				_, err := repo.GetWithTracks(plsA.ID, true, false)
+				_, err := repo.GetWithTracks(ctx, plsA.ID, true, false)
 				Expect(err).ToNot(HaveOccurred())
 			})
 
@@ -203,19 +204,19 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				bystander := model.Playlist{Name: "Bystander", OwnerID: "userid", Public: true, Rules: &criteria.Criteria{
 					Expression: criteria.All{criteria.Contains{"title": "Day"}},
 				}}
-				Expect(repo.Put(&bystander)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(bystander.ID) })
+				Expect(repo.Put(ctx, &bystander)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, bystander.ID) })
 
 				parent := model.Playlist{Name: "Empty Path", OwnerID: "userid", Public: true, Rules: &criteria.Criteria{
 					Expression: criteria.All{criteria.InPlaylist{"path": ""}},
 				}}
-				Expect(repo.Put(&parent)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(parent.ID) })
+				Expect(repo.Put(ctx, &parent)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, parent.ID) })
 
-				_, err := repo.GetWithTracks(parent.ID, true, false)
+				_, err := repo.GetWithTracks(ctx, parent.ID, true, false)
 				Expect(err).ToNot(HaveOccurred())
 
-				reloaded, err := repo.Get(bystander.ID)
+				reloaded, err := repo.Get(ctx, bystander.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(reloaded.EvaluatedAt).To(BeNil())
 			})
@@ -226,16 +227,16 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				child := model.Playlist{Name: "NFD Child", OwnerID: "userid", Public: true, Path: filepath.FromSlash("/mu\u0301sica/child.nsp"), Rules: &criteria.Criteria{
 					Expression: criteria.All{criteria.Contains{"title": "Day"}},
 				}}
-				Expect(repo.Put(&child)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(child.ID) })
+				Expect(repo.Put(ctx, &child)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, child.ID) })
 
 				parent := model.Playlist{Name: "NFC Parent", OwnerID: "userid", Rules: &criteria.Criteria{
 					Expression: criteria.All{criteria.InPlaylist{"path": "/m\u00fasica/child.nsp"}},
 				}}
-				Expect(repo.Put(&parent)).To(Succeed())
-				DeferCleanup(func() { _ = repo.Delete(parent.ID) })
+				Expect(repo.Put(ctx, &parent)).To(Succeed())
+				DeferCleanup(func() { _ = repo.Delete(ctx, parent.ID) })
 
-				pls, err := repo.GetWithTracks(parent.ID, true, false)
+				pls, err := repo.GetWithTracks(ctx, parent.ID, true, false)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(pls.Tracks).To(HaveLen(1))
 				Expect(pls.Tracks[0].MediaFileID).To(Equal(songDayInALife.ID))
@@ -252,8 +253,8 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 						},
 					}
 					nestedPls := model.Playlist{Name: "Nested", OwnerID: "userid", Public: true, Rules: childRules, EvaluatedAt: &childEvaluatedAt}
-					Expect(repo.Put(&nestedPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(nestedPls.ID) })
+					Expect(repo.Put(ctx, &nestedPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(ctx, nestedPls.ID) })
 
 					// Parent has no EvaluatedAt, so it WILL refresh, but the child should not
 					parentPls := model.Playlist{Name: "Parent", OwnerID: "userid", Rules: &criteria.Criteria{
@@ -261,14 +262,14 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 							criteria.InPlaylist{"id": nestedPls.ID},
 						},
 					}}
-					Expect(repo.Put(&parentPls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(parentPls.ID) })
+					Expect(repo.Put(ctx, &parentPls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(ctx, parentPls.ID) })
 
-					nestedPlsRead, err := repo.Get(nestedPls.ID)
+					nestedPlsRead, err := repo.Get(ctx, nestedPls.ID)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Getting parent with refresh should NOT recursively refresh the nested playlist
-					parent, err := repo.GetWithTracks(parentPls.ID, true, false)
+					parent, err := repo.GetWithTracks(ctx, parentPls.ID, true, false)
 					Expect(err).ToNot(HaveOccurred())
 
 					// Parent should have been refreshed (its EvaluatedAt was nil)
@@ -276,7 +277,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 					Expect(*parent.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
 
 					// Nested playlist should NOT have been refreshed (still within delay window)
-					nestedPlsAfterParentGet, err := repo.Get(nestedPls.ID)
+					nestedPlsAfterParentGet, err := repo.Get(ctx, nestedPls.ID)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(BeTemporally("~", childEvaluatedAt, time.Second))
 					Expect(*nestedPlsAfterParentGet.EvaluatedAt).To(Equal(*nestedPlsRead.EvaluatedAt))
@@ -297,10 +298,10 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 						RefreshDelay: 24 * time.Hour,
 					}
 					pls := model.Playlist{Name: "Frozen Daily", OwnerID: "userid", Rules: rules, EvaluatedAt: &evaluatedAt}
-					Expect(repo.Put(&pls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(pls.ID) })
+					Expect(repo.Put(ctx, &pls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(ctx, pls.ID) })
 
-					got, err := repo.GetWithTracks(pls.ID, true, false)
+					got, err := repo.GetWithTracks(ctx, pls.ID, true, false)
 					Expect(err).ToNot(HaveOccurred())
 					// Not re-evaluated: EvaluatedAt unchanged, no tracks materialized
 					Expect(*got.EvaluatedAt).To(BeTemporally("~", evaluatedAt, time.Second))
@@ -316,10 +317,10 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 						RefreshDelay: 5 * time.Minute,
 					}
 					pls := model.Playlist{Name: "Fast Refresh", OwnerID: "userid", Rules: rules, EvaluatedAt: &evaluatedAt}
-					Expect(repo.Put(&pls)).To(Succeed())
-					DeferCleanup(func() { _ = repo.Delete(pls.ID) })
+					Expect(repo.Put(ctx, &pls)).To(Succeed())
+					DeferCleanup(func() { _ = repo.Delete(ctx, pls.ID) })
 
-					got, err := repo.GetWithTracks(pls.ID, true, false)
+					got, err := repo.GetWithTracks(ctx, pls.ID, true, false)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(*got.EvaluatedAt).To(BeTemporally("~", time.Now(), 2*time.Second))
 					Expect(got.Tracks).To(HaveLen(1))
@@ -334,7 +335,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 
 		AfterEach(func() {
 			if testPlaylistID != "" {
-				Expect(repo.Delete(testPlaylistID)).To(BeNil())
+				Expect(repo.Delete(ctx, testPlaylistID)).To(BeNil())
 				testPlaylistID = ""
 			}
 		})
@@ -344,12 +345,12 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 			newPls := model.Playlist{Name: "Multi-Disc Test", OwnerID: "userid"}
 			// Add tracks in intentionally scrambled order
 			newPls.AddMediaFilesByID([]string{"2001", "2002", "2003", "2004"})
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			By("retrieving tracks sorted by album")
-			tracksRepo := repo.Tracks(newPls.ID, false)
-			tracks, err := tracksRepo.GetAll(model.QueryOptions{Sort: "album", Order: "asc"})
+			tracksRepo := repo.Tracks(ctx, newPls.ID, false)
+			tracks, err := tracksRepo.GetAll(ctx, model.QueryOptions{Sort: "album", Order: "asc"})
 			Expect(err).ToNot(HaveOccurred())
 
 			By("verifying tracks are sorted by disc number then track number")
@@ -367,7 +368,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 
 		AfterEach(func() {
 			if testPlaylistID != "" {
-				_ = repo.Delete(testPlaylistID)
+				_ = repo.Delete(ctx, testPlaylistID)
 				testPlaylistID = ""
 			}
 		})
@@ -381,11 +382,11 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			newPls := model.Playlist{Name: "Starred Album Songs", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			trackIDs := make([]string, len(pls.Tracks))
@@ -404,11 +405,11 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			newPls := model.Playlist{Name: "Starred Artist Songs", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			trackIDs := make([]string, len(pls.Tracks))
@@ -429,11 +430,11 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			newPls := model.Playlist{Name: "Combined Album+Artist", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			trackIDs := make([]string, len(pls.Tracks))
@@ -451,11 +452,11 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			newPls := model.Playlist{Name: "No Match", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(pls.Tracks).To(BeEmpty())
@@ -471,11 +472,11 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			newPls := model.Playlist{Name: "String Loved Nested", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			trackIDs := make([]string, len(pls.Tracks))
@@ -495,8 +496,8 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			boolPls := model.Playlist{Name: "Bool Loved", OwnerID: "userid", Rules: boolRules}
-			Expect(repo.Put(&boolPls)).To(Succeed())
-			DeferCleanup(func() { _ = repo.Delete(boolPls.ID) })
+			Expect(repo.Put(ctx, &boolPls)).To(Succeed())
+			DeferCleanup(func() { _ = repo.Delete(ctx, boolPls.ID) })
 
 			stringRules := &criteria.Criteria{
 				Expression: criteria.All{
@@ -506,13 +507,13 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			stringPls := model.Playlist{Name: "String Loved", OwnerID: "userid", Rules: stringRules}
-			Expect(repo.Put(&stringPls)).To(Succeed())
+			Expect(repo.Put(ctx, &stringPls)).To(Succeed())
 			testPlaylistID = stringPls.ID
 
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second
-			boolResult, err := repo.GetWithTracks(boolPls.ID, true, false)
+			boolResult, err := repo.GetWithTracks(ctx, boolPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
-			stringResult, err := repo.GetWithTracks(stringPls.ID, true, false)
+			stringResult, err := repo.GetWithTracks(ctx, stringPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			boolIDs := make([]string, len(boolResult.Tracks))
@@ -535,10 +536,10 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 
 		trackIDsOf := func(rules *criteria.Criteria) []string {
 			newPls := model.Playlist{Name: "Album Aggregates", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
-			DeferCleanup(func() { _ = repo.Delete(newPls.ID) })
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
+			DeferCleanup(func() { _ = repo.Delete(ctx, newPls.ID) })
 
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 			return slice.Map(pls.Tracks, func(t model.PlaylistTrack) string { return t.MediaFileID })
 		}
@@ -569,7 +570,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 		BeforeEach(func() {
 			ctx := log.NewContext(GinkgoT().Context())
 			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			mfRepo = NewMediaFileRepository(ctx, GetDBXBuilder())
+			mfRepo = NewMediaFileRepository(GetDBXBuilder())
 
 			// Register 'grouping' as a valid tag for smart playlists
 			criteria.AddTagNames([]string{"grouping"})
@@ -590,7 +591,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				LibraryID:    1,
 				Lyrics:       "[]",
 			}
-			Expect(mfRepo.Put(&songWithGrouping)).To(Succeed())
+			Expect(mfRepo.Put(ctx, &songWithGrouping)).To(Succeed())
 
 			// Create a song without the grouping tag
 			songWithoutGrouping = model.MediaFile{
@@ -606,12 +607,12 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				LibraryID:    1,
 				Lyrics:       "[]",
 			}
-			Expect(mfRepo.Put(&songWithoutGrouping)).To(Succeed())
+			Expect(mfRepo.Put(ctx, &songWithoutGrouping)).To(Succeed())
 		})
 
 		AfterEach(func() {
 			if testPlaylistID != "" {
-				_ = repo.Delete(testPlaylistID)
+				_ = repo.Delete(ctx, testPlaylistID)
 				testPlaylistID = ""
 			}
 			// Clean up test media files
@@ -629,12 +630,12 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			newPls := model.Playlist{Name: "Tracks with Grouping", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			By("refreshing the smart playlist")
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			By("verifying only the track with grouping tag is matched")
@@ -650,12 +651,12 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			newPls := model.Playlist{Name: "Tracks without Grouping", OwnerID: "userid", Rules: rules}
-			Expect(repo.Put(&newPls)).To(Succeed())
+			Expect(repo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			By("refreshing the smart playlist")
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
-			pls, err := repo.GetWithTracks(newPls.ID, true, false)
+			pls, err := repo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			By("verifying the track with grouping is NOT in the playlist")
@@ -705,7 +706,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 			// Create test media files in each library
 			ctx := log.NewContext(GinkgoT().Context())
 			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "userid", IsAdmin: true})
-			mfRepo = NewMediaFileRepository(ctx, db)
+			mfRepo = NewMediaFileRepository(db)
 
 			// Song in library 1 (accessible by restricted user)
 			songLib1 := model.MediaFile{
@@ -721,7 +722,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				Tags:         model.Tags{},
 				Lyrics:       "[]",
 			}
-			Expect(mfRepo.Put(&songLib1)).To(Succeed())
+			Expect(mfRepo.Put(ctx, &songLib1)).To(Succeed())
 
 			// Song in library 2 (NOT accessible by restricted user)
 			songLib2 := model.MediaFile{
@@ -737,13 +738,13 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				Tags:         model.Tags{},
 				Lyrics:       "[]",
 			}
-			Expect(mfRepo.Put(&songLib2)).To(Succeed())
+			Expect(mfRepo.Put(ctx, &songLib2)).To(Succeed())
 		})
 
 		AfterEach(func() {
 			db := GetDBXBuilder()
 			if testPlaylistID != "" {
-				_ = repo.Delete(testPlaylistID)
+				_ = repo.Delete(ctx, testPlaylistID)
 				testPlaylistID = ""
 			}
 			// Clean up test data
@@ -761,7 +762,7 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 			// Create the smart playlist as the restricted user
 			restrictedUser := model.User{ID: restrictedUserID, UserName: restrictedUserID, IsAdmin: false}
 			ctx = request.WithUser(ctx, restrictedUser)
-			restrictedRepo := NewPlaylistRepository(ctx, db)
+			restrictedRepo := NewPlaylistRepository(db)
 
 			// Create a smart playlist that matches all songs
 			rules := &criteria.Criteria{
@@ -770,12 +771,12 @@ var _ = Describe("PlaylistRepository - Smart Playlists", func() {
 				},
 			}
 			newPls := model.Playlist{Name: "All Songs", OwnerID: restrictedUserID, Rules: rules}
-			Expect(restrictedRepo.Put(&newPls)).To(Succeed())
+			Expect(restrictedRepo.Put(ctx, &newPls)).To(Succeed())
 			testPlaylistID = newPls.ID
 
 			By("refreshing the smart playlist")
 			conf.Server.SmartPlaylistRefreshDelay = -1 * time.Second // Force refresh
-			pls, err := restrictedRepo.GetWithTracks(newPls.ID, true, false)
+			pls, err := restrictedRepo.GetWithTracks(ctx, newPls.ID, true, false)
 			Expect(err).ToNot(HaveOccurred())
 
 			By("verifying only the track from library 1 is in the playlist")
diff --git a/persistence/sort_index_coverage_test.go b/persistence/sort_index_coverage_test.go
index b5dea231d..138cb32c8 100644
--- a/persistence/sort_index_coverage_test.go
+++ b/persistence/sort_index_coverage_test.go
@@ -52,7 +52,7 @@ var _ = Describe("Sort index coverage", func() {
 		{
 			table: "media_file",
 			newRepo: func(ctx context.Context) *sqlRepository {
-				return &NewMediaFileRepository(ctx, GetDBXBuilder()).(*mediaFileRepository).sqlRepository
+				return &NewMediaFileRepository(GetDBXBuilder()).(*mediaFileRepository).sqlRepository
 			},
 			exceptions: map[string]string{
 				"random":     "not a column sort",
@@ -67,7 +67,7 @@ var _ = Describe("Sort index coverage", func() {
 		{
 			table: "album",
 			newRepo: func(ctx context.Context) *sqlRepository {
-				return &NewAlbumRepository(ctx, GetDBXBuilder()).(*albumRepository).sqlRepository
+				return &NewAlbumRepository(GetDBXBuilder()).(*albumRepository).sqlRepository
 			},
 			exceptions: map[string]string{
 				"random":     "not a column sort",
@@ -79,7 +79,7 @@ var _ = Describe("Sort index coverage", func() {
 		{
 			table: "artist",
 			newRepo: func(ctx context.Context) *sqlRepository {
-				return &NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository).sqlRepository
+				return &NewArtistRepository(GetDBXBuilder()).(*artistRepository).sqlRepository
 			},
 			exceptions: map[string]string{ //nolint:gosec // G101 false positive, same as the artist sortMappings
 				"starred_at":             "sorts on annotation join columns",
diff --git a/persistence/sql_annotations.go b/persistence/sql_annotations.go
index 27445b886..51c7dc146 100644
--- a/persistence/sql_annotations.go
+++ b/persistence/sql_annotations.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"database/sql"
 	"errors"
 	"fmt"
@@ -59,8 +60,8 @@ func filtersNeedAnnotation(query SelectBuilder) bool {
 	return annotationColumnRE().MatchString(sql)
 }
 
-func (r sqlRepository) withAnnotation(query SelectBuilder, idField string) SelectBuilder {
-	userID := loggedUser(r.ctx).ID
+func (r sqlRepository) withAnnotation(ctx context.Context, query SelectBuilder, idField string) SelectBuilder {
+	userID := loggedUser(ctx).ID
 	if userID == invalidUserId {
 		return query.Columns(fmt.Sprintf("%s.average_rating", r.tableName))
 	}
@@ -102,8 +103,8 @@ func annotationBoolFilter(field string) func(string, any) Sqlizer {
 	}
 }
 
-func (r sqlRepository) annId(itemID ...string) And {
-	userID := loggedUser(r.ctx).ID
+func (r sqlRepository) annId(ctx context.Context, itemID ...string) And {
+	userID := loggedUser(ctx).ID
 	return And{
 		Eq{annotationTable + ".user_id": userID},
 		Eq{annotationTable + ".item_type": r.tableName},
@@ -111,20 +112,20 @@ func (r sqlRepository) annId(itemID ...string) And {
 	}
 }
 
-func (r sqlRepository) annUpsert(values map[string]any, itemIDs ...string) error {
-	upd := Update(annotationTable).Where(r.annId(itemIDs...))
+func (r sqlRepository) annUpsert(ctx context.Context, values map[string]any, itemIDs ...string) error {
+	upd := Update(annotationTable).Where(r.annId(ctx, itemIDs...))
 	for f, v := range values {
 		upd = upd.Set(f, v)
 	}
-	c, err := r.executeSQL(upd)
+	c, err := r.executeSQL(ctx, upd)
 	if c == 0 || errors.Is(err, sql.ErrNoRows) {
-		userID := loggedUser(r.ctx).ID
+		userID := loggedUser(ctx).ID
 		for _, itemID := range itemIDs {
 			values["user_id"] = userID
 			values["item_type"] = r.tableName
 			values["item_id"] = itemID
 			ins := Insert(annotationTable).SetMap(values)
-			_, err = r.executeSQL(ins)
+			_, err = r.executeSQL(ctx, ins)
 			if err != nil {
 				return err
 			}
@@ -133,39 +134,39 @@ func (r sqlRepository) annUpsert(values map[string]any, itemIDs ...string) error
 	return err
 }
 
-func (r sqlRepository) SetStar(starred bool, ids ...string) error {
+func (r sqlRepository) SetStar(ctx context.Context, starred bool, ids ...string) error {
 	starredAt := time.Now()
-	return r.annUpsert(map[string]any{"starred": starred, "starred_at": starredAt}, ids...)
+	return r.annUpsert(ctx, map[string]any{"starred": starred, "starred_at": starredAt}, ids...)
 }
 
-func (r sqlRepository) SetRating(rating int, itemID string) error {
+func (r sqlRepository) SetRating(ctx context.Context, rating int, itemID string) error {
 	ratedAt := time.Now()
-	err := r.annUpsert(map[string]any{"rating": rating, "rated_at": ratedAt}, itemID)
+	err := r.annUpsert(ctx, map[string]any{"rating": rating, "rated_at": ratedAt}, itemID)
 	if err != nil {
 		return err
 	}
-	return r.updateAvgRating(itemID)
+	return r.updateAvgRating(ctx, itemID)
 }
 
-func (r sqlRepository) updateAvgRating(itemID string) error {
+func (r sqlRepository) updateAvgRating(ctx context.Context, itemID string) error {
 	upd := Update(r.tableName).
 		Where(Eq{"id": itemID}).
 		Set("average_rating", Expr(
 			"coalesce((select round(avg(rating), 2) from annotation where item_id = ? and item_type = ? and rating > 0), 0)",
 			itemID, r.tableName,
 		))
-	_, err := r.executeSQL(upd)
+	_, err := r.executeSQL(ctx, upd)
 	return err
 }
 
-func (r sqlRepository) IncPlayCount(itemID string, ts time.Time) error {
-	upd := Update(annotationTable).Where(r.annId(itemID)).
+func (r sqlRepository) IncPlayCount(ctx context.Context, itemID string, ts time.Time) error {
+	upd := Update(annotationTable).Where(r.annId(ctx, itemID)).
 		Set("play_count", Expr("play_count+1")).
 		Set("play_date", Expr("max(ifnull(play_date,''),?)", ts))
-	c, err := r.executeSQL(upd)
+	c, err := r.executeSQL(ctx, upd)
 
 	if c == 0 || errors.Is(err, sql.ErrNoRows) {
-		userID := loggedUser(r.ctx).ID
+		userID := loggedUser(ctx).ID
 		values := map[string]any{}
 		values["user_id"] = userID
 		values["item_type"] = r.tableName
@@ -173,7 +174,7 @@ func (r sqlRepository) IncPlayCount(itemID string, ts time.Time) error {
 		values["play_count"] = 1
 		values["play_date"] = ts
 		ins := Insert(annotationTable).SetMap(values)
-		_, err = r.executeSQL(ins)
+		_, err = r.executeSQL(ctx, ins)
 		if err != nil {
 			return err
 		}
@@ -181,28 +182,28 @@ func (r sqlRepository) IncPlayCount(itemID string, ts time.Time) error {
 	return err
 }
 
-func (r sqlRepository) ReassignAnnotation(prevID string, newID string) error {
+func (r sqlRepository) ReassignAnnotation(ctx context.Context, prevID string, newID string) error {
 	if prevID == newID || prevID == "" || newID == "" {
 		return nil
 	}
 	// OR IGNORE keeps newID's own row where a user annotated both, instead of aborting the whole statement
 	upd := Expr("update or ignore "+annotationTable+" set item_id = ? where item_type = ? and item_id = ?",
 		newID, r.tableName, prevID)
-	if _, err := r.executeSQL(upd); err != nil {
+	if _, err := r.executeSQL(ctx, upd); err != nil {
 		return err
 	}
 	// The moved rows change newID's rating population, so its cached average no longer matches
-	return r.updateAvgRating(newID)
+	return r.updateAvgRating(ctx, newID)
 }
 
-func (r sqlRepository) cleanAnnotations() error {
+func (r sqlRepository) cleanAnnotations(ctx context.Context) error {
 	del := Delete(annotationTable).Where(Eq{"item_type": r.tableName}).Where("item_id not in (select id from " + r.tableName + ")")
-	c, err := r.executeSQL(del)
+	c, err := r.executeSQL(ctx, del)
 	if err != nil {
 		return fmt.Errorf("error cleaning up %s annotations: %w", r.tableName, err)
 	}
 	if c > 0 {
-		log.Debug(r.ctx, "Clean-up annotations", "table", r.tableName, "totalDeleted", c)
+		log.Debug(ctx, "Clean-up annotations", "table", r.tableName, "totalDeleted", c)
 	}
 	return nil
 }
diff --git a/persistence/sql_annotations_test.go b/persistence/sql_annotations_test.go
index 79ad3c152..ec28c610a 100644
--- a/persistence/sql_annotations_test.go
+++ b/persistence/sql_annotations_test.go
@@ -15,19 +15,20 @@ var _ = Describe("Annotation Filters", func() {
 	var (
 		albumRepo              *albumRepository
 		albumWithoutAnnotation model.Album
+		ctx                    context.Context
 	)
 
 	BeforeEach(func() {
-		ctx := request.WithUser(context.Background(), model.User{ID: "userid", UserName: "johndoe"})
-		albumRepo = NewAlbumRepository(ctx, GetDBXBuilder()).(*albumRepository)
+		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "userid", UserName: "johndoe"})
+		albumRepo = NewAlbumRepository(GetDBXBuilder()).(*albumRepository)
 
 		// Create album without any annotation (no star, no rating)
 		albumWithoutAnnotation = model.Album{ID: "no-annotation-album", Name: "No Annotation", LibraryID: 1}
-		Expect(albumRepo.Put(&albumWithoutAnnotation)).To(Succeed())
+		Expect(albumRepo.Put(ctx, &albumWithoutAnnotation)).To(Succeed())
 	})
 
 	AfterEach(func() {
-		_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": albumWithoutAnnotation.ID}))
+		_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": albumWithoutAnnotation.ID}))
 	})
 
 	Describe("ReassignAnnotation", func() {
@@ -36,42 +37,42 @@ var _ = Describe("Annotation Filters", func() {
 		BeforeEach(func() {
 			prev = model.Album{ID: "reassign-prev", Name: "Prev", LibraryID: 1}
 			next = model.Album{ID: "reassign-next", Name: "Next", LibraryID: 1}
-			Expect(albumRepo.Put(&prev)).To(Succeed())
-			Expect(albumRepo.Put(&next)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &prev)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &next)).To(Succeed())
 		})
 
 		AfterEach(func() {
-			_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
-			_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": []string{prev.ID, next.ID}}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": []string{prev.ID, next.ID}}))
+			_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": []string{prev.ID, next.ID}}))
 		})
 
 		It("moves the annotation when the new item has none", func() {
-			Expect(albumRepo.SetRating(4, prev.ID)).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 4, prev.ID)).To(Succeed())
 
-			Expect(albumRepo.ReassignAnnotation(prev.ID, next.ID)).To(Succeed())
+			Expect(albumRepo.ReassignAnnotation(ctx, prev.ID, next.ID)).To(Succeed())
 
-			got, err := albumRepo.Get(next.ID)
+			got, err := albumRepo.Get(ctx, next.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Rating).To(Equal(4))
 		})
 
 		It("recomputes the new item's cached average rating", func() {
-			Expect(albumRepo.SetRating(4, prev.ID)).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 4, prev.ID)).To(Succeed())
 
-			Expect(albumRepo.ReassignAnnotation(prev.ID, next.ID)).To(Succeed())
+			Expect(albumRepo.ReassignAnnotation(ctx, prev.ID, next.ID)).To(Succeed())
 
-			got, err := albumRepo.Get(next.ID)
+			got, err := albumRepo.Get(ctx, next.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.AverageRating).To(Equal(4.0))
 		})
 
 		It("keeps the new item's annotation when both exist", func() {
-			Expect(albumRepo.SetRating(4, prev.ID)).To(Succeed())
-			Expect(albumRepo.SetRating(2, next.ID)).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 4, prev.ID)).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 2, next.ID)).To(Succeed())
 
-			Expect(albumRepo.ReassignAnnotation(prev.ID, next.ID)).To(Succeed())
+			Expect(albumRepo.ReassignAnnotation(ctx, prev.ID, next.ID)).To(Succeed())
 
-			got, err := albumRepo.Get(next.ID)
+			got, err := albumRepo.Get(ctx, next.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.Rating).To(Equal(2))
 		})
@@ -100,7 +101,7 @@ var _ = Describe("Annotation Filters", func() {
 
 	Describe("starredFilter", func() {
 		It("false includes items without annotations", func() {
-			albums, err := albumRepo.GetAll(model.QueryOptions{
+			albums, err := albumRepo.GetAll(ctx, model.QueryOptions{
 				Filters: annotationBoolFilter("starred")("starred", "false"),
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -116,7 +117,7 @@ var _ = Describe("Annotation Filters", func() {
 		})
 
 		It("true excludes items without annotations", func() {
-			albums, err := albumRepo.GetAll(model.QueryOptions{
+			albums, err := albumRepo.GetAll(ctx, model.QueryOptions{
 				Filters: annotationBoolFilter("starred")("starred", "true"),
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -129,7 +130,7 @@ var _ = Describe("Annotation Filters", func() {
 
 	Describe("hasRatingFilter", func() {
 		It("false includes items without annotations", func() {
-			albums, err := albumRepo.GetAll(model.QueryOptions{
+			albums, err := albumRepo.GetAll(ctx, model.QueryOptions{
 				Filters: annotationBoolFilter("rating")("rating", "false"),
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -145,7 +146,7 @@ var _ = Describe("Annotation Filters", func() {
 		})
 
 		It("true excludes items without annotations", func() {
-			albums, err := albumRepo.GetAll(model.QueryOptions{
+			albums, err := albumRepo.GetAll(ctx, model.QueryOptions{
 				Filters: annotationBoolFilter("rating")("rating", "true"),
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -158,14 +159,14 @@ var _ = Describe("Annotation Filters", func() {
 		It("true includes items with rating > 0", func() {
 			// Create album with rating 1
 			ratedAlbum := model.Album{ID: "rated-album", Name: "Rated Album", LibraryID: 1}
-			Expect(albumRepo.Put(&ratedAlbum)).To(Succeed())
-			Expect(albumRepo.SetRating(1, ratedAlbum.ID)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &ratedAlbum)).To(Succeed())
+			Expect(albumRepo.SetRating(ctx, 1, ratedAlbum.ID)).To(Succeed())
 			defer func() {
-				_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": ratedAlbum.ID}))
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": ratedAlbum.ID}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": ratedAlbum.ID}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": ratedAlbum.ID}))
 			}()
 
-			albums, err := albumRepo.GetAll(model.QueryOptions{
+			albums, err := albumRepo.GetAll(ctx, model.QueryOptions{
 				Filters: annotationBoolFilter("rating")("rating", "true"),
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -182,11 +183,11 @@ var _ = Describe("Annotation Filters", func() {
 	})
 
 	It("ignores invalid filter values (not strings)", func() {
-		res, err := albumRepo.ReadAll(rest.QueryOptions{
+		res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
 			Filters: map[string]any{"starred": 123},
 		})
 		Expect(err).ToNot(HaveOccurred())
-		albums := res.(model.Albums)
+		albums := res
 
 		var found bool
 		for _, a := range albums {
@@ -254,11 +255,11 @@ var _ = Describe("Annotation Filters", func() {
 
 	Describe("CountAll annotation-join gating", func() {
 		It("counts all items unfiltered (join dropped)", func() {
-			total, err := albumRepo.CountAll()
+			total, err := albumRepo.CountAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(total).To(BeNumerically(">=", int64(1)))
 
-			filtered, err := albumRepo.CountAll(model.QueryOptions{
+			filtered, err := albumRepo.CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.id": albumWithoutAnnotation.ID},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -267,16 +268,16 @@ var _ = Describe("Annotation Filters", func() {
 
 		It("counts starred items correctly (named annotation filter keeps the join)", func() {
 			starredAlbum := model.Album{ID: "counted-starred-album", Name: "Counted Starred", LibraryID: 1}
-			Expect(albumRepo.Put(&starredAlbum)).To(Succeed())
-			Expect(albumRepo.SetStar(true, starredAlbum.ID)).To(Succeed())
+			Expect(albumRepo.Put(ctx, &starredAlbum)).To(Succeed())
+			Expect(albumRepo.SetStar(ctx, true, starredAlbum.ID)).To(Succeed())
 			defer func() {
-				_, _ = albumRepo.executeSQL(squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": starredAlbum.ID}))
-				_, _ = albumRepo.executeSQL(squirrel.Delete("album").Where(squirrel.Eq{"id": starredAlbum.ID}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": starredAlbum.ID}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": starredAlbum.ID}))
 			}()
 
 			// Exactly two albums are starred for this user: the one created above and
 			// albumRadioactivity (id 103) from the seed data.
-			count, err := albumRepo.CountAll(model.QueryOptions{
+			count, err := albumRepo.CountAll(ctx, model.QueryOptions{
 				Filters: annotationBoolFilter("starred")("starred", "true"),
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -284,7 +285,7 @@ var _ = Describe("Annotation Filters", func() {
 		})
 
 		It("counts via a raw annotation filter without a 'no such column' error", func() {
-			count, err := albumRepo.CountAll(model.QueryOptions{
+			count, err := albumRepo.CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Expr("COALESCE(rating, 0) > 0"),
 			})
 			Expect(err).ToNot(HaveOccurred())
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index 026e42b03..be88156d8 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -29,7 +29,7 @@ import (
 // When creating a new repository using this base, you must:
 //
 //   - Embed this struct.
-//   - Set ctx and db fields. ctx should be the context passed to the constructor method, usually obtained from the request
+//   - Set the db field.
 //   - Call registerModel with the model instance and any possible filters.
 //   - If the model has a different table name than the default (lowercase of the model name), it should be set manually
 //     using the tableName field.
@@ -38,7 +38,6 @@ import (
 // All fields in filters and sortMappings must be in snake_case. Only sorts and filters based on real field names or
 // defined in the mappings will be allowed.
 type sqlRepository struct {
-	ctx       context.Context
 	tableName string
 	db        dbx.Builder
 
@@ -65,8 +64,8 @@ func loggedUser(ctx context.Context) *model.User {
 //
 // The predicate uses an unqualified user_id, so it only works on queries where that column is
 // unambiguous (no join introducing a second user_id).
-func (r sqlRepository) ownerFilter() Sqlizer {
-	if usr := loggedUser(r.ctx); !usr.IsAdmin && usr.ID != invalidUserId {
+func (r sqlRepository) ownerFilter(ctx context.Context) Sqlizer {
+	if usr := loggedUser(ctx); !usr.IsAdmin && usr.ID != invalidUserId {
 		return Eq{"user_id": usr.ID}
 	}
 	return nil
@@ -75,12 +74,12 @@ func (r sqlRepository) ownerFilter() Sqlizer {
 // addRestriction combines an optional caller predicate with the ownership filter, producing the
 // WHERE clause for owner-scoped reads. For admins and headless contexts ownerFilter() is nil and
 // only the caller's predicate (if any) remains.
-func (r sqlRepository) addRestriction(sql ...Sqlizer) Sqlizer {
+func (r sqlRepository) addRestriction(ctx context.Context, sql ...Sqlizer) Sqlizer {
 	s := And{}
 	if len(sql) > 0 {
 		s = append(s, sql[0])
 	}
-	if owner := r.ownerFilter(); owner != nil {
+	if owner := r.ownerFilter(ctx); owner != nil {
 		s = append(s, owner)
 	}
 	return s
@@ -121,10 +120,10 @@ func (r *sqlRepository) setSortMappings(mappings map[string]string, tableName ..
 	r.sortMappings = mappings
 }
 
-func (r sqlRepository) newSelect(options ...model.QueryOptions) SelectBuilder {
+func (r sqlRepository) newSelect(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
 	sq := Select().From(r.tableName)
 	if len(options) > 0 {
-		r.resetSeededRandom(options)
+		r.resetSeededRandom(ctx, options)
 		sq = r.applyOptions(sq, options...)
 		sq = r.applyFilters(sq, options...)
 	}
@@ -243,8 +242,8 @@ func libraryIdFilter(_ string, value any) Sqlizer {
 
 // applyLibraryFilter adds library filtering to queries for tables that have a library_id column
 // This ensures users only see content from libraries they have access to
-func (r sqlRepository) applyLibraryFilter(sq SelectBuilder, tableName ...string) SelectBuilder {
-	user := loggedUser(r.ctx)
+func (r sqlRepository) applyLibraryFilter(ctx context.Context, sq SelectBuilder, tableName ...string) SelectBuilder {
+	user := loggedUser(ctx)
 
 	// If the user is an admin, or the user ID is invalid (e.g., when no user is logged in), skip the library filter
 	if user.IsAdmin || user.ID == invalidUserId {
@@ -253,7 +252,7 @@ func (r sqlRepository) applyLibraryFilter(sq SelectBuilder, tableName ...string)
 
 	// A non-admin granted every library sees everything the subquery would return, so applying it is
 	// pure overhead. Skip it in that case (same fast path admins get).
-	if visible, err := r.visibleLibraryIDs(); err == nil && r.userSeesAllLibraries(visible) {
+	if visible, err := r.visibleLibraryIDs(ctx); err == nil && r.userSeesAllLibraries(ctx, visible) {
 		return sq
 	}
 
@@ -270,65 +269,66 @@ func (r sqlRepository) applyLibraryFilter(sq SelectBuilder, tableName ...string)
 
 // userSeesAllLibraries reports whether the visible set already covers every library, so a
 // library filter would exclude nothing.
-func (r sqlRepository) userSeesAllLibraries(visible []int) bool {
-	user := loggedUser(r.ctx)
+func (r sqlRepository) userSeesAllLibraries(ctx context.Context, visible []int) bool {
+	user := loggedUser(ctx)
 	if user.IsAdmin || user.ID == invalidUserId {
 		return true // visible is the whole library table
 	}
-	total, err := NewLibraryRepository(r.ctx, r.db).CountAll()
-	if err != nil || total == 0 {
+	var res struct{ Count int64 }
+	err := r.queryOne(ctx, Select("count(*) as count").From("library"), &res)
+	if err != nil || res.Count == 0 {
 		return false
 	}
-	return int64(len(visible)) == total
+	return int64(len(visible)) == res.Count
 }
 
 // visibleLibraryIDs returns the libraries the current user can see: all libraries for admin and
 // headless processes, otherwise the user's granted libraries.
-func (r sqlRepository) visibleLibraryIDs() ([]int, error) {
-	user := loggedUser(r.ctx)
+func (r sqlRepository) visibleLibraryIDs(ctx context.Context) ([]int, error) {
+	user := loggedUser(ctx)
 	if user.IsAdmin || user.ID == invalidUserId {
 		var ids []int
-		err := r.queryAllSlice(Select("id").From("library"), &ids)
+		err := r.queryAllSlice(ctx, Select("id").From("library"), &ids)
 		return ids, err
 	}
 	return slice.Map(user.Libraries, func(lib model.Library) int { return lib.ID }), nil
 }
 
-func (r sqlRepository) seedKey() string {
+func (r sqlRepository) seedKey(ctx context.Context) string {
 	// Seed keys must be all lowercase, or else SQLite3 will encode it, making it not match the seed
 	// used in the query. Hashing the user ID and converting it to a hex string will do the trick
-	userIDHash := xxh3.Hash([]byte(loggedUser(r.ctx).ID))
+	userIDHash := xxh3.Hash([]byte(loggedUser(ctx).ID))
 	return fmt.Sprintf("%s|%016x", r.tableName, userIDHash)
 }
 
-func (r sqlRepository) resetSeededRandom(options []model.QueryOptions) {
+func (r sqlRepository) resetSeededRandom(ctx context.Context, options []model.QueryOptions) {
 	if len(options) == 0 || options[0].Sort != "random" {
 		return
 	}
 	// CAST: playlist_tracks.id is an INTEGER (unlike other tables' TEXT ids); passing it to
 	// SEEDEDRAND's string param uncast silently drops every row (go-sqlite3 binding gotcha).
-	options[0].Sort = fmt.Sprintf("SEEDEDRAND('%s', CAST(%s.id AS TEXT))", r.seedKey(), r.tableName)
+	options[0].Sort = fmt.Sprintf("SEEDEDRAND('%s', CAST(%s.id AS TEXT))", r.seedKey(ctx), r.tableName)
 	if options[0].Seed != "" {
-		hasher.SetSeed(r.seedKey(), options[0].Seed)
+		hasher.SetSeed(r.seedKey(ctx), options[0].Seed)
 		return
 	}
 	if options[0].Offset == 0 {
-		hasher.Reseed(r.seedKey())
+		hasher.Reseed(r.seedKey(ctx))
 	}
 }
 
-func (r sqlRepository) executeSQL(sq Sqlizer) (int64, error) {
+func (r sqlRepository) executeSQL(ctx context.Context, sq Sqlizer) (int64, error) {
 	query, args, err := r.toSQL(sq)
 	if err != nil {
 		return 0, err
 	}
 	start := time.Now()
 	var c int64
-	res, err := r.db.NewQuery(query).Bind(args).WithContext(r.ctx).Execute()
+	res, err := r.db.NewQuery(query).Bind(args).WithContext(ctx).Execute()
 	if res != nil {
 		c, _ = res.RowsAffected()
 	}
-	r.logSQL(query, args, err, c, start)
+	r.logSQL(ctx, query, args, err, c, start)
 	if err != nil {
 		if err.Error() != "LastInsertId is not supported by this driver" {
 			return 0, err
@@ -356,18 +356,18 @@ func (r sqlRepository) toSQL(sq Sqlizer) (string, dbx.Params, error) {
 	return result, params, nil
 }
 
-func (r sqlRepository) queryOne(sq Sqlizer, response any) error {
+func (r sqlRepository) queryOne(ctx context.Context, sq Sqlizer, response any) error {
 	query, args, err := r.toSQL(sq)
 	if err != nil {
 		return err
 	}
 	start := time.Now()
-	err = r.db.NewQuery(query).Bind(args).WithContext(r.ctx).One(response)
+	err = r.db.NewQuery(query).Bind(args).WithContext(ctx).One(response)
 	if errors.Is(err, sql.ErrNoRows) {
-		r.logSQL(query, args, nil, 0, start)
+		r.logSQL(ctx, query, args, nil, 0, start)
 		return model.ErrNotFound
 	}
-	r.logSQL(query, args, err, 1, start)
+	r.logSQL(ctx, query, args, err, 1, start)
 	return err
 }
 
@@ -392,7 +392,7 @@ func wrapCursor[D, T any](cursor iter.Seq2[D, error], toModel func(D) *T) iter.S
 
 // queryWithStableResults is a helper function to execute a query and return an iterator that will yield its results
 // from a cursor, guaranteeing that the results will be stable, even if the underlying data changes.
-func queryWithStableResults[T any](r sqlRepository, sq SelectBuilder, options ...model.QueryOptions) (iter.Seq2[T, error], error) {
+func queryWithStableResults[T any](ctx context.Context, r sqlRepository, sq SelectBuilder, options ...model.QueryOptions) (iter.Seq2[T, error], error) {
 	if len(options) > 0 && options[0].Offset > 0 {
 		sq = r.optimizePagination(sq, options[0])
 	}
@@ -401,8 +401,8 @@ func queryWithStableResults[T any](r sqlRepository, sq SelectBuilder, options ..
 		return nil, err
 	}
 	start := time.Now()
-	rows, err := r.db.NewQuery(query).Bind(args).WithContext(r.ctx).Rows()
-	r.logSQL(query, args, err, -1, start)
+	rows, err := r.db.NewQuery(query).Bind(args).WithContext(ctx).Rows()
+	r.logSQL(ctx, query, args, err, -1, start)
 	if err != nil {
 		return nil, err
 	}
@@ -422,7 +422,7 @@ func queryWithStableResults[T any](r sqlRepository, sq SelectBuilder, options ..
 	}, nil
 }
 
-func (r sqlRepository) queryAll(sq SelectBuilder, response any, options ...model.QueryOptions) error {
+func (r sqlRepository) queryAll(ctx context.Context, sq SelectBuilder, response any, options ...model.QueryOptions) error {
 	if len(options) > 0 && options[0].Offset > 0 {
 		sq = r.optimizePagination(sq, options[0])
 	}
@@ -431,28 +431,28 @@ func (r sqlRepository) queryAll(sq SelectBuilder, response any, options ...model
 		return err
 	}
 	start := time.Now()
-	err = r.db.NewQuery(query).Bind(args).WithContext(r.ctx).All(response)
+	err = r.db.NewQuery(query).Bind(args).WithContext(ctx).All(response)
 	if errors.Is(err, sql.ErrNoRows) {
-		r.logSQL(query, args, nil, -1, start)
+		r.logSQL(ctx, query, args, nil, -1, start)
 		return model.ErrNotFound
 	}
-	r.logSQL(query, args, err, int64(reflect.ValueOf(response).Elem().Len()), start)
+	r.logSQL(ctx, query, args, err, int64(reflect.ValueOf(response).Elem().Len()), start)
 	return err
 }
 
 // queryAllSlice is a helper function to query a single column and return the result in a slice
-func (r sqlRepository) queryAllSlice(sq SelectBuilder, response any) error {
+func (r sqlRepository) queryAllSlice(ctx context.Context, sq SelectBuilder, response any) error {
 	query, args, err := r.toSQL(sq)
 	if err != nil {
 		return err
 	}
 	start := time.Now()
-	err = r.db.NewQuery(query).Bind(args).WithContext(r.ctx).Column(response)
+	err = r.db.NewQuery(query).Bind(args).WithContext(ctx).Column(response)
 	if errors.Is(err, sql.ErrNoRows) {
-		r.logSQL(query, args, nil, -1, start)
+		r.logSQL(ctx, query, args, nil, -1, start)
 		return model.ErrNotFound
 	}
-	r.logSQL(query, args, err, int64(reflect.ValueOf(response).Elem().Len()), start)
+	r.logSQL(ctx, query, args, err, int64(reflect.ValueOf(response).Elem().Len()), start)
 	return err
 }
 
@@ -469,10 +469,10 @@ func (r sqlRepository) optimizePagination(sq SelectBuilder, options model.QueryO
 	return sq
 }
 
-func (r sqlRepository) exists(cond Sqlizer) (bool, error) {
+func (r sqlRepository) exists(ctx context.Context, cond Sqlizer) (bool, error) {
 	existsQuery := Select("count(*) as exist").From(r.tableName).Where(cond)
 	var res struct{ Exist int64 }
-	err := r.queryOne(existsQuery, &res)
+	err := r.queryOne(ctx, existsQuery, &res)
 	return res.Exist > 0, err
 }
 
@@ -487,20 +487,20 @@ func (r sqlRepository) exists(cond Sqlizer) (bool, error) {
 // another user it returns rest.ErrPermissionDenied, otherwise rest.ErrNotFound. The write itself is
 // still atomic; the extra lookup happens only on the failure path (count == 0), where no write
 // occurred, so there is no TOCTOU on the update.
-func (r sqlRepository) updateOwned(id string, m any, colsToUpdate ...string) error {
+func (r sqlRepository) updateOwned(ctx context.Context, id string, m any, colsToUpdate ...string) error {
 	values, err := toSQLArgs(m)
 	if err != nil {
 		return fmt.Errorf("error preparing values to write to DB: %w", err)
 	}
 	updateValues := filterUpdateValues(values, id, colsToUpdate...)
 	delete(updateValues, "user_id") // ownership is immutable on update
-	update := Update(r.tableName).Where(r.addRestriction(Eq{"id": id})).SetMap(updateValues)
-	count, err := r.executeSQL(update)
+	update := Update(r.tableName).Where(r.addRestriction(ctx, Eq{"id": id})).SetMap(updateValues)
+	count, err := r.executeSQL(ctx, update)
 	if err != nil {
 		return err
 	}
 	if count == 0 {
-		return r.classifyOwnedWriteMiss(id)
+		return r.classifyOwnedWriteMiss(ctx, id)
 	}
 	return nil
 }
@@ -510,13 +510,22 @@ func (r sqlRepository) updateOwned(id string, m any, colsToUpdate ...string) err
 // ownership predicate is part of the DELETE's WHERE clause, so a row owned by another user simply
 // does not match and is left untouched. The failure path mirrors updateOwned (see
 // classifyOwnedWriteMiss), so there is no TOCTOU on the delete.
-func (r sqlRepository) deleteOwned(id string) error {
-	count, err := r.executeSQL(Delete(r.tableName).Where(r.addRestriction(Eq{"id": id})))
+func (r sqlRepository) deleteOwned(ctx context.Context, id string) error {
+	count, err := r.executeSQL(ctx, Delete(r.tableName).Where(r.addRestriction(ctx, Eq{"id": id})))
 	if err != nil {
 		return err
 	}
 	if count == 0 {
-		return r.classifyOwnedWriteMiss(id)
+		return r.classifyOwnedWriteMiss(ctx, id)
+	}
+	return nil
+}
+
+func (r sqlRepository) deleteOwnedAll(ctx context.Context, ids ...string) error {
+	for _, id := range ids {
+		if err := r.deleteOwned(ctx, id); err != nil {
+			return err
+		}
 	}
 	return nil
 }
@@ -524,8 +533,8 @@ func (r sqlRepository) deleteOwned(id string) error {
 // classifyOwnedWriteMiss explains why an ownership-filtered write (updateOwned/deleteOwned) matched
 // no row: rest.ErrPermissionDenied if the row exists but is owned by another user, otherwise
 // rest.ErrNotFound. It runs only on the failure path (count == 0), where no write occurred.
-func (r sqlRepository) classifyOwnedWriteMiss(id string) error {
-	exists, err := r.exists(Eq{"id": id})
+func (r sqlRepository) classifyOwnedWriteMiss(ctx context.Context, id string) error {
+	exists, err := r.exists(ctx, Eq{"id": id})
 	if err != nil {
 		return err
 	}
@@ -535,7 +544,7 @@ func (r sqlRepository) classifyOwnedWriteMiss(id string) error {
 	return rest.ErrNotFound
 }
 
-func (r sqlRepository) count(countQuery SelectBuilder, options ...model.QueryOptions) (int64, error) {
+func (r sqlRepository) count(ctx context.Context, countQuery SelectBuilder, options ...model.QueryOptions) (int64, error) {
 	countQuery = countQuery.
 		RemoveColumns().Columns("count(distinct " + r.tableName + ".id) as count").
 		RemoveOffset().RemoveLimit().
@@ -543,22 +552,22 @@ func (r sqlRepository) count(countQuery SelectBuilder, options ...model.QueryOpt
 		From(r.tableName)
 	countQuery = r.applyFilters(countQuery, options...)
 	var res struct{ Count int64 }
-	err := r.queryOne(countQuery, &res)
+	err := r.queryOne(ctx, countQuery, &res)
 	return res.Count, err
 }
 
-func (r sqlRepository) putByMatch(filter Sqlizer, id string, m any, colsToUpdate ...string) (string, error) {
+func (r sqlRepository) putByMatch(ctx context.Context, filter Sqlizer, id string, m any, colsToUpdate ...string) (string, error) {
 	if id != "" {
-		return r.put(id, m, colsToUpdate...)
+		return r.put(ctx, id, m, colsToUpdate...)
 	}
-	existsQuery := r.newSelect().Columns("id").From(r.tableName).Where(filter)
+	existsQuery := r.newSelect(ctx).Columns("id").From(r.tableName).Where(filter)
 
 	var res struct{ ID string }
-	err := r.queryOne(existsQuery, &res)
+	err := r.queryOne(ctx, existsQuery, &res)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return "", err
 	}
-	return r.put(res.ID, m, colsToUpdate...)
+	return r.put(ctx, res.ID, m, colsToUpdate...)
 }
 
 // selectUpdateColumns keeps only the requested colsToUpdate (or all columns when none are
@@ -588,7 +597,7 @@ func filterUpdateValues(values map[string]any, id string, colsToUpdate ...string
 	return updateValues
 }
 
-func (r sqlRepository) put(id string, m any, colsToUpdate ...string) (newId string, err error) {
+func (r sqlRepository) put(ctx context.Context, id string, m any, colsToUpdate ...string) (newId string, err error) {
 	values, err := toSQLArgs(m)
 	if err != nil {
 		return "", fmt.Errorf("error preparing values to write to DB: %w", err)
@@ -596,7 +605,7 @@ func (r sqlRepository) put(id string, m any, colsToUpdate ...string) (newId stri
 	// If there's an ID, try to update first
 	if id != "" {
 		update := Update(r.tableName).Where(Eq{"id": id}).SetMap(filterUpdateValues(values, id, colsToUpdate...))
-		count, err := r.executeSQL(update)
+		count, err := r.executeSQL(ctx, update)
 		if err != nil {
 			return "", err
 		}
@@ -610,18 +619,18 @@ func (r sqlRepository) put(id string, m any, colsToUpdate ...string) (newId stri
 		values["id"] = id
 	}
 	insert := Insert(r.tableName).SetMap(values)
-	_, err = r.executeSQL(insert)
+	_, err = r.executeSQL(ctx, insert)
 	return id, err
 }
 
-func (r sqlRepository) delete(cond Sqlizer) error {
-	_, err := r.executeSQL(Delete(r.tableName).Where(cond))
+func (r sqlRepository) delete(ctx context.Context, cond Sqlizer) error {
+	_, err := r.executeSQL(ctx, Delete(r.tableName).Where(cond))
 	return err
 }
 
 // deleteByID is for single-item deletes that must report a missing row; delete succeeds silently.
-func (r sqlRepository) deleteByID(id string) error {
-	count, err := r.executeSQL(Delete(r.tableName).Where(Eq{"id": id}))
+func (r sqlRepository) deleteByID(ctx context.Context, id string) error {
+	count, err := r.executeSQL(ctx, Delete(r.tableName).Where(Eq{"id": id}))
 	if err != nil {
 		return err
 	}
@@ -631,9 +640,9 @@ func (r sqlRepository) deleteByID(id string) error {
 	return nil
 }
 
-func (r sqlRepository) logSQL(sql string, args dbx.Params, err error, rowsAffected int64, start time.Time) {
+func (r sqlRepository) logSQL(ctx context.Context, sql string, args dbx.Params, err error, rowsAffected int64, start time.Time) {
 	elapsed := time.Since(start)
-	fields := []any{r.ctx, "SQL: `" + sql + "`", "args", args, "rowsAffected", rowsAffected, "elapsedTime", elapsed}
+	fields := []any{ctx, "SQL: `" + sql + "`", "args", args, "rowsAffected", rowsAffected, "elapsedTime", elapsed}
 	if err == nil || errors.Is(err, context.Canceled) {
 		log.Trace(append(fields, err)...)
 		return
@@ -643,7 +652,7 @@ func (r sqlRepository) logSQL(sql string, args dbx.Params, err error, rowsAffect
 	if code, extended, ok := db.ErrorCodes(err); ok {
 		fields = append(fields, "sqliteCode", code, "sqliteExtended", extended)
 	}
-	if db.IsBusy(err) && hasBusyRetry(r.ctx) {
+	if db.IsBusy(err) && hasBusyRetry(ctx) {
 		log.Warn(append(fields, err)...)
 		return
 	}
diff --git a/persistence/sql_base_repository_test.go b/persistence/sql_base_repository_test.go
index 0f76eb6ab..33a8140f8 100644
--- a/persistence/sql_base_repository_test.go
+++ b/persistence/sql_base_repository_test.go
@@ -13,8 +13,9 @@ import (
 
 var _ = Describe("sqlRepository", func() {
 	var r sqlRepository
+	var ctx context.Context
 	BeforeEach(func() {
-		r.ctx = request.WithUser(context.Background(), model.User{ID: "user-id"})
+		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "user-id"})
 		r.tableName = "table"
 	})
 
@@ -88,19 +89,19 @@ var _ = Describe("sqlRepository", func() {
 
 		When("sanitizing sort", func() {
 			It("returns empty if the sort key is not found in the model nor in the mappings", func() {
-				sort, _ := r.sanitizeSort("unknown", "")
+				sort, _ := r.sanitizeSort(ctx, "unknown", "")
 				Expect(sort).To(BeEmpty())
 			})
 
 			// Validation only: buildSortOrder resolves the mapping, so mapping here too would hand
 			// sortMapping its own output and re-map values whose parts are themselves keys.
 			It("accepts a known sort key without resolving it", func() {
-				sort, _ := r.sanitizeSort("sort1", "")
+				sort, _ := r.sanitizeSort(ctx, "sort1", "")
 				Expect(sort).To(Equal("sort1"))
 			})
 
 			It("is case insensitive", func() {
-				sort, _ := r.sanitizeSort("Sort1", "")
+				sort, _ := r.sanitizeSort(ctx, "Sort1", "")
 				Expect(sort).To(Equal("sort1"))
 			})
 
@@ -112,38 +113,38 @@ var _ = Describe("sqlRepository", func() {
 			// must survive the round trip through sanitizeSort and buildSortOrder unduplicated.
 			It("does not re-map a value whose parts are also keys", func() {
 				r.sortMappings = map[string]string{"rating": "rating", "rated_at": "rating, rated_at"}
-				sort, _ := r.sanitizeSort("rated_at", "")
+				sort, _ := r.sanitizeSort(ctx, "rated_at", "")
 				Expect(r.buildSortOrder(sort, "asc")).To(Equal("rating asc, rated_at asc"))
 			})
 
 			It("returns the field if it is a valid field", func() {
-				sort, _ := r.sanitizeSort("field", "")
+				sort, _ := r.sanitizeSort(ctx, "field", "")
 				Expect(sort).To(Equal("field"))
 			})
 
 			It("is case insensitive for fields", func() {
-				sort, _ := r.sanitizeSort("FIELD", "")
+				sort, _ := r.sanitizeSort(ctx, "FIELD", "")
 				Expect(sort).To(Equal("field"))
 			})
 		})
 		When("sanitizing order", func() {
 			It("returns 'asc' if order is empty", func() {
-				_, order := r.sanitizeSort("", "")
+				_, order := r.sanitizeSort(ctx, "", "")
 				Expect(order).To(Equal(""))
 			})
 
 			It("returns 'asc' if order is 'asc'", func() {
-				_, order := r.sanitizeSort("", "ASC")
+				_, order := r.sanitizeSort(ctx, "", "ASC")
 				Expect(order).To(Equal("asc"))
 			})
 
 			It("returns 'desc' if order is 'desc'", func() {
-				_, order := r.sanitizeSort("", "desc")
+				_, order := r.sanitizeSort(ctx, "", "desc")
 				Expect(order).To(Equal("desc"))
 			})
 
 			It("returns 'asc' if order is unknown", func() {
-				_, order := r.sanitizeSort("", "something")
+				_, order := r.sanitizeSort(ctx, "", "something")
 				Expect(order).To(Equal("asc"))
 			})
 		})
@@ -248,31 +249,31 @@ var _ = Describe("sqlRepository", func() {
 	Describe("resetSeededRandom", func() {
 		var id string
 		BeforeEach(func() {
-			id = r.seedKey()
+			id = r.seedKey(ctx)
 			hasher.SetSeed(id, "")
 		})
 		It("does not reset seed if sort is not random", func() {
 			var options []model.QueryOptions
-			r.resetSeededRandom(options)
+			r.resetSeededRandom(ctx, options)
 			Expect(hasher.CurrentSeed(id)).To(BeEmpty())
 		})
 		It("resets seed if sort is random", func() {
 			options := []model.QueryOptions{{Sort: "random"}}
-			r.resetSeededRandom(options)
+			r.resetSeededRandom(ctx, options)
 			Expect(hasher.CurrentSeed(id)).NotTo(BeEmpty())
 		})
 		It("resets seed if sort is random and seed is provided", func() {
 			options := []model.QueryOptions{{Sort: "random", Seed: "seed"}}
-			r.resetSeededRandom(options)
+			r.resetSeededRandom(ctx, options)
 			Expect(hasher.CurrentSeed(id)).To(Equal("seed"))
 		})
 		It("keeps seed when paginating", func() {
 			options := []model.QueryOptions{{Sort: "random", Seed: "seed", Offset: 0}}
-			r.resetSeededRandom(options)
+			r.resetSeededRandom(ctx, options)
 			Expect(hasher.CurrentSeed(id)).To(Equal("seed"))
 
 			options = []model.QueryOptions{{Sort: "random", Offset: 1}}
-			r.resetSeededRandom(options)
+			r.resetSeededRandom(ctx, options)
 			Expect(hasher.CurrentSeed(id)).To(Equal("seed"))
 		})
 	})
@@ -298,11 +299,11 @@ var _ = Describe("sqlRepository", func() {
 
 		Context("Admin User", func() {
 			BeforeEach(func() {
-				r.ctx = request.WithUser(context.Background(), model.User{ID: "admin", IsAdmin: true})
+				ctx = request.WithUser(ctx, model.User{ID: "admin", IsAdmin: true})
 			})
 
 			It("should not apply library filter for admin users", func() {
-				result := r.applyLibraryFilter(sq)
+				result := r.applyLibraryFilter(ctx, sq)
 				sql, _, err := result.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(Equal("SELECT * FROM test_table"))
@@ -312,13 +313,13 @@ var _ = Describe("sqlRepository", func() {
 		Context("Regular User with a subset of libraries", func() {
 			BeforeEach(func() {
 				// Strict subset: granted lib 1, DB has libs 1 and 2, so the filter must apply.
-				r.ctx = request.WithUser(context.Background(), model.User{
+				ctx = request.WithUser(ctx, model.User{
 					ID: "user123", IsAdmin: false, Libraries: model.Libraries{{ID: 1}},
 				})
 			})
 
 			It("should apply library filter for regular users", func() {
-				result := r.applyLibraryFilter(sq)
+				result := r.applyLibraryFilter(ctx, sq)
 				sql, args, err := result.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(ContainSubstring("IN (SELECT ul.library_id FROM user_library ul WHERE ul.user_id = ?)"))
@@ -326,7 +327,7 @@ var _ = Describe("sqlRepository", func() {
 			})
 
 			It("should use custom table name when provided", func() {
-				result := r.applyLibraryFilter(sq, "custom_table")
+				result := r.applyLibraryFilter(ctx, sq, "custom_table")
 				sql, args, err := result.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(ContainSubstring("custom_table.library_id IN"))
@@ -336,11 +337,11 @@ var _ = Describe("sqlRepository", func() {
 
 		Context("Regular User with no libraries", func() {
 			BeforeEach(func() {
-				r.ctx = request.WithUser(context.Background(), model.User{ID: "empty", IsAdmin: false})
+				ctx = request.WithUser(ctx, model.User{ID: "empty", IsAdmin: false})
 			})
 
 			It("should apply the library filter (never skip on empty)", func() {
-				result := r.applyLibraryFilter(sq)
+				result := r.applyLibraryFilter(ctx, sq)
 				sql, _, err := result.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(ContainSubstring("IN (SELECT ul.library_id FROM user_library ul WHERE ul.user_id = ?)"))
@@ -359,20 +360,20 @@ var _ = Describe("sqlRepository", func() {
 				for _, id := range ids {
 					libs = append(libs, model.Library{ID: id})
 				}
-				r.ctx = request.WithUser(context.Background(), model.User{
+				ctx = request.WithUser(ctx, model.User{
 					ID: "alllibs", IsAdmin: false, Libraries: libs,
 				})
 			})
 
 			It("should not apply the library filter (subquery would filter nothing)", func() {
-				result := r.applyLibraryFilter(sq)
+				result := r.applyLibraryFilter(ctx, sq)
 				sql, _, err := result.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(Equal("SELECT * FROM test_table"))
 			})
 
 			It("should not apply the filter even with a custom table name", func() {
-				result := r.applyLibraryFilter(sq, "custom_table")
+				result := r.applyLibraryFilter(ctx, sq, "custom_table")
 				sql, _, err := result.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(Equal("SELECT * FROM test_table"))
@@ -381,18 +382,18 @@ var _ = Describe("sqlRepository", func() {
 
 		Context("Headless Process (No User Context)", func() {
 			BeforeEach(func() {
-				r.ctx = context.Background() // No user context
+				ctx = GinkgoT().Context() // No user context
 			})
 
 			It("should not apply library filter for headless processes", func() {
-				result := r.applyLibraryFilter(sq)
+				result := r.applyLibraryFilter(ctx, sq)
 				sql, _, err := result.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(Equal("SELECT * FROM test_table"))
 			})
 
 			It("should not apply library filter even with custom table name", func() {
-				result := r.applyLibraryFilter(sq, "custom_table")
+				result := r.applyLibraryFilter(ctx, sq, "custom_table")
 				sql, _, err := result.ToSql()
 				Expect(err).ToNot(HaveOccurred())
 				Expect(sql).To(Equal("SELECT * FROM test_table"))
diff --git a/persistence/sql_bookmarks.go b/persistence/sql_bookmarks.go
index cff57dc9d..ddb63019d 100644
--- a/persistence/sql_bookmarks.go
+++ b/persistence/sql_bookmarks.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"database/sql"
 	"errors"
 	"fmt"
@@ -14,8 +15,8 @@ import (
 
 const bookmarkTable = "bookmark"
 
-func (r sqlRepository) withBookmark(query SelectBuilder, idField string) SelectBuilder {
-	userID := loggedUser(r.ctx).ID
+func (r sqlRepository) withBookmark(ctx context.Context, query SelectBuilder, idField string) SelectBuilder {
+	userID := loggedUser(ctx).ID
 	if userID == invalidUserId {
 		return query
 	}
@@ -26,17 +27,17 @@ func (r sqlRepository) withBookmark(query SelectBuilder, idField string) SelectB
 		Columns("coalesce(position, 0) as bookmark_position")
 }
 
-func (r sqlRepository) bmkID(itemID ...string) And {
+func (r sqlRepository) bmkID(ctx context.Context, itemID ...string) And {
 	return And{
-		Eq{bookmarkTable + ".user_id": loggedUser(r.ctx).ID},
+		Eq{bookmarkTable + ".user_id": loggedUser(ctx).ID},
 		Eq{bookmarkTable + ".item_type": r.tableName},
 		Eq{bookmarkTable + ".item_id": itemID},
 	}
 }
 
-func (r sqlRepository) bmkUpsert(itemID, comment string, position int64) error {
-	client, _ := request.ClientFrom(r.ctx)
-	user, _ := request.UserFrom(r.ctx)
+func (r sqlRepository) bmkUpsert(ctx context.Context, itemID, comment string, position int64) error {
+	client, _ := request.ClientFrom(ctx)
+	user, _ := request.UserFrom(ctx)
 	values := map[string]any{
 		"comment":    comment,
 		"position":   position,
@@ -44,10 +45,10 @@ func (r sqlRepository) bmkUpsert(itemID, comment string, position int64) error {
 		"changed_by": client,
 	}
 
-	upd := Update(bookmarkTable).Where(r.bmkID(itemID)).SetMap(values)
-	c, err := r.executeSQL(upd)
+	upd := Update(bookmarkTable).Where(r.bmkID(ctx, itemID)).SetMap(values)
+	c, err := r.executeSQL(ctx, upd)
 	if err == nil {
-		log.Debug(r.ctx, "Updated bookmark", "id", itemID, "user", user.UserName, "position", position, "comment", comment)
+		log.Debug(ctx, "Updated bookmark", "id", itemID, "user", user.UserName, "position", position, "comment", comment)
 	}
 	if c == 0 || errors.Is(err, sql.ErrNoRows) {
 		values["user_id"] = user.ID
@@ -56,31 +57,31 @@ func (r sqlRepository) bmkUpsert(itemID, comment string, position int64) error {
 		values["created_at"] = time.Now()
 		values["updated_at"] = time.Now()
 		ins := Insert(bookmarkTable).SetMap(values)
-		_, err = r.executeSQL(ins)
+		_, err = r.executeSQL(ctx, ins)
 		if err != nil {
 			return err
 		}
-		log.Debug(r.ctx, "Added bookmark", "id", itemID, "user", user.UserName, "position", position, "comment", comment)
+		log.Debug(ctx, "Added bookmark", "id", itemID, "user", user.UserName, "position", position, "comment", comment)
 	}
 
 	return err
 }
 
-func (r sqlRepository) AddBookmark(id, comment string, position int64) error {
-	user, _ := request.UserFrom(r.ctx)
-	err := r.bmkUpsert(id, comment, position)
+func (r sqlRepository) AddBookmark(ctx context.Context, id, comment string, position int64) error {
+	user, _ := request.UserFrom(ctx)
+	err := r.bmkUpsert(ctx, id, comment, position)
 	if err != nil {
-		log.Error(r.ctx, "Error adding bookmark", "id", id, "user", user.UserName, "position", position, "comment", comment)
+		log.Error(ctx, "Error adding bookmark", "id", id, "user", user.UserName, "position", position, "comment", comment)
 	}
 	return err
 }
 
-func (r sqlRepository) DeleteBookmark(id string) error {
-	user, _ := request.UserFrom(r.ctx)
-	del := Delete(bookmarkTable).Where(r.bmkID(id))
-	_, err := r.executeSQL(del)
+func (r sqlRepository) DeleteBookmark(ctx context.Context, id string) error {
+	user, _ := request.UserFrom(ctx)
+	del := Delete(bookmarkTable).Where(r.bmkID(ctx, id))
+	_, err := r.executeSQL(ctx, del)
 	if err != nil {
-		log.Error(r.ctx, "Error removing bookmark", "id", id, "user", user.UserName)
+		log.Error(ctx, "Error removing bookmark", "id", id, "user", user.UserName)
 	}
 	return err
 }
@@ -96,18 +97,18 @@ type bookmark struct {
 	UpdatedAt time.Time `json:"updatedAt"`
 }
 
-func (r sqlRepository) GetBookmarks() (model.Bookmarks, error) {
-	user, _ := request.UserFrom(r.ctx)
+func (r sqlRepository) GetBookmarks(ctx context.Context) (model.Bookmarks, error) {
+	user, _ := request.UserFrom(ctx)
 
 	idField := r.tableName + ".id"
-	sq := r.newSelect().Columns(r.tableName + ".*")
-	sq = r.withAnnotation(sq, idField)
-	sq = r.withBookmark(sq, idField).Where(NotEq{bookmarkTable + ".item_id": nil})
-	sq = r.applyLibraryFilter(sq)
+	sq := r.newSelect(ctx).Columns(r.tableName + ".*")
+	sq = r.withAnnotation(ctx, sq, idField)
+	sq = r.withBookmark(ctx, sq, idField).Where(NotEq{bookmarkTable + ".item_id": nil})
+	sq = r.applyLibraryFilter(ctx, sq)
 	var mfs dbMediaFiles // TODO Decouple from media_file
-	err := r.queryAll(sq, &mfs)
+	err := r.queryAll(ctx, sq, &mfs)
 	if err != nil {
-		log.Error(r.ctx, "Error getting mediafiles with bookmarks", "user", user.UserName, err)
+		log.Error(ctx, "Error getting mediafiles with bookmarks", "user", user.UserName, err)
 		return nil, err
 	}
 
@@ -118,18 +119,18 @@ func (r sqlRepository) GetBookmarks() (model.Bookmarks, error) {
 		mfMap[mf.ID] = i
 	}
 
-	sq = Select("*").From(bookmarkTable).Where(r.bmkID(ids...))
+	sq = Select("*").From(bookmarkTable).Where(r.bmkID(ctx, ids...))
 	var bmks []bookmark
-	err = r.queryAll(sq, &bmks)
+	err = r.queryAll(ctx, sq, &bmks)
 	if err != nil {
-		log.Error(r.ctx, "Error getting bookmarks", "user", user.UserName, "ids", ids, err)
+		log.Error(ctx, "Error getting bookmarks", "user", user.UserName, "ids", ids, err)
 		return nil, err
 	}
 
 	resp := make(model.Bookmarks, len(bmks))
 	for i, bmk := range bmks {
 		if itemIdx, ok := mfMap[bmk.ItemID]; !ok {
-			log.Debug(r.ctx, "Invalid bookmark", "id", bmk.ItemID, "user", user.UserName)
+			log.Debug(ctx, "Invalid bookmark", "id", bmk.ItemID, "user", user.UserName)
 			continue
 		} else {
 			resp[i] = model.Bookmark{
@@ -145,21 +146,21 @@ func (r sqlRepository) GetBookmarks() (model.Bookmarks, error) {
 	return resp, nil
 }
 
-func (r sqlRepository) reassignBookmark(prevID, newID string) error {
+func (r sqlRepository) reassignBookmark(ctx context.Context, prevID, newID string) error {
 	upd := Expr("update or ignore "+bookmarkTable+" set item_id = ? where item_type = ? and item_id = ?",
 		newID, r.tableName, prevID)
-	_, err := r.executeSQL(upd)
+	_, err := r.executeSQL(ctx, upd)
 	return err
 }
 
-func (r sqlRepository) cleanBookmarks() error {
+func (r sqlRepository) cleanBookmarks(ctx context.Context) error {
 	del := Delete(bookmarkTable).Where(Eq{"item_type": r.tableName}).Where("item_id not in (select id from " + r.tableName + ")")
-	c, err := r.executeSQL(del)
+	c, err := r.executeSQL(ctx, del)
 	if err != nil {
 		return fmt.Errorf("error cleaning up %s bookmarks: %w", r.tableName, err)
 	}
 	if c > 0 {
-		log.Debug(r.ctx, "Clean-up bookmarks", "totalDeleted", c, "itemType", r.tableName)
+		log.Debug(ctx, "Clean-up bookmarks", "totalDeleted", c, "itemType", r.tableName)
 	}
 	return nil
 }
diff --git a/persistence/sql_bookmarks_test.go b/persistence/sql_bookmarks_test.go
index ae01a0e35..b50a35d5d 100644
--- a/persistence/sql_bookmarks_test.go
+++ b/persistence/sql_bookmarks_test.go
@@ -12,23 +12,23 @@ import (
 
 var _ = Describe("sqlBookmarks", func() {
 	var mr model.MediaFileRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
-		ctx := log.NewContext(context.TODO())
-		ctx = request.WithUser(ctx, model.User{ID: "userid"})
-		mr = NewMediaFileRepository(ctx, GetDBXBuilder())
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), model.User{ID: "userid"})
+		mr = NewMediaFileRepository(GetDBXBuilder())
 	})
 
 	Describe("Bookmarks", func() {
 		It("returns an empty collection if there are no bookmarks", func() {
-			Expect(mr.GetBookmarks()).To(BeEmpty())
+			Expect(mr.GetBookmarks(ctx)).To(BeEmpty())
 		})
 
 		It("saves and overrides bookmarks", func() {
 			By("Saving the bookmark")
-			Expect(mr.AddBookmark(songAntenna.ID, "this is a comment", 123)).To(BeNil())
+			Expect(mr.AddBookmark(ctx, songAntenna.ID, "this is a comment", 123)).To(BeNil())
 
-			bms, err := mr.GetBookmarks()
+			bms, err := mr.GetBookmarks(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(bms).To(HaveLen(1))
@@ -42,9 +42,9 @@ var _ = Describe("sqlBookmarks", func() {
 			Expect(updated).To(BeTemporally(">=", created))
 
 			By("Overriding the bookmark")
-			Expect(mr.AddBookmark(songAntenna.ID, "another comment", 333)).To(BeNil())
+			Expect(mr.AddBookmark(ctx, songAntenna.ID, "another comment", 333)).To(BeNil())
 
-			bms, err = mr.GetBookmarks()
+			bms, err = mr.GetBookmarks(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(bms[0].Item.ID).To(Equal(songAntenna.ID))
@@ -54,66 +54,66 @@ var _ = Describe("sqlBookmarks", func() {
 			Expect(bms[0].UpdatedAt).To(BeTemporally(">=", updated))
 
 			By("Saving another bookmark")
-			Expect(mr.AddBookmark(songComeTogether.ID, "one more comment", 444)).To(BeNil())
-			bms, err = mr.GetBookmarks()
+			Expect(mr.AddBookmark(ctx, songComeTogether.ID, "one more comment", 444)).To(BeNil())
+			bms, err = mr.GetBookmarks(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(bms).To(HaveLen(2))
 
 			By("Delete bookmark")
-			Expect(mr.DeleteBookmark(songAntenna.ID)).To(Succeed())
-			bms, err = mr.GetBookmarks()
+			Expect(mr.DeleteBookmark(ctx, songAntenna.ID)).To(Succeed())
+			bms, err = mr.GetBookmarks(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(bms).To(HaveLen(1))
 			Expect(bms[0].Item.ID).To(Equal(songComeTogether.ID))
 			Expect(bms[0].Item.Title).To(Equal(songComeTogether.Title))
 
-			Expect(mr.DeleteBookmark(songComeTogether.ID)).To(Succeed())
-			Expect(mr.GetBookmarks()).To(BeEmpty())
+			Expect(mr.DeleteBookmark(ctx, songComeTogether.ID)).To(Succeed())
+			Expect(mr.GetBookmarks(ctx)).To(BeEmpty())
 		})
 	})
 
 	Describe("library access", func() {
 		var otherLib model.Library
 		var restrictedUser model.User
-		var adminCtx context.Context
+		var adminCtx, userCtx context.Context
 		var userMr model.MediaFileRepository
 
 		BeforeEach(func() {
 			adminCtx, otherLib, restrictedUser = restrictedFixture("bmk")
 
-			adminMr := NewMediaFileRepository(adminCtx, GetDBXBuilder())
-			Expect(adminMr.Put(&model.MediaFile{
+			adminMr := NewMediaFileRepository(GetDBXBuilder())
+			Expect(adminMr.Put(adminCtx, &model.MediaFile{
 				ID: "bmk-otherlib-track", LibraryID: otherLib.ID,
 				Path: "hidden/bookmarked.mp3", Title: "Hidden Bookmarked",
 			})).To(Succeed())
-			DeferCleanup(func() { _ = adminMr.Delete("bmk-otherlib-track") })
+			DeferCleanup(func() { _ = adminMr.Delete(adminCtx, "bmk-otherlib-track") })
 
-			userCtx := request.WithUser(log.NewContext(GinkgoT().Context()), restrictedUser)
-			userMr = NewMediaFileRepository(userCtx, GetDBXBuilder())
+			userCtx = request.WithUser(ctx, restrictedUser)
+			userMr = NewMediaFileRepository(GetDBXBuilder())
 		})
 
 		It("does not return bookmarks for tracks outside the user's libraries", func() {
-			Expect(userMr.AddBookmark("bmk-otherlib-track", "sneaky", 1)).To(Succeed())
+			Expect(userMr.AddBookmark(userCtx, "bmk-otherlib-track", "sneaky", 1)).To(Succeed())
 
-			Expect(userMr.GetBookmarks()).To(BeEmpty())
+			Expect(userMr.GetBookmarks(userCtx)).To(BeEmpty())
 		})
 
 		It("still returns the bookmark for an admin", func() {
-			adminMr := NewMediaFileRepository(adminCtx, GetDBXBuilder())
-			Expect(adminMr.AddBookmark("bmk-otherlib-track", "mine", 1)).To(Succeed())
-			DeferCleanup(func() { _ = adminMr.DeleteBookmark("bmk-otherlib-track") })
+			adminMr := NewMediaFileRepository(GetDBXBuilder())
+			Expect(adminMr.AddBookmark(adminCtx, "bmk-otherlib-track", "mine", 1)).To(Succeed())
+			DeferCleanup(func() { _ = adminMr.DeleteBookmark(adminCtx, "bmk-otherlib-track") })
 
-			bms, err := adminMr.GetBookmarks()
+			bms, err := adminMr.GetBookmarks(adminCtx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(bms).To(HaveLen(1))
 			Expect(bms[0].Item.ID).To(Equal("bmk-otherlib-track"))
 		})
 
 		It("keeps returning bookmarks for tracks inside the user's libraries", func() {
-			Expect(userMr.AddBookmark(songAntenna.ID, "allowed", 5)).To(Succeed())
-			DeferCleanup(func() { _ = userMr.DeleteBookmark(songAntenna.ID) })
+			Expect(userMr.AddBookmark(userCtx, songAntenna.ID, "allowed", 5)).To(Succeed())
+			DeferCleanup(func() { _ = userMr.DeleteBookmark(userCtx, songAntenna.ID) })
 
-			bms, err := userMr.GetBookmarks()
+			bms, err := userMr.GetBookmarks(userCtx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(bms).To(HaveLen(1))
 			Expect(bms[0].Item.ID).To(Equal(songAntenna.ID))
diff --git a/persistence/sql_participations.go b/persistence/sql_participations.go
index 746abed01..bc2af39e2 100644
--- a/persistence/sql_participations.go
+++ b/persistence/sql_participations.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
 
@@ -74,12 +75,12 @@ func unmarshalParticipants(data string) (model.Participants, error) {
 	return participants, nil
 }
 
-func (r sqlRepository) updateParticipants(itemID string, participants model.Participants) error {
+func (r sqlRepository) updateParticipants(ctx context.Context, itemID string, participants model.Participants) error {
 	// Delete all existing participant entries for this item.
 	// This ensures stale role associations are removed when an artist's role changes
 	// (e.g., an artist was both albumartist and composer, but is now only composer).
 	sqd := Delete(r.tableName + "_artists").Where(Eq{r.tableName + "_id": itemID})
-	_, err := r.executeSQL(sqd)
+	_, err := r.executeSQL(ctx, sqd)
 	if err != nil {
 		return err
 	}
@@ -119,14 +120,14 @@ func (r sqlRepository) updateParticipants(itemID string, participants model.Part
 		ON CONFLICT (artist_id, %[1]s_id, role, sub_role) DO NOTHING   -- Ignore duplicates
 	`, r.tableName)
 
-	_, err = r.executeSQL(Expr(query, itemID, string(participantsJSON)))
+	_, err = r.executeSQL(ctx, Expr(query, itemID, string(participantsJSON)))
 	return err
 }
 
-func (r *sqlRepository) getParticipants(m *model.MediaFile) (model.Participants, error) {
-	ar := NewArtistRepository(r.ctx, r.db)
+func (r *sqlRepository) getParticipants(ctx context.Context, m *model.MediaFile) (model.Participants, error) {
+	ar := NewArtistRepository(r.db)
 	ids := m.Participants.AllIDs()
-	artists, err := ar.GetAll(model.QueryOptions{Filters: Eq{"artist.id": ids}})
+	artists, err := ar.GetAll(ctx, model.QueryOptions{Filters: Eq{"artist.id": ids}})
 	if err != nil {
 		return nil, fmt.Errorf("getting participants: %w", err)
 	}
diff --git a/persistence/sql_restful.go b/persistence/sql_restful.go
index b1cfd2379..a758cb847 100644
--- a/persistence/sql_restful.go
+++ b/persistence/sql_restful.go
@@ -54,7 +54,7 @@ func (r *sqlRepository) parseRestFilters(ctx context.Context, options rest.Query
 func (r *sqlRepository) parseRestOptions(ctx context.Context, options ...rest.QueryOptions) model.QueryOptions {
 	qo := model.QueryOptions{}
 	if len(options) > 0 {
-		qo.Sort, qo.Order = r.sanitizeSort(options[0].Sort, options[0].Order)
+		qo.Sort, qo.Order = r.sanitizeSort(ctx, options[0].Sort, options[0].Order)
 		qo.Max = options[0].Max
 		qo.Offset = options[0].Offset
 		if seed, ok := options[0].Filters["seed"].(string); ok {
@@ -66,13 +66,13 @@ func (r *sqlRepository) parseRestOptions(ctx context.Context, options ...rest.Qu
 	return qo
 }
 
-func (r sqlRepository) sanitizeSort(sort, order string) (string, string) {
+func (r sqlRepository) sanitizeSort(ctx context.Context, sort, order string) (string, string) {
 	if sort != "" {
 		sort = toSnakeCase(sort)
 		// Validate only: buildSortOrder resolves the mapping later, and mapping here as well would
 		// feed sortMapping its own output.
 		if _, _, known := r.lookupSortMapping(sort); !known && !r.isFieldWhiteListed(sort) {
-			log.Warn(r.ctx, "Ignoring sort not whitelisted", "sort", sort, "table", r.tableName)
+			log.Warn(ctx, "Ignoring sort not whitelisted", "sort", sort, "table", r.tableName)
 			sort = ""
 		}
 	}
@@ -129,11 +129,9 @@ func idFilter(tableName string) func(string, any) Sqlizer {
 	return func(field string, value any) Sqlizer { return Eq{tableName + ".id": value} }
 }
 
-func invalidFilter(ctx context.Context) func(string, any) Sqlizer {
-	return func(field string, value any) Sqlizer {
-		log.Warn(ctx, "Invalid filter", "fieldName", field, "value", value)
-		return Eq{"1": "0"}
-	}
+func invalidFilter(field string, value any) Sqlizer {
+	log.Warn("Invalid filter", "fieldName", field, "value", value)
+	return Eq{"1": "0"}
 }
 
 var (
diff --git a/persistence/sql_search.go b/persistence/sql_search.go
index 3049baae7..aa8707247 100644
--- a/persistence/sql_search.go
+++ b/persistence/sql_search.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"fmt"
 	"strings"
 
@@ -32,7 +33,7 @@ type searchConfig struct {
 // including FTS Phase 1 which builds its own query outside sq.
 type searchStrategy interface {
 	Sqlizer
-	execute(r sqlRepository, sq SelectBuilder, dest any, cfg searchConfig, options model.QueryOptions) error
+	execute(ctx context.Context, r sqlRepository, sq SelectBuilder, dest any, cfg searchConfig, options model.QueryOptions) error
 }
 
 // getSearchStrategy returns the appropriate search strategy based on config and query content.
@@ -51,7 +52,7 @@ func getSearchStrategy(tableName, query string) searchStrategy {
 // otherwise delegates to getSearchStrategy. sq must already have LIMIT/OFFSET set
 // via newSelect(options...). options is forwarded so FTS Phase 1 can apply the same
 // filters and pagination independently.
-func (r sqlRepository) doSearch(sq SelectBuilder, q string, results any, cfg searchConfig, options model.QueryOptions) error {
+func (r sqlRepository) doSearch(ctx context.Context, sq SelectBuilder, q string, results any, cfg searchConfig, options model.QueryOptions) error {
 	q = strings.TrimSpace(q)
 	q = strings.TrimSuffix(q, "*")
 
@@ -60,13 +61,13 @@ func (r sqlRepository) doSearch(sq SelectBuilder, q string, results any, cfg sea
 	// Empty query (OpenSubsonic `search3?query=""`) — return all in natural order.
 	if q == "" || q == `""` {
 		rowidCore := Select(r.tableName + ".rowid").From(r.tableName).OrderBy(cfg.NaturalOrder)
-		return r.executeTwoPhase(sq, results, rowidCore, cfg, options)
+		return r.executeTwoPhase(ctx, sq, results, rowidCore, cfg, options)
 	}
 
 	// MBID search: if query is a valid UUID, search by MBID fields instead
 	if uuid.Validate(q) == nil && len(cfg.MBIDFields) > 0 {
 		sq = sq.Where(mbidExpr(r.tableName, q, cfg.MBIDFields...))
-		return r.queryAll(sq, results)
+		return r.queryAll(ctx, sq, results)
 	}
 
 	// Min-length guard: single-character queries are too broad for search3.
@@ -81,7 +82,7 @@ func (r sqlRepository) doSearch(sq SelectBuilder, q string, results any, cfg sea
 		return nil
 	}
 
-	return strategy.execute(r, sq, results, cfg, options)
+	return strategy.execute(ctx, r, sq, results, cfg, options)
 }
 
 // executeTwoPhase runs a search in two phases:
@@ -91,7 +92,7 @@ func (r sqlRepository) doSearch(sq SelectBuilder, q string, results any, cfg sea
 //     covering index; with those JOINs, large offsets degrade to O(offset) join probes —
 //     multi-second responses on 100k+ libraries.
 //   - Phase 2: full SELECT with all JOINs, scoped to Phase 1's rowid page.
-func (r sqlRepository) executeTwoPhase(sq SelectBuilder, results any, rowidCore SelectBuilder, cfg searchConfig, options model.QueryOptions) error {
+func (r sqlRepository) executeTwoPhase(ctx context.Context, sq SelectBuilder, results any, rowidCore SelectBuilder, cfg searchConfig, options model.QueryOptions) error {
 	rowidQuery := rowidCore.
 		Where(Eq{r.tableName + ".missing": false})
 	if options.Max > 0 {
@@ -103,17 +104,17 @@ func (r sqlRepository) executeTwoPhase(sq SelectBuilder, results any, rowidCore
 	if cfg.LibraryFilter != nil {
 		rowidQuery = cfg.LibraryFilter(rowidQuery)
 	} else {
-		rowidQuery = r.applyLibraryFilter(rowidQuery)
+		rowidQuery = r.applyLibraryFilter(ctx, rowidQuery)
 	}
 	if options.Filters != nil {
 		rowidQuery = rowidQuery.Where(options.Filters)
 	}
-	return r.hydrateRowidPage(sq, rowidQuery, results)
+	return r.hydrateRowidPage(ctx, sq, rowidQuery, results)
 }
 
 // hydrateRowidPage joins sq to the ordered rowid set produced by rowidQuery, preserving its
 // ordering. rowidQuery must handle pagination itself; sq's LIMIT/OFFSET are stripped.
-func (r sqlRepository) hydrateRowidPage(sq SelectBuilder, rowidQuery SelectBuilder, results any) error {
+func (r sqlRepository) hydrateRowidPage(ctx context.Context, sq SelectBuilder, rowidQuery SelectBuilder, results any) error {
 	rowidSQL, rowidArgs, err := rowidQuery.ToSql()
 	if err != nil {
 		return fmt.Errorf("building rowid query: %w", err)
@@ -125,7 +126,7 @@ func (r sqlRepository) hydrateRowidPage(sq SelectBuilder, rowidQuery SelectBuild
 	)
 	sq = sq.Join(rankedSubquery+" ON "+r.tableName+".rowid = _ranked._rid", rowidArgs...)
 	sq = sq.OrderBy("_ranked._rn")
-	return r.queryAll(sq, results)
+	return r.queryAll(ctx, sq, results)
 }
 
 func mbidExpr(tableName, mbid string, mbidFields ...string) Sqlizer {
diff --git a/persistence/sql_search_fts.go b/persistence/sql_search_fts.go
index fce77afbb..ee43680e6 100644
--- a/persistence/sql_search_fts.go
+++ b/persistence/sql_search_fts.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"fmt"
 	"regexp"
 	"strings"
@@ -270,7 +271,7 @@ func (s *ftsSearch) ToSql() (string, []any, error) {
 // execute runs a two-phase FTS5 search (see executeTwoPhase): Phase 1 here contributes the
 // FTS MATCH join and BM25 rank ordering. Complex ORDER BY (function calls, aggregations) are
 // dropped from Phase 1.
-func (s *ftsSearch) execute(r sqlRepository, sq SelectBuilder, dest any, cfg searchConfig, options model.QueryOptions) error {
+func (s *ftsSearch) execute(ctx context.Context, r sqlRepository, sq SelectBuilder, dest any, cfg searchConfig, options model.QueryOptions) error {
 	qualifiedOrderBys := []string{s.rankExpr}
 	for _, ob := range cfg.OrderBy {
 		if qualified := qualifyOrderBy(s.tableName, ob); qualified != "" {
@@ -282,7 +283,7 @@ func (s *ftsSearch) execute(r sqlRepository, sq SelectBuilder, dest any, cfg sea
 		From(s.tableName).
 		Join(s.ftsTable+" ON "+s.ftsTable+".rowid = "+s.tableName+".rowid AND "+s.ftsTable+" MATCH ?", s.matchExpr).
 		OrderBy(qualifiedOrderBys...)
-	return r.executeTwoPhase(sq, dest, rowidCore, cfg, options)
+	return r.executeTwoPhase(ctx, sq, dest, rowidCore, cfg, options)
 }
 
 // qualifyOrderBy prepends tableName to a simple column name. Returns empty string for
diff --git a/persistence/sql_search_fts_test.go b/persistence/sql_search_fts_test.go
index d0b26e8d5..5d52cb1e8 100644
--- a/persistence/sql_search_fts_test.go
+++ b/persistence/sql_search_fts_test.go
@@ -317,20 +317,20 @@ var _ = Describe("FTS5 Integration Search", func() {
 		mr  model.MediaFileRepository
 		alr model.AlbumRepository
 		arr model.ArtistRepository
+		ctx context.Context
 	)
 
 	BeforeEach(func() {
-		ctx := log.NewContext(context.TODO())
-		ctx = request.WithUser(ctx, adminUser)
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
 		conn := GetDBXBuilder()
-		mr = NewMediaFileRepository(ctx, conn)
-		alr = NewAlbumRepository(ctx, conn)
-		arr = NewArtistRepository(ctx, conn)
+		mr = NewMediaFileRepository(conn)
+		alr = NewAlbumRepository(conn)
+		arr = NewArtistRepository(conn)
 	})
 
 	Describe("MediaFile search", func() {
 		It("finds media files by title", func() {
-			results, err := mr.Search("Radioactivity", model.QueryOptions{Max: 10})
+			results, err := mr.Search(ctx, "Radioactivity", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].Title).To(Equal("Radioactivity"))
@@ -338,7 +338,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 		})
 
 		It("finds media files by artist name", func() {
-			results, err := mr.Search("Beatles", model.QueryOptions{Max: 10})
+			results, err := mr.Search(ctx, "Beatles", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(3))
 			for _, r := range results {
@@ -349,7 +349,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 
 	Describe("Album search", func() {
 		It("finds albums by name", func() {
-			results, err := alr.Search("Sgt Peppers", model.QueryOptions{Max: 10})
+			results, err := alr.Search(ctx, "Sgt Peppers", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].Name).To(Equal("Sgt Peppers"))
@@ -357,7 +357,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 		})
 
 		It("finds albums with multi-word search", func() {
-			results, err := alr.Search("Abbey Road", model.QueryOptions{Max: 10})
+			results, err := alr.Search(ctx, "Abbey Road", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(2))
 		})
@@ -365,7 +365,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 
 	Describe("Artist search", func() {
 		It("finds artists by name", func() {
-			results, err := arr.Search("Kraftwerk", model.QueryOptions{Max: 10})
+			results, err := arr.Search(ctx, "Kraftwerk", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].Name).To(Equal("Kraftwerk"))
@@ -375,7 +375,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 
 	Describe("CJK search", func() {
 		It("finds media files by CJK title", func() {
-			results, err := mr.Search("プラチナ", model.QueryOptions{Max: 10})
+			results, err := mr.Search(ctx, "プラチナ", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].Title).To(Equal("プラチナ・ジェット"))
@@ -383,14 +383,14 @@ var _ = Describe("FTS5 Integration Search", func() {
 		})
 
 		It("finds media files by CJK artist name", func() {
-			results, err := mr.Search("シートベルツ", model.QueryOptions{Max: 10})
+			results, err := mr.Search(ctx, "シートベルツ", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].Artist).To(Equal("シートベルツ"))
 		})
 
 		It("finds albums by CJK artist name", func() {
-			results, err := alr.Search("シートベルツ", model.QueryOptions{Max: 10})
+			results, err := alr.Search(ctx, "シートベルツ", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].Name).To(Equal("COWBOY BEBOP"))
@@ -398,7 +398,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 		})
 
 		It("finds artists by CJK name", func() {
-			results, err := arr.Search("シートベルツ", model.QueryOptions{Max: 10})
+			results, err := arr.Search(ctx, "シートベルツ", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].Name).To(Equal("シートベルツ"))
@@ -408,7 +408,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 
 	Describe("Album version search", func() {
 		It("finds albums by version tag via FTS", func() {
-			results, err := alr.Search("Deluxe", model.QueryOptions{Max: 10})
+			results, err := alr.Search(ctx, "Deluxe", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].ID).To(Equal(albumWithVersion.ID))
@@ -417,7 +417,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 
 	Describe("Punctuation-only search", func() {
 		It("finds media files with punctuation-only title", func() {
-			results, err := mr.Search("!!!!!!!", model.QueryOptions{Max: 10})
+			results, err := mr.Search(ctx, "!!!!!!!", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(1))
 			Expect(results[0].Title).To(Equal("!!!!!!!"))
@@ -427,7 +427,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 
 	Describe("Single-character search (doSearch min-length guard)", func() {
 		It("returns empty results for single-char query via Search", func() {
-			results, err := mr.Search("a", model.QueryOptions{Max: 10})
+			results, err := mr.Search(ctx, "a", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(BeEmpty(), "doSearch should reject single-char queries")
 		})
@@ -435,7 +435,7 @@ var _ = Describe("FTS5 Integration Search", func() {
 
 	Describe("Max=0 means no limit (regression: must not produce LIMIT 0)", func() {
 		It("returns results with Max=0", func() {
-			results, err := mr.Search("Beatles", model.QueryOptions{Max: 0})
+			results, err := mr.Search(ctx, "Beatles", model.QueryOptions{Max: 0})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).ToNot(BeEmpty(), "Max=0 should mean no limit, not LIMIT 0")
 		})
@@ -456,19 +456,19 @@ var _ = Describe("FTS5 Integration Search", func() {
 				{ID: "fts-rank-2", Name: "Modest Mouse", OrderArtistName: "modest mouse"},
 				{ID: "fts-rank-3", Name: "Morrissey", OrderArtistName: "morrissey"},
 			} {
-				Expect(createArtistWithLibrary(arr, &a, 1)).To(Succeed())
+				Expect(createArtistWithLibrary(ctx, arr, &a, 1)).To(Succeed())
 			}
 		})
 
 		It("ranks the exact transliterated match first for 'MO'", func() {
-			results, err := arr.Search("MO", model.QueryOptions{Max: 10})
+			results, err := arr.Search(ctx, "MO", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).To(HaveLen(3))
 			Expect(results[0].Name).To(Equal("MØ"), "exact match via search_normalized must outrank prefix matches")
 		})
 
 		It("ranks the exact match first for the accented query 'MØ'", func() {
-			results, err := arr.Search("MØ", model.QueryOptions{Max: 10})
+			results, err := arr.Search(ctx, "MØ", model.QueryOptions{Max: 10})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(results).ToNot(BeEmpty())
 			Expect(results[0].Name).To(Equal("MØ"))
diff --git a/persistence/sql_search_like.go b/persistence/sql_search_like.go
index 972545ac5..c7d94cc04 100644
--- a/persistence/sql_search_like.go
+++ b/persistence/sql_search_like.go
@@ -1,6 +1,7 @@
 package persistence
 
 import (
+	"context"
 	"strings"
 
 	. "github.com/Masterminds/squirrel"
@@ -20,10 +21,10 @@ func (s *likeSearch) ToSql() (string, []any, error) {
 	return s.filter.ToSql()
 }
 
-func (s *likeSearch) execute(r sqlRepository, sq SelectBuilder, dest any, cfg searchConfig, options model.QueryOptions) error {
+func (s *likeSearch) execute(ctx context.Context, r sqlRepository, sq SelectBuilder, dest any, cfg searchConfig, options model.QueryOptions) error {
 	sq = sq.Where(s.filter)
 	sq = sq.OrderBy(cfg.OrderBy...)
-	return r.queryAll(sq, dest, options)
+	return r.queryAll(ctx, sq, dest, options)
 }
 
 // newLegacySearch creates a LIKE search against the full_text column.
diff --git a/persistence/sql_search_like_test.go b/persistence/sql_search_like_test.go
index 8ee4ef93c..2bfeba29b 100644
--- a/persistence/sql_search_like_test.go
+++ b/persistence/sql_search_like_test.go
@@ -102,32 +102,32 @@ var _ = Describe("likeSearchExpr", func() {
 
 var _ = Describe("Legacy Integration Search", func() {
 	var mr model.MediaFileRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Search.Backend = "legacy"
 
-		ctx := log.NewContext(context.TODO())
-		ctx = request.WithUser(ctx, adminUser)
 		conn := GetDBXBuilder()
-		mr = NewMediaFileRepository(ctx, conn)
+		mr = NewMediaFileRepository(conn)
 	})
 
 	It("returns results using legacy LIKE-based search", func() {
-		results, err := mr.Search("Radioactivity", model.QueryOptions{Max: 10})
+		results, err := mr.Search(ctx, "Radioactivity", model.QueryOptions{Max: 10})
 		Expect(err).ToNot(HaveOccurred())
 		Expect(results).To(HaveLen(1))
 		Expect(results[0].Title).To(Equal("Radioactivity"))
 	})
 
 	It("returns empty results for single-char query (doSearch min-length guard)", func() {
-		results, err := mr.Search("a", model.QueryOptions{Max: 10})
+		results, err := mr.Search(ctx, "a", model.QueryOptions{Max: 10})
 		Expect(err).ToNot(HaveOccurred())
 		Expect(results).To(BeEmpty(), "doSearch should reject single-char queries")
 	})
 
 	It("returns results with Max=0 (regression: must not produce LIMIT 0)", func() {
-		results, err := mr.Search("Beatles", model.QueryOptions{Max: 0})
+		results, err := mr.Search(ctx, "Beatles", model.QueryOptions{Max: 0})
 		Expect(err).ToNot(HaveOccurred())
 		Expect(results).ToNot(BeEmpty(), "Max=0 should mean no limit, not LIMIT 0")
 	})
diff --git a/persistence/sql_tags.go b/persistence/sql_tags.go
index 11f9fe00e..7e1978453 100644
--- a/persistence/sql_tags.go
+++ b/persistence/sql_tags.go
@@ -54,9 +54,9 @@ var indexedTagNames = []model.TagName{model.TagGenre}
 
 // updateTags rewrites this item's <table>_tags rows from its in-memory tags, mirroring
 // updateParticipants (delete-then-insert in the same Put; JOIN to tag skips not-yet-saved ids).
-func (r sqlRepository) updateTags(itemID string, tags model.Tags) error {
+func (r sqlRepository) updateTags(ctx context.Context, itemID string, tags model.Tags) error {
 	del := Delete(r.tableName + "_tags").Where(Eq{r.tableName + "_id": itemID})
-	if _, err := r.executeSQL(del); err != nil {
+	if _, err := r.executeSQL(ctx, del); err != nil {
 		return err
 	}
 	var tagIDs []string
@@ -77,7 +77,7 @@ func (r sqlRepository) updateTags(itemID string, tags model.Tags) error {
 		SELECT ?, value FROM json_each(?)
 		JOIN tag ON tag.id = value
 		ON CONFLICT (%[1]s_id, tag_id) DO NOTHING`, r.tableName)
-	_, err = r.executeSQL(Expr(query, itemID, string(idsJSON)))
+	_, err = r.executeSQL(ctx, Expr(query, itemID, string(idsJSON)))
 	return err
 }
 
@@ -146,11 +146,10 @@ type baseTagRepository struct {
 // newBaseTagRepository creates a new base tag repository with optional tag filtering.
 // If tagFilter is nil, the repository will work with all tags.
 // If tagFilter is provided, the repository will only work with tags of that specific name.
-func newBaseTagRepository(ctx context.Context, db dbx.Builder, tagFilter *model.TagName) *baseTagRepository {
+func newBaseTagRepository(db dbx.Builder, tagFilter *model.TagName) *baseTagRepository {
 	r := &baseTagRepository{
 		tagFilter: tagFilter,
 	}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "tag"
 	r.registerModel(&model.Tag{}, map[string]filterFunc{
@@ -164,12 +163,12 @@ func newBaseTagRepository(ctx context.Context, db dbx.Builder, tagFilter *model.
 }
 
 // applyLibraryFiltering adds the appropriate library joins based on user context
-func (r *baseTagRepository) applyLibraryFiltering(sq SelectBuilder) SelectBuilder {
+func (r *baseTagRepository) applyLibraryFiltering(ctx context.Context, sq SelectBuilder) SelectBuilder {
 	// Add library_tag join
 	sq = sq.LeftJoin("library_tag on library_tag.tag_id = tag.id")
 
 	// For authenticated users, also join with user_library to filter by accessible libraries
-	user := loggedUser(r.ctx)
+	user := loggedUser(ctx)
 	if user.ID != invalidUserId {
 		sq = sq.Join("user_library on user_library.library_id = library_tag.library_id AND user_library.user_id = ?", user.ID)
 	}
@@ -178,8 +177,8 @@ func (r *baseTagRepository) applyLibraryFiltering(sq SelectBuilder) SelectBuilde
 }
 
 // newSelect overrides the base implementation to apply tag name filtering and library filtering.
-func (r *baseTagRepository) newSelect(options ...model.QueryOptions) SelectBuilder {
-	sq := r.sqlRepository.newSelect(options...)
+func (r *baseTagRepository) newSelect(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	sq := r.sqlRepository.newSelect(ctx, options...)
 
 	// Apply tag name filtering if specified
 	if r.tagFilter != nil {
@@ -187,7 +186,7 @@ func (r *baseTagRepository) newSelect(options ...model.QueryOptions) SelectBuild
 	}
 
 	// Apply library filtering and set up aggregation columns
-	sq = r.applyLibraryFiltering(sq).Columns(
+	sq = r.applyLibraryFiltering(ctx, sq).Columns(
 		"tag.id",
 		"tag.tag_name",
 		"tag.tag_value",
@@ -198,9 +197,9 @@ func (r *baseTagRepository) newSelect(options ...model.QueryOptions) SelectBuild
 	return sq
 }
 
-// ResourceRepository interface implementation
+// REST interface methods
 
-func (r *baseTagRepository) Count(options ...rest.QueryOptions) (int64, error) {
+func (r *baseTagRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
 	sq := Select("COUNT(DISTINCT tag.id)").From("tag")
 
 	// Apply tag name filtering if specified
@@ -209,32 +208,24 @@ func (r *baseTagRepository) Count(options ...rest.QueryOptions) (int64, error) {
 	}
 
 	// Apply library filtering
-	sq = r.applyLibraryFiltering(sq)
+	sq = r.applyLibraryFiltering(ctx, sq)
 
-	return r.count(sq, r.parseRestOptions(r.ctx, options...))
+	return r.count(ctx, sq, r.parseRestOptions(ctx, options...))
 }
 
-func (r *baseTagRepository) Read(id string) (any, error) {
-	query := r.newSelect().Where(Eq{"id": id})
+func (r *baseTagRepository) Read(ctx context.Context, id string) (*model.Tag, error) {
+	query := r.newSelect(ctx).Where(Eq{"id": id})
 	var res model.Tag
-	err := r.queryOne(query, &res)
+	err := r.queryOne(ctx, query, &res)
 	return &res, err
 }
 
-func (r *baseTagRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	query := r.newSelect(r.parseRestOptions(r.ctx, options...))
+func (r *baseTagRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Tag, error) {
+	query := r.newSelect(ctx, r.parseRestOptions(ctx, options...))
 	var res model.TagList
-	err := r.queryAll(query, &res)
+	err := r.queryAll(ctx, query, &res)
 	return res, err
 }
 
-func (r *baseTagRepository) EntityName() string {
-	return "tag"
-}
-
-func (r *baseTagRepository) NewInstance() any {
-	return model.Tag{}
-}
-
 // Interface compliance check
-var _ model.ResourceRepository = (*baseTagRepository)(nil)
+var _ rest.Repository[model.Tag] = (*baseTagRepository)(nil)
diff --git a/persistence/tag_library_filtering_test.go b/persistence/tag_library_filtering_test.go
index ddd897165..a4382dccf 100644
--- a/persistence/tag_library_filtering_test.go
+++ b/persistence/tag_library_filtering_test.go
@@ -78,11 +78,11 @@ var _ = Describe("Tag Library Filtering", func() {
 
 		// Create test tags
 		adminCtx := request.WithUser(log.NewContext(context.TODO()), adminUser)
-		tagRepo := NewTagRepository(adminCtx, GetDBXBuilder())
+		tagRepo := NewTagRepository(GetDBXBuilder())
 
 		createTag := func(libraryID int, name, value string) {
 			tag := model.Tag{ID: id.NewTagID(name, value), TagName: model.TagName(name), TagValue: value}
-			err := tagRepo.Add(libraryID, tag)
+			err := tagRepo.Add(adminCtx, libraryID, tag)
 			Expect(err).ToNot(HaveOccurred())
 		}
 
@@ -119,17 +119,16 @@ var _ = Describe("Tag Library Filtering", func() {
 				ctx = context.Background() // Headless context
 			}
 
-			tagRepo := NewTagRepository(ctx, GetDBXBuilder())
-			repo := tagRepo.(model.ResourceRepository)
+			repo := NewTagRepository(GetDBXBuilder())
 
 			var opts rest.QueryOptions
 			if len(filters) > 0 {
 				opts = filters[0]
 			}
 
-			tags, err := repo.ReadAll(opts)
+			tags, err := repo.ReadAll(ctx, opts)
 			Expect(err).ToNot(HaveOccurred())
-			return tags.(model.TagList)
+			return tags
 		}
 
 		// Helper to count tags
@@ -141,10 +140,9 @@ var _ = Describe("Tag Library Filtering", func() {
 				ctx = context.Background()
 			}
 
-			tagRepo := NewTagRepository(ctx, GetDBXBuilder())
-			repo := tagRepo.(model.ResourceRepository)
+			repo := NewTagRepository(GetDBXBuilder())
 
-			count, err := repo.Count()
+			count, err := repo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			return count
 		}
diff --git a/persistence/tag_repository.go b/persistence/tag_repository.go
index f2093c9d8..d13dece66 100644
--- a/persistence/tag_repository.go
+++ b/persistence/tag_repository.go
@@ -7,6 +7,7 @@ import (
 	"time"
 
 	. "github.com/Masterminds/squirrel"
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/pocketbase/dbx"
@@ -16,20 +17,20 @@ type tagRepository struct {
 	*baseTagRepository
 }
 
-func NewTagRepository(ctx context.Context, db dbx.Builder) model.TagRepository {
+func NewTagRepository(db dbx.Builder) model.TagRepository {
 	return &tagRepository{
-		baseTagRepository: newBaseTagRepository(ctx, db, nil), // nil = no filter, works with all tags
+		baseTagRepository: newBaseTagRepository(db, nil), // nil = no filter, works with all tags
 	}
 }
 
-func (r *tagRepository) Add(libraryID int, tags ...model.Tag) error {
+func (r *tagRepository) Add(ctx context.Context, libraryID int, tags ...model.Tag) error {
 	for chunk := range slices.Chunk(tags, 200) {
 		sq := Insert(r.tableName).Columns("id", "tag_name", "tag_value").
 			Suffix("on conflict (id) do nothing")
 		for _, t := range chunk {
 			sq = sq.Values(t.ID, t.TagName, t.TagValue)
 		}
-		_, err := r.executeSQL(sq)
+		_, err := r.executeSQL(ctx, sq)
 		if err != nil {
 			return err
 		}
@@ -40,7 +41,7 @@ func (r *tagRepository) Add(libraryID int, tags ...model.Tag) error {
 		for _, t := range chunk {
 			libSq = libSq.Values(t.ID, libraryID, 0, 0)
 		}
-		_, err = r.executeSQL(libSq)
+		_, err = r.executeSQL(ctx, libSq)
 		if err != nil {
 			return fmt.Errorf("adding library_tag entries: %w", err)
 		}
@@ -50,7 +51,7 @@ func (r *tagRepository) Add(libraryID int, tags ...model.Tag) error {
 
 // UpdateCounts updates the library_tag table with per-library statistics.
 // Only genres are being updated for now.
-func (r *tagRepository) UpdateCounts() error {
+func (r *tagRepository) UpdateCounts(ctx context.Context) error {
 	template := `
 INSERT INTO library_tag (tag_id, library_id, %[1]s_count)
 SELECT jt.value as tag_id, %[1]s.library_id, count(distinct %[1]s.id) as %[1]s_count
@@ -65,8 +66,8 @@ DO UPDATE SET %[1]s_count = excluded.%[1]s_count;
 	for _, table := range []string{"album", "media_file"} {
 		start := time.Now()
 		query := Expr(fmt.Sprintf(template, table))
-		c, err := r.executeSQL(query)
-		log.Debug(r.ctx, "Updated library tag counts", "table", table, "elapsed", time.Since(start), "updated", c)
+		c, err := r.executeSQL(ctx, query)
+		log.Debug(ctx, "Updated library tag counts", "table", table, "elapsed", time.Since(start), "updated", c)
 		if err != nil {
 			return fmt.Errorf("updating %s library tag counts: %w", table, err)
 		}
@@ -74,14 +75,14 @@ DO UPDATE SET %[1]s_count = excluded.%[1]s_count;
 	return nil
 }
 
-func (r *tagRepository) GetAll(name model.TagName, options ...model.QueryOptions) (model.TagList, error) {
-	sq := r.newSelect(options...).Where(Eq{"tag.tag_name": name})
+func (r *tagRepository) GetAll(ctx context.Context, name model.TagName, options ...model.QueryOptions) (model.TagList, error) {
+	sq := r.newSelect(ctx, options...).Where(Eq{"tag.tag_name": name})
 	res := model.TagList{}
-	err := r.queryAll(sq, &res)
+	err := r.queryAll(ctx, sq, &res)
 	return res, err
 }
 
-func (r *tagRepository) purgeUnused() error {
+func (r *tagRepository) purgeUnused(ctx context.Context) error {
 	del := Delete(r.tableName).Where(`
 	id not in (select jt.value
 	from album left join json_tree(album.tags, '$') as jt
@@ -93,14 +94,14 @@ func (r *tagRepository) purgeUnused() error {
 	where atom is not null
 	  and key = 'id')
 `)
-	c, err := r.executeSQL(del)
+	c, err := r.executeSQL(ctx, del)
 	if err != nil {
 		return fmt.Errorf("error purging %s unused tags: %w", r.tableName, err)
 	}
 	if c > 0 {
-		log.Debug(r.ctx, "Purged unused tags", "totalDeleted", c, "table", r.tableName)
+		log.Debug(ctx, "Purged unused tags", "totalDeleted", c, "table", r.tableName)
 	}
 	return err
 }
 
-var _ model.ResourceRepository = &tagRepository{}
+var _ rest.Repository[model.Tag] = &tagRepository{}
diff --git a/persistence/tag_repository_test.go b/persistence/tag_repository_test.go
index 9a019c30e..730d26357 100644
--- a/persistence/tag_repository_test.go
+++ b/persistence/tag_repository_test.go
@@ -18,15 +18,15 @@ import (
 
 var _ = Describe("TagRepository", func() {
 	var repo model.TagRepository
-	var restRepo model.ResourceRepository
+	var restRepo rest.Repository[model.Tag]
 	var ctx context.Context
 
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		ctx = request.WithUser(log.NewContext(context.TODO()), model.User{ID: "userid", UserName: "johndoe", IsAdmin: true})
-		tagRepo := NewTagRepository(ctx, GetDBXBuilder())
+		tagRepo := NewTagRepository(GetDBXBuilder())
 		repo = tagRepo
-		restRepo = tagRepo.(model.ResourceRepository)
+		restRepo = tagRepo
 
 		// Clean the database before each test to ensure isolation
 		db := GetDBXBuilder()
@@ -48,7 +48,7 @@ var _ = Describe("TagRepository", func() {
 			return model.Tag{ID: id.NewTagID(name, value), TagName: model.TagName(name), TagValue: value}
 		}
 
-		err = repo.Add(1,
+		err = repo.Add(ctx, 1,
 			// Genre tags
 			newTag("genre", "rock"),
 			newTag("genre", "pop"),
@@ -84,17 +84,16 @@ var _ = Describe("TagRepository", func() {
 				TagValue: "experimental",
 			}
 
-			err := repo.Add(1, newTag)
+			err := repo.Add(ctx, 1, newTag)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Verify tag was added
-			result, err := restRepo.Read(newTag.ID)
+			resultTag, err := restRepo.Read(ctx, newTag.ID)
 			Expect(err).ToNot(HaveOccurred())
-			resultTag := result.(*model.Tag)
 			Expect(resultTag.TagValue).To(Equal("experimental"))
 
 			// Check count increased
-			count, err := restRepo.Count()
+			count, err := restRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(int64(21))) // 20 from dataset + 1 new
 		})
@@ -107,15 +106,15 @@ var _ = Describe("TagRepository", func() {
 				TagValue: "rock",
 			}
 
-			count, err := restRepo.Count()
+			count, err := restRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(int64(20))) // Still 20 tags
 
-			err = repo.Add(1, duplicateTag)
+			err = repo.Add(ctx, 1, duplicateTag)
 			Expect(err).ToNot(HaveOccurred()) // Should not error
 
 			// Count should remain the same
-			count, err = restRepo.Count()
+			count, err = restRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(int64(20))) // Still 20 tags
 		})
@@ -123,7 +122,7 @@ var _ = Describe("TagRepository", func() {
 
 	Describe("UpdateCounts", func() {
 		It("should update tag counts successfully", func() {
-			err := repo.UpdateCounts()
+			err := repo.UpdateCounts(ctx)
 			Expect(err).ToNot(HaveOccurred())
 		})
 
@@ -133,7 +132,7 @@ var _ = Describe("TagRepository", func() {
 			_, err := db.NewQuery("DELETE FROM tag").Execute()
 			Expect(err).ToNot(HaveOccurred())
 
-			err = repo.UpdateCounts()
+			err = repo.UpdateCounts(ctx)
 			Expect(err).ToNot(HaveOccurred())
 		})
 
@@ -159,7 +158,7 @@ var _ = Describe("TagRepository", func() {
 			Expect(err).ToNot(HaveOccurred())
 
 			// This should not fail with foreign key constraint error
-			err = repo.UpdateCounts()
+			err = repo.UpdateCounts(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Cleanup
@@ -189,7 +188,7 @@ var _ = Describe("TagRepository", func() {
 			Expect(err).ToNot(HaveOccurred())
 
 			// This should not fail with foreign key constraint error
-			err = repo.UpdateCounts()
+			err = repo.UpdateCounts(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Cleanup
@@ -201,7 +200,7 @@ var _ = Describe("TagRepository", func() {
 
 	Describe("Count", func() {
 		It("should return correct count of tags", func() {
-			count, err := restRepo.Count()
+			count, err := restRepo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(int64(20))) // From the test dataset
 		})
@@ -210,25 +209,23 @@ var _ = Describe("TagRepository", func() {
 	Describe("Read", func() {
 		It("should return existing tag", func() {
 			rockID := id.NewTagID("genre", "rock")
-			result, err := restRepo.Read(rockID)
+			resultTag, err := restRepo.Read(ctx, rockID)
 			Expect(err).ToNot(HaveOccurred())
-			resultTag := result.(*model.Tag)
 			Expect(resultTag.ID).To(Equal(rockID))
 			Expect(resultTag.TagName).To(Equal(model.TagName("genre")))
 			Expect(resultTag.TagValue).To(Equal("rock"))
 		})
 
 		It("should return error for non-existent tag", func() {
-			_, err := restRepo.Read("non-existent-id")
+			_, err := restRepo.Read(ctx, "non-existent-id")
 			Expect(err).To(HaveOccurred())
 		})
 	})
 
 	Describe("ReadAll", func() {
 		It("should return all tags from dataset", func() {
-			result, err := restRepo.ReadAll()
+			tags, err := restRepo.ReadAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
-			tags := result.(model.TagList)
 			Expect(tags).To(HaveLen(20))
 		})
 
@@ -236,9 +233,8 @@ var _ = Describe("TagRepository", func() {
 			options := rest.QueryOptions{
 				Filters: map[string]any{"name": "%rock%"}, // Tags containing 'rock'
 			}
-			result, err := restRepo.ReadAll(options)
+			tags, err := restRepo.ReadAll(ctx, options)
 			Expect(err).ToNot(HaveOccurred())
-			tags := result.(model.TagList)
 			Expect(tags).To(HaveLen(2)) // "rock" and "Alternative Rock"
 
 			// Verify all returned tags contain 'rock' in their value
@@ -251,9 +247,8 @@ var _ = Describe("TagRepository", func() {
 			options := rest.QueryOptions{
 				Filters: map[string]any{"name": "%e%"}, // Tags containing 'e'
 			}
-			result, err := restRepo.ReadAll(options)
+			tags, err := restRepo.ReadAll(ctx, options)
 			Expect(err).ToNot(HaveOccurred())
-			tags := result.(model.TagList)
 			Expect(tags).To(HaveLen(8)) // electronic, house, trance, energetic, Blues, decade x2, Alternative Rock
 
 			// Verify all returned tags contain 'e' in their value
@@ -268,9 +263,8 @@ var _ = Describe("TagRepository", func() {
 				Sort:    "name",
 				Order:   "asc",
 			}
-			result, err := restRepo.ReadAll(options)
+			tags, err := restRepo.ReadAll(ctx, options)
 			Expect(err).ToNot(HaveOccurred())
-			tags := result.(model.TagList)
 			Expect(tags).To(HaveLen(7))
 
 			Expect(slices.IsSortedFunc(tags, func(a, b model.Tag) int {
@@ -284,9 +278,8 @@ var _ = Describe("TagRepository", func() {
 				Sort:    "name",
 				Order:   "desc",
 			}
-			result, err := restRepo.ReadAll(options)
+			tags, err := restRepo.ReadAll(ctx, options)
 			Expect(err).ToNot(HaveOccurred())
-			tags := result.(model.TagList)
 			Expect(tags).To(HaveLen(7))
 
 			Expect(slices.IsSortedFunc(tags, func(a, b model.Tag) int {
@@ -294,18 +287,4 @@ var _ = Describe("TagRepository", func() {
 			}))
 		})
 	})
-
-	Describe("EntityName", func() {
-		It("should return correct entity name", func() {
-			name := restRepo.EntityName()
-			Expect(name).To(Equal("tag"))
-		})
-	})
-
-	Describe("NewInstance", func() {
-		It("should return new tag instance", func() {
-			instance := restRepo.NewInstance()
-			Expect(instance).To(BeAssignableToTypeOf(model.Tag{}))
-		})
-	})
 })
diff --git a/persistence/transcoding_repository.go b/persistence/transcoding_repository.go
index fdf67806d..9db56e143 100644
--- a/persistence/transcoding_repository.go
+++ b/persistence/transcoding_repository.go
@@ -13,63 +13,62 @@ type transcodingRepository struct {
 	sqlRepository
 }
 
-func NewTranscodingRepository(ctx context.Context, db dbx.Builder) model.TranscodingRepository {
+func NewTranscodingRepository(db dbx.Builder) model.TranscodingRepository {
 	r := &transcodingRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.registerModel(&model.Transcoding{}, nil)
 	return r
 }
 
-func (r *transcodingRepository) Get(id string) (*model.Transcoding, error) {
-	sel := r.newSelect().Columns("*").Where(Eq{"id": id})
+func (r *transcodingRepository) Get(ctx context.Context, id string) (*model.Transcoding, error) {
+	sel := r.newSelect(ctx).Columns("*").Where(Eq{"id": id})
 	var res model.Transcoding
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-func (r *transcodingRepository) CountAll(qo ...model.QueryOptions) (int64, error) {
-	return r.count(Select(), qo...)
+func (r *transcodingRepository) CountAll(ctx context.Context, qo ...model.QueryOptions) (int64, error) {
+	return r.count(ctx, Select(), qo...)
 }
 
-func (r *transcodingRepository) FindByFormat(format string) (*model.Transcoding, error) {
-	sel := r.newSelect().Columns("*").Where(Eq{"target_format": format})
+func (r *transcodingRepository) FindByFormat(ctx context.Context, format string) (*model.Transcoding, error) {
+	sel := r.newSelect(ctx).Columns("*").Where(Eq{"target_format": format})
 	var res model.Transcoding
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	return &res, err
 }
 
-func (r *transcodingRepository) Put(t *model.Transcoding) error {
-	if !loggedUser(r.ctx).IsAdmin {
+func (r *transcodingRepository) Put(ctx context.Context, t *model.Transcoding) error {
+	if !loggedUser(ctx).IsAdmin {
 		return rest.ErrPermissionDenied
 	}
-	_, err := r.put(t.ID, t)
+	_, err := r.put(ctx, t.ID, t)
 	return err
 }
 
-func (r *transcodingRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	return r.count(Select(), r.parseRestOptions(r.ctx, options...))
+func (r *transcodingRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.count(ctx, Select(), r.parseRestOptions(ctx, options...))
 }
 
-func (r *transcodingRepository) Read(id string) (any, error) {
-	res, err := r.Get(id)
+func (r *transcodingRepository) Read(ctx context.Context, id string) (*model.Transcoding, error) {
+	res, err := r.Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
-	if !loggedUser(r.ctx).IsAdmin {
+	if !loggedUser(ctx).IsAdmin {
 		res.Command = ""
 	}
 	return res, nil
 }
 
-func (r *transcodingRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	sel := r.newSelect(r.parseRestOptions(r.ctx, options...)).Columns("*")
+func (r *transcodingRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.Transcoding, error) {
+	sel := r.newSelect(ctx, r.parseRestOptions(ctx, options...)).Columns("*")
 	res := model.Transcodings{}
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
-	if !loggedUser(r.ctx).IsAdmin {
+	if !loggedUser(ctx).IsAdmin {
 		for i := range res {
 			res[i].Command = ""
 		}
@@ -77,39 +76,35 @@ func (r *transcodingRepository) ReadAll(options ...rest.QueryOptions) (any, erro
 	return res, nil
 }
 
-func (r *transcodingRepository) EntityName() string {
-	return "transcoding"
-}
-
-func (r *transcodingRepository) NewInstance() any {
-	return &model.Transcoding{}
-}
-
-func (r *transcodingRepository) Save(entity any) (string, error) {
-	if !loggedUser(r.ctx).IsAdmin {
+func (r *transcodingRepository) Save(ctx context.Context, t *model.Transcoding) (string, error) {
+	if !loggedUser(ctx).IsAdmin {
 		return "", rest.ErrPermissionDenied
 	}
-	t := entity.(*model.Transcoding)
-	return r.put(t.ID, t)
+	return r.put(ctx, t.ID, t)
 }
 
-func (r *transcodingRepository) Update(id string, entity any, cols ...string) error {
-	if !loggedUser(r.ctx).IsAdmin {
+func (r *transcodingRepository) Update(ctx context.Context, id string, entity model.Transcoding, cols ...string) error {
+	if !loggedUser(ctx).IsAdmin {
 		return rest.ErrPermissionDenied
 	}
-	t := entity.(*model.Transcoding)
+	t := &entity
 	t.ID = id
-	_, err := r.put(id, t)
+	_, err := r.put(ctx, id, t)
 	return err
 }
 
-func (r *transcodingRepository) Delete(id string) error {
-	if !loggedUser(r.ctx).IsAdmin {
+func (r *transcodingRepository) Delete(ctx context.Context, ids ...string) error {
+	if !loggedUser(ctx).IsAdmin {
 		return rest.ErrPermissionDenied
 	}
-	return r.deleteByID(id)
+	for _, id := range ids {
+		if err := r.deleteByID(ctx, id); err != nil {
+			return err
+		}
+	}
+	return nil
 }
 
 var _ model.TranscodingRepository = (*transcodingRepository)(nil)
-var _ rest.Repository = (*transcodingRepository)(nil)
-var _ rest.Persistable = (*transcodingRepository)(nil)
+var _ rest.Repository[model.Transcoding] = (*transcodingRepository)(nil)
+var _ rest.Persistable[model.Transcoding] = (*transcodingRepository)(nil)
diff --git a/persistence/transcoding_repository_test.go b/persistence/transcoding_repository_test.go
index 3be46bae3..372b5801f 100644
--- a/persistence/transcoding_repository_test.go
+++ b/persistence/transcoding_repository_test.go
@@ -1,6 +1,8 @@
 package persistence
 
 import (
+	"context"
+
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -11,83 +13,78 @@ import (
 
 var _ = Describe("TranscodingRepository", func() {
 	var repo model.TranscodingRepository
-	var adminRepo model.TranscodingRepository
+	var ctx, adminCtx context.Context
 
 	BeforeEach(func() {
-		ctx := log.NewContext(GinkgoT().Context())
-		ctx = request.WithUser(ctx, regularUser)
-		repo = NewTranscodingRepository(ctx, GetDBXBuilder())
-
-		adminCtx := log.NewContext(GinkgoT().Context())
-		adminCtx = request.WithUser(adminCtx, adminUser)
-		adminRepo = NewTranscodingRepository(adminCtx, GetDBXBuilder())
+		ctx = request.WithUser(log.NewContext(GinkgoT().Context()), regularUser)
+		adminCtx = request.WithUser(ctx, adminUser)
+		repo = NewTranscodingRepository(GetDBXBuilder())
 	})
 
 	AfterEach(func() {
 		// Clean up any transcoding created during the tests
-		tc, err := adminRepo.FindByFormat("test_format")
+		tc, err := repo.FindByFormat(adminCtx, "test_format")
 		if err == nil {
-			err = adminRepo.(*transcodingRepository).Delete(tc.ID)
+			err = repo.Delete(adminCtx, tc.ID)
 			Expect(err).ToNot(HaveOccurred())
 		}
 	})
 
 	Describe("Admin User", func() {
 		It("creates a new transcoding", func() {
-			base, err := adminRepo.CountAll()
+			base, err := repo.CountAll(adminCtx)
 			Expect(err).ToNot(HaveOccurred())
 
-			err = adminRepo.Put(&model.Transcoding{ID: "new", Name: "new", TargetFormat: "test_format", DefaultBitRate: 320, Command: "ffmpeg"})
+			err = repo.Put(adminCtx, &model.Transcoding{ID: "new", Name: "new", TargetFormat: "test_format", DefaultBitRate: 320, Command: "ffmpeg"})
 			Expect(err).ToNot(HaveOccurred())
 
-			count, err := adminRepo.CountAll()
+			count, err := repo.CountAll(adminCtx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(Equal(base + 1))
 		})
 
 		It("updates an existing transcoding", func() {
 			tr := &model.Transcoding{ID: "upd", Name: "old", TargetFormat: "test_format", DefaultBitRate: 100, Command: "ffmpeg"}
-			Expect(adminRepo.Put(tr)).To(Succeed())
+			Expect(repo.Put(adminCtx, tr)).To(Succeed())
 			tr.Name = "updated"
-			err := adminRepo.Put(tr)
+			err := repo.Put(adminCtx, tr)
 			Expect(err).ToNot(HaveOccurred())
-			res, err := adminRepo.FindByFormat("test_format")
+			res, err := repo.FindByFormat(adminCtx, "test_format")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.Name).To(Equal("updated"))
 		})
 
 		It("deletes a transcoding", func() {
-			err := adminRepo.Put(&model.Transcoding{ID: "to-delete", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 256, Command: "ffmpeg"})
+			err := repo.Put(adminCtx, &model.Transcoding{ID: "to-delete", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 256, Command: "ffmpeg"})
 			Expect(err).ToNot(HaveOccurred())
-			err = adminRepo.(*transcodingRepository).Delete("to-delete")
+			err = repo.Delete(adminCtx, "to-delete")
 			Expect(err).ToNot(HaveOccurred())
-			_, err = adminRepo.Get("to-delete")
+			_, err = repo.Get(adminCtx, "to-delete")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
 		It("returns not found when deleting a missing transcoding", func() {
-			err := adminRepo.(*transcodingRepository).Delete("does-not-exist")
+			err := repo.(*transcodingRepository).Delete(adminCtx, "does-not-exist")
 			Expect(err).To(MatchError(model.ErrNotFound))
 		})
 
 		It("reads the Command field via the REST Read method", func() {
 			tr := &model.Transcoding{ID: "adminread", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg -secret"}
-			Expect(adminRepo.Put(tr)).To(Succeed())
+			Expect(repo.Put(adminCtx, tr)).To(Succeed())
 
-			res, err := adminRepo.(*transcodingRepository).Read("adminread")
+			res, err := repo.Read(adminCtx, "adminread")
 			Expect(err).ToNot(HaveOccurred())
-			Expect(res.(*model.Transcoding).Command).To(Equal("ffmpeg -secret"))
+			Expect(res.Command).To(Equal("ffmpeg -secret"))
 		})
 	})
 
 	Describe("Regular User", func() {
 		It("reads a transcoding but with the Command field redacted", func() {
 			tr := &model.Transcoding{ID: "readreg", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg -secret"}
-			Expect(adminRepo.Put(tr)).To(Succeed())
+			Expect(repo.Put(adminCtx, tr)).To(Succeed())
 
-			res, err := repo.(*transcodingRepository).Read("readreg")
+			t, err := repo.Read(ctx, "readreg")
 			Expect(err).ToNot(HaveOccurred())
-			t := res.(*model.Transcoding)
 			Expect(t.Name).To(Equal("temp"))
 			Expect(t.TargetFormat).To(Equal("test_format"))
 			Expect(t.Command).To(BeEmpty())
@@ -95,11 +92,10 @@ var _ = Describe("TranscodingRepository", func() {
 
 		It("lists transcodings but with the Command field redacted", func() {
 			tr := &model.Transcoding{ID: "listreg", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg -secret"}
-			Expect(adminRepo.Put(tr)).To(Succeed())
+			Expect(repo.Put(adminCtx, tr)).To(Succeed())
 
-			res, err := repo.(*transcodingRepository).ReadAll()
+			list, err := repo.ReadAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
-			list := res.(model.Transcodings)
 			Expect(list).ToNot(BeEmpty())
 			for _, t := range list {
 				Expect(t.Command).To(BeEmpty())
@@ -107,16 +103,16 @@ var _ = Describe("TranscodingRepository", func() {
 		})
 
 		It("counts transcodings", func() {
-			count, err := repo.(*transcodingRepository).Count()
+			count, err := repo.Count(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(count).To(BeNumerically(">=", 0))
 		})
 
 		It("can still resolve a transcoding for streaming via Get (Command not redacted)", func() {
 			tr := &model.Transcoding{ID: "streamreg", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg -secret"}
-			Expect(adminRepo.Put(tr)).To(Succeed())
+			Expect(repo.Put(adminCtx, tr)).To(Succeed())
 
-			res, err := repo.Get("streamreg")
+			res, err := repo.Get(ctx, "streamreg")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.ID).To(Equal("streamreg"))
 			Expect(res.Command).To(Equal("ffmpeg -secret"))
@@ -124,38 +120,34 @@ var _ = Describe("TranscodingRepository", func() {
 
 		It("can still resolve a transcoding for streaming via FindByFormat (Command not redacted)", func() {
 			tr := &model.Transcoding{ID: "fmtreg", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg -secret"}
-			Expect(adminRepo.Put(tr)).To(Succeed())
+			Expect(repo.Put(adminCtx, tr)).To(Succeed())
 
-			res, err := repo.FindByFormat("test_format")
+			res, err := repo.FindByFormat(ctx, "test_format")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(res.ID).To(Equal("fmtreg"))
 			Expect(res.Command).To(Equal("ffmpeg -secret"))
 		})
 
 		It("fails to create", func() {
-			err := repo.Put(&model.Transcoding{ID: "bad", Name: "bad", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg"})
+			err := repo.Put(ctx, &model.Transcoding{ID: "bad", Name: "bad", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg"})
 			Expect(err).To(Equal(rest.ErrPermissionDenied))
 		})
 
 		It("fails to update", func() {
 			tr := &model.Transcoding{ID: "updreg", Name: "old", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg"}
-			Expect(adminRepo.Put(tr)).To(Succeed())
+			Expect(repo.Put(adminCtx, tr)).To(Succeed())
 
 			tr.Name = "bad"
-			err := repo.Put(tr)
+			err := repo.Put(ctx, tr)
 			Expect(err).To(Equal(rest.ErrPermissionDenied))
-
-			//_ = adminRepo.(*transcodingRepository).Delete("updreg")
 		})
 
 		It("fails to delete", func() {
 			tr := &model.Transcoding{ID: "delreg", Name: "temp", TargetFormat: "test_format", DefaultBitRate: 64, Command: "ffmpeg"}
-			Expect(adminRepo.Put(tr)).To(Succeed())
+			Expect(repo.Put(adminCtx, tr)).To(Succeed())
 
-			err := repo.(*transcodingRepository).Delete("delreg")
+			err := repo.Delete(ctx, "delreg")
 			Expect(err).To(Equal(rest.ErrPermissionDenied))
-
-			//_ = adminRepo.(*transcodingRepository).Delete("delreg")
 		})
 	})
 })
diff --git a/persistence/user_props_repository.go b/persistence/user_props_repository.go
index 9307385a2..59d7d332f 100644
--- a/persistence/user_props_repository.go
+++ b/persistence/user_props_repository.go
@@ -13,17 +13,16 @@ type userPropsRepository struct {
 	sqlRepository
 }
 
-func NewUserPropsRepository(ctx context.Context, db dbx.Builder) model.UserPropsRepository {
+func NewUserPropsRepository(db dbx.Builder) model.UserPropsRepository {
 	r := &userPropsRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "user_props"
 	return r
 }
 
-func (r userPropsRepository) Put(userId, key string, value string) error {
+func (r userPropsRepository) Put(ctx context.Context, userId, key string, value string) error {
 	update := Update(r.tableName).Set("value", value).Where(And{Eq{"user_id": userId}, Eq{"key": key}})
-	count, err := r.executeSQL(update)
+	count, err := r.executeSQL(ctx, update)
 	if err != nil {
 		return err
 	}
@@ -31,24 +30,24 @@ func (r userPropsRepository) Put(userId, key string, value string) error {
 		return nil
 	}
 	insert := Insert(r.tableName).Columns("user_id", "key", "value").Values(userId, key, value)
-	_, err = r.executeSQL(insert)
+	_, err = r.executeSQL(ctx, insert)
 	return err
 }
 
-func (r userPropsRepository) Get(userId, key string) (string, error) {
+func (r userPropsRepository) Get(ctx context.Context, userId, key string) (string, error) {
 	sel := Select("value").From(r.tableName).Where(And{Eq{"user_id": userId}, Eq{"key": key}})
 	resp := struct {
 		Value string
 	}{}
-	err := r.queryOne(sel, &resp)
+	err := r.queryOne(ctx, sel, &resp)
 	if err != nil {
 		return "", err
 	}
 	return resp.Value, nil
 }
 
-func (r userPropsRepository) DefaultGet(userId, key string, defaultValue string) (string, error) {
-	value, err := r.Get(userId, key)
+func (r userPropsRepository) DefaultGet(ctx context.Context, userId, key string, defaultValue string) (string, error) {
+	value, err := r.Get(ctx, userId, key)
 	if errors.Is(err, model.ErrNotFound) {
 		return defaultValue, nil
 	}
@@ -58,6 +57,6 @@ func (r userPropsRepository) DefaultGet(userId, key string, defaultValue string)
 	return value, nil
 }
 
-func (r userPropsRepository) Delete(userId, key string) error {
-	return r.delete(And{Eq{"user_id": userId}, Eq{"key": key}})
+func (r userPropsRepository) Delete(ctx context.Context, userId, key string) error {
+	return r.delete(ctx, And{Eq{"user_id": userId}, Eq{"key": key}})
 }
diff --git a/persistence/user_repository.go b/persistence/user_repository.go
index 9399bcb53..20b4e5125 100644
--- a/persistence/user_repository.go
+++ b/persistence/user_repository.go
@@ -53,25 +53,24 @@ var (
 	encKey []byte
 )
 
-func NewUserRepository(ctx context.Context, db dbx.Builder) model.UserRepository {
+func NewUserRepository(db dbx.Builder) model.UserRepository {
 	r := &userRepository{}
-	r.ctx = ctx
 	r.db = db
 	r.tableName = "user"
 	r.registerModel(&model.User{}, map[string]filterFunc{
 		"id":       idFilter(r.tableName),
-		"password": invalidFilter(ctx),
+		"password": invalidFilter,
 		"name":     startsWithFilter(r.tableName + ".name"),
 	})
 	once.Do(func() {
-		_ = r.initPasswordEncryptionKey()
+		_ = r.initPasswordEncryptionKey(context.Background())
 	})
 	return r
 }
 
 // selectUserWithLibraries returns a SelectBuilder that includes library information
-func (r *userRepository) selectUserWithLibraries(options ...model.QueryOptions) SelectBuilder {
-	return r.newSelect(options...).
+func (r *userRepository) selectUserWithLibraries(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
+	return r.newSelect(ctx, options...).
 		Columns(`user.*`,
 			`COALESCE(json_group_array(json_object(
 				'id', library.id,
@@ -89,37 +88,37 @@ func (r *userRepository) selectUserWithLibraries(options ...model.QueryOptions)
 		GroupBy("user.id")
 }
 
-func (r *userRepository) CountAll(qo ...model.QueryOptions) (int64, error) {
-	return r.count(Select(), qo...)
+func (r *userRepository) CountAll(ctx context.Context, qo ...model.QueryOptions) (int64, error) {
+	return r.count(ctx, Select(), qo...)
 }
 
-func (r *userRepository) Get(id string) (*model.User, error) {
-	sel := r.selectUserWithLibraries().Where(Eq{"user.id": id})
+func (r *userRepository) Get(ctx context.Context, id string) (*model.User, error) {
+	sel := r.selectUserWithLibraries(ctx).Where(Eq{"user.id": id})
 	var res dbUser
-	err := r.queryOne(sel, &res)
+	err := r.queryOne(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
 	return res.User, nil
 }
 
-func (r *userRepository) GetAll(options ...model.QueryOptions) (model.Users, error) {
-	sel := r.selectUserWithLibraries(options...)
+func (r *userRepository) GetAll(ctx context.Context, options ...model.QueryOptions) (model.Users, error) {
+	sel := r.selectUserWithLibraries(ctx, options...)
 	var res dbUsers
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	if err != nil {
 		return nil, err
 	}
 	return res.toModels(), nil
 }
 
-func (r *userRepository) Put(u *model.User) error {
+func (r *userRepository) Put(ctx context.Context, u *model.User) error {
 	if u.ID == "" {
 		u.ID = id.NewRandom()
 	}
 	u.UpdatedAt = time.Now()
 	if u.NewPassword != "" {
-		_ = r.encryptPassword(u)
+		_ = r.encryptPassword(ctx, u)
 	}
 	values, err := toSQLArgs(*u)
 	if err != nil {
@@ -134,7 +133,7 @@ func (r *userRepository) Put(u *model.User) error {
 	var epoch int
 	if u.NewPassword != "" {
 		var res struct{ TokenEpoch int }
-		err = r.queryOne(update.Set("token_epoch", Expr("token_epoch + 1")).
+		err = r.queryOne(ctx, update.Set("token_epoch", Expr("token_epoch + 1")).
 			Suffix("RETURNING token_epoch"), &res)
 		switch {
 		case errors.Is(err, model.ErrNotFound):
@@ -145,7 +144,7 @@ func (r *userRepository) Put(u *model.User) error {
 			epoch = res.TokenEpoch
 		}
 	} else {
-		count, err := r.executeSQL(update)
+		count, err := r.executeSQL(ctx, update)
 		if err != nil {
 			return err
 		}
@@ -154,7 +153,7 @@ func (r *userRepository) Put(u *model.User) error {
 	if isNewUser {
 		values["created_at"] = time.Now()
 		insert := Insert(r.tableName).SetMap(values)
-		_, err = r.executeSQL(insert)
+		_, err = r.executeSQL(ctx, insert)
 		if err != nil {
 			return err
 		}
@@ -166,7 +165,7 @@ func (r *userRepository) Put(u *model.User) error {
 			"INSERT OR IGNORE INTO user_library (user_id, library_id) SELECT ?, id FROM library",
 			u.ID,
 		)
-		if _, err := r.executeSQL(sql); err != nil {
+		if _, err := r.executeSQL(ctx, sql); err != nil {
 			return fmt.Errorf("failed to assign all libraries to admin user: %w", err)
 		}
 	} else if isNewUser { // Only for new regular users
@@ -175,117 +174,108 @@ func (r *userRepository) Put(u *model.User) error {
 			"INSERT OR IGNORE INTO user_library (user_id, library_id) SELECT ?, id FROM library WHERE default_new_users = true",
 			u.ID,
 		)
-		if _, err := r.executeSQL(sql); err != nil {
+		if _, err := r.executeSQL(ctx, sql); err != nil {
 			return fmt.Errorf("failed to assign default libraries to new user: %w", err)
 		}
 	}
 
 	// Only the caller's own token can be refreshed in-flight; an admin resetting another
 	// user must keep their own epoch.
-	if u.NewPassword != "" && !isNewUser && loggedUser(r.ctx).ID == u.ID {
-		request.SetTokenEpoch(r.ctx, epoch)
+	if u.NewPassword != "" && !isNewUser && loggedUser(ctx).ID == u.ID {
+		request.SetTokenEpoch(ctx, epoch)
 	}
 
 	return nil
 }
 
-func (r *userRepository) FindFirstAdmin() (*model.User, error) {
-	sel := r.selectUserWithLibraries(model.QueryOptions{Sort: "updated_at", Max: 1}).Where(Eq{"user.is_admin": true})
+func (r *userRepository) FindFirstAdmin(ctx context.Context) (*model.User, error) {
+	sel := r.selectUserWithLibraries(ctx, model.QueryOptions{Sort: "updated_at", Max: 1}).Where(Eq{"user.is_admin": true})
 	var usr dbUser
-	err := r.queryOne(sel, &usr)
+	err := r.queryOne(ctx, sel, &usr)
 	if err != nil {
 		return nil, err
 	}
 	return usr.User, nil
 }
 
-func (r *userRepository) FindByUsername(username string) (*model.User, error) {
-	sel := r.selectUserWithLibraries().Where(Expr("user.user_name = ? COLLATE NOCASE", username))
+func (r *userRepository) FindByUsername(ctx context.Context, username string) (*model.User, error) {
+	sel := r.selectUserWithLibraries(ctx).Where(Expr("user.user_name = ? COLLATE NOCASE", username))
 	var usr dbUser
-	err := r.queryOne(sel, &usr)
+	err := r.queryOne(ctx, sel, &usr)
 	if err != nil {
 		return nil, err
 	}
 	return usr.User, nil
 }
 
-func (r *userRepository) FindByUsernameWithPassword(username string) (*model.User, error) {
-	usr, err := r.FindByUsername(username)
+func (r *userRepository) FindByUsernameWithPassword(ctx context.Context, username string) (*model.User, error) {
+	usr, err := r.FindByUsername(ctx, username)
 	if err != nil {
 		return nil, err
 	}
-	_ = r.decryptPassword(usr)
+	_ = r.decryptPassword(ctx, usr)
 	return usr, nil
 }
 
-func (r *userRepository) UpdateLastLoginAt(id string) error {
+func (r *userRepository) UpdateLastLoginAt(ctx context.Context, id string) error {
 	upd := Update(r.tableName).Where(Eq{"id": id}).Set("last_login_at", time.Now())
-	_, err := r.executeSQL(upd)
+	_, err := r.executeSQL(ctx, upd)
 	return err
 }
 
-func (r *userRepository) UpdateLastAccessAt(id string) error {
+func (r *userRepository) UpdateLastAccessAt(ctx context.Context, id string) error {
 	now := time.Now()
 	upd := Update(r.tableName).Where(Eq{"id": id}).Set("last_access_at", now)
-	_, err := r.executeSQL(upd)
+	_, err := r.executeSQL(ctx, upd)
 	return err
 }
 
-func (r *userRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	usr := loggedUser(r.ctx)
+func (r *userRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	usr := loggedUser(ctx)
 	if !usr.IsAdmin {
 		return 0, rest.ErrPermissionDenied
 	}
-	return r.CountAll(r.parseRestOptions(r.ctx, options...))
+	return r.CountAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *userRepository) Read(id string) (any, error) {
-	usr := loggedUser(r.ctx)
+func (r *userRepository) Read(ctx context.Context, id string) (*model.User, error) {
+	usr := loggedUser(ctx)
 	if !usr.IsAdmin && usr.ID != id {
 		return nil, rest.ErrPermissionDenied
 	}
-	return r.Get(id)
+	return r.Get(ctx, id)
 }
 
-func (r *userRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	usr := loggedUser(r.ctx)
+func (r *userRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.User, error) {
+	usr := loggedUser(ctx)
 	if !usr.IsAdmin {
 		return nil, rest.ErrPermissionDenied
 	}
-	return r.GetAll(r.parseRestOptions(r.ctx, options...))
+	return r.GetAll(ctx, r.parseRestOptions(ctx, options...))
 }
 
-func (r *userRepository) EntityName() string {
-	return "user"
-}
-
-func (r *userRepository) NewInstance() any {
-	return &model.User{}
-}
-
-func (r *userRepository) Save(entity any) (string, error) {
-	usr := loggedUser(r.ctx)
+func (r *userRepository) Save(ctx context.Context, u *model.User) (string, error) {
+	usr := loggedUser(ctx)
 	if !usr.IsAdmin {
 		return "", rest.ErrPermissionDenied
 	}
-	u := entity.(*model.User)
-	if err := validateUsernameUnique(r, u); err != nil {
+	if err := validateUsernameUnique(ctx, r, u); err != nil {
 		return "", err
 	}
 	if err := validateScrobbleFilter(u); err != nil {
 		return "", err
 	}
-	err := r.Put(u)
+	err := r.Put(ctx, u)
 	if err != nil {
 		return "", err
 	}
 	return u.ID, err
 }
 
-func (r *userRepository) Update(id string, entity any, _ ...string) error {
-	u := entity.(*model.User)
+func (r *userRepository) Update(ctx context.Context, id string, entity model.User, _ ...string) error {
+	u := &entity
 	u.ID = id
-	usr := loggedUser(r.ctx)
+	usr := loggedUser(ctx)
 	if !usr.IsAdmin && usr.ID != u.ID {
 		return rest.ErrPermissionDenied
 	}
@@ -298,19 +288,19 @@ func (r *userRepository) Update(id string, entity any, _ ...string) error {
 	}
 
 	// Decrypt the user's existing password before validating. This is required otherwise the existing password entered by the user will never match.
-	if err := r.decryptPassword(usr); err != nil {
+	if err := r.decryptPassword(ctx, usr); err != nil {
 		return err
 	}
 	if err := validatePasswordChange(u, usr); err != nil {
 		return err
 	}
-	if err := validateUsernameUnique(r, u); err != nil {
+	if err := validateUsernameUnique(ctx, r, u); err != nil {
 		return err
 	}
 	if err := validateScrobbleFilter(u); err != nil {
 		return err
 	}
-	return r.Put(u)
+	return r.Put(ctx, u)
 }
 
 func validatePasswordChange(newUser *model.User, logged *model.User) error {
@@ -339,8 +329,8 @@ func validatePasswordChange(newUser *model.User, logged *model.User) error {
 	return nil
 }
 
-func validateUsernameUnique(r model.UserRepository, u *model.User) error {
-	usr, err := r.FindByUsername(u.UserName)
+func validateUsernameUnique(ctx context.Context, r model.UserRepository, u *model.User) error {
+	usr, err := r.FindByUsername(ctx, u.UserName)
 	if errors.Is(err, model.ErrNotFound) {
 		return nil
 	}
@@ -380,18 +370,18 @@ func invalidScrobbleFilter() error {
 	}}
 }
 
-func (r *userRepository) Delete(id string) error {
-	usr := loggedUser(r.ctx)
+func (r *userRepository) Delete(ctx context.Context, ids ...string) error {
+	usr := loggedUser(ctx)
 	if !usr.IsAdmin {
 		return rest.ErrPermissionDenied
 	}
-	if err := r.deleteByID(id); err != nil {
-		return err
-	}
-
-	// Clean up orphaned plugin references for the deleted user
-	if err := cleanupPluginUserReferences(r.db, id); err != nil {
-		log.Error(r.ctx, "Failed to cleanup plugin user references", "userID", id, err)
+	for _, id := range ids {
+		if err := r.deleteByID(ctx, id); err != nil {
+			return err
+		}
+		if err := cleanupPluginUserReferences(r.db, id); err != nil {
+			log.Error(ctx, "Failed to cleanup plugin user references", "userID", id, err)
+		}
 	}
 	return nil
 }
@@ -401,7 +391,7 @@ func keyTo32Bytes(input string) []byte {
 	return data[0:]
 }
 
-func (r *userRepository) initPasswordEncryptionKey() error {
+func (r *userRepository) initPasswordEncryptionKey(ctx context.Context) error {
 	encKey = keyTo32Bytes(consts.DefaultEncryptionKey)
 	if conf.Server.PasswordEncryptionKey == "" {
 		return nil
@@ -410,8 +400,8 @@ func (r *userRepository) initPasswordEncryptionKey() error {
 	key := keyTo32Bytes(conf.Server.PasswordEncryptionKey)
 	keySum := fmt.Sprintf("%x", sha256.Sum256(key))
 
-	props := NewPropertyRepository(r.ctx, r.db)
-	savedKeySum, err := props.Get(consts.PasswordsEncryptedKey)
+	props := NewPropertyRepository(r.db)
+	savedKeySum, err := props.Get(ctx, consts.PasswordsEncryptedKey)
 
 	// If passwords are already encrypted
 	if err == nil {
@@ -425,24 +415,24 @@ func (r *userRepository) initPasswordEncryptionKey() error {
 
 	// if not, try to re-encrypt all current passwords with new encryption key,
 	// assuming they were encrypted with the DefaultEncryptionKey
-	sql := r.newSelect().Columns("id", "user_name", "password")
+	sql := r.newSelect(ctx).Columns("id", "user_name", "password")
 	users := model.Users{}
-	err = r.queryAll(sql, &users)
+	err = r.queryAll(ctx, sql, &users)
 	if err != nil {
 		log.Error("Could not encrypt all passwords", err)
 		return err
 	}
 	log.Warn("New PasswordEncryptionKey set. Encrypting all passwords", "numUsers", len(users))
-	if err = r.decryptAllPasswords(users); err != nil {
+	if err = r.decryptAllPasswords(ctx, users); err != nil {
 		return err
 	}
 	encKey = key
 	for i := range users {
 		u := users[i]
 		u.NewPassword = u.Password
-		if err := r.encryptPassword(&u); err == nil {
+		if err := r.encryptPassword(ctx, &u); err == nil {
 			upd := Update(r.tableName).Set("password", u.NewPassword).Where(Eq{"id": u.ID})
-			_, err = r.executeSQL(upd)
+			_, err = r.executeSQL(ctx, upd)
 			if err != nil {
 				log.Error("Password NOT encrypted! This may cause problems!", "user", u.UserName, "id", u.ID, err)
 			} else {
@@ -451,7 +441,7 @@ func (r *userRepository) initPasswordEncryptionKey() error {
 		}
 	}
 
-	err = props.Put(consts.PasswordsEncryptedKey, keySum)
+	err = props.Put(ctx, consts.PasswordsEncryptedKey, keySum)
 	if err != nil {
 		log.Error("Could not flag passwords as encrypted. It will cause login errors", err)
 		return err
@@ -460,10 +450,10 @@ func (r *userRepository) initPasswordEncryptionKey() error {
 }
 
 // encrypts u.NewPassword
-func (r *userRepository) encryptPassword(u *model.User) error {
-	encPassword, err := utils.Encrypt(r.ctx, encKey, u.NewPassword)
+func (r *userRepository) encryptPassword(ctx context.Context, u *model.User) error {
+	encPassword, err := utils.Encrypt(ctx, encKey, u.NewPassword)
 	if err != nil {
-		log.Error(r.ctx, "Error encrypting user's password", "user", u.UserName, err)
+		log.Error(ctx, "Error encrypting user's password", "user", u.UserName, err)
 		return err
 	}
 	u.NewPassword = encPassword
@@ -471,19 +461,19 @@ func (r *userRepository) encryptPassword(u *model.User) error {
 }
 
 // decrypts u.Password
-func (r *userRepository) decryptPassword(u *model.User) error {
-	plaintext, err := utils.Decrypt(r.ctx, encKey, u.Password)
+func (r *userRepository) decryptPassword(ctx context.Context, u *model.User) error {
+	plaintext, err := utils.Decrypt(ctx, encKey, u.Password)
 	if err != nil {
-		log.Error(r.ctx, "Error decrypting user's password", "user", u.UserName, err)
+		log.Error(ctx, "Error decrypting user's password", "user", u.UserName, err)
 		return err
 	}
 	u.Password = plaintext
 	return nil
 }
 
-func (r *userRepository) decryptAllPasswords(users model.Users) error {
+func (r *userRepository) decryptAllPasswords(ctx context.Context, users model.Users) error {
 	for i := range users {
-		if err := r.decryptPassword(&users[i]); err != nil {
+		if err := r.decryptPassword(ctx, &users[i]); err != nil {
 			return err
 		}
 	}
@@ -492,7 +482,7 @@ func (r *userRepository) decryptAllPasswords(users model.Users) error {
 
 // Library association methods
 
-func (r *userRepository) GetUserLibraries(userID string) (model.Libraries, error) {
+func (r *userRepository) GetUserLibraries(ctx context.Context, userID string) (model.Libraries, error) {
 	sel := Select("l.*").
 		From("library l").
 		Join("user_library ul ON l.id = ul.library_id").
@@ -500,14 +490,14 @@ func (r *userRepository) GetUserLibraries(userID string) (model.Libraries, error
 		OrderBy("l.name")
 
 	var res model.Libraries
-	err := r.queryAll(sel, &res)
+	err := r.queryAll(ctx, sel, &res)
 	return res, err
 }
 
-func (r *userRepository) SetUserLibraries(userID string, libraryIDs []int) error {
+func (r *userRepository) SetUserLibraries(ctx context.Context, userID string, libraryIDs []int) error {
 	// Remove existing associations
 	delSql := Delete("user_library").Where(Eq{"user_id": userID})
-	if _, err := r.executeSQL(delSql); err != nil {
+	if _, err := r.executeSQL(ctx, delSql); err != nil {
 		return err
 	}
 
@@ -517,12 +507,12 @@ func (r *userRepository) SetUserLibraries(userID string, libraryIDs []int) error
 		for _, libID := range libraryIDs {
 			insert = insert.Values(userID, libID)
 		}
-		_, err := r.executeSQL(insert)
+		_, err := r.executeSQL(ctx, insert)
 		return err
 	}
 	return nil
 }
 
 var _ model.UserRepository = (*userRepository)(nil)
-var _ rest.Repository = (*userRepository)(nil)
-var _ rest.Persistable = (*userRepository)(nil)
+var _ rest.Repository[model.User] = (*userRepository)(nil)
+var _ rest.Persistable[model.User] = (*userRepository)(nil)
diff --git a/persistence/user_repository_test.go b/persistence/user_repository_test.go
index 9a51b17dd..0e776fc3a 100644
--- a/persistence/user_repository_test.go
+++ b/persistence/user_repository_test.go
@@ -21,9 +21,11 @@ import (
 
 var _ = Describe("UserRepository", func() {
 	var repo model.UserRepository
+	var ctx context.Context
 
 	BeforeEach(func() {
-		repo = NewUserRepository(log.NewContext(GinkgoT().Context()), GetDBXBuilder())
+		ctx = log.NewContext(GinkgoT().Context())
+		repo = NewUserRepository(GetDBXBuilder())
 	})
 
 	Describe("Put/Get/FindByUsername", func() {
@@ -36,20 +38,20 @@ var _ = Describe("UserRepository", func() {
 			IsAdmin:     true,
 		}
 		It("saves the user to the DB", func() {
-			Expect(repo.Put(&usr)).To(BeNil())
+			Expect(repo.Put(ctx, &usr)).To(BeNil())
 		})
 		It("returns the newly created user", func() {
-			actual, err := repo.Get("123")
+			actual, err := repo.Get(ctx, "123")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Name).To(Equal("Admin"))
 		})
 		It("find the user by case-insensitive username", func() {
-			actual, err := repo.FindByUsername("aDmIn")
+			actual, err := repo.FindByUsername(ctx, "aDmIn")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Name).To(Equal("Admin"))
 		})
 		It("find the user by username and decrypts the password", func() {
-			actual, err := repo.FindByUsernameWithPassword("aDmIn")
+			actual, err := repo.FindByUsernameWithPassword(ctx, "aDmIn")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Name).To(Equal("Admin"))
 			Expect(actual.Password).To(Equal("wordpass"))
@@ -57,27 +59,27 @@ var _ = Describe("UserRepository", func() {
 		It("updates the name and keep the same password", func() {
 			usr.Name = "Jane Doe"
 			usr.NewPassword = ""
-			Expect(repo.Put(&usr)).To(BeNil())
+			Expect(repo.Put(ctx, &usr)).To(BeNil())
 
-			actual, err := repo.FindByUsernameWithPassword("admin")
+			actual, err := repo.FindByUsernameWithPassword(ctx, "admin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Name).To(Equal("Jane Doe"))
 			Expect(actual.Password).To(Equal("wordpass"))
 		})
 		It("updates password if specified", func() {
 			usr.NewPassword = "newpass"
-			Expect(repo.Put(&usr)).To(BeNil())
+			Expect(repo.Put(ctx, &usr)).To(BeNil())
 
-			actual, err := repo.FindByUsernameWithPassword("admin")
+			actual, err := repo.FindByUsernameWithPassword(ctx, "admin")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(actual.Password).To(Equal("newpass"))
 		})
 		It("persists and reads back the scrobble filter", func() {
 			usr := model.User{ID: "u-filter", UserName: "u-filter", Name: "Filter User",
 				ScrobbleFilter: `{"all":[{"contains":{"title":"????"}}]}`}
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
-			saved, err := repo.Get("u-filter")
+			saved, err := repo.Get(ctx, "u-filter")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(saved.ScrobbleFilter).To(Equal(`{"all":[{"contains":{"title":"????"}}]}`))
 		})
@@ -88,7 +90,7 @@ var _ = Describe("UserRepository", func() {
 					"values ('u-rawsql', 'u-rawsql', 'Raw', '', '', datetime('now'), datetime('now'))").Execute()
 			Expect(err).ToNot(HaveOccurred())
 
-			saved, err := repo.Get("u-rawsql")
+			saved, err := repo.Get(ctx, "u-rawsql")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(saved.ScrobbleFilter).To(Equal(""))
 		})
@@ -233,36 +235,34 @@ var _ = Describe("UserRepository", func() {
 	Describe("Delete", func() {
 		It("returns not found for a missing user", func() {
 			adminCtx := request.WithUser(log.NewContext(GinkgoT().Context()), adminUser)
-			adminRepo := NewUserRepository(adminCtx, GetDBXBuilder()).(*userRepository)
-			Expect(adminRepo.Delete("does-not-exist")).To(MatchError(model.ErrNotFound))
+			adminRepo := NewUserRepository(GetDBXBuilder()).(*userRepository)
+			Expect(adminRepo.Delete(adminCtx, "does-not-exist")).To(MatchError(model.ErrNotFound))
 		})
 	})
 
 	Describe("ReadAll name filter", func() {
-		var adminRepo model.ResourceRepository
+		var adminRepo model.UserRepository
+		var adminCtx context.Context
 
 		BeforeEach(func() {
-			adminCtx := request.WithUser(GinkgoT().Context(), model.User{ID: "admin-id", UserName: "admin", IsAdmin: true})
-			adminRepo = NewUserRepository(adminCtx, GetDBXBuilder()).(model.ResourceRepository)
+			adminCtx = request.WithUser(ctx, model.User{ID: "admin-id", UserName: "admin", IsAdmin: true})
+			adminRepo = NewUserRepository(GetDBXBuilder())
 
 			for _, u := range []model.User{
 				{ID: "filter-alice", UserName: "alice_filter", Name: "Alice Filter", NewPassword: "x"},
 				{ID: "filter-bob", UserName: "bob_filter", Name: "Bob Filter", NewPassword: "x"},
 			} {
-				Expect(adminRepo.(model.UserRepository).Put(&u)).To(Succeed())
+				Expect(adminRepo.Put(adminCtx, &u)).To(Succeed())
 			}
 		})
 
 		AfterEach(func() {
-			ur := adminRepo.(model.UserRepository)
-			_ = ur.Delete("filter-alice")
-			_ = ur.Delete("filter-bob")
+			_ = adminRepo.Delete(adminCtx, "filter-alice", "filter-bob")
 		})
 
 		It("matches users whose name starts with the given prefix", func() {
-			res, err := adminRepo.ReadAll(rest.QueryOptions{Filters: map[string]any{"name": "Alice"}})
+			users, err := adminRepo.ReadAll(adminCtx, rest.QueryOptions{Filters: map[string]any{"name": "Alice"}})
 			Expect(err).ToNot(HaveOccurred())
-			users := res.(model.Users)
 
 			var names []string
 			for _, u := range users {
@@ -273,9 +273,8 @@ var _ = Describe("UserRepository", func() {
 		})
 
 		It("does not match names by mid-string substring (startsWith, not contains)", func() {
-			res, err := adminRepo.ReadAll(rest.QueryOptions{Filters: map[string]any{"name": "Filter"}})
+			users, err := adminRepo.ReadAll(adminCtx, rest.QueryOptions{Filters: map[string]any{"name": "Filter"}})
 			Expect(err).ToNot(HaveOccurred())
-			users := res.(model.Users)
 
 			for _, u := range users {
 				Expect(u.ID).ToNot(Or(Equal("filter-alice"), Equal("filter-bob")),
@@ -290,17 +289,17 @@ var _ = Describe("UserRepository", func() {
 		BeforeEach(func() {
 			existingUser = &model.User{ID: "1", UserName: "johndoe"}
 			repo = tests.CreateMockUserRepo()
-			err := repo.Put(existingUser)
+			err := repo.Put(ctx, existingUser)
 			Expect(err).ToNot(HaveOccurred())
 		})
 		It("allows unique usernames", func() {
 			var newUser = &model.User{ID: "2", UserName: "unique_username"}
-			err := validateUsernameUnique(repo, newUser)
+			err := validateUsernameUnique(ctx, repo, newUser)
 			Expect(err).ToNot(HaveOccurred())
 		})
 		It("returns ValidationError if username already exists", func() {
 			var newUser = &model.User{ID: "2", UserName: "johndoe"}
-			err := validateUsernameUnique(repo, newUser)
+			err := validateUsernameUnique(ctx, repo, newUser)
 			var verr *rest.ValidationError
 			isValidationError := errors.As(err, &verr)
 
@@ -311,7 +310,7 @@ var _ = Describe("UserRepository", func() {
 			repo.Error = errors.New("fake error")
 
 			var newUser = &model.User{ID: "2", UserName: "newuser"}
-			err := validateUsernameUnique(repo, newUser)
+			err := validateUsernameUnique(ctx, repo, newUser)
 			Expect(err).To(MatchError("fake error"))
 		})
 	})
@@ -330,39 +329,39 @@ var _ = Describe("UserRepository", func() {
 				NewPassword: "password",
 				IsAdmin:     false,
 			}
-			Expect(repo.Put(&testUser)).To(BeNil())
+			Expect(repo.Put(ctx, &testUser)).To(BeNil())
 			userID = testUser.ID
 
 			library1 = model.Library{ID: 0, Name: "Library 500", Path: "/path/500"}
 			library2 = model.Library{ID: 0, Name: "Library 501", Path: "/path/501"}
 
 			// Create test libraries
-			libRepo := NewLibraryRepository(log.NewContext(context.TODO()), GetDBXBuilder())
-			Expect(libRepo.Put(&library1)).To(BeNil())
-			Expect(libRepo.Put(&library2)).To(BeNil())
+			libRepo := NewLibraryRepository(GetDBXBuilder())
+			Expect(libRepo.Put(ctx, &library1)).To(BeNil())
+			Expect(libRepo.Put(ctx, &library2)).To(BeNil())
 		})
 
 		AfterEach(func() {
 			// Clean up user-library associations to ensure test isolation
-			_ = repo.SetUserLibraries(userID, []int{})
+			_ = repo.SetUserLibraries(ctx, userID, []int{})
 
 			// Clean up test libraries to ensure isolation between test groups
-			libRepo := NewLibraryRepository(log.NewContext(context.TODO()), GetDBXBuilder())
-			_ = libRepo.(*libraryRepository).delete(squirrel.Eq{"id": []int{library1.ID, library2.ID}})
+			libRepo := NewLibraryRepository(GetDBXBuilder())
+			_ = libRepo.(*libraryRepository).delete(ctx, squirrel.Eq{"id": []int{library1.ID, library2.ID}})
 		})
 
 		Describe("GetUserLibraries", func() {
 			It("returns empty list when user has no library associations", func() {
-				libraries, err := repo.GetUserLibraries("non-existent-user")
+				libraries, err := repo.GetUserLibraries(ctx, "non-existent-user")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(libraries).To(HaveLen(0))
 			})
 
 			It("returns user's associated libraries", func() {
-				err := repo.SetUserLibraries(userID, []int{library1.ID, library2.ID})
+				err := repo.SetUserLibraries(ctx, userID, []int{library1.ID, library2.ID})
 				Expect(err).ToNot(HaveOccurred())
 
-				libraries, err := repo.GetUserLibraries(userID)
+				libraries, err := repo.GetUserLibraries(ctx, userID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(libraries).To(HaveLen(2))
 
@@ -374,24 +373,24 @@ var _ = Describe("UserRepository", func() {
 		Describe("SetUserLibraries", func() {
 			It("sets user's library associations", func() {
 				libraryIDs := []int{library1.ID, library2.ID}
-				err := repo.SetUserLibraries(userID, libraryIDs)
+				err := repo.SetUserLibraries(ctx, userID, libraryIDs)
 				Expect(err).ToNot(HaveOccurred())
 
-				libraries, err := repo.GetUserLibraries(userID)
+				libraries, err := repo.GetUserLibraries(ctx, userID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(libraries).To(HaveLen(2))
 			})
 
 			It("replaces existing associations", func() {
 				// Set initial associations
-				err := repo.SetUserLibraries(userID, []int{library1.ID, library2.ID})
+				err := repo.SetUserLibraries(ctx, userID, []int{library1.ID, library2.ID})
 				Expect(err).ToNot(HaveOccurred())
 
 				// Replace with just one library
-				err = repo.SetUserLibraries(userID, []int{library1.ID})
+				err = repo.SetUserLibraries(ctx, userID, []int{library1.ID})
 				Expect(err).ToNot(HaveOccurred())
 
-				libraries, err := repo.GetUserLibraries(userID)
+				libraries, err := repo.GetUserLibraries(ctx, userID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(libraries).To(HaveLen(1))
 				Expect(libraries[0].ID).To(Equal(library1.ID))
@@ -399,14 +398,14 @@ var _ = Describe("UserRepository", func() {
 
 			It("removes all associations when passed empty slice", func() {
 				// Set initial associations
-				err := repo.SetUserLibraries(userID, []int{library1.ID, library2.ID})
+				err := repo.SetUserLibraries(ctx, userID, []int{library1.ID, library2.ID})
 				Expect(err).ToNot(HaveOccurred())
 
 				// Remove all
-				err = repo.SetUserLibraries(userID, []int{})
+				err = repo.SetUserLibraries(ctx, userID, []int{})
 				Expect(err).ToNot(HaveOccurred())
 
-				libraries, err := repo.GetUserLibraries(userID)
+				libraries, err := repo.GetUserLibraries(ctx, userID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(libraries).To(HaveLen(0))
 			})
@@ -422,10 +421,10 @@ var _ = Describe("UserRepository", func() {
 		)
 
 		BeforeEach(func() {
-			libRepo = NewLibraryRepository(log.NewContext(context.TODO()), GetDBXBuilder())
+			libRepo = NewLibraryRepository(GetDBXBuilder())
 
 			// Count initial libraries
-			existingLibs, err := libRepo.GetAll()
+			existingLibs, err := libRepo.GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			initialLibCount = len(existingLibs)
 
@@ -433,16 +432,16 @@ var _ = Describe("UserRepository", func() {
 			library2 = model.Library{ID: 0, Name: "Admin Test Library 2", Path: "/admin/test/path2"}
 
 			// Create test libraries
-			Expect(libRepo.Put(&library1)).To(BeNil())
-			Expect(libRepo.Put(&library2)).To(BeNil())
+			Expect(libRepo.Put(ctx, &library1)).To(BeNil())
+			Expect(libRepo.Put(ctx, &library2)).To(BeNil())
 		})
 
 		AfterEach(func() {
 			// Clean up test libraries and their associations
-			_ = libRepo.(*libraryRepository).delete(squirrel.Eq{"id": []int{library1.ID, library2.ID}})
+			_ = libRepo.(*libraryRepository).delete(ctx, squirrel.Eq{"id": []int{library1.ID, library2.ID}})
 
 			// Clean up user-library associations for these test libraries
-			_, _ = repo.(*userRepository).executeSQL(squirrel.Delete("user_library").Where(squirrel.Eq{"library_id": []int{library1.ID, library2.ID}}))
+			_, _ = repo.(*userRepository).executeSQL(ctx, squirrel.Delete("user_library").Where(squirrel.Eq{"library_id": []int{library1.ID, library2.ID}}))
 		})
 
 		It("automatically assigns all libraries to admin users when created", func() {
@@ -455,11 +454,11 @@ var _ = Describe("UserRepository", func() {
 				IsAdmin:     true,
 			}
 
-			err := repo.Put(&adminUser)
+			err := repo.Put(ctx, &adminUser)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Admin should automatically have access to all libraries (including existing ones)
-			libraries, err := repo.GetUserLibraries(adminUser.ID)
+			libraries, err := repo.GetUserLibraries(ctx, adminUser.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(libraries).To(HaveLen(initialLibCount + 2)) // Initial libraries + our 2 test libraries
 
@@ -481,20 +480,20 @@ var _ = Describe("UserRepository", func() {
 				IsAdmin:     false,
 			}
 
-			err := repo.Put(&regularUser)
+			err := repo.Put(ctx, &regularUser)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Give them access to just one library
-			err = repo.SetUserLibraries(regularUser.ID, []int{library1.ID})
+			err = repo.SetUserLibraries(ctx, regularUser.ID, []int{library1.ID})
 			Expect(err).ToNot(HaveOccurred())
 
 			// Promote to admin
 			regularUser.IsAdmin = true
-			err = repo.Put(&regularUser)
+			err = repo.Put(ctx, &regularUser)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Should now have access to all libraries (including existing ones)
-			libraries, err := repo.GetUserLibraries(regularUser.ID)
+			libraries, err := repo.GetUserLibraries(ctx, regularUser.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(libraries).To(HaveLen(initialLibCount + 2)) // Initial libraries + our 2 test libraries
 
@@ -516,11 +515,11 @@ var _ = Describe("UserRepository", func() {
 				IsAdmin:     false,
 			}
 
-			err := repo.Put(&regularUser)
+			err := repo.Put(ctx, &regularUser)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Regular user should be assigned to default libraries (library ID 1 from migration)
-			libraries, err := repo.GetUserLibraries(regularUser.ID)
+			libraries, err := repo.GetUserLibraries(ctx, regularUser.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(libraries).To(HaveLen(1))
 			Expect(libraries[0].ID).To(Equal(1))
@@ -537,13 +536,13 @@ var _ = Describe("UserRepository", func() {
 		)
 
 		BeforeEach(func() {
-			libRepo = NewLibraryRepository(log.NewContext(context.TODO()), GetDBXBuilder())
+			libRepo = NewLibraryRepository(GetDBXBuilder())
 			library1 = model.Library{ID: 0, Name: "Field Test Library 1", Path: "/field/test/path1"}
 			library2 = model.Library{ID: 0, Name: "Field Test Library 2", Path: "/field/test/path2"}
 
 			// Create test libraries
-			Expect(libRepo.Put(&library1)).To(BeNil())
-			Expect(libRepo.Put(&library2)).To(BeNil())
+			Expect(libRepo.Put(ctx, &library1)).To(BeNil())
+			Expect(libRepo.Put(ctx, &library2)).To(BeNil())
 
 			// Create test user
 			testUser = model.User{
@@ -554,23 +553,23 @@ var _ = Describe("UserRepository", func() {
 				NewPassword: "password",
 				IsAdmin:     false,
 			}
-			Expect(repo.Put(&testUser)).To(BeNil())
+			Expect(repo.Put(ctx, &testUser)).To(BeNil())
 
 			// Assign libraries to user
-			Expect(repo.SetUserLibraries(testUser.ID, []int{library1.ID, library2.ID})).To(BeNil())
+			Expect(repo.SetUserLibraries(ctx, testUser.ID, []int{library1.ID, library2.ID})).To(BeNil())
 		})
 
 		AfterEach(func() {
 			// Clean up test libraries and their associations
-			_ = libRepo.(*libraryRepository).delete(squirrel.Eq{"id": []int{library1.ID, library2.ID}})
-			_ = repo.(*userRepository).delete(squirrel.Eq{"id": testUser.ID})
+			_ = libRepo.(*libraryRepository).delete(ctx, squirrel.Eq{"id": []int{library1.ID, library2.ID}})
+			_ = repo.(*userRepository).delete(ctx, squirrel.Eq{"id": testUser.ID})
 
 			// Clean up user-library associations for these test libraries
-			_, _ = repo.(*userRepository).executeSQL(squirrel.Delete("user_library").Where(squirrel.Eq{"library_id": []int{library1.ID, library2.ID}}))
+			_, _ = repo.(*userRepository).executeSQL(ctx, squirrel.Delete("user_library").Where(squirrel.Eq{"library_id": []int{library1.ID, library2.ID}}))
 		})
 
 		It("populates Libraries field when getting a single user", func() {
-			user, err := repo.Get(testUser.ID)
+			user, err := repo.Get(ctx, testUser.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(user.Libraries).To(HaveLen(2))
 
@@ -591,7 +590,7 @@ var _ = Describe("UserRepository", func() {
 		})
 
 		It("populates Libraries field when getting all users", func() {
-			users, err := repo.(*userRepository).GetAll()
+			users, err := repo.(*userRepository).GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Find our test user in the results
@@ -607,7 +606,7 @@ var _ = Describe("UserRepository", func() {
 		})
 
 		It("populates Libraries field when finding user by username", func() {
-			user, err := repo.FindByUsername(testUser.UserName)
+			user, err := repo.FindByUsername(ctx, testUser.UserName)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(user.Libraries).To(HaveLen(2))
 
@@ -625,10 +624,10 @@ var _ = Describe("UserRepository", func() {
 				NewPassword: "password",
 				IsAdmin:     false,
 			}
-			Expect(repo.Put(&userWithoutLibs)).To(BeNil())
-			defer func() { _ = repo.(*userRepository).delete(squirrel.Eq{"id": userWithoutLibs.ID}) }()
+			Expect(repo.Put(ctx, &userWithoutLibs)).To(BeNil())
+			defer func() { _ = repo.(*userRepository).delete(ctx, squirrel.Eq{"id": userWithoutLibs.ID}) }()
 
-			user, err := repo.Get(userWithoutLibs.ID)
+			user, err := repo.Get(ctx, userWithoutLibs.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(user.Libraries).ToNot(BeNil())
 			// Regular users should be assigned to default libraries (library ID 1 from migration)
@@ -686,8 +685,8 @@ var _ = Describe("UserRepository", func() {
 	Describe("filters", func() {
 		It("qualifies id filter with table name", func() {
 			r := repo.(*userRepository)
-			qo := r.parseRestOptions(r.ctx, rest.QueryOptions{Filters: map[string]any{"id": "123"}})
-			sel := r.selectUserWithLibraries(qo)
+			qo := r.parseRestOptions(ctx, rest.QueryOptions{Filters: map[string]any{"id": "123"}})
+			sel := r.selectUserWithLibraries(ctx, qo)
 			query, _, err := r.toSQL(sel)
 			Expect(err).NotTo(HaveOccurred())
 			Expect(query).To(ContainSubstring("user.id = {:p0}"))
@@ -705,29 +704,28 @@ var _ = Describe("UserRepository", func() {
 		}
 
 		BeforeEach(func() {
-			ctx := log.NewContext(context.TODO())
 			ctx = request.WithUser(ctx, model.User{ID: "userid", IsAdmin: true})
-			repo = NewUserRepository(ctx, GetDBXBuilder())
+			repo = NewUserRepository(GetDBXBuilder())
 			usr = newUser()
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 		})
 
 		It("starts at zero for a new user", func() {
-			got, err := repo.Get(usr.ID)
+			got, err := repo.Get(ctx, usr.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.TokenEpoch).To(Equal(0))
 		})
 
 		It("increments once per password change", func() {
 			usr.NewPassword = "second"
-			Expect(repo.Put(&usr)).To(Succeed())
-			got, err := repo.Get(usr.ID)
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
+			got, err := repo.Get(ctx, usr.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.TokenEpoch).To(Equal(1))
 
 			usr.NewPassword = "third"
-			Expect(repo.Put(&usr)).To(Succeed())
-			got, err = repo.Get(usr.ID)
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
+			got, err = repo.Get(ctx, usr.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.TokenEpoch).To(Equal(2))
 		})
@@ -735,9 +733,9 @@ var _ = Describe("UserRepository", func() {
 		It("leaves the epoch alone when the password is untouched", func() {
 			usr.NewPassword = ""
 			usr.Name = "Renamed"
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
-			got, err := repo.Get(usr.ID)
+			got, err := repo.Get(ctx, usr.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.TokenEpoch).To(Equal(0))
 			Expect(got.Name).To(Equal("Renamed"))
@@ -754,11 +752,11 @@ var _ = Describe("UserRepository", func() {
 					ctx := log.NewContext(context.TODO())
 					ctx = request.WithUser(ctx, model.User{ID: usr.ID})
 					ctx = request.WithTokenEpochHolder(ctx)
-					own := NewUserRepository(ctx, GetDBXBuilder())
+					own := NewUserRepository(GetDBXBuilder())
 
 					u := usr
 					u.NewPassword = "concurrent"
-					if err := own.Put(&u); err != nil {
+					if err := own.Put(ctx, &u); err != nil {
 						return // the shared in-memory test DB can raise SQLITE_LOCKED
 					}
 					epoch, ok := request.TokenEpochFrom(ctx)
@@ -778,73 +776,73 @@ var _ = Describe("UserRepository", func() {
 	})
 
 	Describe("Put and the token epoch", func() {
-		newRepo := func(actingUserID string) model.UserRepository {
+		newRepo := func(actingUserID string) (context.Context, model.UserRepository) {
 			ctx := log.NewContext(context.TODO())
 			ctx = request.WithUser(ctx, model.User{ID: actingUserID, IsAdmin: true})
 			ctx = request.WithTokenEpochHolder(ctx)
-			return NewUserRepository(ctx, GetDBXBuilder())
+			return ctx, NewUserRepository(GetDBXBuilder())
 		}
 
 		It("does not bump when creating a user", func() {
-			repo := newRepo("admin")
+			ctx, repo := newRepo("admin")
 			usr := model.User{ID: id.NewRandom(), UserName: "fresh", NewPassword: "pw1"}
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
-			got, err := repo.Get(usr.ID)
+			got, err := repo.Get(ctx, usr.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.TokenEpoch).To(Equal(0))
 		})
 
 		It("bumps when the password changes", func() {
-			repo := newRepo("admin")
+			ctx, repo := newRepo("admin")
 			usr := model.User{ID: id.NewRandom(), UserName: "changer", NewPassword: "pw1"}
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
 			usr.NewPassword = "pw2"
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
-			got, err := repo.Get(usr.ID)
+			got, err := repo.Get(ctx, usr.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.TokenEpoch).To(Equal(1))
 		})
 
 		It("does not bump on an edit that leaves the password alone", func() {
-			repo := newRepo("admin")
+			ctx, repo := newRepo("admin")
 			usr := model.User{ID: id.NewRandom(), UserName: "renamer", NewPassword: "pw1"}
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
 			usr.NewPassword = ""
 			usr.Name = "New Display Name"
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
-			got, err := repo.Get(usr.ID)
+			got, err := repo.Get(ctx, usr.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(got.TokenEpoch).To(Equal(0))
 		})
 
 		It("signals the new epoch when a user changes their own password", func() {
 			userID := id.NewRandom()
-			repo := newRepo(userID)
+			ctx, repo := newRepo(userID)
 			usr := model.User{ID: userID, UserName: "self", NewPassword: "pw1"}
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
 			usr.NewPassword = "pw2"
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
-			epoch, ok := request.TokenEpochFrom(repo.(*userRepository).ctx)
+			epoch, ok := request.TokenEpochFrom(ctx)
 			Expect(ok).To(BeTrue())
 			Expect(epoch).To(Equal(1))
 		})
 
 		It("does not signal when an admin changes someone else's password", func() {
-			repo := newRepo("some-admin")
+			ctx, repo := newRepo("some-admin")
 			usr := model.User{ID: id.NewRandom(), UserName: "other", NewPassword: "pw1"}
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
 			usr.NewPassword = "pw2"
-			Expect(repo.Put(&usr)).To(Succeed())
+			Expect(repo.Put(ctx, &usr)).To(Succeed())
 
-			_, ok := request.TokenEpochFrom(repo.(*userRepository).ctx)
+			_, ok := request.TokenEpochFrom(ctx)
 			Expect(ok).To(BeFalse())
 		})
 	})
diff --git a/plugins/host_library.go b/plugins/host_library.go
index 3d9f61b4f..25c14a813 100644
--- a/plugins/host_library.go
+++ b/plugins/host_library.go
@@ -37,7 +37,7 @@ func (s *libraryServiceImpl) GetLibrary(ctx context.Context, id int32) (*host.Li
 		return nil, fmt.Errorf("library not accessible: library ID %d is not in the allowed list", id)
 	}
 
-	lib, err := s.ds.Library(ctx).Get(int(id))
+	lib, err := s.ds.Library().Get(ctx, int(id))
 	if err != nil {
 		return nil, fmt.Errorf("library not found: %w", err)
 	}
@@ -55,7 +55,7 @@ func (s *libraryServiceImpl) isLibraryAccessible(id int) bool {
 }
 
 func (s *libraryServiceImpl) GetAllLibraries(ctx context.Context) ([]host.Library, error) {
-	libs, err := s.ds.Library(ctx).GetAll()
+	libs, err := s.ds.Library().GetAll(ctx)
 	if err != nil {
 		return nil, fmt.Errorf("failed to get libraries: %w", err)
 	}
diff --git a/plugins/host_library_test.go b/plugins/host_library_test.go
index 00a953b24..edd4b546f 100644
--- a/plugins/host_library_test.go
+++ b/plugins/host_library_test.go
@@ -47,7 +47,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 			}
 			lib.LastScanAt = lib.LastScanAt.Add(0) // Ensure time is set
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(model.Libraries{*lib})
 
 			result, err := service.GetLibrary(ctx, 1)
@@ -77,7 +77,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 				TotalDuration: 1800.0,
 			}
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(model.Libraries{*lib})
 
 			result, err := service.GetLibrary(ctx, 2)
@@ -91,7 +91,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 		It("should return error for non-existent library", func() {
 			service = newLibraryService(ds, &LibraryPermission{Reason: new("test")}, nil, true).(*libraryServiceImpl)
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(model.Libraries{})
 
 			_, err := service.GetLibrary(ctx, 999)
@@ -109,7 +109,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 				{ID: 2, Name: "Jazz", Path: "/music/jazz", TotalSongs: 50},
 			}
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(libs)
 
 			results, err := service.GetAllLibraries(ctx)
@@ -131,7 +131,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 				{ID: 2, Name: "Jazz", Path: "/music/jazz", TotalSongs: 50},
 			}
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(libs)
 
 			results, err := service.GetAllLibraries(ctx)
@@ -154,7 +154,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 				{ID: 3, Name: "Classical", Path: "/music/classical", TotalSongs: 75},
 			}
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(libs)
 
 			results, err := service.GetAllLibraries(ctx)
@@ -172,7 +172,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 				{ID: 2, Name: "Jazz", Path: "/music/jazz", TotalSongs: 50},
 			}
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(libs)
 
 			// Requesting library 1 which is not in the allowed list
@@ -189,7 +189,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 				{ID: 2, Name: "Jazz", Path: "/music/jazz", TotalSongs: 50},
 			}
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(libs)
 
 			result, err := service.GetLibrary(ctx, 2)
@@ -206,7 +206,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 				{ID: 2, Name: "Jazz", Path: "/music/jazz", TotalSongs: 50},
 			}
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(libs)
 
 			results, err := service.GetAllLibraries(ctx)
@@ -222,7 +222,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 				{ID: 2, Name: "Jazz", Path: "/music/jazz", TotalSongs: 50},
 			}
 
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(libs)
 
 			results, err := service.GetAllLibraries(ctx)
@@ -291,7 +291,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 			Expect(manager.ds).ToNot(BeNil())
 
 			ctx := context.Background()
-			libs, err := manager.ds.Library(adminContext(ctx)).GetAll()
+			libs, err := manager.ds.Library().GetAll(adminContext(ctx))
 			Expect(err).ToNot(HaveOccurred())
 			Expect(libs).To(HaveLen(1))
 			Expect(libs[0].Path).To(Equal("/tmp/test-music"))
diff --git a/plugins/host_matcher_test.go b/plugins/host_matcher_test.go
index f0967628c..7d3e47fae 100644
--- a/plugins/host_matcher_test.go
+++ b/plugins/host_matcher_test.go
@@ -193,7 +193,7 @@ var _ = Describe("MatcherService", Ordered, func() {
 				mediaFileRepo.SetData(model.MediaFiles{mf})
 
 				userRepo = tests.CreateMockUserRepo()
-				Expect(userRepo.Put(&model.User{ID: "u-alice", UserName: "alice"})).To(Succeed())
+				Expect(userRepo.Put(GinkgoT().Context(), &model.User{ID: "u-alice", UserName: "alice"})).To(Succeed())
 
 				ds = &tests.MockDataStore{MockedMediaFile: mediaFileRepo, MockedUser: userRepo}
 			})
@@ -269,7 +269,7 @@ var _ = Describe("MatcherService", Ordered, func() {
 				_, err := svc.MatchSongs(callerCtx, input, host.MatchOptions{})
 				Expect(err).ToNot(HaveOccurred())
 
-				usr, ok := request.UserFrom(capturing.lastMediaFileCtx)
+				usr, ok := request.UserFrom(capturing.lastMediaFileCtx())
 				Expect(ok).To(BeTrue())
 				Expect(usr.IsAdmin).To(BeTrue())
 				Expect(usr.ID).ToNot(Equal("u-caller"))
@@ -283,7 +283,7 @@ var _ = Describe("MatcherService", Ordered, func() {
 				_, err := svc.MatchSongs(callerCtx, input, host.MatchOptions{Username: "alice"})
 				Expect(err).ToNot(HaveOccurred())
 
-				usr, ok := request.UserFrom(capturing.lastMediaFileCtx)
+				usr, ok := request.UserFrom(capturing.lastMediaFileCtx())
 				Expect(ok).To(BeTrue())
 				Expect(usr.ID).To(Equal("u-alice"))
 			})
@@ -395,7 +395,7 @@ var _ = Describe("MatcherService Integration", Ordered, func() {
 		mediaFileRepo.SetData(model.MediaFiles{hit})
 
 		userRepo := tests.CreateMockUserRepo()
-		Expect(userRepo.Put(&model.User{ID: "u-alice", UserName: "alice"})).To(Succeed())
+		Expect(userRepo.Put(GinkgoT().Context(), &model.User{ID: "u-alice", UserName: "alice"})).To(Succeed())
 
 		dataStore := &tests.MockDataStore{
 			MockedPlugin:    mockPluginRepo,
@@ -475,14 +475,38 @@ var _ = Describe("MatcherService Integration", Ordered, func() {
 	})
 })
 
-// ctxCapturingDataStore records the context passed to MediaFile so tests can assert
-// which user the matcher resolved before querying the library.
+// ctxCapturingDataStore records the context the media file queries run with, so tests
+// can assert which user the matcher resolved before querying the library.
 type ctxCapturingDataStore struct {
 	*tests.MockDataStore
-	lastMediaFileCtx context.Context
+	repo *ctxCapturingMediaFileRepo
 }
 
-func (d *ctxCapturingDataStore) MediaFile(ctx context.Context) model.MediaFileRepository {
-	d.lastMediaFileCtx = ctx
-	return d.MockDataStore.MediaFile(ctx)
+func (d *ctxCapturingDataStore) MediaFile() model.MediaFileRepository {
+	if d.repo == nil {
+		d.repo = &ctxCapturingMediaFileRepo{MediaFileRepository: d.MockDataStore.MediaFile()}
+	}
+	return d.repo
+}
+
+func (d *ctxCapturingDataStore) lastMediaFileCtx() context.Context {
+	if d.repo == nil {
+		return nil
+	}
+	return d.repo.lastCtx
+}
+
+type ctxCapturingMediaFileRepo struct {
+	model.MediaFileRepository
+	lastCtx context.Context
+}
+
+func (r *ctxCapturingMediaFileRepo) GetAll(ctx context.Context, options ...model.QueryOptions) (model.MediaFiles, error) {
+	r.lastCtx = ctx
+	return r.MediaFileRepository.GetAll(ctx, options...)
+}
+
+func (r *ctxCapturingMediaFileRepo) GetAllByTags(ctx context.Context, tag model.TagName, values []string, options ...model.QueryOptions) (model.MediaFiles, error) {
+	r.lastCtx = ctx
+	return r.MediaFileRepository.GetAllByTags(ctx, tag, values, options...)
 }
diff --git a/plugins/host_scrobbleretriever.go b/plugins/host_scrobbleretriever.go
index 7417d7c50..780b0274d 100644
--- a/plugins/host_scrobbleretriever.go
+++ b/plugins/host_scrobbleretriever.go
@@ -41,7 +41,7 @@ func (s *scrobbleRetrieverServiceImpl) getFirstLastScrobble(ctx context.Context,
 		return nil, err
 	}
 
-	scrobbles, err := s.ds.Scrobble(ctx).GetAll(model.QueryOptions{Sort: "submission_time", Order: order, Max: 1})
+	scrobbles, err := s.ds.Scrobble().GetAll(ctx, model.QueryOptions{Sort: "submission_time", Order: order, Max: 1})
 	if err != nil {
 		return nil, err
 	}
@@ -80,7 +80,7 @@ func (s *scrobbleRetrieverServiceImpl) GetScrobbles(ctx context.Context, usernam
 	// Fetch one more item than requested. The last item is the next timestamp to fetch
 	lookahead := options.MaxItems + 1
 
-	scrobbles, err := s.ds.Scrobble(ctx).GetAll(model.QueryOptions{
+	scrobbles, err := s.ds.Scrobble().GetAll(ctx, model.QueryOptions{
 		Max:     lookahead,
 		Filters: scrobbleRangeFilters(options.FromTimestamp, options.ToTimestamp),
 		// The id tiebreak makes the order of equal timestamps stable, which is what
@@ -142,7 +142,7 @@ func (s *scrobbleRetrieverServiceImpl) GetScrobbleCount(ctx context.Context, use
 		return 0, err
 	}
 
-	return s.ds.Scrobble(ctx).CountAll(model.QueryOptions{
+	return s.ds.Scrobble().CountAll(ctx, model.QueryOptions{
 		Filters: scrobbleRangeFilters(options.FromTimestamp, options.ToTimestamp),
 	})
 }
diff --git a/plugins/host_scrobbleretriever_test.go b/plugins/host_scrobbleretriever_test.go
index aa92c9eb5..6721c1487 100644
--- a/plugins/host_scrobbleretriever_test.go
+++ b/plugins/host_scrobbleretriever_test.go
@@ -75,36 +75,36 @@ var _ = Describe("Scrobble Retriever Host Function", Ordered, func() {
 		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
 
-		userRepo := dataStore.User(ctx)
+		userRepo := dataStore.User()
 		// Add test users
-		_ = userRepo.Put(&model.User{
+		_ = userRepo.Put(ctx, &model.User{
 			ID:       "user1",
 			UserName: "testuser",
 			IsAdmin:  false,
 		})
-		_ = userRepo.Put(&model.User{
+		_ = userRepo.Put(ctx, &model.User{
 			ID:       "admin1",
 			UserName: "adminuser",
 			IsAdmin:  true,
 		})
 
-		err = dataStore.MediaFile(ctx).Put(&model.MediaFile{ID: "1", LibraryID: 1})
+		err = dataStore.MediaFile().Put(ctx, &model.MediaFile{ID: "1", LibraryID: 1})
 		Expect(err).To(BeNil())
-		err = dataStore.MediaFile(ctx).Put(&model.MediaFile{ID: "2", LibraryID: 1})
+		err = dataStore.MediaFile().Put(ctx, &model.MediaFile{ID: "2", LibraryID: 1})
 		Expect(err).To(BeNil())
-		err = dataStore.MediaFile(ctx).Put(&model.MediaFile{ID: "3", LibraryID: 1})
+		err = dataStore.MediaFile().Put(ctx, &model.MediaFile{ID: "3", LibraryID: 1})
 		Expect(err).To(BeNil())
 
 		scrobbleCtx := request.WithUser(GinkgoT().Context(), model.User{ID: "admin1", UserName: "adminuser"})
 
-		scrobbleRepo := dataStore.Scrobble(scrobbleCtx)
-		err = scrobbleRepo.RecordScrobble("1", time.Unix(0, 0))
+		scrobbleRepo := dataStore.Scrobble()
+		err = scrobbleRepo.RecordScrobble(scrobbleCtx, "1", time.Unix(0, 0))
 		Expect(err).To(BeNil())
-		err = scrobbleRepo.RecordScrobble("2", time.Unix(1, 0))
+		err = scrobbleRepo.RecordScrobble(scrobbleCtx, "2", time.Unix(1, 0))
 		Expect(err).To(BeNil())
-		err = scrobbleRepo.RecordScrobble("3", time.Unix(2, 0))
+		err = scrobbleRepo.RecordScrobble(scrobbleCtx, "3", time.Unix(2, 0))
 		Expect(err).To(BeNil())
-		err = scrobbleRepo.RecordScrobble("1", time.Unix(2, 0))
+		err = scrobbleRepo.RecordScrobble(scrobbleCtx, "1", time.Unix(2, 0))
 		Expect(err).To(BeNil())
 
 		// Create and configure manager
@@ -125,7 +125,7 @@ var _ = Describe("Scrobble Retriever Host Function", Ordered, func() {
 
 		dataStore.MockedPlugin = tests.CreateMockPluginRepo()
 
-		mockPluginRepo := dataStore.Plugin(GinkgoT().Context()).(*tests.MockPluginRepo)
+		mockPluginRepo := dataStore.Plugin().(*tests.MockPluginRepo)
 		mockPluginRepo.Permitted = true
 		enabledPlugin := model.Plugin{
 			ID:      "test-scrobble-retriever",
@@ -300,10 +300,10 @@ var _ = Describe("Scrobble Retriever Host Function", Ordered, func() {
 		BeforeAll(func() {
 			scrobbleCtx := request.WithUser(GinkgoT().Context(), model.User{ID: "admin1", UserName: "adminuser"})
 
-			scrobbleRepo := dataStore.Scrobble(scrobbleCtx)
+			scrobbleRepo := dataStore.Scrobble()
 
 			for i := range 5 {
-				err := scrobbleRepo.RecordScrobble("3", time.Unix(100, 0))
+				err := scrobbleRepo.RecordScrobble(scrobbleCtx, "3", time.Unix(100, 0))
 				Expect(err).To(BeNil())
 
 				scrobble := host.ScrobbleRef{ID: 5 + int64(i), MediaFileID: "3", SubmissionTime: 100}
diff --git a/plugins/host_storage_test.go b/plugins/host_storage_test.go
index 9fc58c396..9d8df23a0 100644
--- a/plugins/host_storage_test.go
+++ b/plugins/host_storage_test.go
@@ -85,7 +85,7 @@ var _ = Describe("Storage Host Function", Ordered, func() {
 		}
 		manager.SetSubsonicRouter(router)
 
-		mockPluginRepo := dataStore.Plugin(GinkgoT().Context()).(*tests.MockPluginRepo)
+		mockPluginRepo := dataStore.Plugin().(*tests.MockPluginRepo)
 		mockPluginRepo.Permitted = true
 
 		// Setup config
diff --git a/plugins/host_subsonicapi.go b/plugins/host_subsonicapi.go
index dba58d795..a8ff12140 100644
--- a/plugins/host_subsonicapi.go
+++ b/plugins/host_subsonicapi.go
@@ -138,7 +138,7 @@ func (s *subsonicAPIServiceImpl) checkPermissions(ctx context.Context, username
 	}
 
 	// Look up the user by username to get their ID
-	usr, err := s.ds.User(ctx).FindByUsername(username)
+	usr, err := s.ds.User().FindByUsername(ctx, username)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
 			return fmt.Errorf("username %s not found", username)
diff --git a/plugins/host_subsonicapi_test.go b/plugins/host_subsonicapi_test.go
index 4b941bc43..0d9c75ee7 100644
--- a/plugins/host_subsonicapi_test.go
+++ b/plugins/host_subsonicapi_test.go
@@ -1,6 +1,7 @@
 package plugins
 
 import (
+	"context"
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
@@ -51,12 +52,12 @@ var _ = Describe("SubsonicAPI Host Function", Ordered, func() {
 		dataStore = &tests.MockDataStore{MockedUser: userRepo}
 
 		// Add test users
-		_ = userRepo.Put(&model.User{
+		_ = userRepo.Put(GinkgoT().Context(), &model.User{
 			ID:       "user1",
 			UserName: "testuser",
 			IsAdmin:  false,
 		})
-		_ = userRepo.Put(&model.User{
+		_ = userRepo.Put(GinkgoT().Context(), &model.User{
 			ID:       "admin1",
 			UserName: "adminuser",
 			IsAdmin:  true,
@@ -77,7 +78,7 @@ var _ = Describe("SubsonicAPI Host Function", Ordered, func() {
 		hash := sha256.Sum256(wasmData)
 		hashHex := hex.EncodeToString(hash[:])
 
-		mockPluginRepo := dataStore.Plugin(GinkgoT().Context()).(*tests.MockPluginRepo)
+		mockPluginRepo := dataStore.Plugin().(*tests.MockPluginRepo)
 		mockPluginRepo.Permitted = true
 		enabledPlugin := model.Plugin{
 			ID:       "test-subsonicapi-plugin",
@@ -234,27 +235,29 @@ var _ = Describe("SubsonicAPI Host Function", Ordered, func() {
 
 var _ = Describe("SubsonicAPIService", func() {
 	var (
+		ctx       context.Context
 		router    *fakeSubsonicRouter
 		userRepo  *tests.MockedUserRepo
 		dataStore *tests.MockDataStore
 	)
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		router = &fakeSubsonicRouter{}
 		userRepo = tests.CreateMockUserRepo()
 		dataStore = &tests.MockDataStore{MockedUser: userRepo}
 
-		_ = userRepo.Put(&model.User{
+		_ = userRepo.Put(ctx, &model.User{
 			ID:       "user1",
 			UserName: "testuser",
 			IsAdmin:  false,
 		})
-		_ = userRepo.Put(&model.User{
+		_ = userRepo.Put(ctx, &model.User{
 			ID:       "admin1",
 			UserName: "adminuser",
 			IsAdmin:  true,
 		})
-		_ = userRepo.Put(&model.User{
+		_ = userRepo.Put(ctx, &model.User{
 			ID:       "user2",
 			UserName: "alloweduser",
 			IsAdmin:  false,
@@ -267,7 +270,6 @@ var _ = Describe("SubsonicAPIService", func() {
 				// allowedUserIDs contains "user2", but testuser is "user1"
 				service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user2"}, false))
 
-				ctx := GinkgoT().Context()
 				_, err := service.Call(ctx, "/ping?u=testuser")
 				Expect(err).To(HaveOccurred())
 				Expect(err.Error()).To(ContainSubstring("not authorized"))
@@ -277,7 +279,6 @@ var _ = Describe("SubsonicAPIService", func() {
 				// allowedUserIDs contains "user2" which is "alloweduser"
 				service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user2"}, false))
 
-				ctx := GinkgoT().Context()
 				response, err := service.Call(ctx, "/ping?u=alloweduser")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(response).To(ContainSubstring("ok"))
@@ -287,7 +288,6 @@ var _ = Describe("SubsonicAPIService", func() {
 				// allowedUserIDs only contains "user1" (testuser), not "admin1"
 				service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user1"}, false))
 
-				ctx := GinkgoT().Context()
 				_, err := service.Call(ctx, "/ping?u=adminuser")
 				Expect(err).To(HaveOccurred())
 				Expect(err.Error()).To(ContainSubstring("not authorized"))
@@ -297,7 +297,6 @@ var _ = Describe("SubsonicAPIService", func() {
 				// allowedUserIDs contains "admin1"
 				service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"admin1"}, false))
 
-				ctx := GinkgoT().Context()
 				response, err := service.Call(ctx, "/ping?u=adminuser")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(response).To(ContainSubstring("ok"))
@@ -308,7 +307,6 @@ var _ = Describe("SubsonicAPIService", func() {
 			It("allows all users regardless of allowed list", func() {
 				service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))
 
-				ctx := GinkgoT().Context()
 				response, err := service.Call(ctx, "/ping?u=testuser")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(response).To(ContainSubstring("ok"))
@@ -317,7 +315,6 @@ var _ = Describe("SubsonicAPIService", func() {
 			It("allows admin users when allUsers is true", func() {
 				service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))
 
-				ctx := GinkgoT().Context()
 				response, err := service.Call(ctx, "/ping?u=adminuser")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(response).To(ContainSubstring("ok"))
@@ -328,7 +325,6 @@ var _ = Describe("SubsonicAPIService", func() {
 			It("returns error when no users are configured", func() {
 				service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, false))
 
-				ctx := GinkgoT().Context()
 				_, err := service.Call(ctx, "/ping?u=testuser")
 				Expect(err).To(HaveOccurred())
 				Expect(err.Error()).To(ContainSubstring("no users configured"))
@@ -337,7 +333,6 @@ var _ = Describe("SubsonicAPIService", func() {
 			It("returns error for empty user list", func() {
 				service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{}, false))
 
-				ctx := GinkgoT().Context()
 				_, err := service.Call(ctx, "/ping?u=testuser")
 				Expect(err).To(HaveOccurred())
 				Expect(err.Error()).To(ContainSubstring("no users configured"))
@@ -349,7 +344,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("returns error for missing username parameter", func() {
 			service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))
 
-			ctx := GinkgoT().Context()
 			_, err := service.Call(ctx, "/ping")
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("missing required parameter"))
@@ -358,7 +352,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("returns error for invalid URL", func() {
 			service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))
 
-			ctx := GinkgoT().Context()
 			_, err := service.Call(ctx, "://invalid")
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("invalid URL"))
@@ -367,7 +360,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("extracts endpoint from path correctly", func() {
 			service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user1"}, false))
 
-			ctx := GinkgoT().Context()
 			_, err := service.Call(ctx, "/rest/ping.view?u=testuser")
 			Expect(err).ToNot(HaveOccurred())
 
@@ -380,7 +372,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("returns binary data and content-type", func() {
 			service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))
 
-			ctx := GinkgoT().Context()
 			contentType, data, err := service.CallRaw(ctx, "/getCoverArt?u=testuser&id=al-1")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(contentType).To(Equal("image/png"))
@@ -390,7 +381,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("does not set f=json parameter", func() {
 			service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))
 
-			ctx := GinkgoT().Context()
 			_, _, err := service.CallRaw(ctx, "/getCoverArt?u=testuser&id=al-1")
 			Expect(err).ToNot(HaveOccurred())
 
@@ -402,7 +392,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("enforces permission checks", func() {
 			service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess([]string{"user2"}, false))
 
-			ctx := GinkgoT().Context()
 			_, _, err := service.CallRaw(ctx, "/getCoverArt?u=testuser&id=al-1")
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("not authorized"))
@@ -411,7 +400,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("returns error when username is missing", func() {
 			service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))
 
-			ctx := GinkgoT().Context()
 			_, _, err := service.CallRaw(ctx, "/getCoverArt")
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("missing required parameter"))
@@ -420,7 +408,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("returns error when router is nil", func() {
 			service := newSubsonicAPIService("test-plugin", nil, dataStore, newUserAccess(nil, true))
 
-			ctx := GinkgoT().Context()
 			_, _, err := service.CallRaw(ctx, "/getCoverArt?u=testuser")
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("router not available"))
@@ -429,7 +416,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("returns error for invalid URL", func() {
 			service := newSubsonicAPIService("test-plugin", router, dataStore, newUserAccess(nil, true))
 
-			ctx := GinkgoT().Context()
 			_, _, err := service.CallRaw(ctx, "://invalid")
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("invalid URL"))
@@ -440,7 +426,6 @@ var _ = Describe("SubsonicAPIService", func() {
 		It("returns error when router is nil", func() {
 			service := newSubsonicAPIService("test-plugin", nil, dataStore, newUserAccess(nil, true))
 
-			ctx := GinkgoT().Context()
 			_, err := service.Call(ctx, "/ping?u=testuser")
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("router not available"))
diff --git a/plugins/host_taskqueue.go b/plugins/host_taskqueue.go
index 2f74c0aa4..b15cfaf56 100644
--- a/plugins/host_taskqueue.go
+++ b/plugins/host_taskqueue.go
@@ -71,7 +71,7 @@ type taskQueueServiceImpl struct {
 	manager        *Manager
 	maxConcurrency int32
 	db             *sql.DB
-	ctx            context.Context
+	ctx            context.Context //nolint:containedctx // service lifecycle ctx for the worker goroutines
 	cancel         context.CancelFunc
 	wg             sync.WaitGroup
 	mu             sync.Mutex
diff --git a/plugins/host_users.go b/plugins/host_users.go
index a56c8f866..28f4dc9b0 100644
--- a/plugins/host_users.go
+++ b/plugins/host_users.go
@@ -23,7 +23,7 @@ func newUsersService(ds model.DataStore, allowedUsers []string, allUsers bool) h
 }
 
 func (s *usersServiceImpl) GetUsers(ctx context.Context) ([]host.User, error) {
-	users, err := s.ds.User(ctx).GetAll()
+	users, err := s.ds.User().GetAll(ctx)
 	if err != nil {
 		return nil, err
 	}
diff --git a/plugins/host_users_test.go b/plugins/host_users_test.go
index 1721d3ee2..56edd9f67 100644
--- a/plugins/host_users_test.go
+++ b/plugins/host_users_test.go
@@ -35,21 +35,21 @@ var _ = Describe("UsersService", Ordered, func() {
 		var mockUserRepo *tests.MockedUserRepo
 
 		BeforeEach(func() {
-			mockUserRepo = ds.User(ctx).(*tests.MockedUserRepo)
+			mockUserRepo = ds.User().(*tests.MockedUserRepo)
 			// Add test users
-			_ = mockUserRepo.Put(&model.User{
+			_ = mockUserRepo.Put(ctx, &model.User{
 				ID:       "user1",
 				UserName: "alice",
 				Name:     "Alice Admin",
 				IsAdmin:  true,
 			})
-			_ = mockUserRepo.Put(&model.User{
+			_ = mockUserRepo.Put(ctx, &model.User{
 				ID:       "user2",
 				UserName: "bob",
 				Name:     "Bob User",
 				IsAdmin:  false,
 			})
-			_ = mockUserRepo.Put(&model.User{
+			_ = mockUserRepo.Put(ctx, &model.User{
 				ID:       "user3",
 				UserName: "charlie",
 				Name:     "Charlie User",
@@ -144,21 +144,21 @@ var _ = Describe("UsersService", Ordered, func() {
 		var mockUserRepo *tests.MockedUserRepo
 
 		BeforeEach(func() {
-			mockUserRepo = ds.User(ctx).(*tests.MockedUserRepo)
+			mockUserRepo = ds.User().(*tests.MockedUserRepo)
 			// Add test users - alice is admin, bob and charlie are not
-			_ = mockUserRepo.Put(&model.User{
+			_ = mockUserRepo.Put(ctx, &model.User{
 				ID:       "user1",
 				UserName: "alice",
 				Name:     "Alice Admin",
 				IsAdmin:  true,
 			})
-			_ = mockUserRepo.Put(&model.User{
+			_ = mockUserRepo.Put(ctx, &model.User{
 				ID:       "user2",
 				UserName: "bob",
 				Name:     "Bob User",
 				IsAdmin:  false,
 			})
-			_ = mockUserRepo.Put(&model.User{
+			_ = mockUserRepo.Put(ctx, &model.User{
 				ID:       "user3",
 				UserName: "charlie",
 				Name:     "Charlie User",
@@ -458,20 +458,20 @@ func setupTestUsersPlugin() (*testUsersSetup, error) {
 }
 
 // createTestUsers creates standard test users in the mock repo
-func createTestUsers(mockUserRepo *tests.MockedUserRepo) {
-	_ = mockUserRepo.Put(&model.User{
+func createTestUsers(ctx context.Context, mockUserRepo *tests.MockedUserRepo) {
+	_ = mockUserRepo.Put(ctx, &model.User{
 		ID:       "user1",
 		UserName: "alice",
 		Name:     "Alice Admin",
 		IsAdmin:  true,
 	})
-	_ = mockUserRepo.Put(&model.User{
+	_ = mockUserRepo.Put(ctx, &model.User{
 		ID:       "user2",
 		UserName: "bob",
 		Name:     "Bob User",
 		IsAdmin:  false,
 	})
-	_ = mockUserRepo.Put(&model.User{
+	_ = mockUserRepo.Put(ctx, &model.User{
 		ID:       "user3",
 		UserName: "charlie",
 		Name:     "Charlie User",
@@ -560,7 +560,7 @@ func setupUsersIntegrationManagerWithEnabled(enabled, allUsers bool, allowedUser
 	}})
 
 	mockUserRepo := tests.CreateMockUserRepo()
-	createTestUsers(mockUserRepo)
+	createTestUsers(GinkgoT().Context(), mockUserRepo)
 
 	dataStore := &tests.MockDataStore{
 		MockedPlugin: mockPluginRepo,
diff --git a/plugins/host_websocket.go b/plugins/host_websocket.go
index d9d82665c..a58deb129 100644
--- a/plugins/host_websocket.go
+++ b/plugins/host_websocket.go
@@ -56,7 +56,7 @@ type wsConnection struct {
 // webSocketServiceImpl implements host.WebSocketService.
 // It provides plugins with WebSocket communication capabilities.
 type webSocketServiceImpl struct {
-	baseCtx       context.Context // bounds the read loops, which outlive the Connect() call
+	baseCtx       context.Context //nolint:containedctx // bounds the read loops, which outlive the Connect() call
 	pluginName    string
 	manager       *Manager
 	requiredHosts []string
diff --git a/plugins/manager.go b/plugins/manager.go
index bab67e987..90247a75c 100644
--- a/plugins/manager.go
+++ b/plugins/manager.go
@@ -49,7 +49,7 @@ type PluginMetricsRecorder interface {
 type Manager struct {
 	mu      sync.RWMutex
 	plugins map[string]*plugin
-	ctx     context.Context
+	ctx     context.Context //nolint:containedctx // manager lifecycle ctx, cancelled by Stop
 	cancel  context.CancelFunc
 	cache   wazero.CompilationCache
 	stopped atomic.Bool    // Set to true when Stop() is called
@@ -134,7 +134,7 @@ func (m *Manager) Start(ctx context.Context) error {
 
 	// Clear previous error states so plugins can be retried on restart
 	adminCtx := adminContext(ctx)
-	if err := m.ds.Plugin(adminCtx).ClearErrors(); err != nil {
+	if err := m.ds.Plugin().ClearErrors(adminCtx); err != nil {
 		log.Error(ctx, "Error clearing plugin errors", err)
 	}
 
@@ -323,9 +323,9 @@ func (m *Manager) EnablePlugin(ctx context.Context, id string) error {
 	}
 
 	adminCtx := adminContext(ctx)
-	repo := m.ds.Plugin(adminCtx)
+	repo := m.ds.Plugin()
 
-	plugin, err := repo.Get(id)
+	plugin, err := repo.Get(adminCtx, id)
 	if err != nil {
 		return fmt.Errorf("getting plugin from DB: %w", err)
 	}
@@ -344,7 +344,7 @@ func (m *Manager) EnablePlugin(ctx context.Context, id string) error {
 		// Store error and return
 		plugin.LastError = err.Error()
 		plugin.UpdatedAt = time.Now()
-		_ = repo.Put(plugin)
+		_ = repo.Put(adminCtx, plugin)
 		return fmt.Errorf("loading plugin: %w", err)
 	}
 
@@ -352,7 +352,7 @@ func (m *Manager) EnablePlugin(ctx context.Context, id string) error {
 	plugin.Enabled = true
 	plugin.LastError = ""
 	plugin.UpdatedAt = time.Now()
-	if err := repo.Put(plugin); err != nil {
+	if err := repo.Put(adminCtx, plugin); err != nil {
 		// Unload since we couldn't update DB
 		_ = m.unloadPlugin(id)
 		return fmt.Errorf("updating plugin in DB: %w", err)
@@ -371,9 +371,9 @@ func (m *Manager) DisablePlugin(ctx context.Context, id string) error {
 	}
 
 	adminCtx := adminContext(ctx)
-	repo := m.ds.Plugin(adminCtx)
+	repo := m.ds.Plugin()
 
-	plugin, err := repo.Get(id)
+	plugin, err := repo.Get(adminCtx, id)
 	if err != nil {
 		return fmt.Errorf("getting plugin from DB: %w", err)
 	}
@@ -390,7 +390,7 @@ func (m *Manager) DisablePlugin(ctx context.Context, id string) error {
 	// Update DB
 	plugin.Enabled = false
 	plugin.UpdatedAt = time.Now()
-	if err := repo.Put(plugin); err != nil {
+	if err := repo.Put(adminCtx, plugin); err != nil {
 		return fmt.Errorf("updating plugin in DB: %w", err)
 	}
 
@@ -408,9 +408,9 @@ func (m *Manager) ValidatePluginConfig(ctx context.Context, id, configJSON strin
 	}
 
 	adminCtx := adminContext(ctx)
-	repo := m.ds.Plugin(adminCtx)
+	repo := m.ds.Plugin()
 
-	plugin, err := repo.Get(id)
+	plugin, err := repo.Get(adminCtx, id)
 	if err != nil {
 		return fmt.Errorf("getting plugin from DB: %w", err)
 	}
@@ -476,9 +476,9 @@ func (m *Manager) updatePluginSettings(ctx context.Context, id string, updateFn
 	}
 
 	adminCtx := adminContext(ctx)
-	repo := m.ds.Plugin(adminCtx)
+	repo := m.ds.Plugin()
 
-	plugin, err := repo.Get(id)
+	plugin, err := repo.Get(adminCtx, id)
 	if err != nil {
 		return fmt.Errorf("getting plugin from DB: %w", err)
 	}
@@ -512,7 +512,7 @@ func (m *Manager) updatePluginSettings(ctx context.Context, id string, updateFn
 			log.Debug(ctx, "Plugin was not loaded", "plugin", id)
 		}
 		plugin.Enabled = false
-		if err := repo.Put(plugin); err != nil {
+		if err := repo.Put(adminCtx, plugin); err != nil {
 			return fmt.Errorf("updating plugin in DB: %w", err)
 		}
 		log.Info(ctx, "Disabled plugin due to "+disableReason, "plugin", id)
@@ -520,7 +520,7 @@ func (m *Manager) updatePluginSettings(ctx context.Context, id string, updateFn
 		return nil
 	}
 
-	if err := repo.Put(plugin); err != nil {
+	if err := repo.Put(adminCtx, plugin); err != nil {
 		return fmt.Errorf("updating plugin in DB: %w", err)
 	}
 
@@ -532,7 +532,7 @@ func (m *Manager) updatePluginSettings(ctx context.Context, id string, updateFn
 		if err := m.loadPluginWithConfig(plugin); err != nil {
 			plugin.LastError = err.Error()
 			plugin.Enabled = false
-			_ = repo.Put(plugin)
+			_ = repo.Put(adminCtx, plugin)
 			return fmt.Errorf("reloading plugin: %w", err)
 		}
 	}
@@ -586,10 +586,10 @@ func (m *Manager) UnloadDisabledPlugins(ctx context.Context) {
 	}
 
 	adminCtx := adminContext(ctx)
-	repo := m.ds.Plugin(adminCtx)
+	repo := m.ds.Plugin()
 
 	// Get all disabled plugins from the database
-	plugins, err := repo.GetAll(model.QueryOptions{
+	plugins, err := repo.GetAll(adminCtx, model.QueryOptions{
 		Filters: squirrel.Eq{"enabled": false},
 	})
 	if err != nil {
diff --git a/plugins/manager_loader.go b/plugins/manager_loader.go
index 024b14b72..cca87e5b0 100644
--- a/plugins/manager_loader.go
+++ b/plugins/manager_loader.go
@@ -219,9 +219,9 @@ func (m *Manager) loadEnabledPlugins(ctx context.Context) error {
 	}
 
 	adminCtx := adminContext(ctx)
-	repo := m.ds.Plugin(adminCtx)
+	repo := m.ds.Plugin()
 
-	plugins, err := repo.GetAll()
+	plugins, err := repo.GetAll(adminCtx)
 	if err != nil {
 		return fmt.Errorf("reading plugins from DB: %w", err)
 	}
@@ -257,7 +257,7 @@ func (m *Manager) loadEnabledPlugins(ctx context.Context) error {
 					plugin.LastError = err.Error()
 					plugin.Enabled = false
 					plugin.UpdatedAt = time.Now()
-					if putErr := repo.Put(&plugin); putErr != nil {
+					if putErr := repo.Put(adminCtx, &plugin); putErr != nil {
 						log.Error(ctx, "Failed to update plugin error in DB", "plugin", plugin.ID, putErr)
 					}
 				}
@@ -269,7 +269,7 @@ func (m *Manager) loadEnabledPlugins(ctx context.Context) error {
 			if plugin.LastError != "" && m.transient == nil {
 				plugin.LastError = ""
 				plugin.UpdatedAt = time.Now()
-				if putErr := repo.Put(&plugin); putErr != nil {
+				if putErr := repo.Put(adminCtx, &plugin); putErr != nil {
 					log.Error(ctx, "Failed to clear plugin error in DB", "plugin", plugin.ID, putErr)
 				}
 			}
@@ -347,7 +347,7 @@ func (m *Manager) loadPluginWithConfig(p *model.Plugin) error {
 
 		if pkg.Manifest.HasLibraryFilesystemPermission() {
 			adminCtx := adminContext(ctx)
-			libraries, err := m.ds.Library(adminCtx).GetAll()
+			libraries, err := m.ds.Library().GetAll(adminCtx)
 			if err != nil {
 				return fmt.Errorf("failed to get libraries for filesystem access: %w", err)
 			}
diff --git a/plugins/manager_plugin.go b/plugins/manager_plugin.go
index 13375a70f..015cd7f4c 100644
--- a/plugins/manager_plugin.go
+++ b/plugins/manager_plugin.go
@@ -126,7 +126,7 @@ func (a userAccess) resolve(ctx context.Context, ds model.DataStore, username st
 	if !a.allUsers && len(a.userIDSet) == 0 {
 		return nil, fmt.Errorf("plugin is not authorized to scope by user")
 	}
-	usr, err := ds.User(ctx).FindByUsername(username)
+	usr, err := ds.User().FindByUsername(ctx, username)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
 			return nil, fmt.Errorf("user %q not found", username)
diff --git a/plugins/manager_readonly_test.go b/plugins/manager_readonly_test.go
index 019b14fbf..0c88459c0 100644
--- a/plugins/manager_readonly_test.go
+++ b/plugins/manager_readonly_test.go
@@ -1,6 +1,7 @@
 package plugins
 
 import (
+	"context"
 	"os"
 	"path/filepath"
 
@@ -14,11 +15,16 @@ import (
 
 var _ = Describe("Manager.LoadPlugins", func() {
 	var (
+		ctx    context.Context
 		mgr    *Manager
 		repo   *tests.MockPluginRepo
 		tmpDir string
 	)
 
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+	})
+
 	// newManager builds a manager over rows the caller can corrupt, with no Subsonic router: a CLI
 	// has none, and Start would log.Fatal on that.
 	newManager := func(rows model.Plugins) *Manager {
@@ -54,7 +60,7 @@ var _ = Describe("Manager.LoadPlugins", func() {
 	It("detects capabilities without a Subsonic router configured", func() {
 		mgr = newManager(nil)
 
-		Expect(mgr.LoadPlugins(GinkgoT().Context(), []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
+		Expect(mgr.LoadPlugins(ctx, []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
 
 		Expect(mgr.PluginNames(string(CapabilityMetadataAgent))).To(ContainElement("test-metadata-agent"))
 	})
@@ -70,9 +76,9 @@ var _ = Describe("Manager.LoadPlugins", func() {
 		It("leaves the stored row untouched", func() {
 			mgr = newManager(brokenRows())
 
-			Expect(mgr.LoadPlugins(GinkgoT().Context(), []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
+			Expect(mgr.LoadPlugins(ctx, []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
 
-			stored, err := repo.Get("broken")
+			stored, err := repo.Get(ctx, "broken")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(stored.Enabled).To(BeTrue(), "inspecting a plugin must never disable it")
 			Expect(stored.LastError).To(BeEmpty())
@@ -83,9 +89,9 @@ var _ = Describe("Manager.LoadPlugins", func() {
 		It("still disables it when not read-only", func() {
 			mgr = newManager(brokenRows())
 
-			Expect(mgr.loadEnabledPlugins(GinkgoT().Context())).To(Succeed())
+			Expect(mgr.loadEnabledPlugins(ctx)).To(Succeed())
 
-			stored, err := repo.Get("broken")
+			stored, err := repo.Get(ctx, "broken")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(stored.Enabled).To(BeFalse())
 			Expect(stored.LastError).ToNot(BeEmpty())
@@ -97,7 +103,7 @@ var _ = Describe("Manager.LoadPlugins", func() {
 	It("does not load a plugin that is not in the agent list", func() {
 		mgr = newManager(nil)
 
-		Expect(mgr.LoadPlugins(GinkgoT().Context(), []string{"some-other-agent"}, false)).To(Succeed())
+		Expect(mgr.LoadPlugins(ctx, []string{"some-other-agent"}, false)).To(Succeed())
 
 		Expect(mgr.PluginNames(string(CapabilityMetadataAgent))).To(BeEmpty())
 	})
@@ -105,7 +111,7 @@ var _ = Describe("Manager.LoadPlugins", func() {
 	It("does nothing when no agents are configured", func() {
 		mgr = newManager(nil)
 
-		Expect(mgr.LoadPlugins(GinkgoT().Context(), nil, false)).To(Succeed())
+		Expect(mgr.LoadPlugins(ctx, nil, false)).To(Succeed())
 
 		Expect(mgr.PluginNames(string(CapabilityMetadataAgent))).To(BeEmpty())
 		// Not even the wazero cache: with nothing to load there is nothing to compile.
@@ -116,7 +122,7 @@ var _ = Describe("Manager.LoadPlugins", func() {
 		mgr = newManager(nil)
 		conf.Server.Plugins.Enabled = false
 
-		Expect(mgr.LoadPlugins(GinkgoT().Context(), []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
+		Expect(mgr.LoadPlugins(ctx, []string{"test-metadata-agent", "broken"}, false)).To(Succeed())
 
 		Expect(mgr.PluginNames(string(CapabilityMetadataAgent))).To(BeEmpty())
 	})
diff --git a/plugins/manager_sync.go b/plugins/manager_sync.go
index 480fa1bb9..33b4f81d4 100644
--- a/plugins/manager_sync.go
+++ b/plugins/manager_sync.go
@@ -65,7 +65,7 @@ func (m *Manager) addPluginToDB(ctx context.Context, repo model.PluginRepository
 		CreatedAt: now,
 		UpdatedAt: now,
 	}
-	if err := repo.Put(newPlugin); err != nil {
+	if err := repo.Put(ctx, newPlugin); err != nil {
 		return fmt.Errorf("adding plugin to DB: %w", err)
 	}
 	log.Info(ctx, "Discovered new plugin", "plugin", name)
@@ -88,7 +88,7 @@ func (m *Manager) updatePluginInDB(ctx context.Context, repo model.PluginReposit
 	dbPlugin.Enabled = false
 	dbPlugin.LastError = ""
 	dbPlugin.UpdatedAt = time.Now()
-	if err := repo.Put(dbPlugin); err != nil {
+	if err := repo.Put(ctx, dbPlugin); err != nil {
 		return fmt.Errorf("updating plugin in DB: %w", err)
 	}
 	log.Info(ctx, "Plugin file changed", "plugin", dbPlugin.ID, "wasEnabled", wasEnabled)
@@ -105,7 +105,7 @@ func (m *Manager) removePluginFromDB(ctx context.Context, repo model.PluginRepos
 			log.Debug(ctx, "Plugin not loaded during removal", "plugin", pluginID, err)
 		}
 	}
-	if err := repo.Delete(pluginID); err != nil {
+	if err := repo.Delete(ctx, pluginID); err != nil {
 		return fmt.Errorf("deleting plugin from DB: %w", err)
 	}
 	// Discard any scrobbles still buffered for the removed plugin, so they are
@@ -115,7 +115,7 @@ func (m *Manager) removePluginFromDB(ctx context.Context, repo model.PluginRepos
 	// wipe the builtin Last.fm retry queue.
 	if scrobbler.IsBuiltinScrobbler(pluginID) {
 		log.Debug(ctx, "Keeping buffered scrobbles: name is owned by a builtin scrobbler", "plugin", pluginID)
-	} else if err := m.ds.ScrobbleBuffer(ctx).Discard(pluginID); err != nil {
+	} else if err := m.ds.ScrobbleBuffer().Discard(ctx, pluginID); err != nil {
 		log.Error(ctx, "Error discarding buffered scrobbles for removed plugin", "plugin", pluginID, err)
 	}
 	log.Info(ctx, "Plugin removed", "plugin", pluginID)
@@ -162,8 +162,8 @@ func (m *Manager) syncPlugins(ctx context.Context, folder string) error {
 	log.Debug(ctx, "Plugin sync: scanned folder", "folder", folder, "entriesTotal", len(entries), "pluginsFound", len(filesOnDisk))
 
 	// Get all plugins from DB
-	repo := m.ds.Plugin(adminCtx)
-	dbPlugins, err := repo.GetAll()
+	repo := m.ds.Plugin()
+	dbPlugins, err := repo.GetAll(adminCtx)
 	if err != nil {
 		return fmt.Errorf("reading plugins from DB: %w", err)
 	}
@@ -192,7 +192,7 @@ func (m *Manager) syncPlugins(ctx context.Context, folder string) error {
 			if dbPlugin.Path != path {
 				dbPlugin.Path = path
 				dbPlugin.UpdatedAt = now
-				if err := repo.Put(dbPlugin); err != nil {
+				if err := repo.Put(adminCtx, dbPlugin); err != nil {
 					log.Error(ctx, "Failed to update plugin path in DB", "plugin", name, err)
 				}
 			}
@@ -215,7 +215,7 @@ func (m *Manager) syncPlugins(ctx context.Context, folder string) error {
 					}
 					dbPlugin.Enabled = false
 				}
-				if putErr := repo.Put(dbPlugin); putErr != nil {
+				if putErr := repo.Put(adminCtx, dbPlugin); putErr != nil {
 					log.Error(ctx, "Failed to update plugin in DB", "plugin", name, err)
 				}
 			}
@@ -225,12 +225,12 @@ func (m *Manager) syncPlugins(ctx context.Context, folder string) error {
 
 		if !exists {
 			// New plugin - add to DB as disabled
-			if err := m.addPluginToDB(ctx, repo, name, path, metadata); err != nil {
+			if err := m.addPluginToDB(adminCtx, repo, name, path, metadata); err != nil {
 				log.Error(ctx, "Failed to add plugin to DB", "plugin", name, err)
 			}
 		} else {
 			// Plugin changed - update DB
-			if err := m.updatePluginInDB(ctx, repo, dbPlugin, path, metadata); err != nil {
+			if err := m.updatePluginInDB(adminCtx, repo, dbPlugin, path, metadata); err != nil {
 				log.Error(ctx, "Failed to update plugin in DB", "plugin", name, err)
 			}
 		}
@@ -240,7 +240,7 @@ func (m *Manager) syncPlugins(ctx context.Context, folder string) error {
 
 	// Remove plugins no longer on disk
 	for _, dbPlugin := range pluginsInDB {
-		if err := m.removePluginFromDB(ctx, repo, dbPlugin); err != nil {
+		if err := m.removePluginFromDB(adminCtx, repo, dbPlugin); err != nil {
 			log.Error(ctx, "Failed to delete plugin from DB", "plugin", dbPlugin.ID, err)
 		}
 	}
diff --git a/plugins/manager_sync_test.go b/plugins/manager_sync_test.go
index dd64dcd3f..e190abd34 100644
--- a/plugins/manager_sync_test.go
+++ b/plugins/manager_sync_test.go
@@ -13,11 +13,13 @@ import (
 )
 
 var _ = Describe("syncPlugins", func() {
+	var ctx context.Context
 	var m *Manager
 	var repo *tests.MockPluginRepo
 	var folder string
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		folder = GinkgoT().TempDir()
 		repo = tests.CreateMockPluginRepo()
 		repo.SetData(model.Plugins{})
@@ -36,7 +38,7 @@ var _ = Describe("syncPlugins", func() {
 
 		Expect(m.syncPlugins(context.Background(), folder)).To(Succeed())
 
-		_, err := repo.Get("my-plugin")
+		_, err := repo.Get(ctx, "my-plugin")
 		Expect(err).ToNot(HaveOccurred())
 	})
 
@@ -46,18 +48,23 @@ var _ = Describe("syncPlugins", func() {
 
 		Expect(m.syncPlugins(context.Background(), folder)).To(Succeed())
 
-		all, err := repo.GetAll()
+		all, err := repo.GetAll(ctx)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(all).To(BeEmpty())
 	})
 })
 
 var _ = Describe("removePluginFromDB", func() {
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+	})
+
 	It("discards buffered scrobbles for the removed plugin", func() {
-		ctx := context.Background()
 		buffer := tests.CreateMockedScrobbleBufferRepo()
-		Expect(buffer.Enqueue("my-plugin", "user1", "track1", time.Now())).To(Succeed())
-		Expect(buffer.Enqueue("other-plugin", "user1", "track2", time.Now())).To(Succeed())
+		Expect(buffer.Enqueue(ctx, "my-plugin", "user1", "track1", time.Now())).To(Succeed())
+		Expect(buffer.Enqueue(ctx, "other-plugin", "user1", "track2", time.Now())).To(Succeed())
 
 		repo := tests.CreateMockPluginRepo()
 		plugin := model.Plugin{ID: "my-plugin", Enabled: false}
@@ -70,22 +77,21 @@ var _ = Describe("removePluginFromDB", func() {
 		}
 		Expect(m.removePluginFromDB(ctx, repo, &plugin)).To(Succeed())
 
-		_, err := repo.Get("my-plugin")
+		_, err := repo.Get(ctx, "my-plugin")
 		Expect(err).To(MatchError(model.ErrNotFound))
 
-		remaining, err := buffer.Length()
+		remaining, err := buffer.Length(ctx)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(remaining).To(Equal(int64(1)))
-		entry, err := buffer.Next("other-plugin", "user1")
+		entry, err := buffer.Next(ctx, "other-plugin", "user1")
 		Expect(err).ToNot(HaveOccurred())
 		Expect(entry).ToNot(BeNil(), "entries of other services must be kept")
 	})
 
 	It("keeps buffered scrobbles of a builtin scrobbler sharing the removed plugin's name", func() {
-		ctx := context.Background()
 		scrobbler.Register("builtin-svc", func(model.DataStore) scrobbler.Scrobbler { return nil })
 		buffer := tests.CreateMockedScrobbleBufferRepo()
-		Expect(buffer.Enqueue("builtin-svc", "user1", "track1", time.Now())).To(Succeed())
+		Expect(buffer.Enqueue(ctx, "builtin-svc", "user1", "track1", time.Now())).To(Succeed())
 
 		repo := tests.CreateMockPluginRepo()
 		plugin := model.Plugin{ID: "builtin-svc", Enabled: false}
@@ -96,7 +102,7 @@ var _ = Describe("removePluginFromDB", func() {
 		}
 		Expect(m.removePluginFromDB(ctx, repo, &plugin)).To(Succeed())
 
-		remaining, err := buffer.Length()
+		remaining, err := buffer.Length(ctx)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(remaining).To(Equal(int64(1)), "builtin scrobbler queue must not be wiped")
 	})
diff --git a/plugins/manager_watcher.go b/plugins/manager_watcher.go
index f7f658be9..ce9e25a9d 100644
--- a/plugins/manager_watcher.go
+++ b/plugins/manager_watcher.go
@@ -157,7 +157,7 @@ func (m *Manager) processPluginEvent(pluginName string) {
 	log.Debug(m.ctx, "Plugin event action", "plugin", pluginName, "action", action, "path", ndpPath)
 
 	ctx := adminContext(m.ctx)
-	repo := m.ds.Plugin(ctx)
+	repo := m.ds.Plugin()
 
 	switch action {
 	case actionUpdate:
@@ -168,7 +168,7 @@ func (m *Manager) processPluginEvent(pluginName string) {
 			return
 		}
 
-		dbPlugin, err := repo.Get(pluginName)
+		dbPlugin, err := repo.Get(ctx, pluginName)
 		if err != nil {
 			// Plugin not in DB yet, need full manifest extraction to add it
 			metadata, extractErr := m.extractManifest(ndpPath)
@@ -176,7 +176,7 @@ func (m *Manager) processPluginEvent(pluginName string) {
 				log.Error(m.ctx, "Failed to extract manifest from new plugin", "plugin", pluginName, extractErr)
 				return
 			}
-			if addErr := m.addPluginToDB(m.ctx, repo, pluginName, ndpPath, metadata); addErr != nil {
+			if addErr := m.addPluginToDB(ctx, repo, pluginName, ndpPath, metadata); addErr != nil {
 				log.Error(m.ctx, "Failed to add plugin to DB", "plugin", pluginName, addErr)
 			}
 			return
@@ -198,23 +198,23 @@ func (m *Manager) processPluginEvent(pluginName string) {
 				_ = m.unloadPlugin(pluginName)
 				dbPlugin.Enabled = false
 			}
-			_ = repo.Put(dbPlugin)
+			_ = repo.Put(ctx, dbPlugin)
 			return
 		}
 
-		if err := m.updatePluginInDB(m.ctx, repo, dbPlugin, ndpPath, metadata); err != nil {
+		if err := m.updatePluginInDB(ctx, repo, dbPlugin, ndpPath, metadata); err != nil {
 			log.Error(m.ctx, "Failed to update plugin in DB", "plugin", pluginName, err)
 		}
 
 	case actionRemove:
 		// File removed - unload if enabled, delete from DB
-		dbPlugin, err := repo.Get(pluginName)
+		dbPlugin, err := repo.Get(ctx, pluginName)
 		if err != nil {
 			log.Debug(m.ctx, "Removed plugin not in DB", "plugin", pluginName)
 			return
 		}
 
-		if err := m.removePluginFromDB(m.ctx, repo, dbPlugin); err != nil {
+		if err := m.removePluginFromDB(ctx, repo, dbPlugin); err != nil {
 			log.Error(m.ctx, "Failed to delete plugin from DB", "plugin", pluginName, err)
 		}
 	}
diff --git a/plugins/manager_watcher_test.go b/plugins/manager_watcher_test.go
index 99326bde1..17d9489dc 100644
--- a/plugins/manager_watcher_test.go
+++ b/plugins/manager_watcher_test.go
@@ -31,7 +31,7 @@ var _ = Describe("Plugin Watcher", func() {
 			_ = manager.unloadPlugin("test-metadata-agent")
 			_ = os.Remove(filepath.Join(tmpDir, "test-metadata-agent"+PackageExtension))
 			// Also remove from DB so tests start with a clean slate
-			_ = manager.ds.Plugin(ctx).Delete("test-metadata-agent")
+			_ = manager.ds.Plugin().Delete(ctx, "test-metadata-agent")
 		})
 
 		// Helper to copy test plugin into the temp folder
@@ -51,7 +51,7 @@ var _ = Describe("Plugin Watcher", func() {
 				// Clean up: unload plugin if loaded, remove copied file, delete from DB
 				_ = manager.unloadPlugin("test-metadata-agent")
 				_ = os.Remove(filepath.Join(tmpDir, "test-metadata-agent"+PackageExtension))
-				_ = manager.ds.Plugin(ctx).Delete("test-metadata-agent")
+				_ = manager.ds.Plugin().Delete(ctx, "test-metadata-agent")
 			})
 
 			It("adds plugin to DB when file exists", func() {
@@ -62,8 +62,8 @@ var _ = Describe("Plugin Watcher", func() {
 				Expect(manager.PluginNames(string(CapabilityMetadataAgent))).ToNot(ContainElement("test-metadata-agent"))
 
 				// Verify it was added to DB
-				repo := manager.ds.Plugin(ctx)
-				plugin, err := repo.Get("test-metadata-agent")
+				repo := manager.ds.Plugin()
+				plugin, err := repo.Get(ctx, "test-metadata-agent")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(plugin.ID).To(Equal("test-metadata-agent"))
 				Expect(plugin.Enabled).To(BeFalse())
@@ -80,11 +80,11 @@ var _ = Describe("Plugin Watcher", func() {
 
 				// Modify the stored SHA256 in DB to simulate a file change
 				// (In reality, the file would have different content)
-				repo := manager.ds.Plugin(ctx)
-				plugin, err := repo.Get("test-metadata-agent")
+				repo := manager.ds.Plugin()
+				plugin, err := repo.Get(ctx, "test-metadata-agent")
 				Expect(err).ToNot(HaveOccurred())
 				plugin.SHA256 = "different-hash-to-simulate-change"
-				err = repo.Put(plugin)
+				err = repo.Put(ctx, plugin)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Simulate modification - the plugin should be disabled and unloaded
@@ -94,7 +94,7 @@ var _ = Describe("Plugin Watcher", func() {
 				Expect(manager.PluginNames(string(CapabilityMetadataAgent))).ToNot(ContainElement("test-metadata-agent"))
 
 				// But still in DB (just disabled)
-				plugin, err = repo.Get("test-metadata-agent")
+				plugin, err = repo.Get(ctx, "test-metadata-agent")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(plugin.Enabled).To(BeFalse())
 			})
@@ -115,8 +115,8 @@ var _ = Describe("Plugin Watcher", func() {
 				Expect(manager.PluginNames(string(CapabilityMetadataAgent))).ToNot(ContainElement("test-metadata-agent"))
 
 				// And removed from DB
-				repo := manager.ds.Plugin(ctx)
-				_, err = repo.Get("test-metadata-agent")
+				repo := manager.ds.Plugin()
+				_, err = repo.Get(ctx, "test-metadata-agent")
 				Expect(err).To(HaveOccurred())
 			})
 		})
diff --git a/scanner/controller.go b/scanner/controller.go
index bfb396c6d..5eed6c58d 100644
--- a/scanner/controller.go
+++ b/scanner/controller.go
@@ -94,7 +94,7 @@ type scanner interface {
 }
 
 type controller struct {
-	rootCtx            context.Context
+	rootCtx            context.Context //nolint:containedctx // scanner lifecycle ctx
 	ds                 model.DataStore
 	broker             events.Broker
 	metrics            metrics.Metrics
@@ -108,7 +108,7 @@ type controller struct {
 
 // getLastScanTime returns the most recent scan time across all libraries
 func (s *controller) getLastScanTime(ctx context.Context) (time.Time, error) {
-	libs, err := s.ds.Library(ctx).GetAll(model.QueryOptions{
+	libs, err := s.ds.Library().GetAll(ctx, model.QueryOptions{
 		Sort:  "last_scan_at",
 		Order: "desc",
 		Max:   1,
@@ -126,9 +126,9 @@ func (s *controller) getLastScanTime(ctx context.Context) (time.Time, error) {
 
 // getScanInfo retrieves scan status from the database
 func (s *controller) getScanInfo(ctx context.Context) (scanType string, elapsed time.Duration, lastErr string) {
-	lastErr, _ = s.ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "")
-	scanType, _ = s.ds.Property(ctx).DefaultGet(consts.LastScanTypeKey, "")
-	startTimeStr, _ := s.ds.Property(ctx).DefaultGet(consts.LastScanStartTimeKey, "")
+	lastErr, _ = s.ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "")
+	scanType, _ = s.ds.Property().DefaultGet(ctx, consts.LastScanTypeKey, "")
+	startTimeStr, _ := s.ds.Property().DefaultGet(ctx, consts.LastScanStartTimeKey, "")
 
 	if startTimeStr != "" {
 		startTime, err := time.Parse(time.RFC3339, startTimeStr)
@@ -185,7 +185,7 @@ func (s *controller) Status(ctx context.Context) (*model.ScannerStatus, error) {
 }
 
 func (s *controller) getCounters(ctx context.Context) (int64, int64, error) {
-	libs, err := s.ds.Library(ctx).GetAll()
+	libs, err := s.ds.Library().GetAll(ctx)
 	if err != nil {
 		return 0, 0, fmt.Errorf("library count: %w", err)
 	}
@@ -238,7 +238,7 @@ func (s *controller) ScanFolders(requestCtx context.Context, fullScan bool, targ
 	}
 	// Store scan error in database so it can be displayed in the UI
 	if scanError != nil {
-		_ = s.ds.Property(ctx).Put(consts.LastScanErrorKey, scanError.Error())
+		_ = s.ds.Property().Put(ctx, consts.LastScanErrorKey, scanError.Error())
 	}
 	// Refresh the query-planner statistics after a successful full scan. This must run in the
 	// server process: with the external scanner, an ANALYZE in the subprocess is invisible to the
@@ -324,7 +324,7 @@ func (s *controller) includesUnscannedLibrary(ctx context.Context, targets []mod
 // anyIncludedLibrary reports whether any library included in the scan (all of them when targets is
 // empty) matches pred.
 func anyIncludedLibrary(ctx context.Context, ds model.DataStore, targets []model.ScanTarget, pred func(model.Library) bool) bool {
-	libraries, err := ds.Library(ctx).GetAll()
+	libraries, err := ds.Library().GetAll(ctx)
 	if err != nil {
 		return false
 	}
diff --git a/scanner/controller_test.go b/scanner/controller_test.go
index 45d202904..bdcb99eda 100644
--- a/scanner/controller_test.go
+++ b/scanner/controller_test.go
@@ -35,7 +35,7 @@ var _ = Describe("Controller", func() {
 		})
 
 		It("includes last scan error", func() {
-			Expect(ds.Property(ctx).Put(consts.LastScanErrorKey, "boom")).To(Succeed())
+			Expect(ds.Property().Put(ctx, consts.LastScanErrorKey, "boom")).To(Succeed())
 			status, err := ctrl.Status(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(status.LastError).To(Equal("boom"))
@@ -43,8 +43,8 @@ var _ = Describe("Controller", func() {
 
 		It("includes scan type and error in status", func() {
 			// Set up test data in property repo
-			Expect(ds.Property(ctx).Put(consts.LastScanErrorKey, "test error")).To(Succeed())
-			Expect(ds.Property(ctx).Put(consts.LastScanTypeKey, "full")).To(Succeed())
+			Expect(ds.Property().Put(ctx, consts.LastScanErrorKey, "test error")).To(Succeed())
+			Expect(ds.Property().Put(ctx, consts.LastScanTypeKey, "full")).To(Succeed())
 
 			// Get status and verify basic info
 			status, err := ctrl.Status(ctx)
diff --git a/scanner/image_changes.go b/scanner/image_changes.go
index a9c4de365..3ea7ce57c 100644
--- a/scanner/image_changes.go
+++ b/scanner/image_changes.go
@@ -54,7 +54,7 @@ func (c *imageChangeCollector) enqueue(ctx context.Context) {
 		if len(items) == 0 {
 			continue
 		}
-		if err := c.ds.ArtworkQueue(ctx).Enqueue(items...); err != nil {
+		if err := c.ds.ArtworkQueue().Enqueue(ctx, items...); err != nil {
 			log.Warn(ctx, "Scanner: could not enqueue artwork for image changes", "lib", lib.Name, err)
 			continue
 		}
@@ -77,7 +77,7 @@ func (c *imageChangeCollector) queueItems(ctx context.Context, lib model.Library
 
 	var items []model.ArtworkQueueItem
 
-	albumIDs, err := c.ds.MediaFile(ctx).GetAlbumIDsByFolder(lib, folderIDs...)
+	albumIDs, err := c.ds.MediaFile().GetAlbumIDsByFolder(ctx, lib, folderIDs...)
 	if err != nil {
 		return nil, err
 	}
@@ -90,7 +90,7 @@ func (c *imageChangeCollector) queueItems(ctx context.Context, lib model.Library
 	}
 	// The resolver climbs to the library root, so the subtree below the folder is the affected set.
 	// A failure here must not discard the album items already collected.
-	artistIDs, err := c.ds.Album(ctx).GetSoleAlbumArtistIDsInSubtrees(lib, artistFolderPaths...)
+	artistIDs, err := c.ds.Album().GetSoleAlbumArtistIDsInSubtrees(ctx, lib, artistFolderPaths...)
 	if err != nil {
 		log.Warn(ctx, "Scanner: could not map image changes to artists", "lib", lib.Name, err)
 		return items, nil
diff --git a/scanner/phase_1_folders.go b/scanner/phase_1_folders.go
index feefde032..7b6a6b097 100644
--- a/scanner/phase_1_folders.go
+++ b/scanner/phase_1_folders.go
@@ -61,7 +61,7 @@ type scanJob struct {
 
 func newScanJob(ctx context.Context, ds model.DataStore, lib model.Library, fullScan bool, targetFolders []string) (*scanJob, error) {
 	// Get folder updates, optionally filtered to specific target folders
-	lastUpdates, err := ds.Folder(ctx).GetFolderUpdateInfo(lib, targetFolders...)
+	lastUpdates, err := ds.Folder().GetFolderUpdateInfo(ctx, lib, targetFolders...)
 	if err != nil {
 		return nil, fmt.Errorf("getting last updates: %w", err)
 	}
@@ -124,8 +124,8 @@ func (j *scanJob) createFolderEntry(path string) *folderEntry {
 type phaseFolders struct {
 	jobs             []*scanJob
 	ds               model.DataStore
-	ctx              context.Context
-	walkCtx          context.Context // cancelled when a folder fails to persist, so the walk stops early
+	ctx              context.Context //nolint:containedctx // phase runs under a single scan ctx
+	walkCtx          context.Context //nolint:containedctx // cancelled when a folder fails to persist, so the walk stops early
 	stopWalk         context.CancelCauseFunc
 	state            *scanState
 	prevAlbumPIDConf string
@@ -139,7 +139,7 @@ func (p *phaseFolders) description() string {
 func (p *phaseFolders) producer() ppl.Producer[*folderEntry] {
 	return ppl.NewProducer(func(put func(entry *folderEntry)) error {
 		var err error
-		p.prevAlbumPIDConf, err = p.ds.Property(p.ctx).DefaultGet(consts.PIDAlbumKey, "")
+		p.prevAlbumPIDConf, err = p.ds.Property().DefaultGet(p.ctx, consts.PIDAlbumKey, "")
 		if err != nil {
 			return fmt.Errorf("getting album PID conf: %w", err)
 		}
@@ -217,7 +217,7 @@ func (p *phaseFolders) processFolder(entry *folderEntry) (*folderEntry, error) {
 	}
 
 	// Load children mediafiles from DB
-	cursor, err := p.ds.MediaFile(p.ctx).GetCursor(model.QueryOptions{
+	cursor, err := p.ds.MediaFile().GetCursor(p.ctx, model.QueryOptions{
 		Filters: squirrel.And{squirrel.Eq{"folder_id": entry.id}},
 	})
 	if err != nil {
@@ -367,34 +367,34 @@ func (p *phaseFolders) persistFolder(ctx context.Context, tx model.DataStore, en
 	albumIDMap := maps.Clone(entry.albumIDMap)
 
 	// Instantiate all repositories just once per folder
-	folderRepo := tx.Folder(ctx)
-	tagRepo := tx.Tag(ctx)
-	artistRepo := tx.Artist(ctx)
-	libraryRepo := tx.Library(ctx)
-	albumRepo := tx.Album(ctx)
-	mfRepo := tx.MediaFile(ctx)
+	folderRepo := tx.Folder()
+	tagRepo := tx.Tag()
+	artistRepo := tx.Artist()
+	libraryRepo := tx.Library()
+	albumRepo := tx.Album()
+	mfRepo := tx.MediaFile()
 
 	// Save folder to DB
 	folder := entry.toFolder()
-	err := folderRepo.Put(folder)
+	err := folderRepo.Put(ctx, folder)
 	if err != nil {
 		return fmt.Errorf("persisting folder: %w", err)
 	}
 
 	// Save all tags to DB
-	err = tagRepo.Add(entry.job.lib.ID, entry.tags...)
+	err = tagRepo.Add(ctx, entry.job.lib.ID, entry.tags...)
 	if err != nil {
 		return fmt.Errorf("persisting tags: %w", err)
 	}
 
 	// Save all new/modified artists to DB. Their information will be incomplete, but they will be refreshed later
 	for i := range entry.artists {
-		err = artistRepo.Put(&entry.artists[i], "name",
+		err = artistRepo.Put(ctx, &entry.artists[i], "name",
 			"mbz_artist_id", "sort_artist_name", "order_artist_name", "full_text", "search_normalized", "updated_at")
 		if err != nil {
 			return fmt.Errorf("persisting artist %q: %w", entry.artists[i].Name, err)
 		}
-		err = libraryRepo.AddArtist(entry.job.lib.ID, entry.artists[i].ID)
+		err = libraryRepo.AddArtist(ctx, entry.job.lib.ID, entry.artists[i].ID)
 		if err != nil {
 			return fmt.Errorf("adding artist %q to library: %w", entry.artists[i].Name, err)
 		}
@@ -416,7 +416,7 @@ func (p *phaseFolders) persistFolder(ctx context.Context, tx model.DataStore, en
 
 	// Save all tracks to DB
 	for i := range entry.tracks {
-		err = mfRepo.Put(&entry.tracks[i])
+		err = mfRepo.Put(ctx, &entry.tracks[i])
 		if err != nil {
 			return fmt.Errorf("persisting track %q: %w", entry.tracks[i].Path, err)
 		}
@@ -425,14 +425,14 @@ func (p *phaseFolders) persistFolder(ctx context.Context, tx model.DataStore, en
 	// A re-imported track returns to unresolved so new embedded art is picked up lazily.
 	if len(entry.tracks) > 0 {
 		trackIDs := slice.Map(entry.tracks, func(t model.MediaFile) string { return t.ID })
-		if err := tx.Artwork(ctx).DeleteForItems(model.KindMediaFileArtwork, trackIDs); err != nil {
+		if err := tx.Artwork().DeleteForItems(ctx, model.KindMediaFileArtwork, trackIDs); err != nil {
 			log.Warn(ctx, "Scanner: could not invalidate media_file artwork", err)
 		}
 	}
 
 	// Mark all missing tracks as not available
 	if len(entry.missingTracks) > 0 {
-		err = mfRepo.MarkMissing(true, entry.missingTracks...)
+		err = mfRepo.MarkMissing(ctx, true, entry.missingTracks...)
 		if err != nil {
 			return fmt.Errorf("marking missing tracks: %w", err)
 		}
@@ -442,7 +442,7 @@ func (p *phaseFolders) persistFolder(ctx context.Context, tx model.DataStore, en
 			return mf.AlbumID, struct{}{}
 		})
 		albumsToUpdate := slices.Collect(maps.Keys(groupedMissingTracks))
-		err = albumRepo.Touch(albumsToUpdate...)
+		err = albumRepo.Touch(ctx, albumsToUpdate...)
 		if err != nil {
 			return fmt.Errorf("touching albums %v: %w", albumsToUpdate, err)
 		}
@@ -451,12 +451,12 @@ func (p *phaseFolders) persistFolder(ctx context.Context, tx model.DataStore, en
 	// Enqueue artwork resolution for changed albums/artists. Never fails the scan.
 	// A full scan re-imports every track, so a re-import is no evidence the art changed.
 	if len(queueItems) > 0 {
-		queue := tx.ArtworkQueue(ctx)
+		queue := tx.ArtworkQueue()
 		enqueue := queue.Enqueue
 		if p.state.fullScan {
 			enqueue = queue.EnqueueIfMissing
 		}
-		if err := enqueue(queueItems...); err != nil {
+		if err := enqueue(ctx, queueItems...); err != nil {
 			log.Warn(ctx, "Scanner: could not enqueue artwork resolution", err)
 		}
 	}
@@ -467,7 +467,7 @@ func (p *phaseFolders) persistFolder(ctx context.Context, tx model.DataStore, en
 func (p *phaseFolders) persistAlbum(repo model.AlbumRepository, a *model.Album, idMap map[string]string) error {
 	prevID := idMap[a.ID]
 	log.Trace(p.ctx, "Persisting album", "album", a.Name, "albumArtist", a.AlbumArtist, "id", a.ID, "prevID", cmp.Or(prevID, "nil"))
-	if err := repo.Put(a); err != nil {
+	if err := repo.Put(p.ctx, a); err != nil {
 		return fmt.Errorf("persisting album %s: %w", a.ID, err)
 	}
 	if prevID == "" {
@@ -476,13 +476,13 @@ func (p *phaseFolders) persistAlbum(repo model.AlbumRepository, a *model.Album,
 
 	// Reassign annotation from previous album to new album
 	log.Trace(p.ctx, "Reassigning album annotations", "from", prevID, "to", a.ID, "album", a.Name)
-	if err := repo.ReassignAnnotation(prevID, a.ID); err != nil {
+	if err := repo.ReassignAnnotation(p.ctx, prevID, a.ID); err != nil {
 		log.Warn(p.ctx, "Scanner: Could not reassign annotations", "from", prevID, "to", a.ID, "album", a.Name, err)
 		p.state.sendWarning(fmt.Sprintf("Could not reassign annotations from %s to %s ('%s'): %v", prevID, a.ID, a.Name, err))
 	}
 
 	// Keep created_at field from previous instance of the album
-	if err := repo.CopyAttributes(prevID, a.ID, "created_at"); err != nil {
+	if err := repo.CopyAttributes(p.ctx, prevID, a.ID, "created_at"); err != nil {
 		// Silently ignore when the previous album is not found
 		if !errors.Is(err, model.ErrNotFound) {
 			log.Warn(p.ctx, "Scanner: Could not copy fields", "from", prevID, "to", a.ID, "album", a.Name, err)
@@ -520,14 +520,14 @@ func (p *phaseFolders) finalize(err error) error {
 				continue
 			}
 			folderIDs := slices.Collect(maps.Keys(job.lastUpdates))
-			if err := tx.Folder(ctx).MarkMissing(true, folderIDs...); err != nil {
+			if err := tx.Folder().MarkMissing(ctx, true, folderIDs...); err != nil {
 				return fmt.Errorf("marking missing folders in %s: %w", job.lib.Name, err)
 			}
-			if err := tx.MediaFile(ctx).MarkMissingByFolder(true, folderIDs...); err != nil {
+			if err := tx.MediaFile().MarkMissingByFolder(ctx, true, folderIDs...); err != nil {
 				return fmt.Errorf("marking tracks in missing folders in %s: %w", job.lib.Name, err)
 			}
 			// Touch all albums that have missing folders, so they get refreshed in later phases
-			if _, err := tx.Album(ctx).TouchByMissingFolder(); err != nil {
+			if _, err := tx.Album().TouchByMissingFolder(ctx); err != nil {
 				return fmt.Errorf("touching albums with missing folders in %s: %w", job.lib.Name, err)
 			}
 		}
diff --git a/scanner/phase_2_missing_tracks.go b/scanner/phase_2_missing_tracks.go
index 6ccc9a46c..945257e47 100644
--- a/scanner/phase_2_missing_tracks.go
+++ b/scanner/phase_2_missing_tracks.go
@@ -33,7 +33,7 @@ type missingTracks struct {
 // 4. Updates the database with the new locations of the matched files and removes the old entries.
 // 5. Logs the results and finalizes the phase by reporting the total number of matched files.
 type phaseMissingTracks struct {
-	ctx                       context.Context
+	ctx                       context.Context //nolint:containedctx // phase runs under a single scan ctx
 	ds                        model.DataStore
 	totalMatched              atomic.Uint32
 	state                     *scanState
@@ -71,7 +71,7 @@ func (p *phaseMissingTracks) produce(put func(tracks *missingTracks)) error {
 	}
 	for _, lib := range p.state.libraries {
 		log.Debug(p.ctx, "Scanner: Checking missing tracks", "libraryId", lib.ID, "libraryName", lib.Name)
-		cursor, err := p.ds.MediaFile(p.ctx).GetMissingAndMatching(lib.ID)
+		cursor, err := p.ds.MediaFile().GetMissingAndMatching(p.ctx, lib.ID)
 		if err != nil {
 			return fmt.Errorf("loading missing tracks for library %s: %w", lib.Name, err)
 		}
@@ -232,7 +232,7 @@ func (p *phaseMissingTracks) processCrossLibraryMoves(in *missingTracks) (*missi
 func (p *phaseMissingTracks) findCrossLibraryMatch(missing model.MediaFile) (model.MediaFile, error) {
 	// First tier: Search by MusicBrainz Track ID if available
 	if missing.MbzReleaseTrackID != "" {
-		matches, err := p.ds.MediaFile(p.ctx).FindRecentFilesByMBZTrackID(missing, missing.CreatedAt)
+		matches, err := p.ds.MediaFile().FindRecentFilesByMBZTrackID(p.ctx, missing, missing.CreatedAt)
 		if err != nil {
 			log.Error(p.ctx, "Scanner: Error searching for recent files by MBZ Track ID", "mbzTrackID", missing.MbzReleaseTrackID, err)
 		} else {
@@ -251,7 +251,7 @@ func (p *phaseMissingTracks) findCrossLibraryMatch(missing model.MediaFile) (mod
 	}
 
 	// Second tier: Search by intrinsic properties (title, size, suffix, etc.)
-	matches, err := p.ds.MediaFile(p.ctx).FindRecentFilesByProperties(missing, missing.CreatedAt)
+	matches, err := p.ds.MediaFile().FindRecentFilesByProperties(p.ctx, missing, missing.CreatedAt)
 	if err != nil {
 		log.Error(p.ctx, "Scanner: Error searching for recent files by properties", "missing", missing.Path, err)
 		return model.MediaFile{}, err
@@ -298,25 +298,25 @@ func (p *phaseMissingTracks) moveMatched(target, missing model.MediaFile) error
 		// Update the target media file with the missing file's ID. This effectively "moves" the track
 		// to the new location while keeping its annotations and references intact.
 		moved.ID = missing.ID
-		if err := tx.MediaFile(ctx).Put(&moved); err != nil {
+		if err := tx.MediaFile().Put(ctx, &moved); err != nil {
 			return fmt.Errorf("update matched track: %w", err)
 		}
 
 		// Discard the new mediafile row (the one that was moved to)
-		if err := tx.MediaFile(ctx).Delete(target.ID); err != nil {
+		if err := tx.MediaFile().Delete(ctx, target.ID); err != nil {
 			return fmt.Errorf("delete discarded track: %w", err)
 		}
 
 		if reassignAlbum {
 			// Reassign direct album annotations (starred, rating)
 			log.Debug(ctx, "Scanner: Reassigning album annotations", "from", oldAlbumID, "to", newAlbumID)
-			if err := tx.Album(ctx).ReassignAnnotation(oldAlbumID, newAlbumID); err != nil {
+			if err := tx.Album().ReassignAnnotation(ctx, oldAlbumID, newAlbumID); err != nil {
 				log.Warn(ctx, "Scanner: Could not reassign album annotations", "from", oldAlbumID, "to", newAlbumID, err)
 			}
 
 			// Keep created_at field from previous instance of the album, so moved albums
 			// don't appear in "Recently Added"
-			if err := tx.Album(ctx).CopyAttributes(oldAlbumID, newAlbumID, "created_at"); err != nil {
+			if err := tx.Album().CopyAttributes(ctx, oldAlbumID, newAlbumID, "created_at"); err != nil {
 				if !errors.Is(err, model.ErrNotFound) {
 					log.Warn(ctx, "Scanner: Could not copy album created_at", "from", oldAlbumID, "to", newAlbumID, err)
 				}
@@ -360,7 +360,7 @@ func (p *phaseMissingTracks) purgeMissing() error {
 	var deletedCount int64
 	err := p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
 		var err error
-		deletedCount, err = tx.MediaFile(ctx).DeleteAllMissing()
+		deletedCount, err = tx.MediaFile().DeleteAllMissing(ctx)
 		return err
 	}, "scanner: purge missing")
 	if err != nil {
diff --git a/scanner/phase_2_missing_tracks_test.go b/scanner/phase_2_missing_tracks_test.go
index b7aa52f90..f61aa4244 100644
--- a/scanner/phase_2_missing_tracks_test.go
+++ b/scanner/phase_2_missing_tracks_test.go
@@ -131,8 +131,8 @@ var _ = Describe("phaseMissingTracks", func() {
 			missingTrack := model.MediaFile{ID: "1", PID: "A", Path: "dir1/path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
 			matchedTrack := model.MediaFile{ID: "2", PID: "A", Path: "dir2/path2.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 			in := &missingTracks{
 				missing: []model.MediaFile{missingTrack},
@@ -144,7 +144,7 @@ var _ = Describe("phaseMissingTracks", func() {
 			Expect(phase.totalMatched.Load()).To(Equal(uint32(1)))
 			Expect(state.changesDetected.Load()).To(BeTrue())
 
-			movedTrack, _ := ds.MediaFile(ctx).Get("1")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "1")
 			Expect(movedTrack.Path).To(Equal(matchedTrack.Path))
 		})
 
@@ -156,8 +156,8 @@ var _ = Describe("phaseMissingTracks", func() {
 				probe = &probeTxDS{MockDataStore: ds.(*tests.MockDataStore)}
 				probe.MockedAlbum = tests.CreateMockAlbumRepo()
 				phase = createPhaseMissingTracks(ctx, state, probe)
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&matchedTrack)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &matchedTrack)
 			})
 
 			It("claims the target album before the transaction, so a concurrent move skips it", func() {
@@ -190,8 +190,8 @@ var _ = Describe("phaseMissingTracks", func() {
 			It("keeps the moved track", func() {
 				missingTrack := model.MediaFile{ID: "1", PID: "A", Path: "dir1/path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
 				matchedTrack := model.MediaFile{ID: "2", PID: "A", Path: "dir2/path2.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&matchedTrack)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 				_, err := phase.processMissingTracks(&missingTracks{
 					missing: []model.MediaFile{missingTrack},
@@ -199,7 +199,7 @@ var _ = Describe("phaseMissingTracks", func() {
 				})
 				Expect(err).ToNot(HaveOccurred())
 
-				movedTrack, err := ds.MediaFile(ctx).Get("1")
+				movedTrack, err := ds.MediaFile().Get(ctx, "1")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(movedTrack.Path).To(Equal(matchedTrack.Path))
 			})
@@ -217,8 +217,8 @@ var _ = Describe("phaseMissingTracks", func() {
 				}
 				missingTrack := model.MediaFile{ID: "1", PID: "A", AlbumID: "old-album", Path: "dir1/path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
 				matchedTrack := model.MediaFile{ID: "2", PID: "A", AlbumID: "new-album", Path: "dir2/path2.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&matchedTrack)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 				_, err := phase.processMissingTracks(&missingTracks{
 					missing: []model.MediaFile{missingTrack},
@@ -233,8 +233,8 @@ var _ = Describe("phaseMissingTracks", func() {
 			missingTrack := model.MediaFile{ID: "1", PID: "A", Path: "path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
 			matchedTrack := model.MediaFile{ID: "2", PID: "A", Path: "path1.flac", Tags: model.Tags{"title": []string{"title1"}}, Size: 200}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 			in := &missingTracks{
 				missing: []model.MediaFile{missingTrack},
@@ -246,7 +246,7 @@ var _ = Describe("phaseMissingTracks", func() {
 			Expect(phase.totalMatched.Load()).To(Equal(uint32(1)))
 			Expect(state.changesDetected.Load()).To(BeTrue())
 
-			movedTrack, _ := ds.MediaFile(ctx).Get("1")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "1")
 			Expect(movedTrack.Path).To(Equal(matchedTrack.Path))
 			Expect(movedTrack.Size).To(Equal(matchedTrack.Size))
 		})
@@ -255,8 +255,8 @@ var _ = Describe("phaseMissingTracks", func() {
 			missingTrack := model.MediaFile{ID: "1", PID: "A", Path: "dir1/path1.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
 			matchedTrack := model.MediaFile{ID: "2", PID: "A", Path: "dir2/path2.flac", Tags: model.Tags{"title": []string{"different title"}}, Size: 200}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 			in := &missingTracks{
 				missing: []model.MediaFile{missingTrack},
@@ -268,7 +268,7 @@ var _ = Describe("phaseMissingTracks", func() {
 			Expect(phase.totalMatched.Load()).To(Equal(uint32(1)))
 			Expect(state.changesDetected.Load()).To(BeTrue())
 
-			movedTrack, _ := ds.MediaFile(ctx).Get("1")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "1")
 			Expect(movedTrack.Path).To(Equal(matchedTrack.Path))
 			Expect(movedTrack.Size).To(Equal(matchedTrack.Size))
 		})
@@ -278,9 +278,9 @@ var _ = Describe("phaseMissingTracks", func() {
 			matchedEquivalent := model.MediaFile{ID: "2", PID: "A", Path: "dir1/file1.flac", Tags: model.Tags{"title": []string{"title1"}}, Size: 200}
 			matchedExact := model.MediaFile{ID: "3", PID: "A", Path: "dir2/file2.mp3", Tags: model.Tags{"title": []string{"title1"}}, Size: 100}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedEquivalent)
-			_ = ds.MediaFile(ctx).Put(&matchedExact)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedEquivalent)
+			_ = ds.MediaFile().Put(ctx, &matchedExact)
 
 			in := &missingTracks{
 				missing: []model.MediaFile{missingTrack},
@@ -293,7 +293,7 @@ var _ = Describe("phaseMissingTracks", func() {
 			Expect(phase.totalMatched.Load()).To(Equal(uint32(1)))
 			Expect(state.changesDetected.Load()).To(BeTrue())
 
-			movedTrack, _ := ds.MediaFile(ctx).Get("1")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "1")
 			Expect(movedTrack.Path).To(Equal(matchedExact.Path))
 			Expect(movedTrack.Size).To(Equal(matchedExact.Size))
 		})
@@ -303,9 +303,9 @@ var _ = Describe("phaseMissingTracks", func() {
 			matched1 := model.MediaFile{ID: "2", PID: "A", Path: "dir1/file2.flac", Title: "another title", Size: 200}
 			matched2 := model.MediaFile{ID: "3", PID: "A", Path: "dir2/file3.mp3", Title: "different title", Size: 100}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matched1)
-			_ = ds.MediaFile(ctx).Put(&matched2)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matched1)
+			_ = ds.MediaFile().Put(ctx, &matched2)
 
 			in := &missingTracks{
 				missing: []model.MediaFile{missingTrack},
@@ -318,7 +318,7 @@ var _ = Describe("phaseMissingTracks", func() {
 			Expect(state.changesDetected.Load()).To(BeFalse())
 
 			// The missing track should still be the same
-			movedTrack, _ := ds.MediaFile(ctx).Get("1")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "1")
 			Expect(movedTrack.Path).To(Equal(missingTrack.Path))
 			Expect(movedTrack.Title).To(Equal(missingTrack.Title))
 			Expect(movedTrack.Size).To(Equal(missingTrack.Size))
@@ -333,9 +333,9 @@ var _ = Describe("phaseMissingTracks", func() {
 			missingTrack2 := model.MediaFile{ID: "2", PID: "A", Path: "old_dir2/song.mp3", Title: "title1", Size: 100}
 			matchedTrack := model.MediaFile{ID: "3", PID: "A", Path: "new_dir/song.mp3", Title: "title1", Size: 200}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack1)
-			_ = ds.MediaFile(ctx).Put(&missingTrack2)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack1)
+			_ = ds.MediaFile().Put(ctx, &missingTrack2)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 			in := &missingTracks{
 				missing: []model.MediaFile{missingTrack1, missingTrack2},
@@ -349,11 +349,11 @@ var _ = Describe("phaseMissingTracks", func() {
 			Expect(state.changesDetected.Load()).To(BeTrue())
 
 			// The matched track should have been consumed by the first missing track
-			movedTrack, _ := ds.MediaFile(ctx).Get("1")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "1")
 			Expect(movedTrack.Path).To(Equal(matchedTrack.Path))
 
 			// The second missing track should remain unchanged
-			unmatchedTrack, _ := ds.MediaFile(ctx).Get("2")
+			unmatchedTrack, _ := ds.MediaFile().Get(ctx, "2")
 			Expect(unmatchedTrack.Path).To(Equal(missingTrack2.Path))
 		})
 
@@ -361,8 +361,8 @@ var _ = Describe("phaseMissingTracks", func() {
 			missingTrack := model.MediaFile{ID: "1", PID: "A", Path: "path1.mp3", Tags: model.Tags{"title": []string{"title1"}}}
 			matchedTrack := model.MediaFile{ID: "2", PID: "A", Path: "path1.mp3", Tags: model.Tags{"title": []string{"title1"}}}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 			in := &missingTracks{
 				missing: []model.MediaFile{missingTrack},
@@ -370,7 +370,7 @@ var _ = Describe("phaseMissingTracks", func() {
 			}
 
 			// Simulate an error when moving the matched track by deleting the track from the DB
-			_ = ds.MediaFile(ctx).Delete("2")
+			_ = ds.MediaFile().Delete(ctx, "2")
 
 			_, err := phase.processMissingTracks(in)
 			Expect(err).To(HaveOccurred())
@@ -514,8 +514,8 @@ var _ = Describe("phaseMissingTracks", func() {
 					CreatedAt:         scanStartTime.Add(-10 * time.Minute),
 				}
 
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&movedTrack)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &movedTrack)
 
 				in := &missingTracks{
 					lib:     model.Library{ID: 1, Name: "Library 1"},
@@ -529,7 +529,7 @@ var _ = Describe("phaseMissingTracks", func() {
 				Expect(state.changesDetected.Load()).To(BeTrue())
 
 				// Verify the move was performed
-				updatedTrack, _ := ds.MediaFile(ctx).Get("missing1")
+				updatedTrack, _ := ds.MediaFile().Get(ctx, "missing1")
 				Expect(updatedTrack.Path).To(Equal("/lib2/track.mp3"))
 				Expect(updatedTrack.LibraryID).To(Equal(2))
 			})
@@ -566,8 +566,8 @@ var _ = Describe("phaseMissingTracks", func() {
 					CreatedAt:         scanStartTime.Add(-10 * time.Minute),
 				}
 
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&movedTrack)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &movedTrack)
 
 				in := &missingTracks{
 					lib:     model.Library{ID: 1, Name: "Library 1"},
@@ -581,7 +581,7 @@ var _ = Describe("phaseMissingTracks", func() {
 				Expect(state.changesDetected.Load()).To(BeTrue())
 
 				// Verify the move was performed
-				updatedTrack, _ := ds.MediaFile(ctx).Get("missing2")
+				updatedTrack, _ := ds.MediaFile().Get(ctx, "missing2")
 				Expect(updatedTrack.Path).To(Equal("/lib2/track2.flac"))
 				Expect(updatedTrack.LibraryID).To(Equal(2))
 			})
@@ -612,8 +612,8 @@ var _ = Describe("phaseMissingTracks", func() {
 					CreatedAt:         scanStartTime.Add(-10 * time.Minute),
 				}
 
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&sameLibTrack)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &sameLibTrack)
 
 				in := &missingTracks{
 					lib:     model.Library{ID: 1, Name: "Library 1"},
@@ -670,9 +670,9 @@ var _ = Describe("phaseMissingTracks", func() {
 					CreatedAt:         scanStartTime.Add(-5 * time.Minute),
 				}
 
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&mbzTrack)
-				_ = ds.MediaFile(ctx).Put(&intrinsicTrack)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &mbzTrack)
+				_ = ds.MediaFile().Put(ctx, &intrinsicTrack)
 
 				in := &missingTracks{
 					lib:     model.Library{ID: 1, Name: "Library 1"},
@@ -686,7 +686,7 @@ var _ = Describe("phaseMissingTracks", func() {
 				Expect(state.changesDetected.Load()).To(BeTrue())
 
 				// Verify the MBZ track was chosen (not the intrinsic one)
-				updatedTrack, _ := ds.MediaFile(ctx).Get("missing4")
+				updatedTrack, _ := ds.MediaFile().Get(ctx, "missing4")
 				Expect(updatedTrack.Path).To(Equal("/lib2/track4.mp3"))
 				Expect(updatedTrack.LibraryID).To(Equal(2))
 			})
@@ -718,8 +718,8 @@ var _ = Describe("phaseMissingTracks", func() {
 					CreatedAt:         scanStartTime.Add(-10 * time.Minute),
 				}
 
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&equivalentTrack)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &equivalentTrack)
 
 				in := &missingTracks{
 					lib:     model.Library{ID: 1, Name: "Library 1"},
@@ -733,7 +733,7 @@ var _ = Describe("phaseMissingTracks", func() {
 				Expect(state.changesDetected.Load()).To(BeTrue())
 
 				// Verify the equivalent match was accepted
-				updatedTrack, _ := ds.MediaFile(ctx).Get("missing5")
+				updatedTrack, _ := ds.MediaFile().Get(ctx, "missing5")
 				Expect(updatedTrack.Path).To(Equal("/lib2/different/track5.mp3"))
 				Expect(updatedTrack.LibraryID).To(Equal(2))
 			})
@@ -788,9 +788,9 @@ var _ = Describe("phaseMissingTracks", func() {
 					CreatedAt:         scanStartTime.Add(-5 * time.Minute),
 				}
 
-				_ = ds.MediaFile(ctx).Put(&missingTrack)
-				_ = ds.MediaFile(ctx).Put(&match1)
-				_ = ds.MediaFile(ctx).Put(&match2)
+				_ = ds.MediaFile().Put(ctx, &missingTrack)
+				_ = ds.MediaFile().Put(ctx, &match1)
+				_ = ds.MediaFile().Put(ctx, &match2)
 
 				in := &missingTracks{
 					lib:     model.Library{ID: 1, Name: "Library 1"},
@@ -804,7 +804,7 @@ var _ = Describe("phaseMissingTracks", func() {
 				Expect(state.changesDetected.Load()).To(BeFalse())
 
 				// Verify no move was performed
-				unchangedTrack, _ := ds.MediaFile(ctx).Get("missing6")
+				unchangedTrack, _ := ds.MediaFile().Get(ctx, "missing6")
 				Expect(unchangedTrack.Path).To(Equal("/lib1/track6.mp3"))
 				Expect(unchangedTrack.LibraryID).To(Equal(1))
 			})
@@ -844,7 +844,7 @@ var _ = Describe("phaseMissingTracks", func() {
 		var albumRepo *tests.MockAlbumRepo
 
 		BeforeEach(func() {
-			albumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
+			albumRepo = ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.ReassignAnnotationCalls = make(map[string]string)
 			albumRepo.CopyAttributesCalls = make(map[string]string)
 		})
@@ -868,8 +868,8 @@ var _ = Describe("phaseMissingTracks", func() {
 				Size:      100,
 			}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 			in := &missingTracks{
 				missing: []model.MediaFile{missingTrack},
@@ -879,7 +879,7 @@ var _ = Describe("phaseMissingTracks", func() {
 			_, err := phase.processMissingTracks(in)
 			Expect(err).ToNot(HaveOccurred())
 
-			movedTrack, _ := ds.MediaFile(ctx).Get("1")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "1")
 			Expect(movedTrack.Path).To(Equal("new/song.mp3"))
 			Expect(movedTrack.CreatedAt).To(Equal(originalTime))
 		})
@@ -905,21 +905,21 @@ var _ = Describe("phaseMissingTracks", func() {
 				{ID: "new-album", LibraryID: 2, CreatedAt: time.Now()},
 			})
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 			err := phase.moveMatched(matchedTrack, missingTrack)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Track's created_at should be preserved from the missing file
-			movedTrack, _ := ds.MediaFile(ctx).Get("missing-ca")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "missing-ca")
 			Expect(movedTrack.CreatedAt).To(Equal(originalTime))
 
 			// Album's created_at should be copied from old to new
 			Expect(albumRepo.CopyAttributesCalls).To(HaveKeyWithValue("old-album", "new-album"))
 
 			// Verify the new album's CreatedAt was actually updated
-			newAlbum, err := albumRepo.Get("new-album")
+			newAlbum, err := albumRepo.Get(ctx, "new-album")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(newAlbum.CreatedAt).To(Equal(originalTime))
 		})
@@ -939,14 +939,14 @@ var _ = Describe("phaseMissingTracks", func() {
 				CreatedAt: time.Now(),
 			}
 
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 
 			err := phase.moveMatched(matchedTrack, missingTrack)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Track's created_at should still be preserved
-			movedTrack, _ := ds.MediaFile(ctx).Get("missing-same")
+			movedTrack, _ := ds.MediaFile().Get(ctx, "missing-same")
 			Expect(movedTrack.CreatedAt).To(Equal(originalTime))
 
 			// CopyAttributes should NOT have been called (same album)
@@ -964,7 +964,7 @@ var _ = Describe("phaseMissingTracks", func() {
 		)
 
 		BeforeEach(func() {
-			albumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
+			albumRepo = ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.ReassignAnnotationCalls = make(map[string]string)
 
 			oldAlbumID = "old-album-id"
@@ -999,8 +999,8 @@ var _ = Describe("phaseMissingTracks", func() {
 			}
 
 			// Store both tracks in the database
-			_ = ds.MediaFile(ctx).Put(&missingTrack)
-			_ = ds.MediaFile(ctx).Put(&matchedTrack)
+			_ = ds.MediaFile().Put(ctx, &missingTrack)
+			_ = ds.MediaFile().Put(ctx, &matchedTrack)
 		})
 
 		When("album ID changes during cross-library move", func() {
@@ -1033,7 +1033,7 @@ var _ = Describe("phaseMissingTracks", func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				// Verify that the track was still moved (ID should be updated)
-				movedTrack, err := ds.MediaFile(ctx).Get(missingTrack.ID)
+				movedTrack, err := ds.MediaFile().Get(ctx, missingTrack.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(movedTrack.Path).To(Equal(matchedTrack.Path))
 			})
diff --git a/scanner/phase_3_refresh_albums.go b/scanner/phase_3_refresh_albums.go
index 964ab7408..58ad9cb80 100644
--- a/scanner/phase_3_refresh_albums.go
+++ b/scanner/phase_3_refresh_albums.go
@@ -26,7 +26,7 @@ import (
 //  5. As a last step, it refreshes the artist statistics to reflect the changes
 type phaseRefreshAlbums struct {
 	ds        model.DataStore
-	ctx       context.Context
+	ctx       context.Context //nolint:containedctx // phase runs under a single scan ctx
 	refreshed atomic.Uint32
 	skipped   atomic.Uint32
 	state     *scanState
@@ -47,7 +47,7 @@ func (p *phaseRefreshAlbums) producer() ppl.Producer[*model.Album] {
 func (p *phaseRefreshAlbums) produce(put func(album *model.Album)) error {
 	count := 0
 	for _, lib := range p.state.libraries {
-		cursor, err := p.ds.Album(p.ctx).GetTouchedAlbums(lib.ID)
+		cursor, err := p.ds.Album().GetTouchedAlbums(p.ctx, lib.ID)
 		if err != nil {
 			return fmt.Errorf("loading touched albums: %w", err)
 		}
@@ -76,7 +76,7 @@ func (p *phaseRefreshAlbums) stages() []ppl.Stage[*model.Album] {
 }
 
 func (p *phaseRefreshAlbums) filterUnmodified(album *model.Album) (*model.Album, error) {
-	mfs, err := p.ds.MediaFile(p.ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album_id": album.ID}})
+	mfs, err := p.ds.MediaFile().GetAll(p.ctx, model.QueryOptions{Filters: squirrel.Eq{"album_id": album.ID}})
 	if err != nil {
 		log.Error(p.ctx, "Error loading media files for album", "album_id", album.ID, err)
 		return nil, err
@@ -104,7 +104,7 @@ func (p *phaseRefreshAlbums) refreshAlbum(album *model.Album) (*model.Album, err
 	}
 	start := time.Now()
 	err := p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
-		return tx.Album(ctx).Put(album)
+		return tx.Album().Put(ctx, album)
 	}, "scanner: refresh album")
 	log.Debug(p.ctx, "Scanner: refreshing album", "album_id", album.ID, "name", album.Name, "songCount", album.SongCount, "elapsed", time.Since(start), err)
 	if err != nil {
@@ -135,7 +135,7 @@ func (p *phaseRefreshAlbums) finalize(err error) error {
 	var cnt int64
 	err = p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
 		var txErr error
-		cnt, txErr = tx.Album(ctx).RefreshPlayCounts()
+		cnt, txErr = tx.Album().RefreshPlayCounts(ctx)
 		return txErr
 	}, "scanner: refresh album play counts")
 	if err != nil {
@@ -147,7 +147,7 @@ func (p *phaseRefreshAlbums) finalize(err error) error {
 	start = time.Now()
 	err = p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
 		var txErr error
-		cnt, txErr = tx.Artist(ctx).RefreshPlayCounts()
+		cnt, txErr = tx.Artist().RefreshPlayCounts(ctx)
 		return txErr
 	}, "scanner: refresh artist play counts")
 	if err != nil {
diff --git a/scanner/phase_3_refresh_albums_test.go b/scanner/phase_3_refresh_albums_test.go
index 1f0baf428..2743da070 100644
--- a/scanner/phase_3_refresh_albums_test.go
+++ b/scanner/phase_3_refresh_albums_test.go
@@ -104,7 +104,7 @@ var _ = Describe("phaseRefreshAlbums", func() {
 
 	Describe("refreshAlbum", func() {
 		It("refreshes the album in the database", func() {
-			Expect(albumRepo.CountAll()).To(Equal(int64(0)))
+			Expect(albumRepo.CountAll(ctx)).To(Equal(int64(0)))
 
 			album := &model.Album{ID: "album1", Name: "Album 1"}
 			result, err := phase.refreshAlbum(album)
@@ -112,7 +112,7 @@ var _ = Describe("phaseRefreshAlbums", func() {
 			Expect(result).ToNot(BeNil())
 			Expect(result.ID).To(Equal("album1"))
 
-			savedAlbum, err := albumRepo.Get("album1")
+			savedAlbum, err := albumRepo.Get(ctx, "album1")
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(savedAlbum).ToNot(BeNil())
diff --git a/scanner/phase_4_playlists.go b/scanner/phase_4_playlists.go
index 4e11fa81d..bb67c1ba3 100644
--- a/scanner/phase_4_playlists.go
+++ b/scanner/phase_4_playlists.go
@@ -19,7 +19,7 @@ import (
 )
 
 type phasePlaylists struct {
-	ctx           context.Context
+	ctx           context.Context //nolint:containedctx // phase runs under a single scan ctx
 	scanState     *scanState
 	ds            model.DataStore
 	pls           playlists.Playlists
@@ -53,7 +53,7 @@ func (p *phasePlaylists) produce(put func(entry *model.Folder)) error {
 	// Resolve the admin at phase time (the producer runs late in the scan), so an
 	// admin created while the scan was in progress is picked up. Assigned once,
 	// before any put() below, so the channel send synchronizes it with the stages.
-	admin, err := p.ds.User(p.ctx).FindFirstAdmin()
+	admin, err := p.ds.User().FindFirstAdmin(p.ctx)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return fmt.Errorf("finding admin user: %w", err)
 	}
@@ -71,9 +71,9 @@ func (p *phasePlaylists) produce(put func(entry *model.Folder)) error {
 	p.pendingImport = pending
 	var cursor model.FolderCursor
 	if p.pendingImport {
-		cursor, err = p.ds.Folder(p.ctx).GetAllWithPlaylists()
+		cursor, err = p.ds.Folder().GetAllWithPlaylists(p.ctx)
 	} else {
-		cursor, err = p.ds.Folder(p.ctx).GetTouchedWithPlaylists()
+		cursor, err = p.ds.Folder().GetTouchedWithPlaylists(p.ctx)
 	}
 	if err != nil {
 		return fmt.Errorf("loading folders with playlists: %w", err)
@@ -102,7 +102,7 @@ func (p *phasePlaylists) produce(put func(entry *model.Folder)) error {
 // the scan does not complete as successful without recording the recovery).
 func (p *phasePlaylists) deferImport() error {
 	err := p.ds.WithTxRetry(p.ctx, func(ctx context.Context, tx model.DataStore) error {
-		return tx.Property(ctx).Put(consts.PlaylistsImportPendingFlagKey, "1")
+		return tx.Property().Put(ctx, consts.PlaylistsImportPendingFlagKey, "1")
 	}, "scanner: defer playlist import")
 	if err != nil {
 		return fmt.Errorf("recording pending playlist import: %w", err)
@@ -113,7 +113,7 @@ func (p *phasePlaylists) deferImport() error {
 }
 
 func (p *phasePlaylists) importPending() (bool, error) {
-	v, err := p.ds.Property(p.ctx).DefaultGet(consts.PlaylistsImportPendingFlagKey, "0")
+	v, err := p.ds.Property().DefaultGet(p.ctx, consts.PlaylistsImportPendingFlagKey, "0")
 	return v == "1", err
 }
 
@@ -150,7 +150,7 @@ func (p *phasePlaylists) processPlaylistsInFolder(folder *model.Folder) (*model.
 		}
 		item := model.ArtworkQueueItem{ItemKind: model.KindPlaylistArtwork.Prefix(), ItemID: pls.ID, ImageType: model.ImageTypePrimary,
 			Priority: model.ArtworkPriorityScan}
-		if err := p.ds.ArtworkQueue(p.ctx).Enqueue(item); err != nil {
+		if err := p.ds.ArtworkQueue().Enqueue(p.ctx, item); err != nil {
 			log.Warn(p.ctx, "Scanner: could not enqueue playlist artwork", "id", pls.ID, err)
 		}
 		p.refreshed.Add(1)
@@ -167,7 +167,7 @@ func (p *phasePlaylists) finalize(err error) error {
 		p.scanState.changesDetected.Store(true)
 	}
 	if p.pendingImport && err == nil {
-		if derr := p.ds.Property(p.ctx).Delete(consts.PlaylistsImportPendingFlagKey); derr != nil {
+		if derr := p.ds.Property().Delete(p.ctx, consts.PlaylistsImportPendingFlagKey); derr != nil {
 			log.Warn(p.ctx, "Scanner: Could not clear pending playlist-import flag", derr)
 		}
 	}
diff --git a/scanner/phase_4_playlists_test.go b/scanner/phase_4_playlists_test.go
index 93ec1a36d..303af338f 100644
--- a/scanner/phase_4_playlists_test.go
+++ b/scanner/phase_4_playlists_test.go
@@ -38,7 +38,7 @@ var _ = Describe("phasePlaylists", func() {
 		folderRepo = &mockFolderRepository{}
 		userRepo = tests.CreateMockUserRepo()
 		// An admin user exists by default, so playlist import proceeds.
-		Expect(userRepo.Put(&model.User{ID: "123", UserName: "admin", IsAdmin: true})).To(Succeed())
+		Expect(userRepo.Put(ctx, &model.User{ID: "123", UserName: "admin", IsAdmin: true})).To(Succeed())
 		propRepo = &tests.MockedPropertyRepo{}
 		ds = &tests.MockDataStore{
 			MockedFolder:   folderRepo,
@@ -102,7 +102,7 @@ var _ = Describe("phasePlaylists", func() {
 
 			Expect(err).ToNot(HaveOccurred())
 			Expect(called).To(BeFalse())
-			v, _ := propRepo.Get(consts.PlaylistsImportPendingFlagKey)
+			v, _ := propRepo.Get(ctx, consts.PlaylistsImportPendingFlagKey)
 			Expect(v).To(Equal("1"))
 		})
 
@@ -113,7 +113,7 @@ var _ = Describe("phasePlaylists", func() {
 
 			Expect(err).To(MatchError(ContainSubstring("finding admin user")))
 			// Must NOT have set the pending flag on a real error.
-			_, getErr := propRepo.Get(consts.PlaylistsImportPendingFlagKey)
+			_, getErr := propRepo.Get(ctx, consts.PlaylistsImportPendingFlagKey)
 			Expect(getErr).To(HaveOccurred())
 		})
 
@@ -127,7 +127,7 @@ var _ = Describe("phasePlaylists", func() {
 		})
 
 		It("imports all playlist folders when the pending flag is set", func() {
-			Expect(propRepo.Put(consts.PlaylistsImportPendingFlagKey, "1")).To(Succeed())
+			Expect(propRepo.Put(ctx, consts.PlaylistsImportPendingFlagKey, "1")).To(Succeed())
 			folderRepo.SetAllData(map[*model.Folder]error{
 				{Path: "/path/to/folder1"}: nil,
 				{Path: "/path/to/folder2"}: nil,
@@ -146,22 +146,22 @@ var _ = Describe("phasePlaylists", func() {
 
 	Describe("finalize", func() {
 		It("clears the pending flag after a successful pending import", func() {
-			Expect(propRepo.Put(consts.PlaylistsImportPendingFlagKey, "1")).To(Succeed())
+			Expect(propRepo.Put(ctx, consts.PlaylistsImportPendingFlagKey, "1")).To(Succeed())
 			phase.pendingImport = true
 
 			Expect(phase.finalize(nil)).To(Succeed())
 
-			_, err := propRepo.Get(consts.PlaylistsImportPendingFlagKey)
+			_, err := propRepo.Get(ctx, consts.PlaylistsImportPendingFlagKey)
 			Expect(err).To(HaveOccurred()) // deleted
 		})
 
 		It("keeps the pending flag when the import failed", func() {
-			Expect(propRepo.Put(consts.PlaylistsImportPendingFlagKey, "1")).To(Succeed())
+			Expect(propRepo.Put(ctx, consts.PlaylistsImportPendingFlagKey, "1")).To(Succeed())
 			phase.pendingImport = true
 
 			Expect(phase.finalize(errors.New("boom"))).To(HaveOccurred())
 
-			v, _ := propRepo.Get(consts.PlaylistsImportPendingFlagKey)
+			v, _ := propRepo.Get(ctx, consts.PlaylistsImportPendingFlagKey)
 			Expect(v).To(Equal("1"))
 		})
 	})
@@ -204,7 +204,7 @@ var _ = Describe("phasePlaylists", func() {
 			_, err := phase.processPlaylistsInFolder(folder)
 			Expect(err).ToNot(HaveOccurred())
 
-			queued, err := ds.ArtworkQueue(ctx).DequeueBatch(10)
+			queued, err := ds.ArtworkQueue().DequeueBatch(ctx, 10)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(queued).To(ContainElement(SatisfyAll(
 				HaveField("ItemKind", "pl"),
@@ -264,11 +264,11 @@ func cursorFromData(data map[*model.Folder]error) model.FolderCursor {
 	}
 }
 
-func (f *mockFolderRepository) GetTouchedWithPlaylists() (model.FolderCursor, error) {
+func (f *mockFolderRepository) GetTouchedWithPlaylists(context.Context) (model.FolderCursor, error) {
 	return cursorFromData(f.data), nil
 }
 
-func (f *mockFolderRepository) GetAllWithPlaylists() (model.FolderCursor, error) {
+func (f *mockFolderRepository) GetAllWithPlaylists(context.Context) (model.FolderCursor, error) {
 	return cursorFromData(f.allData), nil
 }
 
diff --git a/scanner/scanner.go b/scanner/scanner.go
index a8a192771..cd2fe3c8d 100644
--- a/scanner/scanner.go
+++ b/scanner/scanner.go
@@ -88,7 +88,7 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 	}
 
 	// Get libraries and optionally filter by targets
-	allLibs, err := s.ds.Library(ctx).GetAll()
+	allLibs, err := s.ds.Library().GetAll(ctx)
 	if err != nil {
 		state.sendWarning(fmt.Sprintf("getting libraries: %s", err))
 		return
@@ -131,8 +131,8 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 	if state.isSelectiveScan() {
 		scanType += "-selective"
 	}
-	_ = s.ds.Property(ctx).Put(consts.LastScanTypeKey, scanType)
-	_ = s.ds.Property(ctx).Put(consts.LastScanStartTimeKey, startTime.Format(time.RFC3339))
+	_ = s.ds.Property().Put(ctx, consts.LastScanTypeKey, scanType)
+	_ = s.ds.Property().Put(ctx, consts.LastScanStartTimeKey, startTime.Format(time.RFC3339))
 
 	// if there was a full scan in progress, force a full scan
 	if !state.fullScan {
@@ -141,9 +141,9 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 				log.Info(ctx, "Scanner: Interrupted full scan detected", "lib", lib.Name)
 				state.fullScan = true
 				if state.isSelectiveScan() {
-					_ = s.ds.Property(ctx).Put(consts.LastScanTypeKey, "full-selective")
+					_ = s.ds.Property().Put(ctx, consts.LastScanTypeKey, "full-selective")
 				} else {
-					_ = s.ds.Property(ctx).Put(consts.LastScanTypeKey, "full")
+					_ = s.ds.Property().Put(ctx, consts.LastScanTypeKey, "full")
 				}
 				break
 			}
@@ -190,12 +190,12 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 	)
 	if err != nil {
 		log.Error(ctx, "Scanner: Finished with error", "duration", time.Since(startTime), err)
-		_ = s.ds.Property(ctx).Put(consts.LastScanErrorKey, err.Error())
+		_ = s.ds.Property().Put(ctx, consts.LastScanErrorKey, err.Error())
 		state.sendError(err)
 		return
 	}
 
-	_ = s.ds.Property(ctx).Put(consts.LastScanErrorKey, "")
+	_ = s.ds.Property().Put(ctx, consts.LastScanErrorKey, "")
 
 	if state.changesDetected.Load() {
 		state.sendProgress(&ProgressInfo{ChangesDetected: true})
@@ -218,7 +218,7 @@ func (s *scannerImpl) prepareLibrariesForScan(ctx context.Context, state *scanSt
 		if lib.LastScanStartedAt.IsZero() {
 			// This is a new scan - mark it as started
 			err := s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
-				return tx.Library(ctx).ScanBegin(lib.ID, state.fullScan)
+				return tx.Library().ScanBegin(ctx, lib.ID, state.fullScan)
 			}, "scanner: begin library scan")
 			if err != nil {
 				log.Error(ctx, "Scanner: Error marking scan start", "lib", lib.Name, err)
@@ -227,7 +227,7 @@ func (s *scannerImpl) prepareLibrariesForScan(ctx context.Context, state *scanSt
 			}
 
 			// Reload library to get updated state (timestamps, etc.)
-			reloadedLib, err := s.ds.Library(ctx).Get(lib.ID)
+			reloadedLib, err := s.ds.Library().Get(ctx, lib.ID)
 			if err != nil {
 				log.Error(ctx, "Scanner: Error reloading library", "lib", lib.Name, err)
 				state.sendWarning(err.Error())
@@ -291,7 +291,7 @@ func (s *scannerImpl) runEnqueueMissingArtwork(ctx context.Context, state *scanS
 			var n int64
 			err := s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
 				var err error
-				n, err = tx.ArtworkQueue(ctx).EnqueueAllMissing(kind, model.ArtworkPriorityScan)
+				n, err = tx.ArtworkQueue().EnqueueAllMissing(ctx, kind, model.ArtworkPriorityScan)
 				return err
 			}, "scanner: enqueue missing artwork")
 			if err != nil {
@@ -312,7 +312,7 @@ func (s *scannerImpl) runRefreshStats(ctx context.Context, state *scanState) fun
 			return nil
 		}
 		start := time.Now()
-		stats, err := s.ds.Artist(ctx).RefreshStats(state.fullScan)
+		stats, err := s.ds.Artist().RefreshStats(ctx, state.fullScan)
 		if err != nil {
 			log.Error(ctx, "Scanner: Error refreshing artists stats", err)
 			return fmt.Errorf("refreshing artists stats: %w", err)
@@ -321,7 +321,7 @@ func (s *scannerImpl) runRefreshStats(ctx context.Context, state *scanState) fun
 
 		start = time.Now()
 		err = s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
-			return tx.Tag(ctx).UpdateCounts()
+			return tx.Tag().UpdateCounts(ctx)
 		}, "scanner: update tag counts")
 		if err != nil {
 			log.Error(ctx, "Scanner: Error updating tag counts", err)
@@ -337,18 +337,18 @@ func (s *scannerImpl) runUpdateLibraries(ctx context.Context, state *scanState)
 		start := time.Now()
 		return s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
 			for _, lib := range state.libraries {
-				if err := tx.Library(ctx).ScanEnd(lib.ID); err != nil {
+				if err := tx.Library().ScanEnd(ctx, lib.ID); err != nil {
 					return fmt.Errorf("updating last scan completed for %s: %w", lib.Name, err)
 				}
-				if err := tx.Property(ctx).Put(consts.PIDTrackKey, conf.Server.PID.Track); err != nil {
+				if err := tx.Property().Put(ctx, consts.PIDTrackKey, conf.Server.PID.Track); err != nil {
 					return fmt.Errorf("updating track PID conf: %w", err)
 				}
-				if err := tx.Property(ctx).Put(consts.PIDAlbumKey, conf.Server.PID.Album); err != nil {
+				if err := tx.Property().Put(ctx, consts.PIDAlbumKey, conf.Server.PID.Album); err != nil {
 					return fmt.Errorf("updating album PID conf: %w", err)
 				}
 				if state.changesDetected.Load() {
 					log.Debug(ctx, "Scanner: Refreshing library stats", "lib", lib.Name)
-					if err := tx.Library(ctx).RefreshStats(lib.ID); err != nil {
+					if err := tx.Library().RefreshStats(ctx, lib.ID); err != nil {
 						return fmt.Errorf("refreshing library stats for %s: %w", lib.Name, err)
 					}
 				} else {
diff --git a/scanner/scanner_benchmark_test.go b/scanner/scanner_benchmark_test.go
index 65410d500..e6797df36 100644
--- a/scanner/scanner_benchmark_test.go
+++ b/scanner/scanner_benchmark_test.go
@@ -82,7 +82,7 @@ func BenchmarkScan(b *testing.B) {
 	})
 
 	lib := model.Library{ID: 1, Name: "Fake Library", Path: "fake:///music"}
-	err := ds.Library(context.Background()).Put(&lib)
+	err := ds.Library().Put(b.Context(), &lib)
 	if err != nil {
 		b.Fatal(err)
 	}
diff --git a/scanner/scanner_multilibrary_test.go b/scanner/scanner_multilibrary_test.go
index c0d5d4ece..546baf756 100644
--- a/scanner/scanner_multilibrary_test.go
+++ b/scanner/scanner_multilibrary_test.go
@@ -75,7 +75,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			IsAdmin:     true,
 			NewPassword: "password",
 		}
-		Expect(ds.User(ctx).Put(&adminUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &adminUser)).To(Succeed())
 
 		s = scanner.New(ctx, ds, events.NoopBroker(),
 			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
@@ -83,8 +83,8 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 		// Create two test libraries (let DB auto-assign IDs)
 		lib1 = model.Library{Name: "Rock Collection", Path: "rock:///music"}
 		lib2 = model.Library{Name: "Jazz Collection", Path: "jazz:///music"}
-		Expect(ds.Library(ctx).Put(&lib1)).To(Succeed())
-		Expect(ds.Library(ctx).Put(&lib2)).To(Succeed())
+		Expect(ds.Library().Put(ctx, &lib1)).To(Succeed())
+		Expect(ds.Library().Put(ctx, &lib2)).To(Succeed())
 	})
 
 	runScanner := func(ctx context.Context, fullScan bool) error {
@@ -122,7 +122,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Check Rock library media files
-				rockFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				rockFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID},
 					Sort:    "title",
 				})
@@ -138,7 +138,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				}
 
 				// Check Jazz library media files
-				jazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				jazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 					Sort:    "title",
 				})
@@ -158,7 +158,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Check Rock library albums
-				rockAlbums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+				rockAlbums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID},
 					Sort:    "name",
 				})
@@ -172,7 +172,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(rockAlbums[1].SongCount).To(Equal(2))
 
 				// Check Jazz library albums
-				jazzAlbums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+				jazzAlbums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 					Sort:    "name",
 				})
@@ -190,7 +190,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Check Rock library folders
-				rockFolders, err := ds.Folder(ctx).GetAll(model.QueryOptions{
+				rockFolders, err := ds.Folder().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -201,7 +201,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				}
 
 				// Check Jazz library folders
-				jazzFolders, err := ds.Folder(ctx).GetAll(model.QueryOptions{
+				jazzFolders, err := ds.Folder().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -218,7 +218,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				// Check library-artist associations
 
 				// Get all artists and check library associations
-				allArtists, err := ds.Artist(ctx).GetAll()
+				allArtists, err := ds.Artist().GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 
 				rockArtistNames := []string{}
@@ -262,7 +262,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Check Rock library stats
-				rockLib, err := ds.Library(ctx).Get(lib1.ID)
+				rockLib, err := ds.Library().Get(ctx, lib1.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(rockLib.TotalSongs).To(Equal(4))
 				Expect(rockLib.TotalAlbums).To(Equal(2))
@@ -271,7 +271,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(rockLib.TotalFolders).To(Equal(2)) // Abbey Road, IV (only folders with audio files)
 
 				// Check Jazz library stats
-				jazzLib, err := ds.Library(ctx).Get(lib2.ID)
+				jazzLib, err := ds.Library().Get(ctx, lib2.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzLib.TotalSongs).To(Equal(4))
 				Expect(jazzLib.TotalAlbums).To(Equal(2))
@@ -285,25 +285,25 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Verify rock library stats
-				rockLib, err := ds.Library(ctx).Get(lib1.ID)
+				rockLib, err := ds.Library().Get(ctx, lib1.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(rockLib.TotalSongs).To(Equal(4))
 				Expect(rockLib.TotalAlbums).To(Equal(2))
 
 				// Verify jazz library stats
-				jazzLib, err := ds.Library(ctx).Get(lib2.ID)
+				jazzLib, err := ds.Library().Get(ctx, lib2.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzLib.TotalSongs).To(Equal(4))
 				Expect(jazzLib.TotalAlbums).To(Equal(2))
 
 				// Verify that libraries don't interfere with each other
-				rockFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				rockFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(rockFiles).To(HaveLen(4))
 
-				jazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				jazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -316,7 +316,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Verify that rock library only contains rock content
-				rockAlbums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+				rockAlbums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -325,7 +325,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(rockAlbumNames).ToNot(ContainElements("Kind of Blue", "Giant Steps"))
 
 				// Verify that jazz library only contains jazz content
-				jazzAlbums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+				jazzAlbums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -365,7 +365,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				var rockCount, jazzCount int64
 
 				// Get Jeff Beck artist ID
-				jeffArtists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
+				jeffArtists, err := ds.Artist().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"name": "Jeff Beck"},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -389,14 +389,14 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(jazzCount).To(Equal(int64(1)))
 
 				// Verify Jeff Beck albums are in correct libraries
-				rockAlbums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+				rockAlbums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID, "album_artist": "Jeff Beck"},
 				})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(rockAlbums).To(HaveLen(1))
 				Expect(rockAlbums[0].Name).To(Equal("Truth"))
 
-				jazzAlbums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+				jazzAlbums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID, "album_artist": "Jeff Beck"},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -426,13 +426,13 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			Expect(runScanner(ctx, true)).To(Succeed())
 
 			// Verify initial state
-			rockFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			rockFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"library_id": lib1.ID},
 			})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(rockFiles).To(HaveLen(1))
 
-			jazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			jazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"library_id": lib2.ID},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -442,13 +442,13 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			// Verify counts remain the same
-			rockFiles, err = ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			rockFiles, err = ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"library_id": lib1.ID},
 			})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(rockFiles).To(HaveLen(1))
 
-			jazzFiles, err = ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			jazzFiles, err = ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"library_id": lib2.ID},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -485,7 +485,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			// Check that only the rock library file is marked as missing
-			missingRockFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			missingRockFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.And{
 					squirrel.Eq{"library_id": lib1.ID},
 					squirrel.Eq{"missing": true},
@@ -496,7 +496,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			Expect(missingRockFiles[0].Title).To(Equal("Shoot to Thrill"))
 
 			// Check that jazz library files are not affected
-			missingJazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			missingJazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.And{
 					squirrel.Eq{"library_id": lib2.ID},
 					squirrel.Eq{"missing": true},
@@ -506,7 +506,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			Expect(missingJazzFiles).To(HaveLen(0))
 
 			// Verify non-missing files
-			presentRockFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			presentRockFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.And{
 					squirrel.Eq{"library_id": lib1.ID},
 					squirrel.Eq{"missing": false},
@@ -548,7 +548,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(warnings).ToNot(BeEmpty(), "Should have warnings for filesystem errors")
 
 				// Jazz library should have been scanned successfully
-				jazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				jazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -557,7 +557,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(jazzFiles[1].Title).To(BeElementOf("So What", "Freddie Freeloader"))
 
 				// Rock library may have partial content (depending on scanner implementation)
-				rockFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				rockFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -565,12 +565,12 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				_ = rockFiles
 
 				// Verify jazz library stats are correct
-				jazzLib, err := ds.Library(ctx).Get(lib2.ID)
+				jazzLib, err := ds.Library().Get(ctx, lib2.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzLib.TotalSongs).To(Equal(2))
 
 				// Error should be empty (warnings don't count as scan errors)
-				lastError, err := ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "unset")
+				lastError, err := ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "unset")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lastError).To(BeEmpty())
 			})
@@ -586,20 +586,20 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(warnings).ToNot(BeEmpty(), "Should have warnings for multiple filesystem errors")
 
 				// Jazz library should be completely unaffected
-				jazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				jazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzFiles).To(HaveLen(2))
 
 				// Jazz library statistics should be accurate
-				jazzLib, err := ds.Library(ctx).Get(lib2.ID)
+				jazzLib, err := ds.Library().Get(ctx, lib2.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzLib.TotalSongs).To(Equal(2))
 				Expect(jazzLib.TotalAlbums).To(Equal(1))
 
 				// Error should be empty (warnings don't count as scan errors)
-				lastError, err := ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "unset")
+				lastError, err := ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "unset")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lastError).To(BeEmpty())
 			})
@@ -623,7 +623,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			It("should propagate database errors and stop scanning", func() {
 				// Install mock repo that injects DB error
 				mfRepo := &mockMediaFileRepo{
-					MediaFileRepository:        ds.RealDS.MediaFile(ctx),
+					MediaFileRepository:        ds.RealDS.MediaFile(),
 					GetMissingAndMatchingError: errors.New("database connection failed"),
 				}
 				ds.MockedMediaFile = mfRepo
@@ -632,7 +632,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(runScanner(ctx, false)).To(MatchError(ContainSubstring("database connection failed")))
 
 				// Error should be recorded in scanner properties
-				lastError, err := ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "")
+				lastError, err := ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lastError).To(ContainSubstring("database connection failed"))
 			})
@@ -640,7 +640,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			It("should preserve error information in scanner properties", func() {
 				// Install mock repo that injects DB error
 				mfRepo := &mockMediaFileRepo{
-					MediaFileRepository:        ds.RealDS.MediaFile(ctx),
+					MediaFileRepository:        ds.RealDS.MediaFile(),
 					GetMissingAndMatchingError: errors.New("critical database error"),
 				}
 				ds.MockedMediaFile = mfRepo
@@ -649,12 +649,12 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(runScanner(ctx, false)).To(HaveOccurred())
 
 				// Check that error is recorded in scanner properties
-				lastError, err := ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "")
+				lastError, err := ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lastError).To(ContainSubstring("critical database error"))
 
 				// Scan type should still be recorded
-				scanType, _ := ds.Property(ctx).DefaultGet(consts.LastScanTypeKey, "")
+				scanType, _ := ds.Property().DefaultGet(ctx, consts.LastScanTypeKey, "")
 				Expect(scanType).To(BeElementOf("incremental", "quick"))
 			})
 		})
@@ -687,7 +687,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(warnings).ToNot(BeEmpty(), "Should have warnings for filesystem error")
 
 				// Jazz library should scan completely successfully
-				jazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				jazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -695,13 +695,13 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(jazzFiles[0].Title).To(Equal("Chameleon"))
 
 				// Jazz library statistics should be accurate
-				jazzLib, err := ds.Library(ctx).Get(lib2.ID)
+				jazzLib, err := ds.Library().Get(ctx, lib2.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzLib.TotalSongs).To(Equal(1))
 				Expect(jazzLib.TotalAlbums).To(Equal(1))
 
 				// Rock library may have partial content (depending on scanner implementation)
-				rockFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				rockFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -709,7 +709,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				_ = rockFiles
 
 				// Error should be empty (warnings don't count as scan errors)
-				lastError, err := ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "unset")
+				lastError, err := ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "unset")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lastError).To(BeEmpty())
 			})
@@ -724,22 +724,22 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(warnings).ToNot(BeEmpty(), "Should have warnings for file corruption")
 
 				// Verify that the working parts completed successfully
-				jazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				jazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzFiles).To(HaveLen(1))
 
 				// Scanner properties should reflect successful completion despite warnings
-				scanType, _ := ds.Property(ctx).DefaultGet(consts.LastScanTypeKey, "")
+				scanType, _ := ds.Property().DefaultGet(ctx, consts.LastScanTypeKey, "")
 				Expect(scanType).To(Equal("full"))
 
 				// Start time should be recorded
-				startTimeStr, _ := ds.Property(ctx).DefaultGet(consts.LastScanStartTimeKey, "")
+				startTimeStr, _ := ds.Property().DefaultGet(ctx, consts.LastScanStartTimeKey, "")
 				Expect(startTimeStr).ToNot(BeEmpty())
 
 				// Error should be empty (warnings don't count as scan errors)
-				lastError, err := ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "unset")
+				lastError, err := ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "unset")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lastError).To(BeEmpty())
 			})
@@ -780,30 +780,30 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 				Expect(warnings).To(BeEmpty(), "Should have no warnings after error recovery")
 
 				// Verify both libraries now have content (at least jazz should work)
-				rockFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				rockFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib1.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
 				// The scanner should recover and import both rock files
 				Expect(len(rockFiles)).To(Equal(2))
 
-				jazzFiles, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				jazzFiles, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"library_id": lib2.ID},
 				})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzFiles).To(HaveLen(1))
 
 				// Both libraries should have correct content counts
-				rockLib, err := ds.Library(ctx).Get(lib1.ID)
+				rockLib, err := ds.Library().Get(ctx, lib1.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(rockLib.TotalSongs).To(Equal(2))
 
-				jazzLib, err := ds.Library(ctx).Get(lib2.ID)
+				jazzLib, err := ds.Library().Get(ctx, lib2.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(jazzLib.TotalSongs).To(Equal(1))
 
 				// Error should be empty (successful recovery)
-				lastError, err := ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "unset")
+				lastError, err := ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "unset")
 				Expect(err).ToNot(HaveOccurred())
 				Expect(lastError).To(BeEmpty())
 			})
@@ -822,15 +822,15 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			Expect(runScanner(ctx, true)).To(Succeed())
 
 			// Validate properties
-			scanType, _ := ds.Property(ctx).DefaultGet(consts.LastScanTypeKey, "")
+			scanType, _ := ds.Property().DefaultGet(ctx, consts.LastScanTypeKey, "")
 			Expect(scanType).To(Equal("full"))
 
-			startTimeStr, _ := ds.Property(ctx).DefaultGet(consts.LastScanStartTimeKey, "")
+			startTimeStr, _ := ds.Property().DefaultGet(ctx, consts.LastScanStartTimeKey, "")
 			Expect(startTimeStr).ToNot(BeEmpty())
 			_, err := time.Parse(time.RFC3339, startTimeStr)
 			Expect(err).ToNot(HaveOccurred())
 
-			lastError, err := ds.Property(ctx).DefaultGet(consts.LastScanErrorKey, "unset")
+			lastError, err := ds.Property().DefaultGet(ctx, consts.LastScanErrorKey, "unset")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(lastError).To(BeEmpty())
 		})
diff --git a/scanner/scanner_selective_test.go b/scanner/scanner_selective_test.go
index acaa8f850..2f27b74ce 100644
--- a/scanner/scanner_selective_test.go
+++ b/scanner/scanner_selective_test.go
@@ -63,13 +63,13 @@ var _ = Describe("ScanFolders", Ordered, func() {
 			IsAdmin:     true,
 			NewPassword: "password",
 		}
-		Expect(ds.User(ctx).Put(&adminUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &adminUser)).To(Succeed())
 
 		s = scanner.New(ctx, ds, events.NoopBroker(),
 			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 
 		lib = model.Library{ID: 1, Name: "Fake Library", Path: "fake:///music"}
-		Expect(ds.Library(ctx).Put(&lib)).To(Succeed())
+		Expect(ds.Library().Put(ctx, &lib)).To(Succeed())
 
 		// Initialize fake filesystem
 		fsys = storagetest.FakeFS{}
@@ -101,7 +101,7 @@ var _ = Describe("ScanFolders", Ordered, func() {
 			Expect(warnings).To(BeEmpty())
 
 			// Verify all tracks in rock and jazz folders (including subdirectories) were imported
-			allFiles, err := ds.MediaFile(ctx).GetAll()
+			allFiles, err := ds.MediaFile().GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			// Should have 5 tracks (all rock and jazz tracks including subdirectories)
@@ -123,7 +123,7 @@ var _ = Describe("ScanFolders", Ordered, func() {
 
 			// Verify files in the pop folder were NOT scanned
 			Expect(paths).ToNot(ContainElement("pop/track6.mp3"))
-			Expect(ds.Property(ctx).Get(consts.DBAnalyzePendingKey)).To(Equal("1"))
+			Expect(ds.Property().Get(ctx, consts.DBAnalyzePendingKey)).To(Equal("1"))
 		})
 	})
 
@@ -135,26 +135,26 @@ var _ = Describe("ScanFolders", Ordered, func() {
 			})
 			_, err := s.ScanAll(ctx, true)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(ds.Property(ctx).Get(consts.DBAnalyzePendingKey)).To(Equal("0"))
+			Expect(ds.Property().Get(ctx, consts.DBAnalyzePendingKey)).To(Equal("0"))
 
 			fsys.Add("rock/track2.mp3", rock(track(2, "Rock Track 2")), time.Now().Add(time.Second))
 			_, err = s.ScanAll(ctx, false)
 			Expect(err).ToNot(HaveOccurred())
-			Expect(ds.Property(ctx).Get(consts.DBAnalyzePendingKey)).To(Equal("0"))
+			Expect(ds.Property().Get(ctx, consts.DBAnalyzePendingKey)).To(Equal("0"))
 		})
 
 		It("does not treat an interrupted scan in an untargeted library as a full scan", func() {
 			otherLib := model.Library{ID: 2, Name: "Other Library", Path: "fake:///other"}
-			Expect(ds.Library(ctx).Put(&otherLib)).To(Succeed())
-			Expect(ds.Library(ctx).ScanBegin(lib.ID, true)).To(Succeed())
+			Expect(ds.Library().Put(ctx, &otherLib)).To(Succeed())
+			Expect(ds.Library().ScanBegin(ctx, lib.ID, true)).To(Succeed())
 
 			lastAnalyze := "2026-07-09T12:00:00Z"
-			Expect(ds.Property(ctx).Put(consts.LastDBAnalyzeAtKey, lastAnalyze)).To(Succeed())
-			Expect(ds.Property(ctx).Put(consts.DBAnalyzePendingKey, "0")).To(Succeed())
+			Expect(ds.Property().Put(ctx, consts.LastDBAnalyzeAtKey, lastAnalyze)).To(Succeed())
+			Expect(ds.Property().Put(ctx, consts.DBAnalyzePendingKey, "0")).To(Succeed())
 
 			_, err := s.ScanFolders(ctx, false, []model.ScanTarget{{LibraryID: otherLib.ID, FolderPath: "."}})
 			Expect(err).ToNot(HaveOccurred())
-			Expect(ds.Property(ctx).Get(consts.LastDBAnalyzeAtKey)).To(Equal(lastAnalyze))
+			Expect(ds.Property().Get(ctx, consts.LastDBAnalyzeAtKey)).To(Equal(lastAnalyze))
 		})
 	})
 
@@ -187,7 +187,7 @@ var _ = Describe("ScanFolders", Ordered, func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				// Verify initial state - all folders exist
-				folders, err := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"library_id": lib.ID}})
+				folders, err := ds.Folder().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"library_id": lib.ID}})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(folders).To(HaveLen(4)) // root, Artist, Album1, Album2
 
@@ -204,7 +204,7 @@ var _ = Describe("ScanFolders", Ordered, func() {
 				}
 
 				// Verify all tracks exist
-				allTracks, err := ds.MediaFile(ctx).GetAll()
+				allTracks, err := ds.MediaFile().GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(allTracks).To(HaveLen(4))
 
@@ -239,29 +239,29 @@ var _ = Describe("ScanFolders", Ordered, func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				// Verify the deleted child folder is now marked as missing
-				deletedFolder, err := ds.Folder(ctx).Get(album2FolderID)
+				deletedFolder, err := ds.Folder().Get(ctx, album2FolderID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(deletedFolder.Missing).To(BeTrue(), "Deleted child folder should be marked as missing")
 
 				// Verify the deleted folder's tracks are marked as missing
 				for _, trackID := range album2TrackIDs {
-					track, err := ds.MediaFile(ctx).Get(trackID)
+					track, err := ds.MediaFile().Get(ctx, trackID)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(track.Missing).To(BeTrue(), "Track in deleted folder should be marked as missing")
 				}
 
 				// Verify the parent folder is still present and not marked as missing
-				parentFolder, err := ds.Folder(ctx).Get(artistFolderID)
+				parentFolder, err := ds.Folder().Get(ctx, artistFolderID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(parentFolder.Missing).To(BeFalse(), "Parent folder should not be marked as missing")
 
 				// Verify the sibling folder and its tracks are still present and not missing
-				siblingFolder, err := ds.Folder(ctx).Get(album1FolderID)
+				siblingFolder, err := ds.Folder().Get(ctx, album1FolderID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(siblingFolder.Missing).To(BeFalse(), "Sibling folder should not be marked as missing")
 
 				for _, trackID := range album1TrackIDs {
-					track, err := ds.MediaFile(ctx).Get(trackID)
+					track, err := ds.MediaFile().Get(ctx, trackID)
 					Expect(err).ToNot(HaveOccurred())
 					Expect(track.Missing).To(BeFalse(), "Track in sibling folder should not be marked as missing")
 				}
@@ -283,7 +283,7 @@ var _ = Describe("ScanFolders", Ordered, func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				// Verify nested folders were created
-				allFolders, err := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"library_id": lib.ID}})
+				allFolders, err := ds.Folder().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"library_id": lib.ID}})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(len(allFolders)).To(BeNumerically(">", 4), "Should have more folders with nested structure")
 
@@ -301,7 +301,7 @@ var _ = Describe("ScanFolders", Ordered, func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				// Verify all Help! folders (including nested ones) are marked as missing
-				missingFolders, err := ds.Folder(ctx).GetAll(model.QueryOptions{
+				missingFolders, err := ds.Folder().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.And{
 						squirrel.Eq{"library_id": lib.ID},
 						squirrel.Eq{"missing": true},
@@ -311,7 +311,7 @@ var _ = Describe("ScanFolders", Ordered, func() {
 				Expect(len(missingFolders)).To(BeNumerically(">", 0), "At least one folder should be marked as missing")
 
 				// Verify all tracks in deleted folders are marked as missing
-				allTracks, err := ds.MediaFile(ctx).GetAll()
+				allTracks, err := ds.MediaFile().GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(allTracks).To(HaveLen(6))
 
diff --git a/scanner/scanner_test.go b/scanner/scanner_test.go
index 30f4a2b97..4ce8cce1e 100644
--- a/scanner/scanner_test.go
+++ b/scanner/scanner_test.go
@@ -78,7 +78,7 @@ var _ = Describe("Scanner", Ordered, func() {
 
 		ds = &tests.MockDataStore{RealDS: persistence.New(db.Db())}
 		mfRepo = &mockMediaFileRepo{
-			MediaFileRepository: ds.RealDS.MediaFile(ctx),
+			MediaFileRepository: ds.RealDS.MediaFile(),
 		}
 		ds.MockedMediaFile = mfRepo
 
@@ -90,13 +90,13 @@ var _ = Describe("Scanner", Ordered, func() {
 			IsAdmin:     true,
 			NewPassword: "password",
 		}
-		Expect(ds.User(ctx).Put(&adminUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &adminUser)).To(Succeed())
 
 		s = scanner.New(ctx, ds, events.NoopBroker(),
 			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
 
 		lib = model.Library{ID: 1, Name: "Fake Library", Path: "fake:///music"}
-		Expect(ds.Library(ctx).Put(&lib)).To(Succeed())
+		Expect(ds.Library().Put(ctx, &lib)).To(Succeed())
 	})
 
 	runScanner := func(ctx context.Context, fullScan bool) error {
@@ -108,14 +108,14 @@ var _ = Describe("Scanner", Ordered, func() {
 	// so a later scan can only queue genuine reprocessing.
 	resolveQueuedArtwork := func() []model.ArtworkQueueItem {
 		GinkgoHelper()
-		queued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+		queued, err := ds.ArtworkQueue().DequeueBatch(ctx, 1000)
 		Expect(err).ToNot(HaveOccurred())
 		for _, it := range queued {
-			Expect(ds.Artwork(ctx).PutItemArtwork(&model.ItemArtwork{
+			Expect(ds.Artwork().PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: it.ItemKind, ItemID: it.ItemID, ImageType: it.ImageType,
 				Hash: "resolved", Source: "embedded", UpdatedAt: time.Now(),
 			})).To(Succeed())
-			Expect(ds.ArtworkQueue(ctx).DeleteIfUnchanged(it.ItemKind, it.ItemID, it.ImageType, it.RetryAt)).To(Succeed())
+			Expect(ds.ArtworkQueue().DeleteIfUnchanged(ctx, it.ItemKind, it.ItemID, it.ImageType, it.RetryAt)).To(Succeed())
 		}
 		return queued
 	}
@@ -140,7 +140,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			It("should import all folders", func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				folders, _ := ds.Folder(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"library_id": lib.ID}})
+				folders, _ := ds.Folder().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"library_id": lib.ID}})
 				paths := slice.Map(folders, func(f model.Folder) string { return f.Name })
 				Expect(paths).To(SatisfyAll(
 					HaveLen(4),
@@ -150,7 +150,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			It("should import all mediafiles", func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				mfs, _ := ds.MediaFile(ctx).GetAll()
+				mfs, _ := ds.MediaFile().GetAll(ctx)
 				paths := slice.Map(mfs, func(f model.MediaFile) string { return f.Title })
 				Expect(paths).To(SatisfyAll(
 					HaveLen(7),
@@ -163,7 +163,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			It("should import all albums", func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				albums, _ := ds.Album(ctx).GetAll(model.QueryOptions{Sort: "name"})
+				albums, _ := ds.Album().GetAll(ctx, model.QueryOptions{Sort: "name"})
 				Expect(albums).To(HaveLen(2))
 				Expect(albums[0]).To(SatisfyAll(
 					HaveField("Name", Equal("Help!")),
@@ -177,9 +177,9 @@ var _ = Describe("Scanner", Ordered, func() {
 			It("should enqueue artwork resolution for the scanned albums and artists", func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				albums, _ := ds.Album(ctx).GetAll()
-				artists, _ := ds.Artist(ctx).GetAll(model.QueryOptions{Filters: squirrel.NotEq{"name": consts.UnknownArtist}})
-				queued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+				albums, _ := ds.Album().GetAll(ctx)
+				artists, _ := ds.Artist().GetAll(ctx, model.QueryOptions{Filters: squirrel.NotEq{"name": consts.UnknownArtist}})
+				queued, err := ds.ArtworkQueue().DequeueBatch(ctx, 1000)
 				Expect(err).ToNot(HaveOccurred())
 
 				for _, al := range albums {
@@ -204,7 +204,7 @@ var _ = Describe("Scanner", Ordered, func() {
 
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				requeued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+				requeued, err := ds.ArtworkQueue().DequeueBatch(ctx, 1000)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(requeued).To(BeEmpty())
 			})
@@ -213,14 +213,14 @@ var _ = Describe("Scanner", Ordered, func() {
 			It("should update the media_file", func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				mf, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"title": "Help!"}})
+				mf, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"title": "Help!"}})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mf[0].Tags).ToNot(HaveKey("barcode"))
 
 				fsys.UpdateTags("The Beatles/Help!/01 - Help!.mp3", _t{"barcode": "123"})
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				mf, err = ds.MediaFile(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"title": "Help!"}})
+				mf, err = ds.MediaFile().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"title": "Help!"}})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mf[0].Tags).To(HaveKeyWithValue(model.TagName("barcode"), []string{"123"}))
 			})
@@ -234,9 +234,9 @@ var _ = Describe("Scanner", Ordered, func() {
 				fsys.UpdateTags("The Beatles/Help!/01 - Help!.mp3", _t{"producer": "George Martin"})
 				Expect(runScanner(ctx, false)).To(Succeed())
 
-				albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": "Help!"}})
+				albums, err := ds.Album().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"album.name": "Help!"}})
 				Expect(err).ToNot(HaveOccurred())
-				requeued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+				requeued, err := ds.ArtworkQueue().DequeueBatch(ctx, 1000)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(requeued).To(ContainElement(SatisfyAll(
 					HaveField("ItemKind", "al"),
@@ -248,7 +248,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": "Help!"}})
+				albums, err := ds.Album().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"album.name": "Help!"}})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(albums).ToNot(BeEmpty())
 				Expect(albums[0].Participants.First(model.RoleProducer).Name).To(BeEmpty())
@@ -257,7 +257,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				fsys.UpdateTags("The Beatles/Help!/01 - Help!.mp3", _t{"producer": "George Martin"})
 				Expect(runScanner(ctx, false)).To(Succeed())
 
-				albums, err = ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": "Help!"}})
+				albums, err = ds.Album().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"album.name": "Help!"}})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(albums[0].Participants.First(model.RoleProducer).Name).To(Equal("George Martin"))
 				Expect(albums[0].SongCount).To(Equal(3))
@@ -266,12 +266,12 @@ var _ = Describe("Scanner", Ordered, func() {
 			It("invalidates the media_file artwork state so new embedded art is picked up lazily", func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				mf, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"title": "Help!"}})
+				mf, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"title": "Help!"}})
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mf).ToNot(BeEmpty())
 				trackID := mf[0].ID
 
-				Expect(ds.Artwork(ctx).PutItemArtwork(&model.ItemArtwork{
+				Expect(ds.Artwork().PutItemArtwork(ctx, &model.ItemArtwork{
 					ItemKind: "mf", ItemID: trackID, ImageType: model.ImageTypePrimary,
 					Source: "embedded", Hash: "stalehash",
 				})).To(Succeed())
@@ -279,7 +279,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				fsys.UpdateTags("The Beatles/Help!/01 - Help!.mp3", _t{"comment": "reimport"})
 				Expect(runScanner(ctx, true)).To(Succeed())
 
-				_, err = ds.Artwork(ctx).GetItemArtwork(model.KindMediaFileArtwork, trackID, model.ImageTypePrimary)
+				_, err = ds.Artwork().GetItemArtwork(ctx, model.KindMediaFileArtwork, trackID, model.ImageTypePrimary)
 				Expect(err).To(MatchError(model.ErrNotFound))
 			})
 		})
@@ -291,21 +291,21 @@ var _ = Describe("Scanner", Ordered, func() {
 
 		albumID := func(name string) string {
 			GinkgoHelper()
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": name}})
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"album.name": name}})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(albums).To(HaveLen(1))
 			return albums[0].ID
 		}
 		artistID := func(name string) string {
 			GinkgoHelper()
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"artist.name": name}})
+			artists, err := ds.Artist().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"artist.name": name}})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(artists).To(HaveLen(1))
 			return artists[0].ID
 		}
 		queuedItems := func() []model.ArtworkQueueItem {
 			GinkgoHelper()
-			queued, err := ds.ArtworkQueue(ctx).DequeueBatch(1000)
+			queued, err := ds.ArtworkQueue().DequeueBatch(ctx, 1000)
 			Expect(err).ToNot(HaveOccurred())
 			return queued
 		}
@@ -464,7 +464,7 @@ var _ = Describe("Scanner", Ordered, func() {
 		It("should not import the ignored file", func() {
 			Expect(runScanner(ctx, true)).To(Succeed())
 
-			mfs, err := ds.MediaFile(ctx).GetAll()
+			mfs, err := ds.MediaFile().GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(mfs).To(HaveLen(1))
 			for _, mf := range mfs {
@@ -486,11 +486,11 @@ var _ = Describe("Scanner", Ordered, func() {
 		It("should import as one album", func() {
 			Expect(runScanner(ctx, true)).To(Succeed())
 
-			albums, err := ds.Album(ctx).GetAll()
+			albums, err := ds.Album().GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(albums).To(HaveLen(1))
 
-			mfs, err := ds.MediaFile(ctx).GetAll()
+			mfs, err := ds.MediaFile().GetAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(mfs).To(HaveLen(2))
 			for _, mf := range mfs {
@@ -512,7 +512,7 @@ var _ = Describe("Scanner", Ordered, func() {
 		It("should import as two distinct albums", func() {
 			Expect(runScanner(ctx, true)).To(Succeed())
 
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Sort: "release_date"})
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{Sort: "release_date"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(albums).To(HaveLen(2))
 			Expect(albums[0]).To(SatisfyAll(
@@ -551,7 +551,7 @@ var _ = Describe("Scanner", Ordered, func() {
 
 			By("Doing a full scan")
 			Expect(runScanner(ctx, true)).To(Succeed())
-			Expect(ds.MediaFile(ctx).CountAll()).To(Equal(int64(4)))
+			Expect(ds.MediaFile().CountAll(ctx)).To(Equal(int64(4)))
 			findByPath = createFindByPath(ctx, ds)
 		})
 
@@ -559,7 +559,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			fsys.Add("The Beatles/Revolver/03 - I'm Only Sleeping.mp3", revolver(track(3, "I'm Only Sleeping")))
 
 			Expect(runScanner(ctx, false)).To(Succeed())
-			Expect(ds.MediaFile(ctx).CountAll()).To(Equal(int64(5)))
+			Expect(ds.MediaFile().CountAll(ctx)).To(Equal(int64(5)))
 			mf, err := findByPath("The Beatles/Revolver/03 - I'm Only Sleeping.mp3")
 			Expect(err).ToNot(HaveOccurred())
 			Expect(mf.Title).To(Equal("I'm Only Sleeping"))
@@ -569,7 +569,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			fsys.UpdateTags("The Beatles/Revolver/02 - Eleanor Rigby.mp3", _t{"title": "Eleanor Rigby (remix)"})
 
 			Expect(runScanner(ctx, false)).To(Succeed())
-			Expect(ds.MediaFile(ctx).CountAll()).To(Equal(int64(4)))
+			Expect(ds.MediaFile().CountAll(ctx)).To(Equal(int64(4)))
 			mf, _ := findByPath("The Beatles/Revolver/02 - Eleanor Rigby.mp3")
 			Expect(mf.Title).To(Equal("Eleanor Rigby (remix)"))
 		})
@@ -578,7 +578,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			fsys.Add("The Beatles/Revolver/01 - Taxman.mp3", revolver(track(1, "Taxman", _t{"bitrate": 640})))
 
 			Expect(runScanner(ctx, false)).To(Succeed())
-			Expect(ds.MediaFile(ctx).CountAll()).To(Equal(int64(4)))
+			Expect(ds.MediaFile().CountAll(ctx)).To(Equal(int64(4)))
 			mf, _ := findByPath("The Beatles/Revolver/01 - Taxman.mp3")
 			Expect(mf.BitRate).To(Equal(640))
 		})
@@ -591,7 +591,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			By("Checking the file is marked as missing")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": false},
 			})).To(Equal(int64(3)))
 			mf, err := findByPath("The Beatles/Revolver/02 - Eleanor Rigby.mp3")
@@ -612,14 +612,14 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			By("Checking the old file is not in the library")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": false},
 			})).To(Equal(int64(4)))
 			_, err = findByPath("The Beatles/Revolver/02 - Eleanor Rigby.mp3")
 			Expect(err).To(MatchError(model.ErrNotFound))
 
 			By("Checking the new file is in the library")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": true},
 			})).To(BeZero())
 			mf, err := findByPath("The Beatles/Help!/02 - Eleanor Rigby.mp3")
@@ -641,7 +641,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(MatchError(ContainSubstring("I/O read error")))
 
 			By("Checking the both instances of the file are in the lib")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"title": "Taxman"},
 			})).To(Equal(int64(2)))
 
@@ -650,7 +650,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			By("Checking the old file is not in the library")
-			mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"title": "Taxman"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -671,14 +671,14 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			By("Checking the old file is not in the library")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": true},
 			})).To(BeZero())
 			_, err = findByPath("The Beatles/Revolver/02 - Eleanor Rigby.mp3")
 			Expect(err).To(MatchError(model.ErrNotFound))
 
 			By("Checking the new file is in the library")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": false},
 			})).To(Equal(int64(4)))
 			mf, err := findByPath("The Beatles/Revolver/02 - Eleanor Rigby.flac")
@@ -698,7 +698,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			By("Checking the file is marked as missing")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": false},
 			})).To(Equal(int64(3)))
 			mf, err := findByPath("The Beatles/Revolver/02 - Eleanor Rigby.mp3")
@@ -712,7 +712,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			By("Checking the file is not marked as missing")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": false},
 			})).To(Equal(int64(4)))
 			mf, err = findByPath("The Beatles/Revolver/02 - Eleanor Rigby.mp3")
@@ -737,7 +737,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			By("Checking the file was found in the new folder")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": false},
 			})).To(Equal(int64(4)))
 			mf, err = findByPath("The Beatles/Help!/02 - Eleanor Rigby.mp3")
@@ -751,7 +751,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, false)).To(Succeed())
 
 			By("Verifying initial state has 5 tracks")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": false},
 			})).To(Equal(int64(5)))
 
@@ -790,7 +790,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(mf.Missing).To(BeFalse())
 
 			By("Verifying only 2 non-missing tracks remain (Help! tracks)")
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"missing": false},
 			})).To(Equal(int64(2)))
 		})
@@ -815,7 +815,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, true)).To(Succeed())
 
 			nonMissingArtists := func() []string {
-				aa, err := ds.Artist(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"missing": false}})
+				aa, err := ds.Artist().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"missing": false}})
 				Expect(err).ToNot(HaveOccurred())
 				return slice.Map(aa, func(a model.Artist) string { return a.Name })
 			}
@@ -860,7 +860,7 @@ var _ = Describe("Scanner", Ordered, func() {
 
 		It("does not override artist fields when importing an undertagged file", func() {
 			By("Making sure artist in the DB contains MBID and sort name")
-			aa, err := ds.Artist(ctx).GetAll(model.QueryOptions{
+			aa, err := ds.Artist().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"name": "The Beatles"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -887,7 +887,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(mf.SortArtistName).To(BeEmpty())
 
 			By("Makingsure the artist in the DB has not changed")
-			aa, err = ds.Artist(ctx).GetAll(model.QueryOptions{
+			aa, err = ds.Artist().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"name": "The Beatles"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -915,7 +915,7 @@ var _ = Describe("Scanner", Ordered, func() {
 					Expect(runScanner(ctx, true)).To(Succeed())
 
 					By("Checking files are marked as missing but not deleted")
-					count, err := ds.MediaFile(ctx).CountAll(model.QueryOptions{
+					count, err := ds.MediaFile().CountAll(ctx, model.QueryOptions{
 						Filters: squirrel.Eq{"missing": true},
 					})
 					Expect(err).ToNot(HaveOccurred())
@@ -943,7 +943,7 @@ var _ = Describe("Scanner", Ordered, func() {
 					Expect(runScanner(ctx, false)).To(Succeed())
 
 					By("Checking missing files are deleted")
-					count, err := ds.MediaFile(ctx).CountAll(model.QueryOptions{
+					count, err := ds.MediaFile().CountAll(ctx, model.QueryOptions{
 						Filters: squirrel.Eq{"missing": true},
 					})
 					Expect(err).ToNot(HaveOccurred())
@@ -970,7 +970,7 @@ var _ = Describe("Scanner", Ordered, func() {
 					Expect(runScanner(ctx, false)).To(Succeed())
 
 					By("Checking files are marked as missing but not deleted")
-					count, err := ds.MediaFile(ctx).CountAll(model.QueryOptions{
+					count, err := ds.MediaFile().CountAll(ctx, model.QueryOptions{
 						Filters: squirrel.Eq{"missing": true},
 					})
 					Expect(err).ToNot(HaveOccurred())
@@ -992,7 +992,7 @@ var _ = Describe("Scanner", Ordered, func() {
 					Expect(runScanner(ctx, true)).To(Succeed())
 
 					By("Checking missing files are deleted")
-					count, err := ds.MediaFile(ctx).CountAll(model.QueryOptions{
+					count, err := ds.MediaFile().CountAll(ctx, model.QueryOptions{
 						Filters: squirrel.Eq{"missing": true},
 					})
 					Expect(err).ToNot(HaveOccurred())
@@ -1020,10 +1020,10 @@ var _ = Describe("Scanner", Ordered, func() {
 		simulateInterruptedScan := func(fullScan bool) {
 			// Call ScanBegin to properly set LastScanStartedAt and FullScanInProgress
 			// This simulates what would happen if a scan was interrupted (ScanBegin called but ScanEnd not)
-			Expect(ds.Library(ctx).ScanBegin(lib.ID, fullScan)).To(Succeed())
+			Expect(ds.Library().ScanBegin(ctx, lib.ID, fullScan)).To(Succeed())
 
 			// Verify the update was persisted
-			reloaded, err := ds.Library(ctx).Get(lib.ID)
+			reloaded, err := ds.Library().Get(ctx, lib.ID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(reloaded.LastScanStartedAt).ToNot(BeZero())
 			Expect(reloaded.FullScanInProgress).To(Equal(fullScan))
@@ -1035,7 +1035,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Verify files were imported
-				mfs, err := ds.MediaFile(ctx).GetAll()
+				mfs, err := ds.MediaFile().GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mfs).To(HaveLen(2))
 
@@ -1056,7 +1056,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Verify the comment was updated (which means the folder was processed and file re-imported)
-				mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"title": "Help!"},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -1071,7 +1071,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Verify files were imported
-				mfs, err := ds.MediaFile(ctx).GetAll()
+				mfs, err := ds.MediaFile().GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mfs).To(HaveLen(2))
 
@@ -1090,7 +1090,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(runScanner(ctx, false)).To(Succeed())
 
 				// Verify the comment was updated (folder was processed despite unchanged hash)
-				mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"title": "Help!"},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -1105,12 +1105,12 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Verify files were imported
-				mfs, err := ds.MediaFile(ctx).GetAll()
+				mfs, err := ds.MediaFile().GetAll(ctx)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(mfs).To(HaveLen(2))
 
 				// Library should have LastScanStartedAt cleared after successful scan
-				updatedLib, err := ds.Library(ctx).Get(lib.ID)
+				updatedLib, err := ds.Library().Get(ctx, lib.ID)
 				Expect(err).ToNot(HaveOccurred())
 				Expect(updatedLib.LastScanStartedAt).To(BeZero())
 				Expect(updatedLib.FullScanInProgress).To(BeFalse())
@@ -1125,7 +1125,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				// Verify the comment was updated
-				mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"title": "Help!"},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -1144,7 +1144,7 @@ var _ = Describe("Scanner", Ordered, func() {
 				Expect(runScanner(ctx, false)).To(Succeed())
 
 				// Verify the comment was NOT updated (folder was skipped)
-				mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+				mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 					Filters: squirrel.Eq{"title": "Help!"},
 				})
 				Expect(err).ToNot(HaveOccurred())
@@ -1163,7 +1163,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			refreshStatsCalls = nil
 
 			// Create a mock artist repository that tracks RefreshStats calls
-			originalArtistRepo := ds.RealDS.Artist(ctx)
+			originalArtistRepo := ds.RealDS.Artist()
 			ds.MockedArtist = &testArtistRepo{
 				ArtistRepository: originalArtistRepo,
 				callTracker:      &refreshStatsCalls,
@@ -1209,7 +1209,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			Expect(runScanner(ctx, true)).To(Succeed())
 
 			// Verify initial artist stats - should have 1 album, 1 song
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
+			artists, err := ds.Artist().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"name": "The Beatles"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -1228,7 +1228,7 @@ var _ = Describe("Scanner", Ordered, func() {
 
 			By("Verifying artist stats were updated correctly")
 			// Fetch the artist again to check updated stats
-			artists, err = ds.Artist(ctx).GetAll(model.QueryOptions{
+			artists, err = ds.Artist().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"name": "The Beatles"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -1277,8 +1277,8 @@ var _ = Describe("Scanner", Ordered, func() {
 
 			Expect(runScanner(ctx, true)).ToNot(Succeed())
 
-			Expect(ds.Folder(ctx).CountAll(model.QueryOptions{Filters: squirrel.Eq{"missing": true}})).To(BeZero())
-			Expect(ds.MediaFile(ctx).CountAll(model.QueryOptions{Filters: squirrel.Eq{"missing": true}})).To(BeZero())
+			Expect(ds.Folder().CountAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"missing": true}})).To(BeZero())
+			Expect(ds.MediaFile().CountAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"missing": true}})).To(BeZero())
 		})
 	})
 })
@@ -1298,7 +1298,7 @@ func (b *busyPersistDS) WithTxRetry(ctx context.Context, block func(context.Cont
 
 func createFindByPath(ctx context.Context, ds model.DataStore) func(string) (*model.MediaFile, error) {
 	return func(path string) (*model.MediaFile, error) {
-		list, err := ds.MediaFile(ctx).FindByPaths([]string{path})
+		list, err := ds.MediaFile().FindByPaths(ctx, []string{path})
 		if err != nil {
 			return nil, err
 		}
@@ -1315,16 +1315,16 @@ type mockMediaFileRepo struct {
 	cursorCalls                atomic.Int32
 }
 
-func (m *mockMediaFileRepo) GetCursor(options ...model.QueryOptions) (model.MediaFileCursor, error) {
+func (m *mockMediaFileRepo) GetCursor(ctx context.Context, options ...model.QueryOptions) (model.MediaFileCursor, error) {
 	m.cursorCalls.Add(1)
-	return m.MediaFileRepository.GetCursor(options...)
+	return m.MediaFileRepository.GetCursor(ctx, options...)
 }
 
-func (m *mockMediaFileRepo) GetMissingAndMatching(libId int) (model.MediaFileCursor, error) {
+func (m *mockMediaFileRepo) GetMissingAndMatching(ctx context.Context, libId int) (model.MediaFileCursor, error) {
 	if m.GetMissingAndMatchingError != nil {
 		return nil, m.GetMissingAndMatchingError
 	}
-	return m.MediaFileRepository.GetMissingAndMatching(libId)
+	return m.MediaFileRepository.GetMissingAndMatching(ctx, libId)
 }
 
 type testArtistRepo struct {
@@ -1332,7 +1332,7 @@ type testArtistRepo struct {
 	callTracker *[]bool
 }
 
-func (m *testArtistRepo) RefreshStats(allArtists bool) (int64, error) {
+func (m *testArtistRepo) RefreshStats(ctx context.Context, allArtists bool) (int64, error) {
 	*m.callTracker = append(*m.callTracker, allArtists)
-	return m.ArtistRepository.RefreshStats(allArtists)
+	return m.ArtistRepository.RefreshStats(ctx, allArtists)
 }
diff --git a/scanner/watcher.go b/scanner/watcher.go
index baf94b79b..1ac5468f0 100644
--- a/scanner/watcher.go
+++ b/scanner/watcher.go
@@ -23,7 +23,7 @@ type Watcher interface {
 }
 
 type watcher struct {
-	mainCtx         context.Context
+	mainCtx         context.Context //nolint:containedctx // watcher lifecycle ctx
 	ds              model.DataStore
 	scanner         model.Scanner
 	triggerWait     time.Duration
@@ -60,7 +60,7 @@ func (w *watcher) Run(ctx context.Context) error {
 	w.mainCtx = ctx
 
 	// Start watchers for all existing libraries
-	libs, err := w.ds.Library(ctx).GetAll()
+	libs, err := w.ds.Library().GetAll(ctx)
 	if err != nil {
 		return fmt.Errorf("getting libraries: %w", err)
 	}
diff --git a/server/auth.go b/server/auth.go
index 2aaa93e63..3e58359da 100644
--- a/server/auth.go
+++ b/server/auth.go
@@ -49,7 +49,7 @@ func login(ds model.DataStore) func(w http.ResponseWriter, r *http.Request) {
 }
 
 func doLogin(ds model.DataStore, username string, password string, w http.ResponseWriter, r *http.Request) {
-	user, err := validateLogin(ds.User(r.Context()), username, password)
+	user, err := validateLogin(r.Context(), ds.User(), username, password)
 	if err != nil {
 		_ = rest.RespondWithError(w, http.StatusInternalServerError, "Unknown error authentication user. Please try again")
 		return
@@ -127,7 +127,7 @@ func createAdmin(ds model.DataStore) func(w http.ResponseWriter, r *http.Request
 			_ = rest.RespondWithError(w, http.StatusUnprocessableEntity, err.Error())
 			return
 		}
-		c, err := ds.User(r.Context()).CountAll()
+		c, err := ds.User().CountAll(r.Context())
 		if err != nil {
 			_ = rest.RespondWithError(w, http.StatusInternalServerError, err.Error())
 			return
@@ -157,7 +157,7 @@ func createAdminUser(ctx context.Context, ds model.DataStore, username, password
 		IsAdmin:     true,
 		LastLoginAt: new(time.Now()),
 	}
-	err := ds.User(ctx).Put(&initialUser)
+	err := ds.User().Put(ctx, &initialUser)
 	if err != nil {
 		log.Error(ctx, "Could not create initial user", "user", initialUser.UserName, err)
 		return fmt.Errorf("creating initial user: %w", err)
@@ -165,8 +165,8 @@ func createAdminUser(ctx context.Context, ds model.DataStore, username, password
 	return nil
 }
 
-func validateLogin(userRepo model.UserRepository, userName, password string) (*model.User, error) {
-	u, err := userRepo.FindByUsernameWithPassword(userName)
+func validateLogin(ctx context.Context, userRepo model.UserRepository, userName, password string) (*model.User, error) {
+	u, err := userRepo.FindByUsernameWithPassword(ctx, userName)
 	if errors.Is(err, model.ErrNotFound) {
 		return nil, nil
 	}
@@ -176,9 +176,9 @@ func validateLogin(userRepo model.UserRepository, userName, password string) (*m
 	if u.Password != password {
 		return nil, nil
 	}
-	err = userRepo.UpdateLastLoginAt(u.ID)
+	err = userRepo.UpdateLastLoginAt(ctx, u.ID)
 	if err != nil {
-		log.Error("Could not update LastLoginAt", "user", userName)
+		log.Error(ctx, "Could not update LastLoginAt", "user", userName)
 	}
 	return u, nil
 }
@@ -244,7 +244,7 @@ func UsernameFromConfig(*http.Request) string {
 }
 
 func contextWithUser(ctx context.Context, ds model.DataStore, username string) (context.Context, error) {
-	user, err := ds.User(ctx).FindByUsername(username)
+	user, err := ds.User().FindByUsername(ctx, username)
 	if err == nil {
 		ctx = log.NewContext(ctx, "username", username)
 		ctx = request.WithUsername(ctx, user.UserName)
@@ -309,7 +309,7 @@ func tokenAllowed(ctx context.Context) bool {
 // epoch the handler bumped reaches the token the client stores.
 type refreshingWriter struct {
 	http.ResponseWriter
-	ctx   context.Context
+	ctx   context.Context //nolint:containedctx // ResponseWriter wrapper defers work to Write, which has no ctx
 	token jwt.Token
 	once  sync.Once
 }
@@ -377,12 +377,13 @@ func handleLoginFromHeaders(ds model.DataStore, r *http.Request) map[string]any
 		}
 	}
 
-	userRepo := ds.User(r.Context())
-	user, err := userRepo.FindByUsernameWithPassword(username)
+	ctx := r.Context()
+	userRepo := ds.User()
+	user, err := userRepo.FindByUsernameWithPassword(ctx, username)
 	if user == nil || err != nil {
 		log.Info(r, "User passed in header not found", "user", username)
 		// Check if this is the first user being created
-		count, _ := userRepo.CountAll()
+		count, _ := userRepo.CountAll(ctx)
 		isFirstUser := count == 0
 
 		newUser := model.User{
@@ -393,19 +394,19 @@ func handleLoginFromHeaders(ds model.DataStore, r *http.Request) map[string]any
 			NewPassword: consts.PasswordAutogenPrefix + id.NewRandom(),
 			IsAdmin:     isFirstUser, // Make the first user an admin
 		}
-		err := userRepo.Put(&newUser)
+		err := userRepo.Put(ctx, &newUser)
 		if err != nil {
 			log.Error(r, "Could not create new user", "user", username, err)
 			return nil
 		}
-		user, err = userRepo.FindByUsernameWithPassword(username)
+		user, err = userRepo.FindByUsernameWithPassword(ctx, username)
 		if user == nil || err != nil {
 			log.Error(r, "Created user but failed to fetch it", "user", username)
 			return nil
 		}
 	}
 
-	err = userRepo.UpdateLastLoginAt(user.ID)
+	err = userRepo.UpdateLastLoginAt(ctx, user.ID)
 	if err != nil {
 		log.Error(r, "Could not update LastLoginAt", "user", username, err)
 		return nil
diff --git a/server/auth_test.go b/server/auth_test.go
index abe144a12..1095fafc9 100644
--- a/server/auth_test.go
+++ b/server/auth_test.go
@@ -28,6 +28,12 @@ import (
 )
 
 var _ = Describe("Auth", func() {
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+	})
+
 	Describe("User login", func() {
 		var ds model.DataStore
 		var req *http.Request
@@ -48,8 +54,8 @@ var _ = Describe("Auth", func() {
 			})
 
 			It("creates an admin user with the specified password", func() {
-				usr := ds.User(context.Background())
-				u, err := usr.FindByUsername("johndoe")
+				usr := ds.User()
+				u, err := usr.FindByUsername(ctx, "johndoe")
 				Expect(err).To(BeNil())
 				Expect(u.Password).ToNot(BeEmpty())
 				Expect(u.IsAdmin).To(BeTrue())
@@ -99,8 +105,8 @@ var _ = Describe("Auth", func() {
 			fs := os.DirFS("tests/fixtures")
 
 			BeforeEach(func() {
-				usr := ds.User(context.Background())
-				_ = usr.Put(&model.User{ID: "111", UserName: "janedoe", NewPassword: "abc123", Name: "Jane", IsAdmin: false})
+				usr := ds.User()
+				_ = usr.Put(ctx, &model.User{ID: "111", UserName: "janedoe", NewPassword: "abc123", Name: "Jane", IsAdmin: false})
 				req = httptest.NewRequest("GET", "/index.html", nil)
 				req.Header.Add("Remote-User", "janedoe")
 				resp = httptest.NewRecorder()
@@ -232,8 +238,8 @@ var _ = Describe("Auth", func() {
 			})
 
 			It("logs in successfully if user exists", func() {
-				usr := ds.User(context.Background())
-				_ = usr.Put(&model.User{ID: "111", UserName: "janedoe", NewPassword: "abc123", Name: "Jane", IsAdmin: false})
+				usr := ds.User()
+				_ = usr.Put(ctx, &model.User{ID: "111", UserName: "janedoe", NewPassword: "abc123", Name: "Jane", IsAdmin: false})
 
 				login(ds)(resp, req)
 				Expect(resp.Code).To(Equal(http.StatusOK))
@@ -397,14 +403,14 @@ var _ = Describe("Auth", func() {
 			Expect(result["isAdmin"]).To(BeTrue())
 
 			// Verify user was created as admin
-			u, err := ds.User(context.Background()).FindByUsername("firstuser")
+			u, err := ds.User().FindByUsername(ctx, "firstuser")
 			Expect(err).To(BeNil())
 			Expect(u.IsAdmin).To(BeTrue())
 		})
 
 		It("does not make subsequent users admins", func() {
 			// Create the first user
-			_ = ds.User(context.Background()).Put(&model.User{
+			_ = ds.User().Put(ctx, &model.User{
 				ID:       "existing-user-id",
 				UserName: "existinguser",
 				Name:     "Existing User",
@@ -419,7 +425,7 @@ var _ = Describe("Auth", func() {
 			Expect(result["isAdmin"]).To(BeFalse())
 
 			// Verify user was created as non-admin
-			u, err := ds.User(context.Background()).FindByUsername("seconduser")
+			u, err := ds.User().FindByUsername(ctx, "seconduser")
 			Expect(err).To(BeNil())
 			Expect(u.IsAdmin).To(BeFalse())
 		})
@@ -434,9 +440,9 @@ var _ = Describe("Auth", func() {
 			conf.Server.SessionTimeout = time.Hour
 			ds = &tests.MockDataStore{}
 			auth.Init(ds)
-			ur := ds.User(context.TODO()).(*tests.MockedUserRepo)
+			ur := ds.User().(*tests.MockedUserRepo)
 			usr = &model.User{ID: "u1", UserName: "johndoe", NewPassword: "pw", TokenEpoch: 2}
-			Expect(ur.Put(usr)).To(Succeed())
+			Expect(ur.Put(ctx, usr)).To(Succeed())
 		})
 
 		serve := func(token string) *httptest.ResponseRecorder {
diff --git a/server/events/sse.go b/server/events/sse.go
index 565d8c016..e4d6a05e5 100644
--- a/server/events/sse.go
+++ b/server/events/sse.go
@@ -34,7 +34,7 @@ type (
 		id        uint64
 		event     string
 		data      string
-		senderCtx context.Context
+		senderCtx context.Context //nolint:containedctx // queued message carries the sender ctx
 	}
 	messageChan chan message
 	clientsChan chan client
diff --git a/server/initial_setup.go b/server/initial_setup.go
index e75220abe..be9e14ae9 100644
--- a/server/initial_setup.go
+++ b/server/initial_setup.go
@@ -17,23 +17,23 @@ import (
 func initialSetup(ds model.DataStore) {
 	ctx := context.TODO()
 	err := ds.WithTx(func(tx model.DataStore) error {
-		if err := tx.Library(ctx).StoreMusicFolder(); err != nil {
+		if err := tx.Library().StoreMusicFolder(ctx); err != nil {
 			return err
 		}
 
-		properties := tx.Property(ctx)
-		_, err := properties.Get(consts.InitialSetupFlagKey)
+		properties := tx.Property()
+		_, err := properties.Get(ctx, consts.InitialSetupFlagKey)
 		if err == nil {
 			return nil
 		}
 		log.Info("Running initial setup")
 		if conf.Server.DevAutoCreateAdminPassword != "" {
-			if err = createInitialAdminUser(tx, conf.Server.DevAutoCreateAdminPassword); err != nil {
+			if err = createInitialAdminUser(ctx, tx, conf.Server.DevAutoCreateAdminPassword); err != nil {
 				return err
 			}
 		}
 
-		err = properties.Put(consts.InitialSetupFlagKey, time.Now().String())
+		err = properties.Put(ctx, consts.InitialSetupFlagKey, time.Now().String())
 		return err
 	}, "initial setup")
 	if err != nil {
@@ -42,9 +42,9 @@ func initialSetup(ds model.DataStore) {
 }
 
 // If the Dev Admin user is not present, create it
-func createInitialAdminUser(ds model.DataStore, initialPassword string) error {
-	users := ds.User(context.TODO())
-	c, err := users.CountAll(model.QueryOptions{Filters: squirrel.Eq{"user_name": consts.DevInitialUserName}})
+func createInitialAdminUser(ctx context.Context, ds model.DataStore, initialPassword string) error {
+	users := ds.User()
+	c, err := users.CountAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"user_name": consts.DevInitialUserName}})
 	if err != nil {
 		return fmt.Errorf("could not access User table: %w", err)
 	}
@@ -60,7 +60,7 @@ func createInitialAdminUser(ds model.DataStore, initialPassword string) error {
 			NewPassword: initialPassword,
 			IsAdmin:     true,
 		}
-		if err := users.Put(&initialUser); err != nil {
+		if err := users.Put(ctx, &initialUser); err != nil {
 			return fmt.Errorf("could not create initial admin user: %w", err)
 		}
 	}
diff --git a/server/initial_setup_test.go b/server/initial_setup_test.go
index 0ce8a39fa..0c85d9d0a 100644
--- a/server/initial_setup_test.go
+++ b/server/initial_setup_test.go
@@ -15,7 +15,7 @@ type failingPutUserRepo struct {
 	err error
 }
 
-func (r *failingPutUserRepo) Put(*model.User) error { return r.err }
+func (r *failingPutUserRepo) Put(context.Context, *model.User) error { return r.err }
 
 func dsWithFailingPut(err error) model.DataStore {
 	return &tests.MockDataStore{MockedUser: &failingPutUserRepo{UserRepository: tests.CreateMockUserRepo(), err: err}}
@@ -23,37 +23,39 @@ func dsWithFailingPut(err error) model.DataStore {
 
 var _ = Describe("initial_setup", func() {
 	var ds model.DataStore
+	var ctx context.Context
 
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
+		ctx = GinkgoT().Context()
 	})
 
 	Describe("createInitialAdminUser", func() {
 		It("creates a new admin user with specified password if User table is empty", func() {
-			Expect(createInitialAdminUser(ds, "pass123")).To(BeNil())
-			ur := ds.User(context.TODO())
-			admin, err := ur.FindByUsername("admin")
+			Expect(createInitialAdminUser(ctx, ds, "pass123")).To(BeNil())
+			ur := ds.User()
+			admin, err := ur.FindByUsername(ctx, "admin")
 			Expect(err).To(BeNil())
 			Expect(admin.Password).To(Equal("pass123"))
 		})
 
 		It("does not create a new admin user if User table is not empty", func() {
-			Expect(createInitialAdminUser(ds, "first")).To(BeNil())
-			ur := ds.User(context.TODO())
-			Expect(ur.CountAll()).To(Equal(int64(1)))
-			Expect(createInitialAdminUser(ds, "second")).To(BeNil())
-			Expect(ur.CountAll()).To(Equal(int64(1)))
+			Expect(createInitialAdminUser(ctx, ds, "first")).To(BeNil())
+			ur := ds.User()
+			Expect(ur.CountAll(ctx)).To(Equal(int64(1)))
+			Expect(createInitialAdminUser(ctx, ds, "second")).To(BeNil())
+			Expect(ur.CountAll(ctx)).To(Equal(int64(1)))
 		})
 
 		It("returns the error when the user cannot be stored", func() {
 			boom := errors.New("db is down")
-			Expect(createInitialAdminUser(dsWithFailingPut(boom), "pass123")).To(MatchError(boom))
+			Expect(createInitialAdminUser(ctx, dsWithFailingPut(boom), "pass123")).To(MatchError(boom))
 		})
 
 		It("returns the error when the user table cannot be read", func() {
 			boom := errors.New("db is down")
 			ds = &tests.MockDataStore{MockedUser: &tests.MockedUserRepo{Error: boom}}
-			Expect(createInitialAdminUser(ds, "pass123")).To(MatchError(boom))
+			Expect(createInitialAdminUser(ctx, ds, "pass123")).To(MatchError(boom))
 		})
 	})
 })
diff --git a/server/jellyfin/annotations.go b/server/jellyfin/annotations.go
index ec84f65e0..a589798be 100644
--- a/server/jellyfin/annotations.go
+++ b/server/jellyfin/annotations.go
@@ -28,16 +28,16 @@ func (api *Router) resolveAnnotated(w http.ResponseWriter, r *http.Request, id s
 	switch e := entity.(type) {
 	case *model.Album:
 		if u.HasLibraryAccess(e.LibraryID) {
-			return api.ds.Album(ctx), "album"
+			return api.ds.Album(), "album"
 		}
 	case *model.Artist:
-		return api.ds.Artist(ctx), "artist"
+		return api.ds.Artist(), "artist"
 	case *model.MediaFile:
 		if u.HasLibraryAccess(e.LibraryID) {
-			return api.ds.MediaFile(ctx), "song"
+			return api.ds.MediaFile(), "song"
 		}
 	case *model.Playlist:
-		return api.ds.Playlist(ctx), "playlist"
+		return api.ds.Playlist(), "playlist"
 	}
 	// Unknown ids, inaccessible-library items and non-annotatable entities (radios) all read as absent.
 	http.Error(w, "Not Found", http.StatusNotFound)
@@ -74,7 +74,7 @@ func (api *Router) setFavorite(w http.ResponseWriter, r *http.Request, starred b
 	if repo == nil {
 		return
 	}
-	if err := repo.SetStar(starred, id); err != nil {
+	if err := repo.SetStar(r.Context(), starred, id); err != nil {
 		api.internalError(w, r, err)
 		return
 	}
@@ -97,7 +97,7 @@ func (api *Router) setItemRating(w http.ResponseWriter, r *http.Request, rating
 	if repo == nil {
 		return
 	}
-	if err := repo.SetRating(rating, id); err != nil {
+	if err := repo.SetRating(r.Context(), rating, id); err != nil {
 		api.internalError(w, r, err)
 		return
 	}
diff --git a/server/jellyfin/annotations_test.go b/server/jellyfin/annotations_test.go
index dd1487011..a436503ba 100644
--- a/server/jellyfin/annotations_test.go
+++ b/server/jellyfin/annotations_test.go
@@ -32,7 +32,7 @@ var _ = Describe("Annotations", func() {
 
 	Describe("markFavorite / unmarkFavorite", func() {
 		It("stars a song and returns IsFavorite=true", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/s1", nil).WithContext(ctxUser())
@@ -46,7 +46,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("stars an album and returns IsFavorite=true", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser())
@@ -60,7 +60,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("stars an artist without checking library access (artists span multiple libraries)", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			// alice only has access to library 1, but artists aren't gated per-library.
@@ -75,7 +75,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("stars a visible playlist", func() {
-			playlistRepo := ds.Playlist(context.Background()).(*tests.MockPlaylistRepo)
+			playlistRepo := ds.Playlist().(*tests.MockPlaylistRepo)
 			playlistRepo.SetData(model.Playlists{{ID: testID("p1"), Name: "Mix", OwnerID: testID("u1")}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("p1")), nil).WithContext(ctxUser())
@@ -86,7 +86,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("unstars a song and returns IsFavorite=false", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1, Annotations: model.Annotations{Starred: true}}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("DELETE", "/Users/u1/FavoriteItems/s1", nil).WithContext(ctxUser())
@@ -100,7 +100,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("returns 404 and does not star an album in a library the user can't access", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser()) // only has access to library 1
@@ -111,7 +111,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("returns 404 and does not star a song in a library the user can't access", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 2}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/s1", nil).WithContext(ctxUser()) // only has access to library 1
@@ -130,7 +130,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("returns 500 (not 404) when a repository lookup fails for a reason other than not-found", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetError(true)
+			ds.Album().(*tests.MockAlbumRepo).SetError(true)
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/x1", nil).WithContext(ctxUser())
 			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("x1")))
@@ -139,7 +139,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("emits a refreshResource event when starring a song", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/s1", nil).WithContext(ctxUser())
@@ -150,7 +150,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("emits a refreshResource event when starring an album", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser())
@@ -161,7 +161,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("does not emit an event when the item is not accessible", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/FavoriteItems/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser())
@@ -174,7 +174,7 @@ var _ = Describe("Annotations", func() {
 
 	Describe("setRating / removeRating", func() {
 		It("maps a Jellyfin 0-10 rating to Navidrome's 0-5 scale", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=8", nil).WithContext(ctxUser())
@@ -189,7 +189,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("rates an album", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID(testID("a1"))+"/Rating?Rating=10", nil).WithContext(ctxUser())
@@ -200,7 +200,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("rates a visible playlist", func() {
-			playlistRepo := ds.Playlist(context.Background()).(*tests.MockPlaylistRepo)
+			playlistRepo := ds.Playlist().(*tests.MockPlaylistRepo)
 			playlistRepo.SetData(model.Playlists{{ID: testID("p1"), Name: "Mix", OwnerID: testID("u1")}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID(testID("p1"))+"/Rating?Rating=8", nil).WithContext(ctxUser())
@@ -211,7 +211,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("removes a rating", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1, Annotations: model.Annotations{Rating: 4}}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("DELETE", "/Users/u1/Items/s1/Rating", nil).WithContext(ctxUser())
@@ -225,7 +225,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("returns 404 and does not rate an album in a library the user can't access", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/"+dto.EncodeID(testID("a1"))+"/Rating?Rating=10", nil).WithContext(ctxUser()) // only has access to library 1
@@ -236,7 +236,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("rounds an odd rating to the nearest star instead of truncating", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=9", nil).WithContext(ctxUser())
@@ -247,7 +247,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("stores the minimum star for Rating=1 instead of clearing the rating", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1, Annotations: model.Annotations{Rating: 4}}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=1", nil).WithContext(ctxUser())
@@ -258,7 +258,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("accepts a fractional rating (UserItemDataDto.Rating is a double)", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=7.5", nil).WithContext(ctxUser())
@@ -269,7 +269,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("clamps a Rating above 10 to Navidrome's max (5)", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=100", nil).WithContext(ctxUser())
@@ -280,7 +280,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("clamps a negative Rating to Navidrome's min (0)", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=-5", nil).WithContext(ctxUser())
@@ -291,7 +291,7 @@ var _ = Describe("Annotations", func() {
 		})
 
 		It("emits a refreshResource event when rating a song", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("POST", "/Users/u1/Items/s1/Rating?Rating=8", nil).WithContext(ctxUser())
diff --git a/server/jellyfin/api_test.go b/server/jellyfin/api_test.go
index a64dcfe8f..0c6ac9b98 100644
--- a/server/jellyfin/api_test.go
+++ b/server/jellyfin/api_test.go
@@ -1,6 +1,7 @@
 package jellyfin
 
 import (
+	"context"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -18,6 +19,12 @@ import (
 )
 
 var _ = Describe("Router", func() {
+	var ctx context.Context
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+	})
+
 	It("serves the public handshake through the mounted handler", func() {
 		ds := &tests.MockDataStore{}
 		api := New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
@@ -49,8 +56,8 @@ var _ = Describe("Router", func() {
 	It("registers a player on a general authenticated request, not just playback reports", func() {
 		ds := &tests.MockDataStore{}
 		auth.Init(ds)
-		ur := ds.User(GinkgoT().Context()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
+		ur := ds.User().(*tests.MockedUserRepo)
+		Expect(ur.Put(ctx, &model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
 		token, err := auth.CreateToken(&model.User{ID: testID("u1"), UserName: "alice"})
 		Expect(err).ToNot(HaveOccurred())
 
@@ -95,7 +102,7 @@ var _ = Describe("Router", func() {
 		ds := &tests.MockDataStore{}
 		auth.Init(ds)
 		usr := model.User{ID: testID("alice"), UserName: "alice"}
-		Expect(ds.User(GinkgoT().Context()).Put(&usr)).To(Succeed())
+		Expect(ds.User().Put(ctx, &usr)).To(Succeed())
 		token, err := auth.CreateAPIToken(&usr, auth.AudienceJellyfin)
 		Expect(err).ToNot(HaveOccurred())
 		api := New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, quickconnect.New())
diff --git a/server/jellyfin/auth.go b/server/jellyfin/auth.go
index 32b4a1432..264d5b6ca 100644
--- a/server/jellyfin/auth.go
+++ b/server/jellyfin/auth.go
@@ -24,7 +24,7 @@ func (api *Router) authenticateByName(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// Navidrome stores recoverable passwords; this mirrors Subsonic's validateCredentials plaintext path.
-	usr, err := api.ds.User(ctx).FindByUsernameWithPassword(body.Username)
+	usr, err := api.ds.User().FindByUsernameWithPassword(ctx, body.Username)
 	if body.Pw == "" || err != nil || usr == nil || usr.Password != body.Pw {
 		log.Warn(ctx, "Jellyfin API: invalid login", "username", body.Username, "remoteAddr", r.RemoteAddr)
 		http.Error(w, "Unauthorized", http.StatusUnauthorized)
@@ -37,7 +37,7 @@ func (api *Router) signIn(w http.ResponseWriter, r *http.Request, usr *model.Use
 	ctx := r.Context()
 	// Best-effort, like the web UI's validateLogin: without it, Jellyfin-only users show a
 	// never/stale "Last Login" in the admin UI.
-	if err := api.ds.User(ctx).UpdateLastLoginAt(usr.ID); err != nil {
+	if err := api.ds.User().UpdateLastLoginAt(ctx, usr.ID); err != nil {
 		log.Error(ctx, "Jellyfin API: could not update last login date", "username", usr.UserName, err)
 	}
 
diff --git a/server/jellyfin/auth_test.go b/server/jellyfin/auth_test.go
index 0821614d6..dafad9244 100644
--- a/server/jellyfin/auth_test.go
+++ b/server/jellyfin/auth_test.go
@@ -17,13 +17,15 @@ import (
 )
 
 var _ = Describe("AuthenticateByName", func() {
+	var ctx context.Context
 	var api *Router
 	var ds *tests.MockDataStore
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
+		ur := ds.User().(*tests.MockedUserRepo)
+		Expect(ur.Put(ctx, &model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
 		api = &Router{ds: ds}
 	})
 
@@ -105,15 +107,15 @@ var _ = Describe("AuthenticateByName", func() {
 		api.authenticateByName(w, r)
 
 		Expect(w.Code).To(Equal(http.StatusOK))
-		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		usr, err := ur.FindByUsername("alice")
+		ur := ds.User().(*tests.MockedUserRepo)
+		usr, err := ur.FindByUsername(ctx, "alice")
 		Expect(err).ToNot(HaveOccurred())
 		Expect(usr.LastLoginAt).ToNot(BeNil())
 	})
 
 	It("reflects an administrator in the User.Policy", func() {
-		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: testID("admin1"), UserName: "root", NewPassword: "secret", IsAdmin: true})).To(Succeed())
+		ur := ds.User().(*tests.MockedUserRepo)
+		Expect(ur.Put(ctx, &model.User{ID: testID("admin1"), UserName: "root", NewPassword: "secret", IsAdmin: true})).To(Succeed())
 
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("POST", "/Users/AuthenticateByName",
@@ -136,8 +138,8 @@ var _ = Describe("AuthenticateByName", func() {
 	})
 
 	It("rejects an empty password even for a user with an empty stored password with 401", func() {
-		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: testID("e"), UserName: "empty", NewPassword: ""})).To(Succeed())
+		ur := ds.User().(*tests.MockedUserRepo)
+		Expect(ur.Put(ctx, &model.User{ID: testID("e"), UserName: "empty", NewPassword: ""})).To(Succeed())
 
 		w := httptest.NewRecorder()
 		r := httptest.NewRequest("POST", "/Users/AuthenticateByName",
diff --git a/server/jellyfin/browsing.go b/server/jellyfin/browsing.go
index 25c44e748..baebbf0f3 100644
--- a/server/jellyfin/browsing.go
+++ b/server/jellyfin/browsing.go
@@ -77,7 +77,7 @@ func (api *Router) getStudios(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	opts := model.QueryOptions{Sort: "tag_value", Filters: libraryScopeFilter(scope)}
-	labels, err := api.ds.Tag(ctx).GetAll(model.TagRecordLabel, opts)
+	labels, err := api.ds.Tag().GetAll(ctx, model.TagRecordLabel, opts)
 	if err != nil {
 		api.internalError(w, r, err)
 		return
@@ -97,12 +97,12 @@ func (api *Router) getQueryFiltersLegacy(w http.ResponseWriter, r *http.Request)
 		return
 	}
 	genreOpts := model.QueryOptions{Sort: "name", Filters: libraryScopeFilter(scope)}
-	genres, err := api.ds.Genre(ctx).GetAll(genreOpts)
+	genres, err := api.ds.Genre().GetAll(ctx, genreOpts)
 	if err != nil {
 		api.internalError(w, r, err)
 		return
 	}
-	years, err := api.ds.Album(ctx).GetYears(scope...)
+	years, err := api.ds.Album().GetYears(ctx, scope...)
 	if err != nil {
 		api.internalError(w, r, err)
 		return
diff --git a/server/jellyfin/browsing_test.go b/server/jellyfin/browsing_test.go
index 657c7a42c..48a62c4e5 100644
--- a/server/jellyfin/browsing_test.go
+++ b/server/jellyfin/browsing_test.go
@@ -33,7 +33,7 @@ var _ = Describe("Browsing", func() {
 
 	Describe("getArtists", func() {
 		It("lists artists via /Artists", func() {
-			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "A"}})
+			ds.Artist().(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "A"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
 			invoke(api.getArtists, w, r)
@@ -45,7 +45,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("handles /Artists/AlbumArtists the same way", func() {
-			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "A"}})
+			ds.Artist().(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "A"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists/AlbumArtists", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
 			invoke(api.getArtists, w, r)
@@ -56,7 +56,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("scopes results to the user's accessible libraries", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1}, {ID: 2}}
@@ -70,7 +70,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("scopes to a single library when ParentId is an accessible library id", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1}, {ID: 2}}
@@ -85,7 +85,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("does not let ParentId=<inaccessible library id> narrow the scope", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1}} // no access to library 99
@@ -100,7 +100,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("forwards SearchTerm to the repo's Search method", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists?SearchTerm=art", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
@@ -112,7 +112,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("bounds a search the client left unbounded, and clamps an oversized one", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 
 			w := httptest.NewRecorder()
@@ -129,7 +129,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("forwards StartIndex/Limit as Offset/Max", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists?StartIndex=5&Limit=10", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
@@ -140,7 +140,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("does not restrict results for an admin user", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists", nil).WithContext(ctxAdmin())
@@ -158,7 +158,7 @@ var _ = Describe("Browsing", func() {
 
 		DescribeTable("restricts to favorites",
 			func(url string, handler func(*Router) http.HandlerFunc) {
-				artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+				artistRepo := ds.Artist().(*tests.MockArtistRepo)
 				artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", url, nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
@@ -180,7 +180,7 @@ var _ = Describe("Browsing", func() {
 		)
 
 		It("404s a malformed ParentId instead of listing every library's artists", func() {
-			artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+			artistRepo := ds.Artist().(*tests.MockArtistRepo)
 			artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Artists?ParentId=not-a-valid-id", nil).WithContext(ctxUser(model.Libraries{{ID: 1}}))
@@ -210,7 +210,7 @@ var _ = Describe("Browsing", func() {
 
 	Describe("getStudios", func() {
 		It("scopes results to the user's accessible libraries", func() {
-			tagRepo := ds.Tag(context.Background()).(*tests.MockTagRepo)
+			tagRepo := ds.Tag().(*tests.MockTagRepo)
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Studios", nil).WithContext(ctxUser(model.Libraries{{ID: 1}, {ID: 2}}))
 			invoke(api.getStudios, w, r)
@@ -224,7 +224,7 @@ var _ = Describe("Browsing", func() {
 		// An empty scope (admin, or a non-admin with no explicit library grants) must be treated
 		// as unrestricted, matching accessibleLibraryIDs' documented contract, not as "match nothing".
 		It("does not restrict results for an admin user", func() {
-			tagRepo := ds.Tag(context.Background()).(*tests.MockTagRepo)
+			tagRepo := ds.Tag().(*tests.MockTagRepo)
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Studios", nil).WithContext(ctxAdmin())
 			invoke(api.getStudios, w, r)
@@ -242,7 +242,7 @@ var _ = Describe("Browsing", func() {
 
 	Describe("getQueryFiltersLegacy", func() {
 		It("scopes genres to the user's accessible libraries", func() {
-			genreRepo := ds.Genre(context.Background()).(*tests.MockedGenreRepo)
+			genreRepo := ds.Genre().(*tests.MockedGenreRepo)
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/Filters", nil).WithContext(ctxUser(model.Libraries{{ID: 1}, {ID: 2}}))
 			invoke(api.getQueryFiltersLegacy, w, r)
@@ -254,7 +254,7 @@ var _ = Describe("Browsing", func() {
 		})
 
 		It("does not restrict genres for an admin user", func() {
-			genreRepo := ds.Genre(context.Background()).(*tests.MockedGenreRepo)
+			genreRepo := ds.Genre().(*tests.MockedGenreRepo)
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/Filters", nil).WithContext(ctxAdmin())
 			invoke(api.getQueryFiltersLegacy, w, r)
diff --git a/server/jellyfin/e2e/auth_test.go b/server/jellyfin/e2e/auth_test.go
index 156e79ce9..35daaf598 100644
--- a/server/jellyfin/e2e/auth_test.go
+++ b/server/jellyfin/e2e/auth_test.go
@@ -87,10 +87,10 @@ var _ = Describe("Authentication", func() {
 			Expect(pw.Code).To(Equal(http.StatusOK))
 
 			// A real password change through the repository, which is what revokes in production.
-			admin, err := ds.User(ctx).Get(testID("admin-1"))
+			admin, err := ds.User().Get(ctx, testID("admin-1"))
 			Expect(err).ToNot(HaveOccurred())
 			admin.NewPassword = "rotated"
-			Expect(ds.User(ctx).Put(admin)).To(Succeed())
+			Expect(ds.User().Put(ctx, admin)).To(Succeed())
 
 			r = httptest.NewRequest("GET", "/Users/Me", nil)
 			r.Header.Set("X-Emby-Token", res.AccessToken)
diff --git a/server/jellyfin/e2e/e2e_suite_test.go b/server/jellyfin/e2e/e2e_suite_test.go
index 5aa38cba1..4f3cd82b5 100644
--- a/server/jellyfin/e2e/e2e_suite_test.go
+++ b/server/jellyfin/e2e/e2e_suite_test.go
@@ -244,7 +244,7 @@ func enc(id string) string { return dto.EncodeID(id) }
 // guessing repository filter column names.
 
 func albumID(name string) string {
-	albums, err := ds.Album(ctx).GetAll()
+	albums, err := ds.Album().GetAll(ctx)
 	Expect(err).ToNot(HaveOccurred())
 	for _, a := range albums {
 		if a.Name == name {
@@ -256,7 +256,7 @@ func albumID(name string) string {
 }
 
 func songID(title string) string {
-	mfs, err := ds.MediaFile(ctx).GetAll()
+	mfs, err := ds.MediaFile().GetAll(ctx)
 	Expect(err).ToNot(HaveOccurred())
 	for _, mf := range mfs {
 		if mf.Title == title {
@@ -268,7 +268,7 @@ func songID(title string) string {
 }
 
 func artistID(name string) string {
-	artists, err := ds.Artist(ctx).GetAll()
+	artists, err := ds.Artist().GetAll(ctx)
 	Expect(err).ToNot(HaveOccurred())
 	for _, a := range artists {
 		if a.Name == name {
@@ -280,7 +280,7 @@ func artistID(name string) string {
 }
 
 func genreID(name string) string {
-	genres, err := ds.Genre(ctx).GetAll()
+	genres, err := ds.Genre().GetAll(ctx)
 	Expect(err).ToNot(HaveOccurred())
 	for _, g := range genres {
 		if g.Name == name {
@@ -399,7 +399,7 @@ func (f *fakeSonicProvider) FindSonicPath(context.Context, *model.MediaFile, *mo
 // songAgent looks a seeded track up by title (titles are unique in the seed) and builds an
 // agents.Song carrying its title+artist, so the matcher resolves it back to that MediaFile.
 func songAgent(title string) agents.Song {
-	mfs, err := ds.MediaFile(ctx).GetAll()
+	mfs, err := ds.MediaFile().GetAll(ctx)
 	Expect(err).ToNot(HaveOccurred())
 	for _, mf := range mfs {
 		if mf.Title == title {
diff --git a/server/jellyfin/e2e/multiuser_test.go b/server/jellyfin/e2e/multiuser_test.go
index d3a521332..905d4e16f 100644
--- a/server/jellyfin/e2e/multiuser_test.go
+++ b/server/jellyfin/e2e/multiuser_test.go
@@ -19,8 +19,8 @@ var _ = Describe("Multi-user access control", func() {
 
 		It("hides all content from a user with no library access", func() {
 			noAccess := model.User{ID: testID("noaccess-1"), UserName: "noaccess", Name: "No Access", NewPassword: "password"}
-			Expect(ds.User(ctx).Put(&noAccess)).To(Succeed())
-			loaded, err := ds.User(ctx).FindByUsername("noaccess")
+			Expect(ds.User().Put(ctx, &noAccess)).To(Succeed())
+			loaded, err := ds.User().FindByUsername(ctx, "noaccess")
 			Expect(err).ToNot(HaveOccurred())
 
 			q := queryResult(getAs(*loaded, "/Items?IncludeItemTypes=MusicAlbum&Recursive=true"))
diff --git a/server/jellyfin/e2e/playlists_test.go b/server/jellyfin/e2e/playlists_test.go
index 3dd53227f..49c8e5a8c 100644
--- a/server/jellyfin/e2e/playlists_test.go
+++ b/server/jellyfin/e2e/playlists_test.go
@@ -66,13 +66,13 @@ var _ = Describe("Playlists", func() {
 		// dto.DecodeIDs is all-or-nothing: a malformed entry must 404 the whole request, not get
 		// dropped while the well-formed entries are still used to create a playlist.
 		It("404s when one of the Ids is malformed, without creating a playlist", func() {
-			before, err := ds.Playlist(ctx).CountAll()
+			before, err := ds.Playlist().CountAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			body := `{"Name":"ShouldNotExist","Ids":["` + enc(songID("So What")) + `","not-a-valid-id"]}`
 			Expect(post("/Playlists", body).Code).To(Equal(http.StatusNotFound))
 
-			after, err := ds.Playlist(ctx).CountAll()
+			after, err := ds.Playlist().CountAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(after).To(Equal(before))
 		})
@@ -318,14 +318,14 @@ var _ = Describe("Playlists", func() {
 			Expect(upload(adminUser, "/Items/"+enc(plID)+"/Images/Primary", "image/jpeg", jpeg).Code).
 				To(Equal(http.StatusNoContent))
 
-			pls, err := ds.Playlist(ctx).Get(plID)
+			pls, err := ds.Playlist().Get(ctx, plID)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(pls.UploadedImage).ToNot(BeEmpty())
 			_, statErr := os.Stat(pls.UploadedImagePath())
 			Expect(statErr).ToNot(HaveOccurred(), "cover file should exist on disk")
 
 			Expect(del("/Items/" + enc(plID) + "/Images/Primary").Code).To(Equal(http.StatusNoContent))
-			pls, _ = ds.Playlist(ctx).Get(plID)
+			pls, _ = ds.Playlist().Get(ctx, plID)
 			Expect(pls.UploadedImage).To(BeEmpty())
 		})
 
@@ -338,7 +338,7 @@ var _ = Describe("Playlists", func() {
 		// from their tag-keyed cache until the next scan.
 		It("clears the resolved image tag after a cover upload", func() {
 			plID := createPlaylist("Cover Tag", nil)
-			Expect(ds.Artwork(ctx).PutItemArtwork(&model.ItemArtwork{
+			Expect(ds.Artwork().PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: model.KindPlaylistArtwork.Prefix(), ItemID: plID, Hash: "1111111111111111",
 			})).To(Succeed())
 
@@ -378,7 +378,7 @@ var _ = Describe("Playlists", func() {
 		It("renames a playlist", func() {
 			plID := createPlaylist("Old Name", nil)
 			Expect(post("/Playlists/"+enc(plID), `{"Name":"New Name"}`).Code).To(Equal(http.StatusNoContent))
-			pls, _ := ds.Playlist(ctx).Get(plID)
+			pls, _ := ds.Playlist().Get(ctx, plID)
 			Expect(pls.Name).To(Equal("New Name"))
 		})
 
@@ -410,7 +410,7 @@ var _ = Describe("Playlists", func() {
 			q := playlistItems(plID)
 			Expect(q.TotalRecordCount).To(Equal(1))
 			Expect(q.Items[0].Name).To(Equal("So What"))
-			pls, _ := ds.Playlist(ctx).Get(plID)
+			pls, _ := ds.Playlist().Get(ctx, plID)
 			Expect(pls.Name).To(Equal("Combo Renamed"))
 			Expect(pls.Public).To(BeTrue())
 		})
@@ -424,13 +424,13 @@ var _ = Describe("Playlists", func() {
 		// An id that decodes to "" would tell Create to make a new playlist instead of updating one —
 		// itemIDParam must 404 before that decode ever runs, not silently create one.
 		It("404s for a malformed playlist id, without creating a playlist", func() {
-			before, err := ds.Playlist(ctx).CountAll()
+			before, err := ds.Playlist().CountAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 
 			w := post("/Playlists/00000000000000000000000000000000", `{"Ids":["`+enc(songID("So What"))+`"]}`)
 			Expect(w.Code).To(Equal(http.StatusNotFound))
 
-			after, err := ds.Playlist(ctx).CountAll()
+			after, err := ds.Playlist().CountAll(ctx)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(after).To(Equal(before))
 		})
diff --git a/server/jellyfin/e2e/sessions_test.go b/server/jellyfin/e2e/sessions_test.go
index c5c42cb2b..22c87b108 100644
--- a/server/jellyfin/e2e/sessions_test.go
+++ b/server/jellyfin/e2e/sessions_test.go
@@ -27,12 +27,12 @@ var _ = Describe("Sessions", func() {
 
 		It("counts a play stopped past the threshold", func() {
 			id := songID("So What")
-			mf, err := ds.MediaFile(ctx).Get(id)
+			mf, err := ds.MediaFile().Get(ctx, id)
 			Expect(err).ToNot(HaveOccurred())
 			// Report a stop at the end of the track — comfortably past 50% / the 4-minute cap.
 			Expect(post("/Sessions/Playing/Stopped", reportBody(id, ticks(int64(mf.Duration*1000)))).Code).To(Equal(http.StatusNoContent))
 
-			mf, err = ds.MediaFile(ctx).Get(id)
+			mf, err = ds.MediaFile().Get(ctx, id)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(mf.PlayCount).To(BeNumerically(">=", 1))
 		})
@@ -48,7 +48,7 @@ var _ = Describe("Sessions", func() {
 			id := songID("Help!")
 			Expect(post("/Sessions/Playing/Stopped", reportBody(id, ticks(1000))).Code).To(Equal(http.StatusNoContent))
 
-			mf, err := ds.MediaFile(ctx).Get(id)
+			mf, err := ds.MediaFile().Get(ctx, id)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(mf.PlayCount).To(Equal(int64(0)))
 		})
diff --git a/server/jellyfin/e2e/similar_test.go b/server/jellyfin/e2e/similar_test.go
index 06054f8bf..a5d2505ba 100644
--- a/server/jellyfin/e2e/similar_test.go
+++ b/server/jellyfin/e2e/similar_test.go
@@ -68,9 +68,9 @@ var _ = Describe("Similar", func() {
 			// Seed an album in a second library the regular user has no access to, and point a
 			// provider similar-song at it.
 			otherLib := model.Library{ID: 2, Name: "Other Library", Path: "fake:///other"}
-			Expect(ds.Library(ctx).Put(&otherLib)).To(Succeed())
+			Expect(ds.Library().Put(ctx, &otherLib)).To(Succeed())
 			otherAlbum := model.Album{ID: testID("other-album"), Name: "Other Album", LibraryID: 2}
-			Expect(ds.Album(ctx).Put(&otherAlbum)).To(Succeed())
+			Expect(ds.Album().Put(ctx, &otherAlbum)).To(Succeed())
 
 			providerFake.similarSongs = model.MediaFiles{
 				{ID: testID("x1"), AlbumID: albumID("IV")},         // library 1 -> visible
diff --git a/server/jellyfin/images.go b/server/jellyfin/images.go
index 0c9e0380c..6af533dbb 100644
--- a/server/jellyfin/images.go
+++ b/server/jellyfin/images.go
@@ -82,16 +82,16 @@ func hashFromTag(r *http.Request) string {
 // resolveArtworkID maps a Jellyfin item id to a Navidrome ArtworkID, probing
 // album -> artist -> media file -> playlist.
 func (api *Router) resolveArtworkID(ctx context.Context, itemId string) string {
-	if al, err := api.ds.Album(ctx).Get(itemId); err == nil {
+	if al, err := api.ds.Album().Get(ctx, itemId); err == nil {
 		return al.CoverArtID().String()
 	}
-	if ar, err := api.ds.Artist(ctx).Get(itemId); err == nil {
+	if ar, err := api.ds.Artist().Get(ctx, itemId); err == nil {
 		return ar.CoverArtID().String()
 	}
-	if mf, err := api.ds.MediaFile(ctx).Get(itemId); err == nil {
+	if mf, err := api.ds.MediaFile().Get(ctx, itemId); err == nil {
 		return mf.CoverArtID().String()
 	}
-	if pl, err := api.ds.Playlist(ctx).Get(itemId); err == nil {
+	if pl, err := api.ds.Playlist().Get(ctx, itemId); err == nil {
 		return pl.CoverArtID().String()
 	}
 	return (model.ArtworkID{}).String()
diff --git a/server/jellyfin/images_test.go b/server/jellyfin/images_test.go
index b7b262895..b7cf9b7e7 100644
--- a/server/jellyfin/images_test.go
+++ b/server/jellyfin/images_test.go
@@ -68,7 +68,7 @@ var _ = Describe("Images", func() {
 	DescribeTable("derives the requested size from the Jellyfin size params",
 		func(query string, wantSize int) {
 			ds := &tests.MockDataStore{}
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			fa := &fakeArtwork{}
 			api := &Router{ds: ds, artwork: fa}
 
@@ -97,7 +97,7 @@ var _ = Describe("Images", func() {
 
 	It("streams album artwork", func() {
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 		fa := &fakeArtwork{}
 		api := &Router{ds: ds, artwork: fa}
 
@@ -138,7 +138,7 @@ var _ = Describe("Images", func() {
 
 	It("sniffs the Content-Type instead of hardcoding it", func() {
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 
 		png := append([]byte{0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n'}, make([]byte, 512)...)
 		fa := &fakeArtwork{data: png}
@@ -153,7 +153,7 @@ var _ = Describe("Images", func() {
 
 	It("resolves a playlist's cover regardless of visibility, even for an anonymous caller", func() {
 		ds := &tests.MockDataStore{}
-		ds.Playlist(context.Background()).(*tests.MockPlaylistRepo).SetData(model.Playlists{{ID: testID("pl1"), Name: "Mix", OwnerID: testID("someone")}})
+		ds.Playlist().(*tests.MockPlaylistRepo).SetData(model.Playlists{{ID: testID("pl1"), Name: "Mix", OwnerID: testID("someone")}})
 		fa := &fakeArtwork{}
 		api := &Router{ds: ds, artwork: fa}
 
@@ -169,7 +169,7 @@ var _ = Describe("Images", func() {
 	// silently falls back to the placeholder.
 	It("resolves artwork under an elevated admin context", func() {
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 		fa := &fakeArtwork{}
 		api := &Router{ds: ds, artwork: fa}
 
@@ -185,7 +185,7 @@ var _ = Describe("Images", func() {
 	It("serves immutable when the tag param asserts the current hash", func() {
 		const hash = "0123456789abcdef"
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 		fa := &fakeArtwork{hash: hash}
 		api := &Router{ds: ds, artwork: fa}
 
@@ -203,7 +203,7 @@ var _ = Describe("Images", func() {
 	It("revalidates via no-cache when no tag is provided", func() {
 		const hash = "0123456789abcdef"
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 		fa := &fakeArtwork{hash: hash}
 		api := &Router{ds: ds, artwork: fa}
 
diff --git a/server/jellyfin/items.go b/server/jellyfin/items.go
index 23e35dd59..28de4c31e 100644
--- a/server/jellyfin/items.go
+++ b/server/jellyfin/items.go
@@ -382,7 +382,7 @@ func (api *Router) parseItemsQuery(ctx context.Context, r *http.Request) (itemsQ
 		if q.parentId == dto.PlaylistsFolderID {
 			// Browsing into the synthetic playlists folder lists the user's playlists.
 			q.types = []string{"Playlist"}
-		} else if _, err := api.ds.Album(ctx).Get(q.parentId); err == nil {
+		} else if _, err := api.ds.Album().Get(ctx, q.parentId); err == nil {
 			q.types = []string{"Audio"}
 		}
 	}
@@ -412,7 +412,7 @@ func (api *Router) queryItems(ctx context.Context, r *http.Request) (itemsResult
 		return materialized(result([]dto.BaseItemDto{playlistsFolder()}, 1, 0)), nil
 	}
 	if repo, ok := api.playlistTracksRepo(ctx, q); ok {
-		return api.playlistTrackPage(repo, q.fields, q.offset, q.limit)
+		return api.playlistTrackPage(ctx, repo, q.fields, q.offset, q.limit)
 	}
 	if q.search != "" {
 		q.limit = clampLimit(q.limit, defaultSearchLimit, maxSearchLimit)
@@ -702,7 +702,7 @@ func searchPage[S ~[]E, E any](opts model.QueryOptions, search func(model.QueryO
 
 func (api *Router) listAlbums(ctx context.Context, opts model.QueryOptions, q itemsQuery) (itemsResult, error) {
 	toItem := func(al model.Album) dto.BaseItemDto { return dto.AlbumToBaseItem(al, q.fields) }
-	repo := api.ds.Album(ctx)
+	repo := api.ds.Album()
 	filters := squirrel.And{}
 	// For albums, ParentId (browse an artist) and AlbumArtistIds/ArtistIds both mean "this artist's
 	// albums"; contributingArtistIds means "albums they only appear on" (Featured On).
@@ -733,23 +733,23 @@ func (api *Router) listAlbums(ctx context.Context, opts model.QueryOptions, q it
 
 	if q.search != "" {
 		albums, total, err := searchPage(opts, func(o model.QueryOptions) (model.Albums, error) {
-			return repo.Search(q.search, o)
+			return repo.Search(ctx, q.search, o)
 		})
 		if err != nil {
 			return itemsResult{}, err
 		}
 		return materialized(result(slice.Map(albums, toItem), total, opts.Offset)), nil
 	}
-	total, _ := repo.CountAll(model.QueryOptions{Filters: opts.Filters})
+	total, _ := repo.CountAll(ctx, model.QueryOptions{Filters: opts.Filters})
 	open := streamCursor(func() (func(func(model.Album, error) bool), error) {
-		return repo.GetCursor(opts)
+		return repo.GetCursor(ctx, opts)
 	}, toItem)
 	return streamed(open, int(total), opts.Offset), nil
 }
 
 func (api *Router) listSongs(ctx context.Context, opts model.QueryOptions, q itemsQuery) (itemsResult, error) {
 	toItem := func(mf model.MediaFile) dto.BaseItemDto { return dto.SongToBaseItem(mf, q.fields) }
-	repo := api.ds.MediaFile(ctx)
+	repo := api.ds.MediaFile()
 	filters := squirrel.And{}
 	// For songs, ArtistIds/AlbumArtistIds selects an artist's tracks; ParentId selects an album's.
 	switch {
@@ -782,7 +782,7 @@ func (api *Router) listSongs(ctx context.Context, opts model.QueryOptions, q ite
 
 	if q.search != "" {
 		mfs, total, err := searchPage(opts, func(o model.QueryOptions) (model.MediaFiles, error) {
-			return repo.Search(q.search, o)
+			return repo.Search(ctx, q.search, o)
 		})
 		if err != nil {
 			return itemsResult{}, err
@@ -795,9 +795,9 @@ func (api *Router) listSongs(ctx context.Context, opts model.QueryOptions, q ite
 		opts.Sort = filter.SongsByAlbum(q.entityParent).Sort
 	}
 	// A full-library request (Finamp's sync, with MediaSources) is tens of thousands of fat rows.
-	total, _ := repo.CountAll(model.QueryOptions{Filters: opts.Filters})
+	total, _ := repo.CountAll(ctx, model.QueryOptions{Filters: opts.Filters})
 	open := streamCursor(func() (func(func(model.MediaFile, error) bool), error) {
-		return repo.GetCursorWithArtwork(opts)
+		return repo.GetCursorWithArtwork(ctx, opts)
 	}, toItem)
 	return streamed(open, int(total), opts.Offset), nil
 }
@@ -806,7 +806,7 @@ func (api *Router) listSongs(ctx context.Context, opts model.QueryOptions, q ite
 // RoleArtist for performing artists (/Artists). Without the role filter both lists would be identical.
 // genreIds isn't applied to search — a name lookup, like role (see below).
 func (api *Router) listArtists(ctx context.Context, opts model.QueryOptions, q itemsQuery, role model.Role) (itemsResult, error) {
-	repo := api.ds.Artist(ctx)
+	repo := api.ds.Artist()
 	toItem := func(ar model.Artist) dto.BaseItemDto { return dto.ArtistToBaseItem(ar, q.fields) }
 
 	// Artist Search does its own library scoping: it consumes a sole Eq{"library_id": ...} filter as a
@@ -818,7 +818,7 @@ func (api *Router) listArtists(ctx context.Context, opts model.QueryOptions, q i
 			opts.Filters = squirrel.Eq{"library_id": q.scopeIDs}
 		}
 		artists, total, err := searchPage(opts, func(o model.QueryOptions) (model.Artists, error) {
-			return repo.Search(q.search, o)
+			return repo.Search(ctx, q.search, o)
 		})
 		if err != nil {
 			return itemsResult{}, err
@@ -834,9 +834,9 @@ func (api *Router) listArtists(ctx context.Context, opts model.QueryOptions, q i
 	opts.Filters = filters
 	opts = filter.ArtistsByRole(opts, role)
 	opts = filter.ApplyArtistLibraryFilter(opts, q.scopeIDs)
-	total, _ := repo.CountAll(model.QueryOptions{Filters: opts.Filters})
+	total, _ := repo.CountAll(ctx, model.QueryOptions{Filters: opts.Filters})
 	open := streamCursor(func() (func(func(model.Artist, error) bool), error) {
-		return repo.GetCursor(opts)
+		return repo.GetCursor(ctx, opts)
 	}, toItem)
 	return streamed(open, int(total), opts.Offset), nil
 }
@@ -845,7 +845,7 @@ func (api *Router) listArtists(ctx context.Context, opts model.QueryOptions, q i
 // the one listXxx that stays materialized: GenreRepository has no CountAll, so the total is the
 // length of the full list and paging is in-memory — nothing for a cursor to page over.
 func (api *Router) listGenres(ctx context.Context, opts model.QueryOptions) (itemsResult, error) {
-	genres, err := api.ds.Genre(ctx).GetAll(model.QueryOptions{Sort: opts.Sort, Order: opts.Order})
+	genres, err := api.ds.Genre().GetAll(ctx, model.QueryOptions{Sort: opts.Sort, Order: opts.Order})
 	if err != nil {
 		return itemsResult{}, err
 	}
@@ -859,13 +859,13 @@ func (api *Router) listPlaylists(ctx context.Context, opts model.QueryOptions, q
 	if preds := q.filters.predicates(); len(preds) > 0 {
 		opts.Filters = squirrel.And(preds)
 	}
-	repo := api.ds.Playlist(ctx)
-	total, err := repo.CountAll(model.QueryOptions{Filters: opts.Filters})
+	repo := api.ds.Playlist()
+	total, err := repo.CountAll(ctx, model.QueryOptions{Filters: opts.Filters})
 	if err != nil {
 		return itemsResult{}, err
 	}
 	open := streamCursor(func() (func(func(model.Playlist, error) bool), error) {
-		return repo.GetCursor(opts)
+		return repo.GetCursor(ctx, opts)
 	}, func(p model.Playlist) dto.BaseItemDto { return dto.PlaylistToBaseItem(p, q.fields) })
 	return streamed(open, int(total), opts.Offset), nil
 }
@@ -882,21 +882,21 @@ func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fi
 	// Finamp resolves a /UserViews entry (Id=library id) by fetching it as a plain item; without this
 	// the home screen and library tabs 404.
 	if libID, err := strconv.Atoi(id); err == nil && u.HasLibraryAccess(libID) {
-		if lib, err := api.ds.Library(ctx).Get(libID); err == nil {
+		if lib, err := api.ds.Library().Get(ctx, libID); err == nil {
 			return dto.LibraryToBaseItem(*lib), true
 		}
 	}
-	if al, err := api.ds.Album(ctx).Get(id); err == nil {
+	if al, err := api.ds.Album().Get(ctx, id); err == nil {
 		if !u.HasLibraryAccess(al.LibraryID) {
 			return dto.BaseItemDto{}, false
 		}
 		return dto.AlbumToBaseItem(*al, fields), true
 	}
-	if ar, err := api.ds.Artist(ctx).Get(id); err == nil {
+	if ar, err := api.ds.Artist().Get(ctx, id); err == nil {
 		// Artist.Get already scopes to the user's libraries via library_artist.
 		return dto.ArtistToBaseItem(*ar, fields), true
 	}
-	if mf, err := api.ds.MediaFile(ctx).Get(id); err == nil {
+	if mf, err := api.ds.MediaFile().Get(ctx, id); err == nil {
 		if !u.HasLibraryAccess(mf.LibraryID) {
 			return dto.BaseItemDto{}, false
 		}
@@ -906,7 +906,7 @@ func (api *Router) resolveItemByID(ctx context.Context, id string, fields dto.Fi
 	if pl, err := api.playlists.Get(ctx, id); err == nil {
 		return dto.PlaylistToBaseItem(*pl, fields), true
 	}
-	if g, err := api.ds.Genre(ctx).Get(id); err == nil {
+	if g, err := api.ds.Genre().Get(ctx, id); err == nil {
 		return dto.GenreToBaseItem(*g), true
 	}
 	return dto.BaseItemDto{}, false
@@ -917,7 +917,7 @@ func (api *Router) songsByIDs(ctx context.Context, ids []string) map[string]mode
 	songs := make(map[string]model.MediaFile, len(ids))
 	// Chunked to stay under SQLITE_MAX_VARIABLE_NUMBER, like playqueue's loadTracks.
 	for chunk := range slice.CollectChunks(slices.Values(ids), 500) {
-		mfs, err := api.ds.MediaFile(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"media_file.id": chunk}})
+		mfs, err := api.ds.MediaFile().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"media_file.id": chunk}})
 		if err != nil {
 			log.Error(ctx, "Jellyfin API: error fetching songs by id", err)
 			continue
@@ -997,9 +997,9 @@ func (api *Router) getLatest(w http.ResponseWriter, r *http.Request) {
 		opts.Filters = squirrel.And{opts.Filters, filter.AlbumsByArtistID(parentID).Filters}
 	}
 	opts = filter.ApplyLibraryFilter(opts, scopeIDs)
-	repo := api.ds.Album(ctx)
+	repo := api.ds.Album()
 	open := streamCursor(func() (func(func(model.Album, error) bool), error) {
-		return repo.GetCursor(opts)
+		return repo.GetCursor(ctx, opts)
 	}, func(al model.Album) dto.BaseItemDto { return dto.AlbumToBaseItem(al, fields) })
 	api.writeItemsArray(w, r, streamed(open, 0, 0))
 }
diff --git a/server/jellyfin/items_test.go b/server/jellyfin/items_test.go
index a8dfb7bb2..18789a34b 100644
--- a/server/jellyfin/items_test.go
+++ b/server/jellyfin/items_test.go
@@ -49,7 +49,7 @@ var _ = Describe("Items", func() {
 
 	Describe("getItems", func() {
 		It("lists albums when IncludeItemTypes=MusicAlbum", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&Recursive=true", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -62,8 +62,8 @@ var _ = Describe("Items", func() {
 		})
 
 		It("lists an album's songs when ParentId is an album and type is Audio", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", AlbumID: testID("a1")}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", AlbumID: testID("a1")}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("a1"))+"&IncludeItemTypes=Audio", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -75,8 +75,8 @@ var _ = Describe("Items", func() {
 		})
 
 		It("ignores IncludeItemTypes names that aren't Jellyfin item kinds", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", AlbumID: testID("a1")}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", AlbumID: testID("a1")}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("a1"))+"&IncludeItemTypes=music", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -126,8 +126,8 @@ var _ = Describe("Items", func() {
 
 		It("falls through to the type dispatch when ParentId is not a playlist", func() {
 			fp.getErr = model.ErrNotFound
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), AlbumID: testID("a1")}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), AlbumID: testID("a1")}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("a1"))+"&IncludeItemTypes=Audio", nil).
 				WithContext(ctxUser())
@@ -140,7 +140,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("returns 500 when the song cursor fails to open, instead of a truncated 200", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetError(true)
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetError(true)
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&Recursive=true", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -151,8 +151,8 @@ var _ = Describe("Items", func() {
 		// looking for tracks outside any album; answering with every track streams the whole library.
 		Describe("Recursive=false", func() {
 			BeforeEach(func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), AlbumID: testID("a1")}})
+				ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), AlbumID: testID("a1")}})
 			})
 
 			It("returns no songs for a library parent, as tracks are never its direct children", func() {
@@ -223,21 +223,21 @@ var _ = Describe("Items", func() {
 		})
 
 		It("lists an artist's albums when ParentId is an artist and type is MusicAlbum", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", AlbumArtistID: testID("ar1")}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", AlbumArtistID: testID("ar1")}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?ParentId="+dto.EncodeID(testID("ar1"))+"&IncludeItemTypes=MusicAlbum", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
 			var res dto.QueryResult
 			Expect(json.Unmarshal(w.Body.Bytes(), &res)).To(Succeed())
 			Expect(res.Items).To(HaveLen(1))
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			sql, _, err := albumRepo.Options.Filters.ToSql()
 			Expect(err).NotTo(HaveOccurred())
 			Expect(sql).To(ContainSubstring("album_artists"))
 		})
 
 		It("lists artists when IncludeItemTypes=MusicArtist", func() {
-			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
+			ds.Artist().(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicArtist", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -258,7 +258,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("lists playlists when IncludeItemTypes=Playlist", func() {
-			ds.Playlist(context.Background()).(*tests.MockPlaylistRepo).SetData(model.Playlists{{ID: testID("p1"), Name: "My Mix", SongCount: 5}})
+			ds.Playlist().(*tests.MockPlaylistRepo).SetData(model.Playlists{{ID: testID("p1"), Name: "My Mix", SongCount: 5}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Playlist", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -272,8 +272,8 @@ var _ = Describe("Items", func() {
 		})
 
 		It("merges results from every requested type in IncludeItemTypes", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -287,11 +287,11 @@ var _ = Describe("Items", func() {
 		})
 
 		It("merges favorite songs, albums, and playlists", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-			playlistRepo := ds.Playlist(context.Background()).(*tests.MockPlaylistRepo)
+			playlistRepo := ds.Playlist().(*tests.MockPlaylistRepo)
 			playlistRepo.SetData(model.Playlists{{ID: testID("p1"), Name: "My Mix", Annotations: model.Annotations{Starred: true}}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum,Playlist&Filters=IsFavorite", nil).WithContext(ctxUser())
@@ -312,8 +312,8 @@ var _ = Describe("Items", func() {
 		})
 
 		It("applies StartIndex/Limit to the merged multi-type result set", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}, {ID: testID("s2"), Title: "Song2"}})
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}, {ID: testID("s2"), Title: "Song2"}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&StartIndex=1&Limit=2", nil).WithContext(ctxUser())
 			invoke(api.getItems, w, r)
@@ -326,9 +326,9 @@ var _ = Describe("Items", func() {
 		})
 
 		It("caps each per-type query at StartIndex+Limit instead of fetching everything", func() {
-			mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+			mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 			mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}, {ID: testID("s2"), Title: "Song2"}})
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&StartIndex=1&Limit=2", nil).WithContext(ctxUser())
@@ -341,7 +341,7 @@ var _ = Describe("Items", func() {
 
 		DescribeTable("translates the Filters list and its standalone equivalents",
 			func(query string, wantSQL, notWantSQL []string) {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+				albumRepo := ds.Album().(*tests.MockAlbumRepo)
 				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&"+query, nil).WithContext(ctxUser())
@@ -381,8 +381,8 @@ var _ = Describe("Items", func() {
 		// annotation predicate there is "no such column: starred" -> 500.
 		DescribeTable("does not push annotation filters into a search",
 			func(itemType, filters string) {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+				ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET",
 					"/Items?IncludeItemTypes="+itemType+"&SearchTerm=one&Filters="+filters, nil).WithContext(ctxUser())
@@ -390,9 +390,9 @@ var _ = Describe("Items", func() {
 				Expect(w.Code).To(Equal(http.StatusOK))
 				var opts model.QueryOptions
 				if itemType == "MusicAlbum" {
-					opts = ds.Album(context.Background()).(*tests.MockAlbumRepo).Options
+					opts = ds.Album().(*tests.MockAlbumRepo).Options
 				} else {
-					opts = ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).Options
+					opts = ds.MediaFile().(*tests.MockMediaFileRepo).Options
 				}
 				if opts.Filters == nil {
 					return
@@ -410,7 +410,7 @@ var _ = Describe("Items", func() {
 		)
 
 		It("forwards SearchTerm to the repo's Search method", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=one", nil).WithContext(ctxUser())
@@ -422,7 +422,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("caps a search the client left unbounded", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=one", nil).WithContext(ctxUser())
@@ -432,7 +432,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("honors an explicit search Limit up to the ceiling", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=one&Limit=500", nil).
@@ -443,7 +443,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("clamps a search Limit that would materialize the library", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=one&Limit=999999", nil).
@@ -454,7 +454,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("treats an all-whitespace SearchTerm as no search, streaming the unfiltered list", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&SearchTerm=%20%20", nil).
@@ -472,8 +472,8 @@ var _ = Describe("Items", func() {
 			for i := range songs {
 				songs[i] = model.MediaFile{ID: testID(fmt.Sprintf("s%05d", i)), Title: "Song"}
 			}
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(songs)
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&Limit=10", nil).
 				WithContext(ctxUser())
@@ -486,9 +486,9 @@ var _ = Describe("Items", func() {
 		})
 
 		It("bounds the multi-type search window however large StartIndex is", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&StartIndex=500000&Limit=1", nil).
 				WithContext(ctxUser())
@@ -505,8 +505,8 @@ var _ = Describe("Items", func() {
 			for i := range songs {
 				songs[i] = model.MediaFile{ID: testID(fmt.Sprintf("s%05d", i)), Title: "Song"}
 			}
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(songs)
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET",
 				fmt.Sprintf("/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&StartIndex=%d&Limit=1", maxSearchLimit),
@@ -526,8 +526,8 @@ var _ = Describe("Items", func() {
 			}
 			// The mock repo returns rows sorted by ID; reorder to match so index-based assertions hold.
 			slices.SortFunc(songs, func(a, b model.MediaFile) int { return strings.Compare(a.ID, b.ID) })
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(songs)
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET",
 				fmt.Sprintf("/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&StartIndex=%d&Limit=10", maxSearchLimit-1),
@@ -546,8 +546,8 @@ var _ = Describe("Items", func() {
 			for i := range songs {
 				songs[i] = model.MediaFile{ID: testID(fmt.Sprintf("s%05d", i)), Title: "Song"}
 			}
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(songs)
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song", nil).
 				WithContext(ctxUser())
@@ -565,8 +565,8 @@ var _ = Describe("Items", func() {
 			}
 			// The mock repo returns rows sorted by ID; reorder to match so index-based assertions hold.
 			slices.SortFunc(songs, func(a, b model.MediaFile) int { return strings.Compare(a.ID, b.ID) })
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(songs)
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET",
 				fmt.Sprintf("/Items?IncludeItemTypes=Audio,MusicAlbum&SearchTerm=song&StartIndex=%d", defaultSearchLimit+50),
@@ -581,7 +581,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("reports a search total beyond the fetched page instead of the page length", func() {
-			ds.Artist(context.Background()).(*tests.MockArtistRepo).SetData(model.Artists{
+			ds.Artist().(*tests.MockArtistRepo).SetData(model.Artists{
 				{ID: testID("r1"), Name: "Alpha"}, {ID: testID("r2"), Name: "Beta"}, {ID: testID("r3"), Name: "Gamma"},
 			})
 			w := httptest.NewRecorder()
@@ -595,7 +595,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("forwards StartIndex/Limit as Offset/Max", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&StartIndex=5&Limit=10", nil).WithContext(ctxUser())
@@ -609,7 +609,7 @@ var _ = Describe("Items", func() {
 			// Finamp's download/sync fetches a track's BaseItemDto via /Items?ids=<id>; without
 			// this, queryItems ignored Ids and returned the default type-dispatched list instead.
 			It("returns exactly the requested item when Ids has a single id", func() {
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?Ids="+dto.EncodeID(testID("s1")), nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -623,8 +623,8 @@ var _ = Describe("Items", func() {
 			})
 
 			It("returns items of different types for a lowercase ids param with multiple ids", func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
+				ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?ids="+dto.EncodeID(testID("a1"))+","+dto.EncodeID(testID("s1")), nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -640,7 +640,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("resolves song ids with one batched IN query, not a Get per id", func() {
-				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+				mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 1}, {ID: testID("s2"), Title: "Song2", LibraryID: 1}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?ids="+dto.EncodeID(testID("s1"))+","+dto.EncodeID(testID("s2")), nil).WithContext(ctxUser())
@@ -656,8 +656,8 @@ var _ = Describe("Items", func() {
 			})
 
 			It("omits an id in a library the user can't access, without erroring the whole batch", func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 2}}) // alice only has access to library 1
+				ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 2}}) // alice only has access to library 1
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?Ids="+dto.EncodeID(testID("a1"))+","+dto.EncodeID(testID("s1")), nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -673,9 +673,9 @@ var _ = Describe("Items", func() {
 		Describe("sorting", func() {
 			DescribeTable("translates SortBy into the repo's sort keys",
 				func(itemType, sortBy, want string) {
-					albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+					albumRepo := ds.Album().(*tests.MockAlbumRepo)
 					albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
-					mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+					mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 					mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 					w := httptest.NewRecorder()
 					r := httptest.NewRequest("GET", "/Items?IncludeItemTypes="+itemType+"&SortBy="+sortBy, nil).WithContext(ctxUser())
@@ -710,7 +710,7 @@ var _ = Describe("Items", func() {
 			// we honor the first value for all keys, matching Jellyfin's fallback for extra keys.
 			DescribeTable("reads the first SortOrder value for the whole sort",
 				func(sortOrder, want string) {
-					albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+					albumRepo := ds.Album().(*tests.MockAlbumRepo)
 					albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 					w := httptest.NewRecorder()
 					r := httptest.NewRequest("GET",
@@ -728,7 +728,7 @@ var _ = Describe("Items", func() {
 
 		Describe("library scoping", func() {
 			It("scopes a MusicAlbum listing (no ParentId) to the user's accessible libraries", func() {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+				albumRepo := ds.Album().(*tests.MockAlbumRepo)
 				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}, {ID: 2}}
@@ -742,7 +742,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("scopes a Audio listing (no ParentId) to the user's accessible libraries", func() {
-				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+				mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}, {ID: 2}}
@@ -756,7 +756,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("scopes a MusicArtist listing to the user's accessible libraries", func() {
-				artistRepo := ds.Artist(context.Background()).(*tests.MockArtistRepo)
+				artistRepo := ds.Artist().(*tests.MockArtistRepo)
 				artistRepo.SetData(model.Artists{{ID: testID("ar1"), Name: "Artist"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}, {ID: 2}}
@@ -770,7 +770,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("treats a numeric ParentId matching an accessible library as a library scope, not an artist id", func() {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+				albumRepo := ds.Album().(*tests.MockAlbumRepo)
 				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}, {ID: 2}}
@@ -785,7 +785,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("does not let ParentId=<inaccessible library id> scope results to that library", func() {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+				albumRepo := ds.Album().(*tests.MockAlbumRepo)
 				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				libs := model.Libraries{{ID: 1}} // no access to library 99
@@ -803,7 +803,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("does not restrict a default MusicAlbum listing for an admin user", func() {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+				albumRepo := ds.Album().(*tests.MockAlbumRepo)
 				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}, {ID: testID("a2"), Name: "Two", LibraryID: 2}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum", nil).WithContext(ctxAdmin())
@@ -824,7 +824,7 @@ var _ = Describe("Items", func() {
 		// still reach the entity filter, not the unfiltered default.
 		Describe("stale and malformed id filtering", func() {
 			It("404s a malformed ParentId instead of listing every song", func() {
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&ParentId=not-a-valid-id", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -832,7 +832,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("404s a malformed AlbumArtistIds instead of listing every album", func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
+				ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&AlbumArtistIds=not-a-valid-id", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -840,7 +840,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("404s a malformed ArtistIds instead of listing every song", func() {
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&ArtistIds=not-a-valid-id", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -848,7 +848,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("still applies the artist filter (rather than dropping it) for a well-formed but unknown AlbumArtistIds", func() {
-				albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+				albumRepo := ds.Album().(*tests.MockAlbumRepo)
 				albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=MusicAlbum&AlbumArtistIds="+dto.EncodeID(testID("no-such-artist")), nil).WithContext(ctxUser())
@@ -860,7 +860,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("still applies the album filter (rather than dropping it) for a well-formed but unknown ParentId", func() {
-				mfRepo := ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo)
+				mfRepo := ds.MediaFile().(*tests.MockMediaFileRepo)
 				mfRepo.SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song"}})
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio&ParentId="+dto.EncodeID(testID("no-such-album")), nil).WithContext(ctxUser())
@@ -875,8 +875,8 @@ var _ = Describe("Items", func() {
 
 		Describe("mixed IncludeItemTypes merge", func() {
 			BeforeEach(func() {
-				ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "S1"}, {ID: testID("s2"), Title: "S2"}})
+				ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One"}, {ID: testID("a2"), Name: "Two"}})
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "S1"}, {ID: testID("s2"), Title: "S2"}})
 			})
 
 			It("returns a mix of both types, not all of one", func() {
@@ -927,7 +927,7 @@ var _ = Describe("Items", func() {
 			})
 
 			It("propagates a per-type query error", func() {
-				ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetError(true)
+				ds.MediaFile().(*tests.MockMediaFileRepo).SetError(true)
 				w := httptest.NewRecorder()
 				r := httptest.NewRequest("GET", "/Items?IncludeItemTypes=Audio,MusicAlbum&Recursive=true&Limit=4", nil).WithContext(ctxUser())
 				invoke(api.getItems, w, r)
@@ -938,7 +938,7 @@ var _ = Describe("Items", func() {
 
 	Describe("getItem", func() {
 		It("returns an album by id", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser())
 			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
@@ -959,7 +959,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("returns 404 for an album in a library the user can't access", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxUser()) // only has access to library 1
 			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
@@ -968,7 +968,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("returns 404 for a song in a library the user can't access", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 2}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1"), Title: "Song", LibraryID: 2}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("s1")), nil).WithContext(ctxUser()) // only has access to library 1
 			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("s1")))
@@ -977,7 +977,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("returns an album to an admin even when it's outside their (empty) Libraries", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 2}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("a1")), nil).WithContext(ctxAdmin()) // admin, Libraries: nil
 			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("a1")))
@@ -993,7 +993,7 @@ var _ = Describe("Items", func() {
 		It("resolves a library-view id (from /UserViews) as a CollectionFolder item", func() {
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1, Name: "Music Library"}}
-			ds.Library(context.Background()).(*tests.MockLibraryRepo).SetData(libs)
+			ds.Library().(*tests.MockLibraryRepo).SetData(libs)
 			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeLibraryID(1), nil).WithContext(ctxUserWithLibraries(libs))
 			r = withChiURLParam(r, "itemId", dto.EncodeLibraryID(1))
 			invoke(api.getItem, w, r)
@@ -1043,7 +1043,7 @@ var _ = Describe("Items", func() {
 
 		// Finamp's genre "See all" fetches the genre by id; a 404 white-screens it (see resolveItemByID).
 		It("resolves a genre id as a MusicGenre item", func() {
-			Expect(ds.Genre(context.Background()).(*tests.MockedGenreRepo).Put(&model.Genre{ID: testID("g1"), Name: "Rock"})).To(Succeed())
+			Expect(ds.Genre().(*tests.MockedGenreRepo).Put(&model.Genre{ID: testID("g1"), Name: "Rock"})).To(Succeed())
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeID(testID("g1")), nil).WithContext(ctxUser())
 			r = withChiURLParam(r, "itemId", dto.EncodeID(testID("g1")))
@@ -1057,7 +1057,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("resolves a library-view id for an admin even though their Libraries slice is empty", func() {
-			ds.Library(context.Background()).(*tests.MockLibraryRepo).SetData(model.Libraries{{ID: 1, Name: "Music Library"}})
+			ds.Library().(*tests.MockLibraryRepo).SetData(model.Libraries{{ID: 1, Name: "Music Library"}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Items/"+dto.EncodeLibraryID(1), nil).WithContext(ctxAdmin())
 			r = withChiURLParam(r, "itemId", dto.EncodeLibraryID(1))
@@ -1073,7 +1073,7 @@ var _ = Describe("Items", func() {
 
 	Describe("getLatest", func() {
 		It("returns a bare array of the newest albums", func() {
-			ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			r := httptest.NewRequest("GET", "/Users/u1/Items/Latest", nil).WithContext(ctxUser())
 			invoke(api.getLatest, w, r)
@@ -1085,7 +1085,7 @@ var _ = Describe("Items", func() {
 		})
 
 		It("scopes to the user's accessible libraries", func() {
-			albumRepo := ds.Album(context.Background()).(*tests.MockAlbumRepo)
+			albumRepo := ds.Album().(*tests.MockAlbumRepo)
 			albumRepo.SetData(model.Albums{{ID: testID("a1"), Name: "One", LibraryID: 1}})
 			w := httptest.NewRecorder()
 			libs := model.Libraries{{ID: 1}, {ID: 2}}
diff --git a/server/jellyfin/lyrics_test.go b/server/jellyfin/lyrics_test.go
index 2cf53a280..fb00563de 100644
--- a/server/jellyfin/lyrics_test.go
+++ b/server/jellyfin/lyrics_test.go
@@ -52,7 +52,7 @@ var _ = Describe("getLyrics", func() {
 
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
-		ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+		ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 			{ID: testID("s1"), Title: "Song", LibraryID: 1},
 			{ID: testID("s2"), Title: "Silent Song", LibraryID: 1},
 		})
diff --git a/server/jellyfin/middlewares.go b/server/jellyfin/middlewares.go
index 0ae4f6071..4788c84be 100644
--- a/server/jellyfin/middlewares.go
+++ b/server/jellyfin/middlewares.go
@@ -162,7 +162,7 @@ func (api *Router) userFromToken(r *http.Request) (model.User, bool) {
 	if err != nil || claims.Subject == "" {
 		return model.User{}, false
 	}
-	usr, err := api.ds.User(r.Context()).FindByUsername(claims.Subject)
+	usr, err := api.ds.User().FindByUsername(r.Context(), claims.Subject)
 	if err != nil {
 		log.Warn(r.Context(), "Jellyfin API: token subject not found", "user", claims.Subject, err)
 		return model.User{}, false
diff --git a/server/jellyfin/middlewares_test.go b/server/jellyfin/middlewares_test.go
index a3b88799b..2ab9f35eb 100644
--- a/server/jellyfin/middlewares_test.go
+++ b/server/jellyfin/middlewares_test.go
@@ -18,13 +18,15 @@ import (
 )
 
 var _ = Describe("authenticate middleware", func() {
+	var ctx context.Context
 	var api *Router
 	var ds *tests.MockDataStore
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-		Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
+		ur := ds.User().(*tests.MockedUserRepo)
+		Expect(ur.Put(ctx, &model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
 		api = &Router{ds: ds}
 	})
 
@@ -100,9 +102,9 @@ var _ = Describe("authenticate middleware", func() {
 		var usr *model.User
 
 		BeforeEach(func() {
-			ur := ds.User(context.Background()).(*tests.MockedUserRepo)
+			ur := ds.User().(*tests.MockedUserRepo)
 			usr = &model.User{ID: testID("u2"), UserName: "bob", NewPassword: "secret", TokenEpoch: 3}
-			Expect(ur.Put(usr)).To(Succeed())
+			Expect(ur.Put(ctx, usr)).To(Succeed())
 		})
 
 		serve := func(token string) *httptest.ResponseRecorder {
diff --git a/server/jellyfin/playlists.go b/server/jellyfin/playlists.go
index 5fd2df8c9..5569f4f83 100644
--- a/server/jellyfin/playlists.go
+++ b/server/jellyfin/playlists.go
@@ -146,14 +146,14 @@ func (api *Router) clearPlaylist(ctx context.Context, id string) error {
 // playlistTrackPage streams one page of a playlist's tracks. Streams because a playlist can be the
 // whole library (a smart playlist matching everything) and clients may omit Limit. Excludes missing
 // tracks, and counts the same set, like GetWithTracks.
-func (api *Router) playlistTrackPage(repo model.PlaylistTrackRepository, fields dto.Fields, offset, limit int) (itemsResult, error) {
-	total, err := repo.CountAll(model.QueryOptions{Filters: notMissing})
+func (api *Router) playlistTrackPage(ctx context.Context, repo model.PlaylistTrackRepository, fields dto.Fields, offset, limit int) (itemsResult, error) {
+	total, err := repo.CountAll(ctx, model.QueryOptions{Filters: notMissing})
 	if err != nil {
 		return itemsResult{}, err
 	}
 	opts := model.QueryOptions{Sort: "id", Offset: offset, Max: limit, Filters: notMissing}
 	open := streamCursor(func() (func(func(model.PlaylistTrack, error) bool), error) {
-		return repo.GetCursor(opts)
+		return repo.GetCursor(ctx, opts)
 	}, func(t model.PlaylistTrack) dto.BaseItemDto { return trackToBaseItem(t, fields) })
 	return streamed(open, int(total), offset), nil
 }
@@ -188,7 +188,7 @@ func (api *Router) getPlaylist(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	// PlaylistInfo carries every track id, so this can't be paged — but it needs no track data.
-	trackIDs, err := repo.GetMediaFileIDs(model.QueryOptions{Sort: "id", Filters: notMissing})
+	trackIDs, err := repo.GetMediaFileIDs(ctx, model.QueryOptions{Sort: "id", Filters: notMissing})
 	if err != nil {
 		api.internalError(w, r, err)
 		return
@@ -216,7 +216,7 @@ func (api *Router) getPlaylistItems(w http.ResponseWriter, r *http.Request) {
 	}
 	p := req.Params(r)
 	fields := dto.ParseFields(p.Strings("fields")...)
-	res, err := api.playlistTrackPage(repo, fields, p.IntOr("startindex", 0), p.IntOr("limit", 0))
+	res, err := api.playlistTrackPage(ctx, repo, fields, p.IntOr("startindex", 0), p.IntOr("limit", 0))
 	if err != nil {
 		api.internalError(w, r, err)
 		return
@@ -249,9 +249,9 @@ func (api *Router) expandContainerIDs(ctx context.Context, ids []string) []strin
 	for _, id := range ids {
 		if _, ok := songs[id]; ok {
 			out = append(out, id) // already a song
-		} else if _, err := api.ds.Album(ctx).Get(id); err == nil {
+		} else if _, err := api.ds.Album().Get(ctx, id); err == nil {
 			out = append(out, api.songIDs(ctx, filter.SongsByAlbum(id))...)
-		} else if _, err := api.ds.Artist(ctx).Get(id); err == nil {
+		} else if _, err := api.ds.Artist().Get(ctx, id); err == nil {
 			out = append(out, api.songIDs(ctx, filter.SongsByArtistID(id))...)
 		} else if pl, err := api.playlists.GetWithTracks(ctx, id); err == nil {
 			out = append(out, slice.Map(pl.Tracks, func(t model.PlaylistTrack) string { return t.MediaFileID })...)
@@ -263,7 +263,7 @@ func (api *Router) expandContainerIDs(ctx context.Context, ids []string) []strin
 }
 
 func (api *Router) songIDs(ctx context.Context, opts model.QueryOptions) []string {
-	mfs, err := api.ds.MediaFile(ctx).GetAll(opts)
+	mfs, err := api.ds.MediaFile().GetAll(ctx, opts)
 	if err != nil {
 		log.Error(ctx, "Jellyfin: error expanding container to tracks", err)
 		return nil
diff --git a/server/jellyfin/playlists_test.go b/server/jellyfin/playlists_test.go
index edaa63dd1..d38ef3b44 100644
--- a/server/jellyfin/playlists_test.go
+++ b/server/jellyfin/playlists_test.go
@@ -299,27 +299,27 @@ var _ = Describe("Playlists", func() {
 		}
 
 		It("passes a bare song id through unchanged", func() {
-			ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1")}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1")}})
 			createWith(testID("s1"))
 			Expect(fp.createdIds).To(Equal([]string{testID("s1")}))
 		})
 
 		It("expands an album id into its songs, filtered by album", func() {
-			ds.Album(ctx).(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("al1")}})
-			ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{{ID: testID("al1")}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), AlbumID: testID("al1")}, {ID: testID("s2"), AlbumID: testID("al1")},
 			})
 			createWith(testID("al1"))
 			Expect(fp.createdIds).To(Equal([]string{testID("s1"), testID("s2")}))
-			Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Options.Filters).To(Equal(filter.SongsByAlbum(testID("al1")).Filters))
+			Expect(ds.MediaFile().(*tests.MockMediaFileRepo).Options.Filters).To(Equal(filter.SongsByAlbum(testID("al1")).Filters))
 		})
 
 		It("expands an artist id into its songs", func() {
-			ds.Artist(ctx).(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1")}})
-			ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1")}, {ID: testID("s2")}})
+			ds.Artist().(*tests.MockArtistRepo).SetData(model.Artists{{ID: testID("ar1")}})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{{ID: testID("s1")}, {ID: testID("s2")}})
 			createWith(testID("ar1"))
 			Expect(fp.createdIds).To(Equal([]string{testID("s1"), testID("s2")}))
-			Expect(ds.MediaFile(ctx).(*tests.MockMediaFileRepo).Options.Filters).To(Equal(filter.SongsByArtistID(testID("ar1")).Filters))
+			Expect(ds.MediaFile().(*tests.MockMediaFileRepo).Options.Filters).To(Equal(filter.SongsByArtistID(testID("ar1")).Filters))
 		})
 
 		It("expands a playlist id into its tracks' media file ids", func() {
diff --git a/server/jellyfin/quickconnect.go b/server/jellyfin/quickconnect.go
index c478b1894..f7fa1b979 100644
--- a/server/jellyfin/quickconnect.go
+++ b/server/jellyfin/quickconnect.go
@@ -77,7 +77,7 @@ func (api *Router) quickConnectAuthorize(w http.ResponseWriter, r *http.Request)
 			http.Error(w, "Forbidden", http.StatusForbidden)
 			return
 		}
-		usr, err := api.ds.User(ctx).Get(userID)
+		usr, err := api.ds.User().Get(ctx, userID)
 		if errors.Is(err, model.ErrNotFound) {
 			http.Error(w, "Unknown user", http.StatusNotFound)
 			return
@@ -118,7 +118,7 @@ func (api *Router) authenticateWithQuickConnect(w http.ResponseWriter, r *http.R
 		http.Error(w, "Unknown secret", http.StatusNotFound)
 		return
 	}
-	usr, err := api.ds.User(ctx).Get(userID)
+	usr, err := api.ds.User().Get(ctx, userID)
 	if errors.Is(err, model.ErrNotFound) {
 		log.Warn(ctx, "Jellyfin API: Quick Connect user not found", "userID", userID)
 		http.Error(w, "Unauthorized", http.StatusUnauthorized)
diff --git a/server/jellyfin/quickconnect_test.go b/server/jellyfin/quickconnect_test.go
index 0478a356a..94573e6ff 100644
--- a/server/jellyfin/quickconnect_test.go
+++ b/server/jellyfin/quickconnect_test.go
@@ -1,7 +1,6 @@
 package jellyfin
 
 import (
-	"context"
 	"encoding/json"
 	"errors"
 	"net/http"
@@ -42,9 +41,9 @@ var _ = Describe("QuickConnect", func() {
 		conf.Server.Jellyfin.QuickConnect = true
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		ur := ds.User(context.Background()).(*tests.MockedUserRepo)
+		ur := ds.User().(*tests.MockedUserRepo)
 		for _, u := range []model.User{alice, bob, admin} {
-			Expect(ur.Put(&u)).To(Succeed())
+			Expect(ur.Put(GinkgoT().Context(), &u)).To(Succeed())
 		}
 		qc = quickconnect.New()
 		api = &Router{ds: ds, quickConnect: qc}
@@ -294,7 +293,7 @@ var _ = Describe("QuickConnect", func() {
 		It("returns 500 when the user lookup fails", func() {
 			req := initiate()
 			_, _ = qc.Authorize(req.Code, alice.ID)
-			ds.User(context.Background()).(*tests.MockedUserRepo).Error = errors.New("db down")
+			ds.User().(*tests.MockedUserRepo).Error = errors.New("db down")
 			Expect(redeemSecret(req.Secret).Code).To(Equal(http.StatusInternalServerError))
 		})
 	})
diff --git a/server/jellyfin/similar.go b/server/jellyfin/similar.go
index 1bd887f43..50503160c 100644
--- a/server/jellyfin/similar.go
+++ b/server/jellyfin/similar.go
@@ -216,7 +216,7 @@ func (api *Router) similarAlbums(ctx context.Context, id string, limit int) dto.
 			continue
 		}
 		seen[s.AlbumID] = true
-		if al, err := api.ds.Album(ctx).Get(s.AlbumID); err == nil && u.HasLibraryAccess(al.LibraryID) {
+		if al, err := api.ds.Album().Get(ctx, s.AlbumID); err == nil && u.HasLibraryAccess(al.LibraryID) {
 			items = append(items, dto.AlbumToBaseItem(*al, nil))
 			if len(items) >= limit {
 				break
diff --git a/server/jellyfin/similar_test.go b/server/jellyfin/similar_test.go
index cffcce0a8..42d04a632 100644
--- a/server/jellyfin/similar_test.go
+++ b/server/jellyfin/similar_test.go
@@ -122,7 +122,7 @@ var _ = Describe("getInstantMix", func() {
 		DeferCleanup(func() { similarWait = old })
 
 		ds := &tests.MockDataStore{}
-		ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+		ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 			{ID: testID("s1"), Title: "Seed Song", LibraryID: 1},
 		})
 		release := make(chan struct{})
@@ -150,7 +150,7 @@ var _ = Describe("getInstantMix", func() {
 			songs = append(songs, model.MediaFile{ID: testID(fmt.Sprintf("t%d", i)), Title: fmt.Sprintf("Track %d", i), LibraryID: 1})
 		}
 		ds := &tests.MockDataStore{}
-		ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(songs)
+		ds.MediaFile().(*tests.MockMediaFileRepo).SetData(songs)
 		api := &Router{ds: ds, provider: &fakeSimilarProvider{songs: songs[1:]}}
 
 		w := httptest.NewRecorder()
@@ -191,7 +191,7 @@ var _ = Describe("getSimilarAlbums", func() {
 		// With no external agent the provider falls back to the album's own tracks, which map
 		// straight back to the requested album.
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{
 			{ID: testID("al-1"), Name: "Seed Album", LibraryID: 1},
 		})
 		api := &Router{ds: ds, provider: &fakeSimilarProvider{
@@ -212,7 +212,7 @@ var _ = Describe("getSimilarAlbums", func() {
 
 	It("returns albums derived from the provider's similar songs", func() {
 		ds := &tests.MockDataStore{}
-		ds.Album(context.Background()).(*tests.MockAlbumRepo).SetData(model.Albums{
+		ds.Album().(*tests.MockAlbumRepo).SetData(model.Albums{
 			{ID: testID("al-2"), Name: "Other", LibraryID: 1},
 		})
 		api := &Router{ds: ds, provider: &fakeSimilarProvider{
diff --git a/server/jellyfin/socket_test.go b/server/jellyfin/socket_test.go
index b4be0e244..79098aafd 100644
--- a/server/jellyfin/socket_test.go
+++ b/server/jellyfin/socket_test.go
@@ -1,7 +1,6 @@
 package jellyfin
 
 import (
-	"context"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -87,8 +86,8 @@ var _ = Describe("handleSocket", func() {
 		BeforeEach(func() {
 			ds = &tests.MockDataStore{}
 			auth.Init(ds)
-			ur := ds.User(context.Background()).(*tests.MockedUserRepo)
-			Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
+			ur := ds.User().(*tests.MockedUserRepo)
+			Expect(ur.Put(GinkgoT().Context(), &model.User{ID: testID("u1"), UserName: "alice", NewPassword: "secret"})).To(Succeed())
 
 			t, err := auth.CreateToken(&model.User{ID: testID("u1"), UserName: "alice"})
 			Expect(err).ToNot(HaveOccurred())
diff --git a/server/jellyfin/stream.go b/server/jellyfin/stream.go
index b9809bd29..515a6fcb8 100644
--- a/server/jellyfin/stream.go
+++ b/server/jellyfin/stream.go
@@ -29,7 +29,7 @@ func (api *Router) mediaFileForRequest(w http.ResponseWriter, r *http.Request) (
 	if !ok {
 		return nil, false
 	}
-	mf, err := api.ds.MediaFile(ctx).Get(id)
+	mf, err := api.ds.MediaFile().Get(ctx, id)
 	if err != nil {
 		http.Error(w, "Not Found", http.StatusNotFound)
 		return nil, false
diff --git a/server/jellyfin/stream_test.go b/server/jellyfin/stream_test.go
index 1a6d1badc..7a1112f37 100644
--- a/server/jellyfin/stream_test.go
+++ b/server/jellyfin/stream_test.go
@@ -42,7 +42,7 @@ var _ = Describe("Stream", func() {
 
 	Describe("getPlaybackInfo", func() {
 		It("returns a media source for an accessible track", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", Duration: 100, Size: 1000, LibraryID: 1},
 			})
 			w := httptest.NewRecorder()
@@ -61,7 +61,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("returns 404 for a track in a library the user can't access", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 2},
 			})
 			w := httptest.NewRecorder()
@@ -102,7 +102,7 @@ var _ = Describe("Stream", func() {
 		}
 
 		It("advertises a Lyric stream for plugin/sidecar-sourced lyrics not embedded in the file", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			api.lyrics = &fakeLyricsService{lyrics: map[string]model.LyricList{
@@ -113,7 +113,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("advertises no Lyric stream when the pipeline finds nothing", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 
@@ -121,7 +121,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("advertises no Lyric stream when the lyrics endpoint would 404 (main lyric has no lines)", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			api.lyrics = &fakeLyricsService{lyrics: map[string]model.LyricList{
@@ -132,7 +132,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("doesn't duplicate the Lyric stream when lyrics are already embedded", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1, Lyrics: `[{"lang":"xxx","line":[]}]`},
 			})
 			api.lyrics = &fakeLyricsService{lyrics: map[string]model.LyricList{
@@ -145,7 +145,7 @@ var _ = Describe("Stream", func() {
 		It("still returns 200 with a valid MediaSource and no Lyric stream when the lyrics pipeline errors", func() {
 			// Own ID: an erroring loader isn't cached, but a shared ID could still pick up
 			// another test's cached (non-error) result and mask this assertion.
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s-err"), Title: "Song", Suffix: "mp3", Duration: 100, Size: 1000, LibraryID: 1},
 			})
 			api.lyrics = &fakeLyricsService{err: errors.New("boom")}
@@ -166,7 +166,7 @@ var _ = Describe("Stream", func() {
 
 	Describe("streamAudio", func() {
 		It("invokes the transcode decider and streamer for an accessible track", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			streamer.content = "audio-bytes"
@@ -182,7 +182,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("returns 404 for a track in a library the user can't access, without invoking the streamer or decider", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 2},
 			})
 			w := httptest.NewRecorder()
@@ -207,7 +207,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("converts the bps audioBitRate param to kbps", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "flac", LibraryID: 1},
 			})
 			w := httptest.NewRecorder()
@@ -219,7 +219,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("uses the audioCodec param as target format when no container is given", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "flac", LibraryID: 1},
 			})
 			w := httptest.NewRecorder()
@@ -231,7 +231,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("returns 500 and logs when the streamer fails", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			streamer.err = errors.New("boom")
@@ -246,7 +246,7 @@ var _ = Describe("Stream", func() {
 
 	Describe("HEAD requests", func() {
 		head := func(query string) *httptest.ResponseRecorder {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "flac", LibraryID: 1},
 			})
 			streamer.content = "audio-bytes"
@@ -276,7 +276,7 @@ var _ = Describe("Stream", func() {
 
 	Describe("streamUniversal", func() {
 		universal := func(query string) {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Suffix: "mp3", LibraryID: 1},
 			})
 			w := httptest.NewRecorder()
@@ -315,7 +315,7 @@ var _ = Describe("Stream", func() {
 
 	Describe("streamHls", func() {
 		BeforeEach(func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "dsf", Duration: 100.5, LibraryID: 1},
 			})
 		})
@@ -370,21 +370,21 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("returns 404 for a track in a library the user can't access", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "dsf", LibraryID: 2},
 			})
 			Expect(hls("", ctxUser()).Code).To(Equal(http.StatusNotFound))
 		})
 
 		It("returns 404 when the id doesn't match any media file", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{})
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{})
 			Expect(hls("", ctxUser()).Code).To(Equal(http.StatusNotFound))
 		})
 	})
 
 	Describe("streamFile", func() {
 		It("invokes the decider with a raw/direct-play request and the streamer for an accessible track", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 1},
 			})
 			streamer.content = "audio-bytes"
@@ -401,7 +401,7 @@ var _ = Describe("Stream", func() {
 		})
 
 		It("returns 404 for a track in a library the user can't access, without invoking the streamer or decider", func() {
-			ds.MediaFile(context.Background()).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
+			ds.MediaFile().(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
 				{ID: testID("s1"), Title: "Song", Suffix: "mp3", LibraryID: 2},
 			})
 			w := httptest.NewRecorder()
diff --git a/server/jellyfin/system.go b/server/jellyfin/system.go
index 49e41470c..2aae4c9c0 100644
--- a/server/jellyfin/system.go
+++ b/server/jellyfin/system.go
@@ -51,11 +51,11 @@ func resolveServerID(ctx context.Context, ds model.DataStore, cached *string) st
 		*cached = newServerID()
 		return *cached
 	}
-	id, err := ds.Property(ctx).Get(consts.JellyfinServerIDKey)
+	id, err := ds.Property().Get(ctx, consts.JellyfinServerIDKey)
 	switch {
 	case errors.Is(err, model.ErrNotFound):
 		id = newServerID()
-		if err := ds.Property(ctx).Put(consts.JellyfinServerIDKey, id); err != nil {
+		if err := ds.Property().Put(ctx, consts.JellyfinServerIDKey, id); err != nil {
 			log.Error(ctx, "Jellyfin API: could not persist server id", err)
 			return id
 		}
diff --git a/server/jellyfin/system_test.go b/server/jellyfin/system_test.go
index 2350a7342..d339043a7 100644
--- a/server/jellyfin/system_test.go
+++ b/server/jellyfin/system_test.go
@@ -182,10 +182,10 @@ var _ = Describe("System", func() {
 		})
 
 		It("does not overwrite or pin over a stored id when the property read fails transiently", func() {
-			Expect(ds.Property(ctx).Put(consts.JellyfinServerIDKey, "6ba7b8109dad11d180b400c04fd430c8")).To(Succeed())
+			Expect(ds.Property().Put(ctx, consts.JellyfinServerIDKey, "6ba7b8109dad11d180b400c04fd430c8")).To(Succeed())
 
 			r := &Router{ds: ds}
-			props := ds.Property(ctx).(*tests.MockedPropertyRepo)
+			props := ds.Property().(*tests.MockedPropertyRepo)
 			props.Error = errors.New("database is locked")
 			degraded := r.serverID(ctx)
 			Expect(degraded).ToNot(BeEmpty())
@@ -194,7 +194,7 @@ var _ = Describe("System", func() {
 
 			// Once the DB recovers, the stored id is intact and served again.
 			Expect(r.serverID(ctx)).To(Equal("6ba7b8109dad11d180b400c04fd430c8"))
-			stored, err := ds.Property(ctx).Get(consts.JellyfinServerIDKey)
+			stored, err := ds.Property().Get(ctx, consts.JellyfinServerIDKey)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(stored).To(Equal("6ba7b8109dad11d180b400c04fd430c8"))
 		})
@@ -205,7 +205,7 @@ var _ = Describe("System", func() {
 		})
 
 		It("strips dashes from an already-persisted id", func() {
-			Expect(ds.Property(ctx).Put(
+			Expect(ds.Property().Put(ctx,
 				consts.JellyfinServerIDKey, "1b4e28ba-2fa1-11d2-883f-0016d3cca427")).To(Succeed())
 			r := &Router{ds: ds}
 			Expect(r.serverID(ctx)).To(Equal("1b4e28ba2fa111d2883f0016d3cca427"))
diff --git a/server/jellyfin/users.go b/server/jellyfin/users.go
index dddcd99da..d0a54ee63 100644
--- a/server/jellyfin/users.go
+++ b/server/jellyfin/users.go
@@ -17,7 +17,7 @@ func (api *Router) getUserViews(w http.ResponseWriter, r *http.Request) {
 	u, _ := request.UserFrom(ctx)
 	// u.Libraries comes from a projection without counts or stats, and clients hide a library that
 	// looks empty, so the rows are re-read in full here.
-	libs, err := api.ds.Library(ctx).GetAll()
+	libs, err := api.ds.Library().GetAll(ctx)
 	if err != nil {
 		api.internalError(w, r, err)
 		return
@@ -55,7 +55,7 @@ func (api *Router) getPublicUsers(w http.ResponseWriter, r *http.Request) {
 			continue
 		}
 		seen[key] = true
-		usr, err := api.ds.User(ctx).FindByUsername(name)
+		usr, err := api.ds.User().FindByUsername(ctx, name)
 		if err != nil {
 			log.Warn(ctx, "Jellyfin API: configured public user not found", "username", name, err)
 			continue
diff --git a/server/jellyfin/users_test.go b/server/jellyfin/users_test.go
index c6bb99f71..793a64a29 100644
--- a/server/jellyfin/users_test.go
+++ b/server/jellyfin/users_test.go
@@ -18,10 +18,11 @@ import (
 )
 
 var _ = Describe("Users", func() {
+	var ctx context.Context
 	var api *Router
 	// The repo holds the full rows; the user carries the id/name-only copy its projection returns.
 	authedWithLibraries := func(r *http.Request, libs model.Libraries) *http.Request {
-		api.ds.Library(context.Background()).(*tests.MockLibraryRepo).SetData(libs)
+		api.ds.Library().(*tests.MockLibraryRepo).SetData(libs)
 		stripped := make(model.Libraries, len(libs))
 		for i, lib := range libs {
 			stripped[i] = model.Library{ID: lib.ID, Name: lib.Name}
@@ -29,7 +30,10 @@ var _ = Describe("Users", func() {
 		ctx := request.WithUser(context.Background(), model.User{ID: testID("u1"), UserName: "alice", Libraries: stripped})
 		return r.WithContext(ctx)
 	}
-	BeforeEach(func() { api = &Router{ds: &tests.MockDataStore{}} })
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+		api = &Router{ds: &tests.MockDataStore{}}
+	})
 
 	Describe("getUserViews", func() {
 		It("returns one view per accessible library", func() {
@@ -117,9 +121,9 @@ var _ = Describe("Users", func() {
 
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
-			ur = api.ds.User(context.Background()).(*tests.MockedUserRepo)
-			Expect(ur.Put(&model.User{ID: testID("u1"), UserName: "alice"})).To(Succeed())
-			Expect(ur.Put(&model.User{ID: testID("u2"), UserName: "bob"})).To(Succeed())
+			ur = api.ds.User().(*tests.MockedUserRepo)
+			Expect(ur.Put(ctx, &model.User{ID: testID("u1"), UserName: "alice"})).To(Succeed())
+			Expect(ur.Put(ctx, &model.User{ID: testID("u2"), UserName: "bob"})).To(Succeed())
 		})
 
 		It("returns an empty list when the config is unset", func() {
diff --git a/server/middlewares.go b/server/middlewares.go
index 674337e92..b65a2d6e1 100644
--- a/server/middlewares.go
+++ b/server/middlewares.go
@@ -380,7 +380,7 @@ func UpdateLastAccessMiddleware(ds model.DataStore) func(next http.Handler) http
 					ctx, cancel := context.WithTimeout(ctx, time.Second)
 					defer cancel()
 
-					err := ds.User(ctx).UpdateLastAccessAt(usr.ID)
+					err := ds.User().UpdateLastAccessAt(ctx, usr.ID)
 					if err != nil {
 						log.Warn(ctx, "Could not update user's lastAccessAt", "username", usr.UserName,
 							"elapsed", time.Since(start), err)
diff --git a/server/middlewares_test.go b/server/middlewares_test.go
index a9b0bc99e..15cf70341 100644
--- a/server/middlewares_test.go
+++ b/server/middlewares_test.go
@@ -381,7 +381,7 @@ var _ = Describe("middlewares", func() {
 			id = uuid.NewString()
 			ds = &tests.MockDataStore{}
 			lastAccessTime = time.Now()
-			Expect(ds.User(ctx).Put(&model.User{ID: id, UserName: "johndoe", LastAccessAt: &lastAccessTime})).
+			Expect(ds.User().Put(ctx, &model.User{ID: id, UserName: "johndoe", LastAccessAt: &lastAccessTime})).
 				To(Succeed())
 
 			middleware = UpdateLastAccessMiddleware(ds)
@@ -407,14 +407,14 @@ var _ = Describe("middlewares", func() {
 
 				callMiddleware(req)
 
-				user, _ := ds.MockedUser.FindByUsername("johndoe")
+				user, _ := ds.MockedUser.FindByUsername(ctx, "johndoe")
 				Expect(*user.LastAccessAt).To(BeTemporally(">", lastAccessTime, time.Second))
 			})
 
 			It("skip fast successive requests", func() {
 				// First request
 				callMiddleware(req)
-				user, _ := ds.MockedUser.FindByUsername("johndoe")
+				user, _ := ds.MockedUser.FindByUsername(ctx, "johndoe")
 				lastAccessTime = *user.LastAccessAt // Store the last access time
 
 				// Second request
@@ -422,7 +422,7 @@ var _ = Describe("middlewares", func() {
 				callMiddleware(req)
 
 				// The second request should not have changed the last access time
-				user, _ = ds.MockedUser.FindByUsername("johndoe")
+				user, _ = ds.MockedUser.FindByUsername(ctx, "johndoe")
 				Expect(user.LastAccessAt).To(Equal(&lastAccessTime))
 			})
 		})
@@ -431,7 +431,7 @@ var _ = Describe("middlewares", func() {
 				req = req.WithContext(context.Background())
 				callMiddleware(req)
 
-				usr, _ := ds.MockedUser.FindByUsername("johndoe")
+				usr, _ := ds.MockedUser.FindByUsername(ctx, "johndoe")
 				Expect(usr.LastAccessAt).To(Equal(&lastAccessTime))
 			})
 		})
diff --git a/server/nativeapi/artists.go b/server/nativeapi/artists.go
index 193f88eda..91508c825 100644
--- a/server/nativeapi/artists.go
+++ b/server/nativeapi/artists.go
@@ -15,14 +15,12 @@ import (
 )
 
 func (api *Router) addArtistRoute(r chi.Router) {
-	constructor := func(ctx context.Context) rest.Repository {
-		return api.ds.Resource(ctx, model.Artist{})
-	}
+	repo := api.ds.Artist()
 	r.Route("/artist", func(r chi.Router) {
-		r.Get("/", rest.GetAll(constructor))
+		r.Get("/", rest.GetAll(repo))
 		r.Route("/{id}", func(r chi.Router) {
 			r.Use(server.URLParamsMiddleware)
-			r.Get("/", rest.Get(constructor))
+			r.Get("/", rest.Get(repo))
 			r.Post("/image", api.uploadArtistImage())
 			r.Delete("/image", api.deleteArtistImage())
 		})
@@ -32,7 +30,7 @@ func (api *Router) addArtistRoute(r chi.Router) {
 func (api *Router) uploadArtistImage() http.HandlerFunc {
 	return handleImageUpload(func(ctx context.Context, reader io.Reader, ext string) error {
 		artistID := chi.URLParamFromCtx(ctx, "id")
-		ar, err := api.ds.Artist(ctx).Get(artistID)
+		ar, err := api.ds.Artist().Get(ctx, artistID)
 		if err != nil {
 			if errors.Is(err, model.ErrNotFound) {
 				return model.ErrNotFound
@@ -46,7 +44,7 @@ func (api *Router) uploadArtistImage() http.HandlerFunc {
 		}
 		ar.UploadedImage = filename
 		ar.UpdatedAt = new(time.Now())
-		if err := api.ds.Artist(ctx).Put(ar, "uploaded_image", "updated_at"); err != nil {
+		if err := api.ds.Artist().Put(ctx, ar, "uploaded_image", "updated_at"); err != nil {
 			return err
 		}
 		api.imgUpload.EnqueueArtwork(ctx, consts.EntityArtist, ar.ID)
@@ -57,7 +55,7 @@ func (api *Router) uploadArtistImage() http.HandlerFunc {
 func (api *Router) deleteArtistImage() http.HandlerFunc {
 	return handleImageDelete(func(ctx context.Context) error {
 		artistID := chi.URLParamFromCtx(ctx, "id")
-		ar, err := api.ds.Artist(ctx).Get(artistID)
+		ar, err := api.ds.Artist().Get(ctx, artistID)
 		if err != nil {
 			if errors.Is(err, model.ErrNotFound) {
 				return model.ErrNotFound
@@ -69,7 +67,7 @@ func (api *Router) deleteArtistImage() http.HandlerFunc {
 		}
 		ar.UploadedImage = ""
 		ar.UpdatedAt = new(time.Now())
-		if err := api.ds.Artist(ctx).Put(ar, "uploaded_image", "updated_at"); err != nil {
+		if err := api.ds.Artist().Put(ctx, ar, "uploaded_image", "updated_at"); err != nil {
 			return err
 		}
 		api.imgUpload.EnqueueArtwork(ctx, consts.EntityArtist, ar.ID)
diff --git a/server/nativeapi/config_test.go b/server/nativeapi/config_test.go
index 7c4f00fdd..6ac41f07a 100644
--- a/server/nativeapi/config_test.go
+++ b/server/nativeapi/config_test.go
@@ -11,6 +11,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server"
 	"github.com/navidrome/navidrome/tests"
@@ -19,17 +20,19 @@ import (
 )
 
 var _ = Describe("Config API", func() {
+	var ctx context.Context
 	var ds model.DataStore
 	var router http.Handler
 	var adminUser, regularUser model.User
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.EnableSharing = false
 		conf.Server.DevUIShowConfig = true // Enable config endpoint for tests
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, playlists.NewPlaylists(ds, nil), nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
@@ -49,8 +52,8 @@ var _ = Describe("Config API", func() {
 		}
 
 		// Store in mock datastore
-		Expect(ds.User(context.TODO()).Put(&adminUser)).To(Succeed())
-		Expect(ds.User(context.TODO()).Put(&regularUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &adminUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &regularUser)).To(Succeed())
 	})
 
 	Describe("GET /api/config", func() {
diff --git a/server/nativeapi/inspect.go b/server/nativeapi/inspect.go
index 7c96312ed..f1e6c4539 100644
--- a/server/nativeapi/inspect.go
+++ b/server/nativeapi/inspect.go
@@ -13,7 +13,7 @@ import (
 )
 
 func doInspect(ctx context.Context, ds model.DataStore, id string) (*core.InspectOutput, error) {
-	file, err := ds.MediaFile(ctx).Get(id)
+	file, err := ds.MediaFile().Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
diff --git a/server/nativeapi/library_test.go b/server/nativeapi/library_test.go
index cef2e06ad..cc05a30e5 100644
--- a/server/nativeapi/library_test.go
+++ b/server/nativeapi/library_test.go
@@ -13,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server"
 	"github.com/navidrome/navidrome/tests"
@@ -21,17 +22,19 @@ import (
 )
 
 var _ = Describe("Library API", func() {
+	var ctx context.Context
 	var ds model.DataStore
 	var router http.Handler
 	var adminUser, regularUser model.User
 	var library1, library2 model.Library
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.EnableSharing = false
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, playlists.NewPlaylists(ds, nil), nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
@@ -63,10 +66,10 @@ var _ = Describe("Library API", func() {
 		}
 
 		// Store in mock datastore
-		Expect(ds.User(context.TODO()).Put(&adminUser)).To(Succeed())
-		Expect(ds.User(context.TODO()).Put(&regularUser)).To(Succeed())
-		Expect(ds.Library(context.TODO()).Put(&library1)).To(Succeed())
-		Expect(ds.Library(context.TODO()).Put(&library2)).To(Succeed())
+		Expect(ds.User().Put(ctx, &adminUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &regularUser)).To(Succeed())
+		Expect(ds.Library().Put(ctx, &library1)).To(Succeed())
+		Expect(ds.Library().Put(ctx, &library2)).To(Succeed())
 	})
 
 	Describe("Library CRUD Operations", func() {
@@ -293,7 +296,7 @@ var _ = Describe("Library API", func() {
 			Describe("GET /api/user/{id}/library", func() {
 				It("returns user's libraries", func() {
 					// Set up user libraries
-					err := ds.User(context.TODO()).SetUserLibraries(regularUser.ID, []int{1, 2})
+					err := ds.User().SetUserLibraries(ctx, regularUser.ID, []int{1, 2})
 					Expect(err).ToNot(HaveOccurred())
 
 					req := createAuthenticatedRequest("GET", fmt.Sprintf("/user/%s/library", regularUser.ID), nil, adminToken)
diff --git a/server/nativeapi/metadata_test.go b/server/nativeapi/metadata_test.go
index ae6e301a8..294a26efe 100644
--- a/server/nativeapi/metadata_test.go
+++ b/server/nativeapi/metadata_test.go
@@ -11,6 +11,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/auth"
 	"github.com/navidrome/navidrome/core/external"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server"
 	"github.com/navidrome/navidrome/tests"
@@ -38,6 +39,7 @@ func (f *fakeProvider) calls() []string {
 }
 
 var _ = Describe("Metadata API", func() {
+	var ctx context.Context
 	var ds *tests.MockDataStore
 	var artRepo *tests.MockArtworkRepo
 	var queueRepo *tests.MockArtworkQueueRepo
@@ -47,6 +49,7 @@ var _ = Describe("Metadata API", func() {
 	var adminToken, userToken string
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.EnableSharing = false
 		artRepo = tests.CreateMockArtworkRepo()
@@ -54,9 +57,9 @@ var _ = Describe("Metadata API", func() {
 		albumRepo = tests.CreateMockAlbumRepo()
 		artistRepo := tests.CreateMockArtistRepo()
 		playlistRepo := tests.CreateMockPlaylistRepo()
-		Expect(albumRepo.Put(&model.Album{ID: "al-1", Name: "Kid A"})).To(Succeed())
-		Expect(artistRepo.Put(&model.Artist{ID: "ar-1", Name: "Radiohead"})).To(Succeed())
-		Expect(playlistRepo.Put(&model.Playlist{ID: "pl-1", Name: "My Playlist"})).To(Succeed())
+		Expect(albumRepo.Put(ctx, &model.Album{ID: "al-1", Name: "Kid A"})).To(Succeed())
+		Expect(artistRepo.Put(ctx, &model.Artist{ID: "ar-1", Name: "Radiohead"})).To(Succeed())
+		Expect(playlistRepo.Put(ctx, &model.Playlist{ID: "pl-1", Name: "My Playlist"})).To(Succeed())
 		ds = &tests.MockDataStore{
 			MockedArtwork:      artRepo,
 			MockedArtworkQueue: queueRepo,
@@ -66,13 +69,13 @@ var _ = Describe("Metadata API", func() {
 		}
 		auth.Init(ds)
 		provider = &fakeProvider{}
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, provider, nil)
+		nativeRouter := New(ds, nil, playlists.NewPlaylists(ds, nil), nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, provider, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		adminUser := model.User{ID: "admin-1", UserName: "admin", IsAdmin: true, NewPassword: "adminpass"}
 		regularUser := model.User{ID: "user-1", UserName: "regular", IsAdmin: false, NewPassword: "userpass"}
-		Expect(ds.User(context.TODO()).Put(&adminUser)).To(Succeed())
-		Expect(ds.User(context.TODO()).Put(&regularUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &adminUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &regularUser)).To(Succeed())
 
 		var err error
 		adminToken, err = auth.CreateToken(&adminUser)
@@ -83,7 +86,7 @@ var _ = Describe("Metadata API", func() {
 
 	Describe("POST /api/metadata/{kind}/{id}/refresh", func() {
 		It("clears state and enqueues a Bump for admins", func() {
-			Expect(artRepo.PutItemArtwork(&model.ItemArtwork{
+			Expect(artRepo.PutItemArtwork(ctx, &model.ItemArtwork{
 				ItemKind: "al", ItemID: "al-1", Hash: "oldhash", Source: "external",
 			})).To(Succeed())
 
@@ -93,10 +96,10 @@ var _ = Describe("Metadata API", func() {
 
 			Expect(w.Code).To(Equal(http.StatusNoContent))
 
-			_, err := artRepo.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
+			_, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)
 			Expect(err).To(MatchError(model.ErrNotFound))
 
-			queued, err := queueRepo.DequeueBatch(1000)
+			queued, err := queueRepo.DequeueBatch(ctx, 1000)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(queued).To(ContainElement(SatisfyAll(
 				HaveField("ItemKind", "al"),
diff --git a/server/nativeapi/missing.go b/server/nativeapi/missing.go
index de6595e00..a906e36b9 100644
--- a/server/nativeapi/missing.go
+++ b/server/nativeapi/missing.go
@@ -14,24 +14,21 @@ import (
 )
 
 type missingRepository struct {
-	model.ResourceRepository
+	rest.Repository[model.MediaFile]
 	mfRepo model.MediaFileRepository
 }
 
-func newMissingRepository(ds model.DataStore) rest.RepositoryConstructor {
-	return func(ctx context.Context) rest.Repository {
-		return &missingRepository{mfRepo: ds.MediaFile(ctx), ResourceRepository: ds.Resource(ctx, model.MediaFile{})}
-	}
+func newMissingRepository(ds model.DataStore) rest.Repository[model.MediaFile] {
+	mf := ds.MediaFile()
+	return &missingRepository{Repository: mf, mfRepo: mf}
 }
 
-func (r *missingRepository) Count(options ...rest.QueryOptions) (int64, error) {
-	opt := r.parseOptions(options)
-	return r.ResourceRepository.Count(opt)
+func (r *missingRepository) Count(ctx context.Context, options ...rest.QueryOptions) (int64, error) {
+	return r.Repository.Count(ctx, r.parseOptions(options))
 }
 
-func (r *missingRepository) ReadAll(options ...rest.QueryOptions) (any, error) {
-	opt := r.parseOptions(options)
-	return r.ResourceRepository.ReadAll(opt)
+func (r *missingRepository) ReadAll(ctx context.Context, options ...rest.QueryOptions) ([]model.MediaFile, error) {
+	return r.Repository.ReadAll(ctx, r.parseOptions(options))
 }
 
 func (r *missingRepository) parseOptions(options []rest.QueryOptions) rest.QueryOptions {
@@ -44,8 +41,8 @@ func (r *missingRepository) parseOptions(options []rest.QueryOptions) rest.Query
 	return opt
 }
 
-func (r *missingRepository) Read(id string) (any, error) {
-	mf, err := r.mfRepo.Get(id)
+func (r *missingRepository) Read(ctx context.Context, id string) (*model.MediaFile, error) {
+	mf, err := r.mfRepo.Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
@@ -55,10 +52,6 @@ func (r *missingRepository) Read(id string) (any, error) {
 	return mf, nil
 }
 
-func (r *missingRepository) EntityName() string {
-	return "missing_files"
-}
-
 func deleteMissingFiles(maintenance core.Maintenance) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		ctx := r.Context()
@@ -86,5 +79,3 @@ func deleteMissingFiles(maintenance core.Maintenance) http.HandlerFunc {
 		writeDeleteManyResponse(w, r, ids)
 	}
 }
-
-var _ model.ResourceRepository = &missingRepository{}
diff --git a/server/nativeapi/missing_test.go b/server/nativeapi/missing_test.go
index 9d7575a0c..a53f13fc3 100644
--- a/server/nativeapi/missing_test.go
+++ b/server/nativeapi/missing_test.go
@@ -9,6 +9,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server"
 	"github.com/navidrome/navidrome/tests"
@@ -35,12 +36,12 @@ var _ = Describe("Missing Files Endpoint", func() {
 		auth.Init(ds)
 
 		user := model.User{ID: "user-1", UserName: "user", NewPassword: "pass"}
-		Expect(userRepo.Put(&user)).To(Succeed())
+		Expect(userRepo.Put(GinkgoT().Context(), &user)).To(Succeed())
 		var err error
 		token, err = auth.CreateToken(&user)
 		Expect(err).ToNot(HaveOccurred())
 
-		router = server.JWTVerifier(New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil))
+		router = server.JWTVerifier(New(ds, nil, playlists.NewPlaylists(ds, nil), nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil))
 	})
 
 	DescribeTable("GET /missing/{id}",
diff --git a/server/nativeapi/native_api.go b/server/nativeapi/native_api.go
index a7c53df09..97ad14be2 100644
--- a/server/nativeapi/native_api.go
+++ b/server/nativeapi/native_api.go
@@ -60,25 +60,25 @@ func (api *Router) routes() http.Handler {
 	r := chi.NewRouter()
 
 	// Public
-	api.RX(r, "/translation", newTranslationRepository, false)
+	rx(r, "/translation", newTranslationRepository(), false)
 
 	// Protected
 	r.Group(func(r chi.Router) {
 		r.Use(server.Authenticator(api.ds))
 		r.Use(server.JWTRefresher)
 		r.Use(server.UpdateLastAccessMiddleware(api.ds))
-		api.RX(r, "/user", api.users.NewRepository, true)
-		api.R(r, "/song", model.MediaFile{}, false)
-		api.R(r, "/album", model.Album{}, false)
+		rx(r, "/user", api.users.Repository(), true)
+		rx(r, "/song", api.ds.MediaFile(), false)
+		rx(r, "/album", api.ds.Album(), false)
 		api.addArtistRoute(r)
-		api.R(r, "/genre", model.Genre{}, false)
-		api.R(r, "/player", model.Player{}, true)
-		api.R(r, "/transcoding", model.Transcoding{}, conf.Server.EnableTranscodingConfig)
+		rx(r, "/genre", api.ds.Genre(), false)
+		rx(r, "/player", api.ds.Player(), true)
+		rx(r, "/transcoding", api.ds.Transcoding(), conf.Server.EnableTranscodingConfig)
 		api.addRadioRoute(r)
-		api.R(r, "/tag", model.Tag{}, false)
-		api.R(r, "/scrobble", model.Scrobble{}, false)
+		rx(r, "/tag", api.ds.Tag(), false)
+		rx(r, "/scrobble", api.ds.Scrobble(), false)
 		if conf.Server.EnableSharing {
-			api.RX(r, "/share", api.share.NewRepository, true)
+			rx(r, "/share", api.share.Repository(), true)
 		}
 
 		api.addPlaylistRoute(r)
@@ -96,47 +96,38 @@ func (api *Router) routes() http.Handler {
 			api.addUserLibraryRoute(r)
 			api.addPluginRoute(r)
 			api.addMetadataRoute(r)
-			api.RX(r, "/library", api.libs.NewRepository, true)
+			rx(r, "/library", api.libs.Repository(), true)
 		})
 	})
 
 	return r
 }
 
-func (api *Router) R(r chi.Router, pathPrefix string, model any, persistable bool) {
-	constructor := func(ctx context.Context) rest.Repository {
-		return api.ds.Resource(ctx, model)
-	}
-	api.RX(r, pathPrefix, constructor, persistable)
-}
-
-func (api *Router) RX(r chi.Router, pathPrefix string, constructor rest.RepositoryConstructor, persistable bool) {
+func rx[T any](r chi.Router, pathPrefix string, repo rest.Repository[T], persistable bool) {
 	r.Route(pathPrefix, func(r chi.Router) {
-		r.Get("/", rest.GetAll(constructor))
+		r.Get("/", rest.GetAll(repo))
 		if persistable {
-			r.Post("/", rest.Post(constructor))
+			r.Post("/", rest.Post(repo))
 		}
 		r.Route("/{id}", func(r chi.Router) {
 			r.Use(server.URLParamsMiddleware)
-			r.Get("/", rest.Get(constructor))
+			r.Get("/", rest.Get(repo))
 			if persistable {
-				r.Put("/", rest.Put(constructor))
-				r.Delete("/", rest.Delete(constructor))
+				r.Put("/", rest.Put(repo))
+				r.Delete("/", rest.Delete(repo))
 			}
 		})
 	})
 }
 
 func (api *Router) addPlaylistRoute(r chi.Router) {
-	constructor := func(ctx context.Context) rest.Repository {
-		return api.playlists.NewRepository(ctx)
-	}
+	repo := api.playlists.Repository()
 
 	r.Route("/playlist", func(r chi.Router) {
-		r.Get("/", rest.GetAll(constructor))
+		r.Get("/", rest.GetAll(repo))
 		r.Post("/", func(w http.ResponseWriter, r *http.Request) {
 			if r.Header.Get("Content-type") == "application/json" {
-				rest.Post(constructor)(w, r)
+				rest.Post(repo)(w, r)
 				return
 			}
 			createPlaylistFromM3U(api.playlists)(w, r)
@@ -144,9 +135,9 @@ func (api *Router) addPlaylistRoute(r chi.Router) {
 
 		r.Route("/{id}", func(r chi.Router) {
 			r.Use(server.URLParamsMiddleware)
-			r.Get("/", rest.Get(constructor))
-			r.Put("/", rest.Put(constructor))
-			r.Delete("/", rest.Delete(constructor))
+			r.Get("/", rest.Get(repo))
+			r.Put("/", rest.Put(repo))
+			r.Delete("/", rest.Delete(repo))
 			r.Post("/image", uploadPlaylistImage(api.playlists))
 			r.Delete("/image", deletePlaylistImage(api.playlists))
 		})
@@ -198,7 +189,7 @@ func (api *Router) addQueueRoute(r chi.Router) {
 
 func (api *Router) addMissingFilesRoute(r chi.Router) {
 	r.Route("/missing", func(r chi.Router) {
-		api.RX(r, "/", newMissingRepository(api.ds), false)
+		rx(r, "/", newMissingRepository(api.ds), false)
 		r.Delete("/", deleteMissingFiles(api.maintenance))
 	})
 }
diff --git a/server/nativeapi/native_api_song_test.go b/server/nativeapi/native_api_song_test.go
index 954c872a7..f151b1d72 100644
--- a/server/nativeapi/native_api_song_test.go
+++ b/server/nativeapi/native_api_song_test.go
@@ -2,6 +2,7 @@ package nativeapi
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
@@ -12,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server"
 	"github.com/navidrome/navidrome/tests"
@@ -21,6 +23,7 @@ import (
 
 var _ = Describe("Song Endpoints", func() {
 	var (
+		ctx       context.Context
 		router    http.Handler
 		ds        *tests.MockDataStore
 		mfRepo    *tests.MockMediaFileRepo
@@ -31,6 +34,7 @@ var _ = Describe("Song Endpoints", func() {
 	)
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.EnableSharing = false
 		conf.Server.SessionTimeout = time.Minute
@@ -56,7 +60,7 @@ var _ = Describe("Song Endpoints", func() {
 			IsAdmin:     false,
 			NewPassword: "testpass",
 		}
-		err := userRepo.Put(&testUser)
+		err := userRepo.Put(ctx, &testUser)
 		Expect(err).ToNot(HaveOccurred())
 
 		// Create test songs
@@ -95,7 +99,7 @@ var _ = Describe("Song Endpoints", func() {
 		mfRepo.SetData(testSongs)
 
 		// Create the native API router and wrap it with the JWTVerifier middleware
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, playlists.NewPlaylists(ds, nil), nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 		w = httptest.NewRecorder()
 	})
@@ -369,7 +373,7 @@ var _ = Describe("Song Endpoints", func() {
 					IsAdmin:     true,
 					NewPassword: "adminpass",
 				}
-				err := userRepo.Put(&adminUser)
+				err := userRepo.Put(ctx, &adminUser)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Create JWT token for admin user
@@ -392,7 +396,7 @@ var _ = Describe("Song Endpoints", func() {
 					IsAdmin:     false,
 					NewPassword: "userpass",
 				}
-				err := userRepo.Put(&regularUser)
+				err := userRepo.Put(ctx, &regularUser)
 				Expect(err).ToNot(HaveOccurred())
 
 				// Create JWT token for regular user
diff --git a/server/nativeapi/playlists.go b/server/nativeapi/playlists.go
index 00c1575a5..82f138492 100644
--- a/server/nativeapi/playlists.go
+++ b/server/nativeapi/playlists.go
@@ -19,8 +19,6 @@ import (
 	"github.com/navidrome/navidrome/utils/str"
 )
 
-type restHandler = func(rest.RepositoryConstructor, ...rest.Logger) http.HandlerFunc
-
 // writePlaylistError maps a playlist service error to an HTTP status, or defaultStatus if unknown.
 func writePlaylistError(w http.ResponseWriter, err error, defaultStatus int) {
 	switch {
@@ -35,7 +33,7 @@ func writePlaylistError(w http.ResponseWriter, err error, defaultStatus int) {
 	}
 }
 
-func playlistTracksHandler(pls playlists.Playlists, handler restHandler, refreshSmartPlaylist func(*http.Request) bool) http.HandlerFunc {
+func playlistTracksHandler(pls playlists.Playlists, handler func(rest.Repository[model.PlaylistTrack]) http.HandlerFunc, refreshSmartPlaylist func(*http.Request) bool) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		plsId := chi.URLParam(r, "playlistId")
 		tracks := pls.TracksRepository(r.Context(), plsId, refreshSmartPlaylist(r))
@@ -43,12 +41,12 @@ func playlistTracksHandler(pls playlists.Playlists, handler restHandler, refresh
 			http.Error(w, "not found", http.StatusNotFound)
 			return
 		}
-		handler(func(ctx context.Context) rest.Repository { return tracks }).ServeHTTP(w, r)
+		handler(tracks).ServeHTTP(w, r)
 	}
 }
 
 func getPlaylist(pls playlists.Playlists) http.HandlerFunc {
-	handler := playlistTracksHandler(pls, rest.GetAll, func(r *http.Request) bool {
+	handler := playlistTracksHandler(pls, rest.GetAll[model.PlaylistTrack], func(r *http.Request) bool {
 		return req.Params(r).Int64Or("_start", 0) == 0
 	})
 	return func(w http.ResponseWriter, r *http.Request) {
@@ -61,7 +59,7 @@ func getPlaylist(pls playlists.Playlists) http.HandlerFunc {
 }
 
 func getPlaylistTrack(pls playlists.Playlists) http.HandlerFunc {
-	return playlistTracksHandler(pls, rest.Get, func(*http.Request) bool { return true })
+	return playlistTracksHandler(pls, rest.Get[model.PlaylistTrack], func(*http.Request) bool { return true })
 }
 
 func createPlaylistFromM3U(pls playlists.Playlists) http.HandlerFunc {
diff --git a/server/nativeapi/playlists_test.go b/server/nativeapi/playlists_test.go
index 349b4a662..82e3bc86a 100644
--- a/server/nativeapi/playlists_test.go
+++ b/server/nativeapi/playlists_test.go
@@ -97,7 +97,7 @@ var _ = Describe("Playlist Tracks Endpoint", func() {
 			IsAdmin:     false,
 			NewPassword: "testpass",
 		}
-		err := userRepo.Put(&testUser)
+		err := userRepo.Put(GinkgoT().Context(), &testUser)
 		Expect(err).ToNot(HaveOccurred())
 
 		nativeRouter := New(ds, nil, plsSvc, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, nil, nil, nil, nil)
@@ -235,23 +235,15 @@ type mockPlaylistTrackRepo struct {
 	tracks model.PlaylistTracks
 }
 
-func (m *mockPlaylistTrackRepo) Count(...rest.QueryOptions) (int64, error) {
+func (m *mockPlaylistTrackRepo) Count(context.Context, ...rest.QueryOptions) (int64, error) {
 	return int64(len(m.tracks)), nil
 }
 
-func (m *mockPlaylistTrackRepo) ReadAll(...rest.QueryOptions) (any, error) {
+func (m *mockPlaylistTrackRepo) ReadAll(context.Context, ...rest.QueryOptions) ([]model.PlaylistTrack, error) {
 	return m.tracks, nil
 }
 
-func (m *mockPlaylistTrackRepo) EntityName() string {
-	return "playlist_track"
-}
-
-func (m *mockPlaylistTrackRepo) NewInstance() any {
-	return &model.PlaylistTrack{}
-}
-
-func (m *mockPlaylistTrackRepo) Read(id string) (any, error) {
+func (m *mockPlaylistTrackRepo) Read(_ context.Context, id string) (*model.PlaylistTrack, error) {
 	for _, t := range m.tracks {
 		if t.ID == id {
 			return &t, nil
@@ -262,7 +254,8 @@ func (m *mockPlaylistTrackRepo) Read(id string) (any, error) {
 
 type mockPlaylistsService struct {
 	playlists.Playlists
-	tracksRepo    rest.Repository
+	repo          rest.Repository[model.Playlist]
+	tracksRepo    rest.Repository[model.PlaylistTrack]
 	playlist      *model.Playlist
 	removeImageFn func(ctx context.Context, id string) error
 	setImageFn    func(ctx context.Context, id string, reader io.Reader, ext string) error
@@ -282,6 +275,10 @@ func (m *mockPlaylistsService) SetImage(ctx context.Context, id string, reader i
 	return model.ErrNotFound
 }
 
+func (m *mockPlaylistsService) Repository() rest.Repository[model.Playlist] {
+	return m.repo
+}
+
 func (m *mockPlaylistsService) GetWithTracks(_ context.Context, _ string) (*model.Playlist, error) {
 	if m.playlist == nil {
 		return nil, model.ErrNotFound
@@ -289,6 +286,6 @@ func (m *mockPlaylistsService) GetWithTracks(_ context.Context, _ string) (*mode
 	return m.playlist, nil
 }
 
-func (m *mockPlaylistsService) TracksRepository(_ context.Context, _ string, _ bool) rest.Repository {
+func (m *mockPlaylistsService) TracksRepository(_ context.Context, _ string, _ bool) rest.Repository[model.PlaylistTrack] {
 	return m.tracksRepo
 }
diff --git a/server/nativeapi/plugin.go b/server/nativeapi/plugin.go
index a7d261681..d34bf23fc 100644
--- a/server/nativeapi/plugin.go
+++ b/server/nativeapi/plugin.go
@@ -15,17 +15,15 @@ import (
 )
 
 func (api *Router) addPluginRoute(r chi.Router) {
-	constructor := func(ctx context.Context) rest.Repository {
-		return api.ds.Plugin(ctx)
-	}
+	repo := api.ds.Plugin()
 
 	r.Route("/plugin", func(r chi.Router) {
 		r.Use(pluginsEnabledMiddleware)
-		r.Get("/", rest.GetAll(constructor))
+		r.Get("/", rest.GetAll(repo))
 		r.Post("/rescan", api.rescanPlugins)
 		r.Route("/{id}", func(r chi.Router) {
 			r.Use(server.URLParamsMiddleware)
-			r.Get("/", rest.Get(constructor))
+			r.Get("/", rest.Get(repo))
 			r.Put("/", api.updatePlugin)
 		})
 	})
@@ -68,10 +66,10 @@ type PluginUpdateRequest struct {
 func (api *Router) updatePlugin(w http.ResponseWriter, r *http.Request) {
 	id := chi.URLParam(r, "id")
 	ctx := r.Context()
-	repo := api.ds.Plugin(ctx)
+	repo := api.ds.Plugin()
 
 	// Get existing plugin to verify it exists
-	if _, err := repo.Get(id); err != nil {
+	if _, err := repo.Get(ctx, id); err != nil {
 		if errors.Is(err, rest.ErrPermissionDenied) {
 			http.Error(w, "Access denied: admin privileges required", http.StatusForbidden)
 			return
@@ -123,7 +121,7 @@ func (api *Router) updatePlugin(w http.ResponseWriter, r *http.Request) {
 			if enableErr := api.pluginManager.EnablePlugin(ctx, id); enableErr != nil {
 				log.Error(ctx, "Error enabling plugin", "id", id, enableErr)
 				// Refresh plugin from DB to get the error
-				plugin, err := repo.Get(id)
+				plugin, err := repo.Get(ctx, id)
 				if err != nil {
 					log.Error(ctx, "Error getting updated plugin after enable failure", "id", id, err)
 					http.Error(w, "Internal server error", http.StatusInternalServerError)
@@ -153,7 +151,7 @@ func (api *Router) updatePlugin(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// Refresh and return updated plugin
-	plugin, err := repo.Get(id)
+	plugin, err := repo.Get(ctx, id)
 	if err != nil {
 		log.Error(ctx, "Error getting updated plugin", "id", id, err)
 		http.Error(w, "Internal server error", http.StatusInternalServerError)
@@ -204,7 +202,7 @@ func validateAndUpdateConfig(ctx context.Context, pm PluginManager, id, configJS
 // Returns an error if validation or update fails (error response already written).
 func validateAndUpdateUsers(ctx context.Context, pm PluginManager, repo model.PluginRepository, id string, req PluginUpdateRequest, w http.ResponseWriter) error {
 	// Get current values if not provided in request
-	plugin, err := repo.Get(id)
+	plugin, err := repo.Get(ctx, id)
 	if err != nil {
 		log.Error(ctx, "Error getting plugin for users update", "id", id, err)
 		http.Error(w, "Internal server error", http.StatusInternalServerError)
@@ -237,7 +235,7 @@ func validateAndUpdateUsers(ctx context.Context, pm PluginManager, repo model.Pl
 // Returns an error if validation or update fails (error response already written).
 func validateAndUpdateLibraries(ctx context.Context, pm PluginManager, repo model.PluginRepository, id string, req PluginUpdateRequest, w http.ResponseWriter) error {
 	// Get current values if not provided in request
-	plugin, err := repo.Get(id)
+	plugin, err := repo.Get(ctx, id)
 	if err != nil {
 		log.Error(ctx, "Error getting plugin for libraries update", "id", id, err)
 		http.Error(w, "Internal server error", http.StatusInternalServerError)
diff --git a/server/nativeapi/plugin_test.go b/server/nativeapi/plugin_test.go
index 4e45ddb92..c18d61e65 100644
--- a/server/nativeapi/plugin_test.go
+++ b/server/nativeapi/plugin_test.go
@@ -12,6 +12,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server"
@@ -21,6 +22,7 @@ import (
 )
 
 var _ = Describe("Plugin API", func() {
+	var ctx context.Context
 	var ds *tests.MockDataStore
 	var mockManager *tests.MockPluginManager
 	var router http.Handler
@@ -28,13 +30,14 @@ var _ = Describe("Plugin API", func() {
 	var testPlugin1, testPlugin2 model.Plugin
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.EnableSharing = false
 		conf.Server.Plugins.Enabled = true
 		ds = &tests.MockDataStore{}
 		mockManager = &tests.MockPluginManager{}
 		auth.Init(ds)
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, mockManager, nil, nil, nil)
+		nativeRouter := New(ds, nil, playlists.NewPlaylists(ds, nil), nil, tests.NewMockLibraryService(), tests.NewMockUserService(), nil, mockManager, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 
 		// Create test users
@@ -71,8 +74,8 @@ var _ = Describe("Plugin API", func() {
 		}
 
 		// Store users in mock datastore
-		Expect(ds.User(GinkgoT().Context()).Put(&adminUser)).To(Succeed())
-		Expect(ds.User(GinkgoT().Context()).Put(&regularUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &adminUser)).To(Succeed())
+		Expect(ds.User().Put(ctx, &regularUser)).To(Succeed())
 	})
 
 	Context("when plugins are disabled", func() {
@@ -104,10 +107,9 @@ var _ = Describe("Plugin API", func() {
 				Expect(err).ToNot(HaveOccurred())
 
 				// Store test plugins as admin
-				ctx := GinkgoT().Context()
 				adminCtx := request.WithUser(ctx, adminUser)
-				Expect(ds.Plugin(adminCtx).Put(&testPlugin1)).To(Succeed())
-				Expect(ds.Plugin(adminCtx).Put(&testPlugin2)).To(Succeed())
+				Expect(ds.Plugin().Put(adminCtx, &testPlugin1)).To(Succeed())
+				Expect(ds.Plugin().Put(adminCtx, &testPlugin2)).To(Succeed())
 			})
 
 			Describe("GET /api/plugin", func() {
@@ -160,9 +162,9 @@ var _ = Describe("Plugin API", func() {
 					// Configure mock to update the repo when EnablePlugin is called
 					mockManager.EnablePluginFn = func(ctx context.Context, id string) error {
 						adminCtx := request.WithUser(ctx, adminUser)
-						p, _ := ds.Plugin(adminCtx).Get(id)
+						p, _ := ds.Plugin().Get(adminCtx, id)
 						p.Enabled = true
-						return ds.Plugin(adminCtx).Put(p)
+						return ds.Plugin().Put(adminCtx, p)
 					}
 
 					body := bytes.NewBufferString(`{"enabled":true}`)
@@ -186,9 +188,9 @@ var _ = Describe("Plugin API", func() {
 					// Configure mock to update the repo when UpdatePluginConfig is called
 					mockManager.UpdatePluginConfigFn = func(ctx context.Context, id, configJSON string) error {
 						adminCtx := request.WithUser(ctx, adminUser)
-						p, _ := ds.Plugin(adminCtx).Get(id)
+						p, _ := ds.Plugin().Get(adminCtx, id)
 						p.Config = configJSON
-						return ds.Plugin(adminCtx).Put(p)
+						return ds.Plugin().Put(adminCtx, p)
 					}
 
 					body := bytes.NewBufferString(`{"config":"{\"key\":\"value\"}"}`)
@@ -226,9 +228,9 @@ var _ = Describe("Plugin API", func() {
 					// Configure mock to update the repo when UpdatePluginConfig is called
 					mockManager.UpdatePluginConfigFn = func(ctx context.Context, id, configJSON string) error {
 						adminCtx := request.WithUser(ctx, adminUser)
-						p, _ := ds.Plugin(adminCtx).Get(id)
+						p, _ := ds.Plugin().Get(adminCtx, id)
 						p.Config = configJSON
-						return ds.Plugin(adminCtx).Put(p)
+						return ds.Plugin().Put(adminCtx, p)
 					}
 
 					body := bytes.NewBufferString(`{"config":""}`)
@@ -251,10 +253,10 @@ var _ = Describe("Plugin API", func() {
 					// Configure mock to update the repo when UpdatePluginUsers is called
 					mockManager.UpdatePluginUsersFn = func(ctx context.Context, id, usersJSON string, allUsers bool) error {
 						adminCtx := request.WithUser(ctx, adminUser)
-						p, _ := ds.Plugin(adminCtx).Get(id)
+						p, _ := ds.Plugin().Get(adminCtx, id)
 						p.Users = usersJSON
 						p.AllUsers = allUsers
-						return ds.Plugin(adminCtx).Put(p)
+						return ds.Plugin().Put(adminCtx, p)
 					}
 
 					body := bytes.NewBufferString(`{"users":"[\"user1\",\"user2\"]"}`)
@@ -279,10 +281,10 @@ var _ = Describe("Plugin API", func() {
 					// Configure mock to update the repo when UpdatePluginUsers is called
 					mockManager.UpdatePluginUsersFn = func(ctx context.Context, id, usersJSON string, allUsers bool) error {
 						adminCtx := request.WithUser(ctx, adminUser)
-						p, _ := ds.Plugin(adminCtx).Get(id)
+						p, _ := ds.Plugin().Get(adminCtx, id)
 						p.Users = usersJSON
 						p.AllUsers = allUsers
-						return ds.Plugin(adminCtx).Put(p)
+						return ds.Plugin().Put(adminCtx, p)
 					}
 
 					body := bytes.NewBufferString(`{"allUsers":true}`)
@@ -307,10 +309,10 @@ var _ = Describe("Plugin API", func() {
 					// Configure mock to update the repo when UpdatePluginUsers is called
 					mockManager.UpdatePluginUsersFn = func(ctx context.Context, id, usersJSON string, allUsers bool) error {
 						adminCtx := request.WithUser(ctx, adminUser)
-						p, _ := ds.Plugin(adminCtx).Get(id)
+						p, _ := ds.Plugin().Get(adminCtx, id)
 						p.Users = usersJSON
 						p.AllUsers = allUsers
-						return ds.Plugin(adminCtx).Put(p)
+						return ds.Plugin().Put(adminCtx, p)
 					}
 
 					body := bytes.NewBufferString(`{"users":"[\"user1\"]","allUsers":false}`)
@@ -348,10 +350,10 @@ var _ = Describe("Plugin API", func() {
 					// Configure mock to update the repo when UpdatePluginUsers is called
 					mockManager.UpdatePluginUsersFn = func(ctx context.Context, id, usersJSON string, allUsers bool) error {
 						adminCtx := request.WithUser(ctx, adminUser)
-						p, _ := ds.Plugin(adminCtx).Get(id)
+						p, _ := ds.Plugin().Get(adminCtx, id)
 						p.Users = usersJSON
 						p.AllUsers = allUsers
-						return ds.Plugin(adminCtx).Put(p)
+						return ds.Plugin().Put(adminCtx, p)
 					}
 
 					body := bytes.NewBufferString(`{"users":""}`)
diff --git a/server/nativeapi/queue.go b/server/nativeapi/queue.go
index a7700c02c..05188106c 100644
--- a/server/nativeapi/queue.go
+++ b/server/nativeapi/queue.go
@@ -32,7 +32,7 @@ func validateCurrentIndex(w http.ResponseWriter, current int, itemsLength int) b
 // retrieveExistingQueue retrieves an existing play queue for a user with proper error handling.
 // Returns the queue (nil if not found) and false if an error occurred and response was sent.
 func retrieveExistingQueue(ctx context.Context, w http.ResponseWriter, ds model.DataStore, userID string) (*model.PlayQueue, bool) {
-	existing, err := ds.PlayQueue(ctx).Retrieve(userID)
+	existing, err := ds.PlayQueue().Retrieve(ctx, userID)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		log.Error(ctx, "Error retrieving queue", err)
 		http.Error(w, err.Error(), http.StatusInternalServerError)
@@ -70,8 +70,8 @@ func getQueue(ds model.DataStore) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		ctx := r.Context()
 		user, _ := request.UserFrom(ctx)
-		repo := ds.PlayQueue(ctx)
-		pq, err := repo.RetrieveWithMediaFiles(user.ID)
+		repo := ds.PlayQueue()
+		pq, err := repo.RetrieveWithMediaFiles(ctx, user.ID)
 		if err != nil && !errors.Is(err, model.ErrNotFound) {
 			log.Error(ctx, "Error retrieving queue", err)
 			http.Error(w, err.Error(), http.StatusInternalServerError)
@@ -112,7 +112,7 @@ func saveQueue(ds model.DataStore) http.HandlerFunc {
 			ChangedBy: client,
 			Items:     items,
 		}
-		if err := ds.PlayQueue(ctx).Store(pq); err != nil {
+		if err := ds.PlayQueue().Store(ctx, pq); err != nil {
 			log.Error(ctx, "Error saving queue", err)
 			http.Error(w, err.Error(), http.StatusInternalServerError)
 			return
@@ -191,7 +191,7 @@ func updateQueue(ds model.DataStore) http.HandlerFunc {
 		}
 
 		// Perform partial update of the specified columns only
-		if err := ds.PlayQueue(ctx).Store(pq, cols...); err != nil {
+		if err := ds.PlayQueue().Store(ctx, pq, cols...); err != nil {
 			log.Error(ctx, "Error updating queue", err)
 			http.Error(w, err.Error(), http.StatusInternalServerError)
 			return
@@ -204,7 +204,7 @@ func clearQueue(ds model.DataStore) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		ctx := r.Context()
 		user, _ := request.UserFrom(ctx)
-		if err := ds.PlayQueue(ctx).Clear(user.ID); err != nil {
+		if err := ds.PlayQueue().Clear(ctx, user.ID); err != nil {
 			log.Error(ctx, "Error clearing queue", err)
 			http.Error(w, err.Error(), http.StatusInternalServerError)
 			return
diff --git a/server/nativeapi/queue_test.go b/server/nativeapi/queue_test.go
index 0aad09718..6e68fec0e 100644
--- a/server/nativeapi/queue_test.go
+++ b/server/nativeapi/queue_test.go
@@ -25,7 +25,7 @@ var _ = Describe("Queue Endpoints", func() {
 		repo = &tests.MockPlayQueueRepo{}
 		user = model.User{ID: "u1", UserName: "user"}
 		userRepo = tests.CreateMockUserRepo()
-		_ = userRepo.Put(&user)
+		_ = userRepo.Put(GinkgoT().Context(), &user)
 		ds = &tests.MockDataStore{MockedPlayQueue: repo, MockedUser: userRepo, MockedProperty: &tests.MockedPropertyRepo{}}
 	})
 
diff --git a/server/nativeapi/radios.go b/server/nativeapi/radios.go
index 3e88af287..4bacbea7a 100644
--- a/server/nativeapi/radios.go
+++ b/server/nativeapi/radios.go
@@ -14,17 +14,15 @@ import (
 )
 
 func (api *Router) addRadioRoute(r chi.Router) {
-	constructor := func(ctx context.Context) rest.Repository {
-		return api.ds.Resource(ctx, model.Radio{})
-	}
+	repo := api.ds.Radio()
 	r.Route("/radio", func(r chi.Router) {
-		r.Get("/", rest.GetAll(constructor))
-		r.Post("/", rest.Post(constructor))
+		r.Get("/", rest.GetAll(repo))
+		r.Post("/", rest.Post(repo))
 		r.Route("/{id}", func(r chi.Router) {
 			r.Use(server.URLParamsMiddleware)
-			r.Get("/", rest.Get(constructor))
-			r.Put("/", rest.Put(constructor))
-			r.Delete("/", rest.Delete(constructor))
+			r.Get("/", rest.Get(repo))
+			r.Put("/", rest.Put(repo))
+			r.Delete("/", rest.Delete(repo))
 			r.Post("/image", api.uploadRadioImage())
 			r.Delete("/image", api.deleteRadioImage())
 		})
@@ -34,7 +32,7 @@ func (api *Router) addRadioRoute(r chi.Router) {
 func (api *Router) uploadRadioImage() http.HandlerFunc {
 	return handleImageUpload(func(ctx context.Context, reader io.Reader, ext string) error {
 		radioID := chi.URLParamFromCtx(ctx, "id")
-		radio, err := api.ds.Radio(ctx).Get(radioID)
+		radio, err := api.ds.Radio().Get(ctx, radioID)
 		if err != nil {
 			if errors.Is(err, model.ErrNotFound) {
 				return model.ErrNotFound
@@ -47,7 +45,7 @@ func (api *Router) uploadRadioImage() http.HandlerFunc {
 			return err
 		}
 		radio.UploadedImage = filename
-		if err := api.ds.Radio(ctx).Put(radio, "UploadedImage"); err != nil {
+		if err := api.ds.Radio().Put(ctx, radio, "UploadedImage"); err != nil {
 			return err
 		}
 		api.imgUpload.EnqueueArtwork(ctx, consts.EntityRadio, radio.ID)
@@ -58,7 +56,7 @@ func (api *Router) uploadRadioImage() http.HandlerFunc {
 func (api *Router) deleteRadioImage() http.HandlerFunc {
 	return handleImageDelete(func(ctx context.Context) error {
 		radioID := chi.URLParamFromCtx(ctx, "id")
-		radio, err := api.ds.Radio(ctx).Get(radioID)
+		radio, err := api.ds.Radio().Get(ctx, radioID)
 		if err != nil {
 			if errors.Is(err, model.ErrNotFound) {
 				return model.ErrNotFound
@@ -69,7 +67,7 @@ func (api *Router) deleteRadioImage() http.HandlerFunc {
 			return err
 		}
 		radio.UploadedImage = ""
-		if err := api.ds.Radio(ctx).Put(radio, "UploadedImage"); err != nil {
+		if err := api.ds.Radio().Put(ctx, radio, "UploadedImage"); err != nil {
 			return err
 		}
 		api.imgUpload.EnqueueArtwork(ctx, consts.EntityRadio, radio.ID)
diff --git a/server/nativeapi/translations.go b/server/nativeapi/translations.go
index 39d071279..fc4651c4c 100644
--- a/server/nativeapi/translations.go
+++ b/server/nativeapi/translations.go
@@ -23,28 +23,28 @@ type translation struct {
 	TermCount int    `json:"termCount"`
 }
 
-func newTranslationRepository(context.Context) rest.Repository {
+func newTranslationRepository() rest.Repository[translation] {
 	return &translationRepository{}
 }
 
 type translationRepository struct{}
 
-func (r *translationRepository) Read(id string) (any, error) {
+func (r *translationRepository) Read(_ context.Context, id string) (*translation, error) {
 	translations, _ := loadTranslations()
 	if t, ok := translations[id]; ok {
-		return t, nil
+		return &t, nil
 	}
 	return nil, rest.ErrNotFound
 }
 
 // Count simple implementation, does not support any `options`
-func (r *translationRepository) Count(...rest.QueryOptions) (int64, error) {
+func (r *translationRepository) Count(context.Context, ...rest.QueryOptions) (int64, error) {
 	_, count := loadTranslations()
 	return count, nil
 }
 
 // ReadAll simple implementation, only returns IDs. Does not support any `options`
-func (r *translationRepository) ReadAll(...rest.QueryOptions) (any, error) {
+func (r *translationRepository) ReadAll(context.Context, ...rest.QueryOptions) ([]translation, error) {
 	translations, _ := loadTranslations()
 	var result []translation
 	for _, t := range translations {
@@ -54,14 +54,6 @@ func (r *translationRepository) ReadAll(...rest.QueryOptions) (any, error) {
 	return result, nil
 }
 
-func (r *translationRepository) EntityName() string {
-	return "translation"
-}
-
-func (r *translationRepository) NewInstance() any {
-	return &translation{}
-}
-
 var loadTranslations = sync.OnceValues(func() (map[string]translation, int64) {
 	translations := make(map[string]translation)
 	fsys := resources.FS()
@@ -140,4 +132,4 @@ func countTranslatedTerms(obj map[string]any) int {
 	return count
 }
 
-var _ rest.Repository = (*translationRepository)(nil)
+var _ rest.Repository[translation] = (*translationRepository)(nil)
diff --git a/server/nativeapi/user_password_token_refresh_test.go b/server/nativeapi/user_password_token_refresh_test.go
index 27454fc7d..81f28893f 100644
--- a/server/nativeapi/user_password_token_refresh_test.go
+++ b/server/nativeapi/user_password_token_refresh_test.go
@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/core/auth"
+	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/persistence"
@@ -29,10 +30,12 @@ func (noopPluginUnloader) UnloadDisabledPlugins(context.Context) {}
 
 // Pins that the token-epoch handoff survives a real request through the real middleware chain.
 var _ = Describe("PUT /user/{id}: token refresh on self password change", func() {
+	var ctx context.Context
 	var ds model.DataStore
 	var router http.Handler
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		// db.Db() is a process-wide singleton that this DeferCleanup closes for the whole binary; keep this the only real-DB spec in this package.
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.EnableUserEditing = true
@@ -45,13 +48,13 @@ var _ = Describe("PUT /user/{id}: token refresh on self password change", func()
 		auth.Init(ds)
 
 		userService := core.NewUser(ds, noopPluginUnloader{})
-		nativeRouter := New(ds, nil, nil, nil, tests.NewMockLibraryService(), userService, nil, nil, nil, nil, nil)
+		nativeRouter := New(ds, nil, playlists.NewPlaylists(ds, nil), nil, tests.NewMockLibraryService(), userService, nil, nil, nil, nil, nil)
 		router = server.JWTVerifier(nativeRouter)
 	})
 
 	It("carries the bumped epoch in the refreshed token, not the epoch the token was minted with", func() {
 		usr := model.User{UserName: "selfchanger", Name: "Self Changer", NewPassword: "old-password"}
-		Expect(ds.User(GinkgoT().Context()).Put(&usr)).To(Succeed())
+		Expect(ds.User().Put(ctx, &usr)).To(Succeed())
 
 		token, err := auth.CreateToken(&usr)
 		Expect(err).ToNot(HaveOccurred())
@@ -72,7 +75,7 @@ var _ = Describe("PUT /user/{id}: token refresh on self password change", func()
 		claims, err := auth.Validate(refreshed)
 		Expect(err).ToNot(HaveOccurred())
 
-		reloaded, err := ds.User(GinkgoT().Context()).Get(usr.ID)
+		reloaded, err := ds.User().Get(ctx, usr.ID)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(reloaded.TokenEpoch).To(Equal(1))
 		Expect(claims.Epoch).To(Equal(reloaded.TokenEpoch))
diff --git a/server/public/handle_streams.go b/server/public/handle_streams.go
index 3d624f661..37ae56c2b 100644
--- a/server/public/handle_streams.go
+++ b/server/public/handle_streams.go
@@ -26,7 +26,7 @@ func (pub *Router) handleStream(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	share, err := pub.ds.Share(ctx).Get(info.shareID)
+	share, err := pub.ds.Share().Get(ctx, info.shareID)
 	if err != nil {
 		checkShareError(ctx, w, err, info.shareID)
 		return
@@ -35,14 +35,14 @@ func (pub *Router) handleStream(w http.ResponseWriter, r *http.Request) {
 		checkShareError(ctx, w, model.ErrExpired, info.shareID)
 		return
 	}
-	shareOwner, err := pub.ds.User(ctx).Get(share.UserID)
+	shareOwner, err := pub.ds.User().Get(ctx, share.UserID)
 	if err != nil {
 		log.Error(ctx, "Error retrieving share owner for shared stream", "share", info.shareID, "owner", share.UserID, err)
 		http.Error(w, "internal error", http.StatusInternalServerError)
 		return
 	}
 
-	mf, err := pub.ds.MediaFile(ctx).Get(info.id)
+	mf, err := pub.ds.MediaFile().Get(ctx, info.id)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
 			http.Error(w, "not found", http.StatusNotFound)
diff --git a/server/public/handle_streams_test.go b/server/public/handle_streams_test.go
index 870dfa8ef..4b4a3545b 100644
--- a/server/public/handle_streams_test.go
+++ b/server/public/handle_streams_test.go
@@ -107,12 +107,14 @@ var _ = Describe("encodeMediafileShare", func() {
 })
 
 var _ = Describe("handleStream", func() {
+	var ctx context.Context
 	var ds *tests.MockDataStore
 	var shareRepo *tests.MockShareRepo
 	var streamer *mockStreamer
 	var pub *Router
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
 		ds = &tests.MockDataStore{}
 		shareRepo = &tests.MockShareRepo{}
@@ -132,7 +134,7 @@ var _ = Describe("handleStream", func() {
 		shareRepo.ID = "share123"
 		shareRepo.Entity = &model.Share{ID: "share123", UserID: owner.ID, Tracks: model.MediaFiles{mf}}
 		userRepo := tests.CreateMockUserRepo()
-		Expect(userRepo.Put(&owner)).To(Succeed())
+		Expect(userRepo.Put(ctx, &owner)).To(Succeed())
 		ds.MockedUser = userRepo
 		mfRepo := tests.CreateMockMediaFileRepo()
 		mfRepo.SetData(model.MediaFiles{mf})
@@ -171,7 +173,7 @@ var _ = Describe("handleStream", func() {
 	It("returns 404 when the track is not a member of the share", func() {
 		owner := model.User{ID: "owner1", UserName: "owner1", IsAdmin: true}
 		userRepo := tests.CreateMockUserRepo()
-		Expect(userRepo.Put(&owner)).To(Succeed())
+		Expect(userRepo.Put(ctx, &owner)).To(Succeed())
 		ds.MockedUser = userRepo
 		mfRepo := tests.CreateMockMediaFileRepo()
 		mfRepo.SetData(model.MediaFiles{{ID: "mf-shared"}, {ID: "mf-other"}})
diff --git a/server/serve_index.go b/server/serve_index.go
index 651c8c907..4b093b953 100644
--- a/server/serve_index.go
+++ b/server/serve_index.go
@@ -32,7 +32,7 @@ func IndexWithShare(ds model.DataStore, fs fs.FS, shareInfo *model.Share) http.H
 // Injects the config in the `index.html` template
 func serveIndex(ds model.DataStore, fs fs.FS, shareInfo *model.Share) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		c, err := ds.User(r.Context()).CountAll()
+		c, err := ds.User().CountAll(r.Context())
 		firstTime := c == 0 && err == nil
 
 		t, err := getIndexTemplate(r, fs)
diff --git a/server/serve_index_test.go b/server/serve_index_test.go
index 23215a5ef..e2df55c4b 100644
--- a/server/serve_index_test.go
+++ b/server/serve_index_test.go
@@ -1,6 +1,7 @@
 package server
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -341,7 +342,7 @@ type mockedUserRepo struct {
 	empty bool
 }
 
-func (u *mockedUserRepo) CountAll(...model.QueryOptions) (int64, error) {
+func (u *mockedUserRepo) CountAll(context.Context, ...model.QueryOptions) (int64, error) {
 	if u.empty {
 		return 0, nil
 	}
diff --git a/server/subsonic/album_lists.go b/server/subsonic/album_lists.go
index ba5f88a68..0a0c65ec7 100644
--- a/server/subsonic/album_lists.go
+++ b/server/subsonic/album_lists.go
@@ -71,14 +71,14 @@ func (api *Router) getAlbumList(r *http.Request) (model.Albums, int64, error) {
 
 	opts.Offset = p.IntOr("offset", 0)
 	opts.Max = min(p.IntOr("size", 10), 500)
-	albums, err := api.ds.Album(r.Context()).GetAll(opts)
+	albums, err := api.ds.Album().GetAll(r.Context(), opts)
 
 	if err != nil {
 		log.Error(r, "Error retrieving albums", err)
 		return nil, 0, newError(responses.ErrorGeneric, "internal error")
 	}
 
-	count, err := api.ds.Album(r.Context()).CountAll(opts)
+	count, err := api.ds.Album().CountAll(r.Context(), opts)
 	if err != nil {
 		log.Error(r, "Error counting albums", err)
 		return nil, 0, newError(responses.ErrorGeneric, "internal error")
@@ -137,7 +137,7 @@ func (api *Router) getStarredItems(r *http.Request) (model.Artists, model.Albums
 		func() error {
 			artistOpts := filter.ApplyArtistLibraryFilter(filter.ArtistsByStarred(), musicFolderIds)
 			var err error
-			artists, err = api.ds.Artist(ctx).GetAll(artistOpts)
+			artists, err = api.ds.Artist().GetAll(ctx, artistOpts)
 			if err != nil {
 				log.Error(r, "Error retrieving starred artists", err)
 			}
@@ -147,7 +147,7 @@ func (api *Router) getStarredItems(r *http.Request) (model.Artists, model.Albums
 		func() error {
 			albumOpts := filter.ApplyLibraryFilter(filter.ByStarred(), musicFolderIds)
 			var err error
-			albums, err = api.ds.Album(ctx).GetAll(albumOpts)
+			albums, err = api.ds.Album().GetAll(ctx, albumOpts)
 			if err != nil {
 				log.Error(r, "Error retrieving starred albums", err)
 			}
@@ -157,7 +157,7 @@ func (api *Router) getStarredItems(r *http.Request) (model.Artists, model.Albums
 		func() error {
 			mediaFileOpts := filter.ApplyLibraryFilter(filter.ByStarred(), musicFolderIds)
 			var err error
-			mediaFiles, err = api.ds.MediaFile(ctx).GetAll(mediaFileOpts)
+			mediaFiles, err = api.ds.MediaFile().GetAll(ctx, mediaFileOpts)
 			if err != nil {
 				log.Error(r, "Error retrieving starred mediaFiles", err)
 			}
@@ -244,7 +244,7 @@ func (api *Router) GetRandomSongs(r *http.Request) (*responses.Subsonic, error)
 	opts = filter.ApplyLibraryFilter(opts, musicFolderIds)
 	opts.Max = size
 
-	songs, err := api.ds.MediaFile(r.Context()).GetRandom(opts)
+	songs, err := api.ds.MediaFile().GetRandom(r.Context(), opts)
 	if err != nil {
 		log.Error(r, "Error retrieving random songs", err)
 		return nil, err
@@ -286,5 +286,5 @@ func (api *Router) GetSongsByGenre(r *http.Request) (*responses.Subsonic, error)
 func (api *Router) getSongs(ctx context.Context, offset, size int, opts filter.Options) (model.MediaFiles, error) {
 	opts.Offset = offset
 	opts.Max = size
-	return api.ds.MediaFile(ctx).GetAll(opts)
+	return api.ds.MediaFile().GetAll(ctx, opts)
 }
diff --git a/server/subsonic/album_lists_test.go b/server/subsonic/album_lists_test.go
index 220376b15..c4a8847d4 100644
--- a/server/subsonic/album_lists_test.go
+++ b/server/subsonic/album_lists_test.go
@@ -6,7 +6,6 @@ import (
 	"net/http/httptest"
 
 	"github.com/navidrome/navidrome/core/auth"
-	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/subsonic/responses"
@@ -21,12 +20,11 @@ var _ = Describe("Album Lists", func() {
 	var ds model.DataStore
 	var mockRepo *tests.MockAlbumRepo
 	var w *httptest.ResponseRecorder
-	ctx := log.NewContext(context.TODO())
 
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
-		mockRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
+		mockRepo = ds.Album().(*tests.MockAlbumRepo)
 		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		w = httptest.NewRecorder()
 	})
@@ -236,7 +234,7 @@ var _ = Describe("Album Lists", func() {
 		var mockMediaFileRepo *tests.MockMediaFileRepo
 
 		BeforeEach(func() {
-			mockMediaFileRepo = ds.MediaFile(ctx).(*tests.MockMediaFileRepo)
+			mockMediaFileRepo = ds.MediaFile().(*tests.MockMediaFileRepo)
 		})
 
 		It("should return random songs", func() {
@@ -328,7 +326,7 @@ var _ = Describe("Album Lists", func() {
 		var mockMediaFileRepo *tests.MockMediaFileRepo
 
 		BeforeEach(func() {
-			mockMediaFileRepo = ds.MediaFile(ctx).(*tests.MockMediaFileRepo)
+			mockMediaFileRepo = ds.MediaFile().(*tests.MockMediaFileRepo)
 		})
 
 		It("should return songs by genre", func() {
@@ -422,9 +420,9 @@ var _ = Describe("Album Lists", func() {
 		var mockMediaFileRepo *tests.MockMediaFileRepo
 
 		BeforeEach(func() {
-			mockArtistRepo = ds.Artist(ctx).(*tests.MockArtistRepo)
-			mockAlbumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
-			mockMediaFileRepo = ds.MediaFile(ctx).(*tests.MockMediaFileRepo)
+			mockArtistRepo = ds.Artist().(*tests.MockArtistRepo)
+			mockAlbumRepo = ds.Album().(*tests.MockAlbumRepo)
+			mockMediaFileRepo = ds.MediaFile().(*tests.MockMediaFileRepo)
 		})
 
 		It("should return starred items", func() {
@@ -484,9 +482,9 @@ var _ = Describe("Album Lists", func() {
 		var mockMediaFileRepo *tests.MockMediaFileRepo
 
 		BeforeEach(func() {
-			mockArtistRepo = ds.Artist(ctx).(*tests.MockArtistRepo)
-			mockAlbumRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
-			mockMediaFileRepo = ds.MediaFile(ctx).(*tests.MockMediaFileRepo)
+			mockArtistRepo = ds.Artist().(*tests.MockArtistRepo)
+			mockAlbumRepo = ds.Album().(*tests.MockAlbumRepo)
+			mockMediaFileRepo = ds.MediaFile().(*tests.MockMediaFileRepo)
 		})
 
 		It("should return starred items in ID3 format", func() {
diff --git a/server/subsonic/bookmarks.go b/server/subsonic/bookmarks.go
index 7ac492ca8..6a4c4962d 100644
--- a/server/subsonic/bookmarks.go
+++ b/server/subsonic/bookmarks.go
@@ -15,8 +15,8 @@ import (
 func (api *Router) GetBookmarks(r *http.Request) (*responses.Subsonic, error) {
 	user, _ := request.UserFrom(r.Context())
 
-	repo := api.ds.MediaFile(r.Context())
-	bookmarks, err := repo.GetBookmarks()
+	repo := api.ds.MediaFile()
+	bookmarks, err := repo.GetBookmarks(r.Context())
 	if err != nil {
 		return nil, err
 	}
@@ -46,8 +46,8 @@ func (api *Router) CreateBookmark(r *http.Request) (*responses.Subsonic, error)
 	comment, _ := p.String("comment")
 	position := p.Int64Or("position", 0)
 
-	repo := api.ds.MediaFile(r.Context())
-	ok, err := repo.Exists(id)
+	repo := api.ds.MediaFile()
+	ok, err := repo.Exists(r.Context(), id)
 	if err != nil {
 		return nil, err
 	}
@@ -55,7 +55,7 @@ func (api *Router) CreateBookmark(r *http.Request) (*responses.Subsonic, error)
 		return nil, newError(responses.ErrorDataNotFound, "Song not found")
 	}
 
-	err = repo.AddBookmark(id, comment, position)
+	err = repo.AddBookmark(r.Context(), id, comment, position)
 	if err != nil {
 		return nil, err
 	}
@@ -69,8 +69,8 @@ func (api *Router) DeleteBookmark(r *http.Request) (*responses.Subsonic, error)
 		return nil, err
 	}
 
-	repo := api.ds.MediaFile(r.Context())
-	err = repo.DeleteBookmark(id)
+	repo := api.ds.MediaFile()
+	err = repo.DeleteBookmark(r.Context(), id)
 	if err != nil {
 		return nil, err
 	}
@@ -80,8 +80,8 @@ func (api *Router) DeleteBookmark(r *http.Request) (*responses.Subsonic, error)
 func (api *Router) GetPlayQueue(r *http.Request) (*responses.Subsonic, error) {
 	user, _ := request.UserFrom(r.Context())
 
-	repo := api.ds.PlayQueue(r.Context())
-	pq, err := repo.RetrieveWithMediaFiles(user.ID)
+	repo := api.ds.PlayQueue()
+	pq, err := repo.RetrieveWithMediaFiles(r.Context(), user.ID)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return nil, err
 	}
@@ -140,8 +140,8 @@ func (api *Router) SavePlayQueue(r *http.Request) (*responses.Subsonic, error) {
 		UpdatedAt: time.Time{},
 	}
 
-	repo := api.ds.PlayQueue(r.Context())
-	err := repo.Store(pq)
+	repo := api.ds.PlayQueue()
+	err := repo.Store(r.Context(), pq)
 	if err != nil {
 		return nil, err
 	}
@@ -151,8 +151,8 @@ func (api *Router) SavePlayQueue(r *http.Request) (*responses.Subsonic, error) {
 func (api *Router) GetPlayQueueByIndex(r *http.Request) (*responses.Subsonic, error) {
 	user, _ := request.UserFrom(r.Context())
 
-	repo := api.ds.PlayQueue(r.Context())
-	pq, err := repo.RetrieveWithMediaFiles(user.ID)
+	repo := api.ds.PlayQueue()
+	pq, err := repo.RetrieveWithMediaFiles(r.Context(), user.ID)
 	if err != nil && !errors.Is(err, model.ErrNotFound) {
 		return nil, err
 	}
@@ -215,8 +215,8 @@ func (api *Router) SavePlayQueueByIndex(r *http.Request) (*responses.Subsonic, e
 		UpdatedAt: time.Time{},
 	}
 
-	repo := api.ds.PlayQueue(r.Context())
-	err = repo.Store(pq)
+	repo := api.ds.PlayQueue()
+	err = repo.Store(r.Context(), pq)
 	if err != nil {
 		return nil, err
 	}
diff --git a/server/subsonic/bookmarks_test.go b/server/subsonic/bookmarks_test.go
index 0fcb81ab9..387ba6ab2 100644
--- a/server/subsonic/bookmarks_test.go
+++ b/server/subsonic/bookmarks_test.go
@@ -21,7 +21,7 @@ var _ = Describe("Bookmarks", func() {
 		ds = &tests.MockDataStore{}
 		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		ctx = request.WithUser(context.Background(), model.User{ID: "u1", UserName: "u1"})
-		mfRepo = ds.MediaFile(ctx).(*tests.MockMediaFileRepo)
+		mfRepo = ds.MediaFile().(*tests.MockMediaFileRepo)
 		mfRepo.SetData(model.MediaFiles{{ID: "visible"}})
 	})
 
diff --git a/server/subsonic/browsing.go b/server/subsonic/browsing.go
index ac0edb69f..d74468940 100644
--- a/server/subsonic/browsing.go
+++ b/server/subsonic/browsing.go
@@ -33,7 +33,7 @@ func (api *Router) GetMusicFolders(r *http.Request) (*responses.Subsonic, error)
 func (api *Router) getArtist(r *http.Request, libIds []int, ifModifiedSince time.Time) (model.ArtistIndexes, int64, error) {
 	ctx := r.Context()
 
-	lastScanStr, err := api.ds.Property(ctx).DefaultGet(consts.LastScanStartTimeKey, "")
+	lastScanStr, err := api.ds.Property().DefaultGet(ctx, consts.LastScanStartTimeKey, "")
 	if err != nil {
 		log.Error(ctx, "Error retrieving last scan start time", err)
 		return nil, 0, err
@@ -45,7 +45,7 @@ func (api *Router) getArtist(r *http.Request, libIds []int, ifModifiedSince time
 
 	var indexes model.ArtistIndexes
 	if lastScan.After(ifModifiedSince) {
-		indexes, err = api.ds.Artist(ctx).GetIndex(false, libIds, model.RoleAlbumArtist)
+		indexes, err = api.ds.Artist().GetIndex(ctx, false, libIds, model.RoleAlbumArtist)
 		if err != nil {
 			log.Error(ctx, "Error retrieving Indexes", err)
 			return nil, 0, err
@@ -167,7 +167,7 @@ func (api *Router) GetArtist(r *http.Request) (*responses.Subsonic, error) {
 	id, _ := p.String("id")
 	ctx := r.Context()
 
-	artist, err := api.ds.Artist(ctx).Get(id)
+	artist, err := api.ds.Artist().Get(ctx, id)
 	if errors.Is(err, model.ErrNotFound) {
 		log.Error(ctx, "Requested ArtistID not found ", "id", id)
 		return nil, newError(responses.ErrorDataNotFound, "Artist not found")
@@ -191,7 +191,7 @@ func (api *Router) GetAlbum(r *http.Request) (*responses.Subsonic, error) {
 
 	ctx := r.Context()
 
-	album, err := api.ds.Album(ctx).Get(id)
+	album, err := api.ds.Album().Get(ctx, id)
 	if errors.Is(err, model.ErrNotFound) {
 		log.Error(ctx, "Requested AlbumID not found ", "id", id)
 		return nil, newError(responses.ErrorDataNotFound, "Album not found")
@@ -201,7 +201,7 @@ func (api *Router) GetAlbum(r *http.Request) (*responses.Subsonic, error) {
 		return nil, err
 	}
 
-	mfs, err := api.ds.MediaFile(ctx).GetAll(filter.SongsByAlbum(id))
+	mfs, err := api.ds.MediaFile().GetAll(ctx, filter.SongsByAlbum(id))
 	if err != nil {
 		log.Error(ctx, "Error retrieving tracks from album", "id", id, "name", album.Name, err)
 		return nil, err
@@ -247,7 +247,7 @@ func (api *Router) GetSong(r *http.Request) (*responses.Subsonic, error) {
 	id, _ := p.String("id")
 	ctx := r.Context()
 
-	mf, err := api.ds.MediaFile(ctx).Get(id)
+	mf, err := api.ds.MediaFile().Get(ctx, id)
 	if errors.Is(err, model.ErrNotFound) {
 		log.Error(r, "Requested MediaFileID not found ", "id", id)
 		return nil, newError(responses.ErrorDataNotFound, "Song not found")
@@ -264,7 +264,7 @@ func (api *Router) GetSong(r *http.Request) (*responses.Subsonic, error) {
 
 func (api *Router) GetGenres(r *http.Request) (*responses.Subsonic, error) {
 	ctx := r.Context()
-	genres, err := api.ds.Genre(ctx).GetAll(model.QueryOptions{Sort: "song_count, album_count, name desc", Order: "desc"})
+	genres, err := api.ds.Genre().GetAll(ctx, model.QueryOptions{Sort: "song_count, album_count, name desc", Order: "desc"})
 	if err != nil {
 		log.Error(r, err)
 		return nil, err
@@ -421,7 +421,7 @@ func (api *Router) buildArtistDirectory(ctx context.Context, artist *model.Artis
 		dir.Starred = artist.StarredAt
 	}
 
-	albums, err := api.ds.Album(ctx).GetAll(filter.AlbumsByArtistID(artist.ID))
+	albums, err := api.ds.Album().GetAll(ctx, filter.AlbumsByArtistID(artist.ID))
 	if err != nil {
 		return nil, err
 	}
@@ -435,7 +435,7 @@ func (api *Router) buildArtist(r *http.Request, artist *model.Artist) (*response
 	a := &responses.ArtistWithAlbumsID3{}
 	a.ArtistID3 = toArtistID3(r, *artist)
 
-	albums, err := api.ds.Album(ctx).GetAll(filter.AlbumsByArtistID(artist.ID))
+	albums, err := api.ds.Album().GetAll(ctx, filter.AlbumsByArtistID(artist.ID))
 	if err != nil {
 		return nil, err
 	}
@@ -463,7 +463,7 @@ func (api *Router) buildAlbumDirectory(ctx context.Context, album *model.Album)
 		dir.Starred = album.StarredAt
 	}
 
-	mfs, err := api.ds.MediaFile(ctx).GetAll(filter.SongsByAlbum(album.ID))
+	mfs, err := api.ds.MediaFile().GetAll(ctx, filter.SongsByAlbum(album.ID))
 	if err != nil {
 		return nil, err
 	}
diff --git a/server/subsonic/browsing_test.go b/server/subsonic/browsing_test.go
index d34da2f37..71d758cfd 100644
--- a/server/subsonic/browsing_test.go
+++ b/server/subsonic/browsing_test.go
@@ -83,14 +83,14 @@ var _ = Describe("Browsing", func() {
 			ctx = contextWithUser(ctx, "user-id", 2, 3)
 
 			// Setup minimal mock library data for working tests
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(model.Libraries{
 				{ID: 2, Name: "Test Library 2", Path: "/music/library2"},
 				{ID: 3, Name: "Test Library 3", Path: "/music/library3"},
 			})
 
 			// Setup mock artist data
-			mockArtistRepo := ds.Artist(ctx).(*tests.MockArtistRepo)
+			mockArtistRepo := ds.Artist().(*tests.MockArtistRepo)
 			mockArtistRepo.SetData(model.Artists{
 				{ID: "1", Name: "Test Artist 1"},
 				{ID: "2", Name: "Test Artist 2"},
@@ -132,14 +132,14 @@ var _ = Describe("Browsing", func() {
 			ctx = contextWithUser(ctx, "user-id", 1, 2)
 
 			// Setup minimal mock library data for working tests
-			mockLibRepo := ds.Library(ctx).(*tests.MockLibraryRepo)
+			mockLibRepo := ds.Library().(*tests.MockLibraryRepo)
 			mockLibRepo.SetData(model.Libraries{
 				{ID: 1, Name: "Test Library 1", Path: "/music/library1"},
 				{ID: 2, Name: "Test Library 2", Path: "/music/library2"},
 			})
 
 			// Setup mock artist data
-			mockArtistRepo := ds.Artist(ctx).(*tests.MockArtistRepo)
+			mockArtistRepo := ds.Artist().(*tests.MockArtistRepo)
 			mockArtistRepo.SetData(model.Artists{
 				{ID: "1", Name: "Test Artist 1"},
 				{ID: "2", Name: "Test Artist 2"},
diff --git a/server/subsonic/e2e/e2e_suite_test.go b/server/subsonic/e2e/e2e_suite_test.go
index 58e877b0d..fdfb562fd 100644
--- a/server/subsonic/e2e/e2e_suite_test.go
+++ b/server/subsonic/e2e/e2e_suite_test.go
@@ -222,10 +222,10 @@ func createUser(id, username, name string, isAdmin bool) model.User {
 		IsAdmin:     isAdmin,
 		NewPassword: "password",
 	}
-	Expect(ds.User(ctx).Put(&user)).To(Succeed())
-	Expect(ds.User(ctx).SetUserLibraries(user.ID, []int{lib.ID})).To(Succeed())
+	Expect(ds.User().Put(ctx, &user)).To(Succeed())
+	Expect(ds.User().SetUserLibraries(ctx, user.ID, []int{lib.ID})).To(Succeed())
 
-	loadedUser, err := ds.User(ctx).FindByUsername(user.UserName)
+	loadedUser, err := ds.User().FindByUsername(ctx, user.UserName)
 	Expect(err).ToNot(HaveOccurred())
 	user.Libraries = loadedUser.Libraries
 	return user
diff --git a/server/subsonic/e2e/subsonic_album_lists_test.go b/server/subsonic/e2e/subsonic_album_lists_test.go
index 6d32a3c88..e1be3f133 100644
--- a/server/subsonic/e2e/subsonic_album_lists_test.go
+++ b/server/subsonic/e2e/subsonic_album_lists_test.go
@@ -142,7 +142,7 @@ var _ = Describe("Album List Endpoints", func() {
 			setupTestDB()
 
 			// Star an album so the starred filter returns results
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.name": "Abbey Road"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -166,7 +166,7 @@ var _ = Describe("Album List Endpoints", func() {
 			setupTestDB()
 
 			// Rate an album so the highest filter returns results
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.name": "Kind of Blue"},
 			})
 			Expect(err).ToNot(HaveOccurred())
diff --git a/server/subsonic/e2e/subsonic_artwork_test.go b/server/subsonic/e2e/subsonic_artwork_test.go
index 9324ea9e3..9394c8830 100644
--- a/server/subsonic/e2e/subsonic_artwork_test.go
+++ b/server/subsonic/e2e/subsonic_artwork_test.go
@@ -108,8 +108,8 @@ var _ = Describe("Artwork Serving", Ordered, func() {
 		// harness's MaxOpenConns=1, so wipe the golden content and import this library fresh.
 		wipeScannedContent()
 		artLib := model.Library{Name: "Artwork Library", Path: musicDir}
-		Expect(ds.Library(ctx).Put(&artLib)).To(Succeed())
-		Expect(ds.User(ctx).SetUserLibraries(adminUser.ID, []int{artLib.ID})).To(Succeed())
+		Expect(ds.Library().Put(ctx, &artLib)).To(Succeed())
+		Expect(ds.User().SetUserLibraries(ctx, adminUser.ID, []int{artLib.ID})).To(Succeed())
 
 		s := scanner.New(ctx, ds, events.NoopBroker(),
 			playlists.NewPlaylists(ds, artwork.NewUploader(ds)), metrics.NewNoopInstance())
@@ -148,20 +148,20 @@ var _ = Describe("Artwork Serving", Ordered, func() {
 	It("drains the queue: folder art is acquired, the artless album settles absent", func() {
 		// Enqueues the way the serving paths do, so the drain is driven by a plain queue row.
 		for _, id := range []string{artfulID, artlessID} {
-			Expect(ds.ArtworkQueue(ctx).EnqueuePreservingBackoff(model.ArtworkQueueItem{
+			Expect(ds.ArtworkQueue().EnqueuePreservingBackoff(ctx, model.ArtworkQueueItem{
 				ItemKind: model.KindAlbumArtwork.Prefix(), ItemID: id,
 				ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBump,
 			})).To(Succeed())
 		}
 		runWorkerUntil(ctx, worker, func() bool {
-			found, err := ds.Artwork(ctx).GetItemArtwork(model.KindAlbumArtwork, artfulID, model.ImageTypePrimary)
+			found, err := ds.Artwork().GetItemArtwork(ctx, model.KindAlbumArtwork, artfulID, model.ImageTypePrimary)
 			if err != nil || found.Hash == "" {
 				return false
 			}
-			absent, err := ds.Artwork(ctx).GetItemArtwork(model.KindAlbumArtwork, artlessID, model.ImageTypePrimary)
+			absent, err := ds.Artwork().GetItemArtwork(ctx, model.KindAlbumArtwork, artlessID, model.ImageTypePrimary)
 			return err == nil && absent.Hash == ""
 		})
-		ia, err := ds.Artwork(ctx).GetItemArtwork(model.KindAlbumArtwork, artfulID, model.ImageTypePrimary)
+		ia, err := ds.Artwork().GetItemArtwork(ctx, model.KindAlbumArtwork, artfulID, model.ImageTypePrimary)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(ia.Source).To(Equal("folder"))
 		artfulHash = ia.Hash
@@ -277,7 +277,7 @@ func wipeScannedContent() {
 
 func albumIDByName(name string) string {
 	GinkgoHelper()
-	albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": name}})
+	albums, err := ds.Album().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"album.name": name}})
 	Expect(err).ToNot(HaveOccurred())
 	Expect(albums).To(HaveLen(1), "expected exactly one album named %q", name)
 	return albums[0].ID
diff --git a/server/subsonic/e2e/subsonic_bookmarks_test.go b/server/subsonic/e2e/subsonic_bookmarks_test.go
index 726b41743..e2d659b9b 100644
--- a/server/subsonic/e2e/subsonic_bookmarks_test.go
+++ b/server/subsonic/e2e/subsonic_bookmarks_test.go
@@ -19,7 +19,7 @@ var _ = Describe("Bookmark and PlayQueue Endpoints", Ordered, func() {
 
 		BeforeAll(func() {
 			// Get a media file ID from the database to use for bookmarks
-			mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Max: 1})
+			mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Max: 1})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(mfs).ToNot(BeEmpty())
 			trackID = mfs[0].ID
@@ -69,7 +69,7 @@ var _ = Describe("Bookmark and PlayQueue Endpoints", Ordered, func() {
 
 		BeforeAll(func() {
 			// Get multiple media file IDs from the database
-			mfs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Max: 3, Sort: "title"})
+			mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Max: 3, Sort: "title"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(len(mfs)).To(BeNumerically(">=", 2))
 			for _, mf := range mfs {
diff --git a/server/subsonic/e2e/subsonic_browsing_test.go b/server/subsonic/e2e/subsonic_browsing_test.go
index 992f9e0fb..8aa93ee2e 100644
--- a/server/subsonic/e2e/subsonic_browsing_test.go
+++ b/server/subsonic/e2e/subsonic_browsing_test.go
@@ -14,7 +14,7 @@ var _ = Describe("Browsing Endpoints", func() {
 	})
 
 	getBeatlesId := func() string {
-		artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
+		artists, err := ds.Artist().GetAll(ctx, model.QueryOptions{
 			Filters: squirrel.Eq{"name": "The Beatles"},
 		})
 		Expect(err).ToNot(HaveOccurred())
@@ -105,7 +105,7 @@ var _ = Describe("Browsing Endpoints", func() {
 		})
 
 		It("returns an album directory with its tracks as children", func() {
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.name": "Abbey Road"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -159,7 +159,7 @@ var _ = Describe("Browsing Endpoints", func() {
 		})
 
 		It("returns artist with a single album", func() {
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{
+			artists, err := ds.Artist().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"name": "Led Zeppelin"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -177,7 +177,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getAlbum", func() {
 		It("returns album with its tracks", func() {
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.name": "Abbey Road"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -193,7 +193,7 @@ var _ = Describe("Browsing Endpoints", func() {
 		})
 
 		It("includes correct track metadata", func() {
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.name": "Abbey Road"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -210,7 +210,7 @@ var _ = Describe("Browsing Endpoints", func() {
 		})
 
 		It("returns album with correct artist and year", func() {
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.name": "Kind of Blue"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -236,7 +236,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getSong", func() {
 		It("returns a song by its ID", func() {
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"title": "Come Together"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -260,7 +260,7 @@ var _ = Describe("Browsing Endpoints", func() {
 		})
 
 		It("returns correct metadata for a jazz track", func() {
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"title": "So What"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -343,7 +343,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getAlbumInfo", func() {
 		It("returns album info for a valid album", func() {
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.name": "Abbey Road"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -359,7 +359,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getAlbumInfo2", func() {
 		It("returns album info for a valid album", func() {
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.name": "Abbey Road"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -434,7 +434,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getSimilarSongs", func() {
 		It("returns a response for a valid song ID", func() {
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"title": "Come Together"},
 			})
 			Expect(err).ToNot(HaveOccurred())
@@ -451,7 +451,7 @@ var _ = Describe("Browsing Endpoints", func() {
 
 	Describe("getSimilarSongs2", func() {
 		It("returns a response for a valid song ID", func() {
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"title": "Come Together"},
 			})
 			Expect(err).ToNot(HaveOccurred())
diff --git a/server/subsonic/e2e/subsonic_media_annotation_test.go b/server/subsonic/e2e/subsonic_media_annotation_test.go
index 74b5238f2..4b90dd143 100644
--- a/server/subsonic/e2e/subsonic_media_annotation_test.go
+++ b/server/subsonic/e2e/subsonic_media_annotation_test.go
@@ -17,19 +17,19 @@ var _ = Describe("Media Annotation Endpoints", Ordered, func() {
 
 		BeforeAll(func() {
 			// Look up a song from the scanned data
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "title"})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "title"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			songID = songs[0].ID
 
 			// Look up an album
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "name"})
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "name"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(albums).ToNot(BeEmpty())
 			albumID = albums[0].ID
 
 			// Look up an artist
-			artists, err := ds.Artist(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "name"})
+			artists, err := ds.Artist().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "name"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(artists).ToNot(BeEmpty())
 			artistID = artists[0].ID
@@ -97,12 +97,12 @@ var _ = Describe("Media Annotation Endpoints", Ordered, func() {
 		var songID, albumID string
 
 		BeforeAll(func() {
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "title"})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "title"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			songID = songs[0].ID
 
-			albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "name"})
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "name"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(albums).ToNot(BeEmpty())
 			albumID = albums[0].ID
@@ -141,7 +141,7 @@ var _ = Describe("Media Annotation Endpoints", Ordered, func() {
 
 	Describe("Scrobble", func() {
 		It("submits a scrobble for a song", func() {
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "title"})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "title"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 
@@ -163,7 +163,7 @@ var _ = Describe("Media Annotation Endpoints", Ordered, func() {
 		var songID string
 
 		BeforeAll(func() {
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "title"})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "title"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			songID = songs[0].ID
diff --git a/server/subsonic/e2e/subsonic_media_retrieval_test.go b/server/subsonic/e2e/subsonic_media_retrieval_test.go
index 268d93b82..b0ef4fd72 100644
--- a/server/subsonic/e2e/subsonic_media_retrieval_test.go
+++ b/server/subsonic/e2e/subsonic_media_retrieval_test.go
@@ -21,7 +21,7 @@ var _ = Describe("Media Retrieval Endpoints", Ordered, func() {
 
 		BeforeAll(func() {
 			// All test tracks are mp3 at 320kbps
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "title"})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "title"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			trackID = songs[0].ID
@@ -110,7 +110,7 @@ var _ = Describe("Media Retrieval Endpoints", Ordered, func() {
 
 		BeforeAll(func() {
 			// All test tracks are mp3 at 320kbps
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Max: 1, Sort: "title"})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Max: 1, Sort: "title"})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			trackID = songs[0].ID
diff --git a/server/subsonic/e2e/subsonic_multilibrary_test.go b/server/subsonic/e2e/subsonic_multilibrary_test.go
index 18e8c6391..8158be1de 100644
--- a/server/subsonic/e2e/subsonic_multilibrary_test.go
+++ b/server/subsonic/e2e/subsonic_multilibrary_test.go
@@ -44,10 +44,10 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 
 		// Create the second library in the DB (Put auto-assigns admin users)
 		lib2 = model.Library{ID: 2, Name: "Classical Library", Path: "fake2:///classical"}
-		Expect(ds.Library(ctx).Put(&lib2)).To(Succeed())
+		Expect(ds.Library().Put(ctx, &lib2)).To(Succeed())
 
 		// Reload admin user to get both libraries in the Libraries field
-		loadedAdmin, err := ds.User(ctx).FindByUsername(adminUser.UserName)
+		loadedAdmin, err := ds.User().FindByUsername(ctx, adminUser.UserName)
 		Expect(err).ToNot(HaveOccurred())
 		adminWithLibs = *loadedAdmin
 
@@ -65,10 +65,10 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 			IsAdmin:     false,
 			NewPassword: "password",
 		}
-		Expect(ds.User(ctx).Put(&userLib1Only)).To(Succeed())
-		Expect(ds.User(ctx).SetUserLibraries(userLib1Only.ID, []int{lib.ID})).To(Succeed())
+		Expect(ds.User().Put(ctx, &userLib1Only)).To(Succeed())
+		Expect(ds.User().SetUserLibraries(ctx, userLib1Only.ID, []int{lib.ID})).To(Succeed())
 
-		loadedUser, err := ds.User(ctx).FindByUsername(userLib1Only.UserName)
+		loadedUser, err := ds.User().FindByUsername(ctx, userLib1Only.UserName)
 		Expect(err).ToNot(HaveOccurred())
 		userLib1Only.Libraries = loadedUser.Libraries
 	})
@@ -181,7 +181,7 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 
 		BeforeAll(func() {
 			// Look up one song from each library
-			lib1Songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			lib1Songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"media_file.library_id": lib.ID},
 				Max:     1, Sort: "title",
 			})
@@ -189,7 +189,7 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 			Expect(lib1Songs).ToNot(BeEmpty())
 			lib1SongID = lib1Songs[0].ID
 
-			lib2Songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			lib2Songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"media_file.library_id": lib2.ID},
 				Max:     1, Sort: "title",
 			})
@@ -248,7 +248,7 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 		var lib2AlbumID string
 
 		BeforeAll(func() {
-			lib2Albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+			lib2Albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"album.library_id": lib2.ID},
 			})
 			Expect(err).ToNot(HaveOccurred())
diff --git a/server/subsonic/e2e/subsonic_playlists_test.go b/server/subsonic/e2e/subsonic_playlists_test.go
index 467535df7..7a6d7df5d 100644
--- a/server/subsonic/e2e/subsonic_playlists_test.go
+++ b/server/subsonic/e2e/subsonic_playlists_test.go
@@ -19,7 +19,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 		setupTestDB()
 
 		// Look up song IDs from scanned data for playlist operations
-		songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Sort: "title", Max: 6})
+		songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Sort: "title", Max: 6})
 		Expect(err).ToNot(HaveOccurred())
 		Expect(len(songs)).To(BeNumerically(">=", 5))
 		for _, s := range songs {
@@ -244,7 +244,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 		BeforeAll(func() {
 			setupTestDB()
 
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Sort: "title", Max: 6})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Sort: "title", Max: 6})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(len(songs)).To(BeNumerically(">=", 3))
 			for _, s := range songs {
@@ -438,7 +438,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 			setupTestDB()
 
 			// Look up a song ID for mutation tests
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Sort: "title", Max: 1})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Sort: "title", Max: 1})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			songID = songs[0].ID
@@ -450,7 +450,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 				Public:  false,
 				Rules:   &criteria.Criteria{Expression: criteria.Contains{"title": ""}},
 			}
-			Expect(ds.Playlist(ctx).Put(smartPls)).To(Succeed())
+			Expect(ds.Playlist().Put(ctx, smartPls)).To(Succeed())
 			smartPlaylistID = smartPls.ID
 		})
 
@@ -525,7 +525,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 		BeforeAll(func() {
 			setupTestDB()
 
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{Sort: "title", Max: 1})
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Sort: "title", Max: 1})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			songID = songs[0].ID
@@ -543,7 +543,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 				OwnerID: adminUser.ID,
 				Rules:   &criteria.Criteria{Expression: criteria.All{criteria.Is{"loved": true}}},
 			}
-			Expect(ds.Playlist(ctx).Put(boolPls)).To(Succeed())
+			Expect(ds.Playlist().Put(ctx, boolPls)).To(Succeed())
 			boolPlaylistID = boolPls.ID
 
 			// Create smart playlist with string "true"
@@ -552,7 +552,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 				OwnerID: adminUser.ID,
 				Rules:   &criteria.Criteria{Expression: criteria.All{criteria.Is{"loved": "true"}}},
 			}
-			Expect(ds.Playlist(ctx).Put(stringPls)).To(Succeed())
+			Expect(ds.Playlist().Put(ctx, stringPls)).To(Succeed())
 			stringPlaylistID = stringPls.ID
 
 			// Create smart playlist with string "true" in nested any group (exact issue #4826 scenario)
@@ -565,7 +565,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 					},
 				}},
 			}
-			Expect(ds.Playlist(ctx).Put(nestedPls)).To(Succeed())
+			Expect(ds.Playlist().Put(ctx, nestedPls)).To(Succeed())
 			nestedPlaylistID = nestedPls.ID
 		})
 
@@ -607,7 +607,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 				OwnerID: adminUser.ID,
 				Rules:   &criteria.Criteria{Expression: criteria.All{criteria.IsPresent{"genre": "true"}}},
 			}
-			Expect(ds.Playlist(ctx).Put(pls)).To(Succeed())
+			Expect(ds.Playlist().Put(ctx, pls)).To(Succeed())
 
 			resp := doReq("getPlaylist", "id", pls.ID)
 			Expect(resp.Status).To(Equal(responses.StatusOK))
@@ -620,7 +620,7 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 				OwnerID: adminUser.ID,
 				Rules:   &criteria.Criteria{Expression: criteria.All{criteria.IsMissing{"genre": "true"}}},
 			}
-			Expect(ds.Playlist(ctx).Put(pls)).To(Succeed())
+			Expect(ds.Playlist().Put(ctx, pls)).To(Succeed())
 
 			resp := doReq("getPlaylist", "id", pls.ID)
 			Expect(resp.Status).To(Equal(responses.StatusOK))
@@ -633,14 +633,14 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 				OwnerID: adminUser.ID,
 				Rules:   &criteria.Criteria{Expression: criteria.All{criteria.IsMissing{"genre": true}}},
 			}
-			Expect(ds.Playlist(ctx).Put(boolPls)).To(Succeed())
+			Expect(ds.Playlist().Put(ctx, boolPls)).To(Succeed())
 
 			stringPls := &model.Playlist{
 				Name:    "Genre Missing String2",
 				OwnerID: adminUser.ID,
 				Rules:   &criteria.Criteria{Expression: criteria.All{criteria.IsMissing{"genre": "true"}}},
 			}
-			Expect(ds.Playlist(ctx).Put(stringPls)).To(Succeed())
+			Expect(ds.Playlist().Put(ctx, stringPls)).To(Succeed())
 
 			boolResp := doReq("getPlaylist", "id", boolPls.ID)
 			stringResp := doReq("getPlaylist", "id", stringPls.ID)
@@ -654,19 +654,19 @@ var _ = Describe("Playlist Endpoints", Ordered, func() {
 					OwnerID: adminUser.ID,
 					Rules:   &criteria.Criteria{Expression: criteria.Contains{"title": ""}},
 				}
-				Expect(ds.Playlist(ctx).Put(allPls)).To(Succeed())
+				Expect(ds.Playlist().Put(ctx, allPls)).To(Succeed())
 				missingPls := &model.Playlist{
 					Name:    "Missing " + fieldName,
 					OwnerID: adminUser.ID,
 					Rules:   &criteria.Criteria{Expression: criteria.All{criteria.IsMissing{fieldName: true}}},
 				}
-				Expect(ds.Playlist(ctx).Put(missingPls)).To(Succeed())
+				Expect(ds.Playlist().Put(ctx, missingPls)).To(Succeed())
 				presentPls := &model.Playlist{
 					Name:    "Present " + fieldName,
 					OwnerID: adminUser.ID,
 					Rules:   &criteria.Criteria{Expression: criteria.All{criteria.IsPresent{fieldName: true}}},
 				}
-				Expect(ds.Playlist(ctx).Put(presentPls)).To(Succeed())
+				Expect(ds.Playlist().Put(ctx, presentPls)).To(Succeed())
 
 				allResp := doReq("getPlaylist", "id", allPls.ID)
 				missingResp := doReq("getPlaylist", "id", missingPls.ID)
diff --git a/server/subsonic/e2e/subsonic_sharing_test.go b/server/subsonic/e2e/subsonic_sharing_test.go
index 1ae68dc1a..cf3e55d74 100644
--- a/server/subsonic/e2e/subsonic_sharing_test.go
+++ b/server/subsonic/e2e/subsonic_sharing_test.go
@@ -18,14 +18,14 @@ var _ = Describe("Sharing Endpoints", Ordered, func() {
 		conf.Server.EnableSharing = true
 		setupTestDB()
 
-		albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+		albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 			Filters: squirrel.Eq{"album.name": "Abbey Road"},
 		})
 		Expect(err).ToNot(HaveOccurred())
 		Expect(albums).ToNot(BeEmpty())
 		albumID = albums[0].ID
 
-		songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+		songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 			Filters: squirrel.Eq{"title": "Come Together"},
 		})
 		Expect(err).ToNot(HaveOccurred())
@@ -139,7 +139,7 @@ var _ = Describe("Sharing Cross-User Isolation", Ordered, func() {
 		userA = createUser("share-user-a", "share-user-a", "Share User A", false)
 		userB = createUser("share-user-b", "share-user-b", "Share User B", false)
 
-		albums, err := ds.Album(ctx).GetAll(model.QueryOptions{
+		albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
 			Filters: squirrel.Eq{"album.name": "Abbey Road"},
 		})
 		Expect(err).ToNot(HaveOccurred())
@@ -221,7 +221,7 @@ var _ = Describe("Sharing Downloadable Default", func() {
 		resp := doReq("createShare", append([]string{"id", albumID}, params...)...)
 		Expect(resp.Status).To(Equal(responses.StatusOK))
 		Expect(resp.Shares.Share).To(HaveLen(1))
-		share, err := ds.Share(ctx).Get(resp.Shares.Share[0].ID)
+		share, err := ds.Share().Get(ctx, resp.Shares.Share[0].ID)
 		Expect(err).ToNot(HaveOccurred())
 		return share
 	}
@@ -248,7 +248,7 @@ var _ = Describe("Sharing Downloadable Default", func() {
 		resp := doReq("updateShare", "id", share.ID, "description", "Updated")
 		Expect(resp.Status).To(Equal(responses.StatusOK))
 
-		updated, err := ds.Share(ctx).Get(share.ID)
+		updated, err := ds.Share().Get(ctx, share.ID)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(updated.Description).To(Equal("Updated"))
 		Expect(updated.Downloadable).To(BeTrue())
@@ -261,7 +261,7 @@ var _ = Describe("Sharing Downloadable Default", func() {
 		resp := doReq("updateShare", "id", share.ID, "downloadable", "false")
 		Expect(resp.Status).To(Equal(responses.StatusOK))
 
-		updated, err := ds.Share(ctx).Get(share.ID)
+		updated, err := ds.Share().Get(ctx, share.ID)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(updated.Downloadable).To(BeFalse())
 		Expect(updated.Description).To(Equal("Keep me"))
@@ -273,7 +273,7 @@ var _ = Describe("Sharing Downloadable Default", func() {
 		resp := doReq("updateShare", "id", share.ID, "description", "")
 		Expect(resp.Status).To(Equal(responses.StatusOK))
 
-		updated, err := ds.Share(ctx).Get(share.ID)
+		updated, err := ds.Share().Get(ctx, share.ID)
 		Expect(err).ToNot(HaveOccurred())
 		Expect(updated.Description).To(BeEmpty())
 	})
diff --git a/server/subsonic/e2e/subsonic_sonic_similarity_test.go b/server/subsonic/e2e/subsonic_sonic_similarity_test.go
index c0cb1d359..80fa658b7 100644
--- a/server/subsonic/e2e/subsonic_sonic_similarity_test.go
+++ b/server/subsonic/e2e/subsonic_sonic_similarity_test.go
@@ -100,14 +100,14 @@ var _ = Describe("Sonic Similarity Endpoints", func() {
 		)
 
 		BeforeEach(func() {
-			songs, err := ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			songs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"title": "Come Together"},
 			})
 			Expect(err).ToNot(HaveOccurred())
 			Expect(songs).ToNot(BeEmpty())
 			comeTogether = songs[0]
 
-			songs, err = ds.MediaFile(ctx).GetAll(model.QueryOptions{
+			songs, err = ds.MediaFile().GetAll(ctx, model.QueryOptions{
 				Filters: squirrel.Eq{"title": "Something"},
 			})
 			Expect(err).ToNot(HaveOccurred())
diff --git a/server/subsonic/e2e/subsonic_stream_test.go b/server/subsonic/e2e/subsonic_stream_test.go
index 281524636..81998760f 100644
--- a/server/subsonic/e2e/subsonic_stream_test.go
+++ b/server/subsonic/e2e/subsonic_stream_test.go
@@ -21,7 +21,7 @@ var _ = Describe("stream.view (legacy streaming)", Ordered, func() {
 	BeforeAll(func() {
 		setupTestDB()
 
-		songs, err := ds.MediaFile(ctx).GetAll()
+		songs, err := ds.MediaFile().GetAll(ctx)
 		Expect(err).ToNot(HaveOccurred())
 		byTitle := map[string]string{}
 		for _, s := range songs {
diff --git a/server/subsonic/e2e/subsonic_transcode_test.go b/server/subsonic/e2e/subsonic_transcode_test.go
index afe7d52ca..313066938 100644
--- a/server/subsonic/e2e/subsonic_transcode_test.go
+++ b/server/subsonic/e2e/subsonic_transcode_test.go
@@ -127,7 +127,7 @@ var _ = Describe("Transcode Endpoints", Ordered, func() {
 	BeforeAll(func() {
 		setupTestDB()
 
-		songs, err := ds.MediaFile(ctx).GetAll()
+		songs, err := ds.MediaFile().GetAll(ctx)
 		Expect(err).ToNot(HaveOccurred())
 		byTitle := map[string]string{}
 		for _, s := range songs {
@@ -153,29 +153,29 @@ var _ = Describe("Transcode Endpoints", Ordered, func() {
 		// It makes a dummy request to register the player, then updates it via the repository.
 		setPlayerMaxBitRate := func(maxBitRate int) {
 			doReq("ping")
-			player, err := ds.Player(ctx).FindMatch(adminUser.ID, "test-client", "")
+			player, err := ds.Player().FindMatch(ctx, adminUser.ID, "test-client", "")
 			Expect(err).ToNot(HaveOccurred())
 			player.MaxBitRate = maxBitRate
-			Expect(ds.Player(ctx).Put(player)).To(Succeed())
+			Expect(ds.Player().Put(ctx, player)).To(Succeed())
 		}
 
 		setPlayerForcedFormat := func(format string) {
 			doReq("ping")
-			player, err := ds.Player(ctx).FindMatch(adminUser.ID, "test-client", "")
+			player, err := ds.Player().FindMatch(ctx, adminUser.ID, "test-client", "")
 			Expect(err).ToNot(HaveOccurred())
-			trc, err := ds.Transcoding(ctx).FindByFormat(format)
+			trc, err := ds.Transcoding().FindByFormat(ctx, format)
 			Expect(err).ToNot(HaveOccurred())
 			player.TranscodingId = trc.ID
-			Expect(ds.Player(ctx).Put(player)).To(Succeed())
+			Expect(ds.Player().Put(ctx, player)).To(Succeed())
 		}
 
 		AfterEach(func() {
 			// Reset player MaxBitRate to 0 after each test
-			player, err := ds.Player(ctx).FindMatch(adminUser.ID, "test-client", "")
+			player, err := ds.Player().FindMatch(ctx, adminUser.ID, "test-client", "")
 			if err == nil {
 				player.MaxBitRate = 0
 				player.TranscodingId = ""
-				_ = ds.Player(ctx).Put(player)
+				_ = ds.Player().Put(ctx, player)
 			}
 		})
 
@@ -595,13 +595,13 @@ var _ = Describe("Transcode Endpoints", Ordered, func() {
 				Expect(token).ToNot(BeEmpty())
 
 				// Save original UpdatedAt and restore after test
-				mf, err := ds.MediaFile(ctx).Get(mp3TrackID)
+				mf, err := ds.MediaFile().Get(ctx, mp3TrackID)
 				Expect(err).ToNot(HaveOccurred())
 				originalUpdatedAt := mf.UpdatedAt
 
 				// Update the media file's UpdatedAt to simulate a change after token issuance
 				mf.UpdatedAt = time.Now().Add(time.Hour)
-				Expect(ds.MediaFile(ctx).Put(mf)).To(Succeed())
+				Expect(ds.MediaFile().Put(ctx, mf)).To(Succeed())
 
 				// Attempt to stream with the now-stale token
 				w := doRawReq("getTranscodeStream", "mediaId", mp3TrackID, "mediaType", "song", "transcodeParams", token)
@@ -609,7 +609,7 @@ var _ = Describe("Transcode Endpoints", Ordered, func() {
 
 				// Restore original UpdatedAt
 				mf.UpdatedAt = originalUpdatedAt
-				Expect(ds.MediaFile(ctx).Put(mf)).To(Succeed())
+				Expect(ds.MediaFile().Put(ctx, mf)).To(Succeed())
 			})
 
 			It("returns 500 when stream creation fails", func() {
diff --git a/server/subsonic/library_scanning.go b/server/subsonic/library_scanning.go
index 9630425d2..89e5cbc9b 100644
--- a/server/subsonic/library_scanning.go
+++ b/server/subsonic/library_scanning.go
@@ -53,7 +53,7 @@ func (api *Router) StartScan(r *http.Request) (*responses.Subsonic, error) {
 		}
 
 		// Validate all libraries in targets exist and user has access to them
-		userLibraries, err := api.ds.User(ctx).GetUserLibraries(loggedUser.ID)
+		userLibraries, err := api.ds.User().GetUserLibraries(ctx, loggedUser.ID)
 		if err != nil {
 			return nil, newError(responses.ErrorGeneric, "Internal error")
 		}
@@ -67,7 +67,7 @@ func (api *Router) StartScan(r *http.Request) (*responses.Subsonic, error) {
 
 		// Special case: if single library with empty path and it's the only library in DB, call ScanAll
 		if len(targets) == 1 && targets[0].FolderPath == "" {
-			allLibs, err := api.ds.Library(ctx).GetAll()
+			allLibs, err := api.ds.Library().GetAll(ctx)
 			if err != nil {
 				return nil, newError(responses.ErrorGeneric, "Internal error")
 			}
diff --git a/server/subsonic/library_scanning_test.go b/server/subsonic/library_scanning_test.go
index 771fc3352..e2b8827f4 100644
--- a/server/subsonic/library_scanning_test.go
+++ b/server/subsonic/library_scanning_test.go
@@ -80,7 +80,7 @@ var _ = Describe("LibraryScanning", func() {
 		It("triggers a selective scan with single target parameter", func() {
 			// Setup mocks
 			mockUserRepo := tests.CreateMockUserRepo()
-			_ = mockUserRepo.SetUserLibraries("admin-id", []int{1, 2})
+			_ = mockUserRepo.SetUserLibraries(GinkgoT().Context(), "admin-id", []int{1, 2})
 			mockDS := &tests.MockDataStore{MockedUser: mockUserRepo}
 			api.ds = mockDS
 
@@ -116,7 +116,7 @@ var _ = Describe("LibraryScanning", func() {
 		It("triggers a selective scan with multiple target parameters", func() {
 			// Setup mocks
 			mockUserRepo := tests.CreateMockUserRepo()
-			_ = mockUserRepo.SetUserLibraries("admin-id", []int{1, 2})
+			_ = mockUserRepo.SetUserLibraries(GinkgoT().Context(), "admin-id", []int{1, 2})
 			mockDS := &tests.MockDataStore{MockedUser: mockUserRepo}
 			api.ds = mockDS
 
@@ -154,7 +154,7 @@ var _ = Describe("LibraryScanning", func() {
 		It("triggers a selective full scan with target and fullScan parameters", func() {
 			// Setup mocks
 			mockUserRepo := tests.CreateMockUserRepo()
-			_ = mockUserRepo.SetUserLibraries("admin-id", []int{1})
+			_ = mockUserRepo.SetUserLibraries(GinkgoT().Context(), "admin-id", []int{1})
 			mockDS := &tests.MockDataStore{MockedUser: mockUserRepo}
 			api.ds = mockDS
 
@@ -235,7 +235,7 @@ var _ = Describe("LibraryScanning", func() {
 		It("returns error when library does not exist", func() {
 			// Setup mocks - user has access to library 1 and 2 only
 			mockUserRepo := tests.CreateMockUserRepo()
-			_ = mockUserRepo.SetUserLibraries("admin-id", []int{1, 2})
+			_ = mockUserRepo.SetUserLibraries(GinkgoT().Context(), "admin-id", []int{1, 2})
 			mockDS := &tests.MockDataStore{MockedUser: mockUserRepo}
 			api.ds = mockDS
 
@@ -264,7 +264,7 @@ var _ = Describe("LibraryScanning", func() {
 		It("calls ScanAll when single library with empty path and only one library exists", func() {
 			// Setup mocks - single library in DB
 			mockUserRepo := tests.CreateMockUserRepo()
-			_ = mockUserRepo.SetUserLibraries("admin-id", []int{1})
+			_ = mockUserRepo.SetUserLibraries(GinkgoT().Context(), "admin-id", []int{1})
 			mockLibraryRepo := &tests.MockLibraryRepo{}
 			mockLibraryRepo.SetData(model.Libraries{
 				{ID: 1, Name: "Music Library", Path: "/music"},
@@ -302,7 +302,7 @@ var _ = Describe("LibraryScanning", func() {
 		It("calls ScanFolders when single library with empty path but multiple libraries exist", func() {
 			// Setup mocks - multiple libraries in DB
 			mockUserRepo := tests.CreateMockUserRepo()
-			_ = mockUserRepo.SetUserLibraries("admin-id", []int{1, 2})
+			_ = mockUserRepo.SetUserLibraries(GinkgoT().Context(), "admin-id", []int{1, 2})
 			mockLibraryRepo := &tests.MockLibraryRepo{}
 			mockLibraryRepo.SetData(model.Libraries{
 				{ID: 1, Name: "Music Library", Path: "/music"},
diff --git a/server/subsonic/media_annotation.go b/server/subsonic/media_annotation.go
index a43162cf4..d6d160570 100644
--- a/server/subsonic/media_annotation.go
+++ b/server/subsonic/media_annotation.go
@@ -48,19 +48,19 @@ func (api *Router) setRating(ctx context.Context, id string, rating int) error {
 	}
 	switch entity.(type) {
 	case *model.Artist:
-		repo = api.ds.Artist(ctx)
+		repo = api.ds.Artist()
 		resource = "artist"
 	case *model.Album:
-		repo = api.ds.Album(ctx)
+		repo = api.ds.Album()
 		resource = "album"
 	case *model.Playlist:
-		repo = api.ds.Playlist(ctx)
+		repo = api.ds.Playlist()
 		resource = "playlist"
 	default:
-		repo = api.ds.MediaFile(ctx)
+		repo = api.ds.MediaFile()
 		resource = "song"
 	}
-	err = repo.SetRating(rating, id)
+	err = repo.SetRating(ctx, rating, id)
 	if err != nil {
 		return err
 	}
@@ -129,19 +129,19 @@ func (api *Router) setStar(ctx context.Context, star bool, ids ...string) error
 			}
 			switch entity.(type) {
 			case *model.Artist:
-				repo = tx.Artist(ctx)
+				repo = tx.Artist()
 				resource = "artist"
 			case *model.Album:
-				repo = tx.Album(ctx)
+				repo = tx.Album()
 				resource = "album"
 			case *model.Playlist:
-				repo = tx.Playlist(ctx)
+				repo = tx.Playlist()
 				resource = "playlist"
 			default:
-				repo = tx.MediaFile(ctx)
+				repo = tx.MediaFile()
 				resource = "song"
 			}
-			if err := repo.SetStar(star, id); err != nil {
+			if err := repo.SetStar(ctx, star, id); err != nil {
 				return err
 			}
 			event = event.With(resource, id)
@@ -210,7 +210,7 @@ func (api *Router) scrobblerSubmit(ctx context.Context, ids []string, times []ti
 }
 
 func (api *Router) scrobblerNowPlaying(ctx context.Context, trackId string, position int) error {
-	mf, err := api.ds.MediaFile(ctx).Get(trackId)
+	mf, err := api.ds.MediaFile().Get(ctx, trackId)
 	if err != nil {
 		return err
 	}
diff --git a/server/subsonic/media_annotation_test.go b/server/subsonic/media_annotation_test.go
index 1b16dfc68..9948929e3 100644
--- a/server/subsonic/media_annotation_test.go
+++ b/server/subsonic/media_annotation_test.go
@@ -77,7 +77,7 @@ var _ = Describe("MediaAnnotationController", func() {
 		Context("submission=false", func() {
 			var req *http.Request
 			BeforeEach(func() {
-				_ = ds.MediaFile(ctx).Put(&model.MediaFile{ID: "12"})
+				_ = ds.MediaFile().Put(ctx, &model.MediaFile{ID: "12"})
 				ctx = request.WithPlayer(ctx, model.Player{ID: "player-1"})
 				req = newGetRequest("id=12", "submission=false")
 				req = req.WithContext(ctx)
diff --git a/server/subsonic/media_retrieval.go b/server/subsonic/media_retrieval.go
index 8a5152a9d..f5e2ceb25 100644
--- a/server/subsonic/media_retrieval.go
+++ b/server/subsonic/media_retrieval.go
@@ -29,7 +29,7 @@ func (api *Router) GetAvatar(w http.ResponseWriter, r *http.Request) (*responses
 		return nil, err
 	}
 	ctx := r.Context()
-	u, err := api.ds.User(ctx).FindByUsername(username)
+	u, err := api.ds.User().FindByUsername(ctx, username)
 	if err != nil {
 		return nil, err
 	}
@@ -128,7 +128,7 @@ func (api *Router) GetLyricsBySongId(r *http.Request) (*responses.Subsonic, erro
 		return nil, err
 	}
 
-	mediaFile, err := api.ds.MediaFile(r.Context()).Get(id)
+	mediaFile, err := api.ds.MediaFile().Get(r.Context(), id)
 	if err != nil {
 		return nil, err
 	}
diff --git a/server/subsonic/media_retrieval_test.go b/server/subsonic/media_retrieval_test.go
index 7610c866a..ad193518d 100644
--- a/server/subsonic/media_retrieval_test.go
+++ b/server/subsonic/media_retrieval_test.go
@@ -34,7 +34,7 @@ var _ = Describe("MediaRetrievalController", func() {
 		albumRepo := &tests.MockAlbumRepo{}
 		albumRepo.SetData(model.Albums{{ID: "34"}}) // the id the specs request, made accessible
 		radioRepo := tests.CreateMockedRadioRepo()
-		Expect(radioRepo.Put(&model.Radio{ID: "rd1", Name: "Radio"})).To(Succeed())
+		Expect(radioRepo.Put(GinkgoT().Context(), &model.Radio{ID: "rd1", Name: "Radio"})).To(Succeed())
 		ds = &tests.MockDataStore{
 			MockedMediaFile: mockRepo,
 			MockedAlbum:     albumRepo,
@@ -293,8 +293,8 @@ type mockedMediaFile struct {
 	tests.MockMediaFileRepo
 }
 
-func (m *mockedMediaFile) GetAll(opts ...model.QueryOptions) (model.MediaFiles, error) {
-	data, err := m.MockMediaFileRepo.GetAll(opts...)
+func (m *mockedMediaFile) GetAll(ctx context.Context, opts ...model.QueryOptions) (model.MediaFiles, error) {
+	data, err := m.MockMediaFileRepo.GetAll(ctx, opts...)
 	if err != nil {
 		return nil, err
 	}
diff --git a/server/subsonic/middlewares.go b/server/subsonic/middlewares.go
index 35e13eaa5..6617661a9 100644
--- a/server/subsonic/middlewares.go
+++ b/server/subsonic/middlewares.go
@@ -109,7 +109,7 @@ func authenticate(ds model.DataStore) func(next http.Handler) http.Handler {
 			username, isInternalAuth := fromInternalOrProxyAuth(r)
 			if username != "" {
 				authType := If(isInternalAuth, "internal", "reverse-proxy")
-				usr, err = ds.User(ctx).FindByUsername(username)
+				usr, err = ds.User().FindByUsername(ctx, username)
 				if errors.Is(err, context.Canceled) {
 					log.Debug(ctx, "API: Request canceled when authenticating", "auth", authType, "username", username, "remoteAddr", r.RemoteAddr, err)
 					return
@@ -139,7 +139,7 @@ func authenticate(ds model.DataStore) func(next http.Handler) http.Handler {
 					return
 				}
 
-				usr, err = ds.User(ctx).FindByUsernameWithPassword(username)
+				usr, err = ds.User().FindByUsernameWithPassword(ctx, username)
 				if err == nil {
 					err = validateCredentials(usr, pass, token, salt, jwt)
 				}
diff --git a/server/subsonic/middlewares_test.go b/server/subsonic/middlewares_test.go
index 62de09e76..0879ee540 100644
--- a/server/subsonic/middlewares_test.go
+++ b/server/subsonic/middlewares_test.go
@@ -42,11 +42,13 @@ func newPostRequest(queryParam string, formFields ...string) *http.Request {
 }
 
 var _ = Describe("Middlewares", func() {
+	var ctx context.Context
 	var next *mockHandler
 	var w *httptest.ResponseRecorder
 	var ds model.DataStore
 
 	BeforeEach(func() {
+		ctx = GinkgoT().Context()
 		next = &mockHandler{}
 		w = httptest.NewRecorder()
 		ds = &tests.MockDataStore{}
@@ -147,8 +149,8 @@ var _ = Describe("Middlewares", func() {
 
 	Describe("Authenticate", func() {
 		BeforeEach(func() {
-			ur := ds.User(context.TODO())
-			_ = ur.Put(&model.User{
+			ur := ds.User()
+			_ = ur.Put(ctx, &model.User{
 				UserName:    "admin",
 				NewPassword: "wordpass",
 			})
@@ -344,7 +346,7 @@ var _ = Describe("Middlewares", func() {
 
 			It("counts attempts against unknown usernames", func() {
 				failTimes(3, "u=newuser", "p=secret")
-				_ = ds.User(context.TODO()).Put(&model.User{UserName: "newuser", NewPassword: "secret"})
+				_ = ds.User().Put(ctx, &model.User{UserName: "newuser", NewPassword: "secret"})
 
 				serve(newGetRequest("u=newuser", "p=secret"))
 				Expect(next.called).To(BeFalse())
@@ -365,7 +367,7 @@ var _ = Describe("Middlewares", func() {
 			})
 
 			It("does not count server errors", func() {
-				userRepo := ds.User(context.TODO()).(*tests.MockedUserRepo)
+				userRepo := ds.User().(*tests.MockedUserRepo)
 				userRepo.Error = errors.New("db down")
 				failTimes(5, "u=admin", "p=wordpass")
 				userRepo.Error = nil
@@ -375,7 +377,7 @@ var _ = Describe("Middlewares", func() {
 			})
 
 			It("does not block other usernames from the same IP", func() {
-				_ = ds.User(context.TODO()).Put(&model.User{UserName: "other", NewPassword: "otherpass"})
+				_ = ds.User().Put(ctx, &model.User{UserName: "other", NewPassword: "otherpass"})
 				failTimes(3, "u=admin", "p=WRONG")
 
 				serve(newGetRequest("u=other", "p=otherpass"))
@@ -422,7 +424,7 @@ var _ = Describe("Middlewares", func() {
 				conf.Server.AuthRequestLimit = 5
 				conf.Server.AuthWindowLength = time.Minute
 				gate = &gatedUserRepo{
-					UserRepository: ds.User(context.TODO()),
+					UserRepository: ds.User(),
 					entered:        make(chan struct{}, 64),
 					proceed:        make(chan struct{}),
 				}
@@ -583,14 +585,14 @@ var _ = Describe("Middlewares", func() {
 		var usr *model.User
 
 		BeforeEach(func() {
-			ur := ds.User(context.TODO())
-			_ = ur.Put(&model.User{
+			ur := ds.User()
+			_ = ur.Put(ctx, &model.User{
 				UserName:    "admin",
 				NewPassword: "wordpass",
 			})
 
 			var err error
-			usr, err = ur.FindByUsernameWithPassword("admin")
+			usr, err = ur.FindByUsernameWithPassword(ctx, "admin")
 			if err != nil {
 				panic(err)
 			}
@@ -728,7 +730,7 @@ type gatedDataStore struct {
 	users model.UserRepository
 }
 
-func (g *gatedDataStore) User(context.Context) model.UserRepository { return g.users }
+func (g *gatedDataStore) User() model.UserRepository { return g.users }
 
 type gatedUserRepo struct {
 	model.UserRepository
@@ -737,11 +739,11 @@ type gatedUserRepo struct {
 	lookups atomic.Int32
 }
 
-func (g *gatedUserRepo) FindByUsernameWithPassword(username string) (*model.User, error) {
+func (g *gatedUserRepo) FindByUsernameWithPassword(ctx context.Context, username string) (*model.User, error) {
 	g.lookups.Add(1)
 	g.entered <- struct{}{}
 	<-g.proceed
-	return g.UserRepository.FindByUsernameWithPassword(username)
+	return g.UserRepository.FindByUsernameWithPassword(ctx, username)
 }
 
 type countingHandler struct{ calls atomic.Int32 }
diff --git a/server/subsonic/radio.go b/server/subsonic/radio.go
index 1fb266f1d..2c4033467 100644
--- a/server/subsonic/radio.go
+++ b/server/subsonic/radio.go
@@ -32,7 +32,7 @@ func (api *Router) CreateInternetRadio(r *http.Request) (*responses.Subsonic, er
 		Name:        name,
 	}
 
-	err = api.ds.Radio(ctx).Put(radio)
+	err = api.ds.Radio().Put(ctx, radio)
 	if err != nil {
 		return nil, err
 	}
@@ -47,7 +47,7 @@ func (api *Router) DeleteInternetRadio(r *http.Request) (*responses.Subsonic, er
 		return nil, err
 	}
 
-	err = api.ds.Radio(r.Context()).Delete(id)
+	err = api.ds.Radio().Delete(r.Context(), id)
 	if err != nil {
 		return nil, err
 	}
@@ -56,7 +56,7 @@ func (api *Router) DeleteInternetRadio(r *http.Request) (*responses.Subsonic, er
 
 func (api *Router) GetInternetRadios(r *http.Request) (*responses.Subsonic, error) {
 	ctx := r.Context()
-	radios, err := api.ds.Radio(ctx).GetAll(model.QueryOptions{Sort: "name"})
+	radios, err := api.ds.Radio().GetAll(ctx, model.QueryOptions{Sort: "name"})
 	if err != nil {
 		return nil, err
 	}
@@ -119,7 +119,7 @@ func (api *Router) UpdateInternetRadio(r *http.Request) (*responses.Subsonic, er
 		Name:        name,
 	}
 
-	err = api.ds.Radio(ctx).Put(radio, "StreamUrl", "HomePageUrl", "Name")
+	err = api.ds.Radio().Put(ctx, radio, "StreamUrl", "HomePageUrl", "Name")
 	if err != nil {
 		return nil, err
 	}
diff --git a/server/subsonic/searching.go b/server/subsonic/searching.go
index 35233a98f..fb370fc9d 100644
--- a/server/subsonic/searching.go
+++ b/server/subsonic/searching.go
@@ -42,7 +42,7 @@ func (api *Router) getSearchParams(r *http.Request) (*searchParams, error) {
 	return sp, nil
 }
 
-type searchFunc[T any] func(q string, options ...model.QueryOptions) (T, error)
+type searchFunc[T any] func(ctx context.Context, q string, options ...model.QueryOptions) (T, error)
 
 func callSearch[T any](ctx context.Context, s searchFunc[T], q string, options model.QueryOptions, result *T) func() error {
 	return func() error {
@@ -52,7 +52,7 @@ func callSearch[T any](ctx context.Context, s searchFunc[T], q string, options m
 		typ := strings.TrimPrefix(reflect.TypeOf(*result).String(), "model.")
 		var err error
 		start := time.Now()
-		*result, err = s(q, options)
+		*result, err = s(ctx, q, options)
 		if err != nil {
 			log.Error(ctx, "Error searching "+typ, "query", q, "elapsed", time.Since(start), err)
 		} else {
@@ -79,9 +79,9 @@ func (api *Router) searchAll(ctx context.Context, sp *searchParams, musicFolderI
 
 	// Run searches in parallel
 	g, ctx := errgroup.WithContext(ctx)
-	g.Go(callSearch(ctx, api.ds.MediaFile(ctx).Search, q, songOpts, &mediaFiles))
-	g.Go(callSearch(ctx, api.ds.Album(ctx).Search, q, albumOpts, &albums))
-	g.Go(callSearch(ctx, api.ds.Artist(ctx).Search, q, artistOpts, &artists))
+	g.Go(callSearch(ctx, api.ds.MediaFile().Search, q, songOpts, &mediaFiles))
+	g.Go(callSearch(ctx, api.ds.Album().Search, q, albumOpts, &albums))
+	g.Go(callSearch(ctx, api.ds.Artist().Search, q, artistOpts, &artists))
 	err := g.Wait()
 	if err == nil {
 		log.Debug(ctx, fmt.Sprintf("Search resulted in %d songs, %d albums and %d artists",
diff --git a/server/subsonic/searching_test.go b/server/subsonic/searching_test.go
index d31a50cfa..177fa2133 100644
--- a/server/subsonic/searching_test.go
+++ b/server/subsonic/searching_test.go
@@ -26,9 +26,9 @@ var _ = Describe("Search", func() {
 		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 
 		// Get references to the mock repositories so we can inspect their Options
-		mockAlbumRepo = ds.Album(nil).(*tests.MockAlbumRepo)
-		mockArtistRepo = ds.Artist(nil).(*tests.MockArtistRepo)
-		mockMediaFileRepo = ds.MediaFile(nil).(*tests.MockMediaFileRepo)
+		mockAlbumRepo = ds.Album().(*tests.MockAlbumRepo)
+		mockArtistRepo = ds.Artist().(*tests.MockArtistRepo)
+		mockMediaFileRepo = ds.MediaFile().(*tests.MockMediaFileRepo)
 	})
 
 	Context("musicFolderId parameter", func() {
diff --git a/server/subsonic/sharing.go b/server/subsonic/sharing.go
index c4b735832..e5f4f2a54 100644
--- a/server/subsonic/sharing.go
+++ b/server/subsonic/sharing.go
@@ -6,7 +6,6 @@ import (
 	"strings"
 	"time"
 
-	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server/public"
@@ -16,8 +15,8 @@ import (
 )
 
 func (api *Router) GetShares(r *http.Request) (*responses.Subsonic, error) {
-	repo := api.share.NewRepository(r.Context()).(model.ShareRepository)
-	shares, err := repo.GetAll(model.QueryOptions{Sort: "created_at desc"})
+	repo := api.share.Repository()
+	shares, err := repo.GetAll(r.Context(), model.QueryOptions{Sort: "created_at desc"})
 	if err != nil {
 		return nil, err
 	}
@@ -60,7 +59,7 @@ func (api *Router) CreateShare(r *http.Request) (*responses.Subsonic, error) {
 	}
 
 	description, _ := p.String("description")
-	repo := api.share.NewRepository(r.Context())
+	repo := api.share.Repository()
 	share := &model.Share{
 		Description:  description,
 		Downloadable: p.BoolOr("downloadable", conf.Server.DefaultDownloadableShare && conf.Server.EnableDownloads),
@@ -68,12 +67,12 @@ func (api *Router) CreateShare(r *http.Request) (*responses.Subsonic, error) {
 		ResourceIDs:  strings.Join(ids, ","),
 	}
 
-	id, err := repo.(rest.Persistable).Save(share)
+	id, err := repo.Save(r.Context(), share)
 	if err != nil {
 		return nil, err
 	}
 
-	share, err = repo.(model.ShareRepository).Get(id)
+	share, err = repo.Get(r.Context(), id)
 	if err != nil {
 		return nil, err
 	}
@@ -90,18 +89,17 @@ func (api *Router) UpdateShare(r *http.Request) (*responses.Subsonic, error) {
 		return nil, err
 	}
 
-	repo := api.share.NewRepository(r.Context())
+	repo := api.share.Repository()
 
 	// The update always writes description and downloadable, so read back the
 	// stored value for whichever one the client omitted.
 	description := p.StringPtr("description")
 	downloadable := p.BoolPtr("downloadable")
 	if description == nil || downloadable == nil {
-		current, err := repo.Read(id)
+		cur, err := repo.Read(r.Context(), id)
 		if err != nil {
 			return nil, err
 		}
-		cur := current.(*model.Share)
 		description = cmp.Or(description, &cur.Description)
 		downloadable = cmp.Or(downloadable, &cur.Downloadable)
 	}
@@ -113,7 +111,7 @@ func (api *Router) UpdateShare(r *http.Request) (*responses.Subsonic, error) {
 		ExpiresAt:    new(p.TimeOr("expires", time.Time{})),
 	}
 
-	err = repo.(rest.Persistable).Update(id, share)
+	err = repo.Update(r.Context(), id, *share)
 	if err != nil {
 		return nil, err
 	}
@@ -128,8 +126,8 @@ func (api *Router) DeleteShare(r *http.Request) (*responses.Subsonic, error) {
 		return nil, err
 	}
 
-	repo := api.share.NewRepository(r.Context())
-	err = repo.(rest.Persistable).Delete(id)
+	repo := api.share.Repository()
+	err = repo.Delete(r.Context(), id)
 	if err != nil {
 		return nil, err
 	}
diff --git a/server/subsonic/stream.go b/server/subsonic/stream.go
index b4a6b821c..fd26ccc4d 100644
--- a/server/subsonic/stream.go
+++ b/server/subsonic/stream.go
@@ -27,7 +27,7 @@ func (api *Router) Stream(w http.ResponseWriter, r *http.Request) (*responses.Su
 	format, _ := p.String("format")
 	timeOffset := p.IntOr("timeOffset", 0)
 
-	mf, err := api.ds.MediaFile(ctx).Get(id)
+	mf, err := api.ds.MediaFile().Get(ctx, id)
 	if err != nil {
 		return nil, err
 	}
diff --git a/server/subsonic/transcode.go b/server/subsonic/transcode.go
index d64bce605..7a011a616 100644
--- a/server/subsonic/transcode.go
+++ b/server/subsonic/transcode.go
@@ -310,7 +310,7 @@ func (api *Router) GetTranscodeDecision(w http.ResponseWriter, r *http.Request)
 	}
 
 	// Get media file
-	mf, err := api.ds.MediaFile(ctx).Get(mediaID)
+	mf, err := api.ds.MediaFile().Get(ctx, mediaID)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
 			return nil, newError(responses.ErrorDataNotFound, "media file not found: %s", mediaID)
@@ -399,7 +399,7 @@ func (api *Router) GetTranscodeStream(w http.ResponseWriter, r *http.Request) (*
 	}
 
 	// Fetch the media file
-	mf, err := api.ds.MediaFile(ctx).Get(mediaID)
+	mf, err := api.ds.MediaFile().Get(ctx, mediaID)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
 			http.Error(w, "Not Found", http.StatusNotFound)
diff --git a/tests/harness/harness.go b/tests/harness/harness.go
index 5949c4fae..92196ef26 100644
--- a/tests/harness/harness.go
+++ b/tests/harness/harness.go
@@ -61,14 +61,14 @@ func SetupDB(ctx context.Context, users ...*model.User) *DB {
 	auth.Init(ds)
 
 	h.Library = model.Library{ID: 1, Name: "Music Library", Path: "fake:///music"}
-	Expect(ds.Library(ctx).Put(&h.Library)).To(Succeed())
+	Expect(ds.Library().Put(ctx, &h.Library)).To(Succeed())
 
 	for _, u := range users {
 		seeded := *u
 		seeded.NewPassword = "password"
-		Expect(ds.User(ctx).Put(&seeded)).To(Succeed())
-		Expect(ds.User(ctx).SetUserLibraries(u.ID, []int{h.Library.ID})).To(Succeed())
-		loaded, err := ds.User(ctx).FindByUsername(u.UserName)
+		Expect(ds.User().Put(ctx, &seeded)).To(Succeed())
+		Expect(ds.User().SetUserLibraries(ctx, u.ID, []int{h.Library.ID})).To(Succeed())
+		loaded, err := ds.User().FindByUsername(ctx, u.UserName)
 		Expect(err).ToNot(HaveOccurred())
 		u.Libraries = loaded.Libraries
 	}
diff --git a/tests/mock_album_repo.go b/tests/mock_album_repo.go
index 1b14f225b..f8100c189 100644
--- a/tests/mock_album_repo.go
+++ b/tests/mock_album_repo.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"errors"
 	"sync"
 	"time"
@@ -39,7 +40,7 @@ func (m *MockAlbumRepo) SetData(albums model.Albums) {
 	}
 }
 
-func (m *MockAlbumRepo) Exists(id string) (bool, error) {
+func (m *MockAlbumRepo) Exists(_ context.Context, id string) (bool, error) {
 	if m.Err {
 		return false, errors.New("unexpected error")
 	}
@@ -47,7 +48,7 @@ func (m *MockAlbumRepo) Exists(id string) (bool, error) {
 	return found, nil
 }
 
-func (m *MockAlbumRepo) Get(id string) (*model.Album, error) {
+func (m *MockAlbumRepo) Get(_ context.Context, id string) (*model.Album, error) {
 	if m.Err {
 		return nil, errors.New("unexpected error")
 	}
@@ -57,7 +58,7 @@ func (m *MockAlbumRepo) Get(id string) (*model.Album, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockAlbumRepo) Put(al *model.Album) error {
+func (m *MockAlbumRepo) Put(_ context.Context, al *model.Album) error {
 	if m.Err {
 		return errors.New("unexpected error")
 	}
@@ -71,7 +72,7 @@ func (m *MockAlbumRepo) Put(al *model.Album) error {
 	return nil
 }
 
-func (m *MockAlbumRepo) GetAll(qo ...model.QueryOptions) (model.Albums, error) {
+func (m *MockAlbumRepo) GetAll(_ context.Context, qo ...model.QueryOptions) (model.Albums, error) {
 	if len(qo) > 0 {
 		// Recording the last options is a read-path write, and callers resolve concurrently.
 		m.optionsMu.Lock()
@@ -84,8 +85,8 @@ func (m *MockAlbumRepo) GetAll(qo ...model.QueryOptions) (model.Albums, error) {
 	return m.All, nil
 }
 
-func (m *MockAlbumRepo) GetCursor(qo ...model.QueryOptions) (model.AlbumCursor, error) {
-	res, err := m.GetAll(qo...)
+func (m *MockAlbumRepo) GetCursor(ctx context.Context, qo ...model.QueryOptions) (model.AlbumCursor, error) {
+	res, err := m.GetAll(ctx, qo...)
 	if err != nil {
 		return nil, err
 	}
@@ -98,7 +99,7 @@ func (m *MockAlbumRepo) GetCursor(qo ...model.QueryOptions) (model.AlbumCursor,
 	}, nil
 }
 
-func (m *MockAlbumRepo) IncPlayCount(id string, timestamp time.Time) error {
+func (m *MockAlbumRepo) IncPlayCount(_ context.Context, id string, timestamp time.Time) error {
 	if m.Err {
 		return errors.New("unexpected error")
 	}
@@ -109,11 +110,11 @@ func (m *MockAlbumRepo) IncPlayCount(id string, timestamp time.Time) error {
 	}
 	return model.ErrNotFound
 }
-func (m *MockAlbumRepo) CountAll(...model.QueryOptions) (int64, error) {
+func (m *MockAlbumRepo) CountAll(_ context.Context, _ ...model.QueryOptions) (int64, error) {
 	return int64(len(m.All)), nil
 }
 
-func (m *MockAlbumRepo) GetTouchedAlbums(libID int) (model.AlbumCursor, error) {
+func (m *MockAlbumRepo) GetTouchedAlbums(_ context.Context, libID int) (model.AlbumCursor, error) {
 	if m.Err {
 		return nil, errors.New("unexpected error")
 	}
@@ -135,11 +136,11 @@ func (m *MockAlbumRepo) GetTouchedAlbums(libID int) (model.AlbumCursor, error) {
 	}, nil
 }
 
-func (m *MockAlbumRepo) UpdateExternalInfo(album *model.Album) error {
-	return m.Put(album)
+func (m *MockAlbumRepo) UpdateExternalInfo(ctx context.Context, album *model.Album) error {
+	return m.Put(ctx, album)
 }
 
-func (m *MockAlbumRepo) Search(q string, options ...model.QueryOptions) (model.Albums, error) {
+func (m *MockAlbumRepo) Search(_ context.Context, q string, options ...model.QueryOptions) (model.Albums, error) {
 	m.SearchQuery = q
 	if len(options) > 0 {
 		m.Options = options[0]
@@ -152,7 +153,7 @@ func (m *MockAlbumRepo) Search(q string, options ...model.QueryOptions) (model.A
 }
 
 // ReassignAnnotation reassigns annotations from one album to another
-func (m *MockAlbumRepo) ReassignAnnotation(prevID string, newID string) error {
+func (m *MockAlbumRepo) ReassignAnnotation(_ context.Context, prevID string, newID string) error {
 	if m.Err {
 		return errors.New("unexpected error")
 	}
@@ -165,7 +166,7 @@ func (m *MockAlbumRepo) ReassignAnnotation(prevID string, newID string) error {
 }
 
 // CopyAttributes copies attributes from one album to another
-func (m *MockAlbumRepo) CopyAttributes(fromID, toID string, columns ...string) error {
+func (m *MockAlbumRepo) CopyAttributes(_ context.Context, fromID, toID string, columns ...string) error {
 	if m.Err {
 		return errors.New("unexpected error")
 	}
@@ -191,7 +192,7 @@ func (m *MockAlbumRepo) CopyAttributes(fromID, toID string, columns ...string) e
 }
 
 // SetRating sets the rating for an album
-func (m *MockAlbumRepo) SetRating(rating int, itemID string) error {
+func (m *MockAlbumRepo) SetRating(_ context.Context, rating int, itemID string) error {
 	if m.Err {
 		return errors.New("unexpected error")
 	}
@@ -202,7 +203,7 @@ func (m *MockAlbumRepo) SetRating(rating int, itemID string) error {
 }
 
 // SetStar sets the starred status for albums
-func (m *MockAlbumRepo) SetStar(starred bool, itemIDs ...string) error {
+func (m *MockAlbumRepo) SetStar(_ context.Context, starred bool, itemIDs ...string) error {
 	if m.Err {
 		return errors.New("unexpected error")
 	}
@@ -214,7 +215,7 @@ func (m *MockAlbumRepo) SetStar(starred bool, itemIDs ...string) error {
 	return nil
 }
 
-func (m *MockAlbumRepo) GetYears(libraryIDs ...int) ([]int, error) {
+func (m *MockAlbumRepo) GetYears(_ context.Context, libraryIDs ...int) ([]int, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
diff --git a/tests/mock_artist_repo.go b/tests/mock_artist_repo.go
index db7d54d5d..fe63edd94 100644
--- a/tests/mock_artist_repo.go
+++ b/tests/mock_artist_repo.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"errors"
 	"time"
 
@@ -32,7 +33,7 @@ func (m *MockArtistRepo) SetData(artists model.Artists) {
 	}
 }
 
-func (m *MockArtistRepo) Exists(id string) (bool, error) {
+func (m *MockArtistRepo) Exists(_ context.Context, id string) (bool, error) {
 	if m.Err {
 		return false, errors.New("Error!")
 	}
@@ -40,7 +41,7 @@ func (m *MockArtistRepo) Exists(id string) (bool, error) {
 	return found, nil
 }
 
-func (m *MockArtistRepo) Get(id string) (*model.Artist, error) {
+func (m *MockArtistRepo) Get(_ context.Context, id string) (*model.Artist, error) {
 	if m.Err {
 		return nil, errors.New("Error!")
 	}
@@ -50,7 +51,7 @@ func (m *MockArtistRepo) Get(id string) (*model.Artist, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockArtistRepo) Put(ar *model.Artist, columsToUpdate ...string) error {
+func (m *MockArtistRepo) Put(_ context.Context, ar *model.Artist, columsToUpdate ...string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -64,7 +65,7 @@ func (m *MockArtistRepo) Put(ar *model.Artist, columsToUpdate ...string) error {
 	return nil
 }
 
-func (m *MockArtistRepo) IncPlayCount(id string, timestamp time.Time) error {
+func (m *MockArtistRepo) IncPlayCount(_ context.Context, id string, timestamp time.Time) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -76,7 +77,7 @@ func (m *MockArtistRepo) IncPlayCount(id string, timestamp time.Time) error {
 	return model.ErrNotFound
 }
 
-func (m *MockArtistRepo) SetStar(starred bool, itemIDs ...string) error {
+func (m *MockArtistRepo) SetStar(_ context.Context, starred bool, itemIDs ...string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -88,7 +89,7 @@ func (m *MockArtistRepo) SetStar(starred bool, itemIDs ...string) error {
 	return nil
 }
 
-func (m *MockArtistRepo) SetRating(rating int, itemID string) error {
+func (m *MockArtistRepo) SetRating(_ context.Context, rating int, itemID string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -98,7 +99,7 @@ func (m *MockArtistRepo) SetRating(rating int, itemID string) error {
 	return nil
 }
 
-func (m *MockArtistRepo) GetAll(options ...model.QueryOptions) (model.Artists, error) {
+func (m *MockArtistRepo) GetAll(_ context.Context, options ...model.QueryOptions) (model.Artists, error) {
 	if len(options) > 0 {
 		m.Options = options[0]
 	}
@@ -116,8 +117,8 @@ func (m *MockArtistRepo) GetAll(options ...model.QueryOptions) (model.Artists, e
 	return allArtists, nil
 }
 
-func (m *MockArtistRepo) GetCursor(options ...model.QueryOptions) (model.ArtistCursor, error) {
-	res, err := m.GetAll(options...)
+func (m *MockArtistRepo) GetCursor(ctx context.Context, options ...model.QueryOptions) (model.ArtistCursor, error) {
+	res, err := m.GetAll(ctx, options...)
 	if err != nil {
 		return nil, err
 	}
@@ -130,30 +131,30 @@ func (m *MockArtistRepo) GetCursor(options ...model.QueryOptions) (model.ArtistC
 	}, nil
 }
 
-func (m *MockArtistRepo) UpdateExternalInfo(artist *model.Artist) error {
-	return m.Put(artist)
+func (m *MockArtistRepo) UpdateExternalInfo(ctx context.Context, artist *model.Artist) error {
+	return m.Put(ctx, artist)
 }
 
-func (m *MockArtistRepo) RefreshStats(allArtists bool) (int64, error) {
+func (m *MockArtistRepo) RefreshStats(_ context.Context, allArtists bool) (int64, error) {
 	if m.Err {
 		return 0, errors.New("mock repo error")
 	}
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockArtistRepo) RefreshPlayCounts() (int64, error) {
+func (m *MockArtistRepo) RefreshPlayCounts(_ context.Context) (int64, error) {
 	if m.Err {
 		return 0, errors.New("mock repo error")
 	}
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockArtistRepo) GetIndex(includeMissing bool, libraryIds []int, roles ...model.Role) (model.ArtistIndexes, error) {
+func (m *MockArtistRepo) GetIndex(ctx context.Context, includeMissing bool, libraryIds []int, roles ...model.Role) (model.ArtistIndexes, error) {
 	if m.Err {
 		return nil, errors.New("mock repo error")
 	}
 
-	artists, err := m.GetAll()
+	artists, err := m.GetAll(ctx)
 	if err != nil {
 		return nil, err
 	}
@@ -181,14 +182,14 @@ func (m *MockArtistRepo) GetIndex(includeMissing bool, libraryIds []int, roles .
 	return result, nil
 }
 
-func (m *MockArtistRepo) CountAll(...model.QueryOptions) (int64, error) {
+func (m *MockArtistRepo) CountAll(context.Context, ...model.QueryOptions) (int64, error) {
 	if m.Err {
 		return 0, errors.New("mock repo error")
 	}
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockArtistRepo) Search(q string, options ...model.QueryOptions) (model.Artists, error) {
+func (m *MockArtistRepo) Search(ctx context.Context, q string, options ...model.QueryOptions) (model.Artists, error) {
 	if len(options) > 0 {
 		m.Options = options[0]
 	}
@@ -196,7 +197,7 @@ func (m *MockArtistRepo) Search(q string, options ...model.QueryOptions) (model.
 		return nil, errors.New("unexpected error")
 	}
 	// Simple mock implementation - just return all artists for testing
-	return m.GetAll()
+	return m.GetAll(ctx)
 }
 
 var _ model.ArtistRepository = (*MockArtistRepo)(nil)
diff --git a/tests/mock_artwork_queue_repo.go b/tests/mock_artwork_queue_repo.go
index c482e2150..c6a7917f0 100644
--- a/tests/mock_artwork_queue_repo.go
+++ b/tests/mock_artwork_queue_repo.go
@@ -2,6 +2,7 @@ package tests
 
 import (
 	"cmp"
+	"context"
 	"slices"
 	"sync"
 	"time"
@@ -26,7 +27,7 @@ func CreateMockArtworkQueueRepo() *MockArtworkQueueRepo {
 	return &MockArtworkQueueRepo{Data: map[string]model.ArtworkQueueItem{}}
 }
 
-func (m *MockArtworkQueueRepo) Get(kind model.Kind, id, imageType string) (*model.ArtworkQueueItem, error) {
+func (m *MockArtworkQueueRepo) Get(_ context.Context, kind model.Kind, id, imageType string) (*model.ArtworkQueueItem, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -39,7 +40,7 @@ func (m *MockArtworkQueueRepo) Get(kind model.Kind, id, imageType string) (*mode
 	return &it, nil
 }
 
-func (m *MockArtworkQueueRepo) Enqueue(items ...model.ArtworkQueueItem) error {
+func (m *MockArtworkQueueRepo) Enqueue(_ context.Context, items ...model.ArtworkQueueItem) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -73,7 +74,7 @@ func (m *MockArtworkQueueRepo) enqueueLocked(items []model.ArtworkQueueItem) {
 }
 
 // EnqueueIfMissing mirrors the SQL anti-join: skip anything that already has an item_artwork row.
-func (m *MockArtworkQueueRepo) EnqueueIfMissing(items ...model.ArtworkQueueItem) error {
+func (m *MockArtworkQueueRepo) EnqueueIfMissing(_ context.Context, items ...model.ArtworkQueueItem) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -96,7 +97,7 @@ func (m *MockArtworkQueueRepo) EnqueueIfMissing(items ...model.ArtworkQueueItem)
 	return nil
 }
 
-func (m *MockArtworkQueueRepo) DequeueBatch(n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
+func (m *MockArtworkQueueRepo) DequeueBatch(_ context.Context, n int, kinds ...string) ([]model.ArtworkQueueItem, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -118,7 +119,7 @@ func (m *MockArtworkQueueRepo) DequeueBatch(n int, kinds ...string) ([]model.Art
 	return res, nil
 }
 
-func (m *MockArtworkQueueRepo) MarkFailedIfUnchanged(kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error {
+func (m *MockArtworkQueueRepo) MarkFailedIfUnchanged(_ context.Context, kind, id, imageType string, seenRetryAt, retryAt time.Time, trace string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -134,7 +135,7 @@ func (m *MockArtworkQueueRepo) MarkFailedIfUnchanged(kind, id, imageType string,
 	return nil
 }
 
-func (m *MockArtworkQueueRepo) DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) error {
+func (m *MockArtworkQueueRepo) DeleteIfUnchanged(_ context.Context, kind, id, imageType string, retryAt time.Time) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -147,7 +148,7 @@ func (m *MockArtworkQueueRepo) DeleteIfUnchanged(kind, id, imageType string, ret
 	return nil
 }
 
-func (m *MockArtworkQueueRepo) PurgeDangling() (int64, error) {
+func (m *MockArtworkQueueRepo) PurgeDangling(context.Context) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -174,7 +175,7 @@ func queueFilterMatches(it model.ArtworkQueueItem, kinds []model.Kind, prioritie
 		(len(priorities) == 0 || slices.Contains(priorities, it.Priority))
 }
 
-func (m *MockArtworkQueueRepo) PurgeQueued(kinds []model.Kind, priorities []int) (int64, error) {
+func (m *MockArtworkQueueRepo) PurgeQueued(_ context.Context, kinds []model.Kind, priorities []int) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -191,7 +192,7 @@ func (m *MockArtworkQueueRepo) PurgeQueued(kinds []model.Kind, priorities []int)
 	return purged, nil
 }
 
-func (m *MockArtworkQueueRepo) Count() (int64, error) {
+func (m *MockArtworkQueueRepo) Count(context.Context) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -200,7 +201,7 @@ func (m *MockArtworkQueueRepo) Count() (int64, error) {
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockArtworkQueueRepo) CountQueued(kinds []model.Kind, priorities []int) ([]model.ArtworkQueueStat, error) {
+func (m *MockArtworkQueueRepo) CountQueued(_ context.Context, kinds []model.Kind, priorities []int) ([]model.ArtworkQueueStat, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -226,7 +227,7 @@ func (m *MockArtworkQueueRepo) CountQueued(kinds []model.Kind, priorities []int)
 	return res, nil
 }
 
-func (m *MockArtworkQueueRepo) EnqueuePreservingBackoff(items ...model.ArtworkQueueItem) error {
+func (m *MockArtworkQueueRepo) EnqueuePreservingBackoff(_ context.Context, items ...model.ArtworkQueueItem) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -276,7 +277,7 @@ func (m *MockArtworkQueueRepo) matchingSource(kind model.Kind, sources []string)
 	return res
 }
 
-func (m *MockArtworkQueueRepo) CountBySource(kind model.Kind, sources []string) (int64, error) {
+func (m *MockArtworkQueueRepo) CountBySource(_ context.Context, kind model.Kind, sources []string) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -285,7 +286,7 @@ func (m *MockArtworkQueueRepo) CountBySource(kind model.Kind, sources []string)
 	return int64(len(m.matchingSource(kind, sources))), nil
 }
 
-func (m *MockArtworkQueueRepo) SourcesInUse(kind model.Kind) ([]string, error) {
+func (m *MockArtworkQueueRepo) SourcesInUse(_ context.Context, kind model.Kind) ([]string, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -295,7 +296,7 @@ func (m *MockArtworkQueueRepo) SourcesInUse(kind model.Kind) ([]string, error) {
 	return slice.Unique(sources), nil
 }
 
-func (m *MockArtworkQueueRepo) EnqueueBySource(kind model.Kind, sources []string, priority int) (int64, error) {
+func (m *MockArtworkQueueRepo) EnqueueBySource(_ context.Context, kind model.Kind, sources []string, priority int) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -322,7 +323,7 @@ func (m *MockArtworkQueueRepo) EnqueueBySource(kind model.Kind, sources []string
 }
 
 // EnqueueAllMissing mirrors the SQL set-difference insert: ExistingIDs[kind] minus ItemArtworkSource.
-func (m *MockArtworkQueueRepo) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {
+func (m *MockArtworkQueueRepo) EnqueueAllMissing(_ context.Context, kind model.Kind, priority int) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
diff --git a/tests/mock_artwork_repo.go b/tests/mock_artwork_repo.go
index 5d76a0169..350c0e9f6 100644
--- a/tests/mock_artwork_repo.go
+++ b/tests/mock_artwork_repo.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"maps"
 	"sync"
 	"time"
@@ -26,7 +27,7 @@ func CreateMockArtworkRepo() *MockArtworkRepo {
 
 func iaKey(kind, id, imageType string) string { return kind + "|" + id + "|" + imageType }
 
-func (m *MockArtworkRepo) GetImage(hash string) (*model.Artwork, error) {
+func (m *MockArtworkRepo) GetImage(_ context.Context, hash string) (*model.Artwork, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -38,7 +39,7 @@ func (m *MockArtworkRepo) GetImage(hash string) (*model.Artwork, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockArtworkRepo) PutImage(a *model.Artwork) error {
+func (m *MockArtworkRepo) PutImage(_ context.Context, a *model.Artwork) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -50,7 +51,7 @@ func (m *MockArtworkRepo) PutImage(a *model.Artwork) error {
 	return nil
 }
 
-func (m *MockArtworkRepo) GetMimeByHash() (map[string]string, error) {
+func (m *MockArtworkRepo) GetMimeByHash(context.Context) (map[string]string, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -63,7 +64,7 @@ func (m *MockArtworkRepo) GetMimeByHash() (map[string]string, error) {
 	return mimes, nil
 }
 
-func (m *MockArtworkRepo) PurgeDanglingItems() (int64, error) {
+func (m *MockArtworkRepo) PurgeDanglingItems(context.Context) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -84,7 +85,7 @@ func (m *MockArtworkRepo) PurgeDanglingItems() (int64, error) {
 	return purged, nil
 }
 
-func (m *MockArtworkRepo) PurgeOrphans(createdBefore time.Time) (int64, error) {
+func (m *MockArtworkRepo) PurgeOrphans(_ context.Context, createdBefore time.Time) (int64, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -110,7 +111,7 @@ func (m *MockArtworkRepo) referenced(hash string) bool {
 	return false
 }
 
-func (m *MockArtworkRepo) GetItemArtwork(kind model.Kind, id, imageType string) (*model.ItemArtwork, error) {
+func (m *MockArtworkRepo) GetItemArtwork(_ context.Context, kind model.Kind, id, imageType string) (*model.ItemArtwork, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -122,7 +123,7 @@ func (m *MockArtworkRepo) GetItemArtwork(kind model.Kind, id, imageType string)
 	return nil, model.ErrNotFound
 }
 
-func (m *MockArtworkRepo) PutLastFailure(kind model.Kind, id, imageType, trace string) error {
+func (m *MockArtworkRepo) PutLastFailure(_ context.Context, kind model.Kind, id, imageType, trace string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -136,7 +137,7 @@ func (m *MockArtworkRepo) PutLastFailure(kind model.Kind, id, imageType, trace s
 	return nil
 }
 
-func (m *MockArtworkRepo) PutItemArtwork(ia *model.ItemArtwork) error {
+func (m *MockArtworkRepo) PutItemArtwork(_ context.Context, ia *model.ItemArtwork) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -153,7 +154,7 @@ func (m *MockArtworkRepo) PutItemArtwork(ia *model.ItemArtwork) error {
 	return nil
 }
 
-func (m *MockArtworkRepo) DeleteForItems(kind model.Kind, ids []string) error {
+func (m *MockArtworkRepo) DeleteForItems(_ context.Context, kind model.Kind, ids []string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
@@ -167,7 +168,7 @@ func (m *MockArtworkRepo) DeleteForItems(kind model.Kind, ids []string) error {
 	return nil
 }
 
-func (m *MockArtworkRepo) GetInfoForItems(kind model.Kind, ids []string) (map[string]model.ItemArtworkInfo, error) {
+func (m *MockArtworkRepo) GetInfoForItems(_ context.Context, kind model.Kind, ids []string) (map[string]model.ItemArtworkInfo, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	if m.Err != nil {
diff --git a/tests/mock_data_store.go b/tests/mock_data_store.go
index 6a0ebbb31..db798eece 100644
--- a/tests/mock_data_store.go
+++ b/tests/mock_data_store.go
@@ -38,76 +38,76 @@ type MockDataStore struct {
 	GCError  error
 }
 
-func (db *MockDataStore) Library(ctx context.Context) model.LibraryRepository {
+func (db *MockDataStore) Library() model.LibraryRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedLibrary != nil {
 		return db.MockedLibrary
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Library(ctx)
+		return db.RealDS.Library()
 	}
 	db.MockedLibrary = &MockLibraryRepo{}
 	return db.MockedLibrary
 }
 
-func (db *MockDataStore) Folder(ctx context.Context) model.FolderRepository {
+func (db *MockDataStore) Folder() model.FolderRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedFolder != nil {
 		return db.MockedFolder
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Folder(ctx)
+		return db.RealDS.Folder()
 	}
 	db.MockedFolder = struct{ model.FolderRepository }{}
 	return db.MockedFolder
 }
 
-func (db *MockDataStore) Tag(ctx context.Context) model.TagRepository {
+func (db *MockDataStore) Tag() model.TagRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedTag != nil {
 		return db.MockedTag
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Tag(ctx)
+		return db.RealDS.Tag()
 	}
 	db.MockedTag = &MockTagRepo{}
 	return db.MockedTag
 }
 
-func (db *MockDataStore) Album(ctx context.Context) model.AlbumRepository {
+func (db *MockDataStore) Album() model.AlbumRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedAlbum != nil {
 		return db.MockedAlbum
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Album(ctx)
+		return db.RealDS.Album()
 	}
 	db.MockedAlbum = CreateMockAlbumRepo()
 	return db.MockedAlbum
 }
 
-func (db *MockDataStore) Artist(ctx context.Context) model.ArtistRepository {
+func (db *MockDataStore) Artist() model.ArtistRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedArtist != nil {
 		return db.MockedArtist
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Artist(ctx)
+		return db.RealDS.Artist()
 	}
 	db.MockedArtist = CreateMockArtistRepo()
 	return db.MockedArtist
 }
 
-func (db *MockDataStore) MediaFile(ctx context.Context) model.MediaFileRepository {
+func (db *MockDataStore) MediaFile() model.MediaFileRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.RealDS != nil && db.MockedMediaFile == nil {
-		return db.RealDS.MediaFile(ctx)
+		return db.RealDS.MediaFile()
 	}
 	if db.MockedMediaFile == nil {
 		db.MockedMediaFile = CreateMockMediaFileRepo()
@@ -115,128 +115,128 @@ func (db *MockDataStore) MediaFile(ctx context.Context) model.MediaFileRepositor
 	return db.MockedMediaFile
 }
 
-func (db *MockDataStore) Genre(ctx context.Context) model.GenreRepository {
+func (db *MockDataStore) Genre() model.GenreRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedGenre != nil {
 		return db.MockedGenre
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Genre(ctx)
+		return db.RealDS.Genre()
 	}
 	db.MockedGenre = &MockedGenreRepo{}
 	return db.MockedGenre
 }
 
-func (db *MockDataStore) Playlist(ctx context.Context) model.PlaylistRepository {
+func (db *MockDataStore) Playlist() model.PlaylistRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedPlaylist != nil {
 		return db.MockedPlaylist
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Playlist(ctx)
+		return db.RealDS.Playlist()
 	}
 	db.MockedPlaylist = CreateMockPlaylistRepo()
 	return db.MockedPlaylist
 }
 
-func (db *MockDataStore) PlayQueue(ctx context.Context) model.PlayQueueRepository {
+func (db *MockDataStore) PlayQueue() model.PlayQueueRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedPlayQueue != nil {
 		return db.MockedPlayQueue
 	}
 	if db.RealDS != nil {
-		return db.RealDS.PlayQueue(ctx)
+		return db.RealDS.PlayQueue()
 	}
 	db.MockedPlayQueue = &MockPlayQueueRepo{}
 	return db.MockedPlayQueue
 }
 
-func (db *MockDataStore) UserProps(ctx context.Context) model.UserPropsRepository {
+func (db *MockDataStore) UserProps() model.UserPropsRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedUserProps != nil {
 		return db.MockedUserProps
 	}
 	if db.RealDS != nil {
-		return db.RealDS.UserProps(ctx)
+		return db.RealDS.UserProps()
 	}
 	db.MockedUserProps = &MockedUserPropsRepo{}
 	return db.MockedUserProps
 }
 
-func (db *MockDataStore) Property(ctx context.Context) model.PropertyRepository {
+func (db *MockDataStore) Property() model.PropertyRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedProperty != nil {
 		return db.MockedProperty
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Property(ctx)
+		return db.RealDS.Property()
 	}
 	db.MockedProperty = &MockedPropertyRepo{}
 	return db.MockedProperty
 }
 
-func (db *MockDataStore) Share(ctx context.Context) model.ShareRepository {
+func (db *MockDataStore) Share() model.ShareRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedShare != nil {
 		return db.MockedShare
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Share(ctx)
+		return db.RealDS.Share()
 	}
 	db.MockedShare = &MockShareRepo{}
 	return db.MockedShare
 }
 
-func (db *MockDataStore) User(ctx context.Context) model.UserRepository {
+func (db *MockDataStore) User() model.UserRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedUser != nil {
 		return db.MockedUser
 	}
 	if db.RealDS != nil {
-		return db.RealDS.User(ctx)
+		return db.RealDS.User()
 	}
 	db.MockedUser = CreateMockUserRepo()
 	return db.MockedUser
 }
 
-func (db *MockDataStore) Transcoding(ctx context.Context) model.TranscodingRepository {
+func (db *MockDataStore) Transcoding() model.TranscodingRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedTranscoding != nil {
 		return db.MockedTranscoding
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Transcoding(ctx)
+		return db.RealDS.Transcoding()
 	}
 	db.MockedTranscoding = struct{ model.TranscodingRepository }{}
 	return db.MockedTranscoding
 }
 
-func (db *MockDataStore) Player(ctx context.Context) model.PlayerRepository {
+func (db *MockDataStore) Player() model.PlayerRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedPlayer != nil {
 		return db.MockedPlayer
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Player(ctx)
+		return db.RealDS.Player()
 	}
 	db.MockedPlayer = struct{ model.PlayerRepository }{}
 	return db.MockedPlayer
 }
 
-func (db *MockDataStore) ScrobbleBuffer(ctx context.Context) model.ScrobbleBufferRepository {
+func (db *MockDataStore) ScrobbleBuffer() model.ScrobbleBufferRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.RealDS != nil && db.MockedScrobbleBuffer == nil {
-		return db.RealDS.ScrobbleBuffer(ctx)
+		return db.RealDS.ScrobbleBuffer()
 	}
 	db.scrobbleBufferMu.Lock()
 	defer db.scrobbleBufferMu.Unlock()
@@ -246,75 +246,75 @@ func (db *MockDataStore) ScrobbleBuffer(ctx context.Context) model.ScrobbleBuffe
 	return db.MockedScrobbleBuffer
 }
 
-func (db *MockDataStore) Scrobble(ctx context.Context) model.ScrobbleRepository {
+func (db *MockDataStore) Scrobble() model.ScrobbleRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedScrobble != nil {
 		return db.MockedScrobble
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Scrobble(ctx)
+		return db.RealDS.Scrobble()
 	}
-	db.MockedScrobble = &MockScrobbleRepo{ctx: ctx}
+	db.MockedScrobble = &MockScrobbleRepo{}
 	return db.MockedScrobble
 }
 
-func (db *MockDataStore) Radio(ctx context.Context) model.RadioRepository {
+func (db *MockDataStore) Radio() model.RadioRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedRadio != nil {
 		return db.MockedRadio
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Radio(ctx)
+		return db.RealDS.Radio()
 	}
 	db.MockedRadio = CreateMockedRadioRepo()
 	return db.MockedRadio
 }
 
-func (db *MockDataStore) Plugin(ctx context.Context) model.PluginRepository {
+func (db *MockDataStore) Plugin() model.PluginRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedPlugin != nil {
 		return db.MockedPlugin
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Plugin(ctx)
+		return db.RealDS.Plugin()
 	}
 	db.MockedPlugin = CreateMockPluginRepo()
 	return db.MockedPlugin
 }
 
-func (db *MockDataStore) Artwork(ctx context.Context) model.ArtworkRepository {
+func (db *MockDataStore) Artwork() model.ArtworkRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
-	return db.artworkLocked(ctx)
+	return db.artworkLocked()
 }
 
 // artworkLocked is the body of Artwork for callers already holding repoMu; repoMu is a plain
 // Mutex, so re-entering through the exported method would deadlock.
-func (db *MockDataStore) artworkLocked(ctx context.Context) model.ArtworkRepository {
+func (db *MockDataStore) artworkLocked() model.ArtworkRepository {
 	if db.MockedArtwork != nil {
 		return db.MockedArtwork
 	}
 	if db.RealDS != nil {
-		return db.RealDS.Artwork(ctx)
+		return db.RealDS.Artwork()
 	}
 	db.MockedArtwork = CreateMockArtworkRepo()
 	return db.MockedArtwork
 }
 
-func (db *MockDataStore) ArtworkQueue(ctx context.Context) model.ArtworkQueueRepository {
+func (db *MockDataStore) ArtworkQueue() model.ArtworkQueueRepository {
 	db.repoMu.Lock()
 	defer db.repoMu.Unlock()
 	if db.MockedArtworkQueue != nil {
 		return db.MockedArtworkQueue
 	}
 	if db.RealDS != nil {
-		return db.RealDS.ArtworkQueue(ctx)
+		return db.RealDS.ArtworkQueue()
 	}
 	q := CreateMockArtworkQueueRepo()
-	if aw, ok := db.artworkLocked(ctx).(*MockArtworkRepo); ok {
+	if aw, ok := db.artworkLocked().(*MockArtworkRepo); ok {
 		q.ItemArtworkSource = aw
 	}
 	db.MockedArtworkQueue = q
@@ -333,37 +333,6 @@ func (db *MockDataStore) WithTxRetry(ctx context.Context, block func(ctx context
 	return block(ctx, db)
 }
 
-func (db *MockDataStore) Resource(ctx context.Context, m any) model.ResourceRepository {
-	switch m.(type) {
-	case model.MediaFile, *model.MediaFile:
-		return db.MediaFile(ctx).(model.ResourceRepository)
-	case model.Album, *model.Album:
-		return db.Album(ctx).(model.ResourceRepository)
-	case model.Artist, *model.Artist:
-		return db.Artist(ctx).(model.ResourceRepository)
-	case model.User, *model.User:
-		return db.User(ctx).(model.ResourceRepository)
-	case model.Playlist, *model.Playlist:
-		return db.Playlist(ctx).(model.ResourceRepository)
-	case model.Radio, *model.Radio:
-		return db.Radio(ctx).(model.ResourceRepository)
-	case model.Share, *model.Share:
-		return db.Share(ctx).(model.ResourceRepository)
-	case model.Genre, *model.Genre:
-		return db.Genre(ctx).(model.ResourceRepository)
-	case model.Tag, *model.Tag:
-		return db.Tag(ctx).(model.ResourceRepository)
-	case model.Transcoding, *model.Transcoding:
-		return db.Transcoding(ctx).(model.ResourceRepository)
-	case model.Player, *model.Player:
-		return db.Player(ctx).(model.ResourceRepository)
-	case model.Plugin, *model.Plugin:
-		return db.Plugin(ctx).(model.ResourceRepository)
-	default:
-		return struct{ model.ResourceRepository }{}
-	}
-}
-
 func (db *MockDataStore) GC(context.Context, ...int) error {
 	db.GCCalled = true
 	if db.GCError != nil {
diff --git a/tests/mock_genre_repo.go b/tests/mock_genre_repo.go
index ad3ee1a6a..917e2c626 100644
--- a/tests/mock_genre_repo.go
+++ b/tests/mock_genre_repo.go
@@ -1,6 +1,9 @@
 package tests
 
 import (
+	"context"
+
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model"
 )
 
@@ -16,7 +19,7 @@ func (r *MockedGenreRepo) init() {
 	}
 }
 
-func (r *MockedGenreRepo) GetAll(options ...model.QueryOptions) (model.Genres, error) {
+func (r *MockedGenreRepo) GetAll(_ context.Context, options ...model.QueryOptions) (model.Genres, error) {
 	if len(options) > 0 {
 		r.Options = options[0]
 	}
@@ -32,7 +35,7 @@ func (r *MockedGenreRepo) GetAll(options ...model.QueryOptions) (model.Genres, e
 	return all, nil
 }
 
-func (r *MockedGenreRepo) Get(id string) (*model.Genre, error) {
+func (r *MockedGenreRepo) Get(_ context.Context, id string) (*model.Genre, error) {
 	if r.Error != nil {
 		return nil, r.Error
 	}
@@ -51,3 +54,21 @@ func (r *MockedGenreRepo) Put(g *model.Genre) error {
 	r.Data[g.ID] = *g
 	return nil
 }
+
+func (r *MockedGenreRepo) Count(context.Context, ...rest.QueryOptions) (int64, error) {
+	if r.Error != nil {
+		return 0, r.Error
+	}
+	r.init()
+	return int64(len(r.Data)), nil
+}
+
+func (r *MockedGenreRepo) Read(ctx context.Context, id string) (*model.Genre, error) {
+	return r.Get(ctx, id)
+}
+
+func (r *MockedGenreRepo) ReadAll(ctx context.Context, _ ...rest.QueryOptions) ([]model.Genre, error) {
+	return r.GetAll(ctx)
+}
+
+var _ model.GenreRepository = (*MockedGenreRepo)(nil)
diff --git a/tests/mock_library_repo.go b/tests/mock_library_repo.go
index 0f7af2aab..e21dcccce 100644
--- a/tests/mock_library_repo.go
+++ b/tests/mock_library_repo.go
@@ -27,7 +27,7 @@ func (m *MockLibraryRepo) SetData(data model.Libraries) {
 	}
 }
 
-func (m *MockLibraryRepo) GetAll(...model.QueryOptions) (model.Libraries, error) {
+func (m *MockLibraryRepo) GetAll(_ context.Context, _ ...model.QueryOptions) (model.Libraries, error) {
 	if m.Err != nil {
 		return nil, m.Err
 	}
@@ -42,7 +42,7 @@ func (m *MockLibraryRepo) GetAll(...model.QueryOptions) (model.Libraries, error)
 	return libraries, nil
 }
 
-func (m *MockLibraryRepo) CountAll(qo ...model.QueryOptions) (int64, error) {
+func (m *MockLibraryRepo) CountAll(_ context.Context, qo ...model.QueryOptions) (int64, error) {
 	if m.Err != nil {
 		return 0, m.Err
 	}
@@ -71,7 +71,7 @@ func (m *MockLibraryRepo) CountAll(qo ...model.QueryOptions) (int64, error) {
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockLibraryRepo) Get(id int) (*model.Library, error) {
+func (m *MockLibraryRepo) Get(_ context.Context, id int) (*model.Library, error) {
 	if m.Err != nil {
 		return nil, m.Err
 	}
@@ -81,7 +81,7 @@ func (m *MockLibraryRepo) Get(id int) (*model.Library, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockLibraryRepo) GetPath(id int) (string, error) {
+func (m *MockLibraryRepo) GetPath(_ context.Context, id int) (string, error) {
 	if m.Err != nil {
 		return "", m.Err
 	}
@@ -91,7 +91,7 @@ func (m *MockLibraryRepo) GetPath(id int) (string, error) {
 	return "", model.ErrNotFound
 }
 
-func (m *MockLibraryRepo) Put(library *model.Library, colsToUpdate ...string) error {
+func (m *MockLibraryRepo) Put(_ context.Context, library *model.Library, colsToUpdate ...string) error {
 	m.PutCols = colsToUpdate
 	if m.PutFn != nil {
 		return m.PutFn(library)
@@ -106,7 +106,7 @@ func (m *MockLibraryRepo) Put(library *model.Library, colsToUpdate ...string) er
 	return nil
 }
 
-func (m *MockLibraryRepo) Delete(id int) error {
+func (m *MockLibraryRepo) Delete(_ context.Context, id int) error {
 	if m.Err != nil {
 		return m.Err
 	}
@@ -117,48 +117,48 @@ func (m *MockLibraryRepo) Delete(id int) error {
 	return nil
 }
 
-func (m *MockLibraryRepo) StoreMusicFolder() error {
+func (m *MockLibraryRepo) StoreMusicFolder(_ context.Context) error {
 	if m.Err != nil {
 		return m.Err
 	}
 	return nil
 }
 
-func (m *MockLibraryRepo) AddArtist(id int, artistID string) error {
+func (m *MockLibraryRepo) AddArtist(_ context.Context, id int, artistID string) error {
 	if m.Err != nil {
 		return m.Err
 	}
 	return nil
 }
 
-func (m *MockLibraryRepo) ScanBegin(id int, fullScan bool) error {
+func (m *MockLibraryRepo) ScanBegin(_ context.Context, id int, fullScan bool) error {
 	if m.Err != nil {
 		return m.Err
 	}
 	return nil
 }
 
-func (m *MockLibraryRepo) ScanEnd(id int) error {
+func (m *MockLibraryRepo) ScanEnd(_ context.Context, id int) error {
 	if m.Err != nil {
 		return m.Err
 	}
 	return nil
 }
 
-func (m *MockLibraryRepo) ScanInProgress() (bool, error) {
+func (m *MockLibraryRepo) ScanInProgress(_ context.Context) (bool, error) {
 	if m.Err != nil {
 		return false, m.Err
 	}
 	return false, nil
 }
 
-func (m *MockLibraryRepo) RefreshStats(id int) error {
+func (m *MockLibraryRepo) RefreshStats(_ context.Context, id int) error {
 	return nil
 }
 
 // User-library association methods - mock implementations
 
-func (m *MockLibraryRepo) GetUsersWithLibraryAccess(libraryID int) (model.Users, error) {
+func (m *MockLibraryRepo) GetUsersWithLibraryAccess(_ context.Context, libraryID int) (model.Users, error) {
 	if m.Err != nil {
 		return nil, m.Err
 	}
@@ -166,31 +166,22 @@ func (m *MockLibraryRepo) GetUsersWithLibraryAccess(libraryID int) (model.Users,
 	return model.Users{}, nil
 }
 
-func (m *MockLibraryRepo) Count(options ...rest.QueryOptions) (int64, error) {
-	return m.CountAll()
+func (m *MockLibraryRepo) Count(ctx context.Context, _ ...rest.QueryOptions) (int64, error) {
+	return m.CountAll(ctx)
 }
 
-func (m *MockLibraryRepo) Read(id string) (any, error) {
+func (m *MockLibraryRepo) Read(ctx context.Context, id string) (*model.Library, error) {
 	idInt, _ := strconv.Atoi(id)
-	return m.Get(idInt)
+	return m.Get(ctx, idInt)
 }
 
-func (m *MockLibraryRepo) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return m.GetAll()
-}
-
-func (m *MockLibraryRepo) EntityName() string {
-	return "library"
-}
-
-func (m *MockLibraryRepo) NewInstance() any {
-	return &model.Library{}
+func (m *MockLibraryRepo) ReadAll(ctx context.Context, _ ...rest.QueryOptions) ([]model.Library, error) {
+	return m.GetAll(ctx)
 }
 
 // REST Repository methods (string-based IDs)
 
-func (m *MockLibraryRepo) Save(entity any) (string, error) {
-	lib := entity.(*model.Library)
+func (m *MockLibraryRepo) Save(_ context.Context, lib *model.Library) (string, error) {
 	if m.Err != nil {
 		return "", m.Err
 	}
@@ -214,8 +205,8 @@ func (m *MockLibraryRepo) Save(entity any) (string, error) {
 	return strconv.Itoa(lib.ID), nil
 }
 
-func (m *MockLibraryRepo) Update(id string, entity any, cols ...string) error {
-	lib := entity.(*model.Library)
+func (m *MockLibraryRepo) Update(_ context.Context, id string, entity model.Library, _ ...string) error {
+	lib := &entity
 	if m.Err != nil {
 		return m.Err
 	}
@@ -307,4 +298,4 @@ func (m *MockLibraryRepo) ValidateLibraryAccess(ctx context.Context, userID stri
 }
 
 var _ model.LibraryRepository = (*MockLibraryRepo)(nil)
-var _ model.ResourceRepository = (*MockLibraryRepo)(nil)
+var _ rest.Repository[model.Library] = (*MockLibraryRepo)(nil)
diff --git a/tests/mock_library_service.go b/tests/mock_library_service.go
index 78693197d..f5e1f0387 100644
--- a/tests/mock_library_service.go
+++ b/tests/mock_library_service.go
@@ -14,7 +14,7 @@ type MockLibraryService struct {
 	*MockLibraryRepo
 }
 
-// MockLibraryRestAdapter adapts MockLibraryRepo to rest.Repository interface
+// MockLibraryRestAdapter adapts MockLibraryRepo to the REST repository interface
 type MockLibraryRestAdapter struct {
 	*MockLibraryRepo
 }
@@ -33,12 +33,15 @@ func NewMockLibraryService() *MockLibraryService {
 	return &MockLibraryService{MockLibraryRepo: repo}
 }
 
-func (m *MockLibraryService) NewRepository(ctx context.Context) rest.Repository {
+func (m *MockLibraryService) Repository() rest.Repository[model.Library] {
 	return &MockLibraryRestAdapter{MockLibraryRepo: m.MockLibraryRepo}
 }
 
-// rest.Repository interface implementation
-
-func (a *MockLibraryRestAdapter) Delete(id string) error {
-	return a.DeleteByStringID(id)
+func (a *MockLibraryRestAdapter) Delete(_ context.Context, ids ...string) error {
+	for _, id := range ids {
+		if err := a.DeleteByStringID(id); err != nil {
+			return err
+		}
+	}
+	return nil
 }
diff --git a/tests/mock_mediafile_repo.go b/tests/mock_mediafile_repo.go
index 2093a007d..392a4d8e0 100644
--- a/tests/mock_mediafile_repo.go
+++ b/tests/mock_mediafile_repo.go
@@ -2,6 +2,7 @@ package tests
 
 import (
 	"cmp"
+	"context"
 	"errors"
 	"maps"
 	"slices"
@@ -55,7 +56,7 @@ func (m *MockMediaFileRepo) SetData(mfs model.MediaFiles) {
 	}
 }
 
-func (m *MockMediaFileRepo) Exists(id string) (bool, error) {
+func (m *MockMediaFileRepo) Exists(_ context.Context, id string) (bool, error) {
 	if m.Err {
 		return false, errors.New("error")
 	}
@@ -63,7 +64,7 @@ func (m *MockMediaFileRepo) Exists(id string) (bool, error) {
 	return found, nil
 }
 
-func (m *MockMediaFileRepo) Get(id string) (*model.MediaFile, error) {
+func (m *MockMediaFileRepo) Get(_ context.Context, id string) (*model.MediaFile, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -77,7 +78,7 @@ func (m *MockMediaFileRepo) Get(id string) (*model.MediaFile, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockMediaFileRepo) AddBookmark(id, _ string, _ int64) error {
+func (m *MockMediaFileRepo) AddBookmark(_ context.Context, id, _ string, _ int64) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -85,7 +86,7 @@ func (m *MockMediaFileRepo) AddBookmark(id, _ string, _ int64) error {
 	return nil
 }
 
-func (m *MockMediaFileRepo) GetWithParticipants(id string) (*model.MediaFile, error) {
+func (m *MockMediaFileRepo) GetWithParticipants(_ context.Context, id string) (*model.MediaFile, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -95,11 +96,11 @@ func (m *MockMediaFileRepo) GetWithParticipants(id string) (*model.MediaFile, er
 	return nil, model.ErrNotFound
 }
 
-func (m *MockMediaFileRepo) GetAllByTags(_ model.TagName, _ []string, options ...model.QueryOptions) (model.MediaFiles, error) {
-	return m.GetAll(options...)
+func (m *MockMediaFileRepo) GetAllByTags(ctx context.Context, _ model.TagName, _ []string, options ...model.QueryOptions) (model.MediaFiles, error) {
+	return m.GetAll(ctx, options...)
 }
 
-func (m *MockMediaFileRepo) GetAll(qo ...model.QueryOptions) (model.MediaFiles, error) {
+func (m *MockMediaFileRepo) GetAll(_ context.Context, qo ...model.QueryOptions) (model.MediaFiles, error) {
 	if len(qo) > 0 {
 		m.Options = qo[0]
 	}
@@ -117,8 +118,8 @@ func (m *MockMediaFileRepo) GetAll(qo ...model.QueryOptions) (model.MediaFiles,
 	return result, nil
 }
 
-func (m *MockMediaFileRepo) GetRandom(qo ...model.QueryOptions) (model.MediaFiles, error) {
-	res, err := m.GetAll(qo...)
+func (m *MockMediaFileRepo) GetRandom(ctx context.Context, qo ...model.QueryOptions) (model.MediaFiles, error) {
+	res, err := m.GetAll(ctx, qo...)
 	if err != nil {
 		return nil, err
 	}
@@ -128,8 +129,8 @@ func (m *MockMediaFileRepo) GetRandom(qo ...model.QueryOptions) (model.MediaFile
 	return res, nil
 }
 
-func (m *MockMediaFileRepo) GetCursor(qo ...model.QueryOptions) (model.MediaFileCursor, error) {
-	res, err := m.GetAll(qo...)
+func (m *MockMediaFileRepo) GetCursor(ctx context.Context, qo ...model.QueryOptions) (model.MediaFileCursor, error) {
+	res, err := m.GetAll(ctx, qo...)
 	if err != nil {
 		return nil, err
 	}
@@ -142,11 +143,11 @@ func (m *MockMediaFileRepo) GetCursor(qo ...model.QueryOptions) (model.MediaFile
 	}, nil
 }
 
-func (m *MockMediaFileRepo) GetCursorWithArtwork(qo ...model.QueryOptions) (model.MediaFileCursor, error) {
-	return m.GetCursor(qo...)
+func (m *MockMediaFileRepo) GetCursorWithArtwork(ctx context.Context, qo ...model.QueryOptions) (model.MediaFileCursor, error) {
+	return m.GetCursor(ctx, qo...)
 }
 
-func (m *MockMediaFileRepo) Put(mf *model.MediaFile) error {
+func (m *MockMediaFileRepo) Put(_ context.Context, mf *model.MediaFile) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -157,7 +158,7 @@ func (m *MockMediaFileRepo) Put(mf *model.MediaFile) error {
 	return nil
 }
 
-func (m *MockMediaFileRepo) UpdateProbeData(id string, data string) error {
+func (m *MockMediaFileRepo) UpdateProbeData(_ context.Context, id string, data string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -168,7 +169,7 @@ func (m *MockMediaFileRepo) UpdateProbeData(id string, data string) error {
 	return model.ErrNotFound
 }
 
-func (m *MockMediaFileRepo) Delete(id string) error {
+func (m *MockMediaFileRepo) Delete(_ context.Context, id string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -179,7 +180,7 @@ func (m *MockMediaFileRepo) Delete(id string) error {
 	return nil
 }
 
-func (m *MockMediaFileRepo) ReassignReferences(prevID, newID string) error {
+func (m *MockMediaFileRepo) ReassignReferences(_ context.Context, prevID, newID string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -190,7 +191,7 @@ func (m *MockMediaFileRepo) ReassignReferences(prevID, newID string) error {
 	return nil
 }
 
-func (m *MockMediaFileRepo) IncPlayCount(id string, timestamp time.Time) error {
+func (m *MockMediaFileRepo) IncPlayCount(_ context.Context, id string, timestamp time.Time) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -202,7 +203,7 @@ func (m *MockMediaFileRepo) IncPlayCount(id string, timestamp time.Time) error {
 	return model.ErrNotFound
 }
 
-func (m *MockMediaFileRepo) SetStar(starred bool, itemIDs ...string) error {
+func (m *MockMediaFileRepo) SetStar(_ context.Context, starred bool, itemIDs ...string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -214,7 +215,7 @@ func (m *MockMediaFileRepo) SetStar(starred bool, itemIDs ...string) error {
 	return nil
 }
 
-func (m *MockMediaFileRepo) SetRating(rating int, itemID string) error {
+func (m *MockMediaFileRepo) SetRating(_ context.Context, rating int, itemID string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -240,7 +241,7 @@ func (m *MockMediaFileRepo) FindByAlbum(artistId string) (model.MediaFiles, erro
 	return res, nil
 }
 
-func (m *MockMediaFileRepo) GetMissingAndMatching(libId int) (model.MediaFileCursor, error) {
+func (m *MockMediaFileRepo) GetMissingAndMatching(_ context.Context, libId int) (model.MediaFileCursor, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -274,7 +275,7 @@ func (m *MockMediaFileRepo) GetMissingAndMatching(libId int) (model.MediaFileCur
 	}, nil
 }
 
-func (m *MockMediaFileRepo) CountAll(opts ...model.QueryOptions) (int64, error) {
+func (m *MockMediaFileRepo) CountAll(_ context.Context, opts ...model.QueryOptions) (int64, error) {
 	if m.Err {
 		return 0, errors.New("error")
 	}
@@ -287,7 +288,7 @@ func (m *MockMediaFileRepo) CountAll(opts ...model.QueryOptions) (int64, error)
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockMediaFileRepo) DeleteAllMissing() (int64, error) {
+func (m *MockMediaFileRepo) DeleteAllMissing(_ context.Context) (int64, error) {
 	if m.Err {
 		return 0, errors.New("error")
 	}
@@ -305,28 +306,20 @@ func (m *MockMediaFileRepo) DeleteAllMissing() (int64, error) {
 	return count, nil
 }
 
-// ResourceRepository methods
-func (m *MockMediaFileRepo) Count(...rest.QueryOptions) (int64, error) {
-	return m.CountAll()
+// REST repository methods
+func (m *MockMediaFileRepo) Count(ctx context.Context, _ ...rest.QueryOptions) (int64, error) {
+	return m.CountAll(ctx)
 }
 
-func (m *MockMediaFileRepo) Read(id string) (any, error) {
-	return m.Get(id)
+func (m *MockMediaFileRepo) Read(ctx context.Context, id string) (*model.MediaFile, error) {
+	return m.Get(ctx, id)
 }
 
-func (m *MockMediaFileRepo) ReadAll(...rest.QueryOptions) (any, error) {
-	return m.GetAll()
+func (m *MockMediaFileRepo) ReadAll(ctx context.Context, _ ...rest.QueryOptions) ([]model.MediaFile, error) {
+	return m.GetAll(ctx)
 }
 
-func (m *MockMediaFileRepo) EntityName() string {
-	return "mediafile"
-}
-
-func (m *MockMediaFileRepo) NewInstance() any {
-	return &model.MediaFile{}
-}
-
-func (m *MockMediaFileRepo) Search(q string, options ...model.QueryOptions) (model.MediaFiles, error) {
+func (m *MockMediaFileRepo) Search(ctx context.Context, q string, options ...model.QueryOptions) (model.MediaFiles, error) {
 	if len(options) > 0 {
 		m.Options = options[0]
 	}
@@ -334,11 +327,11 @@ func (m *MockMediaFileRepo) Search(q string, options ...model.QueryOptions) (mod
 		return nil, errors.New("unexpected error")
 	}
 	// Simple mock implementation - just return all media files for testing
-	return m.GetAll()
+	return m.GetAll(ctx)
 }
 
 // Cross-library move detection mock methods
-func (m *MockMediaFileRepo) FindRecentFilesByMBZTrackID(missing model.MediaFile, since time.Time) (model.MediaFiles, error) {
+func (m *MockMediaFileRepo) FindRecentFilesByMBZTrackID(_ context.Context, missing model.MediaFile, since time.Time) (model.MediaFiles, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -360,7 +353,7 @@ func (m *MockMediaFileRepo) FindRecentFilesByMBZTrackID(missing model.MediaFile,
 	return result, nil
 }
 
-func (m *MockMediaFileRepo) FindRecentFilesByProperties(missing model.MediaFile, since time.Time) (model.MediaFiles, error) {
+func (m *MockMediaFileRepo) FindRecentFilesByProperties(_ context.Context, missing model.MediaFile, since time.Time) (model.MediaFiles, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -386,7 +379,7 @@ func (m *MockMediaFileRepo) FindRecentFilesByProperties(missing model.MediaFile,
 	return result, nil
 }
 
-func (m *MockMediaFileRepo) MatchesCriteria(string, criteria.Criteria) (bool, error) {
+func (m *MockMediaFileRepo) MatchesCriteria(context.Context, string, criteria.Criteria) (bool, error) {
 	if m.MatchesCriteriaErr != nil {
 		return false, m.MatchesCriteriaErr
 	}
@@ -394,4 +387,4 @@ func (m *MockMediaFileRepo) MatchesCriteria(string, criteria.Criteria) (bool, er
 }
 
 var _ model.MediaFileRepository = (*MockMediaFileRepo)(nil)
-var _ model.ResourceRepository = (*MockMediaFileRepo)(nil)
+var _ rest.Repository[model.MediaFile] = (*MockMediaFileRepo)(nil)
diff --git a/tests/mock_playlist_repo.go b/tests/mock_playlist_repo.go
index 0fa9618ae..824e701f6 100644
--- a/tests/mock_playlist_repo.go
+++ b/tests/mock_playlist_repo.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"errors"
 	"time"
 
@@ -43,7 +44,7 @@ func (m *MockPlaylistRepo) SetData(playlists model.Playlists) {
 	}
 }
 
-func (m *MockPlaylistRepo) GetAll(options ...model.QueryOptions) (model.Playlists, error) {
+func (m *MockPlaylistRepo) GetAll(_ context.Context, options ...model.QueryOptions) (model.Playlists, error) {
 	if len(options) > 0 {
 		m.Options = options[0]
 	}
@@ -53,8 +54,8 @@ func (m *MockPlaylistRepo) GetAll(options ...model.QueryOptions) (model.Playlist
 	return m.All, nil
 }
 
-func (m *MockPlaylistRepo) GetCursor(options ...model.QueryOptions) (model.PlaylistCursor, error) {
-	res, err := m.GetAll(options...)
+func (m *MockPlaylistRepo) GetCursor(ctx context.Context, options ...model.QueryOptions) (model.PlaylistCursor, error) {
+	res, err := m.GetAll(ctx, options...)
 	if err != nil {
 		return nil, err
 	}
@@ -67,7 +68,7 @@ func (m *MockPlaylistRepo) GetCursor(options ...model.QueryOptions) (model.Playl
 	}, nil
 }
 
-func (m *MockPlaylistRepo) Get(id string) (*model.Playlist, error) {
+func (m *MockPlaylistRepo) Get(_ context.Context, id string) (*model.Playlist, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -79,11 +80,11 @@ func (m *MockPlaylistRepo) Get(id string) (*model.Playlist, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockPlaylistRepo) GetWithTracks(id string, _, _ bool) (*model.Playlist, error) {
-	return m.Get(id)
+func (m *MockPlaylistRepo) GetWithTracks(ctx context.Context, id string, _, _ bool) (*model.Playlist, error) {
+	return m.Get(ctx, id)
 }
 
-func (m *MockPlaylistRepo) Put(pls *model.Playlist, _ ...string) error {
+func (m *MockPlaylistRepo) Put(_ context.Context, pls *model.Playlist, _ ...string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -97,7 +98,7 @@ func (m *MockPlaylistRepo) Put(pls *model.Playlist, _ ...string) error {
 	return nil
 }
 
-func (m *MockPlaylistRepo) FindByPath(path string) (*model.Playlist, error) {
+func (m *MockPlaylistRepo) FindByPath(_ context.Context, path string) (*model.Playlist, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -109,15 +110,15 @@ func (m *MockPlaylistRepo) FindByPath(path string) (*model.Playlist, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockPlaylistRepo) Delete(id string) error {
+func (m *MockPlaylistRepo) Delete(_ context.Context, ids ...string) error {
 	if m.Err {
 		return errors.New("error")
 	}
-	m.Deleted = append(m.Deleted, id)
+	m.Deleted = append(m.Deleted, ids...)
 	return nil
 }
 
-func (m *MockPlaylistRepo) SetStar(starred bool, ids ...string) error {
+func (m *MockPlaylistRepo) SetStar(_ context.Context, starred bool, ids ...string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -130,7 +131,7 @@ func (m *MockPlaylistRepo) SetStar(starred bool, ids ...string) error {
 	return nil
 }
 
-func (m *MockPlaylistRepo) SetRating(rating int, id string) error {
+func (m *MockPlaylistRepo) SetRating(_ context.Context, rating int, id string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -141,26 +142,26 @@ func (m *MockPlaylistRepo) SetRating(rating int, id string) error {
 	return nil
 }
 
-func (m *MockPlaylistRepo) IncPlayCount(string, time.Time) error {
+func (m *MockPlaylistRepo) IncPlayCount(context.Context, string, time.Time) error {
 	if m.Err {
 		return errors.New("error")
 	}
 	return nil
 }
 
-func (m *MockPlaylistRepo) ReassignAnnotation(string, string) error {
+func (m *MockPlaylistRepo) ReassignAnnotation(context.Context, string, string) error {
 	if m.Err {
 		return errors.New("error")
 	}
 	return nil
 }
 
-func (m *MockPlaylistRepo) Tracks(_ string, refreshSmartPlaylist bool) model.PlaylistTrackRepository {
+func (m *MockPlaylistRepo) Tracks(_ context.Context, _ string, refreshSmartPlaylist bool) model.PlaylistTrackRepository {
 	m.TracksRefreshed = refreshSmartPlaylist
 	return m.TracksRepo
 }
 
-func (m *MockPlaylistRepo) Exists(id string) (bool, error) {
+func (m *MockPlaylistRepo) Exists(_ context.Context, id string) (bool, error) {
 	if m.Err {
 		return false, errors.New("error")
 	}
@@ -171,14 +172,14 @@ func (m *MockPlaylistRepo) Exists(id string) (bool, error) {
 	return false, nil
 }
 
-func (m *MockPlaylistRepo) Count(_ ...rest.QueryOptions) (int64, error) {
+func (m *MockPlaylistRepo) Count(_ context.Context, _ ...rest.QueryOptions) (int64, error) {
 	if m.Err {
 		return 0, errors.New("error")
 	}
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockPlaylistRepo) CountAll(_ ...model.QueryOptions) (int64, error) {
+func (m *MockPlaylistRepo) CountAll(_ context.Context, _ ...model.QueryOptions) (int64, error) {
 	if m.Err {
 		return 0, errors.New("error")
 	}
diff --git a/tests/mock_playlist_track_repo.go b/tests/mock_playlist_track_repo.go
index 5666e7cc7..794393371 100644
--- a/tests/mock_playlist_track_repo.go
+++ b/tests/mock_playlist_track_repo.go
@@ -1,6 +1,8 @@
 package tests
 
 import (
+	"context"
+
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/slice"
 )
@@ -40,21 +42,21 @@ func (m *MockPlaylistTrackRepo) page(options ...model.QueryOptions) model.Playli
 	return tracks
 }
 
-func (m *MockPlaylistTrackRepo) CountAll(_ ...model.QueryOptions) (int64, error) {
+func (m *MockPlaylistTrackRepo) CountAll(_ context.Context, _ ...model.QueryOptions) (int64, error) {
 	if m.Err != nil {
 		return 0, m.Err
 	}
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockPlaylistTrackRepo) GetAll(options ...model.QueryOptions) (model.PlaylistTracks, error) {
+func (m *MockPlaylistTrackRepo) GetAll(_ context.Context, options ...model.QueryOptions) (model.PlaylistTracks, error) {
 	if m.Err != nil {
 		return nil, m.Err
 	}
 	return m.page(options...), nil
 }
 
-func (m *MockPlaylistTrackRepo) GetCursor(options ...model.QueryOptions) (model.PlaylistTrackCursor, error) {
+func (m *MockPlaylistTrackRepo) GetCursor(_ context.Context, options ...model.QueryOptions) (model.PlaylistTrackCursor, error) {
 	if m.Err != nil {
 		return nil, m.Err
 	}
@@ -68,21 +70,21 @@ func (m *MockPlaylistTrackRepo) GetCursor(options ...model.QueryOptions) (model.
 	}, nil
 }
 
-func (m *MockPlaylistTrackRepo) GetAlbumIDs(...model.QueryOptions) ([]string, error) {
+func (m *MockPlaylistTrackRepo) GetAlbumIDs(context.Context, ...model.QueryOptions) ([]string, error) {
 	if m.Err != nil {
 		return nil, m.Err
 	}
 	return m.AlbumIDs, nil
 }
 
-func (m *MockPlaylistTrackRepo) GetMediaFileIDs(options ...model.QueryOptions) ([]string, error) {
+func (m *MockPlaylistTrackRepo) GetMediaFileIDs(_ context.Context, options ...model.QueryOptions) ([]string, error) {
 	if m.Err != nil {
 		return nil, m.Err
 	}
 	return slice.Map(m.page(options...), func(t model.PlaylistTrack) string { return t.MediaFileID }), nil
 }
 
-func (m *MockPlaylistTrackRepo) Add(ids []string) (int, error) {
+func (m *MockPlaylistTrackRepo) Add(_ context.Context, ids []string) (int, error) {
 	m.AddedIds = append(m.AddedIds, ids...)
 	if m.Err != nil {
 		return 0, m.Err
@@ -90,38 +92,38 @@ func (m *MockPlaylistTrackRepo) Add(ids []string) (int, error) {
 	return m.AddCount, nil
 }
 
-func (m *MockPlaylistTrackRepo) Insert(ids []string, pos int) (int, error) {
+func (m *MockPlaylistTrackRepo) Insert(ctx context.Context, ids []string, pos int) (int, error) {
 	m.InsertPos = pos
-	return m.Add(ids)
+	return m.Add(ctx, ids)
 }
 
-func (m *MockPlaylistTrackRepo) AddAlbums(_ []string) (int, error) {
+func (m *MockPlaylistTrackRepo) AddAlbums(_ context.Context, _ []string) (int, error) {
 	if m.Err != nil {
 		return 0, m.Err
 	}
 	return m.AddCount, nil
 }
 
-func (m *MockPlaylistTrackRepo) AddArtists(_ []string) (int, error) {
+func (m *MockPlaylistTrackRepo) AddArtists(_ context.Context, _ []string) (int, error) {
 	if m.Err != nil {
 		return 0, m.Err
 	}
 	return m.AddCount, nil
 }
 
-func (m *MockPlaylistTrackRepo) AddDiscs(_ []model.DiscID) (int, error) {
+func (m *MockPlaylistTrackRepo) AddDiscs(_ context.Context, _ []model.DiscID) (int, error) {
 	if m.Err != nil {
 		return 0, m.Err
 	}
 	return m.AddCount, nil
 }
 
-func (m *MockPlaylistTrackRepo) Delete(ids ...string) error {
+func (m *MockPlaylistTrackRepo) Delete(_ context.Context, ids ...string) error {
 	m.DeletedIds = append(m.DeletedIds, ids...)
 	return m.Err
 }
 
-func (m *MockPlaylistTrackRepo) Reorder(_, _ int) error {
+func (m *MockPlaylistTrackRepo) Reorder(_ context.Context, _, _ int) error {
 	m.Reordered = true
 	return m.Err
 }
diff --git a/tests/mock_playqueue_repo.go b/tests/mock_playqueue_repo.go
index 19976db57..b445a5085 100644
--- a/tests/mock_playqueue_repo.go
+++ b/tests/mock_playqueue_repo.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"errors"
 
 	"github.com/navidrome/navidrome/model"
@@ -13,7 +14,7 @@ type MockPlayQueueRepo struct {
 	LastCols []string
 }
 
-func (m *MockPlayQueueRepo) Store(q *model.PlayQueue, cols ...string) error {
+func (m *MockPlayQueueRepo) Store(_ context.Context, q *model.PlayQueue, cols ...string) error {
 	if m.Err {
 		return errors.New("error")
 	}
@@ -26,7 +27,7 @@ func (m *MockPlayQueueRepo) Store(q *model.PlayQueue, cols ...string) error {
 	return nil
 }
 
-func (m *MockPlayQueueRepo) RetrieveWithMediaFiles(userId string) (*model.PlayQueue, error) {
+func (m *MockPlayQueueRepo) RetrieveWithMediaFiles(_ context.Context, userId string) (*model.PlayQueue, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -40,7 +41,7 @@ func (m *MockPlayQueueRepo) RetrieveWithMediaFiles(userId string) (*model.PlayQu
 	return &qCopy, nil
 }
 
-func (m *MockPlayQueueRepo) Retrieve(userId string) (*model.PlayQueue, error) {
+func (m *MockPlayQueueRepo) Retrieve(_ context.Context, userId string) (*model.PlayQueue, error) {
 	if m.Err {
 		return nil, errors.New("error")
 	}
@@ -56,7 +57,7 @@ func (m *MockPlayQueueRepo) Retrieve(userId string) (*model.PlayQueue, error) {
 	return &qCopy, nil
 }
 
-func (m *MockPlayQueueRepo) Clear(userId string) error {
+func (m *MockPlayQueueRepo) Clear(_ context.Context, userId string) error {
 	if m.Err {
 		return errors.New("error")
 	}
diff --git a/tests/mock_plugin_repo.go b/tests/mock_plugin_repo.go
index e65d56def..feaf9b212 100644
--- a/tests/mock_plugin_repo.go
+++ b/tests/mock_plugin_repo.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"errors"
 	"time"
 
@@ -29,7 +30,7 @@ func (m *MockPluginRepo) SetError(err bool) {
 	m.Err = err
 }
 
-func (m *MockPluginRepo) ClearErrors() error {
+func (m *MockPluginRepo) ClearErrors(context.Context) error {
 	if m.Err {
 		return errors.New("unexpected error")
 	}
@@ -55,7 +56,7 @@ func (m *MockPluginRepo) SetPermitted(permitted bool) {
 	m.Permitted = permitted
 }
 
-func (m *MockPluginRepo) Get(id string) (*model.Plugin, error) {
+func (m *MockPluginRepo) Get(_ context.Context, id string) (*model.Plugin, error) {
 	if !m.Permitted {
 		return nil, rest.ErrPermissionDenied
 	}
@@ -68,11 +69,11 @@ func (m *MockPluginRepo) Get(id string) (*model.Plugin, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockPluginRepo) Read(id string) (any, error) {
-	return m.Get(id)
+func (m *MockPluginRepo) Read(ctx context.Context, id string) (*model.Plugin, error) {
+	return m.Get(ctx, id)
 }
 
-func (m *MockPluginRepo) Put(p *model.Plugin) error {
+func (m *MockPluginRepo) Put(_ context.Context, p *model.Plugin) error {
 	if !m.Permitted {
 		return rest.ErrPermissionDenied
 	}
@@ -105,7 +106,7 @@ func (m *MockPluginRepo) Put(p *model.Plugin) error {
 	return nil
 }
 
-func (m *MockPluginRepo) Delete(id string) error {
+func (m *MockPluginRepo) Delete(_ context.Context, id string) error {
 	if !m.Permitted {
 		return rest.ErrPermissionDenied
 	}
@@ -123,7 +124,7 @@ func (m *MockPluginRepo) Delete(id string) error {
 	return nil
 }
 
-func (m *MockPluginRepo) GetAll(qo ...model.QueryOptions) (model.Plugins, error) {
+func (m *MockPluginRepo) GetAll(_ context.Context, qo ...model.QueryOptions) (model.Plugins, error) {
 	if len(qo) > 0 {
 		m.Options = qo[0]
 	}
@@ -136,7 +137,7 @@ func (m *MockPluginRepo) GetAll(qo ...model.QueryOptions) (model.Plugins, error)
 	return m.All, nil
 }
 
-func (m *MockPluginRepo) CountAll(qo ...model.QueryOptions) (int64, error) {
+func (m *MockPluginRepo) CountAll(_ context.Context, qo ...model.QueryOptions) (int64, error) {
 	if len(qo) > 0 {
 		m.Options = qo[0]
 	}
@@ -149,36 +150,16 @@ func (m *MockPluginRepo) CountAll(qo ...model.QueryOptions) (int64, error) {
 	return int64(len(m.All)), nil
 }
 
-// rest.Repository interface methods
-func (m *MockPluginRepo) Count(options ...rest.QueryOptions) (int64, error) {
+// REST repository methods
+func (m *MockPluginRepo) Count(_ context.Context, _ ...rest.QueryOptions) (int64, error) {
 	if !m.Permitted {
 		return 0, rest.ErrPermissionDenied
 	}
 	return int64(len(m.All)), nil
 }
 
-func (m *MockPluginRepo) EntityName() string {
-	return "plugin"
-}
-
-func (m *MockPluginRepo) NewInstance() any {
-	return &model.Plugin{}
-}
-
-func (m *MockPluginRepo) ReadAll(options ...rest.QueryOptions) (any, error) {
-	return m.GetAll()
-}
-
-func (m *MockPluginRepo) Save(entity any) (string, error) {
-	p := entity.(*model.Plugin)
-	err := m.Put(p)
-	return p.ID, err
-}
-
-func (m *MockPluginRepo) Update(id string, entity any, cols ...string) error {
-	p := entity.(*model.Plugin)
-	p.ID = id
-	return m.Put(p)
+func (m *MockPluginRepo) ReadAll(ctx context.Context, _ ...rest.QueryOptions) ([]model.Plugin, error) {
+	return m.GetAll(ctx)
 }
 
 var _ model.PluginRepository = (*MockPluginRepo)(nil)
diff --git a/tests/mock_property_repo.go b/tests/mock_property_repo.go
index 9adc66e6d..949f894c1 100644
--- a/tests/mock_property_repo.go
+++ b/tests/mock_property_repo.go
@@ -1,6 +1,10 @@
 package tests
 
-import "github.com/navidrome/navidrome/model"
+import (
+	"context"
+
+	"github.com/navidrome/navidrome/model"
+)
 
 type MockedPropertyRepo struct {
 	model.PropertyRepository
@@ -14,7 +18,7 @@ func (p *MockedPropertyRepo) init() {
 	}
 }
 
-func (p *MockedPropertyRepo) Put(id string, value string) error {
+func (p *MockedPropertyRepo) Put(_ context.Context, id string, value string) error {
 	if p.Error != nil {
 		return p.Error
 	}
@@ -23,7 +27,7 @@ func (p *MockedPropertyRepo) Put(id string, value string) error {
 	return nil
 }
 
-func (p *MockedPropertyRepo) Get(id string) (string, error) {
+func (p *MockedPropertyRepo) Get(_ context.Context, id string) (string, error) {
 	if p.Error != nil {
 		return "", p.Error
 	}
@@ -34,7 +38,7 @@ func (p *MockedPropertyRepo) Get(id string) (string, error) {
 	return "", model.ErrNotFound
 }
 
-func (p *MockedPropertyRepo) Delete(id string) error {
+func (p *MockedPropertyRepo) Delete(_ context.Context, id string) error {
 	if p.Error != nil {
 		return p.Error
 	}
@@ -46,12 +50,12 @@ func (p *MockedPropertyRepo) Delete(id string) error {
 	return model.ErrNotFound
 }
 
-func (p *MockedPropertyRepo) DefaultGet(id string, defaultValue string) (string, error) {
+func (p *MockedPropertyRepo) DefaultGet(ctx context.Context, id string, defaultValue string) (string, error) {
 	if p.Error != nil {
 		return "", p.Error
 	}
 	p.init()
-	v, err := p.Get(id)
+	v, err := p.Get(ctx, id)
 	if err != nil {
 		return defaultValue, nil //nolint:nilerr
 	}
diff --git a/tests/mock_radio_repository.go b/tests/mock_radio_repository.go
index 20f81ec45..21898ea53 100644
--- a/tests/mock_radio_repository.go
+++ b/tests/mock_radio_repository.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"errors"
 
 	"github.com/navidrome/navidrome/model"
@@ -23,29 +24,27 @@ func (m *MockedRadioRepo) SetError(err bool) {
 	m.Err = err
 }
 
-func (m *MockedRadioRepo) CountAll(options ...model.QueryOptions) (int64, error) {
+func (m *MockedRadioRepo) CountAll(_ context.Context, options ...model.QueryOptions) (int64, error) {
 	if m.Err {
 		return 0, errors.New("error")
 	}
 	return int64(len(m.Data)), nil
 }
 
-func (m *MockedRadioRepo) Delete(id string) error {
+func (m *MockedRadioRepo) Delete(_ context.Context, ids ...string) error {
 	if m.Err {
 		return errors.New("Error!")
 	}
-
-	_, found := m.Data[id]
-
-	if !found {
-		return errors.New("not found")
+	for _, id := range ids {
+		if _, found := m.Data[id]; !found {
+			return errors.New("not found")
+		}
+		delete(m.Data, id)
 	}
-
-	delete(m.Data, id)
 	return nil
 }
 
-func (m *MockedRadioRepo) Exists(id string) (bool, error) {
+func (m *MockedRadioRepo) Exists(_ context.Context, id string) (bool, error) {
 	if m.Err {
 		return false, errors.New("Error!")
 	}
@@ -53,7 +52,7 @@ func (m *MockedRadioRepo) Exists(id string) (bool, error) {
 	return found, nil
 }
 
-func (m *MockedRadioRepo) Get(id string) (*model.Radio, error) {
+func (m *MockedRadioRepo) Get(_ context.Context, id string) (*model.Radio, error) {
 	if m.Err {
 		return nil, errors.New("Error!")
 	}
@@ -63,7 +62,7 @@ func (m *MockedRadioRepo) Get(id string) (*model.Radio, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockedRadioRepo) GetAll(qo ...model.QueryOptions) (model.Radios, error) {
+func (m *MockedRadioRepo) GetAll(_ context.Context, qo ...model.QueryOptions) (model.Radios, error) {
 	if len(qo) > 0 {
 		m.Options = qo[0]
 	}
@@ -73,7 +72,7 @@ func (m *MockedRadioRepo) GetAll(qo ...model.QueryOptions) (model.Radios, error)
 	return m.All, nil
 }
 
-func (m *MockedRadioRepo) Put(radio *model.Radio, _ ...string) error {
+func (m *MockedRadioRepo) Put(_ context.Context, radio *model.Radio, _ ...string) error {
 	if m.Err {
 		return errors.New("error")
 	}
diff --git a/tests/mock_scrobble_buffer_repo.go b/tests/mock_scrobble_buffer_repo.go
index 2eb5e8a93..91177eeef 100644
--- a/tests/mock_scrobble_buffer_repo.go
+++ b/tests/mock_scrobble_buffer_repo.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"sync"
 	"time"
 
@@ -17,7 +18,7 @@ func CreateMockedScrobbleBufferRepo() *MockedScrobbleBufferRepo {
 	return &MockedScrobbleBufferRepo{}
 }
 
-func (m *MockedScrobbleBufferRepo) UserIDs(service string) ([]string, error) {
+func (m *MockedScrobbleBufferRepo) UserIDs(_ context.Context, service string) ([]string, error) {
 	if m.Error != nil {
 		return nil, m.Error
 	}
@@ -36,7 +37,7 @@ func (m *MockedScrobbleBufferRepo) UserIDs(service string) ([]string, error) {
 	return result, nil
 }
 
-func (m *MockedScrobbleBufferRepo) Enqueue(service, userId, mediaFileId string, playTime time.Time) error {
+func (m *MockedScrobbleBufferRepo) Enqueue(_ context.Context, service, userId, mediaFileId string, playTime time.Time) error {
 	if m.Error != nil {
 		return m.Error
 	}
@@ -52,7 +53,7 @@ func (m *MockedScrobbleBufferRepo) Enqueue(service, userId, mediaFileId string,
 	return nil
 }
 
-func (m *MockedScrobbleBufferRepo) Next(service, userId string) (*model.ScrobbleEntry, error) {
+func (m *MockedScrobbleBufferRepo) Next(_ context.Context, service, userId string) (*model.ScrobbleEntry, error) {
 	if m.Error != nil {
 		return nil, m.Error
 	}
@@ -66,7 +67,7 @@ func (m *MockedScrobbleBufferRepo) Next(service, userId string) (*model.Scrobble
 	return nil, nil
 }
 
-func (m *MockedScrobbleBufferRepo) Dequeue(entry *model.ScrobbleEntry) error {
+func (m *MockedScrobbleBufferRepo) Dequeue(_ context.Context, entry *model.ScrobbleEntry) error {
 	if m.Error != nil {
 		return m.Error
 	}
@@ -83,7 +84,7 @@ func (m *MockedScrobbleBufferRepo) Dequeue(entry *model.ScrobbleEntry) error {
 	return nil
 }
 
-func (m *MockedScrobbleBufferRepo) Discard(service string) error {
+func (m *MockedScrobbleBufferRepo) Discard(_ context.Context, service string) error {
 	if m.Error != nil {
 		return m.Error
 	}
@@ -99,7 +100,7 @@ func (m *MockedScrobbleBufferRepo) Discard(service string) error {
 	return nil
 }
 
-func (m *MockedScrobbleBufferRepo) Length() (int64, error) {
+func (m *MockedScrobbleBufferRepo) Length(context.Context) (int64, error) {
 	if m.Error != nil {
 		return 0, m.Error
 	}
@@ -107,3 +108,5 @@ func (m *MockedScrobbleBufferRepo) Length() (int64, error) {
 	defer m.mu.RUnlock()
 	return int64(len(m.Data)), nil
 }
+
+var _ model.ScrobbleBufferRepository = (*MockedScrobbleBufferRepo)(nil)
diff --git a/tests/mock_scrobble_repo.go b/tests/mock_scrobble_repo.go
index d6d88d221..a76bc5d59 100644
--- a/tests/mock_scrobble_repo.go
+++ b/tests/mock_scrobble_repo.go
@@ -5,16 +5,16 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
 )
 
 type MockScrobbleRepo struct {
 	RecordedScrobbles []model.Scrobble
-	ctx               context.Context
 }
 
-func (m *MockScrobbleRepo) Get(id string) (*model.Scrobble, error) {
+func (m *MockScrobbleRepo) Get(_ context.Context, id string) (*model.Scrobble, error) {
 	for idx := range m.RecordedScrobbles {
 		if strconv.FormatInt(m.RecordedScrobbles[idx].ID, 10) == id {
 			return &m.RecordedScrobbles[idx], nil
@@ -24,16 +24,16 @@ func (m *MockScrobbleRepo) Get(id string) (*model.Scrobble, error) {
 	return nil, model.ErrNotFound
 }
 
-func (m *MockScrobbleRepo) GetAll(options ...model.QueryOptions) (model.Scrobbles, error) {
+func (m *MockScrobbleRepo) GetAll(_ context.Context, _ ...model.QueryOptions) (model.Scrobbles, error) {
 	return m.RecordedScrobbles, nil
 }
 
-func (m *MockScrobbleRepo) CountAll(options ...model.QueryOptions) (int64, error) {
+func (m *MockScrobbleRepo) CountAll(_ context.Context, _ ...model.QueryOptions) (int64, error) {
 	return int64(len(m.RecordedScrobbles)), nil
 }
 
-func (m *MockScrobbleRepo) RecordScrobble(fileID string, submissionTime time.Time) error {
-	user, _ := request.UserFrom(m.ctx)
+func (m *MockScrobbleRepo) RecordScrobble(ctx context.Context, fileID string, submissionTime time.Time) error {
+	user, _ := request.UserFrom(ctx)
 	m.RecordedScrobbles = append(m.RecordedScrobbles, model.Scrobble{
 		MediaFileID:    fileID,
 		UserID:         user.ID,
@@ -42,4 +42,16 @@ func (m *MockScrobbleRepo) RecordScrobble(fileID string, submissionTime time.Tim
 	return nil
 }
 
+func (m *MockScrobbleRepo) Count(ctx context.Context, _ ...rest.QueryOptions) (int64, error) {
+	return m.CountAll(ctx)
+}
+
+func (m *MockScrobbleRepo) Read(ctx context.Context, id string) (*model.Scrobble, error) {
+	return m.Get(ctx, id)
+}
+
+func (m *MockScrobbleRepo) ReadAll(ctx context.Context, _ ...rest.QueryOptions) ([]model.Scrobble, error) {
+	return m.GetAll(ctx)
+}
+
 var _ model.ScrobbleRepository = (*MockScrobbleRepo)(nil)
diff --git a/tests/mock_share_repo.go b/tests/mock_share_repo.go
index 9fbf0057e..0c872dc0d 100644
--- a/tests/mock_share_repo.go
+++ b/tests/mock_share_repo.go
@@ -1,14 +1,13 @@
 package tests
 
 import (
-	"github.com/deluan/rest"
+	"context"
+
 	"github.com/navidrome/navidrome/model"
 )
 
 type MockShareRepo struct {
 	model.ShareRepository
-	rest.Repository
-	rest.Persistable
 
 	Entity any
 	ID     string
@@ -16,11 +15,10 @@ type MockShareRepo struct {
 	Error  error
 }
 
-func (m *MockShareRepo) Save(entity any) (string, error) {
+func (m *MockShareRepo) Save(_ context.Context, s *model.Share) (string, error) {
 	if m.Error != nil {
 		return "", m.Error
 	}
-	s := entity.(*model.Share)
 	if s.ID == "" {
 		s.ID = "id"
 	}
@@ -28,24 +26,24 @@ func (m *MockShareRepo) Save(entity any) (string, error) {
 	return s.ID, nil
 }
 
-func (m *MockShareRepo) Update(id string, entity any, cols ...string) error {
+func (m *MockShareRepo) Update(_ context.Context, id string, entity model.Share, cols ...string) error {
 	if m.Error != nil {
 		return m.Error
 	}
 	m.ID = id
-	m.Entity = entity
+	m.Entity = &entity
 	m.Cols = cols
 	return nil
 }
 
-func (m *MockShareRepo) Exists(id string) (bool, error) {
+func (m *MockShareRepo) Exists(_ context.Context, id string) (bool, error) {
 	if m.Error != nil {
 		return false, m.Error
 	}
 	return id == m.ID, nil
 }
 
-func (m *MockShareRepo) Get(id string) (*model.Share, error) {
+func (m *MockShareRepo) Get(_ context.Context, id string) (*model.Share, error) {
 	if m.Error != nil {
 		return nil, m.Error
 	}
diff --git a/tests/mock_tag_repo.go b/tests/mock_tag_repo.go
index a59035ea6..f1f252efe 100644
--- a/tests/mock_tag_repo.go
+++ b/tests/mock_tag_repo.go
@@ -1,6 +1,8 @@
 package tests
 
 import (
+	"context"
+
 	"github.com/navidrome/navidrome/model"
 )
 
@@ -13,7 +15,7 @@ type MockTagRepo struct {
 	Err     error
 }
 
-func (r *MockTagRepo) GetAll(_ model.TagName, options ...model.QueryOptions) (model.TagList, error) {
+func (r *MockTagRepo) GetAll(_ context.Context, _ model.TagName, options ...model.QueryOptions) (model.TagList, error) {
 	if len(options) > 0 {
 		r.Options = options[0]
 	}
diff --git a/tests/mock_transcoding_repo.go b/tests/mock_transcoding_repo.go
index 641daca8a..52eb16eed 100644
--- a/tests/mock_transcoding_repo.go
+++ b/tests/mock_transcoding_repo.go
@@ -1,16 +1,20 @@
 package tests
 
-import "github.com/navidrome/navidrome/model"
+import (
+	"context"
+
+	"github.com/navidrome/navidrome/model"
+)
 
 type MockTranscodingRepo struct {
 	model.TranscodingRepository
 }
 
-func (m *MockTranscodingRepo) Get(id string) (*model.Transcoding, error) {
+func (m *MockTranscodingRepo) Get(_ context.Context, id string) (*model.Transcoding, error) {
 	return &model.Transcoding{ID: id, TargetFormat: "mp3", DefaultBitRate: 160}, nil
 }
 
-func (m *MockTranscodingRepo) FindByFormat(format string) (*model.Transcoding, error) {
+func (m *MockTranscodingRepo) FindByFormat(_ context.Context, format string) (*model.Transcoding, error) {
 	switch format {
 	case "mp3":
 		return &model.Transcoding{ID: "mp31", TargetFormat: "mp3", DefaultBitRate: 160}, nil
diff --git a/tests/mock_user_props_repo.go b/tests/mock_user_props_repo.go
index 1b1e17650..278a68431 100644
--- a/tests/mock_user_props_repo.go
+++ b/tests/mock_user_props_repo.go
@@ -1,6 +1,10 @@
 package tests
 
-import "github.com/navidrome/navidrome/model"
+import (
+	"context"
+
+	"github.com/navidrome/navidrome/model"
+)
 
 type MockedUserPropsRepo struct {
 	model.UserPropsRepository
@@ -14,7 +18,7 @@ func (p *MockedUserPropsRepo) init() {
 	}
 }
 
-func (p *MockedUserPropsRepo) Put(userId, key string, value string) error {
+func (p *MockedUserPropsRepo) Put(_ context.Context, userId, key string, value string) error {
 	if p.Error != nil {
 		return p.Error
 	}
@@ -23,7 +27,7 @@ func (p *MockedUserPropsRepo) Put(userId, key string, value string) error {
 	return nil
 }
 
-func (p *MockedUserPropsRepo) Get(userId, key string) (string, error) {
+func (p *MockedUserPropsRepo) Get(_ context.Context, userId, key string) (string, error) {
 	if p.Error != nil {
 		return "", p.Error
 	}
@@ -34,7 +38,7 @@ func (p *MockedUserPropsRepo) Get(userId, key string) (string, error) {
 	return "", model.ErrNotFound
 }
 
-func (p *MockedUserPropsRepo) Delete(userId, key string) error {
+func (p *MockedUserPropsRepo) Delete(_ context.Context, userId, key string) error {
 	if p.Error != nil {
 		return p.Error
 	}
@@ -46,12 +50,12 @@ func (p *MockedUserPropsRepo) Delete(userId, key string) error {
 	return model.ErrNotFound
 }
 
-func (p *MockedUserPropsRepo) DefaultGet(userId, key string, defaultValue string) (string, error) {
+func (p *MockedUserPropsRepo) DefaultGet(ctx context.Context, userId, key string, defaultValue string) (string, error) {
 	if p.Error != nil {
 		return "", p.Error
 	}
 	p.init()
-	v, err := p.Get(userId, key)
+	v, err := p.Get(ctx, userId, key)
 	if err != nil {
 		return defaultValue, nil //nolint:nilerr
 	}
diff --git a/tests/mock_user_repo.go b/tests/mock_user_repo.go
index 2d6ff3c02..58c985157 100644
--- a/tests/mock_user_repo.go
+++ b/tests/mock_user_repo.go
@@ -1,6 +1,7 @@
 package tests
 
 import (
+	"context"
 	"encoding/base64"
 	"fmt"
 	"strings"
@@ -23,14 +24,14 @@ type MockedUserRepo struct {
 	UserLibraries map[string][]int // userID -> libraryIDs
 }
 
-func (u *MockedUserRepo) CountAll(qo ...model.QueryOptions) (int64, error) {
+func (u *MockedUserRepo) CountAll(_ context.Context, qo ...model.QueryOptions) (int64, error) {
 	if u.Error != nil {
 		return 0, u.Error
 	}
 	return int64(len(u.Data)), nil
 }
 
-func (u *MockedUserRepo) Put(usr *model.User) error {
+func (u *MockedUserRepo) Put(_ context.Context, usr *model.User) error {
 	if u.Error != nil {
 		return u.Error
 	}
@@ -42,7 +43,7 @@ func (u *MockedUserRepo) Put(usr *model.User) error {
 	return nil
 }
 
-func (u *MockedUserRepo) FindByUsername(username string) (*model.User, error) {
+func (u *MockedUserRepo) FindByUsername(_ context.Context, username string) (*model.User, error) {
 	if u.Error != nil {
 		return nil, u.Error
 	}
@@ -53,11 +54,11 @@ func (u *MockedUserRepo) FindByUsername(username string) (*model.User, error) {
 	return usr, nil
 }
 
-func (u *MockedUserRepo) FindByUsernameWithPassword(username string) (*model.User, error) {
-	return u.FindByUsername(username)
+func (u *MockedUserRepo) FindByUsernameWithPassword(ctx context.Context, username string) (*model.User, error) {
+	return u.FindByUsername(ctx, username)
 }
 
-func (u *MockedUserRepo) FindFirstAdmin() (*model.User, error) {
+func (u *MockedUserRepo) FindFirstAdmin(_ context.Context) (*model.User, error) {
 	if u.Error != nil {
 		return nil, u.Error
 	}
@@ -69,7 +70,7 @@ func (u *MockedUserRepo) FindFirstAdmin() (*model.User, error) {
 	return nil, model.ErrNotFound
 }
 
-func (u *MockedUserRepo) Get(id string) (*model.User, error) {
+func (u *MockedUserRepo) Get(_ context.Context, id string) (*model.User, error) {
 	if u.Error != nil {
 		return nil, u.Error
 	}
@@ -81,7 +82,7 @@ func (u *MockedUserRepo) Get(id string) (*model.User, error) {
 	return nil, model.ErrNotFound
 }
 
-func (u *MockedUserRepo) GetAll(options ...model.QueryOptions) (model.Users, error) {
+func (u *MockedUserRepo) GetAll(_ context.Context, options ...model.QueryOptions) (model.Users, error) {
 	if u.Error != nil {
 		return nil, u.Error
 	}
@@ -92,7 +93,7 @@ func (u *MockedUserRepo) GetAll(options ...model.QueryOptions) (model.Users, err
 	return users, nil
 }
 
-func (u *MockedUserRepo) UpdateLastLoginAt(id string) error {
+func (u *MockedUserRepo) UpdateLastLoginAt(_ context.Context, id string) error {
 	for _, usr := range u.Data {
 		if usr.ID == id {
 			usr.LastLoginAt = new(time.Now())
@@ -102,7 +103,7 @@ func (u *MockedUserRepo) UpdateLastLoginAt(id string) error {
 	return u.Error
 }
 
-func (u *MockedUserRepo) UpdateLastAccessAt(id string) error {
+func (u *MockedUserRepo) UpdateLastAccessAt(_ context.Context, id string) error {
 	for _, usr := range u.Data {
 		if usr.ID == id {
 			usr.LastAccessAt = new(time.Now())
@@ -114,7 +115,7 @@ func (u *MockedUserRepo) UpdateLastAccessAt(id string) error {
 
 // Library association methods - mock implementations
 
-func (u *MockedUserRepo) GetUserLibraries(userID string) (model.Libraries, error) {
+func (u *MockedUserRepo) GetUserLibraries(_ context.Context, userID string) (model.Libraries, error) {
 	if u.Error != nil {
 		return nil, u.Error
 	}
@@ -135,7 +136,7 @@ func (u *MockedUserRepo) GetUserLibraries(userID string) (model.Libraries, error
 	return libraries, nil
 }
 
-func (u *MockedUserRepo) SetUserLibraries(userID string, libraryIDs []int) error {
+func (u *MockedUserRepo) SetUserLibraries(_ context.Context, userID string, libraryIDs []int) error {
 	if u.Error != nil {
 		return u.Error
 	}
@@ -146,10 +147,19 @@ func (u *MockedUserRepo) SetUserLibraries(userID string, libraryIDs []int) error
 	return nil
 }
 
-func (u *MockedUserRepo) Delete(id string) error {
+func (u *MockedUserRepo) Delete(_ context.Context, ids ...string) error {
 	if u.Error != nil {
 		return u.Error
 	}
+	for _, id := range ids {
+		if err := u.deleteOne(id); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (u *MockedUserRepo) deleteOne(id string) error {
 	for key, usr := range u.Data {
 		if usr.ID == id {
 			delete(u.Data, key)
@@ -160,19 +170,17 @@ func (u *MockedUserRepo) Delete(id string) error {
 	return model.ErrNotFound
 }
 
-func (u *MockedUserRepo) Save(entity any) (string, error) {
-	usr := entity.(*model.User)
-	if err := u.Put(usr); err != nil {
+func (u *MockedUserRepo) Save(ctx context.Context, usr *model.User) (string, error) {
+	if err := u.Put(ctx, usr); err != nil {
 		return "", err
 	}
 	return usr.ID, nil
 }
 
-func (u *MockedUserRepo) Update(id string, entity any, cols ...string) error {
+func (u *MockedUserRepo) Update(ctx context.Context, id string, entity model.User, _ ...string) error {
 	if u.Error != nil {
 		return u.Error
 	}
-	usr := entity.(*model.User)
-	usr.ID = id
-	return u.Put(usr)
+	entity.ID = id
+	return u.Put(ctx, &entity)
 }
diff --git a/tests/mock_user_service.go b/tests/mock_user_service.go
index f2700de45..bde843d1a 100644
--- a/tests/mock_user_service.go
+++ b/tests/mock_user_service.go
@@ -1,9 +1,8 @@
 package tests
 
 import (
-	"context"
-
 	"github.com/deluan/rest"
+	"github.com/navidrome/navidrome/model"
 )
 
 // MockUserService provides a simple wrapper around MockedUserRepo
@@ -13,7 +12,7 @@ type MockUserService struct {
 	*MockedUserRepo
 }
 
-// MockUserRestAdapter adapts MockedUserRepo to rest.Repository interface
+// MockUserRestAdapter adapts MockedUserRepo to the REST repository interface
 type MockUserRestAdapter struct {
 	*MockedUserRepo
 }
@@ -25,6 +24,6 @@ func NewMockUserService() *MockUserService {
 	return &MockUserService{MockedUserRepo: repo}
 }
 
-func (m *MockUserService) NewRepository(ctx context.Context) rest.Repository {
+func (m *MockUserService) Repository() rest.Repository[model.User] {
 	return &MockUserRestAdapter{MockedUserRepo: m.MockedUserRepo}
 }

From 6b05189190a924b66042e32da13792ed53abdcf4 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Fri, 25 Sep 2026 18:18:58 -0400
Subject: [PATCH 184/200] chore: update Go dependencies to latest versions

---
 go.mod | 18 +++++++++---------
 go.sum | 36 ++++++++++++++++++------------------
 2 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/go.mod b/go.mod
index 01fb0f73d..464038d7e 100644
--- a/go.mod
+++ b/go.mod
@@ -8,7 +8,7 @@ replace go.senan.xyz/taglib => github.com/deluan/go-taglib v0.0.0-20260913142955
 require (
 	github.com/Masterminds/squirrel v1.5.4
 	github.com/andybalholm/cascadia v1.3.5
-	github.com/bmatcuk/doublestar/v4 v4.10.0
+	github.com/bmatcuk/doublestar/v4 v4.10.2
 	github.com/deluan/rest v1.0.1
 	github.com/deluan/sanitize v0.0.0-20241120162836-fdfd8fdfaa55
 	github.com/dexterlb/mpvipc v0.0.0-20260722094525-0cf47d745b36
@@ -16,7 +16,7 @@ require (
 	github.com/djherbis/fscache v0.10.2-0.20260829235704-6d85d5878c22
 	github.com/djherbis/stream v1.5.1
 	github.com/djherbis/times v1.6.0
-	github.com/dustin/go-humanize v1.0.1
+	github.com/dustin/go-humanize v1.1.0
 	github.com/extism/go-sdk v1.7.1
 	github.com/fatih/structs v1.1.0
 	github.com/gen2brain/webp v0.6.4
@@ -39,8 +39,8 @@ require (
 	github.com/mattn/go-sqlite3 v1.14.52
 	github.com/microcosm-cc/bluemonday v1.0.27
 	github.com/mileusna/useragent v1.3.5
-	github.com/onsi/ginkgo/v2 v2.32.2
-	github.com/onsi/gomega v1.43.0
+	github.com/onsi/ginkgo/v2 v2.33.0
+	github.com/onsi/gomega v1.44.0
 	github.com/pelletier/go-toml/v2 v2.4.3
 	github.com/pmezard/go-difflib v1.0.0
 	github.com/pocketbase/dbx v1.12.0
@@ -81,15 +81,15 @@ require (
 	github.com/creack/pty v1.1.24 // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 // indirect
 	github.com/dylibso/observe-sdk/go v0.0.0-20240828172851-9145d8ad07e1 // indirect
-	github.com/ebitengine/purego v0.10.2 // indirect
+	github.com/ebitengine/purego v0.11.1 // indirect
 	github.com/fsnotify/fsnotify v1.10.1 // indirect
 	github.com/go-logr/logr v1.4.4 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
-	github.com/gobwas/glob v0.2.3 // indirect
+	github.com/gobwas/glob v1.0.0 // indirect
 	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
-	github.com/google/pprof v0.0.0-20260825171938-4d453200e7d9 // indirect
+	github.com/google/pprof v0.0.0-20260906184651-6331bc6350fe // indirect
 	github.com/google/subcommands v1.2.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
@@ -133,8 +133,8 @@ require (
 	go.yaml.in/yaml/v3 v3.0.5 // indirect
 	golang.org/x/crypto v0.57.0 // indirect
 	golang.org/x/mod v0.41.0 // indirect
-	golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5 // indirect
-	golang.org/x/tools v0.49.0 // indirect
+	golang.org/x/telemetry v0.0.0-20260908163034-4bcc4b2ee518 // indirect
+	golang.org/x/tools v0.50.0 // indirect
 	google.golang.org/protobuf v1.36.12 // indirect
 	gopkg.in/ini.v1 v1.67.3 // indirect
 	gopkg.in/natefinch/npipe.v2 v2.0.0-20160621034901-c1b8fa8bdcce // indirect
diff --git a/go.sum b/go.sum
index bcc1395ba..929366a76 100644
--- a/go.sum
+++ b/go.sum
@@ -14,8 +14,8 @@ github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuP
 github.com/aymerick/douceur v0.2.0/go.mod h1:wlT5vV2O3h55X9m7iVYN0TBM0NH/MmbLnd30/FjWUq4=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
-github.com/bmatcuk/doublestar/v4 v4.10.0 h1:zU9WiOla1YA122oLM6i4EXvGW62DvKZVxIe6TYWexEs=
-github.com/bmatcuk/doublestar/v4 v4.10.0/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
+github.com/bmatcuk/doublestar/v4 v4.10.2 h1:eF7W7HWKg3z9NrWV9pTLnNeoXaqq3Tq9DNKXVMfoCnw=
+github.com/bmatcuk/doublestar/v4 v4.10.2/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
 github.com/cespare/reflex v0.3.2 h1:SBN/trM94Ifs/ozz77cR3KxKm4dNE22zfG+0+54y5bQ=
 github.com/cespare/reflex v0.3.2/go.mod h1:3hfHPnuDWHtNWk0aLKwwP6pomRkS3r2nM127108jY/4=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
@@ -47,12 +47,12 @@ github.com/djherbis/times v1.6.0 h1:w2ctJ92J8fBvWPxugmXIv7Nz7Q3iDMKNx9v5ocVH20c=
 github.com/djherbis/times v1.6.0/go.mod h1:gOHeRAz2h+VJNZ5Gmc/o7iD9k4wW7NMVqieYCY99oc0=
 github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
 github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
-github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
-github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg=
+github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI=
 github.com/dylibso/observe-sdk/go v0.0.0-20240828172851-9145d8ad07e1 h1:idfl8M8rPW93NehFw5H1qqH8yG158t5POr+LX9avbJY=
 github.com/dylibso/observe-sdk/go v0.0.0-20240828172851-9145d8ad07e1/go.mod h1:C8DzXehI4zAbrdlbtOByKX6pfivJTBiV9Jjqv56Yd9Q=
-github.com/ebitengine/purego v0.10.2 h1:W809HbnvzAxgdm+aOvlSekrM16wGCdT/e76+9tS7gzE=
-github.com/ebitengine/purego v0.10.2/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/ebitengine/purego v0.11.1 h1:2zpWRSQNVKN4eKsKO9eM1ILDgWfYMY9GwqRmK6XeQ/0=
+github.com/ebitengine/purego v0.11.1/go.mod h1:DCHPP08djqhNSoTfImcnHYQRZmd0qhakvrozqaEYhGQ=
 github.com/extism/go-sdk v1.7.1 h1:lWJos6uY+tRFdlIHR+SJjwFDApY7OypS/2nMhiVQ9Sw=
 github.com/extism/go-sdk v1.7.1/go.mod h1:IT+Xdg5AZM9hVtpFUA+uZCJMge/hbvshl8bwzLtFyKA=
 github.com/fatih/structs v1.1.0 h1:Q7juDM0QtcnhCpeyLGQKyg4TOIghuNXrkL32pHAUMxo=
@@ -88,8 +88,8 @@ github.com/go-viper/encoding/ini v0.1.1 h1:MVWY7B2XNw7lnOqHutGRc97bF3rP7omOdgjdM
 github.com/go-viper/encoding/ini v0.1.1/go.mod h1:Pfi4M2V1eAGJVZ5q6FrkHPhtHED2YgLlXhvgMVrB+YQ=
 github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
-github.com/gobwas/glob v0.2.3 h1:A4xDbljILXROh+kObIiy5kIaPYD8e96x1tgBhUI5J+Y=
-github.com/gobwas/glob v0.2.3/go.mod h1:d3Ez4x06l9bZtSvzIay5+Yzi0fmZzPgnTbPcKjJAkT8=
+github.com/gobwas/glob v1.0.0 h1:p+FKbLEIsK1yZ39/OINwFvqNb5oyPY4H8xcy6uYu8dg=
+github.com/gobwas/glob v1.0.0/go.mod h1:oWCdo522i2P1n/hMXGNWs7yoV4wy/ciZuUIbvKj5rkc=
 github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
 github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
@@ -101,8 +101,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc h1:hd+uUVsB1vdxohPneMrhGH2YfQuH5hRIK9u4/XCeUtw=
 github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc/go.mod h1:SL66SJVysrh7YbDCP9tH30b8a9o/N2HeiQNUm85EKhc=
-github.com/google/pprof v0.0.0-20260825171938-4d453200e7d9 h1:dl4UZiszMU+NKHirOiCKTC+hRuNAQ0moHPxSg6WcU1o=
-github.com/google/pprof v0.0.0-20260825171938-4d453200e7d9/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
+github.com/google/pprof v0.0.0-20260906184651-6331bc6350fe h1:QAinXoAFJdGQYztXn3VpFey7KCwpedbZ/EkzbplQ0cY=
+github.com/google/pprof v0.0.0-20260906184651-6331bc6350fe/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
 github.com/google/subcommands v1.2.0 h1:vWQspBTo2nEqTUFita5/KeEWlUL8kQObDFbub/EN9oE=
 github.com/google/subcommands v1.2.0/go.mod h1:ZjhPrFU+Olkh9WazFPsl27BQ4UPiG37m3yTrtFlrHVk=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -180,10 +180,10 @@ github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOF
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/ogier/pflag v0.0.1 h1:RW6JSWSu/RkSatfcLtogGfFgpim5p7ARQ10ECk5O750=
 github.com/ogier/pflag v0.0.1/go.mod h1:zkFki7tvTa0tafRvTBIZTvzYyAu6kQhPZFnshFFPE+g=
-github.com/onsi/ginkgo/v2 v2.32.2 h1:2o6vyFvR6snrJWgRVztC+OwuqqPEMI1UzYl2s2iU7Cg=
-github.com/onsi/ginkgo/v2 v2.32.2/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
-github.com/onsi/gomega v1.43.0 h1:VlG/1FxqNxhSO+lq/OHBNaaqwiBK/mO8JbVkX9Y+FeU=
-github.com/onsi/gomega v1.43.0/go.mod h1:REff/hsDsodHoKlWsP2mAPhu1+5/6hVYNf9rIEBpeSg=
+github.com/onsi/ginkgo/v2 v2.33.0 h1:C8gBA6Uc2ZEubiV+SXiu5tZnMTwEmXHgkJwGozKtZf8=
+github.com/onsi/ginkgo/v2 v2.33.0/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
+github.com/onsi/gomega v1.44.0 h1:eAiGl3Pw5jz5GQdDff0BcxYpAX1JxW8xD7mFUuwNfZQ=
+github.com/onsi/gomega v1.44.0/go.mod h1:e/C2HwaZ1DhvjzXXuFhcR7hY7Sh9pl7MmoWKEjzwcdA=
 github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
 github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
@@ -309,8 +309,8 @@ golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5h
 golang.org/x/sys v0.0.0-20220615213510-4f61da869c0c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
 golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
-golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5 h1:ZUSxONxc981v7AW7QUg+I9WwZzSTTJ019ENBYr5pV/Q=
-golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5/go.mod h1:LVehoXe41cL5SCVQilsV7Gg6BNG+Js6P9PhSbYTIUkQ=
+golang.org/x/telemetry v0.0.0-20260908163034-4bcc4b2ee518 h1:F5BWKvW126NXR74uxkxuc1jQHhm/rwm/J3rSiFyuRs4=
+golang.org/x/telemetry v0.0.0-20260908163034-4bcc4b2ee518/go.mod h1:i+ivNqjDnTF3WTElsdk5g9V5DTSBYgdNo7xTU9SDwYA=
 golang.org/x/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE=
 golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
@@ -320,8 +320,8 @@ golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
 golang.org/x/time v0.16.0 h1:vMb6ptszcQMkcwiRTAuNNU50gom6++Q/6gY2hDM6VDE=
 golang.org/x/time v0.16.0/go.mod h1:rVKOqvZeKvrDKTQiAHJ7wmwP0RzleSphoEA9RcdLA0s=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
-golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
-golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
+golang.org/x/tools v0.50.0 h1:c2ifzfcuY7L90lZ2aKd8S4K2NpASF08SZx9ZuJkHmSU=
+golang.org/x/tools v0.50.0/go.mod h1:7ulVMw3831Mwi5EZD6RomGyffr4VFjuNYXf2BbCEAV0=
 google.golang.org/appengine v1.6.5/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCIDZVag1xfc=
 google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
 google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

From 4113d954ca0cbfe5e9f89a919c09f0fe6f7d1339 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 26 Sep 2026 11:43:00 -0400
Subject: [PATCH 185/200] fix(scanner): register .webm as audio/webm (#6230)

Go 1.27 changed the built-in MIME type for .webm from audio/webm to video/webm, so the scanner stopped treating WebM files as audio after the Go bump in 0.64.0. Map .webm to audio/webm in mime_types.yaml so it no longer depends on the Go version.
---
 model/file_types_test.go  | 4 ++++
 resources/mime_types.yaml | 1 +
 2 files changed, 5 insertions(+)

diff --git a/model/file_types_test.go b/model/file_types_test.go
index 93301e151..07dac645e 100644
--- a/model/file_types_test.go
+++ b/model/file_types_test.go
@@ -18,6 +18,10 @@ var _ = Describe("File Types()", func() {
 			Expect(model.IsAudioFile("test.flac")).To(BeTrue())
 		})
 
+		It("returns true for a WebM file", func() {
+			Expect(model.IsAudioFile("test.webm")).To(BeTrue())
+		})
+
 		It("returns false for a non-audio file", func() {
 			Expect(model.IsAudioFile("test.jpg")).To(BeFalse())
 		})
diff --git a/resources/mime_types.yaml b/resources/mime_types.yaml
index 18a2c22b5..1a963bdf7 100644
--- a/resources/mime_types.yaml
+++ b/resources/mime_types.yaml
@@ -29,6 +29,7 @@ types:
   .wvp: audio/x-wavpack 
   .tak: audio/tak 
   .mka: audio/x-matroska 
+  .webm: audio/webm
 
 # Image
   .gif: image/gif

From bb7d81a5ea1b4ad7d5479c82c9abbabc6c66a359 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 26 Sep 2026 12:30:52 -0400
Subject: [PATCH 186/200] refactor(scanner): remove the unused legacy ffmpeg
 metadata extractor (#6231)

* refactor(scanner): remove the legacy ffmpeg metadata extractor

The ffmpeg extractor in scanner/metadata_old has not been wired into the scanner since the taglib-only rewrite, so it was only exercised by its own tests. Remove the package, the FFmpeg.Probe method and its ffmetadata command that only it used, and the startup fallback for Scanner.Extractor="ffmpeg". Configs that still set it keep working: unknown extractors already fall back to taglib with a warning.

* fix(conf): warn and fall back to taglib for an unknown Scanner.Extractor

Validate the option when loading the config, so invalid values such as the removed "ffmpeg" extractor are reported once at startup instead of only when a library storage is created.
---
 conf/configuration.go                         |   5 +
 conf/configuration_test.go                    |  21 +
 core/ffmpeg/ffmpeg.go                         |  27 --
 core/ffmpeg/ffmpeg_test.go                    |  15 +-
 scanner/metadata_old/ffmpeg/ffmpeg.go         | 211 ---------
 .../metadata_old/ffmpeg/ffmpeg_suite_test.go  |  17 -
 scanner/metadata_old/ffmpeg/ffmpeg_test.go    | 375 ----------------
 scanner/metadata_old/metadata.go              | 411 ------------------
 .../metadata_old/metadata_internal_test.go    | 144 ------
 scanner/metadata_old/metadata_suite_test.go   |  17 -
 scanner/metadata_old/metadata_test.go         |  95 ----
 server/initial_setup.go                       |   4 -
 tests/harness/harness.go                      |   2 -
 tests/mock_ffmpeg.go                          |   6 -
 14 files changed, 30 insertions(+), 1320 deletions(-)
 delete mode 100644 scanner/metadata_old/ffmpeg/ffmpeg.go
 delete mode 100644 scanner/metadata_old/ffmpeg/ffmpeg_suite_test.go
 delete mode 100644 scanner/metadata_old/ffmpeg/ffmpeg_test.go
 delete mode 100644 scanner/metadata_old/metadata.go
 delete mode 100644 scanner/metadata_old/metadata_internal_test.go
 delete mode 100644 scanner/metadata_old/metadata_suite_test.go
 delete mode 100644 scanner/metadata_old/metadata_test.go

diff --git a/conf/configuration.go b/conf/configuration.go
index 6f295ebeb..0173f5628 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -514,6 +514,11 @@ func Load(noConfigDump bool) {
 		Server.UICoverArtSize = newValue
 	}
 
+	if Server.Scanner.Extractor != consts.DefaultScannerExtractor {
+		log.Warn("Invalid Scanner.Extractor, using default", "value", Server.Scanner.Extractor, "default", consts.DefaultScannerExtractor)
+		Server.Scanner.Extractor = consts.DefaultScannerExtractor
+	}
+
 	// Floor MaxImageSize at MaxImageUploadSize so accepted uploads can always be read back.
 	imgSize, _ := humanize.ParseBytes(Server.MaxImageSize)
 	uploadSize, _ := humanize.ParseBytes(Server.MaxImageUploadSize)
diff --git a/conf/configuration_test.go b/conf/configuration_test.go
index 9404f01bc..8c4c8ab86 100644
--- a/conf/configuration_test.go
+++ b/conf/configuration_test.go
@@ -402,6 +402,27 @@ var _ = Describe("Configuration", func() {
 		})
 	})
 
+	Describe("Scanner.Extractor", func() {
+		BeforeEach(func() {
+			viper.Reset()
+			conf.SetViperDefaults()
+			viper.SetDefault("datafolder", GinkgoT().TempDir())
+			viper.SetDefault("loglevel", "error")
+			conf.ResetConf()
+		})
+
+		It("falls back to taglib for an unknown extractor", func() {
+			viper.SetDefault("scanner.extractor", "ffmpeg")
+			conf.Load(true)
+			Expect(conf.Server.Scanner.Extractor).To(Equal("taglib"))
+		})
+
+		It("keeps taglib", func() {
+			conf.Load(true)
+			Expect(conf.Server.Scanner.Extractor).To(Equal("taglib"))
+		})
+	})
+
 	Describe("EnforceNonRootUser", func() {
 		It("defaults to false", func() {
 			conf.Load(true)
diff --git a/core/ffmpeg/ffmpeg.go b/core/ffmpeg/ffmpeg.go
index cc38dd9de..af59178af 100644
--- a/core/ffmpeg/ffmpeg.go
+++ b/core/ffmpeg/ffmpeg.go
@@ -49,7 +49,6 @@ type FFmpeg interface {
 	Transcode(ctx context.Context, opts TranscodeOptions) (io.ReadCloser, error)
 	ExtractImage(ctx context.Context, path string) (io.ReadCloser, error)
 	ConvertAnimatedImage(ctx context.Context, reader io.Reader, maxSize int, quality int) (io.ReadCloser, error)
-	Probe(ctx context.Context, files []string) (string, error)
 	ProbeAudioStream(ctx context.Context, filePath string) (*AudioProbeResult, error)
 	CmdPath() (string, error)
 	IsAvailable() bool
@@ -68,7 +67,6 @@ var ErrAnimatedWebPUnsupported = errors.New("ffmpeg lacks libwebp_anim encoder 
 
 const (
 	extractImageCmd     = "ffmpeg -i %s -map 0:v -map -0:V -vcodec copy -f image2pipe -"
-	probeCmd            = "ffmpeg %s -f ffmetadata"
 	probeAudioStreamCmd = "ffprobe -v error -select_streams a:0 -print_format json -show_streams -show_format %s"
 )
 
@@ -149,17 +147,6 @@ func fileExists(path string) error {
 	return nil
 }
 
-func (e *ffmpeg) Probe(ctx context.Context, files []string) (string, error) {
-	if _, err := ffmpegCmd(); err != nil {
-		return "", err
-	}
-	args := createProbeCommand(probeCmd, files)
-	log.Trace(ctx, "Executing ffmpeg command", "args", args)
-	cmd := exec.CommandContext(ctx, args[0], args[1:]...) // #nosec
-	output, _ := cmd.CombinedOutput()
-	return string(output), nil
-}
-
 func (e *ffmpeg) ProbeAudioStream(ctx context.Context, filePath string) (*AudioProbeResult, error) {
 	if _, err := ffmpegCmd(); err != nil {
 		return nil, err
@@ -593,20 +580,6 @@ func createFFmpegCommand(cmd, path string, maxBitRate, offset int) []string {
 	return args
 }
 
-func createProbeCommand(cmd string, inputs []string) []string {
-	var args []string
-	for _, s := range fixCmd(cmd) {
-		if s == "%s" {
-			for _, inp := range inputs {
-				args = append(args, "-i", inp)
-			}
-		} else {
-			args = append(args, s)
-		}
-	}
-	return args
-}
-
 func fixCmd(cmd string) []string {
 	split := strings.Fields(cmd)
 	cmdPath, _ := ffmpegCmd()
diff --git a/core/ffmpeg/ffmpeg_test.go b/core/ffmpeg/ffmpeg_test.go
index dbc8fa3c8..46684fe14 100644
--- a/core/ffmpeg/ffmpeg_test.go
+++ b/core/ffmpeg/ffmpeg_test.go
@@ -62,23 +62,16 @@ var _ = Describe("ffmpeg", func() {
 		})
 	})
 
-	Describe("createProbeCommand", func() {
-		It("creates a valid command line", func() {
-			args := createProbeCommand(probeCmd, []string{"/music library/one.mp3", "/music library/two.mp3"})
-			Expect(args).To(Equal([]string{"ffmpeg", "-i", "/music library/one.mp3", "-i", "/music library/two.mp3", "-f", "ffmetadata"}))
-		})
-	})
-
 	When("ffmpegPath is set", func() {
 		It("returns the correct ffmpeg path", func() {
 			ffmpegPath = "/usr/bin/ffmpeg"
-			args := createProbeCommand(probeCmd, []string{"one.mp3"})
-			Expect(args).To(Equal([]string{"/usr/bin/ffmpeg", "-i", "one.mp3", "-f", "ffmetadata"}))
+			args := createFFmpegCommand("ffmpeg -i %s -f mp3 -", "one.mp3", 0, 0)
+			Expect(args).To(Equal([]string{"/usr/bin/ffmpeg", "-i", "one.mp3", "-f", "mp3", "-"}))
 		})
 		It("returns the correct ffmpeg path with spaces", func() {
 			ffmpegPath = "/usr/bin/with spaces/ffmpeg.exe"
-			args := createProbeCommand(probeCmd, []string{"one.mp3"})
-			Expect(args).To(Equal([]string{"/usr/bin/with spaces/ffmpeg.exe", "-i", "one.mp3", "-f", "ffmetadata"}))
+			args := createFFmpegCommand("ffmpeg -i %s -f mp3 -", "one.mp3", 0, 0)
+			Expect(args).To(Equal([]string{"/usr/bin/with spaces/ffmpeg.exe", "-i", "one.mp3", "-f", "mp3", "-"}))
 		})
 	})
 
diff --git a/scanner/metadata_old/ffmpeg/ffmpeg.go b/scanner/metadata_old/ffmpeg/ffmpeg.go
deleted file mode 100644
index 8fc496c02..000000000
--- a/scanner/metadata_old/ffmpeg/ffmpeg.go
+++ /dev/null
@@ -1,211 +0,0 @@
-package ffmpeg
-
-import (
-	"bufio"
-	"context"
-	"errors"
-	"regexp"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/navidrome/navidrome/core/ffmpeg"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/scanner/metadata_old"
-)
-
-const ExtractorID = "ffmpeg"
-
-type Extractor struct {
-	ffmpeg ffmpeg.FFmpeg
-}
-
-func (e *Extractor) Parse(files ...string) (map[string]metadata_old.ParsedTags, error) {
-	output, err := e.ffmpeg.Probe(context.TODO(), files)
-	if err != nil {
-		log.Error("Cannot use ffmpeg to extract tags. Aborting", err)
-		return nil, err
-	}
-	fileTags := map[string]metadata_old.ParsedTags{}
-	if len(output) == 0 {
-		return fileTags, errors.New("error extracting metadata files")
-	}
-	infos := e.parseOutput(output)
-	for file, info := range infos {
-		tags, err := e.extractMetadata(file, info)
-		// Skip files with errors
-		if err == nil {
-			fileTags[file] = tags
-		}
-	}
-	return fileTags, nil
-}
-
-func (e *Extractor) CustomMappings() metadata_old.ParsedTags {
-	return metadata_old.ParsedTags{
-		"disc":         {"tpa"},
-		"has_picture":  {"metadata_block_picture"},
-		"originaldate": {"tdor"},
-	}
-}
-
-func (e *Extractor) Version() string {
-	return e.ffmpeg.Version()
-}
-
-func (e *Extractor) extractMetadata(filePath, info string) (metadata_old.ParsedTags, error) {
-	tags := e.parseInfo(info)
-	if len(tags) == 0 {
-		log.Trace("Not a media file. Skipping", "filePath", filePath)
-		return nil, errors.New("not a media file")
-	}
-
-	return tags, nil
-}
-
-var (
-	// Input #0, mp3, from 'groovin.mp3':
-	inputRegex = regexp.MustCompile(`(?m)^Input #\d+,.*,\sfrom\s'(.*)'`)
-
-	//    TITLE           : Back In Black
-	tagsRx = regexp.MustCompile(`(?i)^\s{4,6}([\w\s-]+)\s*:(.*)`)
-
-	//                    : Second comment line
-	continuationRx = regexp.MustCompile(`(?i)^\s+:(.*)`)
-
-	//  Duration: 00:04:16.00, start: 0.000000, bitrate: 995 kb/s`
-	durationRx = regexp.MustCompile(`^\s\sDuration: ([\d.:]+).*bitrate: (\d+)`)
-
-	//    Stream #0:0: Audio: mp3, 44100 Hz, stereo, fltp, 192 kb/s
-	bitRateRx = regexp.MustCompile(`^\s{2,4}Stream #\d+:\d+: Audio:.*, (\d+) kb/s`)
-
-	//    Stream #0:0: Audio: mp3, 44100 Hz, stereo, fltp, 192 kb/s
-	//    Stream #0:0: Audio: flac, 44100 Hz, stereo, s16
-	//    Stream #0:0: Audio: dsd_lsbf_planar, 352800 Hz, stereo, fltp, 5644 kb/s
-	audioStreamRx = regexp.MustCompile(`^\s{2,4}Stream #\d+:\d+.*: Audio: (.*), (.*) Hz, ([\w.]+),*(.*.,)*`)
-
-	//    Stream #0:1: Video: mjpeg, yuvj444p(pc, bt470bg/unknown/unknown), 600x600 [SAR 1:1 DAR 1:1], 90k tbr, 90k tbn, 90k tbc`
-	coverRx = regexp.MustCompile(`^\s{2,4}Stream #\d+:.+: (Video):.*`)
-)
-
-func (e *Extractor) parseOutput(output string) map[string]string {
-	outputs := map[string]string{}
-	all := inputRegex.FindAllStringSubmatchIndex(output, -1)
-	for i, loc := range all {
-		// Filename is the first captured group
-		file := output[loc[2]:loc[3]]
-
-		// File info is everything from the match, up until the beginning of the next match
-		info := ""
-		initial := loc[1]
-		if i < len(all)-1 {
-			end := all[i+1][0] - 1
-			info = output[initial:end]
-		} else {
-			// if this is the last match
-			info = output[initial:]
-		}
-		outputs[file] = info
-	}
-	return outputs
-}
-
-func (e *Extractor) parseInfo(info string) map[string][]string {
-	tags := map[string][]string{}
-
-	reader := strings.NewReader(info)
-	scanner := bufio.NewScanner(reader)
-	lastTag := ""
-	for scanner.Scan() {
-		line := scanner.Text()
-		if len(line) == 0 {
-			continue
-		}
-		match := tagsRx.FindStringSubmatch(line)
-		if len(match) > 0 {
-			tagName := strings.TrimSpace(strings.ToLower(match[1]))
-			if tagName != "" {
-				tagValue := strings.TrimSpace(match[2])
-				tags[tagName] = append(tags[tagName], tagValue)
-				lastTag = tagName
-				continue
-			}
-		}
-
-		if lastTag != "" {
-			match = continuationRx.FindStringSubmatch(line)
-			if len(match) > 0 {
-				if tags[lastTag] == nil {
-					tags[lastTag] = []string{""}
-				}
-				tagValue := tags[lastTag][0]
-				tags[lastTag][0] = tagValue + "\n" + strings.TrimSpace(match[1])
-				continue
-			}
-		}
-
-		lastTag = ""
-		match = coverRx.FindStringSubmatch(line)
-		if len(match) > 0 {
-			tags["has_picture"] = []string{"true"}
-			continue
-		}
-
-		match = durationRx.FindStringSubmatch(line)
-		if len(match) > 0 {
-			tags["duration"] = []string{e.parseDuration(match[1])}
-			if len(match) > 1 {
-				tags["bitrate"] = []string{match[2]}
-			}
-			continue
-		}
-
-		match = bitRateRx.FindStringSubmatch(line)
-		if len(match) > 0 {
-			tags["bitrate"] = []string{match[1]}
-		}
-
-		match = audioStreamRx.FindStringSubmatch(line)
-		if len(match) > 0 {
-			tags["samplerate"] = []string{match[2]}
-			tags["channels"] = []string{e.parseChannels(match[3])}
-		}
-	}
-
-	comment := tags["comment"]
-	if len(comment) > 0 && comment[0] == "Cover (front)" {
-		delete(tags, "comment")
-	}
-
-	return tags
-}
-
-var zeroTime = time.Date(0000, time.January, 1, 0, 0, 0, 0, time.UTC)
-
-func (e *Extractor) parseDuration(tag string) string {
-	d, err := time.Parse("15:04:05", tag)
-	if err != nil {
-		return "0"
-	}
-	return strconv.FormatFloat(d.Sub(zeroTime).Seconds(), 'f', 2, 32)
-}
-
-func (e *Extractor) parseChannels(tag string) string {
-	switch tag {
-	case "mono":
-		return "1"
-	case "stereo":
-		return "2"
-	case "5.1":
-		return "6"
-	case "7.1":
-		return "8"
-	default:
-		return "0"
-	}
-}
-
-// Inputs will always be absolute paths
-func init() {
-	metadata_old.RegisterExtractor(ExtractorID, &Extractor{ffmpeg: ffmpeg.New()})
-}
diff --git a/scanner/metadata_old/ffmpeg/ffmpeg_suite_test.go b/scanner/metadata_old/ffmpeg/ffmpeg_suite_test.go
deleted file mode 100644
index 815940381..000000000
--- a/scanner/metadata_old/ffmpeg/ffmpeg_suite_test.go
+++ /dev/null
@@ -1,17 +0,0 @@
-package ffmpeg
-
-import (
-	"testing"
-
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/tests"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-func TestFFMpeg(t *testing.T) {
-	tests.Init(t, true)
-	log.SetLevel(log.LevelFatal)
-	RegisterFailHandler(Fail)
-	RunSpecs(t, "FFMpeg Suite")
-}
diff --git a/scanner/metadata_old/ffmpeg/ffmpeg_test.go b/scanner/metadata_old/ffmpeg/ffmpeg_test.go
deleted file mode 100644
index 6c7f43a5d..000000000
--- a/scanner/metadata_old/ffmpeg/ffmpeg_test.go
+++ /dev/null
@@ -1,375 +0,0 @@
-package ffmpeg
-
-import (
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Extractor", func() {
-	var e *Extractor
-	BeforeEach(func() {
-		e = &Extractor{}
-	})
-
-	Context("extractMetadata", func() {
-		It("extracts MusicBrainz custom tags", func() {
-			const output = `
-Input #0, ape, from './Capture/02 01 - Symphony No. 5 in C minor, Op. 67 I. Allegro con brio - Ludwig van Beethoven.ape':
-  Metadata:
-    ALBUM           : Forever Classics
-    ARTIST          : Ludwig van Beethoven
-    TITLE           : Symphony No. 5 in C minor, Op. 67: I. Allegro con brio
-    MUSICBRAINZ_ALBUMSTATUS: official
-    MUSICBRAINZ_ALBUMTYPE: album
-    MusicBrainz_AlbumComment: MP3
-    Musicbrainz_Albumid: 71eb5e4a-90e2-4a31-a2d1-a96485fcb667
-    musicbrainz_trackid: ffe06940-727a-415a-b608-b7e45737f9d8
-    Musicbrainz_Artistid: 1f9df192-a621-4f54-8850-2c5373b7eac9
-    Musicbrainz_Albumartistid: 89ad4ac3-39f7-470e-963a-56509c546377
-    Musicbrainz_Releasegroupid: 708b1ae1-2d3d-34c7-b764-2732b154f5b6
-    musicbrainz_releasetrackid: 6fee2e35-3049-358f-83be-43b36141028b
-    CatalogNumber   : PLD 1201
-`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(SatisfyAll(
-				HaveKeyWithValue("catalognumber", []string{"PLD 1201"}),
-				HaveKeyWithValue("musicbrainz_trackid", []string{"ffe06940-727a-415a-b608-b7e45737f9d8"}),
-				HaveKeyWithValue("musicbrainz_albumid", []string{"71eb5e4a-90e2-4a31-a2d1-a96485fcb667"}),
-				HaveKeyWithValue("musicbrainz_artistid", []string{"1f9df192-a621-4f54-8850-2c5373b7eac9"}),
-				HaveKeyWithValue("musicbrainz_albumartistid", []string{"89ad4ac3-39f7-470e-963a-56509c546377"}),
-				HaveKeyWithValue("musicbrainz_albumtype", []string{"album"}),
-				HaveKeyWithValue("musicbrainz_albumcomment", []string{"MP3"}),
-			))
-		})
-
-		It("detects embedded cover art correctly", func() {
-			const output = `
-Input #0, mp3, from '/Users/deluan/Music/iTunes/iTunes Media/Music/Compilations/Putumayo Presents Blues Lounge/09 Pablo's Blues.mp3':
-  Metadata:
-    compilation     : 1
-  Duration: 00:00:01.02, start: 0.000000, bitrate: 477 kb/s
-    Stream #0:0: Audio: mp3, 44100 Hz, stereo, fltp, 192 kb/s
-    Stream #0:1: Video: mjpeg, yuvj444p(pc, bt470bg/unknown/unknown), 600x600 [SAR 1:1 DAR 1:1], 90k tbr, 90k tbn, 90k tbc`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("has_picture", []string{"true"}))
-		})
-
-		It("detects embedded cover art in ffmpeg 4.4 output", func() {
-			const output = `
-Input #0, flac, from '/run/media/naomi/Archivio/Musica/Katy Perry/Chained to the Rhythm/01 Katy Perry featuring Skip Marley - Chained to the Rhythm.flac':
-  Metadata:
-    ARTIST          : Katy Perry featuring Skip Marley
-  Duration: 00:03:57.91, start: 0.000000, bitrate: 983 kb/s
-  Stream #0:0: Audio: flac, 44100 Hz, stereo, s16
-  Stream #0:1: Video: mjpeg (Baseline), yuvj444p(pc, bt470bg/unknown/unknown), 599x518, 90k tbr, 90k tbn, 90k tbc (attached pic)
-    Metadata:
-      comment         : Cover (front)`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("has_picture", []string{"true"}))
-		})
-
-		It("detects embedded cover art in ogg containers", func() {
-			const output = `
-Input #0, ogg, from '/Users/deluan/Music/iTunes/iTunes Media/Music/_Testes/Jamaican In New York/01-02 Jamaican In New York (Album Version).opus':
-  Duration: 00:04:28.69, start: 0.007500, bitrate: 139 kb/s
-    Stream #0:0(eng): Audio: opus, 48000 Hz, stereo, fltp
-    Metadata:
-      ALBUM           : Jamaican In New York
-      metadata_block_picture: AAAAAwAAAAppbWFnZS9qcGVnAAAAAAAAAAAAAAAAAAAAAAAAAAAAA4Id/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsKCwsNDhIQDQ4RDgsLEBYQERMUFRUVDA8XGBYUGBIUFRT/2wBDAQMEBAUEBQkFBQkUDQsNFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQ
-      TITLE           : Jamaican In New York (Album Version)`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKey("metadata_block_picture"))
-			md = md.Map(e.CustomMappings())
-			Expect(md).To(HaveKey("has_picture"))
-		})
-
-		It("detects embedded cover art in m4a containers", func() {
-			const output = `
-Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'Putumayo Presents_ Euro Groove/01 Destins et Désirs.m4a':
-  Metadata:
-    album           : Putumayo Presents: Euro Groove
-  Duration: 00:05:15.81, start: 0.047889, bitrate: 133 kb/s
-  Stream #0:0[0x1](und): Audio: aac (LC) (mp4a / 0x6134706D), 44100 Hz, stereo, fltp, 125 kb/s (default)
-    Metadata:
-      creation_time   : 2008-03-11T21:03:23.000000Z
-      vendor_id       : [0][0][0][0]
-  Stream #0:1[0x0]: Video: png, rgb24(pc), 350x350, 90k tbr, 90k tbn (attached pic)
-`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("has_picture", []string{"true"}))
-		})
-
-		It("gets bitrate from the stream, if available", func() {
-			const output = `
-Input #0, mp3, from '/Users/deluan/Music/iTunes/iTunes Media/Music/Compilations/Putumayo Presents Blues Lounge/09 Pablo's Blues.mp3':
-  Duration: 00:00:01.02, start: 0.000000, bitrate: 477 kb/s
-    Stream #0:0: Audio: mp3, 44100 Hz, stereo, fltp, 192 kb/s`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("bitrate", []string{"192"}))
-		})
-
-		It("parses duration with milliseconds", func() {
-			const output = `
-Input #0, mp3, from '/Users/deluan/Music/iTunes/iTunes Media/Music/Compilations/Putumayo Presents Blues Lounge/09 Pablo's Blues.mp3':
-  Duration: 00:05:02.63, start: 0.000000, bitrate: 140 kb/s`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("duration", []string{"302.63"}))
-		})
-
-		It("parse flac bitrates", func() {
-			const output = `
-Input #0, mp3, from '/Users/deluan/Music/iTunes/iTunes Media/Music/Compilations/Putumayo Presents Blues Lounge/09 Pablo's Blues.mp3':
-  Duration: 00:00:01.02, start: 0.000000, bitrate: 477 kb/s
-    Stream #0:0: Audio: mp3, 44100 Hz, stereo, fltp, 192 kb/s`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("channels", []string{"2"}))
-		})
-
-		It("parse channels from the stream with bitrate", func() {
-			const output = `
-Input #0, flac, from '/Users/deluan/Music/Music/Media/__/Crazy For You/01-01 Crazy For You.flac':
-  Metadata:
-    TITLE           : Crazy For You
-  Duration: 00:04:13.00, start: 0.000000, bitrate: 852 kb/s
-  Stream #0:0: Audio: flac, 44100 Hz, stereo, s16
-  Stream #0:1: Video: mjpeg (Progressive), yuvj444p(pc, bt470bg/unknown/unknown), 600x600, 90k tbr, 90k tbn, 90k tbc (attached pic)
-`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("bitrate", []string{"852"}))
-		})
-
-		It("parse 7.1 channels from the stream", func() {
-			const output = `
-Input #0, wav, from '/Users/deluan/Music/Music/Media/_/multichannel/Nums_7dot1_24_48000.wav':
-  Duration: 00:00:09.05, bitrate: 9216 kb/s
-  Stream #0:0: Audio: pcm_s24le ([1][0][0][0] / 0x0001), 48000 Hz, 7.1, s32 (24 bit), 9216 kb/s`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("channels", []string{"8"}))
-		})
-
-		It("parse channels from the stream without bitrate", func() {
-			const output = `
-Input #0, flac, from '/Users/deluan/Music/iTunes/iTunes Media/Music/Compilations/Putumayo Presents Blues Lounge/09 Pablo's Blues.flac':
-  Duration: 00:00:01.02, start: 0.000000, bitrate: 1371 kb/s
-    Stream #0:0: Audio: flac, 44100 Hz, stereo, fltp, s32 (24 bit)`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("channels", []string{"2"}))
-		})
-
-		It("parse channels from the stream with lang", func() {
-			const output = `
-Input #0, flac, from '/Users/deluan/Music/iTunes/iTunes Media/Music/Compilations/Putumayo Presents Blues Lounge/09 Pablo's Blues.m4a':
-  Duration: 00:00:01.02, start: 0.000000, bitrate: 1371 kb/s
-    Stream #0:0(eng): Audio: aac (LC) (mp4a / 0x6134706D), 44100 Hz, stereo, fltp, 262 kb/s (default)`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("channels", []string{"2"}))
-		})
-
-		It("parse channels from the stream with lang 2", func() {
-			const output = `
-Input #0, flac, from '/Users/deluan/Music/iTunes/iTunes Media/Music/Compilations/Putumayo Presents Blues Lounge/09 Pablo's Blues.m4a':
-  Duration: 00:00:01.02, start: 0.000000, bitrate: 1371 kb/s
-    Stream #0:0(eng): Audio: vorbis, 44100 Hz, stereo, fltp, 192 kb/s`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("channels", []string{"2"}))
-		})
-
-		It("parse sampleRate from the stream", func() {
-			const output = `
-Input #0, dsf, from '/Users/deluan/Downloads/06-04 Perpetual Change.dsf':
-  Duration: 00:14:19.46, start: 0.000000, bitrate: 5644 kb/s
-  Stream #0:0: Audio: dsd_lsbf_planar, 352800 Hz, stereo, fltp, 5644 kb/s`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("samplerate", []string{"352800"}))
-		})
-
-		It("parse sampleRate from the stream", func() {
-			const output = `
-Input #0, wav, from '/Users/deluan/Music/Music/Media/_/multichannel/Nums_7dot1_24_48000.wav':
-  Duration: 00:00:09.05, bitrate: 9216 kb/s
-  Stream #0:0: Audio: pcm_s24le ([1][0][0][0] / 0x0001), 48000 Hz, 7.1, s32 (24 bit), 9216 kb/s`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("samplerate", []string{"48000"}))
-		})
-
-		It("parses stream level tags", func() {
-			const output = `
-Input #0, ogg, from './01-02 Drive (Teku).opus':
-  Metadata:
-    ALBUM           : Hot Wheels Acceleracers Soundtrack
-  Duration: 00:03:37.37, start: 0.007500, bitrate: 135 kb/s
-    Stream #0:0(eng): Audio: opus, 48000 Hz, stereo, fltp
-    Metadata:
-      TITLE           : Drive (Teku)`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("title", []string{"Drive (Teku)"}))
-		})
-
-		It("does not overlap top level tags with the stream level tags", func() {
-			const output = `
-Input #0, mp3, from 'groovin.mp3':
-  Metadata:
-    title           : Groovin' (feat. Daniel Sneijers, Susanne Alt)
-  Duration: 00:03:34.28, start: 0.025056, bitrate: 323 kb/s
-    Metadata:
-      title           : garbage`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("title", []string{"Groovin' (feat. Daniel Sneijers, Susanne Alt)", "garbage"}))
-		})
-
-		It("parses multiline tags", func() {
-			const outputWithMultilineComment = `
-Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'modulo.m4a':
-  Metadata:
-    comment         : https://www.mixcloud.com/codigorock/30-minutos-com-saara-saara/
-                    :
-                    : Tracklist:
-                    :
-                    : 01. Saara Saara
-                    : 02. Carta Corrente
-                    : 03. X
-                    : 04. Eclipse Lunar
-                    : 05. Vírus de Sírius
-                    : 06. Doktor Fritz
-                    : 07. Wunderbar
-                    : 08. Quarta Dimensão
-  Duration: 00:26:46.96, start: 0.052971, bitrate: 69 kb/s`
-			const expectedComment = `https://www.mixcloud.com/codigorock/30-minutos-com-saara-saara/
-
-Tracklist:
-
-01. Saara Saara
-02. Carta Corrente
-03. X
-04. Eclipse Lunar
-05. Vírus de Sírius
-06. Doktor Fritz
-07. Wunderbar
-08. Quarta Dimensão`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", outputWithMultilineComment)
-			Expect(md).To(HaveKeyWithValue("comment", []string{expectedComment}))
-		})
-
-		It("parses sort tags correctly", func() {
-			const output = `
-Input #0, mp3, from '/Users/deluan/Downloads/椎名林檎 - 加爾基 精液 栗ノ花 - 2003/02 - ドツペルゲンガー.mp3':
-  Metadata:
-    title-sort      : Dopperugengā
-    album           : 加爾基 精液 栗ノ花
-    artist          : 椎名林檎
-    album_artist    : 椎名林檎
-    title           : ドツペルゲンガー
-    albumsort       : Kalk Samen Kuri No Hana
-    artist_sort     : Shiina, Ringo
-    ALBUMARTISTSORT : Shiina, Ringo
-`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(SatisfyAll(
-				HaveKeyWithValue("title", []string{"ドツペルゲンガー"}),
-				HaveKeyWithValue("album", []string{"加爾基 精液 栗ノ花"}),
-				HaveKeyWithValue("artist", []string{"椎名林檎"}),
-				HaveKeyWithValue("album_artist", []string{"椎名林檎"}),
-				HaveKeyWithValue("title-sort", []string{"Dopperugengā"}),
-				HaveKeyWithValue("albumsort", []string{"Kalk Samen Kuri No Hana"}),
-				HaveKeyWithValue("artist_sort", []string{"Shiina, Ringo"}),
-				HaveKeyWithValue("albumartistsort", []string{"Shiina, Ringo"}),
-			))
-		})
-
-		It("ignores cover comment", func() {
-			const output = `
-Input #0, mp3, from './Edie Brickell/Picture Perfect Morning/01-01 Tomorrow Comes.mp3':
-  Metadata:
-    title           : Tomorrow Comes
-    artist          : Edie Brickell
-  Duration: 00:03:56.12, start: 0.000000, bitrate: 332 kb/s
-    Stream #0:0: Audio: mp3, 44100 Hz, stereo, s16p, 320 kb/s
-    Stream #0:1: Video: mjpeg, yuvj420p(pc, bt470bg/unknown/unknown), 1200x1200 [SAR 72:72 DAR 1:1], 90k tbr, 90k tbn, 90k tbc
-    Metadata:
-      comment         : Cover (front)`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).ToNot(HaveKey("comment"))
-		})
-
-		It("parses tags with spaces in the name", func() {
-			const output = `
-Input #0, mp3, from '/Users/deluan/Music/Music/Media/_/Wyclef Jean - From the Hut, to the Projects, to the Mansion/10 - The Struggle (interlude).mp3':
-  Metadata:
-    ALBUM ARTIST    : Wyclef Jean
-`
-			md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-			Expect(md).To(HaveKeyWithValue("album artist", []string{"Wyclef Jean"}))
-		})
-	})
-
-	It("parses an integer TBPM tag", func() {
-		const output = `
-		Input #0, mp3, from 'tests/fixtures/test.mp3':
-		  Metadata:
-		    TBPM            : 123`
-		md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-		Expect(md).To(HaveKeyWithValue("tbpm", []string{"123"}))
-	})
-
-	It("parses and rounds a floating point fBPM tag", func() {
-		const output = `
-		Input #0, ogg, from 'tests/fixtures/test.ogg':
-  		  Metadata:
-	        FBPM            : 141.7`
-		md, _ := e.extractMetadata("tests/fixtures/test.ogg", output)
-		Expect(md).To(HaveKeyWithValue("fbpm", []string{"141.7"}))
-	})
-
-	It("parses replaygain data correctly", func() {
-		const output = `
-		Input #0, mp3, from 'test.mp3':
-			Metadata:
-				REPLAYGAIN_ALBUM_PEAK: 0.9125
-				REPLAYGAIN_TRACK_PEAK: 0.4512
-				REPLAYGAIN_TRACK_GAIN: -1.48 dB
-				REPLAYGAIN_ALBUM_GAIN: +3.21518 dB
-				Side data:
-					replaygain: track gain - -1.480000, track peak - 0.000011, album gain - 3.215180, album peak - 0.000021, 
-		`
-		md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-		Expect(md).To(SatisfyAll(
-			HaveKeyWithValue("replaygain_track_gain", []string{"-1.48 dB"}),
-			HaveKeyWithValue("replaygain_track_peak", []string{"0.4512"}),
-			HaveKeyWithValue("replaygain_album_gain", []string{"+3.21518 dB"}),
-			HaveKeyWithValue("replaygain_album_peak", []string{"0.9125"}),
-		))
-	})
-
-	It("parses lyrics with language code", func() {
-		const output = `
-		Input #0, mp3, from 'test.mp3':
-  		Metadata:
-				lyrics-eng      : [00:00.00]This is
-												: [00:02.50]English
-				lyrics-xxx      : [00:00.00]This is
-												: [00:02.50]unspecified
-		`
-		md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-		Expect(md).To(SatisfyAll(
-			HaveKeyWithValue("lyrics-eng", []string{
-				"[00:00.00]This is\n[00:02.50]English",
-			}),
-			HaveKeyWithValue("lyrics-xxx", []string{
-				"[00:00.00]This is\n[00:02.50]unspecified",
-			}),
-		))
-	})
-
-	It("parses normal LYRICS tag", func() {
-		const output = `
-		Input #0, mp3, from 'test.mp3':
-  		Metadata:
-				LYRICS      : [00:00.00]This is
-										: [00:02.50]English
-		`
-		md, _ := e.extractMetadata("tests/fixtures/test.mp3", output)
-		Expect(md).To(HaveKeyWithValue("lyrics", []string{
-			"[00:00.00]This is\n[00:02.50]English",
-		}))
-	})
-})
diff --git a/scanner/metadata_old/metadata.go b/scanner/metadata_old/metadata.go
deleted file mode 100644
index 2906a2c09..000000000
--- a/scanner/metadata_old/metadata.go
+++ /dev/null
@@ -1,411 +0,0 @@
-package metadata_old
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"math"
-	"os"
-	"path"
-	"regexp"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/djherbis/times"
-	"github.com/google/uuid"
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/consts"
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/model"
-)
-
-type Extractor interface {
-	Parse(files ...string) (map[string]ParsedTags, error)
-	CustomMappings() ParsedTags
-	Version() string
-}
-
-var extractors = map[string]Extractor{}
-
-func RegisterExtractor(id string, parser Extractor) {
-	extractors[id] = parser
-}
-
-func LogExtractors() {
-	for id, p := range extractors {
-		log.Debug("Registered metadata extractor", "id", id, "version", p.Version())
-	}
-}
-
-func Extract(files ...string) (map[string]Tags, error) {
-	p, ok := extractors[conf.Server.Scanner.Extractor]
-	if !ok {
-		log.Warn("Invalid 'Scanner.Extractor' option. Using default", "requested", conf.Server.Scanner.Extractor,
-			"validOptions", "ffmpeg,taglib", "default", consts.DefaultScannerExtractor)
-		p = extractors[consts.DefaultScannerExtractor]
-	}
-
-	extractedTags, err := p.Parse(files...)
-	if err != nil {
-		return nil, err
-	}
-
-	result := map[string]Tags{}
-	for filePath, tags := range extractedTags {
-		fileInfo, err := os.Stat(filePath)
-		if err != nil {
-			log.Warn("Error stating file. Skipping", "filePath", filePath, err)
-			continue
-		}
-
-		tags = tags.Map(p.CustomMappings())
-		result[filePath] = NewTag(filePath, fileInfo, tags)
-	}
-
-	return result, nil
-}
-
-func NewTag(filePath string, fileInfo os.FileInfo, tags ParsedTags) Tags {
-	for t, values := range tags {
-		values = removeDuplicatesAndEmpty(values)
-		if len(values) == 0 {
-			delete(tags, t)
-			continue
-		}
-		tags[t] = values
-	}
-	return Tags{
-		filePath: filePath,
-		fileInfo: fileInfo,
-		Tags:     tags,
-	}
-}
-
-func removeDuplicatesAndEmpty(values []string) []string {
-	encountered := map[string]struct{}{}
-	empty := true
-	result := make([]string, 0, len(values))
-	for _, v := range values {
-		if _, ok := encountered[v]; ok {
-			continue
-		}
-		encountered[v] = struct{}{}
-		empty = empty && v == ""
-		result = append(result, v)
-	}
-	if empty {
-		return nil
-	}
-	return result
-}
-
-type ParsedTags map[string][]string
-
-func (p ParsedTags) Map(customMappings ParsedTags) ParsedTags {
-	if customMappings == nil {
-		return p
-	}
-	for tagName, alternatives := range customMappings {
-		for _, altName := range alternatives {
-			if altValue, ok := p[altName]; ok {
-				p[tagName] = append(p[tagName], altValue...)
-				delete(p, altName)
-			}
-		}
-	}
-	return p
-}
-
-type Tags struct {
-	filePath string
-	fileInfo os.FileInfo
-	Tags     ParsedTags
-}
-
-// Common tags
-
-func (t Tags) Title() string  { return t.getFirstTagValue("title", "sort_name", "titlesort") }
-func (t Tags) Album() string  { return t.getFirstTagValue("album", "sort_album", "albumsort") }
-func (t Tags) Artist() string { return t.getFirstTagValue("artist", "sort_artist", "artistsort") }
-func (t Tags) AlbumArtist() string {
-	return t.getFirstTagValue("album_artist", "album artist", "albumartist")
-}
-func (t Tags) SortTitle() string           { return t.getSortTag("tsot", "title", "name") }
-func (t Tags) SortAlbum() string           { return t.getSortTag("tsoa", "album") }
-func (t Tags) SortArtist() string          { return t.getSortTag("tsop", "artist") }
-func (t Tags) SortAlbumArtist() string     { return t.getSortTag("tso2", "albumartist", "album_artist") }
-func (t Tags) Genres() []string            { return t.getAllTagValues("genre") }
-func (t Tags) Date() (int, string)         { return t.getDate("date") }
-func (t Tags) OriginalDate() (int, string) { return t.getDate("originaldate") }
-func (t Tags) ReleaseDate() (int, string)  { return t.getDate("releasedate") }
-func (t Tags) Comment() string             { return t.getFirstTagValue("comment") }
-func (t Tags) Compilation() bool           { return t.getBool("tcmp", "compilation", "wm/iscompilation") }
-func (t Tags) TrackNumber() (int, int)     { return t.getTuple("track", "tracknumber") }
-func (t Tags) DiscNumber() (int, int)      { return t.getTuple("disc", "discnumber") }
-func (t Tags) DiscSubtitle() string {
-	return t.getFirstTagValue("tsst", "discsubtitle", "setsubtitle")
-}
-func (t Tags) CatalogNum() string { return t.getFirstTagValue("catalognumber") }
-func (t Tags) Bpm() int           { return (int)(math.Round(t.getFloat("tbpm", "bpm", "fbpm"))) }
-func (t Tags) HasPicture() bool   { return t.getFirstTagValue("has_picture") != "" }
-
-// MusicBrainz Identifiers
-
-func (t Tags) MbzReleaseTrackID() string {
-	return t.getMbzID("musicbrainz_releasetrackid", "musicbrainz release track id")
-}
-
-func (t Tags) MbzRecordingID() string {
-	return t.getMbzID("musicbrainz_trackid", "musicbrainz track id")
-}
-func (t Tags) MbzAlbumID() string { return t.getMbzID("musicbrainz_albumid", "musicbrainz album id") }
-func (t Tags) MbzArtistID() string {
-	return t.getMbzID("musicbrainz_artistid", "musicbrainz artist id")
-}
-func (t Tags) MbzAlbumArtistID() string {
-	return t.getMbzID("musicbrainz_albumartistid", "musicbrainz album artist id")
-}
-func (t Tags) MbzAlbumType() string {
-	return t.getFirstTagValue("musicbrainz_albumtype", "musicbrainz album type")
-}
-func (t Tags) MbzAlbumComment() string {
-	return t.getFirstTagValue("musicbrainz_albumcomment", "musicbrainz album comment")
-}
-
-// Gain Properties
-
-func (t Tags) RGAlbumGain() float64 {
-	return t.getGainValue("replaygain_album_gain", "r128_album_gain")
-}
-func (t Tags) RGAlbumPeak() float64 { return t.getPeakValue("replaygain_album_peak") }
-func (t Tags) RGTrackGain() float64 {
-	return t.getGainValue("replaygain_track_gain", "r128_track_gain")
-}
-func (t Tags) RGTrackPeak() float64 { return t.getPeakValue("replaygain_track_peak") }
-
-// File properties
-
-func (t Tags) Duration() float32           { return float32(t.getFloat("duration")) }
-func (t Tags) SampleRate() int             { return t.getInt("samplerate") }
-func (t Tags) BitRate() int                { return t.getInt("bitrate") }
-func (t Tags) Channels() int               { return t.getInt("channels") }
-func (t Tags) ModificationTime() time.Time { return t.fileInfo.ModTime() }
-func (t Tags) Size() int64                 { return t.fileInfo.Size() }
-func (t Tags) FilePath() string            { return t.filePath }
-func (t Tags) Suffix() string              { return strings.ToLower(strings.TrimPrefix(path.Ext(t.filePath), ".")) }
-func (t Tags) BirthTime() time.Time {
-	if ts := times.Get(t.fileInfo); ts.HasBirthTime() {
-		return ts.BirthTime()
-	}
-	return time.Now()
-}
-
-func (t Tags) Lyrics() string {
-	lyricList := model.LyricList{}
-	basicLyrics := t.getAllTagValues("lyrics", "unsynced_lyrics", "unsynced lyrics", "unsyncedlyrics")
-
-	for _, value := range basicLyrics {
-		parsed, err := model.ParseLyrics(context.Background(), ".lrc", "xxx", []byte(value))
-		if err != nil {
-			log.Warn("Unexpected failure occurred when parsing lyrics", "file", t.filePath, "error", err)
-			continue
-		}
-		if main, ok := parsed.Main(); ok {
-			lyricList = append(lyricList, main)
-		}
-	}
-
-	for tag, value := range t.Tags {
-		if after, ok := strings.CutPrefix(tag, "lyrics-"); ok {
-			language := strings.TrimSpace(after)
-
-			if language == "" {
-				language = "xxx"
-			}
-
-			for _, text := range value {
-				parsed, err := model.ParseLyrics(context.Background(), ".lrc", language, []byte(text))
-				if err != nil {
-					log.Warn("Unexpected failure occurred when parsing lyrics", "file", t.filePath, "error", err)
-					continue
-				}
-				if main, ok := parsed.Main(); ok {
-					lyricList = append(lyricList, main)
-				}
-			}
-		}
-	}
-
-	res, err := json.Marshal(lyricList)
-	if err != nil {
-		log.Warn("Unexpected error occurred when serializing lyrics", "file", t.filePath, "error", err)
-		return ""
-	}
-	return string(res)
-}
-
-func (t Tags) getGainValue(rgTagName, r128TagName string) float64 {
-	// Check for ReplayGain first
-	// ReplayGain is in the form [-]a.bb dB and normalized to -18dB
-	var tag = t.getFirstTagValue(rgTagName)
-	if tag != "" {
-		tag = strings.TrimSpace(strings.Replace(tag, "dB", "", 1))
-		var value, err = strconv.ParseFloat(tag, 64)
-		if err != nil || value == math.Inf(-1) || value == math.Inf(1) {
-			return 0
-		}
-		return value
-	}
-
-	// If ReplayGain is not found, check for R128 gain
-	// R128 gain is a Q7.8 fixed point number normalized to -23dB
-	tag = t.getFirstTagValue(r128TagName)
-	if tag != "" {
-		var iValue, err = strconv.Atoi(tag)
-		if err != nil {
-			return 0
-		}
-		// Convert Q7.8 to float
-		var value = float64(iValue) / 256.0
-		// Adding 5 dB to normalize with ReplayGain level
-		return value + 5
-	}
-
-	return 0
-}
-
-func (t Tags) getPeakValue(tagName string) float64 {
-	var tag = t.getFirstTagValue(tagName)
-	var value, err = strconv.ParseFloat(tag, 64)
-	if err != nil || value == math.Inf(-1) || value == math.Inf(1) {
-		// A default of 1 for peak value results in no changes
-		return 1
-	}
-	return value
-}
-
-func (t Tags) getTags(tagNames ...string) []string {
-	for _, tag := range tagNames {
-		if v, ok := t.Tags[tag]; ok {
-			return v
-		}
-	}
-	return nil
-}
-
-func (t Tags) getFirstTagValue(tagNames ...string) string {
-	ts := t.getTags(tagNames...)
-	if len(ts) > 0 {
-		return ts[0]
-	}
-	return ""
-}
-
-func (t Tags) getAllTagValues(tagNames ...string) []string {
-	values := make([]string, 0, len(tagNames)*2)
-	for _, tag := range tagNames {
-		if v, ok := t.Tags[tag]; ok {
-			values = append(values, v...)
-		}
-	}
-	return values
-}
-
-func (t Tags) getSortTag(originalTag string, tagNames ...string) string {
-	formats := []string{"sort%s", "sort_%s", "sort-%s", "%ssort", "%s_sort", "%s-sort"}
-	all := make([]string, 1, len(tagNames)*len(formats)+1)
-	all[0] = originalTag
-	for _, tag := range tagNames {
-		for _, format := range formats {
-			name := fmt.Sprintf(format, tag)
-			all = append(all, name)
-		}
-	}
-	return t.getFirstTagValue(all...)
-}
-
-var dateRegex = regexp.MustCompile(`([12]\d\d\d)`)
-
-func (t Tags) getDate(tagNames ...string) (int, string) {
-	tag := t.getFirstTagValue(tagNames...)
-	if len(tag) < 4 {
-		return 0, ""
-	}
-	// first get just the year
-	match := dateRegex.FindStringSubmatch(tag)
-	if len(match) == 0 {
-		log.Warn("Error parsing "+tagNames[0]+" field for year", "file", t.filePath, "date", tag)
-		return 0, ""
-	}
-	year, _ := strconv.Atoi(match[1])
-
-	if len(tag) < 5 {
-		return year, match[1]
-	}
-
-	//then try YYYY-MM-DD
-	if len(tag) > 10 {
-		tag = tag[:10]
-	}
-	layout := "2006-01-02"
-	_, err := time.Parse(layout, tag)
-	if err != nil {
-		layout = "2006-01"
-		_, err = time.Parse(layout, tag)
-		if err != nil {
-			log.Warn("Error parsing "+tagNames[0]+" field for month + day", "file", t.filePath, "date", tag)
-			return year, match[1]
-		}
-	}
-	return year, tag
-}
-
-func (t Tags) getBool(tagNames ...string) bool {
-	tag := t.getFirstTagValue(tagNames...)
-	if tag == "" {
-		return false
-	}
-	i, _ := strconv.Atoi(strings.TrimSpace(tag))
-	return i == 1
-}
-
-func (t Tags) getTuple(tagNames ...string) (int, int) {
-	tag := t.getFirstTagValue(tagNames...)
-	if tag == "" {
-		return 0, 0
-	}
-	tuple := strings.Split(tag, "/")
-	t1, t2 := 0, 0
-	t1, _ = strconv.Atoi(tuple[0])
-	if len(tuple) > 1 {
-		t2, _ = strconv.Atoi(tuple[1])
-	} else {
-		t2tag := t.getFirstTagValue(tagNames[0] + "total")
-		t2, _ = strconv.Atoi(t2tag)
-	}
-	return t1, t2
-}
-
-func (t Tags) getMbzID(tagNames ...string) string {
-	tag := t.getFirstTagValue(tagNames...)
-	if _, err := uuid.Parse(tag); err != nil {
-		return ""
-	}
-	return tag
-}
-
-func (t Tags) getInt(tagNames ...string) int {
-	tag := t.getFirstTagValue(tagNames...)
-	i, _ := strconv.Atoi(tag)
-	return i
-}
-
-func (t Tags) getFloat(tagNames ...string) float64 {
-	var tag = t.getFirstTagValue(tagNames...)
-	var value, err = strconv.ParseFloat(tag, 64)
-	if err != nil {
-		return 0
-	}
-	return value
-}
diff --git a/scanner/metadata_old/metadata_internal_test.go b/scanner/metadata_old/metadata_internal_test.go
deleted file mode 100644
index aff1ede9c..000000000
--- a/scanner/metadata_old/metadata_internal_test.go
+++ /dev/null
@@ -1,144 +0,0 @@
-package metadata_old
-
-import (
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Tags", func() {
-	DescribeTable("getDate",
-		func(tag string, expectedYear int, expectedDate string) {
-			md := &Tags{}
-			md.Tags = map[string][]string{"date": {tag}}
-			testYear, testDate := md.Date()
-			Expect(testYear).To(Equal(expectedYear))
-			Expect(testDate).To(Equal(expectedDate))
-		},
-		Entry(nil, "1985", 1985, "1985"),
-		Entry(nil, "2002-01", 2002, "2002-01"),
-		Entry(nil, "1969.06", 1969, "1969"),
-		Entry(nil, "1980.07.25", 1980, "1980"),
-		Entry(nil, "2004-00-00", 2004, "2004"),
-		Entry(nil, "2016-12-31", 2016, "2016-12-31"),
-		Entry(nil, "2013-May-12", 2013, "2013"),
-		Entry(nil, "May 12, 2016", 2016, "2016"),
-		Entry(nil, "01/10/1990", 1990, "1990"),
-		Entry(nil, "invalid", 0, ""),
-	)
-
-	Describe("getMbzID", func() {
-		It("return a valid MBID", func() {
-			md := &Tags{}
-			md.Tags = map[string][]string{
-				"musicbrainz_trackid":        {"8f84da07-09a0-477b-b216-cc982dabcde1"},
-				"musicbrainz_releasetrackid": {"6caf16d3-0b20-3fe6-8020-52e31831bc11"},
-				"musicbrainz_albumid":        {"f68c985d-f18b-4f4a-b7f0-87837cf3fbf9"},
-				"musicbrainz_artistid":       {"89ad4ac3-39f7-470e-963a-56509c546377"},
-				"musicbrainz_albumartistid":  {"ada7a83c-e3e1-40f1-93f9-3e73dbc9298a"},
-			}
-			Expect(md.MbzRecordingID()).To(Equal("8f84da07-09a0-477b-b216-cc982dabcde1"))
-			Expect(md.MbzReleaseTrackID()).To(Equal("6caf16d3-0b20-3fe6-8020-52e31831bc11"))
-			Expect(md.MbzAlbumID()).To(Equal("f68c985d-f18b-4f4a-b7f0-87837cf3fbf9"))
-			Expect(md.MbzArtistID()).To(Equal("89ad4ac3-39f7-470e-963a-56509c546377"))
-			Expect(md.MbzAlbumArtistID()).To(Equal("ada7a83c-e3e1-40f1-93f9-3e73dbc9298a"))
-		})
-		It("return empty string for invalid MBID", func() {
-			md := &Tags{}
-			md.Tags = map[string][]string{
-				"musicbrainz_trackid":       {"11406732-6"},
-				"musicbrainz_albumid":       {"11406732"},
-				"musicbrainz_artistid":      {"200455"},
-				"musicbrainz_albumartistid": {"194"},
-			}
-			Expect(md.MbzRecordingID()).To(Equal(""))
-			Expect(md.MbzAlbumID()).To(Equal(""))
-			Expect(md.MbzArtistID()).To(Equal(""))
-			Expect(md.MbzAlbumArtistID()).To(Equal(""))
-		})
-	})
-
-	Describe("getAllTagValues", func() {
-		It("returns values from all tag names", func() {
-			md := &Tags{}
-			md.Tags = map[string][]string{
-				"genre": {"Rock", "Pop", "New Wave"},
-			}
-
-			Expect(md.Genres()).To(ConsistOf("Rock", "Pop", "New Wave"))
-		})
-	})
-
-	Describe("removeDuplicatesAndEmpty", func() {
-		It("removes duplicates", func() {
-			md := NewTag("/music/artist/album01/Song.mp3", nil, ParsedTags{
-				"genre": []string{"pop", "rock", "pop"},
-				"date":  []string{"2023-03-01", "2023-03-01"},
-				"mood":  []string{"happy", "sad"},
-			})
-			Expect(md.Tags).To(HaveKeyWithValue("genre", []string{"pop", "rock"}))
-			Expect(md.Tags).To(HaveKeyWithValue("date", []string{"2023-03-01"}))
-			Expect(md.Tags).To(HaveKeyWithValue("mood", []string{"happy", "sad"}))
-		})
-		It("removes empty tags", func() {
-			md := NewTag("/music/artist/album01/Song.mp3", nil, ParsedTags{
-				"genre": []string{"pop", "rock", "pop"},
-				"mood":  []string{"", ""},
-			})
-			Expect(md.Tags).To(HaveKeyWithValue("genre", []string{"pop", "rock"}))
-			Expect(md.Tags).ToNot(HaveKey("mood"))
-		})
-	})
-
-	Describe("BPM", func() {
-		var t *Tags
-		BeforeEach(func() {
-			t = &Tags{Tags: map[string][]string{
-				"fbpm": {"141.7"},
-			}}
-		})
-
-		It("rounds a floating point fBPM tag", func() {
-			Expect(t.Bpm()).To(Equal(142))
-		})
-	})
-
-	Describe("ReplayGain", func() {
-		DescribeTable("getGainValue",
-			func(tag string, expected float64) {
-				md := &Tags{}
-				md.Tags = map[string][]string{"replaygain_track_gain": {tag}}
-				Expect(md.RGTrackGain()).To(Equal(expected))
-
-			},
-			Entry("0", "0", 0.0),
-			Entry("1.2dB", "1.2dB", 1.2),
-			Entry("Infinity", "Infinity", 0.0),
-			Entry("Invalid value", "INVALID VALUE", 0.0),
-		)
-		DescribeTable("getPeakValue",
-			func(tag string, expected float64) {
-				md := &Tags{}
-				md.Tags = map[string][]string{"replaygain_track_peak": {tag}}
-				Expect(md.RGTrackPeak()).To(Equal(expected))
-
-			},
-			Entry("0", "0", 0.0),
-			Entry("0.5", "0.5", 0.5),
-			Entry("Invalid dB suffix", "0.7dB", 1.0),
-			Entry("Infinity", "Infinity", 1.0),
-			Entry("Invalid value", "INVALID VALUE", 1.0),
-		)
-		DescribeTable("getR128GainValue",
-			func(tag string, expected float64) {
-				md := &Tags{}
-				md.Tags = map[string][]string{"r128_track_gain": {tag}}
-				Expect(md.RGTrackGain()).To(Equal(expected))
-
-			},
-			Entry("0", "0", 5.0),
-			Entry("-3776", "-3776", -9.75),
-			Entry("Infinity", "Infinity", 0.0),
-			Entry("Invalid value", "INVALID VALUE", 0.0),
-		)
-	})
-})
diff --git a/scanner/metadata_old/metadata_suite_test.go b/scanner/metadata_old/metadata_suite_test.go
deleted file mode 100644
index 03ec3c847..000000000
--- a/scanner/metadata_old/metadata_suite_test.go
+++ /dev/null
@@ -1,17 +0,0 @@
-package metadata_old
-
-import (
-	"testing"
-
-	"github.com/navidrome/navidrome/log"
-	"github.com/navidrome/navidrome/tests"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-func TestMetadata(t *testing.T) {
-	tests.Init(t, true)
-	log.SetLevel(log.LevelFatal)
-	RegisterFailHandler(Fail)
-	RunSpecs(t, "Metadata Suite")
-}
diff --git a/scanner/metadata_old/metadata_test.go b/scanner/metadata_old/metadata_test.go
deleted file mode 100644
index 444bb7fc4..000000000
--- a/scanner/metadata_old/metadata_test.go
+++ /dev/null
@@ -1,95 +0,0 @@
-package metadata_old_test
-
-import (
-	"cmp"
-	"encoding/json"
-	"slices"
-
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/conf/configtest"
-	"github.com/navidrome/navidrome/core/ffmpeg"
-	"github.com/navidrome/navidrome/model"
-	"github.com/navidrome/navidrome/scanner/metadata_old"
-	_ "github.com/navidrome/navidrome/scanner/metadata_old/ffmpeg"
-	. "github.com/onsi/ginkgo/v2"
-	. "github.com/onsi/gomega"
-)
-
-var _ = Describe("Tags", func() {
-	var zero int64 = 0
-	var secondTs int64 = 2500
-
-	makeLyrics := func(synced bool, lang, secondLine string) model.Lyrics {
-		lines := []model.Line{
-			{Value: "This is"},
-			{Value: secondLine},
-		}
-
-		if synced {
-			lines[0].Start = &zero
-			lines[1].Start = &secondTs
-		}
-
-		lyrics := model.Lyrics{
-			Lang:   lang,
-			Line:   lines,
-			Synced: synced,
-		}
-
-		return lyrics
-	}
-
-	sortLyrics := func(lines model.LyricList) model.LyricList {
-		slices.SortFunc(lines, func(a, b model.Lyrics) int {
-			langDiff := cmp.Compare(a.Lang, b.Lang)
-			if langDiff != 0 {
-				return langDiff
-			}
-			return cmp.Compare(a.Line[1].Value, b.Line[1].Value)
-		})
-
-		return lines
-	}
-
-	compareLyrics := func(m metadata_old.Tags, expected model.LyricList) {
-		lyrics := model.LyricList{}
-		Expect(json.Unmarshal([]byte(m.Lyrics()), &lyrics)).To(BeNil())
-		Expect(sortLyrics(lyrics)).To(Equal(sortLyrics(expected)))
-	}
-
-	// Only run these tests if FFmpeg is available
-	FFmpegContext := XContext
-	if ffmpeg.New().IsAvailable() {
-		FFmpegContext = Context
-	}
-	FFmpegContext("Extract with FFmpeg", func() {
-		BeforeEach(func() {
-			DeferCleanup(configtest.SetupConfig())
-			conf.Server.Scanner.Extractor = "ffmpeg"
-		})
-
-		DescribeTable("Lyrics test",
-			func(file string) {
-				path := "tests/fixtures/" + file
-				mds, err := metadata_old.Extract(path)
-				Expect(err).ToNot(HaveOccurred())
-				Expect(mds).To(HaveLen(1))
-
-				m := mds[path]
-				compareLyrics(m, model.LyricList{
-					makeLyrics(true, "eng", "English"),
-					makeLyrics(true, "xxx", "unspecified"),
-				})
-			},
-
-			Entry("Parses AIFF file", "test.aiff"),
-			Entry("Parses MP3 files", "test.mp3"),
-			// Disabled, because it fails in pipeline
-			// Entry("Parses WAV files", "test.wav"),
-
-			// FFMPEG behaves very weirdly for multivalued tags for non-ID3
-			// Specifically, they are separated by ";, which is indistinguishable
-			// from other fields
-		)
-	})
-})
diff --git a/server/initial_setup.go b/server/initial_setup.go
index be9e14ae9..462e22e54 100644
--- a/server/initial_setup.go
+++ b/server/initial_setup.go
@@ -72,10 +72,6 @@ func checkFFmpegInstallation() {
 	_, err := f.CmdPath()
 	if err != nil {
 		log.Warn("Unable to find ffmpeg. Transcoding will fail if used", err)
-		if conf.Server.Scanner.Extractor == "ffmpeg" {
-			log.Warn("ffmpeg cannot be used for metadata extraction. Falling back to taglib")
-			conf.Server.Scanner.Extractor = "taglib"
-		}
 		return
 	}
 	if !f.IsProbeAvailable() {
diff --git a/tests/harness/harness.go b/tests/harness/harness.go
index 92196ef26..67f3150a2 100644
--- a/tests/harness/harness.go
+++ b/tests/harness/harness.go
@@ -176,8 +176,6 @@ func (NoopFFmpeg) ExtractImage(context.Context, string) (io.ReadCloser, error) {
 	return nil, errors.New("noop ffmpeg: extract image not supported")
 }
 
-func (NoopFFmpeg) Probe(context.Context, []string) (string, error) { return "", nil }
-
 func (NoopFFmpeg) ProbeAudioStream(context.Context, string) (*ffmpeg.AudioProbeResult, error) {
 	return nil, errors.New("noop ffmpeg: probe not supported")
 }
diff --git a/tests/mock_ffmpeg.go b/tests/mock_ffmpeg.go
index f9862767e..8e4d12f0b 100644
--- a/tests/mock_ffmpeg.go
+++ b/tests/mock_ffmpeg.go
@@ -57,12 +57,6 @@ func (ff *MockFFmpeg) ConvertAnimatedImage(_ context.Context, reader io.Reader,
 	return io.NopCloser(bytes.NewReader(data)), nil
 }
 
-func (ff *MockFFmpeg) Probe(context.Context, []string) (string, error) {
-	if ff.Error != nil {
-		return "", ff.Error
-	}
-	return "", nil
-}
 func (ff *MockFFmpeg) ProbeAudioStream(context.Context, string) (*ffmpeg.AudioProbeResult, error) {
 	if ff.Error != nil {
 		return nil, ff.Error

From c22ce9ebb27c5e80b104c28a82ac70b018f07895 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 26 Sep 2026 15:27:23 -0400
Subject: [PATCH 187/200] feat(api): add the API v1 foundation behind DevAPIv1
 (#6227)

* feat(api): add OpenAPI v1 spec skeleton, lint ruleset and bundle tooling

vacuum v0.30.6's `bundle --composed` mangles component names for this
spec's multi-file layout (duplicates Problem as Problem__schemas etc.),
so api-bundle uses the Redocly CLI (npx @redocly/cli bundle) instead.

* fix(api): pin the Redocly CLI version

Tried moving components out of the root document (per libopenapi's
nested_files example) so vacuum's own bundler could produce clean
names, but any component declared via $ref inside components.* still
gets a __<parent>-suffixed twin regardless of collisions elsewhere, so
vacuum's --composed bundler can't cleanly bundle this spec. Pin the
already-working Redocly fallback to an exact version instead of
@latest.

* fix(api): bundle the OpenAPI spec with vacuum

vacuum's --composed bundler suffixes any component reached via a $ref
written directly inside the root document's own components.* block,
regardless of collisions elsewhere. Dropping the root-level schemas/
parameters/responses declarations (keeping only securitySchemes, and
leaving every component file under api/openapi/components/ untouched)
lets vacuum bundle cleanly with no __ suffixes, going back to Go-only
tooling. Components nothing references yet (ListMeta, offset, limit,
BadRequest, Unauthorized, Forbidden, NotFound) are absent from the
bundle until a later task's operation references them.

* fix(api): make spec lint rules cover all schemas and error codes

nd-schema-property-descriptions targeted $.components.schemas, but our
schemas live in path/response files, not the root document, so it was
dead code; switched to $..properties[*] to walk every resolved schema
wherever it ends up. nd-error-responses-are-problems only checked a
hardcoded status-code list; switched to a patternProperties schema
matching the full 4xx/5xx range. Also: api-diff now diffs against the
merge-base with API_DIFF_BASE (falling back to its tip with a notice
if no merge-base exists), gen no longer depends on api-gen until Task
3 wires up oapi-codegen, and api-lint suppresses vacuum's banner.

* feat(api): embed the bundled OpenAPI spec and expose its version

* feat(api): generate the v1 server interface with oapi-codegen

* feat(api): add RFC 9457 problem responses for API v1

* feat(api): add API v1 router with /server discovery and spec routes

* fix(api): serve the OpenAPI document without range support

* feat(api): mount API v1 behind the DevAPIv1 flag

* chore(ci): lint, regenerate and diff the OpenAPI v1 spec

* refactor(api): tighten spec version access, lint rules and test naming

* refactor(api): simplify spec routes, tests and OpenAPI tooling

Share one If-None-Match parser (utils/req) between the image and spec
routes, declare the YAML spec response as an object so tests need no
decoder override, and reuse ETag/304 spec components.

Install the OpenAPI tools only when missing or at a different version,
fail api-diff when its base ref does not exist, and in CI cache the
tools, fold regeneration into the go generate check, and fetch only the
PR base commit for the breaking-change gate.

* refactor(api): raise the list limit maximum to 2000 and drop the flag test

* feat(api): treat added enum values as non-breaking

Enums in API v1 are open: clients must accept unknown values. api-diff
now downgrades response-property-enum-value-added to INFO, while
removing a value from a request enum stays breaking.

* feat(api): gate breaking changes on x-stability-level

Every operation declares x-stability-level (alpha, beta, stable). oasdiff
ignores breaking changes to alpha operations and rejects lowering a
level, so unreleased endpoints can evolve while beta and stable ones
stay additive. All current operations start as alpha.

* feat(api): declare loginMethods as an enum

Prefix generated enum constants with their type name so enums sharing a
value (for example password) cannot collide in package apiv1.

* feat(api): send Allow on 405 and answer HEAD wherever GET is routed

chi only sets Allow in its default 405 handler, so the problem-format
handler now builds it by matching each method against the v1 router.
HEAD requests fall back to the GET route, as RFC 9110 expects.

* refactor(api): hash the spec ETag with xxh3

The bytes are compiled in, and the digest was truncated to 64 bits
anyway, so this matches the artwork ETags instead of paying for
cryptographic strength we discard.

* docs(api): explain the about:blank problem type

* feat(api): make code the problem identifier and omit a blank type

RFC 9457 says clients switch on the type URI, but no adopter surveyed
ships both a populated type and a separate code. Declare code as an
enum, and send type only once a problem has semantics of its own.

* fix(api): advertise the configured base path in the served OpenAPI spec

With BaseURL=/music the API is mounted at /music/api/v1, but the spec
told clients to call /api/v1 at the host root. The server now rewrites
servers[0].url to BasePath + /api/v1 when it serves the document.

Relative server URLs were tested first: "." and "../v1" work in
openapi-generator, Swagger UI and Redoc, but Scalar resolves them
against the page origin, so it breaks even without a base path. The
committed bundle keeps /api/v1, and a test pins that it appears exactly
once, which the rewrite relies on.
---
 .github/workflows/pipeline.yml                |  23 +-
 Makefile                                      |  45 +-
 api/.oasdiff-levels.txt                       |   1 +
 api/.vacuum.yaml                              | 155 +++++++
 api/api_suite_test.go                         |  17 +
 api/bundled/openapi.json                      | 262 ++++++++++++
 api/bundled/openapi.yaml                      | 194 +++++++++
 api/embed.go                                  |  35 ++
 api/embed_test.go                             |  37 ++
 api/openapi/components/headers/ETag.yaml      |   3 +
 api/openapi/components/parameters/limit.yaml  |   9 +
 api/openapi/components/parameters/offset.yaml |   8 +
 .../components/responses/BadRequest.yaml      |   5 +
 .../components/responses/Forbidden.yaml       |   5 +
 .../components/responses/InternalError.yaml   |   5 +
 .../components/responses/NotFound.yaml        |   5 +
 .../components/responses/NotModified.yaml     |   4 +
 .../components/responses/Unauthorized.yaml    |   5 +
 api/openapi/components/schemas/ListMeta.yaml  |  13 +
 api/openapi/components/schemas/Problem.yaml   |  35 ++
 .../components/schemas/ServerInfo.yaml        |  22 +
 .../components/schemas/ValidationError.yaml   |  10 +
 api/openapi/openapi.yaml                      |  39 ++
 api/openapi/paths/openapi.yaml                |  42 ++
 api/openapi/paths/server.yaml                 |  19 +
 cmd/root.go                                   |   3 +
 cmd/wire_gen.go                               |  10 +-
 cmd/wire_injectors.go                         |   8 +
 conf/configuration.go                         |   2 +
 consts/consts.go                              |   1 +
 go.mod                                        |   6 +
 go.sum                                        |  18 +-
 server/apiv1/api.go                           |  98 +++++
 server/apiv1/api_gen.go                       | 390 ++++++++++++++++++
 server/apiv1/api_test.go                      |  75 ++++
 server/apiv1/apiv1_suite_test.go              |  66 +++
 server/apiv1/oapi-codegen.yaml                |  12 +
 server/apiv1/problem.go                       |  72 ++++
 server/apiv1/problem_test.go                  | 114 +++++
 server/apiv1/server_info.go                   |  23 ++
 server/apiv1/server_info_test.go              |  61 +++
 server/apiv1/spec.go                          |  51 +++
 server/apiv1/spec_test.go                     | 136 ++++++
 server/imghttp/headers.go                     |  23 +-
 utils/req/req.go                              |  18 +
 utils/req/req_test.go                         |  18 +
 46 files changed, 2177 insertions(+), 26 deletions(-)
 create mode 100644 api/.oasdiff-levels.txt
 create mode 100644 api/.vacuum.yaml
 create mode 100644 api/api_suite_test.go
 create mode 100644 api/bundled/openapi.json
 create mode 100644 api/bundled/openapi.yaml
 create mode 100644 api/embed.go
 create mode 100644 api/embed_test.go
 create mode 100644 api/openapi/components/headers/ETag.yaml
 create mode 100644 api/openapi/components/parameters/limit.yaml
 create mode 100644 api/openapi/components/parameters/offset.yaml
 create mode 100644 api/openapi/components/responses/BadRequest.yaml
 create mode 100644 api/openapi/components/responses/Forbidden.yaml
 create mode 100644 api/openapi/components/responses/InternalError.yaml
 create mode 100644 api/openapi/components/responses/NotFound.yaml
 create mode 100644 api/openapi/components/responses/NotModified.yaml
 create mode 100644 api/openapi/components/responses/Unauthorized.yaml
 create mode 100644 api/openapi/components/schemas/ListMeta.yaml
 create mode 100644 api/openapi/components/schemas/Problem.yaml
 create mode 100644 api/openapi/components/schemas/ServerInfo.yaml
 create mode 100644 api/openapi/components/schemas/ValidationError.yaml
 create mode 100644 api/openapi/openapi.yaml
 create mode 100644 api/openapi/paths/openapi.yaml
 create mode 100644 api/openapi/paths/server.yaml
 create mode 100644 server/apiv1/api.go
 create mode 100644 server/apiv1/api_gen.go
 create mode 100644 server/apiv1/api_test.go
 create mode 100644 server/apiv1/apiv1_suite_test.go
 create mode 100644 server/apiv1/oapi-codegen.yaml
 create mode 100644 server/apiv1/problem.go
 create mode 100644 server/apiv1/problem_test.go
 create mode 100644 server/apiv1/server_info.go
 create mode 100644 server/apiv1/server_info_test.go
 create mode 100644 server/apiv1/spec.go
 create mode 100644 server/apiv1/spec_test.go

diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index 2702163d3..c1ba8714c 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -92,8 +92,23 @@ jobs:
             exit 1
           fi
 
+      - name: Resolve OpenAPI tool versions
+        id: api-tools
+        run: echo "key=$(grep -E '^(VACUUM|OAPI_CODEGEN|OASDIFF)_VERSION' Makefile | tr -d ' \n')" >> "$GITHUB_OUTPUT"
+
+      - name: Cache OpenAPI tools
+        uses: actions/cache@v6
+        with:
+          path: bin
+          key: api-tools-${{ runner.os }}-${{ steps.api-tools.outputs.key }}
+
+      - name: Lint OpenAPI spec
+        run: make api-lint
+
       - name: Run go generate
-        run: go generate ./...
+        run: |
+          make api-gen
+          go generate ./...
       - name: Verify no changes from go generate
         run: |
           git status --porcelain
@@ -102,6 +117,12 @@ jobs:
             exit 1
           fi
 
+      - name: Check for breaking OpenAPI changes
+        if: github.event_name == 'pull_request'
+        run: |
+          git fetch --no-tags --depth=1 origin ${{ github.event.pull_request.base.sha }}
+          make api-diff API_DIFF_BASE=${{ github.event.pull_request.base.sha }}
+
   validate-migrations:
     name: Validate DB migrations
     runs-on: ubuntu-latest
diff --git a/Makefile b/Makefile
index eccccbffb..f31d98a01 100644
--- a/Makefile
+++ b/Makefile
@@ -21,6 +21,10 @@ PLATFORMS ?= $(SUPPORTED_PLATFORMS)
 DOCKER_TAG ?= deluan/navidrome:develop
 
 GOLANGCI_LINT_VERSION ?= v2.14.0
+VACUUM_VERSION ?= v0.30.6
+OAPI_CODEGEN_VERSION ?= v2.8.0
+OASDIFF_VERSION ?= v1.32.1
+API_DIFF_BASE ?= origin/master
 
 UI_SRC_FILES := $(shell find ui -type f -not -path "ui/build/*" -not -path "ui/node_modules/*")
 
@@ -92,6 +96,45 @@ install-golangci-lint: ##@Development Install golangci-lint if not present
 	fi
 .PHONY: install-golangci-lint
 
+install-api-tools: ##@Development Install OpenAPI tools (vacuum, oapi-codegen, oasdiff) into ./bin
+	@STAMP=bin/.api-tools-$(VACUUM_VERSION)-$(OAPI_CODEGEN_VERSION)-$(OASDIFF_VERSION); \
+	if [ ! -f $$STAMP ] || [ ! -x bin/vacuum ] || [ ! -x bin/oapi-codegen ] || [ ! -x bin/oasdiff ]; then \
+		echo "Installing OpenAPI tools..."; \
+		GOBIN=$(CURDIR)/bin go install github.com/daveshanley/vacuum@$(VACUUM_VERSION) && \
+		GOBIN=$(CURDIR)/bin go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@$(OAPI_CODEGEN_VERSION) && \
+		GOBIN=$(CURDIR)/bin go install github.com/oasdiff/oasdiff@$(OASDIFF_VERSION) && \
+		rm -f bin/.api-tools-* && touch $$STAMP; \
+	fi
+.PHONY: install-api-tools
+
+api-lint: install-api-tools ##@Development Lint the OpenAPI spec
+	./bin/vacuum lint -r api/.vacuum.yaml -d -q -b --fail-severity error api/openapi/openapi.yaml
+.PHONY: api-lint
+
+api-bundle: install-api-tools ##@Development Bundle the multi-file OpenAPI spec into api/bundled
+	./bin/vacuum bundle -q --composed -p api/openapi api/openapi/openapi.yaml api/bundled/openapi.yaml
+	./bin/vacuum bundle -q --composed --format json -p api/openapi api/openapi/openapi.yaml api/bundled/openapi.json
+.PHONY: api-bundle
+
+api-gen: api-bundle ##@Development Generate the API v1 server code from the bundled spec
+	./bin/oapi-codegen -config server/apiv1/oapi-codegen.yaml api/bundled/openapi.json
+.PHONY: api-gen
+
+api-diff: api-bundle ##@Development Fail on breaking OpenAPI changes against the merge-base with $(API_DIFF_BASE)
+	@git rev-parse --verify --quiet $(API_DIFF_BASE)^{commit} >/dev/null || { echo "Base ref $(API_DIFF_BASE) not found; set API_DIFF_BASE"; exit 1; }; \
+	BASE="$$(git merge-base HEAD $(API_DIFF_BASE) 2>/dev/null)"; \
+	if [ -z "$$BASE" ]; then \
+		echo "No merge-base with $(API_DIFF_BASE); falling back to its tip"; \
+		BASE=$(API_DIFF_BASE); \
+	fi; \
+	if git cat-file -e $$BASE:api/bundled/openapi.json 2>/dev/null; then \
+		git show $$BASE:api/bundled/openapi.json > $(CURDIR)/bin/api-base.json && \
+		./bin/oasdiff breaking $(CURDIR)/bin/api-base.json api/bundled/openapi.json --fail-on ERR --severity-levels api/.oasdiff-levels.txt; \
+	else \
+		echo "No bundled spec at $$BASE; skipping breaking-change check"; \
+	fi
+.PHONY: api-diff
+
 lint: install-golangci-lint ##@Development Lint Go code
 	PATH=./bin:$$PATH golangci-lint run --timeout 5m
 .PHONY: lint
@@ -111,7 +154,7 @@ wire: check_go_env ##@Development Update Dependency Injection
 	go tool wire gen -tags="$$(echo '$(GO_BUILD_TAGS)' | tr ',' ' ')" ./...
 .PHONY: wire
 
-gen: check_go_env ##@Development Run go generate for code generation
+gen: check_go_env api-gen ##@Development Run go generate for code generation
 	go generate ./...
 	cd plugins/cmd/ndpgen && go run . -shared-types -input=../../types -output=../../pdk -go -rust
 	cd plugins/cmd/ndpgen && go run . -host-wrappers -input=../../host -package=host -shared=../../types
diff --git a/api/.oasdiff-levels.txt b/api/.oasdiff-levels.txt
new file mode 100644
index 000000000..1792adcb2
--- /dev/null
+++ b/api/.oasdiff-levels.txt
@@ -0,0 +1 @@
+response-property-enum-value-added INFO
diff --git a/api/.vacuum.yaml b/api/.vacuum.yaml
new file mode 100644
index 000000000..bd31e23f8
--- /dev/null
+++ b/api/.vacuum.yaml
@@ -0,0 +1,155 @@
+extends: [[spectral:oas, recommended]]
+rules:
+  # vacuum's `enumeration` function mis-resolves hyphenated `then.field` names,
+  # so the value check below targets `x-module` via `given` instead.
+  nd-operation-x-module-required:
+    description: Every operation belongs to exactly one capability module.
+    severity: error
+    given: $.paths[*][get,put,post,delete,patch]
+    then:
+      field: x-module
+      function: truthy
+  nd-operation-x-module:
+    description: Every operation's capability module is one of the known values.
+    severity: error
+    given: $.paths[*][get,put,post,delete,patch]['x-module']
+    then:
+      function: enumeration
+      functionOptions:
+        values:
+          - core
+          - streaming
+          - download
+          - artwork
+          - lyrics
+          - transcoding
+          - annotations
+          - playback
+          - queue
+          - custom-tags
+          - grouping
+          - playlists
+          - smart-playlists
+          - sync
+          - events
+          - jukebox
+          - sharing
+          - radio
+          - admin
+  nd-operation-stability-level-required:
+    description: Every operation declares its stability level, which the breaking-change gate relies on.
+    severity: error
+    given: $.paths[*][get,put,post,delete,patch]
+    then:
+      field: x-stability-level
+      function: truthy
+  nd-operation-stability-level:
+    description: Every operation's stability level is alpha, beta, or stable.
+    severity: error
+    given: $.paths[*][get,put,post,delete,patch]['x-stability-level']
+    then:
+      function: enumeration
+      functionOptions:
+        values:
+          - alpha
+          - beta
+          - stable
+  nd-operation-required-fields:
+    description: Operations need a stable operationId, summary, description and tags.
+    severity: error
+    given: $.paths[*][get,put,post,delete,patch]
+    then:
+      - field: operationId
+        function: truthy
+      - field: summary
+        function: truthy
+      - field: description
+        function: truthy
+      - field: tags
+        function: truthy
+  # Our schemas live in path/response files, not root components, so this
+  # walks every resolved `properties` map in the document via `$..` instead.
+  nd-schema-property-descriptions:
+    description: Every schema property is documented.
+    severity: error
+    given: $..properties[*]
+    then:
+      field: description
+      function: truthy
+  # patternProperties covers the full 4xx/5xx range; needs an explicit
+  # `properties` entry too, or `additionalProperties: false` rejects it.
+  nd-error-responses-are-problems:
+    description: 4xx and 5xx responses use application/problem+json.
+    severity: error
+    given: $.paths[*][*].responses
+    then:
+      function: schema
+      functionOptions:
+        forceValidationOnCurrentNode: true
+        schema:
+          type: object
+          patternProperties:
+            "^[45][0-9][0-9]$":
+              type: object
+              required: [content]
+              properties:
+                content:
+                  type: object
+                  properties:
+                    application/problem+json: {}
+                  required: [application/problem+json]
+                  additionalProperties: false
+  # Same filter limitation applies here: "is this a list endpoint" is expressed
+  # as a JSON Schema if/then on the operation object instead of a `given` filter.
+  nd-list-endpoints-paginate:
+    description: List endpoints declare the shared offset and limit parameters.
+    severity: error
+    given: $.paths[*].get
+    then:
+      function: schema
+      functionOptions:
+        forceValidationOnCurrentNode: true
+        schema:
+          type: object
+          if:
+            required: [responses]
+            properties:
+              responses:
+                type: object
+                required: ['200']
+                properties:
+                  '200':
+                    type: object
+                    required: [content]
+                    properties:
+                      content:
+                        type: object
+                        required: [application/json]
+                        properties:
+                          application/json:
+                            type: object
+                            required: [schema]
+                            properties:
+                              schema:
+                                type: object
+                                required: [properties]
+                                properties:
+                                  properties:
+                                    type: object
+                                    required: [items]
+          then:
+            required: [parameters]
+            properties:
+              parameters:
+                type: array
+                allOf:
+                  - contains:
+                      type: object
+                      properties:
+                        name:
+                          const: offset
+                  - contains:
+                      type: object
+                      properties:
+                        name:
+                          const: limit
diff --git a/api/api_suite_test.go b/api/api_suite_test.go
new file mode 100644
index 000000000..62a547b7c
--- /dev/null
+++ b/api/api_suite_test.go
@@ -0,0 +1,17 @@
+package api_test
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestAPI(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "API Spec Suite")
+}
diff --git a/api/bundled/openapi.json b/api/bundled/openapi.json
new file mode 100644
index 000000000..bfe794c71
--- /dev/null
+++ b/api/bundled/openapi.json
@@ -0,0 +1,262 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Navidrome API",
+    "version": "1.0.0",
+    "description": "Navidrome API v1. Spec-first, additive within v1. Clients discover implemented\ncapability modules through `GET /server` and never sniff versions.\n\nEnums are open: new values may be added to any enum within v1. Clients must\naccept values they do not recognise instead of failing.\n\nEvery operation declares `x-stability-level`: `alpha` operations may change or\ndisappear without notice, `beta` and `stable` operations only change additively.\nA level is only ever raised, never lowered.\n\n`HEAD` is accepted wherever `GET` is. A `405` response lists the allowed methods\nin its `Allow` header.\n",
+    "license": {
+      "name": "GPL-3.0",
+      "url": "https://www.gnu.org/licenses/gpl-3.0.html"
+    }
+  },
+  "servers": [
+    {
+      "url": "/api/v1"
+    }
+  ],
+  "tags": [
+    {
+      "name": "server",
+      "description": "Server discovery and the published OpenAPI document."
+    }
+  ],
+  "paths": {
+    "/server": {
+      "get": {
+        "operationId": "getServerInfo",
+        "x-module": "core",
+        "x-stability-level": "alpha",
+        "tags": [
+          "server"
+        ],
+        "summary": "Describe the server",
+        "description": "Returns the public server description. No authentication required.\nAuthenticated requests will additionally receive the implemented capability modules\nonce authentication is available.\n",
+        "responses": {
+          "200": {
+            "description": "Server description.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ServerInfo"
+                }
+              }
+            }
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalError"
+          }
+        }
+      }
+    },
+    "/openapi.json": {
+      "get": {
+        "operationId": "getOpenAPISpecJSON",
+        "x-module": "core",
+        "x-stability-level": "alpha",
+        "tags": [
+          "server"
+        ],
+        "summary": "Get the OpenAPI document (JSON)",
+        "description": "The bundled OpenAPI document of the running server version. Supports ETag revalidation.",
+        "responses": {
+          "200": {
+            "description": "The OpenAPI document.",
+            "headers": {
+              "ETag": {
+                "$ref": "#/components/headers/ETag"
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "description": "OpenAPI 3.0 document."
+                }
+              }
+            }
+          },
+          "304": {
+            "$ref": "#/components/responses/NotModified"
+          }
+        }
+      }
+    },
+    "/openapi.yaml": {
+      "get": {
+        "operationId": "getOpenAPISpecYAML",
+        "x-module": "core",
+        "x-stability-level": "alpha",
+        "tags": [
+          "server"
+        ],
+        "summary": "Get the OpenAPI document (YAML)",
+        "description": "The bundled OpenAPI document of the running server version. Supports ETag revalidation.",
+        "responses": {
+          "200": {
+            "description": "The OpenAPI document.",
+            "headers": {
+              "ETag": {
+                "$ref": "#/components/headers/ETag"
+              }
+            },
+            "content": {
+              "application/yaml": {
+                "schema": {
+                  "type": "object",
+                  "description": "OpenAPI 3.0 document."
+                }
+              }
+            }
+          },
+          "304": {
+            "$ref": "#/components/responses/NotModified"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT",
+        "description": "Short-lived access token minted from a device grant. Not yet applied to any operation."
+      }
+    },
+    "schemas": {
+      "ServerInfo": {
+        "type": "object",
+        "description": "Public server description. Everything an add-server screen needs before login.",
+        "required": [
+          "name",
+          "serverVersion",
+          "specVersion",
+          "setupRequired",
+          "loginMethods"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-readable server product name."
+          },
+          "serverVersion": {
+            "type": "string",
+            "description": "Version of the running server build."
+          },
+          "specVersion": {
+            "type": "string",
+            "description": "Version of the OpenAPI document this server implements."
+          },
+          "setupRequired": {
+            "type": "boolean",
+            "description": "True until the first admin user has been created."
+          },
+          "loginMethods": {
+            "type": "array",
+            "description": "Login methods this server accepts. New methods may be added; clients ignore values they do not recognise.",
+            "items": {
+              "type": "string",
+              "enum": [
+                "password"
+              ]
+            }
+          }
+        }
+      },
+      "Problem": {
+        "type": "object",
+        "description": "RFC 9457 problem details, returned for every 4xx and 5xx response.",
+        "required": [
+          "title",
+          "status",
+          "code"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "URI reference identifying the problem type. Omitted while the problem carries no semantics\nbeyond its HTTP status code, which RFC 9457 defines as `about:blank`. Problems with their\nown semantics get their own URI; switch on `code` instead.\n"
+          },
+          "title": {
+            "type": "string",
+            "description": "Short human-readable summary, the same for all occurrences of this problem type."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code of this response."
+          },
+          "detail": {
+            "type": "string",
+            "description": "Human-readable explanation specific to this occurrence. Omitted for internal errors."
+          },
+          "code": {
+            "type": "string",
+            "description": "Machine-readable error code, and the value clients switch on. New codes may be added.",
+            "enum": [
+              "validation",
+              "unauthorized",
+              "forbidden",
+              "not_found",
+              "method_not_allowed",
+              "unavailable",
+              "internal"
+            ]
+          },
+          "errors": {
+            "type": "array",
+            "description": "Per-field failures. Present only when `code` is `validation`.",
+            "items": {
+              "$ref": "#/components/schemas/ValidationError"
+            }
+          }
+        }
+      },
+      "ValidationError": {
+        "type": "object",
+        "description": "One field-level validation failure.",
+        "required": [
+          "field",
+          "message"
+        ],
+        "properties": {
+          "field": {
+            "type": "string",
+            "description": "Name of the offending query parameter, path parameter, or body field (dotted for nested)."
+          },
+          "message": {
+            "type": "string",
+            "description": "Why the value was rejected."
+          }
+        }
+      }
+    },
+    "responses": {
+      "InternalError": {
+        "description": "Unexpected server failure. Details are in the server log.",
+        "content": {
+          "application/problem+json": {
+            "schema": {
+              "$ref": "#/components/schemas/Problem"
+            }
+          }
+        }
+      },
+      "NotModified": {
+        "description": "Not modified.",
+        "headers": {
+          "ETag": {
+            "$ref": "#/components/headers/ETag"
+          }
+        }
+      }
+    },
+    "headers": {
+      "ETag": {
+        "description": "Entity tag for `If-None-Match` revalidation.",
+        "schema": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/api/bundled/openapi.yaml b/api/bundled/openapi.yaml
new file mode 100644
index 000000000..f1ae95b76
--- /dev/null
+++ b/api/bundled/openapi.yaml
@@ -0,0 +1,194 @@
+openapi: 3.0.3
+info:
+  title: Navidrome API
+  version: 1.0.0
+  description: |
+    Navidrome API v1. Spec-first, additive within v1. Clients discover implemented
+    capability modules through `GET /server` and never sniff versions.
+
+    Enums are open: new values may be added to any enum within v1. Clients must
+    accept values they do not recognise instead of failing.
+
+    Every operation declares `x-stability-level`: `alpha` operations may change or
+    disappear without notice, `beta` and `stable` operations only change additively.
+    A level is only ever raised, never lowered.
+
+    `HEAD` is accepted wherever `GET` is. A `405` response lists the allowed methods
+    in its `Allow` header.
+  license:
+    name: GPL-3.0
+    url: https://www.gnu.org/licenses/gpl-3.0.html
+servers:
+  - url: /api/v1
+tags:
+  - name: server
+    description: Server discovery and the published OpenAPI document.
+paths:
+  /server:
+    get:
+      operationId: getServerInfo
+      x-module: core
+      x-stability-level: alpha
+      tags: [server]
+      summary: Describe the server
+      description: |
+        Returns the public server description. No authentication required.
+        Authenticated requests will additionally receive the implemented capability modules
+        once authentication is available.
+      responses:
+        '200':
+          description: Server description.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ServerInfo'
+        '500':
+          $ref: '#/components/responses/InternalError'
+  /openapi.json:
+    get:
+      operationId: getOpenAPISpecJSON
+      x-module: core
+      x-stability-level: alpha
+      tags: [server]
+      summary: Get the OpenAPI document (JSON)
+      description: The bundled OpenAPI document of the running server version. Supports ETag revalidation.
+      responses:
+        '200':
+          description: The OpenAPI document.
+          headers:
+            ETag:
+              $ref: '#/components/headers/ETag'
+          content:
+            application/json:
+              schema:
+                type: object
+                description: OpenAPI 3.0 document.
+        '304':
+          $ref: '#/components/responses/NotModified'
+  /openapi.yaml:
+    get:
+      operationId: getOpenAPISpecYAML
+      x-module: core
+      x-stability-level: alpha
+      tags: [server]
+      summary: Get the OpenAPI document (YAML)
+      description: The bundled OpenAPI document of the running server version. Supports ETag revalidation.
+      responses:
+        '200':
+          description: The OpenAPI document.
+          headers:
+            ETag:
+              $ref: '#/components/headers/ETag'
+          content:
+            application/yaml:
+              schema:
+                type: object
+                description: OpenAPI 3.0 document.
+        '304':
+          $ref: '#/components/responses/NotModified'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: Short-lived access token minted from a device grant. Not yet applied to any operation.
+  schemas:
+    ServerInfo:
+      type: object
+      description: Public server description. Everything an add-server screen needs before login.
+      required:
+        - name
+        - serverVersion
+        - specVersion
+        - setupRequired
+        - loginMethods
+      properties:
+        name:
+          type: string
+          description: Human-readable server product name.
+        serverVersion:
+          type: string
+          description: Version of the running server build.
+        specVersion:
+          type: string
+          description: Version of the OpenAPI document this server implements.
+        setupRequired:
+          type: boolean
+          description: True until the first admin user has been created.
+        loginMethods:
+          type: array
+          description: Login methods this server accepts. New methods may be added; clients ignore values they do not recognise.
+          items:
+            type: string
+            enum:
+              - password
+    Problem:
+      type: object
+      description: RFC 9457 problem details, returned for every 4xx and 5xx response.
+      required:
+        - title
+        - status
+        - code
+      properties:
+        type:
+          type: string
+          description: |
+            URI reference identifying the problem type. Omitted while the problem carries no semantics
+            beyond its HTTP status code, which RFC 9457 defines as `about:blank`. Problems with their
+            own semantics get their own URI; switch on `code` instead.
+        title:
+          type: string
+          description: Short human-readable summary, the same for all occurrences of this problem type.
+        status:
+          type: integer
+          description: HTTP status code of this response.
+        detail:
+          type: string
+          description: Human-readable explanation specific to this occurrence. Omitted for internal errors.
+        code:
+          type: string
+          description: Machine-readable error code, and the value clients switch on. New codes may be added.
+          enum:
+            - validation
+            - unauthorized
+            - forbidden
+            - not_found
+            - method_not_allowed
+            - unavailable
+            - internal
+        errors:
+          type: array
+          description: Per-field failures. Present only when `code` is `validation`.
+          items:
+            $ref: '#/components/schemas/ValidationError'
+    ValidationError:
+      type: object
+      description: One field-level validation failure.
+      required:
+        - field
+        - message
+      properties:
+        field:
+          type: string
+          description: Name of the offending query parameter, path parameter, or body field (dotted for nested).
+        message:
+          type: string
+          description: Why the value was rejected.
+  responses:
+    InternalError:
+      description: Unexpected server failure. Details are in the server log.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+    NotModified:
+      description: Not modified.
+      headers:
+        ETag:
+          $ref: '#/components/headers/ETag'
+  headers:
+    ETag:
+      description: Entity tag for `If-None-Match` revalidation.
+      schema:
+        type: string
diff --git a/api/embed.go b/api/embed.go
new file mode 100644
index 000000000..7e94c2362
--- /dev/null
+++ b/api/embed.go
@@ -0,0 +1,35 @@
+package api
+
+import (
+	_ "embed"
+	"encoding/json"
+	"sync"
+)
+
+//go:embed bundled/openapi.json
+var specJSON []byte
+
+//go:embed bundled/openapi.yaml
+var specYAML []byte
+
+func SpecJSON() []byte {
+	return specJSON
+}
+
+func SpecYAML() []byte {
+	return specYAML
+}
+
+var specVersion = sync.OnceValue(func() string {
+	var doc struct {
+		Info struct {
+			Version string `json:"version"`
+		} `json:"info"`
+	}
+	_ = json.Unmarshal(SpecJSON(), &doc)
+	return doc.Info.Version
+})
+
+func SpecVersion() string {
+	return specVersion()
+}
diff --git a/api/embed_test.go b/api/embed_test.go
new file mode 100644
index 000000000..ebd5a7d1d
--- /dev/null
+++ b/api/embed_test.go
@@ -0,0 +1,37 @@
+package api_test
+
+import (
+	"os"
+
+	"github.com/getkin/kin-openapi/openapi3"
+	"github.com/navidrome/navidrome/api"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"gopkg.in/yaml.v3"
+)
+
+var _ = Describe("Bundled spec", func() {
+	It("embeds a valid OpenAPI 3 document", func() {
+		doc, err := openapi3.NewLoader().LoadFromData(api.SpecJSON())
+		Expect(err).ToNot(HaveOccurred())
+		Expect(doc.Validate(GinkgoT().Context())).To(Succeed())
+		Expect(doc.Paths.Find("/server")).ToNot(BeNil())
+	})
+
+	It("embeds the YAML variant", func() {
+		var doc map[string]any
+		Expect(yaml.Unmarshal(api.SpecYAML(), &doc)).To(Succeed())
+		Expect(doc).To(HaveKey("paths"))
+	})
+
+	It("reports the version from the bundle, matching the source root document", func() {
+		src, err := os.ReadFile("api/openapi/openapi.yaml")
+		Expect(err).ToNot(HaveOccurred())
+		var root struct {
+			Info struct{ Version string } `yaml:"info"`
+		}
+		Expect(yaml.Unmarshal(src, &root)).To(Succeed())
+		Expect(api.SpecVersion()).To(Equal(root.Info.Version))
+		Expect(api.SpecVersion()).ToNot(BeEmpty())
+	})
+})
diff --git a/api/openapi/components/headers/ETag.yaml b/api/openapi/components/headers/ETag.yaml
new file mode 100644
index 000000000..0f64e6792
--- /dev/null
+++ b/api/openapi/components/headers/ETag.yaml
@@ -0,0 +1,3 @@
+description: Entity tag for `If-None-Match` revalidation.
+schema:
+  type: string
diff --git a/api/openapi/components/parameters/limit.yaml b/api/openapi/components/parameters/limit.yaml
new file mode 100644
index 000000000..9bef4fc8b
--- /dev/null
+++ b/api/openapi/components/parameters/limit.yaml
@@ -0,0 +1,9 @@
+name: limit
+in: query
+description: Maximum number of items to return.
+required: false
+schema:
+  type: integer
+  minimum: 1
+  maximum: 2000
+  default: 100
diff --git a/api/openapi/components/parameters/offset.yaml b/api/openapi/components/parameters/offset.yaml
new file mode 100644
index 000000000..9145d6eaa
--- /dev/null
+++ b/api/openapi/components/parameters/offset.yaml
@@ -0,0 +1,8 @@
+name: offset
+in: query
+description: Zero-based index of the first item to return.
+required: false
+schema:
+  type: integer
+  minimum: 0
+  default: 0
diff --git a/api/openapi/components/responses/BadRequest.yaml b/api/openapi/components/responses/BadRequest.yaml
new file mode 100644
index 000000000..1a6e0b657
--- /dev/null
+++ b/api/openapi/components/responses/BadRequest.yaml
@@ -0,0 +1,5 @@
+description: The request is malformed or fails validation.
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/Problem.yaml
diff --git a/api/openapi/components/responses/Forbidden.yaml b/api/openapi/components/responses/Forbidden.yaml
new file mode 100644
index 000000000..6259185ea
--- /dev/null
+++ b/api/openapi/components/responses/Forbidden.yaml
@@ -0,0 +1,5 @@
+description: The caller is authenticated but not allowed to do this.
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/Problem.yaml
diff --git a/api/openapi/components/responses/InternalError.yaml b/api/openapi/components/responses/InternalError.yaml
new file mode 100644
index 000000000..20e654d44
--- /dev/null
+++ b/api/openapi/components/responses/InternalError.yaml
@@ -0,0 +1,5 @@
+description: Unexpected server failure. Details are in the server log.
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/Problem.yaml
diff --git a/api/openapi/components/responses/NotFound.yaml b/api/openapi/components/responses/NotFound.yaml
new file mode 100644
index 000000000..6083a5cd1
--- /dev/null
+++ b/api/openapi/components/responses/NotFound.yaml
@@ -0,0 +1,5 @@
+description: No such resource or endpoint.
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/Problem.yaml
diff --git a/api/openapi/components/responses/NotModified.yaml b/api/openapi/components/responses/NotModified.yaml
new file mode 100644
index 000000000..36bc1a61c
--- /dev/null
+++ b/api/openapi/components/responses/NotModified.yaml
@@ -0,0 +1,4 @@
+description: Not modified.
+headers:
+  ETag:
+    $ref: ../headers/ETag.yaml
diff --git a/api/openapi/components/responses/Unauthorized.yaml b/api/openapi/components/responses/Unauthorized.yaml
new file mode 100644
index 000000000..0209f4dd9
--- /dev/null
+++ b/api/openapi/components/responses/Unauthorized.yaml
@@ -0,0 +1,5 @@
+description: Missing, invalid, or expired credentials.
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/Problem.yaml
diff --git a/api/openapi/components/schemas/ListMeta.yaml b/api/openapi/components/schemas/ListMeta.yaml
new file mode 100644
index 000000000..6321e0588
--- /dev/null
+++ b/api/openapi/components/schemas/ListMeta.yaml
@@ -0,0 +1,13 @@
+type: object
+description: Pagination metadata carried by every list response.
+required: [total, offset, limit]
+properties:
+  total:
+    type: integer
+    description: Total number of items matching the request, ignoring pagination.
+  offset:
+    type: integer
+    description: Zero-based index of the first returned item.
+  limit:
+    type: integer
+    description: Maximum number of items in this page.
diff --git a/api/openapi/components/schemas/Problem.yaml b/api/openapi/components/schemas/Problem.yaml
new file mode 100644
index 000000000..0fd36d4b1
--- /dev/null
+++ b/api/openapi/components/schemas/Problem.yaml
@@ -0,0 +1,35 @@
+type: object
+description: RFC 9457 problem details, returned for every 4xx and 5xx response.
+required: [title, status, code]
+properties:
+  type:
+    type: string
+    description: |
+      URI reference identifying the problem type. Omitted while the problem carries no semantics
+      beyond its HTTP status code, which RFC 9457 defines as `about:blank`. Problems with their
+      own semantics get their own URI; switch on `code` instead.
+  title:
+    type: string
+    description: Short human-readable summary, the same for all occurrences of this problem type.
+  status:
+    type: integer
+    description: HTTP status code of this response.
+  detail:
+    type: string
+    description: Human-readable explanation specific to this occurrence. Omitted for internal errors.
+  code:
+    type: string
+    description: Machine-readable error code, and the value clients switch on. New codes may be added.
+    enum:
+      - validation
+      - unauthorized
+      - forbidden
+      - not_found
+      - method_not_allowed
+      - unavailable
+      - internal
+  errors:
+    type: array
+    description: Per-field failures. Present only when `code` is `validation`.
+    items:
+      $ref: ./ValidationError.yaml
diff --git a/api/openapi/components/schemas/ServerInfo.yaml b/api/openapi/components/schemas/ServerInfo.yaml
new file mode 100644
index 000000000..8906924eb
--- /dev/null
+++ b/api/openapi/components/schemas/ServerInfo.yaml
@@ -0,0 +1,22 @@
+type: object
+description: Public server description. Everything an add-server screen needs before login.
+required: [name, serverVersion, specVersion, setupRequired, loginMethods]
+properties:
+  name:
+    type: string
+    description: Human-readable server product name.
+  serverVersion:
+    type: string
+    description: Version of the running server build.
+  specVersion:
+    type: string
+    description: Version of the OpenAPI document this server implements.
+  setupRequired:
+    type: boolean
+    description: True until the first admin user has been created.
+  loginMethods:
+    type: array
+    description: Login methods this server accepts. New methods may be added; clients ignore values they do not recognise.
+    items:
+      type: string
+      enum: [password]
diff --git a/api/openapi/components/schemas/ValidationError.yaml b/api/openapi/components/schemas/ValidationError.yaml
new file mode 100644
index 000000000..8a1cbc4f9
--- /dev/null
+++ b/api/openapi/components/schemas/ValidationError.yaml
@@ -0,0 +1,10 @@
+type: object
+description: One field-level validation failure.
+required: [field, message]
+properties:
+  field:
+    type: string
+    description: Name of the offending query parameter, path parameter, or body field (dotted for nested).
+  message:
+    type: string
+    description: Why the value was rejected.
diff --git a/api/openapi/openapi.yaml b/api/openapi/openapi.yaml
new file mode 100644
index 000000000..73cbb7b27
--- /dev/null
+++ b/api/openapi/openapi.yaml
@@ -0,0 +1,39 @@
+openapi: 3.0.3
+info:
+  title: Navidrome API
+  version: 1.0.0
+  description: |
+    Navidrome API v1. Spec-first, additive within v1. Clients discover implemented
+    capability modules through `GET /server` and never sniff versions.
+
+    Enums are open: new values may be added to any enum within v1. Clients must
+    accept values they do not recognise instead of failing.
+
+    Every operation declares `x-stability-level`: `alpha` operations may change or
+    disappear without notice, `beta` and `stable` operations only change additively.
+    A level is only ever raised, never lowered.
+
+    `HEAD` is accepted wherever `GET` is. A `405` response lists the allowed methods
+    in its `Allow` header.
+  license:
+    name: GPL-3.0
+    url: https://www.gnu.org/licenses/gpl-3.0.html
+servers:
+  - url: /api/v1
+tags:
+  - name: server
+    description: Server discovery and the published OpenAPI document.
+paths:
+  /server:
+    $ref: ./paths/server.yaml
+  /openapi.json:
+    $ref: ./paths/openapi.yaml#/json
+  /openapi.yaml:
+    $ref: ./paths/openapi.yaml#/yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: Short-lived access token minted from a device grant. Not yet applied to any operation.
diff --git a/api/openapi/paths/openapi.yaml b/api/openapi/paths/openapi.yaml
new file mode 100644
index 000000000..3c25dc8b7
--- /dev/null
+++ b/api/openapi/paths/openapi.yaml
@@ -0,0 +1,42 @@
+json:
+  get:
+    operationId: getOpenAPISpecJSON
+    x-module: core
+    x-stability-level: alpha
+    tags: [server]
+    summary: Get the OpenAPI document (JSON)
+    description: The bundled OpenAPI document of the running server version. Supports ETag revalidation.
+    responses:
+      '200':
+        description: The OpenAPI document.
+        headers:
+          ETag:
+            $ref: ../components/headers/ETag.yaml
+        content:
+          application/json:
+            schema:
+              type: object
+              description: OpenAPI 3.0 document.
+      '304':
+        $ref: ../components/responses/NotModified.yaml
+yaml:
+  get:
+    operationId: getOpenAPISpecYAML
+    x-module: core
+    x-stability-level: alpha
+    tags: [server]
+    summary: Get the OpenAPI document (YAML)
+    description: The bundled OpenAPI document of the running server version. Supports ETag revalidation.
+    responses:
+      '200':
+        description: The OpenAPI document.
+        headers:
+          ETag:
+            $ref: ../components/headers/ETag.yaml
+        content:
+          application/yaml:
+            schema:
+              type: object
+              description: OpenAPI 3.0 document.
+      '304':
+        $ref: ../components/responses/NotModified.yaml
diff --git a/api/openapi/paths/server.yaml b/api/openapi/paths/server.yaml
new file mode 100644
index 000000000..1f881dbb1
--- /dev/null
+++ b/api/openapi/paths/server.yaml
@@ -0,0 +1,19 @@
+get:
+  operationId: getServerInfo
+  x-module: core
+  x-stability-level: alpha
+  tags: [server]
+  summary: Describe the server
+  description: |
+    Returns the public server description. No authentication required.
+    Authenticated requests will additionally receive the implemented capability modules
+    once authentication is available.
+  responses:
+    '200':
+      description: Server description.
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ServerInfo.yaml
+    '500':
+      $ref: ../components/responses/InternalError.yaml
diff --git a/cmd/root.go b/cmd/root.go
index b23674441..edfcbe69c 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -133,6 +133,9 @@ func startServer(ctx context.Context) func() error {
 		if conf.Server.Jellyfin.Enabled {
 			a.MountRouter("Jellyfin API", consts.URLPathJellyfinAPI, CreateJellyfinAPIRouter(ctx))
 		}
+		if conf.Server.DevAPIv1 {
+			a.MountRouter("API v1", consts.URLPathAPIv1, CreateAPIv1Router(ctx))
+		}
 		if conf.Server.Prometheus.Enabled {
 			p := CreatePrometheus()
 			// blocking call because takes <100ms but useful if fails
diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index cb06cc047..19f92d9d5 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -31,6 +31,7 @@ import (
 	"github.com/navidrome/navidrome/plugins"
 	"github.com/navidrome/navidrome/scanner"
 	"github.com/navidrome/navidrome/server"
+	"github.com/navidrome/navidrome/server/apiv1"
 	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/server/jellyfin"
 	"github.com/navidrome/navidrome/server/nativeapi"
@@ -142,6 +143,13 @@ func CreateJellyfinAPIRouter(ctx context.Context) *jellyfin.Router {
 	return router
 }
 
+func CreateAPIv1Router(ctx context.Context) *apiv1.Router {
+	sqlDB := db.Db()
+	dataStore := persistence.New(sqlDB)
+	router := apiv1.New(dataStore)
+	return router
+}
+
 func CreatePublicRouter() *public.Router {
 	sqlDB := db.Db()
 	dataStore := persistence.New(sqlDB)
@@ -259,7 +267,7 @@ func getPluginManager() *plugins.Manager {
 
 // wire_injectors.go:
 
-var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, jellyfin.New, jellyfin.NewDiscovery, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.GetInstance, 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(sonic.Engine), new(*sonic.Sonic)), 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)), wire.Bind(new(playlists.ImageUploadService), new(artwork.Uploader)))
+var allProviders = wire.NewSet(core.Set, artwork.Set, server.New, subsonic.New, jellyfin.New, jellyfin.NewDiscovery, apiv1.New, nativeapi.New, public.New, persistence.New, lastfm.NewRouter, listenbrainz.NewRouter, events.GetBroker, scanner.GetInstance, 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(sonic.Engine), new(*sonic.Sonic)), 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)), wire.Bind(new(playlists.ImageUploadService), new(artwork.Uploader)))
 
 func GetPluginManager(ctx context.Context) *plugins.Manager {
 	manager := getPluginManager()
diff --git a/cmd/wire_injectors.go b/cmd/wire_injectors.go
index 527617959..c5006e07f 100644
--- a/cmd/wire_injectors.go
+++ b/cmd/wire_injectors.go
@@ -23,6 +23,7 @@ import (
 	"github.com/navidrome/navidrome/plugins"
 	"github.com/navidrome/navidrome/scanner"
 	"github.com/navidrome/navidrome/server"
+	"github.com/navidrome/navidrome/server/apiv1"
 	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/server/jellyfin"
 	"github.com/navidrome/navidrome/server/nativeapi"
@@ -37,6 +38,7 @@ var allProviders = wire.NewSet(
 	subsonic.New,
 	jellyfin.New,
 	jellyfin.NewDiscovery,
+	apiv1.New,
 	nativeapi.New,
 	public.New,
 	persistence.New,
@@ -91,6 +93,12 @@ func CreateJellyfinAPIRouter(ctx context.Context) *jellyfin.Router {
 	))
 }
 
+func CreateAPIv1Router(ctx context.Context) *apiv1.Router {
+	panic(wire.Build(
+		allProviders,
+	))
+}
+
 func CreatePublicRouter() *public.Router {
 	panic(wire.Build(
 		allProviders,
diff --git a/conf/configuration.go b/conf/configuration.go
index 0173f5628..efa9cbf9a 100644
--- a/conf/configuration.go
+++ b/conf/configuration.go
@@ -161,6 +161,7 @@ type configOptions struct {
 	DevExternalArtistFetchMultiplier  float64
 	DevPreserveUnicodeInExternalCalls bool
 	DevEnableMediaFileProbe           bool
+	DevAPIv1                          bool
 }
 
 type scannerOptions struct {
@@ -1124,6 +1125,7 @@ func setViperDefaults() {
 	viper.SetDefault("devshowartistpage", true)
 	viper.SetDefault("devuishowconfig", true)
 	viper.SetDefault("devneweventstream", true)
+	viper.SetDefault("devapiv1", false)
 	viper.SetDefault("devoffsetoptimize", 50000)
 	// Half the pool: streams may take up to this many connections, leaving the rest for the scanner,
 	// scrobbles and the UI. See MaxOpenConns.
diff --git a/consts/consts.go b/consts/consts.go
index 486ea66bc..7228299c6 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -59,6 +59,7 @@ const (
 	URLPathPublic       = "/share"
 	URLPathPublicImages = URLPathPublic + "/img"
 	URLPathJellyfinAPI  = "/jellyfin"
+	URLPathAPIv1        = "/api/v1"
 
 	// JellyfinServerIDKey is the Property key for the stable, persisted server Id reported by the
 	// Jellyfin API. Jellyfin clients cache this value, so it must survive process restarts.
diff --git a/go.mod b/go.mod
index 464038d7e..e96b8c8b3 100644
--- a/go.mod
+++ b/go.mod
@@ -20,6 +20,7 @@ require (
 	github.com/extism/go-sdk v1.7.1
 	github.com/fatih/structs v1.1.0
 	github.com/gen2brain/webp v0.6.4
+	github.com/getkin/kin-openapi v0.149.0
 	github.com/go-chi/chi/v5 v5.3.2
 	github.com/go-chi/cors v1.2.2
 	github.com/go-chi/httprate v0.16.0
@@ -84,6 +85,8 @@ require (
 	github.com/ebitengine/purego v0.11.1 // indirect
 	github.com/fsnotify/fsnotify v1.10.1 // indirect
 	github.com/go-logr/logr v1.4.4 // indirect
+	github.com/go-openapi/jsonpointer v0.22.5 // indirect
+	github.com/go-openapi/swag/jsonname v0.25.5 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
 	github.com/gobwas/glob v1.0.0 // indirect
 	github.com/goccy/go-json v0.10.6 // indirect
@@ -92,6 +95,7 @@ require (
 	github.com/google/pprof v0.0.0-20260906184651-6331bc6350fe // indirect
 	github.com/google/subcommands v1.2.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
+	github.com/gorilla/mux v1.8.0 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/ianlancetaylor/demangle v0.0.0-20260724033716-83e58baca724 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
@@ -110,6 +114,8 @@ require (
 	github.com/mfridman/interpolate v0.0.2 // indirect
 	github.com/mitchellh/go-wordwrap v1.0.1 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/oasdiff/yaml v0.1.1 // indirect
+	github.com/oasdiff/yaml3 v0.0.14 // indirect
 	github.com/ogier/pflag v0.0.1 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
diff --git a/go.sum b/go.sum
index 929366a76..fe6dbbc3f 100644
--- a/go.sum
+++ b/go.sum
@@ -63,6 +63,8 @@ github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx5
 github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
 github.com/gen2brain/webp v0.6.4 h1:SUDdmxADOAiPQ+5ylNmuHhuYf2dOi0KgKZHL5vpVCNU=
 github.com/gen2brain/webp v0.6.4/go.mod h1:iGWMaCSw7t3I/Cv9llzEKmpnR36S8lS8VL/ZVjxU0JE=
+github.com/getkin/kin-openapi v0.149.0 h1:ZbhmVJ4yq5RZDUsyP8lcBcGMsjsaTqXEFt6isdtMDfA=
+github.com/getkin/kin-openapi v0.149.0/go.mod h1:1+BHDzstro+P5CKtPy1X4PfofnFgmRe6uvMy9+r9fKY=
 github.com/gkampitakis/ciinfo v0.3.2 h1:JcuOPk8ZU7nZQjdUhctuhQofk7BGHuIy0c9Ez8BNhXs=
 github.com/gkampitakis/ciinfo v0.3.2/go.mod h1:1NIwaOcFChN4fa/B0hEBdAb6npDlFL8Bwx4dfRLRqAo=
 github.com/gkampitakis/go-diff v1.3.2 h1:Qyn0J9XJSDTgnsgHRdz9Zp24RaJeKMUHg2+PDZZdC4M=
@@ -79,6 +81,12 @@ github.com/go-chi/jwtauth/v5 v5.4.0 h1:Ieh0xMJsFvqylqJ02/mQHKzbbKO9DYNBh4DPKCwTw
 github.com/go-chi/jwtauth/v5 v5.4.0/go.mod h1:w6yjqUUXz1b8+oiJel64Sz1KJwduQM6qUA5QNzO5+bQ=
 github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8=
 github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-openapi/jsonpointer v0.22.5 h1:8on/0Yp4uTb9f4XvTrM2+1CPrV05QPZXu+rvu2o9jcA=
+github.com/go-openapi/jsonpointer v0.22.5/go.mod h1:gyUR3sCvGSWchA2sUBJGluYMbe1zazrYWIkWPjjMUY0=
+github.com/go-openapi/swag/jsonname v0.25.5 h1:8p150i44rv/Drip4vWI3kGi9+4W9TdI3US3uUYSFhSo=
+github.com/go-openapi/swag/jsonname v0.25.5/go.mod h1:jNqqikyiAK56uS7n8sLkdaNY/uq6+D2m2LANat09pKU=
+github.com/go-openapi/testify/v2 v2.4.0 h1:8nsPrHVCWkQ4p8h1EsRVymA2XABB4OT40gcvAu+voFM=
+github.com/go-openapi/testify/v2 v2.4.0/go.mod h1:HCPmvFFnheKK2BuwSA0TbbdxJ3I16pjwMkYkP4Ywn54=
 github.com/go-sql-driver/mysql v1.4.1/go.mod h1:zAC/RDZ24gD3HViQzih4MyKcchzm+sOG5ZlKdlhCg5w=
 github.com/go-sql-driver/mysql v1.10.0 h1:Q+1LV8DkHJvSYAdR83XzuhDaTykuDx0l6fkXxoWCWfw=
 github.com/go-sql-driver/mysql v1.10.0/go.mod h1:M+cqaI7+xxXGG9swrdeUIoPG3Y3KCkF0pZej+SK+nWk=
@@ -111,6 +119,8 @@ github.com/google/wire v0.7.0 h1:JxUKI6+CVBgCO2WToKy/nQk0sS+amI9z9EjVmdaocj4=
 github.com/google/wire v0.7.0/go.mod h1:n6YbUQD9cPKTnHXEBN2DXlOp/mVADhVErcMFb0v3J18=
 github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
 github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
+github.com/gorilla/mux v1.8.0 h1:i40aqfkR1h2SlN9hojwV5ZA91wcXFOvkdNIeFDP5koI=
+github.com/gorilla/mux v1.8.0/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
@@ -178,6 +188,10 @@ github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/oasdiff/yaml v0.1.1 h1:6nHx+pn9gBRM6YpBlFZFQGCCd1nuvqOBtTD3KKTgGxY=
+github.com/oasdiff/yaml v0.1.1/go.mod h1:EYJNoyktvWMJ0Hmhx+6qTaqMOsalUaRGT8Sj1hNcegU=
+github.com/oasdiff/yaml3 v0.0.14 h1:aLJee3hxBK2H5wdXd9iPcIXb93Nty1Ge0pT171eHtkw=
+github.com/oasdiff/yaml3 v0.0.14/go.mod h1:csto2xfDjYccdUn/yw/bPjj/cYTdp6HtFA0J4TWG+gg=
 github.com/ogier/pflag v0.0.1 h1:RW6JSWSu/RkSatfcLtogGfFgpim5p7ARQ10ECk5O750=
 github.com/ogier/pflag v0.0.1/go.mod h1:zkFki7tvTa0tafRvTBIZTvzYyAu6kQhPZFnshFFPE+g=
 github.com/onsi/ginkgo/v2 v2.33.0 h1:C8gBA6Uc2ZEubiV+SXiu5tZnMTwEmXHgkJwGozKtZf8=
@@ -326,8 +340,8 @@ google.golang.org/appengine v1.6.5/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCID
 google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
 google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=
-gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/ini.v1 v1.67.3 h1:iM9Lhz5MRSGhHVGGwCuzG9KO8PoirCXj/m/qTmOJJQw=
 gopkg.in/ini.v1 v1.67.3/go.mod h1:x/cyOwCgZqOkJoDIJ3c1KNHMo10+nLGAhh+kn3Zizss=
 gopkg.in/natefinch/npipe.v2 v2.0.0-20160621034901-c1b8fa8bdcce h1:+JknDZhAj8YMt7GC73Ei8pv4MzjDUNPHgQWJdtMAaDU=
diff --git a/server/apiv1/api.go b/server/apiv1/api.go
new file mode 100644
index 000000000..a75de3d8d
--- /dev/null
+++ b/server/apiv1/api.go
@@ -0,0 +1,98 @@
+package apiv1
+
+import (
+	"errors"
+	"net/http"
+	"runtime/debug"
+	"slices"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/navidrome/navidrome/api"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+type Router struct {
+	http.Handler
+	ds model.DataStore
+}
+
+func New(ds model.DataStore) *Router {
+	rt := &Router{ds: ds}
+	rt.Handler = rt.routes()
+	return rt
+}
+
+func (rt *Router) routes() http.Handler {
+	r := chi.NewRouter()
+	r.Use(problemRecoverer, headAsGet(r))
+	r.NotFound(func(w http.ResponseWriter, req *http.Request) {
+		writeProblemStatus(w, req, http.StatusNotFound, ProblemCodeNotFound, "no such endpoint")
+	})
+	r.MethodNotAllowed(func(w http.ResponseWriter, req *http.Request) {
+		w.Header().Set("Allow", strings.Join(allowedMethods(r, req), ", "))
+		writeProblemStatus(w, req, http.StatusMethodNotAllowed, ProblemCodeMethodNotAllowed, "")
+	})
+
+	r.Get("/openapi.json", specHandler(withBasePath(api.SpecJSON(), `"url": `, true), "application/json"))
+	r.Get("/openapi.yaml", specHandler(withBasePath(api.SpecYAML(), "url: ", false), "application/yaml"))
+
+	strict := NewStrictHandlerWithOptions(rt, nil, StrictHTTPServerOptions{
+		RequestErrorHandlerFunc: func(w http.ResponseWriter, req *http.Request, err error) {
+			writeProblemStatus(w, req, http.StatusBadRequest, "validation", err.Error())
+		},
+		ResponseErrorHandlerFunc: writeProblem,
+	})
+	HandlerWithOptions(strict, ChiServerOptions{BaseRouter: r, ErrorHandlerFunc: bindingErrorHandler})
+	return r
+}
+
+func problemRecoverer(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			rec := recover()
+			if rec == nil {
+				return
+			}
+			if err, ok := rec.(error); ok && errors.Is(err, http.ErrAbortHandler) {
+				panic(rec)
+			}
+			log.Error(r.Context(), "API v1: panic in handler", "panic", rec, "stack", string(debug.Stack()))
+			writeProblemStatus(w, r, http.StatusInternalServerError, ProblemCodeInternal, "")
+		}()
+		next.ServeHTTP(w, r)
+	})
+}
+
+var routableMethods = []string{http.MethodGet, http.MethodHead, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete}
+
+// Looks routes up on mux itself: chi's RouteContext().Routes points at the parent router when mounted.
+func allowedMethods(mux chi.Routes, req *http.Request) []string {
+	path := routePath(req)
+	var allowed []string
+	for _, m := range routableMethods {
+		if mux.Match(chi.NewRouteContext(), m, path) || (m == http.MethodHead && slices.Contains(allowed, http.MethodGet)) {
+			allowed = append(allowed, m)
+		}
+	}
+	return allowed
+}
+
+func headAsGet(mux chi.Routes) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+			if req.Method == http.MethodHead && !mux.Match(chi.NewRouteContext(), http.MethodHead, routePath(req)) {
+				chi.RouteContext(req.Context()).RouteMethod = http.MethodGet
+			}
+			next.ServeHTTP(w, req)
+		})
+	}
+}
+
+func routePath(req *http.Request) string {
+	if rctx := chi.RouteContext(req.Context()); rctx != nil && rctx.RoutePath != "" {
+		return rctx.RoutePath
+	}
+	return req.URL.Path
+}
diff --git a/server/apiv1/api_gen.go b/server/apiv1/api_gen.go
new file mode 100644
index 000000000..4bffd47fc
--- /dev/null
+++ b/server/apiv1/api_gen.go
@@ -0,0 +1,390 @@
+// Package apiv1 provides primitives to interact with the openapi HTTP API.
+//
+// Code generated by github.com/oapi-codegen/oapi-codegen/v2 version v2.8.0 DO NOT EDIT.
+package apiv1
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+)
+
+// Defines values for ProblemCode.
+const (
+	ProblemCodeForbidden        ProblemCode = "forbidden"
+	ProblemCodeInternal         ProblemCode = "internal"
+	ProblemCodeMethodNotAllowed ProblemCode = "method_not_allowed"
+	ProblemCodeNotFound         ProblemCode = "not_found"
+	ProblemCodeUnauthorized     ProblemCode = "unauthorized"
+	ProblemCodeUnavailable      ProblemCode = "unavailable"
+	ProblemCodeValidation       ProblemCode = "validation"
+)
+
+// Valid indicates whether the value is a known member of the ProblemCode enum.
+func (e ProblemCode) Valid() bool {
+	switch e {
+	case ProblemCodeForbidden:
+		return true
+	case ProblemCodeInternal:
+		return true
+	case ProblemCodeMethodNotAllowed:
+		return true
+	case ProblemCodeNotFound:
+		return true
+	case ProblemCodeUnauthorized:
+		return true
+	case ProblemCodeUnavailable:
+		return true
+	case ProblemCodeValidation:
+		return true
+	default:
+		return false
+	}
+}
+
+// Defines values for ServerInfoLoginMethods.
+const (
+	ServerInfoLoginMethodsPassword ServerInfoLoginMethods = "password"
+)
+
+// Valid indicates whether the value is a known member of the ServerInfoLoginMethods enum.
+func (e ServerInfoLoginMethods) Valid() bool {
+	switch e {
+	case ServerInfoLoginMethodsPassword:
+		return true
+	default:
+		return false
+	}
+}
+
+// Problem RFC 9457 problem details, returned for every 4xx and 5xx response.
+type Problem struct {
+	// Code Machine-readable error code, and the value clients switch on. New codes may be added.
+	Code ProblemCode `json:"code"`
+
+	// Detail Human-readable explanation specific to this occurrence. Omitted for internal errors.
+	Detail *string `json:"detail,omitempty"`
+
+	// Errors Per-field failures. Present only when `code` is `validation`.
+	Errors *[]ValidationError `json:"errors,omitempty"`
+
+	// Status HTTP status code of this response.
+	Status int `json:"status"`
+
+	// Title Short human-readable summary, the same for all occurrences of this problem type.
+	Title string `json:"title"`
+
+	// Type URI reference identifying the problem type. Omitted while the problem carries no semantics
+	// beyond its HTTP status code, which RFC 9457 defines as `about:blank`. Problems with their
+	// own semantics get their own URI; switch on `code` instead.
+	Type *string `json:"type,omitempty"`
+}
+
+// ProblemCode Machine-readable error code, and the value clients switch on. New codes may be added.
+type ProblemCode string
+
+// ServerInfo Public server description. Everything an add-server screen needs before login.
+type ServerInfo struct {
+	// LoginMethods Login methods this server accepts. New methods may be added; clients ignore values they do not recognise.
+	LoginMethods []ServerInfoLoginMethods `json:"loginMethods"`
+
+	// Name Human-readable server product name.
+	Name string `json:"name"`
+
+	// ServerVersion Version of the running server build.
+	ServerVersion string `json:"serverVersion"`
+
+	// SetupRequired True until the first admin user has been created.
+	SetupRequired bool `json:"setupRequired"`
+
+	// SpecVersion Version of the OpenAPI document this server implements.
+	SpecVersion string `json:"specVersion"`
+}
+
+// ServerInfoLoginMethods defines model for ServerInfo.LoginMethods.
+type ServerInfoLoginMethods string
+
+// ValidationError One field-level validation failure.
+type ValidationError struct {
+	// Field Name of the offending query parameter, path parameter, or body field (dotted for nested).
+	Field string `json:"field"`
+
+	// Message Why the value was rejected.
+	Message string `json:"message"`
+}
+
+// InternalError RFC 9457 problem details, returned for every 4xx and 5xx response.
+type InternalError = Problem
+
+// ServerInterface represents all server handlers.
+type ServerInterface interface {
+	// GetServerInfo Describe the server
+	// (GET /server)
+	GetServerInfo(w http.ResponseWriter, r *http.Request)
+}
+
+// Unimplemented server implementation that returns http.StatusNotImplemented for each endpoint.
+
+type Unimplemented struct{}
+
+// GetServerInfo Describe the server
+// (GET /server)
+func (_ Unimplemented) GetServerInfo(w http.ResponseWriter, r *http.Request) {
+	w.WriteHeader(http.StatusNotImplemented)
+}
+
+// ServerInterfaceWrapper converts contexts to parameters.
+type ServerInterfaceWrapper struct {
+	Handler            ServerInterface
+	HandlerMiddlewares []MiddlewareFunc
+	ErrorHandlerFunc   func(w http.ResponseWriter, r *http.Request, err error)
+}
+
+type MiddlewareFunc func(http.Handler) http.Handler
+
+// GetServerInfo operation middleware
+func (siw *ServerInterfaceWrapper) GetServerInfo(w http.ResponseWriter, r *http.Request) {
+
+	handler := http.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		siw.Handler.GetServerInfo(w, r)
+	}))
+
+	for _, middleware := range siw.HandlerMiddlewares {
+		handler = middleware(handler)
+	}
+
+	handler.ServeHTTP(w, r)
+}
+
+type UnescapedCookieParamError struct {
+	ParamName string
+	Err       error
+}
+
+func (e *UnescapedCookieParamError) Error() string {
+	return fmt.Sprintf("error unescaping cookie parameter '%s'", e.ParamName)
+}
+
+func (e *UnescapedCookieParamError) Unwrap() error {
+	return e.Err
+}
+
+type UnmarshalingParamError struct {
+	ParamName string
+	Err       error
+}
+
+func (e *UnmarshalingParamError) Error() string {
+	return fmt.Sprintf("Error unmarshaling parameter %s as JSON: %s", e.ParamName, e.Err.Error())
+}
+
+func (e *UnmarshalingParamError) Unwrap() error {
+	return e.Err
+}
+
+type RequiredParamError struct {
+	ParamName string
+}
+
+func (e *RequiredParamError) Error() string {
+	return fmt.Sprintf("Query argument %s is required, but not found", e.ParamName)
+}
+
+type RequiredHeaderError struct {
+	ParamName string
+	Err       error
+}
+
+func (e *RequiredHeaderError) Error() string {
+	return fmt.Sprintf("Header parameter %s is required, but not found", e.ParamName)
+}
+
+func (e *RequiredHeaderError) Unwrap() error {
+	return e.Err
+}
+
+type InvalidParamFormatError struct {
+	ParamName string
+	Err       error
+}
+
+func (e *InvalidParamFormatError) Error() string {
+	return fmt.Sprintf("Invalid format for parameter %s: %s", e.ParamName, e.Err.Error())
+}
+
+func (e *InvalidParamFormatError) Unwrap() error {
+	return e.Err
+}
+
+type TooManyValuesForParamError struct {
+	ParamName string
+	Count     int
+}
+
+func (e *TooManyValuesForParamError) Error() string {
+	return fmt.Sprintf("Expected one value for %s, got %d", e.ParamName, e.Count)
+}
+
+// Handler creates http.Handler with routing matching OpenAPI spec.
+func Handler(si ServerInterface) http.Handler {
+	return HandlerWithOptions(si, ChiServerOptions{})
+}
+
+type ChiServerOptions struct {
+	BaseURL          string
+	BaseRouter       chi.Router
+	Middlewares      []MiddlewareFunc
+	ErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, err error)
+}
+
+// HandlerFromMux creates http.Handler with routing matching OpenAPI spec based on the provided mux.
+func HandlerFromMux(si ServerInterface, r chi.Router) http.Handler {
+	return HandlerWithOptions(si, ChiServerOptions{
+		BaseRouter: r,
+	})
+}
+
+func HandlerFromMuxWithBaseURL(si ServerInterface, r chi.Router, baseURL string) http.Handler {
+	return HandlerWithOptions(si, ChiServerOptions{
+		BaseURL:    baseURL,
+		BaseRouter: r,
+	})
+}
+
+// HandlerWithOptions creates http.Handler with additional options
+func HandlerWithOptions(si ServerInterface, options ChiServerOptions) http.Handler {
+	r := options.BaseRouter
+
+	if r == nil {
+		r = chi.NewRouter()
+	}
+	if options.ErrorHandlerFunc == nil {
+		options.ErrorHandlerFunc = func(w http.ResponseWriter, r *http.Request, err error) {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+		}
+	}
+	wrapper := ServerInterfaceWrapper{
+		Handler:            si,
+		HandlerMiddlewares: options.Middlewares,
+		ErrorHandlerFunc:   options.ErrorHandlerFunc,
+	}
+
+	r.Group(func(r chi.Router) {
+		r.Get(options.BaseURL+"/server", wrapper.GetServerInfo)
+	})
+
+	return r
+}
+
+type InternalErrorApplicationProblemPlusJSONResponse Problem
+
+type GetServerInfoRequestObject struct {
+}
+
+type GetServerInfoResponseObject interface {
+	VisitGetServerInfoResponse(w http.ResponseWriter) error
+}
+
+type GetServerInfo200JSONResponse ServerInfo
+
+func (response GetServerInfo200JSONResponse) VisitGetServerInfoResponse(w http.ResponseWriter) error {
+
+	var buf bytes.Buffer
+	if err := json.NewEncoder(&buf).Encode(response); err != nil {
+		return err
+	}
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(200)
+	_, err := buf.WriteTo(w)
+	return err
+}
+
+type GetServerInfo500ApplicationProblemPlusJSONResponse struct {
+	InternalErrorApplicationProblemPlusJSONResponse
+}
+
+func (response GetServerInfo500ApplicationProblemPlusJSONResponse) VisitGetServerInfoResponse(w http.ResponseWriter) error {
+
+	var buf bytes.Buffer
+	if err := json.NewEncoder(&buf).Encode(response); err != nil {
+		return err
+	}
+	w.Header().Set("Content-Type", "application/problem+json")
+	w.WriteHeader(500)
+	_, err := buf.WriteTo(w)
+	return err
+}
+
+// StrictServerInterface represents all server handlers.
+type StrictServerInterface interface {
+	// GetServerInfo Describe the server
+	// (GET /server)
+	GetServerInfo(ctx context.Context, request GetServerInfoRequestObject) (GetServerInfoResponseObject, error)
+}
+
+type StrictHandlerFunc func(ctx context.Context, w http.ResponseWriter, r *http.Request, request any) (any, error)
+type StrictMiddlewareFunc func(f StrictHandlerFunc, operationID string) StrictHandlerFunc
+
+type StrictHTTPServerOptions struct {
+	RequestErrorHandlerFunc  func(w http.ResponseWriter, r *http.Request, err error)
+	ResponseErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, err error)
+}
+
+func NewStrictHandler(ssi StrictServerInterface, middlewares []StrictMiddlewareFunc) ServerInterface {
+	return &strictHandler{ssi: ssi, middlewares: middlewares, options: StrictHTTPServerOptions{
+		RequestErrorHandlerFunc: func(w http.ResponseWriter, r *http.Request, err error) {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+		},
+		ResponseErrorHandlerFunc: func(w http.ResponseWriter, r *http.Request, err error) {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+		},
+	}}
+}
+
+func NewStrictHandlerWithOptions(ssi StrictServerInterface, middlewares []StrictMiddlewareFunc, options StrictHTTPServerOptions) ServerInterface {
+	if options.RequestErrorHandlerFunc == nil {
+		options.RequestErrorHandlerFunc = func(w http.ResponseWriter, r *http.Request, err error) {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+		}
+	}
+	if options.ResponseErrorHandlerFunc == nil {
+		options.ResponseErrorHandlerFunc = func(w http.ResponseWriter, r *http.Request, err error) {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+		}
+	}
+	return &strictHandler{ssi: ssi, middlewares: middlewares, options: options}
+}
+
+type strictHandler struct {
+	ssi         StrictServerInterface
+	middlewares []StrictMiddlewareFunc
+	options     StrictHTTPServerOptions
+}
+
+// GetServerInfo operation middleware
+func (sh *strictHandler) GetServerInfo(w http.ResponseWriter, r *http.Request) {
+	var request GetServerInfoRequestObject
+
+	handler := func(ctx context.Context, w http.ResponseWriter, r *http.Request, request interface{}) (interface{}, error) {
+		return sh.ssi.GetServerInfo(ctx, request.(GetServerInfoRequestObject))
+	}
+	for _, middleware := range sh.middlewares {
+		handler = middleware(handler, "GetServerInfo")
+	}
+
+	response, err := handler(r.Context(), w, r, request)
+
+	if err != nil {
+		sh.options.ResponseErrorHandlerFunc(w, r, err)
+	} else if validResponse, ok := response.(GetServerInfoResponseObject); ok {
+		if err := validResponse.VisitGetServerInfoResponse(w); err != nil {
+			sh.options.ResponseErrorHandlerFunc(w, r, err)
+		}
+	} else if response != nil {
+		sh.options.ResponseErrorHandlerFunc(w, r, fmt.Errorf("unexpected response type: %T", response))
+	}
+}
diff --git a/server/apiv1/api_test.go b/server/apiv1/api_test.go
new file mode 100644
index 000000000..2552e40b0
--- /dev/null
+++ b/server/apiv1/api_test.go
@@ -0,0 +1,75 @@
+package apiv1
+
+import (
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Router", func() {
+	var router *Router
+
+	BeforeEach(func() {
+		router = New(&tests.MockDataStore{})
+	})
+
+	It("returns a 404 problem for unknown paths", func() {
+		w := serve(router, httptest.NewRequest(http.MethodGet, "/api/v1/nope", nil))
+		Expect(w.Code).To(Equal(http.StatusNotFound))
+		Expect(w.Header().Get("Content-Type")).To(Equal(problemContentType))
+		Expect(decodeProblem(w).Code).To(Equal(ProblemCodeNotFound))
+	})
+
+	It("returns a 405 problem listing the allowed methods for a wrong method on a known path", func() {
+		w := serve(router, httptest.NewRequest(http.MethodPost, "/api/v1/server", nil))
+		Expect(w.Code).To(Equal(http.StatusMethodNotAllowed))
+		Expect(w.Header().Get("Allow")).To(Equal("GET, HEAD"))
+		Expect(decodeProblem(w).Code).To(Equal(ProblemCodeMethodNotAllowed))
+	})
+
+	DescribeTable("answers HEAD wherever GET is routed",
+		func(path, contentType string) {
+			w := serve(router, httptest.NewRequest(http.MethodHead, path, nil))
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(w.Header().Get("Content-Type")).To(Equal(contentType))
+		},
+		Entry("server info", "/api/v1/server", "application/json"),
+		Entry("JSON spec", "/api/v1/openapi.json", "application/json"),
+		Entry("YAML spec", "/api/v1/openapi.yaml", "application/yaml"),
+	)
+
+	It("revalidates HEAD requests with If-None-Match", func() {
+		etag := serve(router, httptest.NewRequest(http.MethodHead, "/api/v1/openapi.json", nil)).Header().Get("ETag")
+		req := httptest.NewRequest(http.MethodHead, "/api/v1/openapi.json", nil)
+		req.Header.Set("If-None-Match", etag)
+		Expect(serve(router, req).Code).To(Equal(http.StatusNotModified))
+	})
+
+	It("returns a 404 problem for HEAD on unknown paths", func() {
+		w := serve(router, httptest.NewRequest(http.MethodHead, "/api/v1/nope", nil))
+		Expect(w.Code).To(Equal(http.StatusNotFound))
+		Expect(w.Header().Get("Allow")).To(BeEmpty())
+	})
+
+	panicking := func(v any) http.Handler {
+		return problemRecoverer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { panic(v) }))
+	}
+
+	It("turns a handler panic into a 500 problem", func() {
+		w := httptest.NewRecorder()
+		panicking("kaboom").ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/boom", nil))
+		Expect(w.Code).To(Equal(http.StatusInternalServerError))
+		p := decodeProblem(w)
+		Expect(p.Code).To(Equal(ProblemCodeInternal))
+		Expect(p.Detail).To(BeNil())
+	})
+
+	It("re-panics http.ErrAbortHandler so the server can drop the connection", func() {
+		Expect(func() {
+			panicking(http.ErrAbortHandler).ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/abort", nil))
+		}).To(PanicWith(http.ErrAbortHandler))
+	})
+})
diff --git a/server/apiv1/apiv1_suite_test.go b/server/apiv1/apiv1_suite_test.go
new file mode 100644
index 000000000..f89244e38
--- /dev/null
+++ b/server/apiv1/apiv1_suite_test.go
@@ -0,0 +1,66 @@
+package apiv1
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/getkin/kin-openapi/openapi3"
+	"github.com/getkin/kin-openapi/openapi3filter"
+	"github.com/getkin/kin-openapi/routers"
+	"github.com/getkin/kin-openapi/routers/gorillamux"
+	"github.com/go-chi/chi/v5"
+	"github.com/navidrome/navidrome/api"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestAPIv1(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "API v1 Suite")
+}
+
+var specRouter routers.Router
+
+var _ = BeforeSuite(func() {
+	doc, err := openapi3.NewLoader().LoadFromData(api.SpecJSON())
+	Expect(err).ToNot(HaveOccurred())
+	specRouter, err = gorillamux.NewRouter(doc)
+	Expect(err).ToNot(HaveOccurred())
+})
+
+// serve routes req through h mounted at /api/v1 and asserts the response conforms to the spec.
+func serve(h http.Handler, req *http.Request) *httptest.ResponseRecorder {
+	root := chi.NewRouter()
+	root.Mount("/api/v1", h)
+	w := httptest.NewRecorder()
+	root.ServeHTTP(w, req)
+	validateAgainstSpec(req, w)
+	return w
+}
+
+func validateAgainstSpec(req *http.Request, w *httptest.ResponseRecorder) {
+	route, pathParams, err := specRouter.FindRoute(req)
+	if errors.Is(err, routers.ErrPathNotFound) || errors.Is(err, routers.ErrMethodNotAllowed) {
+		return
+	}
+	ExpectWithOffset(2, err).ToNot(HaveOccurred())
+	input := &openapi3filter.ResponseValidationInput{
+		RequestValidationInput: &openapi3filter.RequestValidationInput{
+			Request: req, PathParams: pathParams, Route: route,
+		},
+		Status:  w.Code,
+		Header:  w.Header(),
+		Body:    io.NopCloser(bytes.NewReader(w.Body.Bytes())),
+		Options: &openapi3filter.Options{IncludeResponseStatus: true},
+	}
+	ExpectWithOffset(2, openapi3filter.ValidateResponse(req.Context(), input)).To(Succeed(),
+		"response for %s %s does not conform to the spec", req.Method, req.URL.Path)
+}
diff --git a/server/apiv1/oapi-codegen.yaml b/server/apiv1/oapi-codegen.yaml
new file mode 100644
index 000000000..b9236de1a
--- /dev/null
+++ b/server/apiv1/oapi-codegen.yaml
@@ -0,0 +1,12 @@
+package: apiv1
+output: server/apiv1/api_gen.go
+generate:
+  chi-server: true
+  strict-server: true
+  models: true
+output-options:
+  exclude-operation-ids:
+    - getOpenAPISpecJSON
+    - getOpenAPISpecYAML
+compatibility:
+  always-prefix-enum-values: true
diff --git a/server/apiv1/problem.go b/server/apiv1/problem.go
new file mode 100644
index 000000000..aa6389357
--- /dev/null
+++ b/server/apiv1/problem.go
@@ -0,0 +1,72 @@
+package apiv1
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+)
+
+const problemContentType = "application/problem+json"
+
+func writeProblem(w http.ResponseWriter, r *http.Request, err error) {
+	status, code := classifyError(err)
+	detail := err.Error()
+	if status == http.StatusInternalServerError {
+		log.Error(r.Context(), "API v1: unexpected error", "path", r.URL.Path, err)
+		detail = ""
+	}
+	writeProblemStatus(w, r, status, code, detail)
+}
+
+func classifyError(err error) (int, ProblemCode) {
+	switch {
+	case errors.Is(err, model.ErrNotFound):
+		return http.StatusNotFound, ProblemCodeNotFound
+	case errors.Is(err, model.ErrNotAuthorized):
+		return http.StatusForbidden, ProblemCodeForbidden
+	case errors.Is(err, model.ErrInvalidAuth), errors.Is(err, model.ErrExpired):
+		return http.StatusUnauthorized, ProblemCodeUnauthorized
+	case errors.Is(err, model.ErrValidation):
+		return http.StatusBadRequest, ProblemCodeValidation
+	case errors.Is(err, model.ErrNotAvailable):
+		return http.StatusServiceUnavailable, ProblemCodeUnavailable
+	}
+	return http.StatusInternalServerError, ProblemCodeInternal
+}
+
+func writeProblemStatus(w http.ResponseWriter, r *http.Request, status int, code ProblemCode, detail string, fieldErrors ...ValidationError) {
+	p := Problem{Title: http.StatusText(status), Status: status, Code: code}
+	if detail != "" {
+		p.Detail = &detail
+	}
+	if len(fieldErrors) > 0 {
+		p.Errors = &fieldErrors
+	}
+	w.Header().Set("Content-Type", problemContentType)
+	w.WriteHeader(status)
+	if err := json.NewEncoder(w).Encode(p); err != nil {
+		log.Warn(r.Context(), "API v1: could not write problem response", err)
+	}
+}
+
+func bindingErrorHandler(w http.ResponseWriter, r *http.Request, err error) {
+	var fieldErrors []ValidationError
+	var required *RequiredParamError
+	var invalid *InvalidParamFormatError
+	var tooMany *TooManyValuesForParamError
+	var unmarshal *UnmarshalingParamError
+	switch {
+	case errors.As(err, &required):
+		fieldErrors = append(fieldErrors, ValidationError{Field: required.ParamName, Message: "is required"})
+	case errors.As(err, &invalid):
+		fieldErrors = append(fieldErrors, ValidationError{Field: invalid.ParamName, Message: invalid.Err.Error()})
+	case errors.As(err, &tooMany):
+		fieldErrors = append(fieldErrors, ValidationError{Field: tooMany.ParamName, Message: "expected a single value"})
+	case errors.As(err, &unmarshal):
+		fieldErrors = append(fieldErrors, ValidationError{Field: unmarshal.ParamName, Message: unmarshal.Err.Error()})
+	}
+	writeProblemStatus(w, r, http.StatusBadRequest, ProblemCodeValidation, err.Error(), fieldErrors...)
+}
diff --git a/server/apiv1/problem_test.go b/server/apiv1/problem_test.go
new file mode 100644
index 000000000..256296b3c
--- /dev/null
+++ b/server/apiv1/problem_test.go
@@ -0,0 +1,114 @@
+package apiv1
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func decodeProblem(w *httptest.ResponseRecorder) Problem {
+	var p Problem
+	ExpectWithOffset(1, json.Unmarshal(w.Body.Bytes(), &p)).To(Succeed())
+	return p
+}
+
+var _ = Describe("problem", func() {
+	var w *httptest.ResponseRecorder
+	var r *http.Request
+
+	BeforeEach(func() {
+		w = httptest.NewRecorder()
+		r = httptest.NewRequest(http.MethodGet, "/api/v1/server", nil)
+	})
+
+	Describe("writeProblem", func() {
+		DescribeTable("maps domain errors to status and code",
+			func(err error, status int, code ProblemCode) {
+				writeProblem(w, r, err)
+				Expect(w.Code).To(Equal(status))
+				Expect(w.Header().Get("Content-Type")).To(Equal(problemContentType))
+				p := decodeProblem(w)
+				Expect(p.Status).To(Equal(status))
+				Expect(p.Code).To(Equal(code))
+				Expect(p.Title).To(Equal(http.StatusText(status)))
+				Expect(p.Type).To(BeNil())
+				Expect(w.Body.String()).ToNot(ContainSubstring(`"type"`))
+			},
+			Entry("not found", model.ErrNotFound, http.StatusNotFound, ProblemCodeNotFound),
+			Entry("not authorized", model.ErrNotAuthorized, http.StatusForbidden, ProblemCodeForbidden),
+			Entry("invalid auth", model.ErrInvalidAuth, http.StatusUnauthorized, ProblemCodeUnauthorized),
+			Entry("expired", model.ErrExpired, http.StatusUnauthorized, ProblemCodeUnauthorized),
+			Entry("validation", model.ErrValidation, http.StatusBadRequest, ProblemCodeValidation),
+			Entry("not available", model.ErrNotAvailable, http.StatusServiceUnavailable, ProblemCodeUnavailable),
+			Entry("unknown", errors.New("boom"), http.StatusInternalServerError, ProblemCodeInternal),
+		)
+
+		DescribeTable("keeps the wrapping context as detail for client errors",
+			func(err error) {
+				writeProblem(w, r, err)
+				p := decodeProblem(w)
+				Expect(p.Status).To(Equal(http.StatusNotFound))
+				Expect(p.Detail).ToNot(BeNil())
+				Expect(*p.Detail).To(ContainSubstring("album 123"))
+			},
+			Entry("fmt.Errorf %w", fmt.Errorf("album 123: %w", model.ErrNotFound)),
+			Entry("errors.Join", errors.Join(errors.New("album 123"), model.ErrNotFound)),
+		)
+
+		It("hides details for internal errors", func() {
+			writeProblem(w, r, errors.New("db password is hunter2"))
+			p := decodeProblem(w)
+			Expect(p.Detail).To(BeNil())
+		})
+	})
+
+	Describe("writeProblemStatus", func() {
+		It("writes field errors only when provided", func() {
+			writeProblemStatus(w, r, http.StatusBadRequest, ProblemCodeValidation, "bad input",
+				ValidationError{Field: "limit", Message: "must be <= 2000"})
+			p := decodeProblem(w)
+			Expect(p.Errors).ToNot(BeNil())
+			Expect(*p.Errors).To(HaveLen(1))
+			Expect((*p.Errors)[0].Field).To(Equal("limit"))
+		})
+
+		It("omits detail when empty", func() {
+			writeProblemStatus(w, r, http.StatusMethodNotAllowed, ProblemCodeMethodNotAllowed, "")
+			Expect(w.Body.String()).ToNot(ContainSubstring(`"detail"`))
+			Expect(w.Body.String()).ToNot(ContainSubstring(`"errors"`))
+		})
+	})
+
+	Describe("bindingErrorHandler", func() {
+		DescribeTable("maps parameter binding errors to a validation problem with the field",
+			func(err error, field, message string) {
+				bindingErrorHandler(w, r, err)
+				Expect(w.Code).To(Equal(http.StatusBadRequest))
+				p := decodeProblem(w)
+				Expect(p.Code).To(Equal(ProblemCodeValidation))
+				Expect(p.Errors).ToNot(BeNil())
+				Expect(*p.Errors).To(HaveLen(1))
+				Expect((*p.Errors)[0].Field).To(Equal(field))
+				Expect((*p.Errors)[0].Message).To(ContainSubstring(message))
+			},
+			Entry("required", &RequiredParamError{ParamName: "limit"}, "limit", "is required"),
+			Entry("invalid format", &InvalidParamFormatError{ParamName: "offset", Err: errors.New("not a number")}, "offset", "not a number"),
+			Entry("too many values", &TooManyValuesForParamError{ParamName: "sort", Count: 2}, "sort", "single value"),
+			Entry("unmarshaling", &UnmarshalingParamError{ParamName: "ids", Err: errors.New("bad json")}, "ids", "bad json"),
+		)
+
+		It("still returns a validation problem for unknown binding errors", func() {
+			bindingErrorHandler(w, r, errors.New("weird"))
+			p := decodeProblem(w)
+			Expect(p.Status).To(Equal(http.StatusBadRequest))
+			Expect(p.Code).To(Equal(ProblemCodeValidation))
+			Expect(p.Errors).To(BeNil())
+		})
+	})
+})
diff --git a/server/apiv1/server_info.go b/server/apiv1/server_info.go
new file mode 100644
index 000000000..458363efe
--- /dev/null
+++ b/server/apiv1/server_info.go
@@ -0,0 +1,23 @@
+package apiv1
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/navidrome/navidrome/api"
+	"github.com/navidrome/navidrome/consts"
+)
+
+func (rt *Router) GetServerInfo(ctx context.Context, _ GetServerInfoRequestObject) (GetServerInfoResponseObject, error) {
+	count, err := rt.ds.User().CountAll(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("counting users: %w", err)
+	}
+	return GetServerInfo200JSONResponse{
+		Name:          "Navidrome",
+		ServerVersion: consts.Version,
+		SpecVersion:   api.SpecVersion(),
+		SetupRequired: count == 0,
+		LoginMethods:  []ServerInfoLoginMethods{ServerInfoLoginMethodsPassword},
+	}, nil
+}
diff --git a/server/apiv1/server_info_test.go b/server/apiv1/server_info_test.go
new file mode 100644
index 000000000..b9dae6f8d
--- /dev/null
+++ b/server/apiv1/server_info_test.go
@@ -0,0 +1,61 @@
+package apiv1
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/navidrome/navidrome/api"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("GET /server", func() {
+	var ctx context.Context
+	var ds *tests.MockDataStore
+	var users *tests.MockedUserRepo
+
+	BeforeEach(func() {
+		ctx = GinkgoT().Context()
+		users = tests.CreateMockUserRepo()
+		ds = &tests.MockDataStore{MockedUser: users}
+	})
+
+	get := func() (*httptest.ResponseRecorder, ServerInfo) {
+		w := serve(New(ds), httptest.NewRequest(http.MethodGet, "/api/v1/server", nil))
+		var info ServerInfo
+		if w.Code == http.StatusOK {
+			ExpectWithOffset(1, json.Unmarshal(w.Body.Bytes(), &info)).To(Succeed())
+		}
+		return w, info
+	}
+
+	It("describes the server with setupRequired when there are no users", func() {
+		w, info := get()
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Header().Get("Content-Type")).To(HavePrefix("application/json"))
+		Expect(info.Name).To(Equal("Navidrome"))
+		Expect(info.ServerVersion).To(Equal(consts.Version))
+		Expect(info.SpecVersion).To(Equal(api.SpecVersion()))
+		Expect(info.SetupRequired).To(BeTrue())
+		Expect(info.LoginMethods).To(ConsistOf(ServerInfoLoginMethodsPassword))
+	})
+
+	It("reports setupRequired=false once a user exists", func() {
+		Expect(users.Put(ctx, &model.User{ID: "u1", UserName: "admin", IsAdmin: true})).To(Succeed())
+		_, info := get()
+		Expect(info.SetupRequired).To(BeFalse())
+	})
+
+	It("returns a 500 problem when the user count fails", func() {
+		users.Error = errors.New("db down")
+		w, _ := get()
+		Expect(w.Code).To(Equal(http.StatusInternalServerError))
+		Expect(decodeProblem(w).Code).To(Equal(ProblemCodeInternal))
+	})
+})
diff --git a/server/apiv1/spec.go b/server/apiv1/spec.go
new file mode 100644
index 000000000..bdca19693
--- /dev/null
+++ b/server/apiv1/spec.go
@@ -0,0 +1,51 @@
+package apiv1
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"path"
+	"strconv"
+
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/utils/req"
+	"github.com/zeebo/xxh3"
+)
+
+func specHandler(body []byte, contentType string) http.HandlerFunc {
+	etag := fmt.Sprintf("%016x", xxh3.Hash(body))
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("ETag", `"`+etag+`"`)
+		w.Header().Set("Cache-Control", "no-cache")
+		if req.IfNoneMatch(r, etag) {
+			w.WriteHeader(http.StatusNotModified)
+			return
+		}
+		w.Header().Set("Content-Type", contentType)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(body)
+	}
+}
+
+// withBasePath adds BasePath to the advertised server URL, since only the running server knows it.
+func withBasePath(body []byte, key string, quotedInBundle bool) []byte {
+	serverURL := path.Join(conf.Server.BasePath, consts.URLPathAPIv1)
+	if serverURL == consts.URLPathAPIv1 {
+		return body
+	}
+	oldURL := consts.URLPathAPIv1
+	if quotedInBundle {
+		oldURL = strconv.Quote(oldURL)
+	}
+	old := []byte(key + oldURL)
+	if bytes.Count(body, old) != 1 {
+		log.Error("API v1: server URL not found in the bundled spec, serving it without the base path", "key", key)
+		return body
+	}
+	// A JSON string is also a valid YAML double-quoted scalar, so one encoding escapes both formats.
+	newURL, _ := json.Marshal(serverURL)
+	return bytes.Replace(body, old, append([]byte(key), newURL...), 1)
+}
diff --git a/server/apiv1/spec_test.go b/server/apiv1/spec_test.go
new file mode 100644
index 000000000..a2368f899
--- /dev/null
+++ b/server/apiv1/spec_test.go
@@ -0,0 +1,136 @@
+package apiv1
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/navidrome/navidrome/api"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"gopkg.in/yaml.v3"
+)
+
+var _ = Describe("OpenAPI document routes", func() {
+	var router *Router
+
+	BeforeEach(func() {
+		router = New(&tests.MockDataStore{})
+	})
+
+	get := func(path string, headers map[string]string) *httptest.ResponseRecorder {
+		req := httptest.NewRequest(http.MethodGet, path, nil)
+		for k, v := range headers {
+			req.Header.Set(k, v)
+		}
+		return serve(router, req)
+	}
+
+	DescribeTable("serves the embedded bundle",
+		func(path, contentType string, body []byte) {
+			w := get(path, nil)
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(w.Header().Get("Content-Type")).To(Equal(contentType))
+			Expect(w.Header().Get("ETag")).ToNot(BeEmpty())
+			Expect(w.Header().Get("Cache-Control")).To(Equal("no-cache"))
+			Expect(w.Body.Bytes()).To(Equal(body))
+		},
+		Entry("JSON", "/api/v1/openapi.json", "application/json", api.SpecJSON()),
+		Entry("YAML", "/api/v1/openapi.yaml", "application/yaml", api.SpecYAML()),
+	)
+
+	DescribeTable("revalidates with If-None-Match",
+		func(ifNoneMatch func(etag string) string, expected int) {
+			etag := get("/api/v1/openapi.json", nil).Header().Get("ETag")
+			w := get("/api/v1/openapi.json", map[string]string{"If-None-Match": ifNoneMatch(etag)})
+			Expect(w.Code).To(Equal(expected))
+			if expected == http.StatusNotModified {
+				Expect(w.Body.Len()).To(BeZero())
+				Expect(w.Header().Get("ETag")).To(Equal(etag))
+			} else {
+				Expect(w.Body.Bytes()).To(Equal(api.SpecJSON()))
+			}
+		},
+		Entry("exact ETag", func(etag string) string { return etag }, http.StatusNotModified),
+		Entry("ETag in a list", func(etag string) string { return `"other", ` + etag }, http.StatusNotModified),
+		Entry("weak ETag", func(etag string) string { return "W/" + etag }, http.StatusNotModified),
+		Entry("wildcard", func(string) string { return "*" }, http.StatusNotModified),
+		Entry("stale ETag", func(string) string { return `"stale"` }, http.StatusOK),
+	)
+
+	It("ignores Range and returns the full document", func() {
+		w := get("/api/v1/openapi.json", map[string]string{"Range": "bytes=0-9"})
+		Expect(w.Code).To(Equal(http.StatusOK))
+		Expect(w.Header().Get("Accept-Ranges")).To(BeEmpty())
+		Expect(w.Body.Bytes()).To(Equal(api.SpecJSON()))
+	})
+
+	It("uses different ETags for JSON and YAML", func() {
+		j := get("/api/v1/openapi.json", nil)
+		y := get("/api/v1/openapi.yaml", nil)
+		Expect(j.Header().Get("ETag")).ToNot(Equal(y.Header().Get("ETag")))
+	})
+
+	Describe("with a base path", func() {
+		decode := func(format string, body []byte) map[string]any {
+			var doc map[string]any
+			if format == "json" {
+				ExpectWithOffset(1, json.Unmarshal(body, &doc)).To(Succeed())
+			} else {
+				ExpectWithOffset(1, yaml.Unmarshal(body, &doc)).To(Succeed())
+			}
+			return doc
+		}
+		serverURL := func(doc map[string]any) any {
+			return doc["servers"].([]any)[0].(map[string]any)["url"]
+		}
+		var plainETag string
+
+		BeforeEach(func() {
+			plainETag = get("/api/v1/openapi.json", nil).Header().Get("ETag")
+			DeferCleanup(configtest.SetupConfig())
+			conf.Server.BasePath = "/music"
+			router = New(&tests.MockDataStore{})
+		})
+
+		DescribeTable("advertises the server under the base path and changes nothing else",
+			func(path, format string, bundle []byte) {
+				w := get(path, nil)
+				Expect(w.Code).To(Equal(http.StatusOK))
+				served, original := decode(format, w.Body.Bytes()), decode(format, bundle)
+				Expect(serverURL(served)).To(Equal("/music/api/v1"))
+				delete(served, "servers")
+				delete(original, "servers")
+				Expect(served).To(Equal(original))
+			},
+			Entry("JSON", "/api/v1/openapi.json", "json", api.SpecJSON()),
+			Entry("YAML", "/api/v1/openapi.yaml", "yaml", api.SpecYAML()),
+		)
+
+		It("uses its own ETag, and still revalidates", func() {
+			etag := get("/api/v1/openapi.json", nil).Header().Get("ETag")
+			Expect(etag).ToNot(Equal(plainETag))
+			Expect(get("/api/v1/openapi.json", map[string]string{"If-None-Match": etag}).Code).To(Equal(http.StatusNotModified))
+		})
+
+		It("escapes base paths that need quoting", func() {
+			conf.Server.BasePath = "/my music: \"live\""
+			router = New(&tests.MockDataStore{})
+			Expect(serverURL(decode("json", get("/api/v1/openapi.json", nil).Body.Bytes()))).To(Equal("/my music: \"live\"/api/v1"))
+			Expect(serverURL(decode("yaml", get("/api/v1/openapi.yaml", nil).Body.Bytes()))).To(Equal("/my music: \"live\"/api/v1"))
+		})
+	})
+
+	DescribeTable("the bundle advertises the API path exactly once, which the base-path rewrite relies on",
+		func(bundle []byte) {
+			Expect(bytes.Count(bundle, []byte(consts.URLPathAPIv1))).To(Equal(1))
+		},
+		Entry("JSON", api.SpecJSON()),
+		Entry("YAML", api.SpecYAML()),
+	)
+})
diff --git a/server/imghttp/headers.go b/server/imghttp/headers.go
index 9308bcdab..354b11793 100644
--- a/server/imghttp/headers.go
+++ b/server/imghttp/headers.go
@@ -4,9 +4,9 @@ package imghttp
 
 import (
 	"net/http"
-	"strings"
 
 	"github.com/navidrome/navidrome/core/artwork"
+	"github.com/navidrome/navidrome/utils/req"
 )
 
 // WriteImageHeaders applies the artwork caching contract and reports whether a 304 was written
@@ -40,28 +40,9 @@ func WriteImageHeaders(w http.ResponseWriter, r *http.Request, img *artwork.Imag
 		h.Set("Cache-Control", "public, no-cache")
 	}
 
-	if etag != "" && ifNoneMatch(r.Header.Get("If-None-Match"), etag) {
+	if etag != "" && req.IfNoneMatch(r, etag) {
 		w.WriteHeader(http.StatusNotModified)
 		return true
 	}
 	return false
 }
-
-// ifNoneMatch reports whether If-None-Match asserts hash, using RFC 9110 weak comparison.
-func ifNoneMatch(header, hash string) bool {
-	header = strings.TrimSpace(header)
-	if header == "" {
-		return false
-	}
-	if header == "*" {
-		return true
-	}
-	for tag := range strings.SplitSeq(header, ",") {
-		tag = strings.TrimSpace(tag)
-		tag = strings.TrimPrefix(tag, "W/")
-		if strings.Trim(tag, `"`) == hash {
-			return true
-		}
-	}
-	return false
-}
diff --git a/utils/req/req.go b/utils/req/req.go
index 861cca9f7..6a863184c 100644
--- a/utils/req/req.go
+++ b/utils/req/req.go
@@ -178,3 +178,21 @@ func (r *Values) Float64Or(param string, def float64) float64 {
 	}
 	return f
 }
+
+// IfNoneMatch reports whether the request's If-None-Match asserts etag (unquoted), using RFC 9110 weak comparison.
+func IfNoneMatch(r *http.Request, etag string) bool {
+	header := strings.TrimSpace(r.Header.Get("If-None-Match"))
+	if header == "" {
+		return false
+	}
+	if header == "*" {
+		return true
+	}
+	for tag := range strings.SplitSeq(header, ",") {
+		tag = strings.TrimPrefix(strings.TrimSpace(tag), "W/")
+		if strings.Trim(tag, `"`) == etag {
+			return true
+		}
+	}
+	return false
+}
diff --git a/utils/req/req_test.go b/utils/req/req_test.go
index 5f9de8483..d64f51b02 100644
--- a/utils/req/req_test.go
+++ b/utils/req/req_test.go
@@ -290,3 +290,21 @@ var _ = Describe("Request Helpers", func() {
 		})
 	})
 })
+
+var _ = Describe("IfNoneMatch", func() {
+	DescribeTable("matches the ETag",
+		func(header string, expected bool) {
+			r := httptest.NewRequest("GET", "/", nil)
+			if header != "" {
+				r.Header.Set("If-None-Match", header)
+			}
+			Expect(req.IfNoneMatch(r, "abc123")).To(Equal(expected))
+		},
+		Entry("absent header", "", false),
+		Entry("exact quoted tag", `"abc123"`, true),
+		Entry("weak tag", `W/"abc123"`, true),
+		Entry("tag in a list", `"other", W/"abc123"`, true),
+		Entry("wildcard", "*", true),
+		Entry("different tag", `"stale"`, false),
+	)
+})

From 46c432719fdd2fb34c2ec6c4f573a1488fb90215 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 26 Sep 2026 23:30:50 -0400
Subject: [PATCH 188/200] fix(log): redact LastFM keys and Prometheus password
 in config dump (#6233)

The startup Configuration dump is rendered with pretty.Sprintf("%# v"), which
pads multi-line struct fields with spaces after the colon. The ApiKey and
Secret redaction patterns required the quote right after the colon, so
LastFM.ApiKey and LastFM.Secret were logged in clear text even with
EnableLogRedacting on. Allow optional whitespace after the colon, like the
other config patterns already do.

Prometheus.Password had no redaction pattern at all. Add one that also skips
escaped quotes, since the password can hold any character and pretty prints
it Go-quoted.

Add tests for the padded and unpadded forms, plus one that redacts a real
pretty.Sprintf dump of LastFM- and Prometheus-shaped structs so a padding
change in pretty can't bring the leak back.

Reported in https://github.com/navidrome/navidrome/discussions/6232
---
 log/log.go      |  6 +++--
 log/log_test.go | 67 ++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/log/log.go b/log/log.go
index de2f171b2..da1d7622e 100644
--- a/log/log.go
+++ b/log/log.go
@@ -27,14 +27,16 @@ var redacted = &Hook{
 	AcceptedLevels: logrus.AllLevels,
 	RedactionList: []string{
 		// Keys from the config
-		"(ApiKey:\")[\\w]*",
-		"(Secret:\")[\\w]*",
+		"(ApiKey:[\\s]*\")[\\w]*",
+		"(Secret:[\\s]*\")[\\w]*",
 		"(PasswordEncryptionKey:[\\s]*\")[^\"]*",
 		"(UserHeader:[\\s]*\")[^\"]*",
 		"(TrustedSources:[\\s]*\")[^\"]*",
 		"(MetricsPath:[\\s]*\")[^\"]*",
 		"(DevAutoCreateAdminPassword:[\\s]*\")[^\"]*",
 		"(DevAutoLoginUsername:[\\s]*\")[^\"]*",
+		// Prometheus.Password. Any character is allowed, so skip escaped quotes in the value
+		`(Password:[\s]*")(?:[^"\\]|\\.)*`,
 
 		// UI appConfig
 		"(subsonicToken:)[\\w]+(\\s)",
diff --git a/log/log_test.go b/log/log_test.go
index 82207c672..184ff57db 100644
--- a/log/log_test.go
+++ b/log/log_test.go
@@ -9,6 +9,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/kr/pretty"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/sirupsen/logrus"
@@ -94,7 +95,7 @@ var _ = Describe("Logger", func() {
 			SetLogSourceLine(true)
 			Error("A crash happened")
 			// NOTE: This assertion breaks if the line number above changes
-			Expect(hook.LastEntry().Data[" source"]).To(ContainSubstring("/log/log_test.go:95"))
+			Expect(hook.LastEntry().Data[" source"]).To(ContainSubstring("/log/log_test.go:96"))
 			Expect(hook.LastEntry().Message).To(Equal("A crash happened"))
 		})
 
@@ -291,5 +292,69 @@ var _ = Describe("Logger", func() {
 			Expect(got).ToNot(ContainSubstring("secret"))
 			Expect(got).To(ContainSubstring(`"User-Agent":["Finamp/1.0"]`))
 		})
+
+		// https://github.com/navidrome/navidrome/discussions/6232
+		DescribeTable("redacts config keys in the startup Configuration dump",
+			func(line, expected string) {
+				Expect(Redact(line)).To(Equal(expected))
+			},
+			Entry("unpadded ApiKey", `ApiKey:"0123456789abcdef0123456789abcdef"`, `ApiKey:"[REDACTED]"`),
+			Entry("unpadded Secret", `Secret:"fedcba9876543210fedcba9876543210"`, `Secret:"[REDACTED]"`),
+			Entry("padded ApiKey", `        ApiKey:                  "0123456789abcdef0123456789abcdef",`,
+				`        ApiKey:                  "[REDACTED]",`),
+			Entry("padded Secret", `        Secret:                  "fedcba9876543210fedcba9876543210",`,
+				`        Secret:                  "[REDACTED]",`),
+			Entry("unpadded Prometheus Password", `Password:"p@ss w0rd!"`, `Password:"[REDACTED]"`),
+			Entry("padded Prometheus Password", `        Password:    "p@ss w0rd!",`, `        Password:    "[REDACTED]",`),
+			Entry("Prometheus Password with escaped quotes", `        Password:    "a\"b\\\"c",`,
+				`        Password:    "[REDACTED]",`),
+		)
+
+		It("redacts secrets in a pretty-printed config struct", func() {
+			// Mirrors conf.lastfmOptions and conf.prometheusOptions (conf imports log, so it can't be
+			// used here). pretty only breaks a struct into padded lines when it is long enough, so
+			// keep all the fields.
+			type lastfmOptions struct {
+				Enabled                 bool
+				ApiKey                  string
+				Secret                  string
+				Language                string
+				ScrobbleFirstArtistOnly bool
+				Languages               []string
+			}
+			type prometheusOptions struct {
+				Enabled     bool
+				MetricsPath string
+				Password    string
+			}
+			type configOptions struct {
+				Address    string
+				LastFM     lastfmOptions
+				Prometheus prometheusOptions
+			}
+			cfg := configOptions{
+				Address: "0.0.0.0",
+				LastFM: lastfmOptions{ //nolint:gosec
+					Enabled:   true,
+					ApiKey:    "0123456789abcdef0123456789abcdef",
+					Secret:    "fedcba9876543210fedcba9876543210",
+					Language:  "en",
+					Languages: []string{"en"},
+				},
+				Prometheus: prometheusOptions{ //nolint:gosec
+					Enabled:     true,
+					MetricsPath: "/metrics",
+					Password:    `prom"pass-tail`,
+				},
+			}
+			dump := pretty.Sprintf("Configuration: %# v", cfg)
+			Expect(dump).To(MatchRegexp(`ApiKey:\s{2,}"`), "the dump must use the padded layout")
+
+			got := Redact(dump)
+			Expect(got).ToNot(ContainSubstring(cfg.LastFM.ApiKey))
+			Expect(got).ToNot(ContainSubstring(cfg.LastFM.Secret))
+			Expect(got).ToNot(ContainSubstring("pass-tail"))
+			Expect(got).To(ContainSubstring(`"en"`))
+		})
 	})
 })

From ce484083bf070662e3b976daeca156fd7822c332 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 27 Sep 2026 14:18:24 -0400
Subject: [PATCH 189/200] fix(server): exit with an error code when the server
 fails to start (#6236)

When a startup step failed (for example, the port was already in use), runNavidrome only logged the error and returned. In service mode, service.Run() kept waiting for a stop signal, so the process stayed up serving nothing and the service manager never restarted it. A plain run exited with code 0.

runNavidrome now returns the error, unless its context was cancelled by a normal shutdown. Both the plain run and the service goroutine exit with code 1 on that error. The systemd unit no longer lists 1, 2 and 8 in SuccessExitStatus, so Restart=on-failure restarts the service on exit code 1.

Fixes #6235
---
 cmd/root.go | 20 ++++++++++++--------
 cmd/svc.go  |  9 +++++++--
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/cmd/root.go b/cmd/root.go
index edfcbe69c..089f09472 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -44,7 +44,9 @@ Complete documentation is available at https://www.navidrome.org/docs`,
 			preRun()
 		},
 		Run: func(cmd *cobra.Command, args []string) {
-			runNavidrome(cmd.Context())
+			if err := runNavidrome(cmd.Context()); err != nil {
+				log.Fatal("Fatal error in Navidrome. Aborting", err)
+			}
 		},
 		PostRun: func(cmd *cobra.Command, args []string) {
 			postRun()
@@ -76,12 +78,12 @@ func postRun() {
 }
 
 // runNavidrome is the main entry point for the Navidrome server. It starts all the services and blocks.
-// If any of the services returns an error, it will log it and exit. If the process receives a signal to exit,
-// it will cancel the context and exit gracefully.
-func runNavidrome(ctx context.Context) {
-	defer db.Init(ctx)()
+// If any of the services returns an error, it stops the others and returns that error, so the caller can
+// exit with a non-zero code. If the context is cancelled (a signal or a service stop), it returns nil.
+func runNavidrome(parentCtx context.Context) error {
+	defer db.Init(parentCtx)()
 
-	g, ctx := errgroup.WithContext(ctx)
+	g, ctx := errgroup.WithContext(parentCtx)
 	g.Go(startServer(ctx))
 	g.Go(startSignaller(ctx))
 	g.Go(startScheduler(ctx))
@@ -102,9 +104,11 @@ func runNavidrome(ctx context.Context) {
 		log.Warn(ctx, "Automatic Scanning is DISABLED")
 	}
 
-	if err := g.Wait(); err != nil {
-		log.Error("Fatal error in Navidrome. Aborting", err)
+	// Errors caused by a normal shutdown are not failures
+	if err := g.Wait(); err != nil && parentCtx.Err() == nil {
+		return err
 	}
+	return nil
 }
 
 // mainContext returns a context that is cancelled when the process receives a signal to exit.
diff --git a/cmd/svc.go b/cmd/svc.go
index c71f5ef2b..4e8b1fd85 100644
--- a/cmd/svc.go
+++ b/cmd/svc.go
@@ -53,8 +53,13 @@ func (p *svcControl) Start(service.Service) error {
 	p.done = make(chan struct{})
 	p.ctx, p.cancel = context.WithCancel(context.Background())
 	go func() {
-		runNavidrome(p.ctx)
+		err := runNavidrome(p.ctx)
 		close(p.done)
+		// service.Run() only returns when it gets a stop request, so exit here to let the
+		// service manager see the failure and restart the service
+		if err != nil {
+			log.Fatal("Fatal error in Navidrome. Aborting", err)
+		}
 	}()
 	return nil
 }
@@ -74,7 +79,7 @@ func (p *svcControl) Stop(service.Service) error {
 var svcInstance = sync.OnceValue(func() service.Service {
 	options := make(service.KeyValue)
 	options["Restart"] = "on-failure"
-	options["SuccessExitStatus"] = "1 2 8 SIGKILL"
+	options["SuccessExitStatus"] = "SIGKILL"
 	options["UserService"] = false
 	options["LogDirectory"] = conf.Server.DataFolder.String()
 	options["SystemdScript"] = systemdScript

From 4cdffd5633e05cbc29cfd71e34382bf25eae256a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sun, 27 Sep 2026 21:56:58 -0400
Subject: [PATCH 190/200] feat(subsonic): OpenSubsonic API key authentication
 (#6219)

* feat(persistence): store hashed API keys on players

* feat(core): refresh key-bound players without renaming them

Add Players.Touch, which records usage for a player already identified by
an API key without guessing its identity or overwriting its name. Register
also stops renaming players that have an API key.

Register no longer returns player save errors (or a stale FindMatch
ErrNotFound when the save is rate-limited); save failures are only logged,
and only the transcoding lookup error is returned, same as Touch.

* feat(subsonic): authenticate with OpenSubsonic API keys

Co-authored-by: amCap1712 <amCap1712@users.noreply.github.com>

* feat(subsonic): add tokenInfo and advertise apiKeyAuthentication

* feat(server): add endpoints to generate and revoke player API keys

* feat(ui): manage player API keys

Co-authored-by: amCap1712 <amCap1712@users.noreply.github.com>

* fix(subsonic): throttle API keys per key and IP

A stale key on one device exhausted the shared per-IP bucket and locked out
every valid key from the same IP. The limiter only stores a hash of the bucket
string, so the key is not retained. Also adds e2e coverage of API key auth
through the real repository, and clarifies the player resolution log message.

* fix(ui): keep the new API key dialog open until closed

The key is shown only once, so Escape and backdrop clicks no longer dismiss
it. Also clarifies when the key can be used as a password.

* refactor: simplify API key code paths

Share the player refresh tail between Register and Touch, fold the
ownership-filtered write tail into execOwned, parse the query once for
apiKey conflicts, derive HasAPIKey in the player mock, share the player
form inputs between create and edit, and pick the delete button by key
state instead of spreading conditional props.

* feat(players): set API keys through the player record

The key is a write-only apiKey field applied on save: required and owner-only on create, optional on edit, empty to revoke. Replaces the generate/revoke endpoints.

* fix(players): reject API keys already in use

Creating or editing a player with a key another player already has now returns a validation error instead of a 500, and a create that loses the race no longer leaves a keyless player behind. Ownership is checked before the key on create.

* feat(ui): edit player API keys as a form field

Replaces the show-once dialog, whose icon-less Close button was invisible on mobile. The key is generated in the browser, required and pre-filled on create.

* fix(ui): keep new player API keys out of the record cache

The json-server create response echoes the request body, and undoable edits merge the payload into the cache, so the key could reappear on the edit page. Strip it from the create result and save player edits pessimistically. Also fall back to a prompt when the clipboard write fails.

* fix(ui): polish player API key field

Set userId on the created player record so owner actions show immediately, and show a neutral no-key message to non-owners.

* refactor: simplify player API key create and field

Write the key hash in the create INSERT so the unique index settles
races, re-read the created player instead of hand-building the cached
record, reuse isWritable for the revoke check, and collapse the key
field's derived state and generate/regenerate buttons.

* fix(ui): let the API key field size like other inputs

fullWidth is now opt-in instead of forced.

* fix(ui): align the API key field with other player inputs

Apply react-admin's input className, move the actions (now including Copy) below the field, and use a monospace font so the whole key fits.

* fix(ui): redirect to the player list after create

Matches the other create pages.

* refactor(persistence): name the write-access rule for owned rows

Owned-row writes now say which row they target and who may write it: ownedRow(rowID, ownerOrAdmin|ownerOnly) builds the WHERE, updateOwnedRow applies it, and SetAPIKey uses ownerOnly instead of a hand-built user_id filter. updateOwned/deleteOwned keep their signatures.

* fix(players): apply an edit's key change and fields atomically

Update now runs SetAPIKey and the column update in one transaction. Also shares the key format check, drops FindByAPIKey's unneeded empty-key guard, and sets the context username only on the apiKey path.

* fix(subsonic): treat any credential param sent with apiKey as a conflict

The spec requires error 43 when u, p, t or s is present with apiKey, even with an empty value.

* refactor(subsonic): leave the player cookie code unchanged for key-bound requests

Return early instead of wrapping the cookie block, so the diff (and CodeQL's view of it) matches master.

* fix(subsonic): don't count key lookup errors as failed logins

A database error while checking a key sent as the password now surfaces as a server error instead of a bad password, so it no longer feeds the failed-login limiter.

* feat(players): use nds_ as the API key prefix

Part of a Navidrome secret prefix family (nd + a letter for the kind), alongside ndg_ for API v1 grants.

* feat(ui): make player API keys easier to find

Label the Settings menu entry "Players & API keys", add an API key
filter to the player list, show the key icon in the mobile list, and
add Brazilian Portuguese translations for the new player strings.

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

* feat(ui): always show the player API key filter

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

* fix(ui): hide the unset Last Seen date in the player list

Players created by hand have no last_seen yet, which showed as 12/31/1.

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

---------

Signed-off-by: Deluan <deluan@navidrome.org>
Co-authored-by: amCap1712 <amCap1712@users.noreply.github.com>
---
 consts/consts.go                              |   1 +
 core/players.go                               |  28 +-
 core/players_test.go                          |  37 +++
 ...20260924010054_add_player_api_key_hash.sql |   8 +
 model/player.go                               |   4 +
 persistence/player_repository.go              | 121 +++++++-
 persistence/player_repository_test.go         | 269 +++++++++++++++++-
 persistence/sql_base_repository.go            |  40 ++-
 persistence/sql_base_repository_test.go       |  20 ++
 resources/i18n/pt-br.json                     |  25 +-
 server/subsonic/api.go                        |   1 +
 server/subsonic/e2e/subsonic_apikey_test.go   |  54 ++++
 server/subsonic/middlewares.go                | 118 +++++++-
 server/subsonic/middlewares_test.go           | 162 +++++++++++
 server/subsonic/opensubsonic.go               |   1 +
 server/subsonic/opensubsonic_test.go          |  66 ++---
 .../Responses TokenInfo should match .JSON    |  10 +
 .../Responses TokenInfo should match .XML     |   3 +
 server/subsonic/responses/errors.go           |  38 +--
 server/subsonic/responses/responses.go        |   5 +
 server/subsonic/responses/responses_test.go   |  14 +
 server/subsonic/system.go                     |   8 +
 server/subsonic/system_test.go                |  23 ++
 tests/mock_data_store.go                      |   2 +-
 tests/mock_player_repo.go                     |  75 +++++
 ui/src/App.jsx                                |   2 +-
 ui/src/dataProvider/wrapperDataProvider.js    |   9 +
 .../dataProvider/wrapperDataProvider.test.js  |  15 +
 ui/src/i18n/en.json                           |  25 +-
 ui/src/layout/AppBar.jsx                      |   8 +-
 ui/src/layout/AppBar.test.jsx                 |  24 +-
 ui/src/player/ApiKeyInput.jsx                 | 107 +++++++
 ui/src/player/ApiKeyInput.test.jsx            | 172 +++++++++++
 ui/src/player/PlayerCreate.jsx                |  33 +++
 ui/src/player/PlayerCreate.test.jsx           |  47 +++
 ui/src/player/PlayerEdit.jsx                  |  55 ++--
 ui/src/player/PlayerEdit.test.jsx             |  25 ++
 ui/src/player/PlayerList.jsx                  |  17 +-
 ui/src/player/apiKey.js                       |  15 +
 ui/src/player/apiKey.test.js                  |  15 +
 ui/src/player/index.js                        |   2 +
 ui/src/player/playerInputs.jsx                |  34 +++
 42 files changed, 1610 insertions(+), 128 deletions(-)
 create mode 100644 db/migrations/20260924010054_add_player_api_key_hash.sql
 create mode 100644 server/subsonic/e2e/subsonic_apikey_test.go
 create mode 100644 server/subsonic/responses/.snapshots/Responses TokenInfo should match .JSON
 create mode 100644 server/subsonic/responses/.snapshots/Responses TokenInfo should match .XML
 create mode 100644 server/subsonic/system_test.go
 create mode 100644 tests/mock_player_repo.go
 create mode 100644 ui/src/player/ApiKeyInput.jsx
 create mode 100644 ui/src/player/ApiKeyInput.test.jsx
 create mode 100644 ui/src/player/PlayerCreate.jsx
 create mode 100644 ui/src/player/PlayerCreate.test.jsx
 create mode 100644 ui/src/player/PlayerEdit.test.jsx
 create mode 100644 ui/src/player/apiKey.js
 create mode 100644 ui/src/player/apiKey.test.js
 create mode 100644 ui/src/player/playerInputs.jsx

diff --git a/consts/consts.go b/consts/consts.go
index 7228299c6..9bdac9125 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -49,6 +49,7 @@ const (
 	DefaultEncryptionKey  = "just for obfuscation"
 	PasswordsEncryptedKey = "PasswordsEncryptedKey"
 	PasswordAutogenPrefix = "__NAVIDROME_AUTOGEN__" //nolint:gosec
+	APIKeyPrefix          = "nds_"
 
 	DevInitialUserName = "admin"
 	DevInitialName     = "Dev Admin"
diff --git a/core/players.go b/core/players.go
index e03d8caa2..6fe86fd70 100644
--- a/core/players.go
+++ b/core/players.go
@@ -17,6 +17,7 @@ import (
 type Players interface {
 	Get(ctx context.Context, playerId string) (*model.Player, error)
 	Register(ctx context.Context, id, client, userAgent, ip string) (*model.Player, *model.Transcoding, error)
+	Touch(ctx context.Context, plr model.Player, client, userAgent, ip string) (*model.Player, *model.Transcoding, error)
 }
 
 func NewPlayers(ds model.DataStore) Players {
@@ -33,7 +34,6 @@ type players struct {
 
 func (p *players) Register(ctx context.Context, playerID, client, userAgent, ip string) (*model.Player, *model.Transcoding, error) {
 	var plr *model.Player
-	var trc *model.Transcoding
 	var err error
 	user, _ := request.UserFrom(ctx)
 	if playerID != "" {
@@ -58,7 +58,21 @@ func (p *players) Register(ctx context.Context, playerID, client, userAgent, ip
 			log.Info(ctx, "Registering new player", "id", plr.ID, "client", client, "username", username, "type", userAgent)
 		}
 	}
-	plr.Name = fmt.Sprintf("%s [%s]", client, userAgent)
+	if !plr.HasAPIKey {
+		plr.Name = fmt.Sprintf("%s [%s]", client, userAgent)
+	}
+	return p.refresh(ctx, plr, userAgent, ip)
+}
+
+// Touch refreshes a player that the request already identified (by API key), without guessing or renaming it.
+func (p *players) Touch(ctx context.Context, plr model.Player, client, userAgent, ip string) (*model.Player, *model.Transcoding, error) {
+	if plr.Client == "" {
+		plr.Client = client
+	}
+	return p.refresh(ctx, &plr, userAgent, ip)
+}
+
+func (p *players) refresh(ctx context.Context, plr *model.Player, userAgent, ip string) (*model.Player, *model.Transcoding, error) {
 	plr.UserAgent = userAgent
 	plr.IP = ip
 	plr.LastSeen = time.Now()
@@ -66,14 +80,14 @@ func (p *players) Register(ctx context.Context, playerID, client, userAgent, ip
 		ctx, cancel := context.WithTimeout(ctx, time.Second)
 		defer cancel()
 
-		err = p.ds.Player().Put(ctx, plr)
-		if err != nil {
-			log.Warn(ctx, "Could not save player", "id", plr.ID, "client", client, "username", username, "type", userAgent, err)
+		if err := p.ds.Player().Put(ctx, plr); err != nil {
+			log.Warn(ctx, "Could not save player", "id", plr.ID, "client", plr.Client, "username", userName(ctx), "type", plr.UserAgent, err)
 		}
 	})
-	if plr.TranscodingId != "" {
-		trc, err = p.ds.Transcoding().Get(ctx, plr.TranscodingId)
+	if plr.TranscodingId == "" {
+		return plr, nil, nil
 	}
+	trc, err := p.ds.Transcoding().Get(ctx, plr.TranscodingId)
 	return plr, trc, err
 }
 
diff --git a/core/players_test.go b/core/players_test.go
index 302d63157..e452c52ba 100644
--- a/core/players_test.go
+++ b/core/players_test.go
@@ -114,6 +114,15 @@ var _ = Describe("Players", func() {
 			Expect(trc.ID).To(Equal("1"))
 		})
 
+		It("does not rename a player that has an API key", func() {
+			plr := &model.Player{ID: "123", Name: "My Phone", Client: "client", UserId: "userid", HasAPIKey: true}
+			repo.add(plr)
+			p, _, err := players.Register(ctx, "123", "client", "chrome", "1.2.3.4")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(p.ID).To(Equal("123"))
+			Expect(p.Name).To(Equal("My Phone"))
+		})
+
 		Context("bad username casing", func() {
 			ctx := log.NewContext(context.TODO())
 			ctx = request.WithUser(ctx, model.User{ID: "userid", UserName: "Johndoe"})
@@ -130,6 +139,34 @@ var _ = Describe("Players", func() {
 			})
 		})
 	})
+
+	Describe("Touch", func() {
+		It("records usage but keeps the name and client", func() {
+			plr := model.Player{ID: "123", Name: "My Phone", Client: "Symfonium", UserId: "userid", HasAPIKey: true}
+			p, trc, err := players.Touch(ctx, plr, "OtherClient", "android", "1.2.3.4")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(p.Name).To(Equal("My Phone"))
+			Expect(p.Client).To(Equal("Symfonium"))
+			Expect(p.UserAgent).To(Equal("android"))
+			Expect(p.IP).To(Equal("1.2.3.4"))
+			Expect(p.LastSeen).To(BeTemporally(">=", beforeRegister))
+			Expect(repo.lastSaved).To(Equal(p))
+			Expect(trc).To(BeNil())
+		})
+
+		It("fills in the client on first use", func() {
+			p, _, err := players.Touch(ctx, model.Player{ID: "123", Name: "Manual", UserId: "userid"}, "Symfonium", "android", "1.2.3.4")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(p.Client).To(Equal("Symfonium"))
+		})
+
+		It("returns the player's transcoding", func() {
+			p, trc, err := players.Touch(ctx, model.Player{ID: "123", UserId: "userid", TranscodingId: "1"}, "c", "ua", "1.2.3.4")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(p.ID).To(Equal("123"))
+			Expect(trc.ID).To(Equal("1"))
+		})
+	})
 })
 
 type mockPlayerRepository struct {
diff --git a/db/migrations/20260924010054_add_player_api_key_hash.sql b/db/migrations/20260924010054_add_player_api_key_hash.sql
new file mode 100644
index 000000000..bbc4cf4d9
--- /dev/null
+++ b/db/migrations/20260924010054_add_player_api_key_hash.sql
@@ -0,0 +1,8 @@
+-- +goose Up
+-- +goose StatementBegin
+alter table player add column api_key_hash varchar default null;
+create unique index if not exists player_api_key_hash on player(api_key_hash);
+-- +goose StatementEnd
+
+-- +goose Down
+SELECT 1;
diff --git a/model/player.go b/model/player.go
index 2e4484a10..c03058419 100644
--- a/model/player.go
+++ b/model/player.go
@@ -21,6 +21,8 @@ type Player struct {
 	MaxBitRate      int       `structs:"max_bit_rate" json:"maxBitRate"`
 	ReportRealPath  bool      `structs:"report_real_path" json:"reportRealPath"`
 	ScrobbleEnabled bool      `structs:"scrobble_enabled" json:"scrobbleEnabled"`
+	HasAPIKey       bool      `structs:"-" db:"has_api_key" json:"hasApiKey"`
+	APIKey          *string   `structs:"-" json:"apiKey,omitempty"`
 }
 
 type Players []Player
@@ -33,4 +35,6 @@ type PlayerRepository interface {
 	Put(ctx context.Context, p *Player) error
 	CountAll(ctx context.Context, options ...QueryOptions) (int64, error)
 	CountByClient(ctx context.Context, options ...QueryOptions) (map[string]int64, error)
+	FindByAPIKey(ctx context.Context, key string) (*Player, error)
+	SetAPIKey(ctx context.Context, playerID, key string) error
 }
diff --git a/persistence/player_repository.go b/persistence/player_repository.go
index e46a8d82d..ba5d26794 100644
--- a/persistence/player_repository.go
+++ b/persistence/player_repository.go
@@ -2,10 +2,16 @@ package persistence
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"regexp"
+	"strings"
 
 	. "github.com/Masterminds/squirrel"
 	"github.com/deluan/rest"
+	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/id"
 	"github.com/pocketbase/dbx"
 )
 
@@ -17,7 +23,8 @@ func NewPlayerRepository(db dbx.Builder) model.PlayerRepository {
 	r := &playerRepository{}
 	r.db = db
 	r.registerModel(&model.Player{}, map[string]filterFunc{
-		"name": containsFilter("player.name"),
+		"name":      containsFilter("player.name"),
+		"hasapikey": hasAPIKeyFilter,
 	})
 	r.setSortMappings(map[string]string{
 		"user_name": "username", //TODO rename all user_name and userName to username
@@ -25,6 +32,13 @@ func NewPlayerRepository(db dbx.Builder) model.PlayerRepository {
 	return r
 }
 
+func hasAPIKeyFilter(_ string, value any) Sqlizer {
+	if v, _ := value.(string); strings.EqualFold(v, "true") {
+		return NotEq{"player.api_key_hash": nil}
+	}
+	return Eq{"player.api_key_hash": nil}
+}
+
 func (r *playerRepository) Put(ctx context.Context, p *model.Player) error {
 	_, err := r.put(ctx, p.ID, p)
 	return err
@@ -32,7 +46,7 @@ func (r *playerRepository) Put(ctx context.Context, p *model.Player) error {
 
 func (r *playerRepository) selectPlayer(ctx context.Context, options ...model.QueryOptions) SelectBuilder {
 	return r.newSelect(ctx, options...).
-		Columns("player.*").
+		Columns("player.*", "player.api_key_hash is not null as has_api_key").
 		Join("user ON player.user_id = user.id").
 		Columns("user.user_name username")
 }
@@ -103,32 +117,115 @@ func (r *playerRepository) ReadAll(ctx context.Context, options ...rest.QueryOpt
 	return res, err
 }
 
-// isPermitted authorizes creating a new record, based on the owner declared in the request body.
-// This is only safe for inserts: there is no stored row yet, and a non-admin may only create a
-// player they own. Updates must not use this (the body owner is attacker-controlled); they go
-// through updateOwned, which authorizes against the persisted user_id in the WHERE clause.
-func (r *playerRepository) isPermitted(ctx context.Context, p *model.Player) bool {
-	u := loggedUser(ctx)
-	return u.IsAdmin || p.UserId == u.ID
+var apiKeyFormat = regexp.MustCompile(`^` + consts.APIKeyPrefix + `[0-9A-Za-z]{22}$`)
+
+func apiKeyValidationError(msg string) error {
+	return &rest.ValidationError{Errors: map[string]string{"apiKey": msg}}
+}
+
+func validateAPIKey(key string) error {
+	if !apiKeyFormat.MatchString(key) {
+		return apiKeyValidationError("resources.player.validation.apiKeyFormat")
+	}
+	return nil
 }
 
 func (r *playerRepository) Save(ctx context.Context, t *model.Player) (string, error) {
-	if !r.isPermitted(ctx, t) {
+	u := loggedUser(ctx)
+	if t.UserId == "" && u.ID != invalidUserId {
+		t.UserId = u.ID
+	}
+	if t.UserId != u.ID {
 		return "", rest.ErrPermissionDenied
 	}
-	return r.put(ctx, "", t) // Save only creates; edits go through the owner-scoped Update
+	// Hand-made players are only reachable through a key, so one is required
+	if t.APIKey == nil || *t.APIKey == "" {
+		return "", apiKeyValidationError("ra.validation.required")
+	}
+	if err := validateAPIKey(*t.APIKey); err != nil {
+		return "", err
+	}
+	values, err := toSQLArgs(t)
+	if err != nil {
+		return "", err
+	}
+	// Save only creates, so the key hash goes in the same INSERT and the unique index settles races
+	values["id"] = id.NewRandom()
+	values["api_key_hash"] = hashAPIKey(*t.APIKey)
+	_, err = r.executeSQL(ctx, Insert(r.tableName).SetMap(values))
+	if isUniqueViolation(err) {
+		return "", apiKeyValidationError("ra.validation.unique")
+	}
+	if err != nil {
+		return "", err
+	}
+	return values["id"].(string), nil
 }
 
 func (r *playerRepository) Update(ctx context.Context, id string, entity model.Player, cols ...string) error {
 	t := &entity
 	t.ID = id
-	return r.updateOwned(ctx, id, t, cols...)
+	if t.APIKey == nil {
+		return r.updateOwned(ctx, id, t, cols...)
+	}
+	// The key and the other columns are two writes; commit both or neither
+	return r.inTx(func(tx *playerRepository) error {
+		if err := tx.SetAPIKey(ctx, id, *t.APIKey); err != nil {
+			return err
+		}
+		return tx.updateOwned(ctx, id, t, cols...)
+	})
+}
+
+func (r *playerRepository) inTx(block func(tx *playerRepository) error) error {
+	conn, ok := r.db.(*dbx.DB)
+	if !ok {
+		return block(r) // already inside a transaction
+	}
+	return conn.Transactional(func(tx *dbx.Tx) error {
+		return block(NewPlayerRepository(tx).(*playerRepository))
+	})
 }
 
 func (r *playerRepository) Delete(ctx context.Context, ids ...string) error {
 	return r.deleteOwnedAll(ctx, ids...)
 }
 
+// Keys are long random strings, not user-chosen passwords, so a fast unsalted hash is enough and keeps lookups indexed.
+func hashAPIKey(key string) string {
+	sum := sha256.Sum256([]byte(key))
+	return hex.EncodeToString(sum[:])
+}
+
+func (r *playerRepository) FindByAPIKey(ctx context.Context, key string) (*model.Player, error) {
+	sel := r.selectPlayer(ctx).Where(Eq{"player.api_key_hash": hashAPIKey(key)})
+	var res model.Player
+	if err := r.queryOne(ctx, sel, &res); err != nil {
+		return nil, err
+	}
+	return &res, nil
+}
+
+// SetAPIKey stores the key's hash, or revokes it when key is empty. Setting is owner-only, even for
+// admins, so nobody can mint a login for someone else.
+func (r *playerRepository) SetAPIKey(ctx context.Context, playerID, key string) error {
+	if key == "" {
+		return r.updateOwnedRow(ctx, playerID, ownerOrAdmin, map[string]any{"api_key_hash": nil})
+	}
+	if err := validateAPIKey(key); err != nil {
+		return err
+	}
+	err := r.updateOwnedRow(ctx, playerID, ownerOnly, map[string]any{"api_key_hash": hashAPIKey(key)})
+	if isUniqueViolation(err) {
+		return apiKeyValidationError("ra.validation.unique")
+	}
+	return err
+}
+
+func isUniqueViolation(err error) bool {
+	return err != nil && strings.Contains(err.Error(), "UNIQUE constraint failed")
+}
+
 var _ model.PlayerRepository = (*playerRepository)(nil)
 var _ rest.Repository[model.Player] = (*playerRepository)(nil)
 var _ rest.Persistable[model.Player] = (*playerRepository)(nil)
diff --git a/persistence/player_repository_test.go b/persistence/player_repository_test.go
index f12f3e74e..69afa9556 100644
--- a/persistence/player_repository_test.go
+++ b/persistence/player_repository_test.go
@@ -2,6 +2,7 @@ package persistence
 
 import (
 	"context"
+	"errors"
 
 	"github.com/deluan/rest"
 	"github.com/navidrome/navidrome/log"
@@ -12,6 +13,14 @@ import (
 	"github.com/pocketbase/dbx"
 )
 
+const testAPIKey = "nds_0123456789abcdefghijkl"
+
+func expectAPIKeyError(err error, msg string) {
+	var verr *rest.ValidationError
+	ExpectWithOffset(1, errors.As(err, &verr)).To(BeTrue())
+	ExpectWithOffset(1, verr.Errors).To(HaveKeyWithValue("apiKey", msg))
+}
+
 var _ = Describe("PlayerRepository", func() {
 	var adminRepo *playerRepository
 	var database *dbx.DB
@@ -178,11 +187,12 @@ var _ = Describe("PlayerRepository", func() {
 				clone := player
 				clone.ID = ""
 				clone.IP = "192.168.1.1"
+				clone.APIKey = new(testAPIKey)
 				id, err := repo.Save(repoCtx, &clone)
 
 				if clone.UserId == "" {
 					Expect(err).To(HaveOccurred())
-				} else if !admin && player.Username == adminPlayer1.Username {
+				} else if player.UserId != userPlayer.UserId {
 					Expect(err).To(Equal(rest.ErrPermissionDenied))
 					clone.UserId = ""
 				} else {
@@ -202,12 +212,13 @@ var _ = Describe("PlayerRepository", func() {
 				} else {
 					Expect(count).To(Equal(baseCount + 1))
 					Expect(err).To(BeNil())
+					clone.APIKey = nil
+					clone.HasAPIKey = true
 					Expect(*newItem).To(Equal(clone))
 				}
 			},
 				Entry("same user", userPlayer),
 				Entry("other item", otherPlayer),
-				Entry("fake item", model.Player{}),
 			)
 		})
 
@@ -251,6 +262,259 @@ var _ = Describe("PlayerRepository", func() {
 		Entry("regular context", false, model.Players{regularPlayer}, regularPlayer, adminPlayer1),
 	)
 
+	Describe("API keys", func() {
+		const key = testAPIKey
+		const otherKey = "nds_ABCDEFGHIJKLMNOPQRSTUV"
+		var ownerCtx, otherCtx context.Context
+
+		BeforeEach(func() {
+			ownerCtx = request.WithUser(log.NewContext(GinkgoT().Context()), regularUser)
+			otherCtx = request.WithUser(log.NewContext(GinkgoT().Context()), thirdUser)
+		})
+
+		storedHash := func(id string) string {
+			var row struct {
+				Hash string `db:"api_key_hash"`
+			}
+			Expect(database.NewQuery("select coalesce(api_key_hash, '') as api_key_hash from player where id = {:id}").
+				Bind(dbx.Params{"id": id}).One(&row)).To(Succeed())
+			return row.Hash
+		}
+
+		Describe("SetAPIKey", func() {
+			It("stores only the hash and finds the player by the key", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+
+				Expect(storedHash(regularPlayer.ID)).To(Equal(hashAPIKey(key)))
+				plr, err := adminRepo.FindByAPIKey(ctx, key)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(plr.ID).To(Equal(regularPlayer.ID))
+				Expect(plr.HasAPIKey).To(BeTrue())
+				Expect(plr.APIKey).To(BeNil())
+			})
+
+			It("replaces the previous key", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, otherKey)).To(Succeed())
+
+				_, err := adminRepo.FindByAPIKey(ctx, key)
+				Expect(err).To(MatchError(model.ErrNotFound))
+				_, err = adminRepo.FindByAPIKey(ctx, otherKey)
+				Expect(err).ToNot(HaveOccurred())
+			})
+
+			DescribeTable("rejects malformed keys",
+				func(bad string) {
+					err := adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, bad)
+					expectAPIKeyError(err, "resources.player.validation.apiKeyFormat")
+					Expect(storedHash(regularPlayer.ID)).To(BeEmpty())
+				},
+				Entry("no prefix", "0123456789abcdefghijklmn"),
+				Entry("too short", "nds_short"),
+				Entry("too long", key+"x"),
+				Entry("bad chars", "nds_0123456789abcdefghij-!"),
+			)
+
+			It("revokes with an empty key, by the owner or an admin", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, "")).To(Succeed())
+				Expect(storedHash(regularPlayer.ID)).To(BeEmpty())
+
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+				Expect(adminRepo.SetAPIKey(ctx, regularPlayer.ID, "")).To(Succeed())
+				Expect(storedHash(regularPlayer.ID)).To(BeEmpty())
+			})
+
+			It("accepts revoking a player that has no key", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, "")).To(Succeed())
+			})
+
+			It("does not let an admin set a key on another user's player", func() {
+				Expect(adminRepo.SetAPIKey(ctx, regularPlayer.ID, key)).To(MatchError(rest.ErrPermissionDenied))
+				Expect(storedHash(regularPlayer.ID)).To(BeEmpty())
+			})
+
+			It("does not let another user set or revoke", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+				Expect(adminRepo.SetAPIKey(otherCtx, regularPlayer.ID, otherKey)).To(MatchError(rest.ErrPermissionDenied))
+				Expect(adminRepo.SetAPIKey(otherCtx, regularPlayer.ID, "")).To(MatchError(rest.ErrPermissionDenied))
+				Expect(storedHash(regularPlayer.ID)).To(Equal(hashAPIKey(key)))
+			})
+
+			It("returns not found for a missing player", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, "missing", key)).To(MatchError(rest.ErrNotFound))
+				Expect(adminRepo.SetAPIKey(ownerCtx, "missing", "")).To(MatchError(rest.ErrNotFound))
+			})
+
+			It("does not find unknown or empty keys", func() {
+				_, err := adminRepo.FindByAPIKey(ctx, otherKey)
+				Expect(err).To(MatchError(model.ErrNotFound))
+				_, err = adminRepo.FindByAPIKey(ctx, "")
+				Expect(err).To(MatchError(model.ErrNotFound))
+			})
+
+			It("drops the key with the player", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+				Expect(adminRepo.Delete(ownerCtx, regularPlayer.ID)).To(Succeed())
+				_, err := adminRepo.FindByAPIKey(ctx, key)
+				Expect(err).To(MatchError(model.ErrNotFound))
+			})
+		})
+
+		Describe("hasApiKey filter", func() {
+			BeforeEach(func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+			})
+
+			filtered := func(value string) []string {
+				res, err := adminRepo.ReadAll(ctx, rest.QueryOptions{Filters: map[string]any{"hasApiKey": value}})
+				Expect(err).ToNot(HaveOccurred())
+				var ids []string
+				for _, p := range res {
+					ids = append(ids, p.ID)
+				}
+				return ids
+			}
+
+			It("lists only players with a key", func() {
+				Expect(filtered("true")).To(ConsistOf(regularPlayer.ID))
+				count, err := adminRepo.Count(ctx, rest.QueryOptions{Filters: map[string]any{"hasApiKey": "true"}})
+				Expect(err).ToNot(HaveOccurred())
+				Expect(count).To(Equal(int64(1)))
+			})
+
+			It("lists only players without a key", func() {
+				Expect(filtered("false")).To(ConsistOf(adminPlayer1.ID, adminPlayer2.ID))
+			})
+		})
+
+		Describe("Save (create)", func() {
+			It("creates the player with the key, owned by the logged-in user", func() {
+				id, err := adminRepo.Save(ownerCtx, &model.Player{Name: "Manual player", APIKey: new(key)})
+				Expect(err).ToNot(HaveOccurred())
+
+				plr, err := adminRepo.FindByAPIKey(ctx, key)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(plr.ID).To(Equal(id))
+				Expect(plr.UserId).To(Equal(regularUser.ID))
+			})
+
+			It("requires a key", func() {
+				count, _ := adminRepo.CountAll(ctx)
+				_, err := adminRepo.Save(ownerCtx, &model.Player{Name: "No key"})
+				expectAPIKeyError(err, "ra.validation.required")
+
+				_, err = adminRepo.Save(ownerCtx, &model.Player{Name: "Empty key", APIKey: new("")})
+				expectAPIKeyError(err, "ra.validation.required")
+				Expect(adminRepo.CountAll(ctx)).To(Equal(count))
+			})
+
+			It("rejects a malformed key without creating the player", func() {
+				count, _ := adminRepo.CountAll(ctx)
+				_, err := adminRepo.Save(ownerCtx, &model.Player{Name: "Bad", APIKey: new("nds_bad")})
+				expectAPIKeyError(err, "resources.player.validation.apiKeyFormat")
+				Expect(adminRepo.CountAll(ctx)).To(Equal(count))
+			})
+
+			It("does not let an admin create a keyed player for another user", func() {
+				count, _ := adminRepo.CountAll(ctx)
+				_, err := adminRepo.Save(ctx, &model.Player{Name: "For someone", UserId: regularUser.ID, APIKey: new(key)})
+				Expect(err).To(MatchError(rest.ErrPermissionDenied))
+				_, err = adminRepo.Save(ctx, &model.Player{Name: "For someone", UserId: regularUser.ID})
+				Expect(err).To(MatchError(rest.ErrPermissionDenied))
+				Expect(adminRepo.CountAll(ctx)).To(Equal(count))
+			})
+
+			It("rejects a key already used by another player without creating the player", func() {
+				Expect(adminRepo.SetAPIKey(ctx, adminPlayer1.ID, key)).To(Succeed())
+				count, _ := adminRepo.CountAll(ctx)
+				_, err := adminRepo.Save(ownerCtx, &model.Player{Name: "Duplicate", APIKey: new(key)})
+				expectAPIKeyError(err, "ra.validation.unique")
+				Expect(adminRepo.CountAll(ctx)).To(Equal(count))
+			})
+		})
+
+		Describe("Update (edit)", func() {
+			It("rolls back the key change when the rest of the edit fails", func() {
+				_, err := database.NewQuery(`create trigger fail_player_rename before update of name on player
+					when new.name = 'boom' begin select raise(abort, 'boom'); end`).Execute()
+				Expect(err).ToNot(HaveOccurred())
+				DeferCleanup(func() {
+					_, _ = database.NewQuery("drop trigger if exists fail_player_rename").Execute()
+				})
+
+				plr := regularPlayer
+				plr.Name = "boom"
+				plr.APIKey = new(key)
+				Expect(adminRepo.Update(ownerCtx, plr.ID, plr, "name", "apiKey")).ToNot(Succeed())
+				Expect(storedHash(regularPlayer.ID)).To(BeEmpty())
+			})
+
+			It("keeps the key when apiKey is absent (a normal edit)", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+
+				plr := regularPlayer
+				plr.Name = "Renamed"
+				Expect(adminRepo.Update(ownerCtx, plr.ID, plr, "name", "hasApiKey")).To(Succeed())
+				Expect(adminRepo.Update(ownerCtx, plr.ID, plr)).To(Succeed())
+
+				found, err := adminRepo.FindByAPIKey(ctx, key)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(found.Name).To(Equal("Renamed"))
+			})
+
+			It("sets a new key when apiKey has a value", func() {
+				plr := regularPlayer
+				plr.APIKey = new(key)
+				Expect(adminRepo.Update(ownerCtx, plr.ID, plr, "name", "apiKey")).To(Succeed())
+				Expect(storedHash(regularPlayer.ID)).To(Equal(hashAPIKey(key)))
+			})
+
+			It("revokes the key when apiKey is empty", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+				plr := regularPlayer
+				plr.APIKey = new("")
+				Expect(adminRepo.Update(ownerCtx, plr.ID, plr, "apiKey")).To(Succeed())
+				Expect(storedHash(regularPlayer.ID)).To(BeEmpty())
+			})
+
+			It("lets an admin edit another user's keyed player without touching the key", func() {
+				Expect(adminRepo.SetAPIKey(ownerCtx, regularPlayer.ID, key)).To(Succeed())
+				plr := regularPlayer
+				plr.MaxBitRate = 192
+				Expect(adminRepo.Update(ctx, plr.ID, plr, "maxBitRate", "hasApiKey")).To(Succeed())
+				Expect(storedHash(regularPlayer.ID)).To(Equal(hashAPIKey(key)))
+			})
+
+			It("refuses an admin setting a key on another user's player and leaves other columns alone", func() {
+				plr := regularPlayer
+				plr.Name = "Hijacked"
+				plr.APIKey = new(key)
+				Expect(adminRepo.Update(ctx, plr.ID, plr, "name", "apiKey")).To(MatchError(rest.ErrPermissionDenied))
+
+				got, err := adminRepo.Get(ctx, regularPlayer.ID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(got.Name).To(Equal(regularPlayer.Name))
+				Expect(storedHash(regularPlayer.ID)).To(BeEmpty())
+			})
+
+			It("refuses a key already used by another player and leaves other columns alone", func() {
+				Expect(adminRepo.SetAPIKey(ctx, adminPlayer1.ID, key)).To(Succeed())
+				plr := regularPlayer
+				plr.Name = "Renamed"
+				plr.APIKey = new(key)
+				err := adminRepo.Update(ownerCtx, plr.ID, plr, "name", "apiKey")
+				expectAPIKeyError(err, "ra.validation.unique")
+
+				got, err := adminRepo.Get(ctx, regularPlayer.ID)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(got.Name).To(Equal(regularPlayer.Name))
+				Expect(storedHash(regularPlayer.ID)).To(BeEmpty())
+				Expect(storedHash(adminPlayer1.ID)).To(Equal(hashAPIKey(key)))
+			})
+		})
+	})
+
 	Describe("Ownership enforcement (cross-tenant write protection)", func() {
 		var regularRepo *playerRepository
 		var regularCtx context.Context
@@ -287,6 +551,7 @@ var _ = Describe("PlayerRepository", func() {
 				Name:           "HIJACKED",
 				UserId:         regularUser.ID,
 				ReportRealPath: true,
+				APIKey:         new(testAPIKey),
 			}
 
 			id, err := regularRepo.Save(regularCtx, &spoofed)
diff --git a/persistence/sql_base_repository.go b/persistence/sql_base_repository.go
index be88156d8..03cc6a01b 100644
--- a/persistence/sql_base_repository.go
+++ b/persistence/sql_base_repository.go
@@ -85,6 +85,22 @@ func (r sqlRepository) addRestriction(ctx context.Context, sql ...Sqlizer) Sqliz
 	return s
 }
 
+// writeAccess says who may change a row in a table with a user_id column.
+type writeAccess int
+
+const (
+	ownerOrAdmin writeAccess = iota // admins may write any row
+	ownerOnly                       // even admins may only write their own rows
+)
+
+// ownedRow matches the row rowID only if the logged-in user may write it under access.
+func (r sqlRepository) ownedRow(ctx context.Context, rowID string, access writeAccess) Sqlizer {
+	if access == ownerOnly {
+		return And{Eq{"id": rowID}, Eq{"user_id": loggedUser(ctx).ID}}
+	}
+	return r.addRestriction(ctx, Eq{"id": rowID})
+}
+
 func (r *sqlRepository) registerModel(instance any, filters map[string]filterFunc) {
 	if r.tableName == "" {
 		r.tableName = strings.TrimPrefix(reflect.TypeOf(instance).String(), "*model.")
@@ -494,15 +510,12 @@ func (r sqlRepository) updateOwned(ctx context.Context, id string, m any, colsTo
 	}
 	updateValues := filterUpdateValues(values, id, colsToUpdate...)
 	delete(updateValues, "user_id") // ownership is immutable on update
-	update := Update(r.tableName).Where(r.addRestriction(ctx, Eq{"id": id})).SetMap(updateValues)
-	count, err := r.executeSQL(ctx, update)
-	if err != nil {
-		return err
-	}
-	if count == 0 {
-		return r.classifyOwnedWriteMiss(ctx, id)
-	}
-	return nil
+	return r.updateOwnedRow(ctx, id, ownerOrAdmin, updateValues)
+}
+
+// updateOwnedRow sets values on the row rowID if the logged-in user may write it under access.
+func (r sqlRepository) updateOwnedRow(ctx context.Context, rowID string, access writeAccess, values map[string]any) error {
+	return r.runRowWrite(ctx, rowID, Update(r.tableName).SetMap(values).Where(r.ownedRow(ctx, rowID, access)))
 }
 
 // deleteOwned performs an atomic, ownership-restricted delete of the row identified by id, for
@@ -511,12 +524,17 @@ func (r sqlRepository) updateOwned(ctx context.Context, id string, m any, colsTo
 // does not match and is left untouched. The failure path mirrors updateOwned (see
 // classifyOwnedWriteMiss), so there is no TOCTOU on the delete.
 func (r sqlRepository) deleteOwned(ctx context.Context, id string) error {
-	count, err := r.executeSQL(ctx, Delete(r.tableName).Where(r.addRestriction(ctx, Eq{"id": id})))
+	return r.runRowWrite(ctx, id, Delete(r.tableName).Where(r.ownedRow(ctx, id, ownerOrAdmin)))
+}
+
+// runRowWrite executes q, a write already filtered by ownedRow(rowID, …), and classifies a miss.
+func (r sqlRepository) runRowWrite(ctx context.Context, rowID string, q Sqlizer) error {
+	count, err := r.executeSQL(ctx, q)
 	if err != nil {
 		return err
 	}
 	if count == 0 {
-		return r.classifyOwnedWriteMiss(ctx, id)
+		return r.classifyOwnedWriteMiss(ctx, rowID)
 	}
 	return nil
 }
diff --git a/persistence/sql_base_repository_test.go b/persistence/sql_base_repository_test.go
index 33a8140f8..4b42e7f1d 100644
--- a/persistence/sql_base_repository_test.go
+++ b/persistence/sql_base_repository_test.go
@@ -19,6 +19,26 @@ var _ = Describe("sqlRepository", func() {
 		r.tableName = "table"
 	})
 
+	Describe("ownedRow", func() {
+		DescribeTable("matches the row, limited to what the logged-in user may write",
+			func(user model.User, access writeAccess, expectedSQL string, expectedArgs ...any) {
+				userCtx := request.WithUser(GinkgoT().Context(), user)
+				sql, args, err := r.ownedRow(userCtx, "row-1", access).ToSql()
+				Expect(err).ToNot(HaveOccurred())
+				Expect(sql).To(Equal(expectedSQL))
+				Expect(args).To(Equal(expectedArgs))
+			},
+			Entry("admin, ownerOrAdmin: any row", model.User{ID: "admin", IsAdmin: true}, ownerOrAdmin,
+				"(id = ?)", "row-1"),
+			Entry("regular, ownerOrAdmin: own rows", model.User{ID: "user"}, ownerOrAdmin,
+				"(id = ? AND user_id = ?)", "row-1", "user"),
+			Entry("admin, ownerOnly: own rows", model.User{ID: "admin", IsAdmin: true}, ownerOnly,
+				"(id = ? AND user_id = ?)", "row-1", "admin"),
+			Entry("regular, ownerOnly: own rows", model.User{ID: "user"}, ownerOnly,
+				"(id = ? AND user_id = ?)", "row-1", "user"),
+		)
+	})
+
 	Describe("applyOptions", func() {
 		var sq squirrel.SelectBuilder
 		BeforeEach(func() {
diff --git a/resources/i18n/pt-br.json b/resources/i18n/pt-br.json
index 6fcde56ca..f0d8a0e06 100644
--- a/resources/i18n/pt-br.json
+++ b/resources/i18n/pt-br.json
@@ -182,6 +182,7 @@
     },
     "player": {
       "name": "Tocador |||| Tocadores",
+      "menuName": "Tocadores e chaves de API",
       "fields": {
         "name": "Nome",
         "transcodingId": "Conversão",
@@ -190,7 +191,29 @@
         "userName": "Usuário",
         "lastSeen": "Últ. acesso",
         "reportRealPath": "Use paths reais",
-        "scrobbleEnabled": "Enviar scrobbles para serviços externos"
+        "scrobbleEnabled": "Enviar scrobbles para serviços externos",
+        "hasApiKey": "Chave de API"
+      },
+      "actions": {
+        "generateApiKey": "Gerar chave de API",
+        "regenerateApiKey": "Gerar nova",
+        "revokeApiKey": "Revogar",
+        "copyApiKey": "Copiar"
+      },
+      "message": {
+        "apiKeyActive": "Este tocador tem uma chave de API. Use-a no seu app como chave de API, ou como senha se o app não usar autenticação por token.",
+        "apiKeyNone": "Sem chave de API. Gere uma para conectar um app a este tocador.",
+        "apiKeyNoneOther": "Sem chave de API.",
+        "apiKeyPending": "Copie esta chave agora. Ela será salva quando você clicar em Salvar e não será exibida novamente.",
+        "apiKeyRevokePending": "A chave de API será removida quando você salvar.",
+        "deleteWithKeyTitle": "Excluir tocador",
+        "deleteWithKeyContent": "Este tocador tem uma chave de API. Os apps que a usam vão parar de funcionar."
+      },
+      "notifications": {
+        "apiKeyCopied": "Chave de API copiada para o clipboard"
+      },
+      "validation": {
+        "apiKeyFormat": "Formato de chave de API inválido"
       }
     },
     "transcoding": {
diff --git a/server/subsonic/api.go b/server/subsonic/api.go
index deedc46c7..fe724741c 100644
--- a/server/subsonic/api.go
+++ b/server/subsonic/api.go
@@ -107,6 +107,7 @@ func (api *Router) routes() http.Handler {
 			r.Use(getPlayer(api.players))
 			h(r, "ping", api.Ping)
 			h(r, "getLicense", api.GetLicense)
+			h(r, "tokenInfo", api.TokenInfo)
 		})
 		r.Group(func(r chi.Router) {
 			r.Use(getPlayer(api.players))
diff --git a/server/subsonic/e2e/subsonic_apikey_test.go b/server/subsonic/e2e/subsonic_apikey_test.go
new file mode 100644
index 000000000..bb263c15d
--- /dev/null
+++ b/server/subsonic/e2e/subsonic_apikey_test.go
@@ -0,0 +1,54 @@
+package e2e
+
+import (
+	"net/http/httptest"
+	"net/url"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/server/subsonic/responses"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("API key authentication", func() {
+	var key string
+
+	BeforeEach(func() {
+		setupTestDB()
+		userCtx := request.WithUser(ctx, regularUser)
+		player := &model.Player{ID: "apikey-player", Name: "Phone", UserId: regularUser.ID, Client: "test-client"}
+		Expect(ds.Player().Put(userCtx, player)).To(Succeed())
+		key = "nds_0123456789abcdefghijkl"
+		Expect(ds.Player().SetAPIKey(userCtx, player.ID, key)).To(Succeed())
+	})
+
+	doKeyReq := func(endpoint, apiKey string) *responses.Subsonic {
+		q := url.Values{"apiKey": {apiKey}, "v": {"1.16.1"}, "c": {"test-client"}, "f": {"json"}}
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, httptest.NewRequest("GET", "/"+endpoint+"?"+q.Encode(), nil))
+		return parseJSONResponse(w)
+	}
+
+	It("authenticates ping with only the key", func() {
+		resp := doKeyReq("ping", key)
+
+		Expect(resp.Status).To(Equal(responses.StatusOK))
+	})
+
+	It("reports the key owner in tokenInfo", func() {
+		resp := doKeyReq("tokenInfo", key)
+
+		Expect(resp.Status).To(Equal(responses.StatusOK))
+		Expect(resp.TokenInfo).ToNot(BeNil())
+		Expect(resp.TokenInfo.Username).To(Equal(regularUser.UserName))
+	})
+
+	It("rejects an unknown key with error 44", func() {
+		resp := doKeyReq("ping", "nds_unknown")
+
+		Expect(resp.Status).To(Equal(responses.StatusFailed))
+		Expect(resp.Error).ToNot(BeNil())
+		Expect(resp.Error.Code).To(Equal(int32(44)))
+	})
+})
diff --git a/server/subsonic/middlewares.go b/server/subsonic/middlewares.go
index 6617661a9..fdb4af28d 100644
--- a/server/subsonic/middlewares.go
+++ b/server/subsonic/middlewares.go
@@ -65,14 +65,15 @@ func checkRequiredParameters(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		var requiredParameters []string
 
+		p := req.Params(r)
 		username, _ := fromInternalOrProxyAuth(r)
-		if username != "" {
+		apiKey, _ := p.String("apiKey")
+		if username != "" || apiKey != "" {
 			requiredParameters = []string{"v", "c"}
 		} else {
 			requiredParameters = []string{"u", "v", "c"}
 		}
 
-		p := req.Params(r)
 		for _, param := range requiredParameters {
 			if _, err := p.String(param); err != nil {
 				log.Warn(r, err)
@@ -104,10 +105,14 @@ func authenticate(ds model.DataStore) func(next http.Handler) http.Handler {
 			ctx := r.Context()
 
 			var usr *model.User
+			var keyPlayer *model.Player
 			var err error
 
+			p := req.Params(r)
+			apiKey, _ := p.String("apiKey")
 			username, isInternalAuth := fromInternalOrProxyAuth(r)
-			if username != "" {
+			switch {
+			case username != "":
 				authType := If(isInternalAuth, "internal", "reverse-proxy")
 				usr, err = ds.User().FindByUsername(ctx, username)
 				if errors.Is(err, context.Canceled) {
@@ -119,8 +124,16 @@ func authenticate(ds model.DataStore) func(next http.Handler) http.Handler {
 				} else if err != nil {
 					log.Error(ctx, "API: Error authenticating username", "auth", authType, "username", username, "remoteAddr", r.RemoteAddr, err)
 				}
-			} else {
-				p := req.Params(r)
+			case apiKey != "":
+				usr, keyPlayer, err = authenticateAPIKey(ctx, ds, limiter, r, apiKey)
+				if err != nil {
+					if ctx.Err() == nil {
+						sendError(w, r, err)
+					}
+					return
+				}
+				ctx = request.WithUsername(ctx, usr.UserName)
+			default:
 				username, _ := p.String("u")
 				pass, _ := p.String("p")
 				token, _ := p.String("t")
@@ -142,6 +155,9 @@ func authenticate(ds model.DataStore) func(next http.Handler) http.Handler {
 				usr, err = ds.User().FindByUsernameWithPassword(ctx, username)
 				if err == nil {
 					err = validateCredentials(usr, pass, token, salt, jwt)
+					if errors.Is(err, model.ErrInvalidAuth) && pass != "" && jwt == "" {
+						keyPlayer, err = playerFromPasswordKey(ctx, ds, usr, pass)
+					}
 				}
 				invalidLogin := errors.Is(err, model.ErrNotFound) || errors.Is(err, model.ErrInvalidAuth)
 				slot.release(invalidLogin)
@@ -162,11 +178,77 @@ func authenticate(ds model.DataStore) func(next http.Handler) http.Handler {
 			}
 
 			ctx = request.WithUser(ctx, *usr)
+			if keyPlayer != nil {
+				ctx = request.WithPlayer(ctx, *keyPlayer)
+			}
 			next.ServeHTTP(w, r.WithContext(ctx))
 		})
 	}
 }
 
+var apiKeyConflicts = []string{"u", "p", "t", "s", "jwt"}
+
+func authenticateAPIKey(ctx context.Context, ds model.DataStore, limiter *authLimiter, r *http.Request, key string) (*model.User, *model.Player, error) {
+	query := r.URL.Query()
+	for _, param := range apiKeyConflicts {
+		if query.Has(param) {
+			log.Warn(ctx, "API: apiKey sent with other credentials", "auth", "apikey", "param", param, "remoteAddr", r.RemoteAddr)
+			return nil, nil, newError(responses.ErrorMultipleAuthMechanismsProvided)
+		}
+	}
+
+	// Per key, so a stale key on one device cannot lock out valid keys sharing the IP
+	slot, allowed := limiter.acquire(ctx, "apikey\x00"+server.ClientIP(r)+"\x00"+key)
+	if !allowed {
+		if err := ctx.Err(); err != nil {
+			return nil, nil, err
+		}
+		log.Warn(ctx, "API: Too many failed API key attempts", "auth", "apikey", "remoteAddr", r.RemoteAddr)
+		return nil, nil, newError(responses.ErrorInvalidAPIKey)
+	}
+
+	player, err := ds.Player().FindByAPIKey(ctx, key)
+	var usr *model.User
+	if err == nil {
+		usr, err = ds.User().Get(ctx, player.UserId)
+	}
+	slot.release(errors.Is(err, model.ErrNotFound))
+	switch {
+	case errors.Is(err, context.Canceled):
+		return nil, nil, err
+	case errors.Is(err, model.ErrNotFound):
+		log.Warn(ctx, "API: Invalid API key", "auth", "apikey", "remoteAddr", r.RemoteAddr)
+		return nil, nil, newError(responses.ErrorInvalidAPIKey)
+	case err != nil:
+		log.Error(ctx, "API: Error authenticating API key", "auth", "apikey", "remoteAddr", r.RemoteAddr, err)
+		return nil, nil, newError(responses.ErrorAuthenticationFail)
+	}
+	return usr, player, nil
+}
+
+// playerFromPasswordKey lets clients that only have a password field log in with an API key.
+// It returns ErrInvalidAuth when pass is not a key of usr, so only real failures skip the limiter count.
+func playerFromPasswordKey(ctx context.Context, ds model.DataStore, usr *model.User, pass string) (*model.Player, error) {
+	key := decodePassword(pass)
+	if !strings.HasPrefix(key, consts.APIKeyPrefix) {
+		return nil, model.ErrInvalidAuth
+	}
+	plr, err := ds.Player().FindByAPIKey(ctx, key)
+	if errors.Is(err, model.ErrNotFound) || (err == nil && plr.UserId != usr.ID) {
+		return nil, model.ErrInvalidAuth
+	}
+	return plr, err
+}
+
+func decodePassword(pass string) string {
+	if strings.HasPrefix(pass, "enc:") {
+		if dec, err := hex.DecodeString(pass[4:]); err == nil {
+			return string(dec)
+		}
+	}
+	return pass
+}
+
 func adminOnly(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		loggedUser, ok := request.UserFrom(r.Context())
@@ -194,12 +276,7 @@ func validateCredentials(user *model.User, pass, token, salt, jwt string) error
 			claims.Subject == user.UserName &&
 			auth.CheckClaims(claims, *user, auth.AudienceSubsonic) == nil
 	case pass != "":
-		if strings.HasPrefix(pass, "enc:") {
-			if dec, err := hex.DecodeString(pass[4:]); err == nil {
-				pass = string(dec)
-			}
-		}
-		valid = pass == user.Password
+		valid = decodePassword(pass) == user.Password
 	case token != "":
 		t := fmt.Sprintf("%x", md5.Sum([]byte(user.Password+salt)))
 		valid = t == token
@@ -217,12 +294,20 @@ func getPlayer(players core.Players) func(next http.Handler) http.Handler {
 			ctx := r.Context()
 			userName, _ := request.UsernameFrom(ctx)
 			client, _ := request.ClientFrom(ctx)
-			playerId := playerIDFromCookie(r, userName)
 			ip, _, _ := net.SplitHostPort(r.RemoteAddr)
 			userAgent := canonicalUserAgent(r)
-			player, trc, err := players.Register(ctx, playerId, client, userAgent, ip)
+
+			var player *model.Player
+			var trc *model.Transcoding
+			var err error
+			keyPlayer, boundByKey := request.PlayerFrom(ctx)
+			if boundByKey {
+				player, trc, err = players.Touch(ctx, keyPlayer, client, userAgent, ip)
+			} else {
+				player, trc, err = players.Register(ctx, playerIDFromCookie(r, userName), client, userAgent, ip)
+			}
 			if err != nil {
-				log.Error(ctx, "Could not register player", "username", userName, "client", client, err)
+				log.Error(ctx, "Could not resolve player", "username", userName, "client", client, err)
 			} else {
 				ctx = request.WithPlayer(ctx, *player)
 				if trc != nil {
@@ -230,6 +315,11 @@ func getPlayer(players core.Players) func(next http.Handler) http.Handler {
 				}
 				r = r.WithContext(ctx)
 
+				// A key already identifies the player, so the cookie would only add a second, weaker signal
+				if boundByKey {
+					next.ServeHTTP(w, r)
+					return
+				}
 				cookie := &http.Cookie{ //nolint:gosec // Secure omitted: Navidrome may run over plain HTTP
 					Name:     playerIDCookieName(userName),
 					Value:    player.ID,
diff --git a/server/subsonic/middlewares_test.go b/server/subsonic/middlewares_test.go
index 0879ee540..b3ad972b7 100644
--- a/server/subsonic/middlewares_test.go
+++ b/server/subsonic/middlewares_test.go
@@ -3,6 +3,7 @@ package subsonic
 import (
 	"context"
 	"crypto/md5"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"net/http"
@@ -119,6 +120,14 @@ var _ = Describe("Middlewares", func() {
 			Expect(next.called).To(BeTrue())
 		})
 
+		It("does not require u when apiKey is present", func() {
+			r := newGetRequest("apiKey=nds_abc", "v=1.15", "c=test")
+			cp := checkRequiredParameters(next)
+			cp.ServeHTTP(w, r)
+
+			Expect(next.called).To(BeTrue())
+		})
+
 		It("fails when user is missing", func() {
 			r := newGetRequest("v=1.15", "c=test")
 			cp := checkRequiredParameters(next)
@@ -311,6 +320,101 @@ var _ = Describe("Middlewares", func() {
 			})
 		})
 
+		When("using API key authentication", func() {
+			var key string
+			serve := func(params ...string) {
+				authenticate(ds)(next).ServeHTTP(w, newGetRequest(params...))
+			}
+
+			BeforeEach(func() {
+				usr, err := ds.User().FindByUsername(ctx, "admin")
+				Expect(err).ToNot(HaveOccurred())
+				Expect(ds.Player().Put(ctx, &model.Player{ID: "player-1", Name: "My Phone", UserId: usr.ID, Client: "Symfonium"})).To(Succeed())
+				key = "nds_0123456789abcdefghijkl"
+				Expect(ds.Player().SetAPIKey(ctx, "player-1", key)).To(Succeed())
+			})
+
+			It("authenticates the owner and binds the key's player", func() {
+				serve("apiKey=" + key)
+
+				Expect(next.called).To(BeTrue())
+				user, _ := request.UserFrom(next.req.Context())
+				Expect(user.UserName).To(Equal("admin"))
+				username, _ := request.UsernameFrom(next.req.Context())
+				Expect(username).To(Equal("admin"))
+				player, ok := request.PlayerFrom(next.req.Context())
+				Expect(ok).To(BeTrue())
+				Expect(player.ID).To(Equal("player-1"))
+			})
+
+			It("accepts the key in a POST form body", func() {
+				r := newPostRequest("", "apiKey="+key)
+				cp := postFormToQueryParams(authenticate(ds)(next))
+				cp.ServeHTTP(w, r)
+
+				Expect(next.called).To(BeTrue())
+				player, _ := request.PlayerFrom(next.req.Context())
+				Expect(player.ID).To(Equal("player-1"))
+			})
+
+			It("rejects an unknown key with error 44", func() {
+				serve("apiKey=nds_unknown")
+
+				Expect(w.Body.String()).To(ContainSubstring(`code="44"`))
+				Expect(next.called).To(BeFalse())
+			})
+
+			DescribeTable("rejects apiKey mixed with other credentials with error 43",
+				func(extra string) {
+					serve("apiKey="+key, extra)
+
+					Expect(w.Body.String()).To(ContainSubstring(`code="43"`))
+					Expect(next.called).To(BeFalse())
+				},
+				Entry("u", "u=admin"),
+				Entry("p", "p=wordpass"),
+				Entry("t", "t=abc"),
+				Entry("s", "s=abc"),
+				Entry("jwt", "jwt=abc"),
+				Entry("empty u", "u="),
+				Entry("empty p", "p="),
+			)
+
+			Context("key sent as the password", func() {
+				It("authenticates and binds the key's player", func() {
+					serve("u=admin", "p="+key)
+
+					Expect(next.called).To(BeTrue())
+					player, ok := request.PlayerFrom(next.req.Context())
+					Expect(ok).To(BeTrue())
+					Expect(player.ID).To(Equal("player-1"))
+				})
+
+				It("accepts the hex-encoded form", func() {
+					serve("u=admin", "p=enc:"+hex.EncodeToString([]byte(key)))
+
+					Expect(next.called).To(BeTrue())
+				})
+
+				It("still accepts a real password that starts with the key prefix", func() {
+					Expect(ds.User().Put(ctx, &model.User{UserName: "prefixed", NewPassword: "nds_secret"})).To(Succeed())
+					serve("u=prefixed", "p=nds_secret")
+
+					Expect(next.called).To(BeTrue())
+					_, ok := request.PlayerFrom(next.req.Context())
+					Expect(ok).To(BeFalse())
+				})
+
+				It("rejects another user's key with error 40", func() {
+					Expect(ds.User().Put(ctx, &model.User{UserName: "other", NewPassword: "pw"})).To(Succeed())
+					serve("u=other", "p="+key)
+
+					Expect(w.Body.String()).To(ContainSubstring(`code="40"`))
+					Expect(next.called).To(BeFalse())
+				})
+			})
+		})
+
 		When("failed attempts reach AuthRequestLimit", func() {
 			var cp http.Handler
 
@@ -376,6 +480,21 @@ var _ = Describe("Middlewares", func() {
 				Expect(next.called).To(BeTrue())
 			})
 
+			It("does not count server errors when a key is sent as the password", func() {
+				usr, _ := ds.User().FindByUsername(ctx, "admin")
+				playerRepo := ds.Player().(*tests.MockPlayerRepo)
+				Expect(playerRepo.Put(ctx, &model.Player{ID: "player-1", UserId: usr.ID})).To(Succeed())
+				key := "nds_0123456789abcdefghijkl"
+				Expect(playerRepo.SetAPIKey(ctx, "player-1", key)).To(Succeed())
+
+				playerRepo.Error = errors.New("db down")
+				failTimes(5, "u=admin", "p="+key)
+				playerRepo.Error = nil
+
+				serve(newGetRequest("u=admin", "p="+key))
+				Expect(next.called).To(BeTrue())
+			})
+
 			It("does not block other usernames from the same IP", func() {
 				_ = ds.User().Put(ctx, &model.User{UserName: "other", NewPassword: "otherpass"})
 				failTimes(3, "u=admin", "p=WRONG")
@@ -405,6 +524,25 @@ var _ = Describe("Middlewares", func() {
 				Expect(next.called).To(BeTrue())
 			})
 
+			It("throttles a repeated bad key without locking out valid keys from the same IP", func() {
+				usr, _ := ds.User().FindByUsername(ctx, "admin")
+				playerRepo := ds.Player().(*tests.MockPlayerRepo)
+				Expect(playerRepo.Put(ctx, &model.Player{ID: "player-1", UserId: usr.ID})).To(Succeed())
+				key := "nds_0123456789abcdefghijkl"
+				Expect(playerRepo.SetAPIKey(ctx, "player-1", key)).To(Succeed())
+
+				for range 3 {
+					Expect(serve(newGetRequest("apiKey=nds_bad")).Body.String()).To(ContainSubstring(`code="44"`))
+				}
+				playerRepo.APIKeys["nds_bad"] = "player-1"
+				rec := serve(newGetRequest("apiKey=nds_bad"))
+				Expect(next.called).To(BeFalse())
+				Expect(rec.Body.String()).To(ContainSubstring(`code="44"`))
+
+				serve(newGetRequest("apiKey=" + key))
+				Expect(next.called).To(BeTrue())
+			})
+
 			It("is disabled when AuthRequestLimit is 0", func() {
 				conf.Server.AuthRequestLimit = 0
 				cp = authenticate(ds)(next)
@@ -532,6 +670,24 @@ var _ = Describe("Middlewares", func() {
 			Expect(cookieStr).To(BeEmpty())
 		})
 
+		Context("player bound by an API key", func() {
+			BeforeEach(func() {
+				r = r.WithContext(request.WithPlayer(r.Context(), model.Player{ID: "keyed"}))
+				gp := getPlayer(mockedPlayers)(next)
+				gp.ServeHTTP(w, r)
+			})
+
+			It("uses the key's player", func() {
+				Expect(mockedPlayers.touched).To(BeTrue())
+				player, _ := request.PlayerFrom(next.req.Context())
+				Expect(player.ID).To(Equal("keyed"))
+			})
+
+			It("does not set the player cookie", func() {
+				Expect(w.Header().Get("Set-Cookie")).To(BeEmpty())
+			})
+		})
+
 		Context("PlayerId specified in Cookies", func() {
 			BeforeEach(func() {
 				cookie := &http.Cookie{
@@ -712,6 +868,12 @@ func (mh *mockHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 type mockPlayers struct {
 	core.Players
 	transcoding *model.Transcoding
+	touched     bool
+}
+
+func (mp *mockPlayers) Touch(_ context.Context, plr model.Player, _, _, _ string) (*model.Player, *model.Transcoding, error) {
+	mp.touched = true
+	return &plr, mp.transcoding, nil
 }
 
 func (mp *mockPlayers) Get(ctx context.Context, playerId string) (*model.Player, error) {
diff --git a/server/subsonic/opensubsonic.go b/server/subsonic/opensubsonic.go
index 2b2a31bf3..21c407039 100644
--- a/server/subsonic/opensubsonic.go
+++ b/server/subsonic/opensubsonic.go
@@ -16,6 +16,7 @@ func (api *Router) GetOpenSubsonicExtensions(_ *http.Request) (*responses.Subson
 		{Name: "transcoding", Versions: []int32{1}},
 		{Name: "playbackReport", Versions: []int32{1}},
 		{Name: "topSongsByArtistId", Versions: []int32{1}},
+		{Name: "apiKeyAuthentication", Versions: []int32{1}},
 	}
 	if api.sonic != nil && api.sonic.HasProvider() {
 		extensions = append(extensions, responses.OpenSubsonicExtension{
diff --git a/server/subsonic/opensubsonic_test.go b/server/subsonic/opensubsonic_test.go
index 2615a652d..8740c9971 100644
--- a/server/subsonic/opensubsonic_test.go
+++ b/server/subsonic/opensubsonic_test.go
@@ -44,44 +44,13 @@ var _ = Describe("GetOpenSubsonicExtensions", func() {
 			router = subsonic.New(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		})
 
-		It("should return the base 6 OpenSubsonicExtensions without sonicSimilarity", func() {
+		It("should return the base 8 OpenSubsonicExtensions without sonicSimilarity", func() {
 			router.ServeHTTP(w, r)
 
 			// Make sure the endpoint is public, by not passing any authentication
 			Expect(w.Code).To(Equal(http.StatusOK))
 			Expect(w.Header().Get("Content-Type")).To(Equal("application/json"))
 
-			var response responses.JsonWrapper
-			err := json.Unmarshal(w.Body.Bytes(), &response)
-			Expect(err).NotTo(HaveOccurred())
-			Expect(*response.Subsonic.OpenSubsonicExtensions).To(SatisfyAll(
-				HaveLen(7),
-				ContainElement(responses.OpenSubsonicExtension{Name: "transcodeOffset", Versions: []int32{1}}),
-				ContainElement(responses.OpenSubsonicExtension{Name: "formPost", Versions: []int32{1}}),
-				ContainElement(responses.OpenSubsonicExtension{Name: "songLyrics", Versions: []int32{1, 2}}),
-				ContainElement(responses.OpenSubsonicExtension{Name: "indexBasedQueue", Versions: []int32{1}}),
-				ContainElement(responses.OpenSubsonicExtension{Name: "transcoding", Versions: []int32{1}}),
-				ContainElement(responses.OpenSubsonicExtension{Name: "playbackReport", Versions: []int32{1}}),
-				ContainElement(responses.OpenSubsonicExtension{Name: "topSongsByArtistId", Versions: []int32{1}}),
-			))
-			Expect(*response.Subsonic.OpenSubsonicExtensions).NotTo(
-				ContainElement(responses.OpenSubsonicExtension{Name: "sonicSimilarity", Versions: []int32{1}}),
-			)
-		})
-	})
-
-	Context("with sonic similarity plugin", func() {
-		BeforeEach(func() {
-			sonicService := sonicsvc.New(nil, &mockSonicPluginLoader{names: []string{"test-plugin"}}, nil)
-			router = subsonic.New(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, sonicService)
-		})
-
-		It("should return 7 extensions including sonicSimilarity", func() {
-			router.ServeHTTP(w, r)
-
-			Expect(w.Code).To(Equal(http.StatusOK))
-			Expect(w.Header().Get("Content-Type")).To(Equal("application/json"))
-
 			var response responses.JsonWrapper
 			err := json.Unmarshal(w.Body.Bytes(), &response)
 			Expect(err).NotTo(HaveOccurred())
@@ -93,8 +62,41 @@ var _ = Describe("GetOpenSubsonicExtensions", func() {
 				ContainElement(responses.OpenSubsonicExtension{Name: "indexBasedQueue", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "transcoding", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "playbackReport", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "topSongsByArtistId", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "apiKeyAuthentication", Versions: []int32{1}}),
+			))
+			Expect(*response.Subsonic.OpenSubsonicExtensions).NotTo(
+				ContainElement(responses.OpenSubsonicExtension{Name: "sonicSimilarity", Versions: []int32{1}}),
+			)
+		})
+	})
+
+	Context("with sonic similarity plugin", func() {
+		BeforeEach(func() {
+			sonicService := sonicsvc.New(nil, &mockSonicPluginLoader{names: []string{"test-plugin"}}, nil)
+			router = subsonic.New(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, sonicService)
+		})
+
+		It("should return 9 extensions including sonicSimilarity", func() {
+			router.ServeHTTP(w, r)
+
+			Expect(w.Code).To(Equal(http.StatusOK))
+			Expect(w.Header().Get("Content-Type")).To(Equal("application/json"))
+
+			var response responses.JsonWrapper
+			err := json.Unmarshal(w.Body.Bytes(), &response)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(*response.Subsonic.OpenSubsonicExtensions).To(SatisfyAll(
+				HaveLen(9),
+				ContainElement(responses.OpenSubsonicExtension{Name: "transcodeOffset", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "formPost", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "songLyrics", Versions: []int32{1, 2}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "indexBasedQueue", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "transcoding", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "playbackReport", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "sonicSimilarity", Versions: []int32{1}}),
 				ContainElement(responses.OpenSubsonicExtension{Name: "topSongsByArtistId", Versions: []int32{1}}),
+				ContainElement(responses.OpenSubsonicExtension{Name: "apiKeyAuthentication", Versions: []int32{1}}),
 			))
 		})
 	})
diff --git a/server/subsonic/responses/.snapshots/Responses TokenInfo should match .JSON b/server/subsonic/responses/.snapshots/Responses TokenInfo should match .JSON
new file mode 100644
index 000000000..f2e251f49
--- /dev/null
+++ b/server/subsonic/responses/.snapshots/Responses TokenInfo should match .JSON	
@@ -0,0 +1,10 @@
+{
+  "status": "ok",
+  "version": "1.16.1",
+  "type": "navidrome",
+  "serverVersion": "v0.55.0",
+  "openSubsonic": true,
+  "tokenInfo": {
+    "username": "deluan"
+  }
+}
diff --git a/server/subsonic/responses/.snapshots/Responses TokenInfo should match .XML b/server/subsonic/responses/.snapshots/Responses TokenInfo should match .XML
new file mode 100644
index 000000000..7ea786bb9
--- /dev/null
+++ b/server/subsonic/responses/.snapshots/Responses TokenInfo should match .XML	
@@ -0,0 +1,3 @@
+<subsonic-response xmlns="http://subsonic.org/restapi" status="ok" version="1.16.1" type="navidrome" serverVersion="v0.55.0" openSubsonic="true">
+  <tokenInfo username="deluan"></tokenInfo>
+</subsonic-response>
diff --git a/server/subsonic/responses/errors.go b/server/subsonic/responses/errors.go
index 42e5427b3..9c9dd10f6 100644
--- a/server/subsonic/responses/errors.go
+++ b/server/subsonic/responses/errors.go
@@ -1,25 +1,29 @@
 package responses
 
 const (
-	ErrorGeneric            int32 = 0
-	ErrorMissingParameter   int32 = 10
-	ErrorClientTooOld       int32 = 20
-	ErrorServerTooOld       int32 = 30
-	ErrorAuthenticationFail int32 = 40
-	ErrorAuthorizationFail  int32 = 50
-	ErrorTrialExpired       int32 = 60
-	ErrorDataNotFound       int32 = 70
+	ErrorGeneric                        int32 = 0
+	ErrorMissingParameter               int32 = 10
+	ErrorClientTooOld                   int32 = 20
+	ErrorServerTooOld                   int32 = 30
+	ErrorAuthenticationFail             int32 = 40
+	ErrorMultipleAuthMechanismsProvided int32 = 43
+	ErrorInvalidAPIKey                  int32 = 44
+	ErrorAuthorizationFail              int32 = 50
+	ErrorTrialExpired                   int32 = 60
+	ErrorDataNotFound                   int32 = 70
 )
 
-var errors = map[int32]string{
-	ErrorGeneric:            "A generic error",
-	ErrorMissingParameter:   "Required parameter is missing",
-	ErrorClientTooOld:       "Incompatible Subsonic REST protocol version. Client must upgrade",
-	ErrorServerTooOld:       "Incompatible Subsonic REST protocol version. Server must upgrade",
-	ErrorAuthenticationFail: "Wrong username or password",
-	ErrorAuthorizationFail:  "User is not authorized for the given operation",
-	ErrorTrialExpired:       "The trial period for the Subsonic server is over. Please upgrade to Subsonic Premium. Visit subsonic.org for details",
-	ErrorDataNotFound:       "The requested data was not found",
+var errors = map[int32]string{ //nolint:gosec // G101 false positive: error messages, not credentials
+	ErrorGeneric:                        "A generic error",
+	ErrorMissingParameter:               "Required parameter is missing",
+	ErrorClientTooOld:                   "Incompatible Subsonic REST protocol version. Client must upgrade",
+	ErrorServerTooOld:                   "Incompatible Subsonic REST protocol version. Server must upgrade",
+	ErrorAuthenticationFail:             "Wrong username or password",
+	ErrorMultipleAuthMechanismsProvided: "Multiple conflicting authentication mechanisms provided",
+	ErrorInvalidAPIKey:                  "Invalid API key",
+	ErrorAuthorizationFail:              "User is not authorized for the given operation",
+	ErrorTrialExpired:                   "The trial period for the Subsonic server is over. Please upgrade to Subsonic Premium. Visit subsonic.org for details",
+	ErrorDataNotFound:                   "The requested data was not found",
 }
 
 func ErrorMsg(code int32) string {
diff --git a/server/subsonic/responses/responses.go b/server/subsonic/responses/responses.go
index 252eee4c6..51d0020b2 100644
--- a/server/subsonic/responses/responses.go
+++ b/server/subsonic/responses/responses.go
@@ -63,6 +63,7 @@ type Subsonic struct {
 	PlayQueueByIndex       *PlayQueueByIndex       `xml:"playQueueByIndex,omitempty" json:"playQueueByIndex,omitempty"`
 	TranscodeDecision      *TranscodeDecision      `xml:"transcodeDecision,omitempty"       json:"transcodeDecision,omitempty"`
 	SonicMatches           *Array[SonicMatch]      `xml:"sonicMatch,omitempty"              json:"sonicMatch,omitempty"`
+	TokenInfo              *TokenInfo              `xml:"tokenInfo,omitempty"               json:"tokenInfo,omitempty"`
 }
 
 const (
@@ -596,6 +597,10 @@ type OpenSubsonicExtension struct {
 
 type OpenSubsonicExtensions []OpenSubsonicExtension
 
+type TokenInfo struct {
+	Username string `xml:"username,attr" json:"username"`
+}
+
 type ItemGenre struct {
 	Name string `xml:"name,attr" json:"name"`
 }
diff --git a/server/subsonic/responses/responses_test.go b/server/subsonic/responses/responses_test.go
index 586e46b63..027ac11d5 100644
--- a/server/subsonic/responses/responses_test.go
+++ b/server/subsonic/responses/responses_test.go
@@ -1015,6 +1015,20 @@ var _ = Describe("Responses", func() {
 		})
 	})
 
+	Describe("TokenInfo", func() {
+		BeforeEach(func() {
+			response.OpenSubsonic = true
+			response.TokenInfo = &TokenInfo{Username: "deluan"}
+		})
+
+		It("should match .XML", func() {
+			Expect(xml.MarshalIndent(response, "", "  ")).To(MatchSnapshot())
+		})
+		It("should match .JSON", func() {
+			Expect(json.MarshalIndent(response, "", "  ")).To(MatchSnapshot())
+		})
+	})
+
 	Describe("InternetRadioStations", func() {
 		BeforeEach(func() {
 			response.InternetRadioStations = &InternetRadioStations{}
diff --git a/server/subsonic/system.go b/server/subsonic/system.go
index e14099942..4a59e7898 100644
--- a/server/subsonic/system.go
+++ b/server/subsonic/system.go
@@ -3,6 +3,7 @@ package subsonic
 import (
 	"net/http"
 
+	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/subsonic/responses"
 )
 
@@ -15,3 +16,10 @@ func (api *Router) GetLicense(_ *http.Request) (*responses.Subsonic, error) {
 	response.License = &responses.License{Valid: true}
 	return response, nil
 }
+
+func (api *Router) TokenInfo(r *http.Request) (*responses.Subsonic, error) {
+	user, _ := request.UserFrom(r.Context())
+	response := newResponse()
+	response.TokenInfo = &responses.TokenInfo{Username: user.UserName}
+	return response, nil
+}
diff --git a/server/subsonic/system_test.go b/server/subsonic/system_test.go
new file mode 100644
index 000000000..a8c85238e
--- /dev/null
+++ b/server/subsonic/system_test.go
@@ -0,0 +1,23 @@
+package subsonic
+
+import (
+	"net/http/httptest"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/request"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("TokenInfo", func() {
+	It("returns the authenticated username", func() {
+		api := &Router{}
+		r := httptest.NewRequest("GET", "/tokenInfo", nil)
+		r = r.WithContext(request.WithUser(r.Context(), model.User{UserName: "deluan"}))
+
+		resp, err := api.TokenInfo(r)
+
+		Expect(err).ToNot(HaveOccurred())
+		Expect(resp.TokenInfo.Username).To(Equal("deluan"))
+	})
+})
diff --git a/tests/mock_data_store.go b/tests/mock_data_store.go
index db798eece..a5e4126cf 100644
--- a/tests/mock_data_store.go
+++ b/tests/mock_data_store.go
@@ -228,7 +228,7 @@ func (db *MockDataStore) Player() model.PlayerRepository {
 	if db.RealDS != nil {
 		return db.RealDS.Player()
 	}
-	db.MockedPlayer = struct{ model.PlayerRepository }{}
+	db.MockedPlayer = CreateMockPlayerRepo()
 	return db.MockedPlayer
 }
 
diff --git a/tests/mock_player_repo.go b/tests/mock_player_repo.go
new file mode 100644
index 000000000..56835f0cc
--- /dev/null
+++ b/tests/mock_player_repo.go
@@ -0,0 +1,75 @@
+package tests
+
+import (
+	"context"
+	"maps"
+	"slices"
+
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/id"
+)
+
+func CreateMockPlayerRepo() *MockPlayerRepo {
+	return &MockPlayerRepo{Data: map[string]*model.Player{}, APIKeys: map[string]string{}}
+}
+
+// MockPlayerRepo keeps API keys in plaintext (key -> player ID); hashing belongs to the real repository.
+type MockPlayerRepo struct {
+	model.PlayerRepository
+	Error   error
+	Data    map[string]*model.Player
+	APIKeys map[string]string
+}
+
+func (m *MockPlayerRepo) Get(_ context.Context, id string) (*model.Player, error) {
+	if m.Error != nil {
+		return nil, m.Error
+	}
+	p, ok := m.Data[id]
+	if !ok {
+		return nil, model.ErrNotFound
+	}
+	cp := *p
+	cp.HasAPIKey = slices.Contains(slices.Collect(maps.Values(m.APIKeys)), id)
+	return &cp, nil
+}
+
+func (m *MockPlayerRepo) Put(_ context.Context, p *model.Player) error {
+	if m.Error != nil {
+		return m.Error
+	}
+	if p.ID == "" {
+		p.ID = id.NewRandom()
+	}
+	cp := *p
+	m.Data[p.ID] = &cp
+	return nil
+}
+
+func (m *MockPlayerRepo) FindByAPIKey(ctx context.Context, key string) (*model.Player, error) {
+	if m.Error != nil {
+		return nil, m.Error
+	}
+	if playerID, ok := m.APIKeys[key]; ok {
+		return m.Get(ctx, playerID)
+	}
+	return nil, model.ErrNotFound
+}
+
+func (m *MockPlayerRepo) SetAPIKey(_ context.Context, playerID, key string) error {
+	if m.Error != nil {
+		return m.Error
+	}
+	if _, ok := m.Data[playerID]; !ok {
+		return model.ErrNotFound
+	}
+	m.removeKeys(playerID)
+	if key != "" {
+		m.APIKeys[key] = playerID
+	}
+	return nil
+}
+
+func (m *MockPlayerRepo) removeKeys(playerID string) {
+	maps.DeleteFunc(m.APIKeys, func(_ string, v string) bool { return v == playerID })
+}
diff --git a/ui/src/App.jsx b/ui/src/App.jsx
index d10aa5a33..4de369394 100644
--- a/ui/src/App.jsx
+++ b/ui/src/App.jsx
@@ -141,7 +141,7 @@ const Admin = (props) => {
         <Resource
           name="player"
           {...player}
-          options={{ subMenu: 'settings' }}
+          options={{ subMenu: 'settings', label: 'resources.player.menuName' }}
         />,
         permissions === 'admin' ? (
           <Resource
diff --git a/ui/src/dataProvider/wrapperDataProvider.js b/ui/src/dataProvider/wrapperDataProvider.js
index f0e44ce1d..7de20bcce 100644
--- a/ui/src/dataProvider/wrapperDataProvider.js
+++ b/ui/src/dataProvider/wrapperDataProvider.js
@@ -148,6 +148,12 @@ const updateUser = async (params) => {
   return userResponse
 }
 
+// ra-data-json-server merges the request body into the result; re-read so the plaintext key is never cached
+const createPlayer = async (resource, params) => {
+  const { data } = await dataProvider.create(resource, params)
+  return dataProvider.getOne(resource, { id: data.id })
+}
+
 const wrapperDataProvider = {
   ...dataProvider,
   getList: (resource, params) => {
@@ -194,6 +200,9 @@ const wrapperDataProvider = {
       return createUser(params)
     }
     const [r, p] = mapResource(resource, params)
+    if (resource === 'player') {
+      return createPlayer(r, p)
+    }
     return dataProvider.create(r, p)
   },
   delete: (resource, params) => {
diff --git a/ui/src/dataProvider/wrapperDataProvider.test.js b/ui/src/dataProvider/wrapperDataProvider.test.js
index 4225a5a54..1c33aad5d 100644
--- a/ui/src/dataProvider/wrapperDataProvider.test.js
+++ b/ui/src/dataProvider/wrapperDataProvider.test.js
@@ -88,6 +88,21 @@ describe('wrapperDataProvider', () => {
     })
   })
 
+  describe('create player', () => {
+    it('returns the server record, never the plaintext API key', async () => {
+      const data = { name: 'Phone', apiKey: 'nds_0123456789abcdefghijkl' }
+      const saved = { id: 'p1', name: 'Phone', hasApiKey: true, userId: 'u1' }
+      mockProvider.create.mockResolvedValue({ data: { ...data, id: 'p1' } })
+      mockProvider.getOne.mockResolvedValue({ data: saved })
+
+      const result = await wrapperDataProvider.create('player', { data })
+
+      expect(mockProvider.create).toHaveBeenCalledWith('player', { data })
+      expect(mockProvider.getOne).toHaveBeenCalledWith('player', { id: 'p1' })
+      expect(result.data).toEqual(saved)
+    })
+  })
+
   describe('refreshMetadata', () => {
     it('posts to the album metadata refresh endpoint', () => {
       mockHttpClient.mockResolvedValue({ json: {} })
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index f5af05b7b..851b47ee3 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -182,6 +182,7 @@
     },
     "player": {
       "name": "Player |||| Players",
+      "menuName": "Players & API keys",
       "fields": {
         "name": "Name",
         "transcodingId": "Transcoding",
@@ -190,7 +191,29 @@
         "userName": "Username",
         "lastSeen": "Last Seen At",
         "reportRealPath": "Report Real Path",
-        "scrobbleEnabled": "Send Scrobbles to external services"
+        "scrobbleEnabled": "Send Scrobbles to external services",
+        "hasApiKey": "API Key"
+      },
+      "actions": {
+        "generateApiKey": "Generate API key",
+        "regenerateApiKey": "Regenerate",
+        "revokeApiKey": "Revoke",
+        "copyApiKey": "Copy"
+      },
+      "message": {
+        "apiKeyActive": "This player has an API key. Use it in your app as the API key, or as the password if the app does not use token authentication.",
+        "apiKeyNone": "No API key. Generate one to connect an app to this player.",
+        "apiKeyNoneOther": "No API key.",
+        "apiKeyPending": "Copy this key now. It is saved when you click Save and will not be shown again.",
+        "apiKeyRevokePending": "The API key will be removed when you save.",
+        "deleteWithKeyTitle": "Delete player",
+        "deleteWithKeyContent": "This player has an API key. Apps using it will stop working."
+      },
+      "notifications": {
+        "apiKeyCopied": "API key copied to clipboard"
+      },
+      "validation": {
+        "apiKeyFormat": "Invalid API key format"
       }
     },
     "transcoding": {
diff --git a/ui/src/layout/AppBar.jsx b/ui/src/layout/AppBar.jsx
index 7de111e67..460d33bb9 100644
--- a/ui/src/layout/AppBar.jsx
+++ b/ui/src/layout/AppBar.jsx
@@ -102,9 +102,11 @@ const CustomUserMenu = ({ onClick, ...rest }) => {
   }
 
   const renderSettingsMenuItemLink = (resource, id) => {
-    const label = translate(`resources.${resource.name}.name`, {
-      smart_count: id ? 1 : 2,
-    })
+    const label = resource.options.label
+      ? translate(resource.options.label)
+      : translate(`resources.${resource.name}.name`, {
+          smart_count: id ? 1 : 2,
+        })
     const link = id ? `/${resource.name}/${id}` : `/${resource.name}`
     return (
       <MenuItemLink
diff --git a/ui/src/layout/AppBar.test.jsx b/ui/src/layout/AppBar.test.jsx
index 7c8cd3dcd..cc5ef781d 100644
--- a/ui/src/layout/AppBar.test.jsx
+++ b/ui/src/layout/AppBar.test.jsx
@@ -9,11 +9,14 @@ import config from '../config'
 
 let store
 
+const mocks = vi.hoisted(() => ({ resources: [] }))
+
 vi.mock('react-admin', () => ({
   AppBar: ({ userMenu }) => <div data-testid="appbar">{userMenu}</div>,
+  MenuItemLink: ({ primaryText }) => <div>{primaryText}</div>,
   useTranslate: () => (x) => x,
   usePermissions: () => ({ permissions: 'admin' }),
-  getResources: () => [],
+  getResources: () => mocks.resources,
 }))
 
 vi.mock('./NowPlayingPanel', () => ({
@@ -41,6 +44,7 @@ describe('<AppBar />', () => {
     config.devActivityPanel = true
     config.enableNowPlaying = true
     config.enableQuickConnect = false
+    mocks.resources = []
     store = createStore(combineReducers({ activity: activityReducer }), {
       activity: { nowPlayingCount: 0 },
     })
@@ -84,4 +88,22 @@ describe('<AppBar />', () => {
     expect(screen.queryAllByText('menu.quickConnect.name')).toHaveLength(0)
     expect(screen.queryAllByText('menu.about')).not.toHaveLength(0)
   })
+
+  it('uses the resource label for settings items when set', () => {
+    mocks.resources = [
+      {
+        name: 'player',
+        hasList: true,
+        options: { subMenu: 'settings', label: 'resources.player.menuName' },
+      },
+      { name: 'transcoding', hasList: true, options: { subMenu: 'settings' } },
+    ]
+    render(
+      <Provider store={store}>
+        <AppBar />
+      </Provider>,
+    )
+    expect(screen.getByText('resources.player.menuName')).toBeInTheDocument()
+    expect(screen.getByText('resources.transcoding.name')).toBeInTheDocument()
+  })
 })
diff --git a/ui/src/player/ApiKeyInput.jsx b/ui/src/player/ApiKeyInput.jsx
new file mode 100644
index 000000000..1f2dd1ed2
--- /dev/null
+++ b/ui/src/player/ApiKeyInput.jsx
@@ -0,0 +1,107 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { useInput, useNotify, useTranslate } from 'react-admin'
+import { Button, TextField } from '@material-ui/core'
+import { FaKey } from 'react-icons/fa'
+import { MdContentCopy, MdDelete, MdRefresh } from 'react-icons/md'
+import { isWritable } from '../common/playlistUtils'
+import { generateApiKey } from './apiKey'
+
+const identity = (v) => v
+const MASK = '•'.repeat(26)
+
+const ApiKeyInput = ({ record, isCreate, fullWidth, className, ...props }) => {
+  const translate = useTranslate()
+  const notify = useNotify()
+  // Identity format/parse keep "" (revoke) distinct from undefined (untouched)
+  const {
+    input: { value, onChange },
+    meta: { error, touched },
+  } = useInput({ ...props, format: identity, parse: identity })
+
+  const isOwner = isCreate || record?.userId === localStorage.getItem('userId')
+  const pending = !!value
+  const revoking = value === '' && !!record?.hasApiKey
+  const saved = value == null && !!record?.hasApiKey
+  const hasKey = pending || saved
+
+  const copy = () => {
+    const fallback = () =>
+      prompt(translate('message.shareCopyToClipboard'), value)
+    if (navigator.clipboard && window.isSecureContext) {
+      navigator.clipboard
+        .writeText(value)
+        .then(
+          () => notify('resources.player.notifications.apiKeyCopied'),
+          fallback,
+        )
+    } else {
+      fallback()
+    }
+  }
+
+  const helperText = pending
+    ? 'resources.player.message.apiKeyPending'
+    : revoking
+      ? 'resources.player.message.apiKeyRevokePending'
+      : saved
+        ? 'resources.player.message.apiKeyActive'
+        : isOwner
+          ? 'resources.player.message.apiKeyNone'
+          : 'resources.player.message.apiKeyNoneOther'
+
+  return (
+    <div>
+      <TextField
+        label={translate('resources.player.fields.hasApiKey')}
+        value={pending ? value : saved ? MASK : ''}
+        variant="outlined"
+        margin="dense"
+        fullWidth={fullWidth}
+        className={className}
+        // Monospace keeps the whole key visible in a standard-width input
+        inputProps={{
+          style: { fontFamily: 'monospace', fontSize: '0.875rem' },
+        }}
+        InputProps={{ readOnly: true }}
+        error={!!(touched && error)}
+        helperText={translate(touched && error ? error : helperText)}
+      />
+      <div>
+        {pending && (
+          <Button startIcon={<MdContentCopy />} onClick={copy}>
+            {translate('resources.player.actions.copyApiKey')}
+          </Button>
+        )}
+        {isOwner && (
+          <Button
+            startIcon={hasKey ? <MdRefresh /> : <FaKey />}
+            onClick={() => onChange(generateApiKey())}
+          >
+            {translate(
+              hasKey
+                ? 'resources.player.actions.regenerateApiKey'
+                : 'resources.player.actions.generateApiKey',
+            )}
+          </Button>
+        )}
+        {saved && isWritable(record?.userId) && (
+          <Button startIcon={<MdDelete />} onClick={() => onChange('')}>
+            {translate('resources.player.actions.revokeApiKey')}
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+ApiKeyInput.propTypes = {
+  source: PropTypes.string.isRequired,
+  record: PropTypes.object,
+  isCreate: PropTypes.bool,
+  fullWidth: PropTypes.bool,
+  className: PropTypes.string,
+  validate: PropTypes.oneOfType([PropTypes.func, PropTypes.array]),
+}
+
+export default ApiKeyInput
diff --git a/ui/src/player/ApiKeyInput.test.jsx b/ui/src/player/ApiKeyInput.test.jsx
new file mode 100644
index 000000000..dd4269d6e
--- /dev/null
+++ b/ui/src/player/ApiKeyInput.test.jsx
@@ -0,0 +1,172 @@
+import * as React from 'react'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { Form } from 'react-final-form'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import ApiKeyInput from './ApiKeyInput'
+
+const hooks = vi.hoisted(() => ({ notify: vi.fn() }))
+const KEY = 'nds_0123456789abcdefghijkl'
+const KEY_FORMAT = /^nds_[0-9A-Za-z]{22}$/
+
+vi.mock('react-admin', async () => {
+  const actual = await vi.importActual('react-admin')
+  return {
+    ...actual,
+    useNotify: () => hooks.notify,
+    useTranslate: () => (key) => key,
+  }
+})
+
+const renderInput = ({
+  record,
+  initialValues = {},
+  isCreate = false,
+  fullWidth,
+}) => {
+  let values
+  const utils = render(
+    <Form
+      onSubmit={() => {}}
+      initialValues={initialValues}
+      render={({ values: v }) => {
+        values = v
+        return (
+          <ApiKeyInput
+            source="apiKey"
+            record={record}
+            isCreate={isCreate}
+            fullWidth={fullWidth}
+          />
+        )
+      }}
+    />,
+  )
+  return { ...utils, values: () => values }
+}
+
+const text = (key) => screen.queryByText(key)
+
+describe('ApiKeyInput', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    localStorage.setItem('userId', 'owner')
+    localStorage.setItem('role', 'regular')
+  })
+
+  it('shows a pending key with copy and regenerate on create', () => {
+    const { values } = renderInput({
+      record: {},
+      isCreate: true,
+      initialValues: { apiKey: KEY },
+    })
+    expect(screen.getByDisplayValue(KEY)).toBeInTheDocument()
+    expect(text('resources.player.message.apiKeyPending')).toBeInTheDocument()
+    expect(
+      screen.getByRole('button', {
+        name: 'resources.player.actions.copyApiKey',
+      }),
+    ).toBeInTheDocument()
+    expect(
+      text('resources.player.actions.revokeApiKey'),
+    ).not.toBeInTheDocument()
+
+    fireEvent.click(
+      screen.getByText('resources.player.actions.regenerateApiKey'),
+    )
+    expect(values().apiKey).toMatch(KEY_FORMAT)
+    expect(values().apiKey).not.toBe(KEY)
+  })
+
+  it('masks a saved key and lets the owner regenerate or revoke', () => {
+    const { values } = renderInput({
+      record: { id: 'p1', userId: 'owner', hasApiKey: true },
+    })
+    expect(screen.queryByDisplayValue(/^nds_/)).not.toBeInTheDocument()
+    expect(text('resources.player.message.apiKeyActive')).toBeInTheDocument()
+    expect(
+      text('resources.player.actions.regenerateApiKey'),
+    ).toBeInTheDocument()
+
+    fireEvent.click(screen.getByText('resources.player.actions.revokeApiKey'))
+    expect(values().apiKey).toBe('')
+    expect(
+      text('resources.player.message.apiKeyRevokePending'),
+    ).toBeInTheDocument()
+    expect(text('resources.player.actions.generateApiKey')).toBeInTheDocument()
+  })
+
+  it('lets the owner generate a key when there is none', () => {
+    const { values } = renderInput({
+      record: { id: 'p1', userId: 'owner', hasApiKey: false },
+    })
+    expect(values().apiKey).toBeUndefined()
+    expect(text('resources.player.message.apiKeyNone')).toBeInTheDocument()
+
+    fireEvent.click(screen.getByText('resources.player.actions.generateApiKey'))
+    expect(values().apiKey).toMatch(KEY_FORMAT)
+    expect(text('resources.player.message.apiKeyPending')).toBeInTheDocument()
+  })
+
+  it('lets an admin revoke but not set a key on another user player', () => {
+    localStorage.setItem('role', 'admin')
+    renderInput({ record: { id: 'p1', userId: 'someone', hasApiKey: true } })
+    expect(
+      text('resources.player.actions.regenerateApiKey'),
+    ).not.toBeInTheDocument()
+    expect(text('resources.player.actions.revokeApiKey')).toBeInTheDocument()
+  })
+
+  it('falls back to a prompt when the clipboard write fails', async () => {
+    vi.stubGlobal('isSecureContext', true)
+    vi.stubGlobal('prompt', vi.fn())
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true,
+      value: { writeText: vi.fn().mockRejectedValue(new Error('denied')) },
+    })
+    try {
+      renderInput({
+        record: {},
+        isCreate: true,
+        initialValues: { apiKey: KEY },
+      })
+      fireEvent.click(
+        screen.getByRole('button', {
+          name: 'resources.player.actions.copyApiKey',
+        }),
+      )
+      await waitFor(() =>
+        expect(window.prompt).toHaveBeenCalledWith(
+          'message.shareCopyToClipboard',
+          KEY,
+        ),
+      )
+      expect(hooks.notify).not.toHaveBeenCalled()
+    } finally {
+      vi.unstubAllGlobals()
+      delete navigator.clipboard
+    }
+  })
+
+  it('shows a neutral message to an admin viewing another user player with no key', () => {
+    localStorage.setItem('role', 'admin')
+    renderInput({ record: { id: 'p1', userId: 'someone', hasApiKey: false } })
+    expect(text('resources.player.message.apiKeyNoneOther')).toBeInTheDocument()
+    expect(text('resources.player.message.apiKeyNone')).not.toBeInTheDocument()
+    expect(screen.queryAllByRole('button')).toHaveLength(0)
+  })
+
+  it('shows no actions to another regular user', () => {
+    renderInput({ record: { id: 'p1', userId: 'someone', hasApiKey: true } })
+    expect(screen.queryAllByRole('button')).toHaveLength(0)
+  })
+
+  it('is not full width unless asked', () => {
+    const record = { id: 'p1', userId: 'owner', hasApiKey: true }
+    const { container, unmount } = renderInput({ record })
+    expect(container.querySelector('.MuiFormControl-fullWidth')).toBeNull()
+    unmount()
+
+    const { container: wide } = renderInput({ record, fullWidth: true })
+    expect(wide.querySelector('.MuiFormControl-fullWidth')).not.toBeNull()
+  })
+})
diff --git a/ui/src/player/PlayerCreate.jsx b/ui/src/player/PlayerCreate.jsx
new file mode 100644
index 000000000..bf02cde1b
--- /dev/null
+++ b/ui/src/player/PlayerCreate.jsx
@@ -0,0 +1,33 @@
+import React, { useMemo } from 'react'
+import { Create, SimpleForm, required, useTranslate } from 'react-admin'
+import { Title } from '../common'
+import { playerInputs } from './playerInputs'
+import ApiKeyInput from './ApiKeyInput'
+import { generateApiKey } from './apiKey'
+
+const PlayerCreateTitle = () => {
+  const translate = useTranslate()
+  const resourceName = translate('resources.player.name', { smart_count: 1 })
+  return (
+    <Title subTitle={translate('ra.page.create', { name: resourceName })} />
+  )
+}
+
+const PlayerCreate = (props) => {
+  // Memoized so re-renders don't swap the key the user may have already copied
+  const initialValues = useMemo(() => ({ apiKey: generateApiKey() }), [])
+  return (
+    <Create title={<PlayerCreateTitle />} {...props}>
+      <SimpleForm
+        variant="outlined"
+        redirect="list"
+        initialValues={initialValues}
+      >
+        {playerInputs()}
+        <ApiKeyInput source="apiKey" isCreate validate={required()} />
+      </SimpleForm>
+    </Create>
+  )
+}
+
+export default PlayerCreate
diff --git a/ui/src/player/PlayerCreate.test.jsx b/ui/src/player/PlayerCreate.test.jsx
new file mode 100644
index 000000000..dc1f817db
--- /dev/null
+++ b/ui/src/player/PlayerCreate.test.jsx
@@ -0,0 +1,47 @@
+import * as React from 'react'
+import { render } from '@testing-library/react'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import PlayerCreate from './PlayerCreate'
+import ApiKeyInput from './ApiKeyInput'
+
+const hooks = vi.hoisted(() => ({ forms: [] }))
+
+vi.mock('react-admin', async () => {
+  const actual = await vi.importActual('react-admin')
+  return {
+    ...actual,
+    Create: ({ children }) => children,
+    SimpleForm: (props) => {
+      hooks.forms.push(props)
+      return null
+    },
+  }
+})
+
+describe('PlayerCreate', () => {
+  beforeEach(() => {
+    hooks.forms = []
+  })
+
+  it('pre-fills one generated API key that survives re-renders', () => {
+    const { rerender } = render(<PlayerCreate resource="player" />)
+    rerender(<PlayerCreate resource="player" />)
+
+    const [first, second] = hooks.forms.map((f) => f.initialValues)
+    expect(hooks.forms).toHaveLength(2)
+    expect(first.apiKey).toMatch(/^nds_[0-9A-Za-z]{22}$/)
+    expect(second).toBe(first)
+  })
+
+  it('requires the API key', () => {
+    render(<PlayerCreate resource="player" />)
+
+    const input = React.Children.toArray(hooks.forms[0].children).find(
+      (child) => child.type === ApiKeyInput,
+    )
+    expect(input.props.source).toBe('apiKey')
+    expect(input.props.isCreate).toBe(true)
+    expect(input.props.validate('')).toBeTruthy()
+    expect(input.props.validate('nds_0123456789abcdefghijkl')).toBeUndefined()
+  })
+})
diff --git a/ui/src/player/PlayerEdit.jsx b/ui/src/player/PlayerEdit.jsx
index 1826500bd..08f389698 100644
--- a/ui/src/player/PlayerEdit.jsx
+++ b/ui/src/player/PlayerEdit.jsx
@@ -1,17 +1,17 @@
 import {
-  TextInput,
-  BooleanInput,
   TextField,
   Edit,
-  required,
   SimpleForm,
-  SelectInput,
-  ReferenceInput,
   useTranslate,
+  DeleteButton,
+  DeleteWithConfirmButton,
+  SaveButton,
+  Toolbar,
 } from 'react-admin'
+import { makeStyles } from '@material-ui/core/styles'
 import { Title } from '../common'
-import config from '../config'
-import { BITRATE_CHOICES } from '../consts'
+import ApiKeyInput from './ApiKeyInput'
+import { playerInputs } from './playerInputs'
 
 const PlayerTitle = ({ record }) => {
   const translate = useTranslate()
@@ -19,24 +19,35 @@ const PlayerTitle = ({ record }) => {
   return <Title subTitle={`${resourceName} ${record ? record.name : ''}`} />
 }
 
+const useToolbarStyles = makeStyles({
+  toolbar: {
+    display: 'flex',
+    justifyContent: 'space-between',
+  },
+})
+
+const PlayerEditToolbar = (props) => (
+  <Toolbar {...props} classes={useToolbarStyles()}>
+    <SaveButton />
+    {props.record?.hasApiKey ? (
+      <DeleteWithConfirmButton
+        mutationMode="pessimistic"
+        confirmTitle="resources.player.message.deleteWithKeyTitle"
+        confirmContent="resources.player.message.deleteWithKeyContent"
+      />
+    ) : (
+      <DeleteButton />
+    )}
+  </Toolbar>
+)
+
 const PlayerEdit = (props) => (
-  <Edit title={<PlayerTitle />} {...props}>
-    <SimpleForm variant={'outlined'}>
-      <TextInput source="name" validate={[required()]} />
-      <ReferenceInput
-        source="transcodingId"
-        reference="transcoding"
-        sort={{ field: 'name', order: 'ASC' }}
-      >
-        <SelectInput source="name" resettable />
-      </ReferenceInput>
-      <SelectInput source="maxBitRate" resettable choices={BITRATE_CHOICES} />
-      <BooleanInput source="reportRealPath" fullWidth />
-      {(config.lastFMEnabled || config.listenBrainzEnabled) && (
-        <BooleanInput source="scrobbleEnabled" fullWidth />
-      )}
+  <Edit title={<PlayerTitle />} mutationMode="pessimistic" {...props}>
+    <SimpleForm variant={'outlined'} toolbar={<PlayerEditToolbar />}>
+      {playerInputs()}
       <TextField source="client" />
       <TextField source="userName" />
+      <ApiKeyInput source="apiKey" />
     </SimpleForm>
   </Edit>
 )
diff --git a/ui/src/player/PlayerEdit.test.jsx b/ui/src/player/PlayerEdit.test.jsx
new file mode 100644
index 000000000..38fa2cc8e
--- /dev/null
+++ b/ui/src/player/PlayerEdit.test.jsx
@@ -0,0 +1,25 @@
+import * as React from 'react'
+import { render } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import PlayerEdit from './PlayerEdit'
+
+const hooks = vi.hoisted(() => ({ editProps: null }))
+
+vi.mock('react-admin', async () => {
+  const actual = await vi.importActual('react-admin')
+  return {
+    ...actual,
+    Edit: (props) => {
+      hooks.editProps = props
+      return null
+    },
+  }
+})
+
+describe('PlayerEdit', () => {
+  // An optimistic or undoable save would put the new key in react-admin's cache
+  it('saves pessimistically', () => {
+    render(<PlayerEdit resource="player" id="p1" />)
+    expect(hooks.editProps.mutationMode).toBe('pessimistic')
+  })
+})
diff --git a/ui/src/player/PlayerList.jsx b/ui/src/player/PlayerList.jsx
index a2b009bad..c7bd32570 100644
--- a/ui/src/player/PlayerList.jsx
+++ b/ui/src/player/PlayerList.jsx
@@ -2,18 +2,20 @@ import React from 'react'
 import {
   Datagrid,
   TextField,
-  DateField,
   FunctionField,
   ReferenceField,
   Filter,
   SearchInput,
+  NullableBooleanInput,
 } from 'react-admin'
 import { useMediaQuery } from '@material-ui/core'
-import { SimpleList, List } from '../common'
+import { FaKey } from 'react-icons/fa'
+import { SimpleList, List, DateField } from '../common'
 
 const PlayerFilter = (props) => (
   <Filter {...props} variant={'outlined'}>
     <SearchInput id="search" source="name" alwaysOn />
+    <NullableBooleanInput source="hasApiKey" alwaysOn />
   </Filter>
 )
 
@@ -30,7 +32,11 @@ const PlayerList = ({ permissions, ...props }) => {
         <SimpleList
           primaryText={(r) => r.name}
           secondaryText={(r) => r.userName}
-          tertiaryText={(r) => (r.maxBitRate ? r.maxBitRate : '-')}
+          tertiaryText={(r) => (
+            <>
+              {r.hasApiKey && <FaKey />} {r.maxBitRate ? r.maxBitRate : '-'}
+            </>
+          )}
         />
       ) : (
         <Datagrid rowClick="edit">
@@ -43,6 +49,11 @@ const PlayerList = ({ permissions, ...props }) => {
             source="maxBitRate"
             render={(r) => (r.maxBitRate ? r.maxBitRate : '-')}
           />
+          <FunctionField
+            source="hasApiKey"
+            sortable={false}
+            render={(r) => (r.hasApiKey ? <FaKey /> : null)}
+          />
           <DateField source="lastSeen" showTime sortByOrder={'DESC'} />
         </Datagrid>
       )}
diff --git a/ui/src/player/apiKey.js b/ui/src/player/apiKey.js
new file mode 100644
index 000000000..27d683052
--- /dev/null
+++ b/ui/src/player/apiKey.js
@@ -0,0 +1,15 @@
+const API_KEY_PREFIX = 'nds_'
+const ALPHABET =
+  '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+const KEY_LENGTH = 22
+
+// Bytes >= 248 are dropped so every character is equally likely (248 = 4 * 62).
+export const generateApiKey = () => {
+  let key = ''
+  while (key.length < KEY_LENGTH) {
+    for (const b of window.crypto.getRandomValues(new Uint8Array(32))) {
+      if (b < 248 && key.length < KEY_LENGTH) key += ALPHABET[b % 62]
+    }
+  }
+  return API_KEY_PREFIX + key
+}
diff --git a/ui/src/player/apiKey.test.js b/ui/src/player/apiKey.test.js
new file mode 100644
index 000000000..4c41871e7
--- /dev/null
+++ b/ui/src/player/apiKey.test.js
@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest'
+import { generateApiKey } from './apiKey'
+
+describe('generateApiKey', () => {
+  it('returns the prefix plus 22 base62 characters', () => {
+    for (let i = 0; i < 50; i++) {
+      expect(generateApiKey()).toMatch(/^nds_[0-9A-Za-z]{22}$/)
+    }
+  })
+
+  it('returns a different key each time', () => {
+    const keys = new Set(Array.from({ length: 100 }, generateApiKey))
+    expect(keys.size).toBe(100)
+  })
+})
diff --git a/ui/src/player/index.js b/ui/src/player/index.js
index aaa3d58d7..c28cfa414 100644
--- a/ui/src/player/index.js
+++ b/ui/src/player/index.js
@@ -1,9 +1,11 @@
 import { BsFillMusicPlayerFill } from 'react-icons/bs'
 import PlayerList from './PlayerList'
 import PlayerEdit from './PlayerEdit'
+import PlayerCreate from './PlayerCreate'
 
 export default {
   list: PlayerList,
   edit: PlayerEdit,
+  create: PlayerCreate,
   icon: BsFillMusicPlayerFill,
 }
diff --git a/ui/src/player/playerInputs.jsx b/ui/src/player/playerInputs.jsx
new file mode 100644
index 000000000..a8b719a81
--- /dev/null
+++ b/ui/src/player/playerInputs.jsx
@@ -0,0 +1,34 @@
+import React from 'react'
+import {
+  BooleanInput,
+  ReferenceInput,
+  SelectInput,
+  TextInput,
+  required,
+} from 'react-admin'
+import config from '../config'
+import { BITRATE_CHOICES } from '../consts'
+
+// Returned as an array, not a component, so SimpleForm still injects its props into each input.
+export const playerInputs = () =>
+  [
+    <TextInput key="name" source="name" validate={[required()]} />,
+    <ReferenceInput
+      key="transcodingId"
+      source="transcodingId"
+      reference="transcoding"
+      sort={{ field: 'name', order: 'ASC' }}
+    >
+      <SelectInput source="name" resettable />
+    </ReferenceInput>,
+    <SelectInput
+      key="maxBitRate"
+      source="maxBitRate"
+      resettable
+      choices={BITRATE_CHOICES}
+    />,
+    <BooleanInput key="reportRealPath" source="reportRealPath" fullWidth />,
+    (config.lastFMEnabled || config.listenBrainzEnabled) && (
+      <BooleanInput key="scrobbleEnabled" source="scrobbleEnabled" fullWidth />
+    ),
+  ].filter(Boolean)

From ab5869123dad0d435bda3040849a9b9c0fc11888 Mon Sep 17 00:00:00 2001
From: DawidKrynski <dawid_krynski.64@wp.pl>
Date: Mon, 28 Sep 2026 14:07:05 +0200
Subject: [PATCH 191/200] fix(playlists): include co-credited album artists
 when adding an artist to a playlist - #6240 (#6241)

* fix(persistence): include co-credited album artists when adding an artist to a playlist - #6240

Signed-off-by: Dawid Krynski <188586034+DawidKrynski@users.noreply.github.com>

* test(persistence): cover first album artist and track-artist-only in AddArtists

The joint track now uses a track artist that is not an album artist, and
the AddArtists specs check all three cases: the first album artist still
matches, a co-credited album artist matches, and a track-artist-only ID
adds nothing. The last case guards against widening the role filter.

---------

Signed-off-by: Dawid Krynski <188586034+DawidKrynski@users.noreply.github.com>
Co-authored-by: Dawid Krynski <188586034+DawidKrynski@users.noreply.github.com>
Co-authored-by: Deluan <deluan@navidrome.org>
---
 persistence/playlist_track_repository.go      |  4 +-
 persistence/playlist_track_repository_test.go | 39 +++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/persistence/playlist_track_repository.go b/persistence/playlist_track_repository.go
index 341aab8af..392446cef 100644
--- a/persistence/playlist_track_repository.go
+++ b/persistence/playlist_track_repository.go
@@ -234,7 +234,9 @@ func (r *playlistTrackRepository) AddAlbums(ctx context.Context, albumIds []stri
 }
 
 func (r *playlistTrackRepository) AddArtists(ctx context.Context, artistIds []string) (int, error) {
-	return r.addMediaFileIds(ctx, Eq{"album_artist_id": artistIds})
+	// Match by album-artist participation, not the deprecated album_artist_id
+	// column, which only holds the first album artist.
+	return r.addMediaFileIds(ctx, ParticipantIDFilter("media_file", artistIds, model.RoleAlbumArtist))
 }
 
 func (r *playlistTrackRepository) AddDiscs(ctx context.Context, discs []model.DiscID) (int, error) {
diff --git a/persistence/playlist_track_repository_test.go b/persistence/playlist_track_repository_test.go
index 3c532c405..119c57116 100644
--- a/persistence/playlist_track_repository_test.go
+++ b/persistence/playlist_track_repository_test.go
@@ -219,6 +219,45 @@ var _ = Describe("PlaylistTrackRepository", func() {
 		})
 	})
 
+	Describe("AddArtists", func() {
+		var tracks model.PlaylistTrackRepository
+		var joint model.MediaFile
+
+		BeforeEach(func() {
+			mfRepo := NewMediaFileRepository(GetDBXBuilder())
+			joint = mf(model.MediaFile{ID: "pls-coartist-track", Title: "Joint Track", ArtistID: artistPunctuation.ID,
+				Artist: artistPunctuation.Name, AlbumID: "pls-coartist-album", Album: "Joint Album",
+				AlbumArtistID: artistKraftwerk.ID, AlbumArtist: artistKraftwerk.Name, Path: p("joint/track.mp3")})
+			joint.Participants[model.RoleAlbumArtist] = model.ParticipantList{
+				{Artist: artistKraftwerk},
+				{Artist: artistBeatles},
+			}
+			Expect(mfRepo.Put(ctx, &joint)).To(Succeed())
+			DeferCleanup(func() { _ = mfRepo.Delete(ctx, joint.ID) })
+
+			plsRepo := NewPlaylistRepository(GetDBXBuilder())
+			pls := model.Playlist{Name: "Co-album-artist", OwnerID: adminUser.ID, OwnerName: adminUser.UserName}
+			Expect(plsRepo.Put(ctx, &pls)).To(Succeed())
+			DeferCleanup(func() { _ = plsRepo.Delete(ctx, pls.ID) })
+			tracks = plsRepo.Tracks(ctx, pls.ID, false)
+		})
+
+		It("adds tracks where the artist is the first album artist", func() {
+			Expect(tracks.AddArtists(ctx, []string{artistKraftwerk.ID})).To(Equal(1))
+			Expect(tracks.GetMediaFileIDs(ctx)).To(ConsistOf(joint.ID))
+		})
+
+		It("adds tracks where the artist is not the first album artist", func() {
+			Expect(tracks.AddArtists(ctx, []string{artistBeatles.ID})).To(Equal(1))
+			Expect(tracks.GetMediaFileIDs(ctx)).To(ConsistOf(joint.ID))
+		})
+
+		It("does not add tracks where the artist is only the track artist", func() {
+			Expect(tracks.AddArtists(ctx, []string{artistPunctuation.ID})).To(Equal(0))
+			Expect(tracks.GetMediaFileIDs(ctx)).To(BeEmpty())
+		})
+	})
+
 	Describe("library access", func() {
 		var otherLib model.Library
 		var restrictedUser model.User

From 612c8290f956c6a35a75c4adad6aa12f10da9c3a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Mon, 28 Sep 2026 08:48:36 -0400
Subject: [PATCH 192/200] feat(ui): show read-only values in edit forms as
 dimmed, themable inputs (#6238)

---
 ui/src/common/ReadOnlyFields.jsx      |  99 +++++++++++++++
 ui/src/common/ReadOnlyFields.test.jsx | 121 +++++++++++++++++++
 ui/src/common/index.js                |   1 +
 ui/src/library/LibraryEdit.jsx        | 166 +++++++-------------------
 ui/src/player/PlayerEdit.jsx          |   7 +-
 ui/src/playlist/PlaylistEdit.jsx      |  12 +-
 ui/src/radio/RadioEdit.jsx            |  12 +-
 ui/src/share/ShareEdit.jsx            |  31 +++--
 ui/src/user/UserEdit.jsx              |  11 +-
 ui/src/user/UserEdit.test.jsx         |   6 +-
 10 files changed, 306 insertions(+), 160 deletions(-)
 create mode 100644 ui/src/common/ReadOnlyFields.jsx
 create mode 100644 ui/src/common/ReadOnlyFields.test.jsx

diff --git a/ui/src/common/ReadOnlyFields.jsx b/ui/src/common/ReadOnlyFields.jsx
new file mode 100644
index 000000000..c56643fbd
--- /dev/null
+++ b/ui/src/common/ReadOnlyFields.jsx
@@ -0,0 +1,99 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import get from 'lodash/get'
+import { FieldTitle, useRecordContext } from 'react-admin'
+import { TextField } from '@material-ui/core'
+import { makeStyles } from '@material-ui/core/styles'
+import { useDateLocale } from '../i18n/useDateLocale'
+import {
+  formatBytes,
+  formatDateTime,
+  formatDuration2,
+  formatNumber,
+} from '../utils/formatters'
+import { isDateSet } from '../utils/validations'
+
+const useStyles = makeStyles(
+  (theme) => ({
+    inputRoot: {
+      '&:hover $notchedOutline': {
+        borderColor: theme.palette.divider,
+      },
+    },
+    notchedOutline: {
+      borderColor: theme.palette.divider,
+    },
+  }),
+  { name: 'NDReadOnlyField' },
+)
+
+const identity = (v) => v
+
+// Renders a record value as a dimmed, non-editable input, so it lines up with the inputs in a form
+export const ReadOnlyTextField = ({
+  source,
+  label,
+  resource,
+  className,
+  fullWidth,
+  format = identity,
+  ...props
+}) => {
+  const classes = useStyles(props)
+  const record = useRecordContext(props)
+  const value = get(record, source)
+
+  return (
+    <TextField
+      id={source}
+      className={className}
+      label={<FieldTitle label={label} source={source} resource={resource} />}
+      value={value == null ? '' : format(value)}
+      variant="outlined"
+      margin="dense"
+      fullWidth={fullWidth}
+      focused={false}
+      helperText=" "
+      InputProps={{
+        readOnly: true,
+        classes: {
+          root: classes.inputRoot,
+          notchedOutline: classes.notchedOutline,
+        },
+      }}
+      inputProps={{ tabIndex: -1 }}
+    />
+  )
+}
+
+ReadOnlyTextField.propTypes = {
+  source: PropTypes.string.isRequired,
+  label: PropTypes.oneOfType([PropTypes.string, PropTypes.bool]),
+  record: PropTypes.object,
+  resource: PropTypes.string,
+  className: PropTypes.string,
+  classes: PropTypes.object,
+  fullWidth: PropTypes.bool,
+  format: PropTypes.func,
+}
+
+export const ReadOnlyDateField = (props) => {
+  const locale = useDateLocale()
+  const format = (v) => (isDateSet(v) ? formatDateTime(v, locale) : '')
+  return <ReadOnlyTextField format={format} {...props} />
+}
+
+export const ReadOnlyNumberField = (props) => {
+  const locale = useDateLocale()
+  return (
+    <ReadOnlyTextField format={(v) => formatNumber(v, locale)} {...props} />
+  )
+}
+
+export const ReadOnlySizeField = (props) => (
+  <ReadOnlyTextField format={formatBytes} {...props} />
+)
+
+export const ReadOnlyDurationField = (props) => (
+  <ReadOnlyTextField format={formatDuration2} {...props} />
+)
diff --git a/ui/src/common/ReadOnlyFields.test.jsx b/ui/src/common/ReadOnlyFields.test.jsx
new file mode 100644
index 000000000..00543a786
--- /dev/null
+++ b/ui/src/common/ReadOnlyFields.test.jsx
@@ -0,0 +1,121 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import {
+  ReadOnlyDateField,
+  ReadOnlyDurationField,
+  ReadOnlyNumberField,
+  ReadOnlySizeField,
+  ReadOnlyTextField,
+} from './ReadOnlyFields'
+
+vi.mock('react-admin', async (importOriginal) => ({
+  ...(await importOriginal()),
+  useLocale: vi.fn(),
+}))
+
+describe('ReadOnlyFields', () => {
+  const record = {
+    id: '1',
+    client: 'NavidromeUI',
+    createdAt: '2026-09-17T14:30:00Z',
+    lastVisitedAt: '0001-01-01T00:00:00Z',
+    count: 1234567,
+    zero: 0,
+    size: 1536000,
+    duration: 3725,
+  }
+
+  beforeEach(async () => {
+    vi.clearAllMocks()
+    vi.spyOn(navigator, 'languages', 'get').mockReturnValue([])
+    const { useLocale } = await import('react-admin')
+    vi.mocked(useLocale).mockReturnValue('de')
+  })
+
+  const renderField = (Field, props) =>
+    render(<Field record={record} resource="player" {...props} />)
+
+  describe('<ReadOnlyTextField>', () => {
+    it('shows the record value with the translated field label', () => {
+      renderField(ReadOnlyTextField, { source: 'client' })
+      const input = screen.getByLabelText('resources.player.fields.client')
+      expect(input).toHaveValue('NavidromeUI')
+    })
+
+    it('cannot be edited or reached with the Tab key', () => {
+      renderField(ReadOnlyTextField, { source: 'client' })
+      const input = screen.getByRole('textbox')
+      expect(input).toHaveAttribute('readonly')
+      expect(input).toHaveAttribute('tabindex', '-1')
+    })
+
+    it('shows an empty value when the record has no value', () => {
+      renderField(ReadOnlyTextField, { source: 'userName' })
+      expect(screen.getByRole('textbox')).toHaveValue('')
+    })
+
+    it('uses an explicit label when given', () => {
+      renderField(ReadOnlyTextField, { source: 'client', label: 'Custom' })
+      expect(screen.getByLabelText('Custom')).toBeInTheDocument()
+    })
+
+    it('applies a custom format', () => {
+      renderField(ReadOnlyTextField, {
+        source: 'client',
+        format: (v) => v.toUpperCase(),
+      })
+      expect(screen.getByRole('textbox')).toHaveValue('NAVIDROMEUI')
+    })
+
+    it('exposes theme-overridable class names', () => {
+      const { container } = renderField(ReadOnlyTextField, {
+        source: 'client',
+      })
+      expect(
+        container.querySelector('[class*="NDReadOnlyField-inputRoot"]'),
+      ).toBeInTheDocument()
+      expect(
+        container.querySelector('[class*="NDReadOnlyField-notchedOutline"]'),
+      ).toBeInTheDocument()
+    })
+  })
+
+  describe('<ReadOnlyDateField>', () => {
+    it('formats the date using the selected language', () => {
+      renderField(ReadOnlyDateField, { source: 'createdAt' })
+      expect(screen.getByRole('textbox').value).toMatch(/^17\.9\.2026, /)
+    })
+
+    it('shows an empty value when the date is not set', () => {
+      renderField(ReadOnlyDateField, { source: 'lastVisitedAt' })
+      expect(screen.getByRole('textbox')).toHaveValue('')
+    })
+  })
+
+  describe('<ReadOnlyNumberField>', () => {
+    it('formats the number using the selected language', () => {
+      renderField(ReadOnlyNumberField, { source: 'count' })
+      expect(screen.getByRole('textbox')).toHaveValue('1.234.567')
+    })
+
+    it('shows zero', () => {
+      renderField(ReadOnlyNumberField, { source: 'zero' })
+      expect(screen.getByRole('textbox')).toHaveValue('0')
+    })
+  })
+
+  describe('<ReadOnlySizeField>', () => {
+    it('formats bytes as a human-readable size', () => {
+      renderField(ReadOnlySizeField, { source: 'size' })
+      expect(screen.getByRole('textbox')).toHaveValue('1.46 MB')
+    })
+  })
+
+  describe('<ReadOnlyDurationField>', () => {
+    it('formats seconds as a human-readable duration', () => {
+      renderField(ReadOnlyDurationField, { source: 'duration' })
+      expect(screen.getByRole('textbox')).toHaveValue('1h 2m 5s')
+    })
+  })
+})
diff --git a/ui/src/common/index.js b/ui/src/common/index.js
index 0177df326..fb8f40f00 100644
--- a/ui/src/common/index.js
+++ b/ui/src/common/index.js
@@ -15,6 +15,7 @@ export * from './perPageStore'
 export * from './PlayButton'
 export * from './QuickFilter'
 export * from './RangeField'
+export * from './ReadOnlyFields'
 export * from './ShuffleAllButton'
 export * from './SimpleList'
 export * from './SizeField'
diff --git a/ui/src/library/LibraryEdit.jsx b/ui/src/library/LibraryEdit.jsx
index 7e89c892c..53d17ac7f 100644
--- a/ui/src/library/LibraryEdit.jsx
+++ b/ui/src/library/LibraryEdit.jsx
@@ -6,7 +6,6 @@ import {
   BooleanInput,
   required,
   SaveButton,
-  DateField,
   useTranslate,
   useMutation,
   useNotify,
@@ -16,8 +15,13 @@ import {
 import { Typography, Box } from '@material-ui/core'
 import { makeStyles } from '@material-ui/core/styles'
 import DeleteLibraryButton from './DeleteLibraryButton'
-import { Title } from '../common'
-import { formatBytes, formatDuration2, formatNumber } from '../utils/index.js'
+import {
+  ReadOnlyDateField,
+  ReadOnlyDurationField,
+  ReadOnlyNumberField,
+  ReadOnlySizeField,
+  Title,
+} from '../common'
 
 const useStyles = makeStyles({
   toolbar: {
@@ -26,6 +30,8 @@ const useStyles = makeStyles({
   },
 })
 
+const readOnlyProps = { resource: 'library', fullWidth: true }
+
 const LibraryTitle = ({ record }) => {
   const translate = useTranslate()
   const resourceName = translate('resources.library.name', { smart_count: 1 })
@@ -125,132 +131,40 @@ const LibraryEdit = (props) => {
                     {translate('resources.library.sections.statistics')}
                   </Typography>
 
-                  <Box display="flex">
-                    <Box flex={1} mr="0.5em">
-                      <TextInput
-                        InputProps={{ readOnly: true }}
-                        resource={'library'}
-                        source={'totalSongs'}
-                        label={translate('resources.library.fields.totalSongs')}
-                        fullWidth
-                        variant="outlined"
-                      />
-                    </Box>
-                    <Box flex={1} ml="0.5em">
-                      <TextInput
-                        InputProps={{ readOnly: true }}
-                        resource={'library'}
-                        source={'totalAlbums'}
-                        label={translate(
-                          'resources.library.fields.totalAlbums',
-                        )}
-                        fullWidth
-                        variant="outlined"
-                      />
-                    </Box>
-                  </Box>
-
-                  <Box display="flex">
-                    <Box flex={1} mr="0.5em">
-                      <TextInput
-                        InputProps={{ readOnly: true }}
-                        resource={'library'}
-                        source={'totalArtists'}
-                        label={translate(
-                          'resources.library.fields.totalArtists',
-                        )}
-                        fullWidth
-                        variant="outlined"
-                      />
-                    </Box>
-                    <Box flex={1} ml="0.5em">
-                      <TextInput
-                        InputProps={{ readOnly: true }}
-                        resource={'library'}
-                        source={'totalSize'}
-                        label={translate('resources.library.fields.totalSize')}
-                        format={(v) => formatBytes(v, 2)}
-                        fullWidth
-                        variant="outlined"
-                      />
-                    </Box>
-                  </Box>
-
-                  <Box display="flex">
-                    <Box flex={1} mr="0.5em">
-                      <TextInput
-                        InputProps={{ readOnly: true }}
-                        resource={'library'}
-                        source={'totalDuration'}
-                        label={translate(
-                          'resources.library.fields.totalDuration',
-                        )}
-                        format={formatDuration2}
-                        fullWidth
-                        variant="outlined"
-                      />
-                    </Box>
-                    <Box flex={1} ml="0.5em">
-                      <TextInput
-                        InputProps={{ readOnly: true }}
-                        resource={'library'}
-                        source={'totalMissingFiles'}
-                        label={translate(
-                          'resources.library.fields.totalMissingFiles',
-                        )}
-                        fullWidth
-                        variant="outlined"
-                      />
-                    </Box>
-                  </Box>
-
-                  {/* Timestamps Section */}
-                  <Box mb="1em">
-                    <Typography
-                      variant="body2"
-                      color="textSecondary"
-                      gutterBottom
-                    >
-                      {translate('resources.library.fields.lastScanAt')}
-                    </Typography>
-                    <DateField
-                      variant="body1"
-                      source="lastScanAt"
-                      showTime
-                      record={formProps.record}
+                  <Box
+                    display="grid"
+                    gridTemplateColumns="1fr 1fr"
+                    gridColumnGap="1em"
+                  >
+                    <ReadOnlyNumberField
+                      source="totalSongs"
+                      {...readOnlyProps}
                     />
-                  </Box>
-
-                  <Box mb="1em">
-                    <Typography
-                      variant="body2"
-                      color="textSecondary"
-                      gutterBottom
-                    >
-                      {translate('resources.library.fields.updatedAt')}
-                    </Typography>
-                    <DateField
-                      variant="body1"
-                      source="updatedAt"
-                      showTime
-                      record={formProps.record}
+                    <ReadOnlyNumberField
+                      source="totalAlbums"
+                      {...readOnlyProps}
                     />
-                  </Box>
-
-                  <Box mb="2em">
-                    <Typography
-                      variant="body2"
-                      color="textSecondary"
-                      gutterBottom
-                    >
-                      {translate('resources.library.fields.createdAt')}
-                    </Typography>
-                    <DateField
-                      variant="body1"
-                      source="createdAt"
-                      showTime
-                      record={formProps.record}
+                    <ReadOnlyNumberField
+                      source="totalArtists"
+                      {...readOnlyProps}
                     />
+                    <ReadOnlySizeField source="totalSize" {...readOnlyProps} />
+                    <ReadOnlyDurationField
+                      source="totalDuration"
+                      {...readOnlyProps}
+                    />
+                    <ReadOnlyNumberField
+                      source="totalMissingFiles"
+                      {...readOnlyProps}
+                    />
+                    <Box gridColumn="1 / -1">
+                      <ReadOnlyDateField
+                        source="lastScanAt"
+                        {...readOnlyProps}
+                      />
+                    </Box>
+                    <ReadOnlyDateField source="updatedAt" {...readOnlyProps} />
+                    <ReadOnlyDateField source="createdAt" {...readOnlyProps} />
                   </Box>
                 </Box>
               </Box>
diff --git a/ui/src/player/PlayerEdit.jsx b/ui/src/player/PlayerEdit.jsx
index 08f389698..d785eb04e 100644
--- a/ui/src/player/PlayerEdit.jsx
+++ b/ui/src/player/PlayerEdit.jsx
@@ -1,5 +1,4 @@
 import {
-  TextField,
   Edit,
   SimpleForm,
   useTranslate,
@@ -9,7 +8,7 @@ import {
   Toolbar,
 } from 'react-admin'
 import { makeStyles } from '@material-ui/core/styles'
-import { Title } from '../common'
+import { ReadOnlyTextField, Title } from '../common'
 import ApiKeyInput from './ApiKeyInput'
 import { playerInputs } from './playerInputs'
 
@@ -45,8 +44,8 @@ const PlayerEdit = (props) => (
   <Edit title={<PlayerTitle />} mutationMode="pessimistic" {...props}>
     <SimpleForm variant={'outlined'} toolbar={<PlayerEditToolbar />}>
       {playerInputs()}
-      <TextField source="client" />
-      <TextField source="userName" />
+      <ReadOnlyTextField source="client" />
+      <ReadOnlyTextField source="userName" />
       <ApiKeyInput source="apiKey" />
     </SimpleForm>
   </Edit>
diff --git a/ui/src/playlist/PlaylistEdit.jsx b/ui/src/playlist/PlaylistEdit.jsx
index f6882e366..c7594fa13 100644
--- a/ui/src/playlist/PlaylistEdit.jsx
+++ b/ui/src/playlist/PlaylistEdit.jsx
@@ -3,7 +3,6 @@ import {
   FormDataConsumer,
   SimpleForm,
   TextInput,
-  TextField,
   BooleanInput,
   required,
   useTranslate,
@@ -11,13 +10,14 @@ import {
   ReferenceInput,
   SelectInput,
 } from 'react-admin'
-import { isWritable, Title } from '../common'
+import { isWritable, ReadOnlyTextField, Title } from '../common'
 
 const SyncFragment = ({ formData, variant, ...rest }) => {
+  if (!formData.path) return null
   return (
     <>
-      {formData.path && <BooleanInput source="sync" {...rest} />}
-      {formData.path && <TextField source="path" {...rest} />}
+      <BooleanInput source="sync" {...rest} />
+      <ReadOnlyTextField source="path" {...rest} />
     </>
   )
 }
@@ -56,10 +56,10 @@ const PlaylistEditForm = (props) => {
           />
         </ReferenceInput>
       ) : (
-        <TextField source="ownerName" />
+        <ReadOnlyTextField source="ownerName" />
       )}
       <BooleanInput source="public" disabled={!isWritable(record.ownerId)} />
-      <FormDataConsumer>
+      <FormDataConsumer fullWidth>
         {(formDataProps) => <SyncFragment {...formDataProps} />}
       </FormDataConsumer>
     </SimpleForm>
diff --git a/ui/src/radio/RadioEdit.jsx b/ui/src/radio/RadioEdit.jsx
index bbe001e6f..af879deaa 100644
--- a/ui/src/radio/RadioEdit.jsx
+++ b/ui/src/radio/RadioEdit.jsx
@@ -1,5 +1,4 @@
 import {
-  DateField,
   Edit,
   required,
   SimpleForm,
@@ -9,7 +8,12 @@ import {
 import { CardMedia } from '@material-ui/core'
 import { makeStyles } from '@material-ui/core/styles'
 import { urlValidate } from '../utils/validations'
-import { Title, ImageUploadOverlay, useImageLoadingState } from '../common'
+import {
+  Title,
+  ImageUploadOverlay,
+  ReadOnlyDateField,
+  useImageLoadingState,
+} from '../common'
 import subsonic from '../subsonic'
 import config from '../config'
 import { RADIO_PLACEHOLDER_IMAGE } from '../consts'
@@ -65,8 +69,8 @@ const RadioEdit = (props) => {
           fullWidth
           validate={[urlValidate]}
         />
-        <DateField variant="body1" source="updatedAt" showTime />
-        <DateField variant="body1" source="createdAt" showTime />
+        <ReadOnlyDateField source="updatedAt" />
+        <ReadOnlyDateField source="createdAt" />
       </SimpleForm>
     </Edit>
   )
diff --git a/ui/src/share/ShareEdit.jsx b/ui/src/share/ShareEdit.jsx
index 2cf7f2df7..a222d3369 100644
--- a/ui/src/share/ShareEdit.jsx
+++ b/ui/src/share/ShareEdit.jsx
@@ -2,13 +2,16 @@ import {
   DateTimeInput,
   BooleanInput,
   Edit,
-  NumberField,
   SimpleForm,
   TextInput,
 } from 'react-admin'
 import { sharePlayerUrl } from '../utils'
 import { Link } from '@material-ui/core'
-import { DateField } from '../common'
+import {
+  ReadOnlyDateField,
+  ReadOnlyNumberField,
+  ReadOnlyTextField,
+} from '../common'
 import config from '../config'
 
 export const ShareEdit = (props) => {
@@ -16,20 +19,26 @@ export const ShareEdit = (props) => {
   const url = sharePlayerUrl(id)
   return (
     <Edit {...props}>
-      <SimpleForm {...rest}>
-        <Link source="URL" href={url} target="_blank" rel="noopener noreferrer">
+      <SimpleForm variant={'outlined'} {...rest}>
+        <Link
+          source="URL"
+          href={url}
+          target="_blank"
+          rel="noopener noreferrer"
+          variant="inherit"
+        >
           {url}
         </Link>
         <TextInput source="description" />
         {config.enableDownloads && <BooleanInput source="downloadable" />}
         <DateTimeInput source="expiresAt" />
-        <TextInput source="contents" disabled />
-        <TextInput source="format" disabled />
-        <TextInput source="maxBitRate" disabled />
-        <TextInput source="username" disabled />
-        <NumberField source="visitCount" disabled />
-        <DateField source="lastVisitedAt" disabled showTime />
-        <DateField source="createdAt" disabled showTime />
+        <ReadOnlyTextField source="contents" />
+        <ReadOnlyTextField source="format" />
+        <ReadOnlyTextField source="maxBitRate" />
+        <ReadOnlyTextField source="username" />
+        <ReadOnlyNumberField source="visitCount" />
+        <ReadOnlyDateField source="lastVisitedAt" />
+        <ReadOnlyDateField source="createdAt" />
       </SimpleForm>
     </Edit>
   )
diff --git a/ui/src/user/UserEdit.jsx b/ui/src/user/UserEdit.jsx
index c5d9c75a4..feadafff1 100644
--- a/ui/src/user/UserEdit.jsx
+++ b/ui/src/user/UserEdit.jsx
@@ -3,7 +3,6 @@ import { makeStyles } from '@material-ui/core/styles'
 import {
   TextInput,
   BooleanInput,
-  DateField,
   PasswordInput,
   Edit,
   required,
@@ -21,7 +20,7 @@ import {
   useRecordContext,
 } from 'react-admin'
 import { Typography } from '@material-ui/core'
-import { Title } from '../common'
+import { ReadOnlyDateField, Title } from '../common'
 import DeleteUserButton from './DeleteUserButton'
 import { LibrarySelectionField } from './LibrarySelectionField.jsx'
 import { validateUserForm } from './userValidation'
@@ -183,10 +182,10 @@ const UserEdit = (props) => {
           helperText={translate('resources.user.helperTexts.scrobbleFilter')}
         />
 
-        <DateField variant="body1" source="lastLoginAt" showTime />
-        <DateField variant="body1" source="lastAccessAt" showTime />
-        <DateField variant="body1" source="updatedAt" showTime />
-        <DateField variant="body1" source="createdAt" showTime />
+        <ReadOnlyDateField source="lastLoginAt" />
+        <ReadOnlyDateField source="lastAccessAt" />
+        <ReadOnlyDateField source="updatedAt" />
+        <ReadOnlyDateField source="createdAt" />
       </SimpleForm>
     </Edit>
   )
diff --git a/ui/src/user/UserEdit.test.jsx b/ui/src/user/UserEdit.test.jsx
index 74405cc13..837b25ad6 100644
--- a/ui/src/user/UserEdit.test.jsx
+++ b/ui/src/user/UserEdit.test.jsx
@@ -51,9 +51,6 @@ vi.mock('react-admin', () => ({
   BooleanInput: ({ source }) => (
     <input type="checkbox" data-testid={`boolean-input-${source}`} />
   ),
-  DateField: ({ source }) => (
-    <div data-testid={`date-field-${source}`}>Date</div>
-  ),
   PasswordInput: ({ source }) => (
     <input type="password" data-testid={`password-input-${source}`} />
   ),
@@ -82,6 +79,9 @@ vi.mock('./DeleteUserButton', () => ({
 
 vi.mock('../common', () => ({
   Title: ({ subTitle }) => <div data-testid="title">{subTitle}</div>,
+  ReadOnlyDateField: ({ source }) => (
+    <div data-testid={`date-field-${source}`}>Date</div>
+  ),
 }))
 
 // Mock Material-UI

From a62d1629f0ff56208460f17aa407b44a41569f0c Mon Sep 17 00:00:00 2001
From: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date: Mon, 28 Sep 2026 15:06:44 -0700
Subject: [PATCH 193/200] fix(ui): honor EnableCoverAnimation for theme cover
 animations (#6234)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: honor cover animation setting in Squiddies Glass

Fixes #5170

* fix(ui): move cover animation check into AlbumDetails

Apply a noCoverAnimation class from AlbumDetails when
enableCoverAnimation is off, so every theme gets the fix. Drop the
Squiddies Glass theme changes and its test, and cover the class in
AlbumDetails.test.jsx.

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
---
 ui/src/album/AlbumDetails.jsx      | 11 ++++-
 ui/src/album/AlbumDetails.test.jsx | 70 +++++++++++++++++++++++++++++-
 2 files changed, 79 insertions(+), 2 deletions(-)

diff --git a/ui/src/album/AlbumDetails.jsx b/ui/src/album/AlbumDetails.jsx
index 7fbc479db..8d636a047 100644
--- a/ui/src/album/AlbumDetails.jsx
+++ b/ui/src/album/AlbumDetails.jsx
@@ -16,6 +16,7 @@ import {
   useRecordContext,
   useTranslate,
 } from 'react-admin'
+import clsx from 'clsx'
 import Lightbox from 'react-image-lightbox'
 import config from '../config'
 import 'react-image-lightbox/style.css'
@@ -79,6 +80,9 @@ const useStyles = makeStyles(
       alignItems: 'center',
       justifyContent: 'center',
     },
+    noCoverAnimation: {
+      '&, &::before, &::after': { animation: 'none' },
+    },
     cover: {
       objectFit: 'contain',
       cursor: 'pointer',
@@ -250,7 +254,12 @@ const AlbumDetails = (props) => {
   return (
     <Card className={classes.root}>
       <div className={classes.cardContents}>
-        <div className={classes.coverParent}>
+        <div
+          className={clsx(
+            classes.coverParent,
+            !config.enableCoverAnimation && classes.noCoverAnimation,
+          )}
+        >
           <Artwork
             record={record}
             fit="contain"
diff --git a/ui/src/album/AlbumDetails.test.jsx b/ui/src/album/AlbumDetails.test.jsx
index 484045444..afc4bf0a0 100644
--- a/ui/src/album/AlbumDetails.test.jsx
+++ b/ui/src/album/AlbumDetails.test.jsx
@@ -3,7 +3,29 @@ import { describe, test, expect, beforeEach, afterEach } from 'vitest'
 import { render } from '@testing-library/react'
 import { RecordContextProvider } from 'react-admin'
 import { useMediaQuery } from '@material-ui/core'
-import { Details } from './AlbumDetails'
+import { createTheme, ThemeProvider } from '@material-ui/core/styles'
+import config from '../config'
+import AlbumDetails, { Details } from './AlbumDetails'
+
+vi.mock('../subsonic', () => ({
+  default: {
+    getAlbumInfo: () =>
+      Promise.resolve({
+        json: { 'subsonic-response': { status: 'ok', albumInfo: {} } },
+      }),
+    getCoverArtUrl: () => '',
+  },
+}))
+
+vi.mock('react-admin', async () => {
+  const actual = await vi.importActual('react-admin')
+  return {
+    ...actual,
+    useDataProvider: () => ({ getOne: vi.fn() }),
+    useNotify: () => vi.fn(),
+    useRefresh: () => vi.fn(),
+  }
+})
 
 // Mock useMediaQuery
 vi.mock('@material-ui/core', async () => {
@@ -343,3 +365,49 @@ describe('Details component', () => {
     })
   })
 })
+
+describe('AlbumDetails cover animation', () => {
+  const albumRecord = {
+    id: '123',
+    name: 'Test Album',
+    songCount: 12,
+    duration: 3600,
+    size: 102400,
+  }
+  const originalEnableCoverAnimation = config.enableCoverAnimation
+
+  beforeEach(() => {
+    vi.mocked(useMediaQuery).mockReturnValue(false)
+  })
+
+  afterEach(() => {
+    config.enableCoverAnimation = originalEnableCoverAnimation
+  })
+
+  const renderAlbum = () =>
+    render(
+      <ThemeProvider theme={createTheme()}>
+        <RecordContextProvider value={albumRecord}>
+          <AlbumDetails />
+        </RecordContextProvider>
+      </ThemeProvider>,
+    )
+
+  test('applies noCoverAnimation when enableCoverAnimation is false', () => {
+    config.enableCoverAnimation = false
+    const { container } = renderAlbum()
+    const cover = container.querySelector('[class*="coverParent"]')
+
+    expect(cover).not.toBeNull()
+    expect(cover.className).toMatch(/noCoverAnimation/)
+  })
+
+  test('omits noCoverAnimation when enableCoverAnimation is true', () => {
+    config.enableCoverAnimation = true
+    const { container } = renderAlbum()
+    const cover = container.querySelector('[class*="coverParent"]')
+
+    expect(cover).not.toBeNull()
+    expect(cover.className).not.toMatch(/noCoverAnimation/)
+  })
+})

From 3a31f702b529fe3d9843894e024d3a0316c11650 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Dav=C3=B3?= <david@ddavo.me>
Date: Tue, 29 Sep 2026 04:50:13 +0200
Subject: [PATCH 194/200] feat(ui): add played filter to album list (#6207)

---
 persistence/album_repository.go      |  1 +
 persistence/album_repository_test.go | 74 ++++++++++++++++++++++++++++
 persistence/sql_annotations_test.go  |  2 +
 ui/src/album/AlbumList.jsx           |  1 +
 ui/src/i18n/en.json                  |  3 +-
 5 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/persistence/album_repository.go b/persistence/album_repository.go
index 8e7662b8f..6a940a320 100644
--- a/persistence/album_repository.go
+++ b/persistence/album_repository.go
@@ -131,6 +131,7 @@ var albumFilters = sync.OnceValue(func() map[string]filterFunc {
 		"recently_played": recentlyPlayedFilter,
 		"starred":         annotationBoolFilter("starred"),
 		"has_rating":      annotationBoolFilter("rating"),
+		"played":          annotationBoolFilter("play_count"),
 		"missing":         booleanFilter,
 		"genre_id":        genreFilter(AlbumGenres),
 		"role_total_id":   allRolesFilter,
diff --git a/persistence/album_repository_test.go b/persistence/album_repository_test.go
index 7652e703d..0235805c0 100644
--- a/persistence/album_repository_test.go
+++ b/persistence/album_repository_test.go
@@ -417,6 +417,80 @@ var _ = Describe("AlbumRepository", func() {
 				}
 			})
 		})
+
+		Describe("played", func() {
+			var playedAlbum model.Album
+
+			BeforeEach(func() {
+				playedAlbum = model.Album{ID: "played-album", Name: "Played Album", LibraryID: 1, SongCount: 1}
+				Expect(albumRepo.Put(ctx, &playedAlbum)).To(Succeed())
+				Expect(albumRepo.IncPlayCount(ctx, playedAlbum.ID, time.Now())).To(Succeed())
+			})
+
+			AfterEach(func() {
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("annotation").Where(squirrel.Eq{"item_id": playedAlbum.ID}))
+				_, _ = albumRepo.executeSQL(ctx, squirrel.Delete("album").Where(squirrel.Eq{"id": playedAlbum.ID}))
+			})
+
+			It("false includes items without annotations", func() {
+				res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
+					Filters: map[string]any{"played": "false"},
+				})
+				Expect(err).ToNot(HaveOccurred())
+				albums := res
+
+				var found bool
+				for _, a := range albums {
+					if a.ID == albumWithoutAnnotation.ID {
+						found = true
+						break
+					}
+				}
+				Expect(found).To(BeTrue(), "Album without annotation should be included in played=false filter")
+			})
+
+			It("true excludes items without annotations", func() {
+				res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
+					Filters: map[string]any{"played": "true"},
+				})
+				Expect(err).ToNot(HaveOccurred())
+				albums := res
+
+				for _, a := range albums {
+					Expect(a.ID).ToNot(Equal(albumWithoutAnnotation.ID))
+				}
+			})
+
+			It("true includes items with play count", func() {
+				res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
+					Filters: map[string]any{"played": "true"},
+				})
+				Expect(err).ToNot(HaveOccurred())
+				albums := res
+
+				var found bool
+				for _, a := range albums {
+					if a.ID == playedAlbum.ID {
+						found = true
+						Expect(a.PlayCount).To(BeNumerically(">", 0))
+						break
+					}
+				}
+				Expect(found).To(BeTrue(), "Album with play count should be included in played=true filter")
+			})
+
+			It("false excludes items with play count", func() {
+				res, err := albumRepo.ReadAll(ctx, rest.QueryOptions{
+					Filters: map[string]any{"played": "false"},
+				})
+				Expect(err).ToNot(HaveOccurred())
+				albums := res
+
+				for _, a := range albums {
+					Expect(a.ID).ToNot(Equal(playedAlbum.ID))
+				}
+			})
+		})
 	})
 
 	Describe("Album.PlayCount", func() {
diff --git a/persistence/sql_annotations_test.go b/persistence/sql_annotations_test.go
index ec28c610a..6761331d9 100644
--- a/persistence/sql_annotations_test.go
+++ b/persistence/sql_annotations_test.go
@@ -91,6 +91,8 @@ var _ = Describe("Annotation Filters", func() {
 			Entry("starred=false", "starred", "false", "COALESCE(starred, 0) = 0", []any(nil)),
 			Entry("starred=True (case insensitive)", "starred", "True", "COALESCE(starred, 0) > 0", []any(nil)),
 			Entry("rating=true", "rating", "true", "COALESCE(rating, 0) > 0", []any(nil)),
+			Entry("play_count=true", "play_count", "true", "COALESCE(play_count, 0) > 0", []any(nil)),
+			Entry("play_count=false", "play_count", "false", "COALESCE(play_count, 0) = 0", []any(nil)),
 		)
 
 		It("returns nil if value is not a string", func() {
diff --git a/ui/src/album/AlbumList.jsx b/ui/src/album/AlbumList.jsx
index 3cb8a648e..81e4dcd14 100644
--- a/ui/src/album/AlbumList.jsx
+++ b/ui/src/album/AlbumList.jsx
@@ -163,6 +163,7 @@ const AlbumFilter = (props) => {
         />
       </ReferenceInput>
       <NullableBooleanInput source="compilation" />
+      <NullableBooleanInput source="played" defaultValue={false} />
       <NumberInput source="year" />
       {config.enableFavourites && (
         <NullableBooleanInput
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index 851b47ee3..a04b6e311 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -83,7 +83,8 @@
         "grouping": "Grouping",
         "media": "Media",
         "mood": "Mood",
-        "missing": "Missing"
+        "missing": "Missing",
+        "played": "Played"
       },
       "actions": {
         "playAll": "Play",

From e03ce871773c434b95ec2a623243c6397df160f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 29 Sep 2026 11:21:14 -0400
Subject: [PATCH 195/200] fix(ui): make Undo and AMusic Save buttons readable
 (#6249)

---
 ui/src/layout/Notification.jsx | 25 ++++++++++++++++++++-----
 ui/src/themes/amusic.js        | 15 +++++++++++++++
 ui/src/themes/nuclear.js       |  7 +++++++
 3 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/ui/src/layout/Notification.jsx b/ui/src/layout/Notification.jsx
index 001d3fc01..ff641ec22 100644
--- a/ui/src/layout/Notification.jsx
+++ b/ui/src/layout/Notification.jsx
@@ -1,11 +1,26 @@
 import React from 'react'
 import { Notification as RANotification } from 'react-admin'
+import { makeStyles } from '@material-ui/core/styles'
 
-const Notification = (props) => (
-  <RANotification
-    {...props}
-    anchorOrigin={{ vertical: 'top', horizontal: 'center' }}
-  />
+// RA's primary.light Undo is unreadable on the light snackbar of dark themes
+const useStyles = makeStyles(
+  {
+    undo: {
+      color: 'inherit',
+    },
+  },
+  { name: 'NDNotification' },
 )
 
+const Notification = (props) => {
+  const classes = useStyles()
+  return (
+    <RANotification
+      {...props}
+      classes={{ undo: classes.undo }}
+      anchorOrigin={{ vertical: 'top', horizontal: 'center' }}
+    />
+  )
+}
+
 export default Notification
diff --git a/ui/src/themes/amusic.js b/ui/src/themes/amusic.js
index 55205baf3..eef7f90d6 100644
--- a/ui/src/themes/amusic.js
+++ b/ui/src/themes/amusic.js
@@ -79,6 +79,16 @@ export default {
         color: '#eee',
         backgroundColor: '#ff4e6b',
       },
+      containedPrimary: {
+        color: '#fff',
+        backgroundColor: '#D60017',
+        '&:hover': {
+          backgroundColor: '#a30011',
+          '@media (hover: none)': {
+            backgroundColor: '#D60017',
+          },
+        },
+      },
       textSizeSmall: {
         fontSize: '0.8rem',
         paddingRight: '0.5rem',
@@ -192,6 +202,11 @@ export default {
         paddingBottom: '1rem',
       },
     },
+    NDNotification: {
+      undo: {
+        color: '#fff',
+      },
+    },
     RaConfirm: {
       confirmPrimary: {
         color: '#fff',
diff --git a/ui/src/themes/nuclear.js b/ui/src/themes/nuclear.js
index b34896c97..bf804139e 100644
--- a/ui/src/themes/nuclear.js
+++ b/ui/src/themes/nuclear.js
@@ -86,6 +86,13 @@ export default {
         },
       },
     },
+    NDNotification: {
+      undo: {
+        '& .MuiButton-label': {
+          color: 'inherit',
+        },
+      },
+    },
     MuiChip: {
       root: {
         backgroundColor: nukeCol['accent'],

From 0e1893530b844898cbf87825fdefd4b13e1ff3cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 29 Sep 2026 13:23:36 -0400
Subject: [PATCH 196/200] fix(ui): don't crash the playlist list when rows lose
 their record (#6250)

* fix(ui): don't crash playlist list rows that lost their record

react-admin 3 evicts records fetched more than 10 minutes ago whenever
another getList for the same resource completes, but the list keeps its
cached ids. The Datagrid then renders those rows with an undefined record,
and the Public and Auto-import switches crashed reading record.id. This
happened when the playlist list was left open and the sidebar or the add
to playlist dialog reloaded a smaller set of playlists.

Both switches now render nothing when the row has no record; the next list
refresh fills the row in again.

* refactor(ui): merge playlist list toggles into one ToggleField

The Public and Auto-import switches were copies that differed only in the
field they flip. ToggleField now flips its source field, and
ToggleAutoImport just shows it for playlists that have a file path. The
tests render inside TestContext, so they use react-admin's real hooks
instead of mocks.
---
 ui/src/playlist/PlaylistList.jsx      | 46 ++++++---------------------
 ui/src/playlist/PlaylistList.test.jsx | 25 ++++++++++++++-
 2 files changed, 34 insertions(+), 37 deletions(-)

diff --git a/ui/src/playlist/PlaylistList.jsx b/ui/src/playlist/PlaylistList.jsx
index d2b17b108..14d819a4e 100644
--- a/ui/src/playlist/PlaylistList.jsx
+++ b/ui/src/playlist/PlaylistList.jsx
@@ -67,15 +67,15 @@ const PlaylistFilter = (props) => {
   )
 }
 
-const TogglePublicInput = ({ resource, source }) => {
+export const ToggleField = ({ resource, source }) => {
   const record = useRecordContext()
   const notify = useNotify()
-  const [togglePublic] = useUpdate(
+  const [toggle] = useUpdate(
     resource,
-    record.id,
+    record?.id,
     {
       ...record,
-      public: !record.public,
+      [source]: !record?.[source],
     },
     {
       undoable: false,
@@ -86,10 +86,12 @@ const TogglePublicInput = ({ resource, source }) => {
   )
 
   const handleClick = (e) => {
-    togglePublic()
+    toggle()
     e.stopPropagation()
   }
 
+  if (!record) return null
+
   return (
     <Switch
       checked={record[source]}
@@ -99,35 +101,9 @@ const TogglePublicInput = ({ resource, source }) => {
   )
 }
 
-const ToggleAutoImport = ({ resource, source }) => {
+export const ToggleAutoImport = (props) => {
   const record = useRecordContext()
-  const notify = useNotify()
-  const [ToggleAutoImport] = useUpdate(
-    resource,
-    record.id,
-    {
-      ...record,
-      sync: !record.sync,
-    },
-    {
-      undoable: false,
-      onFailure: (error) => {
-        notify('ra.page.error', 'warning')
-      },
-    },
-  )
-  const handleClick = (e) => {
-    ToggleAutoImport()
-    e.stopPropagation()
-  }
-
-  return record.path ? (
-    <Switch
-      checked={record[source]}
-      onClick={handleClick}
-      disabled={!isWritable(record.ownerId)}
-    />
-  ) : null
+  return record?.path ? <ToggleField {...props} /> : null
 }
 
 const PlaylistListBulkActions = (props) => {
@@ -169,9 +145,7 @@ const PlaylistList = (props) => {
       updatedAt: isDesktop && (
         <DateField source="updatedAt" sortByOrder={'DESC'} />
       ),
-      public: !isXsmall && (
-        <TogglePublicInput source="public" sortByOrder={'DESC'} />
-      ),
+      public: !isXsmall && <ToggleField source="public" sortByOrder={'DESC'} />,
       comment: <TextField source="comment" />,
       sync: !isXsmall && (
         <ToggleAutoImport source="sync" sortByOrder={'DESC'} />
diff --git a/ui/src/playlist/PlaylistList.test.jsx b/ui/src/playlist/PlaylistList.test.jsx
index 4fbc6d516..6c714b827 100644
--- a/ui/src/playlist/PlaylistList.test.jsx
+++ b/ui/src/playlist/PlaylistList.test.jsx
@@ -1,7 +1,8 @@
 import React from 'react'
 import { render, screen } from '@testing-library/react'
 import { describe, it, expect, vi } from 'vitest'
-import { PlaylistLove } from './PlaylistList'
+import { TestContext } from 'ra-test'
+import { PlaylistLove, ToggleField, ToggleAutoImport } from './PlaylistList'
 
 vi.mock('../config', () => ({
   default: { enableFavourites: true },
@@ -32,3 +33,25 @@ describe('<PlaylistLove />', () => {
     })
   })
 })
+
+// react-admin evicts records older than 10 minutes while the list still holds
+// their ids, so rows can render with no record.
+describe('playlist toggles without a record', () => {
+  it('<ToggleField /> renders nothing', () => {
+    const { container } = render(
+      <TestContext>
+        <ToggleField resource="playlist" source="public" />
+      </TestContext>,
+    )
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('<ToggleAutoImport /> renders nothing', () => {
+    const { container } = render(
+      <TestContext>
+        <ToggleAutoImport resource="playlist" source="sync" />
+      </TestContext>,
+    )
+    expect(container.innerHTML).toBe('')
+  })
+})

From 758e64c9996e6aa01e8428fb587292873f9f181f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Fri, 2 Oct 2026 05:05:32 -0400
Subject: [PATCH 197/200] feat(scanner): per-library PID configuration (#6252)

* feat(model): add per-library PID config columns

* refactor(metadata): pass PID config to ToMediaFile and add spec validation

* feat(scanner): rescan only libraries whose PID config changed

* feat(server): validate library PID config and rescan on change

* feat(ui): edit per-library PID config

* fix(ui): label the PID mode selects

* fix: tighten per-library PID rescan edge cases

An interrupted PID rescan no longer upgrades every library to a full scan, a save that loses the race for the scanner logs at debug, the confirm dialog only shows when the effective PID spec changes, and it now gets translation keys.

* refactor(metadata): pass the library to ToMediaFile

ToMediaFile and core.Inspect took the library ID and its PID config as
separate arguments, so a caller could mix values from two libraries. They
now take the model.Library and resolve the effective PID config from it.

* chore: tidy per-library PID comments, PropTypes and migration

Trim comments that restated the code, add PropTypes to the new UI
components, and recreate the migration with make migration-sql.

* fix(ui): show the PID spec help under its input

* feat(cmd): make inspect use the file's library PID config

inspect always used the global PID config, so it showed different IDs than
the scanner for files in a library with an override. It now finds the
file's library in the DB and uses its effective config, falling back to
the global config when there is no DB or the file is outside every
library. It never creates a DB. The library path matcher moves from
core/playlists to model so both can use it.

* refactor: simplify per-library PID code

Share the DB-file check between CLI commands, move ErrAlreadyScanning to
model so core no longer imports scanner, read the libraries once for
insights, and let ValidatePIDSpec accept an empty spec and look tags up
directly. In the scanner, use FullScanInProgress instead of a second
flag, and skip recomputing album IDs when the album spec did not change.
In the UI, share the PID inputs between Create and Edit, and use docsUrl.

* feat(ui): add section titles to Library Create and pre-fill Custom PID specs

Custom now starts from the global spec, so admins edit a working spec
instead of typing one from scratch.

* fix(inspect): map files with the library-relative path the scanner uses

Inspect gave metadata the file's directory as typed, so folder-based PIDs
never matched the DB. It now uses the path relative to the library root,
through the scanner's helper, which moves to model.

* fix(scanner): say when a PID rescan only covers target folders

* fix: reject tag aliases in album PID specs and match root libraries

Tags are stored under canonical names, so an alias in a spec always reads
as empty. In an album spec that gives every album the same ID, so album
specs now require the tag name. Track specs keep accepting aliases, since
the default one uses them. LibraryMatcher now matches paths under a
library at the filesystem root.

* refactor(model): move the tag alias lookup to tag_mappings.go

* test: run the library matcher and inspect tests on Windows

Build test paths with filepath instead of Unix literals, so they use the
OS separator like filepath.Abs output, and drop the Windows skips.

* feat(ui): add pt-BR translations for per-library PID settings
---
 adapters/gotaglib/end_to_end_test.go          |   2 +-
 cmd/inspect.go                                |  46 +++-
 cmd/inspect_test.go                           |  61 +++++
 cmd/root.go                                   |  28 ++-
 cmd/root_test.go                              |  30 +++
 cmd/utils.go                                  |  13 +-
 consts/consts.go                              |   2 -
 core/inspect.go                               |  16 +-
 core/inspect_test.go                          |  45 ++++
 core/library.go                               |  54 ++++-
 core/library_test.go                          |  73 ++++++
 core/metrics/insights.go                      |   9 +-
 core/playlists/import.go                      |   4 +-
 core/playlists/parse_m3u.go                   |  70 +-----
 core/playlists/parse_m3u_test.go              | 181 --------------
 ...20260929221042_add_library_pid_columns.sql |  18 ++
 model/library.go                              |  37 +++
 model/library_matcher.go                      |  57 +++++
 model/library_matcher_test.go                 |  91 +++++++
 model/library_test.go                         |  73 ++++++
 model/metadata/map_mediafile.go               |  10 +-
 model/metadata/map_mediafile_test.go          |  16 +-
 model/metadata/map_participants_test.go       |   2 +-
 model/metadata/metadata_test.go               |   2 +-
 model/metadata/persistent_ids.go              |  55 ++++-
 model/metadata/persistent_ids_test.go         |  54 ++++-
 model/scanner.go                              |   3 +
 model/tag_mappings.go                         |  22 ++
 model/tag_mappings_test.go                    |  19 ++
 persistence/library_repository.go             |  11 +
 persistence/library_repository_test.go        |  32 +++
 resources/i18n/pt-br.json                     |  19 +-
 scanner/controller.go                         |   8 +-
 scanner/controller_test.go                    |  12 +-
 scanner/phase_1_folders.go                    |  73 +++---
 scanner/scanner.go                            |  55 ++---
 scanner/scanner_internal_test.go              |  39 ---
 scanner/scanner_multilibrary_test.go          | 166 +++++++++++++
 server/nativeapi/inspect.go                   |   7 +-
 server/serve_index.go                         |   2 +
 server/serve_index_test.go                    |   2 +
 tests/mock_library_repo.go                    |  11 +
 ui/src/config.js                              |   2 +
 ui/src/i18n/en.json                           |  19 +-
 ui/src/library/LibraryCreate.jsx              |  31 +++
 ui/src/library/LibraryEdit.jsx                | 222 +++++++++++-------
 ui/src/library/LibraryEdit.test.jsx           | 125 ++++++++++
 ui/src/library/PIDInput.jsx                   | 114 +++++++++
 ui/src/library/pidPresets.js                  |  33 +++
 ui/src/library/pidPresets.test.js             |  65 +++++
 50 files changed, 1626 insertions(+), 515 deletions(-)
 create mode 100644 cmd/inspect_test.go
 create mode 100644 core/inspect_test.go
 create mode 100644 db/migrations/20260929221042_add_library_pid_columns.sql
 create mode 100644 model/library_matcher.go
 create mode 100644 model/library_matcher_test.go
 create mode 100644 model/library_test.go
 create mode 100644 ui/src/library/LibraryEdit.test.jsx
 create mode 100644 ui/src/library/PIDInput.jsx
 create mode 100644 ui/src/library/pidPresets.js
 create mode 100644 ui/src/library/pidPresets.test.js

diff --git a/adapters/gotaglib/end_to_end_test.go b/adapters/gotaglib/end_to_end_test.go
index e7dd18ac1..0f9a90d94 100644
--- a/adapters/gotaglib/end_to_end_test.go
+++ b/adapters/gotaglib/end_to_end_test.go
@@ -90,7 +90,7 @@ var _ = Describe("Extractor", func() {
 		info.FileInfo = testFileInfo{FileInfo: fileInfo}
 
 		metadata := metadata.New(path, info)
-		return new(metadata.ToMediaFile(1, "folderID"))
+		return new(metadata.ToMediaFile(model.Library{ID: 1}, "folderID"))
 	}
 
 	BeforeEach(func() {
diff --git a/cmd/inspect.go b/cmd/inspect.go
index 5e88793cc..05f569f3e 100644
--- a/cmd/inspect.go
+++ b/cmd/inspect.go
@@ -1,13 +1,17 @@
 package cmd
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
+	"path/filepath"
 	"strings"
 
 	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/persistence"
 	"github.com/pelletier/go-toml/v2"
 	"github.com/spf13/cobra"
 	"gopkg.in/yaml.v3"
@@ -28,7 +32,7 @@ var inspectCmd = &cobra.Command{
 	Long:  "Show file tags as seen by Navidrome",
 	Args:  cobra.MinimumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
-		runInspector(args)
+		runInspector(cmd.Context(), args)
 	},
 }
 
@@ -55,18 +59,24 @@ func prettyMarshal(v any) ([]byte, error) {
 	return []byte(res.String()), nil
 }
 
-func runInspector(args []string) {
+func runInspector(ctx context.Context, args []string) {
 	marshal := marshalers[format]
 	if marshal == nil {
 		log.Fatal("Invalid format", "format", format)
 	}
+	libs := loadLibraries(ctx)
+	matcher := model.NewLibraryMatcher(libs)
 	var out []core.InspectOutput
 	for _, filePath := range args {
 		if !model.IsAudioFile(filePath) {
 			log.Warn("Not an audio file", "file", filePath)
 			continue
 		}
-		output, err := core.Inspect(filePath, 1, "")
+		lib, ok := libraryForFile(matcher, filePath)
+		if !ok && len(libs) > 0 {
+			log.Warn("File is not in any library, using the global PID config", "file", filePath)
+		}
+		output, err := core.Inspect(filePath, lib, "")
 		if err != nil {
 			log.Warn("Unable to process file", "file", filePath, "error", err)
 			continue
@@ -77,3 +87,33 @@ func runInspector(args []string) {
 	data, _ := marshal(out)
 	fmt.Println(string(data))
 }
+
+// loadLibraries reads the libraries, so each file gets its library's PID config. It never creates a DB.
+func loadLibraries(ctx context.Context) model.Libraries {
+	if dbFile, ok := existingDBFile(); !ok {
+		log.Warn(ctx, "No database found, using the global PID config", "path", dbFile)
+		return nil
+	}
+	defer db.Init(ctx)()
+	libs, err := persistence.New(db.Db()).Library().GetAll(ctx)
+	if err != nil {
+		log.Warn(ctx, "Could not load libraries, using the global PID config", err)
+		return nil
+	}
+	for i := range libs {
+		if absPath, err := filepath.Abs(libs[i].Path); err == nil {
+			libs[i].Path = absPath
+		}
+	}
+	return libs
+}
+
+// libraryForFile falls back to the default library with no overrides, which uses the global PID config.
+func libraryForFile(matcher *model.LibraryMatcher, filePath string) (model.Library, bool) {
+	if absPath, err := filepath.Abs(filePath); err == nil {
+		if lib, ok := matcher.FindLibrary(absPath); ok {
+			return lib, true
+		}
+	}
+	return model.Library{ID: model.DefaultLibraryID}, false
+}
diff --git a/cmd/inspect_test.go b/cmd/inspect_test.go
new file mode 100644
index 000000000..728dc8770
--- /dev/null
+++ b/cmd/inspect_test.go
@@ -0,0 +1,61 @@
+package cmd
+
+import (
+	"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("inspect", func() {
+	Describe("libraryForFile", func() {
+		var matcher *model.LibraryMatcher
+		var root string
+
+		BeforeEach(func() {
+			root = GinkgoT().TempDir()
+			cwd, err := os.Getwd()
+			Expect(err).ToNot(HaveOccurred())
+			matcher = model.NewLibraryMatcher(model.Libraries{
+				{ID: 1, Path: filepath.Join(root, "music")},
+				{ID: 2, Path: filepath.Join(cwd, "loose"), PIDAlbum: "folder"},
+			})
+		})
+
+		It("returns the library that contains an absolute path", func() {
+			lib, ok := libraryForFile(matcher, filepath.Join(root, "music", "album", "track.mp3"))
+			Expect(ok).To(BeTrue())
+			Expect(lib.ID).To(Equal(1))
+		})
+
+		It("resolves a relative path against the working directory", func() {
+			lib, ok := libraryForFile(matcher, filepath.Join("loose", "track.mp3"))
+			Expect(ok).To(BeTrue())
+			Expect(lib.PIDAlbum).To(Equal("folder"))
+		})
+
+		It("falls back to the default library without overrides", func() {
+			lib, ok := libraryForFile(matcher, filepath.Join(root, "elsewhere", "track.mp3"))
+			Expect(ok).To(BeFalse())
+			Expect(lib).To(Equal(model.Library{ID: model.DefaultLibraryID}))
+		})
+	})
+
+	Describe("loadLibraries", func() {
+		BeforeEach(func() {
+			DeferCleanup(configtest.SetupConfig())
+		})
+
+		It("does not create a database when there is none", func() {
+			dbFile := filepath.Join(GinkgoT().TempDir(), "navidrome.db")
+			conf.Server.DbPath = dbFile + "?_journal_mode=WAL"
+
+			Expect(loadLibraries(GinkgoT().Context())).To(BeNil())
+			Expect(dbFile).ToNot(BeAnExistingFile())
+		})
+	})
+})
diff --git a/cmd/root.go b/cmd/root.go
index 089f09472..e39c55365 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -190,16 +190,20 @@ func schedulePeriodicScan(ctx context.Context) func() error {
 	}
 }
 
-func pidHashChanged(ds model.DataStore) (bool, error) {
-	pidAlbum, err := ds.Property().DefaultGet(context.Background(), consts.PIDAlbumKey, "")
+// librariesWithChangedPID returns the names of the libraries whose effective PID config differs from
+// the one used by their last finished scan
+func librariesWithChangedPID(ctx context.Context, ds model.DataStore) ([]string, error) {
+	libs, err := ds.Library().GetAll(ctx)
 	if err != nil {
-		return false, err
+		return nil, err
 	}
-	pidTrack, err := ds.Property().DefaultGet(context.Background(), consts.PIDTrackKey, "")
-	if err != nil {
-		return false, err
+	var names []string
+	for _, lib := range libs {
+		if lib.PIDChanged() {
+			names = append(names, lib.Name)
+		}
 	}
-	return !strings.EqualFold(pidAlbum, conf.Server.PID.Album) || !strings.EqualFold(pidTrack, conf.Server.PID.Track), nil
+	return names, nil
 }
 
 // runInitialScan runs an initial scan of the music library if needed.
@@ -214,12 +218,12 @@ func runInitialScan(ctx context.Context) func() error {
 		if err != nil {
 			return err
 		}
-		pidHasChanged, err := pidHashChanged(ds)
+		pidChangedLibs, err := librariesWithChangedPID(ctx, ds)
 		if err != nil {
 			return err
 		}
 		scanOnStartup := conf.Server.Scanner.Enabled && conf.Server.Scanner.ScanOnStartup
-		scanNeeded := scanOnStartup || inProgress || fullScanRequired == "1" || pidHasChanged
+		scanNeeded := scanOnStartup || inProgress || fullScanRequired == "1" || len(pidChangedLibs) > 0
 		time.Sleep(2 * time.Second) // Wait 2 seconds before the initial scan
 		if scanNeeded {
 			s := CreateScanner(ctx)
@@ -227,9 +231,9 @@ func runInitialScan(ctx context.Context) func() error {
 			case fullScanRequired == "1":
 				log.Warn(ctx, "Full scan required after migration")
 				_ = ds.Property().Delete(ctx, consts.FullScanAfterMigrationFlagKey)
-			case pidHasChanged:
-				log.Warn(ctx, "PID config changed, performing full scan")
-				fullScanRequired = "1"
+			case len(pidChangedLibs) > 0:
+				// Includes never-scanned libraries. The scanner rescans in full only the ones that need it
+				log.Warn(ctx, "Libraries with a new or changed PID config, scanning", "libraries", pidChangedLibs)
 			case inProgress:
 				log.Warn(ctx, "Resuming interrupted scan")
 			default:
diff --git a/cmd/root_test.go b/cmd/root_test.go
index af8d44e7e..423cd2a8f 100644
--- a/cmd/root_test.go
+++ b/cmd/root_test.go
@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"path"
@@ -9,6 +10,8 @@ import (
 	"github.com/go-chi/chi/v5"
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -44,3 +47,30 @@ var _ = Describe("profilerHandler", func() {
 		Entry("with a trailing-slash BasePath", "/music/"),
 	)
 })
+
+var _ = Describe("librariesWithChangedPID", func() {
+	var ds *tests.MockDataStore
+	var libs *tests.MockLibraryRepo
+
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		libs = &tests.MockLibraryRepo{}
+		ds = &tests.MockDataStore{MockedLibrary: libs}
+	})
+
+	It("returns only the libraries whose PID config changed", func() {
+		pid := model.Library{}.EffectivePID()
+		libs.SetData(model.Libraries{
+			{ID: 1, Name: "Same", ScannedPIDAlbum: pid.Album, ScannedPIDTrack: pid.Track},
+			{ID: 2, Name: "Changed", PIDAlbum: "folder", ScannedPIDAlbum: pid.Album, ScannedPIDTrack: pid.Track},
+			{ID: 3, Name: "Never scanned"},
+		})
+		Expect(librariesWithChangedPID(GinkgoT().Context(), ds)).To(ConsistOf("Changed", "Never scanned"))
+	})
+
+	It("returns the error from the repository", func() {
+		libs.Err = errors.New("db down")
+		_, err := librariesWithChangedPID(GinkgoT().Context(), ds)
+		Expect(err).To(MatchError("db down"))
+	})
+})
diff --git a/cmd/utils.go b/cmd/utils.go
index 72ec67f90..f35a31fb1 100644
--- a/cmd/utils.go
+++ b/cmd/utils.go
@@ -18,11 +18,16 @@ import (
 	"github.com/navidrome/navidrome/persistence"
 )
 
-// requireExistingDB aborts the command when the database file (DbPath minus DSN
-// params) does not exist.
-func requireExistingDB() {
+// existingDBFile returns the database file (DbPath minus DSN params), and whether it exists.
+func existingDBFile() (string, bool) {
 	path, _, _ := strings.Cut(conf.Server.DbPath, "?")
-	if _, err := os.Stat(path); os.IsNotExist(err) {
+	_, err := os.Stat(path)
+	return path, err == nil
+}
+
+// requireExistingDB aborts the command when the database file does not exist.
+func requireExistingDB() {
+	if path, ok := existingDBFile(); !ok {
 		log.Fatal("No existing database", "path", path)
 	}
 }
diff --git a/consts/consts.go b/consts/consts.go
index 9bdac9125..42e9ec42f 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -156,8 +156,6 @@ const (
 	//DefaultAlbumPID = "album_legacy"
 	DefaultAlbumPID = "musicbrainz_albumid|albumartistid,album,albumversion,releasedate"
 	DefaultTrackPID = "musicbrainz_trackid|albumid,discnumber,tracknumber,title"
-	PIDAlbumKey     = "PIDAlbum"
-	PIDTrackKey     = "PIDTrack"
 )
 
 const (
diff --git a/core/inspect.go b/core/inspect.go
index 01ec33760..c60459b88 100644
--- a/core/inspect.go
+++ b/core/inspect.go
@@ -15,7 +15,7 @@ type InspectOutput struct {
 	MappedTags *model.MediaFile `json:"mappedTags,omitempty"`
 }
 
-func Inspect(filePath string, libraryId int, folderId string) (*InspectOutput, error) {
+func Inspect(filePath string, lib model.Library, folderId string) (*InspectOutput, error) {
 	path, file := filepath.Split(filePath)
 
 	s, err := storage.For(path)
@@ -39,12 +39,22 @@ func Inspect(filePath string, libraryId int, folderId string) (*InspectOutput, e
 		return nil, model.ErrNotFound
 	}
 
-	md := metadata.New(path, tag)
+	md := metadata.New(scannerPath(lib, filePath), tag)
 	result := &InspectOutput{
 		File:       filePath,
 		RawTags:    tags[file].Tags,
-		MappedTags: new(md.ToMediaFile(libraryId, folderId)),
+		MappedTags: new(md.ToMediaFile(lib, folderId)),
 	}
 
 	return result, nil
 }
+
+// scannerPath returns the path the scanner uses for the file (relative to its library), so
+// folder-based PIDs match the DB. Files outside the library keep their absolute path.
+func scannerPath(lib model.Library, filePath string) string {
+	absPath, err := filepath.Abs(filePath)
+	if err != nil || lib.Path == "" {
+		return filePath
+	}
+	return model.LibraryRelativePath(lib.Path, absPath)
+}
diff --git a/core/inspect_test.go b/core/inspect_test.go
new file mode 100644
index 000000000..0ac90990c
--- /dev/null
+++ b/core/inspect_test.go
@@ -0,0 +1,45 @@
+package core_test
+
+import (
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Inspect", func() {
+	var fixtures string
+
+	BeforeEach(func() {
+		var err error
+		fixtures, err = filepath.Abs(filepath.Join("tests", "fixtures"))
+		Expect(err).ToNot(HaveOccurred())
+	})
+
+	It("maps the file with the library-relative path the scanner uses", func() {
+		lib := model.Library{ID: 2, Path: filepath.Dir(fixtures), PIDAlbum: "folder"}
+		out, err := core.Inspect(filepath.Join(fixtures, "test.mp3"), lib, "")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(out.MappedTags.Path).To(Equal("fixtures/test.mp3"))
+		Expect(out.MappedTags.LibraryID).To(Equal(2))
+	})
+
+	It("gives the same IDs for relative and absolute paths", func() {
+		lib := model.Library{ID: 2, Path: filepath.Dir(fixtures), PIDAlbum: "folder"}
+		abs, err := core.Inspect(filepath.Join(fixtures, "test.mp3"), lib, "")
+		Expect(err).ToNot(HaveOccurred())
+		rel, err := core.Inspect(filepath.Join("tests", "fixtures", "test.mp3"), lib, "")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(rel.MappedTags.AlbumID).To(Equal(abs.MappedTags.AlbumID))
+		Expect(rel.MappedTags.PID).To(Equal(abs.MappedTags.PID))
+	})
+
+	It("keeps the given path for a file outside the library", func() {
+		filePath := filepath.Join(fixtures, "test.mp3")
+		out, err := core.Inspect(filePath, model.Library{ID: model.DefaultLibraryID}, "")
+		Expect(err).ToNot(HaveOccurred())
+		Expect(out.MappedTags.Path).To(Equal(filePath))
+	})
+})
diff --git a/core/library.go b/core/library.go
index 628ee4b7b..f1153da26 100644
--- a/core/library.go
+++ b/core/library.go
@@ -2,10 +2,12 @@ package core
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
@@ -15,6 +17,7 @@ import (
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/model/metadata"
 	"github.com/navidrome/navidrome/model/request"
 	"github.com/navidrome/navidrome/server/events"
 	"github.com/navidrome/navidrome/utils/slice"
@@ -200,23 +203,22 @@ func (r *libraryRepositoryWrapper) Update(ctx context.Context, id string, entity
 	}
 
 	pathChanged := originalLib.Path != lib.Path
+	pidChanged := (updatesColumn(cols, "pidAlbum") && originalLib.PIDAlbum != lib.PIDAlbum) ||
+		(updatesColumn(cols, "pidTrack") && originalLib.PIDTrack != lib.PIDTrack)
 
 	err = r.LibraryRepository.Put(ctx, lib, cols...)
 	if err != nil {
 		return r.mapError(err)
 	}
 
-	// Restart watcher and trigger scan if path was updated
-	if pathChanged {
-		if r.watcher != nil {
-			if err := r.watcher.Watch(ctx, lib); err != nil {
-				log.Warn(ctx, "Failed to restart watcher for updated library", "libraryID", lib.ID, "name", lib.Name, "path", lib.Path, err)
-			}
+	if pathChanged && r.watcher != nil {
+		if err := r.watcher.Watch(ctx, lib); err != nil {
+			log.Warn(ctx, "Failed to restart watcher for updated library", "libraryID", lib.ID, "name", lib.Name, "path", lib.Path, err)
 		}
+	}
 
-		if r.scanner != nil {
-			go r.triggerScan(ctx, lib, "updated")
-		}
+	if (pathChanged || pidChanged) && r.scanner != nil {
+		go r.triggerScan(ctx, lib, "updated")
 	}
 
 	// Send library refresh event to all clients
@@ -325,6 +327,15 @@ func (r *libraryRepositoryWrapper) validateLibrary(ctx context.Context, library
 		}
 	}
 
+	library.PIDAlbum = strings.TrimSpace(library.PIDAlbum)
+	library.PIDTrack = strings.TrimSpace(library.PIDTrack)
+	if err := metadata.ValidatePIDSpec(library.PIDAlbum, true); err != nil {
+		validationErrors["pidAlbum"] = err.Error()
+	}
+	if err := metadata.ValidatePIDSpec(library.PIDTrack, false); err != nil {
+		validationErrors["pidTrack"] = err.Error()
+	}
+
 	if len(validationErrors) > 0 {
 		return &rest.ValidationError{Errors: validationErrors}
 	}
@@ -332,6 +343,11 @@ func (r *libraryRepositoryWrapper) validateLibrary(ctx context.Context, library
 	return nil
 }
 
+// updatesColumn reports whether an update with these columns writes col. No columns means all of them.
+func updatesColumn(cols []string, col string) bool {
+	return len(cols) == 0 || slices.Contains(cols, col)
+}
+
 func (r *libraryRepositoryWrapper) validateLibraryPath(ctx context.Context, library *model.Library) error {
 	// Validate path format
 	if !filepath.IsAbs(library.Path) {
@@ -399,11 +415,27 @@ func (s *libraryService) validateLibraryIDs(ctx context.Context, libraryIDs []in
 	return nil
 }
 
+var scanWaitInterval = time.Second
+
 func (r *libraryRepositoryWrapper) triggerScan(ctx context.Context, lib *model.Library, action string) {
+	// Runs in its own goroutine and outlives the HTTP request
+	ctx = context.WithoutCancel(ctx)
+
+	// A running scan loaded the libraries before this change, and would reject a new request
+	for {
+		status, err := r.scanner.Status(ctx)
+		if err != nil || !status.Scanning {
+			break
+		}
+		time.Sleep(scanWaitInterval)
+	}
+
 	log.Info(ctx, fmt.Sprintf("Triggering scan for %s library", action), "libraryID", lib.ID, "name", lib.Name, "path", lib.Path)
 	start := time.Now()
-	warnings, err := r.scanner.ScanAll(ctx, false) // Quick scan for new library
-	if err != nil {
+	warnings, err := r.scanner.ScanAll(ctx, false) // Quick scan: the scanner rescans libraries with a changed PID config in full
+	if errors.Is(err, model.ErrAlreadyScanning) {
+		log.Debug(ctx, "Scan already running, it covers this change", "libraryID", lib.ID, "name", lib.Name)
+	} else if err != nil {
 		log.Error(ctx, fmt.Sprintf("Error scanning %s library", action), "libraryID", lib.ID, "name", lib.Name, err)
 	} else {
 		log.Info(ctx, fmt.Sprintf("Scan completed for %s library", action), "libraryID", lib.ID, "name", lib.Name, "warnings", len(warnings), "elapsed", time.Since(start))
diff --git a/core/library_test.go b/core/library_test.go
index 5402eac22..e6ebb1974 100644
--- a/core/library_test.go
+++ b/core/library_test.go
@@ -322,6 +322,37 @@ var _ = Describe("Library Service", func() {
 			})
 		})
 
+		Describe("PID validation", func() {
+			pidError := func(err error, field string) string {
+				var validationErr *rest.ValidationError
+				Expect(errors.As(err, &validationErr)).To(BeTrue())
+				return validationErr.Errors[field]
+			}
+
+			It("rejects an unknown attribute in the album PID", func() {
+				_, err := repo.Save(ctx, &model.Library{Name: "Lib", Path: tempDir, PIDAlbum: "albmversion"})
+				Expect(pidError(err, "pidAlbum")).To(ContainSubstring(`unknown attribute "albmversion"`))
+			})
+
+			It("rejects albumid in the album PID", func() {
+				_, err := repo.Save(ctx, &model.Library{Name: "Lib", Path: tempDir, PIDAlbum: "albumid"})
+				Expect(pidError(err, "pidAlbum")).To(ContainSubstring("albumid"))
+			})
+
+			It("rejects an unknown attribute in the track PID", func() {
+				_, err := repo.Save(ctx, &model.Library{Name: "Lib", Path: tempDir, PIDTrack: "nosuchtag"})
+				Expect(pidError(err, "pidTrack")).To(ContainSubstring(`unknown attribute "nosuchtag"`))
+			})
+
+			It("trims spaces", func() {
+				library := &model.Library{Name: "Lib", Path: tempDir, PIDAlbum: " folder ", PIDTrack: "  "}
+				_, err := repo.Save(ctx, library)
+				Expect(err).ToNot(HaveOccurred())
+				Expect(library.PIDAlbum).To(Equal("folder"))
+				Expect(library.PIDTrack).To(BeEmpty())
+			})
+		})
+
 		Describe("Path Validation", func() {
 			Context("Create operation", func() {
 				It("fails when path is not absolute", func() {
@@ -679,6 +710,48 @@ var _ = Describe("Library Service", func() {
 			}, "100ms", "10ms").Should(Equal(0))
 		})
 
+		It("triggers scan when updating the library PID config", func() {
+			libraryRepo.SetData(model.Libraries{{ID: 1, Name: "Library", Path: tempDir}})
+
+			library := model.Library{ID: 1, Name: "Library", Path: tempDir, PIDAlbum: "folder"}
+			Expect(repo.Update(ctx, "1", library)).To(Succeed())
+
+			Eventually(func() int {
+				return scanner.GetScanAllCallCount()
+			}, "1s", "10ms").Should(Equal(1))
+			// A quick scan: the scanner itself rescans this library in full
+			Expect(scanner.GetScanAllCalls()[0].FullScan).To(BeFalse())
+		})
+
+		It("does not trigger scan when the PID fields were not sent", func() {
+			libraryRepo.SetData(model.Libraries{{ID: 1, Name: "Library", Path: tempDir, PIDAlbum: "folder"}})
+
+			// The REST layer decodes a missing pidAlbum as "". Only the sent fields count.
+			library := model.Library{ID: 1, Name: "Renamed", Path: tempDir}
+			Expect(repo.Update(ctx, "1", library, "name", "path")).To(Succeed())
+
+			Consistently(func() int {
+				return scanner.GetScanAllCallCount()
+			}, "100ms", "10ms").Should(Equal(0))
+		})
+
+		It("waits for a running scan before triggering a new one", func() {
+			libraryRepo.SetData(model.Libraries{{ID: 1, Name: "Library", Path: tempDir}})
+			scanner.SetScanning(true)
+
+			library := model.Library{ID: 1, Name: "Library", Path: tempDir, PIDAlbum: "folder"}
+			Expect(repo.Update(ctx, "1", library)).To(Succeed())
+
+			Consistently(func() int {
+				return scanner.GetScanAllCallCount()
+			}, "200ms", "20ms").Should(Equal(0))
+
+			scanner.SetScanning(false)
+			Eventually(func() int {
+				return scanner.GetScanAllCallCount()
+			}, "3s", "20ms").Should(Equal(1))
+		})
+
 		It("does not trigger scan when library creation fails", func() {
 			// Try to create library with invalid data (empty name)
 			library := &model.Library{Path: tempDir}
diff --git a/core/metrics/insights.go b/core/metrics/insights.go
index 4a78a7f3f..1d2ff5df4 100644
--- a/core/metrics/insights.go
+++ b/core/metrics/insights.go
@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"runtime/debug"
+	"slices"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -269,9 +270,13 @@ func (c *insightsCollector) collect(ctx context.Context) []byte {
 	if err != nil {
 		log.Trace(ctx, "Error reading radios count", err)
 	}
-	data.Library.Libraries, err = c.ds.Library().CountAll(ctx)
+	libs, err := c.ds.Library().GetAll(ctx)
 	if err != nil {
-		log.Trace(ctx, "Error reading libraries count", err)
+		log.Trace(ctx, "Error reading libraries", err)
+	}
+	data.Library.Libraries = int64(len(libs))
+	if slices.ContainsFunc(libs, func(lib model.Library) bool { return lib.PIDAlbum != "" || lib.PIDTrack != "" }) {
+		data.Config.HasCustomPID = true
 	}
 	data.Library.ActiveUsers, err = c.ds.User().CountAll(ctx, model.QueryOptions{
 		Filters: squirrel.Gt{"last_access_at": time.Now().Add(-7 * 24 * time.Hour)},
diff --git a/core/playlists/import.go b/core/playlists/import.go
index 658bd92dc..b5991b095 100644
--- a/core/playlists/import.go
+++ b/core/playlists/import.go
@@ -78,8 +78,8 @@ func (s *playlists) resolveFolder(ctx context.Context, dir string) (*model.Folde
 	if err != nil {
 		return nil, err
 	}
-	matcher := newLibraryMatcher(libs)
-	lib, ok := matcher.findLibrary(dir)
+	matcher := model.NewLibraryMatcher(libs)
+	lib, ok := matcher.FindLibrary(dir)
 	if !ok {
 		return nil, fmt.Errorf("%w: %s", errNotInLibrary, dir)
 	}
diff --git a/core/playlists/parse_m3u.go b/core/playlists/parse_m3u.go
index 9610e9dbb..ab95b8850 100644
--- a/core/playlists/parse_m3u.go
+++ b/core/playlists/parse_m3u.go
@@ -1,13 +1,11 @@
 package playlists
 
 import (
-	"cmp"
 	"context"
 	"fmt"
 	"io"
 	"net/url"
 	"path/filepath"
-	"slices"
 	"strings"
 	"time"
 
@@ -156,61 +154,9 @@ func (r pathResolution) ToQualifiedString() (string, error) {
 	return fmt.Sprintf("%d:%s", r.libraryID, filepath.ToSlash(relativePath)), nil
 }
 
-// libraryMatcher holds sorted libraries with cleaned paths for efficient path matching.
-type libraryMatcher struct {
-	libraries    model.Libraries
-	cleanedPaths []string
-}
-
-// findLibraryForPath finds which library contains the given absolute path.
-// Returns library ID and path, or 0 and empty string if not found.
-func (lm *libraryMatcher) findLibraryForPath(absolutePath string) (int, string) {
-	lib, ok := lm.findLibrary(absolutePath)
-	if !ok {
-		return 0, ""
-	}
-	return lib.ID, filepath.Clean(lib.Path)
-}
-
-// findLibrary checks if the absolute path is under any of the library paths.
-func (lm *libraryMatcher) findLibrary(absolutePath string) (model.Library, bool) {
-	// Check sorted libraries (longest path first) to find the best match
-	for i, cleanLibPath := range lm.cleanedPaths {
-		// Check if absolutePath is under this library path
-		if strings.HasPrefix(absolutePath, cleanLibPath) {
-			// Ensure it's a proper path boundary (not just a prefix)
-			if len(absolutePath) == len(cleanLibPath) || absolutePath[len(cleanLibPath)] == filepath.Separator {
-				return lm.libraries[i], true
-			}
-		}
-	}
-	return model.Library{}, false
-}
-
-// newLibraryMatcher creates a libraryMatcher with libraries sorted by path length (longest first).
-// This ensures correct matching when library paths are prefixes of each other.
-// Example: /music-classical must be checked before /music
-// Otherwise, /music-classical/track.mp3 would match /music instead of /music-classical
-func newLibraryMatcher(libs model.Libraries) *libraryMatcher {
-	// Sort libraries by path length (descending) to ensure longest paths match first.
-	slices.SortFunc(libs, func(i, j model.Library) int {
-		return cmp.Compare(len(j.Path), len(i.Path)) // Reverse order for descending
-	})
-
-	// Pre-clean all library paths once for efficient matching
-	cleanedPaths := make([]string, len(libs))
-	for i, lib := range libs {
-		cleanedPaths[i] = filepath.Clean(lib.Path)
-	}
-	return &libraryMatcher{
-		libraries:    libs,
-		cleanedPaths: cleanedPaths,
-	}
-}
-
 // pathResolver handles path resolution logic for playlist imports.
 type pathResolver struct {
-	matcher *libraryMatcher
+	matcher *model.LibraryMatcher
 }
 
 // newPathResolver creates a pathResolver with libraries loaded from the datastore.
@@ -219,7 +165,7 @@ func newPathResolver(ctx context.Context, ds model.DataStore) (*pathResolver, er
 	if err != nil {
 		return nil, err
 	}
-	matcher := newLibraryMatcher(libs)
+	matcher := model.NewLibraryMatcher(libs)
 	return &pathResolver{matcher: matcher}, nil
 }
 
@@ -246,14 +192,14 @@ func (r *pathResolver) resolvePath(line string, folder *model.Folder) pathResolu
 // a pathResolution with the library information. Returns an invalid resolution if
 // the path is not found in any library.
 func (r *pathResolver) findInLibraries(absolutePath string) pathResolution {
-	libID, libPath := r.matcher.findLibraryForPath(absolutePath)
-	if libID == 0 {
+	lib, ok := r.matcher.FindLibrary(absolutePath)
+	if !ok {
 		return pathResolution{valid: false}
 	}
 	return pathResolution{
 		absolutePath: absolutePath,
-		libraryPath:  libPath,
-		libraryID:    libID,
+		libraryPath:  filepath.Clean(lib.Path),
+		libraryID:    lib.ID,
 		valid:        true,
 	}
 }
@@ -288,7 +234,7 @@ func (r *pathResolver) resolvePaths(ctx context.Context, folder *model.Folder, l
 // HTTP(S) URLs are stored as-is (gated by EnableM3UExternalAlbumArt).
 // Local paths (file://, absolute, or relative) are resolved to an absolute path
 // and validated against known library boundaries via matcher.
-func resolveImageURL(value string, folder *model.Folder, matcher *libraryMatcher, owner model.User) string {
+func resolveImageURL(value string, folder *model.Folder, matcher *model.LibraryMatcher, owner model.User) string {
 	value = strings.TrimSpace(value)
 	if value == "" {
 		return ""
@@ -308,7 +254,7 @@ func resolveImageURL(value string, folder *model.Folder, matcher *libraryMatcher
 		return ""
 	}
 
-	lib, ok := matcher.findLibrary(localPath)
+	lib, ok := matcher.FindLibrary(localPath)
 	// A playlist without a folder (API upload, or CLI import from outside all libraries) may only use the owner's libraries.
 	if !ok || (folder == nil && !owner.HasLibraryAccess(lib.ID)) {
 		return ""
diff --git a/core/playlists/parse_m3u_test.go b/core/playlists/parse_m3u_test.go
index b6a3a96f9..ced6c2b16 100644
--- a/core/playlists/parse_m3u_test.go
+++ b/core/playlists/parse_m3u_test.go
@@ -9,187 +9,6 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-var _ = Describe("libraryMatcher", func() {
-	var ds *tests.MockDataStore
-	var mockLibRepo *tests.MockLibraryRepo
-	ctx := context.Background()
-
-	BeforeEach(func() {
-		tests.SkipOnWindows("path separator bug (#TBD-path-sep-playlists)")
-		mockLibRepo = &tests.MockLibraryRepo{}
-		ds = &tests.MockDataStore{
-			MockedLibrary: mockLibRepo,
-		}
-	})
-
-	// Helper function to create a libraryMatcher from the mock datastore
-	createMatcher := func(ds model.DataStore) *libraryMatcher {
-		libs, err := ds.Library().GetAll(ctx)
-		Expect(err).ToNot(HaveOccurred())
-		return newLibraryMatcher(libs)
-	}
-
-	Describe("Longest library path matching", func() {
-		It("matches the longest library path when multiple libraries share a prefix", func() {
-			// Setup libraries with prefix conflicts
-			mockLibRepo.SetData([]model.Library{
-				{ID: 1, Path: "/music"},
-				{ID: 2, Path: "/music-classical"},
-				{ID: 3, Path: "/music-classical/opera"},
-			})
-
-			matcher := createMatcher(ds)
-
-			// Test that longest path matches first and returns correct library ID
-			testCases := []struct {
-				path            string
-				expectedLibID   int
-				expectedLibPath string
-			}{
-				{"/music-classical/opera/track.mp3", 3, "/music-classical/opera"},
-				{"/music-classical/track.mp3", 2, "/music-classical"},
-				{"/music/track.mp3", 1, "/music"},
-				{"/music-classical/opera/subdir/file.mp3", 3, "/music-classical/opera"},
-			}
-
-			for _, tc := range testCases {
-				libID, libPath := matcher.findLibraryForPath(tc.path)
-				Expect(libID).To(Equal(tc.expectedLibID), "Path %s should match library ID %d, but got %d", tc.path, tc.expectedLibID, libID)
-				Expect(libPath).To(Equal(tc.expectedLibPath), "Path %s should match library path %s, but got %s", tc.path, tc.expectedLibPath, libPath)
-			}
-		})
-
-		It("handles libraries with similar prefixes but different structures", func() {
-			mockLibRepo.SetData([]model.Library{
-				{ID: 1, Path: "/home/user/music"},
-				{ID: 2, Path: "/home/user/music-backup"},
-			})
-
-			matcher := createMatcher(ds)
-
-			// Test that music-backup library is matched correctly
-			libID, libPath := matcher.findLibraryForPath("/home/user/music-backup/track.mp3")
-			Expect(libID).To(Equal(2))
-			Expect(libPath).To(Equal("/home/user/music-backup"))
-
-			// Test that music library is still matched correctly
-			libID, libPath = matcher.findLibraryForPath("/home/user/music/track.mp3")
-			Expect(libID).To(Equal(1))
-			Expect(libPath).To(Equal("/home/user/music"))
-		})
-
-		It("matches path that is exactly the library root", func() {
-			mockLibRepo.SetData([]model.Library{
-				{ID: 1, Path: "/music"},
-				{ID: 2, Path: "/music-classical"},
-			})
-
-			matcher := createMatcher(ds)
-
-			// Exact library path should match
-			libID, libPath := matcher.findLibraryForPath("/music-classical")
-			Expect(libID).To(Equal(2))
-			Expect(libPath).To(Equal("/music-classical"))
-		})
-
-		It("handles complex nested library structures", func() {
-			mockLibRepo.SetData([]model.Library{
-				{ID: 1, Path: "/media"},
-				{ID: 2, Path: "/media/audio"},
-				{ID: 3, Path: "/media/audio/classical"},
-				{ID: 4, Path: "/media/audio/classical/baroque"},
-			})
-
-			matcher := createMatcher(ds)
-
-			testCases := []struct {
-				path            string
-				expectedLibID   int
-				expectedLibPath string
-			}{
-				{"/media/audio/classical/baroque/bach/track.mp3", 4, "/media/audio/classical/baroque"},
-				{"/media/audio/classical/mozart/track.mp3", 3, "/media/audio/classical"},
-				{"/media/audio/rock/track.mp3", 2, "/media/audio"},
-				{"/media/video/movie.mp4", 1, "/media"},
-			}
-
-			for _, tc := range testCases {
-				libID, libPath := matcher.findLibraryForPath(tc.path)
-				Expect(libID).To(Equal(tc.expectedLibID), "Path %s should match library ID %d", tc.path, tc.expectedLibID)
-				Expect(libPath).To(Equal(tc.expectedLibPath), "Path %s should match library path %s", tc.path, tc.expectedLibPath)
-			}
-		})
-	})
-
-	Describe("Edge cases", func() {
-		It("handles empty library list", func() {
-			mockLibRepo.SetData([]model.Library{})
-
-			matcher := createMatcher(ds)
-			Expect(matcher).ToNot(BeNil())
-
-			// Should not match anything
-			libID, libPath := matcher.findLibraryForPath("/music/track.mp3")
-			Expect(libID).To(Equal(0))
-			Expect(libPath).To(BeEmpty())
-		})
-
-		It("handles single library", func() {
-			mockLibRepo.SetData([]model.Library{
-				{ID: 1, Path: "/music"},
-			})
-
-			matcher := createMatcher(ds)
-
-			libID, libPath := matcher.findLibraryForPath("/music/track.mp3")
-			Expect(libID).To(Equal(1))
-			Expect(libPath).To(Equal("/music"))
-		})
-
-		It("handles libraries with special characters in paths", func() {
-			mockLibRepo.SetData([]model.Library{
-				{ID: 1, Path: "/music[test]"},
-				{ID: 2, Path: "/music(backup)"},
-			})
-
-			matcher := createMatcher(ds)
-			Expect(matcher).ToNot(BeNil())
-
-			// Special characters should match literally
-			libID, libPath := matcher.findLibraryForPath("/music[test]/track.mp3")
-			Expect(libID).To(Equal(1))
-			Expect(libPath).To(Equal("/music[test]"))
-		})
-	})
-
-	Describe("Path matching order", func() {
-		It("ensures longest paths match first", func() {
-			mockLibRepo.SetData([]model.Library{
-				{ID: 1, Path: "/a"},
-				{ID: 2, Path: "/ab"},
-				{ID: 3, Path: "/abc"},
-			})
-
-			matcher := createMatcher(ds)
-
-			// Verify that longer paths match correctly (not cut off by shorter prefix)
-			testCases := []struct {
-				path          string
-				expectedLibID int
-			}{
-				{"/abc/file.mp3", 3},
-				{"/ab/file.mp3", 2},
-				{"/a/file.mp3", 1},
-			}
-
-			for _, tc := range testCases {
-				libID, _ := matcher.findLibraryForPath(tc.path)
-				Expect(libID).To(Equal(tc.expectedLibID), "Path %s should match library ID %d", tc.path, tc.expectedLibID)
-			}
-		})
-	})
-})
-
 var _ = Describe("pathResolver", func() {
 	var ds *tests.MockDataStore
 	var mockLibRepo *tests.MockLibraryRepo
diff --git a/db/migrations/20260929221042_add_library_pid_columns.sql b/db/migrations/20260929221042_add_library_pid_columns.sql
new file mode 100644
index 000000000..487512287
--- /dev/null
+++ b/db/migrations/20260929221042_add_library_pid_columns.sql
@@ -0,0 +1,18 @@
+-- +goose Up
+-- +goose StatementBegin
+alter table library add column pid_album varchar default '' not null;
+alter table library add column pid_track varchar default '' not null;
+alter table library add column scanned_pid_album varchar default '' not null;
+alter table library add column scanned_pid_track varchar default '' not null;
+
+-- Every library was scanned with the global PID config, so seed it as their scanned config.
+-- This way the upgrade does not trigger a full rescan.
+update library set
+    scanned_pid_album = coalesce((select value from property where id = 'PIDAlbum'), ''),
+    scanned_pid_track = coalesce((select value from property where id = 'PIDTrack'), '');
+
+delete from property where id in ('PIDAlbum', 'PIDTrack');
+-- +goose StatementEnd
+
+-- +goose Down
+SELECT 1;
diff --git a/model/library.go b/model/library.go
index 1e33222ac..e80d22c89 100644
--- a/model/library.go
+++ b/model/library.go
@@ -1,10 +1,13 @@
 package model
 
 import (
+	"cmp"
 	"context"
+	"strings"
 	"time"
 
 	"github.com/deluan/rest"
+	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/utils/slice"
 )
 
@@ -27,6 +30,38 @@ type Library struct {
 	TotalSize          int64     `json:"totalSize" db:"total_size"`
 	TotalDuration      float64   `json:"totalDuration" db:"total_duration"`
 	DefaultNewUsers    bool      `json:"defaultNewUsers" db:"default_new_users"`
+	PIDAlbum           string    `json:"pidAlbum" db:"pid_album"`
+	PIDTrack           string    `json:"pidTrack" db:"pid_track"`
+	ScannedPIDAlbum    string    `json:"-" db:"scanned_pid_album"`
+	ScannedPIDTrack    string    `json:"-" db:"scanned_pid_track"`
+}
+
+// PIDConfig holds the persistent ID specs used to compute track and album IDs.
+type PIDConfig struct {
+	Track string
+	Album string
+}
+
+// EffectivePID returns the PID specs in effect for this library: its own overrides, falling back to
+// the global config.
+func (l Library) EffectivePID() PIDConfig {
+	return PIDConfig{
+		Track: cmp.Or(l.PIDTrack, conf.Server.PID.Track),
+		Album: cmp.Or(l.PIDAlbum, conf.Server.PID.Album),
+	}
+}
+
+// PIDChanged reports whether the effective PID specs differ from the ones used by the last finished
+// scan of this library. A library that was never scanned counts as changed.
+func (l Library) PIDChanged() bool {
+	pid := l.EffectivePID()
+	return !strings.EqualFold(l.ScannedPIDAlbum, pid.Album) || !strings.EqualFold(l.ScannedPIDTrack, pid.Track)
+}
+
+// NeedsPIDRescan reports whether the library has content imported with an old PID config, so it must be
+// rescanned in full. A library that never finished a scan has nothing to regroup.
+func (l Library) NeedsPIDRescan() bool {
+	return !l.LastScanAt.IsZero() && l.PIDChanged()
 }
 
 const (
@@ -59,6 +94,8 @@ type LibraryRepository interface {
 	// TODO These methods should be moved to a core service
 	ScanBegin(ctx context.Context, id int, fullScan bool) error
 	ScanEnd(ctx context.Context, id int) error
+	// SetScannedPID records the PID specs used by the last finished scan of the library
+	SetScannedPID(ctx context.Context, id int, pid PIDConfig) error
 	ScanInProgress(ctx context.Context) (bool, error)
 	RefreshStats(ctx context.Context, id int) error
 }
diff --git a/model/library_matcher.go b/model/library_matcher.go
new file mode 100644
index 000000000..83af96f9f
--- /dev/null
+++ b/model/library_matcher.go
@@ -0,0 +1,57 @@
+package model
+
+import (
+	"cmp"
+	"path/filepath"
+	"slices"
+	"strings"
+)
+
+// LibraryMatcher finds the library that contains an absolute path.
+type LibraryMatcher struct {
+	libraries    Libraries
+	cleanedPaths []string
+}
+
+// NewLibraryMatcher sorts the libraries longest path first, so /music-classical is checked before /music.
+func NewLibraryMatcher(libs Libraries) *LibraryMatcher {
+	libs = slices.Clone(libs)
+	slices.SortFunc(libs, func(i, j Library) int {
+		return cmp.Compare(len(j.Path), len(i.Path))
+	})
+	cleanedPaths := make([]string, len(libs))
+	for i, lib := range libs {
+		cleanedPaths[i] = filepath.Clean(lib.Path)
+	}
+	return &LibraryMatcher{libraries: libs, cleanedPaths: cleanedPaths}
+}
+
+// FindLibrary returns the library whose path contains absolutePath.
+func (lm *LibraryMatcher) FindLibrary(absolutePath string) (Library, bool) {
+	for i, libPath := range lm.cleanedPaths {
+		// A cleaned path only ends with a separator when it is a filesystem root
+		if strings.HasPrefix(absolutePath, libPath) && (len(absolutePath) == len(libPath) ||
+			absolutePath[len(libPath)] == filepath.Separator || strings.HasSuffix(libPath, string(filepath.Separator))) {
+			return lm.libraries[i], true
+		}
+	}
+	return Library{}, false
+}
+
+// LibraryRelativePath rebases an absolute path onto the library root, as the scanner's io/fs sees it
+// (forward slashes). Relative paths, and absolute paths outside the library root, are returned unchanged.
+func LibraryRelativePath(libPath, path string) string {
+	if !filepath.IsAbs(path) {
+		return path
+	}
+	// The library root may be relative (e.g. the default "./music"); it resolves against the same cwd
+	absLib, err := filepath.Abs(libPath)
+	if err != nil {
+		return path
+	}
+	rel, err := filepath.Rel(absLib, path)
+	if err != nil || !filepath.IsLocal(rel) {
+		return path
+	}
+	return filepath.ToSlash(rel)
+}
diff --git a/model/library_matcher_test.go b/model/library_matcher_test.go
new file mode 100644
index 000000000..09e6f7e33
--- /dev/null
+++ b/model/library_matcher_test.go
@@ -0,0 +1,91 @@
+package model_test
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/navidrome/navidrome/model"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("LibraryMatcher", func() {
+	// Paths are written Unix-style and converted, so they use the OS separator, as filepath.Abs output does
+	find := func(libs model.Libraries, path string) int {
+		for i := range libs {
+			libs[i].Path = filepath.FromSlash(libs[i].Path)
+		}
+		lib, ok := model.NewLibraryMatcher(libs).FindLibrary(filepath.FromSlash(path))
+		if !ok {
+			return 0
+		}
+		return lib.ID
+	}
+
+	DescribeTable("matches the longest library path",
+		func(libs model.Libraries, path string, expectedID int) {
+			Expect(find(libs, path)).To(Equal(expectedID))
+		},
+		Entry("nested library", model.Libraries{{ID: 1, Path: "/music"}, {ID: 2, Path: "/music-classical"}, {ID: 3, Path: "/music-classical/opera"}}, "/music-classical/opera/subdir/track.mp3", 3),
+		Entry("sibling with a shared prefix", model.Libraries{{ID: 1, Path: "/music"}, {ID: 2, Path: "/music-classical"}}, "/music-classical/track.mp3", 2),
+		Entry("shorter library", model.Libraries{{ID: 1, Path: "/music"}, {ID: 2, Path: "/music-classical"}}, "/music/track.mp3", 1),
+		Entry("exact library root", model.Libraries{{ID: 1, Path: "/music"}, {ID: 2, Path: "/music-classical"}}, "/music-classical", 2),
+		Entry("deeply nested libraries", model.Libraries{{ID: 1, Path: "/media"}, {ID: 2, Path: "/media/audio"}, {ID: 3, Path: "/media/audio/classical"}, {ID: 4, Path: "/media/audio/classical/baroque"}}, "/media/audio/classical/mozart/track.mp3", 3),
+		Entry("prefix that is not a path boundary", model.Libraries{{ID: 1, Path: "/a"}, {ID: 2, Path: "/ab"}, {ID: 3, Path: "/abc"}}, "/ab/file.mp3", 2),
+		Entry("special characters match literally", model.Libraries{{ID: 1, Path: "/music[test]"}, {ID: 2, Path: "/music(backup)"}}, "/music[test]/track.mp3", 1),
+		Entry("library path with a trailing slash", model.Libraries{{ID: 1, Path: "/music/"}}, "/music/track.mp3", 1),
+		Entry("library at the filesystem root", model.Libraries{{ID: 1, Path: "/"}}, "/music/track.mp3", 1),
+		Entry("nested library under a root library", model.Libraries{{ID: 1, Path: "/"}, {ID: 2, Path: "/music"}}, "/music/track.mp3", 2),
+	)
+
+	It("does not match a path outside every library", func() {
+		Expect(find(model.Libraries{{ID: 1, Path: "/music"}}, "/music-backup/track.mp3")).To(BeZero())
+	})
+
+	It("does not match anything without libraries", func() {
+		Expect(find(nil, "/music/track.mp3")).To(BeZero())
+	})
+
+	It("does not reorder the caller's libraries", func() {
+		libs := model.Libraries{{ID: 1, Path: "/a"}, {ID: 2, Path: "/abc"}}
+		model.NewLibraryMatcher(libs)
+		Expect(libs.IDs()).To(Equal([]int{1, 2}))
+	})
+})
+
+var _ = Describe("LibraryRelativePath", func() {
+	// Paths are built with filepath so the "absolute" cases stay absolute on every OS
+	// (a Unix-style "/foo" is not absolute on Windows).
+	libRoot, _ := filepath.Abs(filepath.Join("jukebox", "collection"))
+	outside, _ := filepath.Abs(filepath.Join("somewhere", "else"))
+
+	It("returns a relative path unchanged", func() {
+		Expect(model.LibraryRelativePath(libRoot, "_Collection")).To(Equal("_Collection"))
+	})
+
+	It("rebases an absolute target when the library root is relative", func() {
+		cwd, err := os.Getwd()
+		Expect(err).ToNot(HaveOccurred())
+		Expect(model.LibraryRelativePath(filepath.Join("music", "library"), filepath.Join(cwd, "music", "library", "rock"))).To(Equal("rock"))
+	})
+
+	It("rebases an absolute path that equals the library root to '.'", func() {
+		Expect(model.LibraryRelativePath(libRoot, libRoot)).To(Equal("."))
+	})
+
+	It("rebases an absolute path under the library root", func() {
+		Expect(model.LibraryRelativePath(libRoot, filepath.Join(libRoot, "_Collection"))).To(Equal("_Collection"))
+	})
+
+	It("handles a trailing slash on the library path", func() {
+		Expect(model.LibraryRelativePath(libRoot+string(filepath.Separator), filepath.Join(libRoot, "_Collection"))).To(Equal("_Collection"))
+	})
+
+	It("leaves an absolute path outside the library root unchanged", func() {
+		Expect(model.LibraryRelativePath(libRoot, outside)).To(Equal(outside))
+	})
+
+	It("returns an empty path unchanged", func() {
+		Expect(model.LibraryRelativePath(libRoot, "")).To(Equal(""))
+	})
+})
diff --git a/model/library_test.go b/model/library_test.go
new file mode 100644
index 000000000..4e799e13f
--- /dev/null
+++ b/model/library_test.go
@@ -0,0 +1,73 @@
+package model_test
+
+import (
+	"encoding/json"
+	"time"
+
+	"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("Library PID config", func() {
+	BeforeEach(func() {
+		DeferCleanup(configtest.SetupConfig())
+		conf.Server.PID.Album = "global_album"
+		conf.Server.PID.Track = "global_track"
+	})
+
+	Describe("EffectivePID", func() {
+		It("falls back to the global config", func() {
+			Expect(model.Library{}.EffectivePID()).To(Equal(model.PIDConfig{Track: "global_track", Album: "global_album"}))
+		})
+		It("uses the library overrides", func() {
+			lib := model.Library{PIDAlbum: "folder", PIDTrack: "title"}
+			Expect(lib.EffectivePID()).To(Equal(model.PIDConfig{Track: "title", Album: "folder"}))
+		})
+	})
+
+	Describe("PIDChanged", func() {
+		It("is false when the scanned specs match, ignoring case", func() {
+			lib := model.Library{ScannedPIDAlbum: "GLOBAL_ALBUM", ScannedPIDTrack: "global_track"}
+			Expect(lib.PIDChanged()).To(BeFalse())
+		})
+		It("is true when the album override differs from the scanned spec", func() {
+			lib := model.Library{PIDAlbum: "folder", ScannedPIDAlbum: "global_album", ScannedPIDTrack: "global_track"}
+			Expect(lib.PIDChanged()).To(BeTrue())
+		})
+		It("is true when only the track spec changed", func() {
+			lib := model.Library{PIDTrack: "title", ScannedPIDAlbum: "global_album", ScannedPIDTrack: "global_track"}
+			Expect(lib.PIDChanged()).To(BeTrue())
+		})
+		It("is true when the global config changed for a library without overrides", func() {
+			lib := model.Library{ScannedPIDAlbum: "old_album", ScannedPIDTrack: "global_track"}
+			Expect(lib.PIDChanged()).To(BeTrue())
+		})
+		It("is true for a library that was never scanned", func() {
+			Expect(model.Library{}.PIDChanged()).To(BeTrue())
+		})
+	})
+
+	Describe("NeedsPIDRescan", func() {
+		It("is false for a library that never finished a scan", func() {
+			Expect(model.Library{PIDAlbum: "folder"}.NeedsPIDRescan()).To(BeFalse())
+		})
+		It("is true for a scanned library whose PID config changed", func() {
+			lib := model.Library{PIDAlbum: "folder", ScannedPIDAlbum: "global_album", ScannedPIDTrack: "global_track", LastScanAt: time.Now()}
+			Expect(lib.NeedsPIDRescan()).To(BeTrue())
+		})
+		It("is false for a scanned library whose PID config did not change", func() {
+			lib := model.Library{ScannedPIDAlbum: "global_album", ScannedPIDTrack: "global_track", LastScanAt: time.Now()}
+			Expect(lib.NeedsPIDRescan()).To(BeFalse())
+		})
+	})
+
+	It("does not expose the scanned specs in JSON", func() {
+		data, err := json.Marshal(model.Library{PIDAlbum: "folder", ScannedPIDAlbum: "secret_album", ScannedPIDTrack: "secret_track"})
+		Expect(err).ToNot(HaveOccurred())
+		Expect(string(data)).To(ContainSubstring(`"pidAlbum":"folder"`))
+		Expect(string(data)).ToNot(ContainSubstring("secret_"))
+	})
+})
diff --git a/model/metadata/map_mediafile.go b/model/metadata/map_mediafile.go
index 6d12feba9..2135824d2 100644
--- a/model/metadata/map_mediafile.go
+++ b/model/metadata/map_mediafile.go
@@ -8,15 +8,14 @@ import (
 	"math"
 	"strconv"
 
-	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/utils/str"
 )
 
-func (md Metadata) ToMediaFile(libID int, folderID string) model.MediaFile {
+func (md Metadata) ToMediaFile(lib model.Library, folderID string) model.MediaFile {
 	mf := model.MediaFile{
-		LibraryID: libID,
+		LibraryID: lib.ID,
 		FolderID:  folderID,
 		Tags:      maps.Clone(md.tags),
 	}
@@ -84,8 +83,9 @@ func (md Metadata) ToMediaFile(libID int, folderID string) model.MediaFile {
 	mf.AlbumArtist = md.mapDisplayAlbumArtist(mf)
 
 	// Persistent IDs
-	mf.PID = md.trackPID(mf)
-	mf.AlbumID = md.albumID(mf, conf.Server.PID.Album)
+	pid := lib.EffectivePID()
+	mf.PID = md.trackPID(mf, pid)
+	mf.AlbumID = md.albumID(mf, pid.Album)
 
 	// BFR These IDs will go away once the UI handle multiple participants.
 	// BFR For Legacy Subsonic compatibility, we will set them in the API handlers
diff --git a/model/metadata/map_mediafile_test.go b/model/metadata/map_mediafile_test.go
index baaf8fab5..c19398841 100644
--- a/model/metadata/map_mediafile_test.go
+++ b/model/metadata/map_mediafile_test.go
@@ -30,9 +30,23 @@ var _ = Describe("ToMediaFile", func() {
 	var toMediaFile = func(tags model.RawTags) model.MediaFile {
 		props.Tags = tags
 		md = metadata.New("filepath", props)
-		return md.ToMediaFile(1, "folderID")
+		return md.ToMediaFile(model.Library{ID: 1}, "folderID")
 	}
 
+	Describe("Persistent IDs", func() {
+		It("uses the library PID config for the album ID and for albumid in the track spec", func() {
+			props.Tags = model.RawTags{"ALBUM": {"Kind of Blue"}, "TITLE": {"So What"}}
+			md = metadata.New("Jazz/Loose/01.mp3", props)
+
+			byTags := md.ToMediaFile(model.Library{ID: 1, PIDAlbum: "album", PIDTrack: "albumid,title"}, "folderID")
+			byFolder := md.ToMediaFile(model.Library{ID: 1, PIDAlbum: "folder", PIDTrack: "albumid,title"}, "folderID")
+
+			Expect(byFolder.AlbumID).ToNot(Equal(byTags.AlbumID))
+			Expect(byFolder.AlbumID).To(Equal(md.AlbumID(byFolder, "folder")))
+			Expect(byFolder.PID).ToNot(Equal(byTags.PID))
+		})
+	})
+
 	Describe("Dates", func() {
 		It("should parse properly tagged dates ", func() {
 			mf = toMediaFile(model.RawTags{
diff --git a/model/metadata/map_participants_test.go b/model/metadata/map_participants_test.go
index ec66e12b9..db652fb8b 100644
--- a/model/metadata/map_participants_test.go
+++ b/model/metadata/map_participants_test.go
@@ -38,7 +38,7 @@ var _ = Describe("Participants", func() {
 	var toMediaFile = func(tags model.RawTags) model.MediaFile {
 		props.Tags = tags
 		md = metadata.New("filepath", props)
-		return md.ToMediaFile(1, "folderID")
+		return md.ToMediaFile(model.Library{ID: 1}, "folderID")
 	}
 
 	Describe("ARTIST(S) tags", func() {
diff --git a/model/metadata/metadata_test.go b/model/metadata/metadata_test.go
index c84d93981..a1a675006 100644
--- a/model/metadata/metadata_test.go
+++ b/model/metadata/metadata_test.go
@@ -323,7 +323,7 @@ var _ = Describe("Metadata", func() {
 					tag: {tagValue},
 				}
 				md = metadata.New(filePath, props)
-				return md.ToMediaFile(0, "0")
+				return md.ToMediaFile(model.Library{}, "0")
 			}
 
 			DescribeTable("Gain",
diff --git a/model/metadata/persistent_ids.go b/model/metadata/persistent_ids.go
index db315dc6b..b66ce824a 100644
--- a/model/metadata/persistent_ids.go
+++ b/model/metadata/persistent_ids.go
@@ -2,11 +2,11 @@ package metadata
 
 import (
 	"cmp"
+	"errors"
 	"fmt"
 	"path/filepath"
 	"strings"
 
-	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -22,12 +22,13 @@ type hashFunc = func(...string) string
 // attributes. Attributes can be either tags or processed values like folder,
 // albumid, albumartistid, etc. For each field, it gets all its attribute values
 // and concatenates them, then hashes the result. If a field is empty, it is
-// skipped and the function looks for the next field.
+// skipped and the function looks for the next field. albumSpec is the album PID
+// spec used to resolve the `albumid` attribute.
 //
 // Taking hash as a parameter (instead of closing over it in a factory) keeps
 // mf on the stack: closing over mf would force the whole ~1KB MediaFile to the
 // heap on every call.
-func computePID(mf model.MediaFile, md Metadata, spec string, prependLibId bool, hash hashFunc) string {
+func computePID(mf model.MediaFile, md Metadata, spec, albumSpec string, prependLibId bool, hash hashFunc) string {
 	switch spec {
 	case "track_legacy":
 		return legacyTrackID(mf, prependLibId)
@@ -41,7 +42,7 @@ func computePID(mf model.MediaFile, md Metadata, spec string, prependLibId bool,
 		values := make([]string, len(attributes))
 		hasValue := false
 		for i, attr := range attributes {
-			v := getPIDAttr(mf, md, attr, prependLibId, spec, hash)
+			v := getPIDAttr(mf, md, attr, prependLibId, spec, albumSpec, hash)
 			if v != "" {
 				hasValue = true
 			}
@@ -58,15 +59,15 @@ func computePID(mf model.MediaFile, md Metadata, spec string, prependLibId bool,
 	return hash(pid)
 }
 
-func getPIDAttr(mf model.MediaFile, md Metadata, attr string, prependLibId bool, spec string, hash hashFunc) string {
+func getPIDAttr(mf model.MediaFile, md Metadata, attr string, prependLibId bool, spec, albumSpec string, hash hashFunc) string {
 	attr = strings.TrimSpace(strings.ToLower(attr))
 	switch attr {
 	case "albumid":
-		if spec == conf.Server.PID.Album {
+		if spec == albumSpec {
 			log.Error("Recursive PID definition detected, ignoring `albumid`", "spec", spec)
 			return ""
 		}
-		return computePID(mf, md, conf.Server.PID.Album, prependLibId, hash)
+		return computePID(mf, md, albumSpec, albumSpec, prependLibId, hash)
 	case "folder":
 		return filepath.Dir(mf.Path)
 	case "albumartistid":
@@ -79,18 +80,50 @@ func getPIDAttr(mf model.MediaFile, md Metadata, attr string, prependLibId bool,
 	return md.String(model.TagName(attr))
 }
 
-func (md Metadata) trackPID(mf model.MediaFile) string {
-	return computePID(mf, md, conf.Server.PID.Track, true, id.NewHash)
+// ValidatePIDSpec checks a PID override before it is stored; empty means "use the global config".
+// Aliases resolve to empty at scan time: accepted only in track specs, because the default one uses them.
+func ValidatePIDSpec(spec string, isAlbum bool) error {
+	switch {
+	case spec == "", isAlbum && spec == "album_legacy", !isAlbum && spec == "track_legacy":
+		return nil
+	}
+	for field := range strings.SplitSeq(spec, "|") {
+		for attr := range strings.SplitSeq(field, ",") {
+			attr = strings.TrimSpace(strings.ToLower(attr))
+			switch attr {
+			case "":
+				return fmt.Errorf("empty attribute in %q", spec)
+			case "albumid":
+				if isAlbum {
+					return errors.New("albumid cannot be used in an album PID")
+				}
+			case "folder", "albumartistid":
+			default:
+				name, ok := model.CanonicalTagName(attr)
+				if !ok {
+					return fmt.Errorf("unknown attribute %q", attr)
+				}
+				if isAlbum && string(name) != attr {
+					return fmt.Errorf("use the tag name %q instead of its alias %q", name, attr)
+				}
+			}
+		}
+	}
+	return nil
+}
+
+func (md Metadata) trackPID(mf model.MediaFile, pid model.PIDConfig) string {
+	return computePID(mf, md, pid.Track, pid.Album, true, id.NewHash)
 }
 
 func (md Metadata) albumID(mf model.MediaFile, pidConf string) string {
-	return computePID(mf, md, pidConf, true, id.NewHash)
+	return computePID(mf, md, pidConf, pidConf, true, id.NewHash)
 }
 
 // BFR Must be configurable?
 func (md Metadata) artistID(name string) string {
 	mf := model.MediaFile{AlbumArtist: name}
-	return computePID(mf, md, "albumartistid", false, id.NewHash)
+	return computePID(mf, md, "albumartistid", "", false, id.NewHash)
 }
 
 func (md Metadata) mapTrackTitle() string {
diff --git a/model/metadata/persistent_ids_test.go b/model/metadata/persistent_ids_test.go
index 8e38bbd42..9f6eaf1f4 100644
--- a/model/metadata/persistent_ids_test.go
+++ b/model/metadata/persistent_ids_test.go
@@ -3,8 +3,7 @@ package metadata
 import (
 	"strings"
 
-	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/conf/configtest"
+	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
@@ -13,16 +12,18 @@ import (
 
 var _ = Describe("getPID", func() {
 	var (
-		md  Metadata
-		mf  model.MediaFile
-		sum hashFunc
+		md        Metadata
+		mf        model.MediaFile
+		sum       hashFunc
+		albumSpec string
 	)
 	getPID := func(mf model.MediaFile, md Metadata, spec string, prependLibId bool) string {
-		return computePID(mf, md, spec, prependLibId, sum)
+		return computePID(mf, md, spec, albumSpec, prependLibId, sum)
 	}
 
 	BeforeEach(func() {
 		sum = func(s ...string) string { return "(" + strings.Join(s, ",") + ")" }
+		albumSpec = consts.DefaultAlbumPID
 	})
 
 	Context("attributes are tags", func() {
@@ -66,8 +67,7 @@ var _ = Describe("getPID", func() {
 
 	Context("calculated attributes", func() {
 		BeforeEach(func() {
-			DeferCleanup(configtest.SetupConfig())
-			conf.Server.PID.Album = "musicbrainz_albumid|albumartistid,album,albumversion,releasedate"
+			albumSpec = "musicbrainz_albumid|albumartistid,album,albumversion,releasedate"
 		})
 		When("field is title", func() {
 			It("should return the pid", func() {
@@ -121,8 +121,8 @@ var _ = Describe("getPID", func() {
 		When("albumid configuration refers to albumid recursively", func() {
 			It("should avoid infinite recursion", func() {
 				// Reproduce the issue from #4920
-				conf.Server.PID.Album = "albumid,album,albumversion,releasedate"
-				spec := conf.Server.PID.Album
+				albumSpec = "albumid,album,albumversion,releasedate"
+				spec := albumSpec
 				md.tags = map[model.TagName][]string{
 					"album":        {"Album Name"},
 					"albumversion": {"Version"},
@@ -205,8 +205,7 @@ var _ = Describe("getPID", func() {
 		})
 		When("prependLibId is true with nested albumid", func() {
 			It("should handle nested albumid calls correctly", func() {
-				DeferCleanup(configtest.SetupConfig())
-				conf.Server.PID.Album = "album"
+				albumSpec = "album"
 				spec := "albumid"
 				md.tags = map[model.TagName][]string{"album": {"Test Album"}}
 				mf.AlbumArtist = "Test Artist"
@@ -306,3 +305,34 @@ var _ = Describe("getPID", func() {
 		})
 	})
 })
+
+var _ = Describe("ValidatePIDSpec", func() {
+	DescribeTable("accepts valid specs",
+		func(spec string, isAlbum bool) {
+			Expect(ValidatePIDSpec(spec, isAlbum)).To(Succeed())
+		},
+		Entry("empty, meaning the global config", "", true),
+		Entry("default album spec", consts.DefaultAlbumPID, true),
+		Entry("default track spec, which uses tag aliases", consts.DefaultTrackPID, false),
+		Entry("folder", "folder", true),
+		Entry("album legacy", "album_legacy", true),
+		Entry("track legacy", "track_legacy", false),
+		Entry("computed attributes", "albumartistid,album|title", true),
+		Entry("albumid in a track spec", "albumid,title", false),
+		Entry("spaces and mixed case", "MusicBrainz_AlbumID | Folder", true),
+	)
+
+	DescribeTable("rejects invalid specs",
+		func(spec string, isAlbum bool, msg string) {
+			Expect(ValidatePIDSpec(spec, isAlbum)).To(MatchError(ContainSubstring(msg)))
+		},
+		Entry("unknown tag", "albmversion", true, `unknown attribute "albmversion"`),
+		Entry("empty field", "album||title", true, "empty attribute"),
+		Entry("empty attribute", "album,,title", true, "empty attribute"),
+		Entry("trailing separator", "album|", true, "empty attribute"),
+		Entry("albumid in an album spec", "albumid,album", true, "albumid"),
+		Entry("tag alias in an album spec", "talb", true, `use the tag name "album" instead of its alias "talb"`),
+		Entry("track legacy in an album spec", "track_legacy", true, `unknown attribute "track_legacy"`),
+		Entry("album legacy in a track spec", "album_legacy", false, `unknown attribute "album_legacy"`),
+	)
+})
diff --git a/model/scanner.go b/model/scanner.go
index 36c9007fb..d22c3d0d6 100644
--- a/model/scanner.go
+++ b/model/scanner.go
@@ -2,12 +2,15 @@ package model
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"strconv"
 	"strings"
 	"time"
 )
 
+var ErrAlreadyScanning = errors.New("already scanning")
+
 // ScanTarget represents a specific folder within a library to be scanned.
 // NOTE: This struct is used as a map key, so it should only contain comparable types.
 type ScanTarget struct {
diff --git a/model/tag_mappings.go b/model/tag_mappings.go
index ce7d2f37b..5a8168754 100644
--- a/model/tag_mappings.go
+++ b/model/tag_mappings.go
@@ -195,6 +195,28 @@ func TagMappings() map[TagName]TagConf {
 	return mappings
 }
 
+// CanonicalTagName returns the mapped tag that name is, or is an alias of. Tags are stored under this name.
+func CanonicalTagName(name string) (TagName, bool) {
+	tagName, ok := tagNameIndex()[TagName(name).ToLower()]
+	return tagName, ok
+}
+
+// tagNameIndex maps every tag name and alias to its tag name. Names are added last, so they win over aliases
+// (musicbrainz_trackid is a tag and also an alias of musicbrainz_recordingid).
+var tagNameIndex = sync.OnceValue(func() map[TagName]TagName {
+	mappings := TagMappings()
+	index := make(map[TagName]TagName, len(mappings))
+	for name, tag := range mappings {
+		for _, alias := range tag.Aliases {
+			index[TagName(alias)] = name
+		}
+	}
+	for name := range mappings {
+		index[name] = name
+	}
+	return index
+})
+
 func TagRolesConf() TagConf {
 	_, cfg := parseMappings()
 	return cfg.Roles
diff --git a/model/tag_mappings_test.go b/model/tag_mappings_test.go
index e582c3f2f..91e54e5d4 100644
--- a/model/tag_mappings_test.go
+++ b/model/tag_mappings_test.go
@@ -192,3 +192,22 @@ var _ = Describe("TagConf", func() {
 		})
 	})
 })
+
+var _ = Describe("CanonicalTagName", func() {
+	DescribeTable("resolves tag names and aliases",
+		func(name string, expected TagName) {
+			tagName, ok := CanonicalTagName(name)
+			Expect(ok).To(BeTrue())
+			Expect(tagName).To(Equal(expected))
+		},
+		Entry("tag name", "album", TagAlbum),
+		Entry("alias", "talb", TagAlbum),
+		Entry("mixed case alias", "TALB", TagAlbum),
+		Entry("tag name that is also an alias of another tag", "musicbrainz_trackid", TagMusicBrainzTrackID),
+	)
+
+	It("does not resolve an unknown name", func() {
+		_, ok := CanonicalTagName("nosuchtag")
+		Expect(ok).To(BeFalse())
+	})
+})
diff --git a/persistence/library_repository.go b/persistence/library_repository.go
index bf6b8995e..85da65cbc 100644
--- a/persistence/library_repository.go
+++ b/persistence/library_repository.go
@@ -93,6 +93,8 @@ func (r *libraryRepository) Put(ctx context.Context, l *model.Library, colsToUpd
 			"path":              l.Path,
 			"remote_path":       l.RemotePath,
 			"default_new_users": l.DefaultNewUsers,
+			"pid_album":         l.PIDAlbum,
+			"pid_track":         l.PIDTrack,
 		}, colsToUpdate...)
 		cols["updated_at"] = l.UpdatedAt
 		sq := Update(r.tableName).SetMap(cols).Where(Eq{"id": l.ID})
@@ -176,6 +178,15 @@ func (r *libraryRepository) ScanEnd(ctx context.Context, id int) error {
 	return err
 }
 
+func (r *libraryRepository) SetScannedPID(ctx context.Context, id int, pid model.PIDConfig) error {
+	sq := Update(r.tableName).
+		Set("scanned_pid_album", pid.Album).
+		Set("scanned_pid_track", pid.Track).
+		Where(Eq{"id": id})
+	_, err := r.executeSQL(ctx, sq)
+	return err
+}
+
 func (r *libraryRepository) ScanInProgress(ctx context.Context) (bool, error) {
 	query := r.newSelect(ctx).Where(NotEq{"last_scan_started_at": time.Time{}})
 	count, err := r.count(ctx, query)
diff --git a/persistence/library_repository_test.go b/persistence/library_repository_test.go
index 0ff470861..bf485a06f 100644
--- a/persistence/library_repository_test.go
+++ b/persistence/library_repository_test.go
@@ -270,6 +270,38 @@ var _ = Describe("LibraryRepository", func() {
 		})
 	})
 
+	Describe("PID config", func() {
+		It("stores the overrides, and Put never touches the scanned specs", func() {
+			lib := &model.Library{Name: "PID Library", Path: "/music/pid", PIDAlbum: "folder", PIDTrack: "title"}
+			Expect(repo.Put(ctx, lib)).To(Succeed())
+			Expect(repo.SetScannedPID(ctx, lib.ID, model.PIDConfig{Album: "folder", Track: "title"})).To(Succeed())
+
+			// An update coming from the REST API has no scanned specs. It must not clear them
+			update := &model.Library{ID: lib.ID, Name: "PID Library", Path: "/music/pid", PIDTrack: "title"}
+			Expect(repo.Put(ctx, update)).To(Succeed())
+
+			saved, err := repo.Get(ctx, lib.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(saved.PIDAlbum).To(BeEmpty())
+			Expect(saved.PIDTrack).To(Equal("title"))
+			Expect(saved.ScannedPIDAlbum).To(Equal("folder"))
+			Expect(saved.ScannedPIDTrack).To(Equal("title"))
+		})
+
+		It("keeps the overrides when a partial update does not send them", func() {
+			lib := &model.Library{Name: "Partial", Path: "/music/partial", PIDAlbum: "folder", PIDTrack: "title"}
+			Expect(repo.Put(ctx, lib)).To(Succeed())
+
+			Expect(repo.Put(ctx, &model.Library{ID: lib.ID, Name: "Renamed"}, "name")).To(Succeed())
+
+			saved, err := repo.Get(ctx, lib.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(saved.Name).To(Equal("Renamed"))
+			Expect(saved.PIDAlbum).To(Equal("folder"))
+			Expect(saved.PIDTrack).To(Equal("title"))
+		})
+	})
+
 	Describe("Delete", func() {
 		var adminRepo model.LibraryRepository
 		var artistRepo model.ArtistRepository
diff --git a/resources/i18n/pt-br.json b/resources/i18n/pt-br.json
index f0d8a0e06..238919259 100644
--- a/resources/i18n/pt-br.json
+++ b/resources/i18n/pt-br.json
@@ -328,11 +328,22 @@
         "totalDuration": "Duração",
         "defaultNewUsers": "Padrão para Novos Usuários",
         "createdAt": "Data de Criação",
-        "updatedAt": "Últ. Atualização"
+        "updatedAt": "Últ. Atualização",
+        "pidAlbum": "Agrupamento de álbuns",
+        "pidTrack": "Identificação das faixas"
       },
       "sections": {
         "basic": "Informações Básicas",
-        "statistics": "Estatísticas"
+        "statistics": "Estatísticas",
+        "pid": "IDs Persistentes"
+      },
+      "pid": {
+        "global": "Usar configuração global (%{value})",
+        "folder": "Pasta (um álbum por pasta)",
+        "custom": "Personalizado",
+        "spec": "Especificação do PID",
+        "help": "Tags e atributos que identificam um item. Consulte a sintaxe na documentação:",
+        "docs": "IDs Persistentes"
       },
       "actions": {
         "scan": "Scanear Biblioteca",
@@ -362,7 +373,9 @@
       "messages": {
         "deleteConfirm": "Tem certeza que deseja excluir esta biblioteca? Isso removerá todos os dados associados.",
         "scanInProgress": "Scan em progresso...",
-        "noLibrariesAssigned": "Nenhuma biblioteca atribuída a este usuário"
+        "noLibrariesAssigned": "Nenhuma biblioteca atribuída a este usuário",
+        "pidChangeTitle": "Alterar os IDs persistentes?",
+        "pidChangeConfirm": "Ao salvar, os álbuns desta biblioteca serão reagrupados e as faixas serão identificadas novamente. Um scan completo da biblioteca começará imediatamente. As marcações como favoritas, as classificações e as contagens de reprodução das faixas serão mantidas. Os favoritos e as classificações dos álbuns serão transferidos para os novos álbuns quando um álbum antigo corresponder a um novo."
       }
     },
     "plugin": {
diff --git a/scanner/controller.go b/scanner/controller.go
index 5eed6c58d..1b13c1846 100644
--- a/scanner/controller.go
+++ b/scanner/controller.go
@@ -25,7 +25,7 @@ import (
 )
 
 var (
-	ErrAlreadyScanning = errors.New("already scanning")
+	ErrAlreadyScanning = model.ErrAlreadyScanning
 )
 
 func New(rootCtx context.Context, ds model.DataStore, broker events.Broker,
@@ -304,14 +304,14 @@ func LockForMaintenance() (func(), bool) {
 	return scanMaintenanceMux.Unlock, true
 }
 
-// EffectiveFullScan reports whether a scan was requested as full or will resume an interrupted
-// full scan in one of the included libraries.
+// EffectiveFullScan reports whether a scan was requested as full, will resume an interrupted full scan,
+// or will rescan a library in full because its PID config changed, in one of the included libraries.
 func EffectiveFullScan(ctx context.Context, ds model.DataStore, fullScan bool, targets []model.ScanTarget) bool {
 	if fullScan {
 		return true
 	}
 	return anyIncludedLibrary(ctx, ds, targets, func(library model.Library) bool {
-		return library.FullScanInProgress
+		return library.FullScanInProgress || library.NeedsPIDRescan()
 	})
 }
 
diff --git a/scanner/controller_test.go b/scanner/controller_test.go
index bdcb99eda..974540e32 100644
--- a/scanner/controller_test.go
+++ b/scanner/controller_test.go
@@ -2,6 +2,7 @@ package scanner_test
 
 import (
 	"context"
+	"time"
 
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/consts"
@@ -70,14 +71,21 @@ var _ = Describe("EffectiveFullScan", func() {
 	var ds *tests.MockDataStore
 
 	BeforeEach(func() {
+		pid := model.Library{}.EffectivePID()
 		libraries := &tests.MockLibraryRepo{}
 		libraries.SetData(model.Libraries{
-			{ID: 1, FullScanInProgress: true},
-			{ID: 2},
+			{ID: 1, FullScanInProgress: true, ScannedPIDAlbum: pid.Album, ScannedPIDTrack: pid.Track},
+			{ID: 2, ScannedPIDAlbum: pid.Album, ScannedPIDTrack: pid.Track},
+			{ID: 3, LastScanAt: time.Now(), PIDAlbum: "folder", ScannedPIDAlbum: pid.Album, ScannedPIDTrack: pid.Track},
 		})
 		ds = &tests.MockDataStore{MockedLibrary: libraries}
 	})
 
+	It("detects a library that needs a full rescan for a PID change", func() {
+		targets := []model.ScanTarget{{LibraryID: 3, FolderPath: "."}}
+		Expect(scanner.EffectiveFullScan(GinkgoT().Context(), ds, false, targets)).To(BeTrue())
+	})
+
 	It("detects an interrupted full scan in a targeted library", func() {
 		targets := []model.ScanTarget{{LibraryID: 1, FolderPath: "."}}
 		Expect(scanner.EffectiveFullScan(context.Background(), ds, false, targets)).To(BeTrue())
diff --git a/scanner/phase_1_folders.go b/scanner/phase_1_folders.go
index 7b6a6b097..4edaecacd 100644
--- a/scanner/phase_1_folders.go
+++ b/scanner/phase_1_folders.go
@@ -40,6 +40,7 @@ func createPhaseFolders(ctx context.Context, state *scanState, ds model.DataStor
 		if err != nil {
 			log.Error(ctx, "Scanner: Error creating scan context", "lib", lib.Name, err)
 			state.sendError(err)
+			state.markFailed(lib.ID)
 			continue
 		}
 		jobs = append(jobs, job)
@@ -51,12 +52,13 @@ func createPhaseFolders(ctx context.Context, state *scanState, ds model.DataStor
 }
 
 type scanJob struct {
-	lib           model.Library
-	fs            storage.MusicFS
-	lastUpdates   map[string]model.FolderUpdateInfo // Holds last update info for all (DB) folders in this library
-	targetFolders []string                          // Specific folders to scan (including all descendants)
-	lock          sync.Mutex
-	numFolders    atomic.Int64
+	lib              model.Library
+	fs               storage.MusicFS
+	lastUpdates      map[string]model.FolderUpdateInfo // Holds last update info for all (DB) folders in this library
+	targetFolders    []string                          // Specific folders to scan (including all descendants)
+	prevAlbumPIDConf string                            // Album PID spec of the last finished scan, only when it differs from the current one
+	lock             sync.Mutex
+	numFolders       atomic.Int64
 }
 
 func newScanJob(ctx context.Context, ds model.DataStore, lib model.Library, fullScan bool, targetFolders []string) (*scanJob, error) {
@@ -77,16 +79,32 @@ func newScanJob(ctx context.Context, ds model.DataStore, lib model.Library, full
 		return nil, fmt.Errorf("getting fs for library: %w", err)
 	}
 
+	pid := lib.EffectivePID()
+	if lib.NeedsPIDRescan() {
+		msg := "Scanner: PID config changed, rescanning library in full"
+		if len(targetFolders) > 0 {
+			msg = "Scanner: PID config changed, rescanning target folders in full"
+		}
+		log.Info(ctx, msg, "lib", lib.Name, "targetFolders", targetFolders,
+			"album", pid.Album, "track", pid.Track, "scannedAlbum", lib.ScannedPIDAlbum, "scannedTrack", lib.ScannedPIDTrack)
+		fullScan = true
+	}
+	var prevAlbumPIDConf string
+	if lib.ScannedPIDAlbum != pid.Album {
+		prevAlbumPIDConf = lib.ScannedPIDAlbum
+	}
+
 	// Ensure FullScanInProgress reflects the current scan request.
 	// This is important when resuming an interrupted quick scan as a full scan:
 	// the DB may have FullScanInProgress=false, but we need it true for isOutdated() to work correctly.
 	lib.FullScanInProgress = lib.FullScanInProgress || fullScan
 
 	return &scanJob{
-		lib:           lib,
-		fs:            fsys,
-		lastUpdates:   lastUpdates,
-		targetFolders: targetFolders,
+		lib:              lib,
+		fs:               fsys,
+		lastUpdates:      lastUpdates,
+		targetFolders:    targetFolders,
+		prevAlbumPIDConf: prevAlbumPIDConf,
 	}, nil
 }
 
@@ -122,14 +140,13 @@ func (j *scanJob) createFolderEntry(path string) *folderEntry {
 // The phaseFolders struct implements the phase interface, providing methods to produce
 // folder entries, process folders, persist changes to the database, and log the results.
 type phaseFolders struct {
-	jobs             []*scanJob
-	ds               model.DataStore
-	ctx              context.Context //nolint:containedctx // phase runs under a single scan ctx
-	walkCtx          context.Context //nolint:containedctx // cancelled when a folder fails to persist, so the walk stops early
-	stopWalk         context.CancelCauseFunc
-	state            *scanState
-	prevAlbumPIDConf string
-	imageChanges     *imageChangeCollector
+	jobs         []*scanJob
+	ds           model.DataStore
+	ctx          context.Context //nolint:containedctx // phase runs under a single scan ctx
+	walkCtx      context.Context //nolint:containedctx // cancelled when a folder fails to persist, so the walk stops early
+	stopWalk     context.CancelCauseFunc
+	state        *scanState
+	imageChanges *imageChangeCollector
 }
 
 func (p *phaseFolders) description() string {
@@ -138,12 +155,6 @@ func (p *phaseFolders) description() string {
 
 func (p *phaseFolders) producer() ppl.Producer[*folderEntry] {
 	return ppl.NewProducer(func(put func(entry *folderEntry)) error {
-		var err error
-		p.prevAlbumPIDConf, err = p.ds.Property().DefaultGet(p.ctx, consts.PIDAlbumKey, "")
-		if err != nil {
-			return fmt.Errorf("getting album PID conf: %w", err)
-		}
-
 		// TODO Parallelize multiple job when we have multiple libraries
 		var total int64
 		var totalChanged int64
@@ -173,7 +184,7 @@ func (p *phaseFolders) producer() ppl.Producer[*folderEntry] {
 
 				// Check if folder is outdated
 				if folder.isOutdated() {
-					if !p.state.fullScan {
+					if !folder.job.lib.FullScanInProgress {
 						// Ancestor folders need a row even with no files of their own: artwork
 						// resolution climbs them, and an image added later needs a state to diff.
 						if folder.isEmpty() && folder.isNew() {
@@ -239,7 +250,7 @@ func (p *phaseFolders) processFolder(entry *folderEntry) (*folderEntry, error) {
 	for afPath, af := range entry.audioFiles {
 		fullPath := path.Join(entry.path, afPath)
 		dbTrack, foundInDB := dbTracks[fullPath]
-		if !foundInDB || p.state.fullScan {
+		if !foundInDB || entry.job.lib.FullScanInProgress {
 			filesToImport[fullPath] = dbTrack
 		} else {
 			info, err := af.Info()
@@ -289,18 +300,18 @@ func (p *phaseFolders) loadTagsFromFiles(entry *folderEntry, toImport map[string
 		}
 		for filePath, info := range allInfo {
 			md := metadata.New(filePath, info)
-			track := md.ToMediaFile(entry.job.lib.ID, entry.id)
+			track := md.ToMediaFile(entry.job.lib, entry.id)
 			tracks = append(tracks, track)
 			for _, t := range track.Tags.FlattenAll() {
 				uniqueTags[t.ID] = t
 			}
 
 			// Keep track of any album ID changes, to reassign annotations later
-			prevAlbumID := ""
+			prevAlbumID := track.AlbumID
 			if prev := toImport[filePath]; prev != nil {
 				prevAlbumID = prev.AlbumID
-			} else {
-				prevAlbumID = md.AlbumID(track, p.prevAlbumPIDConf)
+			} else if entry.job.prevAlbumPIDConf != "" {
+				prevAlbumID = md.AlbumID(track, entry.job.prevAlbumPIDConf)
 			}
 			_, ok := entry.albumIDMap[track.AlbumID]
 			if prevAlbumID != track.AlbumID && !ok {
@@ -453,7 +464,7 @@ func (p *phaseFolders) persistFolder(ctx context.Context, tx model.DataStore, en
 	if len(queueItems) > 0 {
 		queue := tx.ArtworkQueue()
 		enqueue := queue.Enqueue
-		if p.state.fullScan {
+		if entry.job.lib.FullScanInProgress {
 			enqueue = queue.EnqueueIfMissing
 		}
 		if err := enqueue(ctx, queueItems...); err != nil {
diff --git a/scanner/scanner.go b/scanner/scanner.go
index cd2fe3c8d..305c443f4 100644
--- a/scanner/scanner.go
+++ b/scanner/scanner.go
@@ -4,13 +4,11 @@ import (
 	"context"
 	"fmt"
 	"maps"
-	"path/filepath"
 	"slices"
 	"sync/atomic"
 	"time"
 
 	ppl "github.com/google/go-pipeline/pkg/pipeline"
-	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/log"
@@ -32,6 +30,7 @@ type scanState struct {
 	libraries         model.Libraries  // Store libraries list for consistency across phases
 	targets           map[int][]string // Optional: map[libraryID][]folderPaths for selective scans
 	totalLibraryCount int              // Total number of libraries (unfiltered), for cross-library move detection
+	failedLibs        map[int]bool     // Libraries that could not be scanned in this run
 }
 
 func (s *scanState) sendProgress(info *ProgressInfo) {
@@ -48,29 +47,15 @@ func (s *scanState) sendWarning(msg string) {
 	s.sendProgress(&ProgressInfo{Warning: msg})
 }
 
-func (s *scanState) sendError(err error) {
-	s.sendProgress(&ProgressInfo{Error: err.Error()})
+func (s *scanState) markFailed(libID int) {
+	if s.failedLibs == nil {
+		s.failedLibs = map[int]bool{}
+	}
+	s.failedLibs[libID] = true
 }
 
-// libraryRelativePath rebases an absolute scan target path onto the library root, since the
-// scanner's fs.FS only accepts paths relative to it. Relative paths, and absolute paths outside
-// the library root, are returned unchanged.
-func libraryRelativePath(libPath, folderPath string) string {
-	if !filepath.IsAbs(folderPath) {
-		return folderPath
-	}
-	// The library root may be relative (e.g. the default "./music"); it must be made absolute
-	// to match against an absolute target, and it resolves against the same cwd as the scanner's fs.
-	absLib, err := filepath.Abs(libPath)
-	if err != nil {
-		return folderPath
-	}
-	rel, err := filepath.Rel(absLib, folderPath)
-	if err != nil || !filepath.IsLocal(rel) {
-		return folderPath
-	}
-	// The scanner's fs.FS is an io/fs, which always uses forward slashes.
-	return filepath.ToSlash(rel)
+func (s *scanState) sendError(err error) {
+	s.sendProgress(&ProgressInfo{Error: err.Error()})
 }
 
 func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []model.ScanTarget, progress chan<- *ProgressInfo) {
@@ -104,7 +89,7 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 		})
 
 		for _, target := range targets {
-			folderPath := libraryRelativePath(libPaths[target.LibraryID], target.FolderPath)
+			folderPath := model.LibraryRelativePath(libPaths[target.LibraryID], target.FolderPath)
 			if folderPath == "" {
 				folderPath = "."
 			}
@@ -137,6 +122,10 @@ func (s *scannerImpl) scanFolders(ctx context.Context, fullScan bool, targets []
 	// if there was a full scan in progress, force a full scan
 	if !state.fullScan {
 		for _, lib := range state.libraries {
+			// A pending PID rescan already restarts in full through its own job
+			if lib.NeedsPIDRescan() {
+				continue
+			}
 			if lib.FullScanInProgress {
 				log.Info(ctx, "Scanner: Interrupted full scan detected", "lib", lib.Name)
 				state.fullScan = true
@@ -215,10 +204,13 @@ func (s *scannerImpl) prepareLibrariesForScan(ctx context.Context, state *scanSt
 	var successfulLibs []model.Library
 
 	for _, lib := range state.libraries {
-		if lib.LastScanStartedAt.IsZero() {
+		// A library with a changed PID config restarts its scan: resuming would skip the folders that
+		// the interrupted scan already processed with the old config
+		pidRescan := lib.NeedsPIDRescan()
+		if lib.LastScanStartedAt.IsZero() || pidRescan {
 			// This is a new scan - mark it as started
 			err := s.ds.WithTxRetry(ctx, func(ctx context.Context, tx model.DataStore) error {
-				return tx.Library().ScanBegin(ctx, lib.ID, state.fullScan)
+				return tx.Library().ScanBegin(ctx, lib.ID, state.fullScan || pidRescan)
 			}, "scanner: begin library scan")
 			if err != nil {
 				log.Error(ctx, "Scanner: Error marking scan start", "lib", lib.Name, err)
@@ -340,11 +332,12 @@ func (s *scannerImpl) runUpdateLibraries(ctx context.Context, state *scanState)
 				if err := tx.Library().ScanEnd(ctx, lib.ID); err != nil {
 					return fmt.Errorf("updating last scan completed for %s: %w", lib.Name, err)
 				}
-				if err := tx.Property().Put(ctx, consts.PIDTrackKey, conf.Server.PID.Track); err != nil {
-					return fmt.Errorf("updating track PID conf: %w", err)
-				}
-				if err := tx.Property().Put(ctx, consts.PIDAlbumKey, conf.Server.PID.Album); err != nil {
-					return fmt.Errorf("updating album PID conf: %w", err)
+				// A selective scan covers only part of the library, so the rest may still use the old PID
+				// config. A library that could not be scanned did not apply it either.
+				if !state.isSelectiveScan() && !state.failedLibs[lib.ID] {
+					if err := tx.Library().SetScannedPID(ctx, lib.ID, lib.EffectivePID()); err != nil {
+						return fmt.Errorf("updating PID conf for %s: %w", lib.Name, err)
+					}
 				}
 				if state.changesDetected.Load() {
 					log.Debug(ctx, "Scanner: Refreshing library stats", "lib", lib.Name)
diff --git a/scanner/scanner_internal_test.go b/scanner/scanner_internal_test.go
index 0778bd6ec..e8abb7c7d 100644
--- a/scanner/scanner_internal_test.go
+++ b/scanner/scanner_internal_test.go
@@ -4,8 +4,6 @@ package scanner
 import (
 	"context"
 	"errors"
-	"os"
-	"path/filepath"
 	"sync/atomic"
 
 	ppl "github.com/google/go-pipeline/pkg/pipeline"
@@ -13,43 +11,6 @@ import (
 	. "github.com/onsi/gomega"
 )
 
-var _ = Describe("libraryRelativePath", func() {
-	// Paths are built with filepath so the "absolute" cases stay absolute on every OS
-	// (a Unix-style "/foo" is not absolute on Windows).
-	libRoot, _ := filepath.Abs(filepath.Join("jukebox", "collection"))
-	outside, _ := filepath.Abs(filepath.Join("somewhere", "else"))
-
-	It("returns a relative path unchanged", func() {
-		Expect(libraryRelativePath(libRoot, "_Collection")).To(Equal("_Collection"))
-	})
-
-	It("rebases an absolute target when the library root is relative", func() {
-		cwd, err := os.Getwd()
-		Expect(err).ToNot(HaveOccurred())
-		Expect(libraryRelativePath(filepath.Join("music", "library"), filepath.Join(cwd, "music", "library", "rock"))).To(Equal("rock"))
-	})
-
-	It("rebases an absolute path that equals the library root to '.'", func() {
-		Expect(libraryRelativePath(libRoot, libRoot)).To(Equal("."))
-	})
-
-	It("rebases an absolute path under the library root", func() {
-		Expect(libraryRelativePath(libRoot, filepath.Join(libRoot, "_Collection"))).To(Equal("_Collection"))
-	})
-
-	It("handles a trailing slash on the library path", func() {
-		Expect(libraryRelativePath(libRoot+string(filepath.Separator), filepath.Join(libRoot, "_Collection"))).To(Equal("_Collection"))
-	})
-
-	It("leaves an absolute path outside the library root unchanged", func() {
-		Expect(libraryRelativePath(libRoot, outside)).To(Equal(outside))
-	})
-
-	It("returns an empty path unchanged", func() {
-		Expect(libraryRelativePath(libRoot, "")).To(Equal(""))
-	})
-})
-
 type mockPhase struct {
 	num           int
 	produceFunc   func() ppl.Producer[int]
diff --git a/scanner/scanner_multilibrary_test.go b/scanner/scanner_multilibrary_test.go
index 546baf756..f6634c875 100644
--- a/scanner/scanner_multilibrary_test.go
+++ b/scanner/scanner_multilibrary_test.go
@@ -835,4 +835,170 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 			Expect(lastError).To(BeEmpty())
 		})
 	})
+
+	Context("Per-library PID config", func() {
+		albumsOf := func(libID int) model.Albums {
+			// The mock datastore's GC is a no-op, so run the real one to purge the albums left
+			// empty by a regroup, as the scanner does in production
+			Expect(ds.RealDS.GC(ctx)).To(Succeed())
+			albums, err := ds.Album().GetAll(ctx, model.QueryOptions{
+				Filters: squirrel.Eq{"library_id": libID, "missing": false},
+				Sort:    "name",
+			})
+			Expect(err).ToNot(HaveOccurred())
+			return albums
+		}
+		trackByTitle := func(libID int, title string) model.MediaFile {
+			mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{
+				Filters: squirrel.Eq{"library_id": libID, "title": title},
+			})
+			Expect(err).ToNot(HaveOccurred())
+			Expect(mfs).To(HaveLen(1))
+			return mfs[0]
+		}
+		rockTitles := func() []string {
+			mfs, err := ds.MediaFile().GetAll(ctx, model.QueryOptions{Filters: squirrel.Eq{"library_id": lib1.ID}})
+			Expect(err).ToNot(HaveOccurred())
+			return slice.Map(mfs, func(mf model.MediaFile) string { return mf.Title })
+		}
+		// changeRockInDB edits the rock track in the DB only. A full rescan of the rock library would
+		// restore the title from the file tags, a quick scan leaves it alone.
+		changeRockInDB := func() {
+			_, err := db.Db().ExecContext(ctx, "update media_file set title = 'Changed In DB' where library_id = ?", lib1.ID)
+			Expect(err).ToNot(HaveOccurred())
+		}
+		// changeBlueTrainInDB does the same for one jazz track
+		changeBlueTrainInDB := func() {
+			_, err := db.Db().ExecContext(ctx, "update media_file set title = 'Blue Train In DB' where library_id = ? and title = 'Blue Train'", lib2.ID)
+			Expect(err).ToNot(HaveOccurred())
+		}
+
+		BeforeEach(func() {
+			beatles := template(_t{"albumartist": "The Beatles", "album": "Abbey Road", "year": 1969})
+			_ = createFS("rock", fstest.MapFS{
+				"The Beatles/Abbey Road/01 - Come Together.mp3": beatles(track(1, "Come Together")),
+			})
+
+			miles := template(_t{"albumartist": "Miles Davis", "album": "Kind of Blue", "year": 1959})
+			coltrane := template(_t{"albumartist": "John Coltrane", "album": "Giant Steps", "year": 1960})
+			blueTrain := template(_t{"albumartist": "John Coltrane", "album": "Blue Train", "year": 1957})
+			_ = createFS("jazz", fstest.MapFS{
+				"Loose/01 - So What.mp3":                  miles(track(1, "So What")),
+				"Loose/02 - Giant Steps.mp3":              coltrane(track(1, "Giant Steps")),
+				"Coltrane/Blue Train/01 - Blue Train.mp3": blueTrain(track(1, "Blue Train")),
+			})
+		})
+
+		It("regroups only the library whose PID config changed, keeping annotations", func() {
+			Expect(runScanner(ctx, true)).To(Succeed())
+			Expect(albumsOf(lib2.ID)).To(HaveLen(3))
+
+			// Star Blue Train, to check the star follows the album to its new ID
+			oldBlueTrain := trackByTitle(lib2.ID, "Blue Train")
+			Expect(ds.Album().SetStar(ctx, true, oldBlueTrain.AlbumID)).To(Succeed())
+			changeRockInDB()
+
+			lib2.PIDAlbum = "folder"
+			Expect(ds.Library().Put(ctx, &lib2)).To(Succeed())
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			// Jazz is grouped by folder now: "Loose" is one album
+			Expect(albumsOf(lib2.ID)).To(HaveLen(2))
+			Expect(trackByTitle(lib2.ID, "So What").AlbumID).To(Equal(trackByTitle(lib2.ID, "Giant Steps").AlbumID))
+
+			newBlueTrain := trackByTitle(lib2.ID, "Blue Train")
+			Expect(newBlueTrain.AlbumID).ToNot(Equal(oldBlueTrain.AlbumID))
+			album, err := ds.Album().Get(ctx, newBlueTrain.AlbumID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(album.Starred).To(BeTrue())
+
+			// Rock only got a quick scan
+			Expect(rockTitles()).To(ConsistOf("Changed In DB"))
+
+			jazz, err := ds.Library().Get(ctx, lib2.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(jazz.ScannedPIDAlbum).To(Equal("folder"))
+			Expect(jazz.PIDChanged()).To(BeFalse())
+			rock, err := ds.Library().Get(ctx, lib1.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(rock.PIDChanged()).To(BeFalse())
+		})
+
+		It("rescans only libraries that follow the global config", func() {
+			lib2.PIDAlbum = "folder"
+			Expect(ds.Library().Put(ctx, &lib2)).To(Succeed())
+			Expect(runScanner(ctx, true)).To(Succeed())
+			changeRockInDB()
+			changeBlueTrainInDB()
+
+			conf.Server.PID.Album = "album"
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			// Rock follows the global config, so it was rescanned in full and its title restored
+			Expect(rockTitles()).To(ConsistOf("Come Together"))
+			// Jazz has its own override, so it only got a quick scan
+			trackByTitle(lib2.ID, "Blue Train In DB")
+			jazz, err := ds.Library().Get(ctx, lib2.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(jazz.ScannedPIDAlbum).To(Equal("folder"))
+		})
+
+		It("restarts an interrupted scan when the PID config changed meanwhile", func() {
+			Expect(runScanner(ctx, true)).To(Succeed())
+
+			// Simulate a quick scan of jazz that was interrupted after it had processed every folder:
+			// the folders were updated after the (old) scan start time
+			_, err := db.Db().ExecContext(ctx, "update library set last_scan_started_at = ?, full_scan_in_progress = false where id = ?",
+				time.Now().Add(-time.Hour), lib2.ID)
+			Expect(err).ToNot(HaveOccurred())
+
+			lib2.PIDAlbum = "folder"
+			Expect(ds.Library().Put(ctx, &lib2)).To(Succeed())
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			// Every folder was revisited with the new config
+			Expect(albumsOf(lib2.ID)).To(HaveLen(2))
+		})
+
+		It("does not turn an interrupted PID rescan into a full scan of every library", func() {
+			Expect(runScanner(ctx, true)).To(Succeed())
+			changeRockInDB()
+			lib2.PIDAlbum = "folder"
+			Expect(ds.Library().Put(ctx, &lib2)).To(Succeed())
+
+			// Simulate a PID full scan of jazz that was interrupted
+			Expect(ds.Library().ScanBegin(ctx, lib2.ID, true)).To(Succeed())
+			Expect(runScanner(ctx, false)).To(Succeed())
+
+			// Rock only got a quick scan, jazz was rescanned with the new config
+			Expect(rockTitles()).To(ConsistOf("Changed In DB"))
+			Expect(albumsOf(lib2.ID)).To(HaveLen(2))
+		})
+
+		It("does not record the PID config for a library that could not be scanned", func() {
+			Expect(runScanner(ctx, true)).To(Succeed())
+			broken := model.Library{Name: "Broken", Path: "unregistered:///music", PIDAlbum: "folder"}
+			Expect(ds.Library().Put(ctx, &broken)).To(Succeed())
+
+			// The scan reports an error for the broken library, and still finishes the others
+			_ = runScanner(ctx, false)
+
+			reloaded, err := ds.Library().Get(ctx, broken.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(reloaded.PIDChanged()).To(BeTrue())
+		})
+
+		It("does not record the PID config after a selective scan", func() {
+			Expect(runScanner(ctx, true)).To(Succeed())
+			lib2.PIDAlbum = "folder"
+			Expect(ds.Library().Put(ctx, &lib2)).To(Succeed())
+
+			_, err := s.ScanFolders(ctx, false, []model.ScanTarget{{LibraryID: lib2.ID, FolderPath: "Loose"}})
+			Expect(err).ToNot(HaveOccurred())
+
+			jazz, err := ds.Library().Get(ctx, lib2.ID)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(jazz.PIDChanged()).To(BeTrue())
+		})
+	})
 })
diff --git a/server/nativeapi/inspect.go b/server/nativeapi/inspect.go
index f1e6c4539..61013dd5a 100644
--- a/server/nativeapi/inspect.go
+++ b/server/nativeapi/inspect.go
@@ -22,7 +22,12 @@ func doInspect(ctx context.Context, ds model.DataStore, id string) (*core.Inspec
 		return nil, model.ErrNotFound
 	}
 
-	return core.Inspect(file.AbsolutePath(), file.LibraryID, file.FolderID)
+	lib, err := ds.Library().Get(ctx, file.LibraryID)
+	if err != nil {
+		return nil, err
+	}
+
+	return core.Inspect(file.AbsolutePath(), *lib, file.FolderID)
 }
 
 func inspect(ds model.DataStore) http.HandlerFunc {
diff --git a/server/serve_index.go b/server/serve_index.go
index 4b093b953..167197403 100644
--- a/server/serve_index.go
+++ b/server/serve_index.go
@@ -58,6 +58,8 @@ func serveIndex(ds model.DataStore, fs fs.FS, shareInfo *model.Share) http.Handl
 			"uiSearchDebounceMs":        conf.Server.UISearchDebounceMs,
 			"uiCoverArtSize":            conf.Server.UICoverArtSize,
 			"enableCoverAnimation":      conf.Server.EnableCoverAnimation,
+			"pidAlbum":                  conf.Server.PID.Album,
+			"pidTrack":                  conf.Server.PID.Track,
 			"enableNowPlaying":          conf.Server.EnableNowPlaying,
 			"playbackReportIntervalMs":  conf.Server.UIPlaybackReportInterval.Milliseconds(),
 			"gaTrackingId":              conf.Server.GATrackingID,
diff --git a/server/serve_index_test.go b/server/serve_index_test.go
index e2df55c4b..277513768 100644
--- a/server/serve_index_test.go
+++ b/server/serve_index_test.go
@@ -89,6 +89,8 @@ var _ = Describe("serveIndex", func() {
 		Entry("uiSearchDebounceMs", func() { conf.Server.UISearchDebounceMs = 500 }, "uiSearchDebounceMs", float64(500)),
 		Entry("uiCoverArtSize", func() { conf.Server.UICoverArtSize = 300 }, "uiCoverArtSize", float64(300)),
 		Entry("enableCoverAnimation", func() { conf.Server.EnableCoverAnimation = true }, "enableCoverAnimation", true),
+		Entry("pidAlbum", func() { conf.Server.PID.Album = "folder" }, "pidAlbum", "folder"),
+		Entry("pidTrack", func() { conf.Server.PID.Track = "title" }, "pidTrack", "title"),
 		Entry("enableNowPlaying", func() { conf.Server.EnableNowPlaying = true }, "enableNowPlaying", true),
 		Entry("gaTrackingId", func() { conf.Server.GATrackingID = "UA-12345" }, "gaTrackingId", "UA-12345"),
 		Entry("defaultDownloadableShare", func() { conf.Server.DefaultDownloadableShare = true }, "defaultDownloadableShare", true),
diff --git a/tests/mock_library_repo.go b/tests/mock_library_repo.go
index e21dcccce..6de2b9265 100644
--- a/tests/mock_library_repo.go
+++ b/tests/mock_library_repo.go
@@ -145,6 +145,17 @@ func (m *MockLibraryRepo) ScanEnd(_ context.Context, id int) error {
 	return nil
 }
 
+func (m *MockLibraryRepo) SetScannedPID(_ context.Context, id int, pid model.PIDConfig) error {
+	if m.Err != nil {
+		return m.Err
+	}
+	if lib, ok := m.Data[id]; ok {
+		lib.ScannedPIDAlbum, lib.ScannedPIDTrack = pid.Album, pid.Track
+		m.Data[id] = lib
+	}
+	return nil
+}
+
 func (m *MockLibraryRepo) ScanInProgress(_ context.Context) (bool, error) {
 	if m.Err != nil {
 		return false, m.Err
diff --git a/ui/src/config.js b/ui/src/config.js
index e406e47cf..62b3cb822 100644
--- a/ui/src/config.js
+++ b/ui/src/config.js
@@ -32,6 +32,8 @@ const defaultConfig = {
   listenBrainzEnabled: true,
   enableExternalServices: true,
   enableCoverAnimation: true,
+  pidAlbum: 'musicbrainz_albumid|albumartistid,album,albumversion,releasedate', // See consts.DefaultAlbumPID
+  pidTrack: 'musicbrainz_trackid|albumid,discnumber,tracknumber,title', // See consts.DefaultTrackPID
   enableNowPlaying: true,
   playbackReportIntervalMs: 60000,
   devShowArtistPage: true,
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index a04b6e311..f694ea75f 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -331,11 +331,22 @@
         "totalDuration": "Duration",
         "defaultNewUsers": "Default for New Users",
         "createdAt": "Created",
-        "updatedAt": "Updated"
+        "updatedAt": "Updated",
+        "pidAlbum": "Album grouping",
+        "pidTrack": "Track identity"
       },
       "sections": {
         "basic": "Basic Information",
-        "statistics": "Statistics"
+        "statistics": "Statistics",
+        "pid": "Persistent IDs"
+      },
+      "pid": {
+        "global": "Use global setting (%{value})",
+        "folder": "Folder (one album per folder)",
+        "custom": "Custom",
+        "spec": "PID spec",
+        "help": "Tags and attributes that identify an item. See the documentation for the syntax:",
+        "docs": "Persistent IDs"
       },
       "actions": {
         "scan": "Scan Library",
@@ -365,7 +376,9 @@
       "messages": {
         "deleteConfirm": "Are you sure you want to delete this library? This will remove all associated data and user access.",
         "scanInProgress": "Scan in progress...",
-        "noLibrariesAssigned": "No libraries assigned to this user"
+        "noLibrariesAssigned": "No libraries assigned to this user",
+        "pidChangeTitle": "Change persistent IDs?",
+        "pidChangeConfirm": "This regroups albums and tracks in this library. A full rescan of this library starts now. Track stars, ratings and play counts are kept. Album stars and ratings move to the new albums where an old album maps to a new one."
       }
     },
     "plugin": {
diff --git a/ui/src/library/LibraryCreate.jsx b/ui/src/library/LibraryCreate.jsx
index 0e69964b6..8166bb2f3 100644
--- a/ui/src/library/LibraryCreate.jsx
+++ b/ui/src/library/LibraryCreate.jsx
@@ -1,4 +1,5 @@
 import React, { useCallback } from 'react'
+import PropTypes from 'prop-types'
 import {
   Create,
   SimpleForm,
@@ -10,7 +11,34 @@ import {
   useNotify,
   useRedirect,
 } from 'react-admin'
+import { Typography } from '@material-ui/core'
+import { makeStyles } from '@material-ui/core/styles'
 import { Title } from '../common'
+import { PIDInputs } from './PIDInput'
+
+const useStyles = makeStyles((theme) => ({
+  spaced: { marginTop: theme.spacing(3) },
+}))
+
+// SimpleForm passes form props (variant, record, ...) to its children, so Typography can't be used directly
+const SectionTitle = ({ label, spaced }) => {
+  const translate = useTranslate()
+  const classes = useStyles()
+  return (
+    <Typography
+      variant="h6"
+      gutterBottom
+      className={spaced ? classes.spaced : undefined}
+    >
+      {translate(label)}
+    </Typography>
+  )
+}
+
+SectionTitle.propTypes = {
+  label: PropTypes.string.isRequired,
+  spaced: PropTypes.bool,
+}
 
 const LibraryCreate = (props) => {
   const translate = useTranslate()
@@ -73,9 +101,12 @@ const LibraryCreate = (props) => {
   return (
     <Create title={<Title subTitle={title} />} {...props}>
       <SimpleForm save={save} variant={'outlined'}>
+        <SectionTitle label="resources.library.sections.basic" />
         <TextInput source="name" validate={[required()]} />
         <TextInput source="path" validate={[required()]} fullWidth />
         <BooleanInput source="defaultNewUsers" />
+        <SectionTitle label="resources.library.sections.pid" spaced />
+        <PIDInputs />
       </SimpleForm>
     </Create>
   )
diff --git a/ui/src/library/LibraryEdit.jsx b/ui/src/library/LibraryEdit.jsx
index 53d17ac7f..c42c7ac4b 100644
--- a/ui/src/library/LibraryEdit.jsx
+++ b/ui/src/library/LibraryEdit.jsx
@@ -1,9 +1,11 @@
-import React, { useCallback } from 'react'
+import React, { useCallback, useState } from 'react'
+import PropTypes from 'prop-types'
 import {
   Edit,
   FormWithRedirect,
   TextInput,
   BooleanInput,
+  Confirm,
   required,
   SaveButton,
   useTranslate,
@@ -22,6 +24,9 @@ import {
   ReadOnlySizeField,
   Title,
 } from '../common'
+import config from '../config'
+import { PIDInputs } from './PIDInput'
+import { pidConfigChanged } from './pidPresets'
 
 const useStyles = makeStyles({
   toolbar: {
@@ -53,8 +58,131 @@ const CustomToolbar = ({ showDelete, ...props }) => (
   </Toolbar>
 )
 
-const LibraryEdit = (props) => {
+export const LibraryEditForm = ({ formProps, canEditPath, canDelete }) => {
   const translate = useTranslate()
+  const [confirmOpen, setConfirmOpen] = useState(false)
+
+  // Every submit path (Save button and Enter key) goes through here, so a PID change always asks first
+  const submit = () => {
+    if (
+      pidConfigChanged(
+        formProps.form.getState().values,
+        formProps.record,
+        config,
+      )
+    ) {
+      setConfirmOpen(true)
+      return
+    }
+    formProps.handleSubmit()
+  }
+
+  const handleConfirm = () => {
+    setConfirmOpen(false)
+    formProps.handleSubmit()
+  }
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault()
+        submit()
+      }}
+    >
+      <Box p="1em" maxWidth="800px">
+        <Box display="flex">
+          <Box flex={1} mr="1em">
+            {/* Basic Information */}
+            <Typography variant="h6" gutterBottom>
+              {translate('resources.library.sections.basic')}
+            </Typography>
+
+            <TextInput
+              source="name"
+              label={translate('resources.library.fields.name')}
+              validate={[required()]}
+              variant="outlined"
+            />
+            <TextInput
+              source="path"
+              label={translate('resources.library.fields.path')}
+              validate={[required()]}
+              fullWidth
+              variant="outlined"
+              InputProps={{ readOnly: !canEditPath }} // Disable editing path for library 1
+            />
+            <BooleanInput
+              source="defaultNewUsers"
+              label={translate('resources.library.fields.defaultNewUsers')}
+              variant="outlined"
+            />
+
+            <Box mt="2em" />
+            <Typography variant="h6" gutterBottom>
+              {translate('resources.library.sections.pid')}
+            </Typography>
+            <PIDInputs />
+
+            <Box mt="2em" />
+
+            {/* Statistics - Two Column Layout */}
+            <Typography variant="h6" gutterBottom>
+              {translate('resources.library.sections.statistics')}
+            </Typography>
+
+            <Box
+              display="grid"
+              gridTemplateColumns="1fr 1fr"
+              gridColumnGap="1em"
+            >
+              <ReadOnlyNumberField source="totalSongs" {...readOnlyProps} />
+              <ReadOnlyNumberField source="totalAlbums" {...readOnlyProps} />
+              <ReadOnlyNumberField source="totalArtists" {...readOnlyProps} />
+              <ReadOnlySizeField source="totalSize" {...readOnlyProps} />
+              <ReadOnlyDurationField
+                source="totalDuration"
+                {...readOnlyProps}
+              />
+              <ReadOnlyNumberField
+                source="totalMissingFiles"
+                {...readOnlyProps}
+              />
+              <Box gridColumn="1 / -1">
+                <ReadOnlyDateField source="lastScanAt" {...readOnlyProps} />
+              </Box>
+              <ReadOnlyDateField source="updatedAt" {...readOnlyProps} />
+              <ReadOnlyDateField source="createdAt" {...readOnlyProps} />
+            </Box>
+          </Box>
+        </Box>
+      </Box>
+
+      <CustomToolbar
+        handleSubmitWithRedirect={submit}
+        pristine={formProps.pristine}
+        saving={formProps.saving}
+        record={formProps.record}
+        showDelete={canDelete}
+      />
+      <Confirm
+        isOpen={confirmOpen}
+        loading={formProps.saving}
+        title="resources.library.messages.pidChangeTitle"
+        content="resources.library.messages.pidChangeConfirm"
+        onConfirm={handleConfirm}
+        onClose={() => setConfirmOpen(false)}
+      />
+    </form>
+  )
+}
+
+LibraryEditForm.propTypes = {
+  formProps: PropTypes.object.isRequired,
+  canEditPath: PropTypes.bool,
+  canDelete: PropTypes.bool,
+}
+
+const LibraryEdit = (props) => {
   const [mutate] = useMutation()
   const notify = useNotify()
   const redirect = useRedirect()
@@ -93,91 +221,11 @@ const LibraryEdit = (props) => {
         {...props}
         save={save}
         render={(formProps) => (
-          <form onSubmit={formProps.handleSubmit}>
-            <Box p="1em" maxWidth="800px">
-              <Box display="flex">
-                <Box flex={1} mr="1em">
-                  {/* Basic Information */}
-                  <Typography variant="h6" gutterBottom>
-                    {translate('resources.library.sections.basic')}
-                  </Typography>
-
-                  <TextInput
-                    source="name"
-                    label={translate('resources.library.fields.name')}
-                    validate={[required()]}
-                    variant="outlined"
-                  />
-                  <TextInput
-                    source="path"
-                    label={translate('resources.library.fields.path')}
-                    validate={[required()]}
-                    fullWidth
-                    variant="outlined"
-                    InputProps={{ readOnly: !canEditPath }} // Disable editing path for library 1
-                  />
-                  <BooleanInput
-                    source="defaultNewUsers"
-                    label={translate(
-                      'resources.library.fields.defaultNewUsers',
-                    )}
-                    variant="outlined"
-                  />
-
-                  <Box mt="2em" />
-
-                  {/* Statistics - Two Column Layout */}
-                  <Typography variant="h6" gutterBottom>
-                    {translate('resources.library.sections.statistics')}
-                  </Typography>
-
-                  <Box
-                    display="grid"
-                    gridTemplateColumns="1fr 1fr"
-                    gridColumnGap="1em"
-                  >
-                    <ReadOnlyNumberField
-                      source="totalSongs"
-                      {...readOnlyProps}
-                    />
-                    <ReadOnlyNumberField
-                      source="totalAlbums"
-                      {...readOnlyProps}
-                    />
-                    <ReadOnlyNumberField
-                      source="totalArtists"
-                      {...readOnlyProps}
-                    />
-                    <ReadOnlySizeField source="totalSize" {...readOnlyProps} />
-                    <ReadOnlyDurationField
-                      source="totalDuration"
-                      {...readOnlyProps}
-                    />
-                    <ReadOnlyNumberField
-                      source="totalMissingFiles"
-                      {...readOnlyProps}
-                    />
-                    <Box gridColumn="1 / -1">
-                      <ReadOnlyDateField
-                        source="lastScanAt"
-                        {...readOnlyProps}
-                      />
-                    </Box>
-                    <ReadOnlyDateField source="updatedAt" {...readOnlyProps} />
-                    <ReadOnlyDateField source="createdAt" {...readOnlyProps} />
-                  </Box>
-                </Box>
-              </Box>
-            </Box>
-
-            <CustomToolbar
-              handleSubmitWithRedirect={formProps.handleSubmitWithRedirect}
-              pristine={formProps.pristine}
-              saving={formProps.saving}
-              record={formProps.record}
-              showDelete={canDelete}
-            />
-          </form>
+          <LibraryEditForm
+            formProps={formProps}
+            canEditPath={canEditPath}
+            canDelete={canDelete}
+          />
         )}
       />
     </Edit>
diff --git a/ui/src/library/LibraryEdit.test.jsx b/ui/src/library/LibraryEdit.test.jsx
new file mode 100644
index 000000000..926adc839
--- /dev/null
+++ b/ui/src/library/LibraryEdit.test.jsx
@@ -0,0 +1,125 @@
+import * as React from 'react'
+import { TestContext } from 'ra-test'
+import {
+  FormWithRedirect,
+  RecordContextProvider,
+  SaveContextProvider,
+} from 'react-admin'
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react'
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { LibraryEditForm } from './LibraryEdit'
+import config from '../config'
+
+const record = {
+  id: '2',
+  name: 'Jazz',
+  path: '/music/jazz',
+  pidAlbum: '',
+  pidTrack: '',
+}
+
+// Edit provides a save context in the app. SaveButton only reads these setters from it
+const saveContext = {
+  save: vi.fn(),
+  setOnSuccess: vi.fn(),
+  setOnFailure: vi.fn(),
+  setTransform: vi.fn(),
+}
+
+const renderForm = (save) =>
+  render(
+    <TestContext>
+      <SaveContextProvider value={saveContext}>
+        <RecordContextProvider value={record}>
+          <FormWithRedirect
+            record={record}
+            save={save}
+            render={(formProps) => (
+              <LibraryEditForm
+                formProps={formProps}
+                canEditPath
+                canDelete={false}
+              />
+            )}
+          />
+        </RecordContextProvider>
+      </SaveContextProvider>
+    </TestContext>,
+  )
+
+const chooseAlbumGrouping = (optionText) => {
+  fireEvent.mouseDown(
+    screen.getByLabelText('resources.library.fields.pidAlbum'),
+  )
+  fireEvent.click(within(screen.getByRole('listbox')).getByText(optionText))
+}
+
+const dialogTitle = 'resources.library.messages.pidChangeTitle'
+
+describe('LibraryEditForm', () => {
+  afterEach(cleanup)
+
+  it('saves directly when the PID config did not change', async () => {
+    const save = vi.fn()
+    renderForm(save)
+    fireEvent.change(screen.getByLabelText(/resources.library.fields.name/), {
+      target: { value: 'Jazz Renamed' },
+    })
+    fireEvent.click(screen.getByText('ra.action.save'))
+    await waitFor(() => expect(save).toHaveBeenCalled())
+    expect(screen.queryByText(dialogTitle)).not.toBeInTheDocument()
+  })
+
+  it('asks before saving a PID change, and Cancel keeps the edits', async () => {
+    const save = vi.fn()
+    renderForm(save)
+    chooseAlbumGrouping('resources.library.pid.folder')
+    fireEvent.click(screen.getByText('ra.action.save'))
+
+    expect(await screen.findByText(dialogTitle)).toBeInTheDocument()
+    expect(save).not.toHaveBeenCalled()
+
+    fireEvent.click(screen.getByText('ra.action.cancel'))
+    await waitFor(() =>
+      expect(screen.queryByText(dialogTitle)).not.toBeInTheDocument(),
+    )
+    expect(save).not.toHaveBeenCalled()
+    expect(screen.getByText('resources.library.pid.folder')).toBeInTheDocument()
+  })
+
+  it('saves the PID change after Confirm', async () => {
+    const save = vi.fn()
+    renderForm(save)
+    chooseAlbumGrouping('resources.library.pid.folder')
+    fireEvent.click(screen.getByText('ra.action.save'))
+    fireEvent.click(await screen.findByText('ra.action.confirm'))
+
+    await waitFor(() => expect(save).toHaveBeenCalled())
+    expect(save.mock.calls[0][0]).toMatchObject({ pidAlbum: 'folder' })
+  })
+
+  it('pre-fills a Custom spec with the global spec', () => {
+    renderForm(vi.fn())
+    chooseAlbumGrouping('resources.library.pid.custom')
+    expect(screen.getByLabelText(/resources.library.pid.spec/)).toHaveValue(
+      config.pidAlbum,
+    )
+  })
+
+  it('asks before saving when the form is submitted with Enter', async () => {
+    const save = vi.fn()
+    const { container } = renderForm(save)
+    chooseAlbumGrouping('resources.library.pid.folder')
+    fireEvent.submit(container.querySelector('form'))
+
+    expect(await screen.findByText(dialogTitle)).toBeInTheDocument()
+    expect(save).not.toHaveBeenCalled()
+  })
+})
diff --git a/ui/src/library/PIDInput.jsx b/ui/src/library/PIDInput.jsx
new file mode 100644
index 000000000..6481dc392
--- /dev/null
+++ b/ui/src/library/PIDInput.jsx
@@ -0,0 +1,114 @@
+import React, { useState } from 'react'
+import PropTypes from 'prop-types'
+import { TextInput, required, useTranslate } from 'react-admin'
+import { useField } from 'react-final-form'
+import { FormHelperText, Link, MenuItem, TextField } from '@material-ui/core'
+import { makeStyles } from '@material-ui/core/styles'
+import {
+  PID_CUSTOM,
+  PID_FOLDER,
+  PID_GLOBAL,
+  pidModeFromValue,
+  pidValueForMode,
+} from './pidPresets'
+import config from '../config'
+import { docsUrl } from '../utils'
+
+const PID_DOCS_URL = docsUrl('/docs/usage/pids/')
+
+const useStyles = makeStyles((theme) => ({
+  help: { marginBottom: theme.spacing(1) },
+}))
+
+// PIDInput edits a library PID override: use the global setting, a preset, or a custom spec
+export const PIDInput = ({ source, label, globalValue, allowFolder }) => {
+  const translate = useTranslate()
+  const classes = useStyles()
+  const { input } = useField(source)
+  // Local state, so choosing Custom shows the text box before anything is typed
+  const [mode, setMode] = useState(() =>
+    pidModeFromValue(input.value, allowFolder),
+  )
+
+  const choices = [
+    {
+      id: PID_GLOBAL,
+      name: translate('resources.library.pid.global', { value: globalValue }),
+    },
+    ...(allowFolder
+      ? [{ id: PID_FOLDER, name: translate('resources.library.pid.folder') }]
+      : []),
+    { id: PID_CUSTOM, name: translate('resources.library.pid.custom') },
+  ]
+
+  const handleModeChange = (event) => {
+    const newMode = event.target.value
+    setMode(newMode)
+    input.onChange(pidValueForMode(newMode, globalValue))
+  }
+
+  return (
+    <>
+      <TextField
+        id={`${source}-mode`}
+        select
+        fullWidth
+        variant="outlined"
+        margin="dense"
+        label={label}
+        value={mode}
+        onChange={handleModeChange}
+      >
+        {choices.map((choice) => (
+          <MenuItem key={choice.id} value={choice.id}>
+            {choice.name}
+          </MenuItem>
+        ))}
+      </TextField>
+      {mode === PID_CUSTOM && (
+        <>
+          <TextInput
+            source={source}
+            label={translate('resources.library.pid.spec')}
+            validate={[required()]}
+            fullWidth
+            variant="outlined"
+            helperText={false}
+          />
+          <FormHelperText className={classes.help}>
+            {translate('resources.library.pid.help')}{' '}
+            <Link href={PID_DOCS_URL} target="_blank" rel="noopener noreferrer">
+              {translate('resources.library.pid.docs')}
+            </Link>
+          </FormHelperText>
+        </>
+      )}
+    </>
+  )
+}
+
+PIDInput.propTypes = {
+  source: PropTypes.string.isRequired,
+  label: PropTypes.string.isRequired,
+  globalValue: PropTypes.string,
+  allowFolder: PropTypes.bool,
+}
+
+export const PIDInputs = () => {
+  const translate = useTranslate()
+  return (
+    <>
+      <PIDInput
+        source="pidAlbum"
+        label={translate('resources.library.fields.pidAlbum')}
+        globalValue={config.pidAlbum}
+        allowFolder
+      />
+      <PIDInput
+        source="pidTrack"
+        label={translate('resources.library.fields.pidTrack')}
+        globalValue={config.pidTrack}
+      />
+    </>
+  )
+}
diff --git a/ui/src/library/pidPresets.js b/ui/src/library/pidPresets.js
new file mode 100644
index 000000000..0483fc691
--- /dev/null
+++ b/ui/src/library/pidPresets.js
@@ -0,0 +1,33 @@
+export const PID_GLOBAL = 'global'
+export const PID_FOLDER = 'folder'
+export const PID_CUSTOM = 'custom'
+
+export const pidModeFromValue = (value, allowFolder) => {
+  const v = (value || '').trim()
+  if (v === '') return PID_GLOBAL
+  if (allowFolder && v === PID_FOLDER) return PID_FOLDER
+  return PID_CUSTOM
+}
+
+// Returns the value to store for a dropdown choice. Custom starts from the global spec
+export const pidValueForMode = (mode, globalValue) => {
+  switch (mode) {
+    case PID_GLOBAL:
+      return ''
+    case PID_FOLDER:
+      return PID_FOLDER
+    default:
+      return globalValue || ''
+  }
+}
+
+// Reports whether the form values change the effective PID spec of the saved record. Like the
+// server, it trims, treats empty as the global value and compares case-insensitively
+export const pidConfigChanged = (values, record, globals) => {
+  const effective = (value, field) =>
+    ((value || '').trim() || globals[field] || '').toLowerCase()
+  return ['pidAlbum', 'pidTrack'].some(
+    (field) =>
+      effective(values[field], field) !== effective(record[field], field),
+  )
+}
diff --git a/ui/src/library/pidPresets.test.js b/ui/src/library/pidPresets.test.js
new file mode 100644
index 000000000..dab1c82e2
--- /dev/null
+++ b/ui/src/library/pidPresets.test.js
@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest'
+import {
+  PID_CUSTOM,
+  PID_FOLDER,
+  PID_GLOBAL,
+  pidConfigChanged,
+  pidModeFromValue,
+  pidValueForMode,
+} from './pidPresets'
+
+describe('pidModeFromValue', () => {
+  it('maps an empty value to the global setting', () => {
+    expect(pidModeFromValue('', true)).toBe(PID_GLOBAL)
+    expect(pidModeFromValue(undefined, true)).toBe(PID_GLOBAL)
+  })
+  it('maps folder to the Folder preset when allowed', () => {
+    expect(pidModeFromValue('folder', true)).toBe(PID_FOLDER)
+  })
+  it('maps folder to Custom when the Folder preset is not offered', () => {
+    expect(pidModeFromValue('folder', false)).toBe(PID_CUSTOM)
+  })
+  it('maps any other value to Custom', () => {
+    expect(pidModeFromValue('album|title', true)).toBe(PID_CUSTOM)
+  })
+})
+
+describe('pidValueForMode', () => {
+  it('stores an empty value for the global setting', () => {
+    expect(pidValueForMode(PID_GLOBAL, 'album')).toBe('')
+  })
+  it('stores folder for the Folder preset', () => {
+    expect(pidValueForMode(PID_FOLDER, '')).toBe('folder')
+  })
+  it('starts Custom from the global spec', () => {
+    expect(pidValueForMode(PID_CUSTOM, 'album|title')).toBe('album|title')
+    expect(pidValueForMode(PID_CUSTOM, undefined)).toBe('')
+  })
+})
+
+describe('pidConfigChanged', () => {
+  const record = { pidAlbum: 'folder', pidTrack: '' }
+  const globals = {
+    pidAlbum: 'musicbrainz_albumid|albumartistid,album',
+    pidTrack: 'musicbrainz_trackid|albumid,discnumber,tracknumber,title',
+  }
+  it.each([
+    ['nothing changed', { pidAlbum: 'folder', pidTrack: '' }, false],
+    ['a missing value equals an empty one', { pidAlbum: 'folder' }, false],
+    [
+      'Custom set to the global value',
+      { pidAlbum: 'folder', pidTrack: globals.pidTrack },
+      false,
+    ],
+    ['a case-only change', { pidAlbum: 'FOLDER', pidTrack: '' }, false],
+    [
+      'a whitespace-only change',
+      { pidAlbum: ' folder ', pidTrack: '  ' },
+      false,
+    ],
+    ['the album PID changed', { pidAlbum: '', pidTrack: '' }, true],
+    ['the track PID changed', { pidAlbum: 'folder', pidTrack: 'title' }, true],
+  ])('%s', (_, values, expected) => {
+    expect(pidConfigChanged(values, record, globals)).toBe(expected)
+  })
+})

From 95f67d2c4ef391967327f0c7dccd5d0d8b02f62e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Sat, 3 Oct 2026 08:58:54 -0700
Subject: [PATCH 198/200] fix(share): reuse cached transcodes for share streams
 and zip downloads (#6262)

* fix(share): reuse cached transcodes when streaming from share links

Public share streams built the stream request with only the share's format
and bit rate, leaving sample rate, bit depth and channels at zero. Regular
playback resolves those through the transcode decider (e.g. 48000 Hz for
Opus), and they are part of the transcoding cache key, so a track already
transcoded during normal playback was transcoded again into a separate,
identical cache entry when played through a share link.

The public router now resolves share stream requests with the same
TranscodeDecider.ResolveRequest used by the Subsonic stream endpoint, so
both paths produce the same request and share cache entries.

Fixes #6261

* fix(archiver): reuse cached transcodes when zipping downloads

Zip downloads (album, artist, playlist and share) built the stream request
with only the format and bit rate, leaving sample rate, bit depth and
channels at zero. Those are part of the transcoding cache key, so a track
already transcoded for playback was transcoded again into a separate cache
entry when downloaded in a zip, and vice versa.

The archiver now resolves each request with TranscodeDecider.ResolveRequest,
the same as single-song downloads and streams. This also applies the
decider's defaults, so a zip requested without a bit rate uses the target
format's default bit rate instead of leaving it to ffmpeg.

* fix(archiver): name zip entries after the resolved transcoding format

The transcode decider can pick a different format than the one requested
(for example a player's forced transcoding, or a fallback to the default
downsampling format when the requested one can't be produced). Zip entry
names and the playlist M3U were still built from the requested format, so
an entry could end in .mp3 or .flac while holding Opus data.

Each track's request is now resolved before its entry name is built, and
the name uses the resolved format.
---
 cmd/wire_gen.go                              |  9 +--
 core/archiver.go                             | 30 ++++++----
 core/archiver_test.go                        | 58 +++++++++++++++++++-
 server/public/handle_streams.go              |  5 +-
 server/public/handle_streams_test.go         | 17 ++++--
 server/public/public.go                      |  5 +-
 server/subsonic/e2e/subsonic_artwork_test.go |  2 +-
 7 files changed, 101 insertions(+), 25 deletions(-)

diff --git a/cmd/wire_gen.go b/cmd/wire_gen.go
index 19f92d9d5..2a396689d 100644
--- a/cmd/wire_gen.go
+++ b/cmd/wire_gen.go
@@ -95,8 +95,9 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, imageStore, fFmpeg)
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
+	transcodeDecider := stream.NewTranscodeDecider(dataStore, fFmpeg)
 	share := core.NewShare(dataStore)
-	archiver := core.NewArchiver(mediaStreamer, dataStore, share, artworkArtwork)
+	archiver := core.NewArchiver(mediaStreamer, transcodeDecider, dataStore, share, artworkArtwork)
 	players := core.NewPlayers(dataStore)
 	broker := events.GetBroker()
 	metricsMetrics := metrics.GetPrometheusInstance(dataStore)
@@ -110,7 +111,6 @@ func CreateSubsonicAPIRouter(ctx context.Context) *subsonic.Router {
 	playTracker := scrobbler.GetPlayTracker(dataStore, broker, manager)
 	playbackServer := playback.GetInstance(dataStore)
 	lyricsLyrics := lyrics.NewLyrics(dataStore, manager)
-	transcodeDecider := stream.NewTranscodeDecider(dataStore, fFmpeg)
 	sonicSonic := sonic.New(dataStore, manager, matcherMatcher)
 	router := subsonic.New(dataStore, artworkArtwork, mediaStreamer, archiver, players, provider, modelScanner, broker, playlistsPlaylists, playTracker, share, playbackServer, metricsMetrics, lyricsLyrics, transcodeDecider, sonicSonic)
 	return router
@@ -159,9 +159,10 @@ func CreatePublicRouter() *public.Router {
 	artworkArtwork := artwork.NewArtwork(dataStore, fileCache, imageStore, fFmpeg)
 	transcodingCache := stream.GetTranscodingCache()
 	mediaStreamer := stream.NewMediaStreamer(dataStore, fFmpeg, transcodingCache)
+	transcodeDecider := stream.NewTranscodeDecider(dataStore, fFmpeg)
 	share := core.NewShare(dataStore)
-	archiver := core.NewArchiver(mediaStreamer, dataStore, share, artworkArtwork)
-	router := public.New(dataStore, artworkArtwork, mediaStreamer, share, archiver)
+	archiver := core.NewArchiver(mediaStreamer, transcodeDecider, dataStore, share, artworkArtwork)
+	router := public.New(dataStore, artworkArtwork, mediaStreamer, transcodeDecider, share, archiver)
 	return router
 }
 
diff --git a/core/archiver.go b/core/archiver.go
index 6f362322a..60eb44858 100644
--- a/core/archiver.go
+++ b/core/archiver.go
@@ -35,13 +35,14 @@ type Archiver interface {
 	ZipPlaylist(ctx context.Context, id string, format string, bitrate int, w io.Writer) error
 }
 
-func NewArchiver(ms stream.MediaStreamer, ds model.DataStore, shares Share, artwork artwork.Artwork) Archiver {
-	return &archiver{ds: ds, ms: ms, shares: shares, artwork: artwork}
+func NewArchiver(ms stream.MediaStreamer, decider stream.TranscodeDecider, ds model.DataStore, shares Share, artwork artwork.Artwork) Archiver {
+	return &archiver{ds: ds, ms: ms, decider: decider, shares: shares, artwork: artwork}
 }
 
 type archiver struct {
 	ds      model.DataStore
 	ms      stream.MediaStreamer
+	decider stream.TranscodeDecider
 	shares  Share
 	artwork artwork.Artwork
 }
@@ -78,8 +79,9 @@ func (a *archiver) zipAlbums(ctx context.Context, id string, format string, bitr
 		log.Debug(ctx, "Zipping album", "name", album[0].Album, "artist", album[0].AlbumArtist, "folder", folder,
 			"format", format, "bitrate", bitrate, "isMultiDisc", isMultiDisc, "numTracks", len(album))
 		for _, mf := range album {
-			file := a.albumFilename(mf, format, isMultiDisc, folder)
-			if addErr := a.addFileToZip(ctx, z, mf, format, bitrate, file); errors.Is(addErr, stream.ErrTooManyTranscodes) {
+			req := a.resolveRequest(ctx, &mf, format, bitrate)
+			file := a.albumFilename(mf, req.Format, isMultiDisc, folder)
+			if addErr := a.addFileToZip(ctx, z, mf, req, file); errors.Is(addErr, stream.ErrTooManyTranscodes) {
 				// Stop iterating: continuing would just rack up more
 				// rejections from the limiter. Close finalises whatever
 				// tracks were already written; the rejected one is not
@@ -204,8 +206,9 @@ func (a *archiver) zipMediaFiles(ctx context.Context, id, name string, format st
 
 	zippedMfs := make(model.MediaFiles, len(mfs))
 	for idx, mf := range mfs {
-		file := a.playlistFilename(mf, format, idx)
-		if addErr := a.addFileToZip(ctx, z, mf, format, bitrate, file); errors.Is(addErr, stream.ErrTooManyTranscodes) {
+		req := a.resolveRequest(ctx, &mf, format, bitrate)
+		file := a.playlistFilename(mf, req.Format, idx)
+		if addErr := a.addFileToZip(ctx, z, mf, req, file); errors.Is(addErr, stream.ErrTooManyTranscodes) {
 			// Abort the whole archive: continuing would silently emit
 			// empty zip entries since the headers are already written.
 			_ = z.Close()
@@ -251,7 +254,14 @@ func (a *archiver) playlistFilename(mf model.MediaFile, format string, idx int)
 	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 {
+func (a *archiver) resolveRequest(ctx context.Context, mf *model.MediaFile, format string, bitrate int) stream.Request {
+	if format == "" || format == "raw" {
+		return stream.Request{Format: "raw"}
+	}
+	return a.decider.ResolveRequest(ctx, mf, format, bitrate, 0)
+}
+
+func (a *archiver) addFileToZip(ctx context.Context, z *zip.Writer, mf model.MediaFile, req stream.Request, filename string) error {
 	path := mf.AbsolutePath()
 
 	// Open the source before writing the zip entry header so a rejection
@@ -259,13 +269,13 @@ func (a *archiver) addFileToZip(ctx context.Context, z *zip.Writer, mf model.Med
 	// archive.
 	var r io.ReadCloser
 	var err error
-	if format != "raw" && format != "" {
-		r, err = a.ms.NewStream(ctx, &mf, stream.Request{Format: format, BitRate: bitrate})
+	if req.Format != "raw" {
+		r, err = a.ms.NewStream(ctx, &mf, req)
 	} else {
 		r, err = os.Open(path)
 	}
 	if err != nil {
-		log.Error(ctx, "Error opening file for zipping", "file", path, "format", format, err)
+		log.Error(ctx, "Error opening file for zipping", "file", path, "format", req.Format, err)
 		return err
 	}
 	defer func() {
diff --git a/core/archiver_test.go b/core/archiver_test.go
index 4e00ce78c..178d1b6b9 100644
--- a/core/archiver_test.go
+++ b/core/archiver_test.go
@@ -26,6 +26,7 @@ var _ = Describe("Archiver", func() {
 	var (
 		arch core.Archiver
 		ms   *mockMediaStreamer
+		dc   *fakeDecider
 		ds   *mockDataStore
 		sh   *mockShare
 		ca   *mockCoverArt
@@ -33,10 +34,11 @@ var _ = Describe("Archiver", func() {
 
 	BeforeEach(func() {
 		ms = &mockMediaStreamer{}
+		dc = &fakeDecider{}
 		sh = &mockShare{}
 		ds = &mockDataStore{}
 		ca = &mockCoverArt{images: map[string][]byte{}}
-		arch = core.NewArchiver(ms, ds, sh, ca)
+		arch = core.NewArchiver(ms, dc, ds, sh, ca)
 	})
 
 	Context("ZipAlbum", func() {
@@ -66,6 +68,23 @@ var _ = Describe("Archiver", func() {
 			Expect(zr.File[0].Name).To(Equal("Album_Promo/01 - track1.mp3"))
 			Expect(zr.File[1].Name).To(Equal("Album_Promo/02 - track2.mp3"))
 		})
+
+		It("streams the request resolved by the transcode decider and names the entry after its format", func() {
+			mfRepo := &mockMediaFileRepository{}
+			mfRepo.On("GetAll", mock.Anything).Return(model.MediaFiles{{Path: "test_data/01 - track1.flac", Suffix: "flac", AlbumID: "1"}}, nil)
+			ds.On("MediaFile").Return(mfRepo)
+			resolved := stream.Request{Format: "opus", BitRate: 128, SampleRate: 48000, Channels: 2}
+			dc.resolved = &resolved
+			ms.On("NewStream", mock.Anything, mock.Anything, resolved).Return(io.NopCloser(strings.NewReader("test")), nil).Once()
+
+			out := new(bytes.Buffer)
+			Expect(arch.ZipAlbum(GinkgoT().Context(), "1", "mp3", 128, out)).To(Succeed())
+			ms.AssertExpectations(GinkgoT())
+
+			zr, err := zip.NewReader(bytes.NewReader(out.Bytes()), int64(out.Len()))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(zr.File[0].Name).To(HaveSuffix("01 - track1.opus"))
+		})
 	})
 
 	Context("ZipArtist", func() {
@@ -296,6 +315,30 @@ var _ = Describe("Archiver", func() {
 	})
 
 	Context("ZipPlaylist", func() {
+		It("names the entries and the M3U lines after the resolved format", func() {
+			pls := &model.Playlist{ID: "1", Name: "Test Playlist", Tracks: []model.PlaylistTrack{
+				{MediaFile: model.MediaFile{Path: "test_data/01 - track1.flac", Suffix: "flac", Artist: "Artist 1", Title: "track1"}},
+			}}
+			plRepo := &mockPlaylistRepository{}
+			plRepo.On("GetWithTracks", "1", true, false).Return(pls, nil)
+			ds.On("Playlist").Return(plRepo)
+			dc.resolved = &stream.Request{Format: "opus", BitRate: 128}
+			ms.On("NewStream", mock.Anything, mock.Anything, *dc.resolved).Return(io.NopCloser(strings.NewReader("test")), nil)
+
+			out := new(bytes.Buffer)
+			Expect(arch.ZipPlaylist(GinkgoT().Context(), "1", "mp3", 128, out)).To(Succeed())
+
+			zr, err := zip.NewReader(bytes.NewReader(out.Bytes()), int64(out.Len()))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(zr.File[0].Name).To(Equal("01 - Artist 1 - track1.opus"))
+			m3u, err := zr.File[1].Open()
+			Expect(err).ToNot(HaveOccurred())
+			defer m3u.Close()
+			content, err := io.ReadAll(m3u)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(string(content)).To(ContainSubstring("01 - Artist 1 - track1.opus"))
+		})
+
 		It("zips a playlist correctly", func() {
 			tracks := []model.PlaylistTrack{
 				{MediaFile: model.MediaFile{Path: "test_data/01 - track1.mp3", Suffix: "mp3", AlbumID: "1", Album: "Album 1", DiscNumber: 1, Artist: "AC/DC", Title: "track1"}},
@@ -571,6 +614,19 @@ func (m *mockMediaStreamer) NewStream(ctx context.Context, mf *model.MediaFile,
 	return &stream.Stream{ReadCloser: args.Get(0).(io.ReadCloser)}, nil
 }
 
+// fakeDecider echoes the legacy format/bitrate unless a resolved request is set.
+type fakeDecider struct {
+	stream.TranscodeDecider
+	resolved *stream.Request
+}
+
+func (f *fakeDecider) ResolveRequest(_ context.Context, _ *model.MediaFile, format string, bitRate int, offset int) stream.Request {
+	if f.resolved != nil {
+		return *f.resolved
+	}
+	return stream.Request{Format: format, BitRate: bitRate, Offset: offset}
+}
+
 type mockShare struct {
 	mock.Mock
 	core.Share
diff --git a/server/public/handle_streams.go b/server/public/handle_streams.go
index 37ae56c2b..46c7ca210 100644
--- a/server/public/handle_streams.go
+++ b/server/public/handle_streams.go
@@ -60,9 +60,8 @@ func (pub *Router) handleStream(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	stream, err := pub.streamer.NewStream(ctx, mf, streampkg.Request{
-		Format: info.format, BitRate: info.bitrate,
-	})
+	streamReq := pub.decider.ResolveRequest(ctx, mf, info.format, info.bitrate, 0)
+	stream, err := pub.streamer.NewStream(ctx, mf, streamReq)
 	if err != nil {
 		if errors.Is(err, streampkg.ErrTooManyTranscodes) {
 			w.Header().Set("Retry-After", strconv.Itoa(streampkg.RetryAfterSeconds))
diff --git a/server/public/handle_streams_test.go b/server/public/handle_streams_test.go
index 4b4a3545b..965bc7e05 100644
--- a/server/public/handle_streams_test.go
+++ b/server/public/handle_streams_test.go
@@ -116,11 +116,11 @@ var _ = Describe("handleStream", func() {
 	BeforeEach(func() {
 		ctx = GinkgoT().Context()
 		auth.PublicTokenAuth = jwtauth.New("HS256", []byte("test-secret"), nil)
-		ds = &tests.MockDataStore{}
+		ds = &tests.MockDataStore{MockedTranscoding: &tests.MockTranscodingRepo{}}
 		shareRepo = &tests.MockShareRepo{}
 		ds.MockedShare = shareRepo
 		streamer = &mockStreamer{}
-		pub = &Router{ds: ds, streamer: streamer}
+		pub = &Router{ds: ds, streamer: streamer, decider: stream.NewTranscodeDecider(ds, tests.NewMockFFmpeg(""))}
 	})
 
 	makeRequest := func(token string) *httptest.ResponseRecorder {
@@ -152,8 +152,17 @@ var _ = Describe("handleStream", func() {
 		makeRequest(token)
 
 		Expect(streamer.called).To(BeTrue())
-		Expect(streamer.req.Format).To(Equal("mp3"))
-		Expect(streamer.req.BitRate).To(Equal(192))
+	})
+
+	It("resolves the full stream request like the Subsonic endpoint, so transcodes share the cache", func() {
+		mf := model.MediaFile{ID: "mf-123", Suffix: "flac", BitRate: 1500, SampleRate: 44100, BitDepth: new(24), Channels: 2}
+		shareOwnedBy(model.User{ID: "owner1", UserName: "owner1", IsAdmin: true}, mf)
+
+		claims := auth.Claims{ID: "mf-123", Format: "opus", BitRate: 128, ShareID: "share123"}
+		token, _ := auth.CreateExpiringPublicToken(time.Now().Add(time.Hour), claims)
+		makeRequest(token)
+
+		Expect(streamer.req).To(Equal(stream.Request{Format: "opus", BitRate: 128, SampleRate: 48000, Channels: 2}))
 	})
 
 	It("returns 404 when the track is outside the share owner's libraries", func() {
diff --git a/server/public/public.go b/server/public/public.go
index 142c474bd..8239ef927 100644
--- a/server/public/public.go
+++ b/server/public/public.go
@@ -21,14 +21,15 @@ type Router struct {
 	http.Handler
 	artwork       artwork.Artwork
 	streamer      stream.MediaStreamer
+	decider       stream.TranscodeDecider
 	archiver      core.Archiver
 	share         core.Share
 	assetsHandler http.Handler
 	ds            model.DataStore
 }
 
-func New(ds model.DataStore, artwork artwork.Artwork, streamer stream.MediaStreamer, share core.Share, archiver core.Archiver) *Router {
-	p := &Router{ds: ds, artwork: artwork, streamer: streamer, share: share, archiver: archiver}
+func New(ds model.DataStore, artwork artwork.Artwork, streamer stream.MediaStreamer, decider stream.TranscodeDecider, share core.Share, archiver core.Archiver) *Router {
+	p := &Router{ds: ds, artwork: artwork, streamer: streamer, decider: decider, share: share, archiver: archiver}
 	shareRoot := path.Join(conf.Server.BasePath, consts.URLPathPublic)
 	p.assetsHandler = http.StripPrefix(shareRoot, http.FileServer(http.FS(ui.BuildAssets())))
 	p.Handler = p.routes()
diff --git a/server/subsonic/e2e/subsonic_artwork_test.go b/server/subsonic/e2e/subsonic_artwork_test.go
index 9394c8830..530588759 100644
--- a/server/subsonic/e2e/subsonic_artwork_test.go
+++ b/server/subsonic/e2e/subsonic_artwork_test.go
@@ -137,7 +137,7 @@ var _ = Describe("Artwork Serving", Ordered, func() {
 
 		artRouter = buildArtworkRouter(artSvc)
 		router = artRouter // so the shared doReq/doRawReq helpers hit the artwork-wired router
-		pubRouter = public.New(ds, artSvc, streamerSpy, core.NewShare(ds), noopArchiver{})
+		pubRouter = public.New(ds, artSvc, streamerSpy, stream.NewTranscodeDecider(ds, ffm), core.NewShare(ds), noopArchiver{})
 	})
 
 	It("emits a bare optimistic coverArt id before the queue is drained", func() {

From caa2f8a0c012328efb9d5685d67b8dc45d24a635 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 6 Oct 2026 06:50:11 -0700
Subject: [PATCH 199/200] fix(ui): make playlist toggle switches visible in all
 themes (#6277)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ui): make playlist toggle switches visible in all themes

The Public and Auto-import switches in the playlist list did not set a
color, so Material-UI used the theme's secondary color. Many themes use
secondary as a surface color close to the table background, which made
checked switches nearly invisible (Catppuccin, Rosé Pine, Monokai,
Moonbase and others).

Set color="primary" on the playlist switch, like every other switch in
the app, and make primary the default MuiSwitch color in useCurrentTheme
so future switches cannot regress. Fixes #6272.

* refactor(ui): drop secondary switch overrides from themes

Dracula, Gruvbox Dark, Tokyo Night and Tokyo Night Light styled checked
MuiSwitch colorSecondary to work around the same invisible-switch problem
(Gruvbox in #5064). With primary as the default switch color and every
switch in the app using it, no switch renders with colorSecondary anymore,
so these overrides are dead code.
---
 ui/src/playlist/PlaylistList.jsx       |  1 +
 ui/src/playlist/PlaylistList.test.jsx  | 27 ++++++++++++++++++++++++++
 ui/src/themes/dracula.js               | 10 ----------
 ui/src/themes/gruvboxDark.js           | 10 ----------
 ui/src/themes/tokyoNight.js            | 10 ----------
 ui/src/themes/tokyoNightLight.js       | 10 ----------
 ui/src/themes/useCurrentTheme.js       |  2 ++
 ui/src/themes/useCurrentTheme.test.jsx | 27 ++++++++++++++++++++++++++
 8 files changed, 57 insertions(+), 40 deletions(-)

diff --git a/ui/src/playlist/PlaylistList.jsx b/ui/src/playlist/PlaylistList.jsx
index 14d819a4e..e1695e980 100644
--- a/ui/src/playlist/PlaylistList.jsx
+++ b/ui/src/playlist/PlaylistList.jsx
@@ -95,6 +95,7 @@ export const ToggleField = ({ resource, source }) => {
   return (
     <Switch
       checked={record[source]}
+      color="primary"
       onClick={handleClick}
       disabled={!isWritable(record.ownerId)}
     />
diff --git a/ui/src/playlist/PlaylistList.test.jsx b/ui/src/playlist/PlaylistList.test.jsx
index 6c714b827..c05833166 100644
--- a/ui/src/playlist/PlaylistList.test.jsx
+++ b/ui/src/playlist/PlaylistList.test.jsx
@@ -2,6 +2,7 @@ import React from 'react'
 import { render, screen } from '@testing-library/react'
 import { describe, it, expect, vi } from 'vitest'
 import { TestContext } from 'ra-test'
+import { RecordContextProvider } from 'react-admin'
 import { PlaylistLove, ToggleField, ToggleAutoImport } from './PlaylistList'
 
 vi.mock('../config', () => ({
@@ -14,6 +15,7 @@ vi.mock('../common', () => ({
       {record?.starred ? 'starred' : 'not-starred'}
     </button>
   ),
+  isWritable: (ownerId) => ownerId === 'me',
 }))
 
 describe('<PlaylistLove />', () => {
@@ -55,3 +57,28 @@ describe('playlist toggles without a record', () => {
     expect(container.innerHTML).toBe('')
   })
 })
+
+// Secondary is a surface color in many themes, so these toggles must use primary
+describe('<ToggleField />', () => {
+  const renderToggle = (record) =>
+    render(
+      <TestContext>
+        <RecordContextProvider value={record}>
+          <ToggleField resource="playlist" source="public" />
+        </RecordContextProvider>
+      </TestContext>,
+    )
+
+  it.each([
+    ['owner', 'me', false],
+    ['non-owner', 'someone-else', true],
+  ])('renders a primary-colored switch for the %s', (_, ownerId, disabled) => {
+    renderToggle({ id: 'pl-1', public: true, ownerId })
+    const input = screen.getByRole('checkbox')
+    const switchBase = input.closest('.MuiSwitch-switchBase')
+    expect(input.checked).toBe(true)
+    expect(input.disabled).toBe(disabled)
+    expect(switchBase.classList).toContain('MuiSwitch-colorPrimary')
+    expect(switchBase.classList).not.toContain('MuiSwitch-colorSecondary')
+  })
+})
diff --git a/ui/src/themes/dracula.js b/ui/src/themes/dracula.js
index 2e4ae38e5..45559c3af 100644
--- a/ui/src/themes/dracula.js
+++ b/ui/src/themes/dracula.js
@@ -185,16 +185,6 @@ export default {
         color: `${foreground} !important`,
       },
     },
-    MuiSwitch: {
-      colorSecondary: {
-        '&$checked': {
-          color: green,
-        },
-        '&$checked + $track': {
-          backgroundColor: green,
-        },
-      },
-    },
     NDAlbumGridView: {
       albumName: {
         marginTop: '0.5rem',
diff --git a/ui/src/themes/gruvboxDark.js b/ui/src/themes/gruvboxDark.js
index 0f4cbd7c4..3e2955dcd 100644
--- a/ui/src/themes/gruvboxDark.js
+++ b/ui/src/themes/gruvboxDark.js
@@ -121,16 +121,6 @@ export default {
         boxShadow: '3px 3px 5px #3c3836',
       },
     },
-    MuiSwitch: {
-      colorSecondary: {
-        '&$checked': {
-          color: '#458588',
-        },
-        '&$checked + $track': {
-          backgroundColor: '#458588',
-        },
-      },
-    },
     NDMobileArtistDetails: {
       bgContainer: {
         background:
diff --git a/ui/src/themes/tokyoNight.js b/ui/src/themes/tokyoNight.js
index 07d372a6b..9f6424b77 100644
--- a/ui/src/themes/tokyoNight.js
+++ b/ui/src/themes/tokyoNight.js
@@ -184,16 +184,6 @@ export default {
         color: `${foreground} !important`,
       },
     },
-    MuiSwitch: {
-      colorSecondary: {
-        '&$checked': {
-          color: blue,
-        },
-        '&$checked + $track': {
-          backgroundColor: blue,
-        },
-      },
-    },
     NDAlbumGridView: {
       albumName: {
         marginTop: '0.5rem',
diff --git a/ui/src/themes/tokyoNightLight.js b/ui/src/themes/tokyoNightLight.js
index f84cd0be9..a61c0fe87 100644
--- a/ui/src/themes/tokyoNightLight.js
+++ b/ui/src/themes/tokyoNightLight.js
@@ -184,16 +184,6 @@ export default {
         color: `${foreground} !important`,
       },
     },
-    MuiSwitch: {
-      colorSecondary: {
-        '&$checked': {
-          color: blue,
-        },
-        '&$checked + $track': {
-          backgroundColor: blue,
-        },
-      },
-    },
     NDAlbumGridView: {
       albumName: {
         marginTop: '0.5rem',
diff --git a/ui/src/themes/useCurrentTheme.js b/ui/src/themes/useCurrentTheme.js
index 4ccefe820..fbb5e9bc8 100644
--- a/ui/src/themes/useCurrentTheme.js
+++ b/ui/src/themes/useCurrentTheme.js
@@ -63,6 +63,8 @@ const useCurrentTheme = () => {
         ...theme.props,
         MuiUseMediaQuery: { noSsr: true },
         MuiPopover: { disableScrollLock: true },
+        // MUI defaults to secondary, which many themes use as a surface color
+        MuiSwitch: { color: 'primary' },
       },
     }),
     [theme],
diff --git a/ui/src/themes/useCurrentTheme.test.jsx b/ui/src/themes/useCurrentTheme.test.jsx
index 65c3be8c6..6553d9866 100644
--- a/ui/src/themes/useCurrentTheme.test.jsx
+++ b/ui/src/themes/useCurrentTheme.test.jsx
@@ -3,6 +3,10 @@ import { Provider } from 'react-redux'
 import { createStore } from 'redux'
 import mediaQuery from 'css-mediaquery'
 import { renderHook } from '@testing-library/react-hooks'
+import { render, screen } from '@testing-library/react'
+import { createMuiTheme, ThemeProvider } from '@material-ui/core/styles'
+import Switch from '@material-ui/core/Switch'
+import themes from './index'
 import useCurrentTheme from './useCurrentTheme'
 import { themeReducer } from '../reducers/themeReducer'
 import { AUTO_THEME_ID } from '../consts'
@@ -161,4 +165,27 @@ describe('useCurrentTheme', () => {
       expect(document.body.style.backgroundColor).toBe('rgb(18, 18, 18)')
     })
   })
+  describe('switch color', () => {
+    it.each(Object.keys(themes))(
+      'renders switches with the primary color in %s',
+      (theme) => {
+        const { result } = renderHook(() => useCurrentTheme(), {
+          wrapper: ({ children }) => (
+            <Provider store={createStore(themeReducer, { theme })}>
+              {children}
+            </Provider>
+          ),
+        })
+        render(
+          <ThemeProvider theme={createMuiTheme(result.current)}>
+            <Switch checked onChange={() => {}} />
+          </ThemeProvider>,
+        )
+        const switchBase = screen
+          .getByRole('checkbox')
+          .closest('.MuiSwitch-switchBase')
+        expect(switchBase.classList).toContain('MuiSwitch-colorPrimary')
+      },
+    )
+  })
 })

From 52135913d4747c8f8ddcfd8e7004202b8f53b594 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Tue, 6 Oct 2026 07:57:07 -0700
Subject: [PATCH 200/200] fix(artwork): don't crash the server when a
 playlist's tracks can't be loaded (#6267)

Playlist().Tracks returns nil when its internal Get fails (for example when the
context is canceled at shutdown), and resolvePlaylist called GetAlbumIDs on it,
panicking with a nil pointer dereference. The artwork drain runs on a bare
goroutine, so the panic killed the whole server.

resolvePlaylist now returns an error when Tracks is nil, and the worker recovers
panics per item: it logs the panic with the item details and stack, and marks
the item as a failed attempt so the rest of the batch still runs.

Fixes #6266
---
 core/artwork/resolve.go      |  7 ++++--
 core/artwork/resolve_test.go | 10 +++++++++
 core/artwork/worker.go       | 18 +++++++++++++++-
 core/artwork/worker_test.go  | 42 ++++++++++++++++++++++++++++++++++++
 4 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/core/artwork/resolve.go b/core/artwork/resolve.go
index 40baa2495..fb07332fe 100644
--- a/core/artwork/resolve.go
+++ b/core/artwork/resolve.go
@@ -374,8 +374,11 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
 		}
 	}
 
-	albumIDs, err := r.ds.Playlist().Tracks(ctx, pl.ID, false).
-		GetAlbumIDs(ctx, model.QueryOptions{Max: PlaylistGridSamples, Sort: "random()"})
+	tracks := r.ds.Playlist().Tracks(ctx, pl.ID, false)
+	if tracks == nil {
+		return resolution{}, fmt.Errorf("resolvePlaylist: could not load tracks for playlist %s", pl.ID)
+	}
+	albumIDs, err := tracks.GetAlbumIDs(ctx, model.QueryOptions{Max: PlaylistGridSamples, Sort: "random()"})
 	if err != nil {
 		return resolution{}, err
 	}
diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.go
index da144d8e2..2a36531bb 100644
--- a/core/artwork/resolve_test.go
+++ b/core/artwork/resolve_test.go
@@ -707,6 +707,16 @@ var _ = Describe("resolveItem", func() {
 			Expect(err).To(HaveOccurred())
 			Expect(res).To(Equal(resolution{}))
 		})
+
+		It("returns an error when the playlist tracks cannot be loaded", func() {
+			plRepo := tests.CreateMockPlaylistRepo()
+			plRepo.SetData(model.Playlists{{ID: "pl4", Name: "Playlist"}})
+			ds.MockedPlaylist = plRepo
+
+			res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "pl4"})
+			Expect(err).To(HaveOccurred())
+			Expect(res).To(Equal(resolution{}))
+		})
 	})
 })
 
diff --git a/core/artwork/worker.go b/core/artwork/worker.go
index 28e51958c..4be99f92e 100644
--- a/core/artwork/worker.go
+++ b/core/artwork/worker.go
@@ -4,9 +4,11 @@ import (
 	"bytes"
 	"cmp"
 	"context"
+	"fmt"
 	"io"
 	"math"
 	"math/rand/v2"
+	"runtime/debug"
 	"sync"
 	"time"
 
@@ -244,7 +246,7 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 	item.ImageType = cmp.Or(item.ImageType, model.ImageTypePrimary)
 	trace := &ChainTrace{}
 	ctx = withTrace(ctx, trace)
-	out, got, retryIn := w.proc.acquire(ctx, item)
+	out, got, retryIn := w.safeAcquire(ctx, item)
 
 	queue := w.proc.ds.ArtworkQueue()
 	switch out {
@@ -286,6 +288,20 @@ func (w *Worker) process(ctx context.Context, item model.ArtworkQueueItem) (outc
 	return out, got
 }
 
+// safeAcquire turns a panic into a failed attempt: the drain runs on a bare goroutine, so an
+// unrecovered panic would crash the server, and the still-queued row would crash it again on restart.
+func (w *Worker) safeAcquire(ctx context.Context, item model.ArtworkQueueItem) (out outcome, got *acquired, retryIn time.Duration) {
+	defer func() {
+		if r := recover(); r != nil {
+			log.Error(ctx, "Artwork: Panic while processing item", "kind", item.ItemKind, "id", item.ItemID,
+				"imageType", item.ImageType, "attempts", item.Attempts, "panic", r, "stack", string(debug.Stack()))
+			traceStage(ctx, "panic", fmt.Errorf("%v", r))
+			out, got, retryIn = outcomeFailed, nil, 0
+		}
+	}()
+	return w.proc.acquire(ctx, item)
+}
+
 // recordGiveUp keeps the last failure on the state row after the queue row is deleted. An item
 // that never resolved has no row to update, and creating one would settle it absent.
 func (w *Worker) recordGiveUp(ctx context.Context, item model.ArtworkQueueItem, trace string) {
diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.go
index a6c07b763..80ca68bc3 100644
--- a/core/artwork/worker_test.go
+++ b/core/artwork/worker_test.go
@@ -142,6 +142,18 @@ func (v *visibilityPlaylistRepo) Get(ctx context.Context, id string) (*model.Pla
 	return v.MockPlaylistRepo.Get(ctx, id)
 }
 
+type panickingAlbumRepo struct {
+	*tests.MockAlbumRepo
+	panicID string
+}
+
+func (r *panickingAlbumRepo) Get(ctx context.Context, id string) (*model.Album, error) {
+	if id == r.panicID {
+		panic("boom")
+	}
+	return r.MockAlbumRepo.Get(ctx, id)
+}
+
 func adminUserRepo() *tests.MockedUserRepo {
 	repo := tests.CreateMockUserRepo()
 	Expect(repo.Put(GinkgoT().Context(), &model.User{ID: "admin", UserName: "admin", IsAdmin: true})).To(Succeed())
@@ -278,6 +290,36 @@ var _ = Describe("Worker", func() {
 			Expect(err).To(MatchError(model.ErrNotFound), "a timeout must never settle on absent")
 		})
 
+		It("fails an item that panics, without stopping the rest of the batch", func() {
+			folderRepo.result = []model.Folder{{
+				Path:       "tests/fixtures/artist/an-album",
+				ImageFiles: []string{"cover.jpg"},
+			}}
+			albums := tests.CreateMockAlbumRepo()
+			albums.SetData(model.Albums{
+				{ID: "alboom", Name: "Album", FolderIDs: []string{"f1"}},
+				{ID: "alok", Name: "Album", FolderIDs: []string{"f1"}},
+			})
+			ds.MockedAlbum = &panickingAlbumRepo{MockAlbumRepo: albums, panicID: "alboom"}
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alboom"})).To(Succeed())
+			Expect(queueRepo.Enqueue(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "alok"})).To(Succeed())
+
+			n, err := w.drain(ctx, 1)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(n).To(Equal(2))
+
+			it := findQueued(queueRepo, "al", "alboom")
+			Expect(it).ToNot(BeNil(), "a panicking item must be rescheduled, not dropped")
+			Expect(it.Attempts).To(Equal(1))
+			Expect(it.RetryAt).To(BeTemporally(">", time.Now()))
+			Expect(it.Trace).To(ContainSubstring("boom"))
+
+			Expect(findQueued(queueRepo, "al", "alok")).To(BeNil())
+			ia, err := artRepo.GetItemArtwork(ctx, model.KindAlbumArtwork, "alok", model.ImageTypePrimary)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ia.Source).To(Equal("folder"))
+		})
+
 		It("reschedules past the provider's requested delay when it exceeds the backoff", func() {
 			conf.Server.CoverArtPriority = "external"
 			ds.MockedAlbum.(*tests.MockAlbumRepo).SetData(model.Albums{{ID: "al9", Name: "Album"}})